@rynx-ai/runtime 0.1.0

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

@@ -0,0 +1,341 @@
+import { randomUUID } from "node:crypto";
+import { CodexAppServerTransport, } from "./transport.js";
+const DEFAULT_CLIENT_INFO = {
+    name: "lark-agent-bridge",
+    title: "lark-agent-bridge",
+    version: "0.1.0",
+};
+/** Falls back to the auto policy this long after an interactive approval is
+ *  surfaced with no user answer (5 min). */
+const APPROVAL_TIMEOUT_MS = 300_000;
+export class CodexAppServerClient {
+    transport;
+    logger;
+    clientInfo;
+    approvalDecisionPolicy;
+    interactiveApprovals;
+    channel;
+    notificationSubscribers = new Set();
+    approvalListener = null;
+    pendingApprovals = new Map();
+    initializeResponse = null;
+    constructor({ spawner, channel, logger = defaultLogger, clientInfo = DEFAULT_CLIENT_INFO, approvalDecisionPolicy = "auto-approve-session", interactiveApprovals = false, }) {
+        this.logger = logger;
+        this.clientInfo = clientInfo;
+        this.approvalDecisionPolicy = approvalDecisionPolicy;
+        this.interactiveApprovals = interactiveApprovals;
+        this.channel = channel ?? null;
+        this.transport = new CodexAppServerTransport({
+            ...(channel ? { channel } : { spawner }),
+            logger,
+            onNotification: (method, params) => this.dispatchNotification(method, params),
+            onServerRequest: (method, params) => this.handleServerRequest(method, params),
+        });
+        this.transport.on("exit", () => {
+            this.initializeResponse = null;
+        });
+    }
+    /**
+     * The multi-client endpoint a `codex --remote` TUI can attach to, when this
+     * client runs over a {@link WsRpcChannel}. `undefined` for the default stdio
+     * transport (single client — not co-drivable). Available after the transport
+     * has started (post `ensureInitialized`).
+     */
+    terminalRemoteUrl() {
+        const url = this.channel?.url;
+        return url ? url : undefined;
+    }
+    async ensureInitialized() {
+        if (this.initializeResponse) {
+            return this.initializeResponse;
+        }
+        await this.transport.ensureStarted();
+        const response = await this.transport.sendRequest("initialize", {
+            clientInfo: this.clientInfo,
+            capabilities: { experimentalApi: true },
+        });
+        this.initializeResponse = response;
+        return response;
+    }
+    async getAuthStatus(params = {}) {
+        await this.ensureInitialized();
+        return this.transport.sendRequest("getAuthStatus", params);
+    }
+    async threadStart(params) {
+        await this.ensureInitialized();
+        const response = await this.transport.sendRequest("thread/start", params);
+        return { threadId: response.thread.id };
+    }
+    async threadResume(params) {
+        await this.ensureInitialized();
+        const response = await this.transport.sendRequest("thread/resume", params);
+        // Expose the whole `thread` (not just its id): its `turns[].items[]` are the
+        // backfill the forwarder replays for a fresh thread's first turn.
+        return { threadId: response.thread.id, thread: response.thread };
+    }
+    async turnStart(params) {
+        await this.ensureInitialized();
+        const response = await this.transport.sendRequest("turn/start", params);
+        return { turnId: response.turn.id };
+    }
+    async turnInterrupt(params) {
+        await this.ensureInitialized();
+        await this.transport.sendRequest("turn/interrupt", params);
+    }
+    /**
+     * Inject additional user input into the currently running turn. Returns the
+     * active turn id (may differ from `expectedTurnId`). Fails if no matching
+     * active turn exists, so callers should treat errors as best-effort.
+     */
+    async turnSteer(params) {
+        await this.ensureInitialized();
+        const response = await this.transport.sendRequest("turn/steer", params);
+        return { turnId: response.turnId };
+    }
+    // ---- extended capability methods (driven from Lark slash-commands) ----
+    /** List local conversation/thread history (newest first by default). */
+    async threadList(params = {}) {
+        await this.ensureInitialized();
+        return this.transport.sendRequest("thread/list", params);
+    }
+    /** Fork an existing thread into a new one, optionally overriding settings. */
+    async threadFork(params) {
+        await this.ensureInitialized();
+        return this.transport.sendRequest("thread/fork", params);
+    }
+    /** Update per-thread settings (model / mode / personality / sandbox …). */
+    async threadSettingsUpdate(params) {
+        await this.ensureInitialized();
+        return this.transport.sendRequest("thread/settings/update", params);
+    }
+    /** List the models the local Codex install exposes. */
+    async modelList(params = {}) {
+        await this.ensureInitialized();
+        return this.transport.sendRequest("model/list", params);
+    }
+    /** List the available collaboration-mode presets (experimental). */
+    async collaborationModeList() {
+        await this.ensureInitialized();
+        return this.transport.sendRequest("collaborationMode/list", {});
+    }
+    /** Set (or update) the thread's tracked goal. */
+    async threadGoalSet(params) {
+        await this.ensureInitialized();
+        return this.transport.sendRequest("thread/goal/set", params);
+    }
+    /** Read the thread's current goal. */
+    async threadGoalGet(params) {
+        await this.ensureInitialized();
+        return this.transport.sendRequest("thread/goal/get", params);
+    }
+    /** Clear the thread's tracked goal. */
+    async threadGoalClear(params) {
+        await this.ensureInitialized();
+        return this.transport.sendRequest("thread/goal/clear", params);
+    }
+    /** Start a non-interactive code review on the thread. */
+    async reviewStart(params) {
+        await this.ensureInitialized();
+        return this.transport.sendRequest("review/start", params);
+    }
+    onNotification(listener) {
+        this.notificationSubscribers.add(listener);
+        return () => {
+            this.notificationSubscribers.delete(listener);
+        };
+    }
+    async stop() {
+        await this.transport.stop();
+    }
+    dispatchNotification(method, params) {
+        for (const listener of this.notificationSubscribers) {
+            try {
+                listener(method, params);
+            }
+            catch (error) {
+                this.logger.log({
+                    event: "client.notification_listener_failed",
+                    method,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+    }
+    async handleServerRequest(method, params) {
+        switch (method) {
+            case "item/commandExecution/requestApproval":
+            case "execCommandApproval":
+                return this.handleApproval("exec", params);
+            case "item/fileChange/requestApproval":
+            case "applyPatchApproval":
+                return this.handleApproval("patch", params);
+            case "item/tool/requestUserInput":
+            case "mcpServer/elicitation/request":
+                return this.respondNotSupported(method);
+            case "item/permissions/requestApproval":
+                return { decision: this.declineDecisionForApprovals() };
+            case "account/chatgptAuthTokens/refresh":
+                // Codex asks the host to refresh tokens; without an attached UI the
+                // best we can do is decline, surfacing the auth error to the caller
+                // via the next turn.
+                return null;
+            default:
+                this.logger.log({
+                    event: "client.unhandled_server_request",
+                    method,
+                });
+                return null;
+        }
+    }
+    /**
+     * Register the listener that surfaces interactive approval requests. Set by
+     * the executor for the duration of a run so requests reach its event stream
+     * (and thus the web / Lark approval card).
+     */
+    setApprovalRequestListener(listener) {
+        this.approvalListener = listener;
+    }
+    /**
+     * Deliver a user's decision for a pending interactive approval. Returns false
+     * if the approval id is unknown (already resolved, timed out, or auto-decided).
+     */
+    resolveApproval(approvalId, decision) {
+        const pending = this.pendingApprovals.get(approvalId);
+        if (!pending) {
+            return false;
+        }
+        clearTimeout(pending.timer);
+        this.pendingApprovals.delete(approvalId);
+        pending.resolve(decision);
+        return true;
+    }
+    /**
+     * Interactive approval path: surface the request and block the codex
+     * server-request until the user decides (or the timeout falls back to the
+     * auto policy). When interactive approvals are off, decide immediately.
+     */
+    async handleApproval(kind, params) {
+        const listener = this.approvalListener;
+        if (!this.interactiveApprovals || !listener) {
+            return kind === "exec"
+                ? this.respondCommandApproval(params)
+                : this.respondFileChangeApproval(params);
+        }
+        const approvalId = randomUUID();
+        const request = { approvalId, kind };
+        const p = params;
+        if (typeof p.command === "string")
+            request.command = p.command;
+        if (typeof p.cwd === "string")
+            request.cwd = p.cwd;
+        if (typeof p.diff === "string")
+            request.diff = p.diff;
+        try {
+            listener(request);
+        }
+        catch (error) {
+            this.logger.log({
+                event: "client.approval_listener_failed",
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+        const decision = await new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                this.pendingApprovals.delete(approvalId);
+                resolve(this.autoApprovalDecision());
+            }, APPROVAL_TIMEOUT_MS);
+            timer.unref?.();
+            this.pendingApprovals.set(approvalId, { resolve, timer });
+        });
+        return { decision };
+    }
+    autoApprovalDecision() {
+        switch (this.approvalDecisionPolicy) {
+            case "auto-approve-session":
+                return "acceptForSession";
+            case "auto-decline":
+                return "decline";
+            case "auto-cancel":
+            default:
+                return "cancel";
+        }
+    }
+    respondCommandApproval(_params) {
+        switch (this.approvalDecisionPolicy) {
+            case "auto-approve-session":
+                return { decision: "acceptForSession" };
+            case "auto-decline":
+                return { decision: "decline" };
+            case "auto-cancel":
+            default:
+                return { decision: "cancel" };
+        }
+    }
+    respondFileChangeApproval(_params) {
+        switch (this.approvalDecisionPolicy) {
+            case "auto-approve-session":
+                return { decision: "acceptForSession" };
+            case "auto-decline":
+                return { decision: "decline" };
+            case "auto-cancel":
+            default:
+                return { decision: "cancel" };
+        }
+    }
+    declineDecisionForApprovals() {
+        switch (this.approvalDecisionPolicy) {
+            case "auto-approve-session":
+                return "accept";
+            case "auto-decline":
+                return "decline";
+            case "auto-cancel":
+            default:
+                return "cancel";
+        }
+    }
+    respondNotSupported(method) {
+        this.logger.log({
+            event: "client.server_request_unsupported",
+            method,
+        });
+        return null;
+    }
+}
+/**
+ * Construct a SandboxPolicy compatible with the App Server turn/start params
+ * from the env-configured mode and the allowlist of writable roots. The
+ * shape mirrors `SandboxPolicy` in `codex-app-server` generated types.
+ */
+export function buildSandboxPolicy(options) {
+    switch (options.mode) {
+        case "danger-full-access":
+            return { type: "dangerFullAccess" };
+        case "read-only":
+            return { type: "readOnly", networkAccess: false };
+        case "workspace-write":
+        default: {
+            const writableRoots = options.allowedRoots.length
+                ? options.allowedRoots
+                : [options.cwd];
+            return {
+                type: "workspaceWrite",
+                writableRoots,
+                networkAccess: true,
+                excludeTmpdirEnvVar: false,
+                excludeSlashTmp: false,
+            };
+        }
+    }
+}
+export function buildTextUserInput(message) {
+    return [{ type: "text", text: message, text_elements: [] }];
+}
+const defaultLogger = {
+    log(entry) {
+        console.log(JSON.stringify({
+            level: "info",
+            type: "codex_app_server_client",
+            ...entry,
+        }));
+    },
+};

package/dist/codex-app-server/forwarder.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Persistent codex session forwarder — the heart of omnigent's codex-native
+ * model, ported to rynx. It subscribes to a session's app-server for the whole
+ * session lifetime (not just one turn) and maps every thread notification to a
+ * typed {@link AgentEvent}, so turns started by ANY client — the web composer OR
+ * a co-driving `codex --remote` TUI — are mirrored into the canonical log/bus.
+ * That is what makes terminal↔chat one integrated view instead of two.
+ *
+ * It groups events into turns: `turn/started` opens a response, `turn/completed`
+ * (or a fatal error) closes it. The turn's codex `turnId` is surfaced on
+ * {@link CodexForwarderSink.onTurnStart} so the normalizer's `responseId` is
+ * DETERMINISTIC (`resp_codex_<turnId>`) — the same turn always maps to the same
+ * response id across snapshot/live, so items converge (omnigent's `codex_{turnId}`).
+ *
+ * omnigent's subscribe-then-mirror model (verified against real codex 0.142.5):
+ * the app-server delivers a thread's item/turn notifications to a connection that
+ * has `thread/resume`d it. A fresh TUI-created thread has no rollout until its
+ * first turn, so resume is parked until {@link CodexForwarderSink.onThreadActive}
+ * fires (the live stream shows the thread active), then retried — and the retry
+ * response carries the first turn's items as backfill, replayed via
+ * {@link CodexSessionForwarder.replayBackfill}. Backfill and the live stream are
+ * de-duplicated by codex item id.
+ */
+import type { AgentEvent } from "@rynx-ai/core";
+import type { CodexAppServerClient } from "./client.js";
+import type { ResumedTurn } from "./protocol.js";
+export interface CodexForwarderSink {
+    /** A turn began. `turnId` is codex's turn id, used to derive a stable
+     *  `responseId`. Start a fresh normalizer/response. */
+    onTurnStart(turnId?: string): void;
+    /** One mapped event within the current turn. */
+    onEvent(event: AgentEvent): void;
+    /** The current turn finished; `usage` is the runtime's raw snapshot if any. */
+    onTurnEnd(usage?: Record<string, unknown>): void;
+    /** A turn failed on the runtime. */
+    onTurnError(error: Error): void;
+    /** The user's turn text (sourced from codex's `userMessage` item), so a
+     *  co-driving TUI's prompt is recorded even though this process never injected it. */
+    onUserMessage?(text: string): void;
+    /** A thread was announced on the app-server (a `--remote` TUI creating a thread,
+     *  or a resume). The host persists the id + starts the subscribe loop. */
+    onThreadStarted?(threadId: string): void;
+    /** The thread showed activity (a turn/item began, so its rollout now exists).
+     *  Fired once; lets a parked `thread/resume` retry (omnigent's ready signal). */
+    onThreadActive?(): void;
+}
+export declare class CodexSessionForwarder {
+    private readonly client;
+    private readonly sink;
+    private unsubscribe;
+    private turnOpen;
+    private currentTurnIdValue;
+    private currentThreadIdValue;
+    private activeSignaled;
+    /** Completed-item dedup keys already mirrored (live vs resume backfill). Key =
+     *  `threadId:turnId:item.id`; anonymous items use a per-(thread,turn) position
+     *  counter. Mirrors omnigent `_completed_item_key` + `synced_item_keys`. */
+    private readonly seenCompletedItems;
+    /** Per-(thread,turn) position counter for items lacking a stable codex id
+     *  (peek-then-advance; advanced only on a successful claim). omnigent anon path. */
+    private readonly anonCounters;
+    constructor(client: CodexAppServerClient, sink: CodexForwarderSink);
+    /** Begin mirroring. Idempotent. */
+    start(): void;
+    stop(): void;
+    /** True while a turn is open — injection uses `turn/steer` then, else `turn/start`. */
+    isTurnOpen(): boolean;
+    /** The current turn's codex id (only meaningful while {@link isTurnOpen}). */
+    currentTurnId(): string | null;
+    /** The bound codex thread id captured from `thread/started` (null until then). */
+    threadId(): string | null;
+    /**
+     * Replay the backlog turns from a `thread/resume` response as if they were live
+     * `item/completed` notifications — the fresh-thread first-turn backfill. Each
+     * turn opens its own response (`resp_codex_<turnId>`); items are de-duplicated
+     * against the live stream by codex item id, so a turn that also streams live is
+     * not doubled.
+     */
+    replayBackfill(turns: ResumedTurn[]): void;
+    private handle;
+    /** Map + emit one completed codex item, deduped by a TOTAL key and routing the
+     *  user echo to {@link CodexForwarderSink.onUserMessage}. Shared by live + backfill. */
+    private processCompletedItem;
+    /** Build a total dedup key for one completed item. Stable-id items use
+     *  `threadId:turnId:item.id` — identical across replay + live, so the second
+     *  delivery is dropped. Items without a codex id fall back to a per-(thread,turn)
+     *  position counter (peeked here; advanced only on a successful claim, via
+     *  {@link advanceAnonCounter}). Mirrors omnigent `_completed_item_key`. */
+    private completedItemKey;
+    private advanceAnonCounter;
+    private ensureTurn;
+}

package/dist/codex-app-server/forwarder.js

@@ -0,0 +1,188 @@
+import { mapCodexItem, mapCodexNotification } from "./mapping.js";
+function threadIdFrom(params) {
+    const p = params;
+    return p?.threadId ?? p?.thread?.id;
+}
+function turnIdFrom(params) {
+    const p = params;
+    return p?.turnId ?? p?.turn?.id;
+}
+function userMessageText(item) {
+    if (item.type !== "userMessage")
+        return undefined;
+    const content = item.content ?? [];
+    const text = content
+        .filter((c) => c.type === "text" && typeof c.text === "string")
+        .map((c) => c.text)
+        .join("")
+        .trim();
+    return text || undefined;
+}
+/** Whether a notification implies the thread is now active (its first turn has
+ *  begun, so the rollout exists). Mirrors omnigent's `_event_indicates_thread_active`. */
+function indicatesActive(method, params) {
+    if (method.startsWith("turn/") || method.startsWith("item/"))
+        return true;
+    if (method === "thread/status/changed") {
+        const status = params?.status;
+        return status?.type === "active";
+    }
+    return false;
+}
+export class CodexSessionForwarder {
+    client;
+    sink;
+    unsubscribe = null;
+    turnOpen = false;
+    currentTurnIdValue = null;
+    currentThreadIdValue = null;
+    activeSignaled = false;
+    /** Completed-item dedup keys already mirrored (live vs resume backfill). Key =
+     *  `threadId:turnId:item.id`; anonymous items use a per-(thread,turn) position
+     *  counter. Mirrors omnigent `_completed_item_key` + `synced_item_keys`. */
+    seenCompletedItems = new Set();
+    /** Per-(thread,turn) position counter for items lacking a stable codex id
+     *  (peek-then-advance; advanced only on a successful claim). omnigent anon path. */
+    anonCounters = new Map();
+    constructor(client, sink) {
+        this.client = client;
+        this.sink = sink;
+    }
+    /** Begin mirroring. Idempotent. */
+    start() {
+        if (this.unsubscribe)
+            return;
+        this.unsubscribe = this.client.onNotification((method, params) => {
+            this.handle(method, params);
+        });
+    }
+    stop() {
+        this.unsubscribe?.();
+        this.unsubscribe = null;
+        if (this.turnOpen) {
+            this.turnOpen = false;
+            this.sink.onTurnEnd();
+        }
+    }
+    /** True while a turn is open — injection uses `turn/steer` then, else `turn/start`. */
+    isTurnOpen() {
+        return this.turnOpen;
+    }
+    /** The current turn's codex id (only meaningful while {@link isTurnOpen}). */
+    currentTurnId() {
+        return this.currentTurnIdValue;
+    }
+    /** The bound codex thread id captured from `thread/started` (null until then). */
+    threadId() {
+        return this.currentThreadIdValue;
+    }
+    /**
+     * Replay the backlog turns from a `thread/resume` response as if they were live
+     * `item/completed` notifications — the fresh-thread first-turn backfill. Each
+     * turn opens its own response (`resp_codex_<turnId>`); items are de-duplicated
+     * against the live stream by codex item id, so a turn that also streams live is
+     * not doubled.
+     */
+    replayBackfill(turns) {
+        for (const turn of turns) {
+            const turnId = turn.id ?? turn.turnId;
+            if (turnId)
+                this.currentTurnIdValue = turnId;
+            this.ensureTurn();
+            for (const item of turn.items ?? [])
+                this.processCompletedItem(item);
+            this.turnOpen = false;
+            this.sink.onTurnEnd();
+        }
+    }
+    handle(method, params) {
+        if (method === "thread/started" || method === "thread.started") {
+            const tid = threadIdFrom(params);
+            if (tid && tid !== this.currentThreadIdValue) {
+                this.currentThreadIdValue = tid;
+                this.sink.onThreadStarted?.(tid);
+            }
+            return;
+        }
+        // Release a parked resume as soon as the thread shows activity (rollout now
+        // exists). Fire once.
+        if (!this.activeSignaled && indicatesActive(method, params)) {
+            this.activeSignaled = true;
+            this.sink.onThreadActive?.();
+        }
+        const carriedTurnId = turnIdFrom(params);
+        if (carriedTurnId)
+            this.currentTurnIdValue = carriedTurnId;
+        if (method === "turn/started") {
+            this.ensureTurn();
+            return;
+        }
+        // Completed items (user echo, assistant, tool, reasoning) go through the
+        // deduped path so a resume backfill and the live stream never double them.
+        if (method === "item/completed") {
+            const item = params?.item;
+            if (item) {
+                this.processCompletedItem(item);
+                return;
+            }
+        }
+        const mapped = mapCodexNotification(method, params);
+        if (mapped.events.length || mapped.turnCompleted || mapped.fatalError) {
+            this.ensureTurn();
+        }
+        for (const event of mapped.events) {
+            this.sink.onEvent(event);
+        }
+        if (mapped.fatalError) {
+            this.turnOpen = false;
+            this.sink.onTurnError(mapped.fatalError);
+            return;
+        }
+        if (mapped.turnCompleted) {
+            this.turnOpen = false;
+            this.sink.onTurnEnd(mapped.usage);
+        }
+    }
+    /** Map + emit one completed codex item, deduped by a TOTAL key and routing the
+     *  user echo to {@link CodexForwarderSink.onUserMessage}. Shared by live + backfill. */
+    processCompletedItem(item) {
+        const { key, isAnon } = this.completedItemKey(item);
+        if (this.seenCompletedItems.has(key))
+            return;
+        this.seenCompletedItems.add(key);
+        if (isAnon)
+            this.advanceAnonCounter();
+        this.ensureTurn();
+        const userText = userMessageText(item);
+        if (userText !== undefined) {
+            this.sink.onUserMessage?.(userText);
+            return;
+        }
+        const mapped = mapCodexItem("item/completed", item);
+        for (const event of mapped.events)
+            this.sink.onEvent(event);
+    }
+    /** Build a total dedup key for one completed item. Stable-id items use
+     *  `threadId:turnId:item.id` — identical across replay + live, so the second
+     *  delivery is dropped. Items without a codex id fall back to a per-(thread,turn)
+     *  position counter (peeked here; advanced only on a successful claim, via
+     *  {@link advanceAnonCounter}). Mirrors omnigent `_completed_item_key`. */
+    completedItemKey(item) {
+        const threadId = this.currentThreadIdValue ?? "thread";
+        const turnId = this.currentTurnIdValue ?? "turn";
+        if (item.id)
+            return { key: `${threadId}:${turnId}:${item.id}`, isAnon: false };
+        const n = this.anonCounters.get(`${threadId}:${turnId}`) ?? 0;
+        return { key: `${threadId}:${turnId}:anon:${n}`, isAnon: true };
+    }
+    advanceAnonCounter() {
+        const k = `${this.currentThreadIdValue ?? "thread"}:${this.currentTurnIdValue ?? "turn"}`;
+        this.anonCounters.set(k, (this.anonCounters.get(k) ?? 0) + 1);
+    }
+    ensureTurn() {
+        if (!this.turnOpen) {
+            this.turnOpen = true;
+            this.sink.onTurnStart(this.currentTurnIdValue ?? undefined);
+        }
+    }
+}

package/dist/codex-app-server/mapping.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Pure codex app-server notification → {@link AgentEvent} mapping. Extracted from
+ * the executor so BOTH the per-turn executor and the persistent session
+ * forwarder (which mirrors every thread turn — web- AND TUI-initiated — into the
+ * canonical log, omnigent's codex-native model) share one mapping.
+ */
+import type { AgentEvent } from "@rynx-ai/core";
+import type { ThreadItem } from "./protocol.js";
+export interface CodexMapResult {
+    events: AgentEvent[];
+    finalText?: string;
+    usage?: Record<string, unknown>;
+    turnCompleted?: boolean;
+    fatalError?: Error;
+}
+/** Map one thread item (`item/started` | `item/completed`) to events. */
+export declare function mapCodexItem(method: string, item: ThreadItem): CodexMapResult;
+/** Map one codex app-server notification to events (+ turn/usage/error signals). */
+export declare function mapCodexNotification(method: string, params: unknown): CodexMapResult;