@cueframe/kernel 0.1.1 → 0.1.2

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,35 +64,14 @@ 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;

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

@@ -2,154 +2,42 @@ export interface CuratedTool {
     name: string;
     operationId: string;
     description: string;
-    /** friendly input arg name → op path-param name (e.g. { projectId: 'id' }). */
     pathArgs?: Record<string, string>;
-    /** Optional query-string filters: arg name → one-line teaching description.
-     *  The arg name IS the query-param name; the adapter exposes each as an
-     *  optional string input and threads provided values onto the request URL.
-     *  Without this, a description teaching a filter the curated layer can't
-     *  pass returns the UNFILTERED page silently (end review 2026-07-10). */
     queryArgs?: Record<string, string>;
-    /** Format a successful JSON body. Defaults to pretty JSON. */
     okFormat?: (json: any, args: Record<string, any>) => string;
-    /** Fixed success text (204 / body-less). Takes precedence over okFormat. */
     okText?: (args: Record<string, any>) => string;
-    /**
-     * Human-facing title. Defaults to Title Case of `name` (`create_render` →
-     * "Create Render"); set explicitly only where that reads badly (`wait_job` →
-     * "Wait for Job"). Required by the Anthropic connectors and OpenAI plugin
-     * reviews — an untitled tool is flagged.
-     */
     title?: string;
-    /**
-     * MCP tool annotations — client-side hints (Langfuse pattern).
-     *
-     * OPTIONAL BECAUSE IT OVERRIDES, NOT BECAUSE IT MAY BE ABSENT: when unset,
-     * server.ts falls back to the underlying operation's method-derived
-     * annotations from the generated manifest. Set a value here only where the
-     * curated semantics differ from the HTTP verb — this file stays the semantic
-     * SSOT (only `delete_*` is destructive; `cancel_*` is idempotent, not
-     * destructive), and the generator mirrors that reasoning.
-     */
     annotations?: {
         readOnlyHint?: boolean;
         destructiveHint?: boolean;
         idempotentHint?: boolean;
         openWorldHint?: boolean;
     };
-    /**
-     * Worked input examples (K4, e2e 2026-07-17) — serialized as Anthropic
-     * `input_examples` (the AI SDK core Tool field; the provider adds the
-     * advanced-tool-use beta itself). Use to teach CADENCE the schema can't:
-     * patch-style edits over full re-emissions, batched inspection timestamps.
-     */
     inputExamples?: Array<{
         input: Record<string, unknown>;
     }>;
-    /**
-     * Maturity VISIBILITY mirror (spec 2026-07-20-client-lane-v1-launch §2.0).
-     * Execution gating is server-side (the server capability registry — the
-     * SSOT; this npm-shipped package can go stale, so it only controls listing):
-     * 'expert' hides the tool from the public listing unless the expert layer is
-     * on. Default 'stable'. Drift-gated against the server map in
-     * the backend's capabilities drift test.
-     */
     maturity?: 'stable' | 'expert';
-    /**
-     * Preview media to attach to a successful result, so the agent can SEE (or
-     * HEAR) what it is being asked to judge.
-     *
-     * The MCP surface used to convert every image to text at the boundary, so an
-     * external agent picked stock from resolution/duration/author and never saw
-     * its own previews. `urls` pulls the preview links out of the SAME JSON the
-     * text block already carries — media is purely ADDITIVE, the JSON is
-     * unchanged, and zero usable urls emits NO media block (see `withMedia`).
-     *
-     * `cap` is a TOKEN budget, not a correctness one: a contact sheet of a dozen
-     * thumbnails is the difference between an agent that can see and one that
-     * spends its whole context on a single full-size still.
-     */
     preview?: {
         urls: (json: any) => (string | undefined)[];
-        /** Static kind, or derived from the body (stock sfx returns audio). */
         kind?: 'image' | 'audio' | ((json: any) => 'image' | 'audio');
         cap?: number;
-        /**
-         * Gate on the RESPONSE: attach media only when it buys a decision.
-         * Defaults to always (a `preview_frame` still IS the answer).
-         *
-         * `search_resources` sets this because the measured default was pure waste:
-         * one session shipped 68 previews (~9.24 MB, 99.76% of the tool's bytes) of
-         * which 62 came from `limit:1` calls — a picture attached to a search that
-         * returned ONE candidate decorates a decision already made. Worse, nobody
-         * saw them: base64 blocks enter the MODEL's context, and the CLI host does
-         * not render images, so the human's first sight of any frame was the
-         * finished 3:17 render. The URL is in the text payload either way.
-         */
         attach?: (json: any) => boolean;
     };
 }
