@coralai/sps-cli 0.63.6 → 0.65.0

package/dist/runtime/contract/AgentBackend.d.ts

@@ -0,0 +1,199 @@
+/**
+ * @module contract/AgentBackend
+ * 核心适配接口 —— 消费者(上层编排)只对它编程,不认具体 SDK。
+ * 提炼自 sps-cli 现有 AgentBackend,补齐 resume/cancel/subscribe + 中立会话配置。
+ */
+import type { BackendKind, RunState, StopReason } from './lifecycle.js';
+import type { WorkerOutputEvent, WorkerOutputListener } from './events.js';
+import type { AgentProcessMcpServerV1, AgentProcessStartOptionsV1, AgentProviderRefV1, ConversationOwnerV1, SandboxPolicyRefV1 } from './processProtocol.js';
+export type ResumeFailureReason = 'session_lost' | 'not_found' | 'corrupt' | 'unsupported_version' | 'incompatible_agent_graph' | 'missing_tool' | 'workspace_unavailable' | 'provider_state_unavailable';
+/** Additive, provider-neutral process health snapshot for daemon inspection. */
+export interface AgentLivenessMetrics {
+    dispatchRequestedAt?: string;
+    spawnedAt?: string;
+    firstEventAt?: string;
+    completedAt?: string;
+    spawnLatencyMs?: number;
+    timeToFirstEventMs?: number;
+    runDurationMs?: number;
+    cancelRequestedAt?: string;
+    cancelLatencyMs?: number;
+    exitCode?: number | null;
+    exitSignal?: string | null;
+    replayGap?: number;
+    resumeOutcome?: 'fresh' | 'resumed' | 'not_found' | 'recovered';
+}
+/**
+ * Trusted supervisor configuration for a short-lived external worker.
+ * Executable, args, and environment policy are rebound from live config on
+ * every dispatch and must never be restored from worker-owned state.
+ */
+export interface ExternalProcessSpec {
+    executable: string;
+    args?: string[];
+    protocolVersion?: number;
+    envAllowlist?: string[];
+    cancelGraceMs?: number;
+    killGraceMs?: number;
+    sessionRoot: string;
+    provider: AgentProviderRefV1;
+    conversationOwner?: ConversationOwnerV1;
+    agentBundleVersion: string;
+    sandbox: SandboxPolicyRefV1;
+    mcp?: {
+        servers: AgentProcessMcpServerV1[];
+    };
+    options?: AgentProcessStartOptionsV1;
+    /** Optional deterministic ID source for tests/embedding. */
+    idFactory?: (kind: 'session' | 'run' | 'turn') => string;
+    /** stderr is diagnostic-only and never enters the protocol parser. */
+    onStderr?: (data: string) => void;
+}
+/** 权限策略:替代 ACP 的 fs handler,由本层强制(不靠 agent 自觉)。 */
+export interface PermissionPolicy {
+    /** 预批准的工具名(claude allowedTools;openai 工具白名单)。 */
+    allowTools?: string[];
+    /** 'default' | 'acceptEdits' | 'bypassPermissions' | 'plan'(claude permissionMode 的中立映射)。 */
+    mode?: 'default' | 'acceptEdits' | 'bypass' | 'plan';
+    /**
+     * 编程式逐工具裁决(claude canUseTool / openai tool guardrail 的归一)。
+     * 返回 allow/deny;用于 cwd 越界拦截等多租户边界。
+     */
+    decide?: (toolName: string, input: unknown) => Promise<{
+        allow: boolean;
+        reason?: string;
+    }>;
+}
+/** 外部 / 进程内 MCP 服务声明(两 SDK 都支持 stdio/http;claude 还支持 createSdkMcpServer 进程内实例)。 */
+export interface McpSpec {
+    name: string;
+    /** 'stdio' | 'http' | 'sse' | 'inproc'。inproc 仅 claude(SDK MCP server 实例)。 */
+    transport: 'stdio' | 'http' | 'sse' | 'inproc';
+    command?: string;
+    args?: string[];
+    url?: string;
+    /** transport='inproc' 时的工具实例(由消费者构造,本层透传)。 */
+    instance?: unknown;
+}
+/** 建会话配置(中立;映射到各 SDK 的 Options)。 */
+export interface SessionConfig {
+    backend: BackendKind;
+    /** 模型串(claude 别名/全 id;openai 模型名或 codexModel)。空=后端默认。 */
+    model?: string;
+    /** 工作目录(多租户隔离锚;两 SDK 都按 cwd spawn/解析)。 */
+    cwd: string;
+    /** 额外可访问目录白名单(claude additionalDirectories)。 */
+    additionalDirectories?: string[];
+    /** 配置来源(claude settingSources:让 .claude/settings.local.json 生效 → gameforge 零改动)。 */
+    settingSources?: Array<'user' | 'project' | 'local'>;
+    permission?: PermissionPolicy;
+    mcpServers?: McpSpec[];
+    /** durable resume:有则重载该会话完整 transcript(claude resume / openai 会话存储)。 */
+    resumeSessionId?: string;
+    /** 注入到该会话进程的 env(如第三方端点 ANTHROPIC_BASE_URL/AUTH_TOKEN)。 */
+    env?: Record<string, string>;
+    /** 细粒度:思考预算 / 轮上限 / 部分消息流 / 兜底模型 等(透传到对应 SDK Option)。 */
+    tuning?: {
+        maxThinkingTokens?: number;
+        maxTurns?: number;
+        includePartialMessages?: boolean;
+        fallbackModel?: string;
+        effort?: 'low' | 'medium' | 'high';
+    };
+    /**
+     * 后端专属扩展(charter「差异不抹平」:共性归一,专属能力按需暴露,仅对应后端读取)。
+     * claude 专属:ACP 给不了、直连 SDK 才有的能力。
+     */
+    claude?: {
+        /**
+         * 保活(流式会话)模式:用 `query({prompt: AsyncIterable})` 让**一个 claude 子进程跨多轮常驻**
+         * (等价 sps-cli ACP 的保活体验:免每轮重启、内存里续上下文,代价 ~进程常驻内存)。
+         * 默认 false = 一次性(每次 dispatch 起进程、turn 完即退、空闲零内存)。**仅 claude 支持保活。**
+         */
+        persistent?: boolean;
+        /** 进程内程序化 hooks(PreToolUse/PostToolUse/Stop/SessionStart/...);透传 SDK `options.hooks`。 */
+        hooks?: unknown;
+        /** 子代理定义(`options.agents`:name→{description,prompt,tools})。 */
+        agents?: Record<string, unknown>;
+        /** 自定义 claude 可执行路径(根治平台二进制解析问题,如 0.2.132 musl-on-glibc)。 */
+        pathToClaudeCodeExecutable?: string;
+        /** stderr 诊断回调。 */
+        stderr?: (data: string) => void;
+        /** 逃生舱:原样并入 query options 的额外字段(覆盖于归一字段之上)。 */
+        extraOptions?: Record<string, unknown>;
+    };
+    /**
+     * codex 专属扩展(@openai/codex-sdk)。MCP 走中立 `mcpServers`(本层映射进 codex config.mcp_servers);
+     * 这里放 codex 特有的:原始 config 覆盖(→ `codex exec --config k=v`)、skills 目录、审批策略。
+     */
+    codex?: {
+        /** 原样并入 codex `config`(会被 SDK flatten 成 `--config key=value`)。如 `{ mcp_servers: {...} }`。 */
+        config?: Record<string, unknown>;
+        /** CODEX_HOME:指向含 `skills/`、`config.toml` 的目录(控制 skills / MCP / 本地存储位置)。 */
+        codexHome?: string;
+        /** 审批策略覆盖('never'/'on-request'/'on-failure'/'untrusted')。 */
+        approvalPolicy?: string;
+    };
+    /**
+     * Opt-in external worker substrate. Currently used by the OpenAI daemon
+     * path; absence preserves the released in-process backend behavior.
+     */
+    externalProcess?: ExternalProcessSpec;
+}
+/**
+ * 单个 agent 会话的适配接口。一个实例 = 一个保活会话(可跨多轮复用)。
+ * 实现由各后端适配器提供(claude → claude-agent-sdk query/SDKSession;openai → @openai/agents run/Session)。
+ */
+export interface AgentBackend {
+    readonly kind: string;
+    /** 有外部 worker 时为当前 pid；纯进程内或空闲时为 null/undefined。 */
+    readonly pid?: number | null;
+    /** Optional live health metrics exposed to supervisors and dashboards. */
+    readonly liveness?: AgentLivenessMetrics;
+    /**
+     * 建立/保活底层会话(claude:spawn+初始化或 resume;openai:就绪)。返回底层 sessionId(持久用)。
+     *
+     * R1(类型化 resume 失败,sps-cli 评审必纳入):有 `resumeSessionId` 时,`resumed` 表明是否
+     * 真的重载了既有 transcript;若底层会话已不可用,以 `resumeFailed` **判别式**告知原因
+     * ('session_lost'=会话已被回收 / 'not_found'=查无此 id),消费者据此**确定性**决定是否重放历史,
+     * **不靠错误串匹配**(sps-cli durable resume 旧实现 `String(e).includes('SESSION_LOST')` 迁过来不可行)。
+     * 失败时 `sessionId` 回落为新建会话的 id(已 resume 失败 → 起新会话)。
+     * R3:openai 后端的 `sessionId` 是 RuntimeSession 存储文件 id(非 claude 子进程 session)。
+     */
+    ensure(): Promise<{
+        sessionId: string;
+        resumed: boolean;
+        resumeFailed?: ResumeFailureReason;
+    }>;
+    /** 派一轮 prompt(非阻塞);输出经 subscribe 流出,完成发 result 事件。 */
+    dispatch(prompt: string): Promise<void>;
+    /**
+     * Resume the same logical run after a durable waiting-for-input terminal.
+     * Backends without interruption support leave this method undefined.
+     */
+    resumeInteraction?(interactionId: string, answer: import('./processProtocol.js').JsonValue): Promise<void>;
+    /** Rehydrate a durable waiting run after the supervisor process restarts. */
+    restoreInterruptedRun?(state: {
+        sessionId: string;
+        runId: string;
+        turnId: string;
+        lastSequence: number;
+    }): void;
+    /** Restart a lost external worker from a worker-owned safe checkpoint. */
+    recoverRun?(state: {
+        sessionId: string;
+        runId: string;
+        turnId: string;
+        lastSequence: number;
+    }): Promise<void>;
+    /** 查询当前轮状态(完成判定/超时用)。 */
+    runState(): Promise<RunState>;
+    /** 中断进行中的一轮(claude Query.interrupt / openai 中断),会话保活以便续。 */
+    cancel(): Promise<void>;
+    /** 停止会话(收尾)。 */
+    stop(reason?: StopReason): Promise<void>;
+    /** 订阅统一输出事件;返回退订函数。 */
+    subscribe(listener: WorkerOutputListener): () => void;
+}
+export type { WorkerOutputEvent };
+//# sourceMappingURL=AgentBackend.d.ts.map

