@ai-workbench/remote-agent 0.0.0-stage → 0.8.1

package/dist/index.js

@@ -0,0 +1,360 @@
+import { SessionId } from '@deepseek-ai/dsh-session';
+import Schema from '@deepseek-ai/schemastery';
+import { LlmAdapter, LlmError } from '@deepseek-ai/dsh-llm';
+import { fileURLToPath } from 'node:url';
+import { createHash } from 'node:crypto';
+import * as unstable from '@agentclientprotocol/sdk/unstable';
+import * as acp from '@agentclientprotocol/sdk';
+import { AcpSession } from "./acp.js";
+import { runOneShot } from "./oneshot.js";
+import { StreamMapper } from "./mapping.js";
+import { connectProvider } from "./provider.js";
+import { brokerFactory } from "./broker.js";
+import { AGENTS, CODEX_AGENT } from "./agents.js";
+import { prepareInput } from "./input.js";
+import { createWorkspaceNoticeConsumer, isWorkspaceNoticeMessage } from "./workspace-notice.js";
+import { NeedError } from "./remote.js";
+import { employeeFailure } from "./presentation.js";
+import { createRemoteDetails } from "./remote-details.js";
+import { PROVIDER_NAMES, ProviderLocaleRemote } from "./provider-locale.js";
+export const name = 'ai-workbench-remote-agent';
+export const settingsNamespace = 'ai-workbench-codex';
+// L can be installed/enabled after X; keeping X mounted lets it explain the prerequisite.
+export const inject = ['llm'];
+/** Owner-approved defaults; administrators may override through the existing settings. */
+export const DEFAULT_CONFIG = Object.freeze({ mode: 'session', acpMaxMessageBytes: 4194304, brokerMaxFrameBytes: 2097152, brokerControlMaxBytes: 1048576, oneShotSandbox: 'workspace-write', oneShotApproval: 'never' });
+export const Config = Schema.object({
+    mode: Schema.union([Schema.const('session').i18n({ en: 'Session', zh: '会话模式' }), Schema.const('one-shot').i18n({ en: 'One-shot', zh: '单次模式' })]).i18n({ en: 'Run mode; start a new session after switching modes', zh: 'Codex运行模式；Claude固定会话模式；切换后请新建会话' }).default(DEFAULT_CONFIG.mode).volatile(),
+    acpMaxMessageBytes: Schema.number().min(1).step(1).i18n({ en: 'Session message limit; default 4 MiB, adjustable by administrators', zh: '会话消息容量；默认4 MiB，管理员可调整' }).default(DEFAULT_CONFIG.acpMaxMessageBytes).volatile(),
+    brokerMaxFrameBytes: Schema.number().min(1).step(1).i18n({ en: 'Host output chunk limit; default 2 MiB, adjustable by administrators', zh: '主机回传单段容量；默认2 MiB，管理员可调整' }).default(DEFAULT_CONFIG.brokerMaxFrameBytes).volatile(),
+    brokerControlMaxBytes: Schema.number().min(1).step(1).i18n({ en: 'Host session control reply limit; default 1 MiB, adjustable by administrators', zh: '主机会话管理回复容量；默认1 MiB，管理员可调整' }).default(DEFAULT_CONFIG.brokerControlMaxBytes).volatile(),
+    oneShotSandbox: Schema.union(['read-only', 'workspace-write', 'danger-full-access']).i18n({ en: 'One-shot sandbox; workspace changes are allowed by default', zh: '单次任务沙箱；默认允许工作区内修改' }).default(DEFAULT_CONFIG.oneShotSandbox).volatile(),
+    oneShotApproval: Schema.const('never').i18n({ en: 'Non-interactive approval; permissions follow the launch policy, never automatic approval', zh: '单次模式无交互审批；权限由启动策略决定，不表示自动批准' }).default(DEFAULT_CONFIG.oneShotApproval).volatile(),
+});
+/** DSH volatile settings are handles; adapters freeze their values once per invocation. */
+export function readConfig(config) {
+    return Object.fromEntries(Object.entries(config).map(([key, value]) => [key, typeof value === 'object' && value !== null && 'get' in value ? value.get() : value]));
+}
+function readPointer(options, agent) {
+    const last = options.messages.findLast(message => message.role === 'assistant' && !isWorkspaceNoticeMessage(message));
+    if (!last || last.role !== 'assistant')
+        return;
+    if (last.source.provider !== options.provider || last.source.replayState === undefined)
+        throw new NeedError('SESSION_STATE_MISSING', '已有对话缺少当前模型的远端恢复标识，请新建会话', '当前模型的远端恢复记录');
+    const envelope = last.source.replayState;
+    const pointer = envelope?.response;
+    if (pointer?.version !== 2 || pointer.agent !== agent.id || (pointer.mode !== 'session' && pointer.mode !== 'one-shot') || ![pointer.identity, pointer.cwd, pointer.sessionId].every(value => typeof value === 'string' && value.length > 0))
+        throw new NeedError('SESSION_STATE_INVALID', '原对话缺少新版工作区/模型绑定，不能静默迁移，请新建会话', '有效的新一代远端会话恢复记录');
+    if (options.sessionId && pointer.dshSessionId !== options.sessionId)
+        throw new NeedError('SESSION_CONTEXT_MISMATCH', '此恢复记录属于另一会话，复制或分叉后不能沿用原远端进程，请新建会话', '当前DSH会话自己的远端恢复记录');
+    return pointer;
+}
+export class CodexRemoteAdapter extends LlmAdapter {
+    resolveRuntime;
+    approve;
+    providerName;
+    agent;
+    readImage;
+    config;
+    sessions = new Map();
+    turns = new Map();
+    lifetime = new AbortController();
+    constructor(config, resolveRuntime, approve, providerName = () => PROVIDER_NAMES.en, agent = CODEX_AGENT, readImage) {
+        super();
+        this.resolveRuntime = resolveRuntime;
+        this.approve = approve;
+        this.providerName = providerName;
+        this.agent = agent;
+        this.readImage = readImage;
+        this.config = typeof config === 'function' ? config : () => config;
+    }
+    providerInfo(provider) { return { id: provider, name: this.providerName() }; }
+    async listModels(provider) { return [{ provider, id: 'remote', name: this.providerName(), inputModalities: ((this.agent.oneShot && this.config().mode === 'one-shot') ? ['text'] : ['text', 'image']) }]; }
+    providerRetryPolicy() { return { mode: 'normal', maxRetries: 0, retryableCodes: [], initialDelayMs: 0, maxDelayMs: 0, jitterRatio: 0 }; }
+    async disposeSession(sessionId) {
+        this.turns.get(sessionId)?.abort();
+        const current = this.sessions.get(sessionId);
+        if (!current)
+            return;
+        this.sessions.delete(sessionId);
+        current.session.close();
+        await current.runtime.dispose?.();
+    }
+    async dispose() {
+        this.lifetime.abort();
+        const results = await Promise.allSettled([...this.sessions.keys()].map(id => this.disposeSession(id)));
+        const failure = results.find(result => result.status === 'rejected');
+        if (failure?.status === 'rejected')
+            throw failure.reason;
+    }
+    async *stream(options) {
+        try {
+            yield* this.generate(options);
+        }
+        catch (error) {
+            if (error instanceof NeedError) {
+                const rpc = /RPC 错误码 (-?\d+)/u.exec(error.requires)?.[1];
+                const message = employeeFailure(error.code) + (rpc ? `（技术详情：RPC 错误码 ${rpc}）` : '');
+                throw new LlmError(message, error.code, { cause: new Error(`诊断代码：${error.code}；${error.requires}`) });
+            }
+            throw error;
+        }
+    }
+    async *generate(original) {
+        if (original.purpose)
+            throw new NeedError('PURPOSE_UNSUPPORTED', '此远程模型不处理后台标题或上下文整理请求，未发送模型请求', '独立的后台请求能力');
+        if (this.lifetime.signal.aborted)
+            throw new NeedError('DISPOSED', '远程模型插件已关闭', '启用远程模型插件');
+        const key = original.sessionId;
+        if (key && this.turns.has(key))
+            throw new NeedError('TURN_BUSY', '当前会话正在处理上一轮', '等待上一轮结束');
+        const turn = new AbortController();
+        if (key)
+            this.turns.set(key, turn);
+        const signal = AbortSignal.any([this.lifetime.signal, turn.signal, ...(original.signal ? [original.signal] : [])]);
+        const options = { ...original, signal };
+        let runtime;
+        let session;
+        let live;
+        let succeeded = false;
+        let remoteAttempted = false;
+        let activeMapper;
+        const config = this.config();
+        const mode = this.agent.oneShot ? config.mode : 'session';
+        try {
+            if (!mode || (mode === 'session' && (!Number.isSafeInteger(config.acpMaxMessageBytes) || config.acpMaxMessageBytes < 1)))
+                throw new NeedError('SETTINGS_REQUIRED', '远程模型连接设置无效，请联系管理员检查', '有效的mode/acpMaxMessageBytes');
+            const previous = readPointer(options, this.agent);
+            if (previous && previous.mode !== mode)
+                throw new NeedError('SESSION_CONTEXT_MISMATCH', '运行模式与原会话不一致，请新建会话', '原会话模式');
+            live = key ? this.sessions.get(key) : undefined;
+            if (live?.failure)
+                throw new NeedError('SESSION_STATE_UNCONFIRMED', '上轮远端状态未确认，不能自动重发或重开，请新建会话并核对项目', '管理员核对原会话状态');
+            if (live && !previous)
+                throw new NeedError('SESSION_STATE_MISSING', '上一轮回复尚无持久恢复记录，不能继续当前远端会话', '原会话的持久回复记录');
+            const configuration = JSON.stringify([mode, config.acpMaxMessageBytes, config.brokerMaxFrameBytes, config.brokerControlMaxBytes]);
+            if (live && live.configuration !== configuration)
+                throw new NeedError('SESSION_CONTEXT_MISMATCH', '会话运行设置已改变，请新建会话', '原会话运行设置');
+            const request = { sessionId: options.sessionId, mode, cwd: previous?.cwd, identity: previous?.identity, bindingId: previous?.bindingId, workspaceId: previous?.workspaceId, agent: this.agent, retainProcess: !!key && mode === 'session', signal, brokerSettings: Object.freeze({ brokerMaxFrameBytes: config.brokerMaxFrameBytes, brokerControlMaxBytes: config.brokerControlMaxBytes }) };
+            await this.resolveRuntime.preflight?.(request);
+            const input = await prepareInput(options, this.readImage);
+            const contextSha256 = createHash('sha256').update(input.systemPrompt ?? '').digest('hex');
+            if (previous && this.agent.loginProvider === 'claude' && previous.contextSha256 !== contextSha256)
+                throw new NeedError('SYSTEM_PROMPT_UPDATE_PENDING', 'Claude原会话的系统或开发者要求已变化；主机仅承诺下次上下文整理后生效，本轮未发送，请新建会话应用新要求', '新建Claude会话以立即应用当前系统与开发者要求');
+            if (live) {
+                live.session.validateContext({ systemPrompt: input.systemPrompt });
+                live.session.validatePrompt(input.prompt);
+            }
+            if (mode === 'one-shot' && (input.systemPrompt || input.prompt.some(block => block.type !== 'text')))
+                throw new NeedError('ONESHOT_CONTEXT_REQUIRED', '首版单次模式不支持图片或系统/开发者上下文，请使用会话模式', 'Codex会话模式');
+            if (mode === 'session' && Buffer.byteLength(JSON.stringify({ prompt: input.prompt, systemPrompt: input.systemPrompt }), 'utf8') > config.acpMaxMessageBytes)
+                throw new NeedError('ACP_MESSAGE_TOO_LARGE', '本轮输入超过已设置的会话消息容量，未截断或发送', '管理员调整acpMaxMessageBytes');
+            runtime = await this.resolveRuntime(request);
+            signal.throwIfAborted();
+            if (previous && (previous.identity !== runtime.identity || previous.cwd !== runtime.cwd || previous.bindingId && previous.bindingId !== runtime.binding?.bindingId || previous.workspaceId && previous.workspaceId !== runtime.binding?.workspaceId))
+                throw new NeedError('SESSION_CONTEXT_MISMATCH', '原会话的员工主机或工作区已改变，请新建会话', '原会话的可信目标和工作区');
+            const details = runtime.details;
+            if (!details)
+                throw new NeedError('TECHNICAL_DETAILS_UNAVAILABLE', '技术详情暂不可用，请更新远程主机连接组件。', 'L技术详情持久接收能力');
+            const mapper = new StreamMapper(mode === 'session' ? (live ? live.usageSnapshot : previous ? (previous.usageSnapshot ?? null) : undefined) : undefined, observation => details.record(observation));
+            activeMapper = mapper;
+            let id;
+            let stop;
+            if (runtime.workspaceNotice) {
+                yield* mapper.text(runtime.workspaceNotice.text);
+                yield* mapper.flush();
+            }
+            if (mode === 'session') {
+                if (live && live.runtime !== runtime)
+                    throw new NeedError('SESSION_TRANSPORT_MISMATCH', '原会话的主机通道已更换，不能自动切换进程', '原主机会话通道');
+                if (!runtime.acpTransport)
+                    throw new NeedError('DEPENDENCY_REQUIRED', '我需要该员工主机上的ACP通道', 'S提供的ACP命令与aw-session');
+                const queue = [];
+                let wake;
+                let done = false;
+                let failure;
+                const push = (chunks) => { queue.push(...chunks); wake?.(); wake = undefined; };
+                const hooks = { broker: runtime.broker, approve: (permission, approvalSignal) => this.approve?.(permission, approvalSignal, options) ?? Promise.resolve('unavailable'), onUpdate: notification => { try {
+                        push(mapper.acp(notification.update));
+                    }
+                    catch (error) {
+                        failure = error;
+                        session?.close();
+                    } }, onResponse: response => push(mapper.acpResponse(response)), onDetail: detail => details.record(detail) };
+                const fresh = !live;
+                if (fresh) {
+                    const transport = runtime.acpTransport instanceof acp.AgentApp || runtime.acpTransport instanceof unstable.AgentApp ? runtime.acpTransport : acp.ndJsonStream(runtime.acpTransport.writable, runtime.acpTransport.readable, { maxMessageBytes: config.acpMaxMessageBytes });
+                    session = new AcpSession(transport, hooks);
+                    live = { session, runtime, configuration, usageSnapshot: mapper.usageSnapshot };
+                    if (key)
+                        this.sessions.set(key, live);
+                }
+                else {
+                    session = live.session;
+                    session.setHooks(hooks);
+                    if (previous?.sessionId !== session.id)
+                        throw new NeedError('SESSION_STATE_INVALID', '持久会话标识与当前进程不一致', '原会话的恢复标识');
+                }
+                const task = (async () => {
+                    remoteAttempted = true;
+                    if (fresh)
+                        await session.start(runtime.cwd, previous?.sessionId, signal, { systemPrompt: input.systemPrompt });
+                    else {
+                        const updated = await session.updateContext({ systemPrompt: input.systemPrompt }, signal);
+                        if (updated && this.agent.loginProvider === 'claude')
+                            throw new NeedError('SYSTEM_PROMPT_UPDATE_PENDING', 'Claude原会话的系统或开发者要求已变化；主机仅承诺下次上下文整理后生效，本轮未发送，请新建会话应用新要求', '新建Claude会话以立即应用当前系统与开发者要求');
+                    }
+                    await details.flush();
+                    details.beginTurn(runtime.detailContext?.() ?? { turn: null, step: null });
+                    id = session.id;
+                    try {
+                        return await session.prompt(input.prompt, signal);
+                    }
+                    finally {
+                        details.endTurn();
+                    }
+                })();
+                void task.then(value => { stop = value; }, error => { failure ??= runtime.broker?.error ?? error; }).finally(() => { done = true; wake?.(); wake = undefined; });
+                while (!done || queue.length) {
+                    if (queue.length)
+                        yield queue.shift();
+                    else
+                        await new Promise(resolve => { wake = resolve; });
+                }
+                if (failure)
+                    throw failure;
+                if (stop === 'cancelled')
+                    throw new NeedError('ABORTED', '远端本轮已取消', '核对主机任务状态');
+                if (stop === 'refusal')
+                    for (const chunk of mapper.text('\n[远端拒绝] 此请求未执行。\n'))
+                        yield chunk;
+            }
+            else {
+                if (!runtime.oneShot)
+                    throw new NeedError('DEPENDENCY_REQUIRED', '我需要主机单次运行助手', 'S安装的aw-codex-once');
+                details.beginTurn(runtime.detailContext?.() ?? { turn: null, step: null });
+                const text = input.prompt.map(block => block.type === 'text' ? block.text : '').join('\n');
+                for await (const event of runOneShot(runtime.oneShot, { wrapperPath: fileURLToPath(new URL('./sdk-ssh-wrapper.js', import.meta.url)), sandboxMode: config.oneShotSandbox, approvalPolicy: config.oneShotApproval }, text, previous?.sessionId, signal)) {
+                    if (event.type === 'thread.started')
+                        id = event.thread_id;
+                    for (const chunk of mapper.sdk(event))
+                        yield chunk;
+                }
+            }
+            details.endTurn();
+            await details.flush();
+            if (!id)
+                throw new NeedError('SESSION_ID_MISSING', '远端没有返回会话标识', '有效的远端会话标识');
+            if (live)
+                live.usageSnapshot = mapper.usageSnapshot;
+            yield* mapper.flush();
+            const pointer = { ...(runtime.workspaceNotice ? { presentation: { workspaceNotice: runtime.workspaceNotice } } : {}), version: 2, agent: this.agent.id, contextSha256, ...(mode === 'session' ? { usageSnapshot: mapper.usageSnapshot } : {}), ...(options.sessionId ? { dshSessionId: options.sessionId } : {}), mode, identity: runtime.identity, cwd: runtime.cwd, sessionId: id, ...(runtime.binding ? { bindingId: runtime.binding.bindingId, workspaceId: runtime.binding.workspaceId } : {}) };
+            succeeded = true;
+            yield { type: 'finish', reason: { kind: stop === 'max_tokens' || stop === 'max_turn_requests' ? 'max-tokens' : 'stop' }, replayState: { response: pointer } };
+        }
+        catch (error) {
+            if (live && (remoteAttempted || runtime === live.runtime))
+                live.failure = { cause: error };
+            let reportingFailure;
+            try {
+                await runtime?.details?.flush();
+            }
+            catch (failure) {
+                reportingFailure = { cause: failure };
+            }
+            if (activeMapper)
+                yield* activeMapper.flush();
+            if (reportingFailure !== undefined)
+                throw reportingFailure.cause;
+            throw error;
+        }
+        finally {
+            if (!succeeded || !key || mode !== 'session') {
+                session?.close();
+                await runtime?.dispose?.();
+            }
+            if (key && this.turns.get(key) === turn)
+                this.turns.delete(key);
+        }
+    }
+}
+/** One official registration owns both routes, preserving opaque replay ownership. */
+export class RemoteAgentsAdapter extends LlmAdapter {
+    adapters = new Map();
+    constructor(config, makeRuntime, approve, nameFor, readImage) { super(); for (const agent of AGENTS)
+        this.adapters.set(agent.id, new CodexRemoteAdapter(config, makeRuntime(agent), approve, () => nameFor(agent), agent, readImage)); }
+    adapter(provider) { const adapter = this.adapters.get(provider); if (!adapter)
+        throw new LlmError('远程模型未注册', 'PROVIDER_NOT_FOUND'); return adapter; }
+    providerInfo(provider) { return this.adapter(provider).providerInfo(provider); }
+    listModels(provider) { return this.adapter(provider).listModels(provider); }
+    providerRetryPolicy() { return { mode: 'normal', maxRetries: 0, retryableCodes: [], initialDelayMs: 0, maxDelayMs: 0, jitterRatio: 0 }; }
+    stream(options) { return this.adapter(options.provider).stream(options); }
+    async disposeSession(sessionId) { await Promise.all([...this.adapters.values()].map(adapter => adapter.disposeSession(sessionId))); }
+    async dispose() { await Promise.all([...this.adapters.values()].map(adapter => adapter.dispose())); }
+}
+export function apply(ctx, live) {
+    const config = () => readConfig(live);
+    const get = () => ctx.get('aiWorkbenchConnect');
+    let language = 'en';
+    const readImage = async (ref, signal) => {
+        const attachments = ctx.get('attachments');
+        if (typeof attachments?.readImage !== 'function')
+            throw new NeedError('ATTACHMENT_REQUIRED', '我需要官方附件组件读取这张图片', '官方attachments.readImage');
+        return attachments.readImage(ref, signal);
+    };
+    const openByAgent = new Map(AGENTS.map(agent => [agent.id, brokerFactory(get, undefined, config)]));
+    const detailManagers = new Map();
+    const adapter = new RemoteAgentsAdapter(config, agent => connectProvider(get, { agent, notice: createWorkspaceNoticeConsumer(ctx, agent), details: async (request, api, connection, target) => {
+            const profile = ctx.get('profileContext');
+            if (typeof profile?.dir !== 'string')
+                throw new NeedError('TECHNICAL_DETAILS_UNAVAILABLE', '技术详情暂不可用：缺少官方profile目录。', '官方profileContext.dir');
+            let manager = detailManagers.get(profile.dir);
+            if (!manager) {
+                manager = createRemoteDetails({ profileDir: profile.dir, getApi: get });
+                detailManagers.set(profile.dir, manager);
+            }
+            return manager.open({ sessionId: request.sessionId, provider: agent.loginProvider, identity: `${target.username}@${target.host}:${target.port}`, connection });
+        }, open: async (...args) => {
+            const runtime = await openByAgent.get(agent.id)(...args);
+            runtime.detailContext = () => {
+                const events = args[2].sessionId ? ctx.get('agents')?.get(SessionId(args[2].sessionId))?.session.snapshotEvents() : undefined;
+                let turn = null, step = null;
+                for (const event of events ?? []) {
+                    if (event.type === 'turn/start') {
+                        turn = event.data.turn;
+                        step = null;
+                    }
+                    else if (event.type === 'turn/end') {
+                        turn = null;
+                        step = null;
+                    }
+                    else if (event.type === 'step/start' && event.data.turn === turn)
+                        step = event.data.step;
+                    else if (event.type === 'step/end')
+                        step = null;
+                }
+                return { turn, step };
+            };
+            return runtime;
+        } }), dshApproval(ctx), agent => agent.name[language], readImage);
+    const ids = AGENTS.map(agent => agent.id);
+    const entries = () => AGENTS.map(agent => ({ provider: agent.id, displayName: agent.name[language], settingsNs: settingsNamespace, settingsPath: [] }));
+    const directory = ctx.llm.registerConfigurableProviders(entries());
+    const registration = ctx.llm.registerAdapter(ids, adapter);
+    new ProviderLocaleRemote(ctx, next => { language = next; directory.replace(entries()); registration.replace(ids); });
+    const cleanup = (id) => adapter.disposeSession(id);
+    ctx.on('agent/disposed', ({ agent }) => cleanup(agent.session.id));
+    ctx.on('session/disposed', session => cleanup(session.id));
+    ctx.on('workspace/session-stop', ((request) => cleanup(request.sessionId)));
+    ctx.effect(() => () => adapter.dispose());
+}
+export function dshApproval(ctx) {
+    return async (request, signal, options, context) => {
+        const agent = options.sessionId ? ctx.get('agents')?.get(options.sessionId) : undefined;
+        const approval = ctx.get('approval');
+        if (!agent || !approval)
+            return 'unavailable';
+        return approval.request({ agent, toolName: request.toolCall.name ?? request.toolCall.title ?? '远端工具',
+            reason: `${context ?? '主机'} · 会话 ${request.sessionId}：${request.toolCall.title ?? request.toolCall.toolCallId}`, signal });
+    };
+}

