@vgai/sdk 0.4.0-canary.20260715.0

package/src/mcp/mcp-projection.ts

@@ -0,0 +1,288 @@
+/**
+ * MCP projection of the operation registry (B8, §8 B8).
+ *
+ * The SAME `OperationRegistry` 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
+ * an operation to the SDK gives it an MCP tool for free, just as it gives it
+ * a CLI subcommand (B6) and an HTTP route for free.
+ *
+ * TRANSPORT — HAND-ROLLED, NOT `@modelcontextprotocol/sdk`. That package is
+ * NOT installed in this repo (confirmed: no `@modelcontextprotocol/*` in any
+ * package.json or node_modules). §8 B8 asks only that MCP tools be registered
+ * from the same operation definitions and stay an optional projection; it does
+ * not mandate a particular library or wire transport. So I implement the MCP
+ * JSON-RPC 2.0 message shape directly (`initialize`, `tools/list`,
+ * `tools/call`, `resources/list`, `resources/read`) via this projection's
+ * `handle` method — the derivation of tools/resources from the registry is
+ * what matters here, and it is transport-independent. If the official SDK is
+ * later added, only a transport wrapper around `handle` changes; the
+ * derivation below does not.
+ *
+ * `handle` is IN-PROCESS ONLY today — it takes a parsed JSON-RPC request and
+ * returns a response object, which the tests (and any embedding host) drive
+ * directly; there is no stdio/HTTP-SSE transport bound to it yet. A real
+ * stdio/SSE transport wrapper is a tracked follow-up.
+ *
+ * RESOURCE-vs-TOOL DECISION (§8 B8 AC: "Read-only state is exposed as
+ * resources when that is more appropriate than a tool"):
+ *  - An operation is exposed as a TOOL always (tools can take arguments; a
+ *    parameterised read like `project.scene.read` NEEDS its `scenePath`
+ *    argument, which an MCP resource read — identified only by a URI, with no
+ *    arguments — cannot carry).
+ *  - An operation is ADDITIONALLY exposed as a RESOURCE exactly when it is
+ *    read-only (`mutates: false`) AND its input schema accepts the empty
+ *    object `{}` (no required arguments) — i.e. it names a piece of readable
+ *    STATE that a client can `resources/read` by URI alone, with nothing to
+ *    parameterise. `project.status` and `cinematic.capabilities` qualify;
+ *    `project.scene.read` (needs `scenePath`) does not and stays tool-only.
+ *  A resource's URI is `vgai://op/<name>`; reading it dispatches the op with
+ *  `{}` and returns the SAME structured result the tool call would.
+ *
+ * ERROR FIDELITY: a `tools/call` (or `resources/read`) whose dispatch fails
+ * returns the registry's `{ ok: false, error }` outcome verbatim inside the
+ * tool result (with `isError: true`), so `error.code` over MCP is byte-for-
+ * byte the code the SDK, CLI, and HTTP projection produce for the same input.
+ */
+
+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';
+
+/** URI scheme/prefix under which read-only-state operations are also exposed as MCP resources. */
+export const MCP_RESOURCE_PREFIX = 'vgai://op/';
+
+/** One MCP tool descriptor, as returned by `tools/list`. */
+export interface McpTool {
+  name: string;
+  description: string;
+  inputSchema: unknown;
+}
+
+/** One MCP resource descriptor, as returned by `resources/list`. */
+export interface McpResource {
+  uri: string;
+  name: string;
+  description: string;
+  mimeType: string;
+}
+
+export interface McpProjectionOptions {
+  /** Registry to project. Defaults to the shared `operations` registry (same one the CLI/HTTP projections use). */
+  registry?: OperationRegistry;
+  /** Static context handed to every dispatch. Ignored when `createContext` is given. */
+  context?: OperationContext;
+  /** Per-call context factory (wins over `context`). */
+  createContext?: () => OperationContext | Promise<OperationContext>;
+}
+
+/** The Zod-derived JSON Schema for an op's input — the SAME conversion the HTTP manifest uses. */
+export function toolInputSchema(summary: OperationSummary): unknown {
+  return z.toJSONSchema(summary.input, { unrepresentable: 'any' });
+}
+
+/** Derive one MCP tool from an operation summary: dotted name (mirrors §5.7 hierarchy), description, Zod-derived schema. */
+export function operationToTool(summary: OperationSummary): McpTool {
+  return {
+    name: summary.name,
+    description: `${summary.summary}\n\n${summary.description}`.trim(),
+    inputSchema: toolInputSchema(summary),
+  };
+}
+
+/** 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 {
+  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 {
+  return {
+    uri: `${MCP_RESOURCE_PREFIX}${summary.name}`,
+    name: summary.name,
+    description: summary.summary,
+    mimeType: 'application/json',
+  };
+}
+
+// ---------------------------------------------------------------------------
+// JSON-RPC 2.0 message shape (the MCP wire contract, hand-rolled)
+// ---------------------------------------------------------------------------
+
+export interface JsonRpcRequest {
+  jsonrpc: '2.0';
+  id?: string | number | null;
+  method: string;
+  params?: unknown;
+}
+
+export interface JsonRpcResponse {
+  jsonrpc: '2.0';
+  id: string | number | null;
+  result?: unknown;
+  error?: { code: number; message: string; data?: unknown };
+}
+
+/** JSON-RPC error codes used by this projection (the MCP-relevant subset of the spec's reserved range). */
+const RPC_METHOD_NOT_FOUND = -32601;
+const RPC_INVALID_PARAMS = -32602;
+
+function rpcResult(id: string | number | null, result: unknown): JsonRpcResponse {
+  return { jsonrpc: '2.0', id, result };
+}
+
+function rpcError(
+  id: string | number | null,
+  code: number,
+  message: string,
+  data?: unknown,
+): JsonRpcResponse {
+  return { jsonrpc: '2.0', id, error: { code, message, ...(data !== undefined ? { data } : {}) } };
+}
+
+/**
+ * Wrap an `OperationOutcome` 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
+ * `structuredContent` (the real MCP spec field name for a machine-readable
+ * tool result) so `error.code` survives unchanged. `isError` mirrors
+ * `!outcome.ok`.
+ */
+export function outcomeToToolResult(outcome: OperationOutcome): {
+  content: { type: 'text'; text: string }[];
+  isError: boolean;
+  structuredContent: OperationOutcome;
+} {
+  return {
+    content: [{ type: 'text', text: JSON.stringify(outcome) }],
+    isError: !outcome.ok,
+    structuredContent: outcome,
+  };
+}
+
+/**
+ * The MCP projection object: derive tools/resources from the registry and
+ * handle MCP JSON-RPC messages. `handle` is the single entry point a
+ * transport (or a test) drives.
+ */
+export interface McpProjection {
+  registry: OperationRegistry;
+  listTools(): McpTool[];
+  listResources(): McpResource[];
+  callTool(name: string, args: unknown): Promise<OperationOutcome>;
+  readResource(uri: string): Promise<OperationOutcome>;
+  handle(request: JsonRpcRequest): Promise<JsonRpcResponse>;
+}
+
+export function createMcpProjection(options: McpProjectionOptions = {}): McpProjection {
+  const registry = options.registry ?? defaultRegistry;
+
+  async function resolveContext(): Promise<OperationContext> {
+    if (options.createContext) return options.createContext();
+    return options.context ?? {};
+  }
+
+  function listTools(): McpTool[] {
+    return registry
+      .listOperations()
+      .map(operationToTool)
+      .sort((a, b) => a.name.localeCompare(b.name));
+  }
+
+  function listResources(): McpResource[] {
+    return registry
+      .listOperations()
+      .filter(isResourceEligible)
+      .map(operationToResource)
+      .sort((a, b) => a.uri.localeCompare(b.uri));
+  }
+
+  async function callTool(name: string, args: unknown): Promise<OperationOutcome> {
+    // 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> {
+    if (!uri.startsWith(MCP_RESOURCE_PREFIX)) {
+      return {
+        ok: false,
+        error: {
+          code: CORE_ERROR_CODES.OPERATION_NOT_FOUND,
+          message: `Resource URI must start with ${MCP_RESOURCE_PREFIX}; got "${uri}".`,
+          data: { uri },
+        },
+      };
+    }
+    const name = uri.slice(MCP_RESOURCE_PREFIX.length);
+    const summary = registry.listOperations().find((op) => op.name === name);
+    if (!summary || !isResourceEligible(summary)) {
+      return {
+        ok: false,
+        error: {
+          code: CORE_ERROR_CODES.OPERATION_NOT_FOUND,
+          message: `No read-only resource is exposed at "${uri}".`,
+          data: { uri },
+        },
+      };
+    }
+    return registry.dispatch(name, {}, await resolveContext());
+  }
+
+  async function handle(request: JsonRpcRequest): Promise<JsonRpcResponse> {
+    const id = request.id ?? null;
+    const params = (request.params ?? {}) as Record<string, unknown>;
+
+    switch (request.method) {
+      case 'initialize':
+        return rpcResult(id, {
+          protocolVersion: '2024-11-05',
+          capabilities: { tools: {}, resources: {} },
+          serverInfo: { name: 'vgai-operation-registry', version: '0.1.0' },
+        });
+
+      case 'tools/list':
+        return rpcResult(id, { tools: listTools() });
+
+      case 'tools/call': {
+        const name = params['name'];
+        if (typeof name !== 'string') {
+          return rpcError(id, RPC_INVALID_PARAMS, 'tools/call requires a string `name`.');
+        }
+        const outcome = await callTool(name, params['arguments']);
+        return rpcResult(id, outcomeToToolResult(outcome));
+      }
+
+      case 'resources/list':
+        return rpcResult(id, { resources: listResources() });
+
+      case 'resources/read': {
+        const uri = params['uri'];
+        if (typeof uri !== 'string') {
+          return rpcError(id, RPC_INVALID_PARAMS, 'resources/read requires a string `uri`.');
+        }
+        const outcome = await readResource(uri);
+        return rpcResult(id, {
+          contents: [
+            {
+              uri,
+              mimeType: 'application/json',
+              text: JSON.stringify(outcome),
+            },
+          ],
+          isError: !outcome.ok,
+        });
+      }
+
+      default:
+        return rpcError(id, RPC_METHOD_NOT_FOUND, `Unknown MCP method "${request.method}".`);
+    }
+  }
+
+  return { registry, listTools, listResources, callTool, readResource, handle };
+}

