qlogicagent 2.13.3 → 2.13.5

package/dist/agent/tool-loop.policy-architecture.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/agent/tool-loop.policy-architecture.test.js

@@ -0,0 +1,21 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+describe("tool-loop policy architecture", () => {
+    const sourcePath = fileURLToPath(new URL("./tool-loop.ts", import.meta.url));
+    function source() {
+        return readFileSync(sourcePath, "utf8");
+    }
+    it("does not build skill-learning instructions inline", () => {
+        expect(source()).not.toMatch(/buildSkillInstruction/);
+        expect(source()).not.toMatch(/SkillTurnResult/);
+    });
+    it("does not define token budget continuation thresholds inline", () => {
+        expect(source()).not.toMatch(/MAX_BUDGET_CONTINUATIONS/);
+        expect(source()).not.toMatch(/DIMINISHING_RETURNS_THRESHOLD/);
+    });
+    it("does not carry AP4 variant failure policy inline", () => {
+        expect(source()).not.toMatch(/MAX_TOOL_VARIANT_FAILURES/);
+        expect(source()).not.toMatch(/AP4-variant/);
+    });
+});

package/dist/agent/tool-loop.states.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/agent/tool-loop.states.test.js

@@ -0,0 +1,211 @@
+/**
+ * tool-loop 状态机矩阵 — 钉死高危恢复分支的安全网。
+ *
+ * 配套文档：docs/tool-loop-state-machine.md。每个用例对应文档矩阵的一行，
+ * 断言基于 tool-loop.ts 的真实触发条件与产出事件（非猜测）。
+ *
+ * 这里覆盖 contract.test.ts 未覆盖的 6 个高危态（413 / max-output / abort /
+ * model-fallback / budget-continuation / parallel）+ 正常完成与工具软失败两条基线。
+ */
+import { describe, expect, it, vi } from "vitest";
+import { executeToolLoop } from "./tool-loop.js";
+import { StreamingToolExecutor } from "../runtime/execution/streaming-tool-executor.js";
+import { FallbackTriggeredError } from "../orchestration/index.js";
+class ScriptedTransport {
+    rounds;
+    requests = [];
+    constructor(rounds) {
+        this.rounds = rounds;
+    }
+    async *stream(request) {
+        this.requests.push(request);
+        const round = this.rounds.shift();
+        if (!round)
+            throw new Error("unexpected LLM round");
+        if (!Array.isArray(round))
+            throw round.throw;
+        for (const chunk of round)
+            yield chunk;
+    }
+}
+const log = { info: vi.fn(), warn: vi.fn(), error: vi.fn(), debug: vi.fn() };
+function tool(name = "read") {
+    return {
+        type: "function",
+        function: {
+            name,
+            description: `${name} tool`,
+            parameters: { type: "object", properties: { path: { type: "string" } } },
+        },
+    };
+}
+function runtimePorts(overrides = {}) {
+    return {
+        createContentReplacementState: () => ({}),
+        enforceToolResultBudget: async (messages) => ({ messages, newlyReplacedCount: 0 }),
+        getActiveContextCompressionEngine: () => null,
+        compressMessages: (messages) => ({ messages, droppedCount: 0, strategy: "none" }),
+        getBudgetContinuationMessage: (usagePct) => `Continue; ${Math.round(usagePct)}% budget used.`,
+        createStreamingToolExecutor: (config) => new StreamingToolExecutor(config),
+        resolveToolEligibility: (tools) => ({ eligibleTools: tools, blockedTools: [] }),
+        ...overrides,
+    };
+}
+async function collect(events) {
+    const out = [];
+    for await (const event of events)
+        out.push(event);
+    return out;
+}
+const recoveryActions = (events) => events.filter((e) => e.type === "recovery").map((e) => e.action);
+const types = (events) => events.map((e) => e.type);
+function baseParams(overrides) {
+    return {
+        turnId: "t",
+        sessionId: "s",
+        messages: [{ role: "user", content: "Say hi" }],
+        tools: [tool("read")],
+        model: "model-a",
+        apiKey: "key",
+        maxRounds: 5,
+        ...overrides,
+    };
+}
+function err413() {
+    return Object.assign(new Error("prompt too long: maximum context length exceeded"), { status: 413 });
+}
+describe("executeToolLoop state matrix", () => {
+    // #1 — 正常完成：finishReason=stop，无工具调用 → end
+    it("[normal] completes with end on a plain stop round", async () => {
+        const transport = new ScriptedTransport([
+            [{ type: "delta", text: "Done." }, { type: "usage", promptTokens: 5, completionTokens: 2 }, { type: "done", finishReason: "stop" }],
+        ]);
+        const events = await collect(executeToolLoop(baseParams({ runtimePorts: runtimePorts() }), transport, { invoke: vi.fn() }, log));
+        expect(types(events)).toEqual(["delta", "end"]);
+        expect(events.find((e) => e.type === "end")).toMatchObject({ content: "Done." });
+    });
+    // #2 — 工具硬失败：invoker 返回 {error} → executor 置 ok=false → tool_result{ok:false}，循环继续后完成
+    it("[tool-failure] surfaces ok:false when the invoker returns an error, then completes", async () => {
+        const transport = new ScriptedTransport([
+            [{ type: "tool_call_delta", index: 0, id: "c1", name: "read", arguments: "{\"path\":\"/etc/shadow\"}" }, { type: "done", finishReason: "tool_calls" }],
+            [{ type: "delta", text: "could not read it" }, { type: "done", finishReason: "stop" }],
+        ]);
+        const invoker = { invoke: vi.fn(async () => ({ result: "", error: "permission denied" })) };
+        const events = await collect(executeToolLoop(baseParams({ runtimePorts: runtimePorts() }), transport, invoker, log));
+        expect(events).toContainEqual(expect.objectContaining({ type: "tool_result", callId: "c1", ok: false }));
+        expect(events.find((e) => e.type === "end")).toMatchObject({ content: "could not read it" });
+    });
+    // #8 — 并行工具：单轮两个 tool_call → 两个 tool_result
+    it("[parallel] runs multiple tool calls from one round and emits a result per call", async () => {
+        const transport = new ScriptedTransport([
+            [
+                { type: "tool_call_delta", index: 0, id: "p1", name: "read", arguments: "{\"path\":\"a.txt\"}" },
+                { type: "tool_call_delta", index: 1, id: "p2", name: "read", arguments: "{\"path\":\"b.txt\"}" },
+                { type: "done", finishReason: "tool_calls" },
+            ],
+            [{ type: "delta", text: "both read" }, { type: "done", finishReason: "stop" }],
+        ]);
+        const invoker = { invoke: vi.fn(async (_t, name, args) => ({ result: `${name}(${JSON.parse(args).path}) ok` })) };
+        const events = await collect(executeToolLoop(baseParams({ runtimePorts: runtimePorts() }), transport, invoker, log));
+        expect(events.filter((e) => e.type === "tool_call")).toHaveLength(2);
+        expect(events.filter((e) => e.type === "tool_result")).toHaveLength(2);
+        expect(invoker.invoke).toHaveBeenCalledTimes(2);
+        expect(events.find((e) => e.type === "end")).toBeDefined();
+    });
+    // #5 — 413/prompt_too_long：扣留 → reactive_compact → 耗尽 → error{PROMPT_TOO_LONG}
+    it("[413] withholds prompt_too_long, attempts reactive compact, then surfaces PROMPT_TOO_LONG", async () => {
+        const transport = new ScriptedTransport([{ throw: err413() }, { throw: err413() }]);
+        const events = await collect(executeToolLoop(baseParams({ runtimePorts: runtimePorts() }), transport, { invoke: vi.fn() }, log));
+        expect(recoveryActions(events)).toContain("reactive_compact");
+        expect(events.at(-1)).toMatchObject({ type: "error", code: "PROMPT_TOO_LONG" });
+    });
+    // #6 — max output 截断：finishReason=length → 升档/续写恢复 → 完成
+    it("[max-output] recovers from a length-truncated round and completes", async () => {
+        const transport = new ScriptedTransport([
+            [{ type: "delta", text: "partial" }, { type: "done", finishReason: "length" }],
+            [{ type: "delta", text: " and the rest" }, { type: "done", finishReason: "stop" }],
+        ]);
+        const events = await collect(executeToolLoop(baseParams({ runtimePorts: runtimePorts() }), transport, { invoke: vi.fn() }, log));
+        expect(recoveryActions(events).some((a) => a === "output_escalation" || a === "max_output_tokens_recovery")).toBe(true);
+        expect(events.find((e) => e.type === "end")).toBeDefined();
+        expect(transport.requests).toHaveLength(2);
+    });
+    // #7 — abort：预先 abort 的 signal → 守卫拦截 → error{ABORTED}，不触达 LLM
+    it("[abort] aborts via the guard before any LLM call", async () => {
+        const ac = new AbortController();
+        ac.abort();
+        const transport = new ScriptedTransport([[{ type: "delta", text: "should not run" }, { type: "done", finishReason: "stop" }]]);
+        const events = await collect(executeToolLoop(baseParams({ signal: ac.signal, runtimePorts: runtimePorts() }), transport, { invoke: vi.fn() }, log));
+        expect(events.at(-1)).toMatchObject({ type: "error", code: "ABORTED" });
+        expect(transport.requests).toHaveLength(0); // guard short-circuits before stream
+    });
+    // #9 — model fallback：流抛 FallbackTriggeredError + 设了 fallbackModel → 切模型 → 第二轮完成
+    it("[fallback] switches to fallbackModel on FallbackTriggeredError and finishes there", async () => {
+        const transport = new ScriptedTransport([
+            { throw: new FallbackTriggeredError("model-a", "model-b") },
+            [{ type: "delta", text: "answer on fallback" }, { type: "done", finishReason: "stop" }],
+        ]);
+        const events = await collect(executeToolLoop(baseParams({ fallbackModel: "model-b", runtimePorts: runtimePorts() }), transport, { invoke: vi.fn() }, log));
+        expect(recoveryActions(events)).toContain("model_fallback");
+        expect(transport.requests[0]?.model).toBe("model-a");
+        expect(transport.requests[1]?.model).toBe("model-b");
+        expect(events.find((e) => e.type === "end")).toMatchObject({ content: "answer on fallback" });
+    });
+    // #4 — budget continuation：tokenBudget 未用满 → 注入续写 → 用满后停
+    it("[budget-continuation] injects exactly one continuation while under budget, then completes", async () => {
+        const transport = new ScriptedTransport([
+            [{ type: "delta", text: "part 1" }, { type: "usage", promptTokens: 100, completionTokens: 100 }, { type: "done", finishReason: "stop" }],
+            [{ type: "delta", text: "part 2 done" }, { type: "usage", promptTokens: 5000, completionTokens: 100 }, { type: "done", finishReason: "stop" }],
+        ]);
+        const events = await collect(executeToolLoop(baseParams({ tokenBudget: 5000, runtimePorts: runtimePorts() }), transport, { invoke: vi.fn() }, log));
+        expect(recoveryActions(events).filter((a) => a === "budget_continuation")).toHaveLength(1);
+        expect(transport.requests).toHaveLength(2);
+        // Recovery trace surfaced on the terminal end event (observability).
+        expect(events.find((e) => e.type === "end")).toMatchObject({ recoveryTrace: { budget_continuation: 1 } });
+    });
+    // recovery 轨迹：无恢复发生的正常 turn 不应附带 recoveryTrace
+    it("[recovery-trace] a clean turn carries no recoveryTrace on end", async () => {
+        const transport = new ScriptedTransport([
+            [{ type: "delta", text: "ok" }, { type: "done", finishReason: "stop" }],
+        ]);
+        const events = await collect(executeToolLoop(baseParams({ runtimePorts: runtimePorts() }), transport, { invoke: vi.fn() }, log));
+        const end = events.find((e) => e.type === "end");
+        expect(end).toBeDefined();
+        expect(end.recoveryTrace).toBeUndefined();
+    });
+    // #11 — stale connection：ECONNRESET（无 status）→ 立即重试 → 完成
+    it("[stale-connection] retries on ECONNRESET then completes", async () => {
+        const transport = new ScriptedTransport([
+            { throw: new Error("read ECONNRESET") }, // plain Error → no status
+            [{ type: "delta", text: "recovered" }, { type: "done", finishReason: "stop" }],
+        ]);
+        const events = await collect(executeToolLoop(baseParams({ runtimePorts: runtimePorts() }), transport, { invoke: vi.fn() }, log));
+        expect(recoveryActions(events)).toContain("stale_connection_retry");
+        expect(events.find((e) => e.type === "end")).toMatchObject({ content: "recovered" });
+        expect(transport.requests).toHaveLength(2);
+    });
+    // #7b — max_tokens 上下文溢出：status=400 + 特定消息 → 静默缩小 max_tokens 后重试（无 recovery 事件）
+    it("[max-tokens-overflow] shrinks max_tokens on a 400 overflow and retries silently", async () => {
+        const overflow = Object.assign(new Error("input length and `max_tokens` exceed context limit: 100000 + 50000 > 200000"), { status: 400 });
+        const transport = new ScriptedTransport([
+            { throw: overflow },
+            [{ type: "delta", text: "fits now" }, { type: "done", finishReason: "stop" }],
+        ]);
+        const events = await collect(executeToolLoop(baseParams({ runtimePorts: runtimePorts() }), transport, { invoke: vi.fn() }, log));
+        // available = contextLimit - inputTokens - 1000 = 200000 - 100000 - 1000 = 99000
+        expect(transport.requests[1]?.maxTokens).toBe(99000);
+        expect(recoveryActions(events)).toEqual([]); // silent recovery — no recovery event
+        expect(events.find((e) => e.type === "end")).toMatchObject({ content: "fits now" });
+    });
+    // #10 — 瞬时 429（前台）：退避后重试 → 完成（querySource 未设 → isForegroundSource()===true）
+    it("[429-retry] retries a foreground 429 after backoff then completes", async () => {
+        const rateLimited = Object.assign(new Error("rate limited"), { status: 429 });
+        const transport = new ScriptedTransport([
+            { throw: rateLimited },
+            [{ type: "delta", text: "after backoff" }, { type: "done", finishReason: "stop" }],
+        ]);
+        const events = await collect(executeToolLoop(baseParams({ runtimePorts: runtimePorts() }), transport, { invoke: vi.fn() }, log));
+        expect(recoveryActions(events)).toContain("retry");
+        expect(events.find((e) => e.type === "end")).toMatchObject({ content: "after backoff" });
+    }, 10000); // ~500ms real backoff (computeRetryBackoff) — allow headroom
+});

