aec-agent 1.0.0

package/dist/components/tool-hub/built-in-tools/workspace/workspace-helpers.js.map

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

package/dist/components/tool-hub/built-in-tools/workspace/write-file-tool.d.ts

@@ -0,0 +1,17 @@
+import type { SandboxView, WriteResult } from "../../../sandbox-hub/types/sandbox.js";
+import type { ToolContext, ToolDefinition, ToolHandler, ToolOutput } from "../../types.js";
+import type { WorkspaceToolOptions } from "./types.js";
+/**
+ * write_file — creates or replaces a whole file, then verifies it by reading it back
+ * (sha256 + size must match what was written).
+ */
+export declare class WriteFileTool implements ToolHandler {
+    readonly name = "tool:write-file";
+    readonly version = "1.0.0";
+    readonly definition: ToolDefinition;
+    constructor(_options?: WorkspaceToolOptions);
+    execute(args: Record<string, unknown>, context: ToolContext): Promise<ToolOutput>;
+}
+/** Read-after-write: the file on disk must hash to what was written. Returns an error result on mismatch. */
+export declare function verifyWrite(env: SandboxView, written: WriteResult): Promise<ToolOutput | null>;
+//# sourceMappingURL=write-file-tool.d.ts.map

package/dist/components/tool-hub/built-in-tools/workspace/write-file-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-file-tool.d.ts","sourceRoot":"","sources":["../../../../../src/components/tool-hub/built-in-tools/workspace/write-file-tool.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,uCAAuC,CAAC;AACtF,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAC3F,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAGvD;;;GAGG;AACH,qBAAa,aAAc,YAAW,WAAW;IAC/C,QAAQ,CAAC,IAAI,qBAAqB;IAClC,QAAQ,CAAC,OAAO,WAAW;IAC3B,QAAQ,CAAC,UAAU,EAAE,cAAc,CAAC;IAEpC,YAAY,QAAQ,GAAE,oBAAyB,EAiB9C;IAEK,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAkBtF;CACF;AAED,6GAA6G;AAC7G,wBAAsB,WAAW,CAAC,GAAG,EAAE,WAAW,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAWpG"}

package/dist/components/tool-hub/built-in-tools/workspace/write-file-tool.js

@@ -0,0 +1,61 @@
+import { argError, formatBytes, stringArg, withSandbox } from "./workspace-helpers.js";
+/**
+ * write_file — creates or replaces a whole file, then verifies it by reading it back
+ * (sha256 + size must match what was written).
+ */
+export class WriteFileTool {
+    name = "tool:write-file";
+    version = "1.0.0";
+    definition;
+    constructor(_options = {}) {
+        this.definition = {
+            name: "write_file",
+            description: "Create a file, or replace a file's entire content, in your workspace. Parent folders are created. " +
+                "To change part of an existing file use edit_file instead. The write is verified by reading the file back.",
+            parameters: {
+                type: "object",
+                properties: {
+                    path: { type: "string", description: 'File path, relative to your working directory (e.g. "reports/summary.md") or under /workspace/shared' },
+                    content: { type: "string", description: "The complete new content of the file" },
+                },
+                required: ["path", "content"],
+            },
+            risk: "draft",
+            sandboxOperation: "fs.write",
+        };
+    }
+    async execute(args, context) {
+        const path = stringArg(args, "path")?.trim();
+        const content = stringArg(args, "content");
+        if (!path)
+            return argError("write_file", '"path" must be a non-empty string');
+        if (content === undefined)
+            return argError("write_file", '"content" must be a string');
+        return withSandbox("write_file", context, async (env) => {
+            const written = await env.writeFile(path, content);
+            const failure = await verifyWrite(env, written);
+            if (failure)
+                return failure;
+            const lines = content === "" ? 0 : content.split("\n").length - (content.endsWith("\n") ? 1 : 0);
+            return {
+                content: `${written.created ? "Created" : "Overwrote"} ${written.path} (${formatBytes(written.bytes)}, ${lines} lines) — ` +
+                    `verified by read-back (sha256 ${written.sha256.slice(0, 12)})`,
+                metadata: { path: written.path, bytes: written.bytes, sha256: written.sha256, created: written.created, verified: true },
+            };
+        });
+    }
+}
+/** Read-after-write: the file on disk must hash to what was written. Returns an error result on mismatch. */
+export async function verifyWrite(env, written) {
+    const check = await env.readFile(written.path, { maxBytes: 1 });
+    if (check.sha256 === written.sha256 && check.size === written.bytes)
+        return null;
+    return {
+        content: `The write to ${written.path} could not be verified: the file now has ${formatBytes(check.size)} ` +
+            `(sha256 ${check.sha256.slice(0, 12)}) instead of what was written. Something else may be changing it — read it and try again.`,
+        isError: true,
+        retryable: false,
+        metadata: { path: written.path, expectedSha256: written.sha256, actualSha256: check.sha256, verified: false },
+    };
+}
+//# sourceMappingURL=write-file-tool.js.map

