@lucascouts/claude-agent-tui 0.1.0

package/dist/ansi-mirror.d.ts

@@ -0,0 +1,42 @@
+import type { IPty, IDisposable } from "node-pty";
+/**
+ * The live-view sink: receives each raw PTY chunk verbatim. This is the OUTPUT-ONLY surface a
+ * host may pipe to a terminal view for §9 "is the prompt alive?" gating visibility. It is a sink,
+ * not a source — there is deliberately NO return channel by which a consumer could write back into
+ * engine/session state. Consumers MUST NOT parse this stream back into session state (§2): state
+ * comes only from the JSONL tail.
+ */
+export type AnsiChunkSink = (chunk: string) => void;
+/** Options for {@link attachAnsiMirror}. */
+export interface AnsiMirrorOptions {
+    /**
+     * Master flag — OFF by default (§5/§9). When false/absent, NO `p.onData` listener is attached
+     * and the engine path is byte-for-byte the read-only Degrau-1 behaviour. Only when true AND a
+     * sink is supplied is the cosmetic tap subscribed.
+     */
+    enabled?: boolean;
+    /**
+     * The live-view sink that receives each raw chunk verbatim. The tap is a no-op (and no listener
+     * is attached) when this is absent, so the mirror cannot accidentally subscribe with nowhere to
+     * forward to.
+     */
+    onAnsiChunk?: AnsiChunkSink;
+}
+/**
+ * Conditionally tap the PTY's `p.onData` stream for the cosmetic live ANSI mirror (§5).
+ *
+ * When the mirror is ENABLED (flag on AND a sink supplied), subscribes a stateless `p.onData`
+ * listener that forwards each raw chunk VERBATIM to the sink — no parsing, no ANSI decoding, no
+ * state accumulation, no `SessionUpdate`, no billing — and returns the `IDisposable` so the caller
+ * can detach it on teardown.
+ *
+ * When the mirror is DISABLED (the default — flag off OR no sink), `p.onData` is NEVER touched and
+ * the function returns `undefined`. This is the load-bearing guarantee that the OFF path is
+ * byte-for-byte the read-only Degrau-1 engine path: a disabled mirror attaches no listener at all.
+ *
+ * The mirror is structurally subordinate to the JSONL tail (§2): it is one-way (bytes → sink) and
+ * feeds NOTHING into the structural path. Toggling it on/off does not change the structural event
+ * sequence the JSONL tail produces.
+ */
+export declare function attachAnsiMirror(p: Pick<IPty, "onData">, opts?: AnsiMirrorOptions): IDisposable | undefined;
+//# sourceMappingURL=ansi-mirror.d.ts.map

package/dist/ansi-mirror.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ansi-mirror.d.ts","sourceRoot":"","sources":["../src/ansi-mirror.ts"],"names":[],"mappings":"AA8BA,OAAO,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAElD;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;AAEpD,4CAA4C;AAC5C,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;OAIG;IACH,WAAW,CAAC,EAAE,aAAa,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAC9B,CAAC,EAAE,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,EACvB,IAAI,GAAE,iBAAsB,GAC3B,WAAW,GAAG,SAAS,CAgBzB"}

package/dist/ansi-mirror.js

