@atelierai/uco 1.0.0

package/dist/server/app.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Server factory — create and wire the HTTP + WebSocket server.
+ *
+ * createServer(config) returns a { start(), stop() } handle.
+ */
+import { type Server } from 'node:http';
+import type { Server as NetServer } from 'node:net';
+import { type ServerConfig } from './config.js';
+import { ConnectionRegistry } from './ws/registry.js';
+import { McpHub } from './ws/hub.js';
+import { SessionStateStore } from './session/store.js';
+export interface McpServerHandle {
+    /** The underlying HTTP server. */
+    httpServer: Server;
+    /** The WebSocket hub. */
+    hub: McpHub;
+    /** The connection registry. */
+    registry: ConnectionRegistry;
+    /** The session store. */
+    sessionStore: SessionStateStore;
+    /** Start listening. Returns a promise that resolves when listening. */
+    start(): Promise<ListeningAddress>;
+    /** Attach HTTP handling to an already-listening socket received over Node IPC. */
+    startWithHandle(handle: NetServer): Promise<ListeningAddress>;
+    /** Stop the server and clean up. */
+    stop(): Promise<void>;
+}
+export interface ListeningAddress {
+    address: string;
+    family: string;
+    port: number;
+}
+export interface OwnedServerRuntime {
+    serverInstanceId: string;
+    phase: 'precommit' | 'committed';
+}
+/**
+ * Create the MCP server: HTTP REST + WebSocket hub.
+ *
+ * @param config Server configuration.
+ */
+export declare function createServer(config: ServerConfig, ownedRuntime?: OwnedServerRuntime): McpServerHandle;

package/dist/server/app.js

@@ -0,0 +1,109 @@
+/**
+ * Server factory — create and wire the HTTP + WebSocket server.
+ *
+ * createServer(config) returns a { start(), stop() } handle.
+ */
+import { createServer as createHttpServer } from 'node:http';
+import { validateServerConfig } from './config.js';
+import { ConnectionRegistry } from './ws/registry.js';
+import { PendingTracker } from './ws/pending.js';
+import { McpHub } from './ws/hub.js';
+import { SessionStateStore } from './session/store.js';
+import { CallRecordStore } from './calls/call-record-store.js';
+import { createRestRouter } from './rest/router.js';
+/**
+ * Create the MCP server: HTTP REST + WebSocket hub.
+ *
+ * @param config Server configuration.
+ */
+export function createServer(config, ownedRuntime) {
+    const validated = validateServerConfig(config);
+    const multiPlugin = validated.authorization === 'required';
+    const registry = new ConnectionRegistry(multiPlugin);
+    const pending = new PendingTracker();
+    const sessionStore = new SessionStateStore();
+    const callRecords = new CallRecordStore();
+    const clientData = [];
+    const hub = new McpHub({
+        registry,
+        pending,
+        authToken: validated.token,
+        serverApiVersion: validated.serverApiVersion,
+        serverVersion: validated.serverVersion,
+        heartbeatIntervalMs: validated.heartbeatIntervalMs,
+        clientData,
+        ownedRuntime,
+        onCallRecordCompleted: (requestId, operationId, result, isError) => {
+            callRecords.completeByRequestId(requestId, operationId, result, isError);
+        },
+    });
+    const restCtx = {
+        registry,
+        pending,
+        hub,
+        sessionStore,
+        callRecords,
+        pluginTimeoutMs: validated.pluginTimeoutMs,
+        authToken: validated.token,
+        ownedRuntime,
+    };
+    const requestListener = createRestRouter(restCtx);
+    const httpServer = createHttpServer(requestListener);
+    // Attach the WebSocket hub to the HTTP server.
+    hub.attach(httpServer);
+    // Start the session sweeper and the call-record sweeper.
+    sessionStore.startSweeper();
+    const callRecordSweeper = callRecords.startSweeper();
+    const listeningAddress = () => {
+        const address = httpServer.address();
+        if (address === null || typeof address === 'string') {
+            throw new Error('Node MCP Server did not report an IP listening address.');
+        }
+        const info = address;
+        return { address: info.address, family: info.family, port: info.port };
+    };
+    const listen = (target) => {
+        return new Promise((resolve, reject) => {
+            const onError = (error) => {
+                httpServer.removeListener('listening', onListening);
+                reject(error);
+            };
+            const onListening = () => {
+                httpServer.removeListener('error', onError);
+                try {
+                    resolve(listeningAddress());
+                }
+                catch (error) {
+                    reject(error);
+                }
+            };
+            httpServer.once('error', onError);
+            httpServer.once('listening', onListening);
+            if ('port' in target)
+                httpServer.listen(target.port, target.host);
+            else
+                httpServer.listen(target);
+        });
+    };
+    return {
+        httpServer,
+        hub,
+        registry,
+        sessionStore,
+        start() {
+            return listen({ port: validated.port, host: validated.listenHost });
+        },
+        startWithHandle(handle) {
+            return listen(handle);
+        },
+        stop() {
+            return new Promise((resolve) => {
+                hub.close();
+                sessionStore.dispose();
+                clearInterval(callRecordSweeper);
+                httpServer.close(() => resolve());
+            });
+        },
+    };
+}
+//# sourceMappingURL=app.js.map

