openworkgraph 0.2.12

package/dist/backend/diagnostics.js

@@ -0,0 +1,80 @@
+import { BackendError } from './types.js';
+import { MINIMUM_CODEX_VERSION } from './capabilities.js';
+const stages = { initialize: '连接握手', 'model/list': '读取模型列表', 'thread/start': '启动任务会话', 'turn/start': '启动任务' };
+/** Explain observed failures without forwarding stderr, backend messages, accounts or paths. */
+export function describeCodexFailure(error, rpc, fallbackStage = 'initialize') {
+    const diagnostic = error instanceof BackendError ? error.diagnostic : undefined;
+    const method = diagnostic?.method;
+    const stage = method && Object.hasOwn(stages, method) ? method : fallbackStage;
+    const details = { source: 'codex', stage };
+    let reason = diagnostic?.reason;
+    let explanation;
+    let retryable = false;
+    const failure = rpc?.failure;
+    if (reason === 'unsupported_version') {
+        explanation = `Codex CLI ${diagnostic?.version ?? ''} 不支持任务执行所需协议，请升级到 ${MINIMUM_CODEX_VERSION} 或更高稳定版本。`;
+        details.minimumVersion = MINIMUM_CODEX_VERSION;
+        if (diagnostic?.version)
+            details.version = diagnostic.version;
+    }
+    else if (reason === 'invalid_handshake')
+        explanation = 'Codex 返回的连接握手数据无效，请检查 CLI 版本兼容性。';
+    else if (reason === 'invalid_catalog')
+        explanation = 'Codex 返回的模型目录、推理强度或分页数据格式无效，请检查 CLI 版本兼容性。';
+    else if (error instanceof BackendError && error.code === 'MODEL_UNAVAILABLE') {
+        reason = 'model_unavailable';
+        explanation = '所选模型或推理强度在当前 Codex 目录中不可用，请重新选择。';
+    }
+    else if (error instanceof BackendError && error.code === 'TIMEOUT') {
+        reason = 'rpc_timeout';
+        retryable = true;
+        explanation = `Codex 在 ${diagnostic?.timeoutMs ?? 15000} 毫秒内未响应。`;
+        if (diagnostic?.timeoutMs !== undefined)
+            details.timeoutMs = diagnostic.timeoutMs;
+    }
+    else if (failure?.kind === 'spawn_error') {
+        reason = failure.spawnCode === 'ENOENT' ? 'executable_not_found' : ['EACCES', 'EPERM'].includes(failure.spawnCode ?? '') ? 'execution_denied' : 'spawn_error';
+        explanation = reason === 'executable_not_found' ? '找不到 Codex 可执行程序，请在工作空间设备上安装 Codex CLI，并确认启动工作空间的进程能找到该命令。'
+            : reason === 'execution_denied' ? '操作系统拒绝执行 Codex，请检查工作空间账户的执行权限。'
+                : 'Codex 进程无法启动，请检查可执行程序及工作空间目录是否可用。';
+        if (failure.spawnCode)
+            details.spawnCode = failure.spawnCode;
+    }
+    else if (failure?.kind === 'process_exit') {
+        reason = 'process_exit';
+        retryable = true;
+        explanation = 'Codex 进程在请求完成前退出' + (failure.exitCode != null ? `，退出码 ${failure.exitCode}` : failure.exitSignal ? `，信号 ${failure.exitSignal}` : '') + '。';
+        if (failure.exitCode !== undefined)
+            details.exitCode = failure.exitCode;
+        if (failure.exitSignal !== undefined)
+            details.exitSignal = failure.exitSignal;
+    }
+    else if (failure?.kind === 'invalid_frame' || failure?.kind === 'frame_too_large') {
+        reason = failure.kind;
+        explanation = reason === 'invalid_frame' ? 'Codex 输出了无效的 JSON-RPC 消息。' : 'Codex 输出消息超过工作空间支持的大小限制。';
+    }
+    else if (diagnostic?.rpcCode !== undefined) {
+        const code = diagnostic.rpcCode;
+        details.rpcCode = code;
+        reason = code === -32601 ? 'unsupported_method' : code === -32602 ? 'invalid_arguments' : 'request_rejected';
+        explanation = code === -32601 ? `Codex 不支持此协议请求（${code}），请检查 CLI 版本兼容性。`
+            : code === -32602 ? `Codex 拒绝了请求参数（${code}），请检查 CLI 版本兼容性。`
+                : `Codex 拒绝了请求，协议错误码 ${code}。`;
+    }
+    else if (error instanceof BackendError && error.code === 'PROTOCOL') {
+        reason = 'invalid_response';
+        explanation = 'Codex 返回的协议响应无效。';
+    }
+    else if (failure?.kind === 'stdin_error' || failure?.kind === 'host_close' || error instanceof BackendError && error.code === 'UNAVAILABLE') {
+        reason = failure?.kind ?? 'disconnected';
+        retryable = true;
+        explanation = 'Codex 连接在请求完成前关闭。';
+    }
+    else {
+        reason = 'unknown_error';
+        explanation = '发生未分类的连接错误，请检查工作空间设备上的 Codex 状态。';
+    }
+    details.reason = reason;
+    return { message: `Codex ${stages[stage]}失败：${explanation}`, details, retryable };
+}
+//# sourceMappingURL=diagnostics.js.map

