@rynx-ai/runtime 0.1.11-beta.37 → 0.1.11-beta.39

package/dist/claude/native-integration.d.ts

@@ -4,16 +4,46 @@ import { type ClaudeRunnerStatus } from "./session-status.js";
 /** Mirror sink — the same shape as `CodexForwarderSink` so the host reuses one
  *  per-turn normalizer wiring for both runtimes. */
 export interface ClaudeForwarderSink {
+    /** Begin one transcript source record. The host derives per-item source keys
+     * from this stable base while still running the normalizer for already-seen
+     * items so later records recover the same turn/tool state. */
+    onTranscriptRecordStart?(sourceBase: string, isHandled: (sourceId: string) => boolean, delivery?: {
+        lane?: string;
+        deadLetterPath?: string;
+        /** Persist an individual handled item before the containing record's
+         * byte cursor is allowed to advance. */
+        onHandled?: (sourceId: string) => void;
+    }): void;
+    /** Resolve only after every newly emitted durable item from the current
+     * record has reached a handled delivery outcome. Returns all per-item keys. */
+    onTranscriptRecordEnd?(): Promise<readonly string[]>;
     /** A turn began; `turnId` (the user record uuid) derives a stable responseId. */
     onTurnStart(turnId?: string): void;
     /** The user's prompt text (a `role:user` conversation message — not identity). */
     onUserMessage(text: string): void;
+    /** Provider-generated task notification persisted as hidden model context.
+     * It owns an independent response identity and never changes the parent Turn. */
+    onMetaUserMessage?(text: string, sourceKey?: string, parentToolCallId?: string): void;
+    /** Claude Code native sub-agent task prompt, nested under the parent Task
+     * tool call instead of opening a parent Session turn. */
+    onSubagentUserMessage?(text: string, parentToolCallId: string): void;
+    /** A native sub-agent's top-level `!cmd`, nested under its parent Task. */
+    onSubagentTerminalCommand?(cmd: TerminalCommandData, parentToolCallId: string): void;
+    /** Resolve/publish the canonical parent Turn for a native sub-agent. This
+     * mapping is persisted beside the independent child cursor. */
+    resolveSubagentParentResponseId?(parentToolCallId: string): string | undefined;
+    onSubagentParentResponse?(parentToolCallId: string, responseId: string): void;
     /** A local shell command the user ran in the TUI (claude `!` bash mode), framed
      *  as its own mini-turn (an `onTurnStart`/`onTurnEnd` pair brackets this call). */
     onTerminalCommand(cmd: TerminalCommandData): void;
     /** The agent's task list changed (claude `TaskCreate`/`TaskUpdate`) — the WHOLE
      *  current list (a session-level snapshot, not tied to a turn). */
     onTodos(todos: TodoItem[]): void;
+    /** Best-effort spinner edges around Claude's native compaction. */
+    onCompactionStatus?(status: "in_progress" | "completed" | "failed"): void;
+    /** Persist one compaction boundary. `true` means confirmed/ambiguous-handled;
+     * `false` means a bounded secondary hook delivery was dropped. */
+    onCompactionBoundary?(summary: string, sequence: number, source: "transcript" | "hook"): boolean | Promise<boolean>;
     /** One mapped event within the current turn. */
     onEvent(event: AgentEvent): void;
     /** A provider-neutral question/permission requested or settled while this
@@ -21,7 +51,7 @@ export interface ClaudeForwarderSink {
     onInteraction(event: RuntimeInteractionEvent): void;
     /** The current turn finished (a new user prompt, or the inactivity backstop).
      *  `usage` carries the latest statusLine context/cost snapshot, when captured. */
-    onTurnEnd(usage?: Record<string, unknown>, backgroundTaskCount?: number): void;
+    onTurnEnd(usage?: Record<string, unknown>, backgroundTaskCount?: number, reason?: "rotation"): void;
     /** The current turn ended because the user explicitly interrupted it. */
     onTurnInterrupted?(usage?: Record<string, unknown>): void;
     /** Escape was sent for the open Turn. Publish cancelled UI state immediately;
@@ -34,10 +64,10 @@ export interface ClaudeForwarderSink {
      *  assistant record and the two orderings race; finalizing here would split a
      *  late assistant record into its own turn. The turn is finalized by the next
      *  user prompt or the inactivity backstop, so a late record still joins it. */
-    onIdle(backgroundTaskCount?: number): void;
+    onIdle(backgroundTaskCount?: number, sourceId?: string): void | Promise<void>;
     /** Claude's current Turn or native runtime failed (StopFailure/pane exit).
      * May fire between Turns so Session-level failure can retire stale liveness. */
-    onTurnError(error: Error): void;
+    onTurnError(error: Error, sourceId?: string): void | Promise<void>;
     /** Fired once SessionStart reveals claude's session id + transcript path, so
      *  the host can persist the id and release its readiness gate. */
     onSessionDiscovered?(claudeSessionId: string, transcriptPath: string): void;
@@ -45,10 +75,10 @@ export interface ClaudeForwarderSink {
      *  binding. The host keeps the original binding and fails readiness. */
     onSessionResumeError?(error: Error): void;
     /** The claude session rotated (`/clear` → fresh, `/fork` → derived): a new
-     *  SessionStart reported a new session id + transcript. The forwarder has
-     *  already re-pointed to the new transcript and reset its per-session state; the
-     *  host mints a fresh rynx session and re-targets the mirror to it. */
-    onSessionRotated?(kind: "clear" | "fork", claudeSessionId: string, transcriptPath: string): void;
+     *  SessionStart reported a new session id + transcript. The old Response is
+     *  closed first; the forwarder re-points only after this publication barrier
+     *  resolves, so the host can mint a fresh rynx session and ACK mirror retarget. */
+    onSessionRotated?(kind: "clear" | "fork", claudeSessionId: string, transcriptPath: string, initialTranscriptOffset: number): void | Promise<void>;
 }
 export interface ClaudeLiveSessionOptions {
     /** The session's bridge dir (`hooks.jsonl` lives here). */
@@ -64,6 +94,10 @@ export interface ClaudeLiveSessionOptions {
      *  matching forwarder cursor exists, follow only records appended after the
      *  SessionStart discovery instead of mirroring native history a second time. */
     resumeAtEndOnDiscovery?: boolean;
+    /** Exact native-rotation boundary persisted by the host. It takes
+     * precedence over resumeAtEndOnDiscovery so a delayed restart cannot skip
+     * target records written after SessionStart. */
+    initialTranscriptOffsetOnDiscovery?: number;
     /** Poll interval (ms). The files are append-only, so polling is simplest. */
     pollMs?: number;
     /** Inactivity (ms) FALLBACK close for a turn whose Stop hook never fired. */
@@ -92,9 +126,24 @@ export declare class ClaudeLiveSession {
     private releaseSleep?;
     private hooksOffset;
     private hookEventCursor;
+    /** Rotation publication is a checkpoint barrier. No source is polled under
+     * either logical Session until the daemon confirms the new binding. */
+    private rotationPending;
+    /** A non-rotation async hook (currently compaction completion) holds only the
+     * hook cursor and parent transcript. Native sub-agents, deltas, interactions,
+     * and live status continue to converge while its delivery retries. */
+    private compactionHookPending;
+    private pendingCompactionHook?;
     private interactionsOffset;
     private interactionAcksOffset;
     private transcriptOffset;
+    private committedTranscriptOffset;
+    private transcriptLineCursor;
+    private committedTranscriptLineCursor;
+    private transcriptDeliveryPending;
+    /** A transcript isCompactSummary boundary is currently in its durable lane.
+     * The completion-hook fallback must wait so the real summary remains primary. */
+    private transcriptCompactionPending;
     /** Secondary dedup: source ids (record uuids) already forwarded, so a re-read
      *  (fingerprint reset / mid-poll death) doesn't re-emit. Persisted in the
      *  forwarder state; bounded there. */
@@ -106,11 +155,20 @@ export declare class ClaudeLiveSession {
     /** Persisted native id requested through `claude --resume`. */
     private readonly expectedClaudeSessionId?;
     private readonly resumeAtEndOnDiscovery;
+    private readonly initialTranscriptOffsetOnDiscovery;
     /** Every claude session uuid seen — a resume into an UNSEEN id + a forkedFrom
      *  marker signals a `/fork` (vs. resuming a known branch). */
     private readonly seenClaudeSessionIds;
     private turnOpen;
     private currentTurnId?;
+    /** Input half of a split Claude `!cmd`, plus the turn id its later output
+     * must reuse. Kept across a terminal Stop edge like the current terminal
+     * response id. */
+    private activeTerminalCommand?;
+    /** Split-command state at the latest individually handled source boundary.
+     * Parsing may run ahead through later records, so durable state must not use
+     * the mutable live value until those later items are ACKed too. */
+    private committedTerminalCommand?;
     /** The open turn received an explicit Escape/Stop and must close cancelled. */
     private turnInterrupted;
     /** The Turn opened from a pre-transcript interaction. Its unique provisional
@@ -159,8 +217,17 @@ export declare class ClaudeLiveSession {
      *  append its request immediately before the failure hook lands; closing here
      *  would let the later interaction poll reopen an already-failed Turn. */
     private turnFailurePending;
-    /** Sub-agent (Task) ids already forwarded — a Task tool_result is processed once. */
-    private readonly seenSubagents;
+    /** Stop/StopFailure owns the hook cursor until its terminal status reaches a
+     * handled delivery outcome. This preserves replay on runner restart. */
+    private pendingTerminalHook?;
+    private terminalHookDelivery?;
+    private pendingTranscriptCompactions;
+    /** Claude Code native Task/Agent sidechains. Each child owns an independent
+     * cursor/retry lane so one unavailable delivery cannot block its siblings or
+     * the parent transcript. */
+    private readonly nativeSubagents;
+    private readonly nativeSubagentParentResponses;
+    private subagentStateParentPath?;
     /** The agent's task list, keyed by task id in creation order (claude
      *  `TaskCreate`/`TaskUpdate`). Emitted whole as a snapshot on any change. */
     private readonly todos;
@@ -168,6 +235,7 @@ export declare class ClaudeLiveSession {
      *  a turn's usage on close. undefined until the statusLine hook first fires. */
     private latestStatus?;
     private deltasOffset;
+    private readonly seenDeltaKeys;
     /** Finalized MessageDisplay ids in completion order, FIFO-mapped onto the
      *  transcript's assistant-text records so a streamed message and its final
      *  item share an itemId (message_id is absent from the transcript). */
@@ -213,7 +281,8 @@ export declare class ClaudeLiveSession {
      * first so no hook can still be opening an atomically claimed answer. This is
      * synchronous because the runner process exits immediately afterwards. */
     finalizeStop(): void;
-    /** One poll cycle (hooks → transcript → idle backstop). Exposed for tests to
+    /** One poll cycle (rotation/PreCompact prescan → transcript → hooks → live
+     * lanes → idle backstop). Exposed for tests to
      *  drive deterministically; the async {@link loop} just calls it on an interval. */
     tick(): void;
     /** Bind Claude's per-process session metadata after the terminal exists. */
@@ -224,15 +293,34 @@ export declare class ClaudeLiveSession {
     private supervise;
     private loop;
     private sleepUntilWake;
+    /** Rotation is a control edge, not an ordinary hook-stream item. Scan past a
+     * held Stop/compaction cursor so an old retry can never strand the physical
+     * Claude process on a new Session while Rynx still targets the old one. */
+    private prescanSessionRotation;
+    /** Mint compaction tokens before transcript parsing without advancing the
+     * hook cursor. The ordinary hook pass later observes the same cursor-keyed
+     * edge and converges on the already-created token. */
+    private prescanPrecompactEdges;
     private pollHooks;
+    private isSessionRotationHook;
+    private isForkHookRecord;
     private persistHookCursor;
     private handleHook;
+    private handleTodoHook;
+    private compactionGeneration;
+    private readCompactionState;
+    private notePrecompact;
+    private compactionPendingMatches;
+    private markCompactionPersisted;
+    private claimHookCompaction;
+    private handleCompactionCompletionHook;
     /** Process a provider failure only after this tick has discovered every
      *  blocking request already appended by its hook subprocess. */
     private flushTurnFailure;
     /** Emit the Stop idle signal only after this tick has discovered native
      *  interactions. A pending question/permission is active execution, not idle. */
     private flushStopSignal;
+    private finishTerminalHookDelivery;
     /** SessionStart drives discovery (first) and rotation (a later one with a NEW
      *  session id + transcript). `/clear` → source="clear"; `/fork` → source="resume"
      *  into an unseen id with a forkedFrom marker. Any other new-transcript
@@ -242,7 +330,18 @@ export declare class ClaudeLiveSession {
      *  files — hooks/deltas/status — are shared by the same claude process across a
      *  rotation, so their cursors are NOT reset). */
     private repointTranscript;
+    /** Revalidate the committed cursor every poll, not only after process restart.
+     * Claude may replace/truncate a transcript in place. Treat a stale
+     * nonzero fingerprint as a new file and skips to its current EOF while
+     * preserving the bounded seen set. A temporarily missing file keeps the
+     * cursor unchanged. */
+    private validateLiveTranscriptCursor;
     private pollTranscript;
+    private rememberSourceId;
+    private restoreSubagentForwardStates;
+    private persistSubagentForwardStates;
+    private pollNativeSubagents;
+    private pollNativeSubagent;
     /** Tail blocking hook requests after transcript records, so an interaction
      *  emitted in the same poll attaches to the user Turn that caused it. */
     private pollInteractions;
@@ -276,15 +375,16 @@ export declare class ClaudeLiveSession {
     private scheduleClaimedInteractionScrubs;
     private settleCancelledInteraction;
     private rememberSettled;
+    /** State change represented by this record once its durable terminal item is
+     * handled. Parsing can run through multiple records before their deliveries
+     * settle, so this checkpoint is intentionally separate from the live state. */
+    private terminalCommandCheckpointForRecord;
     private handleRecord;
+    private emitUserMessageRecord;
+    private handleCompactSummary;
     /** Fold a `TaskCreate` (new pending task) or `TaskUpdate` (status/subject/delete)
      *  record into the task list; on any change emit the whole list as a snapshot. */
     private maybeUpdateTodos;
-    /** On a `Task` tool_result, replay the sub-agent's own transcript
-     *  (`subagents/agent-<agentId>.jsonl`) as events tagged with the parent Task
-     *  tool-use id, so the canonical layer nests them under that call. Fired once
-     *  per sub-agent (at tool_result time the file is complete — no live race). */
-    private maybeForwardSubagent;
     /** Tail streamed assistant-text chunks (MessageDisplay) into live `token`
      *  events. Guarded on an open turn — deltas belong to the turn the user record
      *  opened; the offset advances only once processed. */
@@ -305,10 +405,12 @@ export declare class ClaudeLiveSession {
      *  text so a late MessageDisplay final can be reconciled backward. */
     private remapMessageItem;
     private trackTool;
+    private rememberNativeSubagentParentResponse;
     private ensureTurn;
-    /** Mirror a local `!` command as its own mini-turn: close any open turn, then
-     *  open→emit→close so it groups as one response with a stable id (the record
-     *  uuid) and never lingers "running" (input+output are complete in one record). */
+    /** Mirror a Claude `!cmd` as one logical mini-turn even when input and output
+     * are separate transcript records. The output repeats the remembered command
+     * in Rynx's combined terminal item shape; the transcript projection merges
+     * that completion into the preceding command row. */
     private emitTerminalCommand;
     /** The web Stop button interrupted this session (host sent Escape). claude
      *  records the interrupt in its own transcript but may not fire a Stop hook when