@ai-workbench/remote-agent 0.8.2 → 0.8.5

package/dist/broker-runtime.js

@@ -0,0 +1,302 @@
+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 { BrokerTransport, brokerCommand, brokerId, legacyBrokerId, sshIo, controlJson } from "./broker.js";
+import { CODEX_AGENT } from "./agents.js";
+import { protectedOneShotLayout } from "./host-layout.js";
+import { NeedError } from "./remote.js";
+import { identity, unwrap, validateTarget, sameTarget } from "./provider.js";
+import { StageTiming } from "./stage-timing.js";
+import { recoveryKey } from "./recovery.js";
+const need = (code) => new NeedError(code, '原主机会话暂时无法安全接续，本轮尚未发送', '技术详情中的原会话状态');
+const modern = (entry) => Object.hasOwn(entry, 'instanceId');
+function validEntry(entry) {
+    if (!entry || typeof entry.id !== 'string' || !Number.isSafeInteger(entry.pid) || entry.pid < 1 || !['running', 'exited'].includes(entry.state) || ![entry.firstSequence, entry.lastSequence].every(Number.isSafeInteger) || entry.lastSequence < 0 || entry.firstSequence < 1 || entry.firstSequence > entry.lastSequence + 1)
+        throw need('BROKER_PROTOCOL_INVALID');
+    if (modern(entry) && (typeof entry.instanceId !== 'string' || !/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/.test(entry.instanceId) || !Number.isSafeInteger(entry.controlMaxBytes) || entry.controlMaxBytes < 1))
+        throw need('BROKER_PROTOCOL_INVALID');
+}
+async function leaseWait(ms, signal) {
+    if (!Number.isSafeInteger(ms) || ms < 0 || ms > 2147483647)
+        throw need('LEASE_POLICY_INVALID');
+    signal?.throwIfAborted();
+    await new Promise((resolve, reject) => { const clear = () => signal?.removeEventListener('abort', abort); const timer = setTimeout(() => { clear(); resolve(); }, ms); const abort = () => { clearTimeout(timer); clear(); reject(need('ABORTED')); }; signal?.addEventListener('abort', abort, { once: true }); if (signal?.aborted)
+        abort(); });
+}
+/** Test ports are explicit; deployed code always supplies the official-profile journal. */
+export function brokerFactory(get, _ask, configuration, provided) {
+    const active = new Set();
+    const retained = new Map();
+    const testJournals = new Map();
+    const open = async (target, project, initialRequest) => {
+        let request = initialRequest;
+        const settings = request.brokerSettings ?? (typeof configuration === 'function' ? configuration() : configuration);
+        const agent = request.agent ?? CODEX_AGENT;
+        if (!request.sessionId)
+            throw need('SESSION_REQUIRED');
+        if (request.mode === 'one-shot') {
+            const key = 'one-shot/' + identity(target) + '/' + agent.id + '/' + request.sessionId;
+            if (active.has(key))
+                throw need('TURN_BUSY');
+            const layout = protectedOneShotLayout(target);
+            active.add(key);
+            return { identity: identity(target), cwd: project.path, oneShot: { target, cwd: project.path, ...layout }, dispose: async () => { active.delete(key); } };
+        }
+        if (![settings.brokerMaxFrameBytes, settings.brokerControlMaxBytes].every(n => Number.isSafeInteger(n) && n > 0))
+            throw need('SETTINGS_REQUIRED');
+        const key = recoveryKey([identity(target), agent.id, request.sessionId]);
+        const scope = recoveryKey([target.host, target.username, target.port, target.proxyCommand, target.knownHostsFile, target.projectRoot, target.session, project.path, agent.id, settings, request.bindingId, request.workspaceId, request.contextSha256]);
+        const existing = request.retainProcess ? retained.get(key) : undefined;
+        if (existing) {
+            if (existing.scope !== scope)
+                throw need('SESSION_CONTEXT_MISMATCH');
+            if (existing.runtime.broker?.error)
+                throw existing.runtime.broker.error;
+            existing.update(request);
+            existing.runtime.restartNotice = undefined;
+            existing.runtime.recoveredSession = undefined;
+            return existing.runtime;
+        }
+        if (active.has(key))
+            throw need('TURN_BUSY');
+        active.add(key);
+        try {
+            const journal = request.recoveryJournal ?? provided?.journal?.(key) ?? (provided?.io ? { read: async () => structuredClone(testJournals.get(key)), write: async (value) => { testJournals.set(key, structuredClone(value)); } } : undefined);
+            if (!journal)
+                throw need('RECOVERY_STORAGE_REQUIRED');
+            let state = await journal.read();
+            if (state && state.scope !== scope)
+                throw need('SESSION_CONTEXT_MISMATCH');
+            let argv = provided?.argv;
+            if (!provided?.io && !argv) {
+                const name = '@ai-workbench/connect';
+                const supplied = await import(__rewriteRelativeImportExtension(name));
+                if (typeof supplied.sshArgs !== 'function')
+                    throw need('DEPENDENCY_REQUIRED');
+                argv = supplied.sshArgs;
+            }
+            const ioFor = (t) => provided?.io?.(t) ?? sshIo(t, argv, settings.brokerControlMaxBytes);
+            let io = ioFor(target);
+            const command = (args) => brokerCommand(target, args);
+            let timing = request.timing ?? new StageTiming();
+            const validate = async (cleanup = false) => { if (!cleanup)
+                request.signal?.throwIfAborted(); await request.validateContext?.(cleanup); if (!cleanup)
+                request.signal?.throwIfAborted(); };
+            const report = async (code, extra = {}, cleanup = false) => { request.detailChannel?.record({ kind: 'need', severity: 'warning', code, summary: '远端会话恢复状态：' + code, payload: extra }); await request.detailChannel?.flush(); await validate(cleanup); };
+            const list = async (cleanup = false) => timing.run('broker-list', async () => { const rows = controlJson(await io.run(command(['list']), cleanup ? undefined : request.signal)); if (!Array.isArray(rows) || rows.some(row => typeof row?.id !== 'string'))
+                throw need('BROKER_PROTOCOL_INVALID'); return rows; });
+            let rows = await list();
+            const id = brokerId(request.sessionId, agent.id), oldId = legacyBrokerId(request.sessionId, agent.id);
+            let restarted = false;
+            const attachArgs = (entry, after) => ['attach', entry.id, '--after', String(after), '--framed', ...(modern(entry) ? ['--leased', '--if-instance', entry.instanceId] : [])];
+            const connectWithLease = async (transport, entry, cleanup = false) => {
+                try {
+                    await transport.connect();
+                }
+                catch (error) {
+                    if (!(error instanceof NeedError) || error.code !== 'ATTACH_BUSY' || !modern(entry))
+                        throw error;
+                    const current = (await list(cleanup)).find(row => row.id === entry.id);
+                    if (!current || current.instanceId !== entry.instanceId)
+                        throw need('SESSION_INSTANCE_MISMATCH');
+                    validEntry(current);
+                    const policy = current.lifecycle;
+                    if (!policy || typeof policy.enabled !== 'boolean' || typeof policy.attached !== 'boolean')
+                        throw need('LEASE_POLICY_INVALID');
+                    if (policy.attached && !policy.enabled)
+                        throw need('SESSION_IN_USE');
+                    const remaining = policy.attached ? policy.remainingLeaseMs : 0;
+                    if (remaining === undefined || remaining === null || !Number.isSafeInteger(remaining) || remaining < 0)
+                        throw need('LEASE_POLICY_INVALID');
+                    await report('WAITING_PRIOR_CLIENT_LEASE', { brokerId: entry.id, instanceId: entry.instanceId, remainingLeaseMs: remaining }, cleanup);
+                    await leaseWait(remaining, cleanup ? undefined : request.signal);
+                    await validate(cleanup);
+                    try {
+                        await transport.connect();
+                    }
+                    catch (next) {
+                        if (next instanceof NeedError && next.code === 'ATTACH_BUSY')
+                            throw need('SESSION_IN_USE');
+                        throw next;
+                    }
+                }
+            };
+            const claim = async (entry, cleanup = false) => {
+                const probe = new BrokerTransport({ discardOutput: true, onNeed: n => request.detailChannel?.record({ kind: 'need', severity: 'warning', code: n.code, summary: '主机会话连接状态', payload: { brokerId: entry.id, instanceId: entry.instanceId ?? null } }), maxFrameBytes: settings.brokerMaxFrameBytes, initialSequence: entry.lastSequence, instanceId: entry.instanceId, leased: modern(entry), controlMaxBytes: entry.controlMaxBytes, attach: after => io.attach(command(attachArgs(entry, after))) });
+                try {
+                    await connectWithLease(probe, entry, cleanup);
+                }
+                catch (error) {
+                    if (!(entry.state === 'exited' && error instanceof NeedError && error.code === 'AGENT_EXITED')) {
+                        probe.close();
+                        throw error;
+                    }
+                }
+                return probe;
+            };
+            const stop = async (entry, code, owned, cleanup = false, freshOwned = false) => {
+                validEntry(entry);
+                if (!modern(entry))
+                    throw need('BROKER_CAPABILITY_REQUIRED');
+                if (!owned?.online && !freshOwned) {
+                    const current = (await list(cleanup)).find(row => row.id === entry.id);
+                    if (!current) {
+                        await report('SESSION_ALREADY_ABSENT', { brokerId: entry.id, instanceId: entry.instanceId ?? null }, cleanup);
+                        return;
+                    }
+                    validEntry(current);
+                    if (modern(current) !== modern(entry) || current.instanceId !== entry.instanceId)
+                        throw need('SESSION_INSTANCE_MISMATCH');
+                    entry = current;
+                }
+                const probe = owned?.online || freshOwned ? owned : await claim(entry, cleanup);
+                try {
+                    await report(code, { brokerId: entry.id, ...(entry.instanceId ? { instanceId: entry.instanceId } : {}), observedPid: entry.pid, legacySessionSlot: !modern(entry) }, cleanup);
+                    if (entry.state === 'running' && !probe.online && !freshOwned)
+                        throw need('MIGRATION_CLAIM_LOST');
+                    await validate(cleanup);
+                    const ack = controlJson(await io.run(command(['kill', entry.id, ...(entry.instanceId ? ['--if-instance', entry.instanceId] : [])]), cleanup ? undefined : request.signal));
+                    if (ack?.type !== 'killed' || ack.id !== entry.id || modern(entry) && ack.instanceId !== entry.instanceId)
+                        throw need('REMOTE_CLEANUP_UNCONFIRMED');
+                    if ((await list(cleanup)).some(row => row.id === entry.id))
+                        throw need('REMOTE_CLEANUP_UNCONFIRMED');
+                }
+                finally {
+                    probe.close();
+                }
+            };
+            const legacy = rows.find(row => row.id === oldId);
+            if (legacy)
+                await report('PRE_0410_TEST_SESSION_NOT_RESUMED', { brokerId: legacy.id, observedPid: legacy.pid, state: legacy.state, instanceId: legacy.instanceId ?? null, reason: 'OLD_TEST_SESSION_COORDINATOR_CLEANUP', decision: '2026-10-22-00:05', approvalReplies: 0 });
+            let entry = rows.find(row => row.id === id);
+            if (entry)
+                validEntry(entry);
+            if (legacy && !entry)
+                restarted = true;
+            let transport;
+            let resume;
+            const build = (entry, after, recovery) => new BrokerTransport({ onNeed: n => request.detailChannel?.record({ kind: 'need', severity: 'warning', code: n.code, summary: '主机会话连接状态', payload: { brokerId: entry.id, instanceId: entry.instanceId } }), maxFrameBytes: settings.brokerMaxFrameBytes, maxMessageBytes: request.acpMaxMessageBytes ?? settings.brokerMaxFrameBytes, initialSequence: after, instanceId: entry.instanceId, leased: true, controlMaxBytes: entry.controlMaxBytes, beforeInput: async () => { await validate(); if (state?.phase !== 'dirty' || state.instanceId !== entry.instanceId) {
+                    const dirty = { version: 1, scope, brokerId: id, instanceId: entry.instanceId, pid: entry.pid, phase: 'dirty' };
+                    await journal.write(dirty);
+                    state = dirty;
+                } await validate(); }, ...(recovery ? { recoverySessionId: recovery.sessionId, onRecoveryUpdate: (message) => { const params = message.params; if (params.update?.sessionUpdate === 'config_option_update' && recovery.modelConfiguration) {
+                        if (!Array.isArray(params.update.configOptions))
+                            throw need('RECOVERY_MODEL_CONFIGURATION_INVALID');
+                        (recovery.configUpdates ??= []).push(structuredClone(params.update.configOptions));
+                    } request.detailChannel?.record({ kind: 'session', severity: 'info', code: 'ACP_IDLE_UPDATE', summary: '恢复期间的远端状态轨迹', method: 'session/update', payload: message.params }); } } : {}), attach: after => io.attach(command(attachArgs(entry, after))), onDisconnect: async () => {
+                    const api = get();
+                    if (!provided?.io) {
+                        if (!api)
+                            throw need('DEPENDENCY_REQUIRED');
+                        const next = unwrap(await api.getSshTarget());
+                        validateTarget(next);
+                        if (!sameTarget(next, target))
+                            throw need('SESSION_CONTEXT_MISMATCH');
+                        io = ioFor(next);
+                    }
+                    await validate();
+                    await connectWithLease(transport, entry);
+                } });
+            if (entry) {
+                if (!modern(entry))
+                    throw need('BROKER_CAPABILITY_REQUIRED');
+                const clean = state?.phase === 'clean' && state.instanceId === entry.instanceId && state.acp?.sessionId === request.resumeSessionId && state.checkpointId === request.recoveryCheckpointId && state.cursor >= entry.firstSequence - 1 && state.cursor <= entry.lastSequence && entry.state === 'running' && await request.verifyRecovery?.() !== false;
+                if (clean) {
+                    transport = build(entry, state.cursor, state.acp);
+                    try {
+                        await timing.run('broker-attach', () => connectWithLease(transport, entry));
+                        await transport.replayThrough(entry.lastSequence, request.signal);
+                        await request.detailChannel?.flush();
+                        await validate();
+                        resume = state.acp;
+                    }
+                    catch (error) {
+                        transport.close();
+                        if (error instanceof NeedError && ['ATTACH_BUSY', 'SESSION_IN_USE', 'SESSION_INSTANCE_MISMATCH', 'ABORTED'].includes(error.code))
+                            throw error;
+                        await report('SESSION_REPLAY_UNRECOVERABLE', { brokerId: id, instanceId: entry.instanceId, reason: error instanceof NeedError ? error.code : 'UNKNOWN_FAILURE', recordedCursor: state?.cursor ?? null, firstSequence: entry.firstSequence, lastSequence: entry.lastSequence });
+                    }
+                }
+                if (!resume) {
+                    await stop(entry, 'SESSION_CHECKPOINT_UNRECOVERABLE', transport);
+                    restarted = true;
+                    entry = undefined;
+                    transport = undefined;
+                }
+            }
+            if (!entry) {
+                if (request.resumeSessionId) {
+                    restarted = true;
+                    await report('SESSION_BROKER_ABSENT', { brokerId: id });
+                }
+                await validate();
+                state = { version: 1, scope, brokerId: id, phase: 'dirty' };
+                await journal.write(state);
+                const started = await timing.run('broker-start', async () => controlJson(await io.run(command(['start', id, '--cwd', project.path, '--settings', target.session.settingsPath, '--', agent.command]), request.signal)));
+                if (started?.protocolVersion !== 1 || started.id !== id || typeof started.socket !== 'string' || !started.instanceId || !Number.isSafeInteger(started.controlMaxBytes) || !Number.isSafeInteger(started.pid) || started.pid < 1)
+                    throw need('BROKER_START_UNCONFIRMED');
+                entry = { ...started, state: 'running', firstSequence: 1, lastSequence: 0 };
+                state = { ...state, instanceId: entry.instanceId, pid: entry.pid };
+                await journal.write(state);
+                validEntry(entry);
+                transport = build(entry, 0);
+                const opening = transport;
+                const aborted = () => opening.fail(need('ABORTED'));
+                request.signal?.addEventListener('abort', aborted, { once: true });
+                try {
+                    request.signal?.throwIfAborted();
+                    await timing.run('broker-attach', () => connectWithLease(opening, entry));
+                    await validate();
+                }
+                catch (error) {
+                    if (!(error instanceof NeedError && ['ATTACH_BUSY', 'SESSION_IN_USE', 'SESSION_INSTANCE_MISMATCH'].includes(error.code)))
+                        await stop(entry, 'SESSION_OPEN_FAILED', opening, true, true);
+                    opening.close();
+                    throw error;
+                }
+                finally {
+                    request.signal?.removeEventListener('abort', aborted);
+                }
+            }
+            const ownedEntry = entry, ownedTransport = transport;
+            let disposed = false;
+            let disposal;
+            const runtime = { identity: identity(target), cwd: project.path, broker: ownedTransport, acpTransport: ownedTransport,
+                ...(resume ? { recoveredSession: resume } : {}), ...(restarted ? { restartNotice: '上次会话无法接回，已新建会话；本次从你的这条请求继续。', restartInputIds: request.currentInputIds } : {}),
+                saveCheckpoint: async (checkpointId, acp) => { await validate(); const saved = await ownedTransport.commitCheckpoint(async (cursor) => { await validate(); const clean = { version: 1, phase: 'clean', scope, brokerId: id, instanceId: ownedEntry.instanceId, pid: ownedEntry.pid, cursor, checkpointId, acp }; try {
+                    await journal.write(clean);
+                    state = clean;
+                }
+                catch (error) {
+                    state = undefined;
+                    throw error;
+                } }); if (!saved)
+                    await report('SESSION_CHECKPOINT_NOT_CLEAN', { brokerId: id, instanceId: ownedEntry.instanceId }); return saved; },
+                detach: async () => { ownedTransport.close(); active.delete(key); retained.delete(key); },
+                dispose: () => disposal ??= (async () => { if (disposed)
+                    return; try {
+                    await stop(ownedEntry, 'SESSION_ENDED', ownedTransport, true);
+                    await journal.write({ version: 1, phase: 'ended', scope, brokerId: id, instanceId: ownedEntry.instanceId, pid: ownedEntry.pid });
+                    disposed = true;
+                }
+                finally {
+                    ownedTransport.close();
+                    active.delete(key);
+                    retained.delete(key);
+                } })(), };
+            if (request.retainProcess)
+                retained.set(key, { runtime, scope, update: next => { request = next; timing = next.timing ?? new StageTiming(); } });
+            return runtime;
+        }
+        catch (error) {
+            active.delete(key);
+            throw error;
+        }
+    };
+    return open;
+}

