Tools and approval

/** Public schema boundary accepts Zod 3, Zod 4 Classic and Zod 4 Mini. */
export type AgentiumSchema = Zod3Schema | z4.$ZodType;

export interface ApprovalConfig {
    /** Which tools require approval: "none" (default), "all", or an array of tool names. */
    policy: "none" | "all" | string[];
    /** Callback invoked when approval is needed. Return a decision. */
    onApproval?: (request: ApprovalRequest) => Promise<ApprovalDecision>;
    /** Timeout in ms for waiting on human response. Default: 300000 (5 min). */
    timeout?: number;
    /** Default action when approval times out. Default: "deny". */
    timeoutAction?: "approve" | "deny" | "throw";
}

export interface ApprovalDecision {
    approved: boolean;
    reason?: string;
}

/** A host-owned dispatcher that may be shared by concurrent run-local executors. */
export declare class ApprovalManager {
    constructor(config: ApprovalConfig & {
        eventBus?: EventBus;
    });
    /** Unfiltered access is for the trusted owner; hosted callers must supply verified scope. */
    listPending(scope?: {
        runId?: string;
        sessionId?: string;
        userId?: string;
        tenantId?: string;
    }): ApprovalRequest[];
    needsApproval(toolName: string, args: Record<string, unknown>, toolRequiresApproval?: boolean | ((args: Record<string, unknown>) => boolean)): boolean;
    check(toolName: string, args: unknown, ctx: RunContext, agentName: string): Promise<ApprovalDecision>;
    approve(requestId: string, reason?: string): void;
    deny(requestId: string, reason?: string): void;
    cancelRun(runId: string, reason?: string): void;
    close(): void;
}

export interface ApprovalRequest {
    requestId: string;
    toolName: string;
    args: unknown;
    agentName: string;
    runId: string;
    sessionId?: string;
    userId?: string;
    tenantId?: string;
}

export interface Artifact {
    type: string;
    data: unknown;
    mimeType?: string;
}

/** Public dual-version schema conversion boundary.
 * Zod 4 schemas use native conversion; Zod 3 keeps its compatible converter.
 * JSON Schema describes input shape, not arbitrary executable checks. */
export declare function convertJsonSchema(schema: AgentiumSchema): {
    schema: Record<string, unknown>;
    diagnostics: SchemaConversionDiagnostic[];
    dialect: "zod3" | "zod4";
};

/**
 * Returns the `pollResult` companion tool that retrieves results from
 * `defineAsyncTool` handles. Add this once to your agent's tool list.
 */
export declare function createPollResultTool(): ToolDef;

/**
 * Wrap a long-running execute function in the async-handle pattern.
 * The returned tool fires the work in the background and returns
 * `{ handle: "ah:..." }` immediately.
 */
export declare function defineAsyncTool<T extends ToolParameterSchema>(config: DefineAsyncToolConfig<T>): ToolDef;

export interface DefineAsyncToolConfig<T extends ToolParameterSchema> {
    name: string;
    description: string;
    parameters: T;
    /** The long-running implementation. Runs in the background. */
    execute: (args: SchemaOutput<T>, ctx: RunContext) => Promise<string | ToolResult>;
    /** TTL for the cached result in seconds. Default 600 (10 minutes). */
    ttlSeconds?: number;
}

export declare function defineTool<T extends ToolParameterSchema>(config: {
    name: string;
    description: string;
    parameters: T;
    execute: (args: SchemaOutput<T>, ctx: RunContext) => Promise<string | ToolResult>;
    cache?: ToolCacheConfig;
    sandbox?: boolean | SandboxConfig;
    requiresApproval?: boolean | ((args: Record<string, unknown>) => boolean);
    strict?: boolean;
    /** N-shot examples that demonstrate valid tool calls to the LLM. */
    inputExamples?: Array<SchemaOutput<T>>;
    /** Async transformer applied to the tool result before it is appended to the LLM context. */
    toModelOutput?: (result: string | ToolResult, ctx: RunContext) => Promise<string | ToolResult>;
}): ToolDef;

export declare function evaluateExecutionPolicy(policy: ExecutionPolicy | undefined, call: ValidatedToolCall, ctx: RunContext): Promise<ExecutionDecision>;

