@cueframe/kernel 0.1.1 → 0.1.3

package/dist/_members/director/testing/contract.d.ts

@@ -0,0 +1,52 @@
+import type { DirectorRuntime } from "../domain/ports.js";
+export declare function collectRuntime(runtime: DirectorRuntime, prompt?: string): Promise<({
+    type: "text-delta";
+    text: string;
+} | {
+    type: "reasoning-delta";
+    text: string;
+} | {
+    type: "phase";
+    phase: string;
+    detail?: string | undefined;
+} | {
+    type: "generation";
+    artifact: {
+        kind: "video" | "audio" | "image";
+        status: "generating" | "processing" | "cancelled" | "ready" | "failed" | "draft" | "submitting" | "queued" | "provider_complete" | "materialising" | "cancelling";
+        mediaId: string & import("zod").BRAND<"Id<media>">;
+        createdAt: number;
+        updatedAt: number;
+        clientRequestId: string & import("zod").BRAND<"Id<generationRequest>">;
+        generationGroupId: string & import("zod").BRAND<"Id<generationGroup>">;
+        generationId: string & import("zod").BRAND<"Id<generation>">;
+        version: number;
+        artifactVersion: 1;
+        requestSummary: string;
+        placementReady: boolean;
+        parentMediaId?: (string & import("zod").BRAND<"Id<media>">) | undefined;
+        estimateUsd?: number | undefined;
+        progress?: number | undefined;
+        failure?: {
+            code: string;
+            title: string;
+            retryable: boolean;
+            recovery?: string | undefined;
+            correlationId?: string | undefined;
+        } | undefined;
+    };
+} | {
+    type: "error";
+    error: {
+        code: string;
+        title: string;
+        retryable: boolean;
+        recovery?: string | undefined;
+        source?: "provider" | "generation" | "materialisation" | "agent" | "transport" | undefined;
+        correlationId?: string | undefined;
+        details?: string | undefined;
+    };
+} | {
+    type: "finish";
+})[]>;
+export declare function assertDirectorRuntimeContract(runtime: DirectorRuntime): Promise<void>;

package/dist/_members/director/testing/index.d.ts

@@ -0,0 +1 @@
+export * from "./contract.js";

package/dist/_members/errors/registry.d.ts

