@marlinjai/studio-mcp 0.1.0 → 0.1.1

package/README.md

@@ -101,7 +101,7 @@ The token is held in memory only. It is never logged, never serialized into a re
 | `studio_workflow_screenshot` | Render a saved workflow's document as a diagram (labelled boxes and wires, positioned by the document's own layout), the Figma `get_screenshot` equivalent for a workflow graph. Not a pixel-exact canvas preview, a diagnostic diagram for checking topology. Returns `{ url, width, height }` (a 24h signed link). Free, read-only. |
 | `studio_list_published` | List every published recipe: `{ recipes: [{ slug, label, publishedRevision, updatedAt, hasEffects }] }`. `hasEffects` tells you whether running it creates/attaches an entity record (a character, a brand reference) on success, versus a pure generation recipe. Free, read-only. |
 | `studio_describe_published` | 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. Read this before `studio_run_published` to know what params it needs. Free, read-only. |
-| `studio_run_published` | Run a published recipe by slug against its frozen definition; `params` fill the definition's own param bindings. On success, the recipe's declared post-run effects fire automatically (e.g. minting creates the character and attaches its reference views); effects never fire on a failed or partial run. Each node is a paid job. |
+| `studio_run_published` | Run a published recipe by slug against its frozen definition; `params` fill the definition's own param bindings. On success, the recipe's declared post-run effects fire automatically (e.g. minting creates the character and attaches its reference views); effects never fire on a failed, partial or cancelled run. Each node is a paid job. |
 
 All waiting tools accept `waitSeconds` (default 600) and back off between polls (2s doubling up to 15s). A timeout never cancels anything server-side: the tool error carries the id so the agent can poll again.
 
@@ -159,7 +159,7 @@ Two workflows behave differently from a document built through this contract:
 
 A **recipe** is a workflow that has been *published* under a stable public slug: its document and an optional declared list of post-run effects (create a character, attach a reference image, create a brand) are frozen together at publish time. `studio_list_published` / `studio_describe_published` / `studio_run_published` are the derived, read-only-until-you-run surface over every recipe that exists: the same three tools serve every recipe ever published, so the surface never grows as recipes are added.
 
-Running a recipe (`studio_run_published`) always executes the FROZEN definition, never the live authoring document (which may have moved on since publish). If every node in the run succeeds, the recipe's declared effects fire automatically and exactly once; a failed or partial run never triggers them, so a broken run can never leave a half-created character or a reference attached to nothing. Publishing a workflow (setting the slug and the effect list) is not yet exposed as an MCP tool: it is done through the HTTP API (`POST /api/v1/workflows/:savedId/publish`) or on the canvas.
+Running a recipe (`studio_run_published`) always executes the FROZEN definition, never the live authoring document (which may have moved on since publish). If every node in the run succeeds, the recipe's declared effects fire automatically and exactly once; a failed, partial or cancelled run (one somebody stopped) never triggers them, so a broken run can never leave a half-created character or a reference attached to nothing. Publishing a workflow (setting the slug and the effect list) is not yet exposed as an MCP tool: it is done through the HTTP API (`POST /api/v1/workflows/:savedId/publish`) or on the canvas.
 
 `studio_mint_character` and `studio_replace_character_in_video` (above) are today still hand-written tools, not recipes; migrating them onto published recipe twins is planned but not yet done, so both surfaces currently coexist.
 

package/dist/cli.js

@@ -213,8 +213,8 @@ var StudioClient = class {
   }
   /** 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`);
+  getWorkflowScreenshot(savedId2, opts = {}) {
+    return this.json("GET", `/api/v1/workflows/${encodeURIComponent(savedId2)}/screenshot${projectQuery(opts.projectId)}`);
   }
   // ── Recipes (S10): published workflow + closed post-run effect list ──
   publishWorkflow(savedId2, body) {
@@ -239,9 +239,10 @@ var StudioClient = class {
   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)}`);
+  /** `savedId` carries a `saved:` prefix; the colon is URL-encoded. `projectId`
+   * names the project the workflow lives in; absent, the Studio's default. */
+  getWorkflowDocument(savedId2, opts = {}) {
+    return this.json("GET", `/api/v1/workflows/${encodeURIComponent(savedId2)}${projectQuery(opts.projectId)}`);
   }
   /** Create a document by applying `ops` to an empty one (the same code path as apply). */
   createWorkflow(body) {
@@ -412,6 +413,9 @@ function mimeForFilename(name) {
       return "application/octet-stream";
   }
 }
+function projectQuery(projectId) {
+  return projectId === void 0 ? "" : `?projectId=${encodeURIComponent(projectId)}`;
+}
 
 // src/tools.ts
 import { z as z8 } from "zod";
