@vgai/sdk 0.4.1-canary.20260715.0 → 0.4.1

package/package.json

@@ -2,7 +2,7 @@
   "name": "@vgai/sdk",
   "author": "Volter AI, Inc.",
   "license": "Apache-2.0",
-  "version": "0.4.1-canary.20260715.0",
+  "version": "0.4.1",
   "type": "module",
   "repository": {
     "type": "git",
@@ -17,10 +17,11 @@
   ],
   "exports": {
     ".": "./src/index.ts",
-    "./registry": "./src/registry.ts"
+    "./registry": "./src/registry.ts",
+    "./tools": "./src/tools.ts"
   },
   "dependencies": {
-    "@vgai/engine": "0.4.1-canary.20260715.0",
+    "@vgai/engine": "0.4.1",
     "playwright": "^1.58.2",
     "zod": "^4.3.6"
   }

package/src/errors.ts

@@ -41,6 +41,13 @@ export interface StructuredOperationError {
   data?: unknown;
 }
 
+/**
+ * A global brand keeps expected errors recognizable across separately loaded
+ * 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');
+
 /**
  * The only way an operation `impl` should signal an EXPECTED, contractual
  * failure (as opposed to an unexpected bug/exception). `code` must be one
@@ -51,6 +58,7 @@ export interface StructuredOperationError {
  * `normalizeThrown`).
  */
 export class OperationError extends Error {
+  readonly [OPERATION_ERROR_BRAND] = true;
   readonly code: string;
   readonly data: unknown;
 
@@ -62,6 +70,17 @@ export class OperationError extends Error {
   }
 }
 
+export function isOperationError(value: unknown): value is OperationError {
+  if (value instanceof OperationError) 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) => ({

package/src/index.ts

@@ -27,6 +27,18 @@ export {
   type OperationSummary,
 } 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';
 export {
   type ExecutionHost,
   type ExecutionRequirements,

package/src/registry.ts

@@ -1,7 +1,7 @@
 import type { z } from 'zod';
 import {
   CORE_ERROR_CODES,
-  OperationError,
+  isOperationError,
   type StructuredOperationError,
   toStructuredIssues,
 } from './errors.js';
@@ -141,7 +141,7 @@ export type OperationOutcome<TResult = unknown> =
  *     the identifying `code`.
  */
 function normalizeThrown(def: OperationDefinition, err: unknown): StructuredOperationError {
-  if (err instanceof OperationError) {
+  if (isOperationError(err)) {
     const declared = def.errors.find((e) => e.code === err.code);
     if (!declared) {
       return {

package/src/tools.ts

@@ -0,0 +1,24 @@
+/**
+ * Public project-tool contract.
+ *
+ * A tool is an ordinary registered JavaScript/TypeScript function. The SDK's
+ * operation registry remains the internal validated dispatcher used by every
+ * projection, but projects should not need a second public ontology merely
+ * because the host calls their function through a transport.
+ */
+export { OperationError as ToolError } from './errors.js';
+export {
+  defineOperation as defineTool,
+  type ErrorDefinition as ToolErrorDefinition,
+  type OperationDefinition as ToolDefinition,
+  type OperationOutcome as ToolOutcome,
+  OperationRegistry as ToolRegistry,
+  type OperationSummary as ToolSummary,
+} from './registry.js';
+export type {
+  ExecutionHost as ToolHost,
+  ExecutionRequirements as ToolRequirements,
+  OperationContext as ToolContext,
+  PermissionMetadata as ToolPermission,
+  PermissionRisk as ToolPermissionRisk,
+} from './types.js';