@roamcode.ai/server 1.0.0

package/dist/providers/codex-app-server-client.d.ts

@@ -0,0 +1,90 @@
+import { EventEmitter } from "node:events";
+import { type ZodType } from "zod";
+export declare const CODEX_METADATA_ERROR_CODE: "CODEX_METADATA_UNAVAILABLE";
+export declare const DEFAULT_CODEX_APP_SERVER_TIMEOUT_MS = 15000;
+export declare const DEFAULT_CODEX_APP_SERVER_MAX_STDOUT_LINE_BYTES: number;
+export declare const DEFAULT_CODEX_APP_SERVER_MAX_STDOUT_BUFFER_BYTES: number;
+export declare const DEFAULT_CODEX_APP_SERVER_MAX_STDERR_BYTES: number;
+type DiagnosticIssue = "exit" | "malformed_json" | "notification_listener" | "spawn" | "stderr_limit" | "stdout_limit" | "transport_error" | "unknown_message" | "write_error";
+export interface CodexMetadataDiagnostics {
+    readonly lastIssue?: DiagnosticIssue;
+    readonly stderrBytes: number;
+    readonly stderrTruncated: boolean;
+}
+export interface CodexAppServerNotification {
+    readonly method: string;
+    readonly params?: unknown;
+}
+interface WritableTransport extends EventEmitter {
+    write(value: string | Uint8Array, callback?: (error?: Error | null) => void): boolean;
+    end(): void;
+}
+type ReadableTransport = EventEmitter;
+/** The intentionally small child-process surface used by the protocol client and its fake tests. */
+export interface CodexAppServerTransport extends EventEmitter {
+    readonly stdin: WritableTransport;
+    readonly stdout: ReadableTransport;
+    readonly stderr: ReadableTransport;
+    kill(signal?: NodeJS.Signals): boolean | void;
+}
+export type SpawnCodexAppServerTransport = (command: string, args: readonly string[], options?: {
+    readonly env?: NodeJS.ProcessEnv;
+}) => CodexAppServerTransport;
+export interface CodexAppServerClientOptions {
+    readonly codexBin?: string;
+    /** Selects one validated `$CODEX_HOME/<name>.config.toml` layer before app-server starts. */
+    readonly profile?: string;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly spawnTransport?: SpawnCodexAppServerTransport;
+    readonly timeoutMs?: number;
+    readonly maxStdoutLineBytes?: number;
+    readonly maxStdoutBufferBytes?: number;
+    readonly maxStderrBytes?: number;
+}
+export declare class CodexMetadataUnavailableError extends Error {
+    readonly code: "CODEX_METADATA_UNAVAILABLE";
+    constructor();
+}
+/**
+ * Bounded JSON-lines client for the auxiliary Codex app-server metadata channel.
+ * It never participates in terminal streaming and deliberately knows no method-specific result schemas.
+ */
+export declare class CodexAppServerClient {
+    readonly limits: {
+        readonly timeoutMs: number;
+        readonly maxStdoutLineBytes: number;
+        readonly maxStdoutBufferBytes: number;
+        readonly maxStderrBytes: number;
+    };
+    private readonly codexBin;
+    private readonly profile?;
+    private readonly env?;
+    private readonly spawnTransport;
+    private readonly notificationListeners;
+    private active?;
+    private startPromise?;
+    private stopPromise?;
+    private nextRequestId;
+    private nextGeneration;
+    private lastDiagnostics;
+    constructor(options?: CodexAppServerClientOptions);
+    get diagnostics(): CodexMetadataDiagnostics;
+    start(): Promise<void>;
+    request<T>(method: string, params: unknown, schema: ZodType<T>): Promise<T>;
+    onNotification(listener: (notification: CodexAppServerNotification) => void): () => void;
+    stop(): Promise<void>;
+    private createGeneration;
+    private installListeners;
+    private sendRequest;
+    private writeFrame;
+    private flushWrites;
+    private onStdout;
+    private onMessage;
+    private resolveResponse;
+    private rejectResponse;
+    private onStderr;
+    private failGeneration;
+    private removeListeners;
+    private recordIssue;
+}
+export {};

