@cueframe/kernel 0.0.1

package/dist/_members/authoring/scope.d.ts

@@ -0,0 +1,31 @@
+/**
+ * AgentScope — the agent-neutral operating policy for one agent context: which
+ * tools it may call, its system-prompt direction, the skills it can load on
+ * demand, and how its context window is managed.
+ *
+ * Cloud-first by design. The primary consumer is the cloud compose author
+ * (`the Director worker` builds a `composeAuthorScope` whose `prompt` is the
+ * per-run suggestion craft prompt). The desktop `PageScope` simply EXTENDS this
+ * type with its route/store/navigation fields — it adapts to the core, the core
+ * does not bend to it. The scope is a plain data bundle the caller destructures
+ * into the existing `AgentConfig`/`AgentRunOptions` seams (`activeTools` →
+ * `opts.tools`, `prompt` → `systemPrompt`, `contextManagement` → `AgentConfig`),
+ * so adopting it requires no new Agent API.
+ */
+import type { ContextManagementPolicy } from './agent/contextManagement.js';
+export interface AgentScope {
+    /** Tool names this scope may call — passed to the AI SDK as activeTools. */
+    readonly activeTools: readonly string[];
+    /**
+     * System-prompt direction for this scope. The cloud author computes this
+     * per-run (the suggestion craft prompt); desktop scopes are static strings.
+     */
+    readonly prompt: string;
+    /** Context-window management policy for the tool loop (stale-content eviction). */
+    readonly contextManagement?: ContextManagementPolicy;
+}
+/** Bake a craft skill's FULL content into the scope prompt. Structural craft:
+ *  the compose loop's `load_skill` was measured at a 0% load rate over a full
+ *  week — craft offered as a tool the loop may skip gets skipped (spec
+ *  2026-07-13-phased-card-first §2.5). Static per phase → prompt-cache-friendly. */
+export declare function renderSkillContent(name: string, body: string): string;

package/dist/_members/authoring/tools/brandTokens.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Brand Token Resolver -- auto-fills overlay params from template defaults and
+ * (for brand-driven fields) semantic brand-token refs resolved at render time.
+ *
+ * Pure function module. No class, no state, no store imports at runtime.
+ *
+ * Resolution strategy:
+ *   1. Explicit LLM args                → stored as literals (always wins)
+ *   2. Template paramDefaults            → stored as literals (non-content fields)
+ *   3. Brand-driven slots unset by caller → stored as `"$brand:<path>"` refs
+ *      resolved by `@cueframe/compose` at render time, so brand-kit edits
+ *      propagate to existing overlays without rewriting persisted rows.
+ */
+export interface TemplateMeta {
+    id: string;
+    name: string;
+    category: string;
+    description: string;
+    params: string[];
+    paramDefaults: Record<string, string>;
+}
+export interface ResolveContext {
+    templateMeta?: TemplateMeta;
+}
+/**
+ * Fill gaps in overlay params using template defaults and brand-token refs.
+ * Never mutates the input -- returns a new params object.
+ *
+ * Note: brand-driven slots store a `"$brand:<path>"` ref when unset. The
+ * render-time inflater (`@cueframe/compose/inflatePrimitiveProps`) resolves
+ * refs against the active brand kit. This keeps brand-kit edits live for
+ * existing overlays instead of baking a snapshot.
+ */
+export declare function resolveOverlayParams(params: Record<string, unknown>, ctx: ResolveContext): Record<string, unknown>;

package/dist/_members/authoring/tools/composeRoleTools.d.ts

