@vgai/fal 0.1.0 → 0.1.2

package/README.md

@@ -1,6 +1,18 @@
 # @vgai/fal
 
-Optional Project Tools and editor UI for Fal. The package registers
+The **provider boundary** for Fal: pricing, spend routing and credentials,
+behind guarded tools. This package registers NOTHING and contains no editor UI.
+
+Add the capability to a project instead — `vgai add fal` — which copies the tool
+DECLARATIONS and the generation documents into your `src/tools/` as ordinary,
+editable source. They import this package for the parts that must not be
+editable, and nothing else.
+
+Two kinds of code exist in VGAI. This is the dependency side: the machinery that
+makes the system work, which an agent is not meant to read or change. Anything
+that hooks into the editor is on the lib side, so it is visible project source.
+
+The guarded surface this package exports backs these tools:
 `project.fal.quote`, `project.fal.submit`, `project.fal.poll`, and
 `project.fal.cancel`, and `project.fal.accept`. Quote reads current
 account-specific pricing without inspecting provider wallet balance; submission

package/package.json

@@ -2,7 +2,7 @@
   "name": "@vgai/fal",
   "author": "Volter AI, Inc.",
   "license": "Apache-2.0",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "type": "module",
   "description": "Optional registered Fal provider boundary for VGAI projects: quote, submit, poll and accept behind guarded pricing and credentials.",
   "homepage": "https://github.com/volter-ai/vgai-engine#readme",
@@ -20,25 +20,19 @@
   ],
   "exports": {
     "./accept": "./src/accept.ts",
+    "./cancel": "./src/cancel.ts",
     "./contracts": "./src/contracts.ts",
     "./package.json": "./package.json",
     "./poll": "./src/poll.ts",
     "./pricing": "./src/pricing.ts",
-    "./submit": "./src/submit.ts"
-  },
-  "vgai": {
-    "tools": [
-      "./src/submit.tool.ts",
-      "./src/quote.tool.ts",
-      "./src/cancel.tool.ts",
-      "./src/poll.tool.ts",
-      "./src/accept.tool.ts"
-    ]
+    "./provider": "./src/provider.ts",
+    "./submit": "./src/submit.ts",
+    "./tool-error": "./src/tool-error.ts"
   },
   "dependencies": {
     "@fal-ai/client": "1.10.1",
     "@vgai/fal-client-compat": "0.1.0",
-    "@vgai/sdk": "0.5.0",
+    "@vgai/sdk": "^0.5.1",
     "fflate": "^0.8.2",
     "three": "^0.180.0",
     "zod": "^4.3.6"
@@ -47,7 +41,7 @@
     "@types/node": "^25.3.0",
     "@types/react": "^19.2.14",
     "@types/three": "^0.180.0",
-    "@vgai/editor-sdk": "0.5.0",
+    "@vgai/editor-sdk": "^0.5.1",
     "react": "^19.2.4"
   }
 }

package/src/accept.tool.ts

@@ -1,49 +0,0 @@
-import type { GenerationToolContribution } from '@vgai/sdk/generations';
-import { defineTool } from '@vgai/sdk/tools';
-import { acceptFal } from './accept.js';
-import { AcceptInputSchema, AcceptResultSchema } from './contracts.js';
-import { falTool, falToolErrors } from './tool-error.js';
-export const tool = defineTool({
-  name: 'project.fal.accept',
-  summary: 'Accept a completed Fal request',
-  description:
-    'Downloads and validates a completed Fal result, then atomically commits ordinary files and provenance.',
-  input: AcceptInputSchema,
-  result: AcceptResultSchema,
-  errors: falToolErrors,
-  requires: { project: true },
-  host: 'node',
-  mutates: true,
-  supportsDryRun: false,
-  longRunning: true,
-  permission: { risk: 'write', summary: 'Writes one accepted Fal output batch under public/.' },
-  impl: falTool(acceptFal),
-});
-
-export const generation = {
-  role: 'accept',
-  provider: 'fal',
-  toUpdate(inputValue, resultValue) {
-    const input = AcceptInputSchema.parse(inputValue);
-    const result = AcceptResultSchema.parse(resultValue);
-    return {
-      provider: 'fal',
-      externalId: input.requestId,
-      ...(input.mode === 'direct' && result.settledAmount !== undefined
-        ? {
-            billing: {
-              route: 'byok' as const,
-              currency: 'USD' as const,
-              settledAmount: result.settledAmount,
-            },
-          }
-        : input.mode === 'managed' && result.settledCredits !== undefined
-          ? { billing: { route: 'managed' as const, settledCredits: result.settledCredits } }
-          : {}),
-      accepted: {
-        provenanceOperationId: result.provenanceOperationId,
-        outputPaths: result.files.map((file) => file.path),
-      },
-    };
-  },
-} satisfies GenerationToolContribution;

