sanitize → parse intent → guardrails → ROUTER BRAIN → execute → VERIFY → repair → memory → events

const { createAgent, createLLM, checks } = require("@munesoft/agent");

const agent = createAgent({
  tools,
  llmProvider: createLLM("claude", { apiKey: process.env.ANTHROPIC_API_KEY }),
  verify:      { checks: [ checks.hasKeys(["invoiceId", "total"]) ] },
  maxRepairs:  2,
});

const res = await agent.run("Send invoice to John for $200");
// → { success, output, tool, decision, verification, repairs, steps, sessionId }

npm install @munesoft/agent

const { createAgent } = require("@munesoft/agent");

const agent = createAgent({
  tools: [{
    name: "send_email",
    description: "Send an email to a recipient",
    schema: { to: "string", subject: "string" },
    handler: async ({ to, subject }) => ({ messageId: "msg_001", status: "sent" }),
  }],
  rules: [{
    pattern: /send\s+email\s+to\s+(\S+)\s+about\s+(.+)/i,
    action: "send_email",
    extract: (match) => ({ to: match[1], subject: match[2] }),
    confidence: 0.9,
  }],
});

const result = await agent.run("Send email to john@example.com about Q3 Report");
console.log(result.output);            // { messageId: "msg_001", status: "sent" }
console.log(result.decision.strategy); // "exact"

const { createAgent, createLLM } = require("@munesoft/agent");

const llm   = createLLM("openai", { apiKey: process.env.OPENAI_API_KEY });
const agent = createAgent({ tools, llmProvider: llm });
const result = await agent.run("Send invoice to Sarah for $500");

const agent = createAgent({
  tools,
  routing: {
    threshold:    0.5,
    aliases:      { make_bill: "create_invoice" },
    fallbackTool: "handoff_to_human",
    disambiguate: async (intent, candidates) => candidates[0].name,
  },
});

const res = await agent.run("bill Acme for 250");
res.decision; // { strategy: "alias", tool: "create_invoice", score: 0.95, candidates: [...] }

const { createAgent, checks } = require("@munesoft/agent");

const agent = createAgent({
  tools,
  verify:     { checks: [ checks.hasKeys(["invoiceId", "total"]), checks.range("total", { min: 0.01 }) ] },
  maxRepairs: 2,
});

const res = await agent.run("create an invoice for Acme of 250");
res.verification; // { passed: true, score: 1, checks: [...], feedback: "" }
res.repairs;      // 1  (failed once, repaired, then passed)

const { Verifier, checks } = require("@munesoft/agent");
const report = await new Verifier()
  .check(checks.notEmpty())
  .check(checks.custom(o => o.total > 0 || "total must be positive"))
  .verify(output, { input, tool });

const { SessionStore, attachRecorder, makeRecallTool, createHistoryResearchAgent } = require("@munesoft/agent");

const store = new SessionStore({ path: ".agent-sessions/index.jsonl" });

// 1. Auto-capture every run of an agent from its event bus
const detach = attachRecorder(agent, store, { agentName: "billing" });

// 2. Give any agent a tool to search prior sessions mid-task
agent.addTool(makeRecallTool(store)); // → "search_prior_sessions"

// 3. Produce a pre-work brief of related prior sessions before editing
const researcher = createHistoryResearchAgent({ store });
const report = await researcher.research("harden payment retries", ["src/payments/client.ts"]);
console.log(report.brief); // cited snippets, files previously touched, known gotchas

const { CodingHistoryAdapter, makeRecallTool } = require("@munesoft/agent");
const ctxHistory = new CodingHistoryAdapter();
if (ctxHistory.available()) agent.addTool(makeRecallTool(ctxHistory));

const { safeParallel, researchThenEdit, createHistoryResearchAgent } = require("@munesoft/agent");

// Declare the files each task intends to touch
await safeParallel(orch, [
  { agent: "editor-a", input: "update client", files: ["src/payments/client.ts"] },
  { agent: "editor-b", input: "update backoff", files: ["src/util/backoff.ts"] },
], { onConflict: "serialize" });

// Research-then-edit: prior context is injected into each editor's ctx.priorContext
const { report, execution } = await researchThenEdit({
  orchestrator: orch,
  researcher:   createHistoryResearchAgent({ store }),
  task:         "harden payment retries",
  editors:      [{ agent: "editor-a", input: (rep) => `context: ${rep.relatedSessions.length} prior`, files: ["src/payments/client.ts"] }],
});