package/dist/input.d.ts

@@ -0,0 +1,12 @@
+import type { ContentBlock as AcpContentBlock } from '@agentclientprotocol/sdk';
+import type { GenerateOptions, ImageBlock } from '@deepseek-ai/dsh-llm';
+export type ImageReader = (ref: ImageBlock['attachment'], signal?: AbortSignal) => Promise<{
+    ref: ImageBlock['attachment'];
+    data: Uint8Array;
+}>;
+export interface PreparedInput {
+    prompt: AcpContentBlock[];
+    systemPrompt?: string;
+}
+/** The attachment service supplies verified bytes; client paths never cross SSH. */
+export declare function prepareInput(options: GenerateOptions, readImage?: ImageReader): Promise<PreparedInput>;

package/dist/input.js

@@ -0,0 +1,49 @@
+import { NeedError } from "./remote.js";
+import { isWorkspaceNoticeMessage, withoutWorkspaceNotice } from "./workspace-notice.js";
+/** The attachment service supplies verified bytes; client paths never cross SSH. */
+export async function prepareInput(options, readImage) {
+    options.signal?.throwIfAborted();
+    const messages = options.messages.filter(message => !isWorkspaceNoticeMessage(message)).map(withoutWorkspaceNotice);
+    const context = [];
+    if (options.system)
+        context.push('系统上下文：\n' + options.system);
+    for (const message of messages) {
+        if (message.role !== 'system' && message.role !== 'developer')
+            continue;
+        const parts = message.content.map(block => block.type === 'text' ? block.text : JSON.stringify(block));
+        if (parts.length)
+            context.push((message.role === 'system' ? '系统上下文：' : '开发者上下文：') + '\n' + parts.join('\n'));
+    }
+    const after = messages.findLastIndex(message => message.role === 'assistant');
+    const users = messages.slice(after + 1).filter(message => message.role === 'user');
+    if (!users.length)
+        throw new NeedError('INPUT_REQUIRED', '我需要本轮用户输入', '用户输入');
+    const prompt = [];
+    for (const message of users) {
+        for (const block of message.content) {
+            options.signal?.throwIfAborted();
+            if (block.type === 'text') {
+                prompt.push({ type: 'text', text: block.text });
+                continue;
+            }
+            if (block.type === 'image') {
+                if (block.offloaded) {
+                    prompt.push({ type: 'text', text: `图片 ${block.attachment.name ?? block.attachment.attachmentId} 已按官方会话策略移出当前上下文。` });
+                    continue;
+                }
+                if (!readImage)
+                    throw new NeedError('ATTACHMENT_REQUIRED', '我需要官方附件组件读取这张图片', '官方attachments.readImage');
+                const image = await readImage(block.attachment, options.signal);
+                options.signal?.throwIfAborted();
+                if (!image || !(image.data instanceof Uint8Array) || image.ref?.attachmentId !== block.attachment.attachmentId || !['image/png', 'image/jpeg', 'image/webp', 'image/gif'].includes(image.ref.mediaType) || image.ref.bytes !== image.data.byteLength)
+                    throw new NeedError('ATTACHMENT_INVALID', '图片附件没有返回匹配的已核验内容', '官方核验的图片字节与媒体类型');
+                prompt.push({ type: 'image', mimeType: image.ref.mediaType, data: Buffer.from(image.data).toString('base64') });
+                continue;
+            }
+            throw new NeedError('INPUT_TYPE_REQUIRED', `我需要此输入类型的远程转接能力：${block.type}`, '对应类型的公开ACP输入映射');
+        }
+    }
+    if (!prompt.length)
+        throw new NeedError('INPUT_REQUIRED', '我需要本轮用户输入', '用户输入');
+    return { prompt, ...(context.length ? { systemPrompt: context.join('\n\n') } : {}) };
+}