package/dist/backend/index.d.ts

@@ -0,0 +1,6 @@
+export * from './types.js';
+export * from './models.js';
+export * from './capabilities.js';
+export * from './adapter.js';
+export { readRunOutput, validateRunPaths } from './paths.js';
+export { StdioRpc } from './stdio.js';

package/dist/backend/index.js

@@ -0,0 +1,7 @@
+export * from './types.js';
+export * from './models.js';
+export * from './capabilities.js';
+export * from './adapter.js';
+export { readRunOutput, validateRunPaths } from './paths.js';
+export { StdioRpc } from './stdio.js';
+//# sourceMappingURL=index.js.map

package/dist/backend/models.d.ts

@@ -0,0 +1,15 @@
+import type { DatabaseSync } from 'node:sqlite';
+import type { ModelDefaults, ModelOption, ModelSelection } from "../vendor/protocol/index.js";
+export interface BackendModel extends ModelOption {
+    defaultReasoningEffort: string | null;
+}
+export declare function freezeModelSelection(selection: ModelSelection | null, available: readonly BackendModel[]): Readonly<ModelSelection>;
+/** Synchronous CAS only. Resolve/probe catalog before entering a scheduler transaction. */
+export declare class ModelDefaultsStore {
+    private readonly db;
+    constructor(db: DatabaseSync);
+    private read;
+    get(available?: readonly BackendModel[]): ModelDefaults;
+    set(selection: ModelSelection, expectedRevision: number, available: readonly BackendModel[]): ModelDefaults;
+    freeze(override: ModelSelection | undefined, available: readonly BackendModel[]): Readonly<ModelSelection>;
+}

package/dist/backend/models.js

