runline 0.31.0 → 0.33.0

package/dist/plugins/fal/src/index.js

@@ -0,0 +1,181 @@
+import * as t from "typebox";
+import { readImageInput } from "../../_shared/mediaFile.js";
+import { parseSize } from "../../_shared/parseSize.js";
+import { assertModelId, cancel, DEFAULT_TIMEOUT_MS, extraInputSchema, result, runModel, STRICT, saveDirSchema, savedResult, status, submit, timeoutSchema, } from "./shared.js";
+const IMAGE_MODEL = "fal-ai/flux/schnell";
+const EDIT_MODEL = "fal-ai/flux-pro/kontext";
+const VIDEO_MODEL = "fal-ai/kling-video/v1/standard/text-to-video";
+const model = t.String({
+    minLength: 1,
+    description: "fal endpoint id: owner/model[/variant], workflows/owner/model, or comfy/owner/model.",
+});
+const prompt = t.String({
+    minLength: 1,
+    pattern: "\\S",
+    description: "Describe the image, edit, or video.",
+});
+const fileOptions = { saveDir: t.Optional(saveDirSchema) };
+const generationOptions = {
+    ...fileOptions,
+    timeoutMs: t.Optional(timeoutSchema),
+    extraInput: t.Optional(extraInputSchema),
+};
+const createSchema = t.Object({
+    ...generationOptions,
+    prompt,
+    model: t.Optional(t.String({ ...model, default: IMAGE_MODEL })),
+    size: t.Optional(t.String({
+        pattern: "^[1-9][0-9]*x[1-9][0-9]*$",
+        description: "WxH, sent as image_size. Omit for the model's default. For other size fields use extraInput.",
+    })),
+    n: t.Optional(t.Integer({
+        minimum: 1,
+        maximum: 4,
+        default: 1,
+        description: "num_images; supported counts depend on the model.",
+    })),
+}, STRICT);
+const editSchema = t.Object({
+    ...generationOptions,
+    prompt,
+    model: t.Optional(t.String({ ...model, default: EDIT_MODEL })),
+    imagePath: t.String({
+        minLength: 1,
+        description: "Local source image, sent as a data URI. For hosted input URLs use fal.run instead.",
+    }),
+    imageInputKey: t.Optional(t.String({
+        minLength: 1,
+        default: "image_url",
+        description: "Source field; keys ending in _urls receive an array. Use image_urls for fal-ai/nano-banana/edit.",
+    })),
+}, STRICT);
+const videoSchema = t.Object({
+    ...generationOptions,
+    prompt,
+    model: t.Optional(t.String({ ...model, default: VIDEO_MODEL })),
+}, STRICT);
+const modelInput = {
+    model,
+    input: t.Record(t.String(), t.Unknown(), {
+        description: "Model input body, verbatim. See https://fal.ai/models/<model>/api.",
+    }),
+};
+const runSchema = t.Object({ ...modelInput, ...fileOptions, timeoutMs: t.Optional(timeoutSchema) }, STRICT);
+const submitSchema = t.Object(modelInput, STRICT);
+const requestInput = {
+    model,
+    requestId: t.String({
+        minLength: 1,
+        description: "Request id returned by queue.submit or a timeout error.",
+    }),
+};
+const statusInput = t.Object({ ...requestInput, logs: t.Optional(t.Boolean({ default: false })) }, STRICT);
+const resultInput = t.Object({ ...requestInput, ...fileOptions }, STRICT);
+const cancelInput = t.Object(requestInput, STRICT);
+async function generate(ctx, p, model, input, kind) {
+    const id = assertModelId(model);
+    const { output, requestId } = await runModel(ctx, id, { ...input, ...p.extraInput }, p.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+    return savedResult(output, id, requestId, p.saveDir, kind);
+}
+/** fal model inference via its queue API. Generation is billed; downloads return local paths. */
+export default function fal(rl) {
+    rl.setName("fal");
+    rl.setVersion("0.1.0");
+    rl.setConnectionSchema(t.Object({
+        apiKey: t.String({
+            minLength: 1,
+            env: "FAL_KEY",
+            description: "API key from https://fal.ai/dashboard/keys, sent as Authorization: Key <key>.",
+        }),
+    }));
+    rl.registerAction("image.create", {
+        access: "write",
+        description: `Generate images through fal (billed). Defaults to ${IMAGE_MODEL}. Saves files and returns images[].path for send_file. Additional model parameters go in extraInput.`,
+        inputSchema: createSchema,
+        async execute(input, ctx) {
+            const p = input;
+            return generate(ctx, p, p.model ?? IMAGE_MODEL, {
+                prompt: p.prompt,
+                num_images: p.n ?? 1,
+                ...(p.size ? { image_size: parseSize(p.size, "fal") } : {}),
+            }, "images");
+        },
+    });
+    rl.registerAction("image.edit", {
+        access: "write",
+        description: `Edit a local image through fal (billed). Defaults to ${EDIT_MODEL}, using image_url. For fal-ai/nano-banana/edit set imageInputKey to image_urls. Returns images[].path.`,
+        inputSchema: editSchema,
+        async execute(input, ctx) {
+            const p = input;
+            const image = readImageInput(p.imagePath, "fal");
+            const key = p.imageInputKey ?? "image_url";
+            return generate(ctx, p, p.model ?? EDIT_MODEL, {
+                prompt: p.prompt,
+                [key]: key.endsWith("_urls") ? [image.dataUri] : image.dataUri,
+            }, "images");
+        },
+    });
+    rl.registerAction("video.create", {
+        access: "write",
+        description: `Generate a video through fal (billed). Defaults to ${VIDEO_MODEL}; override model and supply its parameters in extraInput. Returns videos[].path. For long jobs prefer queue.submit to avoid host execution deadlines.`,
+        inputSchema: videoSchema,
+        async execute(input, ctx) {
+            const p = input;
+            return generate(ctx, p, p.model ?? VIDEO_MODEL, { prompt: p.prompt }, "videos");
+        },
+    });
+    rl.registerAction("run", {
+        access: "write",
+        description: "Run a fal endpoint with its model-specific input (billed), and wait. Returns raw output plus downloaded files from common top-level image/video/audio/file fields. Automatic downloads accept HTTPS fal.media URLs or data URIs only, up to 512 MiB per file; JSON responses are limited to 32 MiB.",
+        inputSchema: runSchema,
+        async execute(input, ctx) {
+            const p = input;
+            const id = assertModelId(p.model);
+            const { output, requestId } = await runModel(ctx, id, p.input, p.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+            return savedResult(output, id, requestId, p.saveDir);
+        },
+    });
+    rl.registerAction("queue.submit", {
+        access: "write",
+        description: "Submit billed model work and return immediately. Save model and requestId, poll queue.status, then collect with queue.result. No client-side retries: repeating a submission can bill twice.",
+        inputSchema: submitSchema,
+        async execute(input, ctx) {
+            const p = input;
+            const id = assertModelId(p.model);
+            const receipt = await submit(ctx, id, p.input);
+            return {
+                model: id,
+                requestId: receipt.request_id,
+                queuePosition: receipt.queue_position,
+            };
+        },
+    });
+    rl.registerAction("queue.status", {
+        access: "read",
+        description: "Read queue state (IN_QUEUE, IN_PROGRESS, COMPLETED), optionally including logs. COMPLETED can indicate failure; inspect error/error_type or retrieve the result.",
+        inputSchema: statusInput,
+        async execute(input, ctx) {
+            const p = input;
+            return status(ctx, p.model, p.requestId, p.logs);
+        },
+    });
+    rl.registerAction("queue.result", {
+        access: "write",
+        description: "Retrieve completed output without re-running or re-billing. Writes common image/video/audio/file outputs to disk and returns files[].path. Download limits: HTTPS fal.media URLs or data URIs, 512 MiB per file, 60 seconds per file; JSON responses up to 32 MiB.",
+        inputSchema: resultInput,
+        async execute(input, ctx) {
+            const p = input;
+            const id = assertModelId(p.model);
+            return savedResult(await result(ctx, id, p.requestId), id, p.requestId, p.saveDir);
+        },
+    });
+    rl.registerAction("queue.cancel", {
+        access: "write",
+        description: "Request cancellation. Queued work is removed; in-progress work may still finish and incur charges. Fails if already completed or missing.",
+        inputSchema: cancelInput,
+        async execute(input, ctx) {
+            const p = input;
+            return cancel(ctx, p.model, p.requestId);
+        },
+    });
+}

package/dist/plugins/fal/src/shared.js

@@ -0,0 +1,303 @@
+import { setTimeout as sleep } from "node:timers/promises";
+import * as t from "typebox";
+import { Check } from "typebox/value";
+import { authedFetch } from "../../_shared/authedFetch.js";
+import { SEND_FILE_NOTE, writeMediaFile, } from "../../_shared/mediaFile.js";
+import { readBounded, readBoundedBytes, seg } from "../../_shared/provider.js";
+export const STRICT = { additionalProperties: false };
+export const DEFAULT_TIMEOUT_MS = 300_000;
+const QUEUE_BASE = "https://queue.fal.run";
+const MAX_DOWNLOAD_BYTES = 512 * 1024 * 1024;
+const MAX_JSON_BYTES = 32 * 1024 * 1024;
+const receiptSchema = t.Object({
+    request_id: t.String({ minLength: 1 }),
+    status_url: t.Optional(t.String()),
+    response_url: t.Optional(t.String()),
+    cancel_url: t.Optional(t.String()),
+    queue_position: t.Optional(t.Integer()),
+});
+const statusSchema = t.Object({
+    status: t.Union([
+        t.Literal("IN_QUEUE"),
+        t.Literal("IN_PROGRESS"),
+        t.Literal("COMPLETED"),
+    ]),
+    error: t.Optional(t.Union([t.String(), t.Null()])),
+    error_type: t.Optional(t.Union([t.String(), t.Null()])),
+});
+function object(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+export function assertModelId(model) {
+    const id = model.trim();
+    const parts = id.split("/");
+    const namespaced = parts[0] === "workflows" || parts[0] === "comfy";
+    if (!/^[\w-]+(\/[\w.-]+)+$/.test(id) ||
+        parts.some((part) => part === "." || part === "..") ||
+        (namespaced && parts.length < 3)) {
+        throw new Error("fal: invalid model id; expected owner/model[/variant] or workflows/owner/model[/variant]");
+    }
+    return id;
+}
+/** Queue operations address the application, excluding its inference sub-path. */
+function queueUrl(model, suffix = "") {
+    const id = assertModelId(model);
+    const parts = id.split("/");
+    const count = parts[0] === "workflows" || parts[0] === "comfy" ? 3 : 2;
+    return `${QUEUE_BASE}/${suffix ? parts.slice(0, count).join("/") : id}${suffix}`;
+}
+/** Keep validation field names and error types, without echoing model inputs. */
+export function explainFalError(status, body) {
+    const data = object(body) ? body : {};
+    const detail = data.detail;
+    const message = Array.isArray(detail)
+        ? detail
+            .filter(object)
+            .map((entry) => {
+            const field = Array.isArray(entry.loc) ? entry.loc.join(".") : "body";
+            return `${field}: ${String(entry.msg ?? "invalid")} [${String(entry.type ?? "error")}]`;
+        })
+            .join("; ")
+        : typeof detail === "string"
+            ? detail
+            : typeof data.status === "string"
+                ? data.status
+                : "request failed";
+    const type = typeof data.error_type === "string" ? ` [${data.error_type}]` : "";
+    return `fal ${status}: ${message.slice(0, 1000)}${type}`;
+}
+/** All credential-bearing calls use a fixed origin and refuse redirects. */
+async function request(ctx, url, init = {}) {
+    const key = ctx.connection.config.apiKey;
+    if (typeof key !== "string" || !key.trim())
+        throw new Error("Missing FAL_KEY. Create a key at https://fal.ai/dashboard/keys.");
+    const response = await authedFetch(url, {
+        ...init,
+        headers: {
+            authorization: `Key ${key.trim()}`,
+            accept: "application/json",
+            "content-type": "application/json",
+        },
+        signal: init.signal ?? AbortSignal.timeout(60_000),
+    });
+    const text = await readBounded(response, MAX_JSON_BYTES, "fal: response exceeds 32 MiB");
+    let body;
+    try {
+        body = JSON.parse(text);
+    }
+    catch {
+        throw new Error(`fal HTTP ${response.status}: non-JSON response`);
+    }
+    if (!response.ok)
+        throw new Error(explainFalError(response.status, body));
+    return body;
+}
+export async function submit(ctx, model, input, signal) {
+    // A failed POST can have been accepted, so submissions are never retried here.
+    const receipt = await request(ctx, queueUrl(model), {
+        method: "POST",
+        body: JSON.stringify(input),
+        signal,
+    });
+    if (!Check(receiptSchema, receipt))
+        throw new Error("fal: invalid submission receipt or no request id; do not resubmit automatically");
+    seg(receipt.request_id, "request id", "fal");
+    return receipt;
+}
+export async function status(ctx, model, requestId, logs = false, signal) {
+    const body = await request(ctx, queueUrl(model, `/requests/${seg(requestId, "request id", "fal")}/status${logs ? "?logs=1" : ""}`), { signal });
+    if (!Check(statusSchema, body))
+        throw new Error("fal: invalid queue status response");
+    return body;
+}
+export async function result(ctx, model, requestId, signal) {
+    const body = await request(ctx, queueUrl(model, `/requests/${seg(requestId, "request id", "fal")}`), { signal });
+    if (!object(body))
+        throw new Error("fal: expected an object result");
+    return body;
+}
+export async function cancel(ctx, model, requestId) {
+    const body = await request(ctx, queueUrl(model, `/requests/${seg(requestId, "request id", "fal")}/cancel`), { method: "PUT" });
+    if (!object(body) || body.status !== "CANCELLATION_REQUESTED")
+        throw new Error("fal: cancellation was not confirmed");
+    return body;
+}
+/** One deadline covers submission, polling, and result retrieval, including response bodies. */
+export async function runModel(ctx, model, input, timeoutMs) {
+    const signal = AbortSignal.timeout(timeoutMs);
+    let requestId;
+    try {
+        requestId = (await submit(ctx, model, input, signal)).request_id;
+        for (;;) {
+            signal.throwIfAborted();
+            const current = await status(ctx, model, requestId, false, signal);
+            if (current.status === "COMPLETED") {
+                if (current.error || current.error_type)
+                    throw new Error(`fal: ${current.error ?? "generation failed"}${current.error_type ? ` [${current.error_type}]` : ""}`);
+                return {
+                    output: await result(ctx, model, requestId, signal),
+                    requestId,
+                };
+            }
+            await sleep(1000, undefined, { signal });
+        }
+    }
+    catch (error) {
+        const message = signal.aborted
+            ? `fal: timed out after ${timeoutMs}ms`
+            : error instanceof Error
+                ? error.message
+                : String(error);
+        const recovery = requestId
+            ? `Collect with fal.queue.result using model ${model} and requestId ${requestId}; do not submit a replacement automatically.`
+            : "Submission may have been accepted; do not resubmit automatically.";
+        throw new Error(`${message}. ${recovery}`, { cause: error });
+    }
+}
+const MEDIA_FIELDS = {
+    images: ["images", "image"],
+    videos: ["video", "videos"],
+    other: ["audio", "audio_url", "file", "files"],
+};
+/** Only documented top-level media fields are downloaded; other output remains untouched. */
+export function collectMedia(output, kind) {
+    const found = [];
+    const seen = new Set();
+    const push = (value) => {
+        if (value === undefined || value === null)
+            return;
+        if (Array.isArray(value)) {
+            for (const entry of value)
+                push(entry);
+            return;
+        }
+        const url = typeof value === "string" ? value : object(value) ? value.url : undefined;
+        if (typeof url !== "string" || !url)
+            throw new Error("fal: malformed media reference");
+        if (seen.has(url))
+            return;
+        seen.add(url);
+        found.push({
+            url,
+            contentType: object(value) && typeof value.content_type === "string"
+                ? value.content_type
+                : undefined,
+        });
+    };
+    for (const field of kind
+        ? MEDIA_FIELDS[kind]
+        : Object.values(MEDIA_FIELDS).flat())
+        push(output[field]);
+    return found;
+}
+/** Restrict automatic downloads to fal's CDN, including every redirect target. */
+function mediaUrl(value) {
+    const url = new URL(value);
+    if (url.protocol !== "https:" ||
+        url.port ||
+        url.username ||
+        url.password ||
+        !(url.hostname === "fal.media" || url.hostname.endsWith(".fal.media"))) {
+        throw new Error("fal: automatic downloads require an HTTPS fal.media URL");
+    }
+    return url;
+}
+async function download(value) {
+    const signal = AbortSignal.timeout(60_000);
+    let url = value;
+    let response;
+    for (let hops = 0; hops <= 5; hops++) {
+        const inline = url.startsWith("data:");
+        if (!inline)
+            url = mediaUrl(url).href;
+        // No API credential is attached to either CDN or inline media reads.
+        response = await fetch(url, {
+            signal,
+            redirect: "manual",
+            credentials: "omit",
+        });
+        if (response.redirected) {
+            await response.body?.cancel();
+            throw new Error("fal: media fetch followed an unchecked redirect");
+        }
+        if (response.status < 300 || response.status >= 400)
+            break;
+        const location = response.headers.get("location");
+        await response.body?.cancel();
+        if (!location || hops === 5)
+            throw new Error("fal: invalid or excessive media redirects");
+        url = mediaUrl(new URL(location, url).href).href;
+    }
+    if (!response?.ok) {
+        await response?.body?.cancel();
+        throw new Error(`download failed (${response?.status})`);
+    }
+    if (Number(response.headers.get("content-length")) > MAX_DOWNLOAD_BYTES) {
+        await response.body?.cancel();
+        throw new Error("fal: artifact exceeds 512 MiB");
+    }
+    const bytes = await readBoundedBytes(response, MAX_DOWNLOAD_BYTES, "fal: artifact exceeds 512 MiB");
+    if (!bytes.byteLength)
+        throw new Error("fal: empty artifact body");
+    return {
+        bytes,
+        mime: (response.headers.get("content-type") ?? "application/octet-stream")
+            .split(";")[0]
+            .trim(),
+    };
+}
+/** Shared by generation and queue.result so file handling and partial-failure reporting agree. */
+export async function savedResult(output, model, requestId, saveDir, kind) {
+    const files = [];
+    const failures = [];
+    try {
+        const media = collectMedia(output, kind);
+        if (kind && !media.length)
+            throw new Error("fal: model returned no media");
+        for (const ref of media) {
+            try {
+                const { bytes, mime } = await download(ref.url);
+                files.push(writeMediaFile({
+                    bytes,
+                    mimeType: ref.contentType ?? mime,
+                    provider: "fal",
+                    index: files.length,
+                    saveDir,
+                }));
+            }
+            catch (error) {
+                failures.push({
+                    url: ref.url.startsWith("data:") ? "inline media" : ref.url,
+                    reason: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+        if (media.length && !files.length)
+            throw new Error(`fal: none could be downloaded: ${failures.map((f) => f.reason).join("; ")}`);
+    }
+    catch (error) {
+        throw new Error(`${error instanceof Error ? error.message : String(error)}. Retrieve the existing result with model ${model} and requestId ${requestId}; do not regenerate.`, { cause: error });
+    }
+    return {
+        provider: "fal",
+        model,
+        requestId,
+        ...(kind
+            ? { [kind]: files }
+            : { output, ...(files.length ? { files } : {}) }),
+        ...(files.length ? { note: SEND_FILE_NOTE } : {}),
+        ...(failures.length ? { failures } : {}),
+    };
+}
+export const timeoutSchema = t.Integer({
+    minimum: 1000,
+    maximum: 3_600_000,
+    default: DEFAULT_TIMEOUT_MS,
+    description: "Queue deadline in milliseconds (default 300000). Includes submission and result retrieval, not downloads (60 seconds per file). Does not cancel server work; use the requestId in the error to collect it.",
+});
+export const saveDirSchema = t.String({
+    description: "Existing directory for generated files; defaults to the OS temp directory.",
+});
+export const extraInputSchema = t.Record(t.String(), t.Unknown(), {
+    description: "Model-specific fields, overriding action defaults. See https://fal.ai/models/<model>/api. Media downloads support HTTPS fal.media URLs and data URIs, up to 512 MiB each; JSON responses are limited to 32 MiB.",
+});

package/dist/plugins/googleImage/src/index.js

@@ -18,7 +18,7 @@
  * inline next to the instruction and writes the edited result to disk.
  */
 import * as t from "typebox";
-import { readImageInput, SEND_FILE_NOTE, writeImageFile, } from "../../_shared/imageFile.js";
+import { readImageInput, SEND_FILE_NOTE, writeImageFile, } from "../../_shared/mediaFile.js";
 const BASE = "https://generativelanguage.googleapis.com/v1beta/models";
 /** Write every inline image part of a Gemini response to disk. */
 function saveInlineImages(data, saveDir) {

package/dist/plugins/openai/src/index.js

@@ -15,7 +15,7 @@
  *   const { images } = await openai.image.create({ prompt: "a red bicycle on snow" })
  *   // images[0].path -> "/tmp/openai-image-….png"
  */
-import { readImageInput, SEND_FILE_NOTE, writeImageFile, } from "../../_shared/imageFile.js";
+import { readImageInput, SEND_FILE_NOTE, writeImageFile, } from "../../_shared/mediaFile.js";
 const ENDPOINT = "https://api.openai.com/v1/images/generations";
 const EDIT_ENDPOINT = "https://api.openai.com/v1/images/edits";
 /**

package/dist/plugins/recraft/src/index.js

@@ -13,7 +13,7 @@
  * legacy `style` knob — pass `styleId` against your own custom
  * style if you've set one up.
  */
-import { readImageInput, SEND_FILE_NOTE, writeImageFile } from "../../_shared/imageFile.js";
+import { readImageInput, SEND_FILE_NOTE, writeImageFile } from "../../_shared/mediaFile.js";
 const ENDPOINT = "https://external.api.recraft.ai/v1/images/generations";
 const EDIT_ENDPOINT = "https://external.api.recraft.ai/v1/images/imageToImage";
 export default function recraft(rl) {

package/dist/plugins/replicate/src/index.js

@@ -15,11 +15,10 @@
  * Predictions are created with `Prefer: wait` so simple jobs return
  * synchronously; anything still processing is polled until terminal
  * or until `timeoutMs` elapses (default: 5 minutes). Output URLs are
- * downloaded and base64-encoded so callers don't have to fetch them
- * separately.
+ * downloaded to local files so callers can deliver them directly.
  */
 import { Buffer } from "node:buffer";
-import { readImageInput, SEND_FILE_NOTE, writeImageFile } from "../../_shared/imageFile.js";
+import { readImageInput, SEND_FILE_NOTE, writeMediaFile } from "../../_shared/mediaFile.js";
 import { parseSize } from "../../_shared/parseSize.js";
 const POLL_INTERVAL_MS = 2_000;
 const DEFAULT_TIMEOUT_MS = 5 * 60 * 1000;
@@ -78,7 +77,7 @@ async function runPrediction(opts) {
         throw new Error(`Replicate generation ${prediction.status}: ${stringifyError(prediction.error)}`);
     }
     // Output is either a single URL or an array of them. Download
-    // each and base64-encode so the caller gets bytes back, not
+    // each to disk so the caller gets file paths, not
     // pre-signed URLs that expire. Track per-URL failures and
     // surface them: silent partial success would let an agent
     // think it got 3 images when one 404'd.
@@ -107,8 +106,8 @@ async function runPrediction(opts) {
         const contentType = (imgRes.headers.get("content-type") ?? "image/webp")
             .split(";")[0]
             .trim();
-        images.push(writeImageFile({
-            base64: buf.toString("base64"),
+        images.push(writeMediaFile({
+            bytes: buf,
             mimeType: contentType,
             provider: "replicate",
             index: images.length,