@ai-workbench/remote-agent 0.8.5 → 0.8.10

package/dist/employee-endpoint.d.ts

@@ -0,0 +1,91 @@
+import type { ConnectApi as LApi, LocalWorkspaceContextRequest } from '@ai-workbench/connect/api';
+import type { ConnectTarget } from './provider.ts';
+import type { DetailObservation } from './conversation-details.ts';
+/** Exact consumer subset of N0.4.4 employee-endpoint v1; no new provider fields. */
+export interface EmployeeEndpointTarget {
+    version: 1;
+    local: {
+        instanceId: string;
+        epoch: number;
+        workspaceId: string;
+        bindingId: string;
+        directory: {
+            path: string;
+            device: number;
+            inode: number;
+        };
+    };
+    endpoint: {
+        deviceId: string;
+        endpointInstanceId: string;
+        executionContextId: string;
+        remoteUser: string;
+        remoteUid: number;
+        remoteHome: string;
+        endpointCwd: string;
+        endpointShell: string;
+    };
+    bridge: {
+        protocolVersion: 1;
+        command: '/usr/local/aw-host/bin/aw-employee-bridge';
+        settingsPath: string;
+        bridgeInstanceId: string;
+        generation: number;
+    };
+}
+export interface EmployeeNetworkApi {
+    prepareEmployeeEndpoint(request: LocalWorkspaceContextRequest, signal: AbortSignal): Promise<{
+        ok: true;
+        value: EmployeeEndpointTarget;
+    } | {
+        ok: false;
+        error: {
+            code: string;
+            needs: string;
+            message: string;
+            actor: string;
+        };
+    }>;
+    getState(): {
+        phase: 'starting' | 'online' | 'blocked' | 'stopped';
+    };
+    onState(listener: (event: {
+        kind: 'lost' | 'restored';
+        state: {
+            phase: 'starting' | 'online' | 'blocked' | 'stopped';
+        };
+    }) => void): () => void;
+}
+export type EmployeeConnectApi = Pick<LApi, 'getContractInfo' | 'getConnectionState' | 'onConnectionState' | 'getSshTarget' | 'getLocalWorkspaceContext' | 'getWorkspaceLocationState' | 'onWorkspaceLocationState'>;
+export interface EmployeeWorkspace {
+    workspaceId: string;
+    directory: {
+        path: string;
+        device: number;
+        inode: number;
+    };
+}
+export interface EmployeeLeaseOptions {
+    getConnect: () => EmployeeConnectApi | undefined;
+    getNetwork: () => EmployeeNetworkApi | undefined;
+    readWorkspace: () => Promise<EmployeeWorkspace>;
+    host: ConnectTarget;
+    sessionId: string;
+    control: (host: ConnectTarget, command: string, signal?: AbortSignal) => Promise<string>;
+    detail: (detail: DetailObservation) => void;
+}
+export declare function endpointArguments(target: EmployeeEndpointTarget): string[];
+export declare function endpointCommand(target: EmployeeEndpointTarget): string;
+export declare function verifyEmployeeTarget(target: EmployeeEndpointTarget, request: LocalWorkspaceContextRequest, directory: EmployeeWorkspace['directory'], host: ConnectTarget): void;
+export declare function verifyBridgeTarget(value: unknown, expected: EmployeeEndpointTarget): {
+    sshArgs: string[];
+};
+/** Holds only this workspace's dispatch fence. N continues to own the shared device service. */
+export interface EmployeeLease {
+    target: EmployeeEndpointTarget;
+    request: Readonly<LocalWorkspaceContextRequest>;
+    signal: AbortSignal;
+    validate(callerSignal?: AbortSignal): Promise<EmployeeEndpointTarget>;
+    close(): Promise<void>;
+}
+export declare function openEmployeeLease(options: EmployeeLeaseOptions, initialSignal?: AbortSignal): Promise<EmployeeLease>;

package/dist/employee-endpoint.js