package/dist/providers/codex-app-server-client.js

@@ -0,0 +1,485 @@
+import { spawn } from "node:child_process";
+import { EventEmitter } from "node:events";
+import { z } from "zod";
+export const CODEX_METADATA_ERROR_CODE = "CODEX_METADATA_UNAVAILABLE";
+export const DEFAULT_CODEX_APP_SERVER_TIMEOUT_MS = 15_000;
+export const DEFAULT_CODEX_APP_SERVER_MAX_STDOUT_LINE_BYTES = 1024 * 1024;
+export const DEFAULT_CODEX_APP_SERVER_MAX_STDOUT_BUFFER_BYTES = 2 * 1024 * 1024;
+export const DEFAULT_CODEX_APP_SERVER_MAX_STDERR_BYTES = 64 * 1024;
+export class CodexMetadataUnavailableError extends Error {
+    code = CODEX_METADATA_ERROR_CODE;
+    constructor() {
+        super("Codex metadata is unavailable");
+        this.name = "CodexMetadataUnavailableError";
+    }
+}
+const JsonRpcSuccessSchema = z.object({
+    jsonrpc: z.literal("2.0").optional(),
+    id: z.number().int().nonnegative(),
+    result: z.unknown(),
+});
+const JsonRpcErrorSchema = z.object({
+    jsonrpc: z.literal("2.0").optional(),
+    id: z.number().int().nonnegative(),
+    error: z.object({
+        code: z.number().int(),
+        message: z.string(),
+        data: z.unknown().optional(),
+    }),
+});
+const JsonRpcNotificationSchema = z.object({
+    jsonrpc: z.literal("2.0").optional(),
+    method: z.string().min(1),
+    params: z.unknown().optional(),
+});
+const InitializeResultSchema = z.unknown();
+function unavailable() {
+    return new CodexMetadataUnavailableError();
+}
+// Node writable streams may invoke a failed write callback and emit `error` afterwards. This
+// closure-free sink deliberately stays on a dead transport so that late stream errors can never
+// become uncaught host-process exceptions after the generation's active listeners are removed.
+const absorbLateTransportError = () => { };
+function positiveInteger(value, fallback) {
+    return value !== undefined && Number.isSafeInteger(value) && value > 0 ? value : fallback;
+}
+function defaultSpawnTransport(command, args, options) {
+    return spawn(command, [...args], { env: options?.env, stdio: ["pipe", "pipe", "pipe"] });
+}
+/**
+ * Bounded JSON-lines client for the auxiliary Codex app-server metadata channel.
+ * It never participates in terminal streaming and deliberately knows no method-specific result schemas.
+ */
+export class CodexAppServerClient {
+    limits;
+    codexBin;
+    profile;
+    env;
+    spawnTransport;
+    notificationListeners = new Set();
+    active;
+    startPromise;
+    stopPromise;
+    nextRequestId = 1;
+    nextGeneration = 1;
+    lastDiagnostics = { stderrBytes: 0, stderrTruncated: false };
+    constructor(options = {}) {
+        this.codexBin = options.codexBin ?? "codex";
+        this.env = options.env ? { ...options.env } : undefined;
+        if (options.profile !== undefined &&
+            (options.profile.length === 0 ||
+                options.profile.length > 128 ||
+                !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(options.profile))) {
+            throw unavailable();
+        }
+        this.profile = options.profile;
+        this.spawnTransport = options.spawnTransport ?? defaultSpawnTransport;
+        const maxStdoutLineBytes = positiveInteger(options.maxStdoutLineBytes, DEFAULT_CODEX_APP_SERVER_MAX_STDOUT_LINE_BYTES);
+        this.limits = {
+            timeoutMs: positiveInteger(options.timeoutMs, DEFAULT_CODEX_APP_SERVER_TIMEOUT_MS),
+            maxStdoutLineBytes,
+            maxStdoutBufferBytes: positiveInteger(options.maxStdoutBufferBytes, DEFAULT_CODEX_APP_SERVER_MAX_STDOUT_BUFFER_BYTES),
+            maxStderrBytes: positiveInteger(options.maxStderrBytes, DEFAULT_CODEX_APP_SERVER_MAX_STDERR_BYTES),
+        };
+    }
+    get diagnostics() {
+        const generation = this.active;
+        return generation
+            ? {
+                ...this.lastDiagnostics,
+                stderrBytes: generation.stderrBytes,
+                stderrTruncated: generation.stderrTruncated,
+            }
+            : { ...this.lastDiagnostics };
+    }
+    start() {
+        if (this.active?.phase === "running" && !this.active.closed)
+            return Promise.resolve();
+        if (this.startPromise)
+            return this.startPromise;
+        if (this.stopPromise)
+            return this.stopPromise.then(() => this.start());
+        let transport;
+        try {
+            transport = this.spawnTransport(this.codexBin, this.profile ? ["--profile", this.profile, "app-server", "--stdio"] : ["app-server", "--stdio"], { env: this.env ? { ...this.env } : undefined });
+        }
+        catch {
+            this.recordIssue("spawn");
+            return Promise.reject(unavailable());
+        }
+        const generation = this.createGeneration(transport);
+        this.active = generation;
+        this.lastDiagnostics = { stderrBytes: 0, stderrTruncated: false };
+        this.installListeners(generation);
+        const promise = this.sendRequest(generation, "initialize", {
+            clientInfo: { name: "roamcode", title: "RoamCode", version: "0.0.0" },
+            capabilities: {},
+        }, InitializeResultSchema)
+            .then(() => this.writeFrame(generation, { method: "initialized", params: {} }))
+            .then(() => {
+            if (generation.closed || this.active !== generation)
+                throw unavailable();
+            generation.phase = "running";
+        })
+            .catch(() => {
+            if (!generation.closed)
+                this.failGeneration(generation, "transport_error", true);
+            throw unavailable();
+        });
+        this.startPromise = promise;
+        void promise.then(() => {
+            if (this.startPromise === promise)
+                this.startPromise = undefined;
+        }, () => {
+            if (this.startPromise === promise)
+                this.startPromise = undefined;
+        });
+        return promise;
+    }
+    request(method, params, schema) {
+        const generation = this.active;
+        if (!generation || generation.closed || generation.phase !== "running" || !method) {
+            return Promise.reject(unavailable());
+        }
+        return this.sendRequest(generation, method, params, schema);
+    }
+    onNotification(listener) {
+        this.notificationListeners.add(listener);
+        return () => this.notificationListeners.delete(listener);
+    }
+    stop() {
+        if (this.stopPromise)
+            return this.stopPromise;
+        const promise = Promise.resolve();
+        this.stopPromise = promise;
+        const generation = this.active;
+        if (generation)
+            this.failGeneration(generation, "transport_error", true, true);
+        void promise.then(() => {
+            if (this.stopPromise === promise)
+                this.stopPromise = undefined;
+        });
+        return promise;
+    }
+    createGeneration(transport) {
+        const generation = {
+            number: this.nextGeneration++,
+            transport,
+            pending: new Map(),
+            writeQueue: [],
+            stdoutBuffer: Buffer.alloc(0),
+            stderrBytes: 0,
+            stderrTruncated: false,
+            phase: "starting",
+            closed: false,
+            writing: false,
+            listeners: {
+                stdoutData: (chunk) => this.onStdout(generation, chunk),
+                stderrData: (chunk) => this.onStderr(generation, chunk),
+                exit: () => this.failGeneration(generation, "exit", false),
+                error: () => this.failGeneration(generation, "transport_error", true),
+                stdinError: () => this.failGeneration(generation, "write_error", true),
+                stdoutError: () => this.failGeneration(generation, "transport_error", true),
+                stderrError: () => this.failGeneration(generation, "transport_error", true),
+            },
+        };
+        return generation;
+    }
+    installListeners(generation) {
+        const { transport, listeners } = generation;
+        transport.on("error", absorbLateTransportError);
+        transport.stdin.on("error", absorbLateTransportError);
+        transport.stdout.on("error", absorbLateTransportError);
+        transport.stderr.on("error", absorbLateTransportError);
+        transport.stdout.on("data", listeners.stdoutData);
+        transport.stderr.on("data", listeners.stderrData);
+        transport.on("exit", listeners.exit);
+        transport.on("error", listeners.error);
+        transport.stdin.on("error", listeners.stdinError);
+        transport.stdout.on("error", listeners.stdoutError);
+        transport.stderr.on("error", listeners.stderrError);
+    }
+    sendRequest(generation, method, params, schema) {
+        if (generation.closed || this.active !== generation)
+            return Promise.reject(unavailable());
+        const id = this.nextRequestId++;
+        const response = new Promise((resolve, reject) => {
+            const timer = setTimeout(() => this.failGeneration(generation, "transport_error", true), this.limits.timeoutMs);
+            generation.pending.set(id, {
+                schema: schema,
+                resolve: (value) => resolve(value),
+                reject,
+                timer,
+            });
+        });
+        const written = this.writeFrame(generation, { id, method, params }).catch(() => {
+            if (!generation.closed) {
+                this.failGeneration(generation, "write_error", true);
+            }
+            throw unavailable();
+        });
+        return Promise.all([written, response]).then(([, value]) => value);
+    }
+    writeFrame(generation, value) {
+        if (generation.closed || this.active !== generation)
+            return Promise.reject(unavailable());
+        let frame;
+        try {
+            frame = `${JSON.stringify(value)}\n`;
+        }
+        catch {
+            return Promise.reject(unavailable());
+        }
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                if (!generation.closed)
+                    this.failGeneration(generation, "write_error", true);
+            }, this.limits.timeoutMs);
+            generation.writeQueue.push({ frame, resolve, reject, timer });
+            this.flushWrites(generation);
+        });
+    }
+    flushWrites(generation) {
+        if (generation.closed || generation.writing)
+            return;
+        const entry = generation.writeQueue[0];
+        if (!entry)
+            return;
+        generation.writing = true;
+        let callbackDone = false;
+        let drainDone = false;
+        let writeReturned = false;
+        let settled = false;
+        const finish = () => {
+            if (settled || generation.closed || !writeReturned || !callbackDone || !drainDone)
+                return;
+            settled = true;
+            generation.writeQueue.shift();
+            generation.writing = false;
+            clearTimeout(entry.timer);
+            entry.resolve();
+            this.flushWrites(generation);
+        };
+        try {
+            const accepted = generation.transport.stdin.write(entry.frame, (error) => {
+                if (generation.closed)
+                    return;
+                if (error) {
+                    this.failGeneration(generation, "write_error", true);
+                    return;
+                }
+                callbackDone = true;
+                finish();
+            });
+            writeReturned = true;
+            if (generation.closed)
+                return;
+            if (accepted) {
+                drainDone = true;
+            }
+            else {
+                const onDrain = () => {
+                    if (generation.drainListener === onDrain)
+                        generation.drainListener = undefined;
+                    drainDone = true;
+                    finish();
+                };
+                generation.drainListener = onDrain;
+                generation.transport.stdin.once("drain", onDrain);
+            }
+            finish();
+        }
+        catch {
+            this.failGeneration(generation, "write_error", true);
+        }
+    }
+    onStdout(generation, value) {
+        if (generation.closed || this.active !== generation)
+            return;
+        const chunk = Buffer.isBuffer(value) ? value : Buffer.from(value);
+        if (generation.stdoutBuffer.length + chunk.length > this.limits.maxStdoutBufferBytes) {
+            this.failGeneration(generation, "stdout_limit", true);
+            return;
+        }
+        generation.stdoutBuffer = Buffer.concat([generation.stdoutBuffer, chunk]);
+        for (;;) {
+            const newline = generation.stdoutBuffer.indexOf(0x0a);
+            if (newline < 0) {
+                if (generation.stdoutBuffer.length > this.limits.maxStdoutLineBytes) {
+                    this.failGeneration(generation, "stdout_limit", true);
+                }
+                return;
+            }
+            let line = generation.stdoutBuffer.subarray(0, newline);
+            generation.stdoutBuffer = generation.stdoutBuffer.subarray(newline + 1);
+            if (line.at(-1) === 0x0d)
+                line = line.subarray(0, -1);
+            if (line.length > this.limits.maxStdoutLineBytes) {
+                this.failGeneration(generation, "stdout_limit", true);
+                return;
+            }
+            if (line.length === 0)
+                continue;
+            let parsed;
+            try {
+                parsed = JSON.parse(line.toString("utf8"));
+            }
+            catch {
+                this.failGeneration(generation, "malformed_json", true);
+                return;
+            }
+            this.onMessage(generation, parsed);
+            if (generation.closed)
+                return;
+        }
+    }
+    onMessage(generation, message) {
+        if (typeof message !== "object" || message === null || Array.isArray(message)) {
+            this.recordIssue("unknown_message", generation);
+            return;
+        }
+        const hasId = Object.hasOwn(message, "id");
+        const hasResult = Object.hasOwn(message, "result");
+        const hasError = Object.hasOwn(message, "error");
+        const hasMethod = Object.hasOwn(message, "method");
+        if (hasId && hasResult && !hasError && !hasMethod) {
+            const success = JsonRpcSuccessSchema.safeParse(message);
+            if (success.success) {
+                this.resolveResponse(generation, success.data.id, success.data.result);
+                return;
+            }
+        }
+        else if (hasId && hasError && !hasResult && !hasMethod) {
+            const failure = JsonRpcErrorSchema.safeParse(message);
+            if (failure.success) {
+                this.rejectResponse(generation, failure.data.id);
+                return;
+            }
+        }
+        else if (hasMethod && !hasId && !hasResult && !hasError) {
+            const notification = JsonRpcNotificationSchema.safeParse(message);
+            if (!notification.success) {
+                this.recordIssue("unknown_message", generation);
+                return;
+            }
+            const value = {
+                method: notification.data.method,
+                ...(Object.hasOwn(notification.data, "params") ? { params: notification.data.params } : {}),
+            };
+            for (const listener of this.notificationListeners) {
+                try {
+                    listener(value);
+                }
+                catch {
+                    this.recordIssue("notification_listener", generation);
+                }
+            }
+            return;
+        }
+        this.recordIssue("unknown_message", generation);
+    }
+    resolveResponse(generation, id, result) {
+        const pending = generation.pending.get(id);
+        if (!pending) {
+            this.recordIssue("unknown_message", generation);
+            return;
+        }
+        generation.pending.delete(id);
+        clearTimeout(pending.timer);
+        try {
+            const parsed = pending.schema.safeParse(result);
+            if (parsed.success)
+                pending.resolve(parsed.data);
+            else
+                pending.reject(unavailable());
+        }
+        catch {
+            pending.reject(unavailable());
+        }
+    }
+    rejectResponse(generation, id) {
+        const pending = generation.pending.get(id);
+        if (!pending) {
+            this.recordIssue("unknown_message", generation);
+            return;
+        }
+        generation.pending.delete(id);
+        clearTimeout(pending.timer);
+        pending.reject(unavailable());
+    }
+    onStderr(generation, value) {
+        if (generation.closed || this.active !== generation)
+            return;
+        const bytes = Buffer.isBuffer(value) ? value.length : Buffer.byteLength(value);
+        const remaining = this.limits.maxStderrBytes - generation.stderrBytes;
+        generation.stderrBytes += Math.min(remaining, bytes);
+        if (bytes > remaining) {
+            generation.stderrTruncated = true;
+            this.recordIssue("stderr_limit", generation);
+        }
+    }
+    failGeneration(generation, issue, kill, endStdin = false) {
+        if (generation.closed)
+            return;
+        generation.closed = true;
+        generation.writing = false;
+        if (this.active === generation)
+            this.startPromise = undefined;
+        this.recordIssue(issue, generation);
+        this.lastDiagnostics = {
+            ...this.lastDiagnostics,
+            stderrBytes: generation.stderrBytes,
+            stderrTruncated: generation.stderrTruncated,
+        };
+        if (this.active === generation)
+            this.active = undefined;
+        this.removeListeners(generation);
+        const error = unavailable();
+        for (const pending of generation.pending.values()) {
+            clearTimeout(pending.timer);
+            pending.reject(error);
+        }
+        generation.pending.clear();
+        for (const write of generation.writeQueue.splice(0)) {
+            clearTimeout(write.timer);
+            write.reject(error);
+        }
+        if (endStdin) {
+            try {
+                generation.transport.stdin.end();
+            }
+            catch {
+                // The same stable unavailable error already rejects every waiter.
+            }
+        }
+        if (kill) {
+            try {
+                generation.transport.kill("SIGKILL");
+            }
+            catch {
+                // The transport is already unavailable.
+            }
+        }
+    }
+    removeListeners(generation) {
+        const { transport, listeners } = generation;
+        transport.stdout.removeListener("data", listeners.stdoutData);
+        transport.stderr.removeListener("data", listeners.stderrData);
+        transport.removeListener("exit", listeners.exit);
+        transport.removeListener("error", listeners.error);
+        transport.stdin.removeListener("error", listeners.stdinError);
+        transport.stdout.removeListener("error", listeners.stdoutError);
+        transport.stderr.removeListener("error", listeners.stderrError);
+        if (generation.drainListener) {
+            transport.stdin.removeListener("drain", generation.drainListener);
+            generation.drainListener = undefined;
+        }
+    }
+    recordIssue(issue, generation) {
+        this.lastDiagnostics = {
+            lastIssue: issue,
+            stderrBytes: generation?.stderrBytes ?? this.lastDiagnostics.stderrBytes,
+            stderrTruncated: generation?.stderrTruncated ?? this.lastDiagnostics.stderrTruncated,
+        };
+    }
+}