package/dist/server/app.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.js","sourceRoot":"","sources":["../../src/server/app.ts"],"names":[],"mappings":"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"}

package/dist/server/calls/call-record-store.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Bounded durable call records (COCli-09) — one entry per forwarded tool
+ * call, queryable by callId so an observed transport timeout ("result
+ * unknown") can be resolved to a terminal state afterwards.
+ *
+ * The store intentionally survives PendingTracker settlement: durable tools
+ * reply `processing` immediately (settling the tracker entry), and the late
+ * NotifyToolRequestCompleted would otherwise be dropped. A requestId→callId
+ * index here is the authoritative correlation for those late completions.
+ *
+ * Records are process-local and bounded (count + TTL); they are diagnostics,
+ * not a durable queue.
+ */
+export type CallRecordState = 'pending' | 'processing' | 'succeeded' | 'failed' | 'cancelled' | 'abandoned';
+export type AbandonReason = 'server-wait-timeout' | 'caller-disconnect';
+export interface CallRecordError {
+    code: string;
+    message: string;
+    retryable: boolean;
+}
+export interface CallRecord {
+    callId: string;
+    requestId: string;
+    tool: string;
+    mode: 'sync' | 'async';
+    state: CallRecordState;
+    abandonReason?: AbandonReason;
+    /** A terminal completion arrived after the server stopped waiting. */
+    lateCompletion?: boolean;
+    operationId?: string;
+    identity?: Record<string, unknown>;
+    connectionId?: string;
+    generation?: number;
+    createdAtUtc: string;
+    dispatchedAtUtc?: string;
+    settledAtUtc?: string;
+    /** Bounded first text of the terminal result (≤1024 chars). */
+    resultPreview?: string;
+    error?: CallRecordError;
+}
+export declare const MAX_CALL_RECORDS = 256;
+export declare const CALL_RECORD_TTL_MS: number;
+export interface CallRecordBeginInput {
+    callId: string;
+    requestId: string;
+    tool: string;
+    mode: 'sync' | 'async';
+    connectionId?: string;
+    generation?: number;
+}
+interface TerminalResponseShape {
+    status?: string | null;
+    message?: string | null;
+    /** ResponseData<ResponseCallTool> nests content under `value`; a deferred completion result carries it at the top level. */
+    content?: {
+        type?: string | null;
+        text?: string | null;
+    }[] | null;
+    value?: {
+        content?: {
+            type?: string | null;
+            text?: string | null;
+        }[] | null;
+    } | null;
+    error?: {
+        code?: unknown;
+        message?: unknown;
+        retryable?: unknown;
+    } | null;
+}
+export declare class CallRecordStore {
+    private readonly byCallId;
+    private readonly callIdByRequestId;
+    begin(input: CallRecordBeginInput): void;
+    markDispatched(callId: string, identity?: Record<string, unknown>): void;
+    noteOperationId(callId: string, operationId: string | undefined): void;
+    /** Settle from a plugin ResponseData envelope (sync/async forward completion). */
+    settleFromResponse(callId: string, response: TerminalResponseShape | null): void;
+    settleFailed(callId: string, error: CallRecordError): void;
+    settleCancelled(callId: string): void;
+    /** The server stopped waiting; the plugin may still complete the work late. */
+    settleAbandoned(callId: string, reason: AbandonReason): void;
+    /**
+     * Late/deferred completion by requestId — works even after the pending
+     * tracker settled or expired. Flips abandoned records to their terminal
+     * state with `lateCompletion: true`.
+     */
+    completeByRequestId(requestId: string, operationId: string | undefined, result: unknown, isError: boolean): void;
+    get(callId: string): CallRecord | undefined;
+    list(opts?: {
+        limit?: number;
+        state?: CallRecordState;
+    }): CallRecord[];
+    /** Evict records past the TTL; returns the number removed. */
+    sweep(now?: number): number;
+    startSweeper(intervalMs?: number): ReturnType<typeof setInterval>;
+    private evictIfNeeded;
+}
+export {};

package/dist/server/calls/call-record-store.js

@@ -0,0 +1,240 @@
+/**
+ * Bounded durable call records (COCli-09) — one entry per forwarded tool
+ * call, queryable by callId so an observed transport timeout ("result
+ * unknown") can be resolved to a terminal state afterwards.
+ *
+ * The store intentionally survives PendingTracker settlement: durable tools
+ * reply `processing` immediately (settling the tracker entry), and the late
+ * NotifyToolRequestCompleted would otherwise be dropped. A requestId→callId
+ * index here is the authoritative correlation for those late completions.
+ *
+ * Records are process-local and bounded (count + TTL); they are diagnostics,
+ * not a durable queue.
+ */
+export const MAX_CALL_RECORDS = 256;
+export const CALL_RECORD_TTL_MS = 30 * 60_000;
+const MAX_TOOL_NAME_LENGTH = 160;
+const MAX_TEXT_LENGTH = 1024;
+const GENERIC_TOOL_FAILURE_MESSAGES = new Set(['Tool call failed.', 'Tool execution failed.']);
+export class CallRecordStore {
+    byCallId = new Map();
+    callIdByRequestId = new Map();
+    begin(input) {
+        const callId = boundText(input.callId, 160);
+        const requestId = boundText(input.requestId, 160);
+        if (callId === undefined || requestId === undefined)
+            return;
+        const record = {
+            callId,
+            requestId,
+            tool: boundText(input.tool, MAX_TOOL_NAME_LENGTH) ?? '(unknown)',
+            mode: input.mode,
+            state: 'pending',
+            createdAtUtc: new Date().toISOString(),
+            ...(input.connectionId !== undefined ? { connectionId: input.connectionId } : {}),
+            ...(input.generation !== undefined ? { generation: input.generation } : {}),
+        };
+        // A re-issued callId supersedes the earlier record entirely.
+        this.byCallId.delete(callId);
+        this.evictIfNeeded();
+        this.byCallId.set(callId, record);
+        this.callIdByRequestId.set(requestId, callId);
+    }
+    markDispatched(callId, identity) {
+        const record = this.byCallId.get(callId);
+        if (!record)
+            return;
+        if (record.state === 'pending')
+            record.state = 'processing';
+        record.dispatchedAtUtc = new Date().toISOString();
+        if (identity !== undefined && record.identity === undefined) {
+            record.identity = identity;
+        }
+    }
+    noteOperationId(callId, operationId) {
+        if (operationId === undefined)
+            return;
+        const record = this.byCallId.get(callId);
+        if (record && record.operationId === undefined)
+            record.operationId = boundText(operationId, 160);
+    }
+    /** Settle from a plugin ResponseData envelope (sync/async forward completion). */
+    settleFromResponse(callId, response) {
+        const record = this.byCallId.get(callId);
+        if (!record || isTerminal(record))
+            return;
+        if (response === null || response === undefined) {
+            this.settleFailed(callId, { code: 'tool_execution_failed', message: 'Tool hub returned a null response.', retryable: false });
+            return;
+        }
+        const status = typeof response.status === 'string' ? response.status.toLowerCase() : undefined;
+        if (status === 'error') {
+            const message = boundText(pickDiagnostic(response.error?.message, firstText(response)), MAX_TEXT_LENGTH) ?? 'Tool execution failed.';
+            const code = typeof response.error?.code === 'string' && response.error.code.length > 0
+                ? response.error.code
+                : 'tool_execution_failed';
+            this.settleFailed(callId, { code, message, retryable: response.error?.retryable === true });
+            return;
+        }
+        if (status === 'processing') {
+            record.state = 'processing';
+            const preview = firstText(response);
+            if (preview !== undefined)
+                record.resultPreview = preview;
+            record.settledAtUtc = new Date().toISOString();
+            return;
+        }
+        record.state = 'succeeded';
+        const preview = firstText(response);
+        if (preview !== undefined)
+            record.resultPreview = preview;
+        record.settledAtUtc = new Date().toISOString();
+    }
+    settleFailed(callId, error) {
+        const record = this.byCallId.get(callId);
+        if (!record || isTerminal(record))
+            return;
+        record.state = 'failed';
+        record.error = {
+            code: boundText(error.code, 160) ?? 'tool_execution_failed',
+            message: boundText(error.message, MAX_TEXT_LENGTH) ?? 'Tool execution failed.',
+            retryable: error.retryable === true,
+        };
+        record.settledAtUtc = new Date().toISOString();
+    }
+    settleCancelled(callId) {
+        const record = this.byCallId.get(callId);
+        if (!record || isTerminal(record))
+            return;
+        record.state = 'cancelled';
+        record.settledAtUtc = new Date().toISOString();
+    }
+    /** The server stopped waiting; the plugin may still complete the work late. */
+    settleAbandoned(callId, reason) {
+        const record = this.byCallId.get(callId);
+        if (!record || isTerminal(record))
+            return;
+        record.state = 'abandoned';
+        record.abandonReason = reason;
+        record.settledAtUtc = new Date().toISOString();
+    }
+    /**
+     * Late/deferred completion by requestId — works even after the pending
+     * tracker settled or expired. Flips abandoned records to their terminal
+     * state with `lateCompletion: true`.
+     */
+    completeByRequestId(requestId, operationId, result, isError) {
+        const callId = this.callIdByRequestId.get(boundText(requestId, 160) ?? '');
+        if (callId === undefined)
+            return;
+        if (operationId !== undefined)
+            this.noteOperationId(callId, operationId);
+        const record = this.byCallId.get(callId);
+        if (!record)
+            return;
+        const wasAbandoned = record.state === 'abandoned' || record.state === 'pending' || record.state === 'processing';
+        if (isError) {
+            if (isTerminal(record) && record.state !== 'abandoned')
+                return;
+            record.state = 'failed';
+            const envelope = result;
+            const message = boundText(pickDiagnostic(envelope?.error?.message, firstText(envelope)), MAX_TEXT_LENGTH) ?? 'Deferred tool call failed.';
+            const code = typeof envelope?.error?.code === 'string' && envelope.error.code.length > 0
+                ? envelope.error.code
+                : 'tool_execution_failed';
+            record.error = { code, message, retryable: false };
+        }
+        else {
+            if (isTerminal(record) && record.state !== 'abandoned')
+                return;
+            record.state = 'succeeded';
+            const envelope = result;
+            const preview = firstText(envelope);
+            if (preview !== undefined)
+                record.resultPreview = preview;
+        }
+        if (wasAbandoned)
+            record.lateCompletion = true;
+        record.settledAtUtc = new Date().toISOString();
+    }
+    get(callId) {
+        return this.byCallId.get(callId);
+    }
+    list(opts) {
+        const limit = Math.max(1, Math.min(200, opts?.limit ?? 50));
+        const records = [...this.byCallId.values()].reverse();
+        const filtered = opts?.state === undefined
+            ? records
+            : records.filter((record) => record.state === opts.state);
+        return filtered.slice(0, limit);
+    }
+    /** Evict records past the TTL; returns the number removed. */
+    sweep(now = Date.now()) {
+        let removed = 0;
+        for (const [callId, record] of this.byCallId) {
+            const anchor = Date.parse(record.settledAtUtc ?? record.createdAtUtc);
+            if (Number.isFinite(anchor) && now - anchor > CALL_RECORD_TTL_MS) {
+                this.byCallId.delete(callId);
+                if (this.callIdByRequestId.get(record.requestId) === callId) {
+                    this.callIdByRequestId.delete(record.requestId);
+                }
+                removed++;
+            }
+        }
+        return removed;
+    }
+    startSweeper(intervalMs = 5 * 60_000) {
+        const timer = setInterval(() => {
+            this.sweep();
+        }, intervalMs);
+        timer.unref?.();
+        return timer;
+    }
+    evictIfNeeded() {
+        while (this.byCallId.size >= MAX_CALL_RECORDS) {
+            const oldest = this.byCallId.keys().next().value;
+            if (oldest === undefined)
+                break;
+            const record = this.byCallId.get(oldest);
+            this.byCallId.delete(oldest);
+            if (record && this.callIdByRequestId.get(record.requestId) === oldest) {
+                this.callIdByRequestId.delete(record.requestId);
+            }
+        }
+    }
+}
+function isTerminal(record) {
+    return record.state === 'succeeded' || record.state === 'failed'
+        || record.state === 'cancelled' || record.state === 'abandoned';
+}
+function firstText(response) {
+    const content = response?.content ?? response?.value?.content;
+    if (!Array.isArray(content))
+        return undefined;
+    for (const block of content) {
+        if (block?.type !== 'text' || typeof block.text !== 'string')
+            continue;
+        const trimmed = block.text.trim();
+        if (trimmed.length > 0)
+            return trimmed.length <= MAX_TEXT_LENGTH ? trimmed : `${trimmed.slice(0, MAX_TEXT_LENGTH)}…`;
+    }
+    return undefined;
+}
+function boundText(value, max) {
+    if (typeof value !== 'string')
+        return undefined;
+    const trimmed = value.trim();
+    if (trimmed.length === 0)
+        return undefined;
+    return trimmed.length <= max ? trimmed : trimmed.slice(0, max);
+}
+/** Prefer an actionable diagnostic over a generic placeholder message. */
+function pickDiagnostic(structuredMessage, contentText) {
+    if (typeof structuredMessage === 'string'
+        && structuredMessage.trim().length > 0
+        && !GENERIC_TOOL_FAILURE_MESSAGES.has(structuredMessage.trim())) {
+        return structuredMessage;
+    }
+    return contentText ?? (typeof structuredMessage === 'string' && structuredMessage.trim().length > 0 ? structuredMessage : undefined);
+}
+//# sourceMappingURL=call-record-store.js.map

package/dist/server/calls/call-record-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"call-record-store.js","sourceRoot":"","sources":["../../../src/server/calls/call-record-store.ts"],"names":[],"mappings":"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"}

