@router-agent/runtime 0.0.0-stage → 0.3.31

package/dist/port.d.ts

@@ -0,0 +1,295 @@
+import type { Assignment, InputKind, Ticket } from '@router-agent/core/model.js';
+/** 工单执行上下文：Router 负责拼装，运行时只消费。 */
+export interface WorkerContext {
+    ticket: Ticket;
+    assignment: Assignment;
+    /** 预分配目录；为空表示由运行时决定。 */
+    workdir: string;
+    /** 运行时中立的工单契约；Router 正常都会提供，缺省时 adapter 可自行渲染。 */
+    brief?: WorkerBrief;
+    /** 报告文件路径；缺省时由 adapter 按 workersDir 推导。 */
+    report?: ReportPaths;
+    /** 工具策略；缺省时使用内置默认值。 */
+    tools?: ToolPolicy;
+}
+/** 运行时中立的任务契约：只讲“做什么/怎么上报”，不讲某个 CLI 的参数。 */
+export interface WorkerBrief {
+    ticketId: string;
+    title: string;
+    scope: string;
+    workBranch: string;
+    /** 已渲染的正文（工单、授权范围、交付规则、上报命令）。 */
+    contract: string;
+}
+export interface ReportPaths {
+    statePath: string;
+    eventsPath: string;
+}
+/** 中立工具策略；adapter 负责映射到各 CLI 的开关。 */
+export interface ToolPolicy {
+    fileAccess: 'read-only' | 'read-write';
+    /** deny=不给 shell；allowlist=只放行 shellAllow 中的命令前缀；allow=任意 shell。 */
+    shell: 'deny' | 'allowlist' | 'allow';
+    /** shell=allowlist 时生效，按命令前缀匹配，例如 ['ra report','ra doc','git','gh']。 */
+    shellAllow?: string[];
+    allowNetwork: boolean;
+}
+export interface InboundMessage {
+    /** 输入 id（in_xxx）；投递时原样展示给 worker，用于写进 acked_inputs。 */
+    id: string;
+    kind: InputKind;
+    text: string;
+}
+export type ContextItem = {
+    kind: 'system-prompt';
+    text: string;
+} | {
+    kind: 'file';
+    path: string;
+    content: string;
+} | {
+    kind: 'env';
+    key: string;
+    value: string;
+} | {
+    kind: 'dir';
+    path: string;
+};
+/** Router 传给运行时的引用：handle 不透明，其余字段让运行时能定位自己的 meta/会话。 */
+export interface WorkspaceRequest {
+    ticketId: string;
+    repo: string;
+    baseBranch: string;
+    workBranch: string;
+    name: string;
+    workdir?: string;
+}
+export interface Workspace {
+    workspaceRef: string;
+    workdir: string;
+    branch: string;
+    meta?: Record<string, unknown>;
+}
+/** 内部构件：工作区生命周期。Orca 等运行时可以不严格实现。 */
+export interface WorkspaceProvider {
+    readonly id: string;
+    create(req: WorkspaceRequest): Promise<Workspace>;
+    inspect(ref: string): Promise<WorkspaceInfo | null>;
+    /**
+     * 回收检出。`repo` 是源仓库绝对路径：git worktree remove 必须在 git 上下文里跑，
+     * 否则会报 `fatal: not a git repository`。
+     */
+    remove(ref: string, opts?: {
+        force?: boolean;
+        repo?: string;
+    }): Promise<void>;
+    listRepos?(): Promise<RepoDescriptor[]>;
+}
+export interface WorkerRef {
+    handle: string;
+    ticketId: string;
+    workdir?: string;
+    /** 运行时自己的会话 ID（Claude/Codex 用；Orca 可空）。 */
+    sessionId?: string;
+}
+/** 工作区引用：回收/查询时使用，不依赖 provider 私有选择器语法。 */
+export interface WorkspaceRef {
+    ticketId: string;
+    workdir: string;
+    /** provider 自己的稳定标识；为空时由 workdir 推导。 */
+    workspaceRef?: string;
+    /** 源仓库绝对路径；回收检出时用它当 git 上下文。 */
+    repo?: string;
+}
+export interface StartResult {
+    handle: string;
+    workdir: string;
+    /** 实际工作分支（可能被 provider 加后缀）；供 PR 兜底查询。 */
+    branch?: string;
+    /** 会话 ID；写入 runtime 的 meta.json，供 resume/活动定位。 */
+    sessionId?: string;
+    workspaceRef?: string;
+}
+export interface ActivityQuery {
+    ref: WorkerRef;
+    opts?: {
+        maxBytes?: number;
+        maxEvents?: number;
+    };
+}
+/** 投递回执：Router 据此决定是否重投；accepted 不等于 ack。 */
+export type DeliveryReceipt = {
+    status: 'accepted';
+    inputIds: string[];
+    /**
+     * 运行时在投递过程中切换了会话（例如 Claude 的 resume 产生副本）。
+     * Router 必须把 Assignment 的 handle 换成新值，后续 status/stop 才能命中同一会话。
+     */
+    handle?: string;
+    sessionId?: string;
+} | {
+    status: 'queued';
+    inputIds: string[];
+    reason?: string;
+} | {
+    status: 'rejected';
+    inputIds: string[];
+    reason: string;
+    retryable?: boolean;
+    retryAfterMs?: number;
+};
+export interface DeliverOptions {
+    /** 第几次投递（从 1 开始）；同一 attempt 的并发调用必须幂等。 */
+    attempt?: number;
+    /** Router 显式重投：adapter 必须允许同一 input.id 再次进入。 */
+    redeliver?: boolean;
+}
+export type AgentPhase = 'starting' | 'running' | 'blocked' | 'exited' | 'lost' | 'unknown';
+export interface AgentStatus {
+    alive: boolean;
+    phase: AgentPhase;
+    acceptingInput: boolean;
+    /** 最后一次可观测活动时间（ISO）；用于 idle / zombie 判定。 */
+    lastActivityAt?: string;
+    exitCode?: number;
+    exitSignal?: string;
+    /** provider 细节；只进日志，不进判断。 */
+    detail?: Record<string, unknown>;
+}
+export interface AgentOutput {
+    status: 'running' | 'exited' | 'unknown';
+    lines: string[];
+    source?: string;
+}
+/**
+ * 被中断的一轮执行。
+ *
+ * 运行时重启后用来回答「上一轮做到哪、是不是被中途打断的」。
+ * 只有进程会随 Router 一起死的运行时（capabilities.agent.processExit=true）
+ * 才有这个概念；常驻 worker 不会因为 Router 重启而中断，不需要实现。
+ */
+export interface InterruptedTurn {
+    /** 运行时自己的轮次 id；用于去重，保证同一轮只提醒一次。 */
+    turnId: string;
+    /** 已执行到哪一步的简要描述；用来生成有意义的恢复提示。 */
+    summary?: string;
+    /** 中断发生时间（ISO），尽力而为。 */
+    at?: string;
+}
+/** 兼容旧命名。 */
+export type TerminalOutput = AgentOutput;
+/** Agent 会话记录里的一条活动（assistant 文本或工具调用）。 */
+export interface SessionEvent {
+    at: string;
+    kind: 'text' | 'tool';
+    text: string;
+    tool?: {
+        name: string;
+        target?: string;
+    };
+}
+/** 从 Agent 自己的会话记录里读出的最近活动。 */
+export interface SessionSnapshot {
+    at: string;
+    events: SessionEvent[];
+    sessionId?: string;
+    filePath?: string;
+}
+/** 人工接管会话时可直接粘贴到终端的恢复提示。 */
+export interface ResumeHint {
+    /** 完整 shell 命令，已包含 cd 到工作目录。 */
+    command: string;
+    /** 运行时自己的会话 ID；用于展示与排障。 */
+    sessionId?: string;
+    /** 不阻断复制，但需要提示用户的注意事项。 */
+    note?: string;
+}
+export interface RuntimeCapabilities {
+    agent: {
+        liveStatus: boolean;
+        processExit: boolean;
+        output: boolean;
+        activity: boolean;
+        structuredInput: boolean;
+        nudge: boolean;
+    };
+    workspace: {
+        cleanup: boolean;
+        prLink: boolean;
+        discovery: boolean;
+    };
+}
+export interface RepoDescriptor {
+    name: string;
+    path: string;
+    kind?: string;
+}
+export interface WorkspaceInfo {
+    workdir: string;
+    branch: string;
+    dirty?: boolean;
+    linkedPr?: {
+        number: number;
+        url: string;
+        state?: 'open' | 'merged' | 'closed';
+    };
+}
+export interface DiagnosticCheck {
+    name: string;
+    status: 'ok' | 'warn' | 'fail';
+    detail: string;
+    hint?: string;
+}
+/** 运行时错误码；所有 adapter 必须抛 WorkerRuntimeError。 */
+export type WorkerErrorCode = 'workspace:create-failed' | 'workspace:missing-repo' | 'workspace:missing-branch' | 'workspace:remove-failed' | 'agent:launch-failed' | 'agent:not-accepting-input' | 'agent:gone' | 'agent:timeout' | 'runtime:unavailable' | 'runtime:unknown';
+export declare class WorkerRuntimeError extends Error {
+    readonly code: WorkerErrorCode;
+    readonly retryable: boolean;
+    readonly reason: string;
+    readonly cause?: string;
+    readonly detail?: Record<string, unknown>;
+    constructor(code: WorkerErrorCode, reason: string, opts?: {
+        retryable?: boolean;
+        cause?: string;
+        detail?: Record<string, unknown>;
+    });
+}
+/** Worker 运行时端口：换运行时只加一个 adapter，内核与 Router 不改。 */
+export interface WorkerRuntime {
+    readonly id: string;
+    readonly capabilities: RuntimeCapabilities;
+    start(ctx: WorkerContext): Promise<StartResult>;
+    deliver(ref: WorkerRef, inputs: InboundMessage[], opts?: DeliverOptions): Promise<DeliveryReceipt>;
+    stop(ref: WorkerRef, reason: string): Promise<void>;
+    /** 可选：显式唤醒/探活；只有 capabilities.agent.nudge=true 时才实现。 */
+    nudge?(ref: WorkerRef): Promise<void>;
+    /** 可选：进程重启后把仍可恢复的会话接回来；接不回返回 false，不算丢失。 */
+    reattach?(ref: WorkerRef): Promise<boolean>;
+    /**
+     * 可选：查询上一轮是否被中途打断。
+     *
+     * 只有 worker 进程会随 Router 一起死的运行时（capabilities.agent.processExit=true）
+     * 才需要实现：这类运行时重启后「上一轮」确实可能停在半路。
+     * 返回 null 表示「没有被打断的轮次」或「判断不了」，不触发任何恢复动作。
+     */
+    interruptedTurn?(ref: WorkerRef): Promise<InterruptedTurn | null>;
+    /** 可选：结构化活性；返回 null 表示「无法判断」，不是「已丢失」。 */
+    status?(ref: WorkerRef): Promise<AgentStatus | null>;
+    /** 可选：输出尾部；没有则巡检跳过这一路。 */
+    output?(ref: WorkerRef, opts?: {
+        limit?: number;
+    }): Promise<AgentOutput | null>;
+    /** 可选：结构化活动；优先于 output。 */
+    activity?(query: ActivityQuery): Promise<SessionSnapshot | null>;
+    /** 可选：工作区查询/回收；不再使用运行时私有选择器。 */
+    inspectWorkspace?(ref: WorkspaceRef): Promise<WorkspaceInfo | null>;
+    removeWorkspace?(ref: WorkspaceRef): Promise<void>;
+    /** 可选：仓库发现（doctor / init）。 */
+    listRepos?(): Promise<RepoDescriptor[]>;
+    /** 可选：把本地仓库路径解析成 GitHub owner/repo，供 PR 跟踪。 */
+    repoSlug?(ref: WorkerRef): Promise<string | null>;
+    /** 可选：启动前自检。 */
+    doctor?(): Promise<DiagnosticCheck[]>;
+    /** 兼容保留：当前 Router 未调用。 */
+    registerContext?(ref: WorkerRef, items: ContextItem[]): Promise<void>;
+}