@@ -0,0 +1,43 @@
+import { BackendError } from './types.js';
+export function freezeModelSelection(selection, available) {
+    const model = selection && available.find(option => option.id === selection.model);
+    if (!model)
+        throw new BackendError('MODEL_UNAVAILABLE', 'Select an available model explicitly; automatic fallback is disabled');
+    const effort = selection.reasoningEffort ?? model.defaultReasoningEffort;
+    if (effort !== null && !model.reasoningEfforts.includes(effort))
+        throw new BackendError('MODEL_UNAVAILABLE', 'Selected reasoning effort is unavailable');
+    return Object.freeze({ model: model.id, reasoningEffort: effort });
+}
+/** Synchronous CAS only. Resolve/probe catalog before entering a scheduler transaction. */
+export class ModelDefaultsStore {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    read() {
+        const row = this.db.prepare("SELECT value FROM settings WHERE key='modelDefaults'").get();
+        if (!row || typeof row['value'] !== 'string')
+            throw new BackendError('UNAVAILABLE', 'Missing modelDefaults setting');
+        const raw = row['value'];
+        const value = JSON.parse(raw);
+        if (value === null)
+            return { raw, revision: 0, selection: null };
+        if (!Number.isSafeInteger(value.revision) || value.revision < 0 || (value.selection !== null && (typeof value.selection?.model !== 'string' || !(value.selection.reasoningEffort === null || typeof value.selection.reasoningEffort === 'string'))))
+            throw new BackendError('PROTOCOL', 'Invalid persisted model defaults');
+        return { raw, revision: value.revision, selection: value.selection };
+    }
+    get(available = []) { const { revision, selection } = this.read(); return { revision, selection, available: available.map(({ id, reasoningEfforts, defaultReasoningEffort }) => ({ id, reasoningEfforts: [...reasoningEfforts], defaultReasoningEffort })) }; }
+    set(selection, expectedRevision, available) {
+        const frozen = freezeModelSelection(selection, available);
+        const current = this.read();
+        if (!Number.isSafeInteger(expectedRevision) || current.revision !== expectedRevision || expectedRevision >= Number.MAX_SAFE_INTEGER)
+            throw new BackendError('CONFLICT', 'Model defaults revision changed');
+        const next = { revision: expectedRevision + 1, selection: frozen };
+        const result = this.db.prepare("UPDATE settings SET value=? WHERE key='modelDefaults' AND value=?").run(JSON.stringify(next), current.raw);
+        if (result.changes !== 1)
+            throw new BackendError('CONFLICT', 'Model defaults revision changed');
+        return { ...next, available: available.map(({ id, reasoningEfforts, defaultReasoningEffort }) => ({ id, reasoningEfforts: [...reasoningEfforts], defaultReasoningEffort })) };
+    }
+    freeze(override, available) { return freezeModelSelection(override ?? this.read().selection, available); }
+}
+//# sourceMappingURL=models.js.map

package/dist/backend/paths.d.ts

@@ -0,0 +1,6 @@
+import { type BackendRunContext } from './types.js';
+export declare function within(root: string, path: string): boolean;
+/** Runs outside DB transactions. No staging/rollback/Git operations here. */
+export declare function validateRunPaths(context: BackendRunContext): Promise<void>;
+/** Artifact paths remain untrusted even when a turn reports success. No absolute/escaping/symlink paths. */
+export declare function readRunOutput(outputRoot: string, name: string, maxBytes?: number): Promise<Buffer>;

package/dist/backend/paths.js

