@rynx-ai/runtime 0.1.0

package/dist/host.d.ts

@@ -0,0 +1,324 @@
+import { type AgentSpec, type ResolvedExecutionBudget, type SessionEvent } from "@rynx-ai/core";
+import { type AgentRuntimeId } from "@rynx-ai/core";
+import { type AppConfig } from "@rynx-ai/core";
+import { createCodexChildEnv } from "./codex-child-env.js";
+import type { InjectOutcome } from "./runner/protocol.js";
+import { CodexAppServerClient } from "./codex-app-server/client.js";
+import type { ModelListResponse, ThreadGoal } from "./codex-app-server/protocol.js";
+import { type TerminalInjector } from "./claude/native-integration.js";
+import { FileCodexSessionStore, resolveCodexSessionStorePath, type CodexSessionRecord, type CodexSessionStore } from "./codex-session-store.js";
+import { AgentRuntimeError as CodexRuntimeError } from "@rynx-ai/core";
+export { FileCodexSessionStore, resolveCodexSessionStorePath, type CodexSessionRecord, type CodexSessionStore, };
+export interface CodexRuntimeStatus {
+    codex_available: boolean;
+    logged_in: boolean;
+    auth_mode: string | null;
+    session_store_writable: boolean;
+    codex_sessions_accessible: boolean;
+    issues: string[];
+}
+export interface CommandChunk {
+    stream: "stdout" | "stderr";
+    line: string;
+}
+export interface CommandCompletion {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
+export interface RunningCommand {
+    stream: AsyncGenerator<CommandChunk>;
+    completion: Promise<CommandCompletion>;
+}
+export interface CodexCommandRunner {
+    start(options: {
+        args: string[];
+        cwd: string;
+        signal?: AbortSignal;
+    }): RunningCommand;
+    capture(options: {
+        args: string[];
+        cwd?: string;
+    }): Promise<CommandCompletion>;
+}
+export { CodexRuntimeError };
+export declare class SpawnCodexCommandRunner implements CodexCommandRunner {
+    private readonly cliPath;
+    private readonly killGraceMs;
+    constructor(cliPath: string, { killGraceMs }?: {
+        killGraceMs?: number;
+    });
+    start({ args, cwd, signal, }: {
+        args: string[];
+        cwd: string;
+        signal?: AbortSignal;
+    }): RunningCommand;
+    capture({ args, cwd, }: {
+        args: string[];
+        cwd?: string;
+    }): Promise<CommandCompletion>;
+}
+/**
+ * Result of a capability that operates on a specific Lark session's active
+ * Codex thread. `no_active_thread` means the session hasn't run a turn yet (no
+ * Codex thread bound); `unsupported` means the backend can't answer (e.g. the
+ * legacy `exec` backend).
+ */
+export type CapabilityResult<T = void> = {
+    ok: true;
+    data: T;
+} | {
+    ok: false;
+    reason: "unsupported" | "no_active_thread" | "error";
+    message?: string;
+};
+/**
+ * Read-only / per-thread Codex capabilities surfaced to the Lark bot for
+ * slash-commands. List capabilities resolve to `null` on the legacy `exec`
+ * backend; per-thread capabilities return a `CapabilityResult` so the bot can
+ * tell "no session yet" apart from "unsupported".
+ */
+export interface CodexCapabilities {
+    listModels(runtime?: AgentRuntimeId): Promise<ModelListResponse | null>;
+    getGoal(localThreadId: string): Promise<CapabilityResult<ThreadGoal | null>>;
+    setGoal(localThreadId: string, objective: string): Promise<CapabilityResult>;
+    clearGoal(localThreadId: string): Promise<CapabilityResult>;
+    /**
+     * Fork the Codex thread bound to `currentLocalThreadId` and bind the forked
+     * thread (carrying full context) to `newLocalThreadId`, so a new Lark
+     * conversation resumes from it. Used by `/fork`.
+     */
+    forkSession(currentLocalThreadId: string, newLocalThreadId: string): Promise<CapabilityResult>;
+}
+/**
+ * Per-session claude-native live handle. claude has no app-server, so the
+ * forwarder tails the bridge (`hooks.jsonl`) + the transcript JSONL instead of
+ * subscribing to RPC. Injection is tmux send-keys into the pane, whose injector
+ * the runner-child attaches via {@link LocalAgentHost.attachTerminalInjector}.
+ */
+/** Re-target the runner-child's mirror to a freshly minted rynx session (claude
+ *  `/clear`·`/fork` rotation) and record the terminal transfer with the daemon.
+ *  The runner-child owns the mirror emitter + transport, so it supplies this. */
+export type RetargetMirror = (newSessionId: string, meta: {
+    kind: "clear" | "fork";
+    agent?: string;
+    model?: string;
+    cwd?: string;
+    parentSessionId?: string;
+}) => void;
+export interface LiveSessionOpts {
+    runtime?: AgentRuntimeId;
+    /** Preset agent id (or inline {@link LiveSessionOpts.agentSpec}), so the live
+     *  launch applies the agent's model / skills / instructions — not just the
+     *  runtime. Absent ⇒ falls back to the config defaults (prior behavior). */
+    agentName?: string;
+    agentSpec?: AgentSpec;
+    retargetMirror?: RetargetMirror;
+}
+/**
+ * The `OPENAI_*` retry env for a codex-lineage app-server spawn, or `undefined`
+ * when the budget declares no retry or the runtime is claude. claude applies
+ * its retry budget per-run in `buildOptions` (see the claude executor), so it
+ * never needs a dedicated app-server.
+ */
+export declare function codexRetryEnv(runtime: AgentRuntimeId, budget?: ResolvedExecutionBudget): Record<string, string> | undefined;
+export declare function codexBackendKey(runtime: AgentRuntimeId, budget?: ResolvedExecutionBudget): string;
+export declare class LocalAgentHost implements CodexCapabilities {
+    private readonly config;
+    private readonly sessionStore;
+    private readonly allowedRoots;
+    private readonly defaultRuntime;
+    private readonly injectedCommandRunner?;
+    private readonly injectedAppServerClient?;
+    private readonly clock;
+    private readonly backendIdleTtlMs;
+    private readonly forwarderClientFactory;
+    private readonly backends;
+    private readonly sessionId;
+    private sessionSandbox?;
+    private sessionApprovalPolicy?;
+    private cachedCodexHome?;
+    private readonly liveSessions;
+    private readonly liveClaudeSessions;
+    private readonly liveEnsuring;
+    constructor({ config, commandRunner, sessionStore, allowedRoots, appServerClient, now, backendIdleTtlMs, forwarderClientFactory, sessionId, }: {
+        config: AppConfig;
+        commandRunner?: CodexCommandRunner;
+        sessionStore?: CodexSessionStore;
+        allowedRoots?: string[];
+        appServerClient?: CodexAppServerClient | null;
+        /** Monotonic-ish clock for idle reaping (tests inject a controllable one). */
+        now?: () => number;
+        /** Idle TTL after which a per-budget composite backend is reaped (ms). */
+        backendIdleTtlMs?: number;
+        /** Override the live-session forwarder connection factory (tests inject a fake). */
+        forwarderClientFactory?: (appServerUrl: string) => CodexAppServerClient;
+        /** The rynx session (localThreadId) this host serves — a per-session runner
+         *  child sets it from `RYNX_RUNNER_SESSION` so the private CODEX_HOME is
+         *  session-scoped. The shared `__cap__` child / tests fall back to a sentinel
+         *  (its home only backs home-agnostic caps like listModels). */
+        sessionId?: string;
+    });
+    private getBackend;
+    /**
+     * Stop + drop per-budget composite backends that have been idle longer than
+     * the TTL and have no in-flight run. Base per-runtime backends (key === the
+     * bare runtime id) are never reaped — they live for the process lifetime, as
+     * before. There are no per-conversation close hooks, so this lazy sweep (run
+     * on every `getBackend`) is how dedicated app-servers get reclaimed.
+     */
+    private reapIdleBackends;
+    private createBackend;
+    /** This session's private CODEX_HOME (prepared once), shared by its app-server + TUI. */
+    private codexHome;
+    private createAppServerClient;
+    /**
+     * Deliver a user's decision for a pending interactive approval (Phase D).
+     * Routes to the codex app-server client for the thread's runtime. Returns
+     * false when no matching pending approval exists (unknown id / already
+     * resolved / claude runtime).
+     */
+    resolveApproval(localThreadId: string, approvalId: string, decision: "acceptForSession" | "accept" | "decline" | "cancel"): Promise<boolean>;
+    /**
+     * The command to run in a session's live terminal so it co-drives the codex
+     * app-server thread (Phase D). Returns `null` when live-terminal is off, the
+     * runtime is claude (not codex-lineage), or the app-server has no ws endpoint —
+     * the caller then falls back to a plain shell. Ensures the app-server is up so
+     * its ws url is available; `codex --remote resume <threadId>` attaches to the
+     * SAME thread the structured data channel drives.
+     */
+    codexTerminalSpec(localThreadId: string): Promise<{
+        command: string;
+        args: string[];
+        cwd: string;
+        env?: Record<string, string>;
+    } | null>;
+    /**
+     * Bring up (idempotently) a session's persistent codex forwarder and emit its
+     * mirrored {@link SessionEvent}s. omnigent's codex-native single-writer model:
+     * this forwarder is the SOLE producer of the session's canonical events — every
+     * turn on the thread, web-composer-injected AND co-driving-`codex --remote`-TUI
+     * initiated. Each turn gets a {@link SessionNormalizer} whose `responseId` is
+     * DETERMINISTIC (`resp_codex_<turnId>`) so items converge across snapshot/live.
+     *
+     * Returns false for claude / no app-server (the caller falls back to the
+     * streaming run path). This client CREATES the codex thread (`threadStart`) so
+     * it owns the thread's item/turn notification stream — the app-server delivers
+     * items to the thread-creating connection, for turns started by ANY client (web
+     * inject AND the co-driving `codex --remote` TUI). The TUI pane (launched by the
+     * runner child, which owns the terminal registry) merely `resume`s this thread
+     * to display it. The thread id is persisted so `codexTerminalSpec` resumes it.
+     */
+    ensureLiveCodexSession(localThreadId: string, emit: (event: SessionEvent) => void, opts?: LiveSessionOpts): Promise<boolean>;
+    private startLiveCodexSession;
+    /** Bind a session's codex thread id once known (TUI broadcast or store): persist
+     *  it, unblock injection, and kick off the resume-subscribe loop (once). */
+    private onLiveThreadStarted;
+    /**
+     * Subscribe the forwarder connection to a thread (omnigent's
+     * `_subscribe_until_ready`). A fresh TUI thread has no rollout until its first
+     * turn, so `thread/resume` is retried: park until the forwarder observes the
+     * thread active, then retry WITHOUT `excludeTurns` so the response backfills the
+     * first turn's items (replayed, deduped against the live stream). Once resume
+     * succeeds, subsequent turns arrive as live notifications on this connection.
+     */
+    private subscribeUntilReady;
+    /** Await a live session's thread binding (bounded). Returns false on timeout /
+     *  no live session. Injection and the runner's `live.ready` gate on this. */
+    waitLiveReady(localThreadId: string, timeoutMs?: number): Promise<boolean>;
+    /**
+     * Inject a user turn into a session's live codex thread — omnigent's
+     * single-writer web send. `turn/steer` when a turn is open (mid-turn
+     * supplement), else `turn/start`. NEVER creates a thread (the TUI owns creation;
+     * this targets the id the forwarder captured). Serialized per session so two
+     * injects can't double-open a turn.
+     *
+     * Returns an {@link InjectOutcome}: `notLive` when this session has no live
+     * forwarder (caller may use the run path); `notReady`/`failed` are hard errors
+     * the caller reports WITHOUT re-running (re-running double-writes alongside the
+     * forwarder). Park-until-ready (~60s), aligning omnigent's executor waiting for
+     * the bridge instead of a short race that falls back to a second output path.
+     */
+    injectMessage(localThreadId: string, text: string): Promise<InjectOutcome>;
+    /**
+     * Interrupt the session's active turn — the web Stop button. codex: the
+     * app-server `turn/interrupt` on the active `{threadId, turnId}` (exactly what
+     * codex's own TUI interrupt key sends — omnigent `_handle_codex_native_interrupt`).
+     * claude: an Escape keystroke into the pane (no app-server — omnigent
+     * `inject_interrupt`). Returns false as a no-op when there is no active turn.
+     */
+    interruptLive(localThreadId: string): Promise<boolean>;
+    /** Stop + drop a session's live forwarder and its dedicated connection (session
+     *  close / runner shutdown). The backend inject client is shared — left running. */
+    stopLiveCodexSession(localThreadId: string): void;
+    /** The interactive `claude` TUI spec for a claude-native live session: the real
+     *  `claude` binary with rynx's hooks (`--settings`), resuming the bound session.
+     *  Trust is pre-seeded so the daemon-spawned TUI never blocks on a first-run
+     *  prompt. (PermissionRequest approvals land in Phase 6; until then the TUI
+     *  surfaces its own permission prompt in the co-driven pane.) */
+    private claudeTerminalSpec;
+    /** Bring up a claude-native live forwarder: prepare the bridge dir (the TUI's
+     *  hooks write into it), then tail bridge + transcript and drive a per-turn
+     *  {@link SessionNormalizer} → `emit` (the SAME sink shape the codex path uses). */
+    /** Resolve an agent spec's launch config — model + the session skill env —
+     *  for a LIVE native session, reusing the same core resolvers the non-live
+     *  run path uses ({@link resolveAgentExecution} for the model,
+     *  {@link resolveAgent} for skills). Instructions are intentionally NOT
+     *  returned: the co-driven TUI runs on vendor defaults (see
+     *  startLiveClaudeSession).
+     *
+     *  Skills are spec-rooted: each declared ref is replayed into a
+     *  SESSION-scoped temp dir (cache-accelerated); the owner's catalog plays no
+     *  role, and no spec / no `skills` means ZERO skills. The env-build report
+     *  (installs, failures, content drift) is logged — a declared skill that
+     *  can't be provisioned is loudly absent, never silent; the session still
+     *  starts. `skillsCleanup` removes the session dir (call on session stop). */
+    private resolveLiveAgentConfig;
+    private startLiveClaudeSession;
+    /** Persist claude's discovered session id (reusing the `codexSessionId` store
+     *  field, as the claude executor already does) and release the readiness gate. */
+    private onClaudeDiscovered;
+    /** Inject a web message into a claude-native pane via tmux (omnigent recipe),
+     *  serialized per session. Parks until the thread is ready AND the tmux injector
+     *  is (re)attached, then pastes; `injectViaTerminal` RAISES if the prompt never
+     *  appears (omnigent RAISE), so a not-ready pane is a hard error — NOT a
+     *  fall-through-to-run signal. Returns {@link InjectOutcome}. */
+    private injectClaude;
+    /** Park until the claude session's tmux injector is (re)attached by the
+     *  runner-child, or the deadline passes. Pane relaunch re-attaches it via
+     *  {@link attachTerminalInjector}; without this a message during that window
+     *  would fail and (pre-omnigent) fall through to a second output path. */
+    private waitInjector;
+    /** Attach a session's tmux pane injector (from the runner-child, which owns the
+     *  terminal registry — the host does not hold tmux). Ignored for codex sessions
+     *  (they inject via the app-server). Idempotent. */
+    attachTerminalInjector(localThreadId: string, injector: TerminalInjector): void;
+    /** The PermissionRequest hook's server target from the runner-child env (the
+     *  daemon control URL + token), or undefined when unset — then no permission
+     *  hook is registered and claude surfaces its own TUI prompt in the pane. */
+    private claudePermissionConfig;
+    /** List the models a runtime exposes (App Server for codex/traex; static for claude). */
+    listModels(runtime?: AgentRuntimeId): Promise<ModelListResponse | null>;
+    /**
+     * Run a per-thread capability against a session's active thread on whichever
+     * runtime it is bound to. Normalises the "no app-server backend" and "session
+     * has no thread yet" cases into a `CapabilityResult`.
+     */
+    private withCodexThread;
+    getGoal(localThreadId: string): Promise<CapabilityResult<ThreadGoal | null>>;
+    setGoal(localThreadId: string, objective: string): Promise<CapabilityResult>;
+    clearGoal(localThreadId: string): Promise<CapabilityResult>;
+    forkSession(currentLocalThreadId: string, newLocalThreadId: string): Promise<CapabilityResult>;
+}
+export declare function parseCodexLoginStatus(exitCode: number, output: string): {
+    loggedIn: boolean;
+    authMode: string | null;
+    issues: string[];
+};
+export declare function getCodexModel(config: AppConfig, override?: string): string;
+export { createCodexChildEnv };
+export declare function isUnsupportedMethodError(error: unknown): boolean;
+/** A `thread/resume` failure meaning the thread has no (or an empty) rollout yet
+ *  — a fresh TUI thread before its first turn. Retryable (park until active).
+ *  Mirrors omnigent's `_is_thread_not_ready_error`. */
+export declare function isThreadNotReadyError(error: unknown): boolean;