@ai-workbench/remote-agent 0.8.5 → 0.8.11

package/dist/employee-exec.js

@@ -0,0 +1,423 @@
+import { randomUUID } from 'node:crypto';
+import { NeedError } from "./remote.js";
+const object = (value) => !!value && typeof value === 'object' && !Array.isArray(value) && (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null);
+const need = (code) => new NeedError(code, code === 'ABORTED' ? '员工执行等待已取消，命令结果需另行确认' : '员工执行通道无法继续（' + code + '），未重放请求', '当前员工工作区绑定、N/S端点与实际命令状态');
+const failure = (error) => error instanceof NeedError ? error : need('EMPLOYEE_EXEC_UNKNOWN');
+function capacity(value) { if (!Number.isSafeInteger(value) || value < 1)
+    throw new NeedError('SETTINGS_REQUIRED', '我需要有效的 acpMaxMessageBytes', '管理员确认 acpMaxMessageBytes'); }
+function encoded(message, maxBytes) {
+    if (!object(message))
+        throw need('EMPLOYEE_EXEC_PROTOCOL_INVALID');
+    let json;
+    try {
+        json = JSON.stringify(message);
+    }
+    catch {
+        throw need('EMPLOYEE_EXEC_PROTOCOL_INVALID');
+    }
+    if (Buffer.byteLength(json) > maxBytes)
+        throw need('ACP_MESSAGE_TOO_LARGE');
+    // Freeze this operation's wire value before any async gate can yield.
+    const value = JSON.parse(json);
+    if (!object(value))
+        throw need('EMPLOYEE_EXEC_PROTOCOL_INVALID');
+    return { message: value, line: Buffer.from(json + '\n') };
+}
+function cancelled(signal) { if (signal?.aborted)
+    throw need('ABORTED'); }
+function waiting(operation, signal) {
+    if (signal.aborted) {
+        void operation.catch(() => { });
+        return Promise.reject(need('ABORTED'));
+    }
+    return new Promise((resolve, reject) => {
+        const abort = () => { signal.removeEventListener('abort', abort); reject(need('ABORTED')); };
+        signal.addEventListener('abort', abort, { once: true });
+        void operation.then(value => { signal.removeEventListener('abort', abort); resolve(value); }, error => { signal.removeEventListener('abort', abort); reject(error); });
+        if (signal.aborted)
+            abort();
+    });
+}
+/** One immutable workspace binding owns one executor. UNKNOWN is terminal, never replayed. */
+export class EmployeeExecution {
+    options;
+    lifetime = new AbortController();
+    executionId;
+    io;
+    opening = false;
+    ended = false;
+    error;
+    pendingRead = false;
+    writeTail = Promise.resolve();
+    queuedWriteBytes = 0;
+    closing = Promise.resolve();
+    factoryReceipt = Promise.resolve();
+    constructor(options) {
+        capacity(options.acpMaxMessageBytes);
+        if (typeof options.bindingId !== 'string' || !options.bindingId)
+            throw need('EMPLOYEE_EXEC_IDENTITY_MISMATCH');
+        this.options = options;
+    }
+    parse(params) {
+        if (!object(params) || Object.keys(params).some(key => !['version', 'bindingId', 'operation', 'executionId', 'message'].includes(key)) || params.version !== 1 || typeof params.bindingId !== 'string' || !['open', 'write', 'read', 'close'].includes(params.operation))
+            throw need('EMPLOYEE_EXEC_PROTOCOL_INVALID');
+        if (params.bindingId !== this.options.bindingId)
+            throw need('EMPLOYEE_EXEC_IDENTITY_MISMATCH');
+        if (params.operation === 'open') {
+            if (Object.hasOwn(params, 'executionId') || Object.hasOwn(params, 'message'))
+                throw need('EMPLOYEE_EXEC_PROTOCOL_INVALID');
+        }
+        else {
+            if (typeof params.executionId !== 'string' || !params.executionId)
+                throw need('EMPLOYEE_EXEC_PROTOCOL_INVALID');
+            if (params.executionId !== this.executionId)
+                throw need('EMPLOYEE_EXEC_IDENTITY_MISMATCH');
+            if (params.operation === 'write' ? !object(params.message) : Object.hasOwn(params, 'message'))
+                throw need('EMPLOYEE_EXEC_PROTOCOL_INVALID');
+        }
+        return params;
+    }
+    active() { if (this.ended)
+        throw this.error ?? need('EMPLOYEE_EXEC_CLOSED'); }
+    async gate(signal) { this.active(); cancelled(signal); await waiting(this.options.validate(signal), signal); this.active(); cancelled(signal); }
+    stop(error) {
+        if (this.ended)
+            return;
+        this.ended = true;
+        this.error = error;
+        this.lifetime.abort();
+        const io = this.io;
+        this.io = undefined;
+        if (io)
+            this.closeTransport(io);
+    }
+    closeTransport(io) {
+        let closing;
+        try {
+            closing = Promise.resolve(io.close());
+        }
+        catch {
+            closing = Promise.reject(need('EMPLOYEE_EXEC_UNKNOWN'));
+        }
+        this.closing = Promise.all([this.closing, closing]).then(() => { }, () => { const unknown = need('EMPLOYEE_EXEC_UNKNOWN'); this.error ??= unknown; throw unknown; });
+        // Revocation starts cleanup without a caller waiting yet; retain rejection for close/dispose.
+        void this.closing.catch(() => { });
+    }
+    invalidate(error = need('EMPLOYEE_CONTEXT_CHANGED')) { this.stop(error); }
+    async cleanup() { await this.factoryReceipt; await this.closing; }
+    async dispose() { this.stop(); await this.cleanup(); }
+    async handle(params, signal) {
+        const request = this.parse(params);
+        cancelled(signal);
+        if (request.operation === 'close') {
+            this.stop();
+            await this.cleanup();
+            return { version: 1, closed: true, result: 'UNKNOWN' };
+        }
+        this.active();
+        const current = signal ? AbortSignal.any([signal, this.lifetime.signal]) : this.lifetime.signal;
+        if (request.operation === 'open')
+            return this.open(current);
+        if (request.operation === 'read')
+            return this.read(current);
+        const value = encoded(request.message, this.options.acpMaxMessageBytes);
+        const size = value.line.byteLength;
+        if (this.queuedWriteBytes + size > this.options.acpMaxMessageBytes) {
+            const error = need('ACP_MESSAGE_TOO_LARGE');
+            this.stop(error);
+            throw error;
+        }
+        this.queuedWriteBytes += size;
+        const operation = this.writeTail.then(async () => {
+            try {
+                await this.gate(current);
+                const io = this.io;
+                if (!io)
+                    throw need('EMPLOYEE_EXEC_CLOSED');
+                await waiting(io.write(value.message, current), current);
+                await this.gate(current);
+                return { version: 1 };
+            }
+            catch (error) {
+                const known = this.error ?? failure(error);
+                this.stop(known);
+                throw known;
+            }
+            finally {
+                this.queuedWriteBytes -= size;
+            }
+        });
+        this.writeTail = operation.catch(() => { });
+        return operation;
+    }
+    async open(signal) {
+        if (this.opening || this.executionId)
+            throw need('EMPLOYEE_EXEC_ALREADY_OPEN');
+        this.opening = true;
+        try {
+            await this.gate(signal);
+            // A factory may finish after revoke/abort. Its late executor belongs to this binding and must close.
+            const created = Promise.resolve().then(() => { cancelled(signal); return this.options.transport(signal); }).then(async (io) => { if (this.ended || signal.aborted) {
+                this.closeTransport(io);
+                await this.closing;
+                throw this.error ?? need('ABORTED');
+            } this.io = io; return io; });
+            // Open cancellation may return immediately; the runtime still owns the full allocation receipt.
+            this.factoryReceipt = created.then(() => { }, error => { if (failure(error).code === 'EMPLOYEE_EXEC_UNKNOWN') {
+                const unknown = need('EMPLOYEE_EXEC_UNKNOWN');
+                this.error ??= unknown;
+                throw unknown;
+            } });
+            void this.factoryReceipt.catch(() => { });
+            await waiting(created, signal);
+            await this.gate(signal);
+            this.executionId = randomUUID();
+            return { version: 1, executionId: this.executionId };
+        }
+        catch (error) {
+            const known = this.error ?? failure(error);
+            this.stop(known);
+            throw known;
+        }
+        finally {
+            this.opening = false;
+        }
+    }
+    async read(signal) {
+        if (this.pendingRead)
+            throw need('EMPLOYEE_EXEC_READ_BUSY');
+        this.pendingRead = true;
+        let consumed = false;
+        try {
+            await this.gate(signal);
+            const io = this.io;
+            if (!io)
+                throw need('EMPLOYEE_EXEC_CLOSED');
+            const message = await waiting(io.read(signal).then(message => { consumed = message !== null; return message; }), signal);
+            if (this.ended) {
+                if (this.error)
+                    throw this.error;
+                return { version: 1, messages: [], closed: true };
+            }
+            await this.gate(signal);
+            if (message === null) {
+                this.stop();
+                return { version: 1, messages: [], closed: true };
+            }
+            const value = encoded(message, this.options.acpMaxMessageBytes);
+            if (Buffer.byteLength(JSON.stringify({ version: 1, messages: [value.message], closed: false })) > this.options.acpMaxMessageBytes)
+                throw need('ACP_MESSAGE_TOO_LARGE');
+            return { version: 1, messages: [value.message], closed: false };
+        }
+        catch (error) {
+            if (this.error)
+                throw this.error;
+            if (signal.aborted && !this.ended) {
+                if (consumed) {
+                    const unknown = need('EMPLOYEE_EXEC_UNKNOWN');
+                    this.stop(unknown);
+                    throw unknown;
+                }
+                throw need('ABORTED');
+            }
+            if (this.ended && !this.error)
+                return { version: 1, messages: [], closed: true };
+            const known = failure(error);
+            this.stop(known);
+            throw known;
+        }
+        finally {
+            this.pendingRead = false;
+        }
+    }
+}
+/** NDJSON carrier with byte bounds and backpressure derived solely from acpMaxMessageBytes. */
+export function createEmployeeProcessTransport(child, acpMaxMessageBytes, stderrCodes = []) {
+    capacity(acpMaxMessageBytes);
+    let partial = Buffer.alloc(0), queuedBytes = 0, writingBytes = 0, closed = false, reason;
+    let processClosed = false, terminationRequested = false;
+    const receipt = Promise.withResolvers();
+    void receipt.promise.catch(() => { });
+    let sawOutput = false, diagnosticCode, stderrPosition = 0;
+    const knownCodes = stderrCodes.filter(code => /^[A-Z][A-Z0-9_]*$/.test(code));
+    let stderrCandidates = knownCodes;
+    const queue = [];
+    let pending;
+    const writes = new Set();
+    const settle = () => { if (!pending)
+        return; const reader = pending; pending = undefined; reader.clear(); reason ? reader.reject(reason) : reader.resolve(null); };
+    const terminate = () => {
+        if (processClosed || terminationRequested)
+            return;
+        terminationRequested = true;
+        try {
+            child.stdin.end();
+        }
+        catch {
+            receipt.reject(need('EMPLOYEE_EXEC_UNKNOWN'));
+        }
+        // A paused output pipe must drain before Node can deliver the actual child close event.
+        child.stdout.resume();
+        child.stderr.resume();
+        try {
+            if (!child.kill('SIGTERM') && !processClosed)
+                receipt.reject(need('EMPLOYEE_EXEC_UNKNOWN'));
+        }
+        catch {
+            receipt.reject(need('EMPLOYEE_EXEC_UNKNOWN'));
+        }
+    };
+    const finish = (error, kill = false) => {
+        if (!closed) {
+            closed = true;
+            reason = error;
+            partial = Buffer.alloc(0);
+            if (error) {
+                queue.length = 0;
+                queuedBytes = 0;
+            }
+            settle();
+            for (const reject of writes)
+                reject(error ?? need('EMPLOYEE_EXEC_UNKNOWN'));
+            writes.clear();
+        }
+        if (kill)
+            terminate();
+    };
+    const output = (message, bytes) => {
+        if (pending) {
+            const reader = pending;
+            pending = undefined;
+            reader.clear();
+            reader.resolve(message);
+        }
+        else {
+            if (queuedBytes + bytes > acpMaxMessageBytes)
+                throw need('ACP_MESSAGE_TOO_LARGE');
+            queue.push({ message, bytes });
+            queuedBytes += bytes;
+            child.stdout.pause();
+        }
+    };
+    child.stdout.on('data', (chunk) => {
+        if (closed)
+            return;
+        sawOutput = true;
+        diagnosticCode = undefined;
+        try {
+            let start = 0;
+            while (start < chunk.length) {
+                const end = chunk.indexOf(10, start), last = end < 0 ? chunk.length : end;
+                const length = partial.length + last - start;
+                if (length > acpMaxMessageBytes || queuedBytes + length > acpMaxMessageBytes)
+                    throw need('ACP_MESSAGE_TOO_LARGE');
+                if (end < 0) {
+                    partial = Buffer.concat([partial, chunk.subarray(start)]);
+                    break;
+                }
+                const line = partial.length ? Buffer.concat([partial, chunk.subarray(start, end)]) : chunk.subarray(start, end);
+                partial = Buffer.alloc(0);
+                start = end + 1;
+                let value;
+                try {
+                    value = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(line));
+                }
+                catch {
+                    throw need('EMPLOYEE_EXEC_PROTOCOL_INVALID');
+                }
+                if (!object(value))
+                    throw need('EMPLOYEE_EXEC_PROTOCOL_INVALID');
+                output(value, line.byteLength);
+            }
+        }
+        catch (error) {
+            finish(failure(error), true);
+        }
+    });
+    // Match fixed startup codes byte by byte. No arbitrary diagnostic bytes are retained.
+    child.stderr.on('data', (chunk) => {
+        if (sawOutput || closed || !knownCodes.length)
+            return;
+        for (const byte of chunk) {
+            if (byte === 10) {
+                const match = stderrCandidates.find(code => code.length === stderrPosition);
+                if (match)
+                    diagnosticCode = match;
+                stderrPosition = 0;
+                stderrCandidates = knownCodes;
+            }
+            else if (stderrCandidates.length) {
+                stderrCandidates = stderrCandidates.filter(code => code.charCodeAt(stderrPosition) === byte);
+                stderrPosition++;
+            }
+        }
+    });
+    child.stderr.resume();
+    child.stdin.on('error', () => finish(need(diagnosticCode ?? 'EMPLOYEE_EXEC_UNKNOWN'), true));
+    child.once('error', () => finish(need('EMPLOYEE_EXEC_UNKNOWN'), true));
+    child.once('close', (code, signal) => { processClosed = true; finish(partial.length ? need('EMPLOYEE_EXEC_PROTOCOL_INVALID') : code === 0 && !signal ? undefined : need(diagnosticCode ?? 'EMPLOYEE_EXEC_UNKNOWN')); receipt.resolve(); });
+    return {
+        write: async (message, signal) => {
+            cancelled(signal);
+            if (closed)
+                throw reason ?? need('EMPLOYEE_EXEC_UNKNOWN');
+            const value = encoded(message, acpMaxMessageBytes);
+            if (writingBytes + value.line.byteLength > acpMaxMessageBytes) {
+                const error = need('ACP_MESSAGE_TOO_LARGE');
+                finish(error, true);
+                throw error;
+            }
+            writingBytes += value.line.byteLength;
+            await new Promise((resolve, reject) => {
+                let done = false;
+                const cleanup = () => { if (done)
+                    return false; done = true; writingBytes -= value.line.byteLength; writes.delete(fail); signal?.removeEventListener('abort', abort); return true; };
+                const fail = (error) => { if (cleanup())
+                    reject(error); };
+                const abort = () => { const error = need('EMPLOYEE_EXEC_UNKNOWN'); finish(error, true); fail(error); };
+                writes.add(fail);
+                signal?.addEventListener('abort', abort, { once: true });
+                try {
+                    child.stdin.write(value.line, error => { if (error) {
+                        finish(need('EMPLOYEE_EXEC_UNKNOWN'), true);
+                        fail(need('EMPLOYEE_EXEC_UNKNOWN'));
+                    }
+                    else if (cleanup())
+                        resolve(); });
+                }
+                catch {
+                    finish(need('EMPLOYEE_EXEC_UNKNOWN'), true);
+                    fail(need('EMPLOYEE_EXEC_UNKNOWN'));
+                }
+                if (signal?.aborted)
+                    abort();
+            });
+        },
+        read: async (signal) => {
+            cancelled(signal);
+            if (reason)
+                throw reason;
+            if (pending)
+                throw need('EMPLOYEE_EXEC_READ_BUSY');
+            if (queue.length) {
+                const item = queue.shift();
+                queuedBytes -= item.bytes;
+                if (!queue.length && !closed)
+                    child.stdout.resume();
+                return item.message;
+            }
+            if (closed)
+                return null;
+            return new Promise((resolve, reject) => {
+                const abort = () => { if (pending?.resolve !== resolve)
+                    return; pending.clear(); pending = undefined; reject(need('ABORTED')); };
+                pending = { resolve, reject, clear: () => signal?.removeEventListener('abort', abort) };
+                signal?.addEventListener('abort', abort, { once: true });
+                child.stdout.resume();
+                if (signal?.aborted)
+                    abort();
+            });
+        },
+        close: () => { finish(undefined, true); queue.length = 0; queuedBytes = 0; return receipt.promise; }
+    };
+}

