@ossclip/core 0.1.0

package/src/producer/anthropic.ts

@@ -0,0 +1,73 @@
+import Anthropic from "@anthropic-ai/sdk";
+import { zodOutputFormat } from "@anthropic-ai/sdk/helpers/zod";
+import type { z } from "zod/v4";
+import type { LlmProvider } from "./provider";
+import type { LlmUsage } from "./usage";
+
+export const DEFAULT_CLAUDE_MODEL = "claude-opus-5";
+
+/**
+ * Claude via the official SDK with schema-constrained structured output.
+ * Auth: ANTHROPIC_API_KEY env (SDK default resolution).
+ */
+export class AnthropicProvider implements LlmProvider {
+  readonly name = "claude";
+  readonly usage: LlmUsage[] = [];
+  private client: Anthropic;
+
+  constructor(
+    private model: string = DEFAULT_CLAUDE_MODEL,
+    apiKey?: string,
+  ) {
+    this.client = new Anthropic(apiKey ? { apiKey } : {});
+  }
+
+  async complete<T>(req: {
+    system: string;
+    user: string;
+    schema: z.ZodType<T>;
+    schemaName: string;
+    maxTokens?: number;
+  }): Promise<T> {
+    const started = Date.now();
+    const response = await this.client.messages.parse({
+      model: this.model,
+      max_tokens: req.maxTokens ?? 16000,
+      system: req.system,
+      messages: [{ role: "user", content: req.user }],
+      output_config: { format: zodOutputFormat(req.schema) },
+    });
+    // Recorded before the failure checks: a refusal or a truncation still
+    // consumed tokens, and a run that fell over is exactly when the cost of
+    // getting there matters.
+    this.usage.push({
+      provider: this.name,
+      model: response.model ?? this.model,
+      schemaName: req.schemaName,
+      // The API reports cached tokens OUTSIDE `input_tokens`; ossclip's
+      // `inputTokens` means every input token however it was served, so they
+      // are folded in here and also reported separately for the discount note.
+      inputTokens:
+        response.usage.input_tokens +
+        (response.usage.cache_read_input_tokens ?? 0) +
+        (response.usage.cache_creation_input_tokens ?? 0),
+      outputTokens: response.usage.output_tokens,
+      cachedInputTokens:
+        (response.usage.cache_read_input_tokens ?? 0) +
+        (response.usage.cache_creation_input_tokens ?? 0),
+      exact: true,
+      billed: true,
+      ms: Date.now() - started,
+    });
+    if (response.stop_reason === "refusal") {
+      throw new Error(`claude declined the request (${response.stop_details?.category ?? "unspecified"})`);
+    }
+    if (response.stop_reason === "max_tokens") {
+      throw new Error("claude output truncated at max_tokens");
+    }
+    if (response.parsed_output == null) {
+      throw new Error("claude returned no parseable structured output");
+    }
+    return response.parsed_output as T;
+  }
+}

package/src/producer/beats.ts