package/src/operations.ts

@@ -0,0 +1,83 @@
+/**
+ * B1's sample operation(s). Per the spec ("you may register a SMALL set of
+ * real or stub-but-typed ops to exercise the registry ... the point is the
+ * REGISTRY MACHINERY + validation, not implementing all of B2-B8"), this
+ * exercises a real filesystem read (project.status) without duplicating
+ * B2/B3/B4/B5's real work.
+ *
+ * B1 originally also registered TWO further stand-ins here:
+ *  - `editor.selection.get` (an editor-browser-host op that always threw
+ *    EDITOR_NOT_RUNNING) — B3 (`./editor/selection-operations.ts`) now
+ *    registers the REAL `editor.selection.get` under the same name.
+ *  - `cinematic.render` (a node/longRunning op that always threw
+ *    NOT_IMPLEMENTED, to exercise the review-hardened execution-host
+ *    metadata shape end to end) — B5 (`./cinematic/render-operations.ts`)
+ *    now registers the REAL `cinematic.render` under the same name.
+ * Both stand-ins were removed from here to avoid a duplicate-name
+ * registration; see each namespace's own `index.ts` for the live
+ * implementation.
+ */
+
+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';
+
+// ---------------------------------------------------------------------------
+// project.status — real, file-native (B2 project.* stand-in)
+// ---------------------------------------------------------------------------
+
+export const ProjectStatusInput = z
+  .object({})
+  .describe('No input — status is computed for ctx.projectRoot.');
+
+export const ProjectStatusResult = z
+  .object({
+    projectRoot: z.string().describe('Absolute path this status was computed for.'),
+    hasProject: z
+      .boolean()
+      .describe('True when a vgai.game.json manifest exists directly under projectRoot.'),
+  })
+  .describe('Discovery result for the project at ctx.projectRoot.');
+
+export const projectStatus = defineOperation({
+  name: 'project.status',
+  summary: 'Report whether a vgai project manifest exists at the execution context project root.',
+  description:
+    'File-native discovery operation (B2 project.* namespace stand-in for B1). Reads ' +
+    'ctx.projectRoot from disk — no editor process required — and reports whether a ' +
+    'vgai.game.json manifest is present there.',
+  input: ProjectStatusInput,
+  result: ProjectStatusResult,
+  errors: [
+    {
+      code: 'NO_PROJECT_ROOT',
+      summary: 'dispatch() was called without ctx.projectRoot.',
+      data: z.object({}).describe('No additional data.'),
+    },
+  ],
+  requires: { project: true },
+  host: 'node',
+  mutates: false,
+  supportsDryRun: false,
+  permission: { risk: 'read', summary: "Reads one file's existence under projectRoot; no writes." },
+  async impl(_input, ctx) {
+    if (!ctx.projectRoot) {
+      throw new OperationError(
+        'NO_PROJECT_ROOT',
+        'dispatch() was called without ctx.projectRoot.',
+        {},
+      );
+    }
+    return {
+      projectRoot: ctx.projectRoot,
+      hasProject: existsSync(join(ctx.projectRoot, 'vgai.game.json')),
+    };
+  },
+});
+
+/** Register every B1 sample operation onto `registry`. */
+export function registerBuiltinOperations(registry: OperationRegistry): void {
+  registry.register(projectStatus);
+}