package/dist/agent/tunable-defaults.d.ts

@@ -0,0 +1 @@
+export * from "../runtime/config/tunable-defaults.js";

package/dist/agent/tunable-defaults.js

@@ -0,0 +1 @@
+export * from "../runtime/config/tunable-defaults.js";

package/dist/agent/types.d.ts

@@ -0,0 +1,311 @@
+/**
+ * Pure agent typeszero I/O framework dependencies.
+ *
+ * Wire-level types (ChatMessage, ToolDefinition) are canonical in
+ * protocol/wire/. This file re-exports them and adds
+ * internal-only extensions (e.g. backfillObservableInput on ToolDefinition).
+ */
+import type { SkillInstruction } from "../orchestration/index.js";
+import type { HookRegistry } from "../contracts/hooks.js";
+import type { AccumulatedToolCall, LLMChunk, LLMRequest, LLMTransport } from "../runtime/ports/index.js";
+import type { ChatMessage as WireChatMessage, ChatMessageRole as WireChatMessageRole, ThinkingBlock as WireThinkingBlock, ToolCallMessage as WireToolCallMessage, ToolDefinition as WireToolDefinition, WireTokenUsage } from "../protocol/wire/index.js";
+export type ChatMessageRole = WireChatMessageRole;
+export type ThinkingBlock = WireThinkingBlock;
+export type ToolCallMessage = WireToolCallMessage;
+export type ChatMessage = WireChatMessage;
+export type { AccumulatedToolCall, LLMChunk, LLMRequest, LLMTransport, };
+export type MediaCapability = "image" | "video" | "music" | "music_realtime" | "tts" | "3d" | "stt" | "embedding" | "video_understanding" | "image_understanding" | "voice_clone" | "rerank" | "document_parsing" | "realtime_audio" | "realtime_video";
+export interface ToolDefinition extends WireToolDefinition {
+    /**
+     * Backfill derived/legacy fields onto a shallow copy of the tool input
+     * before hooks and observers see it (CC backfillObservableInput parity).
+     * The original API-bound input is never modified.
+     * Internal-onlynever serialized over JSON-RPC.
+     */
+    backfillObservableInput?: (input: Record<string, unknown>) => void;
+}
+/**
+ * Token usageunified with WireTokenUsage from contracts.
+ * No more internal/wire split: all code uses the same field names
+ * (inputTokens, outputTokens, reasoningTokens, cacheRead, cacheWrite).
+ */
+export type TokenUsage = WireTokenUsage;
+/**
+ * Why the previous iteration continuedeach variant corresponds to one of
+ * the 7 `continue` sites in the main while(true) loop.
+ * Tests can assert recovery paths fired without inspecting message contents.
+ */
+export type ToolLoopTransition = {
+    reason: "collapse_drain_retry";
+    committed: number;
+} | {
+    reason: "reactive_compact_retry";
+} | {
+    reason: "max_output_tokens_escalate";
+} | {
+    reason: "max_output_tokens_recovery";
+    attempt: number;
+} | {
+    reason: "stop_hook_blocking";
+} | {
+    reason: "token_budget_continuation";
+} | {
+    reason: "next_turn";
+};
+/** Terminal exit reasons from the tool loop. */
+export type ToolLoopTerminal = {
+    reason: "completed";
+} | {
+    reason: "aborted";
+} | {
+    reason: "prompt_too_long";
+} | {
+    reason: "image_error";
+} | {
+    reason: "model_error";
+    error?: unknown;
+} | {
+    reason: "max_turns";
+} | {
+    reason: "budget_exhausted";
+} | {
+    reason: "tool_loop_limit";
+} | {
+    reason: "stop_hook_prevented";
+} | {
+    reason: "hook_stopped";
+};
+export interface TurnRequest {
+    turnId: string;
+    sessionId: string;
+    messages: ChatMessage[];
+    tools: ToolDefinition[];
+    systemPrompt?: string;
+    config?: TurnConfig;
+}
+export interface TurnConfig {
+    /** LLM provider id, e.g. "deepseek" */
+    provider?: string;
+    /** Model id, e.g. "deepseek-v4-flash" */
+    model?: string;
+    /** User API key */
+    apiKey?: string;
+    /** Optional base URL override */
+    baseUrl?: string;
+    /** Max tool-call rounds per turn (default 25, max 100) */
+    maxRounds?: number;
+    /** Temperature override */
+    temperature?: number;
+    /** Context window size in tokens (for turn-loop-guard budget checks) */
+    contextWindowTokens?: number;
+    /** Max output tokens for current model */
+    maxOutputTokens?: number;
+    /** Model's absolute max output tokens (for escalation ceiling) */
+    modelMaxOutputTokens?: number;
+    /** Tool choice strategy: "auto" (default), "none", "required" */
+    toolChoice?: "auto" | "none" | "required";
+    /** Parent fork depth (0 = top-level, default 0). CC: depth tracking for fork recursion limit. */
+    parentDepth?: number;
+    /** Per-turn token budget (prompt + completion). 0 or undefined = unlimited. */
+    tokenBudget?: number;
+    /** Fallback model to switch to after repeated 529 errors (CC parity). */
+    fallbackModel?: string;
+    /** Max turns (tool loop iterations). 0 or undefined = use maxRounds. */
+    maxTurns?: number;
+    /** Max concurrent tool executions (0 = unlimited). */
+    maxConcurrentTools?: number;
+    /** Model requires streamingdisable non-streaming fallback. */
+    streamRequired?: boolean;
+    /** Reasoning effort for models that support it (GPT-5.x, o-series). */
+    reasoning?: {
+        effort: "minimal" | "low" | "medium" | "high" | "xhigh";
+        includeEncryptedReasoning?: boolean;
+    };
+    /** Prompt cache bucketing key used instead of the provider-level `user` field. */
+    promptCacheKey?: string;
+    /** Prompt cache retention: "in_memory" (5-10min) or "24h". */
+    promptCacheRetention?: "in_memory" | "24h";
+    /** Service tier: "auto", "default", "flex" (50% cheaper), "priority". */
+    serviceTier?: "auto" | "default" | "flex" | "priority";
+    /** OpenAI Responses API built-in tools to inject. */
+    openaiBuiltinTools?: Array<{
+        type: "web_search_preview" | "file_search" | "code_interpreter" | "computer_use_preview";
+        [key: string]: unknown;
+    }>;
+    /** Max builtin tool calls per turn (shared across all builtin tools). */
+    maxToolCalls?: number;
+    /** Disable parallel tool calling (force sequential). */
+    parallelToolCalls?: boolean;
+    /** Text output verbosity hint: "low", "medium", "high". */
+    textVerbosity?: "low" | "medium" | "high";
+    /**
+     * User-designated provider+model per media category.
+     * Each entry maps a media type (image/video/music/tts/3d/...) to
+     * the specific provider and model the user chose. No failover
+     * if the designated provider fails, the error propagates directly.
+     */
+    mediaProviders?: Partial<Record<MediaCapability, {
+        provider: string;
+        model: string;
+    }>>;
+    /** MCP server configurations (stdio/sse/http). Passed from host to agent per-turn. */
+    mcpServers?: Record<string, unknown>;
+}
+export type TurnEvent = {
+    type: "start";
+    turnId: string;
+} | {
+    type: "delta";
+    turnId: string;
+    text: string;
+} | {
+    type: "tool_call";
+    turnId: string;
+    callId: string;
+    name: string;
+    arguments: string;
+    inputSummary?: string;
+} | {
+    type: "end";
+    turnId: string;
+    content: string;
+    usage?: TokenUsage;
+    model?: string;
+    provider?: string;
+    /** Per-turn recovery trace (action -> count); present only when recoveries fired. */
+    recoveryTrace?: Record<string, number>;
+} | {
+    type: "error";
+    turnId: string;
+    error: string;
+    code?: string;
+    usage?: TokenUsage;
+} | {
+    type: "skill_instruction";
+    turnId: string;
+    instruction: SkillInstruction;
+} | {
+    type: "tool_result";
+    turnId: string;
+    callId: string;
+    name: string;
+    ok: boolean;
+    error?: string;
+    outputPreview?: string;
+    durationMs?: number;
+    exitCode?: number;
+    stdout?: string;
+    stderr?: string;
+    details?: Record<string, unknown>;
+} | {
+    type: "tool_blocked";
+    turnId: string;
+    callId: string;
+    name: string;
+    reason: string;
+} | {
+    type: "recovery";
+    turnId: string;
+    action: string;
+    detail?: string;
+} | {
+    type: "plan_update";
+    turnId: string;
+    slug: string;
+    content: string;
+} | {
+    type: "heartbeat";
+    turnId: string;
+    message: string;
+} | {
+    type: "tool_use_summary";
+    turnId: string;
+    summary: string;
+} | {
+    type: "reasoning_delta";
+    turnId: string;
+    text: string;
+} | {
+    type: "suggestions";
+    turnId: string;
+    items: Array<{
+        text: string;
+        icon?: string;
+        action?: string;
+    }>;
+} | {
+    type: "media_result";
+    turnId: string;
+    mediaType: "image" | "tts" | "video" | "music" | "3d";
+    url: string;
+    model?: string;
+    provider?: string;
+    durationSeconds?: number;
+    width?: number;
+    height?: number;
+    mimeType?: string;
+    billingUnit?: string;
+    billingQuantity?: number;
+    taskId?: string;
+} | {
+    type: "artifact";
+    turnId: string;
+    artifactId: string;
+    artifactType: "code" | "file" | "image" | "document" | "diagram" | "table";
+    title: string;
+    filePath?: string;
+    language?: string;
+    content?: string;
+    mimeType?: string;
+} | {
+    type: "annotations";
+    turnId: string;
+    annotations: Array<{
+        type: string;
+        url?: string;
+        title?: string;
+        [key: string]: unknown;
+    }>;
+} | {
+    type: "subagent_started";
+    turnId: string;
+    subagentId: string;
+    agentType: string;
+    prompt?: string;
+} | {
+    type: "subagent_ended";
+    turnId: string;
+    subagentId: string;
+    agentType: string;
+    ok: boolean;
+    outputPreview?: string;
+    error?: string;
+};
+/**
+ * ToolInvoker: request tool execution from the host process (Gateway).
+ * In CLI mode this sends a JSON-RPC notification over stdio and waits for result.
+ */
+export interface ToolInvoker {
+    invoke(turnId: string, name: string, args: string, signal?: AbortSignal): Promise<{
+        result: string;
+        error?: string;
+        toolReferences?: string[];
+        imageUrls?: string[];
+        details?: Record<string, unknown>;
+    }>;
+}
+/**
+ * AgentLogger: structured logging interface.
+ * In CLI mode this writes to stderr; in Hub mode this uses pino.
+ */
+export interface AgentLogger {
+    info(message: string): void;
+    info(obj: Record<string, unknown>, message: string): void;
+    warn(message: string): void;
+    warn(obj: Record<string, unknown>, message: string): void;
+    error(message: string): void;
+    error(obj: Record<string, unknown>, message: string): void;
+    debug(message: string): void;
+    debug(obj: Record<string, unknown>, message: string): void;
+}
+export type { HookRegistry };