package/dist/runtime/contract/AgentBackend.d.ts.map

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

package/dist/runtime/contract/AgentBackend.js

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

package/dist/runtime/contract/AgentBackend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentBackend.js","sourceRoot":"","sources":["../../../src/runtime/contract/AgentBackend.ts"],"names":[],"mappings":""}

package/dist/runtime/contract/events.d.ts

@@ -0,0 +1,96 @@
+/**
+ * @module contract/events
+ * 统一输出事件流。两个 SDK 的消息/流式事件归一成同一组 WorkerOutputEvent,
+ * 让消费者(sps-cli chat/worker)只订阅一套事件,不认 SDK 差异。
+ *
+ * 映射来源:
+ *  - claude-agent-sdk:system(init)/assistant/user/result/stream_event
+ *  - openai-agents:RunItemStreamEvent / RunRawModelStreamEvent / RunResult(usage)
+ */
+import type { AgentProcessEventV1 } from './processProtocol.js';
+import type { RunState } from './lifecycle.js';
+/** token / 成本用量(turn_complete 携带)。两 SDK 都给 usage;claude 还给 total_cost_usd。 */
+export interface Usage {
+    inputTokens?: number;
+    outputTokens?: number;
+    /** 思考/推理 token(claude maxThinkingTokens / openai reasoning)。 */
+    reasoningTokens?: number;
+    /** 仅 claude result 提供;openai 需自行按模型价估。 */
+    costUsd?: number;
+    /** 按模型名分账(claude modelUsage)。 */
+    byModel?: Record<string, {
+        inputTokens?: number;
+        outputTokens?: number;
+    }>;
+}
+export type WorkerOutputEvent = 
+/** 会话建立,拿到底层 sessionId(claude:system.init.session_id;openai:会话存储 id)。durable resume 的锚。 */
+{
+    kind: 'session';
+    sessionId: string;
+}
+/** 助手文本增量。 */
+ | {
+    kind: 'text';
+    text: string;
+}
+/** 思考/推理增量(可选,claude includePartialMessages / openai ReasoningItem)。 */
+ | {
+    kind: 'thinking';
+    text: string;
+}
+/** 工具调用开始。 */
+ | {
+    kind: 'tool_use';
+    id: string;
+    title: string;
+    toolName: string;
+    input?: unknown;
+}
+/** 工具调用状态/结果更新。 */
+ | {
+    kind: 'tool_update';
+    id: string;
+    status: 'running' | 'completed' | 'failed';
+}
+/**
+ * 一轮结束(完成判定的主信号)。
+ * R4(sps-cli 评审):`stopReason` 含 `'cancelled'`,让 chat 能把"用户中断"与"失败"区分开。
+ * 已知值列出但保持开放(`& {}` 容纳模型原生 stop reason),不丢 SDK 原值。
+ */
+ | {
+    kind: 'result';
+    status: 'completed' | 'failed';
+    text?: string;
+    usage?: Usage;
+    stopReason?: 'end_turn' | 'max_tokens' | 'stop_sequence' | 'tool_use' | 'cancelled' | 'error' | (string & {});
+}
+/** 运行期错误。 */
+ | {
+    kind: 'error';
+    message: string;
+    recoverable?: boolean;
+}
+/** 后端主动上报的 run 生命周期，供异步进程监管同步服务记录。 */
+ | {
+    kind: 'run_state';
+    state: RunState;
+    runId?: string;
+}
+/** 外部 worker 的完整 versioned 事件;薄事件仍并行提供给既有消费者。 */
+ | {
+    kind: 'process';
+    event: AgentProcessEventV1;
+}
+/**
+ * 无损逃生舱:未被归一映射的原生 SDK 消息/事件原样透出(backend 标明来源)。
+ * 保证"对照官方文档全部接入"—— SDK 出新消息类型时消费者仍拿得到,无需改 agent-runtime。
+ */
+ | {
+    kind: 'raw';
+    backend: string;
+    type?: string;
+    message: unknown;
+};
+export type WorkerOutputListener = (ev: WorkerOutputEvent) => void;
+//# sourceMappingURL=events.d.ts.map