@@ -0,0 +1,61 @@
+// === §5 Espelho ANSI ao vivo (opcional) — cosmetic live PTY mirror (story 035) ===
+//
+// Optional, flag-gated tap on the story-013/014 PTY's `p.onData(chunk => …)` stream that
+// forwards the RAW TUI bytes to a "live-view" sink, for the §5 "ao vivo" effect ONLY. Its sole
+// purpose is the §9 v1 gating-visibility surface: a human can render this stream to confirm the
+// real `claude` prompt is alive and drawing in-TUI, WITHOUT it ever becoming a structural input.
+//
+// ── tail-as-source-of-truth fence (§2 ordering) ──────────────────────────────────────────────
+// This mirror is STRICTLY subordinate to the JSONL tail (stories 015/016/017). It:
+//   • holds NO parsed state — it is stateless and one-way (bytes → sink, nothing read back);
+//   • emits NO ACP `SessionUpdate` — it never calls the tail watcher, the event switch, the
+//     translators, or any `SessionUpdate` producer (structure/state come ONLY from the JSONL);
+//   • does NOT decode/parse ANSI — the byte stream is interleaved/partial across chunks, so any
+//     parse attempt would corrupt state; it forwards the chunk verbatim and nothing else;
+//   • touches NO billing and has NO IO side-effect beyond the single sink call.
+// ANY future code that derives session state from `onData` bytes is a §2 violation by construction.
+//
+// ── OFF is byte-for-byte the read-only Degrau-1 path (story 023) ─────────────────────────────
+// The flag is OFF by default. When disabled, {@link attachAnsiMirror} returns WITHOUT calling
+// `p.onData` at all — no listener is ever attached — so the engine path is identical to the
+// read-only Degrau-1 behaviour. Enabling/disabling the mirror changes NOTHING in the structural
+// output: the JSONL tail produces the identical event sequence with the mirror on or off.
+//
+// ── §7 caveat: streamEventToAcpNotifications stays UNWIRED in v1 ──────────────────────────────
+// `streamEventToAcpNotifications` (`content_block_delta` deltas) is left without a source in the
+// JSONL (which is per-block granular, §7); it would ONLY be viable layered ON TOP of this cosmetic
+// mirror. But this mirror has NO ordering or structural guarantees (structure still comes from the
+// JSONL tail per §2), so wiring deltas onto it is DELIBERATELY left undone in v1. This module
+// implements NO delta-to-`SessionUpdate` translation, and no such wiring exists in this path.
+/**
+ * Conditionally tap the PTY's `p.onData` stream for the cosmetic live ANSI mirror (§5).
+ *
+ * When the mirror is ENABLED (flag on AND a sink supplied), subscribes a stateless `p.onData`
+ * listener that forwards each raw chunk VERBATIM to the sink — no parsing, no ANSI decoding, no
+ * state accumulation, no `SessionUpdate`, no billing — and returns the `IDisposable` so the caller
+ * can detach it on teardown.
+ *
+ * When the mirror is DISABLED (the default — flag off OR no sink), `p.onData` is NEVER touched and
+ * the function returns `undefined`. This is the load-bearing guarantee that the OFF path is
+ * byte-for-byte the read-only Degrau-1 engine path: a disabled mirror attaches no listener at all.
+ *
+ * The mirror is structurally subordinate to the JSONL tail (§2): it is one-way (bytes → sink) and
+ * feeds NOTHING into the structural path. Toggling it on/off does not change the structural event
+ * sequence the JSONL tail produces.
+ */
+export function attachAnsiMirror(p, opts = {}) {
+    // OFF path (default): do NOT touch p.onData. No listener is attached → byte-for-byte the
+    // read-only Degrau-1 path. The `onAnsiChunk` guard means an enabled-but-sinkless config is also
+    // a no-op (it would have nowhere to forward to), never a dangling subscription.
+    if (!opts.enabled || !opts.onAnsiChunk) {
+        return undefined;
+    }
+    const sink = opts.onAnsiChunk;
+    // ON path: forward the raw chunk verbatim. STATELESS and one-way — bytes → sink ONLY. This
+    // handler deliberately does NOT call the tail watcher (015), the event switch (016), the
+    // translators, or any `SessionUpdate` producer (§2). Deriving any state from `chunk` here would
+    // be a §2 violation: structure/state come solely from the JSONL tail.
+    return p.onData((chunk) => {
+        sink(chunk);
+    });
+}

package/dist/besteffort.d.ts

@@ -0,0 +1,44 @@
+import { type AgentSideConnection, type SessionNotification } from "@agentclientprotocol/sdk";
+import { type ContentBlockParam } from "@anthropic-ai/sdk/resources";
+import { BetaContentBlock, BetaRawContentBlockDelta } from "@anthropic-ai/sdk/resources/beta.mjs";
+import { toAcpNotifications, type Logger, type ToolUseCache } from "./acp-agent.js";
+/**
+ * Per-surface enable flags for the convenience translation. Each surface is gated independently so
+ * the orchestrator can, e.g., keep `plan` while suppressing `image` (or disable both entirely).
+ */
+export interface ConvenienceFlags {
+    /** Emit `plan` updates derived from `TodoWrite` tool_use blocks when true. */
+    plan: boolean;
+    /** Emit `image` content updates derived from `image` blocks when true. */
+    image: boolean;
+}
+/**
+ * A CONVENIENCE block is one whose translation produces a best-effort surface (NOT part of the core
+ * text/tool thread): an `image` content block, OR a `TodoWrite` tool_use (which routes to `plan`).
+ * Everything else (text, thinking, other tool_use, tool_result, …) is CORE.
+ */
+export declare function isConvenienceBlock(block: any): boolean;
+type ContentBlock = ContentBlockParam | BetaContentBlock | BetaRawContentBlockDelta;
+type TranslateFn = typeof toAcpNotifications;
+/**
+ * Translate `content` with the plan/image convenience surface gated behind a best-effort flag.
+ *
+ * CORE pass (always, never gated): the non-convenience blocks are translated via the REAL
+ * `toAcpNotifications` (`registerHooks: false` to stay synchronous, mirroring the §7 seam tests). A
+ * convenience failure can NEVER touch these updates — they are produced before the gated pass runs.
+ *
+ * CONVENIENCE pass (flag-gated + try/catch): only when at least one surface flag is on AND there is
+ * at least one convenience block, the convenience subset is translated (via the injectable
+ * `opts.translate`, default the real translator) inside a try/catch. Surviving updates are filtered
+ * to the enabled surfaces and appended after the core updates. On a thrown error OR an unusable
+ * (non-array) result, a drift note is logged via `logger.error(...)` and that surface is SKIPPED
+ * (nothing appended) — the error is NEVER rethrown, so the live thread is never broken.
+ *
+ * Signature mirrors `toAcpNotifications`'s real parameter list/types (acp-agent.ts:2866), with the
+ * required `flags` and the optional `opts.translate` test seam appended.
+ */
+export declare function translateBestEffort(content: string | ContentBlock[], role: "assistant" | "user", sessionId: string, cache: ToolUseCache, client: AgentSideConnection, logger: Logger, flags: ConvenienceFlags, opts?: {
+    translate?: TranslateFn;
+}): SessionNotification[];
+export {};
+//# sourceMappingURL=besteffort.d.ts.map

