@quantiya/codevibe-core 2.0.8 → 2.0.10

package/dist/reviewer/token-usage.d.ts

@@ -1,14 +1,39 @@
 /**
- * [P2-0] Clamp an UNTYPED token field (from agent CLI JSON) to a finite,
- * non-negative INTEGER. Token fields come from untyped agent JSON — a string /
- * object / `NaN` / negative / fractional value would poison the per-task
- * accumulator (→ `NaN` render, or a reopened window showing a LOWER total),
- * violating the "token count is a number" invariant. Every numeric ingress
- * (`unwrapClaudeJson` usage reads, Codex `sumCodexTokens` per-event sum, the
- * QuorumLoop `addTaskTokens`) gates on this, so a malformed field contributes 0,
- * never corrupts the accumulator.
+ * [P2-0] Clamp an UNTYPED token field (from agent CLI JSON) to the same finite,
+ * bounded INTEGER contract the runtime persists. Token fields come from untyped
+ * agent JSON — a string / object / `NaN` / negative / fractional / over-contract
+ * value would poison the per-task accumulator or fabricate usage. Malformed
+ * fields contribute 0 to legacy additive counters and canonical snapshots mark
+ * reported invalid fields as `usage_invalid`.
  */
 export declare function finiteToken(n: unknown): number;
+export type InvocationUsageAvailability = 'complete' | 'partial' | 'unavailable';
+export interface InvocationUsageSnapshot {
+    /** Prompt/input tokens. `cachedInputTokens` is a subset, not an addend. */
+    inputTokens: number | null;
+    /** Output/completion tokens. */
+    outputTokens: number | null;
+    /** Cached input token subset when the provider exposes it. */
+    cachedInputTokens: number | null;
+    /** Backward-compatible aggregate: input + output, never cache-added. */
+    totalTokens: number | null;
+    /** End-to-end invocation elapsed time when known. */
+    elapsedMs: number | null;
+    availability: InvocationUsageAvailability;
+    /** Closed reason label when availability is unavailable/partial. */
+    unavailableReason: string | null;
+}
+export declare function tokenFieldAvailable(value: unknown): value is number;
+export declare function usageSnapshotFromParts(args: {
+    inputTokens: number;
+    outputTokens: number;
+    cachedInputTokens?: number;
+    elapsedMs?: number | null;
+    inputTokensAvailable?: boolean;
+    outputTokensAvailable?: boolean;
+    cachedInputTokensAvailable?: boolean;
+}): InvocationUsageSnapshot;
+export declare function unavailableUsageSnapshot(reason: string, elapsedMs?: number | null): InvocationUsageSnapshot;
 /**
  * Locate the FIRST balanced top-level `{...}` in `stdout` that parses to an object
  * with `type === 'result'` — Claude may emit non-JSON warning / MCP lines before
@@ -31,12 +56,16 @@ export declare function firstResultEnvelope(stdout: string): Record<string, unkn
  *   • `is_error === true` OR `result` not a non-empty string → `{ text:'', tokens:
  *     undefined }`. The CALLER treats an empty/failed result as an agent FAILURE
  *     (reviewer ESCALATE / resolver human-gate — same as today), NOT a silent pass.
- *   • else → `{ text: result, tokens: (finiteToken(usage.input_tokens) +
- *     finiteToken(usage.output_tokens)) || undefined }`. `finiteToken` clamps
- *     absent/malformed usage to 0 (no `TypeError`, no `NaN`); cache tokens are
- *     excluded in v1 (input+output only — see design "Known v1 limitation").
+ *   • else → `{ text: result, tokens: totalTokens || undefined }`. `finiteToken`
+ *     clamps absent/malformed usage to 0 (no `TypeError`, no `NaN`). Claude's
+ *     documented input total is uncached input plus cache-write/cache-read
+ *     buckets, while `cachedInputTokens` remains the cached subset. The older
+ *     `cached_input_tokens` alias is intentionally ignored unless backed by
+ *     documented Claude result-envelope evidence.
  */
+export declare function extractClaudeUsageSnapshot(stdout: string, elapsedMs?: number | null): InvocationUsageSnapshot;
 export declare function unwrapClaudeJson(stdout: string): {
     text: string;
     tokens?: number;
+    usage: InvocationUsageSnapshot;
 };

