@vgai/sdk 0.5.0 → 0.5.2

package/package.json

@@ -2,7 +2,7 @@
   "name": "@vgai/sdk",
   "author": "Volter AI, Inc.",
   "license": "Apache-2.0",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "type": "module",
   "repository": {
     "type": "git",
@@ -27,7 +27,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@vgai/engine": "0.5.0",
+    "@vgai/engine": "0.5.2",
     "playwright": "^1.58.2",
     "zod": "^4.3.6"
   }

package/src/account.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 
-export const AccountModeSchema = z.enum(['mock', 'live']);
+// Which account backend this session is signed into: the zero-charge in-process mock control plane, or the live VGAI account service. NOT a generation switch — generation execution routes (mock/managed/byok) are chosen per call; see preferredRoute for the UI default.
+export const AccountBackendSchema = z.enum(['mock', 'live']);
 export const AccountPlanSchema = z.object({
   id: z.string().min(1),
   name: z.string().min(1),
@@ -47,10 +48,10 @@ export const AccountUsageEntrySchema = z.object({
   externalId: z.string().optional(),
 });
 export const AccountSnapshotSchema = z.discriminatedUnion('authenticated', [
-  z.object({ authenticated: z.literal(false), mode: AccountModeSchema }),
+  z.object({ authenticated: z.literal(false), backend: AccountBackendSchema }),
   z.object({
     authenticated: z.literal(true),
-    mode: AccountModeSchema,
+    backend: AccountBackendSchema,
     user: AccountUserSchema,
     plan: AccountPlanSchema,
     credits: AccountCreditsSchema,
@@ -83,7 +84,7 @@ export const ProviderCredentialTestResultSchema = z.object({
   testedAt: z.string().datetime(),
 });
 
-export type AccountMode = z.infer<typeof AccountModeSchema>;
+export type AccountBackend = z.infer<typeof AccountBackendSchema>;
 export type AccountPlan = z.infer<typeof AccountPlanSchema>;
 export type AccountCredits = z.infer<typeof AccountCreditsSchema>;
 export type AccountSpendPolicy = z.infer<typeof AccountSpendPolicySchema>;

package/src/cinematic/capabilities-operations.ts

@@ -27,7 +27,7 @@
  */
 
 import { z } from 'zod';
-import { defineOperation, type OperationRegistry } from '../registry.js';
+import { defineTool, type ToolRegistry } from '../registry.js';
 import { checkFfmpegCapability } from '../render/capabilities/ffmpeg.js';
 
 const BinaryCapability = z.discriminatedUnion('ok', [
@@ -76,7 +76,7 @@ const DECLARED_FORMATS = [
   { format: 'png' as const, alpha: true },
 ];
 
-export const cinematicCapabilities = defineOperation({
+export const cinematicCapabilities = defineTool({
   name: 'cinematic.capabilities',
   summary:
     'Report ffmpeg/ffprobe capture capability and the render pipeline’s declared codec/format support.',
@@ -123,6 +123,6 @@ export const cinematicCapabilities = defineOperation({
 });
 
 /** Register cinematic.capabilities onto `registry`. */
-export function registerCapabilitiesOperations(registry: OperationRegistry): void {
+export function registerCapabilitiesOperations(registry: ToolRegistry): void {
   registry.register(cinematicCapabilities);
 }

package/src/cinematic/cue-operations.ts

@@ -24,12 +24,12 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { isAbsolute, join } from 'node:path';
 import { z } from 'zod';
-import { OperationError } from '../errors.js';
-import { defineOperation, type ErrorDefinition, type OperationRegistry } from '../registry.js';
-import type { OperationContext } from '../types.js';
+import { ToolError } from '../errors.js';
+import { defineTool, type ToolErrorDefinition, type ToolRegistry } from '../registry.js';
+import type { ToolContext } from '../types.js';
 import { NO_ROOT_ERROR } from './theatre-operations.js';
 
-export const CUE_FILE_NOT_FOUND_ERROR: ErrorDefinition = {
+export const CUE_FILE_NOT_FOUND_ERROR: ToolErrorDefinition = {
   code: 'FILE_NOT_FOUND',
   summary: 'The referenced cue module file does not exist on disk.',
   data: z.object({ path: z.string() }),
@@ -71,22 +71,22 @@ const CueSourceInput = z.object({
     .describe('Base directory for a relative `path`. Defaults to ctx.projectRoot.'),
 });
 
-function resolveSource(input: z.infer<typeof CueSourceInput>, ctx: OperationContext): string {
+function resolveSource(input: z.infer<typeof CueSourceInput>, ctx: ToolContext): string {
   if (input.source !== undefined) return input.source;
   if (input.path === undefined) {
-    throw new OperationError('BAD_INPUT', 'One of `source` or `path` must be given.', {});
+    throw new ToolError('BAD_INPUT', 'One of `source` or `path` must be given.', {});
   }
   const root = input.root ?? ctx.projectRoot;
   const absPath = isAbsolute(input.path) ? input.path : root ? join(root, input.path) : undefined;
   if (!absPath) {
-    throw new OperationError(
+    throw new ToolError(
       'NO_ROOT',
       'A relative `path` was given but neither `root` nor ctx.projectRoot is available.',
       {},
     );
   }
   if (!existsSync(absPath)) {
-    throw new OperationError('FILE_NOT_FOUND', `File not found: ${absPath}`, { path: absPath });
+    throw new ToolError('FILE_NOT_FOUND', `File not found: ${absPath}`, { path: absPath });
   }
   return readFileSync(absPath, 'utf-8');
 }
@@ -103,7 +103,7 @@ const CinematicCueListResult = z.object({
     .describe('Every {id, time} pair found, in source declaration order.'),
 });
 
-export const cinematicCueList = defineOperation({
+export const cinematicCueList = defineTool({
   name: 'cinematic.cue.list',
   summary: 'Best-effort static list of {id, time} cue entries in a TypeScript cue module.',
   description:
@@ -137,7 +137,7 @@ const CinematicCueValidateResult = z.object({
   cues: z.array(HeuristicCueSchema),
 });
 
-export const cinematicCueValidate = defineOperation({
+export const cinematicCueValidate = defineTool({
   name: 'cinematic.cue.validate',
   summary:
     'Validate unique cue IDs and ascending time ordering for the cues found by cinematic.cue.list’s ' +
@@ -192,7 +192,7 @@ export const cinematicCueValidate = defineOperation({
 });
 
 /** Register cinematic.cue.list / cinematic.cue.validate onto `registry`. */
-export function registerCueOperations(registry: OperationRegistry): void {
+export function registerCueOperations(registry: ToolRegistry): void {
   registry.register(cinematicCueList);
   registry.register(cinematicCueValidate);
 }

package/src/cinematic/gsap-operations.ts

@@ -25,9 +25,9 @@
 import { readFileSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { z } from 'zod';
-import { OperationError } from '../errors.js';
+import { ToolError } from '../errors.js';
 import { listProjectFiles } from '../project/shared.js';
-import { defineOperation, type OperationRegistry } from '../registry.js';
+import { defineTool, type ToolRegistry } from '../registry.js';
 import { NO_ROOT_ERROR } from './theatre-operations.js';
 
 /** True when the file text looks like it registers a GSAP timeline for deterministic scrub/export. */
@@ -70,7 +70,7 @@ const CinematicGsapInspectResult = z.object({
     .describe('Every *.ts/*.tsx file whose text imports gsap-registration, sorted by path.'),
 });
 
-export const cinematicGsapInspect = defineOperation({
+export const cinematicGsapInspect = defineTool({
   name: 'cinematic.gsap.inspect',
   summary:
     'Best-effort static discovery of source files that call registerGsap(...) to register a ' +
@@ -90,7 +90,7 @@ export const cinematicGsapInspect = defineOperation({
   async impl(input, ctx) {
     const root = input.root ?? ctx.projectRoot;
     if (!root) {
-      throw new OperationError(
+      throw new ToolError(
         'NO_ROOT',
         'Neither an explicit `root` input nor ctx.projectRoot was given.',
         {},
@@ -121,6 +121,6 @@ export const cinematicGsapInspect = defineOperation({
 });
 
 /** Register cinematic.gsap.inspect onto `registry`. */
-export function registerGsapOperations(registry: OperationRegistry): void {
+export function registerGsapOperations(registry: ToolRegistry): void {
   registry.register(cinematicGsapInspect);
 }

package/src/cinematic/index.ts

@@ -1,7 +1,7 @@
 /**
  * B5 — `cinematic.*` operations
  * (docs/AI-NATIVE-AUTHORING-IMPLEMENTATION-SPEC.md §8 B5). Registered
- * separately from B1's `registerBuiltinOperations` (`../operations.ts`),
+ * separately from B1's `registerBuiltinTools` (`../operations.ts`),
  * B2's `registerProjectOperations` (`../project/index.ts`), B3's
  * `registerEditorOperations` (`../editor/index.ts`), and B4's
  * `registerPlayOperations` (`../play/index.ts`) — the default `operations`
@@ -40,7 +40,7 @@ export {
 } from './render-transport.js';
 export * from './theatre-operations.js';
 
-import type { OperationRegistry } from '../registry.js';
+import type { ToolRegistry } from '../registry.js';
 import { registerCapabilitiesOperations } from './capabilities-operations.js';
 import { registerCueOperations } from './cue-operations.js';
 import { registerGsapOperations } from './gsap-operations.js';
@@ -49,7 +49,7 @@ import { registerRenderOperations } from './render-operations.js';
 import { registerTheatreOperations } from './theatre-operations.js';
 
 /** Register every B5 `cinematic.*` operation onto `registry`. */
-export function registerCinematicOperations(registry: OperationRegistry): void {
+export function registerCinematicOperations(registry: ToolRegistry): void {
   registerTheatreOperations(registry);
   registerCueOperations(registry);
   registerGsapOperations(registry);

package/src/cinematic/preview-operations.ts

@@ -14,8 +14,8 @@
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { z } from 'zod';
-import { OperationError } from '../errors.js';
-import { defineOperation, type ErrorDefinition, type OperationRegistry } from '../registry.js';
+import { ToolError } from '../errors.js';
+import { defineTool, type ToolErrorDefinition, type ToolRegistry } from '../registry.js';
 import {
   createPreviewSession,
   getCinematicOpenPreviewFn,
@@ -25,7 +25,7 @@ import {
   stopPreviewSession,
 } from './preview-transport.js';
 
-const PREVIEW_SESSION_NOT_FOUND_ERROR: ErrorDefinition = {
+const PREVIEW_SESSION_NOT_FOUND_ERROR: ToolErrorDefinition = {
   code: 'PREVIEW_SESSION_NOT_FOUND',
   summary:
     'No open preview session with the given previewId exists (this process’s in-memory registry).',
@@ -67,7 +67,7 @@ function stateOf(session: {
 function requireSession(previewId: string) {
   const session = getPreviewSession(previewId);
   if (!session) {
-    throw new OperationError(
+    throw new ToolError(
       'PREVIEW_SESSION_NOT_FOUND',
       `No open preview session "${previewId}".`,
       { previewId },
@@ -113,7 +113,7 @@ const CinematicPreviewInput = z.object({
   playbackRate: z.number().positive().optional().describe('Autoplay speed multiplier. Default 1.'),
 });
 
-export const cinematicPreview = defineOperation({
+export const cinematicPreview = defineTool({
   name: 'cinematic.preview',
   summary:
     'Open a headless preview session against a render-control-mode page and (by default) start playing it.',
@@ -180,7 +180,7 @@ export const cinematicPreview = defineOperation({
 
 const PreviewIdInput = z.object({ previewId: z.string() });
 
-export const cinematicPause = defineOperation({
+export const cinematicPause = defineTool({
   name: 'cinematic.pause',
   summary: 'Stop a preview session’s autoplay loop without closing it.',
   description:
@@ -214,7 +214,7 @@ const CinematicSeekInput = z.object({
   frame: z.number().int().min(0).optional().describe('Seek to this exact frame index.'),
 });
 
-export const cinematicSeek = defineOperation({
+export const cinematicSeek = defineTool({
   name: 'cinematic.seek',
   summary: 'Seek a preview session to an exact time or frame.',
   description:
@@ -238,7 +238,7 @@ export const cinematicSeek = defineOperation({
   async impl(input) {
     const session = requireSession(input.previewId);
     if ((input.time === undefined) === (input.frame === undefined)) {
-      throw new OperationError('BAD_INPUT', 'Supply exactly one of time or frame.', {});
+      throw new ToolError('BAD_INPUT', 'Supply exactly one of time or frame.', {});
     }
     const frame = input.frame ?? Math.round(input.time! * session.handle.fps);
     await seekPreviewSession(session, frame);
@@ -250,7 +250,7 @@ export const cinematicSeek = defineOperation({
 // cinematic.stop
 // ---------------------------------------------------------------------------
 
-export const cinematicStop = defineOperation({
+export const cinematicStop = defineTool({
   name: 'cinematic.stop',
   summary: 'Close a preview session (its page/browser) and forget it.',
   description:
@@ -271,7 +271,7 @@ export const cinematicStop = defineOperation({
 });
 
 /** Register cinematic.preview / .pause / .seek / .stop onto `registry`. */
-export function registerPreviewOperations(registry: OperationRegistry): void {
+export function registerPreviewOperations(registry: ToolRegistry): void {
   registry.register(cinematicPreview);
   registry.register(cinematicPause);
   registry.register(cinematicSeek);

package/src/cinematic/preview-transport.ts

@@ -42,7 +42,7 @@
 
 import type { RenderCinematicRequest } from '../render/render-cinematic.js';
 import { openRenderCinematicPage } from '../render/render-cinematic.js';
-import type { OperationContext } from '../types.js';
+import type { ToolContext } from '../types.js';
 
 /** The narrow surface preview sessions need — deliberately NOT Playwright's `Page` (see module jsdoc). */
 export interface CinematicPreviewHandle {
@@ -96,7 +96,7 @@ async function openRealPreviewHandle(
 }
 
 /** Resolve the preview-page opener to use: `ctx['cinematicOpenPreviewFn']` when injected (tests), else the real launcher. */
-export function getCinematicOpenPreviewFn(ctx: OperationContext): CinematicOpenPreviewFn {
+export function getCinematicOpenPreviewFn(ctx: ToolContext): CinematicOpenPreviewFn {
   const injected = ctx['cinematicOpenPreviewFn'];
   return (injected as CinematicOpenPreviewFn | undefined) ?? openRealPreviewHandle;
 }

package/src/cinematic/render-operations.ts

@@ -16,8 +16,8 @@
  */
 
 import { z } from 'zod';
-import { OperationError } from '../errors.js';
-import { defineOperation, type ErrorDefinition, type OperationRegistry } from '../registry.js';
+import { ToolError } from '../errors.js';
+import { defineTool, type ToolErrorDefinition, type ToolRegistry } from '../registry.js';
 import {
   RenderCinematicFfmpegError,
   type RenderCinematicRequest,
@@ -34,7 +34,7 @@ import {
 // Shared error definitions
 // ---------------------------------------------------------------------------
 
-const RENDER_REQUEST_INVALID_ERROR: ErrorDefinition = {
+const RENDER_REQUEST_INVALID_ERROR: ToolErrorDefinition = {
   code: 'RENDER_REQUEST_INVALID',
   summary:
     'The render request failed validation (I1 AC: "fail before launching the browser") — no job ' +
@@ -42,19 +42,19 @@ const RENDER_REQUEST_INVALID_ERROR: ErrorDefinition = {
   data: z.object({ message: z.string() }),
 };
 
-const RENDER_CAPABILITY_UNAVAILABLE_ERROR: ErrorDefinition = {
+const RENDER_CAPABILITY_UNAVAILABLE_ERROR: ToolErrorDefinition = {
   code: 'RENDER_CAPABILITY_UNAVAILABLE',
   summary: 'ffmpeg/ffprobe preflight failed (A1) — no job was created.',
   data: z.object({ message: z.string() }),
 };
 
-const RENDER_JOB_NOT_FOUND_ERROR: ErrorDefinition = {
+const RENDER_JOB_NOT_FOUND_ERROR: ToolErrorDefinition = {
   code: 'RENDER_JOB_NOT_FOUND',
   summary: 'No render job with the given jobId exists (this process’s in-memory job registry).',
   data: z.object({ jobId: z.string() }),
 };
 
-const RENDER_JOB_NOT_RUNNING_ERROR: ErrorDefinition = {
+const RENDER_JOB_NOT_RUNNING_ERROR: ToolErrorDefinition = {
   code: 'RENDER_JOB_NOT_RUNNING',
   summary: 'The job has already settled (completed/failed/cancelled) — nothing to cancel.',
   data: z.object({ jobId: z.string(), status: z.string() }),
@@ -255,7 +255,7 @@ function toRenderCinematicRequest(
 // cinematic.render
 // ---------------------------------------------------------------------------
 
-export const cinematicRender = defineOperation({
+export const cinematicRender = defineTool({
   name: 'cinematic.render',
   summary: 'Render a Theatre-driven cinematic sequence to a video or frame-sequence artifact.',
   description:
@@ -285,10 +285,10 @@ export const cinematicRender = defineOperation({
       job = startRenderJob(toRenderCinematicRequest(input), renderFn);
     } catch (err) {
       if (err instanceof RenderCinematicRequestError) {
-        throw new OperationError('RENDER_REQUEST_INVALID', err.message, { message: err.message });
+        throw new ToolError('RENDER_REQUEST_INVALID', err.message, { message: err.message });
       }
       if (err instanceof RenderCinematicFfmpegError) {
-        throw new OperationError('RENDER_CAPABILITY_UNAVAILABLE', err.message, {
+        throw new ToolError('RENDER_CAPABILITY_UNAVAILABLE', err.message, {
           message: err.message,
         });
       }
@@ -309,7 +309,7 @@ export const cinematicRender = defineOperation({
 
 const CinematicRenderStatusInput = z.object({ jobId: z.string() });
 
-export const cinematicRenderStatus = defineOperation({
+export const cinematicRenderStatus = defineTool({
   name: 'cinematic.render.status',
   summary: 'Poll a cinematic.render job’s progress, current frame, elapsed time, and output paths.',
   description:
@@ -327,7 +327,7 @@ export const cinematicRenderStatus = defineOperation({
   async impl(input) {
     const job = getRenderJob(input.jobId);
     if (!job) {
-      throw new OperationError('RENDER_JOB_NOT_FOUND', `No render job "${input.jobId}".`, {
+      throw new ToolError('RENDER_JOB_NOT_FOUND', `No render job "${input.jobId}".`, {
         jobId: input.jobId,
       });
     }
@@ -339,7 +339,7 @@ export const cinematicRenderStatus = defineOperation({
 // cinematic.render.cancel
 // ---------------------------------------------------------------------------
 
-export const cinematicRenderCancel = defineOperation({
+export const cinematicRenderCancel = defineTool({
   name: 'cinematic.render.cancel',
   summary: 'Cancel a running cinematic.render job.',
   description:
@@ -361,12 +361,12 @@ export const cinematicRenderCancel = defineOperation({
   async impl(input) {
     const job = getRenderJob(input.jobId);
     if (!job) {
-      throw new OperationError('RENDER_JOB_NOT_FOUND', `No render job "${input.jobId}".`, {
+      throw new ToolError('RENDER_JOB_NOT_FOUND', `No render job "${input.jobId}".`, {
         jobId: input.jobId,
       });
     }
     if (job.status !== 'running') {
-      throw new OperationError(
+      throw new ToolError(
         'RENDER_JOB_NOT_RUNNING',
         `Render job "${input.jobId}" has already settled (${job.status}) — nothing to cancel.`,
         { jobId: input.jobId, status: job.status },
@@ -402,7 +402,7 @@ export const cinematicRenderCancel = defineOperation({
 });
 
 /** Register cinematic.render / .status / .cancel onto `registry`. */
-export function registerRenderOperations(registry: OperationRegistry): void {
+export function registerRenderOperations(registry: ToolRegistry): void {
   registry.register(cinematicRender);
   registry.register(cinematicRenderStatus);
   registry.register(cinematicRenderCancel);

package/src/cinematic/render-transport.ts

@@ -52,7 +52,7 @@ import {
   renderCinematic,
   resolveRenderCinematicRequest,
 } from '../render/render-cinematic.js';
-import type { OperationContext } from '../types.js';
+import type { ToolContext } from '../types.js';
 
 export type CinematicRenderFn = (
   request: RenderCinematicRequest,
@@ -60,7 +60,7 @@ export type CinematicRenderFn = (
 ) => Promise<RenderCinematicResult>;
 
 /** Resolve the render function to use: `ctx['cinematicRenderFn']` when injected (tests), else the real pipeline. */
-export function getCinematicRenderFn(ctx: OperationContext): CinematicRenderFn {
+export function getCinematicRenderFn(ctx: ToolContext): CinematicRenderFn {
   const injected = ctx['cinematicRenderFn'];
   return (injected as CinematicRenderFn | undefined) ?? renderCinematic;
 }

package/src/cinematic/theatre-operations.ts

@@ -30,28 +30,28 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { isAbsolute, join } from 'node:path';
 import { z } from 'zod';
-import { OperationError } from '../errors.js';
+import { ToolError } from '../errors.js';
 import { listProjectFiles } from '../project/shared.js';
-import { defineOperation, type ErrorDefinition, type OperationRegistry } from '../registry.js';
-import type { OperationContext } from '../types.js';
+import { defineTool, type ToolErrorDefinition, type ToolRegistry } from '../registry.js';
+import type { ToolContext } from '../types.js';
 
 // ---------------------------------------------------------------------------
 // Shared path resolution: `root` (explicit) > `ctx.projectRoot` (fallback).
 // ---------------------------------------------------------------------------
 
-export const NO_ROOT_ERROR: ErrorDefinition = {
+export const NO_ROOT_ERROR: ToolErrorDefinition = {
   code: 'NO_ROOT',
   summary: 'Neither an explicit `root` input nor ctx.projectRoot was given.',
   data: z.object({}).describe('No additional data.'),
 };
 
-export const THEATRE_FILE_NOT_FOUND_ERROR: ErrorDefinition = {
+export const THEATRE_FILE_NOT_FOUND_ERROR: ToolErrorDefinition = {
   code: 'FILE_NOT_FOUND',
   summary: 'The referenced Theatre project-state file does not exist on disk.',
   data: z.object({ path: z.string() }),
 };
 
-export const INVALID_THEATRE_PROJECT_ERROR: ErrorDefinition = {
+export const INVALID_THEATRE_PROJECT_ERROR: ToolErrorDefinition = {
   code: 'INVALID_THEATRE_PROJECT',
   summary:
     "The file's outer shape (sheetsById/definitionVersion/revisionHistory, and — for " +
@@ -59,17 +59,17 @@ export const INVALID_THEATRE_PROJECT_ERROR: ErrorDefinition = {
   data: z.object({ issues: z.array(z.string()) }),
 };
 
-export const SHEET_NOT_FOUND_ERROR: ErrorDefinition = {
+export const SHEET_NOT_FOUND_ERROR: ToolErrorDefinition = {
   code: 'SHEET_NOT_FOUND',
   summary: 'No sheet with the given name exists in this Theatre project’s sheetsById.',
   data: z.object({ sheetName: z.string(), availableSheets: z.array(z.string()) }),
 };
 
 /** Resolve `root` input against `ctx.projectRoot`, requiring at least one. */
-function resolveRoot(root: string | undefined, ctx: OperationContext): string {
+function resolveRoot(root: string | undefined, ctx: ToolContext): string {
   const resolved = root ?? ctx.projectRoot;
   if (!resolved) {
-    throw new OperationError(
+    throw new ToolError(
       'NO_ROOT',
       'Neither an explicit `root` input nor ctx.projectRoot was given.',
       {},
@@ -85,7 +85,7 @@ function resolveTheatreProjectPath(root: string, theatreProjectPath: string): st
 
 function readTheatreProjectFile(absPath: string): unknown {
   if (!existsSync(absPath)) {
-    throw new OperationError('FILE_NOT_FOUND', `File not found: ${absPath}`, { path: absPath });
+    throw new ToolError('FILE_NOT_FOUND', `File not found: ${absPath}`, { path: absPath });
   }
   return JSON.parse(readFileSync(absPath, 'utf-8'));
 }
@@ -135,7 +135,7 @@ const CinematicProjectListResult = z.object({
     ),
 });
 
-export const cinematicProjectList = defineOperation({
+export const cinematicProjectList = defineTool({
   name: 'cinematic.project.list',
   summary: 'List every committed Theatre project-state file under a directory.',
   description:
@@ -176,7 +176,7 @@ const CinematicSheetListResult = z.object({
   sheets: z.array(z.string()).describe('Every sheet name in sheetsById, sorted.'),
 });
 
-export const cinematicSheetList = defineOperation({
+export const cinematicSheetList = defineTool({
   name: 'cinematic.sheet.list',
   summary: 'List every sheet name in a committed Theatre project-state file.',
   description: 'Static, file-native (§8 B5 "list Theatre ... sheets"). Outer-shape validated only.',
@@ -194,7 +194,7 @@ export const cinematicSheetList = defineOperation({
     const json = readTheatreProjectFile(absPath);
     const parsed = TheatreProjectOuterShape.safeParse(json);
     if (!parsed.success) {
-      throw new OperationError(
+      throw new ToolError(
         'INVALID_THEATRE_PROJECT',
         `${absPath} does not match Theatre project-state's outer shape.`,
         { issues: parsed.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`) },
@@ -236,7 +236,7 @@ const CinematicSequenceInspectResult = z.object({
     ),
 });
 
-export const cinematicSequenceInspect = defineOperation({
+export const cinematicSequenceInspect = defineTool({
   name: 'cinematic.sequence.inspect',
   summary:
     'Inspect one sheet’s sequence length and tracked objects in a Theatre project-state file.',
@@ -263,7 +263,7 @@ export const cinematicSequenceInspect = defineOperation({
     const json = readTheatreProjectFile(absPath);
     const parsed = TheatreProjectDeepShape.safeParse(json);
     if (!parsed.success) {
-      throw new OperationError(
+      throw new ToolError(
         'INVALID_THEATRE_PROJECT',
         `${absPath} does not match Theatre project-state's shape (incl. per-sheet sequence).`,
         { issues: parsed.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`) },
@@ -271,7 +271,7 @@ export const cinematicSequenceInspect = defineOperation({
     }
     const sheet = parsed.data.sheetsById[input.sheetName];
     if (!sheet) {
-      throw new OperationError(
+      throw new ToolError(
         'SHEET_NOT_FOUND',
         `No sheet named "${input.sheetName}" in ${absPath}.`,
         { sheetName: input.sheetName, availableSheets: Object.keys(parsed.data.sheetsById).sort() },
@@ -299,7 +299,7 @@ export const cinematicSequenceInspect = defineOperation({
 });
 
 /** Register cinematic.project.list / cinematic.sheet.list / cinematic.sequence.inspect onto `registry`. */
-export function registerTheatreOperations(registry: OperationRegistry): void {
+export function registerTheatreOperations(registry: ToolRegistry): void {
   registry.register(cinematicProjectList);
   registry.register(cinematicSheetList);
   registry.register(cinematicSequenceInspect);

package/src/editor/camera-operations.ts

@@ -22,8 +22,8 @@
  */
 
 import { z } from 'zod';
-import { OperationError } from '../errors.js';
-import { defineOperation, type OperationRegistry } from '../registry.js';
+import { ToolError } from '../errors.js';
+import { defineTool, type ToolRegistry } from '../registry.js';
 import {
   EDITOR_COMMAND_TIMEOUT_MS,
   EDITOR_NOT_RUNNING_ERROR,
@@ -65,7 +65,7 @@ const EditorViewportCameraGetInput = z
 
 const EditorViewportCameraGetResult = CameraPoseSchema.describe('Live viewport camera pose.');
 
-export const editorViewportCameraGet = defineOperation({
+export const editorViewportCameraGet = defineTool({
   name: 'editor.viewport.camera.get',
   summary: 'Read the viewport camera pose (position/target/fov) from a connected editor session.',
   description:
@@ -89,7 +89,7 @@ export const editorViewportCameraGet = defineOperation({
       'editor.viewport.camera.get',
     ).catch(() => undefined);
     if (!camera) {
-      throw new OperationError(
+      throw new ToolError(
         'CAMERA_STATE_UNAVAILABLE',
         'No browser tab has bound/reported a viewport camera pose yet.',
         {},
@@ -124,7 +124,7 @@ const EditorViewportCameraSetInput = z
 
 const EditorViewportCameraSetResult = z.object({ ok: z.literal(true) });
 
-export const editorViewportCameraSet = defineOperation({
+export const editorViewportCameraSet = defineTool({
   name: 'editor.viewport.camera.set',
   summary:
     'Move the viewport camera via focus-entity, focus-selection, a view preset, or an arbitrary pose.',
@@ -155,7 +155,7 @@ export const editorViewportCameraSet = defineOperation({
       error: err instanceof Error ? err.message : String(err),
     }));
     if (!result.ok) {
-      throw new OperationError('COMMAND_FAILED', result.error ?? 'camera command failed', {
+      throw new ToolError('COMMAND_FAILED', result.error ?? 'camera command failed', {
         message: result.error ?? 'camera command failed',
       });
     }
@@ -163,7 +163,7 @@ export const editorViewportCameraSet = defineOperation({
   },
 });
 
-export function registerCameraOperations(registry: OperationRegistry): void {
+export function registerCameraOperations(registry: ToolRegistry): void {
   registry.register(editorViewportCameraGet);
   registry.register(editorViewportCameraSet);
 }

package/src/editor/console-operations.ts

@@ -15,8 +15,8 @@
  */
 
 import { z } from 'zod';
-import { OperationError } from '../errors.js';
-import { defineOperation, type OperationRegistry } from '../registry.js';
+import { ToolError } from '../errors.js';
+import { defineTool, type ToolRegistry } from '../registry.js';
 import {
   EDITOR_NOT_RUNNING_ERROR,
   EDITOR_READ_TIMEOUT_MS,
@@ -47,7 +47,7 @@ const EditorConsoleSubscribeResult = z.object({
     .describe('Number of play-mode log entries currently buffered/persisted.'),
 });
 
-export const editorConsoleSubscribe = defineOperation({
+export const editorConsoleSubscribe = defineTool({
   name: 'editor.console.subscribe',
   summary: "Describe how to subscribe to a connected editor session's events and logs.",
   description:
@@ -72,7 +72,7 @@ export const editorConsoleSubscribe = defineOperation({
       'editor.console.subscribe',
     ).catch(() => undefined);
     if (!metadata) {
-      throw new OperationError(
+      throw new ToolError(
         'CONSOLE_METADATA_UNAVAILABLE',
         'The connected editor session did not answer the log-entries read in time.',
         {},
@@ -82,6 +82,6 @@ export const editorConsoleSubscribe = defineOperation({
   },
 });
 
-export function registerConsoleOperations(registry: OperationRegistry): void {
+export function registerConsoleOperations(registry: ToolRegistry): void {
   registry.register(editorConsoleSubscribe);
 }