package/dist/components/tool-hub/built-in-tools/workspace/write-file-tool.js.map

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

package/dist/components/tool-hub/policies/default-tool-policy.d.ts

@@ -0,0 +1,17 @@
+import type { AuthorizationHook, ToolContext, ToolDefinition, ToolPolicy, ToolPolicyDecision } from "../types.js";
+export interface DefaultToolPolicyOptions {
+    authorizationHook?: AuthorizationHook;
+}
+export declare class DefaultToolPolicy implements ToolPolicy {
+    readonly name = "policy:default";
+    readonly version = "1.0.0";
+    private authorizationHook?;
+    constructor(options?: DefaultToolPolicyOptions);
+    initialize(): Promise<void>;
+    dispose(): Promise<void>;
+    check(toolName: string, args: Record<string, unknown>, context: ToolContext, definition: ToolDefinition, allowedTools: string[]): Promise<ToolPolicyDecision>;
+    private checkAllowlist;
+    private validateSchema;
+    private checkType;
+}
+//# sourceMappingURL=default-tool-policy.d.ts.map

package/dist/components/tool-hub/policies/default-tool-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"default-tool-policy.d.ts","sourceRoot":"","sources":["../../../../src/components/tool-hub/policies/default-tool-policy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,iBAAiB,EAEjB,WAAW,EACX,cAAc,EACd,UAAU,EACV,kBAAkB,EACnB,MAAM,aAAa,CAAC;AAErB,MAAM,WAAW,wBAAwB;IACvC,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;CACvC;AAED,qBAAa,iBAAkB,YAAW,UAAU;IAClD,QAAQ,CAAC,IAAI,oBAAoB;IACjC,QAAQ,CAAC,OAAO,WAAW;IAE3B,OAAO,CAAC,iBAAiB,CAAC,CAAoB;IAE9C,YAAY,OAAO,CAAC,EAAE,wBAAwB,EAE7C;IAEK,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAG;IAC9B,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAG;IAE3B,KAAK,CACT,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,EAAE,WAAW,EACpB,UAAU,EAAE,cAAc,EAC1B,YAAY,EAAE,MAAM,EAAE,GACrB,OAAO,CAAC,kBAAkB,CAAC,CAgB7B;IAED,OAAO,CAAC,cAAc;IAkBtB,OAAO,CAAC,cAAc;IA6BtB,OAAO,CAAC,SAAS;CA0ClB"}

package/dist/components/tool-hub/policies/default-tool-policy.js

