@vgai/fal 0.1.0

package/README.md

@@ -0,0 +1,41 @@
+# @vgai/fal
+
+Optional Project Tools and editor UI for Fal. The package registers
+`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
+creates an external candidate; cancellation changes the shared job
+only after Fal confirms it; acceptance validates and atomically commits its
+ordinary files and provenance. Install `@vgai/fal-client-compat` alone when only
+directly authored `@fal-ai/client` calls are needed.
+
+Operation-shaped creation documents submit native Fal inputs for image
+generation, reference-conditioned image editing, audio, object reconstruction,
+video, panorama, and layered-world work. The image-edit document accepts one
+reference URL per line and submits the ordered list as native `image_urls`.
+Native JSON is available under Advanced. The poll operation contributes native
+result media inside the editor-owned result document; all operations still feed
+the single durable **Generations** activity ledger. There is no
+provider-specific queue.
+
+Mock is the default UI mode. Direct mode reads `FAL_KEY`; managed mode reads
+`VGAI_GENERATION_GATEWAY` and `VGAI_ACCESS_TOKEN`. Supported registered
+endpoints match the compatibility package's tested image, audio, splat, video,
+panorama, and Hunyuan-world slices. Other Fal endpoints remain directly
+callable and are not forced through a VGAI request schema.
+The global Account document can store the Fal key in the operating system
+credential manager; the trusted editor server hydrates `FAL_KEY` before tool
+execution. An explicitly inherited `FAL_KEY` remains the higher-priority
+CI/agent override.
+Connection testing verifies the inference credential without inspecting the
+provider wallet. Poll results preserve native status and queue position. Submit also preserves Fal's
+provider-issued response, status, and cancellation URLs; status responses are
+tolerated when the live provider omits those documented fields. Cancellation
+uses the exact saved URL instead of reconstructing one from a possibly aliased
+endpoint. The shared ledger separately records the last poll and the last
+actual provider-state change.
+
+The document receives only the editor's sanitized account projection; `FAL_KEY`
+and the VGAI bearer token stay in Node transports. Its result module exports
+`match(job, result)` so future Fal result shapes cannot collide by registration
+order.

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@vgai/fal",
+  "author": "Volter AI, Inc.",
+  "license": "Apache-2.0",
+  "version": "0.1.0",
+  "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",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/volter-ai/vgai-engine.git",
+    "directory": "packages/fal"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "exports": {
+    "./accept": "./src/accept.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"
+    ]
+  },
+  "dependencies": {
+    "@fal-ai/client": "1.10.1",
+    "@vgai/fal-client-compat": "0.1.0",
+    "@vgai/sdk": "0.5.0",
+    "fflate": "^0.8.2",
+    "three": "^0.180.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.0",
+    "@types/react": "^19.2.14",
+    "@types/three": "^0.180.0",
+    "@vgai/editor-sdk": "0.5.0",
+    "react": "^19.2.4"
+  }
+}

package/src/accept.tool.ts

@@ -0,0 +1,49 @@
+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/accept.ts

@@ -0,0 +1,193 @@
+import { posix } from 'node:path';
+import type { ToolContext } from '@vgai/sdk/tools';
+import { unzipSync } from 'fflate';
+import { PLYLoader } from 'three/addons/loaders/PLYLoader.js';
+import type { AcceptInput, FalEndpoint } from './contracts.js';
+import { SEEDANCE_2_REFERENCE_TO_VIDEO_ENDPOINT } from './contracts.js';
+import { quoteFalPrice } from './pricing.js';
+import { falArtifactFetch, falBilling, falClient } from './provider.js';
+
+interface NativeFile {
+  url: string;
+  content_type?: string;
+  file_name?: string;
+}
+interface AcceptedFile {
+  filename: string;
+  mediaType: string;
+  bytes: Uint8Array;
+}
+
+function directory(value: string): string {
+  const normalized = posix
+    .normalize(value.replaceAll('\\', '/'))
+    .replace(/^\.\//, '')
+    .replace(/\/$/, '');
+  if (
+    !normalized.startsWith('public/') ||
+    normalized === 'public' ||
+    normalized.split('/').includes('..')
+  ) {
+    throw new Error('Fal outputDirectory must be a project-relative directory under public/.');
+  }
+  return normalized;
+}
+
+function nativeFile(value: unknown, label: string): NativeFile {
+  if (!value || typeof value !== 'object' || typeof (value as NativeFile).url !== 'string') {
+    throw new Error(`Fal result has no ${label} file.`);
+  }
+  return value as NativeFile;
+}
+
+function decodeDataUrl(url: string): Uint8Array | undefined {
+  const match = /^data:[^;,]+;base64,(.+)$/.exec(url);
+  return match?.[1] ? Uint8Array.from(Buffer.from(match[1], 'base64')) : undefined;
+}
+
+async function download(file: NativeFile, fetcher: typeof fetch): Promise<Uint8Array> {
+  const embedded = decodeDataUrl(file.url);
+  if (embedded) return embedded;
+  const response = await fetcher(file.url);
+  if (!response.ok) throw new Error(`Fal artifact download failed with HTTP ${response.status}.`);
+  return new Uint8Array(await response.arrayBuffer());
+}
+
+function png(bytes: Uint8Array, panorama = false): void {
+  const signature = [137, 80, 78, 71, 13, 10, 26, 10];
+  if (bytes.byteLength < 24 || !signature.every((byte, index) => bytes[index] === byte))
+    throw new Error('Fal image is not a PNG container.');
+  if (panorama) {
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    if (view.getUint32(16) !== view.getUint32(20) * 2)
+      throw new Error('Fal panorama must be exactly 2:1.');
+  }
+}
+
+function wav(bytes: Uint8Array): void {
+  const text = new TextDecoder().decode(bytes.subarray(0, 12));
+  if (!text.startsWith('RIFF') || !text.endsWith('WAVE'))
+    throw new Error('Fal audio is not a WAV container.');
+}
+
+function webm(bytes: Uint8Array): void {
+  if (![0x1a, 0x45, 0xdf, 0xa3].every((byte, index) => bytes[index] === byte))
+    throw new Error('Fal video is not a WebM container.');
+}
+
+function mp4(bytes: Uint8Array): void {
+  if (bytes.byteLength < 12 || new TextDecoder().decode(bytes.subarray(4, 8)) !== 'ftyp') {
+    throw new Error('Fal video is not an MP4 container.');
+  }
+}
+
+async function video(file: NativeFile, fetcher: typeof fetch): Promise<AcceptedFile> {
+  const bytes = await download(file, fetcher);
+  const mediaType = file.content_type?.split(';', 1)[0]?.toLowerCase();
+  if (mediaType === 'video/webm' || bytes[0] === 0x1a) {
+    webm(bytes);
+    return { filename: 'video.webm', mediaType: 'video/webm', bytes };
+  }
+  mp4(bytes);
+  return { filename: 'video.mp4', mediaType: 'video/mp4', bytes };
+}
+
+function ply(bytes: Uint8Array): void {
+  const geometry = new PLYLoader().parse(Uint8Array.from(bytes).buffer);
+  try {
+    if (!geometry.getAttribute('position') || geometry.getAttribute('position').count === 0)
+      throw new Error('Fal PLY contains no positions.');
+  } finally {
+    geometry.dispose();
+  }
+}
+
+async function acceptedFiles(
+  endpoint: FalEndpoint,
+  data: Record<string, unknown>,
+  fetcher: typeof fetch,
+): Promise<AcceptedFile[]> {
+  if (
+    endpoint === 'fal-ai/nano-banana-2' ||
+    endpoint === 'fal-ai/nano-banana-2/edit' ||
+    endpoint === 'fal-ai/nano-banana' ||
+    endpoint === 'fal-ai/nano-banana/edit'
+  ) {
+    const images = data['images'];
+    if (!Array.isArray(images) || images.length === 0) throw new Error('Fal result has no images.');
+    return Promise.all(
+      images.map(async (value, index) => {
+        const bytes = await download(nativeFile(value, 'image'), fetcher);
+        png(bytes);
+        return { filename: `image-${index + 1}.png`, mediaType: 'image/png', bytes };
+      }),
+    );
+  }
+  if (endpoint === 'fal-ai/stable-audio') {
+    const bytes = await download(nativeFile(data['audio_file'], 'audio'), fetcher);
+    wav(bytes);
+    return [{ filename: 'audio.wav', mediaType: 'audio/wav', bytes }];
+  }
+  if (endpoint === 'fal-ai/sam-3/3d-objects') {
+    const bytes = await download(nativeFile(data['gaussian_splat'], 'Gaussian splat'), fetcher);
+    ply(bytes);
+    return [{ filename: 'splat.ply', mediaType: 'application/octet-stream', bytes }];
+  }
+  if (
+    endpoint === 'fal-ai/minimax/hailuo-02/standard/text-to-video' ||
+    endpoint === SEEDANCE_2_REFERENCE_TO_VIDEO_ENDPOINT
+  ) {
+    return [await video(nativeFile(data['video'], 'video'), fetcher)];
+  }
+  if (endpoint === 'fal-ai/hunyuan_world') {
+    const bytes = await download(nativeFile(data['image'], 'panorama'), fetcher);
+    png(bytes, true);
+    return [{ filename: 'panorama.png', mediaType: 'image/png', bytes }];
+  }
+  const bytes = await download(nativeFile(data['world_file'], 'world archive'), fetcher);
+  const archive = unzipSync(bytes);
+  for (const name of ['mesh_layer0.ply', 'mesh_layer1.ply']) {
+    const layer = archive[name];
+    if (!layer) throw new Error(`Fal world archive is missing ${name}.`);
+    ply(layer);
+  }
+  return [{ filename: 'world.zip', mediaType: 'application/zip', bytes }];
+}
+
+export async function acceptFal(input: AcceptInput, ctx: ToolContext) {
+  if (!ctx.projectOutputs) throw new Error('The project-output writer is unavailable.');
+  const result = await falClient(input.mode).queue.result(input.endpoint, {
+    requestId: input.requestId,
+  });
+  const usage = falBilling(input.requestId);
+  const quote = input.mode === 'direct' ? await quoteFalPrice(input) : undefined;
+  const files = await acceptedFiles(
+    input.endpoint,
+    result.data as Record<string, unknown>,
+    falArtifactFetch(input.mode),
+  );
+  const root = directory(input.outputDirectory);
+  const committed = await ctx.projectOutputs.write(
+    files.map((file) => ({
+      path: `${root}/${file.filename}`,
+      content: file.bytes,
+      mediaType: file.mediaType,
+      role: 'asset' as const,
+    })),
+  );
+  if (!committed.provenanceOperationId)
+    throw new Error('Fal output commit returned no provenance operation ID.');
+  return {
+    requestId: input.requestId,
+    files: committed.files.map((file) => ({
+      path: file.path,
+      bytes: file.bytes,
+      ...(file.mediaType ? { mediaType: file.mediaType } : {}),
+    })),
+    provenanceOperationId: committed.provenanceOperationId,
+    ...(quote && usage?.billableUnits !== undefined
+      ? { settledAmount: quote.unitPrice * usage.billableUnits }
+      : {}),
+    ...(usage?.settledCredits === undefined ? {} : { settledCredits: usage.settledCredits }),
+  };
+}

package/src/cancel.tool.ts

@@ -0,0 +1,36 @@
+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/cancel.ts

@@ -0,0 +1,70 @@
+import { ApiError } from '@fal-ai/client';
+import { ToolError } from '@vgai/sdk/tools';
+import type { CancelInput } from './contracts.js';
+import { falClient } from './provider.js';
+
+function endpointFromCancelUrl(cancelUrl: string, requestId: string): string {
+  const url = new URL(cancelUrl);
+  const match = /^\/(.+)\/requests\/([^/]+)\/cancel$/.exec(url.pathname);
+  if (
+    url.protocol !== 'https:' ||
+    url.hostname !== 'queue.fal.run' ||
+    !match?.[1] ||
+    decodeURIComponent(match[2] ?? '') !== requestId
+  ) {
+    throw new ToolError('PROVIDER_ERROR', 'Fal returned an invalid cancellation URL.');
+  }
+  return match[1];
+}
+
+export async function cancelFal(input: CancelInput) {
+  try {
+    const endpoint = input.cancelUrl
+      ? endpointFromCancelUrl(input.cancelUrl, input.requestId)
+      : input.endpoint;
+    await falClient(input.mode).queue.cancel(endpoint, {
+      requestId: input.requestId,
+    });
+  } catch (cause) {
+    const body =
+      cause instanceof ApiError ? (cause.body as Record<string, unknown> | undefined) : undefined;
+    const providerStatus = typeof body?.['status'] === 'string' ? body['status'] : undefined;
+    if (cause instanceof ApiError && cause.status === 404) {
+      throw new ToolError(
+        'REQUEST_NOT_FOUND',
+        `Fal does not recognize request ${input.requestId}; cancellation was not recorded.`,
+        {
+          provider: 'fal',
+          requestId: input.requestId,
+          status: cause.status,
+          providerStatus,
+          ...(input.cancelUrl ? { cancelUrl: input.cancelUrl } : {}),
+        },
+      );
+    }
+    if (
+      cause instanceof ApiError &&
+      cause.status === 400 &&
+      providerStatus === 'ALREADY_COMPLETED'
+    ) {
+      throw new ToolError(
+        'ALREADY_COMPLETED',
+        `Fal completed request ${input.requestId} before cancellation. Poll it for the result.`,
+        { provider: 'fal', requestId: input.requestId, status: cause.status, providerStatus },
+      );
+    }
+    const detail = body?.['detail'] ?? body?.['message'];
+    const message =
+      typeof detail === 'string'
+        ? detail
+        : detail !== undefined
+          ? JSON.stringify(detail)
+          : cause instanceof Error
+            ? cause.message
+            : String(cause);
+    throw new ToolError('PROVIDER_ERROR', message, {
+      ...(cause instanceof ApiError && cause.status ? { status: cause.status } : {}),
+    });
+  }
+  return { requestId: input.requestId, status: 'cancelled' as const };
+}

package/src/contracts.ts

@@ -0,0 +1,102 @@
+import { z } from 'zod';
+
+export const ExecutionModeSchema = z.enum(['mock', 'direct', 'managed']);
+export const DEFAULT_FAL_IMAGE_ENDPOINT = 'fal-ai/nano-banana-2' as const;
+export const DEFAULT_FAL_IMAGE_EDIT_ENDPOINT = 'fal-ai/nano-banana-2/edit' as const;
+export const NANO_BANANA_2_UNDERLYING_ENDPOINT = 'fal-ai/gemini-3.1-flash-image-preview' as const;
+export const SEEDANCE_2_REFERENCE_TO_VIDEO_ENDPOINT =
+  'bytedance/seedance-2.0/reference-to-video' as const;
+export const FAL_IMAGE_CONTRIBUTION_DEFAULTS = {
+  'generate-image': DEFAULT_FAL_IMAGE_ENDPOINT,
+  'edit-image': DEFAULT_FAL_IMAGE_EDIT_ENDPOINT,
+} as const;
+export const FalEndpointSchema = z.enum([
+  DEFAULT_FAL_IMAGE_ENDPOINT,
+  DEFAULT_FAL_IMAGE_EDIT_ENDPOINT,
+  NANO_BANANA_2_UNDERLYING_ENDPOINT,
+  'fal-ai/nano-banana',
+  'fal-ai/nano-banana/edit',
+  'fal-ai/stable-audio',
+  'fal-ai/sam-3/3d-objects',
+  'fal-ai/minimax/hailuo-02/standard/text-to-video',
+  SEEDANCE_2_REFERENCE_TO_VIDEO_ENDPOINT,
+  'fal-ai/hunyuan_world/image-to-world',
+  'fal-ai/hunyuan_world',
+]);
+export const SubmissionSchema = z.object({
+  mode: ExecutionModeSchema.default('mock'),
+  endpoint: FalEndpointSchema,
+  input: z.record(z.string(), z.unknown()),
+  outputDirectory: z.string().min(1).default('public/generated/fal/output'),
+});
+export const QuoteInputSchema = SubmissionSchema.pick({ mode: true, endpoint: true, input: true });
+export const QuoteResultSchema = z
+  .object({
+    mode: ExecutionModeSchema,
+    endpoint: FalEndpointSchema,
+    currency: z.literal('USD'),
+    unitPrice: z.number().nonnegative(),
+    unit: z.string().min(1),
+    quantity: z.number().positive().optional(),
+    estimatedAmount: z.number().nonnegative().optional(),
+    estimatedCredits: z.number().nonnegative().optional(),
+  })
+  .nullable();
+export const SubmitResultSchema = z.object({
+  requestId: z.string(),
+  responseUrl: z.string().url(),
+  statusUrl: z.string().url(),
+  cancelUrl: z.string().url(),
+  mode: ExecutionModeSchema,
+  endpoint: FalEndpointSchema,
+  input: z.record(z.string(), z.unknown()),
+  outputDirectory: z.string(),
+  quote: QuoteResultSchema.optional(),
+  estimatedCredits: z.number().nonnegative().optional(),
+});
+export const PollInputSchema = z.object({
+  mode: ExecutionModeSchema,
+  endpoint: FalEndpointSchema,
+  requestId: z.string().min(1),
+});
+export const PollResultSchema = z.object({
+  requestId: z.string(),
+  responseUrl: z.string().url().optional(),
+  statusUrl: z.string().url().optional(),
+  cancelUrl: z.string().url().optional(),
+  status: z.enum(['IN_QUEUE', 'IN_PROGRESS', 'COMPLETED']),
+  done: z.boolean(),
+  queuePosition: z.number().int().nonnegative().optional(),
+  estimatedCredits: z.number().nonnegative().optional(),
+  settledCredits: z.number().nonnegative().optional(),
+  output: z.unknown().optional(),
+  error: z.object({ status: z.number().int().optional(), message: z.string().min(1) }).optional(),
+});
+export const CancelInputSchema = PollInputSchema.extend({
+  cancelUrl: z.string().url().optional(),
+});
+export const CancelResultSchema = z.object({
+  requestId: z.string(),
+  status: z.literal('cancelled'),
+});
+export const AcceptInputSchema = SubmissionSchema.extend({ requestId: z.string().min(1) });
+export const AcceptResultSchema = z.object({
+  requestId: z.string(),
+  files: z.array(
+    z.object({
+      path: z.string(),
+      bytes: z.number().int().nonnegative(),
+      mediaType: z.string().optional(),
+    }),
+  ),
+  provenanceOperationId: z.string(),
+  settledAmount: z.number().nonnegative().optional(),
+  settledCredits: z.number().nonnegative().optional(),
+});
+export type ExecutionMode = z.infer<typeof ExecutionModeSchema>;
+export type FalEndpoint = z.infer<typeof FalEndpointSchema>;
+export type Submission = z.infer<typeof SubmissionSchema>;
+export type QuoteInput = z.infer<typeof QuoteInputSchema>;
+export type PollInput = z.infer<typeof PollInputSchema>;
+export type CancelInput = z.infer<typeof CancelInputSchema>;
+export type AcceptInput = z.infer<typeof AcceptInputSchema>;

package/src/poll.tool.ts

@@ -0,0 +1,70 @@
+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/poll.ts

@@ -0,0 +1,55 @@
+import { ApiError } from '@fal-ai/client';
+import type { PollInput } from './contracts.js';
+import { falBilling, falClient } from './provider.js';
+
+function providerError(error: unknown): { status?: number; message: string } {
+  if (error instanceof ApiError) {
+    const body = error.body as Record<string, unknown> | undefined;
+    const detail = body?.['detail'];
+    const message =
+      typeof detail === 'string'
+        ? detail
+        : detail !== undefined
+          ? JSON.stringify(detail)
+          : typeof body?.['message'] === 'string'
+            ? body['message']
+            : body
+              ? JSON.stringify(body)
+              : error.message;
+    return { status: error.status, message };
+  }
+  return { message: error instanceof Error ? error.message : String(error) };
+}
+
+export async function pollFal(input: PollInput) {
+  const status = await falClient(input.mode).queue.status(input.endpoint, {
+    requestId: input.requestId,
+  });
+  let output: { data: unknown } | undefined;
+  let error: { status?: number; message: string } | undefined;
+  if (status.status === 'COMPLETED') {
+    try {
+      output = await falClient(input.mode).queue.result(input.endpoint, {
+        requestId: input.requestId,
+      });
+    } catch (cause) {
+      error = providerError(cause);
+    }
+  }
+  const billing = input.mode === 'managed' ? falBilling(input.requestId) : undefined;
+  return {
+    requestId: input.requestId,
+    ...(status.response_url ? { responseUrl: status.response_url } : {}),
+    ...(status.status_url ? { statusUrl: status.status_url } : {}),
+    ...(status.cancel_url ? { cancelUrl: status.cancel_url } : {}),
+    status: status.status,
+    done: status.status === 'COMPLETED',
+    ...(status.status === 'IN_QUEUE' ? { queuePosition: status.queue_position } : {}),
+    ...(output ? { output: output.data } : {}),
+    ...(billing?.estimatedCredits === undefined
+      ? {}
+      : { estimatedCredits: billing.estimatedCredits }),
+    ...(billing?.settledCredits === undefined ? {} : { settledCredits: billing.settledCredits }),
+    ...(error ? { error } : {}),
+  };
+}

package/src/pricing.ts

@@ -0,0 +1,149 @@
+import {
+  type ExecutionMode,
+  type FalEndpoint,
+  NANO_BANANA_2_UNDERLYING_ENDPOINT,
+} from './contracts.js';
+
+export interface FalPriceQuote {
+  mode: ExecutionMode;
+  endpoint: FalEndpoint;
+  currency: 'USD';
+  unitPrice: number;
+  unit: string;
+  quantity?: number;
+  estimatedAmount?: number;
+  estimatedCredits?: number;
+}
+
+function required(name: string): string {
+  const value = process.env[name];
+  if (!value) throw new Error(`${name} is required for this execution mode.`);
+  return value;
+}
+
+function positiveNumber(value: unknown): number | undefined {
+  const parsed =
+    typeof value === 'number' ? value : typeof value === 'string' ? Number(value) : NaN;
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : undefined;
+}
+
+function duration(input: Record<string, unknown>): number | undefined {
+  return ['seconds_total', 'duration', 'video_length']
+    .map((key) => positiveNumber(input[key]))
+    .find((value) => value !== undefined);
+}
+
+function quantity(unit: string, input: Record<string, unknown>): number | undefined {
+  const normalized = unit.toLowerCase().replaceAll('-', '_').replaceAll(' ', '_');
+  if (normalized.includes('image') && !normalized.includes('megapixel')) {
+    return typeof input['num_images'] === 'number' ? input['num_images'] : 1;
+  }
+  if (normalized.includes('second')) {
+    return duration(input);
+  }
+  if (normalized.includes('request') || normalized.includes('generation') || normalized === 'unit')
+    return 1;
+  return undefined;
+}
+
+function nanoBanana2UnitPrice(
+  endpoint: FalEndpoint,
+  baseUnitPrice: number,
+  input: Record<string, unknown>,
+): number {
+  if (
+    endpoint !== 'fal-ai/nano-banana-2' &&
+    endpoint !== 'fal-ai/nano-banana-2/edit' &&
+    endpoint !== NANO_BANANA_2_UNDERLYING_ENDPOINT
+  ) {
+    return baseUnitPrice;
+  }
+  const resolutionMultiplier =
+    input['resolution'] === '0.5K'
+      ? 0.75
+      : input['resolution'] === '2K'
+        ? 1.5
+        : input['resolution'] === '4K'
+          ? 2
+          : 1;
+  const webSearchSurcharge =
+    input['enable_web_search'] === true || input['enable_google_search'] === true ? 0.015 : 0;
+  const highThinkingSurcharge = input['thinking_level'] === 'high' ? 0.002 : 0;
+  return baseUnitPrice * resolutionMultiplier + webSearchSurcharge + highThinkingSurcharge;
+}
+
+async function managedCreditEstimate(
+  options: { endpoint: FalEndpoint; input: Record<string, unknown> },
+  price: { unitPrice: number; unit: string; quantity?: number },
+): Promise<number | undefined> {
+  const response = await fetch(
+    `${required('VGAI_GENERATION_GATEWAY').replace(/\/$/, '')}/billing/quote`,
+    {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${required('VGAI_ACCESS_TOKEN')}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        provider: 'fal',
+        model: options.endpoint,
+        input: options.input,
+        providerPrice: { currency: 'USD', ...price },
+      }),
+    },
+  );
+  if (!response.ok) return undefined;
+  const quote = (await response.json()) as { estimatedCredits?: unknown };
+  return typeof quote.estimatedCredits === 'number' && quote.estimatedCredits >= 0
+    ? quote.estimatedCredits
+    : undefined;
+}
+
+export async function quoteFalPrice(options: {
+  mode: ExecutionMode;
+  endpoint: FalEndpoint;
+  input: Record<string, unknown>;
+}): Promise<FalPriceQuote | null> {
+  if (options.mode === 'mock') return null;
+  const target = new URL('https://api.fal.ai/v1/models/pricing');
+  target.searchParams.set('endpoint_id', options.endpoint);
+  const response =
+    options.mode === 'direct'
+      ? await fetch(target, { headers: { Authorization: `Key ${required('FAL_KEY')}` } })
+      : await fetch(
+          `${required('VGAI_GENERATION_GATEWAY').replace(/\/$/, '')}/fal/pricing?${target.searchParams}`,
+          { headers: { Authorization: `Bearer ${required('VGAI_ACCESS_TOKEN')}` } },
+        );
+  if (!response.ok) throw new Error(`Fal pricing request failed with HTTP ${response.status}.`);
+  const body = (await response.json()) as { prices?: unknown };
+  const price = Array.isArray(body.prices)
+    ? body.prices.find(
+        (entry): entry is Record<string, unknown> => !!entry && typeof entry === 'object',
+      )
+    : undefined;
+  if (!price || typeof price['unit_price'] !== 'number' || typeof price['unit'] !== 'string') {
+    throw new Error(`Fal returned no current price for ${options.endpoint}.`);
+  }
+  if (price['currency'] !== undefined && price['currency'] !== 'USD') {
+    throw new Error(`Fal returned unsupported pricing currency ${String(price['currency'])}.`);
+  }
+  const unitPrice = nanoBanana2UnitPrice(options.endpoint, price['unit_price'], options.input);
+  const count = quantity(price['unit'], options.input);
+  const estimatedCredits =
+    options.mode === 'managed'
+      ? await managedCreditEstimate(options, {
+          unitPrice,
+          unit: price['unit'],
+          ...(count === undefined ? {} : { quantity: count }),
+        })
+      : undefined;
+  return {
+    mode: options.mode,
+    endpoint: options.endpoint,
+    currency: 'USD',
+    unitPrice,
+    unit: price['unit'],
+    ...(count === undefined ? {} : { quantity: count, estimatedAmount: unitPrice * count }),
+    ...(estimatedCredits === undefined ? {} : { estimatedCredits }),
+  };
+}

package/src/provider.ts

@@ -0,0 +1,88 @@
+import { createFalClient, type FalClient } from '@fal-ai/client';
+import { createDirectFalFetch } from '@vgai/fal-client-compat/direct';
+import { createManagedFalFetch } from '@vgai/fal-client-compat/managed';
+import { createMockFalClient } from '@vgai/fal-client-compat/mock';
+import type { ExecutionMode } from './contracts.js';
+
+const clients = new Map<ExecutionMode, FalClient>();
+const fetchers = new Map<ExecutionMode, typeof fetch>();
+const billing = new Map<
+  string,
+  { estimatedCredits?: number; settledCredits?: number; billableUnits?: number }
+>();
+
+function numericHeader(response: Response, name: string): number | undefined {
+  const value = Number(response.headers.get(name));
+  return Number.isFinite(value) && value >= 0 ? value : undefined;
+}
+
+function observeBilling(fetcher: typeof fetch): typeof fetch {
+  return async (input, init) => {
+    const request = new Request(input, init);
+    const response = await fetcher(request);
+    const pathId = /\/requests\/([^/]+)/.exec(new URL(request.url).pathname)?.[1];
+    const requestId = response.headers.get('x-fal-request-id') ?? pathId;
+    if (requestId) {
+      const previous = billing.get(decodeURIComponent(requestId)) ?? {};
+      billing.set(decodeURIComponent(requestId), {
+        ...previous,
+        ...(numericHeader(response, 'X-VGAI-Estimated-Credits') === undefined
+          ? {}
+          : { estimatedCredits: numericHeader(response, 'X-VGAI-Estimated-Credits')! }),
+        ...(numericHeader(response, 'X-VGAI-Settled-Credits') === undefined
+          ? {}
+          : { settledCredits: numericHeader(response, 'X-VGAI-Settled-Credits')! }),
+        ...(numericHeader(response, 'X-Fal-Billable-Units') === undefined
+          ? {}
+          : { billableUnits: numericHeader(response, 'X-Fal-Billable-Units')! }),
+      });
+    }
+    return response;
+  };
+}
+
+function required(name: string): string {
+  const value = process.env[name];
+  if (!value) throw new Error(`${name} is required for this execution mode.`);
+  return value;
+}
+
+export function falClient(mode: ExecutionMode): FalClient {
+  const existing = clients.get(mode);
+  if (existing) return existing;
+  let client: FalClient;
+  if (mode === 'mock') {
+    client = createMockFalClient();
+  } else if (mode === 'direct') {
+    const fetcher = observeBilling(createDirectFalFetch());
+    fetchers.set(mode, fetcher);
+    client = createFalClient({ credentials: required('FAL_KEY'), fetch: fetcher });
+  } else {
+    const fetcher = observeBilling(
+      createManagedFalFetch({
+        gatewayUrl: required('VGAI_GENERATION_GATEWAY'),
+        accessToken: () => required('VGAI_ACCESS_TOKEN'),
+      }),
+    );
+    fetchers.set(mode, fetcher);
+    client = createFalClient({
+      credentials: undefined,
+      proxyUrl: {
+        url: `${required('VGAI_GENERATION_GATEWAY').replace(/\/$/, '')}/fal/proxy`,
+        when: 'always',
+      },
+      fetch: fetcher,
+    });
+  }
+  clients.set(mode, client);
+  return client;
+}
+
+export function falBilling(requestId: string) {
+  return billing.get(requestId);
+}
+
+export function falArtifactFetch(mode: ExecutionMode): typeof fetch {
+  falClient(mode);
+  return fetchers.get(mode) ?? globalThis.fetch;
+}

package/src/quote.tool.ts

@@ -0,0 +1,20 @@
+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

@@ -0,0 +1,101 @@
+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;

package/src/submit.ts

@@ -0,0 +1,27 @@
+import type { Submission } from './contracts.js';
+import { quoteFalPrice } from './pricing.js';
+import { falBilling, falClient } from './provider.js';
+
+export async function submitFal(input: Submission) {
+  const quote = await quoteFalPrice(input);
+  const queued = await falClient(input.mode).queue.submit(input.endpoint, {
+    input: input.input as never,
+  });
+  const billing = input.mode === 'managed' ? falBilling(queued.request_id) : undefined;
+  return {
+    requestId: queued.request_id,
+    responseUrl: queued.response_url,
+    statusUrl: queued.status_url,
+    cancelUrl: queued.cancel_url,
+    mode: input.mode,
+    endpoint: input.endpoint,
+    input: input.input,
+    outputDirectory: input.outputDirectory,
+    ...(quote ? { quote } : {}),
+    ...(billing?.estimatedCredits === undefined && quote?.estimatedCredits === undefined
+      ? {}
+      : {
+          estimatedCredits: billing?.estimatedCredits ?? quote!.estimatedCredits!,
+        }),
+  };
+}

package/src/tool-error.ts

@@ -0,0 +1,29 @@
+import { type ToolContext, ToolError } from '@vgai/sdk/tools';
+
+export const falToolErrors = [
+  { code: 'PROVIDER_ERROR', summary: 'Fal rejected the request or could not be reached.' },
+  { code: 'REQUEST_NOT_FOUND', summary: 'Fal no longer recognizes the request id.' },
+  { code: 'ALREADY_COMPLETED', summary: 'Fal completed the request before cancellation.' },
+] as const;
+
+const OPERATION_ERROR_BRAND = Symbol.for('@vgai/sdk.ToolError');
+
+export function falTool<TInput, TResult>(
+  impl: (input: TInput, ctx: ToolContext) => Promise<TResult>,
+): (input: TInput, ctx: ToolContext) => Promise<TResult> {
+  return async (input, ctx) => {
+    try {
+      return await impl(input, ctx);
+    } catch (cause) {
+      if (
+        cause &&
+        typeof cause === 'object' &&
+        (cause as Record<PropertyKey, unknown>)[OPERATION_ERROR_BRAND] === true
+      ) {
+        throw cause;
+      }
+      const message = cause instanceof Error ? cause.message : String(cause);
+      throw new ToolError('PROVIDER_ERROR', message, { provider: 'fal', message });
+    }
+  };
+}