@marlinjai/studio-mcp 0.1.0

package/dist/index.js

@@ -0,0 +1,3352 @@
+// src/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+// src/errors.ts
+var StudioApiError = class extends Error {
+  status;
+  method;
+  path;
+  body;
+  constructor(opts) {
+    super(`${opts.method} ${opts.path} -> ${opts.status}: ${opts.message}`);
+    this.name = "StudioApiError";
+    this.status = opts.status;
+    this.method = opts.method;
+    this.path = opts.path;
+    this.body = opts.body;
+  }
+};
+var PollTimeoutError = class extends Error {
+  lastState;
+  constructor(what, timeoutMs, lastState) {
+    super(
+      `Timed out after ${Math.round(timeoutMs / 1e3)}s waiting for ${what}. The work is still running server-side; poll it again with the returned id.`
+    );
+    this.name = "PollTimeoutError";
+    this.lastState = lastState;
+  }
+};
+var ToolInputError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ToolInputError";
+  }
+};
+function redactSecret(text, secret) {
+  if (!secret || secret.length === 0) return text;
+  return text.split(secret).join("[REDACTED]");
+}
+function apiMessageFromBody(body, fallback) {
+  if (body && typeof body === "object") {
+    const o = body;
+    if (typeof o.error === "string" && o.error.length > 0) {
+      const detail = typeof o.message === "string" ? o.message : "";
+      const adds = detail.length > 0 && !o.error.includes(detail) && !detail.includes(o.error);
+      const headline = adds ? `${o.error}: ${detail}` : o.error;
+      const quota = quotaDetail(o);
+      return quota ? `${headline} (${quota})` : headline;
+    }
+    const code = typeof o.code === "string" && o.code.length > 0 ? o.code : null;
+    if (typeof o.message === "string" && o.message.length > 0) return code ? `${code}: ${o.message}` : o.message;
+    if (code) {
+      const issues = Array.isArray(o.issues) ? o.issues.map(formatIssue).filter((s) => s !== null) : [];
+      return issues.length > 0 ? `${code}: ${issues.join("; ")}` : code;
+    }
+  }
+  if (typeof body === "string" && body.trim().length > 0) return body.trim().slice(0, 500);
+  return fallback;
+}
+function quotaDetail(body) {
+  if (typeof body.capUsd === "number" && typeof body.usedUsd === "number") {
+    const resetsAt = typeof body.resetsAt === "string" ? `, resets ${body.resetsAt}` : "";
+    return `cap $${body.capUsd.toFixed(2)}, used $${body.usedUsd.toFixed(2)}${resetsAt}`;
+  }
+  if (typeof body.rpm === "number") {
+    return `limit ${body.rpm} req/min, see the response's Retry-After header for when to retry`;
+  }
+  return null;
+}
+function formatIssue(issue) {
+  if (!issue || typeof issue !== "object") return null;
+  const o = issue;
+  if (typeof o.message !== "string") return null;
+  const path = Array.isArray(o.path) ? o.path.map(String).join(".") : "";
+  return `${path || "body"}: ${o.message}`;
+}
+function errorMessage(err) {
+  if (err instanceof Error) return err.message;
+  return String(err);
+}
+
+// src/client.ts
+var StudioClient = class {
+  baseUrl;
+  // Native private fields: not enumerable, never serialized, unreachable from outside.
+  #apiKey;
+  #fetchImpl;
+  #requestTimeoutMs;
+  #userAgent;
+  constructor(config, opts = {}) {
+    this.baseUrl = config.baseUrl;
+    this.#apiKey = config.apiKey;
+    this.#fetchImpl = opts.fetch ?? ((input, init) => fetch(input, init));
+    this.#requestTimeoutMs = opts.requestTimeoutMs ?? 6e4;
+    this.#userAgent = opts.userAgent ?? "studio-mcp";
+  }
+  /** Strip the bearer token from any string before it can reach a caller. */
+  redact(text) {
+    return redactSecret(text, this.#apiKey);
+  }
+  // ── Projects ──
+  listProjects() {
+    return this.json("GET", "/api/v1/projects");
+  }
+  // ── Generation jobs ──
+  generate(body) {
+    return this.json("POST", "/api/generate", { json: body });
+  }
+  getJob(jobId) {
+    return this.json("GET", `/api/v1/jobs/${encodeURIComponent(jobId)}`);
+  }
+  // ── Characters ──
+  listCharacters() {
+    return this.json("GET", "/api/characters");
+  }
+  getCharacter(slug2) {
+    return this.json("GET", `/api/characters/${encodeURIComponent(slug2)}`);
+  }
+  createCharacter(body) {
+    return this.json("POST", "/api/characters", { json: body });
+  }
+  uploadCharacterReference(slug2, input) {
+    const form = new FormData();
+    form.append("file", toFile(input.file));
+    form.append("category", input.category);
+    if (input.label) form.append("label", input.label);
+    return this.json("POST", `/api/characters/${encodeURIComponent(slug2)}/references/upload`, { form });
+  }
+  // ── Brands ──
+  createBrand(body) {
+    return this.json("POST", "/api/brands", { json: body });
+  }
+  uploadBrandReference(slug2, input) {
+    const form = new FormData();
+    form.append("file", toFile(input.file));
+    form.append("category", input.category ?? "general");
+    if (input.label) form.append("name", input.label);
+    if (input.tags && input.tags.length > 0) form.append("tags", input.tags.join(","));
+    if (input.score !== void 0) form.append("score", String(input.score));
+    return this.json("POST", `/api/brands/${encodeURIComponent(slug2)}/library/upload`, { form });
+  }
+  // ── Workflows ──
+  runWorkflow(body) {
+    return this.json("POST", "/api/v1/workflows/run", { json: body });
+  }
+  getRun(runId) {
+    return this.json("GET", `/api/v1/workflows/runs/${encodeURIComponent(runId)}`);
+  }
+  /** Submit a human decision on a parked judge node (P3 J2). Approving
+   * resumes the run from that node; rejecting fails it and stops the branch. */
+  decideJudgeNode(runId, nodeId, body) {
+    return this.json(
+      "POST",
+      `/api/v1/workflows/runs/${encodeURIComponent(runId)}/node/${encodeURIComponent(nodeId)}/decision`,
+      { json: body }
+    );
+  }
+  getRunNodeUrl(runId, nodeId) {
+    return this.json(
+      "GET",
+      `/api/v1/workflows/runs/${encodeURIComponent(runId)}/node/${encodeURIComponent(nodeId)}/url`
+    );
+  }
+  /** S9: a rendered diagram of a saved workflow's document, so an agent can
+   * see the graph it just built. */
+  getWorkflowScreenshot(savedId2) {
+    return this.json("GET", `/api/v1/workflows/${encodeURIComponent(savedId2)}/screenshot`);
+  }
+  // ── Recipes (S10): published workflow + closed post-run effect list ──
+  publishWorkflow(savedId2, body) {
+    return this.json("POST", `/api/v1/workflows/${encodeURIComponent(savedId2)}/publish`, { json: body });
+  }
+  unpublishWorkflow(savedId2) {
+    return this.json("DELETE", `/api/v1/workflows/${encodeURIComponent(savedId2)}/publish`);
+  }
+  listPublished() {
+    return this.json("GET", "/api/v1/recipes");
+  }
+  describePublished(slug2) {
+    return this.json("GET", `/api/v1/recipes/${encodeURIComponent(slug2)}`);
+  }
+  runPublished(slug2, body) {
+    return this.json("POST", `/api/v1/recipes/${encodeURIComponent(slug2)}/run`, { json: body });
+  }
+  saveWorkflow(body) {
+    return this.json("POST", "/api/v1/workflows", { json: body });
+  }
+  // ── Workflow command model: describe, get, create, apply, validate ──
+  describeNodeTypes() {
+    return this.json("GET", "/api/v1/node-types");
+  }
+  /** `savedId` carries a `saved:` prefix; the colon is URL-encoded. */
+  getWorkflowDocument(savedId2) {
+    return this.json("GET", `/api/v1/workflows/${encodeURIComponent(savedId2)}`);
+  }
+  /** Create a document by applying `ops` to an empty one (the same code path as apply). */
+  createWorkflow(body) {
+    return this.json("POST", "/api/v1/workflows", { json: body });
+  }
+  /**
+   * Apply a patch atomically on top of `patch.baseRevision`. 409 on a stale
+   * base; 422 when the workflow is not editable, imports with loss and has not
+   * been acknowledged, or the idempotency key belongs to a different patch.
+   */
+  applyWorkflowPatch(savedId2, patch) {
+    return this.json("PATCH", `/api/v1/workflows/${encodeURIComponent(savedId2)}`, { json: patch });
+  }
+  /** Stateless dry-run of ops and run params against a document. No side effects. */
+  validateWorkflow(body) {
+    return this.json("POST", "/api/v1/workflows/validate", { json: body });
+  }
+  // ── Spend ──
+  getSpend(tzOffsetMinutes) {
+    const qs = tzOffsetMinutes === void 0 ? "" : `?tz=${encodeURIComponent(String(tzOffsetMinutes))}`;
+    return this.json("GET", `/api/spend${qs}`);
+  }
+  /**
+   * The metering read model (docs/plans/2026-08-21-studio-api-keys-and-quotas.md,
+   * scope item 2): this key's month-to-date usage against its tenant's plan
+   * (cap, rpm), broken down by model.
+   */
+  getUsage() {
+    return this.json("GET", "/api/v1/usage");
+  }
+  /**
+   * Download a (signed) asset URL to bytes. Goes through the same fetch so tests
+   * can intercept it; no auth header is sent to a foreign host.
+   */
+  async downloadUrl(url) {
+    const res = await this.#fetchImpl(url, {
+      method: "GET",
+      headers: { "user-agent": this.#userAgent },
+      signal: AbortSignal.timeout(this.#requestTimeoutMs * 4)
+    });
+    if (!res.ok) {
+      throw new StudioApiError({
+        status: res.status,
+        method: "GET",
+        path: this.redact(stripQuery(url)),
+        message: `download failed (${res.status})`
+      });
+    }
+    const data = await res.blob();
+    return { data, filename: filenameFromUrl(url, data.type) };
+  }
+  // ── Core request ──
+  async json(method, path, opts = {}) {
+    const headers = {
+      authorization: `Bearer ${this.#apiKey}`,
+      accept: "application/json",
+      "user-agent": this.#userAgent
+    };
+    let body;
+    if (opts.form) {
+      body = opts.form;
+    } else if (opts.json !== void 0) {
+      headers["content-type"] = "application/json";
+      body = JSON.stringify(opts.json);
+    }
+    const timeout = opts.form ? this.#requestTimeoutMs * 4 : this.#requestTimeoutMs;
+    let res;
+    try {
+      res = await this.#fetchImpl(`${this.baseUrl}${path}`, {
+        method,
+        headers,
+        body,
+        signal: AbortSignal.timeout(timeout)
+      });
+    } catch (err) {
+      const reason = err instanceof Error ? err.message : String(err);
+      throw new StudioApiError({
+        status: 0,
+        method,
+        path,
+        message: this.redact(`network error: ${reason}`)
+      });
+    }
+    const text = await res.text();
+    let parsed = text;
+    if (text.length > 0) {
+      try {
+        parsed = JSON.parse(text);
+      } catch {
+        parsed = text;
+      }
+    }
+    if (!res.ok) {
+      const fallback = res.status === 401 || res.status === 403 ? "unauthorized: the API key was rejected" : `HTTP ${res.status}`;
+      throw new StudioApiError({
+        status: res.status,
+        method,
+        path,
+        message: this.redact(apiMessageFromBody(parsed, fallback)),
+        body: typeof parsed === "string" ? this.redact(parsed) : parsed
+      });
+    }
+    if (typeof parsed === "string") {
+      throw new StudioApiError({
+        status: res.status,
+        method,
+        path,
+        message: this.redact(`expected JSON, got: ${parsed.slice(0, 200)}`)
+      });
+    }
+    return parsed;
+  }
+};
+function toFile(file) {
+  if (file.data instanceof File && file.data.name === file.filename) return file.data;
+  return new File([file.data], file.filename, { type: file.data.type });
+}
+function stripQuery(url) {
+  const i = url.indexOf("?");
+  return i === -1 ? url : url.slice(0, i);
+}
+function filenameFromUrl(url, mime) {
+  let base = "asset";
+  try {
+    const p = new URL(url).pathname;
+    const last = p.split("/").filter(Boolean).pop();
+    if (last) base = last;
+  } catch {
+  }
+  if (/\.[a-z0-9]{2,5}$/i.test(base)) return base;
+  const ext = extensionForMime(mime);
+  return ext ? `${base}.${ext}` : base;
+}
+function extensionForMime(mime) {
+  const m = (mime || "").toLowerCase().split(";")[0].trim();
+  switch (m) {
+    case "image/png":
+      return "png";
+    case "image/jpeg":
+      return "jpg";
+    case "image/webp":
+      return "webp";
+    case "image/gif":
+      return "gif";
+    case "video/mp4":
+      return "mp4";
+    default:
+      return null;
+  }
+}
+function mimeForFilename(name) {
+  const ext = name.toLowerCase().split(".").pop() ?? "";
+  switch (ext) {
+    case "png":
+      return "image/png";
+    case "jpg":
+    case "jpeg":
+      return "image/jpeg";
+    case "webp":
+      return "image/webp";
+    case "gif":
+      return "image/gif";
+    case "avif":
+      return "image/avif";
+    case "mp4":
+      return "video/mp4";
+    default:
+      return "application/octet-stream";
+  }
+}
+
+// src/config.ts
+var DEFAULT_BASE_URL = "https://studio.lumitra.co";
+var ConfigError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ConfigError";
+  }
+};
+var PLACEHOLDER = /^\s*\$\{[^}]*\}\s*$/;
+function isUnexpandedPlaceholder(value) {
+  return typeof value === "string" && PLACEHOLDER.test(value);
+}
+function readEnvVar(name, env) {
+  const candidates = env === process.env ? [env[name]] : [env[name], process.env[name]];
+  for (const raw of candidates) {
+    if (typeof raw !== "string") continue;
+    const v = raw.trim();
+    if (v.length === 0 || isUnexpandedPlaceholder(v)) continue;
+    return v;
+  }
+  return void 0;
+}
+function resolveConfig(env = process.env) {
+  const rawBase = readEnvVar("LUMITRA_STUDIO_BASE_URL", env) ?? DEFAULT_BASE_URL;
+  let baseUrl;
+  try {
+    const u = new URL(rawBase);
+    if (u.protocol !== "http:" && u.protocol !== "https:") throw new Error("bad protocol");
+    baseUrl = u.origin + u.pathname.replace(/\/+$/, "");
+  } catch {
+    throw new ConfigError(
+      `LUMITRA_STUDIO_BASE_URL is not a valid http(s) URL (got ${JSON.stringify(rawBase)})`
+    );
+  }
+  const apiKey = readEnvVar("LUMITRA_STUDIO_API_KEY", env) ?? readEnvVar("LUMITRA_STUDIO_SERVICE_TOKEN", env);
+  if (!apiKey) {
+    throw new ConfigError(
+      'Missing API key: set LUMITRA_STUDIO_API_KEY (or the legacy LUMITRA_STUDIO_SERVICE_TOKEN) to a Lumitra Studio bearer token. An unexpanded "${...}" placeholder counts as unset.'
+    );
+  }
+  return { baseUrl, apiKey };
+}
+
+// src/tools.ts
+import { z as z8 } from "zod";
+
+// ../lumitra-core/dist/workflow/index.js
+import { z as z2 } from "zod";
+import { z } from "zod";
+import { z as z3 } from "zod";
+import { z as z4 } from "zod";
+import { z as z5 } from "zod";
+var MODEL_TASKS = [
+  "text-to-image",
+  "image-to-image",
+  "image-edit",
+  "virtual-try-on",
+  "text-to-video",
+  "image-to-video",
+  "video-to-video",
+  // A finishing pass over a DRAFT video: the upstream draft's cache bundle is
+  // the only input, and the output is the full-quality render of the same take.
+  "video-enhance",
+  "text-to-3d",
+  "image-to-3d",
+  "multiview-to-3d",
+  "remesh",
+  "texture",
+  "text-to-audio",
+  "text-to-speech",
+  "speech-to-text",
+  "speech-to-speech",
+  "image-to-text",
+  "image-to-json",
+  // A human decision gate over candidate images (P3 J1). Still a model task,
+  // not a new node kind: WorkflowNode already requires task + model, and the
+  // ranking call underneath is the same image-to-json vision model
+  // shotReview.ts uses. The task, ports and wire legality land in J1; the
+  // pausing execution state that actually runs a judge node is J2.
+  "judge",
+  "text-generation",
+  "upscale",
+  "background-remove",
+  "segmentation"
+];
+var PORT_TYPES = ["text", "image", "video", "mask", "mesh3d", "audio", "json"];
+var INPUT_PORT_TYPES = PORT_TYPES.filter((p) => p !== "mask");
+var TASK_PORTS = {
+  // GENERATE: born from text (or a mesh prompt), no upstream asset input.
+  "text-to-image": { inputs: ["text"], output: "image" },
+  "text-to-video": { inputs: ["text"], output: "video" },
+  "text-to-3d": { inputs: ["text"], output: "mesh3d" },
+  // TRANSFORM: consume an upstream asset, emit another.
+  "image-to-image": { inputs: ["image", "text"], output: "image" },
+  "image-edit": { inputs: ["image", "text", "mask"], output: "image" },
+  // Two image inputs (garment + person); the port type set is coarse (both are
+  // 'image'), the two-image contract lives in the fal adapter, not the ports.
+  "virtual-try-on": { inputs: ["image"], output: "image" },
+  "image-to-video": { inputs: ["image"], output: "video" },
+  // Video-to-video (character replace): a source video plus ONE reference image
+  // (the person to swap in). The two-input contract lives in the fal adapter.
+  "video-to-video": { inputs: ["video", "image"], output: "video" },
+  // Video-enhance: the upstream DRAFT video's cache bundle is the whole input.
+  // The wire is typed 'video' so it only accepts a video node; whether that
+  // node actually produced a draft cache is checked at run time, loudly.
+  "video-enhance": { inputs: ["video"], output: "video" },
+  "image-to-3d": { inputs: ["image"], output: "mesh3d" },
+  "multiview-to-3d": { inputs: ["image"], output: "mesh3d" },
+  "remesh": { inputs: ["mesh3d"], output: "mesh3d" },
+  "texture": { inputs: ["mesh3d"], output: "mesh3d" },
+  // AUDIO + VOICE.
+  "text-to-audio": { inputs: ["text"], output: "audio" },
+  "text-to-speech": { inputs: ["text"], output: "audio" },
+  "speech-to-text": { inputs: ["audio"], output: "text" },
+  "speech-to-speech": { inputs: ["audio"], output: "audio" },
+  // VISION + LANGUAGE.
+  "image-to-text": { inputs: ["image", "text"], output: "text" },
+  "image-to-json": { inputs: ["image", "text"], output: "json" },
+  // Judge (P3 J1): one candidate wire in (the several results of ONE
+  // upstream node-run, not fan-in), the approved candidate out. Both sides
+  // are typed 'image' so an approved candidate can feed straight into any
+  // node that already accepts an image wire (e.g. image-to-video), with zero
+  // change to the downstream port rules.
+  "judge": { inputs: ["image"], output: "image" },
+  "text-generation": { inputs: ["text"], output: "text" },
+  // ENHANCE: a utility pass over an asset.
+  "upscale": { inputs: ["image"], output: "image" },
+  "background-remove": { inputs: ["image"], output: "image" },
+  "segmentation": { inputs: ["image"], output: "mask" }
+};
+function taskPorts(task) {
+  return TASK_PORTS[task];
+}
+var JsonValueSchema = z.lazy(
+  () => z.union([
+    z.string(),
+    z.number().finite(),
+    z.boolean(),
+    z.null(),
+    z.array(JsonValueSchema),
+    z.record(z.string(), JsonValueSchema)
+  ])
+);
+var JsonNonNullValueSchema = z.union([
+  z.string(),
+  z.number().finite(),
+  z.boolean(),
+  z.array(JsonValueSchema),
+  z.record(z.string(), JsonValueSchema)
+]);
+function toJsonValue(value, what = "value") {
+  const r = JsonValueSchema.safeParse(value);
+  if (!r.success) throw new TypeError(`${what} is not a JSON value: ${r.error.issues[0]?.message ?? "invalid"}`);
+  return r.data;
+}
+var WORKFLOW_SCHEMA_VERSION = 1;
+var SchemaVersionSchema = z2.object({
+  schema: z2.number().int().positive()
+});
+var LiteralBindingSchema = z2.object({
+  kind: z2.literal("literal"),
+  value: JsonValueSchema
+});
+var ParamBindingSchema = z2.object({
+  kind: z2.literal("param"),
+  name: z2.string().min(1),
+  // Same ensure-array wrapping as a ref: a single-value input (one image url)
+  // wired into an array port (`inputImages`) resolves to a one-element array.
+  wrap: z2.literal("array").optional()
+});
+var RefBindingSchema = z2.object({
+  kind: z2.literal("ref"),
+  node: z2.string().min(1),
+  path: z2.string().min(1),
+  // Ensure-array wrapping: some job-input ports (e.g. generate_image's
+  // `inputImages`) take a string ARRAY while upstream outputs expose single
+  // values (`url`). `wrap: "array"` resolves the ref then wraps a non-array
+  // value in a one-element array (an existing array passes through), closing
+  // the "no array-of-refs" gap without widening the binding grammar itself.
+  wrap: z2.literal("array").optional()
+});
+var BindingSchema = z2.discriminatedUnion("kind", [
+  LiteralBindingSchema,
+  ParamBindingSchema,
+  RefBindingSchema
+]);
+var WorkflowTaskSchema = z2.enum(MODEL_TASKS);
+var RetryPolicySchema = z2.object({
+  maxAttempts: z2.number().int().positive(),
+  backoffMs: z2.number().int().nonnegative()
+});
+var WorkflowNodeSchema = z2.object({
+  id: z2.string().min(1),
+  task: WorkflowTaskSchema,
+  model: z2.string().min(1),
+  inputs: z2.record(z2.string(), BindingSchema).default({}),
+  retry: RetryPolicySchema.optional()
+});
+var WorkflowParamSpecSchema = z2.object({
+  name: z2.string().min(1),
+  /** The JSON-level type of the value a caller supplies. */
+  type: z2.enum(["string", "number", "boolean", "json"]),
+  required: z2.boolean().default(true),
+  label: z2.string().optional(),
+  description: z2.string().optional(),
+  /** The port type the param feeds (what an input NODE declares): an agent
+   * needs to know that `still` is an image url, not just "a string". Absent on
+   * definitions authored before the workflow command model. */
+  inputType: z2.enum(INPUT_PORT_TYPES).optional(),
+  /** `many`: the caller supplies a LIST of `inputType` values (several
+   * reference images in one param). Absent means one value. */
+  cardinality: z2.enum(["one", "many"]).optional(),
+  /** Used when a run omits the param. Never null: absent means no default. */
+  default: JsonNonNullValueSchema.optional()
+});
+var WorkflowDefinitionSchema = z2.object({
+  version: SchemaVersionSchema.default({ schema: WORKFLOW_SCHEMA_VERSION }),
+  id: z2.string().min(1),
+  label: z2.string().optional(),
+  params: z2.array(WorkflowParamSpecSchema).default([]),
+  nodes: z2.array(WorkflowNodeSchema).min(1)
+});
+function kahnOrder(ids, edges) {
+  const indegree = /* @__PURE__ */ new Map();
+  const adj = /* @__PURE__ */ new Map();
+  for (const id of ids) {
+    indegree.set(id, 0);
+    adj.set(id, []);
+  }
+  for (const [from, to] of edges) {
+    const list = adj.get(from);
+    if (!list || !indegree.has(to)) continue;
+    list.push(to);
+    indegree.set(to, indegree.get(to) + 1);
+  }
+  const queue = [];
+  for (const id of ids) if (indegree.get(id) === 0) queue.push(id);
+  const order = [];
+  for (let head = 0; head < queue.length; head++) {
+    const id = queue[head];
+    order.push(id);
+    for (const next of adj.get(id) ?? []) {
+      const d = indegree.get(next) - 1;
+      indegree.set(next, d);
+      if (d === 0) queue.push(next);
+    }
+  }
+  return order.length === ids.length ? order : null;
+}
+var DOCUMENT_SCHEMA_VERSION = 1;
+var RESERVED_KEYS = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
+var notReserved = (s) => !RESERVED_KEYS.has(s);
+var IdSchema = z3.string().regex(/^[A-Za-z0-9_][A-Za-z0-9_.:-]{0,127}$/, "id must be 1 to 128 chars of letters, digits, _ . : -").refine(notReserved, "reserved id");
+var KeySchema = z3.string().regex(/^[A-Za-z_][A-Za-z0-9_.-]{0,63}$/, "key must be 1 to 64 chars of letters, digits, _ . -").refine(notReserved, "reserved key");
+var InputNameSchema = z3.string().regex(/^[A-Za-z_][A-Za-z0-9_-]{0,63}$/, "input name must be 1 to 64 chars of letters, digits, _ -").refine(notReserved, "reserved name");
+var LabelSchema = z3.string().max(200);
+var DescriptionSchema = z3.string().max(2e3);
+var PromptTextSchema = z3.string().max(2e4);
+var ModelIdSchema = z3.string().max(256);
+var UrlSchema = z3.string().max(4096);
+var AssetIdSchema = z3.string().max(128);
+var PortTypeSchema = z3.enum(PORT_TYPES);
+var InputTypeSchema = z3.enum(INPUT_PORT_TYPES);
+var PositionSchema = z3.object({ x: z3.number().finite(), y: z3.number().finite() });
+var TaskNodeSchema = z3.object({
+  id: IdSchema,
+  kind: z3.literal("task"),
+  task: z3.enum(MODEL_TASKS),
+  /** Catalog model id. Empty is a legal EDITING state (the picker is blank);
+   * the projection refuses to run it. */
+  model: ModelIdSchema.default(""),
+  /** The inline literal prompt. A wired text edge (prompt-source or text input)
+   * replaces it at projection time. */
+  prompt: PromptTextSchema.default(""),
+  /** Per-generation modality knobs, keyed in SETTINGS space. Entry-granular ops
+   * (`setNodeSetting`) so two actors editing different knobs commute. */
+  settings: z3.record(KeySchema, JsonNonNullValueSchema).default({}),
+  /** LITERAL inputs the canvas does not reconstruct from prompt/settings/wires
+   * (a campaign shot's baked reference stack and lineage literals). Literals
+   * only: a `ref` or `param` here would be a dependency the DAG check cannot
+   * see. Preserved across projections; a wire over a baked key wins explicitly. */
+  bakedInputs: z3.record(KeySchema, LiteralBindingSchema).default({}),
+  /** The generation id that feeds downstream. Absent = latest (D4). */
+  activeGeneration: IdSchema.optional(),
+  label: LabelSchema.optional()
+});
+var PromptSourceNodeSchema = z3.object({
+  id: IdSchema,
+  kind: z3.literal("prompt-source"),
+  text: PromptTextSchema.default(""),
+  label: LabelSchema.optional()
+});
+var ImageSourceNodeSchema = z3.object({
+  id: IdSchema,
+  kind: z3.literal("image-source"),
+  /** The uploaded url. Empty or `data:` means still uploading: a legal editing
+   * state, refused at projection time. */
+  imageUrl: UrlSchema.default(""),
+  /** The Storage Brain asset id, when known (E18: every image input resolves to
+   * an asset id). */
+  assetId: AssetIdSchema.optional(),
+  label: LabelSchema.optional()
+});
+var InputNodeSchema = z3.object({
+  id: IdSchema,
+  kind: z3.literal("input"),
+  name: InputNameSchema,
+  type: InputTypeSchema,
+  required: z3.boolean().default(true),
+  /** `many` declares a LIST of values of `type` (several reference images in
+   * one param). Absent means one value. A list input can only wire into a
+   * port whose binding is an array (`inputImages`); `validateDocument` checks. */
+  cardinality: z3.enum(["one", "many"]).optional(),
+  /** Used when a run omits the input. Never null: absent means no default. */
+  default: JsonNonNullValueSchema.optional(),
+  label: LabelSchema.optional(),
+  description: DescriptionSchema.optional()
+});
+var DocNodeSchema = z3.discriminatedUnion("kind", [
+  TaskNodeSchema,
+  PromptSourceNodeSchema,
+  ImageSourceNodeSchema,
+  InputNodeSchema
+]);
+var DocEdgeSchema = z3.object({
+  source: IdSchema,
+  target: IdSchema,
+  port: PortTypeSchema
+});
+var DocGroupSchema = z3.object({
+  id: IdSchema,
+  label: LabelSchema.optional(),
+  nodeIds: z3.array(IdSchema).min(1)
+});
+var WorkflowDocumentSchema = z3.object({
+  schema: z3.number().int().positive(),
+  id: IdSchema,
+  label: LabelSchema.default(""),
+  nodes: z3.array(DocNodeSchema).max(2e3),
+  edges: z3.array(DocEdgeSchema).max(8e3),
+  layout: z3.record(IdSchema, PositionSchema).default({}),
+  groups: z3.array(DocGroupSchema).max(500).default([])
+});
+function edgeKey(e) {
+  return JSON.stringify([e.source, e.target, e.port]);
+}
+function slotKey(target, port) {
+  return JSON.stringify([target, port]);
+}
+var MODEL_CATALOG = [
+  // ── 3D AI Studio: 3D generation ────────────────────────────────────────
+  {
+    id: "studio3d/tripo-3-1-text-to-3d",
+    provider: "studio3d",
+    modality: "3d",
+    task: "text-to-3d",
+    label: "Tripo 3.1 (text-to-3D)",
+    description: "Cheapest text-to-3D path on 3D AI Studio. Good for fast iteration.",
+    cost: { credits: 20 },
+    capabilities: { supportsTextures: true, supportsPbr: true },
+    isDefault: true
+  },
+  {
+    id: "studio3d/tripo-3-1-image-to-3d",
+    provider: "studio3d",
+    modality: "3d",
+    task: "image-to-3d",
+    label: "Tripo 3.1 (image-to-3D)",
+    cost: { credits: 40 },
+    capabilities: { needsImageInput: true, supportsTextures: true, supportsPbr: true }
+  },
+  {
+    id: "studio3d/hunyuan-3-1-rapid",
+    provider: "studio3d",
+    modality: "3d",
+    task: "text-to-3d",
+    label: "Hunyuan 3.1 Rapid",
+    description: "Tencent Hunyuan3D, rapid edition. Mid-quality, mid-cost.",
+    cost: { credits: 35 },
+    capabilities: { supportsTextures: true, supportsPbr: true }
+  },
+  {
+    id: "studio3d/hunyuan-3-1-pro",
+    provider: "studio3d",
+    modality: "3d",
+    task: "text-to-3d",
+    label: "Hunyuan 3.1 Pro",
+    description: "Tencent Hunyuan3D, pro edition. High quality, ~3x cost.",
+    cost: { credits: 60 },
+    capabilities: { supportsTextures: true, supportsPbr: true, maxOutputDetail: "1.5M polys" }
+  },
+  {
+    id: "studio3d/trellis-2",
+    provider: "studio3d",
+    modality: "3d",
+    task: "image-to-3d",
+    label: "Trellis 2",
+    description: "Microsoft Trellis 2. Best image-to-3D fidelity. Image input only.",
+    cost: { credits: 30 },
+    capabilities: { needsImageInput: true, supportsTextures: true, supportsPbr: true, maxOutputDetail: "1024" },
+    isDefault: true
+  },
+  // ── 3D AI Studio: post-processing ──────────────────────────────────────
+  {
+    id: "studio3d/tripo-remesh",
+    provider: "studio3d",
+    modality: "3d",
+    task: "remesh",
+    label: "Tripo Remesh",
+    description: "Convert + remesh: target polycount, quad topology, multiple output formats.",
+    cost: { credits: 10 },
+    isDefault: true
+  },
+  {
+    id: "studio3d/tripo-texture",
+    provider: "studio3d",
+    modality: "3d",
+    task: "texture",
+    label: "Tripo Texture",
+    cost: { credits: 20 },
+    capabilities: { supportsTextures: true, supportsPbr: true },
+    isDefault: true
+  },
+  // KIE: image gen. Pricing pulled 2026-05-08 from https://kie.ai/pricing
+  // (1 credit = $0.005 USD). Indemnification: KIE provides ZERO IP indemnity,
+  // so reserve these for internal asset work. v0.1 ships as private internal
+  // infra, so KIE is the v0.1 default; revisit if customer-facing output is
+  // ever needed.
+  {
+    // Verified 2026-05-09 via two consecutive CLI smokes at 1:1, 1K, single
+    // candidate, default options: KIE billed 8 credits ($0.040) each time.
+    // Earlier spec estimate was $0.020 (4 credits); replaced with the measured
+    // value. The provider's costUsd from creditsConsumed remains the source of
+    // truth for accounting; this catalog field is UI hints only.
+    id: "kie/nano-banana-2",
+    provider: "kie",
+    modality: "image",
+    task: "text-to-image",
+    label: "Nano Banana 2 (KIE)",
+    description: "Google Gemini 2.5 Flash Image via KIE. Kept as fallback aggregator path; default flipped to fal/nano-banana-2 in 2026-06-04 fal slice.",
+    cost: { usd: 0.04 }
+  },
+  {
+    // imagen-4-fast price is estimated; KIE docs do not publish a per-image
+    // USD rate. Read data.creditsConsumed from a real run to verify.
+    id: "kie/imagen-4-fast",
+    provider: "kie",
+    modality: "image",
+    task: "text-to-image",
+    label: "Imagen 4 Fast (KIE)",
+    description: "Google Imagen 4 Fast via KIE. No price advantage vs Vertex direct. No IP indemnity.",
+    cost: { usd: 0.02 }
+  },
+  {
+    id: "kie/seedream-v4",
+    provider: "kie",
+    modality: "image",
+    task: "text-to-image",
+    label: "Seedream V4 (KIE)",
+    description: "ByteDance Seedream V4 via KIE. Stylized output not available on Vertex. No IP indemnity.",
+    cost: { usd: 0.0175 }
+  },
+  // ── fal.ai: image gen ─────────────────────────────────────────────────
+  // Prices from docs/internal/research/fal-api-reference.md (vetted
+  // 2026-06-04). Nano Banana 2 is the SAME upstream model as today's KIE
+  // nano-banana-2 default; flipping the default from kie/nano-banana-2 to
+  // fal/nano-banana-2 is zero aesthetic change. FLUX 1.1 [pro] is the
+  // fal-native flagship; FLUX.1 [schnell] the fast/cheap option; FLUX.1
+  // Kontext [pro] is for instruction edits.
+  //
+  // Per-task entries (Weave-style classification, option a from the spec):
+  // Nano Banana 2 appears as both text-to-image (default) and the /edit
+  // endpoint as image-to-image + image-edit, sharing one upstream id.
+  {
+    id: "fal/nano-banana-2",
+    provider: "fal",
+    modality: "image",
+    task: "text-to-image",
+    label: "Nano Banana 2 (fal)",
+    description: "Google Gemini 2.5 Flash Image via fal. Default for image gen; same upstream model as KIE nano-banana-2 with no aesthetic change. $0.08 per image (2K x1.5, 4K x2).",
+    cost: { usd: 0.08 },
+    capabilities: { maxInputImages: 0 },
+    isDefault: true
+  },
+  {
+    id: "fal/nano-banana-2-edit",
+    provider: "fal",
+    modality: "image",
+    task: "image-edit",
+    label: "Nano Banana 2 Edit (fal)",
+    description: "Nano Banana 2 instruction edit. Takes up to 8 reference images for full brand consistency.",
+    cost: { usd: 0.08 },
+    capabilities: { needsImageInput: true, maxInputImages: 8 }
+  },
+  {
+    id: "fal/nano-banana-2-edit-i2i",
+    provider: "fal",
+    modality: "image",
+    task: "image-to-image",
+    label: "Nano Banana 2 Image-to-Image (fal)",
+    description: "Nano Banana 2 in image-to-image mode; same upstream endpoint as the edit entry, separate task classification.",
+    cost: { usd: 0.08 },
+    capabilities: { needsImageInput: true, maxInputImages: 8 }
+  },
+  // ── fal.ai: Reve 2.1 (A/B alternative to Nano Banana for the mint flow) ──
+  // Reve's current flagship. Two endpoints mirror the Nano Banana split: the
+  // t2i entry generates from text only, the remix entry generates FROM up to 6
+  // reference images (image_urls array; prompts may address refs as <img>0</img>).
+  // The provider auto-routes the family exactly like Nano Banana: refs present
+  // -> remix, no refs -> text-to-image. $0.04 per image on both endpoints
+  // (fal pricing page, verified 2026-07-24).
+  {
+    id: "fal/reve",
+    provider: "fal",
+    modality: "image",
+    task: "text-to-image",
+    label: "Reve 2.1 (fal)",
+    description: "Reve 2.1 text-to-image via fal. Native 4K, strong prompt adherence; $0.04 per image. Text-only (refs route to the remix entry).",
+    cost: { usd: 0.04 },
+    capabilities: { maxInputImages: 0 }
+  },
+  {
+    id: "fal/reve-remix",
+    provider: "fal",
+    modality: "image",
+    task: "image-edit",
+    label: "Reve 2.1 Remix (fal)",
+    description: "Reve 2.1 remix via fal: generates from up to 6 reference images plus a prompt; $0.04 per image. The mint-flow A/B counterpart to Nano Banana 2 Edit.",
+    cost: { usd: 0.04 },
+    capabilities: { needsImageInput: true, maxInputImages: 6 }
+  },
+  {
+    id: "fal/flux-1-1-pro",
+    provider: "fal",
+    modality: "image",
+    task: "text-to-image",
+    label: "FLUX 1.1 [pro] (fal)",
+    description: "Black Forest Labs FLUX 1.1 [pro] via fal. Flagship text-to-image; $0.04 per megapixel. Text-only, no reference-image brand conditioning.",
+    cost: { usd: 0.04 },
+    capabilities: { maxInputImages: 0 }
+  },
+  {
+    id: "fal/flux-schnell",
+    provider: "fal",
+    modality: "image",
+    task: "text-to-image",
+    label: "FLUX.1 [schnell] (fal)",
+    description: "Black Forest Labs FLUX.1 [schnell] via fal. Fast/cheap text-to-image; $0.003 per megapixel. Text-only.",
+    cost: { usd: 3e-3 },
+    capabilities: { maxInputImages: 0 }
+  },
+  {
+    id: "fal/flux-kontext-pro",
+    provider: "fal",
+    modality: "image",
+    task: "image-edit",
+    label: "FLUX.1 Kontext [pro] (fal)",
+    description: "FLUX.1 Kontext instruction edit via fal. Single image_url input ($0.04 per image). For multi-ref, the kontext/max/multi endpoint is a follow-up.",
+    cost: { usd: 0.04 },
+    capabilities: { needsImageInput: true, maxInputImages: 1 }
+  },
+  // ── fal.ai: virtual try-on (E3) ────────────────────────────────────────
+  // FASHN garment-preserving try-on. A DISTINCT task from image-edit: it takes
+  // TWO named images (garment + person/model) and preserves the garment's
+  // pixels (text/pattern/fabric) rather than letting a general diffusion edit
+  // redraw them. Id, schema, and price verified 2026-07-20 against fal's model
+  // page for fal-ai/fashn/tryon/v1.6; see docs/internal/research/fal-fashn-tryon.md.
+  // Flat $0.075 per run (fal does not return cost; the provider computes it).
+  {
+    id: "fal/fashn-tryon-v1-6",
+    provider: "fal",
+    modality: "image",
+    task: "virtual-try-on",
+    label: "FASHN Try-On v1.6",
+    description: "Garment-preserving virtual try-on via fal. Preserves product text/pattern/fabric; takes a garment image and a model/person image. $0.075 per run (fal-ai/fashn/tryon/v1.6, vetted 2026-07-20).",
+    cost: { usd: 0.075 },
+    capabilities: { maxInputImages: 2, needsImageInput: true },
+    isDefault: true
+  },
+  // ── fal.ai: video gen (B1) ─────────────────────────────────────────────
+  // Async via fal's queue API (submit -> webhook / poll). Prices are per the
+  // fal model pages (vetted 2026-06-16); fal does NOT return cost, so the
+  // provider computes a flat per-video estimate from the catalog usd anchored
+  // to the model's base clip length. Exactly one isDefault per (video, task):
+  // Kling 2.5 Turbo Pro for image-to-video, Seedance 1.0 Pro for text-to-video.
+  {
+    id: "fal/kling-v2-5-image-to-video",
+    provider: "fal",
+    modality: "video",
+    task: "image-to-video",
+    label: "Kling 2.5 Turbo Pro (image-to-video)",
+    description: "Kuaishou Kling 2.5 Turbo Pro via fal. Cinematic image-to-video; $0.35 base (5s) plus $0.07 per extra second. Default image-to-video.",
+    cost: { usd: 0.35 },
+    capabilities: { needsImageInput: true, maxInputImages: 1 },
+    isDefault: true
+  },
+  {
+    id: "fal/seedance-pro-image-to-video",
+    provider: "fal",
+    modality: "video",
+    task: "image-to-video",
+    label: "Seedance 1.0 Pro (image-to-video)",
+    description: "ByteDance Seedance 1.0 Pro via fal. Image-to-video; roughly $0.62 per 1080p 5s clip. Alternative to Kling for stylized motion.",
+    cost: { usd: 0.62 },
+    capabilities: { needsImageInput: true, maxInputImages: 1 }
+  },
+  {
+    id: "fal/seedance-2-5-image-to-video",
+    provider: "fal",
+    modality: "video",
+    task: "image-to-video",
+    label: "Seedance 2.5 (image-to-video)",
+    description: "ByteDance Seedance 2.5 via fal. Accepts a start frame AND an end frame (end_image_url), selectable duration 4-30s, up to 1080p, with synchronised audio (generate_audio, on by default). Token-billed: (w*h*s*24)/1024 at $0.0214 per 1000 tokens, so roughly $1.89 for 4s at 720p and $4.16 at 1080p. CAUTION: ByteDance partner moderation on 2.5 rejected even fal's own robot test image with content_policy_violation (observed 2026-08-21), so it may refuse input that 2.0 accepts. Try 2.0 first for photographic input.",
+    cost: { usd: 1.89 },
+    capabilities: { needsImageInput: true, maxInputImages: 1 }
+  },
+  {
+    id: "fal/seedance-2-0-image-to-video",
+    provider: "fal",
+    modality: "video",
+    task: "image-to-video",
+    label: "Seedance 2.0 (image-to-video)",
+    description: "ByteDance Seedance 2.0 via fal. Start frame plus optional end frame (end_image_url), duration 4-15s, up to 4k, and it accepts seven explicit aspect ratios where 2.5 is fixed to auto. Not simply superseded by 2.5: 2.0 generated from photographic input that 2.5 refused on content policy (observed 2026-08-21), and it is the only one offering 4k. Token-billed identically to 2.5.",
+    cost: { usd: 1.89 },
+    capabilities: { needsImageInput: true, maxInputImages: 1 }
+  },
+  // ── FLUX.3 (Black Forest Labs) ───────────────────────────────────────────
+  // One model, three tiers of the same three input shapes:
+  //   draft     $0.06/s, fixed 720p, plus a draft_cache bundle   (preview)
+  //   direct    $0.17/s at 720p, $0.29/s at 1080p, one shot       (finished)
+  //   enhance   $0.29/s, fixed 1080p, from the cache only         (finished)
+  // Draft + enhance totals $0.35/s, a 21% premium over direct 1080p on a first-try
+  // keeper and cheaper from the second attempt on, which is exactly the
+  // generate-several-pick-one shape. Use direct when one confident render is
+  // enough or 720p is the deliverable; use draft + enhance when a human picks.
+  // The completion handler mirrors each draft's cache into Storage Brain, so an
+  // approval gate between the two can take as long as it needs (measured: the
+  // bundle is ~29 KB and fal enhances from a re-hosted copy, 2026-08-23).
+  // Different model owner than Seedance, so ByteDance partner moderation does
+  // not apply here. That changes which filter runs, and nothing about whether we
+  // hold the depicted person's consent.
+  {
+    id: "fal/flux-3-image-to-video-draft",
+    provider: "fal",
+    modality: "video",
+    task: "image-to-video",
+    label: "FLUX.3 draft (image-to-video)",
+    description: "Black Forest Labs FLUX.3 draft tier via fal. Single opening keyframe, duration auto or 5-20s, fixed 720p, audio ON by default (generate_audio). $0.06 per second of draft. Returns a draft_cache for a later full-quality enhance pass, which bills separately. Accepts no resolution, seed or negative prompt. PREVIEW QUALITY: do not ship a draft as a deliverable.",
+    cost: { usd: 0.3 },
+    capabilities: { needsImageInput: true, maxInputImages: 1, emitsDraftCache: true }
+  },
+  {
+    id: "fal/flux-3-first-last-frame-to-video-draft",
+    provider: "fal",
+    modality: "video",
+    task: "image-to-video",
+    label: "FLUX.3 draft (first + last frame)",
+    description: "Black Forest Labs FLUX.3 draft tier via fal. Start AND end keyframe, duration 5-20s, fixed 720p, audio ON by default. $0.06 per second of draft, roughly a third of Kling 2.5 for the same two-keyframe shot. Note it names the start frame start_image_url, not image_url. Minimum 5s, so a 4s cut means rendering 5s and trimming. PREVIEW QUALITY: enhance before shipping.",
+    cost: { usd: 0.3 },
+    capabilities: { needsImageInput: true, maxInputImages: 2, emitsDraftCache: true }
+  },
+  {
+    id: "fal/flux-3-keyframes-to-video-draft",
+    provider: "fal",
+    modality: "video",
+    task: "image-to-video",
+    label: "FLUX.3 draft (keyframes)",
+    description: "Black Forest Labs FLUX.3 draft tier via fal. Up to 10 images pinned to positions on a 24 fps timeline (params.keyframes as [{ imageUrl, frameIndex }]), duration 5-20s, fixed 720p, audio ON by default. $0.06 per second of draft. The only endpoint here that expresses motion through more than two keyframes, so it can describe a pass-by or a multi-beat action that a first/last pair structurally cannot. Falls back to deriving two keyframes from the standard start/end inputs. PREVIEW QUALITY: enhance before shipping.",
+    cost: { usd: 0.3 },
+    capabilities: { needsImageInput: true, maxInputImages: 10, emitsDraftCache: true }
+  },
+  {
+    id: "fal/flux-3-image-to-video",
+    provider: "fal",
+    modality: "video",
+    task: "image-to-video",
+    label: "FLUX.3 (image-to-video)",
+    description: "Black Forest Labs FLUX.3 direct tier via fal. Single opening keyframe, duration auto or 5-20s, resolution 720p (default) or 1080p, audio ON by default. $0.17 per second at 720p, $0.29 at 1080p; the catalog usd anchors 5s at 720p. One-shot finished render, returns the seed. Use when one confident render is enough; for iterate-then-pick, draft + enhance is cheaper.",
+    cost: { usd: 0.85 },
+    capabilities: { needsImageInput: true, maxInputImages: 1 }
+  },
+  {
+    id: "fal/flux-3-first-last-frame-to-video",
+    provider: "fal",
+    modality: "video",
+    task: "image-to-video",
+    label: "FLUX.3 (first + last frame)",
+    description: "Black Forest Labs FLUX.3 direct tier via fal. Start AND end keyframe (start_image_url / end_image_url), duration 5-20s, resolution 720p (default) or 1080p, audio ON by default. $0.17 per second at 720p, $0.29 at 1080p; the catalog usd anchors 5s at 720p. Minimum 5s, so a 4s cut means rendering 5s and trimming. Finished quality, returns the seed.",
+    cost: { usd: 0.85 },
+    capabilities: { needsImageInput: true, maxInputImages: 2 }
+  },
+  {
+    id: "fal/flux-3-keyframes-to-video",
+    provider: "fal",
+    modality: "video",
+    task: "image-to-video",
+    label: "FLUX.3 (keyframes)",
+    description: "Black Forest Labs FLUX.3 direct tier via fal. Up to 10 images pinned to positions on a 24 fps timeline (params.keyframes as [{ imageUrl, frameIndex }]), duration 5-20s, resolution 720p (default) or 1080p, audio ON by default. $0.17 per second at 720p, $0.29 at 1080p; the catalog usd anchors 5s at 720p. Multi-beat actions and pass-bys that a first/last pair cannot express. Finished quality, returns the seed.",
+    cost: { usd: 0.85 },
+    capabilities: { needsImageInput: true, maxInputImages: 10 }
+  },
+  {
+    id: "fal/flux-3-draft-enhance",
+    provider: "fal",
+    modality: "video",
+    task: "video-enhance",
+    label: "FLUX.3 enhance (draft to 1080p)",
+    description: "Black Forest Labs FLUX.3 draft-enhance via fal. Input is ONLY the draft_cache of a FLUX.3 draft node (wire the draft node in; nothing else can be enhanced, only re-rendered). Renders the same take, same motion and composition, at a fixed 1080p with synchronized audio. $0.29 per second of enhanced video; the catalog usd anchors 5s. No prompt, duration, aspect or audio knobs (all baked into the cache); safety_tolerance only. Output has no seed or cache.",
+    cost: { usd: 1.45 },
+    capabilities: { needsImageInput: false, maxInputImages: 0 },
+    isDefault: true
+  },
+  {
+    id: "fal/seedance-pro-text-to-video",
+    provider: "fal",
+    modality: "video",
+    task: "text-to-video",
+    label: "Seedance 1.0 Pro (text-to-video)",
+    description: "ByteDance Seedance 1.0 Pro via fal. Text-to-video; roughly $0.62 per 1080p 5s clip. Default text-to-video.",
+    cost: { usd: 0.62 },
+    capabilities: { maxInputImages: 0 },
+    isDefault: true
+  },
+  // Video-to-video: Wan 2.2 Animate Replace swaps the person in a source video
+  // for the character in ONE reference image, keeping scene + motion. Priced
+  // per video second by resolution (fal pricing, vetted 2026-08-20): 480p $0.04,
+  // 580p $0.06, 720p $0.08. The catalog usd anchors a 5s clip at 720p, the same
+  // way Kling anchors its base clip; the provider scales by duration + resolution.
+  // Output is 50fps, 720p max. Only model for the task, so it is the default.
+  {
+    id: "fal/wan-animate-replace",
+    provider: "fal",
+    modality: "video",
+    task: "video-to-video",
+    label: "Wan 2.2 Animate Replace (video-to-video)",
+    description: "Wan 2.2 14B Animate Replace via fal. Replaces the person in a source video with the character from one reference image, preserving motion and scene. $0.04 (480p) / $0.06 (580p) / $0.08 (720p) per video second. Default video-to-video.",
+    cost: { usd: 0.4 },
+    capabilities: { needsImageInput: true, maxInputImages: 1 },
+    isDefault: true
+  },
+  // ── fal.ai: vision + utility (B4) ──────────────────────────────────────
+  // All sync via fal's subscribe. Two return text/json (vision), two return a
+  // new image (upscale / background-remove). fal bills these per compute second
+  // and does NOT return a per-call cost, so the catalog usd is a UI hint only
+  // (the provider leaves costUsd undefined, same as an unknown image endpoint).
+  // Endpoint ids + schemas verified 2026-06-16 against the fal model /api pages.
+  // Modality stays `image` (these consume / produce images); one isDefault per
+  // (image, task) for the four new tasks.
+  {
+    id: "fal/florence-2-detailed-caption",
+    provider: "fal",
+    modality: "image",
+    task: "image-to-text",
+    label: "Florence-2 Detailed Caption (fal)",
+    description: "Microsoft Florence-2 Large detailed caption via fal. Returns a rich text description of an image (caption -> job.output.text, no asset). Default image-to-text.",
+    cost: { usd: 3e-3 },
+    capabilities: { needsImageInput: true, maxInputImages: 1 },
+    isDefault: true
+  },
+  {
+    id: "fal/moondream-next-vqa",
+    provider: "fal",
+    modality: "image",
+    task: "image-to-json",
+    label: "MoonDreamNext VQA (fal)",
+    description: "MoonDreamNext visual question answering via fal. Answers a prompt about an image; the provider parses the answer into structured JSON (-> job.output.json, no asset). Default image-to-json.",
+    cost: { usd: 3e-3 },
+    capabilities: { needsImageInput: true, maxInputImages: 1 },
+    isDefault: true
+  },
+  // Judge (P3 J1). The same MoonDreamNext VQA endpoint `fal/moondream-next-vqa`
+  // above already runs shotReview.ts's ranking call, under a separate catalog
+  // id because a catalog entry's `task` is fixed and `listByTask('judge')`
+  // needs at least one entry to give a placed judge node a selectable default
+  // model. Not dispatched yet: `judge` runs as a human gate (`taskExecution`
+  // in task-kind.ts) and makes no model call at all until J5 wires the actual
+  // ranking back onto shotReview.ts rather than a second implementation.
+  {
+    id: "fal/moondream-next-vqa-judge",
+    provider: "fal",
+    modality: "image",
+    task: "judge",
+    label: "MoonDreamNext VQA (judge ranking)",
+    description: "The judge node's ranking call: the same MoonDreamNext VQA endpoint shotReview.ts already uses to score a candidate image. A judge node runs as a human GATE (it parks the run on a decision, see taskExecution), so it has no job kind; this model is what P3 J5 will rank candidates with. Default judge.",
+    cost: { usd: 3e-3 },
+    capabilities: { needsImageInput: true, maxInputImages: 1 },
+    isDefault: true
+  },
+  {
+    id: "fal/aura-sr-upscale",
+    provider: "fal",
+    modality: "image",
+    task: "upscale",
+    label: "AuraSR Upscale (fal)",
+    description: "AuraSR GigaGAN upscaler via fal. Produces a higher-resolution Image asset from a source image (default 4x). Default upscale. Compute-second billed; catalog usd is a hint.",
+    cost: { usd: 0.01 },
+    capabilities: { needsImageInput: true, maxInputImages: 1 },
+    isDefault: true
+  },
+  {
+    id: "fal/birefnet-v2-background-remove",
+    provider: "fal",
+    modality: "image",
+    task: "background-remove",
+    label: "BiRefNet v2 Background Removal (fal)",
+    description: "BiRefNet v2 background removal via fal. Produces a transparent-background PNG Image asset from a source image. Default background-remove. Compute-second billed; catalog usd is a hint.",
+    cost: { usd: 0.01 },
+    capabilities: { needsImageInput: true, maxInputImages: 1 },
+    isDefault: true
+  },
+  // ── audio: music via Suno-through-KIE (B2) ─────────────────────────────
+  // Async via KIE's Suno job API (createTask -> webhook / record-info poll).
+  // KIE does not return a per-song USD on the result, so the catalog usd is a
+  // flat per-song estimate (~$0.03-$0.04 per song per audio-providers.md, KIE's
+  // markup keeps it in that band). V5 is Suno's current top model.
+  {
+    id: "kie/suno-v5",
+    provider: "kie",
+    modality: "audio",
+    task: "text-to-audio",
+    label: "Suno V5 (KIE)",
+    description: "Suno V5 music generation via KIE. Text-to-music with or without lyrics; ~4 min cap per generation. Default text-to-audio. No IP indemnity (KIE aggregator).",
+    cost: { usd: 0.04 },
+    isDefault: true
+  },
+  // ── audio: voice via ElevenLabs (B2) ───────────────────────────────────
+  // Sync against the official ElevenLabs API (xi-api-key). TTS returns audio
+  // bytes inline; STT returns a transcript (text, not a binary asset). Prices
+  // per ElevenLabs usage tiers (audio-providers.md): TTS ~ $0.0003 per char on
+  // a paid tier, STT ~ $0.40 per audio hour; the catalog usd is a per-call
+  // hint, the provider does not bill per call so cost stays approximate.
+  {
+    id: "elevenlabs/tts-multilingual-v2",
+    provider: "elevenlabs",
+    modality: "audio",
+    task: "text-to-speech",
+    label: "ElevenLabs Multilingual v2 (TTS)",
+    description: "ElevenLabs Multilingual v2 text-to-speech. 99+ languages, brand-voice cloning capable. Default text-to-speech. Returns mp3 bytes synchronously.",
+    cost: { usd: 0.03 },
+    isDefault: true
+  },
+  {
+    id: "elevenlabs/scribe-v1",
+    provider: "elevenlabs",
+    modality: "audio",
+    task: "speech-to-text",
+    label: "ElevenLabs Scribe v1 (STT)",
+    description: "ElevenLabs Scribe v1 speech-to-text. Whisper-class transcription; returns a transcript (text), not a binary asset. Default speech-to-text.",
+    cost: { usd: 0.01 },
+    isDefault: true
+  },
+  // ── text: LLM director (B3) ────────────────────────────────────────────
+  // The director's brain, NOT an asset-generation path: prompt improvement and
+  // shot descriptions via a synchronous TextClient (no Jobs, no Assets). KIE
+  // exposes Claude (Sonnet / Opus) at a lower rate than the official API via an
+  // Anthropic-Messages-compatible endpoint (api.kie.ai/claude/v1/messages,
+  // vetted 2026-06-16); OpenRouter routes the same Claude family through its
+  // OpenAI chat/completions surface and returns the authoritative usage.cost.
+  // KIE / OpenRouter report real cost per call, so the catalog usd is a UI hint.
+  // Exactly one isDefault for (text, text-generation): KIE Sonnet (cheapest
+  // reliable director path with no IP-indemnity concern for internal use).
+  {
+    id: "kie/claude-sonnet-4-5",
+    provider: "kie",
+    modality: "text",
+    task: "text-generation",
+    label: "Claude Sonnet 4.5 (KIE)",
+    description: "Anthropic Claude Sonnet 4.5 via KIE (Anthropic Messages API at a lower rate). Default LLM director: prompt improvement + shot descriptions. Cost billed per token; catalog usd is a hint.",
+    cost: { usd: 0.01 },
+    isDefault: true
+  },
+  {
+    id: "kie/claude-opus-4-5",
+    provider: "kie",
+    modality: "text",
+    task: "text-generation",
+    label: "Claude Opus 4.5 (KIE)",
+    description: "Anthropic Claude Opus 4.5 via KIE. Higher quality, higher cost; use for harder director reasoning. Cost billed per token; catalog usd is a hint.",
+    cost: { usd: 0.05 }
+  },
+  {
+    id: "openrouter/claude-sonnet-4-6",
+    provider: "openrouter",
+    modality: "text",
+    task: "text-generation",
+    label: "Claude Sonnet 4.6 (OpenRouter)",
+    description: "Anthropic Claude Sonnet 4.6 via OpenRouter (OpenAI chat/completions shape). Alternative director path; returns authoritative usage.cost per request.",
+    cost: { usd: 0.012 }
+  },
+  // ── Vertex AI: fallback path, kept unwired for v0.1 ────────────────────
+  // Provider code is still in place so a future flip back is one isDefault
+  // move. Activating any of these requires GOOGLE_APPLICATION_CREDENTIALS_JSON
+  // in Infisical prod, which v0.1 explicitly skips.
+  {
+    id: "vertex/gemini-2-5-flash-image",
+    provider: "vertex",
+    modality: "image",
+    task: "text-to-image",
+    label: "Gemini 2.5 Flash Image",
+    description: "Vertex AI direct. Fallback if KIE pricing or reliability turns sour. Needs GAC_JSON provisioning to activate."
+  },
+  {
+    id: "vertex/gemini-3-pro-image-preview",
+    provider: "vertex",
+    modality: "image",
+    task: "text-to-image",
+    label: "Nano Banana Pro (preview)"
+  },
+  {
+    id: "vertex/gemini-3-1-flash-image-preview",
+    provider: "vertex",
+    modality: "image",
+    task: "text-to-image",
+    label: "Gemini 3.1 Flash Image (preview)",
+    description: "Vertex AI direct, newest flash variant. Global region. Preview status."
+  }
+];
+function tryGetModel(id) {
+  return MODEL_CATALOG.find((m) => m.id === id);
+}
+var PROMPT_REQUIRED = /* @__PURE__ */ new Set([
+  "text-to-image",
+  "image-to-image",
+  "image-edit",
+  "text-to-3d",
+  "image-to-3d",
+  "multiview-to-3d",
+  "text-to-video",
+  // Audio is prompt-only: a music description (text-to-audio) / the text to
+  // speak (text-to-speech). No upstream wire, so no portBinding entry.
+  "text-to-audio",
+  "text-to-speech"
+]);
+var PROMPT_OPTIONAL = /* @__PURE__ */ new Set(["image-to-video", "image-to-json", "texture"]);
+function taskNeedsPrompt(task) {
+  return PROMPT_REQUIRED.has(task) || PROMPT_OPTIONAL.has(task);
+}
+function taskRequiresPrompt(task) {
+  return PROMPT_REQUIRED.has(task);
+}
+function promptInputKey(task) {
+  return task === "texture" ? "texturePrompt" : "prompt";
+}
+function portBinding(task, port) {
+  if (port === "image" && (task === "image-to-3d" || task === "multiview-to-3d" || task === "image-to-video" || task === "image-to-text" || task === "image-to-json")) {
+    return { key: "inputImageUrl", path: "url" };
+  }
+  if (port === "mesh3d" && (task === "remesh" || task === "texture")) {
+    return { key: "parentAssetId", path: "assetId" };
+  }
+  if (port === "video" && task === "video-to-video") {
+    return { key: "inputVideoUrl", path: "url" };
+  }
+  if (port === "image" && task === "video-to-video") {
+    return { key: "inputImages", path: "url", wrap: "array" };
+  }
+  if (port === "video" && task === "video-enhance") {
+    return { key: "draftCacheUrl", path: "draftCacheUrl" };
+  }
+  if (port === "image" && task === "image-edit") {
+    return { key: "inputImages", path: "url", wrap: "array" };
+  }
+  if (port === "text" && taskNeedsPrompt(task)) {
+    return { key: promptInputKey(task), path: "text" };
+  }
+  if (port === "image" && (task === "upscale" || task === "background-remove")) {
+    return { key: "parentAssetId", path: "assetId" };
+  }
+  if (port === "audio" && task === "speech-to-text") {
+    return { key: "inputAudioUrl", path: "url" };
+  }
+  if (port === "image" && task === "judge") {
+    return { key: "candidateAssetIds", path: "assetId", wrap: "array" };
+  }
+  return null;
+}
+function canConnect(sourceOut, targetTask, targetPort) {
+  if (sourceOut !== targetPort) return false;
+  return portBinding(targetTask, targetPort) !== null;
+}
+function sourcePortOf(node) {
+  switch (node.kind) {
+    case "task":
+      return taskPorts(node.task).output;
+    case "prompt-source":
+      return "text";
+    case "image-source":
+      return "image";
+    case "input":
+      return node.type;
+  }
+}
+function wireLegality(source, target, port) {
+  if (source.id === target.id) return { ok: false, code: "cycle", message: `node "${source.id}" cannot wire into itself` };
+  const produced = sourcePortOf(source);
+  if (produced !== port) {
+    return { ok: false, code: "invalid_port", message: `node "${source.id}" produces ${produced}, not ${port}` };
+  }
+  if (target.kind !== "task") {
+    return { ok: false, code: "invalid_port", message: `node "${target.id}" (${target.kind}) has no inputs` };
+  }
+  if (!canConnect(produced, target.task, port)) {
+    return { ok: false, code: "invalid_port", message: `a ${port} wire into "${target.id}" (${target.task}) is not supported` };
+  }
+  if (source.kind === "input" && source.cardinality === "many" && portBinding(target.task, port)?.wrap !== "array") {
+    return {
+      ok: false,
+      code: "invalid_port",
+      message: `list input "${source.id}" needs an array port; "${target.id}" (${target.task}) takes one ${port}`
+    };
+  }
+  if (target.task === "video-enhance" && port === "video") {
+    if (source.kind !== "task") {
+      return {
+        ok: false,
+        code: "invalid_port",
+        message: `"${target.id}" (video-enhance) finishes a FLUX.3 DRAFT node's take from its draft cache; an uploaded or external video has no cache and cannot be enhanced, only re-rendered.`
+      };
+    }
+    const model = source.model ? tryGetModel(source.model) : void 0;
+    if (source.model && model && !model.capabilities?.emitsDraftCache) {
+      return {
+        ok: false,
+        code: "invalid_port",
+        message: `"${source.id}" (${source.model}) produces no draft cache, so "${target.id}" (video-enhance) cannot finish it. Wire a FLUX.3 draft node instead, or re-render at the target quality directly.`
+      };
+    }
+  }
+  return { ok: true };
+}
+function documentTopologicalOrder(doc) {
+  return kahnOrder(
+    doc.nodes.map((n) => n.id),
+    doc.edges.map((e) => [e.source, e.target])
+  );
+}
+function validateDocument(doc) {
+  if (doc.schema !== DOCUMENT_SCHEMA_VERSION) {
+    return {
+      ok: false,
+      code: "schema",
+      message: `document schema ${doc.schema} is not the current ${DOCUMENT_SCHEMA_VERSION}; migrate it on read first`
+    };
+  }
+  const byId = /* @__PURE__ */ new Map();
+  for (const node of doc.nodes) {
+    if (byId.has(node.id)) return { ok: false, code: "conflict", message: `duplicate node id "${node.id}"` };
+    byId.set(node.id, node);
+  }
+  const inputNames = /* @__PURE__ */ new Set();
+  for (const node of doc.nodes) {
+    if (node.kind !== "input") continue;
+    if (inputNames.has(node.name)) {
+      return { ok: false, code: "conflict", message: `duplicate input name "${node.name}"` };
+    }
+    inputNames.add(node.name);
+  }
+  const edgeKeys = /* @__PURE__ */ new Set();
+  const slots = /* @__PURE__ */ new Set();
+  for (const e of doc.edges) {
+    const key = edgeKey(e);
+    if (edgeKeys.has(key)) return { ok: false, code: "conflict", message: `duplicate edge ${key}` };
+    edgeKeys.add(key);
+    const source = byId.get(e.source);
+    const target = byId.get(e.target);
+    if (!source) return { ok: false, code: "not_found", message: `edge source "${e.source}" does not exist` };
+    if (!target) return { ok: false, code: "not_found", message: `edge target "${e.target}" does not exist` };
+    const legal = wireLegality(source, target, e.port);
+    if (!legal.ok) return legal;
+    const slot = slotKey(e.target, e.port);
+    if (slots.has(slot)) {
+      return {
+        ok: false,
+        code: "cardinality",
+        message: `node "${e.target}" accepts one ${e.port} wire, got more`
+      };
+    }
+    slots.add(slot);
+  }
+  if (documentTopologicalOrder(doc) === null) {
+    return { ok: false, code: "cycle", message: `document "${doc.id}" has a cycle in its wires` };
+  }
+  for (const id of Object.keys(doc.layout)) {
+    if (!byId.has(id)) return { ok: false, code: "not_found", message: `layout entry for unknown node "${id}"` };
+  }
+  const groupIds = /* @__PURE__ */ new Set();
+  const grouped = /* @__PURE__ */ new Map();
+  for (const g of doc.groups) {
+    if (groupIds.has(g.id)) return { ok: false, code: "conflict", message: `duplicate group id "${g.id}"` };
+    groupIds.add(g.id);
+    for (const id of g.nodeIds) {
+      if (!byId.has(id)) return { ok: false, code: "not_found", message: `group "${g.id}" references unknown node "${id}"` };
+      const other = grouped.get(id);
+      if (other !== void 0) {
+        return {
+          ok: false,
+          code: "conflict",
+          message: `node "${id}" is in groups "${other}" and "${g.id}"; a node belongs to at most one group`
+        };
+      }
+      grouped.set(id, g.id);
+    }
+  }
+  return { ok: true };
+}
+var Index = z4.number().int().nonnegative();
+var TaskNodePropsSchema = z4.object({
+  task: z4.enum(MODEL_TASKS),
+  model: ModelIdSchema,
+  prompt: PromptTextSchema,
+  label: LabelSchema.nullable()
+}).partial().strict();
+var PromptSourcePropsSchema = z4.object({
+  text: PromptTextSchema,
+  label: LabelSchema.nullable()
+}).partial().strict();
+var ImageSourcePropsSchema = z4.object({
+  imageUrl: UrlSchema,
+  assetId: AssetIdSchema.nullable(),
+  label: LabelSchema.nullable()
+}).partial().strict();
+var InputNodePropsSchema = z4.object({
+  name: InputNameSchema,
+  type: InputTypeSchema,
+  required: z4.boolean(),
+  cardinality: z4.enum(["one", "many"]).nullable(),
+  default: JsonNonNullValueSchema.nullable(),
+  label: LabelSchema.nullable(),
+  description: DescriptionSchema.nullable()
+}).partial().strict();
+var GroupPropsSchema = z4.object({
+  label: LabelSchema.nullable(),
+  nodeIds: z4.array(IdSchema).min(1)
+}).partial().strict();
+var DocumentPropsSchema = z4.object({
+  label: LabelSchema
+}).partial().strict();
+var AddNodeOpSchema = z4.object({
+  type: z4.literal("addNode"),
+  node: DocNodeSchema,
+  /** Explicit position; omit to leave the node unplaced (auto-layout, D7). */
+  position: PositionSchema.optional(),
+  /** Insertion index in `nodes`; omit to append. Inverses use it for exactness. */
+  index: Index.optional()
+});
+var RemoveNodeOpSchema = z4.object({
+  type: z4.literal("removeNode"),
+  id: IdSchema
+});
+var SetNodePropsOpSchema = z4.discriminatedUnion("kind", [
+  z4.object({ type: z4.literal("setNodeProps"), kind: z4.literal("task"), id: IdSchema, props: TaskNodePropsSchema }),
+  z4.object({ type: z4.literal("setNodeProps"), kind: z4.literal("prompt-source"), id: IdSchema, props: PromptSourcePropsSchema }),
+  z4.object({ type: z4.literal("setNodeProps"), kind: z4.literal("image-source"), id: IdSchema, props: ImageSourcePropsSchema }),
+  z4.object({ type: z4.literal("setNodeProps"), kind: z4.literal("input"), id: IdSchema, props: InputNodePropsSchema })
+]);
+var SetNodeSettingOpSchema = z4.object({
+  type: z4.literal("setNodeSetting"),
+  id: IdSchema,
+  key: KeySchema,
+  /** null unsets the knob. */
+  value: JsonNonNullValueSchema.nullable()
+});
+var SetBakedInputOpSchema = z4.object({
+  type: z4.literal("setBakedInput"),
+  id: IdSchema,
+  key: KeySchema,
+  /** A literal only (a dependency must be a wire); null removes the entry. */
+  binding: LiteralBindingSchema.nullable()
+});
+var ConnectOpSchema = z4.object({
+  type: z4.literal("connect"),
+  source: IdSchema,
+  target: IdSchema,
+  port: PortTypeSchema,
+  index: Index.optional()
+});
+var DisconnectOpSchema = z4.object({
+  type: z4.literal("disconnect"),
+  source: IdSchema,
+  target: IdSchema,
+  port: PortTypeSchema
+});
+var ExposeAsInputOpSchema = z4.object({
+  type: z4.literal("exposeAsInput"),
+  /** A prompt-source or image-source node; it becomes an input node IN PLACE
+   * (same id, same produced port type), so its wires survive. */
+  id: IdSchema,
+  name: InputNameSchema,
+  required: z4.boolean().optional(),
+  /** undefined keeps the source's label, null unsets it. */
+  label: LabelSchema.nullable().optional(),
+  description: DescriptionSchema.nullable().optional(),
+  /** undefined derives the default from the source's literal (when it is a
+   * usable value), null declares no default. */
+  default: JsonNonNullValueSchema.nullable().optional()
+});
+var FreezeInputOpSchema = z4.object({
+  type: z4.literal("freezeInput"),
+  /** A text or image input node; it becomes a prompt-source / image-source IN
+   * PLACE carrying `value` (a chosen run's resolved value, or any literal). */
+  id: IdSchema,
+  value: PromptTextSchema,
+  assetId: AssetIdSchema.optional(),
+  /** undefined keeps the input's label, null unsets it. */
+  label: LabelSchema.nullable().optional()
+});
+var SetActiveGenerationOpSchema = z4.object({
+  type: z4.literal("setActiveGeneration"),
+  id: IdSchema,
+  /** null = latest (D4). */
+  generationId: IdSchema.nullable()
+});
+var SetLayoutOpSchema = z4.object({
+  type: z4.literal("setLayout"),
+  id: IdSchema,
+  /** null unplaces the node (it becomes an auto-layout target again). */
+  position: PositionSchema.nullable()
+});
+var GroupOpSchema = z4.object({
+  type: z4.literal("group"),
+  id: IdSchema,
+  label: LabelSchema.optional(),
+  nodeIds: z4.array(IdSchema).min(1),
+  index: Index.optional()
+});
+var UngroupOpSchema = z4.object({
+  type: z4.literal("ungroup"),
+  id: IdSchema
+});
+var SetGroupPropsOpSchema = z4.object({
+  type: z4.literal("setGroupProps"),
+  id: IdSchema,
+  props: GroupPropsSchema
+});
+var SetDocumentPropsOpSchema = z4.object({
+  type: z4.literal("setDocumentProps"),
+  props: DocumentPropsSchema
+});
+var OpSchema = z4.discriminatedUnion("type", [
+  AddNodeOpSchema,
+  RemoveNodeOpSchema,
+  SetNodePropsOpSchema,
+  SetNodeSettingOpSchema,
+  SetBakedInputOpSchema,
+  ConnectOpSchema,
+  DisconnectOpSchema,
+  ExposeAsInputOpSchema,
+  FreezeInputOpSchema,
+  SetActiveGenerationOpSchema,
+  SetLayoutOpSchema,
+  GroupOpSchema,
+  UngroupOpSchema,
+  SetGroupPropsOpSchema,
+  SetDocumentPropsOpSchema
+]);
+var MAX_PATCH_OPS = 500;
+var PatchSchema = z4.object({
+  baseRevision: z4.number().int().nonnegative(),
+  ops: z4.array(OpSchema).min(1).max(MAX_PATCH_OPS),
+  idempotencyKey: z4.string().min(1).max(128).optional()
+});
+function opTouches(doc, op) {
+  const out = /* @__PURE__ */ new Set();
+  switch (op.type) {
+    case "addNode":
+      out.add(op.node.id);
+      break;
+    case "removeNode": {
+      out.add(op.id);
+      for (const e of doc.edges) {
+        if (e.source === op.id) out.add(e.target);
+        else if (e.target === op.id) out.add(e.source);
+      }
+      for (const g of doc.groups) if (g.nodeIds.includes(op.id)) for (const id of g.nodeIds) out.add(id);
+      break;
+    }
+    case "connect":
+    case "disconnect":
+      out.add(op.source);
+      out.add(op.target);
+      break;
+    case "group":
+      for (const id of op.nodeIds) out.add(id);
+      break;
+    case "ungroup":
+    case "setGroupProps": {
+      const g = doc.groups.find((x) => x.id === op.id);
+      for (const id of g?.nodeIds ?? []) out.add(id);
+      if (op.type === "setGroupProps") for (const id of op.props.nodeIds ?? []) out.add(id);
+      break;
+    }
+    case "setDocumentProps":
+      break;
+    default:
+      out.add(op.id);
+  }
+  return [...out];
+}
+var RECIPE_EFFECT_TYPES = ["createCharacter", "addCharacterReference", "createBrand", "addBrandReference"];
+var EffectValueSourceSchema = z5.discriminatedUnion("kind", [
+  z5.object({ kind: z5.literal("literal"), value: JsonNonNullValueSchema }),
+  /** Reads a value out of the recipe run's own input params (the same
+   * params object `studio_run_published` accepts). */
+  z5.object({ kind: z5.literal("param"), name: z5.string().min(1) }),
+  /** Reads a value off a completed node's resolvable output (the same map
+   * `collectOutputs` builds: `url`, `assetId`, ...). For a `forEachNode`
+   * effect, `node` MUST equal that effect's own `forEachNode` (checked by
+   * `validateRecipeEffects`); for a non-iterating effect, `node` names any
+   * node in the workflow. */
+  z5.object({ kind: z5.literal("nodeOutput"), node: IdSchema, path: z5.string().min(1) })
+]);
+var FieldsSchema = z5.record(z5.string().min(1), EffectValueSourceSchema);
+var RecipeEffectSchema = z5.object({
+  type: z5.enum(RECIPE_EFFECT_TYPES),
+  /** "For each output of node X, apply this effect." Absent = the effect
+   * runs exactly once. Present = once per iteration of that node's output
+   * (today: once, since a node run produces one output; the field exists so
+   * a future batch-output node needs no schema change here). */
+  forEachNode: IdSchema.optional(),
+  /** Field name -> how to fill it. The required/allowed fields per `type`
+   * are checked by `validateRecipeEffects`, not by this schema (a
+   * discriminated-union-of-fields would duplicate the repository input
+   * shapes here; the validator is the one place that has to agree with
+   * them). */
+  fields: FieldsSchema
+});
+var RecipeEffectsSchema = z5.array(RecipeEffectSchema).max(50);
+function taskModality(task) {
+  const out = taskPorts(task).output;
+  switch (out) {
+    case "mesh3d":
+      return "3d";
+    case "video":
+      return "video";
+    case "audio":
+      return "audio";
+    case "text":
+    case "json":
+      return "text";
+    case "image":
+    case "mask":
+      return "image";
+  }
+}
+function lit(value) {
+  return { kind: "literal", value: toJsonValue(value, "setting") };
+}
+function isFiniteNumber(v) {
+  return typeof v === "number" && Number.isFinite(v);
+}
+function settingsBindings(task, settings) {
+  if (!task || !settings || Object.keys(settings).length === 0) return {};
+  const modality = taskModality(task);
+  switch (modality) {
+    case "image": {
+      const out = {};
+      if (typeof settings.aspectRatio === "string") out.aspectRatio = lit(settings.aspectRatio);
+      if (typeof settings.resolution === "string") out.imageSize = lit(settings.resolution);
+      if (isFiniteNumber(settings.seed)) out.seed = lit(settings.seed);
+      return out;
+    }
+    case "video": {
+      const options = {};
+      if (typeof settings.aspectRatio === "string") options.aspectRatio = settings.aspectRatio;
+      if (typeof settings.resolution === "string") options.resolution = settings.resolution;
+      if (isFiniteNumber(settings.duration)) options.durationSeconds = settings.duration;
+      return Object.keys(options).length > 0 ? { options: lit(options) } : {};
+    }
+    case "audio": {
+      const options = {};
+      if (isFiniteNumber(settings.duration)) options.durationSeconds = settings.duration;
+      return Object.keys(options).length > 0 ? { options: lit(options) } : {};
+    }
+    default:
+      return {};
+  }
+}
+var TASK_TO_KIND = {
+  // image
+  "text-to-image": "generate_image",
+  "image-to-image": "generate_image",
+  "image-edit": "generate_image",
+  // virtual try-on (E3): two named image inputs (garment + person) ride the
+  // generate_image job's `inputImages` array; the fal provider routes the task
+  // to the FASHN adapter and the result persists through the sync image branch.
+  "virtual-try-on": "generate_image",
+  // 3D
+  "text-to-3d": "generate_3d",
+  "image-to-3d": "generate_3d",
+  "multiview-to-3d": "generate_3d",
+  remesh: "remesh_3d",
+  texture: "texture_3d",
+  // video (async via fal queue)
+  "text-to-video": "generate_video",
+  "image-to-video": "generate_video",
+  // video-to-video (character replace via Wan 2.2 Animate): rides the same
+  // generate_video job; the fal provider routes the task to the replace endpoint.
+  "video-to-video": "generate_video",
+  // video-enhance (FLUX.3 draft-enhance): the same generate_video job; the fal
+  // provider sends the upstream draft's cache bundle instead of frames.
+  "video-enhance": "generate_video",
+  // audio + voice
+  "text-to-audio": "generate_audio",
+  "text-to-speech": "synthesize_speech",
+  "speech-to-text": "transcribe",
+  // vision (text/json output, no binary asset)
+  "image-to-text": "analyze_image",
+  "image-to-json": "analyze_image",
+  // utility (new Image asset off the source)
+  upscale: "transform_image",
+  "background-remove": "transform_image",
+  // No asset/job path yet: text-generation is the LLM director (a sync text
+  // service, no Job/Asset); speech-to-speech and segmentation have no provider
+  // wiring. These are not authorable on the canvas (isBuildableTask is false).
+  "text-generation": null,
+  "speech-to-speech": null,
+  segmentation: null,
+  // Judge (P3 J2): null here FOREVER, and that is not "unrunnable". A judge
+  // node runs as a human gate, never as a queued Job: it parks the run on a
+  // person's decision instead of dispatching to a provider. Runnability is
+  // therefore `taskExecution` below, not this table; giving judge a JobKind
+  // would enqueue a pg-boss job no handler consumes.
+  judge: null
+};
+function taskExecution(task) {
+  if (task === "judge") return "gate";
+  return TASK_TO_KIND[task] === null ? null : "job";
+}
+function paramTypeForInput(type) {
+  return type === "json" ? "json" : "string";
+}
+function isUsableImageUrl(url) {
+  return url.length > 0 && !url.startsWith("data:");
+}
+function documentToDefinition(doc, opts = {}) {
+  const integrity = validateDocument(doc);
+  if (!integrity.ok) return { ok: false, issues: [{ code: "integrity", message: integrity.message }] };
+  const issues = [];
+  const byId = new Map(doc.nodes.map((n) => [n.id, n]));
+  const incoming = /* @__PURE__ */ new Map();
+  for (const e of doc.edges) {
+    const list = incoming.get(e.target);
+    if (list) list.push(e);
+    else incoming.set(e.target, [e]);
+  }
+  const params = doc.nodes.filter((n) => n.kind === "input").map((n) => ({
+    name: n.name,
+    type: n.cardinality === "many" ? "json" : paramTypeForInput(n.type),
+    required: n.required,
+    ...n.label !== void 0 ? { label: n.label } : {},
+    ...n.description !== void 0 ? { description: n.description } : {},
+    inputType: n.type,
+    ...n.cardinality === "many" ? { cardinality: "many" } : {},
+    ...n.default !== void 0 ? { default: n.default } : {}
+  }));
+  const nodes = [];
+  for (const node of doc.nodes) {
+    if (node.kind !== "task") continue;
+    const { task } = node;
+    if (taskExecution(task) === null) {
+      issues.push({ code: "not_runnable", nodeId: node.id, message: `Node "${node.id}" (${task}) is not runnable yet.` });
+      continue;
+    }
+    if (node.model.length === 0) {
+      issues.push({ code: "no_model", nodeId: node.id, message: `Node "${node.id}" needs a model.` });
+    }
+    const inputs = {};
+    const wires = incoming.get(node.id) ?? [];
+    const textWire = wires.find((e) => e.port === "text");
+    let promptMissing = false;
+    if (taskNeedsPrompt(task)) {
+      const key = promptInputKey(task);
+      const source = textWire ? byId.get(textWire.source) : void 0;
+      if (source?.kind === "prompt-source") {
+        const text = source.text.trim();
+        if (text.length > 0) inputs[key] = { kind: "literal", value: text };
+      } else if (source?.kind === "input") {
+        inputs[key] = { kind: "param", name: source.name };
+      } else if (source?.kind === "task") {
+        inputs[key] = { kind: "ref", node: source.id, path: portBinding(task, "text").path };
+      } else {
+        const text = node.prompt.trim();
+        if (text.length > 0) inputs[key] = { kind: "literal", value: text };
+      }
+      if (!(key in inputs) && taskRequiresPrompt(task)) {
+        promptMissing = true;
+        issues.push({ code: "prompt_required", nodeId: node.id, message: `Node "${node.id}" (${task}) needs a prompt.` });
+      }
+    }
+    for (const e of wires) {
+      if (e.port === "text") continue;
+      const b = portBinding(task, e.port);
+      const source = byId.get(e.source);
+      if (source.kind === "image-source") {
+        const url = source.imageUrl.trim();
+        if (!isUsableImageUrl(url)) {
+          issues.push({ code: "source_uploading", nodeId: node.id, message: `Image source for "${node.id}" is still uploading; wait for it to finish.` });
+          continue;
+        }
+        inputs[b.key] = { kind: "literal", value: b.wrap === "array" ? [url] : url };
+      } else if (source.kind === "input") {
+        inputs[b.key] = b.wrap === "array" && source.cardinality !== "many" ? { kind: "param", name: source.name, wrap: "array" } : { kind: "param", name: source.name };
+      } else if (source.kind === "task") {
+        inputs[b.key] = b.wrap === "array" ? { kind: "ref", node: source.id, path: b.path, wrap: "array" } : { kind: "ref", node: source.id, path: b.path };
+      }
+    }
+    for (const [key, binding] of Object.entries(node.bakedInputs)) if (!(key in inputs)) inputs[key] = binding;
+    if (Object.keys(inputs).length === 0 && !promptMissing) {
+      issues.push({ code: "no_inputs", nodeId: node.id, message: `Node "${node.id}" (${task}) needs an input: wire in an upstream asset or type a prompt.` });
+    }
+    Object.assign(inputs, settingsBindings(task, node.settings));
+    nodes.push({ id: node.id, task, model: node.model, inputs });
+  }
+  if (nodes.length === 0 && issues.length === 0) {
+    issues.push({ code: "no_task_nodes", message: "Add at least one model node." });
+  }
+  if (issues.length > 0) return { ok: false, issues };
+  const label = opts.label ?? doc.label;
+  return {
+    ok: true,
+    definition: {
+      version: { schema: 1 },
+      id: opts.id ?? doc.id,
+      ...label.length > 0 ? { label } : {},
+      params,
+      nodes
+    }
+  };
+}
+
+// src/characterSheet.ts
+var IDENTITY_INSTRUCTION = "This is the same person, same face, same identity as the reference image: keep the facial structure, features, hair, and proportions identical. Do not invent a new face.";
+var NEUTRAL_STUDIO = "Plain light-gray seamless studio background, no props, no text, no watermark, photorealistic, sharp focus.";
+var WARDROBE_STANDARD_PHRASE = "plain heather-gray crew-neck t-shirt";
+var WARDROBE_INSTRUCTION = `Wardrobe: the character is wearing a ${WARDROBE_STANDARD_PHRASE}, unbranded, with no logos, graphics, prints, or patterns.`;
+var FULL_BODY_WARDROBE_INSTRUCTION = `Wardrobe: the character is wearing a ${WARDROBE_STANDARD_PHRASE} and plain dark straight-leg trousers, unbranded, with no logos, graphics, prints, or patterns.`;
+function wardrobeInstructionForCategory(category) {
+  return category === "full-body" ? FULL_BODY_WARDROBE_INSTRUCTION : WARDROBE_INSTRUCTION;
+}
+function identityAnchor(description) {
+  return `Character identity (keep identical in every view): ${description.trim()}`;
+}
+function seedFacePrompt(description) {
+  return [
+    identityAnchor(description),
+    "Generate a clean front-facing reference portrait of this character: head-and-shoulders framing, neutral expression, looking straight at the camera. Square 1:1 crop.",
+    "Even, soft, neutral studio lighting.",
+    wardrobeInstructionForCategory("face"),
+    NEUTRAL_STUDIO,
+    IDENTITY_INSTRUCTION
+  ].join("\n\n");
+}
+var VIEW_INSTRUCTION = {
+  "three-quarter": "Three-quarter (45 degree) view: turn the head and upper body slightly to one side. Chest-up framing, square 1:1 crop. Even neutral studio lighting.",
+  profile: "Full side profile (90 degree) view. Chest-up framing, square 1:1 crop. Even neutral studio lighting.",
+  "full-body": "Full-body head-to-toe view: the character standing in a relaxed neutral pose, facing forward. 3:4 portrait crop with the whole figure in frame. Even neutral studio lighting.",
+  "close-up": "Tight front-facing close-up of the face, capturing fine facial detail. Square 1:1 crop. Even neutral studio lighting.",
+  "lighting-warm": "Front-facing head-and-shoulders portrait, square 1:1 crop, under warm golden-hour key lighting.",
+  "lighting-cool": "Front-facing head-and-shoulders portrait, square 1:1 crop, under cool blue-toned key lighting."
+};
+function turnaroundViewPrompt(view, seedDescription) {
+  return [
+    identityAnchor(seedDescription),
+    VIEW_INSTRUCTION[view],
+    wardrobeInstructionForCategory(view),
+    NEUTRAL_STUDIO,
+    IDENTITY_INSTRUCTION
+  ].join("\n\n");
+}
+var CHARACTER_SHEET_NODES = [
+  { nodeId: "seed", param: "seedPrompt", category: "face", label: "Seed face" },
+  { nodeId: "view-three-quarter", param: "threeQuarterPrompt", category: "three-quarter", label: "Three-quarter", view: "three-quarter" },
+  { nodeId: "view-profile", param: "profilePrompt", category: "profile", label: "Profile", view: "profile" },
+  { nodeId: "view-full-body", param: "fullBodyPrompt", category: "full-body", label: "Full body", view: "full-body" },
+  { nodeId: "view-close-up", param: "closeUpPrompt", category: "close-up", label: "Close-up", view: "close-up" },
+  { nodeId: "view-lighting-warm", param: "lightingWarmPrompt", category: "lighting-warm", label: "Warm lighting", view: "lighting-warm" },
+  { nodeId: "view-lighting-cool", param: "lightingCoolPrompt", category: "lighting-cool", label: "Cool lighting", view: "lighting-cool" }
+];
+var MINT_REFERENCE_CATEGORIES = Object.fromEntries(
+  CHARACTER_SHEET_NODES.map((n) => [n.nodeId, n.category])
+);
+function categoryForNode(nodeId) {
+  return MINT_REFERENCE_CATEGORIES[nodeId] ?? null;
+}
+function buildCharacterSheetParams(description) {
+  const params = {};
+  for (const node of CHARACTER_SHEET_NODES) {
+    params[node.param] = node.view ? turnaroundViewPrompt(node.view, description) : seedFacePrompt(description);
+  }
+  return params;
+}
+var CHARACTER_SHEET_ID = "character-sheet";
+var SEED_MODEL = "fal/nano-banana-2";
+var VIEW_MODEL = "fal/nano-banana-2-edit";
+function viewNode(n, aspectRatio) {
+  return {
+    id: n.nodeId,
+    task: "image-edit",
+    model: VIEW_MODEL,
+    inputs: {
+      prompt: { kind: "param", name: n.param },
+      inputImages: { kind: "ref", node: "seed", path: "url", wrap: "array" },
+      aspectRatio: { kind: "literal", value: aspectRatio }
+    }
+  };
+}
+var CHARACTER_SHEET_DEFINITION = {
+  version: { schema: 1 },
+  id: CHARACTER_SHEET_ID,
+  label: "Character Sheet (seed face -> turnaround)",
+  params: CHARACTER_SHEET_NODES.map((n) => ({
+    name: n.param,
+    type: "string",
+    required: true,
+    label: `${n.label} prompt`
+  })),
+  nodes: [
+    {
+      id: "seed",
+      task: "text-to-image",
+      model: SEED_MODEL,
+      inputs: {
+        prompt: { kind: "param", name: "seedPrompt" },
+        aspectRatio: { kind: "literal", value: "1:1" }
+      }
+    },
+    ...CHARACTER_SHEET_NODES.filter((n) => n.view !== void 0).map(
+      (n) => viewNode(n, n.category === "full-body" ? "3:4" : "1:1")
+    )
+  ]
+};
+function characterSheetDefinition(overrides) {
+  const def = structuredClone(CHARACTER_SHEET_DEFINITION);
+  if (overrides?.seedModel || overrides?.viewModel) {
+    def.nodes = def.nodes.map(
+      (node) => node.id === "seed" ? { ...node, model: overrides.seedModel ?? node.model } : { ...node, model: overrides.viewModel ?? node.model }
+    );
+  }
+  return def;
+}
+
+// src/media.ts
+import { readFile, stat } from "fs/promises";
+import { basename, resolve } from "path";
+import { fileURLToPath } from "url";
+var MAX_UPLOAD_BYTES = 25 * 1024 * 1024;
+function isHttpUrl(s) {
+  return /^https?:\/\//i.test(s);
+}
+async function loadImageSource(source, client) {
+  const trimmed = source.trim();
+  if (trimmed.length === 0) throw new ToolInputError("source is empty: pass a local file path or an http(s) URL");
+  if (isHttpUrl(trimmed)) {
+    const file2 = await client.downloadUrl(trimmed);
+    assertImage(file2, trimmed);
+    return file2;
+  }
+  const path = trimmed.startsWith("file://") ? fileURLToPath(trimmed) : resolve(trimmed);
+  let size;
+  try {
+    const s = await stat(path);
+    if (!s.isFile()) throw new ToolInputError(`not a file: ${path}`);
+    size = s.size;
+  } catch (err) {
+    if (err instanceof ToolInputError) throw err;
+    throw new ToolInputError(`cannot read ${path}: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  if (size > MAX_UPLOAD_BYTES) {
+    throw new ToolInputError(`${path} is ${size} bytes, above the ${MAX_UPLOAD_BYTES} byte upload limit`);
+  }
+  const bytes = await readFile(path);
+  const filename = basename(path);
+  const file = { data: new Blob([bytes], { type: mimeForFilename(filename) }), filename };
+  assertImage(file, path);
+  return file;
+}
+function assertImage(file, source) {
+  if (!file.data.type.startsWith("image/")) {
+    throw new ToolInputError(
+      `${source} does not look like an image (content type ${file.data.type || "unknown"}); the Studio only accepts image/* references`
+    );
+  }
+  if (file.data.size === 0) throw new ToolInputError(`${source} is empty (0 bytes)`);
+}
+
+// src/poll.ts
+var DEFAULT_TIMEOUT_MS = 6e5;
+var defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+async function pollUntil(what, fetchState, isDone, opts = {}) {
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const factor = opts.factor ?? 1.5;
+  const maxDelay = opts.maxDelayMs ?? 15e3;
+  const sleep = opts.sleep ?? defaultSleep;
+  const now = opts.now ?? Date.now;
+  const start = now();
+  let delay = opts.initialDelayMs ?? 2e3;
+  let last = await fetchState();
+  if (isDone(last)) return last;
+  for (; ; ) {
+    const elapsed = now() - start;
+    const remaining = timeoutMs - elapsed;
+    if (remaining <= 0) throw new PollTimeoutError(what, timeoutMs, last);
+    await sleep(Math.min(delay, remaining));
+    last = await fetchState();
+    if (isDone(last)) return last;
+    delay = Math.min(maxDelay, Math.round(delay * factor));
+  }
+}
+var TERMINAL_JOB_STATUSES = /* @__PURE__ */ new Set(["succeeded", "failed", "canceled"]);
+var TERMINAL_RUN_STATUSES = /* @__PURE__ */ new Set(["succeeded", "failed", "partial"]);
+function isJobTerminal(res) {
+  return TERMINAL_JOB_STATUSES.has(res.job.status);
+}
+function isRunTerminal(res) {
+  return TERMINAL_RUN_STATUSES.has(res.run.status);
+}
+function isRunParked(res) {
+  return res.run.status === "awaiting_decision";
+}
+function isRunSettledOrParked(res) {
+  return isRunTerminal(res) || isRunParked(res);
+}
+function waitForJob(client, jobId, opts) {
+  return pollUntil(`job ${jobId}`, () => client.getJob(jobId), isJobTerminal, opts);
+}
+function waitForRun(client, runId, opts) {
+  return pollUntil(`workflow run ${runId}`, () => client.getRun(runId), isRunSettledOrParked, opts);
+}
+function runCostUsd(res) {
+  return res.nodeRuns.reduce((sum, nr) => sum + (typeof nr.costUsd === "number" ? nr.costUsd : 0), 0);
+}
+function runFailureSummary(res) {
+  const parts = res.nodeRuns.filter((nr) => nr.status === "failed").map((nr) => `${nr.nodeId}: ${nr.errorMessage ?? "failed without a message"}`);
+  const runLevel = res.run.status === "succeeded" && typeof res.run.errorMessage === "string" ? res.run.errorMessage.trim() : "";
+  if (runLevel.length > 0) parts.push(runLevel);
+  return parts.length > 0 ? parts.join("; ") : null;
+}
+
+// src/recipes.ts
+var DEFAULT_SWAP_EDIT_MODEL = "fal/nano-banana-2-edit";
+var DEFAULT_SWAP_VIDEO_MODEL = "fal/seedance-pro-image-to-video";
+var KEYFRAME_SWAP_VIDEO_MODEL = "fal/kling-v2-5-image-to-video";
+var DEFAULT_SWAP_PROMPT = "Replace the person in the first image with the person from the second image. Keep the pose, framing, camera angle, clothing fit, lighting, background, and every other pixel of the scene identical. Match the face, hair, and body of the second image exactly. Photorealistic, no artifacts.";
+var DEFAULT_MOTION_PROMPT = "Natural, subtle motion that continues the scene: gentle camera movement, realistic body motion, consistent lighting. Keep the person identical to the still.";
+var SWAP_EDIT_NODE_ID = "edit";
+var SWAP_VIDEO_NODE_ID = "video";
+function defaultVideoModelFor(input) {
+  if (input.videoModel) return input.videoModel;
+  return input.endFrameUrl ? KEYFRAME_SWAP_VIDEO_MODEL : DEFAULT_SWAP_VIDEO_MODEL;
+}
+function buildCharacterSwapDefinition(input) {
+  const videoModel = defaultVideoModelFor(input);
+  return {
+    version: { schema: 1 },
+    id: "character-swap-still-to-video",
+    label: "Character swap (still edit -> image-to-video)",
+    params: [],
+    nodes: [
+      {
+        id: SWAP_EDIT_NODE_ID,
+        task: "image-edit",
+        model: input.editModel ?? DEFAULT_SWAP_EDIT_MODEL,
+        inputs: {
+          prompt: { kind: "literal", value: input.swapPrompt ?? DEFAULT_SWAP_PROMPT },
+          inputImages: { kind: "literal", value: [input.sceneFrameUrl, input.characterImageUrl] },
+          aspectRatio: { kind: "literal", value: input.aspectRatio ?? "16:9" }
+        }
+      },
+      {
+        id: SWAP_VIDEO_NODE_ID,
+        task: "image-to-video",
+        model: videoModel,
+        inputs: {
+          prompt: { kind: "literal", value: input.motionPrompt ?? DEFAULT_MOTION_PROMPT },
+          inputImageUrl: { kind: "ref", node: SWAP_EDIT_NODE_ID, path: "url" },
+          ...input.endFrameUrl ? { endImageUrl: { kind: "literal", value: input.endFrameUrl } } : {}
+        }
+      }
+    ]
+  };
+}
+var CHARACTER_REFERENCE_PREFERENCE = ["full-body", "three-quarter", "face"];
+function pickCharacterReferenceUrl(references) {
+  for (const category of CHARACTER_REFERENCE_PREFERENCE) {
+    const hit = references.find((r) => r.category === category && typeof r.url === "string" && r.url.length > 0);
+    if (hit) return { url: hit.url, category };
+  }
+  const any = references.find((r) => typeof r.url === "string" && r.url.length > 0);
+  return any ? { url: any.url, category: any.category } : null;
+}
+
+// src/toolDef.ts
+function defineTool(def) {
+  return def;
+}
+
+// src/workflowTools.ts
+import { randomUUID } from "crypto";
+import { z as z7 } from "zod";
+
+// src/workflow.ts
+import { z as z6 } from "zod";
+var SUMMARY_TEXT_CHARS = 80;
+var SKEW_HINT = "update @marlinjai/studio-mcp to a version that matches the Studio";
+var ContractError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ContractError";
+  }
+};
+function firstIssue(error) {
+  const issue = error.issues[0];
+  if (!issue) return "invalid";
+  const path = issue.path.map(String).join(".");
+  return path ? `${path}: ${issue.message}` : issue.message;
+}
+function parseDocument(raw, what) {
+  const r = WorkflowDocumentSchema.safeParse(raw);
+  if (!r.success) {
+    throw new ContractError(`${what} returned a workflow document this studio-mcp cannot read (${firstIssue(r.error)}); ${SKEW_HINT}`);
+  }
+  return r.data;
+}
+var OpsSchema = z6.array(OpSchema);
+function parseOps(raw, what) {
+  const r = OpsSchema.safeParse(raw);
+  if (!r.success) {
+    throw new ContractError(`${what} returned ops this studio-mcp cannot read (${firstIssue(r.error)}); ${SKEW_HINT}`);
+  }
+  return r.data;
+}
+function projectionOf(doc) {
+  const r = documentToDefinition(doc);
+  return r.ok ? { ok: true, issues: [] } : { ok: false, issues: r.issues };
+}
+function clipText(text) {
+  return text.length > SUMMARY_TEXT_CHARS ? text.slice(0, SUMMARY_TEXT_CHARS) : text;
+}
+function wireCounts(doc) {
+  const counts = /* @__PURE__ */ new Map();
+  const of = (id) => {
+    let c = counts.get(id);
+    if (!c) {
+      c = { in: 0, out: 0 };
+      counts.set(id, c);
+    }
+    return c;
+  };
+  for (const e of doc.edges) {
+    of(e.source).out += 1;
+    of(e.target).in += 1;
+  }
+  return counts;
+}
+function summarizeNode(node, wires) {
+  const base = { id: node.id, kind: node.kind, wires: { ...wires } };
+  if (node.label !== void 0) base.label = node.label;
+  switch (node.kind) {
+    case "task":
+      base.task = node.task;
+      base.model = node.model;
+      base.prompt = clipText(node.prompt);
+      base.promptLength = node.prompt.length;
+      if (node.activeGeneration !== void 0) base.activeGeneration = node.activeGeneration;
+      break;
+    case "prompt-source":
+      base.prompt = clipText(node.text);
+      base.promptLength = node.text.length;
+      break;
+    case "image-source":
+      base.imageUrl = clipText(node.imageUrl);
+      break;
+    case "input":
+      base.name = node.name;
+      base.type = node.type;
+      base.required = node.required;
+      if (node.cardinality !== void 0) base.cardinality = node.cardinality;
+      break;
+  }
+  return base;
+}
+function summarizeDocument(doc, meta) {
+  const wires = wireCounts(doc);
+  const summary = {
+    savedId: meta.savedId,
+    revision: meta.revision,
+    label: meta.label ?? doc.label,
+    nodes: doc.nodes.map((n) => summarizeNode(n, wires.get(n.id) ?? { in: 0, out: 0 })),
+    edgeCount: doc.edges.length,
+    groupCount: doc.groups.length,
+    projection: meta.projection ?? projectionOf(doc)
+  };
+  if (meta.lossy !== void 0) summary.lossy = meta.lossy;
+  if (meta.notes !== void 0) summary.notes = meta.notes;
+  return summary;
+}
+function touchedNodeIds(doc, applied, inverse) {
+  const touched = /* @__PURE__ */ new Set();
+  for (const op of applied) for (const id of opTouches(doc, op)) touched.add(id);
+  for (const op of inverse) for (const id of opTouches(doc, op)) touched.add(id);
+  const present = new Set(doc.nodes.map((n) => n.id));
+  const ordered = doc.nodes.map((n) => n.id).filter((id) => touched.has(id));
+  const removed = [...touched].filter((id) => !present.has(id)).sort();
+  return [...ordered, ...removed];
+}
+function affectedNodes(doc, ids) {
+  const wires = wireCounts(doc);
+  const byId = new Map(doc.nodes.map((n) => [n.id, n]));
+  return ids.map((id) => {
+    const node = byId.get(id);
+    return node ? summarizeNode(node, wires.get(id) ?? { in: 0, out: 0 }) : { id, removed: true };
+  });
+}
+
+// src/workflowTools.ts
+var savedId = z7.string().min(1).describe('The saved workflow id (it carries a "saved:" prefix), from studio_workflow_create or the Studio workflow list.');
+var opsSchema = PatchSchema.shape.ops.describe(
+  `The ops to apply in order, 1 to ${MAX_PATCH_OPS}: addNode, removeNode, setNodeProps, setNodeSetting, setBakedInput, connect, disconnect, exposeAsInput, freezeInput, setActiveGeneration, setLayout, group, ungroup, setGroupProps, setDocumentProps. Node ids are yours to choose (UUIDv7 recommended); a later op may reference an id added earlier in the same list.`
+);
+var paramsSchema = z7.record(z7.string(), z7.unknown()).describe("Run parameters by input-node name, checked against the declared inputs (unknown names, missing required values and wrong shapes are issues).");
+var isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+function compactTask(t, opts) {
+  const { settings: rawSettings, models: rawModels, ...rest } = t;
+  const settings = Array.isArray(rawSettings) ? rawSettings : [];
+  const models = Array.isArray(rawModels) ? rawModels : [];
+  return {
+    ...rest,
+    settingCount: settings.length,
+    modelCount: models.length,
+    ...opts.includeSettings ? { settings } : {},
+    ...opts.includeModels ? { models } : {}
+  };
+}
+function messageOf(body, ctx) {
+  return typeof body.message === "string" ? ctx.client.redact(body.message) : null;
+}
+function applyErrorOf(raw, ctx) {
+  const o = isRecord(raw) ? raw : {};
+  return {
+    opIndex: typeof o.opIndex === "number" ? o.opIndex : null,
+    code: typeof o.code === "string" ? o.code : null,
+    message: typeof o.message === "string" ? ctx.client.redact(o.message) : null
+  };
+}
+var REBASE_HINT = "Re-read the workflow (studio_workflow_get), rebase your ops on the current revision (node ids are stable) and apply again with that revision as baseRevision.";
+var RETRY_HINT = "The outcome of this attempt is unknown. Retry studio_workflow_apply with the SAME idempotencyKey and baseRevision: if the first attempt landed, the Studio returns its original result instead of applying the patch twice.";
+var NOT_EDITABLE_HINT = "This workflow is readable (studio_workflow_get) and runnable (studio_run_workflow with its savedId), but it cannot be patched. Build a new workflow with studio_workflow_create instead of trying to edit this one.";
+var LOSSY_HINT = "Read the notes: they name what the import drops for good. To go ahead, resend the SAME ops with acknowledgeLossy: true and a NEW idempotencyKey (the first patch materializes the imported document).";
+var IDEMPOTENCY_HINT = "This is not a replay: that key was used for a different patch. Send this patch again with a NEW idempotencyKey, on the revision above.";
+function stringList(raw, ctx) {
+  if (!Array.isArray(raw)) return null;
+  return raw.filter((n) => typeof n === "string").map((n) => ctx.client.redact(n));
+}
+function mapWriteFailure(err, ctx, info) {
+  if (!(err instanceof StudioApiError)) return null;
+  const body = isRecord(err.body) ? err.body : {};
+  const code = typeof body.code === "string" ? body.code : null;
+  if (err.status === 409 && code === "stale_revision" && info.savedId !== void 0) {
+    const doc = parseDocument(body.document, "PATCH 409 stale_revision");
+    const revision = typeof body.revision === "number" ? body.revision : null;
+    if (revision === null) {
+      throw new ContractError("PATCH 409 stale_revision carried no current revision; update @marlinjai/studio-mcp to a version that matches the Studio");
+    }
+    return {
+      ok: false,
+      code: "stale_revision",
+      revision,
+      summary: summarizeDocument(doc, { savedId: info.savedId, revision }),
+      hint: REBASE_HINT
+    };
+  }
+  if (err.status === 400 && code === "invalid_patch") {
+    return { ok: false, code: "invalid_patch", error: applyErrorOf(body.error, ctx) };
+  }
+  if (err.status === 403 && code === "forbidden") {
+    return {
+      ok: false,
+      code: "forbidden",
+      opIndex: typeof body.opIndex === "number" ? body.opIndex : null,
+      missingScope: typeof body.missingScope === "string" ? body.missingScope : null,
+      message: typeof body.message === "string" ? ctx.client.redact(body.message) : null
+    };
+  }
+  if (err.status === 422 && code === "not_editable") {
+    return { ok: false, code: "not_editable", issues: Array.isArray(body.issues) ? body.issues : [], message: messageOf(body, ctx), hint: NOT_EDITABLE_HINT };
+  }
+  if (err.status === 422 && code === "lossy_import") {
+    return { ok: false, code: "lossy_import", notes: stringList(body.notes, ctx) ?? [], message: messageOf(body, ctx), hint: LOSSY_HINT };
+  }
+  if (err.status === 422 && code === "idempotency_mismatch") {
+    const revision = typeof body.revision === "number" ? body.revision : null;
+    if (revision === null) {
+      throw new ContractError("PATCH 422 idempotency_mismatch carried no current revision; update @marlinjai/studio-mcp to a version that matches the Studio");
+    }
+    return { ok: false, code: "idempotency_mismatch", revision, message: messageOf(body, ctx), hint: IDEMPOTENCY_HINT };
+  }
+  if (info.idempotencyKey !== void 0 && (err.status === 0 || err.status >= 500)) {
+    return {
+      ok: false,
+      code: err.status === 0 ? "network_error" : "server_error",
+      status: err.status,
+      message: err.message,
+      idempotencyKey: info.idempotencyKey,
+      hint: RETRY_HINT
+    };
+  }
+  return null;
+}
+var studioWorkflowDescribe = defineTool({
+  name: "studio_workflow_describe",
+  description: "Describe the node vocabulary before authoring a workflow (read-only, free). Returns { tasks: [{ task, label, family, modality, jobKind, runnable, output, inputs: [{ port, wireable, cardinality, binding }], prompt: { needed, required, key } | null, settingCount, modelCount }], inputTypes (what an input node can declare), opTypes (what studio_workflow_apply accepts), limits: { maxPatchOps } }. Settings knobs and the model catalog are large, so they are dropped unless includeSettings / includeModels is true; filter with tasks to keep the result small.",
+  inputSchema: {
+    tasks: z7.array(z7.string().min(1)).min(1).optional().describe('Only these task ids (e.g. ["text-to-image", "image-to-video"]). An unknown id is an error that lists the known ones.'),
+    includeSettings: z7.boolean().default(false).describe("Include each task's settings knobs (key, type, range, default)."),
+    includeModels: z7.boolean().default(false).describe("Include the model catalog per task (id, label, provider, cost, isDefault).")
+  },
+  annotations: { readOnlyHint: true },
+  handler: async (args, ctx) => {
+    const res = await ctx.client.describeNodeTypes();
+    let tasks = res.tasks;
+    if (args.tasks) {
+      const known = new Set(res.tasks.map((t) => t.task));
+      const unknown = args.tasks.filter((t) => !known.has(t));
+      if (unknown.length > 0) {
+        throw new ToolInputError(`unknown task${unknown.length > 1 ? "s" : ""} ${unknown.join(", ")}; known tasks: ${[...known].join(", ")}`);
+      }
+      const wanted = new Set(args.tasks);
+      tasks = res.tasks.filter((t) => wanted.has(t.task));
+    }
+    return {
+      tasks: tasks.map((t) => compactTask(t, args)),
+      inputTypes: res.inputTypes,
+      opTypes: res.opTypes,
+      limits: res.limits
+    };
+  }
+});
+var studioWorkflowGet = defineTool({
+  name: "studio_workflow_get",
+  description: "Read a saved workflow. By default returns a summary: { savedId, revision, label, readOnly, nodes: [{ id, kind, label?, task?, model?, prompt? (first 80 chars, plus promptLength), imageUrl?, name?, type?, required?, wires: { in, out } }], edgeCount, groupCount, projection: { ok, issues } } where revision is the baseRevision for studio_workflow_apply and projection says whether the workflow can run and why not. A workflow the canvas cannot represent comes back as { readOnly: true, definitionNodeCount, projection, hint } with no nodes: it is readable and runnable (studio_run_workflow with its savedId) but not patchable. needsLossyAcknowledgement: true means its first patch must carry acknowledgeLossy: true. full: true returns the whole response instead; use it only when you need every field.",
+  inputSchema: {
+    savedId,
+    full: z7.boolean().default(false).describe("Return the whole response (the full document, or the stored definition of a read-only workflow) instead of the summary.")
+  },
+  annotations: { readOnlyHint: true },
+  handler: async (args, ctx) => {
+    const res = await ctx.client.getWorkflowDocument(args.savedId);
+    if (args.full) return res;
+    if (res.readOnly === true || res.document === null) {
+      const definition = isRecord(res.definition) ? res.definition : null;
+      const nodes = definition && Array.isArray(definition.nodes) ? definition.nodes : null;
+      return {
+        savedId: res.savedId,
+        revision: res.revision,
+        label: typeof res.label === "string" ? res.label : "",
+        readOnly: true,
+        projection: res.projection ?? { ok: false, issues: [] },
+        ...nodes ? { definitionNodeCount: nodes.length } : {},
+        hint: NOT_EDITABLE_HINT
+      };
+    }
+    const doc = parseDocument(res.document, `GET workflow ${args.savedId}`);
+    const notes = Array.isArray(res.notes) ? res.notes : void 0;
+    const lossy = res.lossy === true;
+    return {
+      ...summarizeDocument(doc, {
+        savedId: res.savedId,
+        revision: res.revision,
+        ...typeof res.label === "string" ? { label: res.label } : {},
+        ...res.projection ? { projection: res.projection } : {},
+        ...lossy ? { lossy: true } : {},
+        ...notes && notes.length > 0 ? { notes } : {}
+      }),
+      readOnly: false,
+      // The server refuses the FIRST patch of a lossy import until the client
+      // acknowledges the notes; say so here rather than after a failed patch.
+      ...lossy && res.materialized === false ? { needsLossyAcknowledgement: true } : {}
+    };
+  }
+});
+var studioWorkflowCreate = defineTool({
+  name: "studio_workflow_create",
+  description: 'Create a new saved workflow by applying ops to an empty document (call studio_workflow_describe first for the task vocabulary and ports). Returns { ok: true, savedId, revision, summary } (the studio_workflow_get summary shape, its projection tells you whether it can run). A bad patch returns { ok: false, code: "invalid_patch", error: { opIndex, code, message } } naming the offending op; a missing credential scope returns { ok: false, code: "forbidden", opIndex, missingScope }. Creating is free; running it with studio_run_workflow (savedId) is what spends money.',
+  inputSchema: {
+    ops: opsSchema,
+    label: LabelSchema.optional().describe("Display label of the saved workflow."),
+    projectId: z7.string().min(1).optional().describe("Project id from studio_list_projects; omit for the default project.")
+  },
+  handler: async (args, ctx) => {
+    let res;
+    try {
+      res = await ctx.client.createWorkflow({
+        ops: args.ops,
+        ...args.label !== void 0 ? { label: args.label } : {},
+        ...args.projectId !== void 0 ? { projectId: args.projectId } : {}
+      });
+    } catch (err) {
+      const mapped = mapWriteFailure(err, ctx, {});
+      if (mapped) return mapped;
+      throw err;
+    }
+    const doc = parseDocument(res.document, "POST workflow");
+    return {
+      ok: true,
+      savedId: res.savedId,
+      revision: res.revision,
+      summary: summarizeDocument(doc, {
+        savedId: res.savedId,
+        revision: res.revision,
+        ...res.projection ? { projection: res.projection } : {}
+      })
+    };
+  }
+});
+var studioWorkflowApply = defineTool({
+  name: "studio_workflow_apply",
+  description: 'Change a saved workflow atomically: the ops are applied all-or-nothing on top of baseRevision (the revision from studio_workflow_get, studio_workflow_create or your last apply). Success returns { ok: true, savedId, revision, appliedCount, inverseCount, affectedNodes (summaries of the nodes the patch touched, removed ones as { id, removed: true }), projection: { ok, issues }, idempotencyKey, replayed }. Every refusal comes back as { ok: false, code, hint } you can act on rather than an error: "stale_revision" (re-read, rebase your ops, apply again on the revision returned), "invalid_patch" (error.opIndex names the offending op), "forbidden" (opIndex plus the missingScope your credential needs), "not_editable" (this workflow is readable and runnable but cannot be patched), "lossy_import" (read notes, then resend with acknowledgeLossy: true and a NEW idempotencyKey), "idempotency_mismatch" (that key belongs to a different patch: use a fresh one), and "network_error" / "server_error" which you retry with the SAME idempotencyKey so the patch can never apply twice.',
+  inputSchema: {
+    savedId,
+    baseRevision: PatchSchema.shape.baseRevision.describe("The revision the ops were written against. The Studio refuses a stale one with stale_revision."),
+    ops: opsSchema,
+    idempotencyKey: PatchSchema.shape.idempotencyKey.describe(
+      "Generated (a UUID) when omitted and returned in the result. Pass the same key only to retry the SAME patch after a network or server failure."
+    ),
+    acknowledgeLossy: z7.boolean().optional().describe(
+      'Only after a "lossy_import" refusal: confirms you read its notes and accept that materializing this pre-command-model workflow drops the bindings they name, for good. Send it with a NEW idempotencyKey.'
+    )
+  },
+  handler: async (args, ctx) => {
+    const idempotencyKey = args.idempotencyKey ?? randomUUID();
+    let res;
+    try {
+      res = await ctx.client.applyWorkflowPatch(args.savedId, {
+        baseRevision: args.baseRevision,
+        ops: args.ops,
+        idempotencyKey,
+        ...args.acknowledgeLossy !== void 0 ? { acknowledgeLossy: args.acknowledgeLossy } : {}
+      });
+    } catch (err) {
+      const mapped = mapWriteFailure(err, ctx, { savedId: args.savedId, idempotencyKey });
+      if (mapped) return mapped;
+      throw err;
+    }
+    const doc = parseDocument(res.document, "PATCH workflow");
+    const applied = parseOps(res.applied, "PATCH workflow (applied)");
+    const inverse = parseOps(res.inverse, "PATCH workflow (inverse)");
+    return {
+      ok: true,
+      savedId: args.savedId,
+      revision: res.revision,
+      appliedCount: applied.length,
+      inverseCount: inverse.length,
+      affectedNodes: affectedNodes(doc, touchedNodeIds(doc, applied, inverse)),
+      projection: res.projection ?? projectionOf(doc),
+      idempotencyKey,
+      // True when this key replayed an earlier result: the patch was already
+      // applied, nothing happened a second time (E3).
+      replayed: res.replayed === true
+    };
+  }
+});
+var studioWorkflowValidate = defineTool({
+  name: "studio_workflow_validate",
+  description: "Dry-run without side effects or cost: check a document (given inline, or fetched by savedId) with optional ops applied on top, and optional run params against the projected definition. Returns exactly what the Studio reports: { apply: { ok, error? } | null, document: { ok, code?, message? }, projection: { ok, issues, params? }, run: { ok, issues, optionalEmpty? } | null }. Use it before a large studio_workflow_apply and before studio_run_workflow, so missing required inputs, unknown params and unrunnable nodes surface before any money is spent.",
+  inputSchema: {
+    document: WorkflowDocumentSchema.optional().describe("The document to validate. Either this or savedId."),
+    savedId: savedId.optional().describe("Fetch this saved workflow first and validate against its current document. Either this or document, not both."),
+    ops: PatchSchema.shape.ops.optional().describe("Ops to apply to the document before projecting it (the same vocabulary and limits as studio_workflow_apply)."),
+    params: paramsSchema.optional()
+  },
+  annotations: { readOnlyHint: true },
+  handler: async (args, ctx) => {
+    if (args.document && args.savedId) throw new ToolInputError("pass either `document` or `savedId`, not both");
+    let document = args.document;
+    if (!document) {
+      if (!args.savedId) throw new ToolInputError("provide a `document` or a `savedId` to validate");
+      const saved = await ctx.client.getWorkflowDocument(args.savedId);
+      if (saved.readOnly === true || saved.document === null) {
+        throw new ToolInputError(
+          `workflow ${args.savedId} has no document to validate: the canvas cannot represent its stored definition (studio_workflow_get shows readOnly: true and why). It is still runnable with studio_run_workflow.`
+        );
+      }
+      document = parseDocument(saved.document, `GET workflow ${args.savedId}`);
+    }
+    return ctx.client.validateWorkflow({
+      document,
+      ...args.ops ? { ops: args.ops } : {},
+      ...args.params ? { params: args.params } : {}
+    });
+  }
+});
+var studioWorkflowScreenshot = defineTool({
+  name: "studio_workflow_screenshot",
+  description: "Render a saved workflow's document as a diagram (labelled boxes and wires, positioned by the document's own layout) so you can see the graph you just built, the Figma get_screenshot equivalent. NOT a pixel-exact preview of the real canvas: a plain diagnostic diagram for checking topology (is everything wired the way I meant, did that addNode land where I expected). Returns { url, width, height }; the url is a signed Storage Brain link, valid for 24h. Free, read-only.",
+  inputSchema: {
+    savedId
+  },
+  annotations: { readOnlyHint: true },
+  handler: async (args, ctx) => {
+    return ctx.client.getWorkflowScreenshot(args.savedId);
+  }
+});
+var WORKFLOW_TOOLS = [
+  studioWorkflowDescribe,
+  studioWorkflowGet,
+  studioWorkflowCreate,
+  studioWorkflowApply,
+  studioWorkflowValidate,
+  studioWorkflowScreenshot
+];
+
+// src/tools.ts
+var slug = z8.string().regex(/^[a-z0-9-]+$/, "lowercase letters, numbers and hyphens only").describe("URL-safe identifier: lowercase letters, numbers, hyphens.");
+var waitSeconds = z8.number().int().min(1).max(3600).default(DEFAULT_TIMEOUT_MS / 1e3).describe("Maximum seconds to wait before giving up and returning the id to poll later. Default 600.");
+var httpUrl = z8.string().url().refine((u) => /^https?:\/\//i.test(u), "must be an http(s) URL");
+function pollOpts(ctx, timeoutSec) {
+  return { ...ctx.poll, timeoutMs: timeoutSec * 1e3 };
+}
+function projectJob(res) {
+  return {
+    jobId: res.job.id,
+    status: res.job.status,
+    model: res.job.model ?? null,
+    costUsd: res.job.costUsd ?? null,
+    errorMessage: res.job.errorMessage ?? null,
+    url: res.resultAsset?.url ?? null,
+    urls: (res.resultAssets ?? []).map((a) => a.url).filter((u) => typeof u === "string")
+  };
+}
+function projectNodeRun(nr) {
+  return {
+    nodeId: nr.nodeId,
+    status: nr.status,
+    url: nr.resultUrl ?? nr.results?.[0]?.url ?? null,
+    kind: nr.results?.[0]?.kind ?? null,
+    text: nr.results?.[0]?.text ?? null,
+    costUsd: nr.costUsd ?? null,
+    errorMessage: nr.errorMessage ?? null,
+    // Only a parked judge node carries these: the pictures a person is being
+    // asked to choose between, each with the `generationId` a decision names.
+    ...nr.candidates && nr.candidates.length > 0 ? { candidates: nr.candidates } : {}
+  };
+}
+function projectRun(res) {
+  const parked = res.nodeRuns.filter((nr) => nr.status === "awaiting_decision");
+  return {
+    runId: res.run.id,
+    status: res.run.status,
+    savedId: res.run.savedId ?? null,
+    costUsd: runCostUsd(res),
+    nodes: res.nodeRuns.map(projectNodeRun),
+    failure: runFailureSummary(res),
+    ...parked.length > 0 ? {
+      waiting: {
+        reason: "This run is parked on a human decision and will not move until a person decides. Do not keep polling, and do not decide on their behalf: show the candidates and ask. Submit their answer with studio_decide_judge.",
+        nodeIds: parked.map((nr) => nr.nodeId)
+      }
+    } : {},
+    // Run-level failure text. For a recipe run this is where a POST-RUN EFFECT
+    // failure lands (the images generated, but creating the character or
+    // attaching a reference did not): the run still reads `succeeded`, so
+    // without this an agent would believe a character exists that does not.
+    errorMessage: res.run.errorMessage ?? null
+  };
+}
+function nodeUrl(res, nodeId) {
+  const nr = res.nodeRuns.find((n) => n.nodeId === nodeId);
+  return nr?.resultUrl ?? nr?.results?.[0]?.url ?? null;
+}
+var studioListProjects = defineTool({
+  name: "studio_list_projects",
+  description: 'List the Studio projects visible to this API key (id, slug, name). A projectId is required by studio_run_workflow, studio_mint_character and studio_replace_character_in_video; call this first to find it (the usual one is slug "default").',
+  inputSchema: {},
+  annotations: { readOnlyHint: true },
+  handler: async (_args, ctx) => {
+    const { projects } = await ctx.client.listProjects();
+    return { projects: projects.map((p) => ({ id: p.id, slug: p.slug, name: p.name })) };
+  }
+});
+var studioGenerateImage = defineTool({
+  name: "studio_generate_image",
+  description: "Generate one image with a brand's style applied (the Studio injects the brand's style prefix and reference images server-side). Optionally pin a minted character so its identity references are injected too. Submits a job and, when wait=true (default), polls until it finishes and returns the signed image URL and cost in USD. With wait=false it returns the jobId immediately for studio_get_job. Typical cost ~$0.04 per image.",
+  inputSchema: {
+    brandSlug: slug.describe('Brand to apply (e.g. "lola-stories"). Required by the API.'),
+    brandMode: z8.string().optional().describe('Optional brand mode (e.g. "illustration"); modes are defined per brand.'),
+    prompt: z8.string().min(1).describe("What to generate. The brand style prefix is prepended server-side."),
+    characterSlug: slug.optional().describe("Optional minted character whose identity references are injected."),
+    model: z8.string().optional().describe('Image model id (e.g. "kie/nano-banana-2", "fal/nano-banana-2"). Omit for the Studio default.'),
+    aspectRatio: z8.string().optional().describe('Aspect ratio such as "1:1", "16:9", "3:4".'),
+    imageSize: z8.string().optional().describe('Provider size hint, e.g. "1K", "2K".'),
+    seed: z8.number().int().optional(),
+    candidateCount: z8.number().int().min(1).max(4).optional().describe("Number of candidates (1 to 4)."),
+    wait: z8.boolean().default(true).describe("Poll until the job finishes (default true)."),
+    waitSeconds
+  },
+  handler: async (args, ctx) => {
+    const settings = {};
+    if (args.model) settings.model = args.model;
+    if (args.aspectRatio) settings.aspectRatio = args.aspectRatio;
+    if (args.imageSize) settings.imageSize = args.imageSize;
+    if (args.seed !== void 0) settings.seed = args.seed;
+    if (args.candidateCount !== void 0) settings.candidateCount = args.candidateCount;
+    const submitted = await ctx.client.generate({
+      brandSlug: args.brandSlug,
+      ...args.brandMode ? { brandMode: args.brandMode } : {},
+      prompt: args.prompt,
+      ...args.characterSlug ? { characterSlug: args.characterSlug } : {},
+      ...Object.keys(settings).length > 0 ? { settings } : {}
+    });
+    if (!args.wait) return { jobId: submitted.jobId, kind: submitted.kind, status: "queued" };
+    const done = await waitForJob(ctx.client, submitted.jobId, pollOpts(ctx, args.waitSeconds));
+    const out = projectJob(done);
+    if (done.job.status !== "succeeded") {
+      throw new Error(`Job ${submitted.jobId} ${done.job.status}: ${done.job.errorMessage ?? "no error message from the API"}`);
+    }
+    return { ...out, kind: submitted.kind };
+  }
+});
+var studioGetJob = defineTool({
+  name: "studio_get_job",
+  description: "Fetch the status of a generation job by jobId: status (queued, running, succeeded, failed, canceled), cost, model, error message and a freshly signed result URL once it succeeded. Set wait=true to block until the job reaches a terminal state.",
+  inputSchema: {
+    jobId: z8.string().min(1),
+    wait: z8.boolean().default(false).describe("Poll until terminal (default false: return the current state)."),
+    waitSeconds
+  },
+  annotations: { readOnlyHint: true },
+  handler: async (args, ctx) => {
+    const res = args.wait ? await waitForJob(ctx.client, args.jobId, pollOpts(ctx, args.waitSeconds)) : await ctx.client.getJob(args.jobId);
+    return projectJob(res);
+  }
+});
+var studioListCharacters = defineTool({
+  name: "studio_list_characters",
+  description: "List all minted characters (slug, name, descriptor prompt, default model). Use a slug with studio_get_character for its reference images, or with studio_generate_image to render that character.",
+  inputSchema: {},
+  annotations: { readOnlyHint: true },
+  handler: async (_args, ctx) => {
+    const { characters } = await ctx.client.listCharacters();
+    return { characters };
+  }
+});
+var studioGetCharacter = defineTool({
+  name: "studio_get_character",
+  description: "Fetch one character by slug with its full context: descriptor and negative prompts plus every frozen reference image (category such as face, three-quarter, profile, full-body, close-up, lighting-warm, lighting-cool; freshly signed URL). The full-body or face reference URL is what studio_replace_character_in_video needs as characterImageUrl.",
+  inputSchema: { slug },
+  annotations: { readOnlyHint: true },
+  handler: async (args, ctx) => {
+    const { character } = await ctx.client.getCharacter(args.slug);
+    return { character };
+  }
+});
+var studioCreateCharacter = defineTool({
+  name: "studio_create_character",
+  description: "Create an empty character record (no reference images yet). Prefer studio_mint_character, which generates the 7-view identity sheet and freezes it as references in one call. Use this only when you will upload your own reference images. Fails with 409 if the slug exists.",
+  inputSchema: {
+    name: z8.string().min(1).describe('Display name, e.g. "Bruno Hartmann".'),
+    slug,
+    descriptorPrompt: z8.string().min(1).describe("The identity description prepended to every generation that uses this character."),
+    negativePrompt: z8.string().optional(),
+    defaultModel: z8.string().optional().describe("Default image model id for this character.")
+  },
+  handler: async (args, ctx) => {
+    const { character } = await ctx.client.createCharacter({
+      name: args.name,
+      slug: args.slug,
+      descriptorPrompt: args.descriptorPrompt,
+      ...args.negativePrompt !== void 0 ? { negativePrompt: args.negativePrompt } : {},
+      ...args.defaultModel !== void 0 ? { defaultModel: args.defaultModel } : {}
+    });
+    return { character };
+  }
+});
+var studioMintCharacter = defineTool({
+  name: "studio_mint_character",
+  description: "Mint a consistent character from a text description: runs the curated character-sheet workflow (seed face with fal/nano-banana-2, then six identity-pinned edits with fal/nano-banana-2-edit: three-quarter, profile, full-body, close-up, warm lighting, cool lighting), waits for it, creates the character, and uploads the 7 views as frozen references with the right categories. Returns the slug, reference count, per-view URLs, the runId and total cost (about $0.30). The description should cover face, hair, age, build and distinguishing features; wardrobe is standardized to a plain gray tee. Takes 2 to 5 minutes.",
+  inputSchema: {
+    projectId: z8.string().min(1).describe("Project id from studio_list_projects."),
+    name: z8.string().min(1).describe("Display name."),
+    slug,
+    description: z8.string().min(10).describe("Seed identity description (face, hair, age, build, distinguishing features)."),
+    descriptorPrompt: z8.string().optional().describe("Override for the character's stored descriptor prompt. Defaults to the description."),
+    negativePrompt: z8.string().optional(),
+    defaultModel: z8.string().optional(),
+    seedModel: z8.string().optional().describe("Override the seed text-to-image model (default fal/nano-banana-2)."),
+    viewModel: z8.string().optional().describe("Override the view image-edit model (default fal/nano-banana-2-edit)."),
+    visibility: z8.enum(["listed", "unlisted"]).optional().describe("Whether the run shows in the Studio workflow list."),
+    waitSeconds
+  },
+  handler: async (args, ctx) => {
+    const definition = characterSheetDefinition({
+      ...args.seedModel ? { seedModel: args.seedModel } : {},
+      ...args.viewModel ? { viewModel: args.viewModel } : {}
+    });
+    const params = buildCharacterSheetParams(args.description);
+    const started = await ctx.client.runWorkflow({
+      projectId: args.projectId,
+      definition,
+      params,
+      ...args.visibility ? { visibility: args.visibility } : {}
+    });
+    const run = await waitForRun(ctx.client, started.runId, pollOpts(ctx, args.waitSeconds));
+    const views = CHARACTER_SHEET_NODES.map((n) => ({ ...n, url: nodeUrl(run, n.nodeId) }));
+    const missing = views.filter((v) => !v.url);
+    if (missing.length > 0) {
+      const failure = runFailureSummary(run);
+      throw new Error(
+        `Character sheet run ${started.runId} ended ${run.run.status} with ${missing.length} of ${views.length} views missing (${missing.map((v) => v.nodeId).join(", ")}).${failure ? ` Failures: ${failure}.` : ""} No character was created; cost so far $${runCostUsd(run).toFixed(2)}.`
+      );
+    }
+    const { character } = await ctx.client.createCharacter({
+      name: args.name,
+      slug: args.slug,
+      descriptorPrompt: args.descriptorPrompt ?? args.description,
+      ...args.negativePrompt !== void 0 ? { negativePrompt: args.negativePrompt } : {},
+      ...args.defaultModel !== void 0 ? { defaultModel: args.defaultModel } : {}
+    });
+    const references = [];
+    for (const view of views) {
+      const file = await ctx.client.downloadUrl(view.url);
+      const category = MINT_REFERENCE_CATEGORIES[view.nodeId];
+      const { reference } = await ctx.client.uploadCharacterReference(args.slug, {
+        file,
+        category,
+        label: view.label
+      });
+      references.push({ nodeId: view.nodeId, category, referenceId: reference.id, url: reference.url });
+    }
+    return {
+      slug: character.slug,
+      name: character.name,
+      runId: started.runId,
+      referenceCount: references.length,
+      references,
+      costUsd: runCostUsd(run)
+    };
+  }
+});
+var studioCreateBrand = defineTool({
+  name: "studio_create_brand",
+  description: "Create a brand (a style preset: name, slug, optional style prefix prepended to every prompt, optional free-text context). Upload reference images afterwards with studio_upload_brand_reference. Fails with 409 if the slug exists.",
+  inputSchema: {
+    name: z8.string().min(1),
+    slug,
+    stylePrefix: z8.string().optional().describe("Text prepended to every prompt generated under this brand."),
+    context: z8.string().optional().describe("Markdown brand context (tone, palette, do/don't)."),
+    defaultModel: z8.string().optional(),
+    maxReferenceImages: z8.number().int().min(0).max(8).optional()
+  },
+  handler: async (args, ctx) => {
+    const { config } = await ctx.client.createBrand({
+      name: args.name,
+      slug: args.slug,
+      ...args.stylePrefix !== void 0 ? { stylePrefix: args.stylePrefix } : {},
+      ...args.context !== void 0 ? { context: args.context } : {},
+      ...args.defaultModel !== void 0 ? { defaultModel: args.defaultModel } : {},
+      ...args.maxReferenceImages !== void 0 ? { maxReferenceImages: args.maxReferenceImages } : {}
+    });
+    return { brand: config };
+  }
+});
+var studioUploadBrandReference = defineTool({
+  name: "studio_upload_brand_reference",
+  description: `Upload one reference image to a brand's library from a local file path or an http(s) URL. The Studio converts it to a 512px WebP and injects it into generations under that brand (up to the brand's maxReferenceImages). Category groups references (default "general"); tags and a 1 to 10 quality score are optional.`,
+  inputSchema: {
+    brandSlug: slug,
+    source: z8.string().min(1).describe("Local file path or http(s) URL of an image."),
+    category: z8.string().optional().describe('Library category, default "general".'),
+    label: z8.string().optional().describe("Optional file name / label."),
+    tags: z8.array(z8.string()).optional(),
+    score: z8.number().int().min(1).max(10).optional()
+  },
+  handler: async (args, ctx) => {
+    const file = await loadImageSource(args.source, ctx.client);
+    const { reference } = await ctx.client.uploadBrandReference(args.brandSlug, {
+      file,
+      ...args.category ? { category: args.category } : {},
+      ...args.label ? { label: args.label } : {},
+      ...args.tags ? { tags: args.tags } : {},
+      ...args.score !== void 0 ? { score: args.score } : {}
+    });
+    return { reference };
+  }
+});
+var workflowDefinitionSchema = WorkflowDefinitionSchema.describe(
+  'Inline workflow DAG: { id, label?, params?: [{ name, type: string|number|boolean|json, required?, label?, description?, inputType?, cardinality?: one|many, default? }], nodes: [{ id, task (one of the model tasks listed), model (catalog id, e.g. fal/nano-banana-2-edit), inputs, retry? }] }. Node inputs are bindings: {kind:"literal",value}, {kind:"param",name,wrap?:"array"} or {kind:"ref",node,path:"url",wrap?:"array"}. Image-edit nodes take inputImages (array, use wrap:"array" on a ref or param); image-to-video nodes take inputImageUrl (string).'
+);
+var studioRunWorkflow = defineTool({
+  name: "studio_run_workflow",
+  description: `Run a generation workflow DAG. Pass an inline definition (nodes of provider calls wired by ref bindings; this is what the hosted Studio accepts) or the savedId of a workflow saved in the Studio (the Studio runs that workflow's current document, exactly what the canvas would run). Params fill {kind:"param"} bindings. Returns the runId plus per-node status, URLs and cost; with wait=true (default) it blocks until the run is terminal (succeeded, failed, partial). Each node becomes a paid job.`,
+  inputSchema: {
+    projectId: z8.string().min(1).describe("Project id from studio_list_projects."),
+    definition: workflowDefinitionSchema.optional(),
+    savedId: z8.string().optional().describe("Id of a saved workflow (from studio_workflow_create, studio_workflow_get or a listed run) to run instead of an inline definition. An unknown id is a 404 naming it; a workflow that is not runnable yet comes back as not_runnable with per-node issues."),
+    params: z8.record(z8.string(), z8.unknown()).optional().describe("Values for the definition's params."),
+    nodeIds: z8.array(z8.string()).optional().describe("Run only this subset of nodes (requires an inline `definition` or a `savedId`)."),
+    runs: z8.number().int().min(1).max(8).optional().describe("Repeat a node subset N times (1 to 8)."),
+    visibility: z8.enum(["listed", "unlisted"]).optional().describe("Whether the run shows in the Studio workflow list."),
+    budgetUsd: z8.number().nonnegative().optional().describe(
+      'S6b: hard cap on the estimated cost, verified server-side before anything is created. An unverifiable estimate (a credits-only or unpriced executing node) refuses too, never proceeds silently. Refusal: { code: "budget_exceeded", estimate }. For `runs`>1 this is the AGGREGATE cap across every iteration.'
+    ),
+    confirm: z8.boolean().optional().describe(
+      'S6b: bypasses the confirmation threshold for this one request (a flat $10 today) when the estimate meets or exceeds it. Without this, such a run refuses with { code: "confirmation_required", estimate }.'
+    ),
+    wait: z8.boolean().default(true),
+    waitSeconds
+  },
+  handler: async (args, ctx) => {
+    if (!args.definition && !args.savedId) {
+      throw new ToolInputError("provide an inline `definition` or a `savedId`");
+    }
+    if (args.nodeIds && args.nodeIds.length > 0 && !args.definition && !args.savedId) {
+      throw new ToolInputError("running a node subset requires an inline `definition` or a `savedId`");
+    }
+    const started = await ctx.client.runWorkflow({
+      projectId: args.projectId,
+      ...args.definition ? { definition: args.definition } : {},
+      ...args.params ? { params: args.params } : {},
+      ...args.nodeIds && args.nodeIds.length > 0 ? { nodeIds: args.nodeIds } : {},
+      ...args.runs !== void 0 ? { runs: args.runs } : {},
+      ...args.savedId ? { savedId: args.savedId } : {},
+      ...args.visibility ? { visibility: args.visibility } : {},
+      ...args.budgetUsd !== void 0 ? { budgetUsd: args.budgetUsd } : {},
+      ...args.confirm !== void 0 ? { confirm: args.confirm } : {}
+    });
+    if (!args.wait) return { runId: started.runId, runIds: started.runIds, status: started.status };
+    const run = await waitForRun(ctx.client, started.runId, pollOpts(ctx, args.waitSeconds));
+    return { ...projectRun(run), runIds: started.runIds };
+  }
+});
+var studioGetRun = defineTool({
+  name: "studio_get_run",
+  description: "Fetch a workflow run by runId: overall status (pending, running, succeeded, failed, partial, awaiting_decision), total cost, and per-node status, result URL, cost and error message. Set wait=true to block until the run settles. A run at awaiting_decision is parked on a person at a judge node: waiting returns immediately with a `waiting` block naming the node and its candidates, because polling can never clear it; ask the user to choose and submit their answer with studio_decide_judge.",
+  inputSchema: {
+    runId: z8.string().min(1),
+    wait: z8.boolean().default(false),
+    waitSeconds
+  },
+  annotations: { readOnlyHint: true },
+  handler: async (args, ctx) => {
+    const res = args.wait ? await waitForRun(ctx.client, args.runId, pollOpts(ctx, args.waitSeconds)) : await ctx.client.getRun(args.runId);
+    return projectRun(res);
+  }
+});
+var studioDecideJudge = defineTool({
+  name: "studio_decide_judge",
+  description: "Submit a PERSON'S decision on a parked judge node (a run whose status is awaiting_decision). Approving that candidate resumes the run from that node; rejecting fails the node and stops the branch. Never call this on your own judgement: a judge node exists precisely because a human is meant to look, so show them the candidates from studio_get_run's `waiting` block and pass on the answer they give. `candidate.generationId` comes from that same block, and may be omitted only when the node has exactly one candidate.",
+  inputSchema: {
+    runId: z8.string().min(1),
+    nodeId: z8.string().min(1),
+    verdict: z8.enum(["approved", "rejected"]),
+    candidate: z8.object({ generationId: z8.string().min(1), index: z8.number().int().min(0).optional() }).optional(),
+    reason: z8.string().max(500).optional()
+  },
+  annotations: { destructiveHint: false, idempotentHint: false },
+  handler: async (args, ctx) => {
+    await ctx.client.decideJudgeNode(args.runId, args.nodeId, {
+      verdict: args.verdict,
+      ...args.candidate ? { candidate: args.candidate } : {},
+      ...args.reason ? { reason: args.reason } : {}
+    });
+    return projectRun(await ctx.client.getRun(args.runId));
+  }
+});
+var studioGetRunOutput = defineTool({
+  name: "studio_get_run_output",
+  description: "Get a FRESH signed URL for one node's output of a workflow run (signed URLs expire; call this when an earlier URL stopped working). Returns url, kind (image, video, model3d) and mime.",
+  inputSchema: {
+    runId: z8.string().min(1),
+    nodeId: z8.string().min(1)
+  },
+  annotations: { readOnlyHint: true },
+  handler: async (args, ctx) => {
+    const res = await ctx.client.getRunNodeUrl(args.runId, args.nodeId);
+    return { runId: args.runId, nodeId: args.nodeId, url: res.url, kind: res.kind ?? null, mime: res.mime ?? null };
+  }
+});
+var studioReplaceCharacterInVideo = defineTool({
+  name: "studio_replace_character_in_video",
+  description: "Put a minted character into a video shot using the proven still-swap recipe: (1) an image-edit node (fal/nano-banana-2-edit) replaces the person in a scene FRAME with the character, keeping everything else identical (16:9); (2) an image-to-video node animates that still (default fal/seedance-pro-image-to-video; with endFrameUrl it switches to fal/kling-v2-5-image-to-video and binds the end keyframe so the clip lands on it). Give the character as characterSlug (its full-body reference is used, falling back to three-quarter then face) or as an explicit characterReferenceUrl. Requires a frame URL: extract a representative frame from the video yourself first (this tool does not decode video). Waits for both nodes and returns stillUrl, videoUrl, runId and costUsd (about $0.70 per take). Keep generated cuts under 5 seconds and budget 2 to 3 takes per shot. Do not use video-to-video swap models on dark or handheld footage; this recipe replaces that.",
+  inputSchema: {
+    projectId: z8.string().min(1).describe("Project id from studio_list_projects."),
+    sceneFrameUrl: httpUrl.describe("Public or signed URL of ONE frame of the target shot (png/jpg)."),
+    characterSlug: slug.optional().describe("Minted character to insert; its full-body reference (fallback three-quarter, face) is resolved automatically."),
+    characterReferenceUrl: httpUrl.optional().describe("Explicit character reference image URL (use instead of characterSlug)."),
+    endFrameUrl: httpUrl.optional().describe("Optional second approved keyframe for the END of the clip. Switches the video model to Kling (start + end frame) unless videoModel is set explicitly."),
+    swapPrompt: z8.string().optional().describe("Override the still-swap edit prompt."),
+    motionPrompt: z8.string().optional().describe("Override the motion description for the video node."),
+    videoModel: z8.string().optional().describe(`Image-to-video model id. Default ${DEFAULT_SWAP_VIDEO_MODEL}, or ${KEYFRAME_SWAP_VIDEO_MODEL} when endFrameUrl is given.`),
+    editModel: z8.string().default(DEFAULT_SWAP_EDIT_MODEL).describe("Image-edit model id for the still swap."),
+    aspectRatio: z8.string().default("16:9"),
+    visibility: z8.enum(["listed", "unlisted"]).optional(),
+    waitSeconds
+  },
+  handler: async (args, ctx) => {
+    if (!args.characterSlug && !args.characterReferenceUrl) {
+      throw new ToolInputError("provide characterSlug or characterReferenceUrl");
+    }
+    let characterImageUrl = args.characterReferenceUrl;
+    let characterReferenceCategory = null;
+    if (!characterImageUrl) {
+      const { character } = await ctx.client.getCharacter(args.characterSlug);
+      const picked = pickCharacterReferenceUrl(character.references ?? []);
+      if (!picked) {
+        throw new ToolInputError(
+          `character ${args.characterSlug} has no reference images with a URL; mint it first (studio_mint_character) or pass characterReferenceUrl`
+        );
+      }
+      characterImageUrl = picked.url;
+      characterReferenceCategory = picked.category;
+    }
+    const videoModel = defaultVideoModelFor({ endFrameUrl: args.endFrameUrl, videoModel: args.videoModel });
+    const definition = buildCharacterSwapDefinition({
+      sceneFrameUrl: args.sceneFrameUrl,
+      characterImageUrl,
+      ...args.endFrameUrl ? { endFrameUrl: args.endFrameUrl } : {},
+      ...args.swapPrompt ? { swapPrompt: args.swapPrompt } : {},
+      ...args.motionPrompt ? { motionPrompt: args.motionPrompt } : {},
+      editModel: args.editModel,
+      videoModel,
+      aspectRatio: args.aspectRatio
+    });
+    const started = await ctx.client.runWorkflow({
+      projectId: args.projectId,
+      definition,
+      ...args.visibility ? { visibility: args.visibility } : {}
+    });
+    const run = await waitForRun(ctx.client, started.runId, pollOpts(ctx, args.waitSeconds));
+    const stillUrl = nodeUrl(run, SWAP_EDIT_NODE_ID);
+    const videoUrl = nodeUrl(run, SWAP_VIDEO_NODE_ID);
+    if (!stillUrl || !videoUrl) {
+      const failure = runFailureSummary(run);
+      throw new Error(
+        `Character swap run ${started.runId} ended ${run.run.status}: ${!stillUrl ? "no swapped still" : "still ok"}, ${!videoUrl ? "no video" : "video ok"}.${failure ? ` Failures: ${failure}.` : ""} Cost so far $${runCostUsd(run).toFixed(2)}.`
+      );
+    }
+    return {
+      runId: started.runId,
+      status: run.run.status,
+      stillUrl,
+      videoUrl,
+      costUsd: runCostUsd(run),
+      videoModel,
+      characterReferenceUrl: characterImageUrl,
+      characterReferenceCategory,
+      stillNodeId: SWAP_EDIT_NODE_ID,
+      videoNodeId: SWAP_VIDEO_NODE_ID
+    };
+  }
+});
+var studioGetSpend = defineTool({
+  name: "studio_get_spend",
+  description: `Read the spend ledger: total USD and job counts for today, the last 7 days and the last 30 days, plus the most recent paid actions. tzOffsetMinutes is the viewer's Date.getTimezoneOffset() so "today" rolls at local midnight (default UTC).`,
+  inputSchema: {
+    tzOffsetMinutes: z8.number().int().min(-840).max(840).optional()
+  },
+  annotations: { readOnlyHint: true },
+  handler: async (args, ctx) => {
+    const ledger = await ctx.client.getSpend(args.tzOffsetMinutes);
+    return ledger;
+  }
+});
+var studioGetUsage = defineTool({
+  name: "studio_get_usage",
+  description: "Read this key's tenant against its plan (docs/plans/2026-08-21-studio-api-keys-and-quotas.md): month-to-date USD spend and job count, the plan's monthly cap and requests-per-minute limit (null = unlimited), and a per-model breakdown, most expensive first. Call this before a large batch to check remaining budget, or after a 402/429 to see what tripped. Every /api/generate, /api/v1/workflows/run and /api/try-on call carries this key's tenant. usedUsd includes in-flight (not yet settled) job estimates, so it can go DOWN as well as up: a job that later fails releases its estimate.",
+  inputSchema: {},
+  annotations: { readOnlyHint: true },
+  handler: async (_args, ctx) => {
+    return ctx.client.getUsage();
+  }
+});
+var studioListPublished = defineTool({
+  name: "studio_list_published",
+  description: "List every published recipe: { recipes: [{ slug, label, publishedRevision, updatedAt, hasEffects }] }. hasEffects tells you whether running it will create/attach an entity record (a character, a brand reference) on success, versus a pure generation recipe. Free, read-only.",
+  inputSchema: {},
+  annotations: { readOnlyHint: true },
+  handler: async (_args, ctx) => ctx.client.listPublished()
+});
+var studioDescribePublished = defineTool({
+  name: "studio_describe_published",
+  description: "Describe one published recipe by slug: { slug, definition, hasEffects }. definition is the FROZEN workflow (params, node shapes) exactly as it was at publish time, never the live authoring document, which may have moved on since. Read this before studio_run_published to know what params it needs. Free, read-only.",
+  inputSchema: {
+    slug: z8.string().min(1).describe("The recipe slug, from studio_list_published.")
+  },
+  annotations: { readOnlyHint: true },
+  handler: async (args, ctx) => {
+    const res = await ctx.client.describePublished(args.slug);
+    return res;
+  }
+});
+var studioRunPublished = defineTool({
+  name: "studio_run_published",
+  description: `Run a published recipe by slug. Runs its FROZEN definition (studio_describe_published shows exactly what it needs); params fill the definition's own {kind:"param"} bindings. On success, the recipe's declared post-run effects fire automatically (e.g. character minting creates the character and attaches its reference views); effects never fire on a failed or partial run, by design. Returns the runId plus per-node status, URLs and cost; with wait=true (default) it blocks until the run is terminal. Each node becomes a paid job. The same $10 confirm-gate as studio_run_workflow applies: an estimate at or over the threshold refuses with { code: "confirmation_required", estimate } unless confirm: true is set.`,
+  inputSchema: {
+    slug: z8.string().min(1).describe("The recipe slug, from studio_list_published."),
+    projectId: z8.string().min(1).describe("Project id from studio_list_projects."),
+    params: z8.record(z8.string(), z8.unknown()).optional().describe("Values for the recipe's params (see studio_describe_published)."),
+    budgetUsd: z8.number().nonnegative().optional().describe(
+      'Hard cap on the estimated cost, verified server-side before anything is created. An unverifiable estimate (a credits-only or unpriced executing node) refuses too. Refusal: { code: "budget_exceeded", estimate }.'
+    ),
+    confirm: z8.boolean().optional().describe(
+      'Bypasses the confirmation threshold for this one request (a flat $10 today) when the estimate meets or exceeds it. Without this, such a run refuses with { code: "confirmation_required", estimate }.'
+    ),
+    wait: z8.boolean().default(true),
+    waitSeconds
+  },
+  handler: async (args, ctx) => {
+    const started = await ctx.client.runPublished(args.slug, {
+      projectId: args.projectId,
+      ...args.params ? { params: args.params } : {},
+      ...args.budgetUsd !== void 0 ? { budgetUsd: args.budgetUsd } : {},
+      ...args.confirm !== void 0 ? { confirm: args.confirm } : {}
+    });
+    if (!args.wait) return { runId: started.runId, status: started.status };
+    const run = await waitForRun(ctx.client, started.runId, pollOpts(ctx, args.waitSeconds));
+    return projectRun(run);
+  }
+});
+var TOOLS = [
+  studioListProjects,
+  studioGenerateImage,
+  studioGetJob,
+  studioListCharacters,
+  studioGetCharacter,
+  studioCreateCharacter,
+  studioMintCharacter,
+  studioCreateBrand,
+  studioUploadBrandReference,
+  studioRunWorkflow,
+  studioGetRun,
+  studioDecideJudge,
+  studioGetRunOutput,
+  studioReplaceCharacterInVideo,
+  studioGetSpend,
+  studioListPublished,
+  studioDescribePublished,
+  studioRunPublished,
+  studioGetUsage,
+  ...WORKFLOW_TOOLS
+];
+var TOOL_NAMES = TOOLS.map((t) => t.name);
+function toolResult(value) {
+  const text = JSON.stringify(value, null, 2);
+  return {
+    content: [{ type: "text", text }],
+    structuredContent: value && typeof value === "object" && !Array.isArray(value) ? value : { value }
+  };
+}
+function toolError(message) {
+  return {
+    isError: true,
+    content: [{ type: "text", text: message }]
+  };
+}
+async function invokeTool(def, args, ctx) {
+  try {
+    const parsed = z8.object(def.inputSchema).parse(args ?? {});
+    const value = await def.handler(parsed, ctx);
+    return toolResult(value);
+  } catch (err) {
+    return toolError(ctx.client.redact(errorMessage(err)));
+  }
+}
+function registerTools(server, ctx) {
+  for (const def of TOOLS) {
+    server.registerTool(
+      def.name,
+      {
+        description: def.description,
+        inputSchema: def.inputSchema,
+        ...def.annotations ? { annotations: def.annotations } : {}
+      },
+      (async (args) => invokeTool(def, args, ctx))
+    );
+  }
+}
+
+// src/server.ts
+var SERVER_NAME = "lumitra-studio";
+var SERVER_VERSION = "0.1.0";
+function createStudioMcpServer(opts = {}) {
+  const config = opts.config ?? resolveConfig(opts.env ?? process.env);
+  const client = new StudioClient(config, {
+    ...opts.fetch ? { fetch: opts.fetch } : {},
+    userAgent: `${SERVER_NAME}-mcp/${SERVER_VERSION}`
+  });
+  const server = new McpServer(
+    { name: SERVER_NAME, version: SERVER_VERSION },
+    {
+      instructions: [
+        "Lumitra Studio: brand-consistent image generation, character minting, workflow runs and the still-swap video recipe over the hosted Studio API.",
+        "Start with studio_list_projects to get a projectId. Every generation costs real money (roughly $0.04 per image, $0.30 per character mint, $0.70 per video take); check studio_get_spend when in doubt.",
+        "Long jobs: tools wait by default (up to timeoutSeconds, 600 by default) and return ids you can poll with studio_get_job / studio_get_run if they time out.",
+        "Authoring a workflow is free and revisioned: studio_workflow_describe for the vocabulary, studio_workflow_create to build one from ops, studio_workflow_apply to change it on top of a baseRevision (a stale_revision result means re-read, rebase, retry), studio_workflow_validate to dry-run before spending, then studio_run_workflow with its savedId."
+      ].join(" ")
+    }
+  );
+  registerTools(server, { client, ...opts.poll ? { poll: opts.poll } : {} });
+  return { server, client };
+}
+
+// src/cli.ts
+import { createServer as createHttpServer } from "http";
+import { randomUUID as randomUUID2 } from "crypto";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+function parseArgs(argv) {
+  const args = { http: false, port: 3939, host: "127.0.0.1", help: false, version: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--http") args.http = true;
+    else if (a === "--port" || a === "-p") {
+      const v = Number(argv[++i]);
+      if (!Number.isInteger(v) || v < 0 || v > 65535) throw new Error(`invalid --port ${argv[i]}`);
+      args.port = v;
+    } else if (a.startsWith("--port=")) {
+      const v = Number(a.slice("--port=".length));
+      if (!Number.isInteger(v) || v < 0 || v > 65535) throw new Error(`invalid ${a}`);
+      args.port = v;
+    } else if (a === "--host") args.host = argv[++i] ?? args.host;
+    else if (a.startsWith("--host=")) args.host = a.slice("--host=".length);
+    else if (a === "--help" || a === "-h") args.help = true;
+    else if (a === "--version" || a === "-v") args.version = true;
+    else throw new Error(`unknown argument ${a}`);
+  }
+  return args;
+}
+var USAGE = `studio-mcp ${SERVER_VERSION}: MCP server for Lumitra Studio
+
+Usage:
+  studio-mcp                     stdio transport (default)
+  studio-mcp --http [--port N]   Streamable HTTP on http://127.0.0.1:N/mcp (default port 3939)
+  studio-mcp --http --host 0.0.0.0 --port 3939
+
+Environment:
+  LUMITRA_STUDIO_API_KEY         bearer token (required; legacy LUMITRA_STUDIO_SERVICE_TOKEN accepted)
+  LUMITRA_STUDIO_BASE_URL        default https://studio.lumitra.co
+
+Tools: ${TOOL_NAMES.join(", ")}
+`;
+async function runStdio() {
+  const { server } = createStudioMcpServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  process.stderr.write(`[${SERVER_NAME}] stdio transport ready (${TOOL_NAMES.length} tools)
+`);
+}
+function createHttpHandler() {
+  resolveConfig();
+  return async (req, res) => {
+    const url = new URL(req.url ?? "/", "http://localhost");
+    if (url.pathname === "/healthz") {
+      res.writeHead(200, { "content-type": "application/json" }).end(JSON.stringify({ ok: true, name: SERVER_NAME, version: SERVER_VERSION }));
+      return;
+    }
+    if (url.pathname !== "/mcp") {
+      res.writeHead(404, { "content-type": "application/json" }).end(JSON.stringify({ error: "not found; use POST /mcp" }));
+      return;
+    }
+    const { server } = createStudioMcpServer();
+    const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: void 0 });
+    res.on("close", () => {
+      void transport.close();
+      void server.close();
+    });
+    try {
+      await server.connect(transport);
+      await transport.handleRequest(req, res);
+    } catch (err) {
+      process.stderr.write(`[${SERVER_NAME}] request failed: ${err instanceof Error ? err.message : String(err)}
+`);
+      if (!res.headersSent) {
+        res.writeHead(500, { "content-type": "application/json" }).end(
+          JSON.stringify({ jsonrpc: "2.0", error: { code: -32603, message: "internal error" }, id: null })
+        );
+      }
+    }
+  };
+}
+async function runHttp(args) {
+  const handler = createHttpHandler();
+  const httpServer = createHttpServer((req, res) => void handler(req, res));
+  await new Promise((resolvePromise, reject) => {
+    httpServer.once("error", reject);
+    httpServer.listen(args.port, args.host, () => resolvePromise());
+  });
+  const addr = httpServer.address();
+  const port = typeof addr === "object" && addr ? addr.port : args.port;
+  process.stderr.write(`[${SERVER_NAME}] Streamable HTTP on http://${args.host}:${port}/mcp (${TOOL_NAMES.length} tools, instance ${randomUUID2().slice(0, 8)})
+`);
+  const shutdown = () => {
+    httpServer.close(() => process.exit(0));
+    setTimeout(() => process.exit(0), 2e3).unref();
+  };
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+}
+async function main(argv = process.argv.slice(2)) {
+  let args;
+  try {
+    args = parseArgs(argv);
+  } catch (err) {
+    process.stderr.write(`${err instanceof Error ? err.message : String(err)}
+
+${USAGE}`);
+    process.exit(2);
+  }
+  if (args.help) {
+    process.stdout.write(USAGE);
+    return;
+  }
+  if (args.version) {
+    process.stdout.write(`${SERVER_VERSION}
+`);
+    return;
+  }
+  try {
+    if (args.http) await runHttp(args);
+    else await runStdio();
+  } catch (err) {
+    if (err instanceof ConfigError) {
+      process.stderr.write(`[${SERVER_NAME}] ${err.message}
+`);
+      process.exit(1);
+    }
+    process.stderr.write(`[${SERVER_NAME}] fatal: ${err instanceof Error ? err.message : String(err)}
+`);
+    process.exit(1);
+  }
+}
+var invokedDirectly = typeof process.argv[1] === "string" && /(^|[\\/])(cli\.(js|ts|mjs)|studio-mcp)$/.test(process.argv[1]);
+if (invokedDirectly) {
+  void main();
+}
+export {
+  CHARACTER_SHEET_DEFINITION,
+  CHARACTER_SHEET_NODES,
+  ConfigError,
+  ContractError,
+  DEFAULT_BASE_URL,
+  DEFAULT_MOTION_PROMPT,
+  DEFAULT_SWAP_EDIT_MODEL,
+  DEFAULT_SWAP_PROMPT,
+  DEFAULT_SWAP_VIDEO_MODEL,
+  DEFAULT_TIMEOUT_MS,
+  MINT_REFERENCE_CATEGORIES,
+  PollTimeoutError,
+  SERVER_NAME,
+  SERVER_VERSION,
+  SUMMARY_TEXT_CHARS,
+  StudioApiError,
+  StudioClient,
+  TOOLS,
+  TOOL_NAMES,
+  ToolInputError,
+  WORKFLOW_TOOLS,
+  affectedNodes,
+  buildCharacterSheetParams,
+  buildCharacterSwapDefinition,
+  categoryForNode,
+  characterSheetDefinition,
+  createHttpHandler,
+  createStudioMcpServer,
+  invokeTool,
+  main,
+  parseArgs,
+  parseDocument,
+  parseOps,
+  pollUntil,
+  projectionOf,
+  redactSecret,
+  registerTools,
+  resolveConfig,
+  seedFacePrompt,
+  studioWorkflowApply,
+  studioWorkflowCreate,
+  studioWorkflowDescribe,
+  studioWorkflowGet,
+  studioWorkflowScreenshot,
+  studioWorkflowValidate,
+  summarizeDocument,
+  summarizeNode,
+  touchedNodeIds,
+  turnaroundViewPrompt,
+  waitForJob,
+  waitForRun
+};
+//# sourceMappingURL=index.js.map