@ai-workbench/remote-agent 0.8.1 → 0.8.5

package/dist/model-catalog.js

@@ -0,0 +1,254 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { spawn } from 'node:child_process';
+import { LlmError, ReasoningEffortId } from '@deepseek-ai/dsh-llm';
+import { sameTarget, validateTarget } from "./provider.js";
+import { ModelConfigurationError } from "./model-configuration.js";
+import { sanitizeObservation } from "./conversation-details.js";
+const object = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+const text = (value) => typeof value === 'string' && value.trim().length > 0;
+function fail(reason) { throw new LlmError('无法获取模型列表：' + reason, 'MODEL_CATALOG_UNAVAILABLE'); }
+function freeze(value) { if (value && typeof value === 'object') {
+    for (const item of Object.values(value))
+        freeze(item);
+    Object.freeze(value);
+} return value; }
+export function parseHostCatalog(input, provider, username) {
+    let wire;
+    try {
+        wire = JSON.parse(input);
+    }
+    catch {
+        fail('主机目录响应不是有效 JSON');
+    }
+    if (!object(wire) || wire.version !== 1 || wire.purpose !== 'model-catalog' || wire.scope !== 'host-user' || wire.provider !== provider)
+        fail('主机目录版本、品牌或作用域不匹配');
+    if (wire.ok === false) {
+        const error = object(wire.error) ? wire.error : undefined;
+        const code = typeof error?.code === 'string' && /^[A-Z][A-Z0-9_]*$/.test(error.code) ? error.code : 'PROTOCOL_INVALID';
+        const reason = text(error?.message) ? sanitizeObservation({ kind: 'session', severity: 'warning', code, summary: error.message, payload: {} }).summary : '主机未提供失败说明';
+        fail('主机目录查询失败（' + code + '）：' + reason);
+    }
+    if (wire.ok !== true || wire.permissionProbe !== false || !object(wire.subject) || wire.subject.username !== username || !Number.isSafeInteger(wire.subject.uid) || !text(wire.observedAt) || !object(wire.source) || !object(wire.settings) || !Array.isArray(wire.models))
+        fail('主机目录缺少完整元数据');
+    const ids = new Set(), values = new Set();
+    for (const model of wire.models) {
+        if (!object(model) || !text(model.id) || !text(model.value) || !text(model.name) || (model.resolvedModel !== null && !text(model.resolvedModel)) || !object(model.source) || !object(model.reasoning))
+            fail('主机模型条目不完整');
+        if (provider === 'codex' && model.resolvedModel !== model.value)
+            fail('Codex目录具体型号与模型值不一致');
+        if (ids.has(model.id) || values.has(model.value))
+            fail('主机目录含重复模型标识或值');
+        ids.add(model.id);
+        values.add(model.value);
+        const r = model.reasoning;
+        if (!Array.isArray(r.options) || typeof r.defaultKnown !== 'boolean' || (r.defaultValue !== null && !text(r.defaultValue)) || (!r.defaultKnown && r.defaultValue !== null))
+            fail('主机推理等级或默认值无效');
+        const efforts = new Set();
+        for (const effort of r.options) {
+            if (!object(effort) || !text(effort.value) || !text(effort.name) || efforts.has(effort.value))
+                fail('主机推理等级条目无效或重复');
+            efforts.add(effort.value);
+        }
+        if (r.defaultKnown && (r.defaultValue === null || !efforts.has(r.defaultValue)))
+            fail('主机默认推理等级缺少对应选项');
+    }
+    if (!wire.models.length)
+        fail('主机返回的完整模型目录为空');
+    return freeze(structuredClone(wire.models));
+}
+/** Only the public L sshArgs function chooses SSH trust and transport arguments. */
+export const runCatalog = async (target, command, signal, maxBytes) => {
+    let argv;
+    try {
+        const moduleName = '@ai-workbench/connect';
+        const l = await import(__rewriteRelativeImportExtension(moduleName));
+        if (typeof l.sshArgs !== 'function')
+            fail('远程主机连接组件缺少可信 SSH 能力');
+        argv = l.sshArgs(target);
+    }
+    catch (error) {
+        if (error instanceof LlmError)
+            throw error;
+        fail('远程主机连接组件缺少可信 SSH 能力');
+    }
+    signal.throwIfAborted();
+    return new Promise((resolve, reject) => {
+        const child = spawn('ssh', ['-n', ...argv, command], { stdio: ['ignore', 'pipe', 'pipe'] });
+        const parts = [];
+        let total = 0, stderr = 0;
+        let failure;
+        const abort = () => { failure = new ModelConfigurationError('连接已改变或目录查询已取消'); child.kill('SIGTERM'); };
+        signal.addEventListener('abort', abort, { once: true });
+        const receive = (buffer, output) => { if (failure)
+            return; total += buffer.length; if (total > maxBytes) {
+            failure = new ModelConfigurationError('目录响应超过 acpMaxMessageBytes，未截断返回');
+            child.kill('SIGTERM');
+            return;
+        } if (output)
+            parts.push(buffer);
+        else
+            stderr += buffer.length; };
+        child.stdout.on('data', (b) => receive(b, true));
+        child.stderr.on('data', (b) => receive(b, false));
+        child.on('error', () => { failure = new ModelConfigurationError('可信 SSH 进程启动失败'); });
+        child.on('close', code => {
+            signal.removeEventListener('abort', abort);
+            if (failure) {
+                reject(failure);
+                return;
+            }
+            let output;
+            try {
+                output = new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(parts));
+            }
+            catch {
+                reject(new ModelConfigurationError('主机目录响应不是有效 UTF-8，未替换模型值'));
+                return;
+            }
+            // S publishes its typed failure JSON on stdout even on nonzero exit.
+            if (code !== 0) {
+                try {
+                    const wire = JSON.parse(output);
+                    if (wire?.ok === false) {
+                        resolve(output);
+                        return;
+                    }
+                }
+                catch { }
+                reject(new ModelConfigurationError('可信 SSH 或主机目录命令失败（退出码 ' + String(code) + '）'));
+                return;
+            }
+            if (stderr) {
+                reject(new ModelConfigurationError('目录命令返回了非预期诊断输出'));
+                return;
+            }
+            resolve(output);
+        });
+        if (signal.aborted)
+            abort();
+    });
+};
+/** No cache: every query binds to L's current object, host-user and generation. */
+export class ModelCatalog {
+    get;
+    maxBytes;
+    run;
+    changed;
+    api;
+    unsubscribe;
+    signature;
+    revision = 0;
+    disposed = false;
+    initialized = false;
+    active = new Set();
+    constructor(get, maxBytes, run = runCatalog, changed = () => { }) {
+        this.get = get;
+        this.maxBytes = maxBytes;
+        this.run = run;
+        this.changed = changed;
+        this.refresh();
+    }
+    refresh() {
+        const api = this.get();
+        const state = api?.getConnectionState?.();
+        const info = api?.getContractInfo?.();
+        const targets = info?.modelCatalogTarget === 1 && api?.getModelCatalogTarget ? ['codex', 'claude'].map(brand => api.getModelCatalogTarget(brand)) : undefined;
+        const login = api?.getLoginPromptState?.();
+        // L's same-epoch recovery wording is presentation metadata, not an execution change.
+        const executionState = state && { instanceId: state.instanceId, epoch: state.epoch, phase: state.phase, needCode: state.need?.code };
+        const executionTargets = targets?.map(result => result.ok ? result : { ok: false, code: result.error.code });
+        const signature = JSON.stringify({ state: executionState, capability: info?.modelCatalogTarget, targets: executionTargets, logins: login?.logins, authorizing: login?.phase === 'authorizing' });
+        const switched = api !== this.api;
+        const changed = this.initialized && (switched || signature !== this.signature);
+        this.initialized = true;
+        if (switched) {
+            this.unsubscribe?.();
+            this.unsubscribe = undefined;
+            this.api = api;
+            const off = [];
+            if (typeof api?.onConnectionState === 'function')
+                off.push(api.onConnectionState(() => this.refresh()));
+            if (typeof api?.onLoginPromptState === 'function')
+                off.push(api.onLoginPromptState(() => this.refresh()));
+            this.unsubscribe = () => { for (const stop of off)
+                stop(); };
+        }
+        this.signature = signature;
+        if (changed) {
+            this.revision++;
+            for (const controller of this.active)
+                controller.abort();
+            this.active.clear();
+            this.changed();
+        }
+    }
+    trusted(agent, api) {
+        const info = api.getContractInfo?.();
+        if (info?.modelCatalogTarget !== 1 || typeof api.getModelCatalogTarget !== 'function')
+            fail('远程主机连接组件尚未提供模型目录目标能力');
+        const state = api.getConnectionState();
+        if (state.phase !== 'connected' || !text(state.instanceId) || !Number.isSafeInteger(state.epoch) || state.epoch < 0)
+            fail('当前没有已验证的远程主机连接');
+        const result = api.getModelCatalogTarget(agent.loginProvider);
+        if (!result.ok)
+            fail(result.error.message);
+        const target = result.value;
+        if (target.version !== 1 || target.purpose !== 'model-catalog' || target.scope !== 'host-user' || target.provider !== agent.loginProvider || target.instanceId !== state.instanceId || target.epoch !== state.epoch)
+            fail('模型目录目标与当前连接或品牌不匹配');
+        try {
+            validateTarget(target.target);
+        }
+        catch {
+            fail('模型目录的可信 SSH 目标不完整');
+        }
+        return structuredClone(target);
+    }
+    async read(agent, signal) {
+        let controller;
+        try {
+            if (this.disposed)
+                fail('远程模型插件已关闭');
+            this.refresh();
+            const api = this.get();
+            if (!api)
+                fail('远程主机连接组件没有装好');
+            const target = freeze(this.trusted(agent, api)), revision = this.revision;
+            const max = this.maxBytes();
+            if (!Number.isSafeInteger(max) || max < 1)
+                fail('acpMaxMessageBytes 设置无效');
+            controller = new AbortController();
+            this.active.add(controller);
+            const combined = signal ? AbortSignal.any([signal, controller.signal]) : controller.signal;
+            const assertCurrent = () => { if (combined.aborted || this.disposed || this.get() !== api || revision !== this.revision)
+                fail('连接已改变，原模型目录已失效'); const current = this.trusted(agent, api); if (current.instanceId !== target.instanceId || current.epoch !== target.epoch || current.provider !== target.provider || !sameTarget(current.target, target.target))
+                fail('可信目标或连接代次已改变，原模型目录已失效'); };
+            assertCurrent();
+            const output = await this.run(target.target, '/usr/local/aw-host/bin/aw-model-catalog --provider ' + agent.loginProvider, combined, max);
+            assertCurrent();
+            const models = parseHostCatalog(output, agent.loginProvider, target.target.username);
+            const own = controller;
+            return { target, models, signal: combined, assertCurrent, release: () => this.active.delete(own) };
+        }
+        catch (error) {
+            if (controller)
+                this.active.delete(controller);
+            if (error instanceof LlmError)
+                throw error;
+            if (error instanceof ModelConfigurationError)
+                fail(error.message.replace(/^无法获取模型列表：/, ''));
+            fail('目录查询失败，根因未查明');
+        }
+    }
+    dispose() { this.disposed = true; this.unsubscribe?.(); for (const controller of this.active)
+        controller.abort(); this.active.clear(); }
+}
+export function modelInfo(provider, model) {
+    return { provider, id: model.id, name: model.name, inputModalities: ['text', 'image'], reasoning: { efforts: model.reasoning.options.map(option => ({ id: ReasoningEffortId(option.value), name: option.name })), ...(model.reasoning.defaultKnown && model.reasoning.defaultValue !== null ? { defaultEffort: ReasoningEffortId(model.reasoning.defaultValue) } : {}) }, catalog: model };
+}

