@volter/sdk 0.0.0-stage → 0.5.203

package/src/tools/errors.ts

@@ -0,0 +1,91 @@
+import type { z } from 'zod';
+
+/**
+ * Core, registry-level error codes — always available regardless of which
+ * operation was dispatched. Operation-specific codes are declared per
+ * operation on `ToolDefinition.errors` (see `registry.ts`).
+ */
+export const CORE_ERROR_CODES = {
+  /** `dispatch()` was called with a name no operation is registered under. */
+  OPERATION_NOT_FOUND: 'OPERATION_NOT_FOUND',
+  /** Input failed the operation's Zod input schema. */
+  INVALID_INPUT: 'INVALID_INPUT',
+  /** The impl's return value failed the operation's Zod result schema, or a
+   *  thrown ToolError's `data` failed its declared error-code schema —
+   *  either way, an implementation bug, not a caller bug. */
+  INVALID_OUTPUT: 'INVALID_OUTPUT',
+  /** The impl threw something that isn't a declared, structured error. */
+  INTERNAL_ERROR: 'INTERNAL_ERROR',
+} as const;
+
+export type CoreErrorCode = (typeof CORE_ERROR_CODES)[keyof typeof CORE_ERROR_CODES];
+
+/** A single Zod validation failure, reduced to a machine-readable shape. */
+export interface StructuredIssue {
+  path: (string | number | symbol)[];
+  message: string;
+  code: string;
+}
+
+/**
+ * The one error shape every `dispatch()` failure normalizes into. `code` is
+ * always machine-readable and always present — nothing in this codebase may
+ * identify an operation failure by parsing `message` prose (§8 B1 AC).
+ */
+export interface StructuredOperationError {
+  code: string;
+  message: string;
+  /** Present for INVALID_INPUT / INVALID_OUTPUT — the exact failing path(s). */
+  issues?: StructuredIssue[];
+  /** Present when the failing code declares a data schema (or the impl attached data). */
+  data?: unknown;
+}
+
+/**
+ * A global brand keeps expected errors recognizable across separately loaded
+ * copies of @volter/sdk (for example, an editor host dispatching a standalone
+ * project's tool). `instanceof` alone cannot cross that package boundary.
+ */
+export const OPERATION_ERROR_BRAND = Symbol.for('@volter/sdk.ToolError');
+
+/**
+ * The only way an operation `impl` should signal an EXPECTED, contractual
+ * failure (as opposed to an unexpected bug/exception). `code` must be one
+ * the operation's `ToolDefinition.errors` declares — `dispatch()`
+ * cross-checks it and validates `data` against that code's schema, so an
+ * undeclared code or mismatched data is itself normalized into a structured
+ * error rather than silently forwarded (see `registry.ts`'s
+ * `normalizeThrown`).
+ */
+export class ToolError extends Error {
+  readonly [OPERATION_ERROR_BRAND] = true;
+  readonly code: string;
+  readonly data: unknown;
+
+  constructor(code: string, message: string, data?: unknown) {
+    super(message);
+    this.name = 'ToolError';
+    this.code = code;
+    this.data = data;
+  }
+}
+
+export function isOperationError(value: unknown): value is ToolError {
+  if (value instanceof ToolError) return true;
+  if (value === null || typeof value !== 'object') return false;
+  const candidate = value as Record<PropertyKey, unknown>;
+  return (
+    candidate[OPERATION_ERROR_BRAND] === true &&
+    typeof candidate['code'] === 'string' &&
+    typeof candidate['message'] === 'string'
+  );
+}
+
+/** Reduce a `ZodError`'s issues to the structured, serializable shape above. */
+export function toStructuredIssues(issues: readonly z.ZodIssue[]): StructuredIssue[] {
+  return issues.map((issue) => ({
+    path: [...issue.path],
+    message: issue.message,
+    code: issue.code,
+  }));
+}

package/src/tools/provider-execution.ts

