@ossclip/core 0.1.28 → 0.1.30

package/package.json

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

package/src/browser.ts

@@ -6,6 +6,7 @@
  */
 export * from "./scene-schema";
 export * from "./scene-registry";
+export * from "./scene-props-controls";
 export * from "./overrides";
 // The editor derives its plain takes with the SAME function the pipeline
 // uses — a copy would drift and the two timelines would disagree.

package/src/producer/antigravity.ts

@@ -9,13 +9,24 @@ import { estimateTokens, type LlmUsage } from "./usage";
 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).
+ * 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
+ * a fall back to the next provider (FINDINGS §132, §143).
+ *
+ * This is a RECOVERY DEADLINE, not a patience allowance (§149). It was 10m on
+ * the theory that a big beat sheet might legitimately need it; the theory was
+ * wrong twice over. agy's hang is intermittent and service-side — §143 probed
+ * a 95,030-token call that answered in 17.6s — so a call that has said nothing
+ * for 90s is not working slowly, it is hung. And what rescues it is the
+ * fallback, which costs seconds. Waiting 10m to start a 5s recovery cost one
+ * field run 605.9s of dead air on a 96-second video (2026-08-23: 692s total
+ * for ~86s of real work).
+ *
+ * 90s is 2x the slowest healthy call ever measured (46s) and below agy's own
+ * 5m default. Go duration format, verified against `agy --help` ("default
+ * 5m0s"). Raise it only for a call measured to SUCCEED slower than this.
  */
-export const AGY_PRINT_TIMEOUT = "10m";
+export const AGY_PRINT_TIMEOUT = "90s";
 
 /**
  * agy takes the prompt as an argv argument only — no stdin — and macOS caps
@@ -25,6 +36,50 @@ export const AGY_PRINT_TIMEOUT = "10m";
  */
 export const MAX_AGY_PROMPT_BYTES = 700_000;
 
+/**
+ * Remove the constraints agy would REJECT a whole generation over and we can
+ * absorb ourselves (§151).
+ *
+ * agy does not constrain decoding — it generates, validates server-side
+ * against the schema we hand it, and on failure regenerates. Captured from a
+ * real call:
+ *
+ *   "error": "invalid arguments:\n- at '/hook': maxLength: got 136, want 120"
+ *
+ * Sixteen characters over, and the whole attempt is discarded. `maxLength`
+ * buys nothing there, because `cappedText` already truncates an overshoot at a
+ * word boundary — so the cap on the wire could only ever cost a generation,
+ * never save one.
+ *
+ * SCOPE, stated because the obvious guess is wrong: this is NOT why agy times
+ * out. That was the theory this function was written under, and it was
+ * refuted by replaying the exact failing beat-sheet request standalone — with
+ * maxLength stripped it still timed out, and with `--json-schema` dropped
+ * ENTIRELY it still timed out, agy's own error being "timeout waiting for
+ * response" with an empty body. The hang is upstream and prompt-triggered
+ * (§143, §149); this only removes one real-but-separate way a generation gets
+ * thrown away.
+ *
+ * `maxItems`, `enum`, `const`, `type` and `required` all stay: a 25th moment
+ * or an invented sceneKind is not something truncation can quietly repair, and
+ * that is the part of the contract worth paying a retry for.
+ *
+ * Only agy needs this. claude-cli receives the schema as prompt text, and
+ * gemini constrains during decoding, so neither turns a long string into a
+ * discarded generation.
+ */
+export function stripAbsorbableCaps(schema: unknown): unknown {
+  if (Array.isArray(schema)) return schema.map(stripAbsorbableCaps);
+  if (schema && typeof schema === "object") {
+    return Object.fromEntries(
+      Object.entries(schema as Record<string, unknown>)
+        .filter(([k]) => k !== "maxLength")
+        .map(([k, v]) => [k, stripAbsorbableCaps(v)]),
+    );
+  }
+  return schema;
+}
+
 /**
  * agy's `--effort` levels. Exposed after the §143 hang incident (2026-08-22):
  * untested at real scale whether a lower effort moves the hang, but the knob
@@ -305,7 +360,9 @@ export class AntigravityProvider implements LlmProvider {
     schema: z.ZodType<T>;
     schemaName: string;
   }): Promise<T> {
-    const schemaText = JSON.stringify(z.toJSONSchema(req.schema));
+    // Stripped before it goes on the wire (§151) — agy validates against this
+    // after generating, and a length overshoot costs the whole attempt.
+    const schemaText = JSON.stringify(stripAbsorbableCaps(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}"). ` +

package/src/producer/beats.ts

@@ -20,6 +20,15 @@ import type { LlmProvider } from "./provider";
  * so the model is still ASKED for the limit; it just no longer costs a run
  * when the model misses by a word. Truncation prefers the last word boundary,
  * and adds no ellipsis — the prompt explicitly forbids one on cover text.
+ *
+ * One provider is now an exception (§151). agy does not constrain decoding: it
+ * generates, validates against the schema server-side, and REGENERATES on a
+ * miss — so there, "still asked" cost the entire attempt, and a run of near
+ * misses walked into the print-timeout as a hang. `stripAbsorbableCaps` drops
+ * maxLength from agy's copy of the schema, and this truncation is what makes
+ * that safe. Every capped string in the beat sheet routes through here for
+ * exactly that reason — a single bare `.max()` would turn agy's retry loop
+ * into a hard local failure instead.
  */
 export function cappedText(max: number): z.ZodType<string> {
   return z.preprocess((v) => {
@@ -86,10 +95,14 @@ export type BeatSheet = z.infer<typeof BeatSheetSchema>;
 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"),
+  // cappedText, not a bare .max(200) (§151): this was the ONE capped string in
+  // the beat sheet that REJECTED an overshoot instead of truncating it. That
+  // asymmetry is load-bearing now — the agy request drops maxLength from the
+  // wire schema precisely because every cap can be absorbed locally, and a
+  // single rejecting field would turn a retry loop into a hard failure.
+  reason: cappedText(200).describe(
+    "one line: why THIS window is the strongest stretch of the take",
+  ),
 });
 export type ClipHighlight = z.infer<typeof ClipHighlightSchema>;
 

package/src/producer/index.ts

@@ -30,7 +30,11 @@ export * from "./youtube";
 export * from "./scene-props";
 export * from "./repair";
 export { AnthropicProvider, DEFAULT_CLAUDE_MODEL } from "./anthropic";
-export { AntigravityProvider, type LlmEffort } from "./antigravity";
+// AGY_PRINT_TIMEOUT is public because the CLI SAYS it: a slow agy call looks
+// identical to a working one on screen, so the spinner names the budget it is
+// waiting out rather than letting the wait read as a freeze (§149). Exported
+// rather than restated in the CLI so the number cannot drift from the flag.
+export { AntigravityProvider, AGY_PRINT_TIMEOUT, type LlmEffort } from "./antigravity";
 export { ClaudeCliProvider } from "./claude-cli";
 export { GeminiProvider, DEFAULT_GEMINI_MODEL } from "./gemini";
 export { MockProvider } from "./mock";

package/src/scene-props-controls.ts

@@ -0,0 +1,63 @@
+import { z } from "zod/v4";
+import { SCENE_REGISTRY } from "./scene-registry";
+import type { SceneComponentId } from "./scene-schema";
+
+/**
+ * The Inspector's controls for a scene's non-text props, derived from the
+ * component's own schema (§153).
+ *
+ * Every string prop already has an editor: select the element and type in the
+ * Text field. Nothing else did. `inverted`, `kenBurns`, `emphasizeLast` and
+ * `fanOut` were reachable only by hand-editing overrides.json, because
+ * `elementTextOf` returns null for anything that is not a string and the Text
+ * field never renders.
+ *
+ * Derived rather than hand-listed on purpose. Hand-wiring per component is
+ * exactly how ScreenshotFrame shipped a `data-edit-id` naming no prop at all —
+ * the UI and the schema drifted and nothing connected them. Reading the schema
+ * means a component that gains a boolean gets a control the day it lands.
+ *
+ * Lives in core, not the editor, and ships through the `browser` entry: zod
+ * is already in that module graph (scene-schema + scene-registry), so the
+ * editor gets the derivation without pulling a schema library into its own
+ * bundle — the same reason `browser.ts` exists at all.
+ */
+export type PropControl = {
+  key: string;
+  kind: "boolean" | "enum";
+  /** The schema's own default — what the scene renders as when unset. */
+  fallback?: boolean;
+  options?: string[];
+};
+
+type JsonSchemaProp = {
+  type?: string;
+  enum?: unknown[];
+  default?: unknown;
+};
+
+export function scalarPropControls(component: SceneComponentId): PropControl[] {
+  const meta = SCENE_REGISTRY[component];
+  if (!meta) return [];
+  const schema = z.toJSONSchema(meta.propsSchema as unknown as z.ZodType) as {
+    properties?: Record<string, JsonSchemaProp>;
+  };
+  const controls: PropControl[] = [];
+  for (const [key, prop] of Object.entries(schema.properties ?? {})) {
+    // Enums first: a string prop with an enum is a CHOICE, not free text, and
+    // the Text field would let you type a value the component cannot render.
+    if (Array.isArray(prop.enum) && prop.enum.every((v) => typeof v === "string")) {
+      controls.push({ key, kind: "enum", options: prop.enum as string[] });
+      continue;
+    }
+    if (prop.type === "boolean") {
+      // The default matters: kenBurns is true when unset, so a checkbox that
+      // assumed false would describe the scene wrongly before you touched it.
+      controls.push({ key, kind: "boolean", fallback: prop.default === true });
+    }
+    // Strings and arrays fall through by design — the per-element Text field
+    // and element selection already own them, and a second control writing the
+    // same prop is how two sources of truth start disagreeing.
+  }
+  return controls;
+}