@@ -0,0 +1,112 @@
+/**
+ * The IN-PROCESS compose-role tools — what is left after the 81-tool registry.
+ *
+ * ── WHY ANYTHING SURVIVED ───────────────────────────────────────────────────
+ * The one-vocabulary merge moved every AGENT-FACING surface onto the curated
+ * `/v1` manifest (`buildCuratedToolSet`): the hosted MCP server, the Convex
+ * editor agent, the desktop Director (over `LocalExecutor`) and the cloud
+ * Director's author / assembler / designer roles all speak the same names now,
+ * and `TOOL_SCHEMAS` / `TOOL_REGISTRY` / `handlers/` are deleted.
+ *
+ * TWO Director roles do not, BY DESIGN: `shouldUseMcpSurface`
+ * (the Director worker) returns false for
+ * `planner` and `motion`. Their verbs are not API calls and cannot be:
+ *
+ *   submit_compose_plan / amend_compose_plan  deliver a value to the RUNNING
+ *       ACTIVITY's `planSink` — a Temporal-local closure. There is no project
+ *       to POST to; the plan is validated and locked by the workflow.
+ *   capture_frames / score_composition        drive the run's in-loop capture
+ *       and verify budgets (one Modal render instance per activity, cost-capped
+ *       per run). The /v1 twins (`preview_frame`, `score_composition`) bill per
+ *       call against a project the candidate does not have yet.
+ *   apply_motion_preset                       mutates the run's headless store
+ *       and mints a tenant component; the storyboard is APPROVED at that point
+ *       and must not round-trip through a scratch session.
+ *   get_context / get_word_timings / inspect_overlay / update_overlay /
+ *   search_library                            read and write THAT store and the
+ *       run's pre-curated candidate pool — neither exists server-side.
+ *
+ * So this module is not a surviving fragment of the old vocabulary; it is the
+ * in-process compose lane's own tool set, ten names, all reachable only from
+ * `COMPOSE_PLANNER_TOOLS`, `COMPOSE_PLANNER_REPAIR_TOOLS` and
+ * `COMPOSE_MOTION_TOOLS`. Anything an EDITING agent can ask for lives in the
+ * manifest. If a role ever moves onto the MCP surface, its entries leave here.
+ *
+ * ── NO `registerToolHandlers` ───────────────────────────────────────────────
+ * The old registry was mutable at runtime, and three consumers reached in to
+ * swap handlers (the pro extension, the Director's compose `search_library`
+ * formatter, the Director's `add_overlay` validator). That global mutability is
+ * gone with it: handlers are bound here, once. The compose-lane `search_library`
+ * formatting is IN the handler below (it was the only real override left), and
+ * a consumer that needs different behaviour supplies a different CAPABILITY,
+ * which is the seam that was always meant to carry it.
+ */
+import { z } from 'zod';
+import type { AgentCapabilities } from '../capabilities.js';
+/** Options bag passed to tool handlers. */
+export type ToolHandlerOptions = Record<string, unknown>;
+/** The shapes handlers actually produce. */
+export type ToolHandlerResult = {
+    error: string;
+} | {
+    success: true;
+    message: string;
+    [key: string]: unknown;
+} | string | string[] | Record<string, unknown>;
+export type ToolHandler = (args: Record<string, unknown>, capabilities: AgentCapabilities, opts?: ToolHandlerOptions) => Promise<ToolHandlerResult>;
+export interface ToolMeta {
+    name: string;
+    description: string;
+    /**
+     * Zod object schema for the tool's input parameters.
+     *
+     * Typed to its OUTPUT shape rather than `z.ZodType<any>`: AI SDK v7 infers a
+     * tool's input from this schema, and `any` collapses that inference to
+     * `never` — every `tool()` built from this registry then fails to typecheck.
+     * These are all object schemas, so saying so is a truer declaration, not a
+     * workaround.
+     */
+    schema: z.ZodType<Record<string, unknown>>;
+    metadata: {
+        label: string;
+        /** True for tools that return image data (base64) — routed to vision blocks. */
+        imageResponse?: boolean;
+        /**
+         * True for read/verification tools whose whole purpose is to be re-issued
+         * with identical args after an edit. The dedup loop-guard skips these:
+         * re-rendering the same beat to confirm a fix is progress, not a stuck
+         * loop, and cost is bounded by the per-run capture budget instead.
+         */
+        dedupExempt?: boolean;
+    };
+    /** When true, the AI SDK enforces strict schema matching. */
+    strict?: boolean;
+    /** Example inputs for AI SDK tool hints. */
+    inputExamples?: Array<{
+        input: Record<string, unknown>;
+    }>;
+    /** Custom output formatter (truncate, summarize). */
+    toModelOutput?: (result: unknown) => {
+        type: 'text';
+        value: string;
+    };
+    handler: ToolHandler;
+}
+/**
+ * FROZEN. The registry this replaces was a mutable process-global that three
+ * consumers reached into at module load (`registerToolHandlers`), so a worker's
+ * tool behaviour depended on import order and one consumer's override silently
+ * became everyone's. `Object.freeze` makes the successor's shape a compile-time
+ * AND runtime fact: a re-introduced mutation throws in strict mode instead of
+ * quietly re-creating the failure mode this deletion removed.
+ */
+export declare const COMPOSE_ROLE_TOOLS: Readonly<Record<string, ToolMeta>>;
+/** Every name this module serves — the in-process lane's whole vocabulary. */
+export declare const COMPOSE_ROLE_TOOL_NAMES: readonly string[];
+/**
+ * Dispatch one in-process tool call. Args are validated against the tool's own
+ * schema first — LLM-generated args are routinely malformed, and a type error
+ * inside a handler reads as an infrastructure failure rather than a fixable
+ * one.
+ */
+export declare function dispatchComposeRoleTool(toolName: string, args: Record<string, unknown>, capabilities: AgentCapabilities, opts?: ToolHandlerOptions): Promise<ToolHandlerResult>;

