adonis-ai-kit 0.0.0-stage → 1.2.0

package/dist/src/guard/guard.d.ts

@@ -0,0 +1,47 @@
+import type { ActionGuard, ExecutionReconciliation } from './types.js';
+export interface ParameterRule<T = unknown> {
+    field: string;
+    validate: (value: T, allArgs: Record<string, unknown>) => string | null;
+}
+export interface PolicyGuardOptions {
+    maxCalls?: number;
+    allowedTools?: string[];
+    rules?: Record<string, ParameterRule[]>;
+}
+/**
+ * Flexible policy guard for constraining tool arguments and invocation counts.
+ *
+ * `check()` reserves a call slot when it allows a call, so parallel tool calls cannot all pass
+ * the `maxCalls` check before any of them is recorded. The slot is turned into a counted call by
+ * `record()`, or given back by `release()`.
+ */
+export declare class PolicyGuard implements ActionGuard {
+    private callCount;
+    private successfulCalls;
+    private inFlight;
+    private maxCalls;
+    private allowedTools?;
+    private rules;
+    constructor(opts?: PolicyGuardOptions);
+    addRule(toolName: string, rule: ParameterRule): this;
+    check(toolName: string, args: unknown): string | null;
+    record(_toolName: string, result: unknown): void;
+    release(_toolName: string): void;
+    get totalCalls(): number;
+    get acceptedCalls(): number;
+    summary(): Record<string, unknown>;
+}
+/**
+ * Reconciles the number of claims made by an LLM with the verified executions in the guard.
+ */
+export declare function reconcileExecutionClaims(claimedCount: unknown, guard?: ActionGuard): ExecutionReconciliation;
+/**
+ * Creates a numeric range validation rule.
+ * Only real numbers (or numeric strings) pass: `''`, `null`, booleans and arrays are rejected.
+ */
+export declare function rangeRule(field: string, min: number, max: number, label?: string): ParameterRule<unknown>;
+/**
+ * Creates an allowed values enum validation rule.
+ */
+export declare function enumRule<T extends string>(field: string, allowed: readonly T[], label?: string): ParameterRule<unknown>;
+//# sourceMappingURL=guard.d.ts.map

package/dist/src/guard/guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guard.d.ts","sourceRoot":"","sources":["../../../src/guard/guard.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAA;AAEtE,MAAM,WAAW,aAAa,CAAC,CAAC,GAAG,OAAO;IACxC,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,GAAG,IAAI,CAAA;CACxE;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAA;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,EAAE,CAAC,CAAA;CACxC;AAED;;;;;;GAMG;AACH,qBAAa,WAAY,YAAW,WAAW;IAC7C,OAAO,CAAC,SAAS,CAAI;IACrB,OAAO,CAAC,eAAe,CAAI;IAC3B,OAAO,CAAC,QAAQ,CAAI;IACpB,OAAO,CAAC,QAAQ,CAAQ;IACxB,OAAO,CAAC,YAAY,CAAC,CAAa;IAClC,OAAO,CAAC,KAAK,CAA0C;gBAE3C,IAAI,GAAE,kBAAuB;IAYzC,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,GAAG,IAAI;IAOpD,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI;IA4BrD,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,IAAI;IAehD,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAIhC,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED,IAAI,aAAa,IAAI,MAAM,CAE1B;IAED,OAAO,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAOnC;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CACtC,YAAY,EAAE,OAAO,EACrB,KAAK,CAAC,EAAE,WAAW,GAClB,uBAAuB,CAWzB;AAED;;;GAGG;AACH,wBAAgB,SAAS,CACvB,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,EACX,KAAK,GAAE,MAAc,GACpB,aAAa,CAAC,OAAO,CAAC,CAgBxB;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,MAAM,EACvC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,SAAS,CAAC,EAAE,EACrB,KAAK,GAAE,MAAc,GACpB,aAAa,CAAC,OAAO,CAAC,CAUxB"}

package/dist/src/guard/guard.js