package/dist/server/config.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Server configuration — parse CLI args into a ServerConfig object.
+ *
+ * Mirrors the .NET DataArguments parameters.
+ */
+export interface ServerConfig {
+    /** Port to listen on (default 8080). */
+    port: number;
+    /** Socket bind host (default loopback-only 127.0.0.1). */
+    listenHost: string;
+    /** Explicit acknowledgement that a non-loopback socket may be opened. */
+    allowLan: boolean;
+    /** Bearer token for auth (empty = no auth). */
+    token?: string;
+    /** Authorization mode: 'none' or 'required' (inferred from token). */
+    authorization: 'none' | 'required';
+    /** Plugin forward timeout in ms (default 10000). */
+    pluginTimeoutMs: number;
+    /** Application heartbeat interval in ms (default 20000). */
+    heartbeatIntervalMs: number;
+    /** Optional webhook URL for analytics events. */
+    webhookUrl?: string;
+    /** Server API version string. */
+    serverApiVersion: string;
+    /** Server version string. */
+    serverVersion: string;
+}
+export declare const DEFAULT_SERVER_API_VERSION = "2.0.0";
+export declare const DEFAULT_SERVER_VERSION = "0.2.1-node";
+/**
+ * Parse CLI args into a ServerConfig.
+ * Supports: --port, --listen-host, --allow-lan, --token, --authorization,
+ * --plugin-timeout-ms, --heartbeat-interval-ms, --webhook-url
+ */
+export declare function parseServerConfig(args: string[], environment?: Readonly<Record<string, string | undefined>>): ServerConfig;
+/** Normalize brackets used in URL-form IPv6 literals before socket binding. */
+export declare function normalizeListenHost(host: string): string;
+/** Classify loopback without resolving arbitrary DNS names. */
+export declare function isLoopbackHost(host: string): boolean;
+/**
+ * Re-check the transport security contract at the public server boundary.
+ * Programmatic callers therefore cannot bypass the CLI parser's validation.
+ */
+export declare function validateServerConfig(config: ServerConfig): ServerConfig;