package/dist/reviewer/types.d.ts

@@ -1,3 +1,4 @@
+import type { InvocationUsageSnapshot } from './token-usage.js';
 /**
  * Agent kinds the reviewer subprocess layer can spawn.
  *
@@ -101,4 +102,6 @@ export interface ReviewerVerdict {
     latency_ms: number | null;
     /** ISO 8601 UTC timestamp string when the reviewer returned the verdict. */
     submitted_at: string;
+    /** Canonical input/output/cache/elapsed usage snapshot. Additive post-launch. */
+    usage?: InvocationUsageSnapshot;
 }

package/dist/substrate/__tests__/command-runner.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/substrate/types.d.ts

@@ -136,6 +136,14 @@ export interface SubstrateProc {
     readonly stdin: Writable | null;
     readonly stdout: Readable | null;
     readonly stderr: Readable | null;
+    /**
+     * The host command runner advertises this only when the returned process is
+     * itself wrapped by CodeVibe's authenticated POSIX process host. The Local
+     * Executor must then await that host's cleanup proof before retiring a
+     * workspace. Docker-backed substrate processes omit it because the
+     * container, rather than a host POSIX group, owns their lifecycle.
+     */
+    readonly hostProcessTreeOwnership?: "posix-host";
     kill(signal?: NodeJS.Signals): boolean;
     on(event: "close" | "error" | "exit", cb: (...a: unknown[]) => void): this;
 }

package/dist/tool-activity/consolidator.d.ts