package/dist/runtime/contract/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../../src/runtime/contract/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAChE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE/C,8EAA8E;AAC9E,MAAM,WAAW,KAAK;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gEAAgE;IAChE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,0CAA0C;IAC1C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iCAAiC;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC3E;AAED,MAAM,MAAM,iBAAiB;AAC3B,2FAA2F;AACzF;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE;AACxC,cAAc;GACZ;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE;AAChC,wEAAwE;GACtE;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE;AACpC,cAAc;GACZ;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE;AACpF,mBAAmB;GACjB;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,SAAS,GAAG,WAAW,GAAG,QAAQ,CAAA;CAAE;AACjF;;;;GAIG;GACD;IACE,IAAI,EAAE,QAAQ,CAAC;IACf,MAAM,EAAE,WAAW,GAAG,QAAQ,CAAC;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,UAAU,CAAC,EAAE,UAAU,GAAG,YAAY,GAAG,eAAe,GAAG,UAAU,GAAG,WAAW,GAAG,OAAO,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;CAC/G;AACH,aAAa;GACX;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,OAAO,CAAA;CAAE;AAC3D,sCAAsC;GACpC;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,KAAK,EAAE,QAAQ,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE;AACxD,iDAAiD;GAC/C;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,mBAAmB,CAAA;CAAE;AACjD;;;GAGG;GACD;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC;AAEtE,MAAM,MAAM,oBAAoB,GAAG,CAAC,EAAE,EAAE,iBAAiB,KAAK,IAAI,CAAC"}

