@vgai/sdk 0.4.1 → 0.5.0-canary.20260719.0

package/package.json

@@ -2,7 +2,7 @@
   "name": "@vgai/sdk",
   "author": "Volter AI, Inc.",
   "license": "Apache-2.0",
-  "version": "0.4.1",
+  "version": "0.5.0-canary.20260719.0",
   "type": "module",
   "repository": {
     "type": "git",
@@ -17,11 +17,17 @@
   ],
   "exports": {
     ".": "./src/index.ts",
+    "./account": "./src/account.ts",
+    "./generations": "./src/generations.ts",
+    "./mcp-stdio": "./src/mcp/mcp-stdio-server.ts",
+    "./project-tool-catalog": "./src/project-tool-catalog.ts",
+    "./project-inspection-node": "./src/project/inspection-node.ts",
     "./registry": "./src/registry.ts",
     "./tools": "./src/tools.ts"
   },
   "dependencies": {
-    "@vgai/engine": "0.4.1",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@vgai/engine": "0.5.0-canary.20260719.0",
     "playwright": "^1.58.2",
     "zod": "^4.3.6"
   }

package/src/account.ts

@@ -0,0 +1,133 @@
+import { z } from 'zod';
+
+export const AccountModeSchema = z.enum(['mock', 'live']);
+export const AccountPlanSchema = z.object({
+  id: z.string().min(1),
+  name: z.string().min(1),
+  status: z.enum(['free', 'trialing', 'active', 'past_due', 'cancelling']),
+  interval: z.enum(['month', 'year']).optional(),
+  renewsAt: z.string().datetime().optional(),
+  endsAt: z.string().datetime().optional(),
+});
+export const AccountCreditsSchema = z.object({
+  included: z.number().nonnegative(),
+  purchased: z.number().nonnegative(),
+  used: z.number().nonnegative(),
+  reserved: z.number().nonnegative(),
+  remaining: z.number().nonnegative(),
+  resetsAt: z.string().datetime().optional(),
+  purchasedExpiresAt: z.string().datetime().optional(),
+});
+export const AccountSpendPolicySchema = z.object({
+  overageEnabled: z.boolean(),
+  monthlyLimitCredits: z.number().nonnegative(),
+  alertThresholds: z.array(z.number().min(1).max(100)).max(8),
+  autoReload: z
+    .object({
+      enabled: z.boolean(),
+      whenRemainingBelow: z.number().nonnegative(),
+      reloadTo: z.number().positive(),
+      monthlyLimitCredits: z.number().nonnegative(),
+    })
+    .optional(),
+});
+export const AccountUserSchema = z.object({
+  id: z.string().min(1),
+  email: z.string().email(),
+  name: z.string().min(1).optional(),
+});
+export const AccountUsageEntrySchema = z.object({
+  id: z.string().min(1),
+  occurredAt: z.string().datetime(),
+  kind: z.literal('generation'),
+  provider: z.string().min(1),
+  operation: z.string().optional(),
+  credits: z.number().nonnegative(),
+  state: z.enum(['reserved', 'settled', 'released']),
+  externalId: z.string().optional(),
+});
+export const AccountSnapshotSchema = z.discriminatedUnion('authenticated', [
+  z.object({ authenticated: z.literal(false), mode: AccountModeSchema }),
+  z.object({
+    authenticated: z.literal(true),
+    mode: AccountModeSchema,
+    user: AccountUserSchema,
+    plan: AccountPlanSchema,
+    credits: AccountCreditsSchema,
+    spendPolicy: AccountSpendPolicySchema,
+    entitlements: z.object({
+      generation: z.boolean(),
+      dailyJobs: z.number().int().positive().optional(),
+    }),
+  }),
+]);
+/** Product-facing routes. Provider tools may translate BYOK to their native
+ * transport name (`direct`) internally. */
+export const GenerationExecutionRouteSchema = z.enum(['mock', 'managed', 'byok']);
+export const ProviderCredentialIdSchema = z.enum(['fal', 'tripo', 'worldlabs']);
+export const ProviderCredentialSourceSchema = z.enum(['environment', 'system', 'session', 'none']);
+export const ProviderCredentialStatusSchema = z.object({
+  provider: ProviderCredentialIdSchema,
+  label: z.string().min(1),
+  environmentVariable: z.string().min(1),
+  configured: z.boolean(),
+  source: ProviderCredentialSourceSchema,
+  editable: z.boolean(),
+  persistence: z.enum(['system', 'session']),
+  maskedKey: z.string().min(1).optional(),
+  problem: z.string().min(1).optional(),
+});
+export const ProviderCredentialTestResultSchema = z.object({
+  provider: ProviderCredentialIdSchema,
+  ok: z.literal(true),
+  testedAt: z.string().datetime(),
+});
+
+export type AccountMode = z.infer<typeof AccountModeSchema>;
+export type AccountPlan = z.infer<typeof AccountPlanSchema>;
+export type AccountCredits = z.infer<typeof AccountCreditsSchema>;
+export type AccountSpendPolicy = z.infer<typeof AccountSpendPolicySchema>;
+export type AccountUser = z.infer<typeof AccountUserSchema>;
+export type AccountUsageEntry = z.infer<typeof AccountUsageEntrySchema>;
+export type AccountSnapshot = z.infer<typeof AccountSnapshotSchema>;
+export type GenerationExecutionRoute = z.infer<typeof GenerationExecutionRouteSchema>;
+export type ProviderCredentialId = z.infer<typeof ProviderCredentialIdSchema>;
+export type ProviderCredentialSource = z.infer<typeof ProviderCredentialSourceSchema>;
+export type ProviderCredentialStatus = z.infer<typeof ProviderCredentialStatusSchema>;
+export type ProviderCredentialTestResult = z.infer<typeof ProviderCredentialTestResultSchema>;
+export type EditorAccountSnapshot = AccountSnapshot & {
+  routes: { mock: true; managed: boolean; byok: boolean; byokProviders: string[] };
+  preferredRoute: GenerationExecutionRoute;
+  /** Editor-only metadata. Credential values never cross the server boundary. */
+  providerCredentials: ProviderCredentialStatus[];
+};
+export interface GenerationAccountProjection {
+  routes: EditorAccountSnapshot['routes'];
+  preferredRoute: GenerationExecutionRoute;
+}
+export function generationAccountProjection(
+  account: EditorAccountSnapshot,
+): GenerationAccountProjection {
+  return {
+    routes: {
+      mock: true,
+      managed: account.routes.managed,
+      byok: account.routes.byok,
+      byokProviders: [...account.routes.byokProviders],
+    },
+    preferredRoute: account.preferredRoute,
+  };
+}
+export const EditorAccountSnapshotSchema: z.ZodType<EditorAccountSnapshot> = z.intersection(
+  AccountSnapshotSchema,
+  z.object({
+    routes: z.object({
+      mock: z.literal(true),
+      managed: z.boolean(),
+      byok: z.boolean(),
+      byokProviders: z.array(z.string().min(1)),
+    }),
+    preferredRoute: GenerationExecutionRouteSchema,
+    providerCredentials: z.array(ProviderCredentialStatusSchema),
+  }),
+);