package/dist/besteffort.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"besteffort.d.ts","sourceRoot":"","sources":["../src/besteffort.ts"],"names":[],"mappings":"AA6BA,OAAO,EAAE,KAAK,mBAAmB,EAAE,KAAK,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC9F,OAAO,EAAE,KAAK,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AACrE,OAAO,EACL,gBAAgB,EAChB,wBAAwB,EACzB,MAAM,sCAAsC,CAAC;AAC9C,OAAO,EAAE,kBAAkB,EAAE,KAAK,MAAM,EAAE,KAAK,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEpF;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,8EAA8E;IAC9E,IAAI,EAAE,OAAO,CAAC;IACd,0EAA0E;IAC1E,KAAK,EAAE,OAAO,CAAC;CAChB;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,GAAG,GAAG,OAAO,CAKtD;AAED,KAAK,YAAY,GAAG,iBAAiB,GAAG,gBAAgB,GAAG,wBAAwB,CAAC;AACpF,KAAK,WAAW,GAAG,OAAO,kBAAkB,CAAC;AA8C7C;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,GAAG,YAAY,EAAE,EAChC,IAAI,EAAE,WAAW,GAAG,MAAM,EAC1B,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,YAAY,EACnB,MAAM,EAAE,mBAAmB,EAC3B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,gBAAgB,EACvB,IAAI,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,WAAW,CAAA;CAAE,GACjC,mBAAmB,EAAE,CA0CvB"}

package/dist/besteffort.js

@@ -0,0 +1,100 @@
+import { toAcpNotifications } from "./acp-agent.js";
+/**
+ * A CONVENIENCE block is one whose translation produces a best-effort surface (NOT part of the core
+ * text/tool thread): an `image` content block, OR a `TodoWrite` tool_use (which routes to `plan`).
+ * Everything else (text, thinking, other tool_use, tool_result, …) is CORE.
+ */
+export function isConvenienceBlock(block) {
+    return (block?.type === "image" ||
+        (block?.type === "tool_use" && block?.name === "TodoWrite"));
+}
+/**
+ * Split `content` into [core, convenience] block subsets using `isConvenienceBlock`. A non-array /
+ * string `content` (the bare-string `toAcpNotifications` fast-path) has no per-block convenience
+ * surface, so it is treated wholly as CORE (returned via the core subset, empty convenience subset).
+ */
+function partitionBlocks(content) {
+    if (typeof content === "string" || !Array.isArray(content)) {
+        return { core: content, convenience: [] };
+    }
+    const core = [];
+    const convenience = [];
+    for (const block of content) {
+        if (isConvenienceBlock(block)) {
+            convenience.push(block);
+        }
+        else {
+            core.push(block);
+        }
+    }
+    return { core, convenience };
+}
+/**
+ * Keep only the convenience updates whose surface flag is on. A `plan` update survives iff
+ * `flags.plan`; an `image`-content update survives iff `flags.image`. Anything else the convenience
+ * pass might emit is dropped (the convenience subset only ever contains image/TodoWrite blocks).
+ */
+function filterConvenienceUpdates(updates, flags) {
+    return updates.filter((n) => {
+        const update = n?.update;
+        if (update?.sessionUpdate === "plan") {
+            return flags.plan;
+        }
+        if (update?.content?.type === "image") {
+            return flags.image;
+        }
+        return false;
+    });
+}
+/**
+ * Translate `content` with the plan/image convenience surface gated behind a best-effort flag.
+ *
+ * CORE pass (always, never gated): the non-convenience blocks are translated via the REAL
+ * `toAcpNotifications` (`registerHooks: false` to stay synchronous, mirroring the §7 seam tests). A
+ * convenience failure can NEVER touch these updates — they are produced before the gated pass runs.
+ *
+ * CONVENIENCE pass (flag-gated + try/catch): only when at least one surface flag is on AND there is
+ * at least one convenience block, the convenience subset is translated (via the injectable
+ * `opts.translate`, default the real translator) inside a try/catch. Surviving updates are filtered
+ * to the enabled surfaces and appended after the core updates. On a thrown error OR an unusable
+ * (non-array) result, a drift note is logged via `logger.error(...)` and that surface is SKIPPED
+ * (nothing appended) — the error is NEVER rethrown, so the live thread is never broken.
+ *
+ * Signature mirrors `toAcpNotifications`'s real parameter list/types (acp-agent.ts:2866), with the
+ * required `flags` and the optional `opts.translate` test seam appended.
+ */
+export function translateBestEffort(content, role, sessionId, cache, client, logger, flags, opts) {
+    const { core, convenience } = partitionBlocks(content);
+    // CORE pass — ALWAYS the real translator, ALWAYS emitted. Outside any try/catch so a convenience
+    // failure provably cannot affect it.
+    const coreUpdates = toAcpNotifications(core, role, sessionId, cache, client, logger, {
+        registerHooks: false,
+    });
+    // CONVENIENCE pass — gated by the flags AND the presence of convenience blocks. Skipped entirely
+    // when both surfaces are off or there is nothing convenient to translate.
+    const anyFlagOn = flags.plan || flags.image;
+    if (!anyFlagOn || convenience.length === 0) {
+        return coreUpdates;
+    }
+    const translate = opts?.translate ?? toAcpNotifications;
+    try {
+        const raw = translate(convenience, role, sessionId, cache, client, logger, {
+            registerHooks: false,
+        });
+        // Guard against an unusable result (e.g. a stub returning undefined/non-array): treat as a
+        // best-effort miss rather than letting a downstream `.filter` throw.
+        if (!Array.isArray(raw)) {
+            logger.error(`[claude-agent-acp] best-effort convenience translation yielded an unusable (non-array) result for session ${sessionId}; skipping the plan/image surface`);
+            return coreUpdates;
+        }
+        const convenienceUpdates = filterConvenienceUpdates(raw, flags);
+        // Core first, then the enabled convenience surfaces appended (ordering trade-off above).
+        return [...coreUpdates, ...convenienceUpdates];
+    }
+    catch (err) {
+        // CONTAINMENT: a thrown convenience translation is caught here, logged as a drift note, and
+        // swallowed. The core stream (already computed) is returned intact — the turn/thread survives.
+        logger.error(`[claude-agent-acp] best-effort convenience translation threw for session ${sessionId}; skipping the plan/image surface (thread preserved): ${err instanceof Error ? err.message : String(err)}`);
+        return coreUpdates;
+    }
+}