@@ -0,0 +1,70 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import type { GenerationJobDraft } from '../generations.js';
+
+export type ProviderExecutionMode = 'direct' | 'managed' | 'mock';
+export type ProviderModeResolver = (
+  provider: string,
+  requestId?: string,
+) => Promise<ProviderExecutionMode>;
+
+const credentialNames: Record<string, string> = {
+  fal: 'FAL_KEY',
+  tripo: 'TRIPO_API_KEY',
+  worldlabs: 'WORLDLABS_API_KEY',
+  openrouter: 'OPENROUTER_API_KEY',
+};
+
+// Project SSR and installed packages can load separate module instances.
+// The host's async context must still be shared, without sharing requests.
+const key = Symbol.for('volter.provider-execution-context');
+const globals = globalThis as typeof globalThis & {
+  [key]?: AsyncLocalStorage<{
+    resolve: ProviderModeResolver;
+    record?: ((job: GenerationJobDraft) => Promise<void>) | undefined;
+  }>;
+};
+const context = globals[key] ?? new AsyncLocalStorage();
+globals[key] = context;
+
+/** Trusted host configuration. Provider choice and billing never enter tool input. */
+export function withProviderExecution<T>(
+  resolve: ProviderModeResolver,
+  work: () => Promise<T>,
+  record?: (job: GenerationJobDraft) => Promise<void>,
+) {
+  const pending = new Map<string, Promise<ProviderExecutionMode>>();
+  return context.run(
+    {
+      record,
+      resolve: (provider, requestId) => {
+        const key = JSON.stringify([provider, requestId]);
+        let result = pending.get(key);
+        if (!result) {
+          result = resolve(provider, requestId);
+          pending.set(key, result);
+        }
+        return result;
+      },
+    },
+    work,
+  );
+}
+
+/** Native provider clients use the same project ledger as registered tools. */
+export async function recordProviderGeneration(job: GenerationJobDraft): Promise<void> {
+  await context.getStore()?.record?.(job);
+}
+
+/** Library-side connection resolution; callers supply only native provider input. */
+export async function resolveProviderMode(
+  provider: string,
+  requestId?: string,
+): Promise<ProviderExecutionMode> {
+  const resolve = context.getStore()?.resolve;
+  if (resolve) return resolve(provider, requestId);
+  const name = credentialNames[provider];
+  if (!name) throw new Error(`Unknown generation provider ${JSON.stringify(provider)}.`);
+  if (process.env[name]?.trim()) return 'direct';
+  if (process.env['VOLTER_GENERATION_GATEWAY'] && process.env['VOLTER_ACCESS_TOKEN']) return 'managed';
+  throw new Error(`Connect ${provider} or sign in to Volter Editor in Account before generating.`);
+}

package/src/tools/registry.ts