package/dist/broker.d.ts

@@ -1,10 +1,18 @@
 import { type ChildProcessWithoutNullStreams } from 'node:child_process';
 import { NeedError, type Need } from './remote.ts';
-import type { Interaction } from './interaction.ts';
-import { type ConnectApi, type ConnectTarget, type Project, type Runtime, type RuntimeRequest } from './provider.ts';
+import { type ConnectTarget } from './provider.ts';
 export type Attachment = ChildProcessWithoutNullStreams;
 export interface BrokerOptions {
     maxFrameBytes: number;
+    initialSequence?: number;
+    instanceId?: string;
+    leased?: boolean;
+    controlMaxBytes?: number;
+    maxMessageBytes?: number;
+    beforeInput?: () => Promise<void>;
+    recoverySessionId?: string;
+    onRecoveryUpdate?: (message: Record<string, unknown>) => void;
+    discardOutput?: boolean;
     attach: (after: number) => Promise<Attachment>;
     onNeed?: (need: Need) => void;
     onDisconnect?: () => Promise<void>;
@@ -27,12 +35,27 @@ export declare class BrokerTransport {
     private approvalSent;
     private unconfirmed;
     private failure?;
+    private heartbeat?;
+    private boundary?;
+    private recovering;
+    private promptSent;
+    private preparingInputs;
+    private inputTail;
+    private exclusive;
     constructor(options: BrokerOptions);
     get online(): boolean;
     get generation(): number;
     get signal(): AbortSignal;
     get lastSequence(): number;
     get error(): NeedError | undefined;
+    get promptInFlight(): boolean;
+    processedMessage(message: Record<string, unknown>): void;
+    checkpointSequence(): number | null;
+    commitCheckpoint(commit: (cursor: number) => Promise<void>): Promise<boolean>;
+    finishRecovery(): void;
+    replayThrough(sequence: number, signal?: AbortSignal): Promise<void>;
+    private stopHeartbeat;
+    private recoveryMessage;
     authorizeResponse(id: string | number | null, generation: number): void;
     /** Called only by the ACP protocol layer after a matching result or current-turn output. */
     acknowledge(method: string): void;
@@ -47,6 +70,7 @@ export declare class BrokerTransport {
     connect(): Promise<void>;
     private attach;
     private write;
+    private send;
 }
 export type SshArgv = (target: ConnectTarget) => string[];
 export interface BrokerIo {
@@ -56,12 +80,11 @@ export interface BrokerIo {
 export declare function controlNeed(stderr: string): NeedError;
 export declare function sshIo(target: ConnectTarget, argv: SshArgv, maxControlBytes: number): BrokerIo;
 export declare function brokerCommand(t: ConnectTarget, args: string[]): string;
+export declare function legacyBrokerId(sessionId: string, agentId?: string): string;
 export declare function brokerId(sessionId: string, agentId?: string): string;
+export declare function controlJson(text: string): unknown;
 export interface BrokerSettings {
     brokerMaxFrameBytes?: number;
     brokerControlMaxBytes?: number;
 }
-export declare function brokerFactory(get: () => ConnectApi | undefined, _ask: Interaction | undefined, configuration: BrokerSettings | (() => BrokerSettings), provided?: {
-    argv?: SshArgv;
-    io?: (target: ConnectTarget) => BrokerIo;
-}): (target: ConnectTarget, project: Project, request: RuntimeRequest) => Promise<Runtime>;
+export { brokerFactory } from './broker-runtime.ts';