@womp/spark-agent 9.1.0 → 9.2.0

package/CHANGELOG.md

@@ -4,6 +4,17 @@ Notable changes to `@womp/spark-agent`, newest first. Versions follow
 [Semantic Versioning](https://semver.org/). Add an entry with each version bump; describe what
 changed for hosts and users, and how to migrate across breaking changes.
 
+## 9.2.0 — 2026-10-12
+
+### Added
+
+- `flowRuns` capability (`flow-runs` skill, `womp.flowRuns`): describe, run, follow (`status`,
+  `wait` up to 60 s) and cancel a run of the user's saved Flow pipeline, with no canvas open.
+  Hosts implement `FlowRunsHost`; one run starts per JavaScript call, and run ids are validated
+  before the host is called. Crow composes it under the run's `flowRun` gate.
+- flowRuns.run({ copy: true }) runs the flow on a new copy of the project ("Flow runs" folder); start and status report projectId, sourceProjectId and projectUrl. A copy start waits through `waitForService` ("Copying the project") when the host has it, so the copy is outside the 60 s JavaScript budget.
+- flowRuns.run({ copy: true, deleteCopy: true }) deletes the copy once the run ends, and flowRuns.deleteCopy(runId) deletes an ended copy run's copy (through `waitForService`, "Deleting the copy"). Start and status report deleteCopy and copyDeletedAt; projectUrl is null once the copy is gone. Output links keep working. Right after a cancel, deleteCopy(runId) may answer run_active for about a minute while the run stops; the skill says to retry later.
+
 ## 9.1.0 — 2026-10-12
 
 The agent writes procedural materials as FlowIR programs, the same way it writes Geometry Nodes,

package/dist/capabilities/flow-runs.d.ts

@@ -0,0 +1,95 @@
+import type { SparkCapability, SparkInvocationContext } from "../capabilities.js";
+/** An input the flow can be run with, addressed by its input node id. */
+export type FlowRunInput = {
+    nodeId: string;
+    typeId: string;
+    valueType: string;
+    /** The value saved in the flow now. */
+    value: unknown;
+    /** Wired into the graph: a run needs a value for it. */
+    required: boolean;
+};
+export type FlowRunOutputNode = {
+    nodeId: string;
+    typeId: string;
+};
+export type FlowRunLive = {
+    runId: string;
+    trigger: string;
+};
+export type FlowRunDescription = {
+    projectId: number;
+    snapshotId: string;
+    inputs: FlowRunInput[];
+    outputs: FlowRunOutputNode[];
+    /** The run live on this flow now, if any; only one can be. */
+    liveRun: FlowRunLive | null;
+};
+export type FlowRunStarted = {
+    runId: string;
+    status: string;
+    repeated: boolean;
+    /** The project the run runs on: the copy for a copy run. */
+    projectId: number;
+    /** The copied project for a copy run; null in place. */
+    sourceProjectId: number | null;
+    /** The URL of projectId; null once a copy run's copy was deleted. */
+    projectUrl: string | null;
+    /** The copy is deleted when the run ends (run({ copy: true, deleteCopy: true })). */
+    deleteCopy: boolean;
+    /** When the copy was deleted (ISO); null while it exists. */
+    copyDeletedAt: string | null;
+};
+export type FlowRunStatus = {
+    runId: string;
+    /** "running", "completed", "failed" or "cancelled". */
+    status: string;
+    /** The output nodes' values once completed. */
+    outputs: unknown;
+    error: string | null;
+    errorCode: string | null;
+    /** For an ended run: "now" when this call reports it, "earlier" when it was already reported. */
+    reported: "now" | "earlier" | null;
+    projectId: number;
+    sourceProjectId: number | null;
+    projectUrl: string | null;
+    deleteCopy: boolean;
+    copyDeletedAt: string | null;
+};
+export type FlowRunCancelled = {
+    runId: string;
+    status: string;
+    cancelled: boolean;
+};
+export type FlowRunCopyDeleted = {
+    runId: string;
+    copyDeletedAt: string;
+};
+export type WompFlowRunsApi = {
+    describe(): Promise<FlowRunDescription>;
+    run(options?: {
+        inputs?: Record<string, unknown>;
+        copy?: boolean;
+        deleteCopy?: boolean;
+    }): Promise<FlowRunStarted>;
+    status(runId: string): Promise<FlowRunStatus>;
+    wait(runId: string, seconds?: number): Promise<FlowRunStatus>;
+    cancel(runId: string): Promise<FlowRunCancelled>;
+    deleteCopy(runId: string): Promise<FlowRunCopyDeleted>;
+};
+export type FlowRunsHost = {
+    describe(context: SparkInvocationContext): Promise<FlowRunDescription>;
+    start(options: {
+        inputs: Record<string, unknown>;
+        copy: boolean;
+        deleteCopy: boolean;
+    }, context: SparkInvocationContext): Promise<FlowRunStarted>;
+    status(runId: string, context: SparkInvocationContext): Promise<FlowRunStatus>;
+    /** Waits at most `seconds` for the run to end and returns its status either way. */
+    wait(runId: string, seconds: number, context: SparkInvocationContext): Promise<FlowRunStatus>;
+    cancel(runId: string, context: SparkInvocationContext): Promise<FlowRunCancelled>;
+    deleteCopy(runId: string, context: SparkInvocationContext): Promise<FlowRunCopyDeleted>;
+};
+export declare const FLOW_RUN_WAIT_MAX_SECONDS = 60;
+export declare const FLOW_RUN_WAIT_DEFAULT_SECONDS = 30;
+export declare function createFlowRunsCapability(host: FlowRunsHost): SparkCapability<WompFlowRunsApi>;

package/dist/capabilities/flow-runs.js

@@ -0,0 +1,77 @@
+import { z } from "zod";
+import { WOMP_FLOW_RUNS_DECLARATIONS } from "../generated/flow-runs-declarations.js";
+export const FLOW_RUN_WAIT_MAX_SECONDS = 60;
+export const FLOW_RUN_WAIT_DEFAULT_SECONDS = 30;
+const runId = z
+    .string()
+    .regex(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i, "Use a runId returned by run().");
+const runOptions = z
+    .object({
+    inputs: z.record(z.string().min(1).max(200), z.json()).optional(),
+    copy: z.boolean().optional(),
+    deleteCopy: z.boolean().optional(),
+})
+    .strict()
+    .refine((options) => !options.deleteCopy || options.copy === true, { message: "deleteCopy needs copy: true." });
+const waitSeconds = z.number().int().min(1).max(FLOW_RUN_WAIT_MAX_SECONDS).default(FLOW_RUN_WAIT_DEFAULT_SECONDS);
+export function createFlowRunsCapability(host) {
+    return {
+        skills: [
+            {
+                name: "flow-runs",
+                version: "1",
+                description: "Run the user's saved Flow (AI Nodes) pipeline on their project, follow the run, and report its result.",
+                instructions: `Use womp.flowRuns to run the user's saved Flow pipeline. No canvas needs to be open.
+A run operates on the user's real flow: the input values you pass are written into the flow and become its saved values. describe() lists the inputs by node id with their current values, and the output nodes. Pass only input node ids it lists.
+Only one run of a flow can be live. run() starts the run and returns at once. For a short flow, call wait(runId) and then report the result.
+To leave the user's flow untouched, pass copy: true. The run then happens on a new copy of the project, placed in the user's "Flow runs" folder: the input values, outputs and any scene changes land on the copy, and the user's flow, its saved values and its scene are not changed. Use it when the user wants to try values without changing their flow, or when their flow is busy. A copy run does not lock the scene. run() returns the copy's projectUrl; give it to the user so they can open the result.
+To keep only the result of a copy run, also pass deleteCopy: true: the copy is deleted when the run ends, whether it completed, failed or was cancelled. Use it when the user wants the outputs, not the project; do not give them that run's projectUrl, which stops working (status() then returns projectUrl null).
+To delete a copy run's copy later, call deleteCopy(runId) once the run has ended; it is refused for a run that is still running (cancel it first) or one that did not run on a copy. Right after cancel(), deleteCopy() may answer run_active for about a minute while the run stops: retry later, or pass deleteCopy: true at start instead. Output links keep working after the copy is deleted, either way.
+A run may outlive your turn. If it does, the system reports the result in a follow-up, so do not keep calling status() across many calls.
+When status() or wait() returns an ended run with reported "now", the result is yours to tell the user. With reported "earlier", the result was already reported, earlier in the conversation or by the refusal run() returned to you; do not repeat it.
+Errors start with a code. flow_busy and snapshot_changed mean the user is using the flow: tell them and do not retry. backend_deploying means try again later. not_authorized is final. no_project means the conversation needs a project first.
+Codes starting with input_ mean fix the inputs using describe() and run again. Any other code means tell the user what happened, and do not start another run unless they ask.
+While a run is live on this project (not a copy run), womp.scene.access is refused, for inspecting the scene as well as editing it; womp.scene.health and womp.scene.screenshot still work. To use the scene, wait for the run to end or cancel it.`,
+                declarations: WOMP_FLOW_RUNS_DECLARATIONS,
+                examples: [
+                    "print(await womp.flowRuns.describe());",
+                    'const started = await womp.flowRuns.run({ inputs: { "input-node-id": 123 } }); print(await womp.flowRuns.wait(started.runId, 60));',
+                    'const started = await womp.flowRuns.run({ inputs: { "input-node-id": 123 }, copy: true }); print(started.projectUrl);',
+                    'const started = await womp.flowRuns.run({ inputs: { "input-node-id": 123 }, copy: true, deleteCopy: true }); print(await womp.flowRuns.wait(started.runId, 60));',
+                ],
+            },
+        ],
+        createApi: (context) => {
+            let started = false;
+            return {
+                describe: () => host.describe(context),
+                run: async (options) => {
+                    context.signal.throwIfAborted();
+                    const parsed = runOptions.parse(options ?? {});
+                    if (started)
+                        throw new Error("Start one flow run per JavaScript call. Continue in a new call.");
+                    started = true;
+                    const copy = parsed.copy ?? false;
+                    const start = () => host.start({ inputs: parsed.inputs ?? {}, copy, deleteCopy: parsed.deleteCopy ?? false }, context);
+                    // Copying can outlast the 60 s JavaScript budget; a service wait is
+                    // outside it, so the host's own copy timeout applies instead.
+                    if (copy && context.waitForService)
+                        return context.waitForService("Copying the project", start);
+                    return start();
+                },
+                status: async (id) => host.status(runId.parse(id), context),
+                wait: async (id, seconds) => host.wait(runId.parse(id), waitSeconds.parse(seconds), context),
+                cancel: async (id) => host.cancel(runId.parse(id), context),
+                deleteCopy: async (id) => {
+                    context.signal.throwIfAborted();
+                    const parsed = runId.parse(id);
+                    const remove = () => host.deleteCopy(parsed, context);
+                    // Deleting a project can outlast the 60 s JavaScript budget, as copying one can.
+                    if (context.waitForService)
+                        return context.waitForService("Deleting the copy", remove);
+                    return remove();
+                },
+            };
+        },
+    };
+}

package/dist/capabilities.d.ts

@@ -17,6 +17,8 @@ export { createGeometryCapability } from "./capabilities/geometry.js";
 export type { SceneHealthHost } from "./capabilities/scene.js";
 export { createFlowCapability } from "./capabilities/flow.js";
 export type { FlowHost, FlowSnapshot, FlowWrite, FlowWriteResult, WompFlowApi, } from "./capabilities/flow.js";
+export { createFlowRunsCapability, FLOW_RUN_WAIT_DEFAULT_SECONDS, FLOW_RUN_WAIT_MAX_SECONDS, } from "./capabilities/flow-runs.js";
+export type { FlowRunCancelled, FlowRunCopyDeleted, FlowRunDescription, FlowRunInput, FlowRunLive, FlowRunOutputNode, FlowRunStarted, FlowRunStatus, FlowRunsHost, WompFlowRunsApi, } from "./capabilities/flow-runs.js";
 export type { GeometryHost, GeometryTarget, GeometryInstance, GeometryParamValue, GeometryWrite, GeometryWriteResult, WompGeometryApi, } from "./capabilities/geometry.js";
 export type { WompOpenScadApi, OpenScadHost, OpenScadTarget, OpenScadSource, OpenScadCreate, OpenScadUpdate, OpenScadValidation, OpenScadPrintability, OpenScadWriteResult, } from "./capabilities/openscad.js";
 export type ArtifactRef = {

package/dist/capabilities.js

@@ -6,6 +6,7 @@ export { createAssetsCapability } from "./capabilities/assets.js";
 export { createOpenScadCapability } from "./capabilities/openscad.js";
 export { createGeometryCapability } from "./capabilities/geometry.js";
 export { createFlowCapability } from "./capabilities/flow.js";
+export { createFlowRunsCapability, FLOW_RUN_WAIT_DEFAULT_SECONDS, FLOW_RUN_WAIT_MAX_SECONDS, } from "./capabilities/flow-runs.js";
 /** The enabled bindings are also the only source of discoverable skills. */
 export function composeCapabilities(capabilities) {
     const skills = Object.values(capabilities).flatMap((capability) => capability.skills);

package/dist/generated/flow-runs-declarations.d.ts

@@ -0,0 +1 @@
+export declare const WOMP_FLOW_RUNS_DECLARATIONS = "declare const womp: { flowRuns: {\n\"describe\": (() => Promise<{\n\"projectId\": number;\n\"snapshotId\": string;\n\"inputs\": Array<{\n\"nodeId\": string;\n\"typeId\": string;\n\"valueType\": string;\n\"value\": unknown;\n\"required\": false | true;\n}>;\n\"outputs\": Array<{\n\"nodeId\": string;\n\"typeId\": string;\n}>;\n\"liveRun\": null | {\n\"runId\": string;\n\"trigger\": string;\n};\n}>);\n\"run\": ((options?: undefined | {\n\"inputs\"?: undefined | {\n[key: string]: unknown;\n};\n\"copy\"?: undefined | false | true;\n\"deleteCopy\"?: undefined | false | true;\n}) => Promise<{\n\"runId\": string;\n\"status\": string;\n\"repeated\": false | true;\n\"projectId\": number;\n\"sourceProjectId\": null | number;\n\"projectUrl\": null | string;\n\"deleteCopy\": false | true;\n\"copyDeletedAt\": null | string;\n}>);\n\"status\": ((runId: string) => Promise<{\n\"runId\": string;\n\"status\": string;\n\"outputs\": unknown;\n\"error\": null | string;\n\"errorCode\": null | string;\n\"reported\": null | \"now\" | \"earlier\";\n\"projectId\": number;\n\"sourceProjectId\": null | number;\n\"projectUrl\": null | string;\n\"deleteCopy\": false | true;\n\"copyDeletedAt\": null | string;\n}>);\n\"wait\": ((runId: string, seconds?: undefined | number) => Promise<{\n\"runId\": string;\n\"status\": string;\n\"outputs\": unknown;\n\"error\": null | string;\n\"errorCode\": null | string;\n\"reported\": null | \"now\" | \"earlier\";\n\"projectId\": number;\n\"sourceProjectId\": null | number;\n\"projectUrl\": null | string;\n\"deleteCopy\": false | true;\n\"copyDeletedAt\": null | string;\n}>);\n\"cancel\": ((runId: string) => Promise<{\n\"runId\": string;\n\"status\": string;\n\"cancelled\": false | true;\n}>);\n\"deleteCopy\": ((runId: string) => Promise<{\n\"runId\": string;\n\"copyDeletedAt\": string;\n}>);\n} };\ndeclare function print(...values: unknown[]): void;\ndeclare function emitImage(ref: { id: string; mediaType: string; name?: string }, options?: { inspect?: boolean }): Promise<void>;\ndeclare function emitFile(ref: { id: string; mediaType: string; name?: string }): Promise<void>;\n";

package/dist/generated/flow-runs-declarations.js

@@ -0,0 +1,3 @@
+// Generated by scripts/generate-skill-declarations.mjs.
+// prettier-ignore
+export const WOMP_FLOW_RUNS_DECLARATIONS = "declare const womp: { flowRuns: {\n\"describe\": (() => Promise<{\n\"projectId\": number;\n\"snapshotId\": string;\n\"inputs\": Array<{\n\"nodeId\": string;\n\"typeId\": string;\n\"valueType\": string;\n\"value\": unknown;\n\"required\": false | true;\n}>;\n\"outputs\": Array<{\n\"nodeId\": string;\n\"typeId\": string;\n}>;\n\"liveRun\": null | {\n\"runId\": string;\n\"trigger\": string;\n};\n}>);\n\"run\": ((options?: undefined | {\n\"inputs\"?: undefined | {\n[key: string]: unknown;\n};\n\"copy\"?: undefined | false | true;\n\"deleteCopy\"?: undefined | false | true;\n}) => Promise<{\n\"runId\": string;\n\"status\": string;\n\"repeated\": false | true;\n\"projectId\": number;\n\"sourceProjectId\": null | number;\n\"projectUrl\": null | string;\n\"deleteCopy\": false | true;\n\"copyDeletedAt\": null | string;\n}>);\n\"status\": ((runId: string) => Promise<{\n\"runId\": string;\n\"status\": string;\n\"outputs\": unknown;\n\"error\": null | string;\n\"errorCode\": null | string;\n\"reported\": null | \"now\" | \"earlier\";\n\"projectId\": number;\n\"sourceProjectId\": null | number;\n\"projectUrl\": null | string;\n\"deleteCopy\": false | true;\n\"copyDeletedAt\": null | string;\n}>);\n\"wait\": ((runId: string, seconds?: undefined | number) => Promise<{\n\"runId\": string;\n\"status\": string;\n\"outputs\": unknown;\n\"error\": null | string;\n\"errorCode\": null | string;\n\"reported\": null | \"now\" | \"earlier\";\n\"projectId\": number;\n\"sourceProjectId\": null | number;\n\"projectUrl\": null | string;\n\"deleteCopy\": false | true;\n\"copyDeletedAt\": null | string;\n}>);\n\"cancel\": ((runId: string) => Promise<{\n\"runId\": string;\n\"status\": string;\n\"cancelled\": false | true;\n}>);\n\"deleteCopy\": ((runId: string) => Promise<{\n\"runId\": string;\n\"copyDeletedAt\": string;\n}>);\n} };\ndeclare function print(...values: unknown[]): void;\ndeclare function emitImage(ref: { id: string; mediaType: string; name?: string }, options?: { inspect?: boolean }): Promise<void>;\ndeclare function emitFile(ref: { id: string; mediaType: string; name?: string }): Promise<void>;\n";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@womp/spark-agent",
-  "version": "9.1.0",
+  "version": "9.2.0",
   "description": "Portable skills-based AI agent with local and durable chat transports for Womp",
   "type": "module",
   "main": "./dist/index.js",