package/dist/interaction.d.ts

@@ -0,0 +1,19 @@
+/** Legacy programmatic test seam only. Production X never opens user questions. */
+export interface Invocation {
+    sessionId?: string;
+    signal?: AbortSignal;
+}
+export interface InteractionQuestion {
+    id: string;
+    question: string;
+    detail?: string;
+    options?: {
+        label: string;
+    }[];
+}
+export interface InteractionAnswer {
+    id: string;
+    selected: string[];
+    custom?: string;
+}
+export type Interaction = (question: InteractionQuestion, invocation: Invocation) => Promise<InteractionAnswer | undefined>;

package/dist/interaction.js

@@ -0,0 +1 @@
+export {};

package/dist/job.d.ts

@@ -0,0 +1,17 @@
+import { type ChildProcess } from 'node:child_process';
+import { type DevelopmentSshTarget } from './remote.ts';
+import { type ConnectTarget } from './provider.ts';
+export interface JobSpec {
+    target: DevelopmentSshTarget | ConnectTarget;
+    cwd: string;
+    runner: string;
+    runnerKind: 'executable' | 'node-source';
+    root: string;
+    codex: string;
+    id: string;
+    /** Test/programmatic transport seam only; never an employee setting. */
+    sshExecutable?: string;
+}
+export type OneShotRuntime = Omit<JobSpec, 'id' | 'sshExecutable'>;
+export declare function jobCommand(spec: JobSpec, op: 'prepare' | 'stage' | 'run' | 'kill'): string;
+export declare function executeJob(spec: JobSpec, op: 'prepare' | 'stage' | 'run' | 'kill', input?: string, onSpawn?: (child: ChildProcess) => void, inheritOutput?: boolean, signal?: AbortSignal): Promise<number | null>;

