@slatesvideo/shared 0.6.3 → 0.6.5

package/dist/manual/index.js

@@ -0,0 +1,20 @@
+import { APP_MANUAL } from './content.js';
+export { APP_MANUAL };
+/** Return whole heading sections, never a truncated sentence or invented UI step. */
+export function appManualSections(query) {
+    if (!query?.trim())
+        return APP_MANUAL;
+    const terms = query.toLowerCase().match(/[\p{L}\p{N}]+/gu) ?? [];
+    const sections = APP_MANUAL.split(/(?=^#{1,6} )/m);
+    const ranked = sections.map((text, index) => {
+        const lower = text.toLowerCase();
+        const heading = lower.split('\n', 1)[0];
+        const score = terms.reduce((sum, term) => sum + (heading.includes(term) ? 4 : lower.includes(term) ? 1 : 0), 0);
+        return { text, index, score };
+    }).filter((s) => s.score > 0).sort((a, b) => b.score - a.score || a.index - b.index);
+    if (!ranked.length)
+        return 'No matching manual section. Available headings:\n' + sections
+            .map((s) => s.split('\n', 1)[0]).filter((s) => s.startsWith('#')).join('\n');
+    return ranked.slice(0, 5).map((s) => s.text.trim()).join('\n\n');
+}
+//# sourceMappingURL=index.js.map

package/dist/operations/index.d.ts

@@ -2,11 +2,30 @@ import { z } from 'zod';
 import { SlatesCloudClient } from '../clients/cloud.js';
 import { SlatesDesktopClient } from '../clients/desktop.js';
 import { type AspectRatio, type VideoResolution } from '../prompts/model-capabilities.js';
+import { type OrderedAttachmentRole, type ShotParams } from '../prompts/shot-spec.js';
 export interface OperationContext {
     cloud: () => SlatesCloudClient;
     desktop: () => SlatesDesktopClient;
+    /**
+     * Cancellation, propagated from the caller.
+     *
+     * 🚨 THIS IS WHAT MAKES "STOP" MEAN STOP. Escape in the desktop Studio Agent
+     * aborted the brain stream and marked the *remaining* tool calls cancelled,
+     * but the op already running got no signal at all — so a sequential batch
+     * (`slates_generate_from_shots`, the largest spender on the surface) kept
+     * firing generations after the user had cancelled. Ops that loop over items,
+     * or block on a long provider call, check it; everything else may ignore it.
+     *
+     * Optional so an older caller that does not pass one still type-checks.
+     */
+    signal?: AbortSignal;
 }
 export declare function defaultContext(): OperationContext;
+/** Thrown by an op that noticed `ctx.signal` had aborted mid-work. */
+export declare class OperationCancelledError extends Error {
+    code: string;
+    constructor(detail?: string);
+}
 export interface OperationResult {
     text: string;
     images?: Array<{
@@ -20,9 +39,118 @@ export interface Operation<I> {
     description: string;
     input: z.ZodType<I>;
     run: (input: I, ctx: OperationContext) => Promise<OperationResult>;
+    /**
+     * This op causes a provider call the user pays for.
+     *
+     * 🚨 IT IS THE DESKTOP'S CONSENT GATE, DECLARED WHERE THE OP IS WRITTEN.
+     * `slate/src/main/studio-agent/loop.ts` refuses a billable name until
+     * `present_plan` has been approved, and refreshes the balance-derived spend
+     * after each one so the deviation pause can fire. That list used to live only
+     * in the desktop, one repo away from the op it gated — and both
+     * `slates_generate_audio` and `slates_generate_from_shots` shipped without an
+     * entry, so the in-app agent could spend on either with no approved plan and
+     * no ledger entry. Set it HERE, beside the description, and the desktop takes
+     * the union of this and its own list (union, so an older published package can
+     * only ever gate MORE, never less).
+     *
+     * Set it on anything that spends INDIRECTLY too —
+     * `slates_generate_from_shots` fires N generations of its own.
+     *
+     * NOT part of the tool schema: it never reaches the model, so it costs no
+     * prefix bytes.
+     */
+    billable?: boolean;
+    /**
+     * MCP tool annotations (spec 2025-06-18), emitted in ListTools.
+     *
+     * 🚨 THIS IS WHAT LETS A HOST TELL A READ FROM A DELETE. Without them a
+     * Claude Desktop or Cursor user is prompted for `slates_list_assets` exactly
+     * the way they are prompted for `slates_delete_project`, and the destructive
+     * ops get no extra warning — so every prompt looks the same and the user
+     * learns to click through all of them.
+     *
+     * Never hand-set: `annotate()` derives all four from the op id below, and
+     * `scripts/agent-surface-lockstep-check.mjs` re-derives them INDEPENDENTLY
+     * from the op's own transport verbs. A `readOnlyHint` on an op whose `run`
+     * body posts is a lie that lets a host auto-approve a mutation, so the check
+     * has to be able to catch it.
+     */
+    annotations?: OperationAnnotations;
+    /**
+     * Which tier of the desktop tool surface this op belongs to.
+     *
+     * `core` is sent on every Studio Agent turn; `extended` is deferred behind
+     * `slates_load_tools` and appended to the tool list for the rest of the run
+     * once a group loads. The MCP server registers everything as before — hosts
+     * there do their own deferral (Claude Code defers stdio tool schemas through
+     * its tool search) and a stdio server has no run to append to.
+     *
+     * Defaults to `core` when absent, so a new op is visible until someone
+     * deliberately defers it.
+     */
+    tier?: OperationTier;
+    /** The `slates_load_tools` group this op arrives in. Required on `extended`. */
+    group?: OperationGroup;
+}
+/** MCP tool annotations. All four are declared on every op — a missing hint is
+ *  indistinguishable from `false` to a host, which is the wrong default for
+ *  `destructiveHint`. */
+export interface OperationAnnotations {
+    readOnlyHint: boolean;
+    destructiveHint: boolean;
+    idempotentHint: boolean;
+    openWorldHint: boolean;
 }
+export type OperationTier = 'core' | 'extended';
+export type OperationGroup = 'library' | 'timeline' | 'admin' | 'blender';
+export declare const CONFIRM_CREDITS = 17;
+/**
+ * The desktop deviation guard's ceiling multiplier: the Studio Agent pauses and
+ * re-asks when projected generation spend exceeds the approved ledger by more
+ * than this factor.
+ *
+ * 🚨 EXPORTED BECAUSE THE NUMBER IS QUOTED DOWNSTREAM. `slates-cost-discipline`
+ * told the agent the threshold was 25% while `loop.ts` paused at 20% — a skill
+ * contradicting the code on the one number that decides whether a run stops.
+ * The skill now renders it from here through `_partials/thresholds.md`; the
+ * desktop loop imports it instead of declaring its own.
+ */
+export declare const DEVIATION_FACTOR = 1.2;
+/**
+ * Per-surface bounds and defaults.
+ *
+ * 🚨 THESE FOUR NUMBERS PER SURFACE LIVE IN THREE REPOS. A change is a
+ * three-site edit, every time:
+ *   1. HERE (`audioCostKey`, the agent's pre-flight quote)
+ *   2. `slate/src/shared/pricing.ts` → MODEL_REGISTRY `audio.durationSeconds`
+ *      (min/max/default), read by `clampAudioDuration` + `audioCreditKey`
+ *   3. `slates-api/src/lib/audio-keys.ts` → the server's fail-closed bounds
+ * `slates-api/scripts/pricing-consistency-check.mjs` §4 asserts 1 and 2 agree
+ * at EVERY value including out-of-range ones; the gate check covers 3.
+ *
+ * The MINs used to be missing here, and the clamp floor was a hardcoded 1. That
+ * made `slates_estimate_generation_cost({model:'seed-audio', duration:2})`
+ * quote a real `seed-audio-2s` price for a generation the desktop would bill as
+ * 3s and the proxy would REJECT outright. Same for an omitted duration, which
+ * quoted `seed-audio-1s` against the desktop's `seed-audio-15s`.
+ */
+export declare const SEED_AUDIO_MIN_SECONDS = 3;
+export declare const SEED_AUDIO_MAX_SECONDS = 120;
+export declare const SEED_AUDIO_DEFAULT_SECONDS = 15;
+export declare const ELEVEN_SFX_MIN_SECONDS = 1;
+export declare const ELEVEN_SFX_MAX_SECONDS = 22;
+export declare const ELEVEN_SFX_DEFAULT_SECONDS = 4;
+export declare const TTS_MODEL: "inworld-tts-2";
+export declare const TTS_BUCKET_CHARS = 250;
+export declare const TTS_MAX_CHARACTERS: number;
+export declare const TTS_BUCKET_COUNT: number;
+/** The seat's cloning spec — reference-clip bounds, the design-prompt bounds
+ *  and the workspace-wide clone rate — read from the SSOT for the same reason
+ *  as the cap: every number in it was MEASURED and lives in exactly one row. */
+export declare const TTS_VOICE_CLONE: import("../prompts/model-capabilities.js").VoiceCloneCapability;
 export declare const getWorkspaceState: Operation<{
     projectId?: string;
+    limit?: number;
 }>;
 export declare const getMe: Operation<Record<string, never>>;
 export declare const getCreditBalance: Operation<Record<string, never>>;
@@ -39,6 +167,9 @@ export declare const estimateGenerationCost: Operation<{
     model: string;
     quantity?: number;
     duration?: number;
+    /** inworld-tts-2 only — the character count of the text, which is what it
+     *  bills on. That surface has no duration dimension at all. */
+    characters?: number;
     /** The FULL union — the runtime Zod enum is generated from MODEL_CAPABILITIES
      *  and `assertVideoCapabilities` is the per-model narrowing authority. */
     videoResolution?: VideoResolution;
@@ -227,36 +358,14 @@ export declare function seedanceEditCostKey(input: {
     seedanceFace?: boolean;
     seedanceRealFace?: boolean;
 }): string;
-export declare const AUDIO_MODELS: readonly ["seed-audio", "eleven-sfx"];
+export declare const AUDIO_MODELS: readonly ["seed-audio", "eleven-sfx", "inworld-tts-2"];
 export type AudioModel = (typeof AUDIO_MODELS)[number];
-/**
- * Per-surface bounds and defaults.
- *
- * 🚨 THESE FOUR NUMBERS PER SURFACE LIVE IN THREE REPOS. A change is a
- * three-site edit, every time:
- *   1. HERE (`audioCostKey`, the agent's pre-flight quote)
- *   2. `slate/src/shared/pricing.ts` → MODEL_REGISTRY `audio.durationSeconds`
- *      (min/max/default), read by `clampAudioDuration` + `audioCreditKey`
- *   3. `slates-api/src/lib/audio-keys.ts` → the server's fail-closed bounds
- * `slates-api/scripts/pricing-consistency-check.mjs` §4 asserts 1 and 2 agree
- * at EVERY value including out-of-range ones; the gate check covers 3.
- *
- * The MINs used to be missing here, and the clamp floor was a hardcoded 1. That
- * made `slates_estimate_generation_cost({model:'seed-audio', duration:2})`
- * quote a real `seed-audio-2s` price for a generation the desktop would bill as
- * 3s and the proxy would REJECT outright. Same for an omitted duration, which
- * quoted `seed-audio-1s` against the desktop's `seed-audio-15s`.
- */
-export declare const SEED_AUDIO_MIN_SECONDS = 3;
-export declare const SEED_AUDIO_MAX_SECONDS = 120;
-export declare const SEED_AUDIO_DEFAULT_SECONDS = 15;
-export declare const ELEVEN_SFX_MIN_SECONDS = 1;
-export declare const ELEVEN_SFX_MAX_SECONDS = 22;
-export declare const ELEVEN_SFX_DEFAULT_SECONDS = 4;
 export declare function audioCostKey(input: {
     model: AudioModel;
     /** seed-audio + eleven-sfx: the REQUESTED duration in seconds (ceiled). */
     durationSeconds?: number;
+    /** inworld-tts-2 ONLY: the character count of the text being spoken. */
+    characters?: number;
 }): string;
 export declare const generateVideo: Operation<{
     prompt: string;
@@ -288,12 +397,27 @@ export declare const generateVideo: Operation<{
     background?: boolean;
     confirm?: boolean;
 }>;
+/**
+ * AGENT PARITY for the voice picker. The desktop browses stock voices by
+ * gender, accent and age and plays each one; until this op the agent could
+ * only pass a `voiceId` it had no way to discover. Disk reads on the desktop,
+ * never a vendor call — browsing is free on every surface.
+ */
+export declare const listVoices: Operation<{
+    gender?: string;
+    accent?: string;
+    age?: string;
+    query?: string;
+}>;
 export declare const generateAudio: Operation<{
     projectId: string;
     model: AudioModel;
     prompt: string;
     durationSeconds?: number;
     voice?: string;
+    voiceId?: string;
+    voiceReferenceAssetId?: string;
+    voiceDescription?: string;
     speed?: number;
     volume?: number;
     pitch?: number;
@@ -447,6 +571,7 @@ export declare const updateCharacter: Operation<{
     name?: string;
     description?: string;
     style?: string;
+    voiceAssetId?: string | null;
 }>;
 export declare const deleteCharacter: Operation<{
     characterId: string;
@@ -505,8 +630,6 @@ export declare const updateFrame: Operation<{
     assetId?: string | null;
     sceneId?: string | null;
     position?: number;
-    frameType?: 'first' | 'last' | 'ingredient' | null;
-    motionPrompt?: string | null;
 }>;
 /**
  * Batch form of `slates_update_frame`.
@@ -529,15 +652,115 @@ export declare const batchUpdateFrames: Operation<{
         assetId?: string | null;
         sceneId?: string | null;
         position?: number;
-        frameType?: 'first' | 'last' | 'ingredient' | null;
-        motionPrompt?: string | null;
     }[];
 }>;
 export declare const deleteFrame: Operation<{
     frameId: string;
 }>;
+interface ShotOpScript {
+    speaker?: string | null;
+    line?: string | null;
+    delivery?: string | null;
+    action?: string | null;
+    prop?: string | null;
+    shotSize?: string | null;
+    camera?: string | null;
+    continues?: boolean;
+}
+interface ShotOpRefs {
+    refs?: Partial<Record<OrderedAttachmentRole, string[]>>;
+    firstFrameAssetId?: string;
+    lastFrameAssetId?: string;
+    audioRefSpokenText?: string[];
+    characterIds?: string[];
+    environmentIds?: string[];
+    styleIds?: string[];
+}
+type ShotOpParams = Pick<ShotParams, 'aspectRatio' | 'duration' | 'videoResolution' | 'imageResolution' | 'gptQuality' | 'imageQuantity' | 'negativePrompt' | 'sound' | 'seedanceFace' | 'audioDurationSeconds' | 'voiceId' | 'voiceReferenceAssetId' | 'voiceDescription'> & {
+    aspectRatio?: AspectRatio;
+    videoResolution?: VideoResolution;
+    imageResolution?: '1k' | '2k' | '3k' | '4k';
+};
+export declare const createShot: Operation<ShotOpRefs & ShotOpScript & {
+    projectId: string;
+    name?: string;
+    prompt: string;
+    model?: string;
+    params?: ShotOpParams;
+    frameId?: string;
+    sceneId?: string;
+}>;
+export declare const updateShot: Operation<ShotOpRefs & ShotOpScript & {
+    shotId: string;
+    projectId: string;
+    name?: string;
+    prompt?: string;
+    model?: string;
+    params?: ShotOpParams;
+    attachFrameId?: string;
+    detachFrameId?: string;
+    posterAssetId?: string | null;
+}>;
+export declare const duplicateShot: Operation<{
+    shotId: string;
+    name?: string;
+    prompt?: string;
+    model?: string;
+    params?: ShotOpParams;
+    frameId?: string | null;
+}>;
+export declare const listShots: Operation<{
+    projectId: string;
+    storyboardId?: string;
+    frameId?: string;
+}>;
+export declare const getShot: Operation<{
+    shotId: string;
+}>;
+/**
+ * SPLIT and MERGE — the chop decision, and the only two cross-row operations on
+ * this surface.
+ *
+ * 🔑 THIS IS THE EXECUTIVE CALL, AND IT IS WHY THEY ARE OPS. *"Sometimes you
+ * might be using more dialogue in one single 30-second generation. Sometimes it
+ * might just be a 4-second generation of one line."* Merging five lines into
+ * one long take or splitting them into five short ones changes the rhythm AND
+ * the price, and the agent has to be able to re-chop what it wrote.
+ *
+ * 🚨 NEITHER EDITS TEXT AS A SIDE EFFECT. Split moves the text after a caret
+ * the caller placed; merge joins two texts at their boundary. Nothing else in
+ * either row is rewritten. That property is what keeps a finished script
+ * finished, and it is the acceptance test for anything added here later.
+ */
+export declare const splitShot: Operation<{
+    shotId: string;
+    caret?: number;
+}>;
+export declare const mergeShots: Operation<{
+    firstId: string;
+    secondId: string;
+}>;
+export declare const generateFromShots: Operation<{
+    shotIds: string[];
+    confirm?: boolean;
+}>;
 export declare const getPromptingGuide: Operation<{
     topic: string;
+    depth?: 'card' | 'full';
+    query?: string;
+}>;
+/**
+ * The one op that changes what OTHER ops are visible.
+ *
+ * 🚨 IT EXISTS BECAUSE THE SURFACE IS 112 KB AND EVERY TURN PAYS FOR ALL OF IT.
+ * The desktop Studio Agent sends `core` plus this; a group arrives when the
+ * work needs it and stays for the rest of the run. On the MCP surface every op
+ * is registered up front (a stdio server has no run to append to), so this
+ * returns the same definitions as a plain listing — useful either way, since
+ * it is also how an agent asks "what else can you do".
+ */
+export declare const loadTools: Operation<{
+    group: OperationGroup;
 }>;
 export declare const blenderStatus: Operation<Record<string, never>>;
 export declare const blenderExecute: Operation<{
@@ -563,5 +786,5 @@ export declare const blenderRenderBlocking: Operation<{
     basename?: string;
 }>;
 export declare const ALL_OPERATIONS: ReadonlyArray<Operation<unknown>>;
-export {};
+export { toolDefinitions, toolDefinition, groupFor, tierFor, OPERATION_GROUPS, GROUP_SUMMARY, type ToolDefinition } from './surface.js';
 //# sourceMappingURL=index.d.ts.map