package/src/cancel.tool.ts

@@ -1,36 +0,0 @@
-import type { GenerationToolContribution } from '@vgai/sdk/generations';
-import { defineTool } from '@vgai/sdk/tools';
-import { cancelFal } from './cancel.js';
-import { CancelInputSchema, CancelResultSchema } from './contracts.js';
-import { falTool, falToolErrors } from './tool-error.js';
-
-export const tool = defineTool({
-  name: 'project.fal.cancel',
-  summary: 'Cancel a Fal request',
-  description: 'Cancels one queued or running Fal request without writing generated project files.',
-  input: CancelInputSchema,
-  result: CancelResultSchema,
-  errors: falToolErrors,
-  requires: { project: true },
-  host: 'node',
-  mutates: false,
-  supportsDryRun: false,
-  longRunning: false,
-  permission: { risk: 'write', summary: 'Cancels one external Fal request.' },
-  impl: falTool(cancelFal),
-});
-
-export const generation = {
-  role: 'cancel',
-  provider: 'fal',
-  toUpdate(inputValue, resultValue) {
-    const input = CancelInputSchema.parse(inputValue);
-    CancelResultSchema.parse(resultValue);
-    return {
-      provider: 'fal',
-      externalId: input.requestId,
-      status: 'cancelled' as const,
-      message: 'Cancelled at the provider.',
-    };
-  },
-} satisfies GenerationToolContribution;

package/src/poll.tool.ts

@@ -1,70 +0,0 @@
-import type { GenerationToolContribution } from '@vgai/sdk/generations';
-import { defineTool } from '@vgai/sdk/tools';
-import { PollInputSchema, PollResultSchema } from './contracts.js';
-import { pollFal } from './poll.js';
-import { falTool, falToolErrors } from './tool-error.js';
-export const tool = defineTool({
-  name: 'project.fal.poll',
-  summary: 'Inspect a Fal request',
-  description: 'Reads one native Fal queue request without writing project files.',
-  input: PollInputSchema,
-  result: PollResultSchema,
-  errors: falToolErrors,
-  requires: { project: true },
-  host: 'node',
-  mutates: false,
-  supportsDryRun: false,
-  longRunning: false,
-  permission: { risk: 'read', summary: 'Reads one Fal request.' },
-  impl: falTool(pollFal),
-});
-
-export const generation = {
-  role: 'poll',
-  provider: 'fal',
-  toUpdate(inputValue, resultValue) {
-    const input = PollInputSchema.parse(inputValue);
-    const result = PollResultSchema.parse(resultValue);
-    return {
-      provider: 'fal',
-      externalId: input.requestId,
-      status: result.error
-        ? 'failed'
-        : result.status === 'COMPLETED'
-          ? 'succeeded'
-          : result.status === 'IN_PROGRESS'
-            ? 'running'
-            : 'queued',
-      providerStatus: result.status,
-      ...(result.queuePosition === undefined ? {} : { queuePosition: result.queuePosition }),
-      ...(result.error ? { message: result.error.message } : {}),
-      ...(result.cancelUrl
-        ? {
-            cancel: {
-              tool: 'project.fal.cancel',
-              input: {
-                mode: input.mode,
-                endpoint: input.endpoint,
-                requestId: input.requestId,
-                cancelUrl: result.cancelUrl,
-              },
-            },
-          }
-        : {}),
-      ...(input.mode === 'managed' &&
-      (result.estimatedCredits !== undefined || result.settledCredits !== undefined)
-        ? {
-            billing: {
-              route: 'managed' as const,
-              ...(result.estimatedCredits === undefined
-                ? {}
-                : { estimatedCredits: result.estimatedCredits }),
-              ...(result.settledCredits === undefined
-                ? {}
-                : { settledCredits: result.settledCredits }),
-            },
-          }
-        : {}),
-    };
-  },
-} satisfies GenerationToolContribution;

package/src/quote.tool.ts

