@vgai/sdk 0.5.0 → 0.5.2

package/src/editor/hierarchy-operations.ts

@@ -12,8 +12,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,
@@ -56,7 +56,7 @@ const EditorHierarchyInspectResult = z.object({
     ),
 });
 
-export const editorHierarchyInspect = defineOperation({
+export const editorHierarchyInspect = defineTool({
   name: 'editor.hierarchy.inspect',
   summary: "Inspect the entity hierarchy of the target editor session's currently loaded scene.",
   description:
@@ -80,7 +80,7 @@ export const editorHierarchyInspect = defineOperation({
       'editor.hierarchy.inspect',
     ).catch(() => undefined);
     if (!hierarchy) {
-      throw new OperationError(
+      throw new ToolError(
         'HIERARCHY_UNAVAILABLE',
         'The connected editor session did not answer the hierarchy-state read in time.',
         {},
@@ -90,6 +90,6 @@ export const editorHierarchyInspect = defineOperation({
   },
 });
 
-export function registerHierarchyOperations(registry: OperationRegistry): void {
+export function registerHierarchyOperations(registry: ToolRegistry): void {
   registry.register(editorHierarchyInspect);
 }

package/src/editor/index.ts

@@ -1,7 +1,7 @@
 /**
  * B3 — `editor.*` operations
  * (docs/AI-NATIVE-AUTHORING-IMPLEMENTATION-SPEC.md §8 B3). Registered
- * separately from B1's `registerBuiltinOperations` (`../operations.ts`) and
+ * separately from B1's `registerBuiltinTools` (`../operations.ts`) and
  * B2's `registerProjectOperations` (`../project/index.ts`) — the default
  * `operations` singleton (`../index.ts`) calls all three.
  */
@@ -39,7 +39,7 @@ export {
   withTimeout,
 } from './transport.js';
 
-import type { OperationRegistry } from '../registry.js';
+import type { ToolRegistry } from '../registry.js';
 import { registerCameraOperations } from './camera-operations.js';
 import { registerConsoleOperations } from './console-operations.js';
 import { registerHierarchyOperations } from './hierarchy-operations.js';
@@ -50,7 +50,7 @@ import { registerSessionOperations } from './session-operations.js';
 import { registerSourceLocationOperations } from './source-location-operations.js';
 
 /** Register every B3 `editor.*` operation onto `registry`. */
-export function registerEditorOperations(registry: OperationRegistry): void {
+export function registerEditorOperations(registry: ToolRegistry): void {
   registerSessionOperations(registry);
   registerSelectionOperations(registry);
   registerHierarchyOperations(registry);

package/src/editor/open-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,
@@ -58,7 +58,7 @@ const EditorSceneOpenInput = z.object({
     .describe('Project-relative path to a .vscn.json scene file to open in the editor.'),
 });
 
-export const editorSceneOpen = defineOperation({
+export const editorSceneOpen = defineTool({
   name: 'editor.scene.open',
   summary: 'Open a scene file in a connected editor session.',
   description:
@@ -87,7 +87,7 @@ export const editorSceneOpen = defineOperation({
       error: err instanceof Error ? err.message : String(err),
     }));
     if (!result.ok) {
-      throw new OperationError('COMMAND_FAILED', result.error ?? 'open-scene command failed', {
+      throw new ToolError('COMMAND_FAILED', result.error ?? 'open-scene command failed', {
         message: result.error ?? 'open-scene command failed',
       });
     }
@@ -115,7 +115,7 @@ const EditorAssetOpenInput = z.object({
   kind: AssetKindSchema,
 });
 
-export const editorAssetOpen = defineOperation({
+export const editorAssetOpen = defineTool({
   name: 'editor.asset.open',
   summary: 'Open an asset as a tab in a connected editor session.',
   description:
@@ -144,7 +144,7 @@ export const editorAssetOpen = defineOperation({
       error: err instanceof Error ? err.message : String(err),
     }));
     if (!result.ok) {
-      throw new OperationError('COMMAND_FAILED', result.error ?? 'open-asset-tab command failed', {
+      throw new ToolError('COMMAND_FAILED', result.error ?? 'open-asset-tab command failed', {
         message: result.error ?? 'open-asset-tab command failed',
       });
     }
@@ -160,7 +160,7 @@ const EditorStoryOpenInput = z.object({
   path: z.string().describe('Project-relative path to a *.stories.tsx/*.stories.ts module.'),
 });
 
-export const editorStoryOpen = defineOperation({
+export const editorStoryOpen = defineTool({
   name: 'editor.story.open',
   summary: 'Open a Storybook CSF story in a connected editor session.',
   description:
@@ -187,14 +187,14 @@ export const editorStoryOpen = defineOperation({
       'editor.story.open',
     ).catch(() => undefined);
     if (!result) {
-      throw new OperationError(
+      throw new ToolError(
         'STORY_OPEN_UNSUPPORTED',
         'The connected editor has no wire-level command to open a story today.',
         {},
       );
     }
     if (!result.ok) {
-      throw new OperationError('COMMAND_FAILED', result.error ?? 'open-story command failed', {
+      throw new ToolError('COMMAND_FAILED', result.error ?? 'open-story command failed', {
         message: result.error ?? 'open-story command failed',
       });
     }
@@ -202,7 +202,7 @@ export const editorStoryOpen = defineOperation({
   },
 });
 
-export function registerOpenOperations(registry: OperationRegistry): void {
+export function registerOpenOperations(registry: ToolRegistry): void {
   registry.register(editorSceneOpen);
   registry.register(editorAssetOpen);
   registry.register(editorStoryOpen);

package/src/editor/screenshot-operations.ts

@@ -16,8 +16,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,
@@ -56,7 +56,7 @@ const EditorViewportScreenshotCaptureResult = z
   })
   .describe('A viewport image — fresh when possible, the last-saved thumbnail otherwise.');
 
-export const editorViewportScreenshotCapture = defineOperation({
+export const editorViewportScreenshotCapture = defineTool({
   name: 'editor.viewport.screenshot.capture',
   summary: "Capture the target editor session's live viewport (falls back to its saved thumbnail).",
   description:
@@ -84,7 +84,7 @@ export const editorViewportScreenshotCapture = defineOperation({
       'editor.viewport.screenshot.capture',
     ).catch(() => undefined);
     if (!shot) {
-      throw new OperationError(
+      throw new ToolError(
         'SCREENSHOT_UNAVAILABLE',
         'No fresh capture or saved thumbnail is available for this session, or the read timed out.',
         {},
@@ -94,6 +94,6 @@ export const editorViewportScreenshotCapture = defineOperation({
   },
 });
 
-export function registerScreenshotOperations(registry: OperationRegistry): void {
+export function registerScreenshotOperations(registry: ToolRegistry): void {
   registry.register(editorViewportScreenshotCapture);
 }

package/src/editor/selection-operations.ts

@@ -10,8 +10,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,
@@ -51,7 +51,7 @@ const EditorSelectionGetResult = z
   })
   .describe('Live selection snapshot from the resolved editor session.');
 
-export const editorSelectionGet = defineOperation({
+export const editorSelectionGet = defineTool({
   name: 'editor.selection.get',
   summary: 'Read the current entity selection from a connected editor session.',
   description:
@@ -75,7 +75,7 @@ export const editorSelectionGet = defineOperation({
       'editor.selection.get',
     ).catch(() => undefined);
     if (!selection) {
-      throw new OperationError(
+      throw new ToolError(
         'SELECTION_UNAVAILABLE',
         'The connected editor session did not answer the selection-state read in time.',
         {},
@@ -97,7 +97,7 @@ const EditorSelectionSetInput = z
 
 const EditorSelectionSetResult = z.object({ ok: z.literal(true) });
 
-export const editorSelectionSet = defineOperation({
+export const editorSelectionSet = defineTool({
   name: 'editor.selection.set',
   summary: 'Set the entity selection in a connected editor session.',
   description:
@@ -130,7 +130,7 @@ export const editorSelectionSet = defineOperation({
       error: err instanceof Error ? err.message : String(err),
     }));
     if (!result.ok) {
-      throw new OperationError('COMMAND_FAILED', result.error ?? 'select command failed', {
+      throw new ToolError('COMMAND_FAILED', result.error ?? 'select command failed', {
         message: result.error ?? 'select command failed',
       });
     }
@@ -138,7 +138,7 @@ export const editorSelectionSet = defineOperation({
   },
 });
 
-export function registerSelectionOperations(registry: OperationRegistry): void {
+export function registerSelectionOperations(registry: ToolRegistry): void {
   registry.register(editorSelectionGet);
   registry.register(editorSelectionSet);
 }

package/src/editor/session-operations.ts

@@ -19,7 +19,7 @@
  */
 
 import { z } from 'zod';
-import { defineOperation, type OperationRegistry } from '../registry.js';
+import { defineTool, type ToolRegistry } from '../registry.js';
 import { EDITOR_SESSION_DISCOVERY_TIMEOUT_MS, getTransport } from './transport.js';
 
 const EditorSessionListInput = z
@@ -41,7 +41,7 @@ const EditorSessionListResult = z.object({
     .describe('Every live session that answered a liveness probe, in no particular order.'),
 });
 
-export const editorSessionList = defineOperation({
+export const editorSessionList = defineTool({
   name: 'editor.session.list',
   summary: 'List every live, probe-verified editor dev-server session on this machine.',
   description:
@@ -68,6 +68,6 @@ export const editorSessionList = defineOperation({
   },
 });
 
-export function registerSessionOperations(registry: OperationRegistry): void {
+export function registerSessionOperations(registry: ToolRegistry): void {
   registry.register(editorSessionList);
 }

package/src/editor/source-location-operations.ts

@@ -14,8 +14,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,
@@ -50,7 +50,7 @@ const EditorSourceLocationLookupResult = z
   })
   .describe('Source location for the given oid. Never mutates anything.');
 
-export const editorSourceLocationLookup = defineOperation({
+export const editorSourceLocationLookup = defineTool({
   name: 'editor.sourceLocation.lookup',
   summary: "Map an inspected React element's oid to its exact component/source location.",
   description:
@@ -81,7 +81,7 @@ export const editorSourceLocationLookup = defineOperation({
       'editor.sourceLocation.lookup',
     ).catch(() => undefined);
     if (!index) {
-      throw new OperationError(
+      throw new ToolError(
         'SOURCE_INDEX_UNAVAILABLE',
         'The connected editor session did not answer the source-location index read in time.',
         {},
@@ -89,7 +89,7 @@ export const editorSourceLocationLookup = defineOperation({
     }
     const entry = index[input.oid];
     if (!entry) {
-      throw new OperationError(
+      throw new ToolError(
         'SOURCE_LOCATION_NOT_FOUND',
         `No source location for oid "${input.oid}".`,
         {
@@ -101,6 +101,6 @@ export const editorSourceLocationLookup = defineOperation({
   },
 });
 
-export function registerSourceLocationOperations(registry: OperationRegistry): void {
+export function registerSourceLocationOperations(registry: ToolRegistry): void {
   registry.register(editorSourceLocationLookup);
 }

package/src/editor/transport.ts

@@ -21,7 +21,7 @@
  *     EDITOR_NOT_RUNNING rather than hanging").
  *
  * `EditorTransport` is INJECTABLE via `ctx['editorTransport']` (a plain
- * bag key on `OperationContext`'s open `[key: string]: unknown` — no change
+ * bag key on `ToolContext`'s open `[key: string]: unknown` — no change
  * to `types.ts` needed) so tests can swap in a mock/fake transport and
  * exercise every op headlessly, with no real browser or dev server
  * (see `../../test/editor-operations.test.ts`).
@@ -109,9 +109,9 @@ import { existsSync, readFileSync, realpathSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join, resolve } from 'node:path';
 import { z } from 'zod';
-import { OperationError } from '../errors.js';
-import type { ErrorDefinition } from '../registry.js';
-import type { OperationContext } from '../types.js';
+import { ToolError } from '../errors.js';
+import type { ToolErrorDefinition } from '../registry.js';
+import type { ToolContext } from '../types.js';
 
 // ---------------------------------------------------------------------------
 // Named timeouts (§8 B3 AC: "enforce a named timeout, don't block forever")
@@ -172,6 +172,8 @@ export interface EditorSessionInfo {
   project: string | null;
   /** Dev-server process id, when known from the local session registry (null for an unregistered/legacy server the caller only probed by port). */
   pid: number | null;
+  /** Registry discriminator. `kind: 'e2e'` is a standalone proof server, never an editor-control target. */
+  kind?: string;
   /** Exact explicitly targeted editor origin/base URL, including protocol and host. */
   url?: string;
 }
@@ -295,6 +297,7 @@ interface RegistrySessionEntry {
   port: number;
   pid: number;
   startedAt: string;
+  kind?: string;
 }
 
 function isRegistrySessionEntry(v: unknown): v is RegistrySessionEntry {
@@ -304,7 +307,8 @@ function isRegistrySessionEntry(v: unknown): v is RegistrySessionEntry {
     (typeof s['project'] === 'string' || s['project'] === null) &&
     typeof s['port'] === 'number' &&
     typeof s['pid'] === 'number' &&
-    typeof s['startedAt'] === 'string'
+    typeof s['startedAt'] === 'string' &&
+    (s['kind'] === undefined || typeof s['kind'] === 'string')
   );
 }
 
@@ -328,7 +332,10 @@ function readRegisteredSessions(): RegistrySessionEntry[] {
   try {
     const raw: unknown = JSON.parse(readFileSync(registryFile, 'utf8'));
     return Array.isArray(raw)
-      ? raw.filter(isRegistrySessionEntry).filter((s) => pidAlive(s.pid))
+      ? raw
+          .filter(isRegistrySessionEntry)
+          .filter((s) => s.kind !== 'e2e')
+          .filter((s) => pidAlive(s.pid))
       : [];
   } catch {
     return [];
@@ -400,7 +407,12 @@ export class HttpEditorTransport implements EditorTransport {
         );
         if (body === undefined) return undefined;
         const project = (body as { project?: { path?: string } | null }).project?.path ?? null;
-        const info: EditorSessionInfo = { port: s.port, project, pid: s.pid };
+        const info: EditorSessionInfo = {
+          port: s.port,
+          project,
+          pid: s.pid,
+          ...(s.kind !== undefined ? { kind: s.kind } : {}),
+        };
         return info;
       }),
     );
@@ -577,7 +589,7 @@ export class HttpEditorTransport implements EditorTransport {
 const defaultTransport = new HttpEditorTransport();
 
 /** Resolve the transport to use: `ctx['editorTransport']` when injected (tests), else the shared real transport. */
-export function getTransport(ctx: OperationContext): EditorTransport {
+export function getTransport(ctx: ToolContext): EditorTransport {
   const injected = ctx['editorTransport'];
   return (injected as EditorTransport | undefined) ?? defaultTransport;
 }
@@ -586,7 +598,7 @@ export function getTransport(ctx: OperationContext): EditorTransport {
 // EDITOR_NOT_RUNNING + deterministic session resolution
 // ---------------------------------------------------------------------------
 
-export const EDITOR_NOT_RUNNING_ERROR: ErrorDefinition = {
+export const EDITOR_NOT_RUNNING_ERROR: ToolErrorDefinition = {
   code: 'EDITOR_NOT_RUNNING',
   summary:
     'No live, responsive editor session is available to target (none running, none matching ' +
@@ -637,12 +649,12 @@ function portOf(url: string): number | undefined {
  * surfaces EDITOR_NOT_RUNNING within that bound, never a hang.
  */
 export async function resolveEditorSession(
-  ctx: OperationContext,
+  ctx: ToolContext,
   transport: EditorTransport,
 ): Promise<EditorSessionInfo> {
   const editorUrl = ctx.editorUrl;
   const notRunning = (): never => {
-    throw new OperationError('EDITOR_NOT_RUNNING', 'No editor connected.', {
+    throw new ToolError('EDITOR_NOT_RUNNING', 'No editor connected.', {
       ...(editorUrl !== undefined ? { editorUrl } : {}),
     });
   };
@@ -669,6 +681,7 @@ export async function resolveEditorSession(
   } catch {
     return notRunning();
   }
+  sessions = sessions.filter((session) => session.kind !== 'e2e');
   if (sessions.length === 0) return notRunning();
 
   if (editorUrl !== undefined) {

package/src/errors.ts

@@ -3,7 +3,7 @@ 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 `OperationDefinition.errors` (see `registry.ts`).
+ * operation on `ToolDefinition.errors` (see `registry.ts`).
  */
 export const CORE_ERROR_CODES = {
   /** `dispatch()` was called with a name no operation is registered under. */
@@ -11,7 +11,7 @@ export const CORE_ERROR_CODES = {
   /** 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 OperationError's `data` failed its declared error-code schema —
+   *  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. */
@@ -46,32 +46,32 @@ export interface StructuredOperationError {
  * copies of @vgai/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('@vgai/sdk.OperationError');
+export const OPERATION_ERROR_BRAND = Symbol.for('@vgai/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 `OperationDefinition.errors` declares — `dispatch()`
+ * 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 OperationError extends Error {
+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 = 'OperationError';
+    this.name = 'ToolError';
     this.code = code;
     this.data = data;
   }
 }
 
-export function isOperationError(value: unknown): value is OperationError {
-  if (value instanceof OperationError) return true;
+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 (

package/src/generations.ts

@@ -48,13 +48,18 @@ export const GenerationJobSchema = z.object({
   createdAt: z.string().datetime(),
   updatedAt: z.string().datetime(),
   progress: z.number().min(0).max(1).optional(),
+  providerStatus: z.string().optional(),
+  queuePosition: z.number().int().nonnegative().optional(),
   message: z.string().optional(),
+  lastPolledAt: z.string().datetime().optional(),
+  lastProviderChangeAt: z.string().datetime().optional(),
   pollError: z.string().optional(),
   pollErrorAt: z.string().datetime().optional(),
   pollFailureCount: z.number().int().nonnegative().optional(),
   nextPollAt: z.string().datetime().optional(),
   billing: GenerationBillingSchema,
   poll: GenerationOperationReferenceSchema,
+  cancel: GenerationOperationReferenceSchema.optional(),
   accept: GenerationOperationReferenceSchema.optional(),
   acceptedAt: z.string().datetime().optional(),
   provenanceOperationId: z.string().optional(),
@@ -79,9 +84,12 @@ export interface GenerationJobDraft {
   mode: 'mock' | 'direct' | 'managed';
   status: GenerationJobStatus;
   progress?: number;
+  providerStatus?: string;
+  queuePosition?: number;
   message?: string;
   billing: GenerationBilling;
   poll: { tool: string; input: unknown };
+  cancel?: { tool: string; input: unknown };
   accept?: { tool: string; input: unknown };
 }
 
@@ -90,8 +98,11 @@ export interface GenerationJobUpdate {
   externalId: string;
   status?: GenerationJobStatus;
   progress?: number;
+  providerStatus?: string;
+  queuePosition?: number;
   message?: string;
   billing?: GenerationBilling;
+  cancel?: { tool: string; input: unknown };
   accepted?: {
     provenanceOperationId: string;
     outputPaths: string[];
@@ -106,7 +117,7 @@ export type GenerationToolContribution =
       toJob(input: unknown, result: unknown): GenerationJobDraft;
     }
   | {
-      role: 'poll' | 'accept';
+      role: 'poll' | 'cancel' | 'accept';
       provider: string;
       toUpdate(input: unknown, result: unknown): GenerationJobUpdate;
     };