package/dist/_members/authoring/tools/index.d.ts

@@ -0,0 +1,4 @@
+/** Barrel re-export for the tool system. */
+export { COMPOSE_PLANNER_TOOLS, COMPOSE_PLANNER_REPAIR_TOOLS, COMPOSE_MOTION_TOOLS, COMPOSE_MOTION_VERIFY_TOOLS, } from './toolSets.js';
+export { COMPOSE_ROLE_TOOLS, COMPOSE_ROLE_TOOL_NAMES, dispatchComposeRoleTool, } from './composeRoleTools.js';
+export type { ToolMeta, ToolHandler, ToolHandlerOptions, ToolHandlerResult, } from './composeRoleTools.js';

package/dist/_members/authoring/tools/toolSets.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The IN-PROCESS compose ROLE scopes — which tool names the planner and the
+ * motion pass may use.
+ *
+ * Names only; no schemas, no handlers. They are read by the in-process factory
+ * over `COMPOSE_ROLE_TOOLS` (composeRoleTools.ts), the ten verbs that
+ * structurally cannot be `/v1` calls.
+ *
+ * ONLY those two roles. The MCP roles' scopes (author / assembler / designer)
+ * are NOT here — they are `CURATED_AUTHOR_TOOLS` / `CURATED_DESIGNER_TOOLS` in
+ * the director's `agent/composeToolScopes.ts` (moved out of @cueframe/mcp
+ * 2026-08-22 — the scopes are director steering). Until
+ * 2026-08-08 this file also carried `COMPOSE_AUTHOR_TOOLS` /
+ * `COMPOSE_ASSEMBLER_TOOLS` / `COMPOSE_DESIGNER_TOOLS`, whose ~18 entries
+ * (`add_clip`, `set_captions`, `add_overlay`, `view_asset`, `verify_graphic`, …)
+ * had been deleted verbs since the registry went: `runAuthorOnMcpSurface`'s
+ * factory ignores the Agent's `allowedTools` and builds the CURATED set, so the
+ * lists scoped nothing while reading exactly like a live scope. They cannot be
+ * restated here without first ADDING a `@cueframe/mcp` dependency to this
+ * package — which nothing mechanically forbids (dependency-cruiser only flags
+ * the UNDECLARED import; a declared edge would resolve and pass), so treat the
+ * one-way vocabulary flow as convention held up by where the gates sit. That is
+ * precisely why the MCP scopes belong on the MCP side. The director joins the
+ * two (agent/composeAuthorScope.ts) and gates the join
+ * (agent/__tests__/oneVocabularyPerSurface.test.ts).
+ *
+ * The per-skill sets that used to live beside these (ANALYSIS_TOOLS,
+ * EDITING_TOOLS, GRAPHICS_TOOLS, CAPTIONS_TOOLS, RESOURCES_TOOLS,
+ * EXPORT_TOOLS — 81 desktop-only verbs) are DELETED with the registry: the
+ * desktop editor agent's scope is now `INTERNAL_EDITOR_TOOLS`
+ * (packages/mcp/src/curation.ts) plus the nine client actions.
+ */
+/** The compose PLANNER's tool subset — read-only context + VISION + the plan
+ *  tool. `capture_frames` lets the planner SEE the raw source (judge shot types:
+ *  wide establishing vs tight speaker) before deciding framing/trims — presence
+ *  data alone can't distinguish a framable tight shot from an un-framable wide
+ *  one. No mutation tools: the planner decides, the assembler builds. */
+export declare const COMPOSE_PLANNER_TOOLS: readonly ["get_context", "get_word_timings", "search_library", "capture_frames", "submit_compose_plan"];
+/** REPAIR-round planner scope (plan-ops, 2026-07-18): same recon set, but
+ *  amend_compose_plan REPLACES submit_compose_plan — a repair round cannot
+ *  re-emit the full plan, so un-amended sections cannot drift (run-3 root
+ *  cause: the bounce path regenerated the whole plan and deleted graphics). */
+export declare const COMPOSE_PLANNER_REPAIR_TOOLS: readonly ["get_context", "get_word_timings", "search_library", "capture_frames", "amend_compose_plan"];
+/** The P2 MOTION pass's tool subset (phased card-first §3): the storyboard is
+ *  APPROVED, so motion may tune and shell but never restructure — no add/remove,
+ *  no framing, no captions. update_overlay tunes library timing/params;
+ *  apply_motion_preset shells static cards; capture/score verify the motion. */
+export declare const COMPOSE_MOTION_TOOLS: readonly ["get_context", "get_word_timings", "inspect_overlay", "capture_frames", "update_overlay", "apply_motion_preset", "score_composition"];
+/** The motion pass's READ/VERIFY subset — COMPOSE_MOTION_TOOLS minus its two
+ *  mutations. The Agent's reserve-verify-step (finalStepTools, P0.2) restricts
+ *  the LAST budgeted step to these, so a mutation can never be the loop's
+ *  unread final act (staging v17b1hsx: the pass's only mutation errored on step
+ *  12/12 and nobody read the error — the card shipped static). */
+export declare const COMPOSE_MOTION_VERIFY_TOOLS: ("capture_frames" | "score_composition" | "get_context" | "get_word_timings" | "inspect_overlay")[];