package/dist/runtime/contract/events.js

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

package/dist/runtime/contract/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../../src/runtime/contract/events.ts"],"names":[],"mappings":""}

package/dist/runtime/contract/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @module contract
+ * runtime 的公开契约(契约即代码)。消费者只 import 这里。
+ * 实现(适配器 + 服务 + 版本管理)待 spec 评审后再铺;当前为契约先行阶段。
+ */
+export type { BackendKind, SessionState, RunState, StopReason } from './lifecycle.js';
+export type { Usage, WorkerOutputEvent, WorkerOutputListener } from './events.js';
+export type { AgentBackend, AgentLivenessMetrics, ExternalProcessSpec, SessionConfig, PermissionPolicy, McpSpec, ResumeFailureReason, } from './AgentBackend.js';
+export type { AgentService, SessionRecord, CapacityPolicy, } from './service.js';
+export type { RuntimePackage, InstalledEntry, InstalledManifest, CompatMatrix, VersionManager, } from './versioning.js';
+export { AGENT_PROCESS_PROTOCOL_VERSION, AgentProcessCommandDecoder, AgentProcessCommandStreamValidator, AgentProcessEventDecoder, AgentProcessEventStreamValidator, AgentProcessProtocolError, isTerminalAgentProcessEventType, parseAgentProcessCommandV1, parseAgentProcessEventV1, } from './processProtocol.js';
+export type { AgentProcessBackendMetadataV1, AgentProcessCancelCommandV1, AgentProcessCommandV1, AgentProcessErrorCodeV1, AgentProcessErrorV1, AgentProcessEventPayloadsV1, AgentProcessEventTypeV1, AgentProcessEventV1, AgentProcessMcpServerV1, AgentProcessProtocolErrorCode, AgentProcessStartCommandV1, AgentProcessStartOptionsV1, AgentProcessTerminalEventTypeV1, AgentProcessUsageV1, AgentProviderRefV1, ConversationOwnerV1, JsonObject, JsonPrimitive, JsonValue, SandboxPolicyRefV1, } from './processProtocol.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/runtime/contract/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/runtime/contract/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACtF,YAAY,EAAE,KAAK,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAClF,YAAY,EACV,YAAY,EACZ,oBAAoB,EACpB,mBAAmB,EACnB,aAAa,EACb,gBAAgB,EAChB,OAAO,EACP,mBAAmB,GACpB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,YAAY,EACZ,aAAa,EACb,cAAc,GACf,MAAM,cAAc,CAAC;AACtB,YAAY,EACV,cAAc,EACd,cAAc,EACd,iBAAiB,EACjB,YAAY,EACZ,cAAc,GACf,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,8BAA8B,EAC9B,0BAA0B,EAC1B,kCAAkC,EAClC,wBAAwB,EACxB,gCAAgC,EAChC,yBAAyB,EACzB,+BAA+B,EAC/B,0BAA0B,EAC1B,wBAAwB,GACzB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,6BAA6B,EAC7B,2BAA2B,EAC3B,qBAAqB,EACrB,uBAAuB,EACvB,mBAAmB,EACnB,2BAA2B,EAC3B,uBAAuB,EACvB,mBAAmB,EACnB,uBAAuB,EACvB,6BAA6B,EAC7B,0BAA0B,EAC1B,0BAA0B,EAC1B,+BAA+B,EAC/B,mBAAmB,EACnB,kBAAkB,EAClB,mBAAmB,EACnB,UAAU,EACV,aAAa,EACb,SAAS,EACT,kBAAkB,GACnB,MAAM,sBAAsB,CAAC"}

