@vgai/sdk 0.5.0 → 0.5.2

package/src/http/http-projection.ts

@@ -1,7 +1,7 @@
 /**
  * HTTP projection of the operation registry (B8, §8 B8).
  *
- * The SAME `OperationRegistry` that backs the SDK (`dispatch`) and the CLI
+ * The SAME `ToolRegistry` that backs the SDK (`dispatch`) and the CLI
  * (`packages/vgai-cli/src/oclif/*`, B6) is projected here as a small HTTP
  * server. Routes are GENERATED from `registry.listOperations()` — one route
  * per operation — never hand-authored per op: adding an operation to the SDK
@@ -26,14 +26,14 @@
  *    `tools/list` and is built from the very same `listOperations()` summaries.
  *
  * OUTCOME SHAPE: every response body is the registry's own
- * `OperationOutcome` — `{ ok: true, data }` or `{ ok: false, error }` with a
+ * `ToolOutcome` — `{ ok: true, data }` or `{ ok: false, error }` with a
  * machine-readable `error.code` — byte-for-byte the shape the SDK returns and
  * the CLI prints under `--json`. The HTTP STATUS is a secondary, best-effort
  * signal derived from that code (`httpStatusForOutcome`); the authoritative,
  * cross-projection-identical fact is always `error.code` in the body (§8 B8
  * AC: "HTTP and MCP return the same structured error codes as SDK and CLI").
  *
- * CONTEXT: an operation's `OperationContext` (projectRoot, editorUrl, an
+ * CONTEXT: an operation's `ToolContext` (projectRoot, editorUrl, an
  * injected editor transport for tests, ...) is produced per request by the
  * caller-supplied `createContext(req)` (or the static `context`), so the same
  * server can serve one project or resolve the project per request — the SDK
@@ -45,22 +45,22 @@ import { createServer } from 'node:http';
 import { z } from 'zod';
 import { CORE_ERROR_CODES } from '../errors.js';
 import { operations as defaultRegistry } from '../index.js';
-import type { OperationOutcome, OperationRegistry, OperationSummary } from '../registry.js';
-import type { OperationContext } from '../types.js';
+import type { ToolOutcome, ToolRegistry, ToolSummary } from '../registry.js';
+import type { ToolContext } from '../types.js';
 
 /** Options for building the HTTP projection handler/server. */
 export interface HttpProjectionOptions {
   /** Registry to project. Defaults to the shared `operations` registry (same one the CLI uses). */
-  registry?: OperationRegistry;
+  registry?: ToolRegistry;
   /**
    * URL prefix every operation route lives under. Default `/op`, so
    * `project.scene.read` is `POST /op/project.scene.read`. No trailing slash.
    */
   basePath?: string;
   /** Static context handed to every `dispatch`. Ignored when `createContext` is given. */
-  context?: OperationContext;
+  context?: ToolContext;
   /** Per-request context factory (wins over `context`) — e.g. resolve `projectRoot` from a header. */
-  createContext?: (req: IncomingMessage) => OperationContext | Promise<OperationContext>;
+  createContext?: (req: IncomingMessage) => ToolContext | Promise<ToolContext>;
 }
 
 /** One entry of the `GET <basePath>` manifest — the HTTP analogue of an MCP tool descriptor. */
@@ -73,21 +73,21 @@ export interface HttpRouteDescriptor {
   mutates: boolean;
   supportsDryRun: boolean;
   host: string;
-  requires: OperationSummary['requires'];
-  permission: OperationSummary['permission'];
+  requires: ToolSummary['requires'];
+  permission: ToolSummary['permission'];
   /** Zod-derived JSON Schema for the request body / `?input=` — same conversion MCP tool schemas use. */
   inputSchema: unknown;
   errorCodes: string[];
 }
 
 /** Convert an operation's Zod input schema to JSON Schema — the repo's established `z.toJSONSchema` call (see `scripts/generate-schema.ts`). */