package/dist/port.js

@@ -0,0 +1,17 @@
+export class WorkerRuntimeError extends Error {
+    code;
+    retryable;
+    reason;
+    cause;
+    detail;
+    constructor(code, reason, opts = {}) {
+        super(reason);
+        this.name = 'WorkerRuntimeError';
+        this.code = code;
+        this.reason = reason;
+        this.retryable = opts.retryable ?? false;
+        this.cause = opts.cause;
+        this.detail = opts.detail;
+    }
+}
+//# sourceMappingURL=port.js.map

package/dist/port.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"port.js","sourceRoot":"","sources":["../../../../packages/runtime/src/port.ts"],"names":[],"mappings":"AA6PA,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAClC,IAAI,CAAiB;IACrB,SAAS,CAAS;IAClB,MAAM,CAAQ;IACL,KAAK,CAAS;IACvB,MAAM,CAA0B;IAEzC,YACE,IAAqB,EACrB,MAAc,EACd,OAAkF,EAAE;QAEpF,KAAK,CAAC,MAAM,CAAC,CAAA;QACb,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAA;QAChC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;QAChB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAA;QACpB,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,KAAK,CAAA;QACxC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAA;QACvB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAA;IAC3B,CAAC;CACF"}

package/dist/registry.d.ts

@@ -0,0 +1,13 @@
+import { type WorkerRuntime } from './port.js';
+/** 按 id 持有运行时；内核只通过它取运行时，不直接 new OrcaRuntime。 */
+export declare class RuntimeRegistry {
+    private readonly runtimes;
+    private readonly defaultId;
+    constructor(runtimes: Map<string, WorkerRuntime>, defaultId: string);
+    get(id: string): WorkerRuntime;
+    has(id: string): boolean;
+    ids(): string[];
+    default(): WorkerRuntime;
+}
+/** 用插件创建好的 adapter 组装注册表；插件发现与加载由 plugins/loader 负责。 */
+export declare function createRuntimes(runtimes: Iterable<WorkerRuntime>, defaultId: string): RuntimeRegistry;

