@armadra/agent 0.4.0 → 0.5.0

package/dist/drivers/types.d.ts

@@ -0,0 +1,122 @@
+/**
+ * 外部 Agent 驱动契约（docs/wave5-plan.md §5.1–§5.3，D14）。[W5-C0] 契约文件，实现归 W5-E。
+ *
+ * 内部词汇 = ACP v1 子集：各家原生协议（Claude stream-json、Codex app-server、一次性打印模式）
+ * 都映射成 `DriverEvent`；权限请求以 `DriverPermissionRequest` 交给 ama 的 broker 链——**只交给人，
+ * 不代答**（auto 分类器与模型都不参与）。`ProcessRunner`（drivers/runner.ts）把 `AgentDriver`
+ * 适配成 `SubagentRunner`，于是外部 Agent 与 ama 子 Agent 共用 `task(agent=…)` 入口。
+ *
+ * 本目录只依赖 agent / permissions / tools 的类型（零运行时依赖）。
+ */
+import type { ContentBlock } from "../ai/types.js";
+import type { ExternalPermissionOrigin, PermissionMode } from "../permissions/types.js";
+export interface DriverCapabilities {
+    resume: "resume" | "load" | "none";
+    list: boolean;
+    /** `unreliable`：有审批通道但不保证每次都走（只在 plan 或只读任务下用）。 */
+    permissions: "interactive" | "none" | "unreliable";
+    steer: boolean;
+    modes: readonly PermissionMode[];
+    usage: "tokens" | "usd" | "requests" | "none";
+    images: boolean;
+}
+export type DriverKind = "acp" | "acp-adapter" | "claude-stream" | "codex-app-server" | "oneshot" | "host";
+export interface DriverProbe {
+    installed: boolean;
+    version?: string;
+    capabilities: DriverCapabilities;
+}
+export interface DriverOpenOptions {
+    cwd: string;
+    /** 不得比 ama 当前模式宽（`agents.<id>.maxMode` 显式放宽除外）。 */
+    mode: PermissionMode;
+    model?: string;
+    /** 外部 CLI 自己的会话 id。 */
+    resume?: string;
+    /** 已按 D16 清理的子进程环境（drivers/env.ts）。 */
+    env: NodeJS.ProcessEnv;
+    signal: AbortSignal;
+    /**
+     * [W5-E] 美元预算：能透传的驱动透传（Claude `--max-budget-usd`）；其余由 ProcessRunner 按用量
+     * 累计、超限 cancel。
+     */
+    budgetUsd?: number;
+    /** [W5-E] 无人值守（没有人能回答审批）：Claude 以 `--permission-prompts none` 启动。 */
+    unattended?: boolean;
+}
+export interface AgentDriver {
+    readonly agentId: string;
+    readonly kind: DriverKind;
+    probe(): Promise<DriverProbe>;
+    open(options: DriverOpenOptions): Promise<DriverSession>;
+}
+/** ACP ToolKind。 */
+export type AcpToolKind = "read" | "edit" | "delete" | "move" | "search" | "execute" | "think" | "fetch" | "switch_mode" | "other";
+export type DriverEvent = {
+    type: "message_delta";
+    text: string;
+} | {
+    type: "thought_delta";
+    text: string;
+} | {
+    type: "tool_call";
+    id: string;
+    title: string;
+    kind: AcpToolKind;
+    status: "pending" | "in_progress" | "completed" | "failed";
+    locations?: string[];
+} | {
+    type: "plan";
+    entries: {
+        content: string;
+        status: string;
+    }[];
+} | {
+    type: "usage";
+    input?: number;
+    output?: number;
+    cacheRead?: number;
+    costUsd?: number;
+    contextTokens?: number;
+    contextWindow?: number;
+} | {
+    type: "notice";
+    level: "info" | "warn";
+    text: string;
+};
+/** 外部 Agent 的权限请求 = 审批上下文里的 `origin`（会话 id 与 agent 由驱动填）。 */
+export type DriverPermissionRequest = Omit<ExternalPermissionOrigin, "agent" | "sessionId">;
+/** 人选了某个选项，或请求被取消（父 abort、`task_ctl stop`、超时、无人值守下的提问类请求）。 */
+export type DriverPermissionOutcome = {
+    outcome: "selected";
+    optionId: string;
+} | {
+    outcome: "cancelled";
+};
+export interface DriverTurnResult {
+    stopReason: "end_turn" | "max_tokens" | "max_turn_requests" | "refusal" | "cancelled";
+    finalText: string;
+    usage?: {
+        input?: number;
+        output?: number;
+        cacheRead?: number;
+        costUsd?: number;
+    };
+    filesTouched: string[];
+    /** ≤ 20 行。 */
+    toolSummary: string[];
+}
+export interface DriverPromptHooks {
+    onEvent(event: DriverEvent): void;
+    onPermission(request: DriverPermissionRequest, signal: AbortSignal): Promise<DriverPermissionOutcome>;
+}
+export interface DriverSession {
+    /** 一律存 CLI 自己的 id。 */
+    readonly sessionId: string;
+    prompt(content: ContentBlock[], hooks: DriverPromptHooks): Promise<DriverTurnResult>;
+    steer?(content: ContentBlock[]): Promise<void>;
+    /** 协议级中断；15 s 无回合结束 → 关 stdin → SIGTERM 进程树。 */
+    cancel(): Promise<void>;
+    /** 挂起审批统一回 cancelled。 */
+    close(): Promise<void>;
+}