package/dist/employee-location.d.ts

@@ -0,0 +1,66 @@
+import type { EmployeeEndpointTarget, NetworkApi } from '@ai-workbench/network/api';
+export interface EmployeeLocationSource {
+    getWorkspaceLocationState(): {
+        instanceId: string;
+        epoch: number;
+        phase: string;
+        items: {
+            workspaceId: string;
+            bindingId: string | null;
+            source: string | null;
+            status: string;
+        }[];
+    };
+    getLocalWorkspaceContext(request: {
+        instanceId: string;
+        epoch: number;
+        workspaceId: string;
+        expectedBindingId: string;
+    }): Promise<{
+        ok: true;
+        value: {
+            version: 1;
+            instanceId: string;
+            epoch: number;
+            workspaceId: string;
+            bindingId: string;
+            source: 'local';
+            directory: {
+                path: string;
+                device: number;
+                inode: number;
+            };
+        };
+    } | {
+        ok: false;
+        error: {
+            code: string;
+            message: string;
+            requires: string;
+        };
+    }>;
+}
+export type EmployeeEndpointSource = Pick<NetworkApi, 'prepareEmployeeEndpoint'>;
+export interface EmployeeLocationOptions {
+    api: EmployeeLocationSource;
+    network: EmployeeEndpointSource;
+    workspace: {
+        id: string;
+        path: string;
+    };
+    connection: {
+        instanceId: string;
+        epoch: number;
+    };
+    expectedLocal?: EmployeeEndpointTarget['local'];
+    settingsPath: string;
+    signal?: AbortSignal;
+}
+/** One admission binds source/canonical directory and real N/S execution identity. No host-path substitute. */
+export declare function admitEmployeeLocation(options: EmployeeLocationOptions): Promise<{
+    cwd: string;
+    bindingId: string;
+    workspaceId: string;
+    endpoint: EmployeeEndpointTarget;
+    validate: (signal: AbortSignal) => Promise<void>;
+}>;

