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

package/dist/remote-details.js

@@ -0,0 +1,250 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { mkdir, open, lstat, realpath, readdir } from 'node:fs/promises';
+import { isAbsolute, join, parse } from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import { sanitizeObservation, isSanitizedRedaction } from "./conversation-details.js";
+import { NeedError } from "./remote.js";
+const failure = (code, message = '技术详情未能持久记录，本轮已停止。') => new NeedError(code, message, '可用的远程主机连接技术详情');
+const hash = (value) => createHash('sha256').update(value).digest('hex');
+const object = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+function unwrap(result) {
+    if (!object(result))
+        throw failure('REMOTE_DETAIL_RESPONSE_INVALID');
+    if (result.ok === false && object(result.error) && typeof result.error.code === 'string')
+        throw failure(result.error.code);
+    if (result.ok !== true)
+        throw failure('REMOTE_DETAIL_RESPONSE_INVALID');
+    return result.value;
+}
+function identifier(value) { return value === null || typeof value === 'string' && value.trim().length > 0 || typeof value === 'number' && Number.isSafeInteger(value) && value >= 0; }
+function kind(observation) {
+    if (/UNKNOWN|UNSUPPORTED|FOREIGN/.test(observation.code))
+        return observation.severity === 'action-required' ? 'action-required' : 'unknown';
+    return { extension: 'extensions', tool: 'tools', need: 'action-required', notice: 'extensions', session: 'extensions' }[observation.kind] ?? observation.kind;
+}
+async function privateDirectory(path) {
+    if (!isAbsolute(path))
+        throw failure('REMOTE_DETAIL_STORAGE_FAILED');
+    // Existing parent/profile ownership is the host's responsibility; reject symlinks
+    // along the full path before creating our own private child directories.
+    let part = parse(path).root;
+    for (const member of path.slice(part.length).split('/').filter(Boolean)) {
+        part = join(part, member);
+        try {
+            const info = await lstat(part);
+            if (!info.isDirectory() || info.isSymbolicLink())
+                throw failure('REMOTE_DETAIL_STORAGE_FAILED');
+        }
+        catch (error) {
+            if (error?.code !== 'ENOENT')
+                throw error;
+            try {
+                await mkdir(part, { mode: 0o700 });
+            }
+            catch (creation) {
+                if (creation?.code !== 'EEXIST')
+                    throw creation;
+                const info = await lstat(part);
+                if (!info.isDirectory() || info.isSymbolicLink())
+                    throw failure('REMOTE_DETAIL_STORAGE_FAILED');
+            }
+        }
+    }
+    if (await realpath(path) !== path)
+        throw failure('REMOTE_DETAIL_STORAGE_FAILED');
+    const info = await lstat(path);
+    if ((info.mode & 0o077) !== 0 || (process.getuid && info.uid !== process.getuid()))
+        throw failure('REMOTE_DETAIL_STORAGE_FAILED');
+}
+async function durableWrite(path, value) {
+    const file = await open(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+    try {
+        await file.writeFile(JSON.stringify(value) + '\n');
+        await file.sync();
+    }
+    finally {
+        await file.close();
+    }
+    const parent = await open(join(path, '..'), 'r');
+    try {
+        await parent.sync();
+    }
+    finally {
+        await parent.close();
+    }
+}
+async function readJournal(path) {
+    const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const info = await file.stat();
+        if (!info.isFile() || (info.mode & 0o077) !== 0 || (process.getuid && info.uid !== process.getuid()))
+            throw failure('REMOTE_DETAIL_STORAGE_FAILED');
+        return JSON.parse(await file.readFile('utf8'));
+    }
+    finally {
+        await file.close();
+    }
+}
+export function createRemoteDetails(options) {
+    const root = join(options.profileDir, 'ai-workbench-remote-agent', 'diagnostics');
+    const scopes = new Map();
+    const initialize = async () => { await privateDirectory(join(options.profileDir, 'ai-workbench-remote-agent')); await privateDirectory(root); };
+    return { async open(request) {
+            if (!request.sessionId || !request.identity || !request.connection.instanceId || !Number.isSafeInteger(request.connection.epoch) || request.connection.epoch < 0 || !['claude', 'codex'].includes(request.provider))
+                throw failure('REMOTE_DETAIL_SCOPE_INVALID');
+            try {
+                await initialize();
+            }
+            catch {
+                throw failure('REMOTE_DETAIL_STORAGE_FAILED');
+            }
+            const api = options.getApi();
+            const stable = () => {
+                const now = api?.getConnectionState();
+                if (!api || options.getApi() !== api || now?.phase !== 'connected' || now.instanceId !== request.connection.instanceId || now.epoch !== request.connection.epoch)
+                    throw failure('CONNECTION_LOST');
+            };
+            stable();
+            const capability = api.getContractInfo?.();
+            if (!object(capability) || capability.remoteConversationDetails !== 1 || !['appendRemoteConversationDetail', 'getRemoteConversationDetailReceipt', 'listRemoteConversationDetails'].every(key => typeof api[key] === 'function')) {
+                await durableWrite(join(root, randomUUID() + '.json'), { version: 1, code: 'TECHNICAL_DETAILS_UNAVAILABLE', summary: '技术详情暂不可用', session: hash(request.sessionId), provider: request.provider });
+                throw failure('TECHNICAL_DETAILS_UNAVAILABLE', '技术详情暂不可用，请更新远程主机连接组件。');
+            }
+            const key = hash(request.identity + '\0' + request.sessionId + '\0' + request.provider), dir = join(root, key);
+            await privateDirectory(dir);
+            const scope = scopes.get(key) ?? { tail: Promise.resolve(), maximum: 0, loaded: false };
+            scopes.set(key, scope);
+            // Serialize open and appends in this host-user/session/brand scope.
+            const load = scope.tail.then(async () => {
+                stable();
+                const generation = request.connection.instanceId + '\0' + request.connection.epoch;
+                if (scope.loaded && scope.generation === generation)
+                    return;
+                const names = await readdir(dir);
+                for (const name of names) {
+                    const match = /^(\d+)-([0-9a-f-]+)\.json$/.exec(name);
+                    if (!match)
+                        continue;
+                    const n = Number(match[1]);
+                    if (!Number.isSafeInteger(n))
+                        throw failure('REMOTE_DETAIL_STORAGE_FAILED');
+                    scope.maximum = Math.max(scope.maximum, n);
+                    const saved = await readJournal(join(dir, name));
+                    if (!object(saved) || !object(saved.detail) || saved.detail.eventId !== match[2] || saved.detail.sequence !== n || saved.detail.sessionId !== request.sessionId || saved.detail.provider !== request.provider)
+                        throw failure('REMOTE_DETAIL_STORAGE_FAILED');
+                    const settled = 'settled-' + match[2] + '.json';
+                    if (names.includes(settled)) {
+                        const result = await readJournal(join(dir, settled));
+                        if (!object(result) || result.eventId !== match[2] || !['recorded', 'rejected'].includes(result.state))
+                            throw failure('REMOTE_DETAIL_STORAGE_FAILED');
+                        continue;
+                    }
+                    // An interrupted append is reconciled by pure read, with the original
+                    // event's epoch intact. Missing receipts stay unknown and never trigger append.
+                    stable();
+                    const receipt = unwrap(await api.getRemoteConversationDetailReceipt({ eventId: match[2], sessionId: request.sessionId, provider: request.provider }));
+                    stable();
+                    if (receipt.eventId !== match[2])
+                        throw failure('REMOTE_DETAIL_RECEIPT_INVALID');
+                    if (!receipt.recorded)
+                        throw failure('REMOTE_DETAIL_DELIVERY_UNKNOWN');
+                    if (!isDeepStrictEqual(receipt.detail, saved.detail))
+                        throw failure('REMOTE_DETAIL_RECEIPT_INVALID');
+                    await durableWrite(join(dir, settled), { eventId: match[2], state: 'recorded' });
+                }
+                let cursor, previous = -1;
+                const seen = new Set();
+                let expected;
+                let count = 0;
+                do {
+                    stable();
+                    const page = unwrap(await api.listRemoteConversationDetails({ sessionId: request.sessionId, provider: request.provider, ...(cursor ? { cursor } : {}) }));
+                    stable();
+                    if (!object(page) || !Array.isArray(page.items) || ![page.total, page.unknownCount, page.actionRequiredCount].every(n => Number.isSafeInteger(n) && n >= 0))
+                        throw failure('REMOTE_DETAIL_RESPONSE_INVALID');
+                    const counts = { total: page.total, unknownCount: page.unknownCount, actionRequiredCount: page.actionRequiredCount };
+                    if (expected && !isDeepStrictEqual(expected, counts))
+                        throw failure('REMOTE_DETAIL_RESPONSE_INVALID');
+                    expected = counts;
+                    for (const entry of page.items) {
+                        if (entry.sessionId !== request.sessionId || entry.provider !== request.provider || !Number.isSafeInteger(entry.sequence) || entry.sequence <= previous)
+                            throw failure('REMOTE_DETAIL_RESPONSE_INVALID');
+                        previous = entry.sequence;
+                        scope.maximum = Math.max(scope.maximum, entry.sequence);
+                        count++;
+                    }
+                    cursor = page.nextCursor;
+                    if (cursor !== undefined && (typeof cursor !== 'string' || !cursor || seen.has(cursor)))
+                        throw failure('REMOTE_DETAIL_CURSOR_INVALID');
+                    if (cursor)
+                        seen.add(cursor);
+                } while (cursor);
+                if (count !== expected?.total)
+                    throw failure('REMOTE_DETAIL_RESPONSE_INVALID');
+                scope.loaded = true;
+                scope.generation = generation;
+            });
+            scope.tail = load.then(() => { }, () => { });
+            await load;
+            let turn = null, step = null;
+            let tail = Promise.resolve(), firstFailure;
+            const enqueue = (operation) => {
+                const task = scope.tail.then(operation);
+                scope.tail = task.then(() => { }, () => { });
+                tail = task.catch(error => { scope.loaded = false; firstFailure ??= { error }; });
+            };
+            return {
+                beginTurn(ids) { if (!identifier(ids.turn) || !identifier(ids.step))
+                    throw failure('REMOTE_DETAIL_SCOPE_INVALID'); turn = ids.turn; step = ids.step; },
+                endTurn() { turn = null; step = null; },
+                record(observation) {
+                    const safe = sanitizeObservation(observation, true);
+                    const wire = (value) => Array.isArray(value) ? value.map(wire) : object(value) ? isSanitizedRedaction(value) ? (typeof value.valueType === 'string' ? { redacted: true, valueType: value.valueType, value: '已脱敏' } : '已脱敏') : Object.fromEntries(Object.entries(value).map(([key, child]) => [key, wire(child)])) : value;
+                    const sequence = scope.maximum + 1;
+                    if (!Number.isSafeInteger(sequence))
+                        throw failure('REMOTE_DETAIL_SEQUENCE_INVALID');
+                    scope.maximum = sequence;
+                    const detail = Object.freeze({ ...safe, payload: wire(safe.payload), version: 1, eventId: randomUUID(), instanceId: request.connection.instanceId, epoch: request.connection.epoch, sessionId: request.sessionId, provider: request.provider, turn, step, sequence, kind: kind(observation) });
+                    enqueue(async () => {
+                        // A private X journal is retained even if L is disconnected or rejects it.
+                        const file = join(dir, sequence + '-' + detail.eventId + '.json');
+                        try {
+                            await durableWrite(file, { state: 'pending', detail });
+                        }
+                        catch {
+                            throw failure('REMOTE_DETAIL_STORAGE_FAILED');
+                        }
+                        stable();
+                        let response;
+                        try {
+                            response = await api.appendRemoteConversationDetail(structuredClone(detail));
+                        }
+                        catch {
+                            stable();
+                            const receipt = unwrap(await api.getRemoteConversationDetailReceipt({ eventId: detail.eventId, sessionId: detail.sessionId, provider: detail.provider }));
+                            stable();
+                            if (receipt.eventId !== detail.eventId)
+                                throw failure('REMOTE_DETAIL_RECEIPT_INVALID');
+                            if (!receipt.recorded)
+                                throw failure('REMOTE_DETAIL_DELIVERY_UNKNOWN');
+                            if (!isDeepStrictEqual(receipt.detail, detail))
+                                throw failure('REMOTE_DETAIL_RECEIPT_INVALID');
+                            await durableWrite(join(dir, 'settled-' + detail.eventId + '.json'), { eventId: detail.eventId, state: 'recorded' });
+                            return;
+                        }
+                        stable();
+                        if (response?.ok === false) {
+                            await durableWrite(join(dir, 'settled-' + detail.eventId + '.json'), { eventId: detail.eventId, state: 'rejected', code: response.error.code });
+                        }
+                        const ack = unwrap(response);
+                        if (ack.eventId !== detail.eventId || ack.recorded !== true)
+                            throw failure('REMOTE_DETAIL_RESPONSE_INVALID');
+                        await durableWrite(join(dir, 'settled-' + detail.eventId + '.json'), { eventId: detail.eventId, state: 'recorded' });
+                    });
+                },
+                async flush() { await tail; if (firstFailure)
+                    throw firstFailure.error; stable(); },
+            };
+        } };
+}