package/dist/drivers/types.js

@@ -0,0 +1,11 @@
+/**
+ * 外部 Agent 驱动契约（docs/wave5-plan.md §5.1–§5.3，D14）。[W5-C0] 契约文件，实现归 W5-E。
+ *
+ * 内部词汇 = ACP v1 子集：各家原生协议（Claude stream-json、Codex app-server、一次性打印模式）
+ * 都映射成 `DriverEvent`；权限请求以 `DriverPermissionRequest` 交给 ama 的 broker 链——**只交给人，
+ * 不代答**（auto 分类器与模型都不参与）。`ProcessRunner`（drivers/runner.ts）把 `AgentDriver`
+ * 适配成 `SubagentRunner`，于是外部 Agent 与 ama 子 Agent 共用 `task(agent=…)` 入口。
+ *
+ * 本目录只依赖 agent / permissions / tools 的类型（零运行时依赖）。
+ */
+export {};

package/dist/git/info.d.ts

@@ -0,0 +1,75 @@
+/**
+ * 状态行的 git 信息（docs/wave5-plan.md §1.3）。[W5-A]
+ *
+ * - 分支与短提交零依赖读 `.git/HEAD`（`checkpoints/git-head.ts`，worktree / 子模块的 gitdir 文件、
+ *   packed-refs 都认）；detached 时没有分支只显示短提交；还没有提交的分支只显示分支名。
+ * - 工作区增删行：`git diff --numstat HEAD`（含暂存，不含未跟踪文件）后台子进程，环境加
+ *   `GIT_OPTIONAL_LOCKS=0`；两次之间 ≥ `minIntervalMs`（缺省 10 s），超过 `timeoutMs`（缺省 2 s）或
+ *   非零退出 / 起不来就省略增删项，并在本实例（本会话）停用 numstat，HEAD 仍照常显示。
+ *   `AMA_STATUS_GIT=0` 直接关闭 numstat（排错用）。
+ * - 非 git 目录 `current()` 为 undefined（状态行整段省略）。
+ * - `refresh()` 在回合边界调用（agent_settled、写类工具结束、回滚、/tree），只发起读取、不阻塞；
+ *   结果有变化时通知 `onChange` 的监听者。
+ */
+export interface GitInfo {
+    /** detached 时 undefined，显示短提交。 */
+    branch?: string;
+    /** 7 位；还没有提交时 undefined。 */
+    shortHead?: string;
+    /** 工作区（含暂存）相对 HEAD；拿不到为 undefined。 */
+    insertions?: number;
+    deletions?: number;
+}
+/** numstat 子进程的最小接口（测试注入）。 */
+export interface NumstatProcess {
+    stdout: NodeJS.ReadableStream | null;
+    on(event: "close", listener: (code: number | null) => void): unknown;
+    on(event: "error", listener: (error: Error) => void): unknown;
+    kill(signal?: NodeJS.Signals): unknown;
+}
+export type NumstatSpawn = (command: string, args: readonly string[], options: {
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+}) => NumstatProcess;
+export interface GitInfoDeps {
+    spawn?: NumstatSpawn;
+    now?(): number;
+    minIntervalMs?: number;
+    timeoutMs?: number;
+    env?: NodeJS.ProcessEnv;
+}
+export declare const GIT_NUMSTAT_INTERVAL_MS = 10000;
+export declare const GIT_NUMSTAT_TIMEOUT_MS = 2000;
+/** 解析 `git diff --numstat` 输出（二进制文件的 `-\t-` 跳过）。 */
+export declare function parseNumstat(text: string): {
+    insertions: number;
+    deletions: number;
+};
+export declare class GitInfoWatcher {
+    private readonly cwd;
+    private info;
+    private readonly listeners;
+    private readonly spawn;
+    private readonly now;
+    private readonly minIntervalMs;
+    private readonly timeoutMs;
+    private readonly env;
+    private numstatDisabled;
+    private lastNumstatAt;
+    private numstatRunning;
+    private headReading;
+    private headAgain;
+    private disposed;
+    private diff;
+    constructor(cwd: string, deps?: GitInfoDeps);
+    current(): GitInfo | undefined;
+    /** numstat 已因超时 / 失败 / 环境变量停用。 */
+    get numstatEnabled(): boolean;
+    onChange(listener: () => void): () => void;
+    /** 回合边界调用：重读 HEAD；距上次 numstat ≥ minInterval 则后台起一次。返回本次读取完成的 Promise（测试用）。 */
+    refresh(): Promise<void>;
+    dispose(): void;
+    private update;
+    private maybeNumstat;
+    private numstat;
+}