@@ -1,15 +1,3 @@
-/**
- * @cueframe/errors — the cross-cutting error contract SSOT.
- *
- * Zero `@cueframe/*` dependencies (enforced by the `errors-is-a-pure-leaf`
- * dependency-cruiser rule) so it can be imported by every framework leaf
- * (incl. perception + composition) and every service without a cycle.
- *
- * One vocabulary (`ERROR_CODES`), one carrier (`CueframeError`), one wire
- * shape (`Envelope`), one Lambda-boundary codec (`encodeError`/`decodeError`),
- * and one sanitization chokepoint (`toWireEnvelope`) that EVERY emit channel
- * routes through before anything reaches an agent.
- */
 export type ErrorStage = "auth" | "billing" | "import" | "validate" | "compose" | "render" | "export" | "system";
 export type ErrorCategory = "authoring" | "transient" | "internal";
 export interface ErrorSpec {
@@ -537,7 +525,7 @@ export declare const ERROR_CODES: {
     };
     readonly behind_matte_unresolved: {
         readonly stage: "render";
-        readonly category: "internal";
+        readonly category: "authoring";
         readonly retryable: false;
         readonly httpStatus: 422;
     };
@@ -595,6 +583,12 @@ export declare const ERROR_CODES: {
         readonly retryable: false;
         readonly httpStatus: 422;
     };
+    readonly render_not_found: {
+        readonly stage: "render";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 404;
+    };
     readonly compose_not_cancellable: {
         readonly stage: "system";
         readonly category: "authoring";
@@ -625,6 +619,90 @@ export declare const ERROR_CODES: {
         readonly retryable: true;
         readonly httpStatus: 503;
     };
+    readonly render_provider_unreachable: {
+        readonly stage: "render";
+        readonly category: "transient";
+        readonly retryable: true;
+        readonly httpStatus: 503;
+    };
+    readonly render_pipeline_unavailable: {
+        readonly stage: "render";
+        readonly category: "transient";
+        readonly retryable: true;
+        readonly httpStatus: 503;
+    };
+    readonly render_route_missing: {
+        readonly stage: "render";
+        readonly category: "internal";
+        readonly retryable: true;
+        readonly httpStatus: 503;
+    };
+    readonly render_pipeline_failed: {
+        readonly stage: "render";
+        readonly category: "transient";
+        readonly retryable: true;
+        readonly httpStatus: 503;
+    };
+    readonly render_stage_timeout: {
+        readonly stage: "render";
+        readonly category: "transient";
+        readonly retryable: true;
+        readonly httpStatus: 504;
+    };
+    readonly render_promotion_failed: {
+        readonly stage: "render";
+        readonly category: "internal";
+        readonly retryable: true;
+        readonly httpStatus: 500;
+    };
+    readonly render_execution_failed: {
+        readonly stage: "render";
+        readonly category: "internal";
+        readonly retryable: false;
+        readonly httpStatus: 500;
+    };
+    readonly invalid_render_terminal: {
+        readonly stage: "render";
+        readonly category: "internal";
+        readonly retryable: false;
+        readonly httpStatus: 500;
+    };
+    readonly sighted_dispatch_failed: {
+        readonly stage: "system";
+        readonly category: "transient";
+        readonly retryable: true;
+        readonly httpStatus: 503;
+    };
+    readonly sighted_stage_timeout: {
+        readonly stage: "render";
+        readonly category: "transient";
+        readonly retryable: true;
+        readonly httpStatus: 504;
+    };
+    readonly sighted_provider_unreachable: {
+        readonly stage: "render";
+        readonly category: "transient";
+        readonly retryable: true;
+        readonly httpStatus: 503;
+    };
+    readonly sighted_artifact_missing: {
+        readonly stage: "render";
+        readonly category: "internal";
+        readonly retryable: true;
+        readonly httpStatus: 500;
+    };
+    readonly sighted_execution_failed: {
+        readonly stage: "render";
+        readonly category: "internal";
+        readonly retryable: false;
+        readonly httpStatus: 500;
+    };
+    readonly sighted_snapshot_missing: {
+        readonly stage: "system";
+        readonly category: "internal";
+        readonly retryable: false;
+        readonly httpStatus: 500;
+    };
     readonly render_stalled: {
         readonly stage: "render";
         readonly category: "transient";
@@ -655,6 +733,18 @@ export declare const ERROR_CODES: {
         readonly retryable: true;
         readonly httpStatus: 503;
     };
+    readonly operation_moved_async: {
+        readonly stage: "system";
+        readonly category: "authoring";
+        readonly retryable: false;
+        readonly httpStatus: 410;
+    };
+    readonly active_composition_invariant: {
+        readonly stage: "system";
+        readonly category: "internal";
+        readonly retryable: false;
+        readonly httpStatus: 500;
+    };
     readonly internal_error: {
         readonly stage: "system";
         readonly category: "internal";
@@ -682,27 +772,7 @@ export declare class CueframeError extends Error {
 }
 export declare function encodeError(e: CueframeError): string;
 export declare function decodeError(msg: string): CueframeError | null;
-/** Scrub SENSITIVE tokens from a raw message that will be PERSISTED or shipped
- *  over a webhook without passing through toWireEnvelope — e.g. failRenderJob's
- *  non-CFERR fallback, where the deep root cause can carry fs paths, presigned
- *  URLs, or Lambda hosts verbatim. */
 export declare function scrubSensitive(s: string): string;
-/**
- * The single sanitization chokepoint. EVERY emit channel routes through it.
- *
- * `opts.trusted` marks an author-curated envelope (a route-built `ApiError`) whose
- * `message` and `fix` we wrote ourselves — vs an UNtrusted envelope translated from a
- * raw/deep error (Lambda/processing/unmapped `ConvexError`) whose text/fields may carry a
- * stack or infra detail. Never set `trusted` for a translated error.
- *
- * - TRUSTED: keep the message (scrubbed defensively) and all `fix` keys (values scrubbed),
- *   so curated fields like `currentEtag`/`projectIds`/`name`/`reason`/`retryAfter` survive
- *   on errors of ANY category — except `internal`, where `fix` is always dropped.
- * - UNTRUSTED: `internal`/`transient` get a generic message; `authoring` keeps a scrubbed
- *   message. `fix` is dropped for `internal` and otherwise reduced to the allow-list +
- *   scrubbed (so `retryAfter` survives but a raw `filePath`/URL cannot).
- * - `locator`: always reduced to the safe key set.
- */
 export declare function toWireEnvelope(e: Envelope, opts?: {
     trusted?: boolean;
 }): Envelope;

package/dist/_members/foundation/codes/index.d.ts

@@ -1,24 +1,3 @@
-/**
- * Cross-cutting invariant code registry.
- *
- * Each domain package declares its own typed code union and constructs
- * `InvariantError` for failures. The shared `InvariantViolation` /
- * `InvariantError` shape gives every domain a uniform error contract
- * (HTTP error mapping, log shape, projection-failure reporting) without
- * forcing all codes into one enum.
- *
- * Usage from a domain package:
- *
- *   import { InvariantError, type InvariantViolation } from "./index.js";
- *
- *   export type CompositionInvariantCode =
- *     | "track_clips_overlap"
- *     | "transition_no_predecessor";
- *
- *   export function trackClipsOverlap(details: { trackId: string }): InvariantViolation<CompositionInvariantCode> {
- *     return { code: "track_clips_overlap", message: "...", details };
- *   }
- */
 export interface InvariantViolation<TCode extends string = string> {
     code: TCode;
     message: string;

package/dist/_members/mcp/adapter.d.ts

@@ -3,42 +3,17 @@ import { type Executor } from './core.js';
 export { CURATED_TOOLS } from './curation.js';
 export { INTERNAL_LOOP_TOOLS } from './internalLoopTools.js';
 export type { CuratedTool } from './curation.js';
-/**
- * The typed sentinel for infra-class tool failures. Thrown from a curated
- * tool's execute(); the AI SDK catches it into a `tool-error` step part, so the
- * throw ALONE changes nothing — the agent loop (authoring/agent.ts) detects the
- * sentinel STRUCTURALLY (name+infra, no package import — mcp↔authoring stay
- * decoupled per Constraint 3(d)), halts the run, and rethrows; the director
- * (mcpSurface) maps it to a nonRetryable ApplicationFailure so the candidate
- * fails loud with the REAL code instead of a design-lock 49 renders later.
- */
 export declare class InfraToolError extends Error {
     readonly code: string;
     readonly infra: true;
     constructor(code: string, message: string);
 }
-/** Structural guard (mirror of the authoring-side local guard). */
 export declare function isInfraToolError(v: unknown): v is InfraToolError;
-/**
- * Classify a non-2xx op response: an infra-class code returns the sentinel to
- * THROW; anything else returns null (caller keeps the Contract-3(a) JSON-string
- * return). Pure + exported for tests. Parses the error envelope itself so it
- * has no dependency on ApiError's shape.
- */
 export declare function infraToolErrorFromResponse(res: {
     status: number;
     text: string;
     requestId?: string;
 }): InfraToolError | null;
-/**
- * Structural progress event/callback — a local, dependency-free mirror of
- * `@cueframe/authoring`'s `OnProgressCallback` (types.ts:368-381). Declared here
- * so `packages/mcp` never imports `@cueframe/authoring` (Constraint 3(d): progress
- * stays external to tool-building; the adapter only *emits* the same shape the
- * in-process `buildDirectorTools` does — buildTools.ts:131-171). `agent:'router'`
- * is a subtype of authoring's `AgentRole`, so an authoring callback is assignable
- * to this param type (contravariance) when threaded through in T7.
- */
 export type AdapterProgressEvent = {
     type: 'tool-call';
     agent: 'router';
@@ -52,87 +27,29 @@ export type AdapterProgressEvent = {
     toolName: string;
     success: boolean;
     message: string;
+    data?: unknown;
     toolCallId: string;
     timestamp: number;
 };
 export type OnProgressCallback = (event: AdapterProgressEvent) => void;
 export interface CuratedToolSetOpts {
-    /**
-     * Which curated tool names to build. REQUIRED — there is no default
-     * surface: the caller owns its allowlist (the director's role scopes live
-     * in its own composeToolScopes.ts since the 2026-08-22 steering
-     * extraction; the desktop and editor lanes pass their own).
-     */
     allowedNames: readonly string[];
-    /**
-     * Optional progress sink — fires a `tool-call` before each op and a
-     * `tool-result` after, mirroring the in-process store (buildTools.ts:131-171).
-     */
     onProgress?: OnProgressCallback;
-    /**
-     * The scratch compose session (Subsystem 1). When present, the adapter injects
-     * `projectId`/`sessionId` from here and HIDES them from every tool schema — the
-     * LLM must never manage session identity — and `apply_composition` stamps
-     * `body.session_id` so writes hit the session SCRATCH, not the project's active
-     * composition (compositions.ts:331 resolves the scratch; the server never mutates
-     * active until commit_session → promoteScratch).
-     */
     session?: {
         projectId: string;
         sessionId: string;
     };
-    /**
-     * Fetch a presigned still URL and return its bytes as base64 (T4). Injectable
-     * for tests; the default streams the R2 presigned PNG to base64, mirroring the
-     * in-process capture path (inLoopCapture.ts:173-174). `render_frame` uses this
-     * to inline each still so the LLM can actually SEE the pixels — the base64 is
-     * returned RAW from execute() and only becomes a vision block in `toModelOutput`
-     * (Constraint 3(b): image bytes never leave execute() content-shaped).
-     */
     fetchImage?: (url: string) => Promise<string>;
-    /**
-     * Per-run in-loop COGS budget (T5). On the MCP path the box-direct
-     * `buildInLoopCapture`/`buildInLoopVerify` caps are gone, so the budget lives in
-     * the tool wrapper: `render_frame` costs a *capture*, `verify_composition` costs
-     * a *verify*. The counters are per-`buildCuratedToolSet` call, so one budget
-     * spans the whole author run (a fresh ToolSet is built per author invocation —
-     * matches the in-process per-run cap, director.ts:282/290). Over budget, the
-     * tool returns a JSON-string error tool output (NOT a throw — Constraint 3(a))
-     * so the LLM sees "you're out of renders — verify or commit" and stops looping.
-     * Read/mutate tools (`apply_composition`, `get_media_context`, …) are un-budgeted
-     * — only capture/verify cost COGS. Dedup (`DEDUP_MAX`) + `stepCountIs` stay in
-     * `agent.ts`, external to tool-building (Constraint 3(d)).
-     */
     budgets?: {
         captures: number;
         verifies: number;
         styleViews: number;
     };
-    /**
-     * The brand kit bound to this project (T3, brand-kit-from-inspiration). When
-     * present, `view_style_reference` presigns THIS kit's inspiration exemplar
-     * frames so the maker SEES the reference pixels; absent ⇒ the tool returns a
-     * `{note}` (no kit, no style reference) rather than an error — the kit is
-     * optional, so its absence is not a failure.
-     */
     brandKitId?: string;
-    /**
-     * Async-job poll knobs for the tools whose API op ENQUEUES a job
-     * (`verify_composition`, `preview_component`). The curated tool blocks until
-     * the job is terminal and returns the RESULT — the author/designer tool set
-     * has no `wait_job`, so a receipt-shaped tool output is a verdict the LLM can
-     * never read (the 2026-07-07 prod LBO run verified into the void exactly this
-     * way). Injectable for tests.
-     */
     jobPoll?: {
         pollMs?: number;
         timeoutMs?: number;
         sleep?: (ms: number) => Promise<void>;
     };
 }
-/**
- * Build an `ai` `ToolSet` from the curated SSOT, filtered to the caller's
- * `allowedNames`. Uses the REAL generated manifest (via opById) so a
- * missing/renamed operationId fails loud — that is the drift signal.
- */
 export declare function buildCuratedToolSet(ex: Executor, opts: CuratedToolSetOpts): ToolSet;

package/dist/_members/mcp/burnedNames.d.ts

@@ -1,22 +1,6 @@
-/**
- * Burned tool names (amendment A12, plan 2026-07-10-flow-verbs) — names that
- * DIED in the verb cutover and may NEVER be reused for a different job: a
- * reused name is a silent behavior change for every old caller.
- *
- * Each burned name registers as a TOMBSTONE tool: calling it hard-errors with
- * the replacement (an agent with a stale memory of the surface gets taught,
- * not a bare method-not-found), and the tools/list entry itself documents the
- * cutover. The gate in curation.test.ts ("burned names stay dead") asserts no
- * curated/infrastructure tool ever takes a burned name back, that the
- * internal-loop overlap stays exactly the documented four, and that every
- * tombstone's replacement is a live tool.
- */
 export interface BurnedName {
-    /** The dead tool name. */
     name: string;
-    /** What to call instead (a live tool name, or a short instruction). */
     replacement: string;
-    /** One line of why — shown in the tombstone error. */
     reason: string;
 }
 export declare const BURNED_NAMES: readonly BurnedName[];

package/dist/_members/mcp/core.d.ts

@@ -1,32 +1,12 @@
-/**
- * Transport-agnostic primitives shared by every MCP layer (raw tools, curated
- * tools, resources, wait_job) and BOTH transports (stdio + hosted). The only
- * thing that varies between transports is the `Executor` — how a tool's HTTP
- * call is actually performed:
- *
- *   - stdio  → network fetch against api.cueframe.ai with the env API key (single-tenant)
- *   - hosted → in-process app.fetch with the caller's forwarded auth (multi-tenant)
- *
- * Everything else (paths from the generated manifest, zod input schemas, result
- * formatting, error advice) is identical, so it lives here once.
- */
 import { z } from 'zod';
 import { ApiError } from '@cueframe/sdk';
 import { type GeneratedOperation } from './generated/operations.js';
-/** The one seam between transports: perform an HTTP call, return status + body text. */
 export interface Executor {
     invoke(req: {
         method: string;
         path: string;
         body?: unknown;
-        /** Query string (without leading `?`), for ops that take query params. */
         query?: string;
-        /**
-         * base64 `PAYMENT-SIGNATURE` for a paid tool call over x402. Forwarded onto
-         * the underlying request so the REST x402 middleware verifies + settles it
-         * (mints `x402:<payer>`) — the SAME money path as a direct REST call. Absent
-         * for key/OAuth-authed calls.
-         */
         payment?: string;
     }): Promise<{
         status: number;
@@ -34,7 +14,6 @@ export interface Executor {
         requestId?: string;
     }>;
 }
-/** MCP content blocks we emit. The protocol also defines `resource`; add when used. */
 export type TextBlock = {
     type: 'text';
     text: string;
@@ -53,34 +32,13 @@ export type ContentBlock = TextBlock | ImageBlock | AudioBlock;
 export type ToolResult = {
     content: ContentBlock[];
     isError?: boolean;
-    /** x402 payment-required envelope (PaymentRequired) — read by the @x402/mcp client. */
     structuredContent?: Record<string, unknown>;
 };
 export declare function text(s: string): ToolResult;
 export declare function errText(s: string): ToolResult;
-/**
- * The JSON payload of a tool result. Since `content` gained image/audio blocks,
- * callers can no longer assume `content[0].text` — but every result still leads
- * with its text block (see `withMedia`), so this is the stable accessor.
- */
 export declare function firstText(r: ToolResult): string;
 export declare function sniffImageMediaType(base64: string): string;
-/** Sniff an audio media type from magic bytes; unknown ⇒ mpeg (Freesound previews are mp3). */
 export declare function sniffAudioMediaType(base64: string): string;
-/**
- * A tool result that carries the JSON payload as text AND the pixels/samples the
- * agent needs to judge it.
- *
- * THE CONTRACT, and why it is shaped this way:
- *  - Media is ADDITIVE. The JSON text block is always first and unchanged, so ids,
- *    urls and flags keep flowing and nothing downstream breaks.
- *  - Zero media ⇒ NO media blocks at all, just the text. An empty content array is
- *    the one failure the old `(b) images never leave execute() content-shaped`
- *    constraint was written to avoid (adapter.ts:384-390) — the fix for "empty
- *    array is invalid" is to omit the block, not to convert every image to text
- *    forever.
- *  - Media types are SNIFFED per item, never declared by the caller.
- */
 export declare function withMedia(payload: string, media: {
     data: string;
     kind: 'image' | 'audio';
@@ -89,33 +47,16 @@ export declare function fetchAsBase64(url: string, opts?: {
     timeoutMs?: number;
     maxBytes?: number;
 }): Promise<string | undefined>;
-/** Test seam — the cache is module-level and outlives a single test. */
 export declare function __resetPreviewCache(): void;
-/**
- * Fetch up to `cap` previews, preserving input order and dropping failures.
- *
- * Bounded by BOTH a count and a cumulative byte budget: the count keeps the
- * contact sheet legible, the bytes keep the response inside Convex's 20MB
- * httpAction ceiling. Sequential rather than parallel because the budget has to
- * be spent in order — a parallel batch cannot know it has already overspent.
- */
 export declare function fetchPreviews(urls: (string | undefined)[], cap?: number, opts?: {
     timeoutMs?: number;
     maxBytes?: number;
-    /**
-     * Injected fetcher (adapter test seam / caller-owned transport). Bypasses
-     * the module cache both ways — an injected fetcher's bytes must not read
-     * from or leak into another caller's cache. Failures (undefined or throw)
-     * drop that url, matching fetchAsBase64's contract.
-     */
     fetchOne?: (url: string) => Promise<string | undefined>;
 }): Promise<string[]>;
-/** MCP tool-callback `extra` (2nd arg) — carries the per-call request `_meta`. */
 export type ToolExtra = {
     _meta?: Record<string, unknown>;
 } | undefined;
 export declare function fmtErr(err: unknown): string;
-/** Reconstruct an ApiError from a non-2xx executor response so adviseError works. */
 export declare function apiErrorFrom(res: {
     status: number;
     text: string;
@@ -123,36 +64,15 @@ export declare function apiErrorFrom(res: {
 }): ApiError;
 export declare function isOk(status: number): boolean;
 export declare function safeParse(textBody: string): unknown;
-/** Look up a generated operation by id; throws (fail-loud) if absent. */
 export declare function opById(operationId: string): GeneratedOperation;
-/** The bound zod body schema for an operation, or undefined for body-less ops. */
 export declare function bodySchemaFor(op: GeneratedOperation): z.ZodTypeAny | undefined;
-/**
- * Substitute path params into an op's template. `mapArg(opParamName)` returns the
- * concrete value (raw layer: the arg of the same name; curated layer: the friendly
- * arg mapped to this op param). Values are URL-encoded.
- */
 export declare function buildPath(op: GeneratedOperation, mapArg: (opParam: string) => unknown): string;
-/** Run an operation through the executor. `body` is sent only for bodied ops. */
-export declare function invokeOp(ex: Executor, op: GeneratedOperation, mapArg: (opParam: string) => unknown, body: unknown, 
-/** base64 PAYMENT-SIGNATURE for a paid (x402) tool call; omitted for authed calls. */
-payment?: string, 
-/** Pre-encoded query string (no leading '?') — curated queryArgs filters. */
-query?: string): Promise<{
+export declare function invokeOp(ex: Executor, op: GeneratedOperation, mapArg: (opParam: string) => unknown, body: unknown, payment?: string, query?: string): Promise<{
     status: number;
     text: string;
     requestId?: string;
 }>;
-/**
- * Run an op through the executor with x402 pay-per-call support (used by every
- * tool). Reads the client's signed payment from the tool call `_meta`, forwards
- * it as `PAYMENT-SIGNATURE` so the REST x402 middleware verifies + settles (the
- * SAME money path as a direct REST call), turns an inner 402 into a
- * payment-required result, and attaches the settle receipt on success.
- * `formatOk` builds the success result from the executor response; `label` names
- * the tool for the error message. Payment-free (key/OAuth) calls are unaffected.
- */
 export declare function dispatchOp(ex: Executor, op: GeneratedOperation, mapArg: (opParam: string) => unknown, body: unknown, extra: ToolExtra, label: string, formatOk: (res: {
     status: number;
     text: string;
-}) => ToolResult | Promise<ToolResult>): Promise<ToolResult>;
+}) => ToolResult | Promise<ToolResult>, query?: string): Promise<ToolResult>;