package/dist/billing/entrypoint-guard.d.ts

@@ -0,0 +1,97 @@
+/**
+ * §10 SUBSCRIPTION set (OK) — client labels that bill on the Claude subscription.
+ * Source: doc §10, `claude` binary 2.1.159.
+ */
+export declare const SUBSCRIPTION_ENTRYPOINTS: readonly ["cli", "claude-vscode", "vscode", "jetbrains", "firstParty", "local-agent"];
+/**
+ * §10 CREDIT set (ABORT) — client labels that bill on API credit (Agent SDK / headless `-p`).
+ * Source: doc §10, `claude` binary 2.1.159.
+ */
+export declare const CREDIT_ENTRYPOINTS: readonly ["sdk-ts", "sdk-py", "sdk-cli", "print"];
+export type EntrypointClass = "subscription" | "credit" | "unknown";
+/**
+ * Classify a client-emitted `entrypoint` self-label into its §10 billing class.
+ *
+ * @param entrypoint the raw `entrypoint` value read from a message event.
+ * @returns `'subscription'` for any label in {@link SUBSCRIPTION_ENTRYPOINTS}; `'credit'` for any
+ *   label in {@link CREDIT_ENTRYPOINTS}; `'unknown'` for any other label (conservative — NEVER
+ *   classifies an unrecognized label as `'subscription'`).
+ */
+export declare function classifyEntrypoint(entrypoint: string): EntrypointClass;
+/**
+ * Structural shape of one watched message event. Mirrors the story-015 watcher's
+ * `SessionMessage` (`{ uuid?: string; [k: string]: unknown }`) plus the two fields this guard
+ * reads. Kept LOCAL & structural on purpose — importing `engine-watcher` would pull in node-pty
+ * and friends, and this module must stay light and pure.
+ */
+export interface WatchedMessage {
+    type?: string;
+    entrypoint?: string;
+    sessionId?: string;
+    [k: string]: unknown;
+}
+/**
+ * The decision {@link inspectEvent} returns for one watched event:
+ *   - `skip`  — a lightweight (non-message) type; nothing to classify.
+ *   - `allow` — an `assistant`/`user` event whose entrypoint is in the §10 SUBSCRIPTION set.
+ *   - `abort` — an `assistant`/`user` event whose entrypoint is credit OR unknown (incl. missing).
+ */
+export type GuardDecision = {
+    action: "skip";
+} | {
+    action: "allow";
+    entrypoint: string;
+    entrypointClass: "subscription";
+} | {
+    action: "abort";
+    entrypoint: string;
+    entrypointClass: "credit" | "unknown";
+};
+/**
+ * Pure decision for one watched message event (see module note). Does not mutate `event` and has
+ * no side effects.
+ *
+ * @param event one event delivered by the story-015 watcher.
+ * @returns `{ action: 'skip' }` for non-message (lightweight) types; otherwise an `allow`/`abort`
+ *   decision carrying the read `entrypoint` and its §10 class. A missing/empty `.entrypoint` on an
+ *   `assistant`/`user` event classifies as `'unknown'` → `abort` (never allowed).
+ */
+export declare function inspectEvent(event: WatchedMessage): GuardDecision;
+/**
+ * Side-effect sink injected into {@link guardEvent}. Kept as an interface (not real I/O) so the guard
+ * is pure w.r.t. globals and testable; story 023 wires these to the engine-lifecycle stop.
+ */
+export interface GuardHooks {
+    /** Loud, unambiguous alert sink. The message MUST carry the offending entrypoint value AND session id. */
+    alert(message: string): void;
+    /** Stop the session (wired to engine-lifecycle stop in story 023). Invoked once per violation. */
+    stopSession(info: {
+        entrypoint: string;
+        sessionId?: string;
+        entrypointClass: "credit" | "unknown";
+    }): void;
+}
+/**
+ * Apply {@link inspectEvent}'s decision for one watched event against the injected {@link GuardHooks}.
+ *
+ * @param event one event delivered by the story-015 watcher. NEVER mutated.
+ * @param hooks the alert/stop sink (the ONLY channel for side effects).
+ * @returns the same {@link GuardDecision} `inspectEvent` produced. On `'abort'` (credit OR unknown),
+ *   first {@link GuardHooks.alert | alerts} with a loud message carrying the offending entrypoint value
+ *   AND session id, then {@link GuardHooks.stopSession | stops the session}; on `'allow'`/`'skip'` it
+ *   returns with no side effect. Does NOT mutate, default, or overwrite `event.entrypoint` (§10).
+ */
+export declare function guardEvent(event: WatchedMessage, hooks: GuardHooks): GuardDecision;
+/**
+ * Fail-fast assertion that NO billing-sensitive env key survived into the env about to be passed to
+ * spawn (§10 post-condition for {@link buildSanitizedEnv}). Read-only: never deletes or mutates `env`.
+ *
+ * @param env the spawn env (process-env shape — values may be `undefined`).
+ * @throws {Error} if any key is present (value not `undefined`) that is exactly
+ *   `CLAUDE_CODE_ENTRYPOINT` OR starts with `CLAUDE_AGENT_SDK_`. The message NAMES every leaked key
+ *   and states the spawn must be refused (these would silently bill the run as API credit — R1, §10).
+ *   A key set to `undefined` is treated as absent (not a leak). `CLAUDECODE` is NOT checked here (it
+ *   is the spawn helper's anti-recusa concern, distinct from this billing check — §10).
+ */
+export declare function assertCleanBillingEnv(env: Record<string, string | undefined>): void;
+//# sourceMappingURL=entrypoint-guard.d.ts.map