package/dist/job.js

@@ -0,0 +1,57 @@
+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 { shellQuote, sshArgs, NeedError } from "./remote.js";
+import { validateTarget } from "./provider.js";
+import { protectedOneShotLayout } from "./host-layout.js";
+export function jobCommand(spec, op) {
+    if (!/^[a-f0-9]{32}$/.test(spec.id) || !['executable', 'node-source'].includes(spec.runnerKind) || ![spec.cwd, spec.root, spec.runner, spec.codex].every(p => p.startsWith('/') && !p.includes('\0'))) {
+        throw new NeedError('INVALID_RUNTIME', '我需要主机提供有效的单次运行上下文', '主机程序与工作目录');
+    }
+    if (!('kind' in spec.target)) {
+        const layout = protectedOneShotLayout(spec.target);
+        if (spec.runnerKind !== layout.runnerKind || spec.runner !== layout.runner || spec.root !== layout.root || spec.codex !== layout.codex)
+            throw new NeedError('INVALID_RUNTIME', '远程主机的单次运行位置需要管理员核对', 'S安装的受保护单次运行路径');
+    }
+    return [...(spec.runnerKind === 'node-source' ? ['node'] : []), spec.runner, op, spec.root, spec.id].map(shellQuote).join(' ');
+}
+export async function executeJob(spec, op, input, onSpawn, inheritOutput = false, signal) {
+    signal?.throwIfAborted();
+    const command = jobCommand(spec, op);
+    let args;
+    if ('kind' in spec.target) {
+        args = sshArgs(spec.target, command, op !== 'stage');
+    }
+    else {
+        validateTarget(spec.target);
+        if (spec.runnerKind !== 'executable')
+            throw new NeedError('INVALID_RUNTIME', '主机单次助手必须使用管理员安装的启动器', 'host-layout 单次启动器');
+        let supplied;
+        try {
+            const moduleName = '@ai-workbench/connect';
+            supplied = await import(__rewriteRelativeImportExtension(moduleName));
+            if (typeof supplied.sshArgs !== 'function')
+                throw Error('missing sshArgs');
+        }
+        catch {
+            throw new NeedError('DEPENDENCY_REQUIRED', '我需要连接组件提供可信连接', '@ai-workbench/connect sshArgs');
+        }
+        args = [...(op === 'stage' ? [] : ['-n']), ...supplied.sshArgs(spec.target), command];
+    }
+    signal?.throwIfAborted();
+    const child = spawn(spec.sshExecutable ?? 'ssh', args, { stdio: ['pipe', inheritOutput ? 'inherit' : 'ignore', 'ignore'], signal });
+    onSpawn?.(child);
+    child.stdin.on('error', () => { }); // Exit status owns transport failure; EPIPE cannot mean success.
+    child.stdin.end(input);
+    return new Promise((resolve, reject) => {
+        let failed = false;
+        child.on('error', () => { failed = true; });
+        child.on('close', code => failed ? reject(new NeedError('SSH_FAILED', 'SSH 启动失败或已取消，根因未查明', '可用的员工连接')) : resolve(code));
+    });
+}