@@ -0,0 +1,133 @@
+/**
+ * Flexible policy guard for constraining tool arguments and invocation counts.
+ *
+ * `check()` reserves a call slot when it allows a call, so parallel tool calls cannot all pass
+ * the `maxCalls` check before any of them is recorded. The slot is turned into a counted call by
+ * `record()`, or given back by `release()`.
+ */
+export class PolicyGuard {
+    callCount = 0;
+    successfulCalls = 0;
+    inFlight = 0;
+    maxCalls;
+    allowedTools;
+    rules = new Map();
+    constructor(opts = {}) {
+        this.maxCalls = opts.maxCalls ?? Infinity;
+        if (opts.allowedTools) {
+            this.allowedTools = new Set(opts.allowedTools);
+        }
+        if (opts.rules) {
+            for (const [tool, rules] of Object.entries(opts.rules)) {
+                this.rules.set(tool, [...rules]);
+            }
+        }
+    }
+    addRule(toolName, rule) {
+        const existing = this.rules.get(toolName) ?? [];
+        existing.push(rule);
+        this.rules.set(toolName, existing);
+        return this;
+    }
+    check(toolName, args) {
+        if (this.allowedTools && !this.allowedTools.has(toolName)) {
+            return `Tool "${toolName}" is not permitted by policy`;
+        }
+        if (this.callCount + this.inFlight >= this.maxCalls) {
+            return `Maximum allowed calls (${this.maxCalls}) exceeded for policy`;
+        }
+        const toolRules = this.rules.get(toolName);
+        if (toolRules && toolRules.length > 0) {
+            // Fail-closed: rules cannot be evaluated against non-object arguments.
+            if (typeof args !== 'object' || args === null || Array.isArray(args)) {
+                return `Arguments for "${toolName}" must be an object to be validated by policy`;
+            }
+            const record = args;
+            for (const rule of toolRules) {
+                const violation = rule.validate(record[rule.field], record);
+                if (violation) {
+                    return violation;
+                }
+            }
+        }
+        this.inFlight += 1;
+        return null;
+    }
+    record(_toolName, result) {
+        this.inFlight = Math.max(0, this.inFlight - 1);
+        this.callCount += 1;
+        if (result &&
+            typeof result === 'object' &&
+            'error' in result &&
+            result.error) {
+            // Failed call
+            return;
+        }
+        this.successfulCalls += 1;
+    }
+    release(_toolName) {
+        this.inFlight = Math.max(0, this.inFlight - 1);
+    }
+    get totalCalls() {
+        return this.callCount;
+    }
+    get acceptedCalls() {
+        return this.successfulCalls;
+    }
+    summary() {
+        return {
+            totalCalls: this.callCount,
+            acceptedCalls: this.successfulCalls,
+            maxCalls: this.maxCalls,
+        };
+    }
+}
+/**
+ * Reconciles the number of claims made by an LLM with the verified executions in the guard.
+ */
+export function reconcileExecutionClaims(claimedCount, guard) {
+    const parsed = Number(claimedCount ?? 0);
+    const claimed = Number.isFinite(parsed) ? parsed : 0;
+    const summary = guard?.summary?.();
+    const verified = typeof summary?.acceptedCalls === 'number' ? summary.acceptedCalls : 0;
+    return {
+        claimed,
+        verified,
+        mismatch: claimed !== verified,
+    };
+}
+/**
+ * Creates a numeric range validation rule.
+ * Only real numbers (or numeric strings) pass: `''`, `null`, booleans and arrays are rejected.
+ */
+export function rangeRule(field, min, max, label = field) {
+    return {
+        field,
+        validate: (val) => {
+            const isNumeric = typeof val === 'number' || (typeof val === 'string' && val.trim() !== '');
+            const num = isNumeric ? Number(val) : Number.NaN;
+            if (!Number.isFinite(num)) {
+                return `${label} must be a valid number`;
+            }
+            if (num < min || num > max) {
+                return `${label} ${num} is out of permitted range [${min}, ${max}]`;
+            }
+            return null;
+        },
+    };
+}
+/**
+ * Creates an allowed values enum validation rule.
+ */
+export function enumRule(field, allowed, label = field) {
+    return {
+        field,
+        validate: (val) => {
+            if (typeof val !== 'string' || !allowed.includes(val)) {
+                return `${label} "${String(val)}" is not allowed. Permitted: ${allowed.join(', ')}`;
+            }
+            return null;
+        },
+    };
+}
+//# sourceMappingURL=guard.js.map