@@ -1,20 +0,0 @@
-import { defineTool } from '@vgai/sdk/tools';
-import { QuoteInputSchema, QuoteResultSchema } from './contracts.js';
-import { quoteFalPrice } from './pricing.js';
-import { falTool, falToolErrors } from './tool-error.js';
-
-export const tool = defineTool({
-  name: 'project.fal.quote',
-  summary: 'Quote a Fal request',
-  description: 'Reads Fal current account pricing for one provider-native request.',
-  input: QuoteInputSchema,
-  result: QuoteResultSchema,
-  errors: falToolErrors,
-  requires: { project: true },
-  host: 'node',
-  mutates: false,
-  supportsDryRun: false,
-  longRunning: false,
-  permission: { risk: 'read', summary: 'Reads current Fal account pricing.' },
-  impl: falTool(quoteFalPrice),
-});

package/src/submit.tool.ts

@@ -1,101 +0,0 @@
-import type { GenerationToolContribution } from '@vgai/sdk/generations';
-import { defineTool } from '@vgai/sdk/tools';
-import {
-  SEEDANCE_2_REFERENCE_TO_VIDEO_ENDPOINT,
-  SubmissionSchema,
-  SubmitResultSchema,
-} from './contracts.js';
-import { submitFal } from './submit.js';
-import { falTool, falToolErrors } from './tool-error.js';
-
-const ENDPOINT_LABELS: Record<string, string> = {
-  'fal-ai/nano-banana-2': 'Generated image',
-  'fal-ai/nano-banana-2/edit': 'Edited image',
-  'fal-ai/gemini-3.1-flash-image-preview': 'Generated image',
-  'fal-ai/nano-banana': 'Generated image',
-  'fal-ai/nano-banana/edit': 'Edited image',
-  'fal-ai/stable-audio': 'Generated audio',
-  'fal-ai/sam-3/3d-objects': 'Reconstructed object',
-  'fal-ai/minimax/hailuo-02/standard/text-to-video': 'Generated video',
-  [SEEDANCE_2_REFERENCE_TO_VIDEO_ENDPOINT]: 'Seedance video treatment',
-  'fal-ai/hunyuan_world': 'Generated panorama',
-  'fal-ai/hunyuan_world/image-to-world': 'Generated layered world',
-};
-
-function jobLabel(endpoint: string, input: Record<string, unknown>): string {
-  const prompt = input['prompt'];
-  if (typeof prompt === 'string' && prompt.trim()) {
-    return prompt.trim().length > 64 ? `${prompt.trim().slice(0, 61)}…` : prompt.trim();
-  }
-  return ENDPOINT_LABELS[endpoint] ?? endpoint;
-}
-export const tool = defineTool({
-  name: 'project.fal.submit',
-  summary: 'Submit a Fal request',
-  description:
-    'Submits one provider-native Fal queue request. No project files are written until project.fal.accept.',
-  input: SubmissionSchema,
-  result: SubmitResultSchema,
-  errors: falToolErrors,
-  requires: { project: true },
-  host: 'node',
-  mutates: false,
-  supportsDryRun: false,
-  longRunning: false,
-  permission: {
-    risk: 'write',
-    summary: 'Creates an external Fal request that may incur provider charges.',
-  },
-  impl: falTool(submitFal),
-});
-
-export const generation = {
-  role: 'submit',
-  provider: 'fal',
-  toJob(inputValue, resultValue) {
-    const input = SubmissionSchema.parse(inputValue);
-    const result = SubmitResultSchema.parse(resultValue);
-    return {
-      provider: 'fal',
-      externalId: result.requestId,
-      label: jobLabel(input.endpoint, input.input),
-      operation: input.endpoint,
-      mode: input.mode,
-      status: 'queued',
-      billing:
-        input.mode === 'mock'
-          ? { route: 'mock' }
-          : input.mode === 'managed'
-            ? {
-                route: 'managed',
-                ...(result.estimatedCredits === undefined
-                  ? {}
-                  : { estimatedCredits: result.estimatedCredits }),
-              }
-            : {
-                route: 'byok',
-                currency: 'USD',
-                ...(result.quote?.estimatedAmount === undefined
-                  ? {}
-                  : { estimatedAmount: result.quote.estimatedAmount }),
-              },
-      poll: {
-        tool: 'project.fal.poll',
-        input: { mode: input.mode, endpoint: input.endpoint, requestId: result.requestId },
-      },
-      cancel: {
-        tool: 'project.fal.cancel',
-        input: {
-          mode: input.mode,
-          endpoint: input.endpoint,
-          requestId: result.requestId,
-          cancelUrl: result.cancelUrl,
-        },
-      },
-      accept: {
-        tool: 'project.fal.accept',
-        input: { ...input, requestId: result.requestId },
-      },
-    };
-  },
-} satisfies GenerationToolContribution;