package/dist/registry.js

@@ -0,0 +1,35 @@
+import { WorkerRuntimeError } from './port.js';
+import { normalizeRuntimeId } from './runtimes/catalog.js';
+/** 按 id 持有运行时；内核只通过它取运行时，不直接 new OrcaRuntime。 */
+export class RuntimeRegistry {
+    runtimes;
+    defaultId;
+    constructor(runtimes, defaultId) {
+        this.runtimes = runtimes;
+        // 默认值可能来自旧配置（claude-cli），先归一再校验。
+        this.defaultId = normalizeRuntimeId(defaultId);
+        if (!runtimes.has(this.defaultId)) {
+            throw new WorkerRuntimeError('runtime:unknown', `默认 runtime 未注册: ${this.defaultId}`);
+        }
+    }
+    get(id) {
+        const runtime = this.runtimes.get(normalizeRuntimeId(id));
+        if (!runtime)
+            throw new WorkerRuntimeError('runtime:unknown', `未知 runtime: ${id}`);
+        return runtime;
+    }
+    has(id) {
+        return this.runtimes.has(normalizeRuntimeId(id));
+    }
+    ids() {
+        return [...this.runtimes.keys()];
+    }
+    default() {
+        return this.get(this.defaultId);
+    }
+}
+/** 用插件创建好的 adapter 组装注册表；插件发现与加载由 plugins/loader 负责。 */
+export function createRuntimes(runtimes, defaultId) {
+    return new RuntimeRegistry(new Map([...runtimes].map(runtime => [runtime.id, runtime])), defaultId);
+}
+//# sourceMappingURL=registry.js.map

