@cargo-ai/cli 1.0.29 → 1.0.31

package/README.md

@@ -136,11 +136,10 @@ cargo-ai orchestration release deploy-draft --file ./my-workflow.ts --workflow-u
 cargo-ai orchestration release deploy-draft --workflow-uuid <uuid> --nodes '[…]' --form-fields '[…]'
 ```
 
-`--file <path>` loads a [`@cargo-ai/workflow-sdk`](../workflow-sdk/README.md) module (its `export default defineWorkflow(...)`) and sources `nodes` / `formFields` / `description` from the compiled output. With `--file`:
+`--file <path>` loads a `@cargo-ai/workflow-sdk` module (its `export default defineWorkflow(...)`) and sources `nodes` / `formFields` from the compiled output. With `--file`:
 
 - `--workflow-uuid` is optional — when omitted, the command best-effort matches the compiled `slug` against existing workflows' `template.slug` and errors if the match is missing or ambiguous.
 - `--version` defaults to the next minor bump over the latest existing release (or `1.0.0` for the first).
-- `--description` defaults to the compiled workflow's description.
 - `--nodes` / `--form-fields` are rejected (they're sourced from the module).
 
 Without `--file`, `--workflow-uuid`, `--nodes`, and `--form-fields` are all required (raw JSON path). Constraint either way: there is **no** workflow-create endpoint, so the target workflow must already exist.

package/build/commands/ai/message.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"message.d.ts","sourceRoot":"","sources":["../../../src/commands/ai/message.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAQxC,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,MAAM,GAAG,GAChB,IAAI,CAgMN"}
+{"version":3,"file":"message.d.ts","sourceRoot":"","sources":["../../../src/commands/ai/message.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAiCxC,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,MAAM,GAAG,GAChB,IAAI,CA2RN"}

package/build/commands/ai/message.js

@@ -1,13 +1,20 @@
-import { handleApiCall, outputJson, parseJson, pollMessageUntilFinished, } from "../runHandler.js";
+import { loadCompiledAgent, resolveCompiledAgentFromState, } from "../../utils/loadCompiledAgent.js";
+import { ExitCodes, failWith, handleApiCall, info, outputJson, parseJson, pollMessageUntilFinished, } from "../runHandler.js";
 export function registerMessageCommands(parent, getApi) {
     const message = parent
         .command("message")
         .description("Manage chat messages (create, get, list, cancel, remove)");
     message
         .command("create")
-        .description("Create a message in a chat. Returns the user message and a pending assistant message.")
-        .requiredOption("--chat-uuid <uuid>", "Chat UUID (string, required)")
+        .description("Create a message in a chat. Returns the user message and a pending " +
+        "assistant message. Pass --file to test-message a defineAgent " +
+        "module inline (its @cargo-ai/cdk handles resolved from " +
+        "cargo.state.json — no deploy).")
+        .option("--chat-uuid <uuid>", "Chat UUID (string). When omitted, a new draft chat is created automatically.")
+        .option("--agent-uuid <uuid>", "Agent UUID for the auto-created chat (string, only used when --chat-uuid is omitted)")
+        .option("--release-uuid <uuid>", "Release UUID for the auto-created chat (string, only used when --chat-uuid is omitted)")
         .requiredOption("--parts <json>", "Message parts (JSON array of part objects, required)")
+        .option("--file <path>", "Path to a @cargo-ai/cdk module whose default export is a defineAgent() handle. Compiles it, resolves its resource handles to real uuids from cargo.state.json, and sends the agent's prompt/tools/models/capabilities inline — no deploy. Rejected with the inline flags (and --agent-uuid / --release-uuid).")
         .option("--actions <json>", "Actions available to the assistant (JSON array of action objects)")
         .option("--resources <json>", "Resources available to the assistant (JSON array of resource objects)")
         .option("--capabilities <json>", "Capabilities to enable (JSON array of capability objects)")
@@ -25,6 +32,9 @@ export function registerMessageCommands(parent, getApi) {
         .addHelpText("after", `
 Examples:
   $ cargo-ai ai message create --chat-uuid 550e8400-... --parts '[{"type":"text","text":"Hello"}]'
+  $ cargo-ai ai message create --parts '[{"type":"text","text":"Hello"}]'
+  $ cargo-ai ai message create --agent-uuid 550e8400-... --parts '[{"type":"text","text":"Hello"}]'
+  $ cargo-ai ai message create --file ./agents/researcher.ts --parts '[{"type":"text","text":"Research acme.com"}]' --wait-until-finished
   $ cargo-ai ai message create --chat-uuid 550e8400-... --parts '[{"type":"text","text":"Find leads"}]' \\
       --actions '[{"slug":"search","kind":"tool","config":{}}]' --wait-until-finished
 