package/dist/model-configuration.d.ts

@@ -0,0 +1,51 @@
+import type { SessionConfigOption } from '@agentclientprotocol/sdk/unstable';
+export type DeepReadonly<T> = T extends readonly unknown[] ? {
+    readonly [K in keyof T]: DeepReadonly<T[K]>;
+} : T extends object ? {
+    readonly [K in keyof T]: DeepReadonly<T[K]>;
+} : T;
+export interface ModelCatalogValue {
+    readonly value: string;
+    readonly name: string;
+    readonly description?: string | null;
+}
+export interface ModelConfigurationSnapshot {
+    readonly configOptions: DeepReadonly<SessionConfigOption[]>;
+    readonly models: readonly ModelCatalogValue[];
+    readonly modelConfigId?: string;
+    readonly effortConfigId?: string;
+    readonly model?: string;
+    readonly effort?: string;
+    readonly effortAvailable: boolean;
+    /** Acknowledges the selected values, not the availability of every catalog entry. */
+    readonly confirmed: boolean;
+    readonly failure?: Readonly<{
+        code: 'MODEL_CATALOG_UNAVAILABLE';
+        message: string;
+    }>;
+}
+export type ModelConfigurationSetter = (configId: string, value: string) => Promise<{
+    configOptions: SessionConfigOption[];
+}>;
+export declare class ModelConfigurationError extends Error {
+    readonly code = "MODEL_CATALOG_UNAVAILABLE";
+    constructor(reason: string, options?: ErrorOptions);
+}
+/** Pure ACP configuration state. All IDs and values come from the given peer data. */
+export declare class ModelConfiguration {
+    private readonly rpcSet;
+    private state;
+    private parsed?;
+    private revision;
+    private busy;
+    constructor(options: SessionConfigOption[], rpcSet: ModelConfigurationSetter);
+    get models(): readonly ModelCatalogValue[];
+    get snapshot(): ModelConfigurationSnapshot;
+    update(options: SessionConfigOption[]): void;
+    private fail;
+    private checkAckRevision;
+    private set;
+    select(model: string, effort?: string): Promise<ModelConfigurationSnapshot>;
+    /** Call immediately before prompt; an idle/new/load/resume update withdraws the ACK. */
+    assertSelection(model: string, effort?: string): void;
+}