package/dist/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../../../packages/runtime/src/registry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAsB,MAAM,WAAW,CAAA;AAClE,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAA;AAC1D,iDAAiD;AACjD,MAAM,OAAO,eAAe;IAIP;IAHF,SAAS,CAAQ;IAElC,YACmB,QAAoC,EACrD,SAAiB;QADA,aAAQ,GAAR,QAAQ,CAA4B;QAGrD,iCAAiC;QACjC,IAAI,CAAC,SAAS,GAAG,kBAAkB,CAAC,SAAS,CAAC,CAAA;QAC9C,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;YAClC,MAAM,IAAI,kBAAkB,CAAC,iBAAiB,EAAE,mBAAmB,IAAI,CAAC,SAAS,EAAE,CAAC,CAAA;QACtF,CAAC;IACH,CAAC;IAED,GAAG,CAAC,EAAU;QACZ,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,kBAAkB,CAAC,EAAE,CAAC,CAAC,CAAA;QACzD,IAAI,CAAC,OAAO;YAAE,MAAM,IAAI,kBAAkB,CAAC,iBAAiB,EAAE,eAAe,EAAE,EAAE,CAAC,CAAA;QAClF,OAAO,OAAO,CAAA;IAChB,CAAC;IAED,GAAG,CAAC,EAAU;QACZ,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,kBAAkB,CAAC,EAAE,CAAC,CAAC,CAAA;IAClD,CAAC;IAED,GAAG;QACD,OAAO,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAA;IAClC,CAAC;IAED,OAAO;QACL,OAAO,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,CAAA;IACjC,CAAC;CACF;AAED,wDAAwD;AACxD,MAAM,UAAU,cAAc,CAAC,QAAiC,EAAE,SAAiB;IACjF,OAAO,IAAI,eAAe,CAAC,IAAI,GAAG,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,SAAS,CAAC,CAAA;AACrG,CAAC"}