-/** Per-resource CRUD coverage. A verb is a curated tool name, or null = gap. */
 export interface ResourceCrud {
     resource: string;
     create?: string[] | null;
     read?: string[] | null;
     update?: string | null;
     delete?: string | null;
-    /** Justify any null/omitted verb so the coverage test passes knowingly. */
     notes?: Record<string, string>;
 }
 export declare function formatMediaList(json: any): string;
 export declare function formatComponentList(json: any): string;
 export declare function formatResourceCandidates(json: any): string;
-/**
- * Render a composition for reading. Verbatim JSON while it fits — that is the
- * documented contract (it is what you hand to validate_composition) — and a
- * STRUCTURAL SUMMARY when the full body would exceed what the host will accept.
- * Every clip is still listed; only the unbounded blobs (card html, caption
- * words) are elided, and the header says so explicitly. Degrading loudly beats
- * returning nothing, and beats a silent truncation that reads like the whole
- * composition.
- */
 export declare function formatComposition(json: any): string;
-/**
- * The `warnings[]` advisory channel, rendered for the reader. One idiom across
- * every verb that carries it (create_render, apply_composition) so an agent
- * learns to look for `⚠` exactly once.
- */
 export declare function formatWarnings(json: any): string;
 export declare const CURATED_TOOLS: CuratedTool[];
-/**
- * THE editor allowlist — the ONE tool vocabulary an editing agent speaks,
- * whichever side of the Executor seam it runs on (the Convex editor agent over
- * the platform executor; the desktop agent over the local one). Passed as
- * `buildCuratedToolSet(executor, { allowedNames: INTERNAL_EDITOR_TOOLS })`, so
- * every name here MUST resolve in `[...INTERNAL_LOOP_TOOLS, ...CURATED_TOOLS]` —
- * the builder SILENTLY SKIPS an unknown name (adapter.ts), which is how a
- * renamed tool becomes a quietly missing capability. curation.test.ts gates the
- * subset relation; the web editor agent re-checks at module
- * load so the failure is loud at boot, not at the turn that needed the tool.
- *
- * INTERNAL, as in "not the hosted MCP server's list": three of these
- * (`get_context`, `search_library`, `analyze_transcript`) live in
- * INTERNAL_LOOP_TOOLS precisely so they stay OFF that server, and `wait_job` is
- * registered there by its own procedure. Membership here is NOT publication.
- */
 export declare const INTERNAL_EDITOR_TOOLS: readonly string[];
-/**
- * Resources whose CRUD is INTENTIONALLY incomplete because the backend op does
- * not exist yet. The coverage gate treats `${resource}.${verb}` keys here as a
- * documented absence — but `known backend gaps are real` in curation.test.ts
- * also asserts no generated op exists for them, so a gap CANNOT silently linger
- * after a backend route ships: the day the op appears, curate it and DELETE the
- * key. These are follow-up specs, not permanent design.
- */
 export declare const KNOWN_BACKEND_GAPS: Set<string>;
-/**
- * Per-resource CRUD coverage map — completeness as an invariant. The coverage
- * tests in curation.test.ts gate this: every referenced tool must be a real
- * CURATED_TOOLS name, and every absent verb must be either curated, justified
- * in `notes`, or a KNOWN_BACKEND_GAPS entry. It fails loud the day a curated
- * tool references a renamed op or a new resource verb lands unjustified.
- */
 export declare const CRUD_COVERAGE: ResourceCrud[];

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

