@vauban-org/agent-sdk 0.16.0

package/dist/testing/test-event-bus.js

@@ -0,0 +1,191 @@
+/**
+ * TestEventBus — In-memory EventBusPort for unit testing.
+ *
+ * No Redis dependency. Messages are stored in a Map and dispatched
+ * synchronously to in-process subscribers. Use for agent unit tests
+ * that need to publish/subscribe without infrastructure.
+ *
+ * Extended in SDK v0.17.0 (sprint-615:quick-7) with:
+ *   - publishWithIdempotency (dedup via InMemoryNonceStore)
+ *   - subscribeDomain (signature verification + DLQ routing)
+ *   - replayFrom (ordered replay from a stream ID)
+ *
+ * @public
+ */
+import { signEvent } from "../auth/sign-event.js";
+import { verifyEvent } from "../auth/verify-event.js";
+import { InMemoryNonceStore } from "../auth/nonce-store.js";
+export class TestEventBus {
+    streams = new Map();
+    subscribers = new Map();
+    dlqMessages = new Map();
+    _consumed = new Map();
+    // Domain event support
+    domainStreams = new Map();
+    domainSubscribers = new Map();
+    domainDlq = [];
+    // Two separate stores: publish dedup (producer side) vs consumer-side replay detection
+    publishIdempotencyStore = new InMemoryNonceStore();
+    consumerNonceStore = new InMemoryNonceStore();
+    /**
+     * Secret used to auto-sign events in publishWithIdempotency.
+     * Override in tests via setSigningSecret().
+     */
+    signingSecret = "test-secret-32-bytes-padding-here";
+    /** Override the signing secret for tests that check signature roundtrip. */
+    setSigningSecret(secret) {
+        this.signingSecret = secret;
+    }
+    // ─── EventBusPort ──────────────────────────────────────────────────────────
+    async publish(event, stream) {
+        if (!event.id)
+            throw new Error("CloudEvent.id is required");
+        if (event.specversion !== "1.0")
+            throw new Error("CloudEvent.specversion must be 1.0");
+        const events = this.streams.get(stream) ?? [];
+        events.push(event);
+        this.streams.set(stream, events);
+        // Track consumed events per stream
+        const consumed = this._consumed.get(stream) ?? [];
+        consumed.push(event);
+        this._consumed.set(stream, consumed);
+        // Dispatch to subscribers
+        const streamSubs = this.subscribers.get(stream);
+        if (streamSubs) {
+            for (const handler of streamSubs.values()) {
+                await handler(event);
+            }
+        }
+    }
+    async publishWithIdempotency(event, key) {
+        // Dedup: silently skip if key already processed (producer-side)
+        const isNew = await this.publishIdempotencyStore.setNX(key, 10 * 60 * 1000);
+        if (!isNew)
+            return;
+        // Auto-sign the event
+        const signature = signEvent(event, this.signingSecret);
+        const signed = { ...event, signature };
+        // Store in domain stream
+        const streamKey = `domain:${event.type}`;
+        const stored = this.domainStreams.get(streamKey) ?? [];
+        const streamId = `${Date.now()}-${stored.length}`;
+        stored.push({ streamId, event: signed });
+        this.domainStreams.set(streamKey, stored);
+        // Dispatch to domain subscribers
+        const typeSubs = this.domainSubscribers.get(event.type);
+        if (typeSubs) {
+            for (const handler of typeSubs.values()) {
+                await handler(signed);
+            }
+        }
+    }
+    subscribe(stream, consumerGroup, handler) {
+        const key = `${stream}:${consumerGroup}`;
+        let streamSubs = this.subscribers.get(stream);
+        if (!streamSubs) {
+            streamSubs = new Map();
+            this.subscribers.set(stream, streamSubs);
+        }
+        streamSubs.set(key, handler);
+        return Promise.resolve(() => {
+            const subs = this.subscribers.get(stream);
+            if (subs) {
+                subs.delete(key);
+                if (subs.size === 0)
+                    this.subscribers.delete(stream);
+            }
+        });
+    }
+    subscribeDomain(eventType, handler, opts) {
+        const groupId = opts?.groupId ?? "default";
+        const key = `${eventType}:${groupId}`;
+        let typeSubs = this.domainSubscribers.get(eventType);
+        if (!typeSubs) {
+            typeSubs = new Map();
+            this.domainSubscribers.set(eventType, typeSubs);
+        }
+        // Wrap handler with signature verification + DLQ routing
+        const wrappedHandler = async (event) => {
+            try {
+                await verifyEvent(event, this.signingSecret, {
+                    nonceStore: this.consumerNonceStore,
+                });
+                await handler(event);
+            }
+            catch {
+                // Route to DLQ on any auth failure
+                this.domainDlq.push(event);
+            }
+        };
+        typeSubs.set(key, wrappedHandler);
+        return {
+            unsubscribe: async () => {
+                const subs = this.domainSubscribers.get(eventType);
+                if (subs) {
+                    subs.delete(key);
+                    if (subs.size === 0)
+                        this.domainSubscribers.delete(eventType);
+                }
+            },
+        };
+    }
+    async *replayFrom(streamKey, fromId) {
+        const stored = this.domainStreams.get(streamKey) ?? [];
+        for (const { streamId, event } of stored) {
+            // Compare stream IDs lexicographically (Redis stream ID format: timestamp-seq)
+            if (streamId >= fromId) {
+                yield event;
+            }
+        }
+    }
+    dlq() {
+        return {
+            depth: async () => this.dlqMessages.size,
+            replay: async (eventId) => {
+                const event = this.dlqMessages.get(eventId);
+                if (event) {
+                    this.dlqMessages.delete(eventId);
+                    // Re-publish to original stream (inferred from type convention)
+                    const stream = `vauban.events.${event.type
+                        .split(".")
+                        .slice(1, 3)
+                        .join(".")}`;
+                    await this.publish(event, stream);
+                }
+            },
+        };
+    }
+    async pendingCount(_stream, _consumerGroup) {
+        return 0;
+    }
+    // ─── Test Helpers ─────────────────────────────────────────────────────────
+    /** All events published to a stream. */
+    published(stream) {
+        return this.streams.get(stream) ?? [];
+    }
+    /** All events consumed (published) to a stream since creation. */
+    consumed(stream) {
+        return this._consumed.get(stream) ?? [];
+    }
+    /** Move an event to DLQ (simulates poison pill). */
+    moveToDlq(event) {
+        this.dlqMessages.set(event.id, structuredClone(event));
+    }
+    /** Domain DLQ — events rejected by signature/clock/replay checks. */
+    get domainDlqEvents() {
+        return [...this.domainDlq];
+    }
+    /** Clear all state. */
+    reset() {
+        this.streams.clear();
+        this.subscribers.clear();
+        this.dlqMessages.clear();
+        this._consumed.clear();
+        this.domainStreams.clear();
+        this.domainSubscribers.clear();
+        this.domainDlq.length = 0;
+        this.publishIdempotencyStore.reset();
+        this.consumerNonceStore.reset();
+    }
+}
+//# sourceMappingURL=test-event-bus.js.map