@@ -0,0 +1,141 @@
+import { lstat, realpath } from 'node:fs/promises';
+import { isDeepStrictEqual } from 'node:util';
+import { sameTarget, unwrap } from "./provider.js";
+import { NeedError, shellQuote } from "./remote.js";
+const fail = (code = 'EMPLOYEE_CONTEXT_CHANGED') => new NeedError(code, '本机工作区或连接已改变，原工具已停止；没有改在主机执行。', '当前L本地绑定与N/S同代员工端点');
+const uuid = (value) => typeof value === 'string' && /^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/.test(value);
+function clean(value) { return typeof value === 'string' && !!value && !/[\x00-\x1f\x7f]/.test(value); }
+export function endpointArguments(target) {
+    return ['--settings', target.bridge.settingsPath, '--device', target.endpoint.deviceId, '--if-instance', target.bridge.bridgeInstanceId, '--if-generation', String(target.bridge.generation), '--if-endpoint', target.endpoint.endpointInstanceId, '--if-context', target.endpoint.executionContextId];
+}
+export function endpointCommand(target) { return [target.bridge.command, 'target', ...endpointArguments(target)].map(shellQuote).join(' '); }
+export function verifyEmployeeTarget(target, request, directory, host) {
+    if (target?.version !== 1 || !target.local || !target.endpoint || !target.bridge || target.local.instanceId !== request.instanceId || target.local.epoch !== request.epoch || target.local.workspaceId !== request.workspaceId || target.local.bindingId !== request.expectedBindingId || !isDeepStrictEqual(target.local.directory, directory))
+        throw fail();
+    const e = target.endpoint, b = target.bridge;
+    if (!/^[a-f0-9]{64}$/.test(e.deviceId) || ![e.endpointInstanceId, e.executionContextId, b.bridgeInstanceId].every(uuid) || !Number.isSafeInteger(b.generation) || b.generation < 1 || b.protocolVersion !== 1 || b.command !== '/usr/local/aw-host/bin/aw-employee-bridge' || b.settingsPath !== host.session.settingsPath || ![e.remoteUser, e.remoteHome, e.endpointCwd, e.endpointShell].every(clean) || !e.remoteHome.startsWith('/') || !e.endpointCwd.startsWith('/') || !e.endpointShell.startsWith('/') || e.remoteUid !== process.getuid?.() || process.getuid?.() !== process.geteuid?.() || e.remoteUid < 1)
+        throw fail('EMPLOYEE_TARGET_INVALID');
+}
+export function verifyBridgeTarget(value, expected) {
+    const raw = value;
+    if (!raw || raw.type !== 'target' || raw.protocolVersion !== 1 || !raw.endpoint || raw.endpoint.state !== 'online' || !Array.isArray(raw.sshArgs) || !raw.sshArgs.length || raw.sshArgs.some(x => typeof x !== 'string' || x.includes('\0')))
+        throw fail('EMPLOYEE_BRIDGE_PROTOCOL_INVALID');
+    const endpoint = raw.endpoint;
+    for (const [field, value] of Object.entries({ ...expected.endpoint, bridgeInstanceId: expected.bridge.bridgeInstanceId, generation: expected.bridge.generation })) {
+        // N's shell/cwd are confirmed by ready; all public identity and execution facts must match.
+        if (endpoint[field] !== value)
+            throw fail();
+    }
+    return { sshArgs: raw.sshArgs };
+}
+export async function openEmployeeLease(options, initialSignal) {
+    initialSignal?.throwIfAborted();
+    const api = options.getConnect(), network = options.getNetwork(), lifetime = new AbortController(), offs = [];
+    if (!api || api.getContractInfo().localWorkspaceContext !== 1 || api.getContractInfo().workspaceLocations !== 1 || !api.getLocalWorkspaceContext || !api.getWorkspaceLocationState || !api.onWorkspaceLocationState)
+        throw fail('EMPLOYEE_CONTEXT_UNAVAILABLE');
+    if (!network || typeof network.prepareEmployeeEndpoint !== 'function' || typeof network.onState !== 'function')
+        throw fail('EMPLOYEE_ENDPOINT_UNAVAILABLE');
+    const workspace = await options.readWorkspace(), connection = api.getConnectionState(), state = api.getWorkspaceLocationState();
+    const items = state.items.filter(x => x.workspaceId === workspace.workspaceId);
+    if (connection.phase !== 'connected' || state.phase !== 'ready' || state.instanceId !== connection.instanceId || state.epoch !== connection.epoch || items.length !== 1 || items[0].source !== 'local' || items[0].status !== 'selected' || !items[0].bindingId)
+        throw fail();
+    const request = { instanceId: connection.instanceId, epoch: connection.epoch, workspaceId: workspace.workspaceId, expectedBindingId: items[0].bindingId };
+    let target, closed = false, diagnosticFailure;
+    const invalidate = (code) => { if (lifetime.signal.aborted)
+        return; try {
+        options.detail({ kind: 'session', severity: 'warning', code: 'CLAUDE_EMPLOYEE_REVOKED', summary: '本机旧绑定已停止派发，在途结果按实际确认；不会重放', payload: { reason: code, workspaceId: request.workspaceId, bindingId: request.expectedBindingId } });
+    }
+    catch (error) {
+        diagnosticFailure ??= error;
+    }
+    finally {
+        lifetime.abort(diagnosticFailure ?? fail(code));
+    } };
+    const current = () => {
+        if (options.getConnect() !== api || options.getNetwork() !== network)
+            throw fail();
+        const c = api.getConnectionState(), s = api.getWorkspaceLocationState(), matches = s.items.filter(x => x.workspaceId === request.workspaceId);
+        if (c.phase !== 'connected' || c.instanceId !== request.instanceId || c.epoch !== request.epoch || s.phase !== 'ready' || s.instanceId !== request.instanceId || s.epoch !== request.epoch || matches.length !== 1 || matches[0].source !== 'local' || matches[0].status !== 'selected' || matches[0].bindingId !== request.expectedBindingId || network.getState().phase !== 'online')
+            throw fail();
+        lifetime.signal.throwIfAborted();
+    };
+    const changed = () => { try {
+        current();
+    }
+    catch {
+        invalidate('EMPLOYEE_CONTEXT_CHANGED');
+    } };
+    offs.push(api.onConnectionState(changed), api.onWorkspaceLocationState(changed), network.onState(event => { if (event?.kind === 'lost' || network.getState().phase !== 'online')
+        invalidate('EMPLOYEE_ENDPOINT_UNAVAILABLE'); }));
+    async function validate(callerSignal) {
+        if (diagnosticFailure)
+            throw diagnosticFailure;
+        callerSignal?.throwIfAborted();
+        const signal = AbortSignal.any([lifetime.signal, ...callerSignal ? [callerSignal] : []]);
+        try {
+            current();
+            const now = await options.readWorkspace();
+            signal.throwIfAborted();
+            current();
+            const stat = await lstat(workspace.directory.path), canonical = await realpath(workspace.directory.path);
+            if (!isDeepStrictEqual(now, workspace) || !stat.isDirectory() || stat.isSymbolicLink() || canonical !== workspace.directory.path || stat.dev !== workspace.directory.device || stat.ino !== workspace.directory.inode)
+                throw fail();
+            const context = unwrap(await api.getLocalWorkspaceContext(request));
+            signal.throwIfAborted();
+            current();
+            if (context.version !== 1 || context.source !== 'local' || context.instanceId !== request.instanceId || context.epoch !== request.epoch || context.workspaceId !== request.workspaceId || context.bindingId !== request.expectedBindingId || !isDeepStrictEqual(context.directory, workspace.directory))
+                throw fail();
+            const prepared = await network.prepareEmployeeEndpoint({ ...request }, signal);
+            signal.throwIfAborted();
+            current();
+            if (!prepared.ok)
+                throw fail(/^[A-Z][A-Z0-9_]*$/.test(prepared.error.code) ? prepared.error.code : 'EMPLOYEE_ENDPOINT_UNAVAILABLE');
+            const next = structuredClone(prepared.value);
+            verifyEmployeeTarget(next, request, workspace.directory, options.host);
+            if (target && !isDeepStrictEqual(next, target))
+                throw fail();
+            const host = unwrap(await api.getSshTarget());
+            if (!sameTarget(host, options.host))
+                throw fail();
+            const raw = await options.control(host, endpointCommand(next), signal);
+            signal.throwIfAborted();
+            current();
+            let result;
+            try {
+                result = JSON.parse(raw);
+            }
+            catch {
+                throw fail('EMPLOYEE_BRIDGE_PROTOCOL_INVALID');
+            }
+            verifyBridgeTarget(result, next);
+            const final = await lstat(workspace.directory.path);
+            signal.throwIfAborted();
+            current();
+            if (final.dev !== workspace.directory.device || final.ino !== workspace.directory.inode)
+                throw fail();
+            target ??= next;
+            return structuredClone(target);
+        }
+        catch (error) {
+            if (!callerSignal?.aborted)
+                invalidate(error instanceof NeedError ? error.code : 'EMPLOYEE_CONTEXT_CHANGED');
+            throw error instanceof NeedError || callerSignal?.aborted ? error : fail();
+        }
+    }
+    try {
+        await validate(initialSignal);
+        return { target: structuredClone(target), request: Object.freeze({ ...request }), signal: lifetime.signal, validate, close: async () => { if (!closed) {
+                closed = true;
+                lifetime.abort(fail('EMPLOYEE_EXECUTOR_CLOSED'));
+                for (const off of offs)
+                    off();
+            } if (diagnosticFailure)
+                throw diagnosticFailure; } };
+    }
+    catch (error) {
+        for (const off of offs)
+            off();
+        lifetime.abort();
+        throw error;
+    }
+}