package/dist/remote.d.ts

@@ -0,0 +1,34 @@
+import type { ChildProcessWithoutNullStreams } from 'node:child_process';
+/** Development-only direct SSH. Product transports must consume L's exported sshArgs (v0.2). */
+export interface DevelopmentSshTarget {
+    kind: 'development-only';
+    host: string;
+    username: string;
+    port: number;
+    proxyCommand?: string;
+    projectRoot: string;
+}
+export interface Need {
+    code: string;
+    message: string;
+    requires: string;
+}
+export declare class NeedError extends Error {
+    code: string;
+    requires: string;
+    constructor(code: string, message: string, requires: string);
+}
+export declare function shellQuote(value: string): string;
+export declare function sshArgs(target: DevelopmentSshTarget, command: string, noInput: boolean): string[];
+export declare function openSsh(target: DevelopmentSshTarget, command: string, noInput?: boolean): ChildProcessWithoutNullStreams;
+export interface Captured {
+    code: number | null;
+    stdout: string;
+    stderr: string;
+}
+export type Capture = (target: DevelopmentSshTarget, command: string) => Promise<Captured>;
+export declare function capture(target: DevelopmentSshTarget, command: string): Promise<Captured>;
+export declare function checkCodexLogin(target: DevelopmentSshTarget, execute?: Capture): Promise<{
+    loggedIn: boolean;
+    need?: Need;
+}>;

