clinkx 0.3.0 → 1.0.0

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

@@ -0,0 +1,389 @@
+import type { ActivityObservation } from "../activity-journal.js";
+import { type ApprovalPolicy, type JsonValue, type ModelListParams, type ModelListResult, type RequestId, type SandboxMode, type SandboxPolicy, type SupportedCommandExecutionApprovalDecision } from "./protocol.js";
+import type { CodexAppServerClient } from "./client-types.js";
+import { type ApprovalType, type EventLogPage, type SessionSnapshot, type SessionStatus } from "./session.js";
+export interface Clock {
+    now(): number;
+}
+export type TimerHandle = unknown;
+export interface RegistryConfig {
+    maxActiveTurns: number;
+    maxRetainedSessions: number;
+    sessionTtlMs: number;
+    eventBuffer: number;
+    turnTimeoutMs: number;
+    approvalTimeoutMs: number;
+    maxAgentDepth: number;
+    /** Depth this ClinkX process is itself running at (from CLINKX_AGENT_DEPTH). */
+    currentDepth: number;
+    maxResponseChars: number;
+    maxEventTextChars: number;
+    /** Bounded budget for the interrupt/decline RPC round-trip before escalation. */
+    interruptBudgetMs: number;
+    /** Bounded budget to await a terminal turn/completed before escalation. */
+    terminalWaitBudgetMs: number;
+    /** Bounded budget for the pre-turn startup RPC sequence in startSession. */
+    startBudgetMs: number;
+}
+type SessionObservationSemantic = {
+    readonly kind: "user";
+    readonly content: string;
+} | {
+    readonly kind: "assistant";
+    readonly itemId: string;
+    readonly content: string;
+    readonly phase: string | null;
+} | {
+    readonly kind: "tool_call";
+    readonly toolName: string;
+    readonly callId: string;
+    readonly summary: string;
+} | {
+    readonly kind: "tool_result";
+    readonly toolName: string;
+    readonly callId: string;
+    readonly outcome: "succeeded" | "failed" | "cancelled";
+    readonly summary: string;
+} | {
+    readonly kind: "approval_request";
+    readonly approvalId: RequestId;
+    readonly approvalType: ApprovalType;
+    readonly action: string;
+} | {
+    readonly kind: "approval_resolution";
+    readonly approvalId: RequestId;
+    readonly decision: SupportedCommandExecutionApprovalDecision;
+} | {
+    readonly kind: "error";
+    readonly code: "app_server_session_failed";
+    readonly message: string;
+    readonly retryable: false;
+} | {
+    readonly kind: "lifecycle";
+    readonly status: SessionStatus;
+    readonly failureReason: string | null;
+} | {
+    readonly kind: "usage";
+    readonly inputTokens: number | null;
+    readonly cachedInputTokens: number | null;
+    readonly outputTokens: number | null;
+    readonly reasoningTokens: number | null;
+    readonly incomplete: boolean;
+} | {
+    readonly kind: "reasoning";
+    readonly itemId: string;
+    readonly summary: string;
+    readonly content: string | null;
+};
+export type SessionObservation = SessionObservationSemantic & {
+    /** Synchronous per-session ordering authority. */
+    readonly sequence: number;
+    readonly sessionId: string;
+    readonly threadId: string;
+    readonly turnId: string | null;
+    /** Informational only; never use as the ordering authority. */
+    readonly atMs: number;
+};
+export interface SessionTurnBinding {
+    readonly sessionId: string;
+    readonly threadId: string;
+    readonly turnId: string;
+}
+/** Optional, fail-open observer at the reduced app-server session seam. */
+export type SessionObserver = ((observation: SessionObservation) => void | Promise<void>) & {
+    /** Optional ordered binding for observations provisionally emitted by turn/start. */
+    bindTurn?: (binding: SessionTurnBinding) => void | Promise<void>;
+};
+export interface RegistryDeps {
+    client: CodexAppServerClient;
+    observer?: SessionObserver | undefined;
+    clock?: Clock;
+    setTimer?: (cb: () => void, ms: number) => TimerHandle;
+    clearTimer?: (handle: TimerHandle) => void;
+    config?: Partial<RegistryConfig>;
+}
+export interface StartSessionOptions {
+    /** Caller-supplied id (Phase 4 generates these; injected here for determinism). */
+    sessionId: string;
+    /** turn/start input array (already assembled by the caller). */
+    input: unknown[];
+    sandbox: SandboxMode;
+    /** Human-facing approval label stored on the record. */
+    approval: string;
+    cwd?: string | undefined;
+    model?: string | undefined;
+    /** Mapped approval policy sent to thread/start + turn/start (1-4 owns mapping). */
+    approvalPolicy?: ApprovalPolicy | undefined;
+    /** Tagged-object sandbox policy for turn/start (1-4 owns mapping). */
+    sandboxPolicy?: SandboxPolicy | undefined;
+    outputSchema?: JsonValue | undefined;
+    /** When set, thread/resume {threadId} instead of thread/start (async reuse). */
+    resumeThreadId?: string | undefined;
+    /**
+     * Explicit per-call wall-clock turn timeout (ms). Overrides the global
+     * `CLINKX_TURN_TIMEOUT_SECONDS` default for THIS session so an adapter's
+     * `timeout_seconds` reaches the per-session turn timer (review fix B). A
+     * value of 0 disables the turn timeout for this session (same semantics as
+     * the global). Omit to inherit the global default/backstop.
+     */
+    turnTimeoutMs?: number | undefined;
+    /**
+     * Optional fail-open dashboard observation. The registry owns it once
+     * supplied so detached turns still reach a truthful terminal state.
+     */
+    activityObservation?: ActivityObservation | undefined;
+    /**
+     * Optional observer owned by this session. When present it takes precedence
+     * over the registry-wide compatibility seam.
+     */
+    sessionObserver?: SessionObserver | undefined;
+}
+export interface WaitOptions {
+    /** Wall-clock cap for the WAIT itself; the turn keeps running on timeout. */
+    timeoutMs?: number | undefined;
+    /**
+     * Abort the WAIT (not the turn): on abort, {@link AppServerRegistry.waitForTurn}
+     * resolves promptly with the current snapshot and clears its local race timer
+     * and terminal/attention subscriptions. The underlying turn keeps running and
+     * retains its lease — cancelling a wait never interrupts the turn.
+     */
+    signal?: AbortSignal | undefined;
+}
+export interface CleanupOptions {
+    /** Interrupt a running turn before eviction. Default cleanup is non-destructive. */
+    force?: boolean | undefined;
+}
+export interface CleanupResult {
+    sessionId: string;
+    cleanedUp: boolean;
+    skippedActive: boolean;
+}
+export interface AppServerRegistryHealth {
+    readonly activeLeases: number;
+    readonly retainedSessionCount: number;
+    readonly appServerProtocol: {
+        readonly acceptedVersion: string | null;
+        readonly minVersion: string;
+        readonly maxVersion: string;
+        readonly strictVersion: boolean;
+    };
+    readonly childRespawnCount: number;
+    readonly recentFailures: {
+        readonly count: number;
+        readonly samples: readonly string[];
+    };
+}
+export declare function resolveRegistryConfig(override?: Partial<RegistryConfig>): RegistryConfig;
+/**
+ * Registry & lifecycle for long-lived Codex app-server sessions.
+ *
+ * CORE responsibilities (Phase 2): the active-turn lease (the SOLE concurrency
+ * gate — the request {@link Semaphore} is never acquired here), session record
+ * accounting, the bounded event ring, retained-cap + TTL reaping, turn and
+ * pending-approval timeouts with the shared interrupt → terminal-wait →
+ * process-group-kill + respawn escalation path, crash semantics, the recursion
+ * depth guard, and a standalone {@link shutdown}.
+ *
+ * Respawn ownership belongs to the client: the registry only calls
+ * {@link CodexAppServerClient.ensureReady} and the client's guarded
+ * {@link CodexAppServerClient.killProcessGroup}.
+ */
+export declare class AppServerRegistry {
+    private readonly client;
+    private readonly observer;
+    private readonly clock;
+    private readonly setTimer;
+    private readonly clearTimer;
+    readonly config: RegistryConfig;
+    private readonly lease;
+    private readonly sessions;
+    /**
+     * Thread ids with an in-flight resume reservation. Held synchronously across
+     * startSession's awaited RPCs so two concurrent resumes of the same thread
+     * cannot both pass the in-flight check before either becomes visible as a
+     * running session (review fix A — closes the deferred-insertion race).
+     */
+    private readonly reservedResumeThreads;
+    private readonly unsubscribeProcessDied;
+    constructor(deps: RegistryDeps);
+    private now;
+    get activeLeases(): number;
+    get sessionCount(): number;
+    health(): AppServerRegistryHealth;
+    /**
+     * Env marker to ADD to the spawned app-server child so the recursion guard
+     * survives the env sanitizer (2-6). The client owns actual env injection
+     * into the AppServerSpawnConfig; the registry only supplies the marker.
+     */
+    childEnvMarker(): Record<string, string>;
+    private require;
+    /**
+     * Start a new (or resumed) session and its first turn. Returns once the turn
+     * is RUNNING (lease held); the turn proceeds asynchronously and the lease is
+     * released only on provable terminality — held even if the MCP call detaches
+     * (2-3). Use {@link waitForTurn} to await completion without consuming a lease.
+     */
+    startSession(opts: StartSessionOptions): Promise<SessionSnapshot>;
+    private buildThreadStartParams;
+    private buildTurnStartParams;
+    /** Snapshot without consuming an active-turn lease (2-4). */
+    poll(sessionId: string): SessionSnapshot;
+    list(filter?: {
+        status?: SessionStatus;
+    }): SessionSnapshot[];
+    /** Bounded event-log read with a monotonic cursor; never consumes a lease (2-4,2-5). */
+    getLog(sessionId: string, cursor?: number, limit?: number): EventLogPage;
+    /**
+     * Discovery passthrough for `model/list`. Spawns/initializes the app-server
+     * child if needed (via the client) but never starts a session or consumes a
+     * lease. Bounded by the start budget like other pre-turn RPCs.
+     */
+    listModels(params?: ModelListParams): Promise<ModelListResult>;
+    /**
+     * Await the active turn's terminality WITHOUT consuming a lease. An optional
+     * `timeoutMs` bounds the wait only — the underlying turn keeps running and
+     * retains its lease on wait-timeout.
+     */
+    waitForTurn(sessionId: string, opts?: WaitOptions): Promise<SessionSnapshot>;
+    /** Reply to a pending approval. The turn continues; the lease is NOT released. */
+    respondApproval(sessionId: string, approvalId: RequestId, decision: SupportedCommandExecutionApprovalDecision): Promise<SessionSnapshot>;
+    /**
+     * Steer the currently active turn. This never starts a new turn and never
+     * acquires a new lease; it targets the active turn id captured in the record.
+     */
+    steer(sessionId: string, input: unknown[]): Promise<SessionSnapshot>;
+    /** Explicit cancel → interrupted snapshot (decision 4). */
+    interrupt(sessionId: string): Promise<SessionSnapshot>;
+    /** Remove a session. Running sessions are skipped unless force:true is supplied. */
+    cleanup(sessionId: string, opts?: CleanupOptions): Promise<CleanupResult>;
+    /**
+     * Standalone shutdown: interrupt every active turn, then kill the app-server
+     * child by process group via the client's guarded kill.
+     */
+    shutdown(reason?: string): Promise<void>;
+    /** TTL + retained-cap reaping of idle sessions (2-4). Running sessions are never reaped. */
+    reapIdle(): void;
+    private handleEvent;
+    /**
+     * Finalize a turn on PROVABLE terminality. Idempotent. Clears timers,
+     * unsubscribes, releases the lease, and resolves the terminal deferred.
+     */
+    private finalizeTurn;
+    private runSessionObservation;
+    private bindSessionObserverTurn;
+    private observeUserInput;
+    private observeApprovalRequest;
+    private observeApprovalResolution;
+    private observeError;
+    private observeLifecycle;
+    private observeRunning;
+    private observeTerminal;
+    private runActivityObservation;
+    /**
+     * Shared terminality/escalation path (2-8 / 2-9):
+     *   1. bounded interrupt RPC
+     *   2. bounded wait for terminal turn/completed
+     *   3. on hang/no-terminal → process-group kill + respawn + mark terminal
+     *
+     * The lease is released only via {@link finalizeTurn}, i.e. only once the
+     * turn is provably terminal.
+     */
+    private terminateTurn;
+    private forceKill;
+    /**
+     * Finalize every co-active running session after the SHARED child was killed.
+     * The client suppresses onProcessDied for intentional kills, so without this
+     * their leases leak (review fix). finalizeTurn is idempotent; `except` is the
+     * triggering runtime, handled by the caller.
+     */
+    private finalizeCoActiveAfterSharedKill;
+    private onTurnTimeout;
+    private onApprovalTimeout;
+    /**
+     * Auto-decline a permissions (sandbox-escalation) approval the moment it
+     * arrives, with a protocol-valid empty grant. Never surfaced to the user
+     * (read-only / approval:never posture). Bounded: the decline RPC is capped by
+     * `interruptBudgetMs`.
+     *
+     * On decline failure/timeout we do NOT merely log: Codex's child is blocked on
+     * a response that never lands, and if the operator disabled the wall-clock
+     * turn timeout (`CLINKX_TURN_TIMEOUT_SECONDS=0`) there is no backstop until
+     * idle reap. So we escalate the turn directly under a bounded budget,
+     * independent of the global turn timeout, mirroring the command/file
+     * decline-failure recovery in {@link onApprovalTimeout}. terminateTurn is
+     * idempotent and no-ops if the turn already finalized, so this never
+     * double-finalizes.
+     */
+    private autoDeclinePermissionsApproval;
+    private handleProcessDied;
+    private scheduleTurnTimeout;
+    private scheduleApprovalTimeout;
+    private clearApprovalTimer;
+    private clearTimers;
+    private evict;
+    /** Reject if `promise` does not settle within `ms`. */
+    private withBudget;
+    /** Resolve `true` if the terminal deferred settles within `ms`, else `false`. */
+    private waitTerminalWithin;
+    private notifyAttention;
+    /**
+     * Await terminality, a wait-local timeout, or newly requested human attention.
+     * All outcomes are lease-free: a pending approval returns a running snapshot.
+     */
+    private raceTurnWait;
+}
+export type AppServerRegistryFactory = (deps: RegistryDeps) => AppServerRegistry;
+export interface AppServerRegistryTestOverrides {
+    client?: CodexAppServerClient;
+    registryFactory?: AppServerRegistryFactory;
+}
+/**
+ * The spawn command/args an app-server adapter wants for the process-wide
+ * registry. `command` falls back to the default `codex` binary; `args` defaults
+ * to `["app-server"]` (the schema default). The registry is a process-wide
+ * singleton multiplexing all sessions, so the first creator's spawn config wins
+ * and any later conflicting request is rejected (see {@link getAppServerRegistry}).
+ */
+export interface AppServerRegistrySpawnRequest {
+    command?: string | undefined;
+    args?: string[] | undefined;
+}
+/**
+ * Derive the registry spawn request from a resolved app_server adapter:
+ * `app_server.command` (falling back to the adapter's top-level `command`) and
+ * `app_server.args`.
+ */
+export declare function spawnRequestFor(adapter: {
+    command: string;
+    app_server?: {
+        command?: string | undefined;
+        args?: string[] | undefined;
+    } | undefined;
+}): AppServerRegistrySpawnRequest;
+/**
+ * Get the process-wide app-server registry, creating it on first call.
+ *
+ * The registry is a singleton: one long-lived `codex app-server` process
+ * multiplexes every session. The adapter's `app_server.command/args` therefore
+ * take effect only at FIRST creation. A later adapter requesting a spawn config
+ * that conflicts with the live one is rejected with {@link InvalidParamsError}
+ * (-32602) rather than silently ignored — building a registry-per-config map
+ * would be over-engineering for a singleton-by-design subsystem.
+ */
+export declare function getAppServerRegistry(spawn?: AppServerRegistrySpawnRequest): AppServerRegistry;
+/**
+ * Return the live process-wide registry WITHOUT creating it. Read-only manage
+ * ops (clink_agent_manage) must not lock in a default spawn config before a run
+ * has chosen one — otherwise a later run with a custom app_server.command would
+ * spuriously hit the spawn-config conflict (-32602). See {@link getAppServerRegistry}.
+ */
+export declare function peekAppServerRegistry(): AppServerRegistry | undefined;
+export declare function shutdownAppServerRegistry(reason: string): Promise<void>;
+/** The spawn command/args the live singleton was created with (test inspection). */
+export declare function appServerRegistrySpawnForTest(): {
+    command: string;
+    args: string[];
+} | undefined;
+export declare function configureAppServerRegistryForTest(overrides: AppServerRegistryTestOverrides): void;
+export declare function resetAppServerRegistryForTest(reason?: string): Promise<void>;
+export {};