export interface ExecutionDecision {
    action: "allow" | "ask" | "deny";
    reason?: string;
}

/**
 * Host-supplied mandatory policy. Model arguments and MCP annotations are not
 * effect authority. The validated arguments must support Node's structured
 * serialization (ordinary data, dates, maps and typed arrays; not functions).
 * Mutating reviewed arguments fails closed before execution.
 */
export interface ExecutionPolicy {
    decide: (call: ValidatedToolCall, ctx: RunContext) => ExecutionDecision | Promise<ExecutionDecision>;
    /** Classifies the complete tool execution, including its result transformer. */
    resolveEffect?: (call: ValidatedToolCall, ctx: RunContext) => ToolEffect | Promise<ToolEffect>;
}

export declare function parseSchema<T extends AgentiumSchema>(schema: T, value: unknown): SchemaOutput<T>;

export declare function resolveSandboxConfig(toolLevel?: boolean | SandboxConfig, agentLevel?: boolean | SandboxConfig): SandboxConfig | null;

export type RunMode = "execute" | "plan";

export declare function safeParseSchema<T extends AgentiumSchema>(schema: T, value: unknown): SchemaParseResult<SchemaOutput<T>>;

export declare class Sandbox {
    constructor(config: SandboxConfig);
    execute(toolExecuteFn: (args: Record<string, unknown>, ctx: RunContext) => Promise<string | ToolResult>, args: Record<string, unknown>, _ctx: RunContext): Promise<string | ToolResult>;
}

export interface SandboxConfig {
    /** Explicit on/off toggle. Defaults to true when config object is provided. */
    enabled?: boolean;
    /** Execution timeout in milliseconds. Default: 30000 (30s). */
    timeout?: number;
    /** Maximum heap memory in MB. Default: 256. */
    maxMemoryMB?: number;
    /** Allow outbound network from the sandbox. Default: false. */
    allowNetwork?: boolean;
    /** Allow filesystem access. Default: false. */
    allowFS?: boolean | {
        readOnly?: string[];
        readWrite?: string[];
    };
    /** Whitelisted environment variables forwarded to the sandbox. */
    env?: Record<string, string>;
}

export interface SchemaConversionDiagnostic {
    path: string;
    kind: "transform" | "refinement";
    message: string;
}

export type SchemaOutput<T extends AgentiumSchema> = T extends z4.$ZodType ? z4.output<T> : T extends Zod3Schema ? T["_output"] : never;

export declare function schemaShape(schema: ToolParameterSchema): Record<string, AgentiumSchema>;

export interface ToolCacheConfig {
    /** Time-to-live in milliseconds. Cached results expire after this duration. */
    ttl: number;
}

export interface ToolCallResult {
    toolCallId: string;
    toolName: string;
    result: string | ToolResult;
    error?: string;
    /** Structured fail-closed execution outcome. */
    denial?: "policy" | "approval_required" | "approval_denied" | "cancelled";
}

export interface ToolDef {
    name: string;
    description: string;
    parameters: ToolParameterSchema;
    execute: (args: Record<string, unknown>, ctx: RunContext) => Promise<string | ToolResult>;
    /** Raw JSON Schema to send to the LLM, bypassing Zod-to-JSON conversion (used by MCP tools). */
    rawJsonSchema?: Record<string, unknown>;
    /** Enable result caching for this tool. */
    cache?: ToolCacheConfig;
    /** Run this tool in a sandboxed subprocess. Off by default. */
    sandbox?: boolean | SandboxConfig;
    /**
     * Require approval before execution; no configured approval service denies the
     * call. False overrides legacy approval defaults, never mandatory host policy.
     */
    requiresApproval?: boolean | ((args: Record<string, unknown>) => boolean);
    /** Enable strict mode for OpenAI Structured Outputs on tool calls. Guarantees valid JSON matching the schema. */
    strict?: boolean;
    /**
     * Optional N-shot examples that demonstrate valid tool calls to the LLM.
     * Each example is rendered into the tool's JSON Schema description.
     */
    inputExamples?: Array<Record<string, unknown>>;
    /**
     * Optional async transformer applied to the tool result *after* execution but
     * *before* the result is appended to the LLM context. Use to compress, summarize,
     * redact, or otherwise reshape large outputs.
     */
    toModelOutput?: (result: string | ToolResult, ctx: RunContext) => Promise<string | ToolResult>;
}