package/dist/providers/codex-latest-service.d.ts

@@ -0,0 +1,50 @@
+export declare const CODEX_VERSION_UNAVAILABLE: "CODEX_VERSION_UNAVAILABLE";
+export declare const CODEX_VERSION_TIMEOUT_MS = 5000;
+export declare const CODEX_VERSION_MAX_OUTPUT_BYTES = 1024;
+export declare const CODEX_LATEST_MAX_RESPONSE_BYTES = 16384;
+export declare const DEFAULT_CODEX_VERSION_CACHE_TTL_MS: number;
+export type CodexInstallProvenance = "npm" | "chatgpt" | "homebrew" | "unknown";
+export interface BoundedVersionRunOptions {
+    readonly timeoutMs: number;
+    readonly maxOutputBytes: number;
+}
+export interface BoundedLatestFetchOptions {
+    readonly timeoutMs: number;
+    readonly maxResponseBytes: number;
+}
+export type RunCodexVersion = (args: readonly string[], options: BoundedVersionRunOptions) => Promise<{
+    readonly code: number;
+    readonly stdout: string;
+    readonly stderr: string;
+}>;
+export type DetectCodexProvenance = () => CodexInstallProvenance | Promise<CodexInstallProvenance>;
+export type FetchNpmLatest = (packageName: string, options: BoundedLatestFetchOptions) => Promise<string>;
+export interface CodexLatestServiceOptions {
+    readonly runVersion: RunCodexVersion;
+    readonly detectProvenance: DetectCodexProvenance;
+    readonly fetchNpmLatest: FetchNpmLatest;
+    readonly now?: () => number;
+    readonly cacheTtlMs?: number;
+}
+export interface CodexVersionInfo {
+    readonly installed: string;
+    readonly provenance: CodexInstallProvenance;
+    readonly latest?: string;
+    readonly updateAvailable?: boolean;
+    readonly updateHint?: string;
+}
+export declare class CodexVersionUnavailableError extends Error {
+    readonly code: "CODEX_VERSION_UNAVAILABLE";
+    constructor();
+}
+export declare function parseCodexVersion(stdout: string): string;
+export declare class CodexLatestService {
+    private readonly options;
+    private readonly now;
+    private readonly cacheTtlMs;
+    private cache?;
+    private inFlight?;
+    constructor(options: CodexLatestServiceOptions);
+    getVersion(force?: boolean): Promise<CodexVersionInfo>;
+    private loadVersion;
+}