package/src/editor/transport.ts

@@ -105,7 +105,7 @@
  *    deliberately never exercised in the first place.)
  */
 
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join, resolve } from 'node:path';
 import { z } from 'zod';
@@ -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;
+  /** Exact explicitly targeted editor origin/base URL, including protocol and host. */
+  url?: string;
 }
 
 export interface EditorCommandResult {
@@ -241,6 +243,8 @@ export interface ConsoleSubscriptionMetadata {
  * `getTransport` below.
  */
 export interface EditorTransport {
+  /** Probe an explicit --url/VGAI_EDITOR_URL without consulting the local session registry. */
+  probeSessionUrl?(editorUrl: string, timeoutMs: number): Promise<EditorSessionInfo | undefined>;
   listSessions(timeoutMs: number): Promise<EditorSessionInfo[]>;
   getSelection(
     session: EditorSessionInfo,
@@ -361,11 +365,30 @@ async function postJson(
 }
 
 function baseUrl(session: EditorSessionInfo): string {
-  return `http://localhost:${session.port}`;
+  return session.url ?? `http://localhost:${session.port}`;
 }
 
 /** The real, production transport — HTTP against a live `vgai edit` dev server. */
 export class HttpEditorTransport implements EditorTransport {
+  async probeSessionUrl(
+    editorUrl: string,
+    timeoutMs: number,
+  ): Promise<EditorSessionInfo | undefined> {
+    let url: URL;
+    try {
+      url = new URL(editorUrl);
+      if (url.protocol !== 'http:' && url.protocol !== 'https:') return undefined;
+    } catch {
+      return undefined;
+    }
+    const base = editorUrl.replace(/\/+$/, '');
+    const body = await fetchJson(`${base}/__editor/project`, timeoutMs);
+    if (body === undefined) return undefined;
+    const project = (body as { project?: { path?: string } | null }).project?.path ?? null;
+    const port = url.port ? Number(url.port) : url.protocol === 'https:' ? 443 : 80;
+    return { port, project, pid: null, url: base };
+  }
+
   async listSessions(timeoutMs: number): Promise<EditorSessionInfo[]> {
     const registered = readRegisteredSessions();
     const perProbeTimeout = Math.min(EDITOR_PROBE_TIMEOUT_MS, Math.max(200, timeoutMs));
@@ -572,7 +595,12 @@ export const EDITOR_NOT_RUNNING_ERROR: ErrorDefinition = {
 };
 
 function canonicalize(p: string): string {
-  return resolve(p);
+  const absolute = resolve(p);
+  try {
+    return realpathSync(absolute);
+  } catch {
+    return absolute;
+  }
 }
 
 /** Extract the port from an `http(s)://host:port` URL, or undefined if unparseable. */
@@ -589,15 +617,16 @@ function portOf(url: string): number | undefined {
  * Deterministic session selection (§8 B3 AC: "Session selection is
  * deterministic when multiple editors are running"). Precedence, in order:
  *
- *  1. `ctx.editorUrl` given -> the live session on THAT exact port, or
- *     EDITOR_NOT_RUNNING if no live session answers there. (Explicit
- *     targeting always wins — mirrors `vgai-cli`'s own `--url` override.)
+ *  1. `ctx.editorUrl` given -> probe THAT exact URL, preserving its protocol
+ *     and host, or EDITOR_NOT_RUNNING if no live session answers there.
+ *     (Explicit targeting always wins — mirrors `vgai-cli`'s own `--url`
+ *     override and supports non-local/HTTPS editor endpoints.)
  *  2. `ctx.projectRoot` given (no editorUrl) -> the live session whose
  *     canonical project path matches `ctx.projectRoot`'s canonical path.
  *     (Mirrors `packages/vgai-cli/src/index.ts`'s `getClient()` cwd rule —
  *     "run `vgai play` from inside a project and it targets THAT project's
  *     editor, whichever port it landed on".)
- *  3. Neither given, or neither matched -> the LOWEST-numbered port among
+ *  3. Neither hint given -> the LOWEST-numbered port among
  *     all live sessions (a total order over the only session field that is
  *     always present and stable, so the rule never depends on registration
  *     order or wall-clock time).
@@ -618,6 +647,18 @@ export async function resolveEditorSession(
     });
   };
 
+  if (editorUrl !== undefined && transport.probeSessionUrl) {
+    try {
+      const session = await withTimeout(
+        transport.probeSessionUrl(editorUrl, EDITOR_PROBE_TIMEOUT_MS),
+        EDITOR_PROBE_TIMEOUT_MS,
+        'explicit editor URL probe',
+      );
+      if (session) return session;
+    } catch {}
+    return notRunning();
+  }
+
   let sessions: EditorSessionInfo[];
   try {
     sessions = await withTimeout(
@@ -634,13 +675,14 @@ export async function resolveEditorSession(
     const port = portOf(editorUrl);
     const match = sessions.find((s) => s.port === port);
     if (!match) return notRunning();
-    return match;
+    return { ...match, url: editorUrl.replace(/\/+$/, '') };
   }
 
   if (ctx.projectRoot !== undefined) {
     const canon = canonicalize(ctx.projectRoot);
     const match = sessions.find((s) => s.project !== null && canonicalize(s.project) === canon);
-    if (match) return match;
+    if (!match) return notRunning();
+    return match;
   }
 
   return [...sessions].sort((a, b) => a.port - b.port)[0]!;

package/src/generations.ts

@@ -0,0 +1,112 @@
+import { z } from 'zod';
+
+/**
+ * First-party generation JOB vocabulary.
+ *
+ * Providers keep their native request and result schemas. This deliberately
+ * normalizes only the lifecycle that is genuinely shared by Fal, Tripo,
+ * World Labs, and future generators: durable identity, state, resumption,
+ * acceptance, and the charge shown to the user.
+ */
+
+export const GenerationJobStatusSchema = z.enum([
+  'queued',
+  'running',
+  'succeeded',
+  'failed',
+  'cancelled',
+]);
+
+export const GenerationBillingSchema = z.discriminatedUnion('route', [
+  z.object({ route: z.literal('mock') }),
+  z.object({
+    route: z.literal('managed'),
+    estimatedCredits: z.number().nonnegative().optional(),
+    settledCredits: z.number().nonnegative().optional(),
+  }),
+  z.object({
+    route: z.literal('byok'),
+    currency: z.literal('USD'),
+    estimatedAmount: z.number().nonnegative().optional(),
+    settledAmount: z.number().nonnegative().optional(),
+  }),
+]);
+
+const GenerationOperationReferenceSchema = z.object({
+  tool: z.string().min(1),
+  input: z.unknown(),
+});
+
+export const GenerationJobSchema = z.object({
+  id: z.string().min(1),
+  provider: z.string().min(1),
+  externalId: z.string().min(1),
+  label: z.string().min(1),
+  operation: z.string().min(1),
+  mode: z.enum(['mock', 'direct', 'managed']),
+  status: GenerationJobStatusSchema,
+  createdAt: z.string().datetime(),
+  updatedAt: z.string().datetime(),
+  progress: z.number().min(0).max(1).optional(),
+  message: z.string().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,
+  accept: GenerationOperationReferenceSchema.optional(),
+  acceptedAt: z.string().datetime().optional(),
+  provenanceOperationId: z.string().optional(),
+  outputPaths: z.array(z.string()).optional(),
+});
+
+export const GenerationJobsDocumentSchema = z.object({
+  version: z.literal(1),
+  jobs: z.array(GenerationJobSchema),
+});
+
+export type GenerationJobStatus = z.infer<typeof GenerationJobStatusSchema>;
+export type GenerationBilling = z.infer<typeof GenerationBillingSchema>;
+export type GenerationJob = z.infer<typeof GenerationJobSchema>;
+export type GenerationJobsDocument = z.infer<typeof GenerationJobsDocumentSchema>;
+
+export interface GenerationJobDraft {
+  provider: string;
+  externalId: string;
+  label: string;
+  operation: string;
+  mode: 'mock' | 'direct' | 'managed';
+  status: GenerationJobStatus;
+  progress?: number;
+  message?: string;
+  billing: GenerationBilling;
+  poll: { tool: string; input: unknown };
+  accept?: { tool: string; input: unknown };
+}
+
+export interface GenerationJobUpdate {
+  provider: string;
+  externalId: string;
+  status?: GenerationJobStatus;
+  progress?: number;
+  message?: string;
+  billing?: GenerationBilling;
+  accepted?: {
+    provenanceOperationId: string;
+    outputPaths: string[];
+  };
+}
+
+/** Provider-owned mapping attached to a registered native operation module. */
+export type GenerationToolContribution =
+  | {
+      role: 'submit';
+      provider: string;
+      toJob(input: unknown, result: unknown): GenerationJobDraft;
+    }
+  | {
+      role: 'poll' | 'accept';
+      provider: string;
+      toUpdate(input: unknown, result: unknown): GenerationJobUpdate;
+    };

package/src/index.ts

@@ -1,3 +1,4 @@
+export * from './account.js';
 export * from './cinematic/index.js';
 export * from './editor/index.js';
 export {
@@ -16,8 +17,10 @@ export {
   projectStatus,
   registerBuiltinOperations,
 } from './operations.js';
+export * from './perf/index.js';
 export * from './play/index.js';
 export * from './project/index.js';
+export * from './project-tool-catalog.js';
 export {
   defineOperation,
   type ErrorDefinition,

package/src/mcp/index.ts

@@ -4,7 +4,9 @@ export {
   isResourceEligible,
   type JsonRpcRequest,
   type JsonRpcResponse,
+  MAX_INLINE_MCP_SCHEMA_BYTES,
   MCP_RESOURCE_PREFIX,
+  MCP_SCHEMA_RESOURCE_PREFIX,
   type McpProjection,
   type McpProjectionOptions,
   type McpResource,
@@ -14,3 +16,15 @@ export {
   outcomeToToolResult,
   toolInputSchema,
 } from './mcp-projection.js';
+export {
+  type CreateMcpServerOptions,
+  createMcpServer,
+  DEFAULT_MCP_INSTRUCTIONS,
+  DEFAULT_MCP_SERVER_INFO,
+  type VgaiMcpServer,
+} from './mcp-server.js';
+export {
+  type ConnectedMcpStdioServer,
+  type ConnectMcpStdioOptions,
+  connectMcpStdioServer,
+} from './mcp-stdio.js';