@volter/editor-sdk 0.5.57

package/src/session.ts

@@ -0,0 +1,41 @@
+/**
+ * THE SESSION FACE — what the session SERVER and the editor PAGE both agree on.
+ *
+ * `@volter/editor-sdk` is the API with four faces (ARCHITECTURE-CORE §The target
+ * shape): protocol, host doors + layouts, widgets, session client. This is the
+ * protocol face's home, and it exists because of a LICENCE fact, not tidiness:
+ * the target shape's editor-kit row says the session server and the CLI are
+ * Apache "ONLY once the session imports nothing of the editor". Every module
+ * re-exported here used to live in `packages/editor/src/` (AGPL-3.0-only) and
+ * was value-imported by `packages/editor/server/**`, so the Node session's
+ * import graph reached AGPL application code on every boot.
+ *
+ * What qualifies for this face: a shape TWO programs must agree on, that imports
+ * neither React, nor the editor shell store, nor `node:` — measured, not
+ * asserted. All twelve below import nothing but `../share`, `@volter/editor-project`'s
+ * manifest schema, and each other. A module the editor app merely happens to
+ * share with the server does NOT qualify; it stays where it is and shows up in
+ * `scripts/validate-import-bans.mjs`'s `server-imports-editor-app` ratchet with
+ * a reason, until someone makes it a contract or deletes it.
+ *
+ * IMPORT THE MODULE, NOT THIS BARREL, from anything the closure meter watches:
+ * `@volter/editor-sdk/session/relative-path-guard`. The subpath is a wildcard
+ * export (`"./session/*"`), the same shape the runtime packages use, because
+ * `export *` here would put all twelve modules in every consumer's static
+ * value-import closure — measured at +4 files on the `full` build and +5 on
+ * `models` the one time this file was the door. This barrel is documentation
+ * and a convenience for callers no meter watches.
+ */
+
+export * from './session/build-report';
+export * from './session/collaboration-types';
+export * from './session/command-table';
+export * from './session/editor-brand';
+export * from './session/editor-compatibility';
+export * from './session/editor-control-lifecycle';
+export * from './session/editor-control-protocol';
+export * from './session/game-css-scope';
+export * from './session/project-module-url';
+export * from './session/relative-path-guard';
+export * from './session/source-glob';
+export * from './session/tool-contribution-convention';

package/src/share.ts