package/dist/billing/entrypoint-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entrypoint-guard.d.ts","sourceRoot":"","sources":["../../src/billing/entrypoint-guard.ts"],"names":[],"mappings":"AAsCA;;;GAGG;AACH,eAAO,MAAM,wBAAwB,uFAO3B,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,kBAAkB,mDAKrB,CAAC;AAEX,MAAM,MAAM,eAAe,GAAG,cAAc,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEpE;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,eAAe,CAQtE;AAeD;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB;AAED;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GACrB;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,GAClB;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,eAAe,EAAE,cAAc,CAAA;CAAE,GACxE;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,eAAe,EAAE,QAAQ,GAAG,SAAS,CAAA;CAAE,CAAC;AAEnF;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,cAAc,GAAG,aAAa,CAUjE;AAkBD;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,0GAA0G;IAC1G,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,kGAAkG;IAClG,WAAW,CAAC,IAAI,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,eAAe,EAAE,QAAQ,GAAG,SAAS,CAAA;KAAE,GAAG,IAAI,CAAC;CAC5G;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,UAAU,GAAG,aAAa,CAkBlF;AAuBD;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GAAG,IAAI,CAenF"}

package/dist/billing/entrypoint-guard.js

@@ -0,0 +1,166 @@
+// Story 022 — entrypoint billing guard-rail.
+//
+// ── GOOD-FAITH LIMITS (this guard-rail is a SIGNAL, never a lever) ─────────────────────────────────
+// Sources: doc §10 "Auditoria de billing — entrypoint"; §0 TL;DR point 3; Appendix row
+// "`entrypoint` como prova de billing"; experiments/DEGRAU0-RESULTS.md (E1).
+//
+//   (a) `entrypoint` is a CLIENT SELF-LABEL, written verbatim from an env var without checking the
+//       real mode. It is a GOOD-FAITH SIGNAL — NOT contractual proof that the run billed on the Claude
+//       subscription, and NOT a contract published by Anthropic. Billing is decided server-side by the
+//       headers the client sends; we do not capture TLS, so this field corroborates, it does not prove.
+//   (b) This code NEVER forces or spoofs `entrypoint=cli`. It only READS and REACTS — rewriting the
+//       value toward 'cli' would be spoofing-with-enforcement (the OpenClaw case) = evasion. `guardEvent`
+//       leaves the observed value untouched and aborts on a credit-class label instead.
+//   (c) The subscription GUARANTEE comes from RUNNING THE REAL TUI with a sanitized env — the E1
+//       keystone (experiments/DEGRAU0-RESULTS.md: a clean-env PTY writes `entrypoint=='cli'`
+//       ORGANICALLY), with billing decided server-side. This guard-rail only DETECTS a drift into
+//       credit (sdk-*/print) after the fact; it must never manufacture the subscription posture.
+// ───────────────────────────────────────────────────────────────────────────────────────────────────
+//
+// Story 022 / Task 1.1 — subscription/credit taxonomy + classifier for the runtime
+// entrypoint billing guard-rail (doc §10 "Auditoria de billing — entrypoint").
+//
+// WHAT THIS IS: the centralized §10 taxonomy (two frozen label sets) plus `classifyEntrypoint`,
+// a PURE function mapping a client-emitted `entrypoint` self-label to a billing class:
+//   - SUBSCRIPTION (OK): the TUI / first-party clients that bill on the Claude subscription.
+//   - CREDIT (ABORT): the Agent SDK / headless `-p` clients that bill on API credit.
+//   - 'unknown': any label in NEITHER set. It MUST be treated conservatively by the caller
+//     (task 2.2) and MUST NEVER fall through to 'subscription' — an unrecognized or newly
+//     introduced label is not proof of subscription billing.
+//
+// WHY a centralized, version-noted constant (doc §10): the taxonomy was reverse-engineered from
+// the `claude` binary 2.1.159 and the `entrypoint` field is the client's own self-label (written
+// verbatim from an env var, not a published contract). It may drift between 2.1.x versions, so the
+// sets live in ONE place with the source version cited below — a binary bump shows up in review.
+//
+// SOURCE: doc §10 "Auditoria de billing — entrypoint", reverse-engineered from `claude` binary
+// 2.1.159. If the binary version changes, re-audit these two sets against the new binary.
+/**
+ * §10 SUBSCRIPTION set (OK) — client labels that bill on the Claude subscription.
+ * Source: doc §10, `claude` binary 2.1.159.
+ */
+export const SUBSCRIPTION_ENTRYPOINTS = [
+    "cli",
+    "claude-vscode",
+    "vscode",
+    "jetbrains",
+    "firstParty",
+    "local-agent",
+];
+/**
+ * §10 CREDIT set (ABORT) — client labels that bill on API credit (Agent SDK / headless `-p`).
+ * Source: doc §10, `claude` binary 2.1.159.
+ */
+export const CREDIT_ENTRYPOINTS = [
+    "sdk-ts",
+    "sdk-py",
+    "sdk-cli",
+    "print",
+];
+/**
+ * Classify a client-emitted `entrypoint` self-label into its §10 billing class.
+ *
+ * @param entrypoint the raw `entrypoint` value read from a message event.
+ * @returns `'subscription'` for any label in {@link SUBSCRIPTION_ENTRYPOINTS}; `'credit'` for any
+ *   label in {@link CREDIT_ENTRYPOINTS}; `'unknown'` for any other label (conservative — NEVER
+ *   classifies an unrecognized label as `'subscription'`).
+ */
+export function classifyEntrypoint(entrypoint) {
+    if (SUBSCRIPTION_ENTRYPOINTS.includes(entrypoint)) {
+        return "subscription";
+    }
+    if (CREDIT_ENTRYPOINTS.includes(entrypoint)) {
+        return "credit";
+    }
+    return "unknown";
+}
+/**
+ * Pure decision for one watched message event (see module note). Does not mutate `event` and has
+ * no side effects.
+ *
+ * @param event one event delivered by the story-015 watcher.
+ * @returns `{ action: 'skip' }` for non-message (lightweight) types; otherwise an `allow`/`abort`
+ *   decision carrying the read `entrypoint` and its §10 class. A missing/empty `.entrypoint` on an
+ *   `assistant`/`user` event classifies as `'unknown'` → `abort` (never allowed).
+ */
+export function inspectEvent(event) {
+    if (event.type !== "assistant" && event.type !== "user") {
+        return { action: "skip" };
+    }
+    const entrypoint = event.entrypoint ?? "";
+    const entrypointClass = classifyEntrypoint(entrypoint);
+    if (entrypointClass === "subscription") {
+        return { action: "allow", entrypoint, entrypointClass };
+    }
+    return { action: "abort", entrypoint, entrypointClass };
+}
+/**
+ * Apply {@link inspectEvent}'s decision for one watched event against the injected {@link GuardHooks}.
+ *
+ * @param event one event delivered by the story-015 watcher. NEVER mutated.
+ * @param hooks the alert/stop sink (the ONLY channel for side effects).
+ * @returns the same {@link GuardDecision} `inspectEvent` produced. On `'abort'` (credit OR unknown),
+ *   first {@link GuardHooks.alert | alerts} with a loud message carrying the offending entrypoint value
+ *   AND session id, then {@link GuardHooks.stopSession | stops the session}; on `'allow'`/`'skip'` it
+ *   returns with no side effect. Does NOT mutate, default, or overwrite `event.entrypoint` (§10).
+ */
+export function guardEvent(event, hooks) {
+    const decision = inspectEvent(event);
+    if (decision.action !== "abort") {
+        // 'allow' (subscription) and 'skip' (lightweight) continue with no side effect.
+        return decision;
+    }
+    const message = `[billing §10] BLOCKED ${decision.entrypointClass}-class entrypoint "${decision.entrypoint}" ` +
+        `on session "${event.sessionId ?? "(unknown)"}": this client bills on API credit, not the ` +
+        `Claude subscription. Stopping the session to avoid silent credit billing — the entrypoint is ` +
+        `NOT being rewritten (forcing it to 'cli' would be evasion).`;
+    hooks.alert(message);
+    hooks.stopSession({
+        entrypoint: decision.entrypoint,
+        sessionId: event.sessionId,
+        entrypointClass: decision.entrypointClass,
+    });
+    return decision;
+}
+// Task 3.1 — startup self-check: fail fast on leaked SDK env BEFORE spawn.
+//
+// `assertCleanBillingEnv` is the POST-CONDITION assertion for the spawn helper's env-sanitize
+// (`buildSanitizedEnv` in engine-pty.ts, which DELETES the billing-sensitive keys). It does NOT
+// delete-and-continue — deletion is the helper's job; this is the read-only check that it worked.
+// Inheriting any of these keys from the parent Node/ACP process would silently bill the spawned
+// TUI as API credit (R1, §10) BEFORE any message event is produced, so this must run BEFORE spawn.
+//
+// SCOPE (the billing subset of engine-pty's FORBIDDEN_BILLING_VARS): the exact key
+// `CLAUDE_CODE_ENTRYPOINT` plus the whole `CLAUDE_AGENT_SDK_*` family. The family is matched by
+// PREFIX (not an enumerated list) on purpose: it covers today's `CLAUDE_AGENT_SDK_VERSION` /
+// `CLAUDE_AGENT_SDK_CLIENT_APP` AND catches any future `CLAUDE_AGENT_SDK_*` sibling the helper's
+// fixed deletion list might miss.
+//
+// `CLAUDECODE` is deliberately NOT checked here. It IS one of engine-pty's FORBIDDEN_BILLING_VARS,
+// but it is the spawn helper's ANTI-RECUSA (anti-nesting) concern — it makes the nested `claude` TUI
+// refuse to start — which is distinct from this BILLING check (§10). Folding it in here would
+// conflate the two guard-rails, so it stays out of the collection logic.
+//
+// PURITY: read-only. Does NOT delete keys and does NOT mutate `env`.
+/**
+ * Fail-fast assertion that NO billing-sensitive env key survived into the env about to be passed to
+ * spawn (§10 post-condition for {@link buildSanitizedEnv}). Read-only: never deletes or mutates `env`.
+ *
+ * @param env the spawn env (process-env shape — values may be `undefined`).
+ * @throws {Error} if any key is present (value not `undefined`) that is exactly
+ *   `CLAUDE_CODE_ENTRYPOINT` OR starts with `CLAUDE_AGENT_SDK_`. The message NAMES every leaked key
+ *   and states the spawn must be refused (these would silently bill the run as API credit — R1, §10).
+ *   A key set to `undefined` is treated as absent (not a leak). `CLAUDECODE` is NOT checked here (it
+ *   is the spawn helper's anti-recusa concern, distinct from this billing check — §10).
+ */
+export function assertCleanBillingEnv(env) {
+    const leaked = Object.keys(env).filter((key) => env[key] !== undefined &&
+        (key === "CLAUDE_CODE_ENTRYPOINT" || key.startsWith("CLAUDE_AGENT_SDK_")));
+    if (leaked.length === 0) {
+        return;
+    }
+    throw new Error(`[billing §10] REFUSING TO SPAWN: ${leaked.length} billing-sensitive env key(s) leaked into the ` +
+        `spawn env: ${leaked.join(", ")}. These would silently bill the spawned TUI as API credit ` +
+        `(R1) instead of the Claude subscription. The spawn-env sanitize must strip them BEFORE spawn — ` +
+        `aborting rather than launch a credit-billed run.`);
+}