package/src/play/control-operations.ts

@@ -0,0 +1,205 @@
+/**
+ * `play.seed.set` / `play.timeScale.set`
+ * (B4, §8 B4 "deterministic seed and time-scale control").
+ *
+ * TIME-SCALE is REAL since Wave 5 (docs/SYNTHETIC-PLAYER-SPEC.md §3.5): the
+ * `set-time-scale` relay case (`command-listener.ts`) reaches the live
+ * session's `GameLoop.timeScale` (`packages/engine/src/core/game-loop.ts`,
+ * a live get/set property clamped to `[0, 8]`) through `play-mode.ts`'s
+ * `getPlayRuntimeAccess()`, and `collectState` reports the applied value
+ * back through `play.status`. `TIME_SCALE_CONTROL_UNSUPPORTED` now fires
+ * only against a stale editor page (the structured `UNKNOWN_COMMAND_TYPE`
+ * marker, translated to `undefined` by the transport) — or a session where
+ * play isn't running, which surfaces as `COMMAND_FAILED`.
+ *
+ * SEED is REAL since D15/T-D15.6 (`docs/D15-DETERMINISM-DESIGN.md` §2.d) —
+ * no longer an honest gap. `play.seed.set` reaches the live session's
+ * `ctx.random.reseed(seed)` (`packages/engine/src/core/seeded-random.ts`,
+ * built on T-D15.1's core) through the `set-seed` relay case
+ * (`command-listener.ts`) and `play-mode.ts`'s `getPlayRuntimeAccess()`.
+ * Semantics are FUTURE-DRAWS-ONLY, matching `SeededRandom.reseed`'s own
+ * contract exactly: reseeding mid-run re-derives every live stream so every
+ * draw AFTER this call is reproducible from the new seed, but it can never
+ * make an already-diverged session's PAST draws reproducible — for a fully
+ * reproducible run, pass the seed at session start instead (manifest
+ * `determinism.defaultSeed` / `?vgai-seed=` / `play.start`'s `seed` field /
+ * `vgai play --seed` / a probe fixture seed option). Throws the declared
+ * `DETERMINISM_NOT_DECLARED` when the running project's manifest doesn't
+ * declare `determinism.seededRandom` — reseeding a project with no
+ * documented determinism contract would silently imply one exists.
+ * `SEED_CONTROL_UNSUPPORTED` now fires only against a stale editor page (the
+ * structured `UNKNOWN_COMMAND_TYPE` marker) — the SAME shape
+ * `TIME_SCALE_CONTROL_UNSUPPORTED_ERROR` uses for its own version-skew case,
+ * immediately below.
+ */
+
+import { z } from 'zod';
+import { OperationError } from '../errors.js';
+import { defineOperation, type OperationRegistry } from '../registry.js';
+import {
+  getPlayTransport,
+  PLAY_COMMAND_TIMEOUT_MS,
+  PLAY_RUNTIME_NOT_AVAILABLE_ERROR,
+  relayErrorMarker,
+  resolvePlaySession,
+  withPlayTimeout,
+} from './transport.js';
+
+const COMMAND_FAILED_ERROR = {
+  code: 'COMMAND_FAILED',
+  summary: 'The connected editor rejected or failed to execute the relayed control command.',
+  data: z.object({ message: z.string() }),
+} as const;
+
+const SEED_CONTROL_UNSUPPORTED_ERROR = {
+  code: 'SEED_CONTROL_UNSUPPORTED',
+  summary:
+    'The connected editor page predates the set-seed relay command (version skew, matched on ' +
+    'the structured UNKNOWN_COMMAND_TYPE marker) — reload the editor tab. Never silently ' +
+    'reported as success.',
+  data: z.object({}),
+} as const;
+
+const DETERMINISM_NOT_DECLARED_ERROR = {
+  code: 'DETERMINISM_NOT_DECLARED',
+  summary:
+    "The running project's manifest does not declare determinism.seededRandom (D15) — " +
+    'play.seed.set has no documented determinism contract to reseed against. Declare the ' +
+    'block (docs/D15-DETERMINISM-DESIGN.md §2.a) to opt in.',
+  data: z.object({}),
+} as const;
+
+const TIME_SCALE_CONTROL_UNSUPPORTED_ERROR = {
+  code: 'TIME_SCALE_CONTROL_UNSUPPORTED',
+  summary:
+    'The connected editor page predates the set-time-scale relay command (version skew, ' +
+    'matched on the structured UNKNOWN_COMMAND_TYPE marker) — reload the editor tab. Never ' +
+    'silently reported as success.',
+  data: z.object({}),
+} as const;
+
+const OkResult = z.object({ ok: z.literal(true) });
+
+// ---------------------------------------------------------------------------
+// play.seed.set
+// ---------------------------------------------------------------------------
+
+const PlaySeedSetInput = z.object({
+  seed: z.number().int().describe('Deterministic seed value to apply to the running play session.'),
+});
+
+export const playSeedSet = defineOperation({
+  name: 'play.seed.set',
+  summary: 'Live-reseed a running play session (future draws only).',
+  description:
+    "Reaches the live session's ctx.random.reseed(seed) (D15/T-D15.6) through the set-seed relay " +
+    'case — future draws only, never a fabricated retroactive reproducibility (see module ' +
+    'jsdoc). Throws DETERMINISM_NOT_DECLARED when the running project has no ' +
+    'determinism.seededRandom manifest declaration, or SEED_CONTROL_UNSUPPORTED against a stale ' +
+    'editor page.',
+  input: PlaySeedSetInput,
+  result: OkResult,
+  errors: [
+    PLAY_RUNTIME_NOT_AVAILABLE_ERROR,
+    SEED_CONTROL_UNSUPPORTED_ERROR,
+    DETERMINISM_NOT_DECLARED_ERROR,
+    COMMAND_FAILED_ERROR,
+  ],
+  requires: { editor: true, play: true },
+  host: 'runtime-page',
+  mutates: true,
+  supportsDryRun: false,
+  permission: {
+    risk: 'write',
+    summary: "Would set the live play session's RNG seed, when supported.",
+  },
+  async impl(input, ctx) {
+    const transport = getPlayTransport(ctx);
+    const session = await resolvePlaySession(ctx, transport);
+    const result = await withPlayTimeout(
+      transport.setSeed(session, input.seed, PLAY_COMMAND_TIMEOUT_MS),
+      PLAY_COMMAND_TIMEOUT_MS,
+      'play.seed.set',
+    ).catch(() => undefined);
+    if (!result) {
+      throw new OperationError(
+        'SEED_CONTROL_UNSUPPORTED',
+        'The connected editor page predates the set-seed relay command — reload it.',
+        {},
+      );
+    }
+    if (!result.ok) {
+      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 OperationError('COMMAND_FAILED', message, { message });
+    }
+    return { ok: true as const };
+  },
+});
+
+// ---------------------------------------------------------------------------
+// play.timeScale.set
+// ---------------------------------------------------------------------------
+
+const PlayTimeScaleSetInput = z.object({
+  timeScale: z
+    .number()
+    .min(0)
+    .max(8)
+    .describe('Simulation time-scale to apply (clamped [0,8] to match GameLoop.timeScale).'),
+});
+
+export const playTimeScaleSet = defineOperation({
+  name: 'play.timeScale.set',
+  summary: "Set a running play session's simulation time-scale.",
+  description:
+    "Sets the live session's GameLoop.timeScale (clamped [0,8]) through the set-time-scale " +
+    'relay command; the applied value is reflected by a subsequent play.status read. Throws ' +
+    'TIME_SCALE_CONTROL_UNSUPPORTED against a stale editor page (see module jsdoc).',
+  input: PlayTimeScaleSetInput,
+  result: OkResult,
+  errors: [
+    PLAY_RUNTIME_NOT_AVAILABLE_ERROR,
+    TIME_SCALE_CONTROL_UNSUPPORTED_ERROR,
+    COMMAND_FAILED_ERROR,
+  ],
+  requires: { editor: true, play: true },
+  host: 'runtime-page',
+  mutates: true,
+  supportsDryRun: false,
+  permission: {
+    risk: 'write',
+    summary: "Would set the live play session's simulation time-scale, when supported.",
+  },
+  async impl(input, ctx) {
+    const transport = getPlayTransport(ctx);
+    const session = await resolvePlaySession(ctx, transport);
+    const result = await withPlayTimeout(
+      transport.setTimeScale(session, input.timeScale, PLAY_COMMAND_TIMEOUT_MS),
+      PLAY_COMMAND_TIMEOUT_MS,
+      'play.timeScale.set',
+    ).catch(() => undefined);
+    if (!result) {
+      throw new OperationError(
+        'TIME_SCALE_CONTROL_UNSUPPORTED',
+        "The connected editor has no wire-level command to change a live play session's " +
+          'time-scale today.',
+        {},
+      );
+    }
+    if (!result.ok) {
+      throw new OperationError('COMMAND_FAILED', result.error ?? 'set-time-scale command failed', {
+        message: result.error ?? 'set-time-scale command failed',
+      });
+    }
+    return { ok: true as const };
+  },
+});
+
+export function registerControlOperations(registry: OperationRegistry): void {
+  registry.register(playSeedSet);
+  registry.register(playTimeScaleSet);
+}