@@ -0,0 +1,160 @@
+/**
+ * THE share-session wire — `/__editor/share-control`'s payloads, declared once.
+ *
+ * This route has three clients living in three different compilation units:
+ * the editor SERVER that serves it (`packages/editor/server/`), the browser
+ * PANEL that polls it (`packages/editor/src/`), and the `vgai share` CLI
+ * (`packages/vgai-cli/src/`). Each of them used to declare its own copy of the
+ * payload, and the copies had already drifted — silently, in both directions,
+ * because an under-declared read of a JSON superset is a type error nowhere:
+ *
+ *   - the CLI's invitation had no `delivery`, so `vgai share` could not report
+ *     that the invitation email had FAILED to send — the one state the field
+ *     exists for;
+ *   - the CLI's audit rows typed `type` and `capability` as bare `string`,
+ *     which accepts any spelling of an event the server never emits;
+ *   - the browser panel's invitation had no `inviterAccountId`;
+ *   - the browser panel had no `audit` at all, and re-declared the tunnel
+ *     health shape inline instead of naming it.
+ *
+ * This package is the right home for all three: `@vgai/editor` and `@vgai/cli`
+ * both already depend on it, it depends on neither, and the CLI's esbuild
+ * bundle inlines it. (The CLI's standing "no editor-package dependency" rule is
+ * about `@vgai/editor` — the server+UI package whose express/vite/chokidar
+ * graph the standalone bundle must not drag in. This is a types-only module.)
+ *
+ * Two things deliberately stay OFF this wire, and stay off it structurally
+ * rather than by memory:
+ *
+ *   - the invitation TOKEN HASH, which is a local extension on the server
+ *     (`share-host.ts`'s `StoredShareInvitation extends ShareInvitationRecord`);
+ *   - a participant's ORGANIZATION list, which the gateway holds on its own
+ *     `ShareAccountProjection` to resolve team invitations. {@link ShareAccount}
+ *     is what a participant projects to, so `status()` narrows to it.
+ */
+
+/**
+ * A share role, least authority first.
+ *
+ * `maintainer` is deliberately absent: it is local-only and has no share role,
+ * which is why the editor's `CollaborationRole` is this union PLUS `maintainer`
+ * rather than the other way around.
+ */
+export type ShareRole = 'viewer' | 'commenter' | 'tester' | 'editor' | 'terminal';
+
+export type ShareTunnelProvider = 'cloudflared' | 'ngrok';
+
+export type ShareTunnelState = 'stopped' | 'starting' | 'healthy' | 'failed';
+
+export interface ShareTunnelHealth {
+  checkedAt: string;
+  latencyMs: number;
+}
+
+/**
+ * The capability vocabulary a grant is checked against.
+ *
+ * Wider than the roles on purpose: `public` and `never-share` are DECLARATIONS
+ * a route makes about itself, and `maintain` is the local-only authority no
+ * share role reaches — so this union is not derivable from {@link ShareRole}.
+ */
+export type ShareCapability =
+  | 'public'
+  | 'view'
+  | 'comment'
+  | 'test'
+  | 'edit'
+  | 'terminal'
+  | 'maintain'
+  | 'never-share';
+
+/** A verified VGAI account, as a share participant projects onto the wire. */
+export interface ShareAccount {
+  id: string;
+  email: string;
+  name?: string;
+}
+
+/**
+ * How the invitation was DELIVERED, when we delivered it.
+ *
+ * Present-and-`failed` is the state this field exists for: an invitation
+ * created whose email never left is otherwise indistinguishable, on every
+ * surface, from one that arrived.
+ */
+export interface ShareInvitationDelivery {
+  channel: 'clerk-email';
+  status: 'sent' | 'failed';
+  providerInvitationId?: string;
+  sentAt?: string;
+  problem?: string;
+}
+
+export interface ShareInvitationRecord {
+  id: string;
+  inviterAccountId: string;
+  recipientAccountId?: string;
+  recipientEmail?: string;
+  recipientOrganizationId?: string;
+  recipientOrganizationName?: string;
+  recipientOrganizationDomain?: string;
+  /** The highest role this invitation may ever be raised to. */
+  roleCeiling: ShareRole;
+  usePolicy: 'person' | 'team';
+  createdAt: string;
+  expiresAt: string;
+  revokedAt?: string;
+  delivery?: ShareInvitationDelivery;
+}
+
+export interface ShareParticipant {
+  participantId: string;
+  account: ShareAccount;
+  invitationId: string;
+  role: ShareRole;
+  roleCeiling: ShareRole;
+  credentials: number;
+  joined: boolean;
+}
+
+export type ShareAuditEventType =
+  | 'auth-failed'
+  | 'auth-started'
+  | 'invite-redeemed'
+  | 'capability-denied'
+  | 'role-changed'
+  | 'participant-kicked'
+  | 'invitation-revoked'
+  | 'terminal-invoked';
+
+export interface ShareAuditEvent {
+  at: string;
+  type: ShareAuditEventType;
+  invitationId?: string;
+  participantId?: string;
+  accountId?: string;
+  capability?: ShareCapability;
+  /** The role a `role-changed` event settled on. */
+  role?: ShareRole;
+}
+
+/** The `/__editor/share-control/status` payload. */
+export interface ShareStatus {
+  active: boolean;
+  sessionId: string;
+  projectRoot: string;
+  publicUrl?: string;
+  tunnelProvider?: ShareTunnelProvider;
+  tunnel: ShareTunnelState;
+  health?: ShareTunnelHealth;
+  invitations: readonly ShareInvitationRecord[];
+  participants: readonly ShareParticipant[];
+  audit: readonly ShareAuditEvent[];
+  problem?: string;
+}
+
+/** The `/__editor/share-control/invitations` reply. */
+export interface CreatedShareInvitation {
+  invitation: ShareInvitationRecord;
+  url: string;
+}

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 @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.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('vgai.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['VGAI_GENERATION_GATEWAY'] && process.env['VGAI_ACCESS_TOKEN']) return 'managed';
+  throw new Error(`Connect ${provider} or sign in to Volter Editor in Account before generating.`);
+}