@ironflow/node 0.20.2 → 0.21.0

package/dist/agent/errors.js

@@ -0,0 +1,136 @@
+/**
+ * Agent module error classes.
+ *
+ * All extend IronflowError. Codes are stable for programmatic handling.
+ */
+import { IronflowError } from "@ironflow/core";
+/**
+ * Thrown when an agent exceeds its configured turn budget.
+ *
+ * Default budget is 20 turns. Configurable via AgentConfig.maxTurns.
+ */
+export class MaxTurnsExceededError extends IronflowError {
+    constructor(maxTurns, options) {
+        super(`agent exceeded maxTurns (${maxTurns})`, {
+            code: "AGENT_MAX_TURNS_EXCEEDED",
+            retryable: false,
+            details: { maxTurns },
+            cause: options?.cause,
+        });
+        this.name = "MaxTurnsExceededError";
+    }
+}
+/**
+ * Base class for classified LLM errors emitted by llm().
+ */
+export class LLMError extends IronflowError {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "LLMError";
+    }
+}
+/**
+ * Provider refused the request (safety, policy, etc.).
+ */
+export class LLMRefusalError extends LLMError {
+    constructor(message, options) {
+        super(message, {
+            code: "LLM_REFUSAL",
+            retryable: false,
+            details: options?.details,
+            cause: options?.cause,
+        });
+        this.name = "LLMRefusalError";
+    }
+}
+/**
+ * Provider returned content that failed JSON parsing when JSON was required.
+ */
+export class LLMInvalidJSONError extends LLMError {
+    constructor(message, options) {
+        super(message, {
+            code: "LLM_INVALID_JSON",
+            retryable: true,
+            details: options?.details,
+            cause: options?.cause,
+        });
+        this.name = "LLMInvalidJSONError";
+    }
+}
+/**
+ * Provider truncated the response by hitting max_tokens.
+ */
+export class LLMMaxTokensError extends LLMError {
+    constructor(message, options) {
+        super(message, {
+            code: "LLM_MAX_TOKENS",
+            retryable: false,
+            details: options?.details,
+            cause: options?.cause,
+        });
+        this.name = "LLMMaxTokensError";
+    }
+}
+/**
+ * Thrown when tool() input fails Zod validation.
+ *
+ * Distinct from generic ValidationError so callers can differentiate
+ * agent-tool input failures from event-payload schema failures.
+ */
+export class ToolValidationError extends IronflowError {
+    constructor(toolName, issues, options) {
+        super(`tool "${toolName}" input validation failed`, {
+            code: "AGENT_TOOL_VALIDATION",
+            retryable: false,
+            details: { toolName, issues },
+            cause: options?.cause,
+        });
+        this.name = "ToolValidationError";
+    }
+}
+/**
+ * Thrown when AgentConfig.tools contains two or more definitions sharing
+ * the same name. Silent overwrite would let LLM-driven dispatch route to
+ * an unintended handler — so we fail loudly at agent construction.
+ */
+export class DuplicateToolError extends IronflowError {
+    constructor(toolName) {
+        super(`duplicate tool "${toolName}" registered on AgentConfig.tools`, {
+            code: "AGENT_DUPLICATE_TOOL",
+            retryable: false,
+            details: { toolName },
+        });
+        this.name = "DuplicateToolError";
+    }
+}
+/**
+ * Thrown when ctx.tool(name, args) is called with a name that isn't
+ * registered on AgentConfig.tools.
+ */
+export class ToolNotFoundError extends IronflowError {
+    constructor(toolName) {
+        super(`tool "${toolName}" not registered on AgentConfig.tools — register it or call by reference`, {
+            code: "AGENT_TOOL_NOT_FOUND",
+            retryable: false,
+            details: { toolName },
+        });
+        this.name = "ToolNotFoundError";
+    }
+}
+/**
+ * Thrown when memory.entityStream() is called without a projection.
+ *
+ * Per architecture decision: raw event replay is not exposed through
+ * the agent memory API. Consumers must define a projection.
+ */
+export class MemoryProjectionRequiredError extends IronflowError {
+    constructor(streamId) {
+        super(`memory.entityStream("${streamId}") requires a projection — raw replay is not exposed via the agent API`, {
+            code: "AGENT_MEMORY_PROJECTION_REQUIRED",
+            retryable: false,
+            details: { streamId },
+        });
+        this.name = "MemoryProjectionRequiredError";
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/agent/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/agent/errors.ts"],"names":[],"mappings":"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"}

package/dist/agent/index.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @ironflow/node/agent — durable agent primitives.
+ *
+ * The agent module is sugar over the existing step client. Each helper
+ * (tool, llm, approve, memory, spawn) records durable steps under the
+ * hood, so agents inherit Ironflow's crash-resume, replay, audit, and
+ * scoped-injection semantics with no new server primitives.
+ *
+ * Anti-scope (locked in CEO + eng review):
+ *   - No LLM provider router. Callers bring their own provider SDK and
+ *     pass the provider call into llm() — the wrapper memoizes the result.
+ *   - No prompt templating. Reasoning frameworks (LangGraph, Claude SDK,
+ *     CrewAI) own that surface. Ironflow hosts them, not replaces them.
+ *   - No graph execution. agent() runs a plain async handler.
+ *
+ * Public API:
+ *
+ *   import { agent, defineTool, exposeMcp } from "@ironflow/node/agent";
+ *
+ *   // tool / llm / approve / memory / spawn are ctx-injected helpers,
+ *   // destructured inside the agent handler:
+ *   agent({ id: "..." }, async ({ step, tool, llm, approve, memory, spawn }) => {
+ *     // ...
+ *   });
+ *
+ * See docs/explanation/comparison-agents.md for the layering model.
+ */
+export type { AgentConfig, AgentContext, AgentHandler, ApproveFn, ApproveOptions, ApproveResult, ExposeMcpConfig, IronflowAgent, LLMClient, LLMCompleteRequest, LLMCompleteResult, McpToolDef, MemoryAppendOptions, MemoryClient, MemoryGetOptions, MemoryConfig, SpawnFn, SpawnOptions, SpawnResult, AnyToolDefinition, ToolDefinition, ToolFn, ToolIdempotency, } from "./types.js";
+export { DuplicateToolError, LLMError, LLMInvalidJSONError, LLMMaxTokensError, LLMRefusalError, MaxTurnsExceededError, MemoryProjectionRequiredError, ToolNotFoundError, ToolValidationError, } from "./errors.js";
+export { agent } from "./agent.js";
+export { defineTool } from "./tool.js";
+export { exposeMcp } from "./mcp.js";
+export type { ExposeMcpHandle } from "./mcp.js";
+export type { MemoryBackend } from "./memory.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/agent/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agent/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,YAAY,EACV,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,SAAS,EACT,cAAc,EACd,aAAa,EACb,eAAe,EACf,aAAa,EACb,SAAS,EACT,kBAAkB,EAClB,iBAAiB,EACjB,UAAU,EACV,mBAAmB,EACnB,YAAY,EACZ,gBAAgB,EAChB,YAAY,EACZ,OAAO,EACP,YAAY,EACZ,WAAW,EACX,iBAAiB,EACjB,cAAc,EACd,MAAM,EACN,eAAe,GAChB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,kBAAkB,EAClB,QAAQ,EACR,mBAAmB,EACnB,iBAAiB,EACjB,eAAe,EACf,qBAAqB,EACrB,6BAA6B,EAC7B,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrC,YAAY,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAChD,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC"}

package/dist/agent/index.js

@@ -0,0 +1,32 @@
+/**
+ * @ironflow/node/agent — durable agent primitives.
+ *
+ * The agent module is sugar over the existing step client. Each helper
+ * (tool, llm, approve, memory, spawn) records durable steps under the
+ * hood, so agents inherit Ironflow's crash-resume, replay, audit, and
+ * scoped-injection semantics with no new server primitives.
+ *
+ * Anti-scope (locked in CEO + eng review):
+ *   - No LLM provider router. Callers bring their own provider SDK and
+ *     pass the provider call into llm() — the wrapper memoizes the result.
+ *   - No prompt templating. Reasoning frameworks (LangGraph, Claude SDK,
+ *     CrewAI) own that surface. Ironflow hosts them, not replaces them.
+ *   - No graph execution. agent() runs a plain async handler.
+ *
+ * Public API:
+ *
+ *   import { agent, defineTool, exposeMcp } from "@ironflow/node/agent";
+ *
+ *   // tool / llm / approve / memory / spawn are ctx-injected helpers,
+ *   // destructured inside the agent handler:
+ *   agent({ id: "..." }, async ({ step, tool, llm, approve, memory, spawn }) => {
+ *     // ...
+ *   });
+ *
+ * See docs/explanation/comparison-agents.md for the layering model.
+ */
+export { DuplicateToolError, LLMError, LLMInvalidJSONError, LLMMaxTokensError, LLMRefusalError, MaxTurnsExceededError, MemoryProjectionRequiredError, ToolNotFoundError, ToolValidationError, } from "./errors.js";
+export { agent } from "./agent.js";
+export { defineTool } from "./tool.js";
+export { exposeMcp } from "./mcp.js";
+//# sourceMappingURL=index.js.map

package/dist/agent/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/agent/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AA4BH,OAAO,EACL,kBAAkB,EAClB,QAAQ,EACR,mBAAmB,EACnB,iBAAiB,EACjB,eAAe,EACf,qBAAqB,EACrB,6BAA6B,EAC7B,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC"}

package/dist/agent/internal-registry.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Process-local registry that links exposeMcp() to serve()'s dispatch
+ * handler. Keyed by qualified name (`{agentName}.{toolName}`).
+ *
+ * The Ironflow server holds the canonical registry (NATS KV in cluster
+ * mode, in-memory in single-node). This map is the SDK's local mirror —
+ * we need the McpToolDef closure (handler + Zod schemas) and the HMAC
+ * secret to validate inbound dispatches.
+ *
+ * Single instance per Node.js process. Re-registering the same agent
+ * name overwrites the prior entries; unregister removes them. HMR may
+ * leave stale entries until the next exposeMcp() call rotates them —
+ * acceptable for dev, documented in the README.
+ */
+import type { AnyMcpToolDef } from "./types.js";
+export interface RegisteredTool {
+    agentName: string;
+    qualifiedName: string;
+    hmacSecret: string;
+    def: AnyMcpToolDef;
+}
+export declare function registerLocal(entry: RegisteredTool): void;
+export declare function unregisterLocal(agentName: string): string[];
+export declare function lookupLocal(qualifiedName: string): RegisteredTool | undefined;
+/** Test-only — drop all entries. */
+export declare function clearLocalForTests(): void;
+//# sourceMappingURL=internal-registry.d.ts.map

package/dist/agent/internal-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal-registry.d.ts","sourceRoot":"","sources":["../../src/agent/internal-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,aAAa,CAAC;CACpB;AAID,wBAAgB,aAAa,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI,CAEzD;AAED,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,CAS3D;AAED,wBAAgB,WAAW,CAAC,aAAa,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAE7E;AAED,oCAAoC;AACpC,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC"}

package/dist/agent/internal-registry.js

@@ -0,0 +1,36 @@
+/**
+ * Process-local registry that links exposeMcp() to serve()'s dispatch
+ * handler. Keyed by qualified name (`{agentName}.{toolName}`).
+ *
+ * The Ironflow server holds the canonical registry (NATS KV in cluster
+ * mode, in-memory in single-node). This map is the SDK's local mirror —
+ * we need the McpToolDef closure (handler + Zod schemas) and the HMAC
+ * secret to validate inbound dispatches.
+ *
+ * Single instance per Node.js process. Re-registering the same agent
+ * name overwrites the prior entries; unregister removes them. HMR may
+ * leave stale entries until the next exposeMcp() call rotates them —
+ * acceptable for dev, documented in the README.
+ */
+const registry = new Map();
+export function registerLocal(entry) {
+    registry.set(entry.qualifiedName, entry);
+}
+export function unregisterLocal(agentName) {
+    const removed = [];
+    for (const [qualifiedName, entry] of registry) {
+        if (entry.agentName === agentName) {
+            registry.delete(qualifiedName);
+            removed.push(qualifiedName);
+        }
+    }
+    return removed;
+}
+export function lookupLocal(qualifiedName) {
+    return registry.get(qualifiedName);
+}
+/** Test-only — drop all entries. */
+export function clearLocalForTests() {
+    registry.clear();
+}
+//# sourceMappingURL=internal-registry.js.map

package/dist/agent/internal-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal-registry.js","sourceRoot":"","sources":["../../src/agent/internal-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAWH,MAAM,QAAQ,GAAG,IAAI,GAAG,EAA0B,CAAC;AAEnD,MAAM,UAAU,aAAa,CAAC,KAAqB;IACjD,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,aAAa,EAAE,KAAK,CAAC,CAAC;AAC3C,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,SAAiB;IAC/C,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,KAAK,MAAM,CAAC,aAAa,EAAE,KAAK,CAAC,IAAI,QAAQ,EAAE,CAAC;QAC9C,IAAI,KAAK,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;YAClC,QAAQ,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC;YAC/B,OAAO,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;QAC9B,CAAC;IACH,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,aAAqB;IAC/C,OAAO,QAAQ,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;AACrC,CAAC;AAED,oCAAoC;AACpC,MAAM,UAAU,kBAAkB;IAChC,QAAQ,CAAC,KAAK,EAAE,CAAC;AACnB,CAAC"}

package/dist/agent/internal.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Internal utilities shared by agent module wrappers.
+ *
+ * Not part of the public API surface — `index.ts` does not re-export.
+ */
+import type { Duration } from "@ironflow/core";
+/**
+ * Normalize a Duration (string | number) into the ms-suffixed string form
+ * that step.run options.timeout expects.
+ *
+ *   normalizeDuration("30s")  → "30s"
+ *   normalizeDuration(5000)   → "5000ms"
+ *   normalizeDuration(undefined) → undefined
+ */
+export declare function normalizeDuration(value: Duration | undefined): string | undefined;
+/**
+ * Escape a value for safe interpolation into a CEL-style match expression
+ * (`data.field == "<value>"`). Replaces `\` and `"` with escaped forms.
+ *
+ * Internal IDs are unlikely to contain quotes, but defending against it
+ * prevents broken filters if upstream ever loosens the format.
+ */
+export declare function escapeMatchValue(value: string): string;
+//# sourceMappingURL=internal.d.ts.map

package/dist/agent/internal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal.d.ts","sourceRoot":"","sources":["../../src/agent/internal.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE/C;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,QAAQ,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAGjF;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEtD"}

package/dist/agent/internal.js

@@ -0,0 +1,29 @@
+/**
+ * Internal utilities shared by agent module wrappers.
+ *
+ * Not part of the public API surface — `index.ts` does not re-export.
+ */
+/**
+ * Normalize a Duration (string | number) into the ms-suffixed string form
+ * that step.run options.timeout expects.
+ *
+ *   normalizeDuration("30s")  → "30s"
+ *   normalizeDuration(5000)   → "5000ms"
+ *   normalizeDuration(undefined) → undefined
+ */
+export function normalizeDuration(value) {
+    if (value === undefined)
+        return undefined;
+    return typeof value === "number" ? `${value}ms` : value;
+}
+/**
+ * Escape a value for safe interpolation into a CEL-style match expression
+ * (`data.field == "<value>"`). Replaces `\` and `"` with escaped forms.
+ *
+ * Internal IDs are unlikely to contain quotes, but defending against it
+ * prevents broken filters if upstream ever loosens the format.
+ */
+export function escapeMatchValue(value) {
+    return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+//# sourceMappingURL=internal.js.map

package/dist/agent/internal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal.js","sourceRoot":"","sources":["../../src/agent/internal.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAA2B;IAC3D,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC1C,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,KAAK,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC;AAC1D,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAa;IAC5C,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;AAC3D,CAAC"}

package/dist/agent/llm.d.ts

@@ -0,0 +1,39 @@
+/**
+ * llm() — memoized completion sugar with classified error surface.
+ *
+ * The wrapper does not own a provider router. Callers pass a closure
+ * (request.call) that talks to their provider of choice and returns a
+ * normalized LLMCompleteResult. The wrapper:
+ *
+ *   1. Increments the agent turn counter and gates against maxTurns.
+ *   2. Wraps the closure in step.run so the assistant response is
+ *      memoized for crash-resume.
+ *   3. Inspects result.finishReason to raise classified errors:
+ *        "refusal"             → LLMRefusalError
+ *        "max_tokens"/"length" → LLMMaxTokensError
+ *      JSON-parse failures must be raised by the caller, by detecting
+ *      invalid JSON in their closure and throwing LLMInvalidJSONError.
+ *
+ * Anti-scope: provider routing, prompt templating, and streaming all
+ * stay out of this module. See module README.
+ */
+import type { StepClient } from "@ironflow/core";
+import type { LLMClient } from "./types.js";
+/**
+ * Turn counter shared between llm() invocations and AgentContext.turn.
+ *
+ * Plain mutable object so the AgentContext getter can read the live value
+ * without callers needing a reactive abstraction.
+ */
+export interface TurnCounter {
+    value: number;
+}
+/** Construct a fresh turn counter. */
+export declare function createTurnCounter(): TurnCounter;
+/**
+ * Build an LLMClient bound to the given step + counter.
+ *
+ * Exported for use by agent.ts; not part of the public API surface.
+ */
+export declare function makeLlm(step: StepClient, counter: TurnCounter, maxTurns: number): LLMClient;
+//# sourceMappingURL=llm.d.ts.map

package/dist/agent/llm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm.d.ts","sourceRoot":"","sources":["../../src/agent/llm.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAMjD,OAAO,KAAK,EACV,SAAS,EAGV,MAAM,YAAY,CAAC;AAEpB;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;CACf;AAED,sCAAsC;AACtC,wBAAgB,iBAAiB,IAAI,WAAW,CAE/C;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CACrB,IAAI,EAAE,UAAU,EAChB,OAAO,EAAE,WAAW,EACpB,QAAQ,EAAE,MAAM,GACf,SAAS,CAYX"}

package/dist/agent/llm.js

@@ -0,0 +1,59 @@
+/**
+ * llm() — memoized completion sugar with classified error surface.
+ *
+ * The wrapper does not own a provider router. Callers pass a closure
+ * (request.call) that talks to their provider of choice and returns a
+ * normalized LLMCompleteResult. The wrapper:
+ *
+ *   1. Increments the agent turn counter and gates against maxTurns.
+ *   2. Wraps the closure in step.run so the assistant response is
+ *      memoized for crash-resume.
+ *   3. Inspects result.finishReason to raise classified errors:
+ *        "refusal"             → LLMRefusalError
+ *        "max_tokens"/"length" → LLMMaxTokensError
+ *      JSON-parse failures must be raised by the caller, by detecting
+ *      invalid JSON in their closure and throwing LLMInvalidJSONError.
+ *
+ * Anti-scope: provider routing, prompt templating, and streaming all
+ * stay out of this module. See module README.
+ */
+import { LLMMaxTokensError, LLMRefusalError, MaxTurnsExceededError, } from "./errors.js";
+/** Construct a fresh turn counter. */
+export function createTurnCounter() {
+    return { value: 0 };
+}
+/**
+ * Build an LLMClient bound to the given step + counter.
+ *
+ * Exported for use by agent.ts; not part of the public API surface.
+ */
+export function makeLlm(step, counter, maxTurns) {
+    return {
+        async complete(request) {
+            counter.value += 1;
+            if (counter.value > maxTurns) {
+                throw new MaxTurnsExceededError(maxTurns);
+            }
+            const result = await step.run(`llm.turn`, () => request.call());
+            classifyResult(result);
+            return result;
+        },
+    };
+}
+function classifyResult(result) {
+    const reason = result.finishReason;
+    if (!reason)
+        return;
+    const normalized = reason.toLowerCase();
+    if (normalized === "refusal" || normalized === "safety" || normalized === "content_filter") {
+        throw new LLMRefusalError(`provider refused: ${reason}`, {
+            details: { finishReason: reason, metadata: result.metadata },
+        });
+    }
+    if (normalized === "max_tokens" || normalized === "length") {
+        throw new LLMMaxTokensError(`provider hit max_tokens (${reason})`, {
+            details: { finishReason: reason, metadata: result.metadata },
+        });
+    }
+}
+//# sourceMappingURL=llm.js.map

package/dist/agent/llm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm.js","sourceRoot":"","sources":["../../src/agent/llm.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,qBAAqB,GACtB,MAAM,aAAa,CAAC;AAiBrB,sCAAsC;AACtC,MAAM,UAAU,iBAAiB;IAC/B,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;AACtB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,OAAO,CACrB,IAAgB,EAChB,OAAoB,EACpB,QAAgB;IAEhB,OAAO;QACL,KAAK,CAAC,QAAQ,CAAC,OAA2B;YACxC,OAAO,CAAC,KAAK,IAAI,CAAC,CAAC;YACnB,IAAI,OAAO,CAAC,KAAK,GAAG,QAAQ,EAAE,CAAC;gBAC7B,MAAM,IAAI,qBAAqB,CAAC,QAAQ,CAAC,CAAC;YAC5C,CAAC;YACD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,UAAU,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;YAChE,cAAc,CAAC,MAAM,CAAC,CAAC;YACvB,OAAO,MAAM,CAAC;QAChB,CAAC;KACF,CAAC;AACJ,CAAC;AAED,SAAS,cAAc,CAAC,MAAyB;IAC/C,MAAM,MAAM,GAAG,MAAM,CAAC,YAAY,CAAC;IACnC,IAAI,CAAC,MAAM;QAAE,OAAO;IACpB,MAAM,UAAU,GAAG,MAAM,CAAC,WAAW,EAAE,CAAC;IACxC,IAAI,UAAU,KAAK,SAAS,IAAI,UAAU,KAAK,QAAQ,IAAI,UAAU,KAAK,gBAAgB,EAAE,CAAC;QAC3F,MAAM,IAAI,eAAe,CAAC,qBAAqB,MAAM,EAAE,EAAE;YACvD,OAAO,EAAE,EAAE,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE;SAC7D,CAAC,CAAC;IACL,CAAC;IACD,IAAI,UAAU,KAAK,YAAY,IAAI,UAAU,KAAK,QAAQ,EAAE,CAAC;QAC3D,MAAM,IAAI,iBAAiB,CAAC,4BAA4B,MAAM,GAAG,EAAE;YACjE,OAAO,EAAE,EAAE,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE;SAC7D,CAAC,CAAC;IACL,CAAC;AACH,CAAC"}

package/dist/agent/mcp.d.ts

@@ -0,0 +1,51 @@
+/**
+ * exposeMcp() — register agent tools with Ironflow's AgentToolsService
+ * and serve dispatched invocations over the existing serve() mount.
+ *
+ * Boot-time flow:
+ *
+ *	1. Convert each McpToolDef.input (Zod) → JSON Schema (Draft 2020-12)
+ *	   via z.toJSONSchema().
+ *	2. POST `/ironflow.v1.AgentToolsService/RegisterTool` with
+ *	   {agentName, callbackUrl, tools[]}.
+ *	3. Stash the returned HMAC secret + def closures in the local
+ *	   registry so serve()'s dispatch route can validate inbound calls.
+ *
+ * Callback flow lives in `dispatch.ts` (HMAC verify + Zod parse + handler).
+ *
+ * Authoritative authorization stays server-side: scopes on McpToolDef
+ * are advisory hints to MCP clients. The server enforces api_key.tool_scopes
+ * superset against ToolDef.required_scopes. RegisterTool requires the
+ * `agent:tools:register` action on the calling key.
+ */
+import type { ExposeMcpConfig } from "./types.js";
+/**
+ * Handle returned from exposeMcp(). `unregister()` removes the tools
+ * from both the Ironflow server's registry and the local SDK mirror.
+ */
+export interface ExposeMcpHandle {
+    /** Server name (== agent namespace) reported to MCP clients. */
+    readonly name: string;
+    /** Number of tools registered with the server. */
+    readonly toolCount: number;
+    /** Status indicator. "active" once RegisterTool succeeds. */
+    readonly status: "active";
+    /** Qualified names registered (`{agentName}.{toolName}`). */
+    readonly toolNames: ReadonlyArray<string>;
+    /**
+     * Remove all tools registered under this agent name. Idempotent —
+     * server returns 200 with removed_count=0 if the agent was already
+     * gone. Local registry entries are cleared even if the server call
+     * fails so handler closures don't leak.
+     */
+    unregister(): Promise<void>;
+}
+/**
+ * Register the supplied MCP tool definitions with the Ironflow server.
+ *
+ * Returns an active handle once RegisterTool succeeds. Throws on
+ * empty tool lists, missing config (server URL / API key / callback URL),
+ * or transport failure.
+ */
+export declare function exposeMcp(config: ExposeMcpConfig): Promise<ExposeMcpHandle>;
+//# sourceMappingURL=mcp.d.ts.map

package/dist/agent/mcp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../../src/agent/mcp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AASH,OAAO,KAAK,EAAiB,eAAe,EAAE,MAAM,YAAY,CAAC;AAKjE;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,gEAAgE;IAChE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,kDAAkD;IAClD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,6DAA6D;IAC7D,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;IAC1B,6DAA6D;IAC7D,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC1C;;;;;OAKG;IACH,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7B;AAOD;;;;;;GAMG;AACH,wBAAsB,SAAS,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAmGjF"}