package/dist/src/guard/guard.js.map

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

package/dist/src/guard/index.d.ts

@@ -0,0 +1,7 @@
+export * from './types.js';
+export * from './errors.js';
+export * from './confirmation.js';
+export * from './guard.js';
+export * from './registry.js';
+export * from './schema_registry.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/guard/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/guard/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAA;AAC1B,cAAc,aAAa,CAAA;AAC3B,cAAc,mBAAmB,CAAA;AACjC,cAAc,YAAY,CAAA;AAC1B,cAAc,eAAe,CAAA;AAC7B,cAAc,sBAAsB,CAAA"}

package/dist/src/guard/index.js

@@ -0,0 +1,7 @@
+export * from './types.js';
+export * from './errors.js';
+export * from './confirmation.js';
+export * from './guard.js';
+export * from './registry.js';
+export * from './schema_registry.js';
+//# sourceMappingURL=index.js.map

package/dist/src/guard/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/guard/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAA;AAC1B,cAAc,aAAa,CAAA;AAC3B,cAAc,mBAAmB,CAAA;AACjC,cAAc,YAAY,CAAA;AAC1B,cAAc,eAAe,CAAA;AAC7B,cAAc,sBAAsB,CAAA"}

package/dist/src/guard/registry.d.ts

@@ -0,0 +1,72 @@
+import type { ActionGuard, Logger, ToolDefinition, ToolPermission } from './types.js';
+import type { ConfirmationService } from './confirmation.js';
+export interface ToolAccessOptions {
+    guard?: ActionGuard;
+    confirmation?: ConfirmationService;
+    sessionId?: string;
+    timeoutMs?: number;
+    /** Agent whose permission matrix applies in `getToolsByList()`. */
+    agentName?: string;
+    /**
+     * Per-call permission map. When given, it is the only source of permissions for this call:
+     * tools missing from it get the registry's `defaultPermission`. The agent matrix is neither
+     * read nor modified, so nothing leaks into later calls.
+     */
+    permissions?: Record<string, ToolPermission>;
+}
+export interface WrapToolOptions extends ToolAccessOptions {
+    /**
+     * Effective permission of the tool. `ask` requires a `confirmation` service (otherwise every
+     * call is refused with `PolicyViolationError`); `deny` refuses every call.
+     * Defaults to `allow` because `wrapTool()` is a low-level primitive; the registry's
+     * `getToolsForAgent()` / `getToolsByList()` always pass the resolved permission.
+     */
+    permission?: ToolPermission;
+}
+export interface ToolRegistryOptions {
+    logger?: Logger;
+    askByDefault?: string[];
+    /**
+     * Permission of tools that have neither an agent-specific nor a tool-level permission.
+     * Default: `deny` (fail-closed).
+     */
+    defaultPermission?: ToolPermission;
+}
+/**
+ * Registry for managing AI agent tools, access permissions, policy guards,
+ * and Human-in-the-loop confirmation hooks.
+ *
+ * Fail-closed: unknown permissions resolve to `deny`, `ask` without a confirmation service
+ * never executes, and every tool that is handed out goes through the policy guard.
+ */
+export declare class ToolRegistry {
+    private tools;
+    private agentPermissions;
+    private defaultPermissions;
+    private askByDefault;
+    private defaultPermission;
+    private logger?;
+    constructor(opts?: ToolRegistryOptions);
+    setLogger(logger: Logger): void;
+    registerTool(name: string, tool: ToolDefinition, defaultPermission?: ToolPermission): this;
+    registerTools(tools: Record<string, ToolDefinition>, defaultPermission?: ToolPermission): this;
+    setAgentPermissions(agentName: string, permissions: Record<string, ToolPermission>): this;
+    getAgentPermission(agentName: string, toolName: string): ToolPermission;
+    /**
+     * Wraps a tool with policy guard validation and, for `ask`, Human-in-the-loop confirmation.
+     * Tools without an `execute` function (provider-executed / client-side tools) are returned as is.
+     */
+    wrapTool(name: string, tool: ToolDefinition, options?: WrapToolOptions): ToolDefinition;
+    /**
+     * Returns the tools an agent may use. `deny` tools are omitted, `ask` tools require
+     * confirmation, and every returned tool is checked by `options.guard` when one is provided.
+     */
+    getToolsForAgent(agentName: string, options?: ToolAccessOptions): Record<string, ToolDefinition>;
+    /**
+     * Returns the requested tools, subject to the permission matrix of `options.agentName`
+     * (or the tool-level / registry defaults when no agent is given).
+     */
+    getToolsByList(toolNames: string[], options?: ToolAccessOptions): Record<string, ToolDefinition>;
+    private resolveTool;
+}
+//# sourceMappingURL=registry.d.ts.map