@@ -0,0 +1,330 @@
+import { z } from "zod/v4";
+import type { Transcript } from "../schema";
+import { LayoutSchema, SceneComponentIdSchema } from "../scene-schema";
+import { SCENE_REGISTRY } from "../scene-registry";
+import { MAX_SCENE_SEC } from "../assemble";
+import { COVER_MAX_WORDS, coverHeadline } from "../cover";
+import type { LlmProvider } from "./provider";
+
+/** Call 1 — the editorial call (PHASE1 §4): moments, copy, component picks. */
+export const MomentSchema = z.object({
+  startWord: z.number().int().nonnegative(),
+  endWord: z.number().int().nonnegative(),
+  purpose: z.string().max(100),
+  /** Short on-screen copy for this beat — the fallback TitleCard title. */
+  onScreenCopy: z.string().max(60),
+  /** "none" = plain talking head with captions; otherwise a library component. */
+  sceneKind: z.union([SceneComponentIdSchema, z.literal("none")]),
+  /**
+   * Stage layout for this scene (PLAN Task B). Optional so an older cached
+   * beat sheet still parses; omitted means the component's registry default.
+   * Feasibility is enforced by `repairMomentLayouts` either way — the schema
+   * carries the request, the repair pass is the constraint (§35's lesson).
+   */
+  layout: LayoutSchema.optional().describe(
+    "stage layout for this scene; omit for the component default. NEVER a layout the framing brief marks UNAVAILABLE for these words",
+  ),
+  rationale: z.string().max(120).optional(),
+});
+export type Moment = z.infer<typeof MomentSchema>;
+
+export const BeatSheetSchema = z.object({
+  hook: z.string().max(120),
+  /**
+   * Banner text for the cover image (FINDINGS §31). Written here rather than
+   * by a second LLM call, because the producer is already choosing the hook —
+   * this is the same editorial judgement, shortened for a thumbnail.
+   */
+  coverText: z
+    .string()
+    .max(60)
+    .optional()
+    .describe(
+      `cover banner: at most ${COVER_MAX_WORDS} words, the hook compressed to a thumbnail headline`,
+    ),
+  moments: z.array(MomentSchema).min(1).max(12),
+});
+export type BeatSheet = z.infer<typeof BeatSheetSchema>;
+
+/**
+ * The `--clip` highlight request (R19 §93d): asked for IN THE SAME editorial
+ * call as the beat sheet — the producer is already reading the whole
+ * transcript and ranking moments, so the window costs approximately nothing
+ * here, and a second call would let two editorial judgements disagree.
+ */
+export const ClipHighlightSchema = z.object({
+  startWord: z.number().int().nonnegative(),
+  endWord: z.number().int().nonnegative(),
+  reason: z
+    .string()
+    .max(200)
+    .describe("one line: why THIS window is the strongest stretch of the take"),
+});
+export type ClipHighlight = z.infer<typeof ClipHighlightSchema>;
+
+export const ClipBeatSheetSchema = BeatSheetSchema.extend({
+  highlight: ClipHighlightSchema.describe(
+    "the single contiguous window to produce — every moment above must lie inside it",
+  ),
+});
+
+export const PRODUCER_SYSTEM = `You are the producer for a short-form vertical video (Reels/Shorts/TikTok). You receive a word-indexed transcript of a talking-head take that has already been cut. Your job is EDITORIAL: segment the take into moments, pick which moments deserve a graphic scene, and write the on-screen copy.
+
+Virality grammar — follow these as hard policies:
+- The first moment is the hook: the strongest claim or number anywhere in the take, on screen within 2 seconds.
+- A pattern interrupt every 3-6 seconds: alternate graphic moments with plain talking-head moments ("none").
+- On-screen copy is SHORT: numbers over adjectives, verbs over descriptions, never full sentences.
+- Use contrast/negation beats (StrikethroughReveal, RuleCard with struck alternatives) when the speaker rejects an idea.
+- End with a payoff or takeaway moment.
+- Moments must be contiguous-ish spans of the transcript, 5-10 seconds of speech each, in transcript order, non-overlapping.
+- COVERAGE: graphics should be on screen for roughly 40-50% of the runtime. Each graphic holds at most ~5 seconds, then hands the frame back — so MOST moments can carry one. Spread them evenly: never leave a stretch longer than ~10 seconds with no graphic.
+- VARIETY: never the same component twice in a row, and prefer a component you have NOT used yet in this video — reuse a treatment only when the beat genuinely calls for it. A repeat reads as a template.
+- Keep the face LARGE: prefer StatCard/RuleCard/ScreenshotFrame (they sit under a big face) over TitleCard (face becomes a small bubble); use FlowDiagram/TerminalMock sparingly — they remove the face entirely and only earn that when the graphic IS the point.
+- The transcript is ASR output and may contain mishearings: an unfamiliar proper noun is more likely a mistranscription of a common phrase than a real entity — write on-screen copy with the common-sense reading, never a suspected mishearing.
+- FRAMING: when the prompt carries a "Camera framing" brief, it is measured from the footage and is a HARD constraint: on words marked CLOSE, never choose a layout listed as UNAVAILABLE there — pick a \`layout\` that keeps the whole head in frame (pip-bubble, graphic-only, full-bleed) or leave the moment as "none". You may set \`layout\` on any moment; omit it to accept the component's default.
+- COVER: also write \`coverText\` — the hook compressed to a thumbnail headline, AT MOST ${COVER_MAX_WORDS} WORDS. It is read at a glance in a profile grid, so it must stand alone without the video: the claim or the number, no lead-in, no ellipsis.`;
+
+/**
+ * The `--clip` request, appended to the USER prompt (R19 §93d). The tuned
+ * PRODUCER_SYSTEM stays untouched — this adds the window request without
+ * rewriting the editorial instructions the beat sheet already follows.
+ */
+export function buildClipAddendum(targetSec: number): string {
+  return (
+    `\n\nCLIP SELECTION: the source is long-form, and only ONE window of roughly ` +
+    `${targetSec.toFixed(0)} seconds will be produced.\n` +
+    `1. First choose the strongest contiguous ~${targetSec.toFixed(0)}s of speech — the highlight: ` +
+    `self-contained, hook-worthy at its start, resolving by its end. Return it as \`highlight\` ` +
+    `(word range + a one-line reason).\n` +
+    `2. Prefer a window that starts at a sentence start and ends at a sentence end — a boundary ` +
+    `mid-sentence will be snapped to the nearest sentence afterwards.\n` +
+    `3. Then write the beat sheet AS IF the highlight were the whole take: the hook and EVERY ` +
+    `moment must lie inside the highlight's word range. Plan nothing outside it.`
+  );
+}
+
+export function buildBeatsUserPrompt(
+  transcript: Transcript,
+  duration: number,
+  intent: string | undefined,
+  framingBrief?: string,
+  clip?: { targetSec: number },
+  aspect?: "9:16" | "16:9",
+): string {
+  const words = transcript.words
+    .map((w, i) => `[${i}]${w.text}`)
+    .join(" ");
+  const menu = Object.entries(SCENE_REGISTRY)
+    .map(([id, meta]) => `- ${id}: ${meta.whenToUse}`)
+    .join("\n");
+  return (
+    `Intent: ${intent ?? "make this clear, punchy and viral-worthy"}\n` +
+    (clip
+      ? `Target clip length: ~${clip.targetSec.toFixed(0)}s (see CLIP SELECTION below)\n\n`
+      : `Output duration after the cut: ${duration.toFixed(1)}s\n\n`) +
+    // Landscape layout guidance (R21 §101): without it the first real 16:9
+    // run put nearly every graphic in a lower third. A deterministic variety
+    // pass downstream is the guarantee; this is the steer.
+    (aspect === "16:9"
+      ? `Output frame: LANDSCAPE 16:9. Vary the \`layout\` deliberately — lower-third, ` +
+        `split-left, split-right and blurred-behind are all available; never the same ` +
+        `layout twice in a row, and never a list/terminal/chat component in a lower-third ` +
+        `(the band is too shallow for a stack).\n\n`
+      : "") +
+    `Scene components available (sceneKind values; "none" = talking head only):\n${menu}\n\n` +
+    // The framing brief sits ABOVE the transcript so the constraint is read
+    // before the content it constrains (Task A).
+    (framingBrief ? `${framingBrief}\n\n` : "") +
+    `Word-indexed transcript (word indices refer to THIS list):\n${words}` +
+    (clip ? buildClipAddendum(clip.targetSec) : "")
+  );
+}
+
+export interface BeatsValidationIssue {
+  /** Index of the offending moment, or -1 for a sheet-wide issue. */
+  moment: number;
+  issue: string;
+}
+
+/** Fraction of the runtime that should show a graphic (FINDINGS §7). */
+export const GRAPHICS_COVERAGE_TARGET = 0.45;
+/**
+ * Below this runtime the percentage budget starves the video (FINDINGS §29):
+ * 45% of a 32s take is 14s, which at the 5s per-scene cap buys only three
+ * graphics — and short-form is exactly where density matters most. Under this
+ * threshold the scene COUNT floor wins over the percentage.
+ */
+export const SHORT_TAKE_SEC = 45;
+export const SHORT_TAKE_MIN_GRAPHICS = 4;
+
+/** A moment's approximate seconds of speech, from the transcript word stamps. */
+function momentDuration(m: Moment, transcript: Transcript): number {
+  const first = transcript.words[m.startWord];
+  const last = transcript.words[m.endWord];
+  return first && last ? Math.max(0, last.end - first.start) : 0;
+}
+
+function momentMidpoint(m: Moment, transcript: Transcript): number {
+  const first = transcript.words[m.startWord];
+  const last = transcript.words[m.endWord];
+  return first && last ? (first.start + last.end) / 2 : 0;
+}
+
+/** Semantic validation beyond the schema; repairs what it can, reports the rest. */
+export function normalizeBeatSheet(
+  sheet: BeatSheet,
+  transcript: Transcript,
+): { sheet: BeatSheet; issues: BeatsValidationIssue[] } {
+  const wordCount = transcript.words.length;
+  const issues: BeatsValidationIssue[] = [];
+  const moments: Moment[] = [];
+  const maxIndex = Math.max(0, wordCount - 1);
+  for (let i = 0; i < sheet.moments.length; i++) {
+    const m = { ...sheet.moments[i]! };
+    if (m.startWord > maxIndex) {
+      issues.push({ moment: i, issue: `startWord ${m.startWord} beyond transcript (${maxIndex})` });
+      continue;
+    }
+    m.endWord = Math.min(m.endWord, maxIndex);
+    if (m.endWord < m.startWord) {
+      issues.push({ moment: i, issue: "endWord before startWord" });
+      continue;
+    }
+    const prev = moments[moments.length - 1];
+    if (prev && m.startWord <= prev.endWord) {
+      const shifted = prev.endWord + 1;
+      if (shifted > m.endWord) {
+        issues.push({ moment: i, issue: "fully overlaps previous moment" });
+        continue;
+      }
+      issues.push({ moment: i, issue: `overlapped previous; startWord ${m.startWord} → ${shifted}` });
+      m.startWord = shifted;
+    }
+    moments.push(m);
+  }
+
+  // ---- Graphics scheduling (FINDINGS §7/§8/§9) -----------------------------
+  // One coverage budget in SECONDS instead of a moment-count cap, so the
+  // per-scene time cap and the demotion can't stack multiplicatively (§7).
+  // Demotion order is by clustering + same-kind adjacency, so survivors stay
+  // spread across the timeline (§8) and varied (§9); hook and payoff are
+  // always spared.
+  const surviving = () => moments.flatMap((m, i) => (m.sceneKind !== "none" ? [i] : []));
+  const estShow = (i: number) =>
+    Math.min(momentDuration(moments[i]!, transcript), MAX_SCENE_SEC);
+  const runtime =
+    transcript.words.length > 0
+      ? transcript.words[transcript.words.length - 1]!.end - transcript.words[0]!.start
+      : 0;
+  const budget = GRAPHICS_COVERAGE_TARGET * runtime;
+
+  const demote = (i: number, why: string) => {
+    issues.push({ moment: i, issue: `demoted ${moments[i]!.sceneKind} to "none" (${why})` });
+    moments[i] = { ...moments[i]!, sceneKind: "none" };
+  };
+
+  // On a short take the count floor outranks the percentage — never demote
+  // below it, whatever the coverage budget says (§29).
+  const minGraphics = runtime < SHORT_TAKE_SEC ? SHORT_TAKE_MIN_GRAPHICS : 0;
+
+  for (;;) {
+    const graphics = surviving();
+    const shown = graphics.reduce((acc, i) => acc + estShow(i), 0);
+    if (shown <= budget + 1e-6) break;
+    if (graphics.length <= minGraphics) {
+      issues.push({
+        moment: 0,
+        issue:
+          `short take (${runtime.toFixed(0)}s): keeping ${graphics.length} graphics ` +
+          `over the ${(GRAPHICS_COVERAGE_TARGET * 100).toFixed(0)}% budget`,
+      });
+      break;
+    }
+    // Hook and payoff stay. Among the rest, demote whichever removal opens
+    // the SMALLEST gap between its surviving neighbours — the survivors stay
+    // spread instead of the tail (or middle) getting hollowed out (§8).
+    // Same-kind neighbours make a candidate maximally demotable (§9).
+    const candidates = graphics.slice(1, -1);
+    if (candidates.length === 0) break;
+    let pick = candidates[0]!;
+    let pickCost = Infinity;
+    for (const i of candidates) {
+      const pos = graphics.indexOf(i);
+      const prev = moments[graphics[pos - 1]!]!;
+      const next = moments[graphics[pos + 1]!]!;
+      const openedGap =
+        momentMidpoint(next, transcript) - momentMidpoint(prev, transcript);
+      const sameKind =
+        prev.sceneKind === moments[i]!.sceneKind || next.sceneKind === moments[i]!.sceneKind;
+      const cost = openedGap - (sameKind ? 1e6 : 0);
+      if (cost < pickCost) {
+        pickCost = cost;
+        pick = i;
+      }
+    }
+    demote(pick, `coverage ${(GRAPHICS_COVERAGE_TARGET * 100).toFixed(0)}%`);
+  }
+
+  // Variety pass independent of budget (§9): adjacent survivors must differ in
+  // kind — demote the later of a same-kind pair (the earlier if the later is
+  // the payoff; never the hook).
+  for (;;) {
+    const graphics = surviving();
+    if (graphics.length <= minGraphics) break; // §29 floor outranks variety too
+    const pair = graphics.findIndex(
+      (idx, p) => p > 0 && moments[idx]!.sceneKind === moments[graphics[p - 1]!]!.sceneKind,
+    );
+    if (pair === -1) break;
+    const later = graphics[pair]!;
+    const earlier = graphics[pair - 1]!;
+    const isPayoff = pair === graphics.length - 1;
+    const target = isPayoff ? (pair - 1 === 0 ? -1 : earlier) : later;
+    if (target === -1) break; // both hook and payoff — leave the repeat alone
+    demote(target, `duplicate adjacent ${moments[target]!.sceneKind}`);
+  }
+
+  // The cover banner (FINDINGS §35). Two things went wrong at once: this
+  // function used to drop `coverText` on the floor, so the CLI fell back to
+  // the full hook — and nothing enforced the nine-word cap the prompt asks
+  // for. Both are fixed here, where every path to a beat sheet passes.
+  const requested = sheet.coverText?.trim() || sheet.hook;
+  const coverText = coverHeadline(requested);
+  if (coverText !== requested) {
+    issues.push({ moment: -1, issue: `coverText shortened to "${coverText}"` });
+  }
+
+  return { sheet: { hook: sheet.hook, coverText, moments }, issues };
+}
+
+export async function generateBeatSheet(
+  provider: LlmProvider,
+  transcript: Transcript,
+  duration: number,
+  intent: string | undefined,
+  speaker?: string,
+  framingBrief?: string,
+  clip?: { targetSec: number },
+  aspect?: "9:16" | "16:9",
+): Promise<{ sheet: BeatSheet; issues: BeatsValidationIssue[]; highlight?: ClipHighlight }> {
+  const user =
+    (speaker ? `The speaker: ${speaker}\n\n` : "") +
+    buildBeatsUserPrompt(transcript, duration, intent, framingBrief, clip, aspect);
+  if (clip) {
+    // Same editorial call, extended schema (R19 §93d) — the highlight and the
+    // beat sheet come from ONE judgement, so they cannot disagree.
+    const raw = await provider.complete({
+      system: PRODUCER_SYSTEM,
+      user,
+      schema: ClipBeatSheetSchema,
+      schemaName: "clip_beat_sheet",
+    });
+    return { ...normalizeBeatSheet(raw, transcript), highlight: raw.highlight };
+  }
+  const raw = await provider.complete({
+    system: PRODUCER_SYSTEM,
+    user,
+    schema: BeatSheetSchema,
+    schemaName: "beat_sheet",
+  });
+  return normalizeBeatSheet(raw, transcript);
+}