-export function inputJsonSchema(summary: OperationSummary): unknown {
+export function inputJsonSchema(summary: ToolSummary): unknown {
   return z.toJSONSchema(summary.input, { unrepresentable: 'any' });
 }
 
 /** Build the `GET <basePath>` manifest from `listOperations()` — routes are derived, never hand-written. */
 export function buildRouteManifest(
-  registry: OperationRegistry,
+  registry: ToolRegistry,
   basePath: string,
 ): HttpRouteDescriptor[] {
   return registry
@@ -109,19 +109,19 @@ export function buildRouteManifest(
     .sort((a, b) => a.name.localeCompare(b.name));
 }
 
-/** A projection-level (not `dispatch`) failure, still shaped as an `OperationOutcome` so every response body is uniform. */
-function failure(code: string, message: string, data?: unknown): OperationOutcome {
+/** A projection-level (not `dispatch`) failure, still shaped as an `ToolOutcome` so every response body is uniform. */
+function failure(code: string, message: string, data?: unknown): ToolOutcome {
   return { ok: false, error: { code, message, ...(data !== undefined ? { data } : {}) } };
 }
 
 /**
- * Map an `OperationOutcome` to an HTTP status. Best-effort ONLY — the
+ * Map an `ToolOutcome` to an HTTP status. Best-effort ONLY — the
  * authoritative, cross-projection-identical signal is `error.code` in the
  * body, not this status. Success is 200; a handful of well-known core codes
  * get their conventional status; every other structured failure defaults to
  * 400 (a caller-actionable problem) rather than 500.
  */
-export function httpStatusForOutcome(outcome: OperationOutcome): number {
+export function httpStatusForOutcome(outcome: ToolOutcome): number {
   if (outcome.ok) return 200;
   switch (outcome.error.code) {
     case CORE_ERROR_CODES.OPERATION_NOT_FOUND:
@@ -205,15 +205,15 @@ async function parseRouteInput(
 /**
  * The pure routing core, exported for tests: given a method, pathname and
  * already-parsed input, resolve the target operation and dispatch it —
- * returning the `OperationOutcome` and the HTTP status, with no `http`
+ * returning the `ToolOutcome` and the HTTP status, with no `http`
  * objects involved. `serveHttpRequest` is the thin I/O wrapper around this.
  */
 export async function dispatchRoute(
-  registry: OperationRegistry,
+  registry: ToolRegistry,
   basePath: string,
   route: ParsedRoute,
-  ctx: OperationContext,
-): Promise<OperationOutcome> {
+  ctx: ToolContext,
+): Promise<ToolOutcome> {
   if (route.parseError !== undefined) {
     // A malformed body is a caller input problem — surface it as the SAME
     // INVALID_INPUT code the SDK/CLI use for a schema rejection.
@@ -240,18 +240,18 @@ export async function dispatchRoute(
   return registry.dispatch(route.name, route.input, ctx);
 }
 
-/** Send an `OperationOutcome` as a JSON response with the derived status. */
-function sendOutcome(res: ServerResponse, outcome: OperationOutcome): void {
+/** Send an `ToolOutcome` as a JSON response with the derived status. */
+function sendOutcome(res: ServerResponse, outcome: ToolOutcome): void {
   const body = `${JSON.stringify(outcome)}\n`;
   res.writeHead(httpStatusForOutcome(outcome), { 'content-type': 'application/json' });
   res.end(body);
 }
 
-/** Resolve the per-request `OperationContext` from the options (static or factory). */
+/** Resolve the per-request `ToolContext` from the options (static or factory). */
 async function resolveHttpContext(
   options: HttpProjectionOptions,
   req: IncomingMessage,
-): Promise<OperationContext> {
+): Promise<ToolContext> {
   if (options.createContext) return options.createContext(req);
   if (options.context) return options.context;
   return {};
@@ -260,7 +260,7 @@ async function resolveHttpContext(
 /** The full request lifecycle, factored out of the returned closure to keep each step flat. */
 async function handleProjectionRequest(
   options: HttpProjectionOptions,
-  registry: OperationRegistry,
+  registry: ToolRegistry,
   basePath: string,
   req: IncomingMessage,
   res: ServerResponse,
@@ -296,7 +296,7 @@ async function handleProjectionRequest(
       ? { name, method, input: undefined, parseError: parsed.parseError }
       : { name, method, input: parsed.input };
 
-  let ctx: OperationContext;
+  let ctx: ToolContext;
   try {
     ctx = await resolveHttpContext(options, req);
   } catch (err) {

package/src/index.ts

@@ -4,9 +4,9 @@ export * from './editor/index.js';
 export {
   CORE_ERROR_CODES,
   type CoreErrorCode,
-  OperationError,
   type StructuredIssue,
   type StructuredOperationError,
+  ToolError,
   toStructuredIssues,
 } from './errors.js';
 export * from './http/index.js';
@@ -15,62 +15,54 @@ export {
   ProjectStatusInput,
   ProjectStatusResult,
   projectStatus,
-  registerBuiltinOperations,
+  registerBuiltinTools,
 } from './operations.js';
 export * from './perf/index.js';
 export * from './play/index.js';
 export * from './project/index.js';
 export * from './project-tool-catalog.js';
 export {
-  defineOperation,
-  type ErrorDefinition,
-  type OperationDefinition,
-  type OperationOutcome,
-  OperationRegistry,
-  type OperationSummary,
+  defineTool,
+  type ToolDefinition,
+  type ToolErrorDefinition,
+  type ToolOutcome,
+  ToolRegistry,
+  type ToolSummary,
 } from './registry.js';
 export * from './render/index.js';
-export type {
-  ToolContext,
-  ToolDefinition,
-  ToolErrorDefinition,
-  ToolHost,
-  ToolOutcome,
-  ToolPermission,
-  ToolPermissionRisk,
-  ToolRequirements,
-  ToolSummary,
-} from './tools.js';
-export { defineTool, ToolError, ToolRegistry } from './tools.js';
+// The tool vocabulary is exported once, from its defining modules below.
+// `./tools.js` is the consumer-facing entry point and re-exports the same
+// symbols; re-exporting them here too would duplicate every identifier.
+export type { ToolHost, ToolPermission, ToolPermissionRisk, ToolRequirements } from './tools.js';
 export {
   type ExecutionHost,
   type ExecutionRequirements,
-  OPERATION_NAMESPACES,
-  type OperationContext,
-  type OperationNamespace,
   type PermissionMetadata,
   type PermissionRisk,
+  TOOL_NAMESPACES,
+  type ToolContext,
+  type ToolNamespace,
 } from './types.js';
 
 import { registerCinematicOperations } from './cinematic/index.js';
 import { registerEditorOperations } from './editor/index.js';
-import { registerBuiltinOperations } from './operations.js';
+import { registerBuiltinTools } from './operations.js';
 import { registerPlayOperations } from './play/index.js';
 import { registerProjectOperations } from './project/index.js';
-import { OperationRegistry } from './registry.js';
+import { ToolRegistry } from './registry.js';
 
 /**
  * Build a fresh registry preloaded with B1's sample operations plus B2's
  * real `project.*` operations, B3's real `editor.*` operations, B4's real
  * `play.*` operations, and B5's real `cinematic.*` operations. Deliberately
  * separate register calls (not one function grown to cover all five) —
- * `registerBuiltinOperations` is B1's own registration function, and its
+ * `registerBuiltinTools` is B1's own registration function, and its
  * registry test asserts exactly what it registers; growing it here would
  * break that assertion for a reason unrelated to what it actually tests.
  */
-export function createOperationRegistry(): OperationRegistry {
-  const registry = new OperationRegistry();
-  registerBuiltinOperations(registry);
+export function createToolRegistry(): ToolRegistry {
+  const registry = new ToolRegistry();
+  registerBuiltinTools(registry);
   registerProjectOperations(registry);
   registerEditorOperations(registry);
   registerPlayOperations(registry);
@@ -79,4 +71,4 @@ export function createOperationRegistry(): OperationRegistry {
 }
 
 /** Convenience default registry — the same one CLI/HTTP/MCP projections (B6-B8) will build on. */
-export const operations = createOperationRegistry();
+export const operations = createToolRegistry();

package/src/mcp/index.ts

@@ -11,8 +11,8 @@ export {
   type McpProjectionOptions,
   type McpResource,
   type McpTool,
-  operationToResource,
-  operationToTool,
+  toolToMcpResource,
+  toolToMcpTool,
   outcomeToToolResult,
   toolInputSchema,
 } from './mcp-projection.js';

package/src/mcp/mcp-projection.ts

@@ -1,7 +1,7 @@
 /**
  * MCP projection of the operation registry (B8, §8 B8).
  *
- * The SAME `OperationRegistry` behind the SDK, the CLI (B6), and the HTTP
+ * The SAME `ToolRegistry` behind the SDK, the CLI (B6), and the HTTP
  * projection is registered here as MCP TOOLS (and, for a principled subset,
  * MCP RESOURCES). Every tool is derived from a `listOperations()` summary —
  * name, description, and a Zod-derived JSON Schema for its input — so adding
@@ -40,8 +40,8 @@
 import { z } from 'zod';
 import { CORE_ERROR_CODES } from '../errors.js';
 import { operations as defaultRegistry } from '../index.js';
-import type { OperationOutcome, OperationRegistry, OperationSummary } from '../registry.js';
-import type { OperationContext } from '../types.js';
+import type { ToolOutcome, ToolRegistry, ToolSummary } from '../registry.js';
+import type { ToolContext } from '../types.js';
 
 /** URI scheme/prefix under which read-only-state operations are also exposed as MCP resources. */
 export const MCP_RESOURCE_PREFIX = 'vgai://op/';
@@ -72,11 +72,11 @@ export interface McpResource {
 
 export interface McpProjectionOptions {
   /** Registry to project. Defaults to the shared `operations` registry (same one the CLI/HTTP projections use). */
-  registry?: OperationRegistry;
+  registry?: ToolRegistry;
   /** Static context handed to every dispatch. Ignored when `createContext` is given. */
-  context?: OperationContext;
+  context?: ToolContext;
   /** Per-call context factory (wins over `context`). */
-  createContext?: () => OperationContext | Promise<OperationContext>;
+  createContext?: () => ToolContext | Promise<ToolContext>;
 }
 
 /** The Zod-derived JSON Schema for an op's input — the SAME conversion the HTTP manifest uses. */
@@ -91,7 +91,7 @@ function objectWireSchema(schema: Record<string, unknown>): Record<string, unkno
 }
 
 function fullOperationSchema(
-  summary: OperationSummary,
+  summary: ToolSummary,
   direction: 'input' | 'output',
 ): Record<string, unknown> {
   const operationSchema = objectWireSchema(
@@ -122,7 +122,7 @@ function fullOperationSchema(
   };
 }
 
-function schemaResourceUri(summary: OperationSummary, direction: 'input' | 'output'): string {
+function schemaResourceUri(summary: ToolSummary, direction: 'input' | 'output'): string {
   return `${MCP_SCHEMA_RESOURCE_PREFIX}${direction}/${summary.name}`;
 }
 
@@ -143,7 +143,7 @@ function compactLargeProperty(value: unknown, resourceUri: string, limit = 4_096
 }
 
 function compactOperationSchema(
-  summary: OperationSummary,
+  summary: ToolSummary,
   direction: 'input' | 'output',
 ): Record<string, unknown> {
   const full = fullOperationSchema(summary, direction);
@@ -176,12 +176,12 @@ function compactOperationSchema(
 }
 
 /** Compact MCP-list schema; the full version is exposed as an on-demand resource when large. */
-export function toolInputSchema(summary: OperationSummary): unknown {
+export function toolInputSchema(summary: ToolSummary): unknown {
   return compactOperationSchema(summary, 'input');
 }
 
 /** Derive one MCP tool from an operation summary: dotted name (mirrors §5.7 hierarchy), description, Zod-derived schema. */
-export function operationToTool(summary: OperationSummary): McpTool {
+export function toolToMcpTool(summary: ToolSummary): McpTool {
   return {
     name: summary.name,
     description: `${summary.summary}\n\n${summary.description}`.trim(),
@@ -199,13 +199,13 @@ export function operationToTool(summary: OperationSummary): McpTool {
 }
 
 /** True when a read-only op takes no required input, so it names readable STATE addressable by URI alone (resource-worthy). See module jsdoc. */
-export function isResourceEligible(summary: OperationSummary): boolean {
+export function isResourceEligible(summary: ToolSummary): boolean {
   if (summary.mutates) return false;
   return summary.input.safeParse({}).success;
 }
 
 /** Derive the MCP resource descriptor for a resource-eligible op. */
-export function operationToResource(summary: OperationSummary): McpResource {
+export function toolToMcpResource(summary: ToolSummary): McpResource {
   return {
     uri: `${MCP_RESOURCE_PREFIX}${summary.name}`,
     name: summary.name,
@@ -214,7 +214,7 @@ export function operationToResource(summary: OperationSummary): McpResource {
   };
 }
 
-function schemaResources(summary: OperationSummary): McpResource[] {
+function schemaResources(summary: ToolSummary): McpResource[] {
   const resources: McpResource[] = [];
   for (const direction of ['input', 'output'] as const) {
     const full = fullOperationSchema(summary, direction);
@@ -267,7 +267,7 @@ function rpcError(
 }
 
 /**
- * Wrap an `OperationOutcome` as an MCP tool-call result. MCP tool results are
+ * Wrap an `ToolOutcome` as an MCP tool-call result. MCP tool results are
  * `{ content: [...], isError?, structuredContent? }`; we put the outcome JSON
  * as a `text` content block (so a model sees it) AND — crucially for machine
  * consumers and the contract test — pass it through verbatim in
@@ -275,10 +275,10 @@ function rpcError(
  * tool result) so `error.code` survives unchanged. `isError` mirrors
  * `!outcome.ok`.
  */
-export function outcomeToToolResult(outcome: OperationOutcome): {
+export function outcomeToToolResult(outcome: ToolOutcome): {
   content: { type: 'text'; text: string }[];
   isError: boolean;
-  structuredContent: OperationOutcome;
+  structuredContent: ToolOutcome;
 } {
   return {
     content: [{ type: 'text', text: JSON.stringify(outcome) }],
@@ -293,18 +293,18 @@ export function outcomeToToolResult(outcome: OperationOutcome): {
  * transport (or a test) drives.
  */
 export interface McpProjection {
-  registry: OperationRegistry;
+  registry: ToolRegistry;
   listTools(): McpTool[];
   listResources(): McpResource[];
-  callTool(name: string, args: unknown): Promise<OperationOutcome>;
-  readResource(uri: string): Promise<OperationOutcome>;
+  callTool(name: string, args: unknown): Promise<ToolOutcome>;
+  readResource(uri: string): Promise<ToolOutcome>;
   handle(request: JsonRpcRequest): Promise<JsonRpcResponse>;
 }
 
 export function createMcpProjection(options: McpProjectionOptions = {}): McpProjection {
   const registry = options.registry ?? defaultRegistry;
 
-  async function resolveContext(): Promise<OperationContext> {
+  async function resolveContext(): Promise<ToolContext> {
     if (options.createContext) return options.createContext();
     return options.context ?? {};
   }
@@ -312,25 +312,25 @@ export function createMcpProjection(options: McpProjectionOptions = {}): McpProj
   function listTools(): McpTool[] {
     return registry
       .listOperations()
-      .map(operationToTool)
+      .map(toolToMcpTool)
       .sort((a, b) => a.name.localeCompare(b.name));
   }
 
   function listResources(): McpResource[] {
     const summaries = registry.listOperations();
     return [
-      ...summaries.filter(isResourceEligible).map(operationToResource),
+      ...summaries.filter(isResourceEligible).map(toolToMcpResource),
       ...summaries.flatMap(schemaResources),
     ].sort((a, b) => a.uri.localeCompare(b.uri));
   }
 
-  async function callTool(name: string, args: unknown): Promise<OperationOutcome> {
+  async function callTool(name: string, args: unknown): Promise<ToolOutcome> {
     // dispatch already returns OPERATION_NOT_FOUND for an unknown name and
     // INVALID_INPUT for a bad-shaped `args` — same codes as SDK/CLI/HTTP.
     return registry.dispatch(name, args ?? {}, await resolveContext());
   }
 
-  async function readResource(uri: string): Promise<OperationOutcome> {
+  async function readResource(uri: string): Promise<ToolOutcome> {
     if (uri.startsWith(MCP_SCHEMA_RESOURCE_PREFIX)) {
       const match = /^vgai:\/\/schema\/(input|output)\/(.+)$/.exec(uri);
       const summary = match

package/src/mcp/mcp-server.ts

@@ -3,7 +3,7 @@
  *
  * This deliberately uses the official SDK's lower-level `Server` rather than
  * re-registering operations through `McpServer.registerTool`. VGAI already has
- * one authoritative validation/dispatch layer (`OperationRegistry`): letting
+ * one authoritative validation/dispatch layer (`ToolRegistry`): letting
  * the high-level helper pre-validate arguments would turn malformed operation
  * input into an SDK protocol error before the registry could return the same
  * structured `INVALID_INPUT` outcome as SDK/CLI/HTTP. The lower-level server
@@ -48,7 +48,7 @@ export const DEFAULT_MCP_INSTRUCTIONS =
   'success. For an existing non-VGAI game, inspect first and never rewrite source without consent. ' +
   'Read operations are safe to call for discovery. Before calling a write or destructive tool, ' +
   'inspect its annotations and description, preserve project source, and use dryRun when the ' +
-  'tool offers it. Tool results are VGAI OperationOutcome objects: {ok:true,data} on success or ' +
+  'tool offers it. Tool results are VGAI ToolOutcome objects: {ok:true,data} on success or ' +
   '{ok:false,error:{code,message,...}} on failure. Operations requiring an editor target the ' +
   'live vgai edit session matching the project unless VGAI_EDITOR_URL/--url selected one explicitly.';
 

package/src/operations.ts

@@ -21,8 +21,8 @@
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 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';
 
 // ---------------------------------------------------------------------------
 // project.status — real, file-native (B2 project.* stand-in)
@@ -41,7 +41,7 @@ export const ProjectStatusResult = z
   })
   .describe('Discovery result for the project at ctx.projectRoot.');
 
-export const projectStatus = defineOperation({
+export const projectStatus = defineTool({
   name: 'project.status',
   summary: 'Report whether a vgai project manifest exists at the execution context project root.',
   description:
@@ -64,7 +64,7 @@ export const projectStatus = defineOperation({
   permission: { risk: 'read', summary: "Reads one file's existence under projectRoot; no writes." },
   async impl(_input, ctx) {
     if (!ctx.projectRoot) {
-      throw new OperationError(
+      throw new ToolError(
         'NO_PROJECT_ROOT',
         'dispatch() was called without ctx.projectRoot.',
         {},
@@ -78,6 +78,6 @@ export const projectStatus = defineOperation({
 });
 
 /** Register every B1 sample operation onto `registry`. */
-export function registerBuiltinOperations(registry: OperationRegistry): void {
+export function registerBuiltinTools(registry: ToolRegistry): void {
   registry.register(projectStatus);
 }

package/src/play/control-operations.ts

@@ -34,8 +34,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 {
   getPlayTransport,
   PLAY_COMMAND_TIMEOUT_MS,
@@ -88,7 +88,7 @@ const PlaySeedSetInput = z.object({
   seed: z.number().int().describe('Deterministic seed value to apply to the running play session.'),
 });
 
-export const playSeedSet = defineOperation({
+export const playSeedSet = defineTool({
   name: 'play.seed.set',
   summary: 'Live-reseed a running play session (future draws only).',
   description:
@@ -122,7 +122,7 @@ export const playSeedSet = defineOperation({
       'play.seed.set',
     ).catch(() => undefined);
     if (!result) {
-      throw new OperationError(
+      throw new ToolError(
         'SEED_CONTROL_UNSUPPORTED',
         'The connected editor page predates the set-seed relay command — reload it.',
         {},
@@ -132,9 +132,9 @@ export const playSeedSet = defineOperation({
       const marker = relayErrorMarker(result);
       const message = result.error ?? 'set-seed command failed';
       if (marker?.code === 'DETERMINISM_NOT_DECLARED') {
-        throw new OperationError('DETERMINISM_NOT_DECLARED', message, {});
+        throw new ToolError('DETERMINISM_NOT_DECLARED', message, {});
       }
-      throw new OperationError('COMMAND_FAILED', message, { message });
+      throw new ToolError('COMMAND_FAILED', message, { message });
     }
     return { ok: true as const };
   },
@@ -152,7 +152,7 @@ const PlayTimeScaleSetInput = z.object({
     .describe('Simulation time-scale to apply (clamped [0,8] to match GameLoop.timeScale).'),
 });
 
-export const playTimeScaleSet = defineOperation({
+export const playTimeScaleSet = defineTool({
   name: 'play.timeScale.set',
   summary: "Set a running play session's simulation time-scale.",
   description:
@@ -183,7 +183,7 @@ export const playTimeScaleSet = defineOperation({
       'play.timeScale.set',
     ).catch(() => undefined);
     if (!result) {
-      throw new OperationError(
+      throw new ToolError(
         'TIME_SCALE_CONTROL_UNSUPPORTED',
         "The connected editor has no wire-level command to change a live play session's " +
           'time-scale today.',
@@ -191,7 +191,7 @@ export const playTimeScaleSet = defineOperation({
       );
     }
     if (!result.ok) {
-      throw new OperationError('COMMAND_FAILED', result.error ?? 'set-time-scale command failed', {
+      throw new ToolError('COMMAND_FAILED', result.error ?? 'set-time-scale command failed', {
         message: result.error ?? 'set-time-scale command failed',
       });
     }
@@ -199,7 +199,7 @@ export const playTimeScaleSet = defineOperation({
   },
 });
 
-export function registerControlOperations(registry: OperationRegistry): void {
+export function registerControlOperations(registry: ToolRegistry): void {
   registry.register(playSeedSet);
   registry.register(playTimeScaleSet);
 }

package/src/play/debug-command-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 {
   getPlayTransport,
   PLAY_COMMAND_TIMEOUT_MS,
@@ -99,7 +99,7 @@ const PlayDebugCommandListResult = z.object({
     .describe('Every debug command the running game registered, with locus and arg shapes.'),
 });
 
-export const playDebugCommandList = defineOperation({
+export const playDebugCommandList = defineTool({
   name: 'play.debugCommand.list',
   summary: 'List the debug commands a running play session registers, with locus and arg shapes.',
   description:
@@ -131,7 +131,7 @@ export const playDebugCommandList = defineOperation({
       'play.debugCommand.list',
     ).catch(() => undefined);
     if (result === undefined) {
-      throw new OperationError(
+      throw new ToolError(
         'DEBUG_COMMANDS_UNSUPPORTED',
         'The connected editor page predates the debug-command relay commands — reload it.',
         {},
@@ -139,7 +139,7 @@ export const playDebugCommandList = defineOperation({
     }
     if (!result.ok) {
       const message = result.error ?? 'list-debug-commands command failed';
-      throw new OperationError('COMMAND_FAILED', message, { message });
+      throw new ToolError('COMMAND_FAILED', message, { message });
     }
     const commands =
       (
@@ -174,7 +174,7 @@ const PlayDebugCommandInvokeResult = z.object({
   result: z.unknown().describe("The command's return value (JSON-serializable), when any."),
 });
 
-export const playDebugCommandInvoke = defineOperation({
+export const playDebugCommandInvoke = defineTool({
   name: 'play.debugCommand.invoke',
   summary: 'Invoke a game-registered debug command in a running play session.',
   description:
@@ -211,7 +211,7 @@ export const playDebugCommandInvoke = defineOperation({
       'play.debugCommand.invoke',
     ).catch(() => undefined);
     if (result === undefined) {
-      throw new OperationError(
+      throw new ToolError(
         'DEBUG_COMMANDS_UNSUPPORTED',
         'The connected editor page predates the debug-command relay commands — reload it.',
         {},
@@ -222,24 +222,24 @@ export const playDebugCommandInvoke = defineOperation({
       const message = result.error ?? 'invoke-debug-command command failed';
       switch (marker?.code) {
         case 'DEBUG_COMMAND_NOT_REGISTERED':
-          throw new OperationError('DEBUG_COMMAND_NOT_REGISTERED', message, {
+          throw new ToolError('DEBUG_COMMAND_NOT_REGISTERED', message, {
             registered: relayStringArray(marker.data['registered']),
           });
         case 'DEBUG_COMMAND_ARGS_INVALID':
-          throw new OperationError('DEBUG_COMMAND_ARGS_INVALID', message, {
+          throw new ToolError('DEBUG_COMMAND_ARGS_INVALID', message, {
             issues: Array.isArray(marker.data['issues']) ? marker.data['issues'] : [],
           });
         case 'DEBUG_COMMAND_FAILED':
-          throw new OperationError('DEBUG_COMMAND_FAILED', message, marker.data);
+          throw new ToolError('DEBUG_COMMAND_FAILED', message, marker.data);
         default:
-          throw new OperationError('COMMAND_FAILED', message, { message });
+          throw new ToolError('COMMAND_FAILED', message, { message });
       }
     }
     return { result: (result.data as { result?: unknown } | undefined)?.result };
   },
 });
 
-export function registerDebugCommandOperations(registry: OperationRegistry): void {
+export function registerDebugCommandOperations(registry: ToolRegistry): void {
   registry.register(playDebugCommandList);
   registry.register(playDebugCommandInvoke);
 }