@@ -1,60 +1,11 @@
-/**
- * Network `Executor` factory + the public API base-URL table.
- *
- * Extracted from ./index.ts so it is importable WITHOUT triggering the stdio
- * boot: ./index.ts runs `await main()` at module top-level (outside VITEST), so
- * importing the barrel from a long-running service (e.g. the Director worker,
- * Subsystem 3) would try to open a StdioServerTransport. This module carries
- * only the pure factory + the URL table, so the Director imports it (and the
- * `./adapter` / `./core` subpaths) with no boot side effect. ./index.ts
- * re-exports `makeNetworkExecutor` so the stdio entry API is unchanged.
- */
 import { type Executor } from './core.js';
-/** Public API hosts by target. `baseUrl` carries no `/v1` — paths are `/v1/…`-prefixed. */
 export declare const API_URLS: Record<string, string>;
-/**
- * Network executor: one bearer token, one base URL (single-tenant). `baseUrl`
- * carries no `/v1` — the manifest pathTemplate is `/v1/…`-prefixed, so
- * `baseUrl + path` is the correct single-`/v1` URL.
- */
 export declare function makeNetworkExecutor(baseUrl: string, apiKey: string): Executor;
-/**
- * Platform executor: CueFrame's OWN internal services (the Director) drive the
- * public /v1 tools as the PLATFORM — the deploy key + an explicit target org —
- * instead of a per-client `Bearer <apiKey>`. One privileged identity, org as a
- * per-call header (`x-org-id`); the `/v1` auth middleware verifies the deploy key
- * server-side (timing-safe) and treats these as internal (billing/rate-limit
- * skipped). No per-run credential lifecycle — the run builds this in one line.
- */
-/**
- * Session executor — the EDITOR clients' transport (unified-surface spec's
- * cloud leg): web + signed-in desktop drive /v1 with the Better Auth SESSION
- * as Bearer (the same credential class `cueframe login` uses; billed like any
- * customer identity). No API key, no deploy key, nothing stored beyond the
- * session the client already holds.
- *
- * Contracts:
- *  - OFFLINE-ABSENCE: a null token yields a synthetic
- *    `{status:0, error.code:"offline"}` WITHOUT a network round-trip —
- *    consumers render cloud capabilities as ABSENT, never as error stubs.
- *  - Idempotency: mutations carry the same content-derived key as the
- *    platform executor, so a retried mutation dedups instead of repeating.
- *  - X-Client-Version: every request states its build, so requestLog can
- *    answer "who breaks if this changes" before /v1 evolves.
- *  - Retry: idempotent GETs retry ONCE on network failure; mutations never
- *    auto-retry (the key makes a caller-driven retry safe).
- */
 export declare function makeSessionExecutor(opts: {
     baseUrl: string;
     getToken: () => Promise<string | null>;
     clientVersion: string;
 }): Executor;
 export declare function makePlatformExecutor(baseUrl: string, deployKey: string, orgId: string, opts?: {
-    /**
-     * Bill this traffic to the org AS this user (X-Acting-User-Id →
-     * auth.delegated). Set by user-facing agent surfaces (editor/clips chat);
-     * omitted by internal execution (Director in-loop — already paid at the
-     * compose terminal).
-     */
     actingUserId?: string;
 }): Executor;

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

@@ -1,7 +1 @@
-/**
- * Tiny shared formatting helpers, server-free so both server.ts and the
- * curation SSOT (curation.ts) can import them without a circular dependency
- * and without pulling in the MCP transport.
- */
-/** Format seconds as `M:SS` (e.g. 75 → "1:15"). */
 export declare function fmtClock(sec: number): string;

package/dist/_members/mcp/generated/catalogPreviews.d.ts

@@ -1,2 +1 @@
-/** Catalog primitive id → published poster still (https://cdn.cueframe.ai). */
 export declare const CATALOG_PREVIEWS: Record<string, string>;