@@ -34,35 +44,91 @@ Resource object shape: { "slug": string, "kind": "model", "modelUuid": string }
 MCP client shape:      { "name": string, "url": string }`)
         .action(async (opts) => {
         const api = getApi();
+        // --file test-messages a defineAgent module: it supplies the whole
+        // LLM / tools / models / capabilities inline (no deploy), so the flags
+        // that would otherwise set those — plus the deployed-agent bindings —
+        // are rejected in its favour.
+        let params;
+        if (opts.file !== undefined) {
+            const conflicts = [
+                ["--agent-uuid", opts.agentUuid],
+                ["--release-uuid", opts.releaseUuid],
+                ["--actions", opts.actions],
+                ["--resources", opts.resources],
+                ["--capabilities", opts.capabilities],
+                ["--mcp-clients", opts.mcpClients],
+                ["--system-prompt", opts.systemPrompt],
+                ["--with-reasoning", opts.withReasoning],
+                ["--temperature", opts.temperature],
+                ["--max-steps", opts.maxSteps],
+                ["--integration-slug", opts.integrationSlug],
+                ["--connector-uuid", opts.connectorUuid],
+                ["--language-model-slug", opts.languageModelSlug],
+                ["--output", opts.output],
+            ]
+                .filter(([, value]) => value !== undefined)
+                .map(([flag]) => flag);
+            if (conflicts.length > 0) {
+                failWith(`${conflicts.join(", ")} not allowed with --file (sourced from the agent).`, { code: ExitCodes.InvalidUsage });
+            }
+            const compiled = await loadCompiledAgent(opts.file);
+            const resolved = resolveCompiledAgentFromState(compiled, opts.file);
+            params = {
+                actions: resolved.actions,
+                resources: resolved.resources,
+                capabilities: resolved.capabilities,
+                mcpClients: resolved.mcpClients,
+                systemPrompt: resolved.systemPrompt,
+                withReasoning: resolved.withReasoning,
+                temperature: resolved.temperature,
+                maxSteps: resolved.maxSteps,
+                connectorUuid: resolved.connectorUuid,
+                languageModelSlug: resolved.languageModelSlug,
+                output: resolved.output,
+            };
+            if (resolved.connectorUuid !== undefined) {
+                const uuid = resolved.connectorUuid;
+                const connectorResult = await handleApiCall(() => api.connection.connector.get({ uuid }));
+                params.integrationSlug = connectorResult.connector.integrationSlug;
+            }
+            info(`Test-messaging agent "${compiled.slug}" — no deploy.`);
+        }
+        else {
+            params = {
+                actions: opts.actions !== undefined
+                    ? parseJson(opts.actions, "--actions")
+                    : undefined,
+                resources: opts.resources !== undefined
+                    ? parseJson(opts.resources, "--resources")
+                    : undefined,
+                capabilities: opts.capabilities !== undefined
+                    ? parseJson(opts.capabilities, "--capabilities")
+                    : undefined,
+                mcpClients: opts.mcpClients !== undefined
+                    ? parseJson(opts.mcpClients, "--mcp-clients")
+                    : undefined,
+                systemPrompt: opts.systemPrompt,
+                withReasoning: opts.withReasoning,
+                temperature: opts.temperature !== undefined
+                    ? parseFloat(opts.temperature)
+                    : undefined,
+                maxSteps: opts.maxSteps !== undefined
+                    ? parseInt(opts.maxSteps, 10)
+                    : undefined,
+                integrationSlug: opts.integrationSlug,
+                connectorUuid: opts.connectorUuid,
+                languageModelSlug: opts.languageModelSlug,
+                output: opts.output !== undefined
+                    ? parseJson(opts.output, "--output")
+                    : undefined,
+            };
+        }
         const result = await handleApiCall(() => api.ai.message.create({
             chatUuid: opts.chatUuid,
+            agentUuid: opts.agentUuid,
+            releaseUuid: opts.releaseUuid,
             parts: parseJson(opts.parts, "--parts"),
-            actions: opts.actions !== undefined
-                ? parseJson(opts.actions, "--actions")
-                : undefined,
-            resources: opts.resources !== undefined
-                ? parseJson(opts.resources, "--resources")
-                : undefined,
-            capabilities: opts.capabilities !== undefined
-                ? parseJson(opts.capabilities, "--capabilities")
-                : undefined,
-            mcpClients: opts.mcpClients !== undefined
-                ? parseJson(opts.mcpClients, "--mcp-clients")
-                : undefined,
-            systemPrompt: opts.systemPrompt,
-            withReasoning: opts.withReasoning,
-            temperature: opts.temperature !== undefined
-                ? parseFloat(opts.temperature)
-                : undefined,
-            maxSteps: opts.maxSteps !== undefined
-                ? parseInt(opts.maxSteps, 10)
-                : undefined,
-            integrationSlug: opts.integrationSlug,
-            connectorUuid: opts.connectorUuid,
-            languageModelSlug: opts.languageModelSlug,
-            output: opts.output !== undefined
-                ? parseJson(opts.output, "--output")
-                : undefined,
+            ...params,
         }));
         if (opts.waitUntilFinished === true) {
             const intervalMs = parseInt(opts.pollingInterval, 10);

package/build/commands/content/file.js

@@ -45,11 +45,11 @@ export function registerFileCommands(parent, getApi) {
     file
         .command("upload")
         .description("Upload a file")
-        .requiredOption("--file-path <path>", "Path to the file to upload")
+        .requiredOption("--file <path>", "Path to the file to upload")
         .option("--folder-uuid <uuid>", "Folder UUID")
         .action(async (opts) => {
-        const buffer = await readFile(opts.filePath);
-        const name = basename(opts.filePath);
+        const buffer = await readFile(opts.file);
+        const name = basename(opts.file);
         const fileObj = new File([buffer], name);
         const api = getApi();
         await handleApiCall(() => new Promise((resolve, reject) => {

package/build/commands/orchestration/batch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"batch.d.ts","sourceRoot":"","sources":["../../../src/commands/orchestration/batch.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAQxC,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,MAAM,GAAG,GAChB,IAAI,CAyON"}
+{"version":3,"file":"batch.d.ts","sourceRoot":"","sources":["../../../src/commands/orchestration/batch.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAexC,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,MAAM,GAAG,GAChB,IAAI,CA2QN"}

package/build/commands/orchestration/batch.js

@@ -1,4 +1,5 @@
-import { handleApiCall, outputJson, parseJson, pollBatchUntilFinished, } from "../runHandler.js";
+import { loadCompiledWorkflow, resolveCompiledWorkflowFromState, } from "../../utils/loadCompiledWorkflow.js";
+import { ExitCodes, failWith, handleApiCall, info, outputJson, parseJson, pollBatchUntilFinished, } from "../runHandler.js";
 export function registerBatchCommands(parent, getApi) {
     const batch = parent
         .command("batch")
@@ -60,25 +61,42 @@ export function registerBatchCommands(parent, getApi) {
     });
     batch
         .command("create")
-        .description("Create a batch")
+        .description("Create a batch. Pass --file to test-run a Workflow SDK module (compiled and " +
+        "run as custom nodes, with @cargo-ai/cdk handles resolved from cargo.state.json — no deploy).")
         .option("--workflow-uuid <uuid>", "Workflow UUID (string)")
         .requiredOption("--data <json>", 'Batch data source (JSON object, required). Supported kinds: {"kind":"segment","segmentUuid":"..."} or {"kind":"file","s3Filename":"..."}')
         .option("--release-uuid <uuid>", "Release UUID to pin the batch to (string)")
-        .option("--nodes <json>", "Custom nodes to override the workflow definition (JSON array).")
+        .option("--file <path>", "Path to a Workflow SDK module (its default export must be the compiled workflow returned by defineWorkflow()). Compiles it, resolves any @cargo-ai/cdk resource handles to real uuids from cargo.state.json, and runs the resulting nodes. Rejected with --nodes.")
+        .option("--nodes <json>", "Custom nodes to override the workflow definition (JSON array). Rejected with --file.")
         .option("--wait-until-finished", "Poll the batch until it reaches a terminal status before returning (boolean flag)")
         .option("--polling-interval <ms>", "Polling interval in milliseconds, used with --wait-until-finished (integer, default: 5000)", "5000")
         .addHelpText("after", `
 Examples:
   $ cargo-ai orchestration batch create --data '{"kind":"segment","segmentUuid":"550e8400-..."}'
