@vgai/sdk 0.4.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.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.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/project/index.ts

@@ -13,6 +13,7 @@ export * from './discovery-operations.js';
 export * from './entity-operations.js';
 export * from './input-map-operations.js';
 export * from './manifest-operations.js';
+export * from './provenance.js';
 export * from './scene-operations.js';
 export {
   BaseHashField,

package/src/project/provenance.ts

@@ -0,0 +1,154 @@
+import { z } from 'zod';
+
+export const PROJECT_PROVENANCE_PATH = '.vgai/provenance.json';
+
+export const ProjectProvenanceOutputSchema = z.object({
+  path: z.string(),
+  bytes: z.number().int().nonnegative(),
+  sha256: z.string().regex(/^[a-f0-9]{64}$/),
+  mediaType: z.string().optional(),
+  role: z.enum(['asset', 'prefab', 'provenance', 'other']).optional(),
+});
+
+export const ProjectProvenanceExecutionSchema = z.object({
+  mode: z.enum(['mock', 'direct', 'managed']),
+  provider: z.string(),
+  operation: z.string().optional(),
+  model: z.string().optional(),
+  requestId: z.string().optional(),
+  taskId: z.string().optional(),
+  managedJobId: z.string().optional(),
+});
+
+export const ProjectProvenanceOperationSchema = z.object({
+  createdAt: z.string().datetime(),
+  operation: z.object({
+    name: z.string(),
+    source: z.string().optional(),
+  }),
+  execution: ProjectProvenanceExecutionSchema.optional(),
+  executions: z.array(ProjectProvenanceExecutionSchema).min(2).optional(),
+  input: z.json().optional(),
+  outputs: z.array(ProjectProvenanceOutputSchema).min(1),
+});
+
+export const ProjectProvenanceDocumentSchema = z.object({
+  version: z.literal(1),
+  operations: z.record(z.string(), ProjectProvenanceOperationSchema),
+});
+
+export type ProjectProvenanceDocument = z.infer<typeof ProjectProvenanceDocumentSchema>;
+export type ProjectProvenanceOperation = z.infer<typeof ProjectProvenanceOperationSchema>;
+export type ProjectProvenanceExecution = z.infer<typeof ProjectProvenanceExecutionSchema>;
+
+export const ProjectAttributionEntrySchema = z.object({
+  key: z.string(),
+  name: z.string().optional(),
+  source: z.string().optional(),
+  sourceUrl: z.string().url().optional(),
+  author: z.string(),
+  license: z.string(),
+  text: z.string(),
+  operationIds: z.array(z.string()),
+  outputPaths: z.array(z.string()),
+});
+
+export const ProjectAttributionReportSchema = z.object({
+  version: z.literal(1),
+  entries: z.array(ProjectAttributionEntrySchema),
+});
+
+export type ProjectAttributionEntry = z.infer<typeof ProjectAttributionEntrySchema>;
+export type ProjectAttributionReport = z.infer<typeof ProjectAttributionReportSchema>;
+
+export function emptyProjectProvenanceDocument(): ProjectProvenanceDocument {
+  return { version: 1, operations: {} };
+}
+
+function objectRecord(value: unknown): Record<string, unknown> | null {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null;
+}
+
+function stringField(record: Record<string, unknown>, key: string): string | undefined {
+  const value = record[key];
+  return typeof value === 'string' && value.trim().length > 0 ? value.trim() : undefined;
+}
+
+function attributionEntry(
+  operationId: string,
+  operation: ProjectProvenanceOperation,
+): ProjectAttributionEntry | null {
+  const input = objectRecord(operation.input);
+  if (!input) return null;
+  const nested = objectRecord(input['attribution']) ?? {};
+  const author = stringField(nested, 'author') ?? stringField(input, 'author');
+  const license = stringField(nested, 'license') ?? stringField(input, 'license');
+  if (!author || !license) return null;
+  const name = stringField(nested, 'name') ?? stringField(input, 'name');
+  const source = stringField(nested, 'source') ?? stringField(input, 'source');
+  const sourceUrl = stringField(nested, 'sourceUrl') ?? stringField(input, 'sourceUrl');
+  const text = stringField(nested, 'text') ?? `${name ? `${name} by ` : ''}${author} (${license})`;
+  const key = JSON.stringify([sourceUrl ?? '', author, license, text]);
+  return ProjectAttributionEntrySchema.parse({
+    key,
+    ...(name ? { name } : {}),
+    ...(source ? { source } : {}),
+    ...(sourceUrl ? { sourceUrl } : {}),
+    author,
+    license,
+    text,
+    operationIds: [operationId],
+    outputPaths: operation.outputs
+      .filter((output) => output.role !== 'provenance')
+      .map((output) => output.path),
+  });
+}
+
+/**
+ * Project credits are a projection of central provenance, never another
+ * persisted ledger or a set of per-asset files.
+ */
+export function deriveProjectAttributionReport(
+  document: ProjectProvenanceDocument,
+): ProjectAttributionReport {
+  const grouped = new Map<string, ProjectAttributionEntry>();
+  for (const [operationId, operation] of Object.entries(document.operations)) {
+    const entry = attributionEntry(operationId, operation);
+    if (!entry) continue;
+    const prior = grouped.get(entry.key);
+    if (!prior) {
+      grouped.set(entry.key, entry);
+      continue;
+    }
+    prior.operationIds.push(...entry.operationIds);
+    prior.outputPaths.push(...entry.outputPaths);
+  }
+  const entries = [...grouped.values()]
+    .map((entry) => ({
+      ...entry,
+      operationIds: [...new Set(entry.operationIds)].sort(),
+      outputPaths: [...new Set(entry.outputPaths)].sort(),
+    }))
+    .sort(
+      (left, right) => left.text.localeCompare(right.text) || left.key.localeCompare(right.key),
+    );
+  return ProjectAttributionReportSchema.parse({ version: 1, entries });
+}
+
+/** Deterministic human-readable projection of the machine report. */
+export function formatProjectAttributionMarkdown(report: ProjectAttributionReport): string {
+  const sections = report.entries.map((entry) => {
+    const heading = entry.name ?? entry.text;
+    return [
+      `## ${heading}`,
+      '',
+      entry.text,
+      '',
+      `Author: ${entry.author}  `,
+      `License: ${entry.license}${entry.sourceUrl ? `  \nSource: ${entry.sourceUrl}` : ''}`,
+    ].join('\n');
+  });
+  return `# Asset attribution\n${sections.length > 0 ? `\n${sections.join('\n\n')}` : '\nNo attributed project assets are currently present.'}\n`;
+}

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';

package/src/types.ts

@@ -68,6 +68,30 @@ export interface ProjectGeneratedOutput {
   files: ProjectGeneratedOutputFile[];
   totalBytes: number;
   dryRun: boolean;
+  /** Host-created logical record in .vgai/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;
+}
+
+/** 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[];
+  /** Schema-validated, JSON-safe operation input. */
+  input?: unknown;
 }
 
 /**