package/dist/mapping.d.ts

@@ -0,0 +1,46 @@
+import type { StreamChunk } from '@deepseek-ai/dsh-llm';
+import type { PromptResponse, SessionUpdate } from '@agentclientprotocol/sdk/unstable';
+import type { ThreadEvent } from '@openai/codex-sdk';
+import { type SanitizedObservation } from './conversation-details.ts';
+/** Persist alongside the exact remote session identity; null means no trusted baseline. */
+export type UsageSnapshot = {
+    version: 1;
+    kind: 'zero';
+} | {
+    version: 1;
+    kind: 'cumulative';
+    source: 'usage' | 'quota';
+    inputTokens: number;
+    outputTokens: number;
+    cachedReadTokens?: number;
+    cachedWriteTokens?: number;
+    thoughtTokens?: number;
+    totalTokens?: number;
+    /** A response was missing or unusable; the next complete response only re-establishes a baseline. */
+    gap?: true;
+};
+/** Only model text enters DSH blocks; remote operations remain diagnostic observations. */
+export declare class StreamMapper {
+    private index;
+    private active;
+    private seen;
+    private baseline;
+    private readonly observations;
+    private readonly onDiagnostic;
+    /** Omitted argument is exclusively for a known new session; pass null on unknown resume. */
+    constructor(previousUsage?: UsageSnapshot | null, onDiagnostic?: (observation: Readonly<SanitizedObservation>) => void);
+    get usageSnapshot(): UsageSnapshot | null;
+    get diagnostics(): readonly Readonly<SanitizedObservation>[];
+    private diagnostic;
+    private usageWarning;
+    text(text: string, reasoning?: boolean): StreamChunk[];
+    /** Close the current text or reasoning block once, before the stream settles. */
+    flush(): StreamChunk[];
+    acp(update: SessionUpdate): StreamChunk[];
+    /** ACP usage and the fixed Claude quota both accumulate across the session, not per turn. */
+    acpResponse(response: PromptResponse): StreamChunk[];
+    private usageGap;
+    private cumulativeUsage;
+    private usage;
+    sdk(event: ThreadEvent): StreamChunk[];
+}