@ossclip/core 0.1.15 → 0.1.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ossclip/core",
-  "version": "0.1.15",
+  "version": "0.1.17",
   "description": "ossclip's framework-free pipeline: schema, transcription, analysis, cutlist, captions, framing, and the LLM producer",
   "type": "module",
   "license": "MIT",

package/src/blooper.ts

@@ -92,12 +92,25 @@ function matchMarker(wordText: string, want: string): MarkerMatch | null {
   if (!norm) return null;
   if (norm === want) return { surface: norm, exact: true };
   if (want.length < FUZZY_MIN_MARKER_LEN) return null;
+  // A plain English inflection of the marker is a REAL word the speaker can
+  // say on purpose — "it removes the bloopers", describing the feature, sits
+  // at distance 1 from a "blooper" marker and the fuzzy arm cut 7.08s of a
+  // good announce take back to its sentence start (FINDINGS §133). Fuzzy
+  // exists for ASR mishearings of the SPOKEN marker; an inflection is far
+  // more likely content, so it stays exact-only, in both directions.
+  if (isPluralPair(norm, want)) return null;
   if (levenshtein(norm, want) <= FUZZY_MAX_DISTANCE) {
     return { surface: norm, exact: false };
   }
   return null;
 }
 
+/** Whether one token is the plain s/es plural of the other. */
+function isPluralPair(a: string, b: string): boolean {
+  const [short, long] = a.length <= b.length ? [a, b] : [b, a];
+  return long === `${short}s` || long === `${short}es`;
+}
+
 /**
  * Spans the speaker marked as bloopers.
  *

package/src/producer/antigravity.ts

@@ -0,0 +1,220 @@
+import { z } from "zod/v4";
+import { run } from "../exec";
+import type { LlmProvider } from "./provider";
+import { estimateTokens, type LlmUsage } from "./usage";
+// Shared fence-stripper for replies that wrap the JSON in prose/markdown.
+// A formatting concern, not a Claude dependency (FINDINGS §132, antigravity
+// provider).
+import { extractJsonObject } from "./claude-cli";
+
+/**
+ * agy's own print timeout defaults to 5m, which a beat-sheet call on a long
+ * transcript can exceed. Core's `run()` has no timeout of its own, so this
+ * flag is the ONLY clock on the spawn — without it a stuck call is a hang,
+ * with it a timeout surfaces as retry-then-throw (FINDINGS §132, antigravity
+ * provider).
+ */
+export const AGY_PRINT_TIMEOUT = "10m";
+
+/**
+ * agy takes the prompt as an argv argument only — no stdin — and macOS caps
+ * ARG_MAX around 1MB. Refuse before the OS does: a pre-spawn check turns
+ * E2BIG into a directed error naming providers that can take the prompt
+ * (FINDINGS §132, antigravity provider).
+ */
+export const MAX_AGY_PROMPT_BYTES = 700_000;
+
+/**
+ * The argv for one `agy` print-mode call. Pure so the flag set is testable
+ * without spawning anything. `--disable-slash-commands` because a transcript
+ * prompt that happens to start with `/` must not expand as a skill.
+ */
+export function buildAgyArgs(
+  prompt: string,
+  opts: { model?: string; schemaJson: string },
+): string[] {
+  return [
+    "-p",
+    prompt,
+    "--output-format",
+    "json",
+    "--disable-slash-commands",
+    "--json-schema",
+    opts.schemaJson,
+    "--print-timeout",
+    AGY_PRINT_TIMEOUT,
+    ...(opts.model ? ["--model", opts.model] : []),
+  ];
+}
+
+/**
+ * The agy JSON envelope, tolerated rather than trusted: 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 (same contract as
+ * `parseCliEnvelope`).
+ *
+ * Token mapping into `LlmUsage` terms:
+ *   - `outputTokens` folds `thinking_tokens` in: thinking is output-side
+ *     spend and LlmUsage has no thinking field of its own.
+ *   - Whether `input_tokens` already includes cache reads is not documented,
+ *     so it is cross-checked against `total_tokens`: if
+ *     input + output + thinking + cache_read exceeds the total, input is
+ *     already cache-inclusive and stands alone; otherwise cache reads are
+ *     added. Worst case is a conservative over-count — the safe direction
+ *     for a number a user might budget against (FINDINGS §132, antigravity
+ *     provider).
+ */
+export function parseAgyEnvelope(stdout: string): {
+  status?: string;
+  response?: string;
+  error?: string;
+  structuredOutput?: unknown;
+  inputTokens?: number;
+  outputTokens?: number;
+  cachedInputTokens?: 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 str = (v: unknown): string | undefined => (typeof v === "string" ? v : undefined);
+  const u = (env.usage ?? {}) as Record<string, unknown>;
+  const input = num(u.input_tokens);
+  const output = num(u.output_tokens);
+  const thinking = num(u.thinking_tokens) ?? 0;
+  const cacheRead = num(u.cache_read_tokens) ?? 0;
+  const total = num(u.total_tokens);
+  const cacheInclusive =
+    input !== undefined && total !== undefined
+      ? input + (output ?? 0) + thinking + cacheRead > total
+      : false;
+  return {
+    status: str(env.status),
+    response: str(env.response),
+    error: str(env.error),
+    structuredOutput: env.structured_output,
+    inputTokens: input === undefined ? undefined : cacheInclusive ? input : input + cacheRead,
+    outputTokens: output === undefined ? undefined : output + thinking,
+    cachedInputTokens: cacheRead || undefined,
+  };
+}
+
+/**
+ * Failures a retry cannot fix: missing auth and a bad model slug are
+ * deterministic, and each retry burns another ~24k-token baseline call (agy's
+ * own agent context) for nothing (FINDINGS §132, antigravity provider).
+ */
+export function isNonRetryableAgyFailure(message: string): boolean {
+  return /authentication|not logged in|login|unknown model|invalid model/i.test(message);
+}
+
+/**
+ * Google Antigravity via the locally installed `agy` CLI. Uses whatever auth
+ * the CLI holds — a logged-in subscription, so producing a video consumes
+ * plan usage rather than pay-per-token API credits (`billed: false`, and agy
+ * reports no cost of its own).
+ *
+ * The schema rides twice: `--json-schema` for server-side enforcement AND
+ * stated in the prompt — the prompt copy is what makes the self-repair retry
+ * meaningful, and server enforcement is not our contract, so the reply is
+ * still zod-validated here.
+ *
+ * Requirements: `agy` on PATH (or OSSCLIP_AGY_BIN) and a prior interactive
+ * sign-in. The envelope carries no model id, so usage records the requested
+ * model or "antigravity-default" (FINDINGS §132, antigravity provider).
+ */
+export class AntigravityProvider implements LlmProvider {
+  readonly name = "antigravity";
+  readonly usage: LlmUsage[] = [];
+
+  constructor(
+    private model?: string,
+    private bin: string = process.env.OSSCLIP_AGY_BIN ?? "agy",
+  ) {}
+
+  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 promptBytes = Buffer.byteLength(prompt, "utf8");
+      if (promptBytes > MAX_AGY_PROMPT_BYTES) {
+        throw new Error(
+          `prompt is ${promptBytes.toLocaleString("en-US")} bytes, over the ${MAX_AGY_PROMPT_BYTES.toLocaleString("en-US")}-byte limit for agy — ` +
+            `it accepts the prompt only as a command-line argument. ` +
+            `Use --llm claude-cli or --llm gemini for a take this long.`,
+        );
+      }
+      const started = Date.now();
+      let stdout = "";
+      try {
+        ({ stdout } = await run(
+          this.bin,
+          buildAgyArgs(prompt, { model: this.model, schemaJson: schemaText }),
+        ));
+      } catch (err) {
+        lastError = err instanceof Error ? err.message : String(err);
+        // run() embeds the stderr tail in its rejection, so auth/bad-slug
+        // failures are matchable here and fail fast instead of re-spending.
+        if (isNonRetryableAgyFailure(lastError)) break;
+        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 = parseAgyEnvelope(stdout);
+      this.usage.push({
+        provider: this.name,
+        // The envelope names no model, so record what was asked for — or the
+        // honest placeholder, which the cost report declines to price.
+        model: this.model ?? "antigravity-default",
+        schemaName: req.schemaName,
+        inputTokens: envelope.inputTokens ?? estimateTokens(prompt),
+        outputTokens: envelope.outputTokens ?? estimateTokens(envelope.response ?? stdout),
+        cachedInputTokens: envelope.cachedInputTokens,
+        exact: envelope.inputTokens !== undefined,
+        // The whole point of this provider: agy's cached sign-in means the
+        // subscription pays, not a card, and agy reports no cost to forward.
+        billed: false,
+        ms: Date.now() - started,
+      });
+      if (envelope.status !== "SUCCESS") {
+        lastError =
+          envelope.error ?? `agy reported status ${envelope.status ?? "unknown"}: ${stdout.slice(0, 300)}`;
+        if (isNonRetryableAgyFailure(lastError)) break;
+        continue;
+      }
+      try {
+        // Prefer the server-parsed object, but still validate it — schema
+        // enforcement on their side is not a contract on ours.
+        if (envelope.structuredOutput !== undefined) {
+          return req.schema.parse(envelope.structuredOutput);
+        }
+        return req.schema.parse(JSON.parse(extractJsonObject(envelope.response ?? stdout)));
+      } catch (err) {
+        lastError = err instanceof Error ? err.message : String(err);
+      }
+    }
+    throw new Error(
+      `agy CLI ('${this.bin}') did not produce valid ${req.schemaName} JSON: ${lastError.slice(0, 400)}\n` +
+        `Is Antigravity installed and logged in? (https://antigravity.google — run 'agy' once interactively to sign in)`,
+    );
+  }
+}