package/dist/employee-location.js

@@ -0,0 +1,51 @@
+import { NeedError } from "./remote.js";
+import { isDeepStrictEqual } from 'node:util';
+const fail = (code) => new NeedError(code, '员工电脑的工作区或执行连接已变化，本轮没有继续执行。', '当前工作区绑定与员工端执行器');
+const absolute = (s) => typeof s === 'string' && s.startsWith('/') && !s.includes('\0');
+const uuid = (s) => typeof s === 'string' && /^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/i.test(s);
+const object = (x) => !!x && typeof x === 'object' && !Array.isArray(x);
+const same = isDeepStrictEqual;
+function endpointValue(value, local, settingsPath) {
+    if (!object(value) || value.version !== 1 || !same(value.local, local) || !object(value.endpoint) || !object(value.bridge))
+        throw fail('EMPLOYEE_ENDPOINT_INVALID');
+    const e = value.endpoint, b = value.bridge;
+    if (typeof e.deviceId !== 'string' || !/^[a-f0-9]{64}$/.test(e.deviceId) || !uuid(e.endpointInstanceId) || !uuid(e.executionContextId) || typeof e.remoteUser !== 'string' || !e.remoteUser || !Number.isInteger(e.remoteUid) || Number(e.remoteUid) < 1 || Number(e.remoteUid) > 4294967294 || !absolute(e.remoteHome) || e.endpointCwd !== e.remoteHome || !absolute(e.endpointShell) || b.protocolVersion !== 1 || b.command !== '/usr/local/aw-host/bin/aw-employee-bridge' || b.settingsPath !== settingsPath || !uuid(b.bridgeInstanceId) || !Number.isSafeInteger(b.generation) || Number(b.generation) < 1)
+        throw fail('EMPLOYEE_ENDPOINT_INVALID');
+    // Copy only the public target fields; never retain process/environment snapshots.
+    return { version: 1, local: structuredClone(local), endpoint: { deviceId: e.deviceId, endpointInstanceId: e.endpointInstanceId, executionContextId: e.executionContextId, remoteUser: e.remoteUser, remoteUid: Number(e.remoteUid), remoteHome: e.remoteHome, endpointCwd: e.endpointCwd, endpointShell: e.endpointShell }, bridge: { protocolVersion: 1, command: b.command, settingsPath, bridgeInstanceId: b.bridgeInstanceId, generation: Number(b.generation) } };
+}
+/** One admission binds source/canonical directory and real N/S execution identity. No host-path substitute. */
+export async function admitEmployeeLocation(options) {
+    const { api, network, workspace, connection, settingsPath } = options;
+    const read = async (signal) => {
+        signal?.throwIfAborted();
+        const state = api.getWorkspaceLocationState();
+        if (state.phase !== 'ready' || state.instanceId !== connection.instanceId || state.epoch !== connection.epoch)
+            throw fail('EMPLOYEE_CONTEXT_CHANGED');
+        const rows = state.items.filter(x => x.workspaceId === workspace.id), item = rows[0];
+        if (rows.length !== 1 || !item || item.source !== 'local' || item.status !== 'selected' || !item.bindingId)
+            throw fail('EMPLOYEE_CONTEXT_CHANGED');
+        const request = { instanceId: connection.instanceId, epoch: connection.epoch, workspaceId: workspace.id, expectedBindingId: item.bindingId };
+        const result = await api.getLocalWorkspaceContext(request);
+        signal?.throwIfAborted();
+        if (!result.ok)
+            throw new NeedError(result.error.code, result.error.message, result.error.requires);
+        const c = result.value;
+        if (c.version !== 1 || c.source !== 'local' || c.instanceId !== connection.instanceId || c.epoch !== connection.epoch || c.workspaceId !== workspace.id || c.bindingId !== item.bindingId || !absolute(c.directory?.path) || c.directory.path !== workspace.path || !Number.isSafeInteger(c.directory.device) || !Number.isSafeInteger(c.directory.inode))
+            throw fail('EMPLOYEE_CONTEXT_CHANGED');
+        const after = api.getWorkspaceLocationState();
+        if (after.instanceId !== connection.instanceId || after.epoch !== connection.epoch || after.phase !== 'ready' || !after.items.some(x => x.workspaceId === workspace.id && x.bindingId === item.bindingId && x.source === 'local' && x.status === 'selected'))
+            throw fail('EMPLOYEE_CONTEXT_CHANGED');
+        return { request, local: { instanceId: c.instanceId, epoch: c.epoch, workspaceId: c.workspaceId, bindingId: c.bindingId, directory: structuredClone(c.directory) } };
+    };
+    const initial = await read(options.signal);
+    if (options.expectedLocal && !same(initial.local, options.expectedLocal))
+        throw fail('EMPLOYEE_CONTEXT_CHANGED');
+    const prepare = async (signal) => { signal.throwIfAborted(); const before = await read(signal); if (!same(before, initial))
+        throw fail('EMPLOYEE_CONTEXT_CHANGED'); const result = await network.prepareEmployeeEndpoint(initial.request, signal); signal.throwIfAborted(); if (!result.ok)
+        throw new NeedError(result.error.code, result.error.message, result.error.needs); const fresh = endpointValue(result.value, initial.local, settingsPath); const after = await read(signal); if (!same(after, initial))
+        throw fail('EMPLOYEE_CONTEXT_CHANGED'); return fresh; };
+    const endpoint = await prepare(options.signal ?? new AbortController().signal);
+    return { cwd: initial.local.directory.path, bindingId: initial.local.bindingId, workspaceId: initial.local.workspaceId, endpoint, validate: async (signal) => { const fresh = await prepare(signal); if (!same(fresh, endpoint))
+            throw fail('EMPLOYEE_CONTEXT_CHANGED'); } };
+}