package/dist/testing/test-event-bus.js.map

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

package/dist/tools/index.d.ts

@@ -0,0 +1,5 @@
+export { ToolRegistryImpl } from "./registry.js";
+export { isValidToolName } from "./types.js";
+export { zodToJsonSchema } from "./zod-to-json-schema.js";
+export type { AgentTool, MCPToolDefinition, ToolError, ToolErrorCode, ToolRegistry, ToolResult, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC1D,YAAY,EACV,SAAS,EACT,iBAAiB,EACjB,SAAS,EACT,aAAa,EACb,YAAY,EACZ,UAAU,GACX,MAAM,YAAY,CAAC"}

package/dist/tools/index.js

@@ -0,0 +1,4 @@
+export { ToolRegistryImpl } from "./registry.js";
+export { isValidToolName } from "./types.js";
+export { zodToJsonSchema } from "./zod-to-json-schema.js";
+//# sourceMappingURL=index.js.map

package/dist/tools/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/tools/registry.d.ts

@@ -0,0 +1,20 @@
+/**
+ * ToolRegistryImpl — in-memory reference implementation of the
+ * `ToolRegistry` contract. CC host overrides this with an OTel-traced
+ * version (src/tools/registry.ts) that implements the same contract.
+ */
+import type { z } from "zod";
+import type { AgentTool, MCPToolDefinition, ToolRegistry, ToolResult } from "./types.js";
+export declare class ToolRegistryImpl implements ToolRegistry {
+    private readonly tools;
+    register<T extends z.ZodTypeAny>(tool: AgentTool<T>): ToolResult<void>;
+    unregister(name: string): boolean;
+    get(name: string): AgentTool | undefined;
+    has(name: string): boolean;
+    listNames(): string[];
+    listMCPDefinitions(): MCPToolDefinition[];
+    get size(): number;
+    clear(): void;
+    execute(name: string, args: unknown): Promise<ToolResult>;
+}
+//# sourceMappingURL=registry.d.ts.map

package/dist/tools/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/tools/registry.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EACV,SAAS,EACT,iBAAiB,EACjB,YAAY,EACZ,UAAU,EACX,MAAM,YAAY,CAAC;AAIpB,qBAAa,gBAAiB,YAAW,YAAY;IACnD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgC;IAEtD,QAAQ,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,IAAI,CAAC;IA2BtE,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIjC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS;IAIxC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI1B,SAAS,IAAI,MAAM,EAAE;IAIrB,kBAAkB,IAAI,iBAAiB,EAAE;IAQzC,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,KAAK,IAAI,IAAI;IAIP,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,UAAU,CAAC;CA2ChE"}

package/dist/tools/registry.js

@@ -0,0 +1,102 @@
+/**
+ * ToolRegistryImpl — in-memory reference implementation of the
+ * `ToolRegistry` contract. CC host overrides this with an OTel-traced
+ * version (src/tools/registry.ts) that implements the same contract.
+ */
+import { isValidToolName } from "./types.js";
+import { zodToJsonSchema } from "./zod-to-json-schema.js";
+export class ToolRegistryImpl {
+    tools = new Map();
+    register(tool) {
+        if (!isValidToolName(tool.name)) {
+            return {
+                ok: false,
+                error: {
+                    code: "validation_failed",
+                    message: `Invalid tool name "${tool.name}" — must be lowercase snake_case (a-z0-9_), 1-63 chars, starting with a letter`,
+                    toolName: tool.name,
+                },
+            };
+        }
+        if (this.tools.has(tool.name)) {
+            return {
+                ok: false,
+                error: {
+                    code: "duplicate_name",
+                    message: `Tool "${tool.name}" is already registered`,
+                    toolName: tool.name,
+                },
+            };
+        }
+        this.tools.set(tool.name, tool);
+        return { ok: true, data: undefined };
+    }
+    unregister(name) {
+        return this.tools.delete(name);
+    }
+    get(name) {
+        return this.tools.get(name);
+    }
+    has(name) {
+        return this.tools.has(name);
+    }
+    listNames() {
+        return [...this.tools.keys()];
+    }
+    listMCPDefinitions() {
+        return [...this.tools.values()].map((tool) => ({
+            name: tool.name,
+            description: tool.description,
+            inputSchema: zodToJsonSchema(tool.parameters),
+        }));
+    }
+    get size() {
+        return this.tools.size;
+    }
+    clear() {
+        this.tools.clear();
+    }
+    async execute(name, args) {
+        const tool = this.tools.get(name);
+        if (!tool) {
+            return {
+                ok: false,
+                error: {
+                    code: "not_found",
+                    message: `Unknown tool: ${name}`,
+                    toolName: name,
+                },
+            };
+        }
+        const parseResult = tool.parameters.safeParse(args);
+        if (!parseResult.success) {
+            const issues = parseResult.error.issues
+                .map((i) => `${i.path.join(".")}: ${i.message}`)
+                .join("; ");
+            return {
+                ok: false,
+                error: {
+                    code: "validation_failed",
+                    message: `Validation failed for tool "${name}": ${issues}`,
+                    toolName: name,
+                },
+            };
+        }
+        try {
+            const data = await tool.execute(parseResult.data);
+            return { ok: true, data };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                ok: false,
+                error: {
+                    code: "execution_failed",
+                    message: `Tool "${name}" execution failed: ${message}`,
+                    toolName: name,
+                },
+            };
+        }
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/tools/registry.js.map

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

package/dist/tools/types.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Tool registry contract — shared types used by AgentLoop and SdkAgentLoop.
+ *
+ * This is the single source of truth for the tool surface. Concrete
+ * registries (in-memory, CC-traced, remote-proxy) all implement
+ * `ToolRegistry` defined here.
+ */
+import type { z } from "zod";
+import type { SdkCapability } from "../permissions/sdk-permissions.js";
+/**
+ * An agent tool: named capability with typed parameters and async handler.
+ * The Zod schema doubles as runtime validator AND MCP inputSchema generator.
+ *
+ * Capability annotations (`capability`, `mcpScopes`, `dangerous`) are read
+ * by SdkAgentLoop for permission enforcement and HITL gating. They are
+ * ignored by the minimal AgentLoop (which only looks at `dangerous`).
+ */
+export interface AgentTool<TParams extends z.ZodTypeAny = z.ZodTypeAny> {
+    /** Unique tool name (snake_case, e.g. "query_knowledge"). */
+    readonly name: string;
+    /** Human-readable description for LLM tool-use. */
+    readonly description: string;
+    /** Zod schema for parameter validation. */
+    readonly parameters: TParams;
+    /** Async handler — receives validated params, returns unknown result. */
+    readonly execute: (params: z.infer<TParams>) => Promise<unknown>;
+    /** Capability surface required. Defaults to "mcp" in SdkAgentLoop. */
+    readonly capability?: SdkCapability;
+    /** Required MCP sub-scopes (e.g. ["brain:write"]). Only honoured when capability === "mcp". */
+    readonly mcpScopes?: readonly string[];
+    /** If true, HITL approval required before each call. */
+    readonly dangerous?: boolean;
+}
+export type ToolResult<T = unknown> = {
+    ok: true;
+    data: T;
+} | {
+    ok: false;
+    error: ToolError;
+};
+export interface ToolError {
+    code: ToolErrorCode;
+    message: string;
+    toolName: string;
+}
+export type ToolErrorCode = "not_found" | "validation_failed" | "execution_failed" | "duplicate_name";
+export interface MCPToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: Record<string, unknown>;
+        required?: string[];
+    };
+}
+export declare function isValidToolName(name: string): boolean;
+/**
+ * Unified tool registry contract consumed by both AgentLoop (minimal) and
+ * SdkAgentLoop (Anthropic-direct). Concrete implementations (CC, test doubles)
+ * must implement every method.
+ */
+export interface ToolRegistry {
+    /** Register a tool. Returns ok or a structured error. */
+    register<T extends z.ZodTypeAny>(tool: AgentTool<T>): ToolResult<void>;
+    /** Unregister a tool by name. Returns false if not found. */
+    unregister(name: string): boolean;
+    /** Get a registered tool by name. */
+    get(name: string): AgentTool | undefined;
+    /** Check if a tool is registered. */
+    has(name: string): boolean;
+    /** List all registered tool names. */
+    listNames(): string[];
+    /** List all tools as MCP-compatible definitions (JSON Schema). */
+    listMCPDefinitions(): MCPToolDefinition[];
+    /** Number of registered tools. */
+    readonly size: number;
+    /** Remove all registered tools. */
+    clear(): void;
+    /**
+     * Execute a tool by name with raw (unvalidated) arguments.
+     * Validates against the tool's Zod schema before invoking execute().
+     */
+    execute(name: string, args: unknown): Promise<ToolResult>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/tools/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/tools/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mCAAmC,CAAC;AAIvE;;;;;;;GAOG;AACH,MAAM,WAAW,SAAS,CAAC,OAAO,SAAS,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU;IACpE,6DAA6D;IAC7D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,mDAAmD;IACnD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,2CAA2C;IAC3C,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,yEAAyE;IACzE,QAAQ,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACjE,sEAAsE;IACtE,QAAQ,CAAC,UAAU,CAAC,EAAE,aAAa,CAAC;IACpC,+FAA+F;IAC/F,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,wDAAwD;IACxD,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;CAC9B;AAID,MAAM,MAAM,UAAU,CAAC,CAAC,GAAG,OAAO,IAC9B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,CAAC,CAAA;CAAE,GACrB;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,SAAS,CAAA;CAAE,CAAC;AAEpC,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,aAAa,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,MAAM,aAAa,GACrB,WAAW,GACX,mBAAmB,GACnB,kBAAkB,GAClB,gBAAgB,CAAC;AAIrB,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ,CAAC;QACf,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACpC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;KACrB,CAAC;CACH;AAMD,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAErD;AAID;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,yDAAyD;IACzD,QAAQ,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;IAEvE,6DAA6D;IAC7D,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAElC,qCAAqC;IACrC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAAC;IAEzC,qCAAqC;IACrC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAE3B,sCAAsC;IACtC,SAAS,IAAI,MAAM,EAAE,CAAC;IAEtB,kEAAkE;IAClE,kBAAkB,IAAI,iBAAiB,EAAE,CAAC;IAE1C,kCAAkC;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,mCAAmC;IACnC,KAAK,IAAI,IAAI,CAAC;IAEd;;;OAGG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CAC3D"}

package/dist/tools/types.js

@@ -0,0 +1,13 @@
+/**
+ * Tool registry contract — shared types used by AgentLoop and SdkAgentLoop.
+ *
+ * This is the single source of truth for the tool surface. Concrete
+ * registries (in-memory, CC-traced, remote-proxy) all implement
+ * `ToolRegistry` defined here.
+ */
+// ─── Tool name validation ──────────────────────────────────────────────────
+const TOOL_NAME_REGEX = /^[a-z][a-z0-9_]{0,62}$/;
+export function isValidToolName(name) {
+    return TOOL_NAME_REGEX.test(name);
+}
+//# sourceMappingURL=types.js.map

package/dist/tools/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/tools/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA8DH,8EAA8E;AAE9E,MAAM,eAAe,GAAG,wBAAwB,CAAC;AAEjD,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,OAAO,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACpC,CAAC"}

package/dist/tools/zod-to-json-schema.d.ts

@@ -0,0 +1,11 @@
+import { z } from "zod";
+import type { MCPToolDefinition } from "./types.js";
+/**
+ * Minimal Zod-to-JSON-Schema converter for MCP tool definitions.
+ * Handles the subset of Zod types used in agent tool parameters:
+ * z.object, z.string, z.number, z.boolean, z.array, z.enum, z.optional, z.default.
+ *
+ * No external dependency — avoids adding zod-to-json-schema to direct deps.
+ */
+export declare function zodToJsonSchema(schema: z.ZodTypeAny): MCPToolDefinition["inputSchema"];
+//# sourceMappingURL=zod-to-json-schema.d.ts.map

package/dist/tools/zod-to-json-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zod-to-json-schema.d.ts","sourceRoot":"","sources":["../../src/tools/zod-to-json-schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,CAAC,CAAC,UAAU,GACnB,iBAAiB,CAAC,aAAa,CAAC,CAMlC"}

package/dist/tools/zod-to-json-schema.js

@@ -0,0 +1,92 @@
+import { z } from "zod";
+/**
+ * Minimal Zod-to-JSON-Schema converter for MCP tool definitions.
+ * Handles the subset of Zod types used in agent tool parameters:
+ * z.object, z.string, z.number, z.boolean, z.array, z.enum, z.optional, z.default.
+ *
+ * No external dependency — avoids adding zod-to-json-schema to direct deps.
+ */
+export function zodToJsonSchema(schema) {
+    const jsonSchema = convertZodType(schema);
+    if (jsonSchema.type === "object") {
+        return jsonSchema;
+    }
+    return { type: "object", properties: { value: jsonSchema } };
+}
+function convertZodType(schema) {
+    if (schema instanceof z.ZodOptional) {
+        const inner = convertZodType(schema.unwrap());
+        return withDescription(schema, inner);
+    }
+    if (schema instanceof z.ZodDefault) {
+        const inner = convertZodType(schema._def.innerType);
+        inner.default = schema._def.defaultValue();
+        return withDescription(schema, inner);
+    }
+    if (schema instanceof z.ZodObject) {
+        const shape = schema.shape;
+        const properties = {};
+        const required = [];
+        for (const [key, value] of Object.entries(shape)) {
+            properties[key] = convertZodType(value);
+            if (!isOptionalType(value)) {
+                required.push(key);
+            }
+        }
+        const result = { type: "object", properties };
+        if (required.length > 0) {
+            result.required = required;
+        }
+        return withDescription(schema, result);
+    }
+    if (schema instanceof z.ZodString) {
+        return withDescription(schema, { type: "string" });
+    }
+    if (schema instanceof z.ZodNumber) {
+        return withDescription(schema, { type: "number" });
+    }
+    if (schema instanceof z.ZodBoolean) {
+        return withDescription(schema, { type: "boolean" });
+    }
+    if (schema instanceof z.ZodArray) {
+        return withDescription(schema, {
+            type: "array",
+            items: convertZodType(schema.element),
+        });
+    }
+    if (schema instanceof z.ZodEnum) {
+        return withDescription(schema, {
+            type: "string",
+            enum: schema.options,
+        });
+    }
+    if (schema instanceof z.ZodLiteral) {
+        const jsonType = schema.value === null ? "null" : typeof schema.value;
+        return withDescription(schema, { type: jsonType, const: schema.value });
+    }
+    if (schema instanceof z.ZodRecord) {
+        return withDescription(schema, {
+            type: "object",
+            additionalProperties: convertZodType(schema._def.valueType),
+        });
+    }
+    if (schema instanceof z.ZodUnion) {
+        const options = schema._def.options.map(convertZodType);
+        return withDescription(schema, { oneOf: options });
+    }
+    return {};
+}
+function withDescription(schema, result) {
+    if (schema.description) {
+        result.description = schema.description;
+    }
+    return result;
+}
+function isOptionalType(schema) {
+    if (schema instanceof z.ZodOptional)
+        return true;
+    if (schema instanceof z.ZodDefault)
+        return true;
+    return false;
+}
+//# sourceMappingURL=zod-to-json-schema.js.map

package/dist/tools/zod-to-json-schema.js.map

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

package/dist/trace/canonical.d.ts

@@ -0,0 +1,37 @@
+/**
+ * canonical — RFC 8785 JSON canonicalization with deterministic pre-processing.
+ *
+ * Pre-processing contract (applied depth-first before canonicalize):
+ *   - Buffer / Uint8Array   → base64 string (RFC 4648 §4, no padding stripping)
+ *   - undefined             → key is omitted (JSON.stringify-compatible semantics)
+ *   - Date                  → ISO-8601 string via .toISOString()
+ *   - BigInt                → { __bigint: string } (decimal representation)
+ *   - NaN / Infinity / -0   → throws NonSerializablePayloadError
+ *   - Circular references   → throws NonSerializablePayloadError
+ *   - Everything else       → left unchanged (strings, booleans, null, plain numbers)
+ *
+ * Usage:
+ *   import { canonicalize, NonSerializablePayloadError } from './canonical.js';
+ *   const json = canonicalize({ b: 2, a: 1 }); // '{"a":1,"b":2}'
+ *
+ * @module trace/canonical
+ */
+/**
+ * Thrown when the value graph contains a non-serializable primitive
+ * (NaN, Infinity, -0) or a circular reference.
+ */
+export declare class NonSerializablePayloadError extends Error {
+    readonly path: string[];
+    constructor(reason: string, path: string[]);
+}
+/**
+ * Produce the RFC 8785 canonical JSON string of any value.
+ *
+ * Pre-processes the value graph (Buffer→base64, Date→ISO-8601,
+ * BigInt→{__bigint}, undefined→omit, cycles/NaN/Inf/-0→throw)
+ * then applies `json-canonicalize` for deterministic key ordering.
+ *
+ * @throws {NonSerializablePayloadError} for NaN, Infinity, -0, or cycles.
+ */
+export declare function canonicalize(value: unknown): string;
+//# sourceMappingURL=canonical.d.ts.map

package/dist/trace/canonical.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical.d.ts","sourceRoot":"","sources":["../../src/trace/canonical.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH;;;GAGG;AACH,qBAAa,2BAA4B,SAAQ,KAAK;aACR,IAAI,EAAE,MAAM,EAAE;gBAA9C,MAAM,EAAE,MAAM,EAAkB,IAAI,EAAE,MAAM,EAAE;CAI3D;AAiHD;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAKnD"}