@@ -0,0 +1,341 @@
+import type { z } from 'zod';
+import {
+  CORE_ERROR_CODES,
+  isOperationError,
+  type StructuredOperationError,
+  toStructuredIssues,
+} from './errors.js';
+import {
+  type ExecutionHost,
+  type ExecutionRequirements,
+  type PermissionMetadata,
+  TOOL_NAMESPACES,
+  type ToolContext,
+  type ToolNamespace,
+} from './types.js';
+
+/** One declared, machine-readable failure mode of an operation (§8 B1: "structured error codes and data schemas"). */
+export interface ToolErrorDefinition<TCode extends string = string> {
+  code: TCode;
+  /** One-line human summary of when this code fires — for docs/help text, never parsed by callers. */
+  summary: string;
+  /** Optional schema for this code's `data` payload. When present, `dispatch()` validates a thrown ToolError's data against it. */
+  data?: z.ZodType;
+}
+
+/**
+ * One operation, fully self-describing: identity, both schemas, every
+ * declared failure mode, where/how it runs, and its own implementation.
+ * Built via `defineTool` (below), which validates the name shape and
+ * error-code uniqueness at definition time.
+ */
+export interface ToolDefinition<
+  TInput extends z.ZodType = z.ZodType,
+  TResult extends z.ZodType = z.ZodType,
+  TErrorCode extends string = string,
+> {
+  /** Fully qualified dotted name, e.g. "project.scene.read" (§5.7 namespaces). */
+  name: string;
+  /** Short, one-line summary (for CLI help / listOperations tables). */
+  summary: string;
+  /** Longer prose description of behavior, side effects, and caveats. */
+  description: string;
+  /** Zod schema every `dispatch()` input is validated against before `impl` runs. */
+  input: TInput;
+  /** Zod schema every `impl` return value is validated against before `dispatch()` succeeds. */
+  result: TResult;
+  /** Every structured failure mode this operation may raise via `ToolError`. */
+  errors: ReadonlyArray<ToolErrorDefinition<TErrorCode>>;
+  /** Which live contexts this operation needs (project/editor/play/render). */
+  requires: ExecutionRequirements;
+  /** Which of the three hosts this operation executes on (node / editor-browser / runtime-page). */
+  host: ExecutionHost;
+  /** True if this operation writes/changes state (files, editor, runtime). */
+  mutates: boolean;
+  /** True if this operation supports a dry-run mode (mutations only, meaningful subset). */
+  supportsDryRun: boolean;
+  /** True for jobs that must not ride a short request/response timeout (e.g. `cinematic.render` on the editor relay). */
+  longRunning?: boolean;
+  /** Coarse permission/risk metadata for gated callers (agents, HTTP/MCP auth). */
+  permission: PermissionMetadata;
+  /** The actual implementation. Receives already-schema-validated input. */
+  impl: (input: z.infer<TInput>, ctx: ToolContext) => Promise<z.infer<TResult>>;
+}
+
+/** `listOperations()`'s element shape — every field of `ToolDefinition` except `impl`, so enumerating never risks invoking anything. */
+export type ToolSummary<
+  TInput extends z.ZodType = z.ZodType,
+  TResult extends z.ZodType = z.ZodType,
+  TErrorCode extends string = string,
+> = Omit<ToolDefinition<TInput, TResult, TErrorCode>, 'impl'>;
+
+const NAME_PATTERN = /^[a-z][a-zA-Z0-9]*(\.[a-z][a-zA-Z0-9]*)+$/;
+
+function namespaceOf(name: string): string {
+  const dot = name.indexOf('.');
+  return dot === -1 ? name : name.slice(0, dot);
+}
+
+/**
+ * Typed helper that builds an `ToolDefinition`. Pure and synchronous —
+ * it does not touch a registry (so it can never itself throw "duplicate
+ * name"; that check happens at `ToolRegistry.register`, which has the
+ * cross-operation state to detect it) — but it DOES validate the two things
+ * that are decidable from the definition alone: the name is a valid dotted
+ * `namespace.rest` string under one of the four operation namespaces
+ * (§5.7), and no two declared error codes on the same operation collide.
+ *
+ * Exists mainly for type inference: it pins `impl`'s parameter/return types
+ * to `z.infer<TInput>` / `z.infer<TResult>` so a mismatched implementation
+ * fails to compile rather than failing at runtime.
+ */
+export function defineTool<
+  TInput extends z.ZodType,
+  TResult extends z.ZodType,
+  TErrorCode extends string = string,
+>(def: ToolDefinition<TInput, TResult, TErrorCode>): ToolDefinition<TInput, TResult, TErrorCode> {
+  if (!NAME_PATTERN.test(def.name)) {
+    throw new Error(
+      `defineTool: "${def.name}" is not a valid dotted operation name ` +
+        '(expected e.g. "project.scene.read" — lowercase-leading segments joined by dots).',
+    );
+  }
+  const ns = namespaceOf(def.name);
+  if (!(TOOL_NAMESPACES as readonly string[]).includes(ns)) {
+    throw new Error(
+      `defineTool: "${def.name}" has unknown namespace "${ns}" — expected one of ` +
+        `${TOOL_NAMESPACES.join(', ')} (§5.7).`,
+    );
+  }
+  const seen = new Set<string>();
+  for (const err of def.errors) {
+    if (seen.has(err.code)) {
+      throw new Error(`defineTool: "${def.name}" declares duplicate error code "${err.code}".`);
+    }
+    seen.add(err.code);
+  }
+  return def;
+}
+
+/** `dispatch()`'s result — a discriminated union, never a thrown exception, so every projection (CLI/HTTP/MCP) gets one uniform JSON-able shape for both success and failure. */
+export type ToolOutcome<TResult = unknown> =
+  | { ok: true; data: TResult }
+  | { ok: false; error: StructuredOperationError };
+
+/**
+ * Normalize whatever an `impl` threw into a `StructuredOperationError`.
+ * Three cases:
+ *  1. A declared `ToolError` whose code IS in `def.errors` and whose
+ *     `data` (if the code declares a schema) validates — forwarded as-is,
+ *     `data` replaced by its *parsed* form.
+ *  2. A declared code whose `data` fails its own schema — that is itself an
+ *     implementation bug, surfaced as INVALID_OUTPUT (never silently
+ *     forwarding unvalidated data).
+ *  3. Anything else — an `ToolError` with an undeclared code, a plain
+ *     `Error`, or a non-Error throw — normalized into INTERNAL_ERROR. The
+ *     raw exception/message is never used as the identifying `code`, but it
+ *     IS carried in `message` as well as `data.message`: every projection
+ *     (the CLI's `volter tool`, the oclif commands, the editor's `screenshot` command's module
+ *     lane) shows `error.message` and only some of them dump `data`, so a
+ *     `message` that said nothing but "threw an unstructured exception"
+ *     hid the one sentence the caller needed ("No editor connected — open
+ *     the editor in a browser tab, then retry.") behind whichever surface
+ *     happened to print the whole outcome.
+ */
+function normalizeThrown(def: ToolDefinition, err: unknown): StructuredOperationError {
+  if (isOperationError(err)) {
+    const declared = def.errors.find((e) => e.code === err.code);
+    if (!declared) {
+      return {
+        code: CORE_ERROR_CODES.INTERNAL_ERROR,
+        message: `"${def.name}" threw undeclared error code "${err.code}".`,
+        data: { undeclaredCode: err.code, message: err.message },
+      };
+    }
+    if (declared.data) {
+      const parsed = declared.data.safeParse(err.data);
+      if (!parsed.success) {
+        return {
+          code: CORE_ERROR_CODES.INVALID_OUTPUT,
+          message:
+            `"${def.name}" threw declared code "${err.code}" but its data failed that ` +
+            "code's own schema.",
+          issues: toStructuredIssues(parsed.error.issues),
+        };
+      }
+      return { code: err.code, message: err.message, data: parsed.data };
+    }
+    return {
+      code: err.code,
+      message: err.message,
+      ...(err.data !== undefined ? { data: err.data } : {}),
+    };
+  }
+
+  const message = err instanceof Error ? err.message : String(err);
+  return {
+    code: CORE_ERROR_CODES.INTERNAL_ERROR,
+    message: `"${def.name}" failed: ${message}`,
+    data: { message },
+  };
+}
+
+function toSummary(def: ToolDefinition): ToolSummary {
+  const { impl: _impl, ...summary } = def;
+  return summary;
+}
+
+/**
+ * Zod object schemas strip unknown keys by default. That is unsafe at an
+ * operation boundary: a misspelled `dryRun` could disappear and let the
+ * operation use its write-default. Detect anything parsing removed, at any
+ * nested object level, and reject it before the implementation can run.
+ */
+function firstStrippedInputPath(
+  raw: unknown,
+  parsed: unknown,
+  path: Array<string | number> = [],
+): Array<string | number> | null {
+  if (Array.isArray(raw) && Array.isArray(parsed)) {
+    for (let index = 0; index < raw.length; index++) {
+      const stripped = firstStrippedInputPath(raw[index], parsed[index], [...path, index]);
+      if (stripped) return stripped;
+    }
+    return null;
+  }
+  if (
+    raw === null ||
+    parsed === null ||
+    typeof raw !== 'object' ||
+    typeof parsed !== 'object' ||
+    Array.isArray(raw) ||
+    Array.isArray(parsed)
+  ) {
+    return null;
+  }
+  const parsedRecord = parsed as Record<string, unknown>;
+  for (const [key, value] of Object.entries(raw as Record<string, unknown>)) {
+    if (!Object.hasOwn(parsedRecord, key)) return [...path, key];
+    const stripped = firstStrippedInputPath(value, parsedRecord[key], [...path, key]);
+    if (stripped) return stripped;
+  }
+  return null;
+}
+
+/**
+ * The one registry of operation definitions (§8 B1). Holds definitions
+ * keyed by their fully-qualified name; `register` rejects a duplicate name
+ * outright (names are unique and stable per the AC), `listOperations`
+ * enumerates metadata without ever touching `impl`, and `dispatch` is the
+ * single validated call path: input schema -> impl -> result schema, with
+ * every failure normalized into `StructuredOperationError`.
+ */
+export class ToolRegistry {
+  private readonly definitions = new Map<string, ToolDefinition>();
+
+  /** Register a definition. Throws synchronously on a duplicate name — names are unique and stable by construction, not by convention. */
+  register<TInput extends z.ZodType, TResult extends z.ZodType, TErrorCode extends string>(
+    def: ToolDefinition<TInput, TResult, TErrorCode>,
+  ): void {
+    if (this.definitions.has(def.name)) {
+      throw new Error(
+        `ToolRegistry.register: "${def.name}" is already registered — operation names ` +
+          'must be unique and stable.',
+      );
+    }
+    this.definitions.set(def.name, def as unknown as ToolDefinition);
+  }
+
+  /** Enumerate every registered operation's metadata. Never invokes `impl`. */
+  listOperations(): ToolSummary[] {
+    return [...this.definitions.values()].map(toSummary);
+  }
+
+  /** Look up one operation's full definition (including `impl`) by name, or `undefined`. */
+  getOperation(name: string): ToolDefinition | undefined {
+    return this.definitions.get(name);
+  }
+
+  has(name: string): boolean {
+    return this.definitions.has(name);
+  }
+
+  /**
+   * Validate `input` against the named operation's input schema, run its
+   * `impl`, validate the return value against its result schema, and return
+   * a uniform `ToolOutcome` — success or a `StructuredOperationError`.
+   * Never throws for an expected failure (unknown name, bad input, impl
+   * throw, bad output); those are exactly what this method exists to turn
+   * into a machine-readable result instead of an exception a caller has to
+   * parse prose out of.
+   */
+  async dispatch<TResult = unknown>(
+    name: string,
+    input: unknown,
+    ctx: ToolContext = {},
+  ): Promise<ToolOutcome<TResult>> {
+    const def = this.definitions.get(name);
+    if (!def) {
+      return {
+        ok: false,
+        error: {
+          code: CORE_ERROR_CODES.OPERATION_NOT_FOUND,
+          message: `No operation is registered as "${name}".`,
+          data: { name },
+        },
+      };
+    }
+
+    const parsedInput = def.input.safeParse(input);
+    if (!parsedInput.success) {
+      return {
+        ok: false,
+        error: {
+          code: CORE_ERROR_CODES.INVALID_INPUT,
+          message: `Input for "${name}" failed schema validation.`,
+          issues: toStructuredIssues(parsedInput.error.issues),
+        },
+      };
+    }
+    const strippedPath = firstStrippedInputPath(input, parsedInput.data);
+    if (strippedPath) {
+      return {
+        ok: false,
+        error: {
+          code: CORE_ERROR_CODES.INVALID_INPUT,
+          message: `Input for "${name}" contains an unknown field.`,
+          issues: [
+            {
+              path: strippedPath,
+              message: 'Unknown input field. Check spelling; unknown fields are never ignored.',
+              code: 'unrecognized_key',
+            },
+          ],
+        },
+      };
+    }
+
+    let rawResult: unknown;
+    try {
+      rawResult = await def.impl(parsedInput.data, ctx);
+    } catch (err) {
+      return { ok: false, error: normalizeThrown(def, err) };
+    }
+
+    const parsedResult = def.result.safeParse(rawResult);
+    if (!parsedResult.success) {
+      return {
+        ok: false,
+        error: {
+          code: CORE_ERROR_CODES.INVALID_OUTPUT,
+          message: `Result of "${name}" failed schema validation (implementation bug).`,
+          issues: toStructuredIssues(parsedResult.error.issues),
+        },
+      };
+    }
+
+    return { ok: true, data: parsedResult.data as TResult };
+  }
+}
+
+export type { ExecutionHost, ExecutionRequirements, ToolContext, ToolNamespace };