package/dist/agent/types.js

@@ -0,0 +1,8 @@
+/**
+ * Pure agent typeszero I/O framework dependencies.
+ *
+ * Wire-level types (ChatMessage, ToolDefinition) are canonical in
+ * protocol/wire/. This file re-exports them and adds
+ * internal-only extensions (e.g. backfillObservableInput on ToolDefinition).
+ */
+export {};

package/dist/cli/acp-commands.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Single-source slash-command registry for the ACP server.
+ *
+ * `buildAvailableCommands` (the list advertised via `available_commands_update` and summarized by
+ * `/help`) and `dispatchSlashCommand` (execution) share one source of truth — `BUILTIN_COMMANDS`.
+ * Each command's `dispatch` calls the same underlying data service the equivalent RPC handler uses
+ * (model-registry / tool-catalog / skills-query / project-store / acp-detector / memory store) and
+ * formats the result as a text reply. No half-wiring: a command is only listed if it can run.
+ *
+ * Command-set decision (per plan): 9 direct commands + `/init` (degraded to a prompt, no automatic
+ * function). `/compact` is intentionally NOT registered — context compaction is triggered
+ * automatically by reactive-compact, so exposing it as an explicit command would be misleading.
+ * `userInvocable` skill commands are enumerated dynamically; this codebase produces no
+ * `SkillCommandSpec`, so the enumeration is empty (a foreseen degradation, not a stub).
+ */
+import type { AcpSessionHost } from "./acp-session-host.js";
+export interface AcpCommandReply {
+    handled: boolean;
+    reply?: string;
+}
+export interface AcpCommandDef {
+    /** Command token including the leading "/". */
+    name: string;
+    description: string;
+    dispatch(host: AcpSessionHost, args: string): Promise<AcpCommandReply>;
+}
+export declare const BUILTIN_COMMANDS: AcpCommandDef[];
+export declare function buildAvailableCommands(host: AcpSessionHost): Array<{
+    name: string;
+    description?: string;
+}>;
+export declare function dispatchSlashCommand(host: AcpSessionHost, text: string, args: string): Promise<AcpCommandReply>;