export type ToolEffect = "read" | "write" | "execute" | "external" | "unknown";

export declare class ToolExecutor {
    constructor(tools: ToolDef[], configOrConcurrency?: number | ToolExecutorConfig);
    getApprovalManager(): ApprovalManager | undefined;
    clearCache(): void;
    executeAll(toolCalls: ToolCall[], ctx: RunContext): Promise<ToolCallResult[]>;
    getToolDefinitions(): Array<{
        name: string;
        description: string;
        parameters: Record<string, unknown>;
        strict?: boolean;
    }>;
}

export interface ToolExecutorConfig {
    concurrency?: number;
    sandbox?: boolean | SandboxConfig;
    approval?: ApprovalConfig & {
        eventBus?: EventBus;
    };
    /** Share a host-owned dispatcher across run-local executors. */
    approvalManager?: ApprovalManager;
    /** Additional borrowed dispatchers whose approval requirements must also pass. */
    additionalApprovalManagers?: readonly ApprovalManager[];
    executionPolicy?: ExecutionPolicy;
    agentName?: string;
    /** Observe authorized calls. Mutating arguments of a protected call denies execution. */
    onToolCall?: (ctx: RunContext, toolName: string, args: unknown) => Promise<void>;
    /**
     * Memory Pointer Pattern: tool outputs over `maxToolOutputBytes` are auto-stored
     * as artifacts and replaced with a `{ pointer, preview }` JSON string before being
     * appended to the LLM context.
     */
    artifacts?: {
        maxToolOutputBytes: number;
        previewChars: number;
    };
    /**
     * Tool-loop detection: when the same `(toolName, arguments)` pair is invoked
     * more than `maxRepeats` times within a single run, take the configured action.
     *   - `"abort"`: raise `ToolLoopError` and stop the run
     *   - `"hint"`: return a synthetic result reminding the model to change strategy
     */
    loopDetection?: {
        maxRepeats: number;
        action: "abort" | "hint";
    };
}

export declare class ToolLoopError extends Error {
    readonly toolName: string;
    readonly repeats: number;
    constructor(toolName: string, repeats: number);
}

export type ToolParameterSchema = (Zod3Schema & {
    readonly _def: {
        readonly typeName: "ZodObject";
    };
    readonly _output: Record<string, unknown>;
    readonly shape: Record<string, Zod3Schema>;
}) | z4.$ZodObject;

export interface ToolResult {
    content: string;
    artifacts?: Artifact[];
}

/**
 * Pre-selects a subset of relevant tools for a given user query using a
 * cheap model. This dramatically reduces prompt tokens when agents have
 * many tools (e.g. 50+ MCP tools) by only sending relevant tool schemas.
 *
 * If the selection fails for any reason, all tools are returned as a fallback.
 */
export declare class ToolRouter {
    constructor(config: ToolRouterConfig);
    select(query: string, tools: ToolDef[]): Promise<ToolDef[]>;
}

export interface ToolRouterConfig {
    /** Cheap/fast model used to select relevant tools. */
    model: ModelProvider;
    /** Maximum tools to select per query. Default: 8 */
    maxTools?: number;
    /** Minimum tools to always return (in case selection fails). Default: 0 (fallback sends all) */
    minTools?: number;
    /** Temperature for the selection model. Default: 0 */
    temperature?: number;
    /** Optional logger for diagnostic output. When omitted, the router is silent. */
    logger?: Logger;
}

export interface ValidatedToolCall {
    readonly toolCallId: string;
    readonly toolName: string;
    readonly args: Readonly<Record<string, unknown>>;
}

/** Structural v3 contract avoids nominal private-field differences between
 * the standalone v3 package and the v3 compatibility copy shipped with v4. */
export interface Zod3Schema {
    readonly _def: {
        readonly typeName?: string;
    };
    readonly _output: unknown;
    parse(value: unknown): unknown;
    safeParse(value: unknown): SchemaParseResult<unknown>;
}

export type SchemaParseResult<T> = {
    success: true;
    data: T;
} | {
    success: false;
    error: {
        message: string;
        issues: readonly {
            path: readonly PropertyKey[];
            message: string;
        }[];
    };
};