@@ -0,0 +1,99 @@
+export class DefaultToolPolicy {
+    name = "policy:default";
+    version = "1.0.0";
+    authorizationHook;
+    constructor(options) {
+        this.authorizationHook = options?.authorizationHook;
+    }
+    async initialize() { }
+    async dispose() { }
+    async check(toolName, args, context, definition, allowedTools) {
+        // 1. Allowlist — tool must be in the agent's allowed set
+        const allowlistResult = this.checkAllowlist(toolName, allowedTools);
+        if (!allowlistResult.allowed)
+            return allowlistResult;
+        // 2. Schema validation — args must match the tool's parameter schema
+        const schemaResult = this.validateSchema(args, definition.parameters);
+        if (!schemaResult.allowed)
+            return schemaResult;
+        // 3. Authorization hook — consumer-provided business rules
+        if (this.authorizationHook) {
+            const hookResult = await this.authorizationHook(toolName, args, context);
+            if (!hookResult.allowed)
+                return hookResult;
+        }
+        return { allowed: true };
+    }
+    checkAllowlist(toolName, allowedTools) {
+        if (allowedTools.length === 0) {
+            return { allowed: true };
+        }
+        if (!allowedTools.includes(toolName)) {
+            return {
+                allowed: false,
+                reason: `Tool "${toolName}" is not in the allowed list`,
+            };
+        }
+        return { allowed: true };
+    }
+    validateSchema(args, schema) {
+        // Check required fields
+        if (schema.required) {
+            for (const field of schema.required) {
+                if (!(field in args) || args[field] === undefined) {
+                    return {
+                        allowed: false,
+                        reason: `Missing required argument: "${field}"`,
+                    };
+                }
+            }
+        }
+        // Check property types and constraints
+        if (schema.properties) {
+            for (const [key, propSchema] of Object.entries(schema.properties)) {
+                if (!(key in args) || args[key] === undefined)
+                    continue;
+                const typeResult = this.checkType(key, args[key], propSchema);
+                if (!typeResult.allowed)
+                    return typeResult;
+            }
+        }
+        return { allowed: true };
+    }
+    checkType(key, value, schema) {
+        const typeMap = {
+            string: "string",
+            number: "number",
+            boolean: "boolean",
+            array: "object",
+            object: "object",
+        };
+        const expectedJsType = typeMap[schema.type];
+        const actualType = typeof value;
+        if (schema.type === "array") {
+            if (!Array.isArray(value)) {
+                return {
+                    allowed: false,
+                    reason: `Argument "${key}" must be an array, got ${actualType}`,
+                };
+            }
+        }
+        else if (actualType !== expectedJsType) {
+            return {
+                allowed: false,
+                reason: `Argument "${key}" must be ${schema.type}, got ${actualType}`,
+            };
+        }
+        // Enum constraint
+        if (schema.enum && typeof value === "string") {
+            if (!schema.enum.includes(value)) {
+                return {
+                    allowed: false,
+                    reason: `Argument "${key}" must be one of [${schema.enum.join(", ")}], got "${value}"`,
+                };
+            }
+        }
+        return { allowed: true };
+    }
+}
+//# sourceMappingURL=default-tool-policy.js.map

package/dist/components/tool-hub/policies/default-tool-policy.js.map

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

package/dist/components/tool-hub/tool-hub.d.ts

@@ -0,0 +1,28 @@
+import type { InteractionHandler, ToolHandler, ToolPolicy } from "./types.js";
+/**
+ * Global hub for tools, for example this hub has 50 tools but user want Devops Agent so user only enable 10 devop tools from 50 tools.
+ */
+export declare class ToolHub {
+    private tools;
+    /**
+     * Host channel to the human user — clarify questions and approvals for consequential tools.
+     * Unset = no interactive user (clarify errors, consequential tools are denied).
+     */
+    private interactionHandler?;
+    /**
+     * Checked before every tool dispatch of every agent: allowlist, argument schema and the
+     * host's authorization hook. Replace it (e.g. a DefaultToolPolicy with an authorizationHook)
+     * with setPolicy(); it applies to running agents on their next dispatch.
+     */
+    private policy;
+    register(tool: ToolHandler): void;
+    get(name: string): ToolHandler | undefined;
+    getByNames(names: string[]): ToolHandler[];
+    list(): ToolHandler[];
+    /** Set (or clear with undefined) the host's interaction channel. Applies to running agents on their next tool dispatch. */
+    setInteractionHandler(handler: InteractionHandler | undefined): void;
+    getInteractionHandler(): InteractionHandler | undefined;
+    setPolicy(policy: ToolPolicy): void;
+    getPolicy(): ToolPolicy;
+}
+//# sourceMappingURL=tool-hub.d.ts.map

package/dist/components/tool-hub/tool-hub.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-hub.d.ts","sourceRoot":"","sources":["../../../src/components/tool-hub/tool-hub.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC9E;;GAEG;AACH,qBAAa,OAAO;IAClB,OAAO,CAAC,KAAK,CAAkC;IAC/C;;;OAGG;IACH,OAAO,CAAC,kBAAkB,CAAC,CAAqB;IAChD;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAuC;IAErD,QAAQ,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,CAKhC;IAED,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAEzC;IAED,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,WAAW,EAAE,CAIzC;IAED,IAAI,IAAI,WAAW,EAAE,CAEpB;IAED,2HAA2H;IAC3H,qBAAqB,CAAC,OAAO,EAAE,kBAAkB,GAAG,SAAS,GAAG,IAAI,CAEnE;IAED,qBAAqB,IAAI,kBAAkB,GAAG,SAAS,CAEtD;IAED,SAAS,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,CAElC;IAED,SAAS,IAAI,UAAU,CAEtB;CACF"}