@@ -634,6 +638,7 @@ 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 CollapsedSchema = z3.boolean();
 var TaskNodeSchema = z3.object({
   id: IdSchema,
   kind: z3.literal("task"),
@@ -654,13 +659,15 @@ var TaskNodeSchema = z3.object({
   bakedInputs: z3.record(KeySchema, LiteralBindingSchema).default({}),
   /** The generation id that feeds downstream. Absent = latest (D4). */
   activeGeneration: IdSchema.optional(),
-  label: LabelSchema.optional()
+  label: LabelSchema.optional(),
+  collapsed: CollapsedSchema.optional()
 });
 var PromptSourceNodeSchema = z3.object({
   id: IdSchema,
   kind: z3.literal("prompt-source"),
   text: PromptTextSchema.default(""),
-  label: LabelSchema.optional()
+  label: LabelSchema.optional(),
+  collapsed: CollapsedSchema.optional()
 });
 var ImageSourceNodeSchema = z3.object({
   id: IdSchema,
@@ -671,7 +678,8 @@ var ImageSourceNodeSchema = z3.object({
   /** The Storage Brain asset id, when known (E18: every image input resolves to
    * an asset id). */
   assetId: AssetIdSchema.optional(),
-  label: LabelSchema.optional()
+  label: LabelSchema.optional(),
+  collapsed: CollapsedSchema.optional()
 });
 var InputNodeSchema = z3.object({
   id: IdSchema,
@@ -686,7 +694,8 @@ var InputNodeSchema = z3.object({
   /** Used when a run omits the input. Never null: absent means no default. */
   default: JsonNonNullValueSchema.optional(),
   label: LabelSchema.optional(),
-  description: DescriptionSchema.optional()
+  description: DescriptionSchema.optional(),
+  collapsed: CollapsedSchema.optional()
 });
 var DocNodeSchema = z3.discriminatedUnion("kind", [
   TaskNodeSchema,
@@ -704,6 +713,18 @@ var DocGroupSchema = z3.object({
   label: LabelSchema.optional(),
   nodeIds: z3.array(IdSchema).min(1)
 });
+var EDGE_ROUTINGS = ["curved", "orthogonal"];
+var EdgeRoutingSchema = z3.enum(EDGE_ROUTINGS);
+var WireRouteSchema = z3.object({
+  from: PositionSchema,
+  to: PositionSchema,
+  points: z3.array(PositionSchema).max(64)
+});
+var DocumentViewSchema = z3.object({
+  edgeRouting: EdgeRoutingSchema.optional(),
+  /** Routed wires from the last Arrange, keyed by `edgeKey`. */
+  wires: z3.record(z3.string().max(512), WireRouteSchema).optional()
+});
 var WorkflowDocumentSchema = z3.object({
   schema: z3.number().int().positive(),
   id: IdSchema,
@@ -711,7 +732,10 @@ var WorkflowDocumentSchema = z3.object({
   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([])
+  groups: z3.array(DocGroupSchema).max(500).default([]),
+  /** Display preferences; absent on every document written before they
+   * existed (additive, so `DOCUMENT_SCHEMA_VERSION` is unchanged). */
+  view: DocumentViewSchema.optional()
 });
 function edgeKey(e) {
   return JSON.stringify([e.source, e.target, e.port]);
@@ -1480,16 +1504,19 @@ var TaskNodePropsSchema = z4.object({
   task: z4.enum(MODEL_TASKS),
   model: ModelIdSchema,
   prompt: PromptTextSchema,
-  label: LabelSchema.nullable()
+  label: LabelSchema.nullable(),
+  collapsed: CollapsedSchema.nullable()
 }).partial().strict();
 var PromptSourcePropsSchema = z4.object({
   text: PromptTextSchema,
-  label: LabelSchema.nullable()
+  label: LabelSchema.nullable(),
+  collapsed: CollapsedSchema.nullable()
 }).partial().strict();
 var ImageSourcePropsSchema = z4.object({
   imageUrl: UrlSchema,
   assetId: AssetIdSchema.nullable(),
-  label: LabelSchema.nullable()
+  label: LabelSchema.nullable(),
+  collapsed: CollapsedSchema.nullable()
 }).partial().strict();
 var InputNodePropsSchema = z4.object({
   name: InputNameSchema,
@@ -1498,14 +1525,19 @@ var InputNodePropsSchema = z4.object({
   cardinality: z4.enum(["one", "many"]).nullable(),
   default: JsonNonNullValueSchema.nullable(),
   label: LabelSchema.nullable(),
-  description: DescriptionSchema.nullable()
+  description: DescriptionSchema.nullable(),
+  collapsed: CollapsedSchema.nullable()
 }).partial().strict();
 var GroupPropsSchema = z4.object({
   label: LabelSchema.nullable(),
   nodeIds: z4.array(IdSchema).min(1)
 }).partial().strict();
 var DocumentPropsSchema = z4.object({
-  label: LabelSchema
+  label: LabelSchema,
+  /** Display preferences (`view.edgeRouting`); null clears the whole
+   * object. The object is replaced, not merged: pass every field you want
+   * kept. */
+  view: DocumentViewSchema.strict().nullable()
 }).partial().strict();
 var AddNodeOpSchema = z4.object({
   type: z4.literal("addNode"),
@@ -2076,7 +2108,7 @@ async function pollUntil(what, fetchState, isDone, opts = {}) {
   }
 }
 var TERMINAL_JOB_STATUSES = /* @__PURE__ */ new Set(["succeeded", "failed", "canceled"]);
-var TERMINAL_RUN_STATUSES = /* @__PURE__ */ new Set(["succeeded", "failed", "partial"]);
+var TERMINAL_RUN_STATUSES = /* @__PURE__ */ new Set(["succeeded", "failed", "partial", "cancelled"]);
 function isJobTerminal(res) {
   return TERMINAL_JOB_STATUSES.has(res.job.status);
 }
@@ -2409,11 +2441,12 @@ var studioWorkflowGet = defineTool({
   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,
+    projectId: z7.string().min(1).optional().describe("Project id from studio_list_projects the workflow lives in; omit for the default project."),
     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);
+    const res = await ctx.client.getWorkflowDocument(args.savedId, args.projectId !== void 0 ? { projectId: args.projectId } : {});
     if (args.full) return res;
     if (res.readOnly === true || res.document === null) {
       const definition = isRecord(res.definition) ? res.definition : null;
@@ -2486,6 +2519,7 @@ var studioWorkflowApply = defineTool({
   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,
+    projectId: z7.string().min(1).optional().describe("Project id from studio_list_projects the workflow lives in; omit for the default project."),
     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(
@@ -2500,6 +2534,7 @@ var studioWorkflowApply = defineTool({
     let res;
     try {
       res = await ctx.client.applyWorkflowPatch(args.savedId, {
+        ...args.projectId !== void 0 ? { projectId: args.projectId } : {},
         baseRevision: args.baseRevision,
         ops: args.ops,
         idempotencyKey,
@@ -2534,16 +2569,18 @@ var studioWorkflowValidate = defineTool({
   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."),
+    projectId: z7.string().min(1).optional().describe("Project id from studio_list_projects the saved workflow lives in (only with savedId); omit for the default project."),
     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");
+    if (args.projectId !== void 0 && !args.savedId) throw new ToolInputError("`projectId` only applies when fetching by `savedId`");
     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);
+      const saved = await ctx.client.getWorkflowDocument(args.savedId, args.projectId !== void 0 ? { projectId: args.projectId } : {});
       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.`
@@ -2562,11 +2599,12 @@ 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
+    savedId,
+    projectId: z7.string().min(1).optional().describe("Project id from studio_list_projects the workflow lives in; omit for the default project.")
   },
   annotations: { readOnlyHint: true },
   handler: async (args, ctx) => {
-    return ctx.client.getWorkflowScreenshot(args.savedId);
+    return ctx.client.getWorkflowScreenshot(args.savedId, args.projectId !== void 0 ? { projectId: args.projectId } : {});
   }
 });
 var WORKFLOW_TOOLS = [
@@ -2599,6 +2637,8 @@ function projectJob(res) {
 function projectNodeRun(nr) {
   return {
     nodeId: nr.nodeId,
+    // The node-run (generation) id: what `upstreamGenerations` pins.
+    id: nr.id ?? null,
     status: nr.status,
     url: nr.resultUrl ?? nr.results?.[0]?.url ?? null,
     kind: nr.results?.[0]?.kind ?? null,
@@ -2856,13 +2896,16 @@ var workflowDefinitionSchema = WorkflowDefinitionSchema.describe(
 );
 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.`,
+  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, cancelled). Each node becomes a paid job. Use an inline definition ONLY for the first batch of a new deliverable (one workflow, a node per item, a stable label); a follow-up on an existing item belongs in that saved workflow as a new node (studio_workflow_apply: addNode plus connect from the node it refines) run here with savedId and nodeIds, because every listed inline run is saved as its own workflow.`,
   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`)."),
+    upstreamGenerations: z8.record(z8.string(), z8.string()).optional().describe(
+      'Pin WHICH generation of an upstream node feeds this subset run: { "<upstream node id>": "<node-run id>" } (the per-node `id` that studio_get_run returns). A verified pin is reused even when the planner has no matching cache key for it (an inline first batch, or a node edited and reverted), so a follow-up node wired from an earlier generation runs against exactly that image. An unknown id is refused naming the node, never silently replaced by the latest.'
+    ),
     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(
@@ -2886,6 +2929,7 @@ var studioRunWorkflow = defineTool({
       ...args.definition ? { definition: args.definition } : {},
       ...args.params ? { params: args.params } : {},
       ...args.nodeIds && args.nodeIds.length > 0 ? { nodeIds: args.nodeIds } : {},
+      ...args.upstreamGenerations ? { upstreamGenerations: args.upstreamGenerations } : {},
       ...args.runs !== void 0 ? { runs: args.runs } : {},
       ...args.savedId ? { savedId: args.savedId } : {},
       ...args.visibility ? { visibility: args.visibility } : {},
@@ -2899,7 +2943,7 @@ var studioRunWorkflow = defineTool({
 });
 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.",
+  description: "Fetch a workflow run by runId: overall status (pending, running, succeeded, failed, partial, awaiting_decision, cancelled; cancelled means somebody stopped it), 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),
@@ -3146,7 +3190,7 @@ function registerTools(server, ctx) {
 
 // src/server.ts
 var SERVER_NAME = "lumitra-studio";
-var SERVER_VERSION = "0.1.0";
+var SERVER_VERSION = "0.1.1";
 function createStudioMcpServer(opts = {}) {
   const config = opts.config ?? resolveConfig(opts.env ?? process.env);
   const client = new StudioClient(config, {
@@ -3160,7 +3204,8 @@ function createStudioMcpServer(opts = {}) {
         "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."
+        "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.",
+        "Workflow hygiene: one deliverable is ONE saved workflow with a node per item, and a refinement of an item (edit, upscale, variation) is a NEW NODE appended to that workflow with studio_workflow_apply (addNode plus a connect from the node it refines, so the earlier generation is its input), then studio_run_workflow with savedId and nodeIds limited to the new node. Never send a fresh inline definition for a follow-up: every listed inline run is saved as its own workflow, which scatters one deliverable across duplicates."
       ].join(" ")
     }
   );

package/dist/index.d.ts

@@ -54,17 +54,20 @@ declare const DocNodeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     }, z.core.$strip>>>;
     activeGeneration: z.ZodOptional<z.ZodString>;
     label: z.ZodOptional<z.ZodString>;
+    collapsed: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>, z.ZodObject<{
     id: z.ZodString;
     kind: z.ZodLiteral<"prompt-source">;
     text: z.ZodDefault<z.ZodString>;
     label: z.ZodOptional<z.ZodString>;
+    collapsed: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>, z.ZodObject<{
     id: z.ZodString;
     kind: z.ZodLiteral<"image-source">;
     imageUrl: z.ZodDefault<z.ZodString>;
     assetId: z.ZodOptional<z.ZodString>;
     label: z.ZodOptional<z.ZodString>;
+    collapsed: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>, z.ZodObject<{
     id: z.ZodString;
     kind: z.ZodLiteral<"input">;
@@ -85,6 +88,7 @@ declare const DocNodeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     default: z.ZodOptional<z.ZodType<JsonNonNullValue, unknown, z.core.$ZodTypeInternals<JsonNonNullValue, unknown>>>;
     label: z.ZodOptional<z.ZodString>;
     description: z.ZodOptional<z.ZodString>;
+    collapsed: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>], "kind">;
 type DocNode = z.infer<typeof DocNodeSchema>;
 type DocNodeKind = DocNode["kind"];
@@ -130,17 +134,20 @@ declare const WorkflowDocumentSchema: z.ZodObject<{
         }, z.core.$strip>>>;
         activeGeneration: z.ZodOptional<z.ZodString>;
         label: z.ZodOptional<z.ZodString>;
+        collapsed: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>, z.ZodObject<{
         id: z.ZodString;
         kind: z.ZodLiteral<"prompt-source">;
         text: z.ZodDefault<z.ZodString>;
         label: z.ZodOptional<z.ZodString>;
+        collapsed: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>, z.ZodObject<{
         id: z.ZodString;
         kind: z.ZodLiteral<"image-source">;
         imageUrl: z.ZodDefault<z.ZodString>;
         assetId: z.ZodOptional<z.ZodString>;
         label: z.ZodOptional<z.ZodString>;
+        collapsed: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>, z.ZodObject<{
         id: z.ZodString;
         kind: z.ZodLiteral<"input">;
@@ -161,6 +168,7 @@ declare const WorkflowDocumentSchema: z.ZodObject<{
         default: z.ZodOptional<z.ZodType<JsonNonNullValue, unknown, z.core.$ZodTypeInternals<JsonNonNullValue, unknown>>>;
         label: z.ZodOptional<z.ZodString>;
         description: z.ZodOptional<z.ZodString>;
+        collapsed: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>], "kind">>;
     edges: z.ZodArray<z.ZodObject<{
         source: z.ZodString;
@@ -184,6 +192,26 @@ declare const WorkflowDocumentSchema: z.ZodObject<{
         label: z.ZodOptional<z.ZodString>;
         nodeIds: z.ZodArray<z.ZodString>;
     }, z.core.$strip>>>;
+    view: z.ZodOptional<z.ZodObject<{
+        edgeRouting: z.ZodOptional<z.ZodEnum<{
+            curved: "curved";
+            orthogonal: "orthogonal";
+        }>>;
+        wires: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+            from: z.ZodObject<{
+                x: z.ZodNumber;
+                y: z.ZodNumber;
+            }, z.core.$strip>;
+            to: z.ZodObject<{
+                x: z.ZodNumber;
+                y: z.ZodNumber;
+            }, z.core.$strip>;
+            points: z.ZodArray<z.ZodObject<{
+                x: z.ZodNumber;
+                y: z.ZodNumber;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 type WorkflowDocument = z.infer<typeof WorkflowDocumentSchema>;
 declare const OpSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -226,17 +254,20 @@ declare const OpSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         }, z.core.$strip>>>;
         activeGeneration: z.ZodOptional<z.ZodString>;
         label: z.ZodOptional<z.ZodString>;
+        collapsed: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>, z.ZodObject<{
         id: z.ZodString;
         kind: z.ZodLiteral<"prompt-source">;
         text: z.ZodDefault<z.ZodString>;
         label: z.ZodOptional<z.ZodString>;
+        collapsed: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>, z.ZodObject<{
         id: z.ZodString;
         kind: z.ZodLiteral<"image-source">;
         imageUrl: z.ZodDefault<z.ZodString>;
         assetId: z.ZodOptional<z.ZodString>;
         label: z.ZodOptional<z.ZodString>;
+        collapsed: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>, z.ZodObject<{
         id: z.ZodString;
         kind: z.ZodLiteral<"input">;
@@ -257,6 +288,7 @@ declare const OpSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         default: z.ZodOptional<z.ZodType<JsonNonNullValue, unknown, z.core.$ZodTypeInternals<JsonNonNullValue, unknown>>>;
         label: z.ZodOptional<z.ZodString>;
         description: z.ZodOptional<z.ZodString>;
+        collapsed: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>], "kind">;
     position: z.ZodOptional<z.ZodObject<{
         x: z.ZodNumber;
@@ -300,6 +332,7 @@ declare const OpSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         model: z.ZodOptional<z.ZodString>;
         prompt: z.ZodOptional<z.ZodString>;
         label: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        collapsed: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
     }, z.core.$strict>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"setNodeProps">;
@@ -308,6 +341,7 @@ declare const OpSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     props: z.ZodObject<{
         text: z.ZodOptional<z.ZodString>;
         label: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        collapsed: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
     }, z.core.$strict>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"setNodeProps">;
@@ -317,6 +351,7 @@ declare const OpSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         imageUrl: z.ZodOptional<z.ZodString>;
         assetId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         label: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        collapsed: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
     }, z.core.$strict>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"setNodeProps">;
@@ -340,6 +375,7 @@ declare const OpSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         default: z.ZodOptional<z.ZodNullable<z.ZodType<JsonNonNullValue, unknown, z.core.$ZodTypeInternals<JsonNonNullValue, unknown>>>>;
         label: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        collapsed: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
     }, z.core.$strict>;
 }, z.core.$strip>], "kind">, z.ZodObject<{
     type: z.ZodLiteral<"setNodeSetting">;
@@ -426,6 +462,26 @@ declare const OpSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"setDocumentProps">;
     props: z.ZodObject<{
         label: z.ZodOptional<z.ZodString>;
+        view: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            edgeRouting: z.ZodOptional<z.ZodEnum<{
+                curved: "curved";
+                orthogonal: "orthogonal";
+            }>>;
+            wires: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+                from: z.ZodObject<{
+                    x: z.ZodNumber;
+                    y: z.ZodNumber;
+                }, z.core.$strip>;
+                to: z.ZodObject<{
+                    x: z.ZodNumber;
+                    y: z.ZodNumber;
+                }, z.core.$strip>;
+                points: z.ZodArray<z.ZodObject<{
+                    x: z.ZodNumber;
+                    y: z.ZodNumber;
+                }, z.core.$strip>>;
+            }, z.core.$strip>>>;
+        }, z.core.$strict>>>;
     }, z.core.$strict>;
 }, z.core.$strip>], "type">;
 type Op = z.infer<typeof OpSchema>;
@@ -473,17 +529,20 @@ declare const PatchSchema: z.ZodObject<{
             }, z.core.$strip>>>;
             activeGeneration: z.ZodOptional<z.ZodString>;
             label: z.ZodOptional<z.ZodString>;
+            collapsed: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strip>, z.ZodObject<{
             id: z.ZodString;
             kind: z.ZodLiteral<"prompt-source">;
             text: z.ZodDefault<z.ZodString>;
             label: z.ZodOptional<z.ZodString>;
+            collapsed: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strip>, z.ZodObject<{
             id: z.ZodString;
             kind: z.ZodLiteral<"image-source">;
             imageUrl: z.ZodDefault<z.ZodString>;
             assetId: z.ZodOptional<z.ZodString>;
             label: z.ZodOptional<z.ZodString>;
+            collapsed: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strip>, z.ZodObject<{
             id: z.ZodString;
             kind: z.ZodLiteral<"input">;
@@ -504,6 +563,7 @@ declare const PatchSchema: z.ZodObject<{
             default: z.ZodOptional<z.ZodType<JsonNonNullValue, unknown, z.core.$ZodTypeInternals<JsonNonNullValue, unknown>>>;
             label: z.ZodOptional<z.ZodString>;
             description: z.ZodOptional<z.ZodString>;
+            collapsed: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strip>], "kind">;
         position: z.ZodOptional<z.ZodObject<{
             x: z.ZodNumber;
@@ -547,6 +607,7 @@ declare const PatchSchema: z.ZodObject<{
             model: z.ZodOptional<z.ZodString>;
             prompt: z.ZodOptional<z.ZodString>;
             label: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            collapsed: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
         }, z.core.$strict>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"setNodeProps">;
@@ -555,6 +616,7 @@ declare const PatchSchema: z.ZodObject<{
         props: z.ZodObject<{
             text: z.ZodOptional<z.ZodString>;
             label: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            collapsed: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
         }, z.core.$strict>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"setNodeProps">;
@@ -564,6 +626,7 @@ declare const PatchSchema: z.ZodObject<{
             imageUrl: z.ZodOptional<z.ZodString>;
             assetId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
             label: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            collapsed: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
         }, z.core.$strict>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"setNodeProps">;
@@ -587,6 +650,7 @@ declare const PatchSchema: z.ZodObject<{
             default: z.ZodOptional<z.ZodNullable<z.ZodType<JsonNonNullValue, unknown, z.core.$ZodTypeInternals<JsonNonNullValue, unknown>>>>;
             label: z.ZodOptional<z.ZodNullable<z.ZodString>>;
             description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            collapsed: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
         }, z.core.$strict>;
     }, z.core.$strip>], "kind">, z.ZodObject<{
         type: z.ZodLiteral<"setNodeSetting">;
@@ -673,6 +737,26 @@ declare const PatchSchema: z.ZodObject<{
         type: z.ZodLiteral<"setDocumentProps">;
         props: z.ZodObject<{
             label: z.ZodOptional<z.ZodString>;
+            view: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+                edgeRouting: z.ZodOptional<z.ZodEnum<{
+                    curved: "curved";
+                    orthogonal: "orthogonal";
+                }>>;
+                wires: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+                    from: z.ZodObject<{
+                        x: z.ZodNumber;
+                        y: z.ZodNumber;
+                    }, z.core.$strip>;
+                    to: z.ZodObject<{
+                        x: z.ZodNumber;
+                        y: z.ZodNumber;
+                    }, z.core.$strip>;
+                    points: z.ZodArray<z.ZodObject<{
+                        x: z.ZodNumber;
+                        y: z.ZodNumber;
+                    }, z.core.$strip>>;
+                }, z.core.$strip>>>;
+            }, z.core.$strict>>>;
         }, z.core.$strict>;
     }, z.core.$strip>], "type">>;
     idempotencyKey: z.ZodOptional<z.ZodString>;
@@ -801,7 +885,7 @@ interface CharacterReference {
 }
 /** `awaiting_decision` (P3 J2) is a run PARKED on a human decision at a judge
  * node: not terminal, not a failure, and polling will never clear it. */
-type RunStatus = 'pending' | 'running' | 'succeeded' | 'failed' | 'partial' | 'awaiting_decision' | (string & {});
+type RunStatus = 'pending' | 'running' | 'succeeded' | 'failed' | 'partial' | 'awaiting_decision' | 'cancelled' | (string & {});
 type NodeStatus = 'pending' | 'running' | 'succeeded' | 'failed' | 'awaiting_decision' | (string & {});
 /** One candidate a parked judge node is waiting on a decision about. The url
  * is signed per response; `generationId` is what a decision names. */
@@ -816,6 +900,8 @@ interface JudgeCandidate {
 }
 interface NodeRun {
     nodeId: string;
+    /** The node-run (generation) id; pinnable via `upstreamGenerations`. */
+    id?: string;
     status: NodeStatus;
     jobId?: string | null;
     resultUrl?: string | null;
@@ -1109,6 +1195,7 @@ declare class StudioClient {
         definitionId?: string;
         params?: Record<string, unknown>;
         nodeIds?: string[];
+        upstreamGenerations?: Record<string, string>;
         runs?: number;
         savedId?: string;
         visibility?: 'listed' | 'unlisted';
@@ -1136,7 +1223,9 @@ declare class StudioClient {
     getRunNodeUrl(runId: string, nodeId: string): Promise<NodeResultResponse>;
     /** S9: a rendered diagram of a saved workflow's document, so an agent can
      * see the graph it just built. */
-    getWorkflowScreenshot(savedId: string): Promise<{
+    getWorkflowScreenshot(savedId: string, opts?: {
+        projectId?: string;
+    }): Promise<{
         url: string;
         width: number;
         height: number;
@@ -1185,8 +1274,11 @@ declare class StudioClient {
         savedId?: string;
     }): Promise<Record<string, unknown>>;
     describeNodeTypes(): Promise<NodeTypesResponse>;
-    /** `savedId` carries a `saved:` prefix; the colon is URL-encoded. */
-    getWorkflowDocument(savedId: string): Promise<WorkflowDocumentResponse>;
+    /** `savedId` carries a `saved:` prefix; the colon is URL-encoded. `projectId`
+     * names the project the workflow lives in; absent, the Studio's default. */
+    getWorkflowDocument(savedId: string, opts?: {
+        projectId?: string;
+    }): Promise<WorkflowDocumentResponse>;
     /** Create a document by applying `ops` to an empty one (the same code path as apply). */
     createWorkflow(body: {
         ops: Op[];
@@ -1200,6 +1292,7 @@ declare class StudioClient {
      */
     applyWorkflowPatch(savedId: string, patch: Patch & {
         acknowledgeLossy?: boolean;
+        projectId?: string;
     }): Promise<WorkflowApplyResponse>;
     /** Stateless dry-run of ops and run params against a document. No side effects. */
     validateWorkflow(body: {
@@ -1311,7 +1404,7 @@ declare function registerTools(server: McpServer, ctx: ToolContext): void;
  */
 
 declare const SERVER_NAME = "lumitra-studio";
-declare const SERVER_VERSION = "0.1.0";
+declare const SERVER_VERSION = "0.1.1";
 interface CreateServerOptions {
     config?: StudioConfig;
     env?: NodeJS.ProcessEnv;
@@ -1360,6 +1453,7 @@ declare const studioWorkflowDescribe: ToolDef<{
 }>;
 declare const studioWorkflowGet: ToolDef<{
     savedId: z.ZodString;
+    projectId: z.ZodOptional<z.ZodString>;
     full: z.ZodDefault<z.ZodBoolean>;
 }>;
 declare const studioWorkflowCreate: ToolDef<{
@@ -1403,17 +1497,20 @@ declare const studioWorkflowCreate: ToolDef<{
             }, z.core.$strip>>>;
             activeGeneration: z.ZodOptional<z.ZodString>;
             label: z.ZodOptional<z.ZodString>;
+            collapsed: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strip>, z.ZodObject<{
             id: z.ZodString;
             kind: z.ZodLiteral<"prompt-source">;
             text: z.ZodDefault<z.ZodString>;
             label: z.ZodOptional<z.ZodString>;
+            collapsed: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strip>, z.ZodObject<{
             id: z.ZodString;
             kind: z.ZodLiteral<"image-source">;
             imageUrl: z.ZodDefault<z.ZodString>;
             assetId: z.ZodOptional<z.ZodString>;
             label: z.ZodOptional<z.ZodString>;
+            collapsed: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strip>, z.ZodObject<{
             id: z.ZodString;
             kind: z.ZodLiteral<"input">;
@@ -1434,6 +1531,7 @@ declare const studioWorkflowCreate: ToolDef<{
             default: z.ZodOptional<z.ZodType<JsonNonNullValue, unknown, z.core.$ZodTypeInternals<JsonNonNullValue, unknown>>>;
             label: z.ZodOptional<z.ZodString>;
             description: z.ZodOptional<z.ZodString>;
+            collapsed: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strip>], "kind">;
         position: z.ZodOptional<z.ZodObject<{
             x: z.ZodNumber;
@@ -1477,6 +1575,7 @@ declare const studioWorkflowCreate: ToolDef<{
             model: z.ZodOptional<z.ZodString>;
             prompt: z.ZodOptional<z.ZodString>;
             label: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            collapsed: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
         }, z.core.$strict>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"setNodeProps">;
@@ -1485,6 +1584,7 @@ declare const studioWorkflowCreate: ToolDef<{
         props: z.ZodObject<{
             text: z.ZodOptional<z.ZodString>;
             label: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            collapsed: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
         }, z.core.$strict>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"setNodeProps">;
@@ -1494,6 +1594,7 @@ declare const studioWorkflowCreate: ToolDef<{
             imageUrl: z.ZodOptional<z.ZodString>;
             assetId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
             label: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            collapsed: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
         }, z.core.$strict>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"setNodeProps">;
@@ -1517,6 +1618,7 @@ declare const studioWorkflowCreate: ToolDef<{
             default: z.ZodOptional<z.ZodNullable<z.ZodType<JsonNonNullValue, unknown, z.core.$ZodTypeInternals<JsonNonNullValue, unknown>>>>;
             label: z.ZodOptional<z.ZodNullable<z.ZodString>>;
             description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            collapsed: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
         }, z.core.$strict>;
     }, z.core.$strip>], "kind">, z.ZodObject<{
         type: z.ZodLiteral<"setNodeSetting">;
@@ -1603,6 +1705,26 @@ declare const studioWorkflowCreate: ToolDef<{
         type: z.ZodLiteral<"setDocumentProps">;
         props: z.ZodObject<{
             label: z.ZodOptional<z.ZodString>;
+            view: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+                edgeRouting: z.ZodOptional<z.ZodEnum<{
+                    curved: "curved";
+                    orthogonal: "orthogonal";
+                }>>;
+                wires: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+                    from: z.ZodObject<{
+                        x: z.ZodNumber;
+                        y: z.ZodNumber;
+                    }, z.core.$strip>;
+                    to: z.ZodObject<{
+                        x: z.ZodNumber;
+                        y: z.ZodNumber;
+                    }, z.core.$strip>;
+                    points: z.ZodArray<z.ZodObject<{
+                        x: z.ZodNumber;
+                        y: z.ZodNumber;
+                    }, z.core.$strip>>;
+                }, z.core.$strip>>>;
+            }, z.core.$strict>>>;
         }, z.core.$strict>;
     }, z.core.$strip>], "type">>;
     label: z.ZodOptional<z.ZodString>;
@@ -1610,6 +1732,7 @@ declare const studioWorkflowCreate: ToolDef<{
 }>;
 declare const studioWorkflowApply: ToolDef<{
     savedId: z.ZodString;
+    projectId: z.ZodOptional<z.ZodString>;
     baseRevision: z.ZodNumber;
     ops: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
         type: z.ZodLiteral<"addNode">;
@@ -1651,17 +1774,20 @@ declare const studioWorkflowApply: ToolDef<{
             }, z.core.$strip>>>;
             activeGeneration: z.ZodOptional<z.ZodString>;
             label: z.ZodOptional<z.ZodString>;
+            collapsed: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strip>, z.ZodObject<{
             id: z.ZodString;
             kind: z.ZodLiteral<"prompt-source">;
             text: z.ZodDefault<z.ZodString>;
             label: z.ZodOptional<z.ZodString>;
+            collapsed: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strip>, z.ZodObject<{
             id: z.ZodString;
             kind: z.ZodLiteral<"image-source">;
             imageUrl: z.ZodDefault<z.ZodString>;
             assetId: z.ZodOptional<z.ZodString>;
             label: z.ZodOptional<z.ZodString>;
+            collapsed: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strip>, z.ZodObject<{
             id: z.ZodString;
             kind: z.ZodLiteral<"input">;
@@ -1682,6 +1808,7 @@ declare const studioWorkflowApply: ToolDef<{
             default: z.ZodOptional<z.ZodType<JsonNonNullValue, unknown, z.core.$ZodTypeInternals<JsonNonNullValue, unknown>>>;
             label: z.ZodOptional<z.ZodString>;
             description: z.ZodOptional<z.ZodString>;
+            collapsed: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strip>], "kind">;
         position: z.ZodOptional<z.ZodObject<{
             x: z.ZodNumber;
@@ -1725,6 +1852,7 @@ declare const studioWorkflowApply: ToolDef<{
             model: z.ZodOptional<z.ZodString>;
             prompt: z.ZodOptional<z.ZodString>;
             label: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            collapsed: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
         }, z.core.$strict>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"setNodeProps">;
@@ -1733,6 +1861,7 @@ declare const studioWorkflowApply: ToolDef<{
         props: z.ZodObject<{
             text: z.ZodOptional<z.ZodString>;
             label: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            collapsed: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
         }, z.core.$strict>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"setNodeProps">;
@@ -1742,6 +1871,7 @@ declare const studioWorkflowApply: ToolDef<{
             imageUrl: z.ZodOptional<z.ZodString>;
             assetId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
             label: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            collapsed: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
         }, z.core.$strict>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"setNodeProps">;
@@ -1765,6 +1895,7 @@ declare const studioWorkflowApply: ToolDef<{
             default: z.ZodOptional<z.ZodNullable<z.ZodType<JsonNonNullValue, unknown, z.core.$ZodTypeInternals<JsonNonNullValue, unknown>>>>;
             label: z.ZodOptional<z.ZodNullable<z.ZodString>>;
             description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            collapsed: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
         }, z.core.$strict>;
     }, z.core.$strip>], "kind">, z.ZodObject<{
         type: z.ZodLiteral<"setNodeSetting">;
@@ -1851,6 +1982,26 @@ declare const studioWorkflowApply: ToolDef<{
         type: z.ZodLiteral<"setDocumentProps">;
         props: z.ZodObject<{
             label: z.ZodOptional<z.ZodString>;
+            view: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+                edgeRouting: z.ZodOptional<z.ZodEnum<{
+                    curved: "curved";
+                    orthogonal: "orthogonal";
+                }>>;
+                wires: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+                    from: z.ZodObject<{
+                        x: z.ZodNumber;
+                        y: z.ZodNumber;
+                    }, z.core.$strip>;
+                    to: z.ZodObject<{
+                        x: z.ZodNumber;
+                        y: z.ZodNumber;
+                    }, z.core.$strip>;
+                    points: z.ZodArray<z.ZodObject<{
+                        x: z.ZodNumber;
+                        y: z.ZodNumber;
+                    }, z.core.$strip>>;
+                }, z.core.$strip>>>;
+            }, z.core.$strict>>>;
         }, z.core.$strict>;
     }, z.core.$strip>], "type">>;
     idempotencyKey: z.ZodOptional<z.ZodString>;
@@ -1899,17 +2050,20 @@ declare const studioWorkflowValidate: ToolDef<{
             }, z.core.$strip>>>;
             activeGeneration: z.ZodOptional<z.ZodString>;
             label: z.ZodOptional<z.ZodString>;
+            collapsed: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strip>, z.ZodObject<{
             id: z.ZodString;
             kind: z.ZodLiteral<"prompt-source">;
             text: z.ZodDefault<z.ZodString>;
             label: z.ZodOptional<z.ZodString>;
+            collapsed: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strip>, z.ZodObject<{
             id: z.ZodString;
             kind: z.ZodLiteral<"image-source">;
             imageUrl: z.ZodDefault<z.ZodString>;
             assetId: z.ZodOptional<z.ZodString>;
             label: z.ZodOptional<z.ZodString>;
+            collapsed: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strip>, z.ZodObject<{
             id: z.ZodString;
             kind: z.ZodLiteral<"input">;
@@ -1930,6 +2084,7 @@ declare const studioWorkflowValidate: ToolDef<{
             default: z.ZodOptional<z.ZodType<JsonNonNullValue, unknown, z.core.$ZodTypeInternals<JsonNonNullValue, unknown>>>;
             label: z.ZodOptional<z.ZodString>;
             description: z.ZodOptional<z.ZodString>;
+            collapsed: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strip>], "kind">>;
         edges: z.ZodArray<z.ZodObject<{
             source: z.ZodString;
@@ -1953,8 +2108,29 @@ declare const studioWorkflowValidate: ToolDef<{
             label: z.ZodOptional<z.ZodString>;
             nodeIds: z.ZodArray<z.ZodString>;
         }, z.core.$strip>>>;
+        view: z.ZodOptional<z.ZodObject<{
+            edgeRouting: z.ZodOptional<z.ZodEnum<{
+                curved: "curved";
+                orthogonal: "orthogonal";
+            }>>;
+            wires: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+                from: z.ZodObject<{
+                    x: z.ZodNumber;
+                    y: z.ZodNumber;
+                }, z.core.$strip>;
+                to: z.ZodObject<{
+                    x: z.ZodNumber;
+                    y: z.ZodNumber;
+                }, z.core.$strip>;
+                points: z.ZodArray<z.ZodObject<{
+                    x: z.ZodNumber;
+                    y: z.ZodNumber;
+                }, z.core.$strip>>;
+            }, z.core.$strip>>>;
+        }, z.core.$strip>>;
     }, z.core.$strip>>;
     savedId: z.ZodOptional<z.ZodString>;
+    projectId: z.ZodOptional<z.ZodString>;
     ops: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
         type: z.ZodLiteral<"addNode">;
         node: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -1995,17 +2171,20 @@ declare const studioWorkflowValidate: ToolDef<{
             }, z.core.$strip>>>;
             activeGeneration: z.ZodOptional<z.ZodString>;
             label: z.ZodOptional<z.ZodString>;
+            collapsed: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strip>, z.ZodObject<{
             id: z.ZodString;
             kind: z.ZodLiteral<"prompt-source">;
             text: z.ZodDefault<z.ZodString>;
             label: z.ZodOptional<z.ZodString>;
+            collapsed: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strip>, z.ZodObject<{
             id: z.ZodString;
             kind: z.ZodLiteral<"image-source">;
             imageUrl: z.ZodDefault<z.ZodString>;
             assetId: z.ZodOptional<z.ZodString>;
             label: z.ZodOptional<z.ZodString>;
+            collapsed: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strip>, z.ZodObject<{
             id: z.ZodString;
             kind: z.ZodLiteral<"input">;
@@ -2026,6 +2205,7 @@ declare const studioWorkflowValidate: ToolDef<{
             default: z.ZodOptional<z.ZodType<JsonNonNullValue, unknown, z.core.$ZodTypeInternals<JsonNonNullValue, unknown>>>;
             label: z.ZodOptional<z.ZodString>;
             description: z.ZodOptional<z.ZodString>;
+            collapsed: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strip>], "kind">;
         position: z.ZodOptional<z.ZodObject<{
             x: z.ZodNumber;
@@ -2069,6 +2249,7 @@ declare const studioWorkflowValidate: ToolDef<{
             model: z.ZodOptional<z.ZodString>;
             prompt: z.ZodOptional<z.ZodString>;
             label: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            collapsed: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
         }, z.core.$strict>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"setNodeProps">;
@@ -2077,6 +2258,7 @@ declare const studioWorkflowValidate: ToolDef<{
         props: z.ZodObject<{
             text: z.ZodOptional<z.ZodString>;
             label: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            collapsed: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
         }, z.core.$strict>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"setNodeProps">;
@@ -2086,6 +2268,7 @@ declare const studioWorkflowValidate: ToolDef<{
             imageUrl: z.ZodOptional<z.ZodString>;
             assetId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
             label: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            collapsed: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
         }, z.core.$strict>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"setNodeProps">;
@@ -2109,6 +2292,7 @@ declare const studioWorkflowValidate: ToolDef<{
             default: z.ZodOptional<z.ZodNullable<z.ZodType<JsonNonNullValue, unknown, z.core.$ZodTypeInternals<JsonNonNullValue, unknown>>>>;
             label: z.ZodOptional<z.ZodNullable<z.ZodString>>;
             description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            collapsed: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
         }, z.core.$strict>;
     }, z.core.$strip>], "kind">, z.ZodObject<{
         type: z.ZodLiteral<"setNodeSetting">;
@@ -2195,12 +2379,33 @@ declare const studioWorkflowValidate: ToolDef<{
         type: z.ZodLiteral<"setDocumentProps">;
         props: z.ZodObject<{
             label: z.ZodOptional<z.ZodString>;
+            view: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+                edgeRouting: z.ZodOptional<z.ZodEnum<{
+                    curved: "curved";
+                    orthogonal: "orthogonal";
+                }>>;
+                wires: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+                    from: z.ZodObject<{
+                        x: z.ZodNumber;
+                        y: z.ZodNumber;
+                    }, z.core.$strip>;
+                    to: z.ZodObject<{
+                        x: z.ZodNumber;
+                        y: z.ZodNumber;
+                    }, z.core.$strip>;
+                    points: z.ZodArray<z.ZodObject<{
+                        x: z.ZodNumber;
+                        y: z.ZodNumber;
+                    }, z.core.$strip>>;
+                }, z.core.$strip>>>;
+            }, z.core.$strict>>>;
         }, z.core.$strict>;
     }, z.core.$strip>], "type">>>;
     params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }>;
 declare const studioWorkflowScreenshot: ToolDef<{
     savedId: z.ZodString;
+    projectId: z.ZodOptional<z.ZodString>;
 }>;
 /** The six primitives, in registration order. */
 declare const WORKFLOW_TOOLS: readonly ToolDef<z.ZodRawShape>[];

package/dist/index.js

@@ -162,8 +162,8 @@ var StudioClient = class {
   }
   /** 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`);
+  getWorkflowScreenshot(savedId2, opts = {}) {
+    return this.json("GET", `/api/v1/workflows/${encodeURIComponent(savedId2)}/screenshot${projectQuery(opts.projectId)}`);
   }
   // ── Recipes (S10): published workflow + closed post-run effect list ──
   publishWorkflow(savedId2, body) {
@@ -188,9 +188,10 @@ var StudioClient = class {
   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)}`);
+  /** `savedId` carries a `saved:` prefix; the colon is URL-encoded. `projectId`
+   * names the project the workflow lives in; absent, the Studio's default. */
+  getWorkflowDocument(savedId2, opts = {}) {
+    return this.json("GET", `/api/v1/workflows/${encodeURIComponent(savedId2)}${projectQuery(opts.projectId)}`);
   }
   /** Create a document by applying `ops` to an empty one (the same code path as apply). */
   createWorkflow(body) {
@@ -361,6 +362,9 @@ function mimeForFilename(name) {
       return "application/octet-stream";
   }
 }
+function projectQuery(projectId) {
+  return projectId === void 0 ? "" : `?projectId=${encodeURIComponent(projectId)}`;
+}
 
 // src/config.ts
 var DEFAULT_BASE_URL = "https://studio.lumitra.co";
@@ -626,6 +630,7 @@ 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 CollapsedSchema = z3.boolean();
 var TaskNodeSchema = z3.object({
   id: IdSchema,
   kind: z3.literal("task"),
@@ -646,13 +651,15 @@ var TaskNodeSchema = z3.object({
   bakedInputs: z3.record(KeySchema, LiteralBindingSchema).default({}),
   /** The generation id that feeds downstream. Absent = latest (D4). */
   activeGeneration: IdSchema.optional(),
-  label: LabelSchema.optional()
+  label: LabelSchema.optional(),
+  collapsed: CollapsedSchema.optional()
 });
 var PromptSourceNodeSchema = z3.object({
   id: IdSchema,
   kind: z3.literal("prompt-source"),
   text: PromptTextSchema.default(""),
-  label: LabelSchema.optional()
+  label: LabelSchema.optional(),
+  collapsed: CollapsedSchema.optional()
 });
 var ImageSourceNodeSchema = z3.object({
   id: IdSchema,
@@ -663,7 +670,8 @@ var ImageSourceNodeSchema = z3.object({
   /** The Storage Brain asset id, when known (E18: every image input resolves to
    * an asset id). */
   assetId: AssetIdSchema.optional(),
-  label: LabelSchema.optional()
+  label: LabelSchema.optional(),
+  collapsed: CollapsedSchema.optional()
 });
 var InputNodeSchema = z3.object({
   id: IdSchema,
@@ -678,7 +686,8 @@ var InputNodeSchema = z3.object({
   /** Used when a run omits the input. Never null: absent means no default. */
   default: JsonNonNullValueSchema.optional(),
   label: LabelSchema.optional(),
-  description: DescriptionSchema.optional()
+  description: DescriptionSchema.optional(),
+  collapsed: CollapsedSchema.optional()
 });
 var DocNodeSchema = z3.discriminatedUnion("kind", [
   TaskNodeSchema,
@@ -696,6 +705,18 @@ var DocGroupSchema = z3.object({
   label: LabelSchema.optional(),
   nodeIds: z3.array(IdSchema).min(1)
 });
+var EDGE_ROUTINGS = ["curved", "orthogonal"];
+var EdgeRoutingSchema = z3.enum(EDGE_ROUTINGS);
+var WireRouteSchema = z3.object({
+  from: PositionSchema,
+  to: PositionSchema,
+  points: z3.array(PositionSchema).max(64)
+});
+var DocumentViewSchema = z3.object({
+  edgeRouting: EdgeRoutingSchema.optional(),
+  /** Routed wires from the last Arrange, keyed by `edgeKey`. */
+  wires: z3.record(z3.string().max(512), WireRouteSchema).optional()
+});
 var WorkflowDocumentSchema = z3.object({
   schema: z3.number().int().positive(),
   id: IdSchema,
@@ -703,7 +724,10 @@ var WorkflowDocumentSchema = z3.object({
   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([])
+  groups: z3.array(DocGroupSchema).max(500).default([]),
+  /** Display preferences; absent on every document written before they
+   * existed (additive, so `DOCUMENT_SCHEMA_VERSION` is unchanged). */
+  view: DocumentViewSchema.optional()
 });
 function edgeKey(e) {
   return JSON.stringify([e.source, e.target, e.port]);
@@ -1472,16 +1496,19 @@ var TaskNodePropsSchema = z4.object({
   task: z4.enum(MODEL_TASKS),
   model: ModelIdSchema,
   prompt: PromptTextSchema,
-  label: LabelSchema.nullable()
+  label: LabelSchema.nullable(),
+  collapsed: CollapsedSchema.nullable()
 }).partial().strict();
 var PromptSourcePropsSchema = z4.object({
   text: PromptTextSchema,
-  label: LabelSchema.nullable()
+  label: LabelSchema.nullable(),
+  collapsed: CollapsedSchema.nullable()
 }).partial().strict();
 var ImageSourcePropsSchema = z4.object({
   imageUrl: UrlSchema,
   assetId: AssetIdSchema.nullable(),
-  label: LabelSchema.nullable()
+  label: LabelSchema.nullable(),
+  collapsed: CollapsedSchema.nullable()
 }).partial().strict();
 var InputNodePropsSchema = z4.object({
   name: InputNameSchema,
@@ -1490,14 +1517,19 @@ var InputNodePropsSchema = z4.object({
   cardinality: z4.enum(["one", "many"]).nullable(),
   default: JsonNonNullValueSchema.nullable(),
   label: LabelSchema.nullable(),
-  description: DescriptionSchema.nullable()
+  description: DescriptionSchema.nullable(),
+  collapsed: CollapsedSchema.nullable()
 }).partial().strict();
 var GroupPropsSchema = z4.object({
   label: LabelSchema.nullable(),
   nodeIds: z4.array(IdSchema).min(1)
 }).partial().strict();
 var DocumentPropsSchema = z4.object({
-  label: LabelSchema
+  label: LabelSchema,
+  /** Display preferences (`view.edgeRouting`); null clears the whole
+   * object. The object is replaced, not merged: pass every field you want
+   * kept. */
+  view: DocumentViewSchema.strict().nullable()
 }).partial().strict();
 var AddNodeOpSchema = z4.object({
   type: z4.literal("addNode"),
@@ -2071,7 +2103,7 @@ async function pollUntil(what, fetchState, isDone, opts = {}) {
   }
 }
 var TERMINAL_JOB_STATUSES = /* @__PURE__ */ new Set(["succeeded", "failed", "canceled"]);
-var TERMINAL_RUN_STATUSES = /* @__PURE__ */ new Set(["succeeded", "failed", "partial"]);
+var TERMINAL_RUN_STATUSES = /* @__PURE__ */ new Set(["succeeded", "failed", "partial", "cancelled"]);
 function isJobTerminal(res) {
   return TERMINAL_JOB_STATUSES.has(res.job.status);
 }
@@ -2404,11 +2436,12 @@ var studioWorkflowGet = defineTool({
   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,
+    projectId: z7.string().min(1).optional().describe("Project id from studio_list_projects the workflow lives in; omit for the default project."),
     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);
+    const res = await ctx.client.getWorkflowDocument(args.savedId, args.projectId !== void 0 ? { projectId: args.projectId } : {});
     if (args.full) return res;
     if (res.readOnly === true || res.document === null) {
       const definition = isRecord(res.definition) ? res.definition : null;
@@ -2481,6 +2514,7 @@ var studioWorkflowApply = defineTool({
   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,
+    projectId: z7.string().min(1).optional().describe("Project id from studio_list_projects the workflow lives in; omit for the default project."),
     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(
@@ -2495,6 +2529,7 @@ var studioWorkflowApply = defineTool({
     let res;
     try {
       res = await ctx.client.applyWorkflowPatch(args.savedId, {
+        ...args.projectId !== void 0 ? { projectId: args.projectId } : {},
         baseRevision: args.baseRevision,
         ops: args.ops,
         idempotencyKey,
@@ -2529,16 +2564,18 @@ var studioWorkflowValidate = defineTool({
   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."),
+    projectId: z7.string().min(1).optional().describe("Project id from studio_list_projects the saved workflow lives in (only with savedId); omit for the default project."),
     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");
+    if (args.projectId !== void 0 && !args.savedId) throw new ToolInputError("`projectId` only applies when fetching by `savedId`");
     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);
+      const saved = await ctx.client.getWorkflowDocument(args.savedId, args.projectId !== void 0 ? { projectId: args.projectId } : {});
       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.`
@@ -2557,11 +2594,12 @@ 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
+    savedId,
+    projectId: z7.string().min(1).optional().describe("Project id from studio_list_projects the workflow lives in; omit for the default project.")
   },
   annotations: { readOnlyHint: true },
   handler: async (args, ctx) => {
-    return ctx.client.getWorkflowScreenshot(args.savedId);
+    return ctx.client.getWorkflowScreenshot(args.savedId, args.projectId !== void 0 ? { projectId: args.projectId } : {});
   }
 });
 var WORKFLOW_TOOLS = [
@@ -2594,6 +2632,8 @@ function projectJob(res) {
 function projectNodeRun(nr) {
   return {
     nodeId: nr.nodeId,
+    // The node-run (generation) id: what `upstreamGenerations` pins.
+    id: nr.id ?? null,
     status: nr.status,
     url: nr.resultUrl ?? nr.results?.[0]?.url ?? null,
     kind: nr.results?.[0]?.kind ?? null,
@@ -2851,13 +2891,16 @@ var workflowDefinitionSchema = WorkflowDefinitionSchema.describe(
 );
 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.`,
+  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, cancelled). Each node becomes a paid job. Use an inline definition ONLY for the first batch of a new deliverable (one workflow, a node per item, a stable label); a follow-up on an existing item belongs in that saved workflow as a new node (studio_workflow_apply: addNode plus connect from the node it refines) run here with savedId and nodeIds, because every listed inline run is saved as its own workflow.`,
   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`)."),
+    upstreamGenerations: z8.record(z8.string(), z8.string()).optional().describe(
+      'Pin WHICH generation of an upstream node feeds this subset run: { "<upstream node id>": "<node-run id>" } (the per-node `id` that studio_get_run returns). A verified pin is reused even when the planner has no matching cache key for it (an inline first batch, or a node edited and reverted), so a follow-up node wired from an earlier generation runs against exactly that image. An unknown id is refused naming the node, never silently replaced by the latest.'
+    ),
     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(
@@ -2881,6 +2924,7 @@ var studioRunWorkflow = defineTool({
       ...args.definition ? { definition: args.definition } : {},
       ...args.params ? { params: args.params } : {},
       ...args.nodeIds && args.nodeIds.length > 0 ? { nodeIds: args.nodeIds } : {},
+      ...args.upstreamGenerations ? { upstreamGenerations: args.upstreamGenerations } : {},
       ...args.runs !== void 0 ? { runs: args.runs } : {},
       ...args.savedId ? { savedId: args.savedId } : {},
       ...args.visibility ? { visibility: args.visibility } : {},
@@ -2894,7 +2938,7 @@ var studioRunWorkflow = defineTool({
 });
 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.",
+  description: "Fetch a workflow run by runId: overall status (pending, running, succeeded, failed, partial, awaiting_decision, cancelled; cancelled means somebody stopped it), 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),
@@ -3141,7 +3185,7 @@ function registerTools(server, ctx) {
 
 // src/server.ts
 var SERVER_NAME = "lumitra-studio";
-var SERVER_VERSION = "0.1.0";
+var SERVER_VERSION = "0.1.1";
 function createStudioMcpServer(opts = {}) {
   const config = opts.config ?? resolveConfig(opts.env ?? process.env);
   const client = new StudioClient(config, {
@@ -3155,7 +3199,8 @@ function createStudioMcpServer(opts = {}) {
         "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."
+        "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.",
+        "Workflow hygiene: one deliverable is ONE saved workflow with a node per item, and a refinement of an item (edit, upscale, variation) is a NEW NODE appended to that workflow with studio_workflow_apply (addNode plus a connect from the node it refines, so the earlier generation is its input), then studio_run_workflow with savedId and nodeIds limited to the new node. Never send a fresh inline definition for a follow-up: every listed inline run is saved as its own workflow, which scatters one deliverable across duplicates."
       ].join(" ")
     }
   );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marlinjai/studio-mcp",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "private": false,
   "description": "Model Context Protocol (MCP) server over the Lumitra Studio HTTP API: generate images, mint characters, run workflows, swap characters into video.",
   "license": "MIT",