package/dist/src/guard/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/guard/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EACX,MAAM,EACN,cAAc,EACd,cAAc,EACf,MAAM,YAAY,CAAA;AACnB,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAA;AAG5D,MAAM,WAAW,iBAAiB;IAChC,KAAK,CAAC,EAAE,WAAW,CAAA;IACnB,YAAY,CAAC,EAAE,mBAAmB,CAAA;IAClC,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,mEAAmE;IACnE,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAA;CAC7C;AAED,MAAM,WAAW,eAAgB,SAAQ,iBAAiB;IACxD;;;;;OAKG;IACH,UAAU,CAAC,EAAE,cAAc,CAAA;CAC5B;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,YAAY,CAAC,EAAE,MAAM,EAAE,CAAA;IACvB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,cAAc,CAAA;CACnC;AASD;;;;;;GAMG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,KAAK,CAAyC;IACtD,OAAO,CAAC,gBAAgB,CAAsD;IAC9E,OAAO,CAAC,kBAAkB,CAAyC;IACnE,OAAO,CAAC,YAAY,CAAa;IACjC,OAAO,CAAC,iBAAiB,CAAgB;IACzC,OAAO,CAAC,MAAM,CAAC,CAAQ;gBAEX,IAAI,GAAE,mBAAwB;IAM1C,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAI/B,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,EAAE,iBAAiB,CAAC,EAAE,cAAc,GAAG,IAAI;IAQ1F,aAAa,CACX,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,EACrC,iBAAiB,CAAC,EAAE,cAAc,GACjC,IAAI;IAOP,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,GAAG,IAAI;IASzF,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,cAAc;IAcvE;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,EAAE,OAAO,GAAE,eAAoB,GAAG,cAAc;IA8F3F;;;OAGG;IACH,gBAAgB,CACd,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,iBAAsB,GAC9B,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC;IAWjC;;;OAGG;IACH,cAAc,CACZ,SAAS,EAAE,MAAM,EAAE,EACnB,OAAO,GAAE,iBAAsB,GAC9B,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC;IAiBjC,OAAO,CAAC,WAAW;CA2BpB"}

package/dist/src/guard/registry.js