package/src/producer/claude-cli.ts

@@ -0,0 +1,150 @@
+import { z } from "zod/v4";
+import { run } from "../exec";
+import type { LlmProvider } from "./provider";
+import { estimateTokens, type LlmUsage } from "./usage";
+
+/**
+ * Claude via the locally installed Claude Code CLI (`claude -p`) instead of
+ * the metered API. Uses whatever auth the CLI holds — for Pro/Max subscribers
+ * that's the subscription, so producing a video consumes plan usage rather
+ * than pay-per-token API credits.
+ *
+ * Unlike the API path there is no server-enforced structured output, so the
+ * schema is stated in the prompt and enforced here with zod, with one
+ * self-repair retry before throwing (the caller adds its own fallback on top).
+ *
+ * Requirements: `claude` on PATH (or OSSCLIP_CLAUDE_BIN) and a logged-in
+ * Claude Code (`claude` → /login). Each call pays ~1-2s of CLI startup.
+ */
+export class ClaudeCliProvider implements LlmProvider {
+  readonly name = "claude-cli";
+  readonly usage: LlmUsage[] = [];
+
+  constructor(
+    private model?: string,
+    private bin: string = process.env.OSSCLIP_CLAUDE_BIN ?? "claude",
+  ) {}
+
+  async complete<T>(req: {
+    system: string;
+    user: string;
+    schema: z.ZodType<T>;
+    schemaName: string;
+  }): Promise<T> {
+    const schemaText = JSON.stringify(z.toJSONSchema(req.schema));
+    const base =
+      `${req.system}\n\n${req.user}\n\n` +
+      `Respond with ONLY a JSON object valid against this JSON Schema ("${req.schemaName}"). ` +
+      `No markdown fences, no commentary, no tool use — just the JSON:\n${schemaText}`;
+
+    let lastError = "";
+    for (let attempt = 0; attempt < 2; attempt++) {
+      const prompt =
+        attempt === 0
+          ? base
+          : `${base}\n\nYour previous reply failed validation:\n${lastError}\nReturn ONLY the corrected JSON.`;
+      const args = ["-p", "--output-format", "json", "--max-turns", "1"];
+      if (this.model) args.push("--model", this.model);
+      const started = Date.now();
+      let stdout = "";
+      try {
+        ({ stdout } = await run(this.bin, args, { stdin: prompt }));
+      } catch (err) {
+        lastError = err instanceof Error ? err.message : String(err);
+        continue;
+      }
+      // Recorded per ATTEMPT, before validation: a reply that failed the
+      // schema still spent the tokens, and a retry is exactly the cost a user
+      // would want to see rather than have quietly absorbed.
+      const envelope = parseCliEnvelope(stdout);
+      this.usage.push({
+        provider: this.name,
+        model: envelope.model ?? this.model,
+        schemaName: req.schemaName,
+        inputTokens: envelope.inputTokens ?? estimateTokens(prompt),
+        outputTokens: envelope.outputTokens ?? estimateTokens(envelope.result ?? stdout),
+        cachedInputTokens: envelope.cachedInputTokens,
+        reportedCostUsd: envelope.costUsd,
+        exact: envelope.inputTokens !== undefined,
+        // The whole point of this provider: Pro/Max auth means the plan pays,
+        // not a card. The cost is still reported, as what the same tokens
+        // would have cost on the API.
+        billed: false,
+        ms: Date.now() - started,
+      });
+      try {
+        return req.schema.parse(JSON.parse(extractJsonObject(unwrapCliEnvelope(stdout))));
+      } catch (err) {
+        lastError = err instanceof Error ? err.message : String(err);
+      }
+    }
+    throw new Error(
+      `claude CLI ('${this.bin}') did not produce valid ${req.schemaName} JSON: ${lastError.slice(0, 400)}\n` +
+        `Is Claude Code installed and logged in? (npm i -g @anthropic-ai/claude-code; run 'claude' once to /login)`,
+    );
+  }
+}
+
+/**
+ * The accounting half of the same envelope: tokens, cost and model, all
+ * optional because the CLI's envelope shape is not ours to depend on. Every
+ * field absent is a valid outcome — the caller falls back to estimates and
+ * says so — so this never throws on a shape it doesn't recognise.
+ */
+export function parseCliEnvelope(stdout: string): {
+  result?: string;
+  model?: string;
+  inputTokens?: number;
+  outputTokens?: number;
+  cachedInputTokens?: number;
+  costUsd?: number;
+} {
+  let env: Record<string, unknown>;
+  try {
+    env = JSON.parse(stdout.trim()) as Record<string, unknown>;
+  } catch {
+    return {};
+  }
+  if (!env || typeof env !== "object") return {};
+  const num = (v: unknown): number | undefined => (typeof v === "number" ? v : undefined);
+  const u = (env.usage ?? {}) as Record<string, unknown>;
+  const cacheRead = num(u.cache_read_input_tokens) ?? 0;
+  const cacheWrite = num(u.cache_creation_input_tokens) ?? 0;
+  const plainInput = num(u.input_tokens);
+  // `modelUsage` is keyed by the model id actually served — more reliable than
+  // the alias passed in with --model ("opus" resolves to a dated id).
+  const modelUsage = (env.modelUsage ?? {}) as Record<string, unknown>;
+  return {
+    result: typeof env.result === "string" ? env.result : undefined,
+    model: Object.keys(modelUsage)[0],
+    inputTokens: plainInput === undefined ? undefined : plainInput + cacheRead + cacheWrite,
+    outputTokens: num(u.output_tokens),
+    cachedInputTokens: cacheRead + cacheWrite || undefined,
+    costUsd: num(env.total_cost_usd),
+  };
+}
+
+/** `claude -p --output-format json` wraps the reply in a result envelope. */
+export function unwrapCliEnvelope(stdout: string): string {
+  const trimmed = stdout.trim();
+  try {
+    const envelope = JSON.parse(trimmed) as { result?: unknown; is_error?: boolean };
+    if (envelope && typeof envelope.result === "string") {
+      if (envelope.is_error) throw new Error(`claude CLI errored: ${envelope.result.slice(0, 300)}`);
+      return envelope.result;
+    }
+  } catch (err) {
+    if (err instanceof Error && err.message.startsWith("claude CLI errored")) throw err;
+    // Not an envelope — fall through and treat stdout as the reply itself.
+  }
+  return trimmed;
+}
+
+/** Tolerate markdown fences / prose around the JSON object. */
+export function extractJsonObject(text: string): string {
+  const unfenced = text.replace(/```(?:json)?/g, "");
+  const start = unfenced.indexOf("{");
+  const end = unfenced.lastIndexOf("}");
+  if (start === -1 || end <= start) throw new Error(`no JSON object in reply: ${text.slice(0, 200)}`);
+  return unfenced.slice(start, end + 1);
+}