package/dist/report-poller.d.ts

@@ -0,0 +1,58 @@
+import type { ReportState } from '@router-agent/core/model.js';
+export interface WorkerStateFile {
+    ticketId: string;
+    assignmentId: string;
+    turn: number;
+    state: ReportState;
+    summary: string;
+    humanAction?: string;
+    prNumber: number;
+    prUrl: string;
+    /** Worker 显式声明是否改了 UI；缺省时由 Router 按改动文件推断。 */
+    uiChange?: boolean;
+    reply?: string;
+    ackedInputs: string[];
+    updatedAt: string;
+}
+export interface WorkerMeta {
+    ticketId: string;
+    assignmentId: string;
+    handle: string;
+    workdir: string;
+    /** 运行时 id；ACP / Claude Code 会写入。 */
+    runtime?: string;
+    /** 底层 Agent 的真实会话 id；用于人工恢复。 */
+    sessionId?: string;
+    repo?: string;
+    [key: string]: unknown;
+}
+export interface PolledState {
+    state: WorkerStateFile;
+    meta: WorkerMeta | null;
+    mtimeMs: number;
+}
+export interface ReportPollerOptions {
+    workersDir: string;
+    onState: (state: WorkerStateFile, meta: WorkerMeta | null, path: string) => void;
+    onError?: (ticketId: string, error: Error) => void;
+}
+/** 轮询 ~/.router-agent/workers/<ticketId>/state.json，按文件内容增量上报。 */
+export declare class ReportPoller {
+    private workersDir;
+    private onState;
+    private onError?;
+    private seen;
+    constructor(opts: ReportPollerOptions);
+    /** 扫描一轮，返回新上报数量。 */
+    scan(): number;
+    /** 清空基线，让下一轮重新上报（Router 重启对账时用）。 */
+    reset(): void;
+}
+export declare function parseStateFile(content: string, expectedTicketId?: string): {
+    ticketId: string;
+    state: WorkerStateFile;
+};
+/** 读取 worker 的 meta.json；供报告轮询与恢复命令共用。 */
+export declare function readWorkerMeta(workersDir: string, ticketId: string): WorkerMeta | null;
+/** 追加一条审计事件到 events.log。 */
+export declare function appendEvent(path: string, event: Record<string, unknown>): void;