package/dist/components/tool-hub/tool-hub.js

@@ -0,0 +1,49 @@
+import { DefaultToolPolicy } from "./policies/default-tool-policy.js";
+/**
+ * Global hub for tools, for example this hub has 50 tools but user want Devops Agent so user only enable 10 devop tools from 50 tools.
+ */
+export class ToolHub {
+    tools = new Map();
+    /**
+     * Host channel to the human user — clarify questions and approvals for consequential tools.
+     * Unset = no interactive user (clarify errors, consequential tools are denied).
+     */
+    interactionHandler;
+    /**
+     * Checked before every tool dispatch of every agent: allowlist, argument schema and the
+     * host's authorization hook. Replace it (e.g. a DefaultToolPolicy with an authorizationHook)
+     * with setPolicy(); it applies to running agents on their next dispatch.
+     */
+    policy = new DefaultToolPolicy();
+    register(tool) {
+        if (this.tools.has(tool.definition.name)) {
+            throw new Error(`Tool "${tool.definition.name}" already registered`);
+        }
+        this.tools.set(tool.definition.name, tool);
+    }
+    get(name) {
+        return this.tools.get(name);
+    }
+    getByNames(names) {
+        return names
+            .map((n) => this.tools.get(n))
+            .filter((t) => t !== undefined);
+    }
+    list() {
+        return [...this.tools.values()];
+    }
+    /** Set (or clear with undefined) the host's interaction channel. Applies to running agents on their next tool dispatch. */
+    setInteractionHandler(handler) {
+        this.interactionHandler = handler;
+    }
+    getInteractionHandler() {
+        return this.interactionHandler;
+    }
+    setPolicy(policy) {
+        this.policy = policy;
+    }
+    getPolicy() {
+        return this.policy;
+    }
+}
+//# sourceMappingURL=tool-hub.js.map

package/dist/components/tool-hub/tool-hub.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-hub.js","sourceRoot":"","sources":["../../../src/components/tool-hub/tool-hub.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AAEtE;;GAEG;AACH,MAAM,OAAO,OAAO;IACV,KAAK,GAAG,IAAI,GAAG,EAAuB,CAAC;IAC/C;;;OAGG;IACK,kBAAkB,CAAsB;IAChD;;;;OAIG;IACK,MAAM,GAAe,IAAI,iBAAiB,EAAE,CAAC;IAErD,QAAQ,CAAC,IAAiB;QACxB,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;YACzC,MAAM,IAAI,KAAK,CAAC,SAAS,IAAI,CAAC,UAAU,CAAC,IAAI,sBAAsB,CAAC,CAAC;QACvE,CAAC;QACD,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAC7C,CAAC;IAED,GAAG,CAAC,IAAY;QACd,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC9B,CAAC;IAED,UAAU,CAAC,KAAe;QACxB,OAAO,KAAK;aACT,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;aAC7B,MAAM,CAAC,CAAC,CAAC,EAAoB,EAAE,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC;IACtD,CAAC;IAED,IAAI;QACF,OAAO,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;IAClC,CAAC;IAED,2HAA2H;IAC3H,qBAAqB,CAAC,OAAuC;QAC3D,IAAI,CAAC,kBAAkB,GAAG,OAAO,CAAC;IACpC,CAAC;IAED,qBAAqB;QACnB,OAAO,IAAI,CAAC,kBAAkB,CAAC;IACjC,CAAC;IAED,SAAS,CAAC,MAAkB;QAC1B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IAED,SAAS;QACP,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;CACF"}

package/dist/components/tool-hub/types.d.ts

