@rynx-ai/runtime 0.1.0

package/dist/claude/native-hooks.js

@@ -0,0 +1,73 @@
+/**
+ * Build the Claude Code `--settings` JSON that registers rynx's claude-native
+ * hooks. Each hook is a `command` that runs a standalone node entrypoint
+ * ({@link ./native-hook-main.ts}) against the session's bridge dir; the
+ * subprocess appends the hook payload to `hooks.jsonl` (observer) or POSTs to
+ * the daemon and relays the verdict (PermissionRequest).
+ *
+ * Registered here (the core turn-framing + approval subset; mirrors omnigent's
+ * `build_hook_settings`):
+ *   - `SessionStart`         → discovery (transcript_path + claude session id)
+ *   - `Stop` / `StopFailure` → turn close (idle / failed)
+ *   - `PermissionRequest`    → approvals (only when a serverUrl is provided)
+ *
+ * Turn OPEN is transcript-driven (the `role:user` record), so `UserPromptSubmit`
+ * is intentionally NOT registered. `MessageDisplay` (streaming) and `statusLine`
+ * (context/cost) are opt-in; the task/todo hooks are added by their later phase.
+ */
+import { fileURLToPath } from "node:url";
+/** Claude waits this long (seconds) for the PermissionRequest hook's verdict — a
+ *  full day is effectively wait-forever for an interactive approval, matching
+ *  omnigent (its default ~60s command-hook timeout would kill the long-poll). */
+const PERMISSION_HOOK_TIMEOUT_S = 86_400;
+/** Absolute path to the built standalone hook entrypoint (sibling `.js`). */
+export function resolveHookEntryPath() {
+    return fileURLToPath(new URL("./native-hook-main.js", import.meta.url));
+}
+/** Absolute path to the built MessageDisplay hook entrypoint (sibling `.js`). */
+export function resolveMessageDisplayEntryPath() {
+    return fileURLToPath(new URL("./native-message-display-main.js", import.meta.url));
+}
+/** Absolute path to the built statusLine entrypoint (sibling `.js`). */
+export function resolveStatusEntryPath() {
+    return fileURLToPath(new URL("./native-status-main.js", import.meta.url));
+}
+/** Quote one argv token for a POSIX shell command string (single-quote wrap). */
+function shQuote(token) {
+    return `'${token.replace(/'/g, `'\\''`)}'`;
+}
+function shJoin(parts) {
+    return parts.map(shQuote).join(" ");
+}
+export function buildClaudeHookSettings(options) {
+    const node = options.nodePath ?? process.execPath;
+    const entry = options.hookEntryPath ?? resolveHookEntryPath();
+    const observer = shJoin([node, entry, "--bridge-dir", options.bridgeDir]);
+    const observerHook = { type: "command", command: observer };
+    const hooks = {
+        SessionStart: [{ hooks: [observerHook] }],
+        Stop: [{ hooks: [observerHook] }],
+        StopFailure: [{ hooks: [observerHook] }],
+    };
+    if (options.permission) {
+        const permission = shJoin([node, entry, "permission-request", "--bridge-dir", options.bridgeDir]);
+        hooks.PermissionRequest = [
+            { hooks: [{ type: "command", command: permission, timeout: PERMISSION_HOOK_TIMEOUT_S }] },
+        ];
+    }
+    if (options.messageDisplay) {
+        const md = options.messageDisplayEntryPath ?? resolveMessageDisplayEntryPath();
+        hooks.MessageDisplay = [
+            { hooks: [{ type: "command", command: shJoin([node, md, "--bridge-dir", options.bridgeDir]) }] },
+        ];
+    }
+    const settings = { hooks };
+    if (options.statusLine) {
+        const status = options.statusEntryPath ?? resolveStatusEntryPath();
+        settings.statusLine = {
+            type: "command",
+            command: shJoin([node, status, "--bridge-dir", options.bridgeDir]),
+        };
+    }
+    return settings;
+}

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

@@ -0,0 +1,213 @@
+import type { AgentEvent, TerminalCommandData, TodoItem } from "@rynx-ai/core";
+/** Mirror sink — the same shape as `CodexForwarderSink` so the host reuses one
+ *  per-turn normalizer wiring for both runtimes. */
+export interface ClaudeForwarderSink {
+    /** 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;
+    /** 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;
+    /** One mapped event within the current turn. */
+    onEvent(event: AgentEvent): 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;
+    /** The runtime went idle (Stop hook) — surface idle status WITHOUT finalizing
+     *  the turn. claude fires Stop around the same time it flushes the final
+     *  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(): void;
+    /** The current turn failed on the runtime (StopFailure hook). */
+    onTurnError(error: Error): 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;
+    /** 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;
+}
+export interface ClaudeLiveSessionOptions {
+    /** The session's bridge dir (`hooks.jsonl` lives here). */
+    bridgeDir: string;
+    sink: ClaudeForwarderSink;
+    /** Resume: a known transcript path to tail immediately (else await SessionStart). */
+    transcriptPath?: string;
+    /** Resume: the claude session id for that transcript — used to match the
+     *  persisted tail cursor so a re-launch resumes instead of re-mirroring. */
+    claudeSessionId?: string;
+    /** 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. */
+    idleCloseMs?: number;
+    /** Grace (ms) after the Stop hook before closing — lets a late assistant record
+     *  flush still join the turn (Stop and the flush race). */
+    stopGraceMs?: number;
+    now?: () => number;
+}
+export declare class ClaudeLiveSession {
+    private readonly bridgeDir;
+    private readonly sink;
+    private readonly pollMs;
+    private readonly idleCloseMs;
+    private readonly stopGraceMs;
+    private readonly now;
+    private started;
+    private stopped;
+    private hooksOffset;
+    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
+     *  forwarder state; bounded there. */
+    private readonly seenSourceIds;
+    private transcriptPath?;
+    private discovered;
+    /** claude's current session uuid (changes on `/clear`·`/fork`·resume). */
+    private currentClaudeSessionId?;
+    /** 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?;
+    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;
+    /** 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
+     *  `TaskCreate`/`TaskUpdate`). Emitted whole as a snapshot on any change. */
+    private readonly todos;
+    /** Latest statusLine context/cost snapshot (context_window + cost); attached to
+     *  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
+     *  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;
+    constructor(opts: ClaudeLiveSessionOptions);
+    /**
+     * Restore the durable forwarder cursor for `transcriptPath` (omnigent'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
+     * to the current EOF — never seek into a stale offset — while preserving
+     * `seenSourceIds` so nothing re-emits.
+     */
+    private restoreForwardState;
+    /** Persist the durable forwarder cursor (byte offset + seen ids + fingerprint). */
+    private persistForwardState;
+    /** True once SessionStart bound the transcript (or a resume path was given). */
+    isReady(): boolean;
+    start(): void;
+    stop(): 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;
+    /** 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
+     *  SessionStart (compact/resume/startup) is followed WITHOUT rotating. */
+    private handleSessionStart;
+    /** Switch the tailed transcript and reset per-session accumulators (the bridge
+     *  files — hooks/deltas/status — are shared by the same claude process across a
+     *  rotation, so their cursors are NOT reset). */
+    private repointTranscript;
+    private pollTranscript;
+    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. */
+    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. */
+    private pollDeltas;
+    /** Refresh the latest statusLine context/cost snapshot (a last-writer-wins file
+     *  the statusLine hook overwrites on every TUI render). */
+    private pollStatus;
+    /** A usage record from the latest statusLine snapshot (snake_case, the keys the
+     *  normalizer's `turn_completed` + the web `readUsageTokens` read), or undefined
+     *  if the statusLine hook has not fired yet. */
+    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. */
+    private remapMessageItem;
+    private trackTool;
+    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). */
+    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
+     *  the response was cancelled before it produced output — leaving the turn open
+     *  and the UI spinner stuck until the long inactivity backstop. Treat the
+     *  interrupt like a Stop: surface idle now (clears the spinner) and schedule the
+     *  turn's close via the same short grace. The Escape has stopped claude, so this
+     *  does not race a still-running response. */
+    noteInterrupted(): void;
+    /** Whether a claude turn is currently open (a response is running / pending).
+     *  The web Stop button gates its interrupt on this so an idle pane is never
+     *  sent an Escape — an Escape into idle claude submits an empty turn, which
+     *  claude answers with a stray "No response requested." bubble. */
+    isTurnOpen(): boolean;
+    private closeTurn;
+    private closeTurnError;
+    private maybeIdleClose;
+}
+/** The tmux-pane operations claude-native injection needs (a subset of
+ *  {@link import("../terminal/tmux.js").TmuxTerminal}). The runner-child hands
+ *  this to the host after launching the pane, since the host doesn't own tmux. */
+export interface TerminalInjector {
+    capturePane(): string;
+    clearInputLine(): void;
+    paste(text: string): void;
+    sendEnter(): void;
+    /** Interrupt the running turn (Escape) — the web Stop button (omnigent). */
+    interrupt(): void;
+}
+export interface InjectViaTerminalOptions {
+    promptGlyph?: string;
+    promptTimeoutMs?: number;
+    pasteCommitMs?: number;
+    settleMs?: number;
+    submitVerifyMs?: number;
+    submitRetryMs?: number;
+    pollMs?: number;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+    /** Abort the paste/submit sequence (the web Stop button). On abort the input
+     *  line is cleared and injection returns false — the message is NOT submitted. */
+    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).
+ *
+ * THROWS if the prompt never appears within the ready-gate window (omnigent
+ * `_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).
+ */
+export declare function injectViaTerminal(injector: TerminalInjector, text: string, opts?: InjectViaTerminalOptions): Promise<boolean>;