package/dist/remote.js

@@ -0,0 +1,51 @@
+import { spawn } from 'node:child_process';
+export class NeedError extends Error {
+    code;
+    requires;
+    constructor(code, message, requires) {
+        super(message);
+        this.name = 'NeedError';
+        this.code = code;
+        this.requires = requires;
+    }
+}
+export function shellQuote(value) {
+    if (value.includes('\0'))
+        throw new NeedError('INVALID_ARGUMENT', '远端参数含无效字符', '有效的远端参数');
+    return "'" + value.replaceAll("'", "'\\''") + "'";
+}
+export function sshArgs(target, command, noInput) {
+    if (target.kind !== 'development-only' || !/^[a-zA-Z0-9][a-zA-Z0-9.:-]*$/.test(target.host)
+        || !/^emp-[a-z0-9-]{1,28}$/.test(target.username)
+        || !Number.isInteger(target.port) || target.port < 1 || target.port > 65535
+        || target.proxyCommand?.includes('\0')) {
+        throw new NeedError('INVALID_TARGET', '我需要 connect 插件提供有效的员工 SSH 目标', 'connect-api SSH 目标');
+    }
+    return [...(noInput ? ['-n'] : []), '-o', 'BatchMode=yes',
+        ...(target.proxyCommand ? ['-o', `ProxyCommand=${target.proxyCommand}`] : []),
+        '-p', String(target.port), '-l', target.username, target.host, command];
+}
+export function openSsh(target, command, noInput = false) {
+    return spawn('ssh', sshArgs(target, command, noInput), { stdio: ['pipe', 'pipe', 'pipe'] });
+}
+export async function capture(target, command) {
+    const child = openSsh(target, command, true);
+    let stdout = '';
+    let stderr = '';
+    child.stdout.setEncoding('utf8').on('data', part => { stdout += part; });
+    child.stderr.setEncoding('utf8').on('data', part => { stderr += part; });
+    return new Promise((resolve, reject) => {
+        child.on('error', () => reject(new NeedError('SSH_FAILED', 'SSH 启动失败，根因未查明', '可用的 SSH 连接')));
+        child.on('close', code => resolve({ code, stdout, stderr }));
+    });
+}
+export async function checkCodexLogin(target, execute = capture) {
+    const { code } = await execute(target, 'codex login status');
+    if (code === 0)
+        return { loggedIn: true };
+    if (code === 1)
+        return { loggedIn: false, need: { code: 'LOGIN_REQUIRED', message: '我需要该员工在主机上的 Codex 完成登录，请通过连接插件授权。', requires: '该员工自己的 Codex 登录' } };
+    if (code === 255 || code === null)
+        throw new NeedError('SSH_FAILED', 'SSH 检查失败，根因未查明', '可用的员工 SSH 连接');
+    throw new NeedError('AUTH_STATUS_INVALID', 'Codex 登录状态检查异常，根因未查明', '有效的官方登录状态');
+}