package/dist/employee-mcp.d.ts

@@ -0,0 +1,42 @@
+import { type Socket } from 'node:net';
+import { type JSONRPCMessage, type Tool } from '@modelcontextprotocol/sdk/types.js';
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+import type { EmployeeLease } from './employee-endpoint.ts';
+import { employeeRouting } from './employee-relay.ts';
+import type { DetailObservation } from './conversation-details.ts';
+import type { EmployeeShell } from './employee-shell.ts';
+export declare const EMPLOYEE_MCP_TOOLS: Tool[];
+/** Same newline-delimited MCP messages as stdio, over an employee-only Unix stream. */
+export declare class EmployeeSocketTransport implements Transport {
+    private socket;
+    private maxBytes;
+    onclose?: () => void;
+    onerror?: (error: Error) => void;
+    onmessage?: (message: JSONRPCMessage) => void;
+    private pending;
+    private ended;
+    private failure?;
+    get error(): Error | undefined;
+    private readonly lifetime;
+    readonly signal: AbortSignal;
+    constructor(socket: Socket, maxBytes: number);
+    private failed;
+    start(): Promise<void>;
+    send(message: JSONRPCMessage): Promise<void>;
+    close(): Promise<void>;
+}
+export interface EmployeeMcpOptions {
+    lease: EmployeeLease;
+    maxBytes: number;
+    killGraceMs: number;
+    activeSignal: () => AbortSignal | undefined;
+    detail: (event: DetailObservation) => void;
+    captureDetail?: () => ((event: DetailObservation) => void);
+    runShell?: EmployeeShell;
+}
+export interface EmployeeMcp {
+    routing: ReturnType<typeof employeeRouting>;
+    signal: AbortSignal;
+    close(): Promise<void>;
+}
+export declare function openEmployeeMcp(options: EmployeeMcpOptions): Promise<EmployeeMcp>;