-  $ cargo-ai orchestration batch create --workflow-uuid 550e8400-... --data '{"kind":"file","s3Filename":"input.csv"}' --wait-until-finished`)
+  $ cargo-ai orchestration batch create --workflow-uuid 550e8400-... --data '{"kind":"file","s3Filename":"input.csv"}' --wait-until-finished
+  $ cargo-ai orchestration batch create --file ./plays/onboarding.ts --data '{"kind":"segment","segmentUuid":"550e8400-..."}' --wait-until-finished`)
         .action(async (opts) => {
+        // `--file` compiles a Workflow SDK module and runs its (state-resolved)
+        // nodes ad-hoc; `--nodes` supplies a raw node graph. They're mutually
+        // exclusive sources for the same payload field.
+        let nodes;
+        if (opts.file !== undefined) {
+            if (opts.nodes !== undefined) {
+                failWith("--nodes is not allowed with --file (sourced from the module)", { code: ExitCodes.InvalidUsage });
+            }
+            const compiled = await loadCompiledWorkflow(opts.file);
+            const resolved = resolveCompiledWorkflowFromState(compiled, opts.file);
+            info(`Test-running "${resolved.slug}" (${String(resolved.nodes.length)} node(s)) — no deploy.`);
+            nodes = resolved.nodes;
+        }
+        else if (opts.nodes !== undefined) {
+            nodes = parseJson(opts.nodes, "--nodes");
+        }
         const api = getApi();
         const result = await handleApiCall(() => api.orchestration.batch.create({
             workflowUuid: opts.workflowUuid,
             releaseUuid: opts.releaseUuid,
-            nodes: opts.nodes !== undefined
-                ? parseJson(opts.nodes, "--nodes")
-                : undefined,
+            nodes,
             data: parseJson(opts.data, "--data"),
         }));
         if (opts.waitUntilFinished === true) {

package/build/commands/orchestration/release.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"release.d.ts","sourceRoot":"","sources":["../../../src/commands/orchestration/release.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAyCxC,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,MAAM,GAAG,GAChB,IAAI,CAkLN"}
+{"version":3,"file":"release.d.ts","sourceRoot":"","sources":["../../../src/commands/orchestration/release.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAmCxC,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,MAAM,GAAG,GAChB,IAAI,CA+KN"}

package/build/commands/orchestration/release.js

@@ -1,6 +1,4 @@
-import { existsSync } from "node:fs";
-import { isAbsolute, resolve } from "node:path";
-import { pathToFileURL } from "node:url";
+import { loadCompiledWorkflow, } from "../../utils/loadCompiledWorkflow.js";
 import { ExitCodes, failWith, handleApiCall, info, outputJson, parseJson, success, } from "../runHandler.js";
 export function registerReleaseCommands(parent, getApi) {
     const release = parent
@@ -90,7 +88,7 @@ export function registerReleaseCommands(parent, getApi) {
         .option("--version <version>", "Release version (e.g. '1.2.0'). With --file, defaults to the next minor bump over the latest existing release; otherwise required by the engine.")
         .option("--nodes <json>", "Nodes (JSON array of node definitions). Required without --file; rejected with --file.")
         .option("--form-fields <json>", "Form fields (JSON array, or 'null'). Required without --file; rejected with --file.")
-        .option("--description <text>", "Release description (with --file, defaults to the compiled workflow's description).")
+        .option("--description <text>", "Release description.")
         .option("--options <json>", "Options (JSON object)")
         .option("--dry-run", "With --file: compile and print the nodes + form fields without deploying. Ignored without --file.")
         .action(async (opts) => {
@@ -157,7 +155,6 @@ async function runFileDeploy(getApi, opts) {
     if (opts.dryRun === true) {
         outputJson({
             slug: compiled.slug,
-            description: compiled.description,
             nodes: compiled.nodes,
             formFields: compiled.formFields,
         });
@@ -168,14 +165,13 @@ async function runFileDeploy(getApi, opts) {
     const version = opts.version !== undefined
         ? opts.version
         : await computeNextVersion(api, workflowUuid);
-    const description = opts.description !== undefined ? opts.description : compiled.description;
     info(`Deploying "${compiled.slug}" → workflow ${workflowUuid} as v${version} (${String(compiled.nodes.length)} node(s))…`);
     const payload = {
         workflowUuid,
         version,
         nodes: compiled.nodes,
         formFields: compiled.formFields,
-        description,
+        description: opts.description,
         options: opts.options !== undefined
             ? parseJson(opts.options, "--options")
             : undefined,
@@ -184,52 +180,6 @@ async function runFileDeploy(getApi, opts) {
     success(`Deployed v${version}.`);
     outputJson(result);
 }
-// Load a workflow module via the tsx ESM loader so `.ts` sources (and their
-// imports of `@cargo-ai/workflow-sdk` / `zod`) are transpiled on the fly,
-// returning its default export validated as a compiled workflow.
-async function loadCompiledWorkflow(file) {
-    const absPath = isAbsolute(file) ? file : resolve(process.cwd(), file);
-    if (!existsSync(absPath)) {
-        failWith(`Workflow file not found: ${absPath}`, {
-            code: ExitCodes.InvalidUsage,
-        });
-    }
-    let mod;
-    try {
-        const { tsImport } = await import("tsx/esm/api");
-        mod = (await tsImport(pathToFileURL(absPath).href, import.meta.url));
-    }
-    catch (error) {
-        failWith(`Failed to load workflow module: ${error instanceof Error ? error.message : String(error)}`, { code: ExitCodes.GenericError });
-    }
-    const candidate = resolveDefaultExport(mod);
-    if (!isCompiledWorkflow(candidate)) {
-        failWith("Workflow module must `export default` a compiled workflow (the value returned by defineWorkflow()).", { code: ExitCodes.InvalidUsage });
-    }
-    return candidate;
-}
-// Peel the extra interop layer tsx adds when a TS source is transpiled to
-// CJS: the ESM namespace's `default` is then the CJS `module.exports`
-// (`{ __esModule: true, default: … }`), so the real value lives one level
-// deeper. True-ESM modules expose it directly.
-function resolveDefaultExport(mod) {
-    const top = mod.default;
-    if (top !== null && typeof top === "object") {
-        const inner = top;
-        if (inner["__esModule"] === true && "default" in inner) {
-            return inner["default"];
-        }
-    }
-    return top;
-}
-function isCompiledWorkflow(value) {
-    if (value === null || typeof value !== "object")
-        return false;
-    const v = value;
-    return (typeof v["slug"] === "string" &&
-        Array.isArray(v["nodes"]) &&
-        Array.isArray(v["formFields"]));
-}
 // Resolve the target workflow UUID. The platform `Workflow` has no free-form
 // slug field — the closest stable identifier is `template.slug` — and there
 // is no `workflow.create` endpoint, so an explicit `--workflow-uuid` always

package/build/commands/orchestration/run.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../../src/commands/orchestration/run.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAQxC,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,GAAG,IAAI,CAmlB5E"}
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../../src/commands/orchestration/run.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAexC,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,GAAG,IAAI,CAsnB5E"}

package/build/commands/orchestration/run.js

@@ -1,4 +1,5 @@
-import { handleApiCall, outputJson, parseJson, pollRunUntilFinished, } from "../runHandler.js";
+import { loadCompiledWorkflow, resolveCompiledWorkflowFromState, } from "../../utils/loadCompiledWorkflow.js";
+import { ExitCodes, failWith, handleApiCall, info, outputJson, parseJson, pollRunUntilFinished, } from "../runHandler.js";
 export function registerRunCommands(parent, getApi) {
     const run = parent
         .command("run")
@@ -69,27 +70,44 @@ Examples:
     });
     run
         .command("create")
-        .description("Create a run")
+        .description("Create a run. Pass --file to test-run a Workflow SDK module (compiled and " +
+        "run as custom nodes, with @cargo-ai/cdk handles resolved from cargo.state.json — no deploy).")
         .option("--workflow-uuid <uuid>", "Workflow UUID (string)")
         .requiredOption("--data <json>", "Run input data (JSON object, required). The shape depends on your workflow's start node configuration")
         .option("--release-uuid <uuid>", "Release UUID to pin the run to (string)")
-        .option("--nodes <json>", "Custom nodes to override the workflow definition (JSON array).")
+        .option("--file <path>", "Path to a Workflow SDK module (its default export must be the compiled workflow returned by defineWorkflow()). Compiles it, resolves any @cargo-ai/cdk resource handles to real uuids from cargo.state.json, and runs the resulting nodes. Rejected with --nodes.")
+        .option("--nodes <json>", "Custom nodes to override the workflow definition (JSON array). Rejected with --file.")
         .option("--wait-until-finished", "Poll the run until it reaches a terminal status before returning (boolean flag)")
         .option("--polling-interval <ms>", "Polling interval in milliseconds, used with --wait-until-finished (integer, default: 5000)", "5000")
         .addHelpText("after", `
 Examples:
   $ cargo-ai orchestration run create --data '{"email":"user@example.com"}'
   $ cargo-ai orchestration run create --workflow-uuid 550e8400-... --data '{"id":"123"}' --wait-until-finished
-  $ cargo-ai orchestration run create --data '{"id":"123"}' --wait-until-finished --polling-interval 10000`)
+  $ cargo-ai orchestration run create --data '{"id":"123"}' --wait-until-finished --polling-interval 10000
+  $ cargo-ai orchestration run create --file ./plays/onboarding.ts --data '{"domain":"acme.com"}' --wait-until-finished`)
         .action(async (opts) => {
         const data = parseJson(opts.data, "--data");
+        // `--file` compiles a Workflow SDK module and runs its (state-resolved)
+        // nodes ad-hoc; `--nodes` supplies a raw node graph. They're mutually
+        // exclusive sources for the same payload field.
+        let nodes;
+        if (opts.file !== undefined) {
+            if (opts.nodes !== undefined) {
+                failWith("--nodes is not allowed with --file (sourced from the module)", { code: ExitCodes.InvalidUsage });
+            }
+            const compiled = await loadCompiledWorkflow(opts.file);
+            const resolved = resolveCompiledWorkflowFromState(compiled, opts.file);
+            info(`Test-running "${resolved.slug}" (${String(resolved.nodes.length)} node(s)) — no deploy.`);
+            nodes = resolved.nodes;
+        }
+        else if (opts.nodes !== undefined) {
+            nodes = parseJson(opts.nodes, "--nodes");
+        }
         const api = getApi();
         const result = await handleApiCall(() => api.orchestration.run.create({
             workflowUuid: opts.workflowUuid,
             releaseUuid: opts.releaseUuid,
-            nodes: opts.nodes !== undefined
-                ? parseJson(opts.nodes, "--nodes")
-                : undefined,
+            nodes,
             data,
         }));
         if (opts.waitUntilFinished === true) {

package/build/commands/workspaceManagement/file.js

@@ -6,10 +6,10 @@ export function registerFileCommands(parent, getApi) {
     file
         .command("upload")
         .description("Upload a file")
-        .requiredOption("--file-path <path>", "Path to the file to upload")
+        .requiredOption("--file <path>", "Path to the file to upload")
         .action(async (opts) => {
-        const buffer = await readFile(opts.filePath);
-        const name = basename(opts.filePath);
+        const buffer = await readFile(opts.file);
+        const name = basename(opts.file);
         const fileObj = new File([buffer], name);
         const api = getApi();
         await handleApiCall(() => new Promise((resolve, reject) => {

package/build/utils/cdkState.d.ts

@@ -0,0 +1,26 @@
+export declare function resolveDefaultExport(mod: {
+    default?: unknown;
+}): unknown;
+/**
+ * Load a `.ts`/`.js` module through the tsx ESM loader (so `.ts` sources and
+ * their imports of `@cargo-ai/*` / `zod` are transpiled on the fly) and return
+ * its resolved default export. Shared by both `--file` loaders: the workflow
+ * loader validates the result as a compiled workflow; the agent loader reads the
+ * agent back out of the CDK registry that loading populated (so it must
+ * `resetRegistry()` BEFORE calling this). `subject` labels the file in errors
+ * (e.g. "Workflow", "Agent").
+ */
+export declare function importModuleDefault(file: string, subject: string): Promise<{
+    absPath: string;
+    defaultExport: unknown;
+}>;
+/**
+ * Deep-resolve every `@cargo-ai/cdk` handle token in `value` to its real uuid
+ * using the nearest cargo.state.json (searched from `file`'s directory upward,
+ * then the cwd). `subject` names the thing under test in error messages (e.g. a
+ * workflow or agent slug). A value with no tokens (literal-uuid refs, or a pure
+ * body) is returned unchanged — no state needed. Fails with an actionable error
+ * when state is missing or a referenced resource isn't deployed yet.
+ */
+export declare function resolveTokensFromState(value: unknown, file: string, subject: string): unknown;
+//# sourceMappingURL=cdkState.d.ts.map

package/build/utils/cdkState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cdkState.d.ts","sourceRoot":"","sources":["../../src/utils/cdkState.ts"],"names":[],"mappings":"AAmBA,wBAAgB,oBAAoB,CAAC,GAAG,EAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CASxE;AAED;;;;;;;;GAQG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GACd,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,OAAO,CAAA;CAAE,CAAC,CAyBtD;AAaD;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GACd,OAAO,CAuCT"}

package/build/utils/cdkState.js

@@ -0,0 +1,101 @@
+// Shared helpers for the CLI `--file` paths that compile a
+// `@cargo-ai/cdk`-aware module (a Workflow SDK workflow, or a `defineAgent`) and
+// test-run it against ALREADY-DEPLOYED resources. Both need the same two things:
+// peel the tsx interop layer off a module's default export, and resolve any
+// `@cargo-ai/cdk` handle tokens the module references to their real uuids from
+// the committed cargo.state.json — without deploying the module itself.
+import { existsSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { dependenciesOf, readState, resolveTokens } from "@cargo-ai/cdk";
+import { ExitCodes, failWith } from "../commands/runHandler.js";
+// Peel the extra interop layer tsx adds when a TS source is transpiled to CJS:
+// the ESM namespace's `default` is then the CJS `module.exports`
+// (`{ __esModule: true, default: … }`), so the real value lives one level
+// deeper. True-ESM modules expose it directly.
+export function resolveDefaultExport(mod) {
+    const top = mod.default;
+    if (top !== null && typeof top === "object") {
+        const inner = top;
+        if (inner["__esModule"] === true && "default" in inner) {
+            return inner["default"];
+        }
+    }
+    return top;
+}
+/**
+ * Load a `.ts`/`.js` module through the tsx ESM loader (so `.ts` sources and
+ * their imports of `@cargo-ai/*` / `zod` are transpiled on the fly) and return
+ * its resolved default export. Shared by both `--file` loaders: the workflow
+ * loader validates the result as a compiled workflow; the agent loader reads the
+ * agent back out of the CDK registry that loading populated (so it must
+ * `resetRegistry()` BEFORE calling this). `subject` labels the file in errors
+ * (e.g. "Workflow", "Agent").
+ */
+export async function importModuleDefault(file, subject) {
+    const absPath = isAbsolute(file) ? file : resolve(process.cwd(), file);
+    if (!existsSync(absPath)) {
+        failWith(`${subject} file not found: ${absPath}`, {
+            code: ExitCodes.InvalidUsage,
+        });
+    }
+    let mod;
+    try {
+        const { tsImport } = await import("tsx/esm/api");
+        mod = (await tsImport(pathToFileURL(absPath).href, import.meta.url));
+    }
+    catch (error) {
+        failWith(`Failed to load ${subject.toLowerCase()} module: ${error instanceof Error ? error.message : String(error)}`, { code: ExitCodes.GenericError });
+    }
+    return { absPath, defaultExport: resolveDefaultExport(mod) };
+}
+// Walk up from `startDir` looking for a directory that holds cargo.state.json.
+function findStateRoot(startDir) {
+    let dir = startDir;
+    for (;;) {
+        if (existsSync(join(dir, "cargo.state.json")))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+}
+/**
+ * Deep-resolve every `@cargo-ai/cdk` handle token in `value` to its real uuid
+ * using the nearest cargo.state.json (searched from `file`'s directory upward,
+ * then the cwd). `subject` names the thing under test in error messages (e.g. a
+ * workflow or agent slug). A value with no tokens (literal-uuid refs, or a pure
+ * body) is returned unchanged — no state needed. Fails with an actionable error
+ * when state is missing or a referenced resource isn't deployed yet.
+ */
+export function resolveTokensFromState(value, file, subject) {
+    const deps = dependenciesOf(value);
+    if (deps.size === 0)
+        return value;
+    const absPath = isAbsolute(file) ? file : resolve(process.cwd(), file);
+    const stateRoot = findStateRoot(dirname(absPath)) ?? findStateRoot(process.cwd());
+    if (stateRoot === undefined) {
+        failWith(`${subject} references ${String(deps.size)} deployed resource(s) ` +
+            `(${[...deps].join(", ")}), but no cargo.state.json was found near ` +
+            `${absPath} or the current directory. Deploy the resources first with ` +
+            "`cargo-ai cdk deploy`, or reference them by literal uuid " +
+            "(toolRef / agentRef / connectorRef).", { code: ExitCodes.NotFound });
+    }
+    const state = readState(stateRoot);
+    const outputs = new Map();
+    if (state !== undefined) {
+        for (const [id, entry] of Object.entries(state.resources)) {
+            outputs.set(id, entry.outputs);
+        }
+    }
+    const missing = [...deps].filter((id) => !outputs.has(id));
+    if (missing.length > 0) {
+        failWith(`${String(missing.length)} resource(s) referenced by ${subject} ` +
+            `aren't in cargo.state.json yet: ${missing.join(", ")}. A test run ` +
+            "resolves existing (already-deployed) resources from state — it won't " +
+            "create new ones. Deploy them first with `cargo-ai cdk deploy`, or " +
+            "reference them by literal uuid (toolRef / agentRef / connectorRef).", { code: ExitCodes.NotFound });
+    }
+    return resolveTokens(value, outputs);
+}

package/build/utils/loadCompiledAgent.d.ts

@@ -0,0 +1,5 @@
+import { type CompiledAgent } from "@cargo-ai/cdk";
+export type { CompiledAgent } from "@cargo-ai/cdk";
+export declare function loadCompiledAgent(file: string): Promise<CompiledAgent>;
+export declare function resolveCompiledAgentFromState(compiled: CompiledAgent, file: string): CompiledAgent;
+//# sourceMappingURL=loadCompiledAgent.d.ts.map

package/build/utils/loadCompiledAgent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loadCompiledAgent.d.ts","sourceRoot":"","sources":["../../src/utils/loadCompiledAgent.ts"],"names":[],"mappings":"AAUA,OAAO,EAEL,KAAK,aAAa,EAInB,MAAM,eAAe,CAAC;AAKvB,YAAY,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAqCnD,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CA6C5E;AAQD,wBAAgB,6BAA6B,CAC3C,QAAQ,EAAE,aAAa,EACvB,IAAI,EAAE,MAAM,GACX,aAAa,CAQf"}

package/build/utils/loadCompiledAgent.js

@@ -0,0 +1,75 @@
+// The `ai message create --file` path: compile a `@cargo-ai/cdk` `defineAgent`
+// module and lower it to the params an `ai message create` accepts, so you can
+// chat against an agent's real prompt / tools / models / capabilities WITHOUT
+// deploying it. Two steps mirror the workflow `--file` flow: `loadCompiledAgent`
+// runs the module's `define*` calls into the shared CDK registry, reads the
+// agent back, and maps its buckets with the SAME transform `cdk deploy` uses
+// (`compileAgent`); `resolveCompiledAgentFromState` then resolves the
+// `@cargo-ai/cdk` handle tokens it still carries to real uuids from
+// cargo.state.json — a faithful test of the agent's core chat behaviour.
+import { compileAgent, resetRegistry, resources, } from "@cargo-ai/cdk";
+import { ExitCodes, failWith } from "../commands/runHandler.js";
+import { importModuleDefault, resolveTokensFromState } from "./cdkState.js";
+function isAgentHandle(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    const v = value;
+    return v["resource"] === "agent" && typeof v["slug"] === "string";
+}
+// Agent config an inline message can't express — rejected up front (rather than
+// silently dropped) so a test run is never quietly less than the deployed agent.
+// Each entry: the spec field, and whether the stored value means "set".
+const UNSUPPORTED = [
+    { field: "evaluator", label: "evaluator", isSet: (v) => v !== null },
+    { field: "heartbeat", label: "heartbeat", isSet: (v) => v !== null },
+    {
+        field: "triggers",
+        label: "triggers",
+        isSet: (v) => Array.isArray(v) && v.length > 0,
+    },
+    {
+        field: "suggestedActions",
+        label: "suggestedActions",
+        isSet: (v) => Array.isArray(v) && v.length > 0,
+    },
+];
+// Load a `defineAgent` module and lower it to a `CompiledAgent` (tokens still
+// embedded — resolve them with `resolveCompiledAgentFromState`). `resetRegistry`
+// first so a stale registry (e.g. a prior load in the same process) can't leak
+// resources into this one.
+export async function loadCompiledAgent(file) {
+    // Reset BEFORE loading: the import runs the module's `define*` calls, which
+    // register into the shared CDK registry we read back below. A stale registry
+    // (e.g. a prior load in the same process) would otherwise leak in.
+    resetRegistry();
+    const { absPath, defaultExport: handle } = await importModuleDefault(file, "Agent");
+    if (!isAgentHandle(handle)) {
+        failWith("Agent module must `export default` an agent handle (the value returned by defineAgent()).", { code: ExitCodes.InvalidUsage });
+    }
+    // A file can register several agents (its sub-agents), so pick THE one it
+    // exports by slug rather than assuming a single registration.
+    const node = resources().find((n) => n.kind === "agent" && n.slug === handle.slug);
+    if (node === undefined) {
+        failWith(`Agent "${handle.slug}" was not registered by ${absPath}. Ensure the ` +
+            "module's default export is the handle returned by defineAgent().", { code: ExitCodes.GenericError });
+    }
+    const setUnsupported = UNSUPPORTED.filter((u) => u.isSet(node.spec[u.field])).map((u) => u.label);
+    if (setUnsupported.length > 0) {
+        failWith(`Agent "${handle.slug}" sets ${setUnsupported.join(", ")}, which a test ` +
+            "message can't apply (they only take effect on a deployed release). " +
+            "Remove them for a test run, or deploy the agent with `cargo-ai cdk " +
+            "deploy` and chat against it by uuid.", { code: ExitCodes.InvalidUsage });
+    }
+    return compileAgent(node.spec);
+}
+// Resolve the agent params' `@cargo-ai/cdk` resource handles (tool / agent /
+// connector / model) to their real uuids using the committed cargo.state.json,
+// so a test message runs against the ALREADY-DEPLOYED resources without
+// deploying the agent itself. Returns the same compiled agent with engine-ready
+// params. An agent with no handle tokens (literal-uuid refs) is returned
+// unchanged — no state needed.
+export function resolveCompiledAgentFromState(compiled, file) {
+    // The slug is a plain string (no token), so resolving the whole object is
+    // safe and keeps it flat.
+    return resolveTokensFromState(compiled, file, `"${compiled.slug}"`);
+}

package/build/utils/loadCompiledWorkflow.d.ts

@@ -0,0 +1,8 @@
+export type CompiledWorkflow = {
+    slug: string;
+    nodes: unknown[];
+    formFields: unknown[];
+};
+export declare function loadCompiledWorkflow(file: string): Promise<CompiledWorkflow>;
+export declare function resolveCompiledWorkflowFromState(compiled: CompiledWorkflow, file: string): CompiledWorkflow;
+//# sourceMappingURL=loadCompiledWorkflow.d.ts.map

package/build/utils/loadCompiledWorkflow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loadCompiledWorkflow.d.ts","sourceRoot":"","sources":["../../src/utils/loadCompiledWorkflow.ts"],"names":[],"mappings":"AAYA,MAAM,MAAM,gBAAgB,GAAG;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,OAAO,EAAE,CAAC;IACjB,UAAU,EAAE,OAAO,EAAE,CAAC;CACvB,CAAC;AAKF,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,gBAAgB,CAAC,CAW3B;AAUD,wBAAgB,gCAAgC,CAC9C,QAAQ,EAAE,gBAAgB,EAC1B,IAAI,EAAE,MAAM,GACX,gBAAgB,CAOlB"}

package/build/utils/loadCompiledWorkflow.js

@@ -0,0 +1,38 @@
+// Shared helpers for the `--file` paths that compile a `@cargo-ai/workflow-sdk`
+// module: `release deploy-draft --file` (deploy it) and `run create --file` /
+// `batch create --file` (test-run it). Loading is identical; `run create` and
+// `batch create` additionally resolve any `@cargo-ai/cdk` resource handles the
+// workflow references to their real uuids from cargo.state.json (see
+// `resolveCompiledWorkflowFromState`).
+import { ExitCodes, failWith } from "../commands/runHandler.js";
+import { importModuleDefault, resolveTokensFromState } from "./cdkState.js";
+// Load a workflow module via the tsx ESM loader so `.ts` sources (and their
+// imports of `@cargo-ai/workflow-sdk` / `zod`) are transpiled on the fly,
+// returning its default export validated as a compiled workflow.
+export async function loadCompiledWorkflow(file) {
+    const { defaultExport } = await importModuleDefault(file, "Workflow");
+    if (!isCompiledWorkflow(defaultExport)) {
+        failWith("Workflow module must `export default` a compiled workflow (the value returned by defineWorkflow()).", { code: ExitCodes.InvalidUsage });
+    }
+    return defaultExport;
+}
+// Resolve the workflow's `@cargo-ai/cdk` resource handles (tool / agent /
+// connector / model / …) to their real uuids using the committed
+// cargo.state.json, so a test-run executes against the ALREADY-DEPLOYED
+// resources without deploying the workflow itself. Returns the same compiled
+// workflow with an engine-ready node graph (`formFields` carry no tokens, so
+// they pass through). A workflow with no handle tokens (literal-uuid refs via
+// `toolRef`/`connectorRef`, or a pure-native body) is returned unchanged — no
+// state needed.
+export function resolveCompiledWorkflowFromState(compiled, file) {
+    const nodes = resolveTokensFromState(compiled.nodes, file, `"${compiled.slug}"`);
+    return { ...compiled, nodes };
+}
+function isCompiledWorkflow(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    const v = value;
+    return (typeof v["slug"] === "string" &&
+        Array.isArray(v["nodes"]) &&
+        Array.isArray(v["formFields"]));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cargo-ai/cli",
-  "version": "1.0.29",
+  "version": "1.0.31",
   "private": false,
   "license": "UNLICENSED",
   "description": "Command-line interface for the Cargo API",
@@ -12,7 +12,8 @@
   },
   "type": "module",
   "bin": {
-    "cargo-ai": "./build/index.js"
+    "cargo-ai": "./build/index.js",
+    "cargo": "./build/index.js"
   },
   "files": [
     "build",