@@ -0,0 +1,69 @@
+import { lstat, realpath, readdir, open } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { isAbsolute, relative, resolve, sep, join } from 'node:path';
+import { BackendError } from './types.js';
+export function within(root, path) { const rel = relative(root, path); return rel === '' || (rel !== '..' && !rel.startsWith('..' + sep) && !isAbsolute(rel)); }
+async function directory(path) {
+    if (!isAbsolute(path))
+        throw new BackendError('INVALID_INPUT', 'Backend paths must be absolute');
+    const stat = await lstat(path);
+    const canonical = await realpath(path);
+    if (!stat.isDirectory() || stat.isSymbolicLink() || canonical !== resolve(path))
+        throw new BackendError('INVALID_INPUT', 'Use canonical non-symlink directories');
+    return canonical;
+}
+/** Runs outside DB transactions. No staging/rollback/Git operations here. */
+export async function validateRunPaths(context) {
+    if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,127}$/.test(context.runId))
+        throw new BackendError('INVALID_INPUT', 'Invalid Run id');
+    const [project, input, output, service] = await Promise.all([context.projectPath, context.inputPath, context.outputPath, context.serviceRoot].map(directory));
+    if (!project || !input || !output || !service)
+        throw new BackendError('INVALID_INPUT', 'Missing Run paths');
+    if (within(project, service) || within(service, project))
+        throw new BackendError('INVALID_INPUT', 'Project and service data directories must not overlap');
+    const expected = join(service, 'runs', context.runId);
+    if (input !== join(expected, 'input') || output !== join(expected, 'output'))
+        throw new BackendError('INVALID_INPUT', 'Input/output must belong to exactly this Run');
+    // Walking ancestors detects a symlink in runs/<id>, too.
+    await directory(join(service, 'runs'));
+    await directory(expected);
+    if ((await readdir(output)).length)
+        throw new BackendError('INVALID_INPUT', 'A new Run requires an empty output directory');
+}
+/** Artifact paths remain untrusted even when a turn reports success. No absolute/escaping/symlink paths. */
+export async function readRunOutput(outputRoot, name, maxBytes = 8 * 1024 * 1024) {
+    if (!name || isAbsolute(name) || name.includes('\0') || name.split(/[\/\\]/).some(part => part === '..' || part === '.'))
+        throw new BackendError('INVALID_INPUT', 'Invalid output path');
+    const root = await directory(outputRoot);
+    const path = resolve(root, name);
+    if (!within(root, path) || path === root)
+        throw new BackendError('INVALID_INPUT', 'Output escapes Run directory');
+    let parent = root;
+    const parts = relative(root, path).split(sep);
+    for (const component of parts.slice(0, -1)) {
+        parent = join(parent, component);
+        await directory(parent);
+    }
+    const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const before = await handle.stat();
+        if (!before.isFile() || before.nlink !== 1 || before.size > maxBytes || before.size < 0)
+            throw new BackendError('INVALID_INPUT', 'Output must be a bounded regular non-hardlinked file');
+        const buffer = Buffer.alloc(before.size + 1);
+        let total = 0;
+        while (total < buffer.length) {
+            const { bytesRead } = await handle.read(buffer, total, buffer.length - total, total);
+            if (!bytesRead)
+                break;
+            total += bytesRead;
+        }
+        const after = await handle.stat();
+        if (total !== before.size || after.size !== before.size || after.mtimeMs !== before.mtimeMs || await realpath(path) !== path)
+            throw new BackendError('INVALID_INPUT', 'Output changed during collection');
+        return buffer.subarray(0, total);
+    }
+    finally {
+        await handle.close();
+    }
+}
+//# sourceMappingURL=paths.js.map

package/dist/backend/stdio.d.ts

@@ -0,0 +1,66 @@
+export type RpcId = string | number;
+export type RpcMessage = {
+    id?: RpcId;
+    method?: string;
+    params?: any;
+    result?: any;
+    error?: {
+        code: number;
+        message: string;
+    };
+};
+export interface StdioOptions {
+    executable?: string;
+    args?: string[];
+    cwd: string;
+    env?: NodeJS.ProcessEnv;
+    timeoutMs?: number;
+    initializeTimeoutMs?: number;
+    maxFrameBytes?: number;
+}
+/** Bounded diagnostic categories only; never include stderr, frames, commands or paths. */
+export interface TransportFailure {
+    kind: "process_exit" | "spawn_error" | "stdin_error" | "frame_too_large" | "invalid_frame" | "rpc_timeout" | "host_close";
+    spawnCode?: 'ENOENT' | 'EACCES' | 'EPERM' | 'ENOEXEC';
+    exitCode?: number | null;
+    exitSignal?: string | null;
+    observedFrameBytes?: number;
+}
+/** npm's Windows .cmd shim cannot be spawned with shell:false. Use its JS entry. */
+export declare function codexCommand(options: StdioOptions, platform?: NodeJS.Platform): {
+    executable: string;
+    args: string[];
+};
+/** Private wire transport: never forward raw backend messages/errors/stderr to HTTP. */
+export declare class StdioRpc {
+    private readonly options;
+    private child;
+    private nextId;
+    private buffer;
+    private bufferBytes;
+    private decoder;
+    private stopped;
+    private exited;
+    private failureKind;
+    private exitCode;
+    private exitSignal;
+    private observedFrameBytes;
+    private spawnCode;
+    private pending;
+    onNotification: (method: string, params: any) => void;
+    onRequest: (id: RpcId, method: string, params: any) => void;
+    onDisconnect: () => void;
+    get isClosed(): boolean;
+    /** Exit is stronger evidence than a broken stdio pipe: this child can no longer run a turn. */
+    get isExited(): boolean;
+    get failure(): TransportFailure | null;
+    constructor(options: StdioOptions);
+    private receive;
+    private write;
+    request(method: string, params: unknown): Promise<any>;
+    notify(method: string): void;
+    reply(id: RpcId, result: unknown): void;
+    reject(id: RpcId): void;
+    private fail;
+    close(): void;
+}