@@ -0,0 +1,192 @@
+import { PolicyViolationError } from './errors.js';
+/** A tool description may be a function (AI SDK v7); fall back to the tool name then. */
+function describeTool(tool, fallback) {
+    return typeof tool.description === 'string' && tool.description.length > 0
+        ? tool.description
+        : fallback;
+}
+/**
+ * Registry for managing AI agent tools, access permissions, policy guards,
+ * and Human-in-the-loop confirmation hooks.
+ *
+ * Fail-closed: unknown permissions resolve to `deny`, `ask` without a confirmation service
+ * never executes, and every tool that is handed out goes through the policy guard.
+ */
+export class ToolRegistry {
+    tools = new Map();
+    agentPermissions = new Map();
+    defaultPermissions = new Map();
+    askByDefault;
+    defaultPermission;
+    logger;
+    constructor(opts = {}) {
+        this.logger = opts.logger;
+        this.askByDefault = new Set(opts.askByDefault ?? []);
+        this.defaultPermission = opts.defaultPermission ?? 'deny';
+    }
+    setLogger(logger) {
+        this.logger = logger;
+    }
+    registerTool(name, tool, defaultPermission) {
+        this.tools.set(name, tool);
+        if (defaultPermission) {
+            this.defaultPermissions.set(name, defaultPermission);
+        }
+        return this;
+    }
+    registerTools(tools, defaultPermission) {
+        for (const [name, tool] of Object.entries(tools)) {
+            this.registerTool(name, tool, defaultPermission);
+        }
+        return this;
+    }
+    setAgentPermissions(agentName, permissions) {
+        const map = this.agentPermissions.get(agentName) ?? new Map();
+        for (const [tool, perm] of Object.entries(permissions)) {
+            map.set(tool, perm);
+        }
+        this.agentPermissions.set(agentName, map);
+        return this;
+    }
+    getAgentPermission(agentName, toolName) {
+        const agentMap = this.agentPermissions.get(agentName);
+        if (agentMap?.has(toolName)) {
+            return agentMap.get(toolName);
+        }
+        if (this.defaultPermissions.has(toolName)) {
+            return this.defaultPermissions.get(toolName);
+        }
+        if (this.askByDefault.has(toolName)) {
+            return 'ask';
+        }
+        return this.defaultPermission;
+    }
+    /**
+     * Wraps a tool with policy guard validation and, for `ask`, Human-in-the-loop confirmation.
+     * Tools without an `execute` function (provider-executed / client-side tools) are returned as is.
+     */
+    wrapTool(name, tool, options = {}) {
+        const originalExecute = tool.execute?.bind(tool);
+        if (!originalExecute) {
+            return tool;
+        }
+        const permission = options.permission ?? 'allow';
+        return {
+            ...tool,
+            execute: async (args, execOptions) => {
+                // 0. Defense in depth: a denied tool never runs, even if it slipped past filtering.
+                if (permission === 'deny') {
+                    throw new PolicyViolationError(name, 'permission is "deny"');
+                }
+                // 1. Guard check (also reserves a call slot in guards that support it)
+                if (options.guard) {
+                    const violation = options.guard.check(name, args);
+                    if (violation) {
+                        this.logger?.warn?.(`[ToolRegistry] Tool "${name}" call rejected by guard: ${violation}`, args);
+                        return {
+                            error: `Rejected by policy guard: ${violation}. Adjust parameters to match approved bounds.`,
+                        };
+                    }
+                }
+                // From here on a call slot may be held in the guard: it must end in exactly one
+                // record() (tool ran) or release() (tool did not run).
+                let executed = false;
+                let slotSettled = false;
+                const settleSlot = (result) => {
+                    if (slotSettled)
+                        return;
+                    slotSettled = true;
+                    options.guard?.record?.(name, result);
+                };
+                try {
+                    // 2. Human-in-the-loop confirmation. Fail-closed: `ask` without a service never runs.
+                    if (permission === 'ask') {
+                        if (!options.confirmation) {
+                            throw new PolicyViolationError(name, 'permission is "ask" but no ConfirmationService was provided');
+                        }
+                        this.logger?.info?.(`[ToolRegistry] Requesting confirmation for "${name}"`);
+                        const confirmation = await options.confirmation.waitForResponse({
+                            sessionId: options.sessionId,
+                            toolName: name,
+                            action: describeTool(tool, name),
+                            params: args ?? {},
+                        }, options.timeoutMs, execOptions?.abortSignal);
+                        if (confirmation.status !== 'approved') {
+                            this.logger?.warn?.(`[ToolRegistry] Tool "${name}" execution not approved: ${confirmation.status} (${confirmation.reason ?? 'no reason'})`);
+                            return {
+                                error: `Tool "${name}" was not executed: ${confirmation.status}. ${confirmation.reason ?? ''}`.trim(),
+                            };
+                        }
+                    }
+                    // 3. Execute underlying tool
+                    executed = true;
+                    const result = await originalExecute(args, execOptions);
+                    // 4. Record execution stats in guard
+                    settleSlot(result);
+                    return result;
+                }
+                catch (err) {
+                    if (executed) {
+                        settleSlot({ error: err instanceof Error ? err.message : String(err) });
+                    }
+                    throw err;
+                }
+                finally {
+                    if (!slotSettled && options.guard) {
+                        slotSettled = true;
+                        options.guard.release?.(name);
+                    }
+                }
+            },
+        };
+    }
+    /**
+     * Returns the tools an agent may use. `deny` tools are omitted, `ask` tools require
+     * confirmation, and every returned tool is checked by `options.guard` when one is provided.
+     */
+    getToolsForAgent(agentName, options = {}) {
+        const result = {};
+        for (const [name, tool] of this.tools.entries()) {
+            const wrapped = this.resolveTool(agentName, name, tool, options);
+            if (wrapped)
+                result[name] = wrapped;
+        }
+        return result;
+    }
+    /**
+     * Returns the requested tools, subject to the permission matrix of `options.agentName`
+     * (or the tool-level / registry defaults when no agent is given).
+     */
+    getToolsByList(toolNames, options = {}) {
+        const result = {};
+        for (const name of toolNames) {
+            const tool = this.tools.get(name);
+            if (!tool) {
+                this.logger?.warn?.(`[ToolRegistry] Unknown tool requested: "${name}"`);
+                continue;
+            }
+            const wrapped = this.resolveTool(options.agentName ?? '', name, tool, options);
+            if (wrapped)
+                result[name] = wrapped;
+        }
+        return result;
+    }
+    resolveTool(agentName, name, tool, options) {
+        const permission = options.permissions
+            ? Object.hasOwn(options.permissions, name)
+                ? options.permissions[name]
+                : this.defaultPermission
+            : this.getAgentPermission(agentName, name);
+        if (permission === 'deny') {
+            return null;
+        }
+        if (permission === 'ask' && !options.confirmation) {
+            this.logger?.warn?.(`[ToolRegistry] Tool "${name}" requires confirmation but no ConfirmationService was provided; calls will be refused.`);
+        }
+        if (permission === 'allow' && !options.guard) {
+            return tool;
+        }
+        return this.wrapTool(name, tool, { ...options, permission });
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/src/guard/registry.js.map

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

package/dist/src/guard/schema_registry.d.ts

@@ -0,0 +1,37 @@
+import type { z } from 'zod';
+/**
+ * Minimal structural view of a Zod issue.
+ * Declared locally so the package works unchanged with Zod 3.24+ (`ZodIssue`) and Zod 4
+ * (`$ZodIssue`, where `ZodIssue` is deprecated).
+ */
+export interface SchemaIssue {
+    code?: string;
+    message: string;
+    path: ReadonlyArray<PropertyKey>;
+}
+export interface ValidationSuccess<T> {
+    success: true;
+    data: T;
+}
+export interface ValidationFailure {
+    success: false;
+    error: string;
+    issues: SchemaIssue[];
+}
+export type ValidationResult<T> = ValidationSuccess<T> | ValidationFailure;
+/**
+ * Registry for structured agent outputs and input schemas using Zod.
+ */
+export declare class SchemaRegistry {
+    private schemas;
+    register(name: string, schema: z.ZodTypeAny): this;
+    registerMany(schemas: Record<string, z.ZodTypeAny>): this;
+    get(name: string): z.ZodTypeAny | undefined;
+    validate<T = unknown>(schemaName: string, data: unknown): ValidationResult<T>;
+    /**
+     * Formats Zod validation issues into actionable prompt text for LLM self-correction.
+     */
+    formatZodIssues(issues: ReadonlyArray<SchemaIssue>): string;
+    getAllNames(): string[];
+}
+//# sourceMappingURL=schema_registry.d.ts.map

package/dist/src/guard/schema_registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema_registry.d.ts","sourceRoot":"","sources":["../../../src/guard/schema_registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAE5B;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,aAAa,CAAC,WAAW,CAAC,CAAA;CACjC;AAED,MAAM,WAAW,iBAAiB,CAAC,CAAC;IAClC,OAAO,EAAE,IAAI,CAAA;IACb,IAAI,EAAE,CAAC,CAAA;CACR;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,KAAK,CAAA;IACd,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,WAAW,EAAE,CAAA;CACtB;AAED,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAAI,iBAAiB,CAAC,CAAC,CAAC,GAAG,iBAAiB,CAAA;AAE1E;;GAEG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,OAAO,CAAkC;IAEjD,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,UAAU,GAAG,IAAI;IAKlD,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,CAAC,GAAG,IAAI;IAOzD,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,CAAC,CAAC,UAAU,GAAG,SAAS;IAI3C,QAAQ,CAAC,CAAC,GAAG,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,gBAAgB,CAAC,CAAC,CAAC;IA0B7E;;OAEG;IACH,eAAe,CAAC,MAAM,EAAE,aAAa,CAAC,WAAW,CAAC,GAAG,MAAM;IAS3D,WAAW,IAAI,MAAM,EAAE;CAGxB"}

package/dist/src/guard/schema_registry.js

@@ -0,0 +1,57 @@
+/**
+ * Registry for structured agent outputs and input schemas using Zod.
+ */
+export class SchemaRegistry {
+    schemas = new Map();
+    register(name, schema) {
+        this.schemas.set(name, schema);
+        return this;
+    }
+    registerMany(schemas) {
+        for (const [name, schema] of Object.entries(schemas)) {
+            this.schemas.set(name, schema);
+        }
+        return this;
+    }
+    get(name) {
+        return this.schemas.get(name);
+    }
+    validate(schemaName, data) {
+        const schema = this.get(schemaName);
+        if (!schema) {
+            return {
+                success: false,
+                error: `Schema "${schemaName}" is not registered in SchemaRegistry`,
+                issues: [],
+            };
+        }
+        const parsed = schema.safeParse(data);
+        if (parsed.success) {
+            return {
+                success: true,
+                data: parsed.data,
+            };
+        }
+        const issues = parsed.error.issues;
+        return {
+            success: false,
+            error: this.formatZodIssues(issues),
+            issues,
+        };
+    }
+    /**
+     * Formats Zod validation issues into actionable prompt text for LLM self-correction.
+     */
+    formatZodIssues(issues) {
+        return issues
+            .map((issue) => {
+            const path = issue.path.length > 0 ? issue.path.map(String).join('.') : 'root';
+            return `- Field "${path}": ${issue.message}`;
+        })
+            .join('\n');
+    }
+    getAllNames() {
+        return Array.from(this.schemas.keys());
+    }
+}
+//# sourceMappingURL=schema_registry.js.map

package/dist/src/guard/schema_registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema_registry.js","sourceRoot":"","sources":["../../../src/guard/schema_registry.ts"],"names":[],"mappings":"AA0BA;;GAEG;AACH,MAAM,OAAO,cAAc;IACjB,OAAO,GAAG,IAAI,GAAG,EAAwB,CAAA;IAEjD,QAAQ,CAAC,IAAY,EAAE,MAAoB;QACzC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,CAAA;QAC9B,OAAO,IAAI,CAAA;IACb,CAAC;IAED,YAAY,CAAC,OAAqC;QAChD,KAAK,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;YACrD,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,CAAA;QAChC,CAAC;QACD,OAAO,IAAI,CAAA;IACb,CAAC;IAED,GAAG,CAAC,IAAY;QACd,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;IAC/B,CAAC;IAED,QAAQ,CAAc,UAAkB,EAAE,IAAa;QACrD,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,CAAA;QACnC,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,OAAO;gBACL,OAAO,EAAE,KAAK;gBACd,KAAK,EAAE,WAAW,UAAU,uCAAuC;gBACnE,MAAM,EAAE,EAAE;aACX,CAAA;QACH,CAAC;QAED,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,CAAA;QACrC,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACnB,OAAO;gBACL,OAAO,EAAE,IAAI;gBACb,IAAI,EAAE,MAAM,CAAC,IAAS;aACvB,CAAA;QACH,CAAC;QAED,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,MAAuB,CAAA;QACnD,OAAO;YACL,OAAO,EAAE,KAAK;YACd,KAAK,EAAE,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC;YACnC,MAAM;SACP,CAAA;IACH,CAAC;IAED;;OAEG;IACH,eAAe,CAAC,MAAkC;QAChD,OAAO,MAAM;aACV,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE;YACb,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAA;YAC9E,OAAO,YAAY,IAAI,MAAM,KAAK,CAAC,OAAO,EAAE,CAAA;QAC9C,CAAC,CAAC;aACD,IAAI,CAAC,IAAI,CAAC,CAAA;IACf,CAAC;IAED,WAAW;QACT,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAA;IACxC,CAAC;CACF"}