package/dist/claude-path.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Resolve an absolute path to an executable subscription `claude` binary.
+ *
+ * Resolution order:
+ *   1. `claude` found on `process.env.PATH` (which-style scan).
+ *   2. The documented native-binary path under the vscode extension.
+ *
+ * @returns absolute path to an executable `claude`.
+ * @throws Error naming both attempted locations if neither is executable.
+ */
+export declare function resolveClaudePath(): string;
+//# sourceMappingURL=claude-path.d.ts.map

package/dist/claude-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-path.d.ts","sourceRoot":"","sources":["../src/claude-path.ts"],"names":[],"mappings":"AAsCA;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAyB1C"}

package/dist/claude-path.js

@@ -0,0 +1,61 @@
+// Resolves the subscription `claude` binary from PATH (story 012, R1/R1.2).
+//
+// The fork must drive the user's *subscription* claude (resolved from PATH),
+// NOT the binary embedded in @anthropic-ai/claude-agent-sdk — the SDK-embedded
+// path bills as credit, while the PATH `claude` bills as signature
+// (`entrypoint == 'cli'`, the E1 keystone — experiments/DEGRAU0-RESULTS.md).
+// This helper is ported 1:1 from the E1-validated experiments/lib/claude-path.ts,
+// preserving its resolution order: PATH first, then the documented native-binary
+// fallback (IMPLEMENTACAO-FORK-ACP §17), else throw naming BOTH attempted
+// locations (R1.3).
+//
+// Dependency-free on purpose: only node: builtins (FORK.md pins node-pty + the
+// SDK as the only runtime deps; this adds none).
+import { accessSync, constants } from "node:fs";
+import { homedir } from "node:os";
+import { delimiter, join } from "node:path";
+// Documented native-binary fallback (IMPLEMENTACAO-FORK-ACP §17), for claude
+// 2.1.159 (frozen base doc anchor, §3). `~` is expanded via os.homedir.
+const FALLBACK_RELATIVE_PATH = join(".vscode", "extensions", "anthropic.claude-code-2.1.159-linux-x64", "resources", "native-binary", "claude");
+/** True if `p` exists and is executable by the current process. */
+function isExecutable(p) {
+    try {
+        accessSync(p, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Resolve an absolute path to an executable subscription `claude` binary.
+ *
+ * Resolution order:
+ *   1. `claude` found on `process.env.PATH` (which-style scan).
+ *   2. The documented native-binary path under the vscode extension.
+ *
+ * @returns absolute path to an executable `claude`.
+ * @throws Error naming both attempted locations if neither is executable.
+ */
+export function resolveClaudePath() {
+    // 1. PATH lookup: scan each PATH entry for an executable `claude`.
+    const pathEnv = process.env.PATH ?? "";
+    const pathEntries = pathEnv.split(delimiter).filter((entry) => entry.length > 0);
+    for (const entry of pathEntries) {
+        const candidate = join(entry, "claude");
+        if (isExecutable(candidate)) {
+            return candidate;
+        }
+    }
+    // 2. Documented native-binary fallback (~ expanded via os.homedir).
+    const fallback = join(homedir(), FALLBACK_RELATIVE_PATH);
+    if (isExecutable(fallback)) {
+        return fallback;
+    }
+    // 3. Neither exists: throw naming BOTH attempted locations.
+    throw new Error(`Could not resolve an executable "claude" binary. Tried: ` +
+        `(1) PATH lookup over ${pathEntries.length} entr${pathEntries.length === 1 ? "y" : "ies"} ` +
+        `("${pathEnv}"), and ` +
+        `(2) the documented native-binary fallback "${fallback}". ` +
+        `Install the Claude Code subscription CLI or ensure "claude" is on PATH.`);
+}

package/dist/diff-enriched-reader.d.ts

@@ -0,0 +1,41 @@
+import type { GetMessages } from "./engine-watcher.js";
+/**
+ * Build a `uuid → toolUseResult` index from raw JSONL transcript lines.
+ *
+ * Only records that ARE plain objects carrying BOTH a string `uuid` AND a defined `toolUseResult`
+ * enter the map — a record without a `toolUseResult` is intentionally absent so the matching message is
+ * returned unchanged (R1.2). Empty/whitespace lines and malformed JSON are skipped silently (robustness:
+ * a torn or partially-written final line must never throw and abort the hydration).
+ *
+ * @param rawLines the transcript's newline-split lines (READ-ONLY; never mutated).
+ * @returns a map from message uuid to its raw `toolUseResult` value (possibly empty).
+ */
+export declare function toolUseResultMap(rawLines: string[]): Map<string, unknown>;
+/** Construction options for {@link createDiffEnrichedReader} — both seams injectable for tests. */
+export interface DiffEnrichedReaderOptions {
+    /**
+     * Locate the session's transcript file(s). Defaults to the in-fork {@link defaultFindTranscript}
+     * (a billing-free recursive glob of `<sessionId>.jsonl` under `~/.claude/projects`). First match.
+     */
+    findTranscript?: (sessionId: string) => string[];
+    /**
+     * Read a transcript file into its newline-split lines. Defaults to a synchronous
+     * `readFileSync(path,'utf8').split('\n')`. Injected so tests can stub the raw read (and simulate an
+     * unreadable transcript for the R1.3 fallback) without touching the filesystem.
+     */
+    readRawLines?: (path: string) => string[];
+}
+/**
+ * Wrap a base `getSessionMessages`-shaped reader so each returned message gains its `toolUseResult`
+ * from the raw transcript, matched by `uuid`. This is PURE hydration: ordering and identity come from
+ * `base`; only the top-level `toolUseResult` key is added (exactly where the diff block reads it,
+ * `turn.message.toolUseResult`). Billing-free — the only extra cost is one `fs` read of the transcript
+ * located from the `sessionId` (R4.2). On ANY locate/read/parse failure, or when no record carries a
+ * `toolUseResult`, the plain reduced messages are returned unchanged (R1.3) and NO patch is fabricated.
+ *
+ * @param base the underlying reader (the SDK `getSessionMessages`, or an injected stub).
+ * @param opts injectable {@link DiffEnrichedReaderOptions} seams (defaults are production behaviour).
+ * @returns a {@link GetMessages} that yields the base messages with `toolUseResult` hydrated by uuid.
+ */
+export declare function createDiffEnrichedReader(base: GetMessages, opts?: DiffEnrichedReaderOptions): GetMessages;
+//# sourceMappingURL=diff-enriched-reader.d.ts.map