package/dist/runtime/contract/index.js

@@ -0,0 +1,2 @@
+export { AGENT_PROCESS_PROTOCOL_VERSION, AgentProcessCommandDecoder, AgentProcessCommandStreamValidator, AgentProcessEventDecoder, AgentProcessEventStreamValidator, AgentProcessProtocolError, isTerminalAgentProcessEventType, parseAgentProcessCommandV1, parseAgentProcessEventV1, } from './processProtocol.js';
+//# sourceMappingURL=index.js.map

package/dist/runtime/contract/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/runtime/contract/index.ts"],"names":[],"mappings":"AA4BA,OAAO,EACL,8BAA8B,EAC9B,0BAA0B,EAC1B,kCAAkC,EAClC,wBAAwB,EACxB,gCAAgC,EAChC,yBAAyB,EACzB,+BAA+B,EAC/B,0BAA0B,EAC1B,wBAAwB,GACzB,MAAM,sBAAsB,CAAC"}

package/dist/runtime/contract/lifecycle.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @module contract/lifecycle
+ * 会话生命周期状态机。两个 SDK 归一后的中立状态(不暴露 claude/openai 细节)。
+ */
+/**
+ * 后端家族。都"直连官方 SDK":
+ * - claude  → @anthropic-ai/claude-agent-sdk(spawn claude 二进制)
+ * - openai  → @openai/agents(纯 HTTP 聊天智能体;codexModel 走订阅)
+ * - codex   → @openai/codex-sdk(本地编码智能体:spawn codex app-server + 订阅 + sandbox + 本地存储)
+ */
+export type BackendKind = 'claude' | 'openai' | 'codex';
+/**
+ * 会话(session)的生命周期状态。
+ * - launching: 正在建立(claude:spawn 子进程并初始化;openai:就绪即用)
+ * - idle:      已就绪,空闲,可接收 dispatch
+ * - running:   正在执行一轮(turn)
+ * - paused:    被中断(interrupt)等待人审/输入
+ * - stopping:  正在收尾
+ * - dead:      进程/会话已终止(可能可经 resume 重建)
+ */
+export type SessionState = 'launching' | 'idle' | 'running' | 'paused' | 'stopping' | 'dead';
+/** 单轮(turn)运行态,供消费者做完成判定/超时。 */
+export type RunState = 'idle' | 'starting' | 'running' | 'awaiting_input' | 'completed' | 'failed' | 'cancelled' | 'lost';
+/** 终止原因。 */
+export type StopReason = 'completed' | 'failed' | 'cancelled' | 'timeout' | 'killed';
+//# sourceMappingURL=lifecycle.d.ts.map