package/dist/sdk-ssh-wrapper.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/sdk-ssh-wrapper.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+/** Codex SDK executable override. Prompt travels through stdin, never SSH argv. */
+import { readFile, lstat } from 'node:fs/promises';
+import { executeJob } from "./job.js";
+let child;
+let stopped = false;
+const lifetime = new AbortController();
+for (const sig of ['SIGTERM', 'SIGINT'])
+    process.on(sig, () => { stopped = true; lifetime.abort(); child?.kill('SIGTERM'); });
+try {
+    const path = process.env.AW_X_JOB_FILE;
+    if (!path)
+        throw new Error('job missing');
+    const meta = await lstat(path);
+    if (!meta.isFile() || meta.isSymbolicLink() || meta.uid !== process.getuid?.() || (meta.mode & 0o077) !== 0)
+        throw new Error('job permissions');
+    const spec = JSON.parse(await readFile(path, 'utf8'));
+    let input = '';
+    for await (const chunk of process.stdin)
+        input += chunk;
+    if (!stopped) {
+        const code = await executeJob(spec, 'stage', JSON.stringify({ argv: process.argv.slice(2), input, cwd: spec.cwd, codex: spec.codex }), c => { child = c; }, false, lifetime.signal);
+        if (code !== 0)
+            throw new Error('stage failed');
+    }
+    if (!stopped)
+        process.exitCode = (await executeJob(spec, 'run', undefined, c => { child = c; }, true, lifetime.signal)) ?? 1;
+    else
+        process.exitCode = 143;
+}
+catch {
+    process.stderr.write('远端单次运行失败；需要连接诊断，根因未查明。\n');
+    process.exitCode = 1;
+}