package/dist/model-configuration.js

@@ -0,0 +1,212 @@
+export class ModelConfigurationError extends Error {
+    code = 'MODEL_CATALOG_UNAVAILABLE';
+    constructor(reason, options) {
+        super(`无法获取模型列表：${reason}`, options);
+        this.name = 'ModelConfigurationError';
+    }
+}
+function unavailable(reason) { throw new ModelConfigurationError(reason); }
+function record(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function text(value) { return typeof value === 'string' && value.trim().length > 0; }
+function label(value) {
+    if (!text(value.name))
+        unavailable('配置名称为空或无效');
+    if (value.description !== undefined && value.description !== null && typeof value.description !== 'string')
+        unavailable('配置说明无效');
+}
+function select(option) {
+    if (!text(option.currentValue) || !Array.isArray(option.options) || !option.options.length)
+        unavailable('选择器缺少实际当前值或可选列表');
+    const values = [];
+    const seen = new Set();
+    const add = (value) => {
+        if (!record(value) || !text(value.value) || 'group' in value || 'options' in value)
+            unavailable('可选值格式无效');
+        label(value);
+        if (seen.has(value.value))
+            unavailable('选择器包含重复可选值');
+        seen.add(value.value);
+        values.push({ value: value.value, name: value.name, ...(value.description === undefined ? {} : { description: value.description }) });
+    };
+    const grouped = record(option.options[0]) && 'group' in option.options[0];
+    const groups = new Set();
+    for (const entry of option.options) {
+        if (grouped) {
+            if (!record(entry) || !text(entry.group) || 'value' in entry || !Array.isArray(entry.options) || !entry.options.length)
+                unavailable('分组选择器格式无效或分组为空');
+            label(entry);
+            if (groups.has(entry.group))
+                unavailable('选择器包含重复分组标识');
+            groups.add(entry.group);
+            for (const value of entry.options)
+                add(value);
+        }
+        else
+            add(entry);
+    }
+    if (!seen.has(option.currentValue))
+        unavailable('实际当前值不在远端可选列表中');
+    return { id: option.id, currentValue: option.currentValue, values };
+}
+function parse(options) {
+    if (!Array.isArray(options) || !options.length)
+        unavailable('远端没有提供完整配置列表');
+    const ids = new Set();
+    const models = [];
+    const efforts = [];
+    for (const option of options) {
+        if (!record(option) || !text(option.id))
+            unavailable('配置标识为空或无效');
+        label(option);
+        if (ids.has(option.id))
+            unavailable('配置列表包含重复标识');
+        ids.add(option.id);
+        if (option.category !== undefined && option.category !== null && typeof option.category !== 'string')
+            unavailable('配置类别无效');
+        if (option.type === 'select') {
+            const selector = select(option);
+            if (option.category === 'model')
+                models.push(selector);
+            if (option.category === 'thought_level')
+                efforts.push(selector);
+        }
+        else if (option.type === 'boolean') {
+            if (typeof option.currentValue !== 'boolean')
+                unavailable('布尔配置当前值无效');
+            if (option.category === 'model' || option.category === 'thought_level')
+                unavailable('模型或推理等级配置不是选择器');
+        }
+        else
+            unavailable('配置类型无法识别');
+    }
+    if (models.length !== 1)
+        unavailable(models.length ? '模型选择器不唯一' : '没有可识别的模型选择器');
+    if (efforts.length > 1)
+        unavailable('推理等级选择器不唯一');
+    return { model: models[0], effort: efforts[0] };
+}
+function freeze(value, seen = new WeakSet()) {
+    if (value !== null && typeof value === 'object' && !seen.has(value)) {
+        seen.add(value);
+        for (const item of Object.values(value))
+            freeze(item, seen);
+        Object.freeze(value);
+    }
+    return value;
+}
+/** Pure ACP configuration state. All IDs and values come from the given peer data. */
+export class ModelConfiguration {
+    rpcSet;
+    state;
+    parsed;
+    revision = 0;
+    busy = false;
+    constructor(options, rpcSet) {
+        this.rpcSet = rpcSet;
+        this.update(options);
+    }
+    get models() {
+        if (!this.parsed)
+            throw new ModelConfigurationError('当前远端配置列表无效');
+        return this.state.models;
+    }
+    get snapshot() { return this.state; }
+    update(options) {
+        this.revision++;
+        let copy = [];
+        try {
+            // The wire is JSON data; clone before validation so caller mutations cannot race ACK checks.
+            const copied = structuredClone(options);
+            if (Array.isArray(copied))
+                copy = copied;
+            const parsed = parse(copied);
+            this.parsed = parsed;
+            this.state = freeze({
+                configOptions: copy, models: parsed.model.values,
+                modelConfigId: parsed.model.id, model: parsed.model.currentValue,
+                ...(parsed.effort ? { effortConfigId: parsed.effort.id, effort: parsed.effort.currentValue } : {}),
+                effortAvailable: !!parsed.effort, confirmed: false,
+            });
+        }
+        catch (cause) {
+            const error = cause instanceof ModelConfigurationError ? cause : new ModelConfigurationError('配置数据无法复制或解析', { cause });
+            this.parsed = undefined;
+            this.state = freeze({ configOptions: copy, models: [], effortAvailable: false, confirmed: false, failure: { code: error.code, message: error.message } });
+            throw error;
+        }
+    }
+    fail(error) {
+        this.state = freeze({ ...this.state, confirmed: false, failure: { code: error.code, message: error.message } });
+    }
+    checkAckRevision(revision, stage) {
+        if (revision !== this.revision)
+            unavailable(`${stage}回执之后收到其他配置更新，原选择未获确认`);
+    }
+    async set(id, value, stage) {
+        const revision = this.revision;
+        let response;
+        try {
+            response = await this.rpcSet(id, value);
+        }
+        catch (cause) {
+            throw new ModelConfigurationError(`${stage}配置请求失败，未获得远端确认`, { cause });
+        }
+        if (revision !== this.revision)
+            unavailable(`${stage}配置请求期间收到其他配置更新，无法确认回执顺序`);
+        if (!record(response) || !Array.isArray(response.configOptions))
+            unavailable(`${stage}配置回执缺少完整配置列表`);
+        this.update(response.configOptions);
+        return this.revision;
+    }
+    async select(model, effort) {
+        if (this.busy)
+            throw new ModelConfigurationError('另一个配置选择尚未完成');
+        this.busy = true;
+        this.state = freeze({ ...this.state, confirmed: false });
+        try {
+            if (!this.parsed)
+                unavailable('当前远端配置列表无效');
+            if (!this.parsed.model.values.some(entry => entry.value === model))
+                unavailable('所选模型不在实际远端列表中');
+            let ackRevision = await this.set(this.parsed.model.id, model, '模型');
+            this.checkAckRevision(ackRevision, '模型');
+            if (this.state.model !== model)
+                unavailable('模型配置回执与所选模型不一致');
+            if (effort !== undefined) {
+                const selector = this.parsed?.effort;
+                if (!selector)
+                    unavailable('远端没有提供实际推理等级选择器');
+                if (!selector.values.some(entry => entry.value === effort))
+                    unavailable('所选推理等级不在模型回执的实际列表中');
+                ackRevision = await this.set(selector.id, effort, '推理等级');
+                this.checkAckRevision(ackRevision, '推理等级');
+                if (this.state.model !== model)
+                    unavailable('推理等级回执中的模型发生变化');
+                if (!this.state.effortAvailable || this.state.effort !== effort)
+                    unavailable('推理等级配置回执与所选等级不一致');
+            }
+            this.checkAckRevision(ackRevision, '选择');
+            this.state = freeze({ ...this.state, confirmed: true });
+            return this.state;
+        }
+        catch (cause) {
+            const error = cause instanceof ModelConfigurationError ? cause : new ModelConfigurationError('配置选择未能完成核对', { cause });
+            this.fail(error);
+            throw error;
+        }
+        finally {
+            this.busy = false;
+        }
+    }
+    /** Call immediately before prompt; an idle/new/load/resume update withdraws the ACK. */
+    assertSelection(model, effort) {
+        if (this.busy || !this.parsed || !this.state.confirmed)
+            unavailable('当前模型选择尚未获得完整远端确认');
+        if (this.state.model !== model)
+            unavailable('当前实际模型与待发送选择不一致');
+        if (effort !== undefined && (!this.state.effortAvailable || this.state.effort !== effort))
+            unavailable('当前实际推理等级与待发送选择不一致');
+    }
+}

package/dist/presentation.js

@@ -40,6 +40,10 @@ export function employeeFailure(code) {
         ACP_MESSAGE_TOO_LARGE: '本轮输入超过会话消息容量，未截断或发送；请联系管理员调整acpMaxMessageBytes。',
         ACP_CLIENT_LOST: '我需要管理员核对并结束遗留的主机会话；当前保留原进程，没有代答旧审批。',
         ONESHOT_CONTEXT_REQUIRED: '首版单次模式不支持图片或系统与开发者上下文，请改用会话模式。',
+        MODEL_CONFIGURATION_UNSUPPORTED: '单次模式不支持确认当前模型与推理等级，本轮未发送；请改用会话模式。',
+        MODEL_SELECTION_REQUIRED: '旧远端恢复记录没有明确模型选择，本轮未发送；请新建会话并选择模型。',
+        MODEL_RESOLUTION_UNCONFIRMED: '所选模型的具体型号尚未获得当前会话确认，本轮未发送；请重新选择模型或联系管理员。',
+        REMOTE_CLEANUP_UNCONFIRMED: '原主机会话的清理结果尚未确认，已阻断继续发送；请联系管理员核对，不能自动重开。',
     };
     return messages[code] ?? `远程主机暂时无法完成这次操作，请联系管理员。技术详情：诊断代码 ${code}`;
 }