package/src/tools/types.ts

@@ -0,0 +1,159 @@
+/**
+ * Shared vocabulary for the operation registry (B1).
+ */
+
+/** The four namespaces every operation name must live under (§5.7). */
+export const TOOL_NAMESPACES = ['project', 'editor', 'play', 'cinematic'] as const;
+export type ToolNamespace = (typeof TOOL_NAMESPACES)[number];
+
+/**
+ * Which of the three hosts an operation executes on (§8 B1, the
+ * review-hardened addition):
+ *  - `node` — runs in the SDK's own Node process against files (or, for
+ *    long-running jobs like `cinematic.render`, launches its own browser).
+ *  - `editor-browser` — invoked through the existing
+ *    `POST /__editor/command` SSE relay in
+ *    `packages/editor-core/server/editor-server.ts`, which broadcasts to the
+ *    connected browser editor and awaits its callback under a short timeout
+ *    (~5s; 120s for `play`). The projection generates the relay stub.
+ *  - `runtime-page` — invoked through the play/render harness in a launched
+ *    runtime page.
+ *
+ * `cinematic.render` is pinned `node` and MUST NOT ride the editor relay's
+ * short timeout — it is a long-running job (see `longRunning` on
+ * `ToolDefinition`).
+ */
+export type ExecutionHost = 'node' | 'editor-browser' | 'runtime-page';
+
+/** Which live contexts an operation needs before it can run. */
+export interface ExecutionRequirements {
+  /** Needs a project directory on disk (no editor process required). */
+  project?: boolean;
+  /** Needs an existing, connected editor session. */
+  editor?: boolean;
+  /** Needs a playable runtime (starts or targets one). */
+  play?: boolean;
+  /** Needs a controlled render runtime. */
+  render?: boolean;
+}
+
+/** Coarse risk classification surfaced to permission-gated callers (agents, HTTP/MCP auth). */
+export type PermissionRisk = 'read' | 'write' | 'destructive';
+
+export interface PermissionMetadata {
+  risk: PermissionRisk;
+  /** Human summary of what this operation is permitted to touch or do. */
+  summary: string;
+}
+
+/** One completed file handed to the host-managed generated-output boundary. */
+export interface ProjectOutputFile {
+  /** Project-relative destination. Slice 1 deliberately permits only public/**. */
+  path: string;
+  content: string | Uint8Array;
+  mediaType?: string;
+  role?: 'asset' | 'provenance' | 'other';
+}
+
+/** JSON-safe summary returned after an atomic generated-output transaction. */
+export interface ProjectGeneratedOutputFile {
+  path: string;
+  bytes: number;
+  mediaType?: string;
+  role?: ProjectOutputFile['role'];
+}
+
+export interface ProjectGeneratedOutput {
+  files: ProjectGeneratedOutputFile[];
+  totalBytes: number;
+  dryRun: boolean;
+  /** Host-created logical record in .volter/provenance.json; absent for dry runs. */
+  provenanceOperationId?: string;
+}
+
+export interface ProjectProviderExecution {
+  mode: 'mock' | 'direct' | 'managed';
+  provider: string;
+  operation?: string;
+  model?: string;
+  requestId?: string;
+  taskId?: string;
+  managedJobId?: string;
+  /** Route-aware charge snapshot when this execution produced accepted output. */
+  billing?: import('../generations.js').GenerationBilling;
+}
+
+/** Facts the operation host already owns and stamps onto every committed batch. */
+export interface ProjectOutputProvenanceContext {
+  operationName: string;
+  operationSource?: string;
+  /** Sanitized facts for a single provider execution. */
+  execution?: ProjectProviderExecution;
+  /** Ordered facts for a native multi-task pipeline that produced one output batch. */
+  executions?: readonly ProjectProviderExecution[];
+  /** WHICH editor session produced the bytes, for a `project.session.write`
+   *  batch — the kind whose producer is a script an agent ran inside a live
+   *  session rather than an operation that ran here. Shape and meaning:
+   *  `project/provenance.ts`'s `ProjectProvenanceSessionSchema`, which is the
+   *  validated form; this mirror exists because `types.ts` carries no zod. */
+  session?: {
+    id: string;
+    port: number;
+    revision: number;
+    callId?: string;
+  };
+  /** Schema-validated, JSON-safe operation input. */
+  input?: unknown;
+  /** Project-relative paths of the project FILES these bytes were produced
+   *  from — a session-written GLB names the `src/models/<name>.blend` it was
+   *  exported from. Shape and meaning: `project/provenance.ts`'s `inputs`,
+   *  which is the validated form; this mirror exists because `types.ts`
+   *  carries no zod. It is what lets a reader drill DOWN by kind from a
+   *  prefab's glTF to the model it came from. */
+  inputs?: readonly string[];
+}
+
+/**
+ * Host capability supplied only to Node-hosted project operations. Generator
+ * implementations may stay ordinary native JS; their thin operation wrapper
+ * calls this once it has a complete batch ready to commit.
+ */
+export interface ProjectOutputWriter {
+  write(
+    files: readonly ProjectOutputFile[],
+    options?: { dryRun?: boolean },
+  ): Promise<ProjectGeneratedOutput>;
+}
+
+/**
+ * Runtime context passed to every operation's `impl`. Intentionally an open
+ * record (`[key: string]: unknown`) — later units (B2-B8) will grow this with
+ * concrete fields (editor session ids, play session handles, render job
+ * state); B1 only needs the two seams its sample operations touch.
+ */
+export interface ToolContext {
+  /** Absolute path to the target project's root, for `project`-context ops. */
+  projectRoot?: string;
+  /** Base URL of a connected editor session, for `editor`-context ops. */
+  editorUrl?: string;
+  /** Cooperative cancellation for long-running (`node`, `longRunning`) ops. */
+  signal?: AbortSignal;
+  /** Atomic writer for generated project assets (Node project operations). */
+  projectOutputs?: ProjectOutputWriter;
+  /** WHICH mounted instance a game-driving tool should address, when the
+   *  editor has several live (multiplayer authoring). A tool that drives the
+   *  game binds `game.instance(ctx.instance)` from it; omitted means the sole
+   *  live instance. */
+  instance?: string;
+  /** The HOST's project-module loader (the editor server's Vite SSR loader,
+   *  wrapped with dependency-change invalidation). A tool that imports the
+   *  project's own source at run time — `project.bake.preview` importing
+   *  `src/models/barrel.ts` — MUST load through this rather than a raw
+   *  `import()`: Node's ESM cache never invalidates, so a raw import returned
+   *  the FIRST version of a model for the life of the server and every later
+   *  edit re-rendered byte-identical until the editor's `restart` command (measured on the
+   *  blind modeling bench, 2026-09-05: three restarts in one barrel). Absent
+   *  only when the tool runs outside an editor server. */
+  loadProjectModule?: (absolutePath: string) => Promise<unknown>;
+  [key: string]: unknown;
+}