package/dist/_members/authoring/transpileComponent.d.ts

@@ -0,0 +1,40 @@
+/**
+ * transpileComponent — TSX → sandbox-ready JS for the Bakeless Render Lane.
+ *
+ * A `live` component renders as a `custom` overlay inside the render-page sandbox
+ * (`evaluateInSandbox`, packages/execution/render-entry/src/sandbox-scope.ts), whose wrapper is:
+ *
+ *   (function(){ "use strict"; const exports = {}; <CODE> return exports.default; })()
+ *
+ * So the transpiled `<CODE>` must (a) contain NO `import`/`export` statements —
+ * they are syntax errors inside a function body, and the sandbox INJECTS React /
+ * remotion / animate as endowments — and (b) assign `exports.default = <Component>`.
+ *
+ * This is the Node/native-esbuild sibling of the desktop `transpileJsx`
+ * (cueframe/src/llm/transpile.ts, esbuild-wasm) and the director's
+ * `serverTranspiler` (activities/director.ts). All three share ONE transpile
+ * config — the SSOT `ESBUILD_JSX_OPTIONS` + `postProcessForSandbox` in
+ * ./transpileHelper — so a live component transpiled here is byte-identical to
+ * what those paths produce. Do NOT inline a second config here.
+ *
+ * Native (not wasm) esbuild `transformSync`: this runs in a Node runtime (a Convex
+ * `"use node"` action or the director), never the Convex V8 isolate. Synchronous +
+ * throwing so the save path can turn a compile failure into a 422
+ * `component_does_not_compile` in one call.
+ */
+/** A live component's TSX did not compile. Carries the esbuild message (the
+ *  author-fixable detail the save path surfaces as `component_does_not_compile`). */
+export declare class TranspileError extends Error {
+    constructor(message: string);
+}
+/**
+ * Transpile a component's authored `tsxSource` to sandbox-ready `jsSource`.
+ * Throws `TranspileError` (with the esbuild message) on a compile failure.
+ *
+ * `componentId` is used only to name the virtual source file so esbuild's error
+ * messages point at the component (`<componentId>.tsx`), never at an anonymous
+ * `<stdin>`.
+ */
+export declare function transpileComponent(tsxSource: string, componentId: string): {
+    jsSource: string;
+};

package/dist/_members/authoring/transpileHelper.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Shared post-processing for AI-generated JSX → sandbox-compatible JS.
+ *
+ * Both desktop (esbuild-wasm) and server (esbuild native) use this after
+ * esbuild.transform(). The sandbox (DynamicOverlay) uses new Function()
+ * which can't handle import/export statements — this strips them.
+ *
+ * The esbuild transform uses the classic JSX transform (React.createElement)
+ * so that React is provided by the sandbox scope, not imported.
+ */
+/**
+ * esbuild transform options for AI-generated JSX.
+ * Use these with esbuild.transform(jsxSource, ESBUILD_JSX_OPTIONS).
+ */
+export declare const ESBUILD_JSX_OPTIONS: {
+    loader: "tsx";
+    jsx: "transform";
+    jsxFactory: string;
+    jsxFragment: string;
+    target: "es2020";
+};
+/**
+ * Post-process esbuild output for the DynamicOverlay sandbox.
+ * Strips imports (sandbox injects them), converts export default → exports.default.
+ */
+export declare function postProcessForSandbox(code: string): string;