package/src/producer/index.ts

@@ -2,6 +2,7 @@ import type { Transcript } from "../schema";
 import type { Scene, SceneComponentId } from "../scene-schema";
 import type { LlmProvider, ProviderName } from "./provider";
 import { AnthropicProvider, DEFAULT_CLAUDE_MODEL } from "./anthropic";
+import { AntigravityProvider } from "./antigravity";
 import { ClaudeCliProvider } from "./claude-cli";
 import { GeminiProvider, DEFAULT_GEMINI_MODEL } from "./gemini";
 import { MockProvider } from "./mock";
@@ -27,6 +28,7 @@ export * from "./beats";
 export * from "./scene-props";
 export * from "./repair";
 export { AnthropicProvider, DEFAULT_CLAUDE_MODEL } from "./anthropic";
+export { AntigravityProvider } from "./antigravity";
 export { ClaudeCliProvider } from "./claude-cli";
 export { GeminiProvider, DEFAULT_GEMINI_MODEL } from "./gemini";
 export { MockProvider } from "./mock";
@@ -41,6 +43,11 @@ export function createProvider(name: ProviderName, model?: string): LlmProvider
       return new ClaudeCliProvider(model);
     case "gemini":
       return new GeminiProvider(model ?? DEFAULT_GEMINI_MODEL);