package/dist/protocol-boundary.d.ts

@@ -0,0 +1,13 @@
+/** Byte fragments remain only in memory. A cursor is clean only after SDK consumption. */
+export declare class ProtocolBoundary {
+    private readonly maxBytes;
+    private partial;
+    private pending;
+    private requests;
+    constructor(maxBytes: number);
+    receive(bytes: Uint8Array, gate?: (message: Record<string, unknown>) => void): void;
+    consumed(message: Record<string, unknown>): void;
+    responded(id: unknown): void;
+    get complete(): boolean;
+    get wholeLine(): boolean;
+}

package/dist/protocol-boundary.js

@@ -0,0 +1,49 @@
+import { createHash } from 'node:crypto';
+import { NeedError } from "./remote.js";
+const fingerprint = (value) => createHash('sha256').update(JSON.stringify(value)).digest('hex');
+/** Byte fragments remain only in memory. A cursor is clean only after SDK consumption. */
+export class ProtocolBoundary {
+    maxBytes;
+    partial = Buffer.alloc(0);
+    pending = [];
+    requests = new Set();
+    constructor(maxBytes) {
+        this.maxBytes = maxBytes;
+    }
+    receive(bytes, gate) {
+        this.partial = Buffer.concat([this.partial, bytes]);
+        let end;
+        while ((end = this.partial.indexOf(10)) >= 0) {
+            if (end > this.maxBytes)
+                throw new NeedError('ACP_MESSAGE_TOO_LARGE', '主机消息超过具名会话容量', 'acpMaxMessageBytes');
+            const line = this.partial.subarray(0, end).toString('utf8').trim();
+            this.partial = this.partial.subarray(end + 1);
+            if (!line)
+                continue;
+            let message;
+            try {
+                message = JSON.parse(line);
+            }
+            catch {
+                throw new NeedError('ACP_OUTPUT_INVALID', '主机消息不是有效JSON', '完整ACP消息');
+            }
+            if (!message || typeof message !== 'object' || Array.isArray(message))
+                throw new NeedError('ACP_OUTPUT_INVALID', '主机消息结构无效', '完整ACP消息');
+            if (gate)
+                gate(message);
+            else
+                this.pending.push(fingerprint(message));
+        }
+        if (this.partial.length > this.maxBytes)
+            throw new NeedError('ACP_MESSAGE_TOO_LARGE', '主机消息超过具名会话容量', 'acpMaxMessageBytes');
+    }
+    consumed(message) {
+        if (this.pending.shift() !== fingerprint(message))
+            throw new NeedError('ACP_BOUNDARY_UNCONFIRMED', '主机消息处理位置无法确认', '完整按序的ACP消息');
+        if (typeof message.method === 'string' && Object.hasOwn(message, 'id'))
+            this.requests.add(JSON.stringify(message.id));
+    }
+    responded(id) { this.requests.delete(JSON.stringify(id)); }
+    get complete() { return this.partial.length === 0 && this.pending.length === 0 && this.requests.size === 0; }
+    get wholeLine() { return this.partial.length === 0; }
+}