package/dist/runtime/contract/lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../../../src/runtime/contract/lifecycle.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,CAAC;AAExD;;;;;;;;GAQG;AACH,MAAM,MAAM,YAAY,GAAG,WAAW,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,UAAU,GAAG,MAAM,CAAC;AAE7F,gCAAgC;AAChC,MAAM,MAAM,QAAQ,GAChB,MAAM,GACN,UAAU,GACV,SAAS,GACT,gBAAgB,GAChB,WAAW,GACX,QAAQ,GACR,WAAW,GACX,MAAM,CAAC;AAEX,YAAY;AACZ,MAAM,MAAM,UAAU,GAAG,WAAW,GAAG,QAAQ,GAAG,WAAW,GAAG,SAAS,GAAG,QAAQ,CAAC"}

package/dist/runtime/contract/lifecycle.js

@@ -0,0 +1,6 @@
+/**
+ * @module contract/lifecycle
+ * 会话生命周期状态机。两个 SDK 归一后的中立状态(不暴露 claude/openai 细节)。
+ */
+export {};
+//# sourceMappingURL=lifecycle.js.map

package/dist/runtime/contract/lifecycle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.js","sourceRoot":"","sources":["../../../src/runtime/contract/lifecycle.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/runtime/contract/processProtocol.d.ts