package/dist/git/info.js

@@ -0,0 +1,191 @@
+/**
+ * 状态行的 git 信息（docs/wave5-plan.md §1.3）。[W5-A]
+ *
+ * - 分支与短提交零依赖读 `.git/HEAD`（`checkpoints/git-head.ts`，worktree / 子模块的 gitdir 文件、
+ *   packed-refs 都认）；detached 时没有分支只显示短提交；还没有提交的分支只显示分支名。
+ * - 工作区增删行：`git diff --numstat HEAD`（含暂存，不含未跟踪文件）后台子进程，环境加
+ *   `GIT_OPTIONAL_LOCKS=0`；两次之间 ≥ `minIntervalMs`（缺省 10 s），超过 `timeoutMs`（缺省 2 s）或
+ *   非零退出 / 起不来就省略增删项，并在本实例（本会话）停用 numstat，HEAD 仍照常显示。
+ *   `AMA_STATUS_GIT=0` 直接关闭 numstat（排错用）。
+ * - 非 git 目录 `current()` 为 undefined（状态行整段省略）。
+ * - `refresh()` 在回合边界调用（agent_settled、写类工具结束、回滚、/tree），只发起读取、不阻塞；
+ *   结果有变化时通知 `onChange` 的监听者。
+ */
+import { spawn as nodeSpawn } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { findGitDir, readGitHead } from "../checkpoints/git-head.js";
+export const GIT_NUMSTAT_INTERVAL_MS = 10_000;
+export const GIT_NUMSTAT_TIMEOUT_MS = 2_000;
+/** 解析 `git diff --numstat` 输出（二进制文件的 `-\t-` 跳过）。 */
+export function parseNumstat(text) {
+    let insertions = 0;
+    let deletions = 0;
+    for (const line of text.split("\n")) {
+        const match = /^(\d+)\t(\d+)\t/.exec(line);
+        if (match === null)
+            continue;
+        insertions += Number(match[1]);
+        deletions += Number(match[2]);
+    }
+    return { insertions, deletions };
+}
+async function readHead(cwd) {
+    const head = await readGitHead(cwd);
+    if (head !== undefined) {
+        return {
+            shortHead: head.head.slice(0, 7),
+            ...(head.branch !== undefined ? { branch: head.branch } : {}),
+        };
+    }
+    // 还没有提交（unborn 分支）：只有分支名
+    const gitDir = await findGitDir(cwd);
+    if (gitDir === undefined)
+        return undefined;
+    const text = await readFile(join(gitDir, "HEAD"), "utf8").catch(() => undefined);
+    const match = /^ref:\s*refs\/heads\/(\S+)\s*$/.exec(text ?? "");
+    return match?.[1] !== undefined ? { branch: match[1] } : undefined;
+}
+const sameInfo = (a, b) => a?.branch === b?.branch &&
+    a?.shortHead === b?.shortHead &&
+    a?.insertions === b?.insertions &&
+    a?.deletions === b?.deletions &&
+    (a === undefined) === (b === undefined);
+export class GitInfoWatcher {
+    cwd;
+    info;
+    listeners = new Set();
+    spawn;
+    now;
+    minIntervalMs;
+    timeoutMs;
+    env;
+    numstatDisabled;
+    lastNumstatAt = Number.NEGATIVE_INFINITY;
+    numstatRunning = false;
+    headReading;
+    headAgain = false;
+    disposed = false;
+    diff;
+    constructor(cwd, deps = {}) {
+        this.cwd = cwd;
+        this.spawn = deps.spawn ?? ((command, args, options) => nodeSpawn(command, args, options));
+        this.now = deps.now ?? Date.now;
+        this.minIntervalMs = deps.minIntervalMs ?? GIT_NUMSTAT_INTERVAL_MS;
+        this.timeoutMs = deps.timeoutMs ?? GIT_NUMSTAT_TIMEOUT_MS;
+        this.env = deps.env ?? process.env;
+        this.numstatDisabled = this.env["AMA_STATUS_GIT"] === "0";
+    }
+    current() {
+        return this.info;
+    }
+    /** numstat 已因超时 / 失败 / 环境变量停用。 */
+    get numstatEnabled() {
+        return !this.numstatDisabled;
+    }
+    onChange(listener) {
+        this.listeners.add(listener);
+        return () => void this.listeners.delete(listener);
+    }
+    /** 回合边界调用：重读 HEAD；距上次 numstat ≥ minInterval 则后台起一次。返回本次读取完成的 Promise（测试用）。 */
+    refresh() {
+        if (this.disposed)
+            return Promise.resolve();
+        if (this.headReading !== undefined) {
+            this.headAgain = true;
+            return this.headReading;
+        }
+        const run = async () => {
+            do {
+                this.headAgain = false;
+                const head = await readHead(this.cwd).catch(() => undefined);
+                this.update(head);
+            } while (this.headAgain && !this.disposed);
+            this.headReading = undefined;
+            if (this.info !== undefined)
+                await this.maybeNumstat();
+        };
+        this.headReading = run();
+        return this.headReading;
+    }
+    dispose() {
+        this.disposed = true;
+        this.listeners.clear();
+    }
+    update(head) {
+        const next = head === undefined
+            ? undefined
+            : {
+                ...head,
+                ...(this.diff !== undefined && head.shortHead !== undefined ? this.diff : {}),
+            };
+        if (sameInfo(this.info, next))
+            return;
+        this.info = next;
+        for (const listener of [...this.listeners])
+            listener();
+    }
+    maybeNumstat() {
+        if (this.numstatDisabled || this.numstatRunning)
+            return Promise.resolve();
+        if (this.info?.shortHead === undefined)
+            return Promise.resolve();
+        const at = this.now();
+        if (at - this.lastNumstatAt < this.minIntervalMs)
+            return Promise.resolve();
+        this.lastNumstatAt = at;
+        this.numstatRunning = true;
+        return this.numstat().then((diff) => {
+            this.numstatRunning = false;
+            if (this.disposed)
+                return;
+            if (diff === undefined) {
+                this.numstatDisabled = true;
+                this.diff = undefined;
+            }
+            else
+                this.diff = diff;
+            const info = this.info;
+            if (info === undefined)
+                return;
+            const { insertions: _i, deletions: _d, ...head } = info;
+            this.update(head);
+        });
+    }
+    numstat() {
+        return new Promise((resolve) => {
+            let settled = false;
+            let timer;
+            const done = (value) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                resolve(value);
+            };
+            let child;
+            try {
+                child = this.spawn("git", ["diff", "--numstat", "HEAD"], {
+                    cwd: this.cwd,
+                    env: { ...this.env, GIT_OPTIONAL_LOCKS: "0" },
+                });
+            }
+            catch {
+                resolve(undefined);
+                return;
+            }
+            timer = setTimeout(() => {
+                child.kill("SIGKILL");
+                done(undefined);
+            }, this.timeoutMs);
+            timer.unref?.();
+            let out = "";
+            child.stdout?.setEncoding?.("utf8");
+            child.stdout?.on("data", (chunk) => {
+                out += String(chunk);
+            });
+            child.on("error", () => done(undefined));
+            child.on("close", (code) => done(code === 0 ? parseNumstat(out) : undefined));
+        });
+    }
+}