package/dist/backend/stdio.js

@@ -0,0 +1,172 @@
+import { spawn } from 'node:child_process';
+import { StringDecoder } from 'node:string_decoder';
+import { existsSync } from 'node:fs';
+import { dirname, isAbsolute, join } from 'node:path';
+import { BackendError } from './types.js';
+const DEFAULT_MAX_FRAME_BYTES = 32 * 1024 * 1024;
+/** npm's Windows .cmd shim cannot be spawned with shell:false. Use its JS entry. */
+export function codexCommand(options, platform = process.platform) {
+    const executable = options.executable ?? 'codex';
+    const args = options.args ?? ['app-server', '--stdio'];
+    if (platform !== 'win32')
+        return { executable, args };
+    const env = options.env ?? process.env;
+    const path = Object.entries(env).find(([key]) => key.toLowerCase() === 'path')?.[1] ?? '';
+    const directories = executable === 'codex' ? path.split(';').filter(Boolean).map(p => p.replace(/^"|"$/g, '')) : /(?:^|[\\/])codex[.](?:cmd|ps1)$/i.test(executable) && isAbsolute(executable) ? [dirname(executable)] : [];
+    // A running Runtime retains its original PATH when npm installs Codex later.
+    // npm's default per-user bin directory remains discoverable through APPDATA.
+    if (executable === 'codex' && env.APPDATA)
+        directories.push(join(env.APPDATA, 'npm'));
+    for (const directory of directories) {
+        const native = join(directory, 'codex.exe');
+        if (existsSync(native))
+            return { executable: native, args };
+        const entry = join(directory, 'node_modules', '@openai', 'codex', 'bin', 'codex.js');
+        if (existsSync(entry))
+            return { executable: process.execPath, args: [entry, ...args] };
+    }
+    return { executable, args };
+}
+/** Private wire transport: never forward raw backend messages/errors/stderr to HTTP. */
+export class StdioRpc {
+    options;
+    child;
+    nextId = 0;
+    buffer = '';
+    bufferBytes = 0;
+    decoder = new StringDecoder('utf8');
+    stopped = false;
+    exited = false;
+    failureKind = null;
+    exitCode = null;
+    exitSignal = null;
+    observedFrameBytes;
+    spawnCode;
+    pending = new Map();
+    onNotification = () => { };
+    onRequest = id => this.reject(id);
+    onDisconnect = () => { };
+    get isClosed() { return this.stopped; }
+    /** Exit is stronger evidence than a broken stdio pipe: this child can no longer run a turn. */
+    get isExited() { return this.exited; }
+    get failure() { return this.failureKind ? { kind: this.failureKind, ...(this.spawnCode ? { spawnCode: this.spawnCode } : {}), ...(this.exited ? { exitCode: this.exitCode, exitSignal: this.exitSignal } : {}), ...(this.observedFrameBytes !== undefined ? { observedFrameBytes: this.observedFrameBytes } : {}) } : null; }
+    constructor(options) {
+        this.options = options;
+        const command = codexCommand(options);
+        this.child = spawn(command.executable, command.args, { cwd: options.cwd, env: options.env ?? process.env, stdio: ['pipe', 'pipe', 'pipe'], shell: false, windowsHide: true });
+        this.child.stderr.resume(); // Drain, but never persist credentials/backend diagnostics.
+        this.child.on('error', (error) => {
+            if (['ENOENT', 'EACCES', 'EPERM', 'ENOEXEC'].includes(error.code ?? ''))
+                this.spawnCode = error.code;
+            this.fail('spawn_error');
+        });
+        this.child.on('exit', (code, signal) => { this.exited = true; this.exitCode = code; this.exitSignal = signal; this.fail('process_exit'); });
+        this.child.stdin.on('error', () => this.fail('stdin_error'));
+        this.child.stdout.on('data', (chunk) => {
+            const decoded = this.decoder.write(chunk);
+            this.buffer += decoded;
+            this.bufferBytes += Buffer.byteLength(decoded);
+            const max = options.maxFrameBytes ?? DEFAULT_MAX_FRAME_BYTES;
+            let end;
+            while ((end = this.buffer.indexOf('\n')) >= 0) {
+                const line = this.buffer.slice(0, end);
+                this.buffer = this.buffer.slice(end + 1);
+                this.bufferBytes -= Buffer.byteLength(line) + 1;
+                if (Buffer.byteLength(line) > max) {
+                    this.observedFrameBytes = Buffer.byteLength(line);
+                    this.fail('frame_too_large');
+                    return;
+                }
+                if (!line.trim())
+                    continue;
+                try {
+                    const message = JSON.parse(line);
+                    this.receive(message);
+                }
+                catch {
+                    this.fail('invalid_frame');
+                    return;
+                }
+            }
+            if (this.bufferBytes > max) {
+                this.observedFrameBytes = this.bufferBytes;
+                this.fail('frame_too_large');
+            }
+        });
+    }
+    receive(m) {
+        if (!m || typeof m !== 'object' || Array.isArray(m))
+            throw new Error('Invalid frame');
+        if (m.id !== undefined && typeof m.id !== 'string' && typeof m.id !== 'number')
+            throw new Error('Invalid id');
+        if (typeof m.method === 'string') {
+            if (m.id !== undefined)
+                this.onRequest(m.id, m.method, m.params);
+            else
+                this.onNotification(m.method, m.params);
+            return;
+        }
+        if (m.id === undefined)
+            throw new Error('Missing id');
+        const pending = this.pending.get(m.id);
+        if (!pending)
+            return;
+        this.pending.delete(m.id);
+        clearTimeout(pending.timer);
+        if (m.error)
+            pending.reject(new BackendError('PROTOCOL', 'Backend rejected request', { method: pending.method, ...(Number.isSafeInteger(m.error.code) ? { rpcCode: m.error.code } : {}) }));
+        else if ('result' in m)
+            pending.resolve(m.result);
+        else
+            pending.reject(new BackendError('PROTOCOL', 'Missing backend result', { method: pending.method }));
+    }
+    write(message) {
+        if (this.stopped)
+            throw new BackendError('UNAVAILABLE', 'Backend connection closed');
+        const line = JSON.stringify(message) + '\n';
+        if (Buffer.byteLength(line) > (this.options.maxFrameBytes ?? DEFAULT_MAX_FRAME_BYTES) || this.child.stdin.writableLength > 2 * 1024 * 1024)
+            throw new BackendError('PROTOCOL', 'Backend message limit exceeded');
+        this.child.stdin.write(line);
+    }
+    request(method, params) {
+        if (this.pending.size >= 128)
+            return Promise.reject(new BackendError('PROTOCOL', 'Too many backend requests'));
+        return new Promise((resolve, reject) => {
+            const id = ++this.nextId;
+            const timeoutMs = method === 'initialize' ? this.options.initializeTimeoutMs ?? this.options.timeoutMs ?? 60000 : this.options.timeoutMs ?? 15000;
+            const timer = setTimeout(() => { this.pending.delete(id); reject(new BackendError('TIMEOUT', 'Backend request timed out; outcome unknown', { method, timeoutMs })); this.fail('rpc_timeout'); }, timeoutMs);
+            this.pending.set(id, { resolve, reject, timer, method });
+            try {
+                this.write({ id, method, params });
+            }
+            catch (error) {
+                clearTimeout(timer);
+                this.pending.delete(id);
+                reject(error);
+            }
+        });
+    }
+    notify(method) { this.write({ method }); }
+    reply(id, result) { this.write({ id, result }); }
+    reject(id) { this.write({ id, error: { code: -32601, message: 'Unsupported backend request' } }); }
+    fail(kind) {
+        if (!this.failureKind)
+            this.failureKind = kind;
+        if (this.stopped)
+            return;
+        this.stopped = true;
+        for (const p of this.pending.values()) {
+            clearTimeout(p.timer);
+            p.reject(new BackendError('UNAVAILABLE', 'Backend disconnected; outcome unknown', { method: p.method }));
+        }
+        this.pending.clear();
+        this.child.kill('SIGTERM');
+        const child = this.child;
+        const killTimer = setTimeout(() => { if (child.exitCode === null && child.signalCode === null)
+            child.kill('SIGKILL'); }, 1000);
+        killTimer.unref();
+        this.onDisconnect();
+    }
+    close() { this.fail("host_close"); }
+}
+//# sourceMappingURL=stdio.js.map