package/dist/_members/mcp/generated/operations.d.ts

@@ -1,16 +1,3 @@
-/**
- * AUTO-GENERATED — do not edit by hand.
- *
- * Source: docs/api/openapi.json
- * Generator: packages/mcp/scripts/generate-tools.mjs
- * Re-run: `pnpm generate:mcp-tools` from the repo root.
- *
- * Transport-agnostic operation manifest. One entry per OpenAPI operation;
- * consumed by the generic raw-tool registrar and the curated tools (for paths)
- * in src/server.ts, executed through the per-transport Executor. CI fails if
- * this file drifts from the current spec.
- */
-/** MCP tool annotations — client-side hints. See the MCP spec's ToolAnnotations. */
 export interface GeneratedAnnotations {
     readOnlyHint: boolean;
     destructiveHint?: boolean;
@@ -18,24 +5,14 @@ export interface GeneratedAnnotations {
     openWorldHint: boolean;
 }
 export interface GeneratedOperation {
-    /** OpenAPI operationId, e.g. "createCompose". */
     operationId: string;
-    /** Raw MCP tool name, e.g. "cueframe_api_createCompose". */
     toolName: string;
-    /** Human-facing title, e.g. "Create Compose". Required by directory reviews. */
     title: string;
-    /** HTTP method, upper-case. */
     method: string;
-    /** Spec path, /v1-prefixed, e.g. "/v1/projects/{id}/compose". */
     pathTemplate: string;
-    /** Path parameter names in declaration order, e.g. ["id"]. */
     pathParams: string[];
-    /** bodySchemas key for the request body, or null for body-less ops. */
     bodyKey: string | null;
-    /** Human/agent-facing description (raw expert layer). */
     description: string;
-    /** Method-derived client hints. Curated entries may override (curation.ts). */
     annotations: GeneratedAnnotations;
 }
-/** 116 operations derived from docs/api/openapi.json. */
 export declare const GENERATED_OPERATIONS: GeneratedOperation[];

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

@@ -1,25 +1,2 @@
-/**
- * INTERNAL in-loop tool registry (A11/A12: the director's in-loop tool names
- * are internal names, exempt from the client-surface rename story).
- *
- * The 2026-07 verb cutover removed the SESSION-SCOPED ops from the public curated
- * surface. But the DIRECTOR's own author/designer loops kept running against a real
- * session — `pathArgs: { projectId, sessionId }` — and THAT is what gave "render this
- * composition at time T" two implementations chosen by caller identity: the agent could
- * not physically address the stateless path, because every sighted tool it had was
- * session-addressed.
- *
- * They are sessionless now, and it needed no new endpoints: these ops already took
- * `body.composition`, so the agent was always sending the very thing it wanted rendered.
- * The `sessionId` in the path never carried composition state — it carried a BOX.
- * Dropping it means the Director's loop and the public API run the ONE seam
- * (bake → stateless capture), and the agent's stills are the SAME content-addressed R2
- * objects the judge grades — so it can no longer be scored on frames it never saw.
- *
- * `commit_session` stays session-addressed: it promotes the run's SCRATCH composition
- * (a real Convex composition row) to active. That scratch is composition versioning, not
- * a box — candidate isolation is a product requirement (only the winner saves), and it
- * survives the box's removal untouched.
- */
 import type { CuratedTool } from './curation.js';
 export declare const INTERNAL_LOOP_TOOLS: CuratedTool[];

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

@@ -1,22 +1,6 @@
-/**
- * Skills-as-prompts.
- *
- * Each published SKILL.md becomes an MCP *prompt*: metadata registered up front,
- * full markdown fetched on demand. SKILL.md stays the single source of truth.
- * Executed through the transport's `Executor` (stdio: network; hosted: in-process)
- * against the public skills ops from the generated manifest.
- *
- * The skill LIST is memoized at module scope so the hosted per-request server
- * doesn't re-fetch it on every request (a warm isolate populates it once).
- *
- * `failLoud`: stdio sets it (boot once — a missing skills API means a broken
- * server, surface it). Hosted leaves it false — a transient skills hiccup must
- * NOT break an unrelated tool call; prompts are simply skipped that request.
- */
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { type Executor } from './core.js';
 export declare function registerSkillPrompts(server: McpServer, ex: Executor, opts?: {
     failLoud?: boolean;
 }): Promise<void>;
-/** Test seam — reset the memoized skill list. */
 export declare function __resetSkillCache(): void;

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

@@ -1,16 +1,3 @@
-/**
- * CueFrame MCP resources — the read side of the surface (no side effects).
- *
- * Every read endpoint is a URI-addressed MCP *resource*, executed through the
- * transport's `Executor` (stdio: network; hosted: in-process) against the GET
- * op's path from the generated manifest — the SAME single source of truth the
- * tools use, so paths are never hand-maintained. Four templates (media,
- * component, project, brand-kit) also carry a `list` callback so resources/list
- * enumerates concrete instances via the matching list op.
- *
- * Fail-loud: a non-2xx read throws, which the MCP server surfaces as a JSON-RPC
- * error (no try/catch swallow).
- */
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { type Executor } from './core.js';
 export declare function registerResources(server: McpServer, ex: Executor): void;

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

@@ -1,69 +1,19 @@
-/**
- * CueFrame MCP — transport-agnostic core. NO transport import lives here, so
- * both the stdio entry (index.ts) and the hosted Hono route
- * (the hosted MCP route) build their server from this one module.
- *
- * Layers (all execute through the injected `Executor`, paths from the generated
- * manifest — single source of truth, drift-gated):
- *   - curated front-door  → registerCuratedTools  (hand-picked names + guidance)
- *   - raw expert layer    → registerRawTools      (generic, one tool per op)
- *   - read resources      → registerResources     (resources.ts)
- *   - skills-as-prompts   → registerSkillPrompts   (prompts.ts; async, by caller)
- */
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { type Executor } from './core.js';
 export { registerSkillPrompts, __resetSkillCache } from './prompts.js';
 export { SERVER_INSTRUCTIONS } from './generated/harness.js';
 export type { Executor } from './core.js';
-/**
- * Transport-agnostic telemetry contract. The core emits; the TRANSPORT decides
- * where it lands (the hosted Convex route ships these to PostHog; stdio passes
- * no sink and pays nothing). Keeping this a plain callback is what lets the
- * package stay free of any analytics dependency.
- */
-/**
- * A completed tool call. No `errorKind`: every handler here already converts a
- * throw into an `isError` result before the wrapper sees it, so a thrown-error
- * class could never be populated — it would be a permanently-null column.
- */
 export type McpTelemetryEvent = {
     tool: string;
     isError: boolean;
-    /**
-     * Preview-attachment outcome, when the tool carries media. `urls` is what the
-     * extractor found in the response; `fetched` is how many actually encoded.
-     *
-     * This rides the SINK, not console.log: the core stays transport-agnostic (it
-     * also ships as a stdio npm package with no Convex in scope), and the hosted
-     * route decides where it lands. urls>0 with fetched===0 is the signature of a
-     * runtime-level failure — it is how the Buffer-in-Convex crash was finally
-     * found, after being invisible behind a silent catch.
-     */
     preview?: {
         urls: number;
         fetched: number;
     };
 };
 export type McpTelemetrySink = (event: McpTelemetryEvent) => void;
-/**
- * Operations the RAW expert layer must not register, even though they are in the
- * manifest. This is a raw-layer property, not a manifest one: the manifest is the
- * transport-agnostic op SSOT the CURATED layer resolves paths through (`opById`),
- * so an op dropped from it becomes uncuratable.
- *
- * `searchLibrary` — the raw registrar builds its inputSchema from path params +
- * the request body only, and every argument of GET /v1/media/search is a QUERY
- * param. `q` is REQUIRED, so the raw tool could not send it and would 400 on
- * every call — worse than absent, because an agent reads that 400 as "the
- * feature is broken". The working surface is the curated `search_library`
- * (internalLoopTools.ts) whose `queryArgs` the adapter threads onto the URL.
- * DELETE this entry once the generator + this registrar thread query params
- * (internal issue 2026-08-07 — the Executor
- * already carries `query`).
- */
 export declare const RAW_EXCLUDED_OPERATION_IDS: ReadonlySet<string>;
 export declare function registerRawTools(server: McpServer, ex: Executor, onEvent?: McpTelemetrySink): void;
-/** `create_render` → "Create Render". Default title for a curated tool. */
 export declare function titleCase(name: string): string;
 export declare function registerCuratedTools(server: McpServer, ex: Executor, opts?: {
     waitCapMs?: number;
@@ -72,21 +22,10 @@ export declare function registerCuratedTools(server: McpServer, ex: Executor, op
 }): void;
 export interface BuildServerOpts {
     executor: Executor;
-    /** Expose the raw `cueframe_api_*` expert layer (one tool per operation). */
     expert?: boolean;
-    /** SERVER_INSTRUCTIONS harness, if any. */
     instructions?: string;
-    /** Cap wait_job blocking (ms). Hosted transports set this under the Convex
-     * httpAction limit; stdio leaves it unset (30-min default applies). */
     waitCapMs?: number;
-    /** Optional telemetry sink. Omitted on stdio; the hosted route supplies one
-     * so agent discovery (initialize) and tool usage are measurable. */
     onEvent?: McpTelemetrySink;
 }
 export declare function buildServer(opts: BuildServerOpts): McpServer;
-/**
- * A12 burned names: each dead verb registers as a TOMBSTONE — calling it
- * hard-errors with the replacement instead of a bare method-not-found, so an
- * agent with a stale memory of the surface gets re-taught in one round-trip.
- */
 export declare function registerBurnedTombstones(server: McpServer, onEvent?: McpTelemetrySink): void;

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

@@ -1,37 +1,15 @@
-/**
- * `wait_job` — block until a long-running job reaches a terminal state, by
- * POLLING its status endpoint through the Executor. Unified across transports:
- * the same poll loop works for stdio (network) and hosted (in-process), so the
- * blocking-SSE path is gone (the agent only ever sees the terminal result, so
- * polling is functionally equivalent; `create_webhook` is the event-driven path
- * for fan-out). Pure + side-effect-free (clock/sleep injectable) so it unit-tests
- * without a server.
- */
 import { type Executor } from './core.js';
 export type WaitResult = {
     ok: boolean;
     text: string;
-    /** True when the wait window expired with the job still running — a
-     *  CONTINUATION, not an error: the caller re-invokes wait_job to keep
-     *  waiting (bounded long-poll; plan 2026-07-06-bounded-api-jobs). */
     stillRunning?: boolean;
-    /** Image urls to attach as MCP image blocks. An async tool's pixels arrive at
-     *  wait_job, not at the enqueue call, so this is where they must surface —
-     *  preview_component's own 202 carries only a jobId. Same treatment
-     *  adapter.ts:578 already gives this url on the ai-SDK path. */
     mediaUrls?: string[];
 };
 export type WaitKind = 'render' | 'compose' | 'suggestions' | 'verify' | 'preview' | 'brand_kit_extract' | 'consult';
 export interface WaitDeps {
     sleep?: (ms: number) => Promise<void>;
     now?: () => number;
-    /** Poll interval; overridable for fast tests. */
     pollMs?: number;
-    /** Reserved headroom for one status invoke (overshoot guard); test override. */
     invokeBudgetMs?: number;
 }
-/**
- * Poll a job's status op until terminal or the deadline. 4xx → fail loud
- * immediately; 5xx/transient → keep polling; 2xx non-terminal → sleep + retry.
- */
 export declare function waitForJob(ex: Executor, kind: WaitKind, id: string, projectId: string | undefined, deadline: number, deps?: WaitDeps): Promise<WaitResult>;