@rynx-ai/runtime 0.1.0 → 0.1.10-beta.2

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

@@ -1,4 +1,5 @@
-import type { AgentEvent, TerminalCommandData, TodoItem } from "@rynx-ai/core";
+import type { AgentEvent, SessionInteractionResolution, TerminalCommandData, TodoItem } from "@rynx-ai/core";
+import type { ResolveInteractionResult, RuntimeInteractionEvent } from "../interactions.js";
 /** Mirror sink — the same shape as `CodexForwarderSink` so the host reuses one
  *  per-turn normalizer wiring for both runtimes. */
 export interface ClaudeForwarderSink {
@@ -14,6 +15,9 @@ export interface ClaudeForwarderSink {
     onTodos(todos: TodoItem[]): void;
     /** One mapped event within the current turn. */
     onEvent(event: AgentEvent): void;
+    /** A provider-neutral question/permission requested or settled while this
+     *  Turn remains active. */
+    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>): void;
@@ -51,6 +55,10 @@ export interface ClaudeLiveSessionOptions {
      *  flush still join the turn (Stop and the flush race). */
     stopGraceMs?: number;
     now?: () => number;
+    /** Process-liveness probe for the blocking native hook (test override). */
+    isProcessAlive?: (pid: number) => boolean;
+    /** Native lease timestamp reader (test override). */
+    interactionLeaseUpdatedAt?: (interactionId: string) => number | undefined;
 }
 export declare class ClaudeLiveSession {
     private readonly bridgeDir;
@@ -59,9 +67,13 @@ export declare class ClaudeLiveSession {
     private readonly idleCloseMs;
     private readonly stopGraceMs;
     private readonly now;
+    private readonly isProcessAlive;
+    private readonly leaseUpdatedAt;
     private started;
     private stopped;
     private hooksOffset;
+    private interactionsOffset;
+    private interactionAcksOffset;
     private transcriptOffset;
     /** Secondary dedup: source ids (record uuids) already forwarded, so a re-read
      *  (fingerprint reset / mid-poll death) doesn't re-emit. Persisted in the
@@ -76,11 +88,40 @@ export declare class ClaudeLiveSession {
     private readonly seenClaudeSessionIds;
     private turnOpen;
     private currentTurnId?;
+    /** The Turn opened from a pre-transcript interaction. Its unique provisional
+     * id keeps responses distinct until the real prompt uuid can be adopted. */
+    private syntheticTurn;
     private lastActivityAt;
     /** When the Stop hook fired (null = not yet) — drives the grace-period close. */
     private stopPendingAt;
     /** Open tool-call ids (start seen, end not yet) — suppresses the idle backstop. */
     private readonly openToolIds;
+    /** Transcript-backed acknowledgements for web→TUI input. A direct idle
+     * submit is recorded as `promptSource:"typed"`; a submit while Claude is busy
+     * is recorded immediately as `queue-operation:enqueue` and only later
+     * promoted to `promptSource:"queued"`. The promotion is intentionally not a
+     * second acknowledgement. */
+    private submissionSequence;
+    private readonly submissionObservations;
+    /** Enqueued type-ahead inputs awaiting their eventual role:user promotion.
+     * Claude has used both `promptSource:"queued"` and `"sdk"` for that later
+     * record, so content correlation is the stable discriminator. */
+    private readonly pendingQueuedSubmissions;
+    /** Blocking native questions/permissions. Their hook subprocess is still
+     *  executing, so the Turn remains running and cannot be idle-closed. */
+    private readonly pendingInteractions;
+    private readonly settledInteractions;
+    /** Claimed response files may still contain the provider-bound, unredacted
+     * answer. Keep tracking them after canonical settlement until ACK/hook cleanup. */
+    private readonly claimedInteractions;
+    private readonly scheduledClaimScrubs;
+    /** Stop is flushed after interactions in the same poll, preventing a
+     *  request+Stop race from briefly reporting this executing Turn as idle. */
+    private stopSignalPending;
+    /** StopFailure is likewise flushed after interactions. A blocking hook can
+     *  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;
     /** The agent's task list, keyed by task id in creation order (claude
@@ -90,14 +131,19 @@ export declare class ClaudeLiveSession {
      *  a turn's usage on close. undefined until the statusLine hook first fires. */
     private latestStatus?;
     private deltasOffset;
-    /** MessageDisplay message ids in first-seen order, FIFO-mapped onto the
+    /** 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). */
     private readonly messageIdQueue;
-    private readonly seenMessageIds;
+    private readonly finalizedMessageIds;
+    /** Transcript messages that arrived before their MessageDisplay stream. A
+     *  matching late final consumes both sides so its id cannot shift the FIFO
+     *  used by the next assistant message. */
+    private readonly unmatchedTranscriptMessages;
+    private readonly streamedMessageText;
     constructor(opts: ClaudeLiveSessionOptions);
     /**
-     * Restore the durable forwarder cursor for `transcriptPath` (omnigent's
+     * Restore the durable forwarder cursor for `transcriptPath` (reference implementation's
      * `_validated_transcript_state`). A cursor for a DIFFERENT file is ignored (a new
      * session starts at 0). A matching cursor whose fingerprint still validates
      * resumes at its `byteOffset`; a MISMATCH (the file was truncated/replaced) skips
@@ -109,14 +155,35 @@ export declare class ClaudeLiveSession {
     private persistForwardState;
     /** True once SessionStart bound the transcript (or a resume path was given). */
     isReady(): boolean;
+    /** Drain records that predate a new injection, then return a monotonic
+     * checkpoint. This prevents a lagging, older identical prompt from
+     * acknowledging the new submit. */
+    beginSubmissionObservation(): number;
+    /** Whether Claude durably accepted `text` after `checkpoint`. Polling the
+     * transcript here makes submit confirmation independent of the background
+     * forwarder interval and covers both idle and type-ahead submissions. */
+    hasObservedSubmissionAfter(checkpoint: number, text: string): boolean;
+    private rememberSubmission;
+    private rememberQueuedSubmission;
+    private consumeQueuedPromotion;
     start(): void;
     stop(): void;
+    /** Phase two of runner shutdown. The caller must stop the Claude terminal
+     * 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
      *  drive deterministically; the async {@link loop} just calls it on an interval. */
     tick(): void;
     private loop;
     private pollHooks;
     private handleHook;
+    /** 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;
     /** 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
@@ -127,6 +194,39 @@ export declare class ClaudeLiveSession {
      *  rotation, so their cursors are NOT reset). */
     private repointTranscript;
     private pollTranscript;
+    /** 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;
+    private drainInteractionCommits;
+    /** A hook acknowledgement is the commit point: it is appended after the hook
+     * consumes the one-shot response and before it returns the native verdict. */
+    private pollInteractionAcks;
+    /** A claimed response is already consumed by the native hook. This fallback
+     * converges the interaction even if the hook exits before appending its
+     * redacted ACK. */
+    private pollInteractionClaims;
+    /** A request cannot remain actionable after its blocking hook exits. A short
+     * post-submit timeout also converges requests created by older hooks that did
+     * not publish a waiter pid, and scrubs any unacknowledged secret response. */
+    private pollAbandonedInteractions;
+    /** Deliver an answer to the blocked hook. The bridge file contains the real
+     *  answer; only the canonical resolved event receives a secret-redacted copy. */
+    resolveInteraction(interactionId: string, resolution: SessionInteractionResolution): ResolveInteractionResult;
+    private cancelPendingInteractions;
+    /** Terminal cancellation may race the hook's atomic result claim. A claim
+     * always wins; otherwise the cancellation file becomes the hook's verdict. */
+    private cancelOrSettlePendingInteraction;
+    private settleClaimedInteraction;
+    /** A claim is the hook's private handoff file and can contain secret answers.
+     * ACK/finally normally removes it; process death or an expired lease is the
+     * crash fallback after the canonical interaction has already settled. */
+    private pollClaimedInteractionCleanup;
+    /** Once this forwarder stops it can no longer poll a later hook crash. Keep a
+     * short unref'd scrub deadline so unredacted claim material cannot persist for
+     * the lifetime of the daemon. */
+    private scheduleClaimedInteractionScrubs;
+    private settleCancelledInteraction;
+    private rememberSettled;
     private handleRecord;
     /** 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. */
@@ -140,6 +240,7 @@ export declare class ClaudeLiveSession {
      *  events. Guarded on an open turn — deltas belong to the turn the user record
      *  opened; the offset advances only once processed. */
     private pollDeltas;
+    private finalizeMessageDisplay;
     /** Refresh the latest statusLine context/cost snapshot (a last-writer-wins file
      *  the statusLine hook overwrites on every TUI render). */
     private pollStatus;
@@ -149,7 +250,8 @@ export declare class ClaudeLiveSession {
     private statusUsage;
     /** Remap an assistant-text `message_completed` onto the FIFO-matched
      *  MessageDisplay message_id, so its streamed deltas and this final item share
-     *  an itemId. No queued delta (MessageDisplay didn't fire) → keep the transcript id. */
+     *  an itemId. No queued delta yet → keep the transcript id and remember its
+     *  text so a late MessageDisplay final can be reconciled backward. */
     private remapMessageItem;
     private trackTool;
     private ensureTurn;
@@ -172,6 +274,7 @@ export declare class ClaudeLiveSession {
     isTurnOpen(): boolean;
     private closeTurn;
     private closeTurnError;
+    private resetMessageCorrelation;
     private maybeIdleClose;
 }
 /** The tmux-pane operations claude-native injection needs (a subset of
@@ -182,16 +285,20 @@ export interface TerminalInjector {
     clearInputLine(): void;
     paste(text: string): void;
     sendEnter(): void;
-    /** Interrupt the running turn (Escape) — the web Stop button (omnigent). */
+    /** Interrupt the running turn (Escape) — the web Stop button (reference implementation). */
     interrupt(): void;
 }
 export interface InjectViaTerminalOptions {
     promptGlyph?: string;
     promptTimeoutMs?: number;
-    pasteCommitMs?: number;
     settleMs?: number;
-    submitVerifyMs?: number;
-    submitRetryMs?: number;
+    /** Transcript-backed proof that Claude accepted this exact input. When
+     * absent, injection keeps the legacy one-Enter best-effort contract. */
+    submissionObserved?: () => boolean;
+    /** Per-attempt wait for a transcript acknowledgement. */
+    submitConfirmMs?: number;
+    /** Total Enter attempts when transcript confirmation is available. */
+    maxSubmitAttempts?: number;
     pollMs?: number;
     now?: () => number;
     sleep?: (ms: number) => Promise<void>;
@@ -200,14 +307,14 @@ export interface InjectViaTerminalOptions {
     signal?: AbortSignal;
 }
 /**
- * Deliver `text` into a claude TUI pane, the omnigent recipe:
- *   ready-gate (poll for `❯`) → clear leftover → bracketed paste (+ trailing
- *   newline) → wait for the draft to land → settle → submit Enter → verify the
- *   draft left the box (re-send Enter while it hasn't).
+ * Deliver `text` into a claude TUI pane, the reference implementation recipe:
+ *   ready-gate (poll for `❯`) → clear leftover → bracketed paste the draft
+ *   → settle → submit Enter → confirm from Claude's transcript.
  *
- * THROWS if the prompt never appears within the ready-gate window (omnigent
+ * THROWS if the prompt never appears within the ready-gate window (reference implementation
  * `_wait_for_claude_prompt_ready` RAISE) — a not-ready pane is a hard error the
- * caller reports, NOT a signal to fall through to a second output path. Returns
- * `true` once the message is submitted (best-effort even if submit-verify times out).
+ * caller reports, NOT a signal to fall through to a second output path. With a
+ * transcript observer, Enter is retried only when Claude has durably recorded
+ * neither a direct user prompt nor a type-ahead enqueue.
  */
 export declare function injectViaTerminal(injector: TerminalInjector, text: string, opts?: InjectViaTerminalOptions): Promise<boolean>;