package/dist/backend/types.d.ts

@@ -0,0 +1,90 @@
+import type { ImageGenerationOptions, ModelSelection, ProjectFileInput, ResourceEnvelope, SandboxMode } from "../vendor/protocol/index.js";
+import type { TransportFailure } from './stdio.js';
+import type { RunContextRequest, RunLineage } from '../run-context.js';
+export type BackendState = 'starting' | 'running' | 'waiting_answer' | 'waiting_approval' | 'cancelling' | 'completed' | 'failed' | 'cancelled' | 'interrupted' | 'unknown';
+export interface BackendProgress {
+    itemId: string;
+    phase: 'commentary' | 'final_answer';
+    text: string;
+}
+export interface RuntimeSnapshot {
+    runId: string;
+    threadId: string | null;
+    turnId: string | null;
+    state: BackendState;
+    observedAt: string;
+    model: ModelSelection;
+    reason: string | null;
+    answer: string;
+    progress?: BackendProgress;
+    transportFailure?: TransportFailure;
+}
+export interface BackendQuestion {
+    id: string;
+    text: string;
+    options: string[];
+}
+export interface BackendInteraction {
+    id: string;
+    kind: 'question' | 'approval';
+    questions: BackendQuestion[];
+    reason: string;
+    command: string | null;
+    canApprove: boolean;
+}
+export type BackendReply = {
+    kind: 'question';
+    answers: Record<string, string[]>;
+} | {
+    kind: 'approval';
+    decision: 'accept' | 'decline';
+};
+/** Trusted service-resolved paths, never directly populated from a browser payload. */
+export interface BackendRunContext {
+    runId: string;
+    kind: 'execution' | 'text_generation' | 'image_generation';
+    projectPath: string;
+    inputPath: string;
+    outputPath: string;
+    serviceRoot: string;
+    prompt: string;
+    model: ModelSelection;
+    imageOptions?: ImageGenerationOptions;
+    sandboxMode?: SandboxMode;
+    resources?: ResourceEnvelope[];
+    projectFiles?: ProjectFileInput[];
+    files?: {
+        resourceId: string;
+        version: number;
+        path: string;
+        sha256: string;
+    }[];
+    upstreamContext?: RunLineage;
+}
+export interface BackendCallbacks {
+    onSnapshot(snapshot: RuntimeSnapshot): void | Promise<void>;
+    onInteraction(interaction: BackendInteraction): void | Promise<void>;
+    /** Must authorize against this Run's project; no global graph/database endpoint. */
+    queryHistory?(query: string): Promise<string>;
+    /** Exact, paginated read; project scope is derived from the calling Run. */
+    readRunContext?(request: RunContextRequest): Promise<string>;
+}
+export interface BackendAdapter {
+    start(context: BackendRunContext, callbacks: BackendCallbacks): Promise<RuntimeSnapshot>;
+    cancel(runId: string): Promise<RuntimeSnapshot>;
+    respond(runId: string, interactionId: string, reply: BackendReply): Promise<RuntimeSnapshot>;
+    reconcile(runId: string): Promise<RuntimeSnapshot>;
+}
+/** Only bounded metadata; raw backend messages may contain credentials and paths. */
+export interface BackendDiagnostic {
+    reason?: 'unsupported_version' | 'invalid_handshake' | 'invalid_catalog';
+    method?: string;
+    timeoutMs?: number;
+    rpcCode?: number;
+    version?: string;
+}
+export declare class BackendError extends Error {
+    readonly code: 'UNAVAILABLE' | 'PROTOCOL' | 'TIMEOUT' | 'CONFLICT' | 'INVALID_INPUT' | 'MODEL_UNAVAILABLE' | 'ISOLATION_UNVERIFIED';
+    readonly diagnostic?: BackendDiagnostic | undefined;
+    constructor(code: 'UNAVAILABLE' | 'PROTOCOL' | 'TIMEOUT' | 'CONFLICT' | 'INVALID_INPUT' | 'MODEL_UNAVAILABLE' | 'ISOLATION_UNVERIFIED', message: string, diagnostic?: BackendDiagnostic | undefined);
+}