+    case "antigravity":
+      // Rides agy's cached subscription sign-in. No default model on purpose:
+      // the editorial tier runs whatever the user configured agy itself to
+      // use (FINDINGS §132, antigravity provider).
+      return new AntigravityProvider(model);
     case "mock":
       return new MockProvider();
   }
@@ -57,6 +64,11 @@ export const DEFAULT_FAST_MODEL: Partial<Record<ProviderName, string>> = {
   claude: "claude-haiku-4-5-20251001",
   "claude-cli": "claude-haiku-4-5-20251001",
   gemini: "gemini-3.5-flash-lite",
+  // Substring-matches the `gemini-3.6-flash` pricing family, so mechanical
+  // calls price from the existing table with no changes; the editorial tier
+  // (agy's own default, reported as "antigravity-default") matches nothing and
+  // reports "cost unknown" — the house honesty rule, not an oversight.
+  antigravity: "gemini-3.6-flash-low",
 };
 
 export interface TieringOptions {
@@ -87,17 +99,33 @@ export function createTieredProvider(
 /**
  * Default provider when --llm isn't given, in preference order.
  *
- * Gemini leads on measured evidence, not vendor preference: on the same clip
- * it ran 3,540 input tokens against the Claude CLI's 83,378 — the CLI re-sends
- * its whole harness prefix per invocation — for ~$0.05 against ~$0.85 and 27s
- * against 171s, with editorial output that held up. Both models recovered the
- * mishearing that matters ("coach and" → "code churn"); Claude is stronger only
- * at recovering a mangled PROPER NOUN, which `--speaker` addresses directly.
+ * Subscription CLIs beat ambient env keys (2026-08 decision, FINDINGS §132,
+ * antigravity provider): a logged-in `agy` or `claude` is an explicit,
+ * already-paid choice the user made on this machine, while an API key in the
+ * environment may just be lying around — and picking the key spends real
+ * per-token money the subscription would have covered. agy carries the same
+ * ~24k-token harness baseline per call that claude-cli does, but it is
+ * subscription-covered, so the weight costs nothing.
  *
- * Falling back to the Claude Code CLI last keeps the no-keys-configured path
- * working on a Pro/Max subscription rather than failing.
+ * Among the keys, Gemini leads on measured evidence, not vendor preference: on
+ * the same clip it ran 3,540 input tokens against the Claude CLI's 83,378 —
+ * the CLI re-sends its whole harness prefix per invocation — for ~$0.05
+ * against ~$0.85 and 27s against 171s, with editorial output that held up.
+ * Both models recovered the mishearing that matters ("coach and" → "code
+ * churn"); Claude is stronger only at recovering a mangled PROPER NOUN, which
+ * `--speaker` addresses directly.
+ *
+ * Falling back to the Claude Code CLI last keeps the nothing-configured path
+ * failing with install guidance rather than silence. The `hasBin` default of
+ * `() => false` keeps this pure — callers that can see a filesystem (the CLI)
+ * inject a real checker; everyone else gets the key-order behavior unchanged.
  */
-export function defaultProviderName(env: NodeJS.ProcessEnv = process.env): ProviderName {
+export function defaultProviderName(
+  env: NodeJS.ProcessEnv = process.env,
+  hasBin: (bin: string) => boolean = () => false,
+): ProviderName {
+  if (hasBin(env.OSSCLIP_AGY_BIN ?? "agy")) return "antigravity";
+  if (hasBin(env.OSSCLIP_CLAUDE_BIN ?? "claude")) return "claude-cli";
   if (env.GEMINI_API_KEY) return "gemini";
   if (env.ANTHROPIC_API_KEY) return "claude";
   return "claude-cli";

package/src/producer/provider.ts

@@ -39,4 +39,4 @@ export interface LlmProvider {
   }): Promise<T>;
 }
 
-export type ProviderName = "claude" | "claude-cli" | "gemini" | "mock";
+export type ProviderName = "claude" | "claude-cli" | "gemini" | "antigravity" | "mock";

package/src/retake.ts

@@ -223,13 +223,18 @@ function silenceFraction(silences: readonly Span[], start: number, end: number):
  * sits earlier is never cut, so a spurious split ends at a report line,
  * not a shear through live audio.
  */
+/** An Instance plus whether the restart split fragmented its coarse sentence. */
+interface SentenceInstance extends Instance {
+  wasSplit: boolean;
+}
+
 function buildInstances(
   transcript: Transcript,
   analysis: Pick<Analysis, "silences" | "fillers">,
   transparentMarker?: string,
-): Instance[] {
+): { fragments: Instance[]; sentences: SentenceInstance[] } {
   const words = transcript.words;
-  if (words.length === 0) return [];
+  if (words.length === 0) return { fragments: [], sentences: [] };
   const fillerIndices = new Set(analysis.fillers.map((f) => f.wordIndex));
   const marker = transparentMarker ? normalizeToken(transparentMarker) : undefined;
 
@@ -269,6 +274,7 @@ function buildInstances(
   };
 
   const instances: Instance[] = [];
+  const sentences: SentenceInstance[] = [];
   for (const sent of coarse) {
     // A sentence that is ALREADY silence-dominated end-to-end is the
     // hallucination shape, not the restart shape: whisper sprinkles sparse
@@ -334,8 +340,17 @@ function buildInstances(
     // runs out of words mid-sentence is a trailing abandoned partial, not a
     // finished take, whatever fragment boundary it happens to land on.
     instances.push(toInstance(fragStart, sent.end, isSentenceEnd(transcript, sent.end), true));
+    // The whole coarse sentence, rejoined across its restart splits, for the
+    // §135 sentence-level pass: VO-paced delivery pauses INSIDE a sentence,
+    // so both takes of a genuine retake fragment into pieces that never
+    // match each other. `wasSplit` records whether the split actually fired —
+    // the pass only acts where fragmentation could have hidden a match.
+    sentences.push({
+      ...toInstance(sent.start, sent.end, isSentenceEnd(transcript, sent.end), true),
+      wasSplit: splitAfter.length > 0,
+    });
   }
-  return instances;
+  return { fragments: instances, sentences };
 }
 
 // ---- matching -------------------------------------------------------------
@@ -427,11 +442,21 @@ function toPublic(i: Instance): RetakeInstance {
  * a clause boundary, not an abandoned take: its own sentence continues
  * without it, so it goes to `undecided` (report-only), never `cuts`.
  */
-function buildGroup(chain: readonly Instance[], hallucinated: readonly Instance[]): RetakeGroup {
+function buildGroup(
+  chain: readonly Instance[],
+  hallucinated: readonly Instance[],
+  // The fragment pass keeps its strict bar. The §135 sentence pass gates
+  // survivors at the HALLUCINATION bar instead: a whole sentence carrying
+  // deliberate mid-sentence pauses is ordinary read-aloud delivery — the
+  // field run's kept take sat at 36% dead air, over the fragment bar by one
+  // point, and a textbook retake went report-only for it. Below the
+  // hallucination bar, a sentence-level survivor is a real take.
+  survivorBar: number = RESTART_SPLIT_MIN_SIL,
+): RetakeGroup {
   const completes = chain.filter((i) => i.complete);
   const lastComplete = completes[completes.length - 1];
   const kept =
-    lastComplete !== undefined && lastComplete.silenceFrac <= RESTART_SPLIT_MIN_SIL
+    lastComplete !== undefined && lastComplete.silenceFrac <= survivorBar
       ? lastComplete
       : undefined;
   const hallu: RetakeHallucination[] = hallucinated.map((i) => ({
@@ -511,7 +536,65 @@ export function findRetakeGroups(
   analysis: Pick<Analysis, "silences" | "fillers">,
   opts: { transparentMarker?: string } = {},
 ): RetakeGroup[] {
-  const instances = buildInstances(transcript, analysis, opts.transparentMarker);
+  const { fragments, sentences } = buildInstances(transcript, analysis, opts.transparentMarker);
+  const groups = chainGroups(fragments);
+
+  // §135 sentence-level pass — the VO field case. Deliberate mid-sentence
+  // pauses (read-aloud delivery) make the restart split shred BOTH takes of a
+  // genuine retake into fragments that never match each other, and the
+  // fragment pass above reports nothing ("takes half [3s] a second" vs
+  // "…half a millisecond" — whole-sentence similarity 0.875, zero fragment
+  // matches). This pass re-runs the SAME chain algorithm over whole coarse
+  // sentences, then keeps a group only when:
+  //   (a) some member's sentence actually WAS split — unsplit sentences were
+  //       already compared whole by the fragment pass, so acting on them here
+  //       could only second-guess a decision that pass already made; and
+  //   (b) no member's words are claimed by a fragment-pass group — including
+  //       its `undecided` members, so a cut the abandonment/cut-validation
+  //       rules (§128) deliberately DECLINED stays declined.
+  // C1-style parallel rhetoric is safe here by construction: those are
+  // different sentences, and whole-sentence similarity scores the divergence
+  // the fragment prefixes hid.
+  const claimed = new Set<number>();
+  for (const g of groups) {
+    const members = [g.kept, ...g.cuts, ...g.hallucinated, ...g.undecided];
+    for (const m of members) {
+      if (!m) continue;
+      for (let w = m.startWord; w <= m.endWord; w++) claimed.add(w);
+    }
+  }
+  const splitByStartWord = new Map(sentences.map((s) => [s.startWord, s.wasSplit]));
+  for (const g of chainGroups(sentences, HALLUCINATION_SILENCE_FRAC)) {
+    const members = [g.kept, ...g.cuts, ...g.hallucinated, ...g.undecided].filter(
+      (m): m is RetakeInstance => m !== null,
+    );
+    if (!members.some((m) => splitByStartWord.get(m.startWord))) continue;
+    let overlaps = false;
+    for (const m of members) {
+      for (let w = m.startWord; w <= m.endWord && !overlaps; w++) {
+        if (claimed.has(w)) overlaps = true;
+      }
+    }
+    if (overlaps) continue;
+    groups.push(g);
+  }
+
+  // Two passes can interleave in transcript order — the report reads in
+  // word order, whichever pass found the group.
+  groups.sort((a, b) => {
+    const first = (g: RetakeGroup): number =>
+      Math.min(
+        ...[g.kept, ...g.cuts, ...g.hallucinated, ...g.undecided]
+          .filter((m): m is RetakeInstance => m !== null)
+          .map((m) => m.startWord),
+      );
+    return first(a) - first(b);
+  });
+  return groups;
+}
+
+/** The chaining rule (doc block above), shared by both passes verbatim. */
+function chainGroups(instances: readonly Instance[], survivorBar?: number): RetakeGroup[] {
   const groups: RetakeGroup[] = [];
 
   let anchor: Instance | null = null;
@@ -520,7 +603,7 @@ export function findRetakeGroups(
 
   const finalize = (): void => {
     if (chain.length >= 2 || (chain.length >= 1 && hallucinated.length > 0)) {
-      groups.push(buildGroup(chain, hallucinated));
+      groups.push(buildGroup(chain, hallucinated, survivorBar));
     }
     chain = [];
     hallucinated = [];