const agent = createAgent({
  tools,
  guardrails: {
    redactSecrets:      true,         // mask API keys, JWTs, bearer tokens, cards, emails in input
    blockOutputSecrets: true,         // reject outputs that leak a credential
    allowedActions:     ["create_invoice", "send_email"],
    blockedActions:     ["delete_account"],
    minConfidence:      0.3,          // reject low-confidence intents
    rateLimit:          30,           // max runs...
    rateWindowMs:       60000,        // ...per sliding window
    maxInputLength:     10000,
    outputValidators:   [(out, tool) => out.total >= 0 || "total must be non-negative"],
  },
});

# Install only the pieces you want — or the whole stack:
npm install @munesoft/retryx @munesoft/asyncx @munesoft/logx @munesoft/envx \
            @munesoft/idx @munesoft/objx @munesoft/api-normalizer \
            @munesoft/memoryx @munesoft/loopx

const { createAgent } = require("@munesoft/agent");
const {
  loadAgentEnv, attachLogx, retryableTool, normalizingTool,
  createMemoryxStore, runAgentLoop, boundedParallel, idFactory, mergeSettings,
} = require("@munesoft/agent/integrations");

// envx — fail fast if the API key is missing
const cfg = await loadAgentEnv({ OPENAI_API_KEY: { type: "string", required: true } });

// retryx + api-normalizer — a resilient, self-normalizing tool
const quote = retryableTool(
  normalizingTool(rawQuoteTool, { customer: ["Customer"], amount: { keys: ["PriceUSD"], type: "number" } }, { coerceTypes: true }),
  { retries: 3 });

const agent = createAgent({ tools: [quote], /* … */ });

// logx — structured logs for every stage
const detach = await attachLogx(agent);

// loopx — run until the output is a normalized quote
const { final } = await runAgentLoop(agent, "price for Acme", {
  until: (res) => typeof res.output?.amount === "number",
});

// memoryx — searchable episodic memory (plugs into makeRecallTool / research agents)
const memory = createMemoryxStore({ namespace: "quotes" });
await memory.record({ task: "quote for Acme", outcome: "success" });

// asyncx — fan out with a concurrency cap
const batch = await boundedParallel(orch, tasks, { concurrency: 5 });

const { stackStatus } = require("@munesoft/agent/integrations");
stackStatus(); // { "@munesoft/retryx": { installed: true, use: "safe, retryable API calls", ... }, ... }

const { createLLM } = require("@munesoft/agent");

const llm = createLLM("openai",      { apiKey: process.env.OPENAI_API_KEY });
const llm = createLLM("claude",      { apiKey: process.env.ANTHROPIC_API_KEY });
const llm = createLLM("gemini",      { apiKey: process.env.GEMINI_API_KEY });
const llm = createLLM("grok",        { apiKey: process.env.XAI_API_KEY });
const llm = createLLM("ollama",      { model: "llama3.2" });                              // local
const llm = createLLM("openrouter",  { apiKey: "...", model: "anthropic/claude-3.5-sonnet" }); // any model

// Shared API across every provider
await llm.complete({ system, user, format: "json" });
await llm.functionCall({ system, user, tools });

const { listProviders } = require("@munesoft/agent");
listProviders(); // every supported provider + alias

const { createBridge } = require("@munesoft/agent");

const bridge = createBridge("langchain");
const tools  = bridge.toTools(agent.registry);   // → DynamicStructuredTool[]

const mcp    = createBridge("mcp");
const handler = mcp.createServerHandler(agent.registry); // serve tools over MCP

const { listBridges } = require("@munesoft/agent");
listBridges();

const { Orchestrator } = require("@munesoft/agent");

const orch = new Orchestrator();
orch.register("research", researchAgent)
    .register("summary",  summaryAgent);

// Sequential pipeline
await orch.pipeline([
  { agent: "research", input: "research AI trends" },
  { agent: "summary",  input: (prev) => `summarize: ${JSON.stringify(prev.output)}` },
]);

// Parallel
await orch.parallel([
  { agent: "analyst", input: "analyze fintech" },
  { agent: "analyst", input: "analyze healthtech" },
]);

// Function or LLM routing, and handoff
await orch.route(input, (i, agents) => i.includes("analyze") ? "analyst" : "research");
await orch.llmRoute(input, llm, { research: "find info", analyst: "analyze data" });
orch.enableHandoff("research", ["analyst"]);

const { WorkflowBuilder } = require("@munesoft/agent");