package/dist/hooks/protocol.js

@@ -23,12 +23,17 @@ const ACCEPTED = {
     SessionStart: ["block"],
     Notification: [],
     SessionEnd: [],
+    PostRewind: [],
+    PostCompact: [],
 };
 /** 退出码 2 映射的阻止决策；undefined = 该事件忽略退出码 2。 */
 export function blockingDecision(event) {
     if (event === "PreToolUse")
         return "deny";
-    if (event === "Notification" || event === "SessionEnd")
+    if (event === "Notification" ||
+        event === "SessionEnd" ||
+        event === "PostRewind" ||
+        event === "PostCompact")
         return undefined;
     return "block";
 }

package/dist/hooks/types.d.ts

@@ -8,7 +8,9 @@
  * - `HookDecision` = stdout JSON 里 `decision` 的取值；合并规则 deny > block > ask > allow。
  */
 import type { PermissionMode } from "../permissions/types.js";
-export type HookEvent = "SessionStart" | "UserPromptSubmit" | "PreToolUse" | "PostToolUse" | "Stop" | "SubagentStop" | "PreCompact" | "Notification" | "SessionEnd";
+export type HookEvent = "SessionStart" | "UserPromptSubmit" | "PreToolUse" | "PostToolUse" | "Stop" | "SubagentStop" | "PreCompact" | "Notification" | "SessionEnd" | "PostRewind"
+/** [W5-C0] 压缩完成后（不可阻止；additionalContext 追加在 ama.post_compact 之后，W5-H1 触发）。 */
+ | "PostCompact";
 export declare const HOOK_EVENTS: readonly HookEvent[];
 export type HookDecision = "allow" | "deny" | "ask" | "block";
 export interface HookCommand {
@@ -65,7 +67,14 @@ export interface HookInput {
     stopHookActive?: boolean;
     tokensBefore?: number;
     trigger?: "auto" | "manual";
+    /** [W5-C0] PostCompact：压缩后的估算 token。 */
+    tokensAfter?: number;
     notification?: HookNotification;
+    /** 回滚到的用户消息条目 id。 */
+    entryId?: string;
+    mode?: "both" | "conversation" | "code";
+    /** 被恢复或删除的文件（cwd 内相对路径，cwd 外绝对路径）；仅对话时为空。 */
+    files?: string[];
     /** Pre/PostToolUse：本次调用来自 codemode 脚本里的 `tools.*`（设计 §5.5）。 */
     viaCodemode?: boolean;
     /** Pre/PostToolUse：codemode 内层调用时为外层 `codemode` 调用的 toolCallId。 */

package/dist/hooks/types.js

@@ -17,4 +17,6 @@ export const HOOK_EVENTS = [
     "PreCompact",
     "Notification",
     "SessionEnd",
+    "PostRewind",
+    "PostCompact",
 ];

package/dist/host/api-impl.d.ts

@@ -5,7 +5,12 @@
  * （B2 组装后才可用，所以全部是惰性函数）、指令收集、broker 槽、sendUser、UI 通知。
  * 事件总线 `AgentEventBus` 由 bootstrap 创建并交给 AgentSession 发事件；处理器只观察，
  * 抛错记日志；`emit` 等待全部处理器（`session_shutdown` 需要被 await）。
+ *
+ * [W5-EG] `runners.provide`（docs/wave5-plan.md §5.5，D17）：宿主注入的 runner 进本适配器的
+ * {@link HostRunnerRegistry}（跨会话共享），每个主会话的外部 Agent 入口（agents/external.ts）经
+ * {@link hostRunnersOf} 取到它；有宿主时 ama 不自 spawn 外部 CLI，只认这里注入的。
  */
+import { HostRunnerRegistry } from "../drivers/host-runners.js";
 import type { AgentEventName, AgentEvents, ApprovalBroker, HostAdapter, HostAdapterHandle, HostApi, HostMode, InstructionSource } from "./types.js";
 import type { ToolRegistryApi } from "../tools/types.js";
 import type { WarmingDecisionHandler } from "../ai/cache/types.js";
@@ -71,5 +76,7 @@ export interface HostApiBinding {
     /** [W3-C0] 宿主经 `cache.onWarmingDecision` 注册的否决钩子（最后注册且未注销的那个）。 */
     warmingDecider(): WarmingDecisionHandler | undefined;
 }
+/** [W5-EG] 宿主经 `runners.provide` 注入的 runner（HostApi 不是本模块创建的返回 undefined）。 */
+export declare function hostRunnersOf(api: HostApi): HostRunnerRegistry | undefined;
 export declare function createHostApi(deps: HostApiDeps): HostApiBinding;
 export {};

package/dist/host/api-impl.js

@@ -5,7 +5,12 @@
  * （B2 组装后才可用，所以全部是惰性函数）、指令收集、broker 槽、sendUser、UI 通知。
  * 事件总线 `AgentEventBus` 由 bootstrap 创建并交给 AgentSession 发事件；处理器只观察，
  * 抛错记日志；`emit` 等待全部处理器（`session_shutdown` 需要被 await）。
+ *
+ * [W5-EG] `runners.provide`（docs/wave5-plan.md §5.5，D17）：宿主注入的 runner 进本适配器的
+ * {@link HostRunnerRegistry}（跨会话共享），每个主会话的外部 Agent 入口（agents/external.ts）经
+ * {@link hostRunnersOf} 取到它；有宿主时 ama 不自 spawn 外部 CLI，只认这里注入的。
  */
+import { HostRunnerRegistry } from "../drivers/host-runners.js";
 import { AmaError } from "../errors.js";
 import { AMA_VERSION } from "../version.js";
 import { HOST_API_VERSION } from "./types.js";
@@ -43,6 +48,11 @@ export class AgentEventBus {
     }
 }
 const TOOL_NAME = /^[a-z][a-z0-9_]{1,63}$/;
+const hostRunnerRegistries = new WeakMap();
+/** [W5-EG] 宿主经 `runners.provide` 注入的 runner（HostApi 不是本模块创建的返回 undefined）。 */
+export function hostRunnersOf(api) {
+    return hostRunnerRegistries.get(api);
+}
 function validateTool(tool) {
     if (typeof tool !== "object" || tool === null) {
         throw new AmaError("invalid_arguments", "tools.register：工具定义应为对象");
@@ -65,6 +75,7 @@ export function createHostApi(deps) {
     let broker;
     const warmingHandlers = [];
     let notify = deps.notify;
+    const runners = new HostRunnerRegistry();
     const writeErr = deps.stderr ?? ((text) => void process.stderr.write(text));
     const log = deps.log ??
         ((level, message) => {
@@ -154,7 +165,11 @@ export function createHostApi(deps) {
                 };
             },
         }),
+        runners: Object.freeze({
+            provide: (runner) => runners.provide(runner),
+        }),
     });
+    hostRunnerRegistries.set(api, runners);
     return {
         api,
         instructions,

package/dist/host/types.d.ts

@@ -10,13 +10,18 @@
  * - （W3-C0）第三波 §1.10 / §1.7：`AgentEvents` 加 `cache_miss`、`context_pressure`；
  *   `HostApi.cache.onWarmingDecision` 为可选面（HOST_API_VERSION 不变，旧宿主不受影响），
  *   多个处理器时最后注册的生效。
+ * - （W5-C0）第五波 §5.5 / §6.5 / §7.5：可选面 `HostApi.runners`（宿主注入的子 Agent runner，
+ *   以 `task(agent=…)` 入口出现；有宿主时内置外部 runner 一律不可用，实现归 W5-E / W5-G）；
+ *   `AgentEvents` 加 `subagent_start / subagent_end / plan_proposed / plan_resolved`。
+ *   HOST_API_VERSION 不变。
  */
 import type { CacheMiss, WarmingDecisionHandler } from "../ai/cache/types.js";
 import type { HookEvent } from "../hooks/types.js";
 import type { ApprovalBroker, ApprovalDecision } from "../permissions/types.js";
-import type { ToolDefinition } from "../tools/types.js";
+import type { SubagentRunner, ToolDefinition } from "../tools/types.js";
+import type { PlanProposedEvent, PlanResolvedEvent, SubagentEndEvent, SubagentStartEvent } from "../agent/types-w5.js";
 export type { ActionPreview, ActionPreviewTarget, ApprovalBroker, ApprovalDecision, ApprovalReason, ApprovalRequest, ApprovalRequestContext, } from "../permissions/types.js";
-export type { ToolAnnotations, ToolContext, ToolDefinition, ToolExecutionMode, ToolPermission, ToolResult, } from "../tools/types.js";
+export type { RunnerHandle, SubagentEvent, SubagentRunRequest, SubagentRunner, ToolAnnotations, ToolContext, ToolDefinition, ToolExecutionMode, ToolPermission, ToolResult, } from "../tools/types.js";
 export type { JsonSchema } from "../ai/types.js";
 export type { CacheMiss, WarmDecision, WarmingDecisionHandler } from "../ai/cache/types.js";
 export declare const HOST_API_VERSION: 1;
@@ -104,7 +109,17 @@ export interface AgentEvents {
         remainingTokens?: number;
         estimatedTurnsLeft?: number;
     };
+    /** [W5-C0] 子 Agent 任务开始 / 结束（含宿主 runner 与外部 Agent）。 */
+    subagent_start: Omit<SubagentStartEvent, "type">;
+    subagent_end: Omit<SubagentEndEvent, "type">;
+    /** [W5-C0] 计划提出 / 审批结果。 */
+    plan_proposed: Omit<PlanProposedEvent, "type">;
+    plan_resolved: Omit<PlanResolvedEvent, "type">;
 }
+/** [W5-C0] 宿主注入的 runner：`id` 即 `task(agent=<id>)` 的名字，`description` 进 task 工具描述。 */
+export type HostRunner = SubagentRunner & {
+    readonly description: string;
+};
 export type AgentEventName = keyof AgentEvents;
 export interface HostApi {
     readonly version: HostApiVersion;
@@ -157,6 +172,13 @@ export interface HostApi {
     readonly cache?: {
         onWarmingDecision(handler: WarmingDecisionHandler): () => void;
     };
+    /**
+     * [W5-C0] 宿主注入的子 Agent runner（画布节点等，docs/wave5-plan.md §5.5）：注入后同名的内置
+     * 外部 runner 被替换；返回值用于注销。可选面：旧版本运行时没有它（实现归 W5-E / W5-G）。
+     */
+    readonly runners?: {
+        provide(runner: HostRunner): () => void;
+    };
 }
 /** Runtime 持有的已激活适配器。 */
 export interface HostAdapterHandle {

package/dist/host/types.js

@@ -10,5 +10,9 @@
  * - （W3-C0）第三波 §1.10 / §1.7：`AgentEvents` 加 `cache_miss`、`context_pressure`；
  *   `HostApi.cache.onWarmingDecision` 为可选面（HOST_API_VERSION 不变，旧宿主不受影响），
  *   多个处理器时最后注册的生效。
+ * - （W5-C0）第五波 §5.5 / §6.5 / §7.5：可选面 `HostApi.runners`（宿主注入的子 Agent runner，
+ *   以 `task(agent=…)` 入口出现；有宿主时内置外部 runner 一律不可用，实现归 W5-E / W5-G）；
+ *   `AgentEvents` 加 `subagent_start / subagent_end / plan_proposed / plan_resolved`。
+ *   HOST_API_VERSION 不变。
  */
 export const HOST_API_VERSION = 1;

package/dist/index.d.ts

@@ -10,6 +10,7 @@ export { HOST_API_VERSION } from "./host/types.js";
 export { RPC_PROTOCOL_VERSION } from "./rpc.js";
 export { SESSION_FORMAT_VERSION } from "./session/types.js";
 export { HOOK_EVENTS } from "./hooks/types.js";
+export { REWIND_NOTE_CUSTOM_TYPE } from "./checkpoints/types.js";
 export { PERMISSION_MODES_STRICT_FIRST } from "./permissions/types.js";
 export { ExitCode, describeExitCode } from "./cli/exit-codes.js";
 export { defineTool } from "./tools/types.js";
@@ -24,10 +25,12 @@ export type * from "./hooks/types.js";
 export type * from "./permissions/types.js";
 export type * from "./host/types.js";
 export type * from "./config/types.js";
+export type * from "./checkpoints/types.js";
 export type { AmaErrorOptions, ErrorCode, KnownErrorCode } from "./errors.js";
 export type { Runtime, RuntimeMode, ResolvedPaths, TrustState, LoadedResources, } from "./cli/runtime.js";
 export { createAgentSession, createRuntime } from "./sdk.js";
 export type { CreateSessionOptions, RuntimeOptions, SessionAuth } from "./sdk.js";
+export type { PlanDecision, PlanResponse, PlanResponseResult, SdkAgentSession, SessionPlanApi, SessionPlanOptions, } from "./sdk.js";
 export { AgentSessionImpl } from "./agent/session.js";
 export { SessionManager } from "./session/manager.js";
 export { ProviderRegistry } from "./ai/providers/registry.js";

package/dist/index.js

@@ -11,6 +11,7 @@ export { HOST_API_VERSION } from "./host/types.js";
 export { RPC_PROTOCOL_VERSION } from "./rpc.js";
 export { SESSION_FORMAT_VERSION } from "./session/types.js";
 export { HOOK_EVENTS } from "./hooks/types.js";
+export { REWIND_NOTE_CUSTOM_TYPE } from "./checkpoints/types.js";
 export { PERMISSION_MODES_STRICT_FIRST } from "./permissions/types.js";
 export { ExitCode, describeExitCode } from "./cli/exit-codes.js";
 export { defineTool } from "./tools/types.js";

package/dist/modes/acp/acp-events.d.ts

@@ -0,0 +1,46 @@
+/**
+ * `ama --mode acp`：ama 的会话事件 → ACP `session/update`（docs/wave5-plan.md §5.6）。[W5-E]
+ *
+ * | ama                                  | ACP                                                        |
+ * | ------------------------------------ | ---------------------------------------------------------- |
+ * | message_update text_delta            | agent_message_chunk                                        |
+ * | message_update thinking_delta        | agent_thought_chunk                                        |
+ * | message_update toolcall_end          | tool_call（pending，带 rawInput 与 locations）             |
+ * | tool_execution_start / end           | tool_call_update（in_progress → completed / failed）       |
+ * | todo_updated                         | plan                                                       |
+ * | turn_end                             | usage_update（上下文用量、窗口、会话累计美元）             |
+ * | permission_mode_changed              | current_mode_update                                        |
+ *
+ * 工具结果只回前 4 KB 文本（完整结果在 ama 会话里），codemode 内层调用（带 parentToolCallId）
+ * 不单列。`session/load` 回放同一套映射（用户消息 → user_message_chunk）。
+ */
+import type { AgentMessage } from "../../session/types.js";
+import type { AgentSession, SessionEvent } from "../../agent/types.js";
+import type { AcpSessionUpdate, AcpToolCallLocation, AcpToolKind } from "../../drivers/acp/types.js";
+export declare const TOOL_OUTPUT_LIMIT: number;
+export declare function toolKind(name: string): AcpToolKind;
+export declare function toolTitle(name: string, args: unknown): string;
+export declare function toolLocations(args: unknown, cwd: string): AcpToolCallLocation[] | undefined;
+export declare function permissionModes(currentModeId: string): {
+    currentModeId: string;
+    availableModes: {
+        id: import("../../permissions/types.js").PermissionMode;
+        name: import("../../permissions/types.js").PermissionMode;
+    }[];
+};
+/** 一个会话的事件映射器（记住模型发出的工具调用，供权限请求关联 toolCallId）。 */
+export declare class AcpEventMapper {
+    private readonly cwd;
+    private readonly emit;
+    private readonly session;
+    /** 模型已发出、尚未执行完的工具调用。 */
+    private readonly pendingCalls;
+    constructor(cwd: string, emit: (update: AcpSessionUpdate) => void, session: () => AgentSession);
+    /** 权限请求对应的工具调用 id（按工具名与参数匹配最近一个）。 */
+    toolCallIdFor(toolName: string, input: unknown): string | undefined;
+    onEvent(event: SessionEvent): void;
+    emitUsage(): void;
+    /** `session/load`：按消息回放历史。 */
+    replay(messages: readonly AgentMessage[]): void;
+    private emitToolCall;
+}