package/dist/backend/types.js

@@ -0,0 +1,11 @@
+export class BackendError extends Error {
+    code;
+    diagnostic;
+    constructor(code, message, diagnostic) {
+        super(message);
+        this.code = code;
+        this.diagnostic = diagnostic;
+        this.name = 'BackendError';
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/backup-api.d.ts

@@ -0,0 +1,10 @@
+import type { IncomingMessage } from 'node:http';
+import type { ApiResult } from './api.js';
+import { Auth } from './auth.js';
+import { Backups } from './operations/backups.js';
+export declare class BackupApi {
+    readonly backups: Backups;
+    readonly auth: Auth;
+    constructor(backups: Backups, auth: Auth);
+    handle(request: IncomingMessage, path: string, token: string, origin: string): Promise<ApiResult>;
+}

package/dist/backup-api.js

@@ -0,0 +1,40 @@
+import { Auth } from './auth.js';
+import { Backups } from './operations/backups.js';
+import { readJson } from './http.js';
+import { ServiceError } from './errors.js';
+import { createHash } from 'node:crypto';
+export class BackupApi {
+    backups;
+    auth;
+    constructor(backups, auth) {
+        this.backups = backups;
+        this.auth = auth;
+    }
+    async handle(request, path, token, origin) {
+        if (path === '/v1/restore-guidance' && request.method === 'GET')
+            return this.auth.withSession(token, origin, () => ({ handled: true, body: { localOnly: true, command: 'openworkgraph restore apply <backup-path> --sha256 <verified-sha256> --data-dir <service-data-dir>' } }));
+        const match = /^[/]v1[/]backups(?:[/]([a-f0-9]{64})[/](download))?$/.exec(path);
+        if (!match)
+            return { handled: false };
+        const principal = this.auth.withSession(token, origin, s => s.id);
+        if (request.method === 'GET') {
+            if (match[1]) {
+                const value = await this.backups.readDownload(match[1]);
+                return this.auth.withSession(token, origin, () => ({ handled: true, binary: value.body, headers: { 'Content-Type': value.contentType, 'Content-Length': String(value.body.length), 'Content-Disposition': 'attachment; filename="' + value.filename + '"' } }));
+            }
+            const value = await this.backups.list();
+            return this.auth.withSession(token, origin, () => ({ handled: true, body: value }));
+        }
+        if (request.method === 'POST' && !match[1]) {
+            const body = await readJson(request);
+            if (Object.keys(body).length !== 1 || typeof body.idempotencyKey !== 'string' || !body.idempotencyKey || body.idempotencyKey.length > 256)
+                throw new ServiceError('INVALID_REQUEST', '备份需要幂等键。');
+            this.auth.withSession(token, origin, () => undefined);
+            const key = createHash('sha256').update(principal + ':' + body.idempotencyKey).digest('hex');
+            const value = await this.backups.create(key);
+            return this.auth.withSession(token, origin, () => ({ handled: true, body: value }));
+        }
+        throw new ServiceError('NOT_FOUND', '备份接口不存在。');
+    }
+}
+//# sourceMappingURL=backup-api.js.map