package/dist/employee-exec.d.ts

@@ -0,0 +1,53 @@
+import type { ChildProcessWithoutNullStreams } from 'node:child_process';
+import { NeedError } from './remote.ts';
+export type EmployeeMessage = Record<string, unknown>;
+export interface EmployeeExecutionTransport {
+    write(message: EmployeeMessage, signal?: AbortSignal): Promise<void>;
+    read(signal?: AbortSignal): Promise<EmployeeMessage | null>;
+    /** Closing a carrier never proves that an employee command completed. */
+    close(): void | Promise<void>;
+}
+export interface EmployeeExecutionOptions {
+    bindingId: string;
+    acpMaxMessageBytes: number;
+    /** Rechecks the current L CAS/directory/account and N/S five-tuple. No cached permit. */
+    validate(signal: AbortSignal): Promise<void>;
+    /** Once allocation starts, settle only after returning its executor or confirming aborted cleanup. */
+    transport(signal: AbortSignal): Promise<EmployeeExecutionTransport>;
+}
+export interface EmployeeExecutionResult {
+    version: 1;
+    executionId?: string;
+    messages?: EmployeeMessage[];
+    closed?: boolean;
+    result?: 'UNKNOWN';
+}
+/** One immutable workspace binding owns one executor. UNKNOWN is terminal, never replayed. */
+export declare class EmployeeExecution {
+    private readonly options;
+    private readonly lifetime;
+    private executionId?;
+    private io?;
+    private opening;
+    private ended;
+    private error?;
+    private pendingRead;
+    private writeTail;
+    private queuedWriteBytes;
+    private closing;
+    private factoryReceipt;
+    constructor(options: EmployeeExecutionOptions);
+    private parse;
+    private active;
+    private gate;
+    private stop;
+    private closeTransport;
+    invalidate(error?: NeedError): void;
+    private cleanup;
+    dispose(): Promise<void>;
+    handle(params: unknown, signal?: AbortSignal): Promise<EmployeeExecutionResult>;
+    private open;
+    private read;
+}
+/** NDJSON carrier with byte bounds and backpressure derived solely from acpMaxMessageBytes. */
+export declare function createEmployeeProcessTransport(child: ChildProcessWithoutNullStreams, acpMaxMessageBytes: number, stderrCodes?: readonly string[]): EmployeeExecutionTransport;