package/dist/workspace-notice.d.ts

@@ -0,0 +1,47 @@
+import type { Context } from '@deepseek-ai/cordis';
+import { type RequestMessage } from '@deepseek-ai/dsh-llm';
+import { type AgentDefinition } from './agents.ts';
+import type { ConnectApi, RuntimeRequest } from './provider.ts';
+import type { WorkspaceNotice, SessionProjectTarget } from './connect-contract.ts';
+/** X-owned adapter metadata; this is not a DSH renderer acknowledgement. */
+export interface WorkspaceNoticeMarker {
+    readonly kind: 'workspace-notice';
+    readonly version: 1;
+    readonly provider: string;
+    readonly loginProvider: 'claude' | 'codex';
+    readonly sessionId: string;
+    readonly noticeId: string;
+    readonly claimId: string;
+    readonly deliveryId: string;
+    readonly messageId: string;
+    readonly workspaceName: string;
+    readonly bindingId: string;
+    readonly workspaceId: string;
+}
+export declare function parseWorkspaceNoticeMarker(message: unknown): WorkspaceNoticeMarker | undefined;
+/** Only this plugin's complete, source-bound notice may be excluded from remote model history. */
+export declare function isWorkspaceNoticeMessage(message: unknown): boolean;
+/** A verified first block in the actual model reply, never a second final message. */
+export interface WorkspaceNoticePresentation {
+    readonly kind: 'workspace-notice';
+    readonly version: 2;
+    readonly provider: string;
+    readonly loginProvider: 'claude' | 'codex';
+    readonly sessionId: string;
+    readonly noticeId: string;
+    readonly claimId: string;
+    readonly workspaceName: string;
+    readonly bindingId: string;
+    readonly workspaceId: string;
+    readonly turn: number;
+    readonly step: number;
+    readonly blockIndex: 0;
+    readonly text: string;
+}
+export declare function workspaceNoticeFromMessage(message: unknown): WorkspaceNoticePresentation | undefined;
+/** Preserve the model answer and exact remote replay pointer; ordinary text is never searched. */
+export declare function withoutWorkspaceNotice<T extends RequestMessage>(message: T): T;
+export declare function createWorkspaceNoticeConsumer(ctx: Context, agent: AgentDefinition): {
+    reconcile: (request: RuntimeRequest, api: ConnectApi) => Promise<void>;
+    deliver: (notice: WorkspaceNotice, resolved: SessionProjectTarget, request: RuntimeRequest, api: ConnectApi) => Promise<WorkspaceNoticePresentation | undefined>;
+};