package/dist/provider.d.ts

@@ -1,6 +1,6 @@
 import type { AgentApp } from '@agentclientprotocol/sdk';
 import type { AgentApp as ExtendedAgentApp } from '@agentclientprotocol/sdk/unstable';
-import type { ConnectState, ConnectApi as LConnectApi, ConnectionState, LoginPromptState } from '@ai-workbench/connect/api';
+import type { ConnectState, ConnectNeed, ConnectApi as LConnectApi, ConnectionState, LoginPromptState } from '@ai-workbench/connect/api';
 export type { ConnectionState, LoginPromptState } from '@ai-workbench/connect/api';
 import type { OneShotRuntime } from './job.ts';
 import type { BrokerTransport, BrokerSettings } from './broker.ts';
@@ -9,6 +9,8 @@ import { type AgentDefinition } from './agents.ts';
 import type { NativeWorkspaceApi, SessionProjectTarget, WorkspaceNotice, LoginProvider } from './connect-contract.ts';
 import type { DetailChannel } from './remote-details.ts';
 import type { WorkspaceNoticePresentation } from './workspace-notice.ts';
+import { StageTiming } from './stage-timing.ts';
+import type { RecoveryJournal, AcpRecovery } from './recovery.ts';
 export interface Runtime {
     identity: string;
     cwd: string;
@@ -28,12 +30,28 @@ export interface Runtime {
     connection?: ConnectionState;
     workspaceNotice?: WorkspaceNoticePresentation;
     details?: DetailChannel;
+    recoveredSession?: AcpRecovery;
+    restartNotice?: string;
+    detach?: () => Promise<void>;
+    restartInputIds?: readonly string[];
+    saveCheckpoint?: (id: string, acp: AcpRecovery) => Promise<boolean>;
     detailContext?: () => {
         turn: string | number | null;
         step: string | number | null;
     };
 }
 export interface RuntimeRequest extends Invocation {
+    recoveryJournal?: RecoveryJournal;
+    detailChannel?: DetailChannel;
+    validateContext?: (ignoreCancellation?: boolean) => Promise<void>;
+    verifyRecovery?: () => Promise<boolean>;
+    acpMaxMessageBytes?: number;
+    contextSha256?: string;
+    resumeSessionId?: string;
+    recoveryCheckpointId?: string;
+    bindingRevision?: number;
+    currentInputIds?: readonly string[];
+    timing?: StageTiming;
     mode: 'session' | 'one-shot';
     cwd?: string;
     identity?: string;
@@ -85,10 +103,10 @@ type Result<T> = {
         code: string;
         message: string;
         requires: string;
-    };
+    } & Pick<ConnectNeed, 'officialReason'>;
 };
 /** 消费正式connect-api 0.7公开子集；X不响应L登录票据、不直接调用登录。 */
-export interface ConnectApi extends Pick<LConnectApi, 'getConnectionState' | 'getLoginPromptState' | 'requestLoginPrompt' | 'refreshLoginPrompts'>, Partial<NativeWorkspaceApi>, Partial<Pick<LConnectApi, 'appendRemoteConversationDetail' | 'getRemoteConversationDetailReceipt' | 'listRemoteConversationDetails'>> {
+export interface ConnectApi extends Pick<LConnectApi, 'getConnectionState' | 'getLoginPromptState' | 'requestLoginPrompt' | 'refreshLoginPrompts'>, Partial<NativeWorkspaceApi>, Partial<Pick<LConnectApi, 'getWorkspaceBindingState' | 'getModelCatalogTarget' | 'onConnectionState' | 'onLoginPromptState' | 'appendRemoteConversationDetail' | 'getRemoteConversationDetailReceipt' | 'listRemoteConversationDetails'>> {
     getState?(): ConnectState;
     getSshTarget(): Promise<Result<ConnectTarget>>;
     checkLogin(provider: LoginProvider): Promise<Result<{