package/dist/report-poller.js

@@ -0,0 +1,130 @@
+import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { z } from 'zod';
+/** 旧版 state.json 的交付物字段，仅用于向后兼容，不再参与新协议。 */
+const LegacyDeliverableSchema = z.object({
+    kind: z.string().optional(),
+    content: z.string().default(''),
+    title: z.string().optional(),
+    url: z.string().default(''),
+}).nullable().optional();
+const StateSchema = z.object({
+    ticket_id: z.string().min(1),
+    assignment_id: z.string().default(''),
+    turn: z.coerce.number().int().min(0).default(0),
+    state: z.enum(['progress', 'ready', 'blocked', 'failed', 'dropped', 'waiting']),
+    summary: z.string().min(1),
+    human_action: z.string().nullable().optional(),
+    pr_number: z.coerce.number().int().min(0).default(0),
+    pr_url: z.string().default(''),
+    /** Worker 显式声明是否改了 UI；缺省时由 Router 按改动文件推断。 */
+    ui_change: z.boolean().optional(),
+    /** Worker 要发给发起人的完整回复（Markdown）。 */
+    reply: z.string().optional().default(''),
+    /** 旧版交付物字段，读取时拼进 reply。 */
+    deliverable: LegacyDeliverableSchema,
+    acked_inputs: z.array(z.string()).default([]),
+    updated_at: z.string().default(() => new Date().toISOString()),
+});
+/** 轮询 ~/.router-agent/workers/<ticketId>/state.json，按文件内容增量上报。 */
+export class ReportPoller {
+    workersDir;
+    onState;
+    onError;
+    seen = new Map();
+    constructor(opts) {
+        this.workersDir = opts.workersDir;
+        this.onState = opts.onState;
+        this.onError = opts.onError;
+    }
+    /** 扫描一轮，返回新上报数量。 */
+    scan() {
+        if (!existsSync(this.workersDir))
+            return 0;
+        let count = 0;
+        const entries = readdirSync(this.workersDir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            const ticketId = entry.name;
+            const statePath = join(this.workersDir, ticketId, 'state.json');
+            if (!existsSync(statePath))
+                continue;
+            try {
+                const content = readFileSync(statePath, 'utf8');
+                const fingerprint = `${statSync(statePath).mtimeMs}:${content}`;
+                if (this.seen.get(ticketId) === fingerprint)
+                    continue;
+                const { ticketId: parsedId, state } = parseStateFile(content, ticketId);
+                this.seen.set(ticketId, fingerprint);
+                const meta = readWorkerMeta(this.workersDir, ticketId);
+                this.onState({ ...state, ticketId: parsedId }, meta, statePath);
+                count += 1;
+            }
+            catch (error) {
+                this.onError?.(ticketId, error instanceof Error ? error : new Error(String(error)));
+            }
+        }
+        return count;
+    }
+    /** 清空基线，让下一轮重新上报（Router 重启对账时用）。 */
+    reset() {
+        this.seen.clear();
+    }
+}
+export function parseStateFile(content, expectedTicketId) {
+    let json;
+    try {
+        json = JSON.parse(content);
+    }
+    catch {
+        throw new Error('state:invalid-json');
+    }
+    const parsed = StateSchema.safeParse(json);
+    if (!parsed.success)
+        throw new Error(`state:invalid: ${parsed.error.issues.map(i => i.path.join('.')).join(',')}`);
+    if (expectedTicketId && parsed.data.ticket_id !== expectedTicketId) {
+        throw new Error(`state:ticket-mismatch: 目录 ${expectedTicketId} 收到 ${parsed.data.ticket_id}`);
+    }
+    const data = parsed.data;
+    const legacy = data.deliverable;
+    // 旧版 deliverable 升级成纯回复：正文 + 链接，不再保留 kind。
+    const reply = data.reply.trim() || [legacy?.content?.trim(), legacy?.url?.trim()].filter(Boolean).join('\n\n');
+    return {
+        ticketId: data.ticket_id,
+        state: {
+            ticketId: data.ticket_id,
+            assignmentId: data.assignment_id,
+            turn: data.turn,
+            state: data.state,
+            summary: data.summary,
+            ...(data.human_action ? { humanAction: data.human_action } : {}),
+            prNumber: data.pr_number,
+            prUrl: data.pr_url,
+            ...(data.ui_change !== undefined ? { uiChange: data.ui_change } : {}),
+            ...(reply ? { reply } : {}),
+            ackedInputs: data.acked_inputs,
+            updatedAt: data.updated_at,
+        },
+    };
+}
+/** 读取 worker 的 meta.json；供报告轮询与恢复命令共用。 */
+export function readWorkerMeta(workersDir, ticketId) {
+    const path = join(workersDir, ticketId, 'meta.json');
+    if (!existsSync(path))
+        return null;
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+/** 追加一条审计事件到 events.log。 */
+export function appendEvent(path, event) {
+    mkdirSync(join(path, '..'), { recursive: true });
+    if (!existsSync(path))
+        writeFileSync(path, '', 'utf8');
+    appendFileSync(path, `${JSON.stringify(event)}\n`, 'utf8');
+}
+//# sourceMappingURL=report-poller.js.map

package/dist/report-poller.js.map

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

package/dist/resume.d.ts

@@ -0,0 +1,52 @@
+/**
+ * 人工恢复命令的拼装与运行时映射。
+ *
+ * 恢复命令只依赖三件事：工作目录、底层 Agent 的真实 session id、该 Agent 的 CLI
+ * 语法。这里用一张静态表把这些知识集中起来，不要求每个运行时实现额外方法。
+ * 只生成 POSIX shell（sh/bash/zsh）可执行的一行命令；动态值全部单引号转义。
+ */
+import type { ResumeHint } from './port.js';
+/** 单个运行时的 CLI 恢复模板。 */
+export interface ResumeSpec {
+    /** 有真实 sessionId 时执行的命令。 */
+    command?: string;
+    /** 有真实 sessionId 时的参数模板，支持 {sessionId}。 */
+    args?: readonly string[];
+    /** 没有 sessionId、但有运行时 handle 时的备用命令；缺省复用 command。 */
+    handleCommand?: string;
+    /** 没有 sessionId、但有运行时 handle 时的备用模板，支持 {handle}。 */
+    handleArgs?: readonly string[];
+    /** handle 兜底命令是否需要在 workdir 里执行；默认 true。Orca 的终端切换与目录无关。 */
+    handleRequiresWorkdir?: boolean;
+    /** 有 sessionId 时附加的提示。 */
+    note?: string;
+    /** 走 handle 备用模板时附加的提示。 */
+    handleNote?: string;
+}
+/** 按运行时 id 取恢复模板；未知/未核实返回 null。 */
+export declare function resumeSpecOf(runtimeId: string, agentId?: string): ResumeSpec | null;
+export interface ResumeSource {
+    workdir?: string;
+    /** 底层 Agent 的真实会话 id；优先级最高。 */
+    sessionId?: string;
+    /** 运行时自己的短句柄；没有 sessionId 时用于 attach 类命令。 */
+    handle?: string;
+    /** 由外部决定用哪个 Agent 的运行时（如 Orca）需要它来选恢复命令。 */
+    agentId?: string;
+}
+/**
+ * 根据运行时与会话信息生成恢复命令。
+ *
+ * @param workdirExists 由调用方传入，保持本模块为纯函数；false 时追加工作区提示。
+ */
+export declare function buildResumeHint(runtimeId: string, source: ResumeSource, opts?: {
+    workdirExists?: boolean;
+}): ResumeHint | null;
+/** 单引号转义；内部单引号写成 '\''。 */
+export declare function shellQuote(value: string): string;
+/**
+ * 生成 `cd <workdir> && <command> <args...>`。
+ *
+ * `command` 只应来自上面的可信常量，不作为用户输入参与转义；workdir 与参数一律转义。
+ */
+export declare function resumeCommand(workdir: string, command: string, args?: readonly string[]): string;