const workflow = new WorkflowBuilder({ name: "Support Ticket Flow" })
  .start("start")
  .agent("triage",    { agent: "triage",  input: (ctx) => ctx.issue })
  .condition("check", { condition: (ctx) => ctx.triage_output?.priority === "high", onTrue: "escalate", onFalse: "queue" })
  .agent("escalate",  { agent: "urgent",  input: (ctx) => ctx.triage_output?.ticketId })
  .agent("queue",     { agent: "normal",  input: (ctx) => ctx.triage_output?.ticketId })
  .transform("enrich", (ctx) => ({ ...ctx, processedAt: new Date().toISOString() }))
  .end("end")
  .connect("start","triage").connect("triage","check")
  .connect("escalate","enrich").connect("queue","enrich").connect("enrich","end")
  .build();

const result = await workflow.execute(orchestrator, { issue: "server is down URGENT" });
console.log(workflow.diagram());  // text diagram
const json = workflow.toJSON();   // export for a visual editor

agent.events.on("intent.parsed",  ({ intent }) => {});
agent.events.on("tool.executed",  ({ tool, success, duration }) => {});
agent.events.on("verify.checked", ({ passed, score }) => {});
agent.events.on("repair.attempt", ({ attempt, feedback }) => {});
agent.events.on("*",              ({ event, ...data }) => {}); // all events

await agent.events.emitAsync("custom", { data });                 // await async handlers
const payload = await agent.events.waitFor("agent.run", { timeout: 5000 });

await agent.stream("Send invoice to John for $200", (stage, data) => {
  if (stage === "intent")   console.log("Action:", data.intent.action);
  if (stage === "routing")  console.log("Routed via:", data.decision.strategy);
  if (stage === "verified") console.log("Verified:", data.passed);
  if (stage === "done")     console.log("Done in", data.response.duration, "ms");
});

@munesoft/agent/
├── index.js                    # Barrel — every public export
├── index.d.ts                  # TypeScript definitions
├── llms.txt                    # Machine-readable overview for LLMs
├── packages/
│   ├── core/                   # Agent + verify/repair loop + Execution Engine
│   ├── intent/                 # Intent Parser (rules · LLM · function calling)
│   ├── router/                 # Router Brain (scored resolution + schema validation)
│   ├── verify/                 # Verification System + check factories
│   ├── memory/                 # MemoryLayer (namespaces, TTL) + adapters (atomic file writes)
│   ├── session/                # SessionStore, recorder, recall tool, history-research agent
│   ├── coordination/           # FileCoordinator, safeParallel, researchThenEdit
│   ├── guardrails/             # Sanitization, secret redaction, rate limits, validators
│   ├── tools/                  # Tool Registry (aliases, tags)
│   ├── events/                 # Event Bus (emitAsync, waitFor, wildcard)
│   ├── orchestrator/           # Multi-agent orchestrator (file-aware parallel)
│   ├── workflow/               # Visual Workflow Builder
│   ├── integrations/           # Opt-in munesoft-stack adapters (lazy-loaded)
│   └── llm/
│       ├── index.js            # Factory: createLLM, createBridge, listProviders/Bridges
│       ├── base.js             # BaseLLMAdapter (HTTP hardening: request timeout, non-2xx)
│       ├── providers/          # 21 LLM provider adapters
│       └── bridges/            # 23 framework bridges
├── examples/
│   ├── invoice-agent.js        support-agent.js     multi-agent.js
│   ├── workflow.js             verified-agent.js    research-then-edit.js
│   └── stack-agent.js          # Full munesoft-stack showcase
└── tests/
    ├── run-all.js              # Core suite (47)
    ├── run-v2.js               # v2 suite (136)
    ├── run-integration.js      # End-to-end orchestration (3)
    └── run-integrations.js     # Munesoft-stack adapters (14, self-skipping)

npm test                # 186 core tests (core + v2 + integration) — zero deps required
npm run test:integrations  # 14 munesoft-stack adapter tests (skips packages you don't have)
npm run test:all        # everything (200 tests)

npm run example            # invoice agent
npm run example:verified   # router brain + verification + auto-repair
npm run example:research   # session memory + file-safe orchestration
npm run example:stack      # full munesoft-stack integration

const {
  ApprovalPolicy, ModelRouter, TraceCollector, Evaluator,
  FileCheckpointStore, runDurable, defineTool,
  MCPDiscovery, PluginRegistry,
} = require("@munesoft/agent");

const approval = new ApprovalPolicy({
  rules: [{ tags: ["destructive"], decision: "ask" }],
  approve: async ({ tool }) => confirmInYourUI(tool.name),
});

const agent = createAgent({ name: "operator", approval, tools: [
  defineTool({
    name: "deploy", description: "Deploy a service",
    jsonSchema: { type: "object", required: ["service"], properties: { service: { type: "string" } } },
    options: { tags: ["destructive"] },
    handler: async ({ service }) => deploy(service),
  }),
] });

for await (const update of agent.streamEvents("deploy billing")) {
  renderProgress(update);
}