@@ -48,6 +48,13 @@ export interface ToolActivityTransport {
  * undecryptable generation forever (a liveness/G2 failure on key rotation).
  */
 export declare function isSessionKeyStaleError(err: unknown): boolean;
+/**
+ * True only when the backend has proved that this session generation can never
+ * accept another event. These errors settle the durable window terminally;
+ * key rotation, contention, throttling, networking, and unknown failures remain
+ * retryable so recoverable tool activity is never discarded.
+ */
+export declare function isTerminalSessionError(err: unknown): boolean;
 export interface ToolActivityConsolidatorOptions {
     agent: string;
     /** The backend session id bound into each window's envelope (X2a routing). */

package/dist/tool-activity/ledger.d.ts

@@ -12,13 +12,13 @@ export declare const LedgerEntrySchema: z.ZodObject<{
      * rewind falls back to session start, which is still SAFE.
      */
     byteOffset: z.ZodNumber;
-    state: z.ZodEnum<["durably-outboxed", "acked"]>;
+    state: z.ZodEnum<["durably-outboxed", "acked", "terminal"]>;
 }, "strip", z.ZodTypeAny, {
-    state: "durably-outboxed" | "acked";
+    state: "terminal" | "durably-outboxed" | "acked";
     byteOffset: number;
     clientEventId: string;
 }, {
-    state: "durably-outboxed" | "acked";
+    state: "terminal" | "durably-outboxed" | "acked";
     byteOffset: number;
     clientEventId: string;
 }>;
@@ -36,30 +36,37 @@ export declare const LedgerFileSchema: z.ZodObject<{
          * rewind falls back to session start, which is still SAFE.
          */
         byteOffset: z.ZodNumber;
-        state: z.ZodEnum<["durably-outboxed", "acked"]>;
+        state: z.ZodEnum<["durably-outboxed", "acked", "terminal"]>;
     }, "strip", z.ZodTypeAny, {
-        state: "durably-outboxed" | "acked";
+        state: "terminal" | "durably-outboxed" | "acked";
         byteOffset: number;
         clientEventId: string;
     }, {
-        state: "durably-outboxed" | "acked";
+        state: "terminal" | "durably-outboxed" | "acked";
         byteOffset: number;
         clientEventId: string;
     }>>;
+    /**
+     * Permanently rejected outbox windows. Optional for backwards compatibility
+     * with version-1 ledgers written before per-window terminal authority existed.
+     */
+    terminalClientEventIds: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
 }, "strip", z.ZodTypeAny, {
     entries: Record<string, {
-        state: "durably-outboxed" | "acked";
+        state: "terminal" | "durably-outboxed" | "acked";
         byteOffset: number;
         clientEventId: string;
     }>;
     version: 1;
+    terminalClientEventIds: string[];
 }, {
     entries: Record<string, {
-        state: "durably-outboxed" | "acked";
+        state: "terminal" | "durably-outboxed" | "acked";
         byteOffset: number;
         clientEventId: string;
     }>;
     version: 1;
+    terminalClientEventIds?: string[] | undefined;
 }>;
 export type LedgerFile = z.infer<typeof LedgerFileSchema>;
 /**
@@ -111,7 +118,9 @@ export declare class ToolActivityLedger {
     private readonly logger;
     private readonly rootDir;
     private entries;
+    private terminalWindows;
     private loaded;
+    private mutationChain;
     constructor(opts: ToolActivityLedgerOptions);
     private filePath;
     private legacyOwnedFilePath;
@@ -133,7 +142,7 @@ export declare class ToolActivityLedger {
      * rebuildability) — used after a ledger loss so a still-pending window is not
      * re-observed as new. The outbox does not carry per-occurrence byteOffsets, so
      * they default to 0 (rewind falls back to the safe session-start bound).
-     * Never DOWNGRADES an existing `acked` entry.
+     * Never DOWNGRADES an existing `acked` or `terminal` entry.
      */
     rebuildFromOutbox(outboxEntries: ToolActivityOutboxEnvelope[]): void;
     /**
@@ -168,7 +177,9 @@ export declare class ToolActivityLedger {
      * (`entries`/`owned`) deferral is permanent, so the cursor advances freely.
      */
     isLegacyInFlight(id: string): boolean;
-    getState(id: string): 'durably-outboxed' | 'acked' | undefined;
+    getState(id: string): 'durably-outboxed' | 'acked' | 'terminal' | undefined;
+    /** True when a window has been durably settled as permanently undeliverable. */
+    isTerminalWindow(clientEventId: string): boolean;
     /**
      * Unique `clientEventId`s still in the `durably-outboxed` state (sealed, not yet
      * acked). The §4.5 N4 startup cross-check compares these against the surviving
@@ -192,6 +203,11 @@ export declare class ToolActivityLedger {
     markDurablyOutboxed(occurrences: OccurrenceRef[], clientEventId: string): Promise<void>;
     /** Mark every id of an acked window `acked` (retained for the pruning horizon). */
     markAcked(clientEventId: string): Promise<void>;
+    /**
+     * Mark every id of a permanently rejected window `terminal`. This must be
+     * persisted before its outbox file is pruned so restart cannot resend it.
+     */
+    markTerminal(clientEventId: string, invocationIds?: string[]): Promise<void>;
     /**
      * Crash-ordered repair step (2) (§4.5 V3/W2): DEMOTE/remove every mapping
      * referencing a quarantined or missing `clientEventId` so its occurrences are
@@ -265,10 +281,14 @@ export declare class ToolActivityLedger {
     /** Test/diagnostic: a snapshot of the in-memory legacy IN-FLIGHT id set. */
     legacyInFlightSnapshot(): string[];
     /**
-     * Bound ledger growth: drop `acked` entries whose source position is strictly
-     * BELOW a safe horizon (§4.5 — max(replay cursor, Stop turn-start)). Never
-     * prunes `durably-outboxed` (still pending an ack). Persists if anything changed.
+     * Bound ledger growth: drop settled (`acked` or `terminal`) entries whose
+     * source position is strictly BELOW a safe horizon (§4.5 — max(replay cursor,
+     * Stop turn-start)). Never prunes `durably-outboxed` or a terminal tombstone
+     * whose outbox file still exists: the latter may be an interrupted prune and
+     * must remain terminal across restart. Persists if anything changed.
      */
     prune(beforeByteOffset: number): Promise<void>;
+    private mutateAndPersist;
+    private outboxEntryExists;
     private persist;
 }

package/dist/track-presentation.d.ts

@@ -0,0 +1,2 @@
+/** Convert the zero-based wire/persistence track index to its user-facing number. */
+export declare function displayTrackNumber(trackIndex: number): number;

package/dist/track-presentation.test.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quantiya/codevibe-core",
-  "version": "2.0.8",
+  "version": "2.0.10",
   "description": "Core library for CodeVibe plugins - shared keychain, crypto, AppSync, and auth functionality",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",