@@ -0,0 +1,138 @@
+import type { Event } from "../../kernel/types.js";
+import type { Plugin } from "../../kernel/interfaces/plugin.js";
+import type { SandboxKind, SandboxView } from "../sandbox-hub/types/sandbox.js";
+import type { SandboxOperation } from "../sandbox-hub/types/policy.js";
+import type { ArtifactView } from "../artifact-hub/types/artifact.js";
+import type { AgentSkills } from "../skill-hub/types/agent-skills.js";
+export interface JsonSchema {
+    type: "object" | "string" | "number" | "boolean" | "array";
+    properties?: Record<string, JsonSchema>;
+    required?: string[];
+    description?: string;
+    items?: JsonSchema;
+    enum?: string[];
+}
+/**
+ * Side-effect class of a tool — decides whether a call needs human approval.
+ *  - "read-only":     retrieves data, changes nothing. Runs after policy checks.
+ *  - "draft":         creates something reversible (a draft, a proposal). Runs after policy checks.
+ *  - "consequential": external or irreversible effect (send, delete, spend). The harness pauses
+ *                     for explicit user approval immediately before execution and fails closed
+ *                     when no InteractionHandler is configured.
+ * Tools that omit `risk` are treated as not requiring approval (backward compatible).
+ */
+export type ToolRisk = "read-only" | "draft" | "consequential";
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    parameters: JsonSchema;
+    allowedModes?: string[];
+    risk?: ToolRisk;
+    /**
+     * Set by tools that work in the agent's sandbox (file / terminal tools).
+     * Before dispatch the harness resolves the sandbox and asks the SandboxHub approval
+     * policy whether this operation needs user approval THERE — e.g. auto in an isolated
+     * Docker sandbox, approval for writes/commands on a host folder.
+     */
+    sandboxOperation?: SandboxOperation;
+}
+export interface ToolHandler extends Plugin {
+    readonly definition: ToolDefinition;
+    execute(args: Record<string, unknown>, context: ToolContext): Promise<ToolOutput>;
+}
+export interface ToolContext {
+    sessionId: string;
+    /**
+     * The agent's sandbox, resolved lazily — the container starts on the first call.
+     * Rejects with SandboxError when the agent has none (fail closed).
+     * File/terminal tools must use this instead of node:fs / child_process.
+     */
+    getSandbox?: () => Promise<SandboxView>;
+    /**
+     * The agent's artifacts (A-62), scoped to this agent and session. Absent when the
+     * host wired no artifact store. Artifacts track files in the agent's sandbox — the
+     * artifact tools hand the context's sandbox (from getSandbox) to every view call.
+     */
+    getArtifacts?: () => ArtifactView;
+    /** ID of the agent running the tool (if known) */
+    agentId?: string;
+    /** Host-provided channel to the human user (clarify / approval). Absent = no interactive user. */
+    interaction?: InteractionHandler;
+    /** The agent's skills — read by skill_view, written by skill_manage. Absent outside an agent. */
+    skills?: AgentSkills;
+    emit: (event: Omit<Event, "id" | "timestamp">) => void;
+    /**
+     * Aborted when the user stops the run (A-65). Long-running tools should
+     * pass it to sandbox operations / fetch calls they make. The harness stops
+     * waiting on the call either way, once it has started — a tool that
+     * ignores the signal keeps running in the background, but its result is
+     * discarded.
+     */
+    signal?: AbortSignal;
+}
+export interface ToolOutput {
+    content: string;
+    isError?: boolean;
+    /**
+     * Set to false on an error result that must not be retried by the harness
+     * (e.g. a blocked URL, a user who already answered, a missing interaction channel).
+     * Defaults to retryable.
+     */
+    retryable?: boolean;
+    metadata?: Record<string, unknown>;
+}
+/** A question the agent asks the user when a request is genuinely ambiguous. */
+export interface ClarifyRequest {
+    sessionId: string;
+    agentId?: string;
+    question: string;
+    /** Optional multiple-choice answers; the user may still answer free-form. */
+    choices?: string[];
+}
+export interface ClarifyResponse {
+    answer: string;
+}
+/**
+ * Shown to the user before a "consequential" tool runs. Carries everything needed
+ * to approve safely: what will run, with which arguments, and why it is gated.
+ */
+export interface ApprovalRequest {
+    sessionId: string;
+    agentId?: string;
+    toolCallId: string;
+    toolName: string;
+    toolDescription: string;
+    risk: ToolRisk;
+    arguments: Record<string, unknown>;
+    /** Why approval is needed, when it is not simply `risk: "consequential"` (e.g. a write on a host folder). */
+    reason?: string;
+    /** Where a sandbox tool would act (sandbox-aware approval). */
+    sandbox?: {
+        id: string;
+        kind: SandboxKind;
+        isolated: boolean;
+    };
+}
+export interface ApprovalDecision {
+    approved: boolean;
+    /** Optional note from the user, returned to the model on denial. */
+    reason?: string;
+}
+/**
+ * Implemented by the host app (server, CLI) to reach the human user. Both calls block the
+ * agent loop until the user responds — the host owns timeouts/cancellation (resolve with
+ * `approved: false`, or reject, when the user does not answer in time).
+ */
+export interface InteractionHandler {
+    askUser(request: ClarifyRequest): Promise<ClarifyResponse>;
+    requestApproval(request: ApprovalRequest): Promise<ApprovalDecision>;
+}
+export interface ToolPolicyDecision {
+    allowed: boolean;
+    reason?: string;
+}
+export type AuthorizationHook = (toolName: string, args: Record<string, unknown>, context: ToolContext) => ToolPolicyDecision | Promise<ToolPolicyDecision>;
+export interface ToolPolicy extends Plugin {
+    check(toolName: string, args: Record<string, unknown>, context: ToolContext, definition: ToolDefinition, allowedTools: string[]): Promise<ToolPolicyDecision>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/components/tool-hub/types.d.ts.map

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

package/dist/components/tool-hub/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/components/tool-hub/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/components/tool-hub/types.ts"],"names":[],"mappings":""}

package/dist/components/trace-service/console-trace-sink.d.ts

@@ -0,0 +1,9 @@
+import type { TraceSink } from "./types/sink.js";
+import type { TraceSpan } from "./types/span.js";
+export declare class ConsoleTraceSink implements TraceSink {
+    onSpanStart(span: TraceSpan): void;
+    onSpanEnd(span: TraceSpan): void;
+    flush(): void;
+    private formatAttributes;
+}
+//# sourceMappingURL=console-trace-sink.d.ts.map

package/dist/components/trace-service/console-trace-sink.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"console-trace-sink.d.ts","sourceRoot":"","sources":["../../../src/components/trace-service/console-trace-sink.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAejD,qBAAa,gBAAiB,YAAW,SAAS;IAChD,WAAW,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI,CAOjC;IAED,SAAS,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI,CAQ/B;IAED,KAAK,IAAI,IAAI,CAAG;IAEhB,OAAO,CAAC,gBAAgB;CAMzB"}

package/dist/components/trace-service/console-trace-sink.js

@@ -0,0 +1,35 @@
+// ---------------------------------------------------------------------------
+// ConsoleTraceSink — human-readable trace output for development
+// ---------------------------------------------------------------------------
+const KindLabel = {
+    "run": "RUN",
+    "iteration": "ITER",
+    "context-assembly": "CTX",
+    "model-call": "MODEL",
+    "tool-dispatch": "TOOL",
+    "skill-dispatch": "SKILL",
+};
+export class ConsoleTraceSink {
+    onSpanStart(span) {
+        const label = KindLabel[span.kind] ?? span.kind;
+        const parent = span.parentSpanId ? ` parent=${span.parentSpanId.slice(0, 8)}` : "";
+        const attrs = this.formatAttributes(span.attributes);
+        console.log(`[trace] ▶ ${label} ${span.name} span=${span.spanId.slice(0, 8)}${parent}${attrs}`);
+    }
+    onSpanEnd(span) {
+        const label = KindLabel[span.kind] ?? span.kind;
+        const duration = span.durationMs !== undefined ? ` ${span.durationMs}ms` : "";
+        const status = span.status === "error" ? " ERROR" : "";
+        const attrs = this.formatAttributes(span.attributes);
+        console.log(`[trace] ◀ ${label} ${span.name}${duration}${status}${attrs}`);
+    }
+    flush() { }
+    formatAttributes(attrs) {
+        const keys = Object.keys(attrs);
+        if (keys.length === 0)
+            return "";
+        const parts = keys.map((k) => `${k}=${JSON.stringify(attrs[k])}`);
+        return ` {${parts.join(", ")}}`;
+    }
+}
+//# sourceMappingURL=console-trace-sink.js.map

package/dist/components/trace-service/console-trace-sink.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"console-trace-sink.js","sourceRoot":"","sources":["../../../src/components/trace-service/console-trace-sink.ts"],"names":[],"mappings":"AAGA,8EAA8E;AAC9E,iEAAiE;AACjE,8EAA8E;AAE9E,MAAM,SAAS,GAA2B;IACxC,KAAK,EAAe,KAAK;IACzB,WAAW,EAAS,MAAM;IAC1B,kBAAkB,EAAE,KAAK;IACzB,YAAY,EAAQ,OAAO;IAC3B,eAAe,EAAK,MAAM;IAC1B,gBAAgB,EAAI,OAAO;CAC5B,CAAC;AAEF,MAAM,OAAO,gBAAgB;IAC3B,WAAW,CAAC,IAAe;QACzB,MAAM,KAAK,GAAG,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC;QAChD,MAAM,MAAM,GAAG,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC,WAAW,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACnF,MAAM,KAAK,GAAG,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QACrD,OAAO,CAAC,GAAG,CACT,aAAa,KAAK,IAAI,IAAI,CAAC,IAAI,SAAS,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,MAAM,GAAG,KAAK,EAAE,CACnF,CAAC;IACJ,CAAC;IAED,SAAS,CAAC,IAAe;QACvB,MAAM,KAAK,GAAG,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC;QAChD,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,UAAU,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;QAC9E,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;QACvD,MAAM,KAAK,GAAG,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QACrD,OAAO,CAAC,GAAG,CACT,aAAa,KAAK,IAAI,IAAI,CAAC,IAAI,GAAG,QAAQ,GAAG,MAAM,GAAG,KAAK,EAAE,CAC9D,CAAC;IACJ,CAAC;IAED,KAAK,KAAU,CAAC;IAER,gBAAgB,CAAC,KAA8B;QACrD,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAChC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,EAAE,CAAC;QACjC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAClE,OAAO,KAAK,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;IAClC,CAAC;CACF"}