@@ -0,0 +1,263 @@
+/**
+ * Versioned NDJSON contract between an agent supervisor and a short-lived
+ * external agent worker. This protocol is independent from the agentd socket
+ * protocol: stdin carries commands, stdout carries events, and stderr is
+ * reserved for diagnostics.
+ */
+export declare const AGENT_PROCESS_PROTOCOL_VERSION: 1;
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export type JsonObject = {
+    [key: string]: JsonValue;
+};
+export type ConversationOwnerV1 = {
+    kind: 'local_session';
+} | {
+    kind: 'openai_conversation';
+    conversationId?: string;
+} | {
+    kind: 'previous_response';
+    previousResponseId?: string;
+};
+export interface AgentProviderRefV1 {
+    providerId: string;
+    model: string;
+    transport: 'responses' | 'chat_completions' | 'codex';
+    baseUrl?: string;
+}
+export interface SandboxPolicyRefV1 {
+    profile: string;
+    provider: 'none' | 'unix_local' | 'docker' | 'hosted';
+    workspaceId?: string;
+}
+export interface AgentProcessMcpServerV1 {
+    name: string;
+    transport: 'stdio' | 'sse' | 'streamable_http';
+    commandRef?: string;
+    url?: string;
+    authRef?: string;
+    allowedTools?: string[];
+}
+export interface AgentProcessStartOptionsV1 {
+    maxTurns?: number;
+    trace?: boolean;
+    outputTypeRef?: string;
+    interactionAnswers?: Record<string, JsonValue>;
+    resumeFromCheckpoint?: boolean;
+    replayAfterSequence?: number;
+}
+export interface AgentProcessStartCommandV1 {
+    command: 'start';
+    protocolVersion: typeof AGENT_PROCESS_PROTOCOL_VERSION;
+    sessionId: string;
+    runId: string;
+    turnId: string;
+    prompt: string;
+    cwd: string;
+    provider: AgentProviderRefV1;
+    conversationOwner: ConversationOwnerV1;
+    sessionRoot: string;
+    agentBundleVersion: string;
+    sandbox: SandboxPolicyRefV1;
+    mcp: {
+        servers: AgentProcessMcpServerV1[];
+    };
+    options: AgentProcessStartOptionsV1;
+}
+export interface AgentProcessCancelCommandV1 {
+    command: 'cancel';
+    protocolVersion: typeof AGENT_PROCESS_PROTOCOL_VERSION;
+    sessionId: string;
+    runId: string;
+    reason?: string;
+}
+export type AgentProcessCommandV1 = AgentProcessStartCommandV1 | AgentProcessCancelCommandV1;
+export interface AgentProcessUsageV1 {
+    inputTokens?: number;
+    outputTokens?: number;
+    reasoningTokens?: number;
+    cachedInputTokens?: number;
+    totalTokens?: number;
+    costUsd?: number;
+}
+export type AgentProcessErrorCodeV1 = 'not_found' | 'corrupt' | 'unsupported_version' | 'incompatible_agent_graph' | 'missing_tool' | 'workspace_unavailable' | 'provider_state_unavailable' | 'operator_reconciliation' | 'provider_error' | 'tool_error' | 'guardrail_error' | 'protocol_error' | 'persistence_error' | 'internal_error';
+export interface AgentProcessErrorV1 {
+    code: AgentProcessErrorCodeV1;
+    message: string;
+    recoverable: boolean;
+    details?: JsonObject;
+}
+export interface AgentProcessEventPayloadsV1 {
+    'session.started': {
+        resumed: boolean;
+        conversationOwner: ConversationOwnerV1;
+    };
+    capabilities: {
+        tools: string[];
+        mcpServers: string[];
+        features: string[];
+        sandboxProvider: SandboxPolicyRefV1['provider'];
+    };
+    'assistant.delta': {
+        delta: string;
+    };
+    'assistant.message': {
+        text: string;
+        itemId?: string;
+    };
+    'tool.call': {
+        toolCallId: string;
+        toolName: string;
+        input: JsonValue;
+        providerCallId?: string;
+        itemId?: string;
+    };
+    'tool.progress': {
+        toolCallId: string;
+        status: 'running' | 'completed' | 'failed';
+        detail?: string;
+    };
+    'tool.result': {
+        toolCallId: string;
+        status: 'completed' | 'failed';
+        output: JsonValue;
+        error?: AgentProcessErrorV1;
+    };
+    'agent.changed': {
+        agentName: string;
+        previousAgentName?: string;
+    };
+    'interaction.required': {
+        interactionId: string;
+        kind: 'approval' | 'choices' | 'form' | 'operator_reconciliation';
+        title: string;
+        schema: JsonValue;
+        toolCallId?: string;
+        revision?: number;
+    };
+    'context.compacted': {
+        strategy: string;
+        beforeItems?: number;
+        afterItems?: number;
+    };
+    'usage.updated': {
+        usage: AgentProcessUsageV1;
+        final: boolean;
+    };
+    'system.warning': {
+        code: string;
+        message: string;
+        recoverable: boolean;
+    };
+    'run.waiting_for_input': {
+        interactionId: string;
+        checkpointRevision: number;
+    };
+    'run.completed': {
+        output?: JsonValue;
+        usage?: AgentProcessUsageV1;
+    };
+    'run.failed': {
+        error: AgentProcessErrorV1;
+        usage?: AgentProcessUsageV1;
+    };
+    'run.cancelled': {
+        reason: string;
+        checkpointRevision?: number;
+        usage?: AgentProcessUsageV1;
+    };
+}
+export type AgentProcessEventTypeV1 = keyof AgentProcessEventPayloadsV1;
+export type AgentProcessTerminalEventTypeV1 = 'run.waiting_for_input' | 'run.completed' | 'run.failed' | 'run.cancelled';
+export interface AgentProcessBackendMetadataV1 {
+    name: 'openai' | 'claude';
+    provider: string;
+    model?: string;
+    requestId?: string;
+    responseId?: string;
+    rawType?: string;
+    metadata?: JsonObject;
+}
+type AgentProcessEventVariantV1<T extends AgentProcessEventTypeV1> = {
+    protocolVersion: typeof AGENT_PROCESS_PROTOCOL_VERSION;
+    eventId: string;
+    sessionId: string;
+    runId: string;
+    turnId: string;
+    sequence: number;
+    timestamp: string;
+    type: T;
+    payload: AgentProcessEventPayloadsV1[T];
+    backend: AgentProcessBackendMetadataV1;
+};
+export type AgentProcessEventV1 = {
+    [T in AgentProcessEventTypeV1]: AgentProcessEventVariantV1<T>;
+}[AgentProcessEventTypeV1];
+export type AgentProcessProtocolErrorCode = 'invalid_json' | 'invalid_shape' | 'unsupported_version' | 'unexpected_command' | 'identity_mismatch' | 'out_of_order' | 'duplicate_event_id' | 'after_terminal' | 'stdout_pollution' | 'incomplete_frame';
+export declare class AgentProcessProtocolError extends Error {
+    readonly code: AgentProcessProtocolErrorCode;
+    readonly line?: string | undefined;
+    constructor(code: AgentProcessProtocolErrorCode, message: string, line?: string | undefined);
+}
+export declare function isTerminalAgentProcessEventType(type: AgentProcessEventTypeV1): type is AgentProcessTerminalEventTypeV1;
+export declare function parseAgentProcessCommandV1(value: unknown): AgentProcessCommandV1;
+export declare function parseAgentProcessEventV1(value: unknown): AgentProcessEventV1;
+/**
+ * Stateful validation for a single run. It rejects identity changes,
+ * duplicate IDs, non-contiguous sequence numbers, and output after terminal.
+ */
+export declare class AgentProcessEventStreamValidator {
+    private readonly expected?;
+    private readonly options;
+    private readonly eventIds;
+    private nextSequence;
+    private terminal;
+    constructor(expected?: {
+        sessionId?: string;
+        runId?: string;
+        turnId?: string;
+    } | undefined, options?: {
+        initialSequence?: number;
+        allowResumeAfterWaiting?: boolean;
+    });
+    accept(value: unknown): AgentProcessEventV1;
+    get lastSequence(): number;
+    get hasTerminal(): boolean;
+}
+/**
+ * Stateful validation for worker stdin. Exactly one start command must be the
+ * first frame; subsequent frames may only cancel that same run.
+ */
+export declare class AgentProcessCommandStreamValidator {
+    private activeStart;
+    accept(value: unknown): AgentProcessCommandV1;
+    get startCommand(): AgentProcessStartCommandV1 | null;
+}
+/**
+ * Incremental UTF-8 NDJSON decoder. It is safe for arbitrarily split or
+ * coalesced chunks and validates every non-empty stdout line.
+ */
+export declare class AgentProcessEventDecoder {
+    private readonly validator;
+    private readonly decoder;
+    private buffer;
+    constructor(validator?: AgentProcessEventStreamValidator);
+    push(chunk: string | Uint8Array): AgentProcessEventV1[];
+    finish(): AgentProcessEventV1[];
+    private drain;
+    private parseLine;
+}
+/** Incremental NDJSON decoder for worker stdin commands. */
+export declare class AgentProcessCommandDecoder {
+    private readonly decoder;
+    private readonly validator;
+    private buffer;
+    push(chunk: string | Uint8Array): AgentProcessCommandV1[];
+    finish(): AgentProcessCommandV1[];
+    private drain;
+    private parseLine;
+}
+export {};
+//# sourceMappingURL=processProtocol.d.ts.map