clinkx 0.2.3 → 1.0.0

package/dist/codex/session.d.ts

@@ -0,0 +1,263 @@
+import { type RequestId, type SandboxMode, type TokenUsage, type TokenUsageBreakdown } from "./protocol.js";
+import type { CodexAppServerEvent } from "./client-types.js";
+/**
+ * Lifecycle status of a session's most recent turn.
+ *
+ * A session is "idle" (retained / reapable) whenever its status is anything
+ * other than `running`. There is no dedicated `idle` value: idleness is the
+ * absence of an active turn, derived via {@link SessionRecord.isIdle}.
+ */
+export type SessionStatus = "running" | "completed" | "interrupted" | "failed" | "timeout";
+export type SessionOrigin = "root" | "nested";
+export type ApprovalType = "commandExecution" | "fileChange" | "permissions";
+export interface PendingApproval {
+    readonly id: RequestId;
+    readonly type: ApprovalType;
+    readonly requestedAtMs: number;
+    readonly reason: string | null;
+    readonly command?: string | null | undefined;
+    readonly cwd?: string | null | undefined;
+    readonly grantRoot?: string | null | undefined;
+    readonly networkApprovalContext?: unknown;
+}
+/**
+ * Token accounting for a session.
+ *
+ * `thread/tokenUsage/updated` reports `last` (the per-turn slice for the turn
+ * that just ended) and `total` (cumulative across the thread's lifetime). The
+ * per-turn delta is the protocol `last` breakdown taken DIRECTLY — never
+ * `total - baseline`. Subtraction breaks on a resumed thread, where the fresh
+ * SessionRecord starts with `cumulativeTotal == null`, so the first delta would
+ * otherwise equal the entire prior-thread cumulative (massive over-count).
+ * Consuming `last` sidesteps resume entirely while `total` stays authoritative
+ * as the cumulative figure. `baselineTotal` is retained for reporting only (the
+ * cumulative captured at turn start). Interrupted/failed turns set `incomplete`
+ * so a consumer can discard the partial delta rather than fold it into a
+ * resumed turn.
+ */
+export interface SessionTokenUsage {
+    baselineTotal: TokenUsageBreakdown | null;
+    lastUsage: TokenUsageBreakdown | null;
+    deltaUsage: TokenUsageBreakdown | null;
+    cumulativeTotal: TokenUsageBreakdown | null;
+    incomplete: boolean;
+}
+export interface StoredSessionEvent {
+    readonly seq: number;
+    readonly method: string;
+    readonly threadId: string | undefined;
+    readonly turnId: string | undefined;
+    readonly payload: unknown;
+    readonly atMs: number;
+}
+export interface EventLogPage {
+    readonly events: StoredSessionEvent[];
+    readonly nextCursor: number;
+    /** True when the requested cursor pointed behind the ring floor (dropped events). */
+    readonly truncated: boolean;
+    readonly floor: number;
+    /** Fixed ring capacity (events retained before oldest-first eviction). */
+    readonly capacity: number;
+}
+/**
+ * Bounded per-session event ring with a monotonic sequence cursor (2-5).
+ *
+ * - `seq` is monotonic and never reused; the cursor returned by {@link read}
+ *   is a sequence number, not an array index.
+ * - On overflow the oldest entry is dropped and the floor advances.
+ * - A read whose cursor points behind the floor returns `truncated: true`
+ *   (NOT an error) and resumes from the floor.
+ */
+export declare class SessionEventRing {
+    private readonly capacity;
+    private readonly maxTextChars;
+    /**
+     * Fixed-size backing store used as a circular buffer. `head` is the slot of
+     * the oldest retained event; `count` is how many slots are live. Append
+     * writes at the tail and, on overflow, OVERWRITES the head slot then advances
+     * head — amortized O(1), no per-drop `shift()` (F7). Slots are typed nullable
+     * only to satisfy strict indexing; within `[head, head+count)` they are live.
+     */
+    private readonly buffer;
+    private head;
+    private count;
+    private nextSeq;
+    private floorSeq;
+    constructor(capacity: number, maxTextChars: number);
+    append(event: CodexAppServerEvent, atMs: number): StoredSessionEvent;
+    read(cursor?: number, limit?: number): EventLogPage;
+    get size(): number;
+}
+export interface SessionSnapshot {
+    readonly sessionId: string;
+    readonly threadId: string;
+    readonly activeTurnId: string | null;
+    readonly status: SessionStatus;
+    readonly cwd: string | null;
+    readonly model: string | null;
+    readonly sandbox: SandboxMode;
+    readonly approval: string;
+    readonly origin: SessionOrigin;
+    readonly depth: number;
+    readonly pendingApprovals: readonly PendingApproval[];
+    readonly finalText: string | null;
+    /** True when `finalText` was capped/truncated at store time (registry cap). */
+    readonly finalTextTruncated: boolean;
+    /**
+     * Running assistant text accumulated from `item/agentMessage/delta` for the
+     * CURRENT turn — lets a poller watch a turn mid-stream without a second
+     * get_log call. Bounded (keeps the most recent chars); reset at turn start.
+     * Once a turn completes, `finalText` is the authoritative answer.
+     */
+    readonly latestAssistantPreview: string | null;
+    /** True when the running preview dropped older chars to stay bounded. */
+    readonly latestAssistantPreviewTruncated: boolean;
+    readonly failureReason: string | null;
+    /** Latest unified-diff string from `turn/diff/updated` (capped, current turn). */
+    readonly latestDiff: string | null;
+    /** Latest plan steps from `turn/plan/updated` (current turn). */
+    readonly latestPlan: ReadonlyArray<{
+        step: string;
+        status: string;
+    }> | null;
+    /** Optional explanation accompanying the latest plan. */
+    readonly planExplanation: string | null;
+    readonly tokenUsage: SessionTokenUsage;
+    readonly eventCount: number;
+    readonly createdAtMs: number;
+    readonly updatedAtMs: number;
+    readonly lastActivityAtMs: number;
+}
+export interface SessionRecordInit {
+    readonly sessionId: string;
+    readonly threadId: string;
+    readonly sandbox: SandboxMode;
+    readonly approval: string;
+    readonly origin: SessionOrigin;
+    readonly depth: number;
+    readonly createdAtMs: number;
+    readonly eventBuffer: number;
+    readonly maxEventTextChars: number;
+    readonly maxFinalTextChars: number;
+    readonly cwd?: string | undefined;
+    readonly model?: string | undefined;
+}
+/**
+ * Serializable record of a single Codex app-server session.
+ *
+ * Holds the durable per-session state (config, status, token accounting,
+ * pending approvals, capped final text) plus the bounded event ring. All
+ * mutating helpers take an injected `nowMs` so the registry's clock drives
+ * every timestamp deterministically.
+ */
+export declare class SessionRecord {
+    readonly sessionId: string;
+    threadId: string;
+    activeTurnId: string | undefined;
+    status: SessionStatus;
+    readonly cwd: string | undefined;
+    readonly model: string | undefined;
+    readonly sandbox: SandboxMode;
+    readonly approval: string;
+    readonly origin: SessionOrigin;
+    readonly depth: number;
+    readonly pendingApprovals: Map<string | number, PendingApproval>;
+    finalText: string | undefined;
+    /** Set when the most recent finalText assignment was capped by the registry. */
+    finalTextTruncated: boolean;
+    /** Running per-turn assistant preview (most-recent chars, bounded). */
+    latestAssistantPreview: string | null;
+    private latestAssistantPreviewTruncated;
+    /**
+     * Turn id the running preview belongs to. Lets {@link beginTurn} distinguish
+     * "establishing the SAME turn whose early deltas already landed" (preserve the
+     * preview) from "starting a genuinely different turn" (reset it). Without this,
+     * a delta arriving before turn/start was established was erased by beginTurn.
+     */
+    private latestAssistantPreviewTurnId;
+    failureReason: string | undefined;
+    latestDiff: string | null;
+    latestPlan: ReadonlyArray<{
+        step: string;
+        status: string;
+    }> | null;
+    planExplanation: string | null;
+    readonly tokenUsage: SessionTokenUsage;
+    readonly events: SessionEventRing;
+    readonly createdAtMs: number;
+    updatedAtMs: number;
+    lastActivityAtMs: number;
+    private readonly maxFinalTextChars;
+    /** Cap for the running assistant preview; shares the event-text budget. */
+    private readonly maxPreviewChars;
+    constructor(init: SessionRecordInit);
+    /** Begin (or resume into) a new active turn. Carries the cumulative token baseline forward. */
+    beginTurn(turnId: string, nowMs: number): void;
+    recordTokenUsage(usage: TokenUsage, nowMs: number): void;
+    appendEvent(event: CodexAppServerEvent, nowMs: number): void;
+    setPendingApproval(approval: PendingApproval, nowMs: number): void;
+    getPendingApproval(id: RequestId): PendingApproval | undefined;
+    clearPendingApproval(id: RequestId, nowMs: number): boolean;
+    clearPendingApprovals(nowMs: number): void;
+    /** Cache the latest unified diff for the active turn, capped to bound memory. */
+    setLatestDiff(diff: string, nowMs: number): void;
+    /**
+     * Cache the latest plan steps (and optional explanation) for the active turn.
+     * Steps are count-capped and each field length-capped, and copied into FRESH
+     * objects so a later mutation of the source array cannot alter stored state.
+     */
+    setLatestPlan(plan: ReadonlyArray<{
+        step: string;
+        status: string;
+    }>, explanation: string | null, nowMs: number): void;
+    /**
+     * Cache the latest final-answer text, capped at assignment so that failure/
+     * kill paths which finalize WITHOUT passing finalText still expose a bounded
+     * value (review fix 7). completeTurn re-applies the same cap idempotently.
+     */
+    setFinalText(text: string): void;
+    /**
+     * Accumulate a streaming assistant delta into the running preview. Bounded by
+     * keeping the MOST RECENT `maxPreviewChars` (a live preview wants the latest
+     * text, unlike finalText which keeps the head); drops to the tail flag
+     * `latestAssistantPreviewTruncated` once older chars are shed.
+     *
+     * `turnId` tags the running preview so {@link beginTurn} can tell whether a
+     * subsequent establishment is for THIS turn (preserve) or a new one (reset).
+     * It may be undefined when the wire event omitted a turn id — but the wire
+     * schema requires it (AgentMessageDeltaNotificationSchema.turnId: z.string()),
+     * so the undefined branch is defense-only and leaves the tag untouched.
+     *
+     * Defense-in-depth ordering guard: correctness must not rely on `turn/started`
+     * always preceding that turn's first delta. We never blindly concatenate
+     * across a turn boundary:
+     *   - Drop a delta whose `turnId` belongs to a DIFFERENT in-flight turn
+     *     (`turnId != activeTurnId` while `activeTurnId != null`). This discards a
+     *     stale, out-of-order cross-turn delta instead of corrupting the current
+     *     turn's preview. The establishment path is preserved because the early
+     *     delta arrives while `activeTurnId` is still null (beginTurn not yet run),
+     *     so it is NOT dropped.
+     *   - If the delta is accepted but its `turnId` differs from the preview's
+     *     current tag, start a fresh preview for it (reset before appending). On
+     *     the establishment path this is a no-op reset of an already-empty preview,
+     *     so the result is identical to a plain append onto null — it cannot
+     *     regress the early-delta (Issue-1) fix.
+     */
+    appendAssistantDelta(delta: string, turnId: string | undefined, nowMs: number): void;
+    /** Cap finalText and record whether the cap actually truncated the value. */
+    private applyFinalText;
+    /**
+     * Mark the active turn terminal. `finalText` is capped via `limitOutput`
+     * AT STORE TIME (2-2). Non-`completed` terminal states flag the token delta
+     * incomplete so resume/retry does not double-count (2-2).
+     */
+    completeTurn(status: SessionStatus, opts: {
+        finalText?: string | undefined;
+        failureReason?: string | undefined;
+    }, nowMs: number): void;
+    isIdle(): boolean;
+    /** A resumable record retains a valid threadId (the on-disk rollout survives). */
+    isResumable(): boolean;
+    touch(nowMs: number): void;
+    snapshot(): SessionSnapshot;
+}