package/dist/components/trace-service/trace-service.d.ts

@@ -0,0 +1,25 @@
+import type { TraceSink } from "./types/sink.js";
+import type { SpanKind, SpanHandle, TraceContext, TraceSpan } from "./types/span.js";
+export declare class TraceService {
+    private sinks;
+    private activeContexts;
+    addSink(sink: TraceSink): void;
+    removeSink(sink: TraceSink): void;
+    getSinks(): readonly TraceSink[];
+    createContext(traceId?: string): MutableTraceContext;
+    getContext(traceId: string): MutableTraceContext | undefined;
+    removeContext(traceId: string): void;
+    startSpan(ctx: TraceContext, name: string, kind: SpanKind, attributes?: Record<string, unknown>): SpanHandle;
+    notifyStart(span: TraceSpan): void;
+    notifyEnd(span: TraceSpan): void;
+    flush(): Promise<void>;
+}
+export declare class MutableTraceContext implements TraceContext {
+    readonly traceId: string;
+    private spanStack;
+    constructor(traceId: string);
+    get currentSpanId(): string | undefined;
+    pushSpan(spanId: string): void;
+    popSpan(): void;
+}
+//# sourceMappingURL=trace-service.d.ts.map

package/dist/components/trace-service/trace-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-service.d.ts","sourceRoot":"","sources":["../../../src/components/trace-service/trace-service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,EACV,QAAQ,EACR,UAAU,EACV,YAAY,EACZ,SAAS,EACV,MAAM,iBAAiB,CAAC;AAwBzB,qBAAa,YAAY;IAKvB,OAAO,CAAC,KAAK,CAAmB;IAMhC,OAAO,CAAC,cAAc,CAA0C;IAMhE,OAAO,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI,CAE7B;IAID,UAAU,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI,CAGhC;IAGD,QAAQ,IAAI,SAAS,SAAS,EAAE,CAE/B;IAWD,aAAa,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,mBAAmB,CAKnD;IAGD,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,mBAAmB,GAAG,SAAS,CAE3D;IAID,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAEnC;IAoBD,SAAS,CACP,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,QAAQ,EACd,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACnC,UAAU,CAiCZ;IAOD,WAAW,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI,CAIjC;IAGD,SAAS,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI,CAI/B;IAIK,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAI3B;CACF;AAaD,qBAAa,mBAAoB,YAAW,YAAY;IAGtD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAKzB,OAAO,CAAC,SAAS,CAAgB;IAEjC,YAAY,OAAO,EAAE,MAAM,EAE1B;IAKD,IAAI,aAAa,IAAI,MAAM,GAAG,SAAS,CAItC;IAID,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAE7B;IAID,OAAO,IAAI,IAAI,CAEd;CACF"}