@cargo-ai/cli 1.0.30 → 1.0.32

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/mcp.d.ts

@@ -0,0 +1,4 @@
+import type { Command } from "commander";
+import type { Api } from "../api.js";
+export declare function registerMcpCommand(parent: Command, getApi: () => Api): void;
+//# sourceMappingURL=mcp.d.ts.map

package/build/commands/mcp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../../src/commands/mcp.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAerC,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,GAAG,IAAI,CAqD3E"}

package/build/commands/mcp.js

@@ -0,0 +1,192 @@
+import { createRequire } from "node:module";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { getConfig } from "../config.js";
+import { getProxyFetch } from "../proxy.js";
+import { ExitCodes, failWith, handleApiCall, info } from "./runHandler.js";
+const require = createRequire(import.meta.url);
+const { version } = require("../../package.json");
+// The prod REST API and the prod MCP server are the same backend image behind
+// two hostnames; the MCP one (mcp.getcargo.io) is tuned for long-lived streaming.
+// Point the bridge there when the CLI is talking to prod, but leave any other
+// base URL (staging, localhost) untouched — that same host serves the MCP routes.
+const PROD_API_HOST = "api.getcargo.io";
+const PROD_MCP_HOST = "mcp.getcargo.io";
+export function registerMcpCommand(parent, getApi) {
+    parent
+        .command("mcp")
+        .description("Run a local MCP server that bridges to a Cargo MCP server over stdio")
+        .option("--server <uuid>", "MCP server UUID to expose (default: CARGO_MCP_SERVER_UUID, or the workspace's only MCP server)")
+        .addHelpText("after", `
+Exposes a Cargo-hosted MCP server as a local stdio MCP server, so any stdio MCP
+client (Claude Code, Claude Desktop, Cursor, ...) can use it with the CLI's own
+credentials — no token to copy into client config.
+
+Register it with a client, e.g. Claude Code:
+  $ claude mcp add cargo -- cargo-ai mcp --server <uuid>
+
+Environment:
+  CARGO_MCP_SERVER_UUID   default --server value
+  CARGO_MCP_BASE_URL      override the MCP endpoint origin (advanced/local dev)
+
+Reads auth from the same place as every other command (CARGO_API_TOKEN or the
+credentials file). stdout carries the MCP protocol; all logs go to stderr.`)
+        .action(async (opts) => {
+        const { accessToken, baseUrl, workspaceUuid } = getConfig();
+        if (accessToken === undefined) {
+            failWith('Not authenticated. Run "cargo-ai login --token <token>" or "cargo-ai login --oauth".', { code: ExitCodes.NotAuthenticated });
+        }
+        const serverUuid = await resolveServerUuid(opts.server, getApi);
+        const endpoint = resolveMcpEndpoint(baseUrl, serverUuid);
+        const headers = {
+            authorization: `Bearer ${accessToken}`,
+            "x-cargo-origin": "cli",
+            "x-cargo-origin-version": version,
+        };
+        if (workspaceUuid !== undefined) {
+            headers["selected-workspace-uuid"] = workspaceUuid;
+        }
+        info(`Cargo MCP bridge -> ${endpoint}`);
+        await runBridge(endpoint, headers);
+    });
+}
+const resolveServerUuid = async (explicit, getApi) => {
+    if (explicit !== undefined)
+        return explicit;
+    const fromEnv = process.env["CARGO_MCP_SERVER_UUID"];
+    if (fromEnv !== undefined && fromEnv.length > 0)
+        return fromEnv;
+    const api = getApi();
+    const { mcpServers } = await handleApiCall(() => api.ai.mcpServer.all(), {
+        spinner: false,
+    });
+    if (mcpServers.length === 0) {
+        failWith("No MCP server in this workspace. Create one with 'cargo-ai ai mcp-server create --name ...', then pass --server <uuid>.", { code: ExitCodes.InvalidUsage });
+    }
+    const only = mcpServers[0];
+    if (mcpServers.length > 1 || only === undefined) {
+        failWith("Multiple MCP servers found; pass --server <uuid>.", {
+            code: ExitCodes.InvalidUsage,
+            extra: {
+                servers: mcpServers.map((server) => ({
+                    uuid: server.uuid,
+                    name: server.name,
+                })),
+            },
+        });
+    }
+    return only.uuid;
+};
+const resolveMcpEndpoint = (baseUrl, uuid) => {
+    const override = process.env["CARGO_MCP_BASE_URL"];
+    const origin = override !== undefined && override.length > 0
+        ? override
+        : mapApiHostToMcp(baseUrl);
+    return `${origin.replace(/\/+$/, "")}/v1/ai/mcpServers/${uuid}/mcp`;
+};
+const mapApiHostToMcp = (baseUrl) => {
+    try {
+        const url = new URL(baseUrl);
+        if (url.hostname === PROD_API_HOST) {
+            url.hostname = PROD_MCP_HOST;
+            return url.origin;
+        }
+        return baseUrl;
+    }
+    catch {
+        return baseUrl;
+    }
+};
+// Pipe two MCP transports message-for-message: the local stdio server (facing the
+// MCP client) and the remote streamable-HTTP client (facing Cargo). Forwarding raw
+// JSON-RPC keeps the bridge transparent — tools, resources, and long-running-tool
+// progress notifications all pass through without enumerating capabilities here.
+const runBridge = async (endpoint, headers) => {
+    // Prefer a proxied fetch when HTTPS_PROXY/HTTP_PROXY applies — Node's
+    // built-in fetch ignores those env vars, so without this the bridge would
+    // fail in proxied environments even though server discovery (Axios) works.
+    const remote = new StreamableHTTPClientTransport(new URL(endpoint), {
+        requestInit: { headers },
+        fetch: getProxyFetch(endpoint),
+    });
+    const local = new StdioServerTransport();
+    await new Promise((resolve, reject) => {
+        const state = { closed: false };
+        // Shared handlers so finish/fail can remove whichever listeners are still
+        // registered. process.once / stdin.once only drop the event that fired; the
+        // others would otherwise keep the event loop alive and hang the process
+        // after resolve()/reject().
+        const onSignal = () => {
+            finish("Cargo MCP: shutting down.");
+        };
+        const onStdinGone = () => {
+            finish("Cargo MCP: client disconnected.");
+        };
+        const teardown = () => {
+            process.removeListener("SIGINT", onSignal);
+            process.removeListener("SIGTERM", onSignal);
+            process.stdin.removeListener("end", onStdinGone);
+            process.stdin.removeListener("close", onStdinGone);
+            void remote.close().catch(() => { });
+            void local.close().catch(() => { });
+        };
+        // Client disconnect and process signals are normal ends — resolve so the
+        // command exits 0. Upstream/startup/stdio failures must reject so callers
+        // and MCP clients see a non-zero exit (CLI contract: 0 means success).
+        const finish = (reason) => {
+            if (state.closed)
+                return;
+            state.closed = true;
+            if (reason !== undefined)
+                info(reason);
+            teardown();
+            resolve();
+        };
+        const fail = (message) => {
+            if (state.closed)
+                return;
+            state.closed = true;
+            teardown();
+            reject(new Error(message));
+        };
+        // Forward raw JSON-RPC both ways. A failing transport reports the reason via
+        // onerror (which fires before the send rejection), so the reason is logged
+        // there once; these catches only need to guarantee teardown.
+        remote.onmessage = (message) => {
+            void local.send(message).catch(() => finish());
+        };
+        local.onmessage = (message) => {
+            void remote.send(message).catch(() => finish());
+        };
+        // Reject with the failure reason once. Stay silent once we're already
+        // closing: the in-flight SSE stream aborting during our own shutdown surfaces
+        // here as expected noise.
+        remote.onerror = (error) => {
+            fail(`Cargo MCP: upstream error: ${error.message}`);
+        };
+        local.onerror = (error) => {
+            fail(`Cargo MCP: stdio error: ${error.message}`);
+        };
+        remote.onclose = () => fail("Cargo MCP: upstream closed.");
+        local.onclose = () => finish("Cargo MCP: client disconnected.");
+        process.once("SIGINT", onSignal);
+        process.once("SIGTERM", onSignal);
+        // @modelcontextprotocol/sdk 1.29.0 StdioServerTransport only listens for
+        // stdin `data`/`error` — it never wires `end`/`close`, so local.onclose
+        // above does not fire when the MCP client closes the pipe without a
+        // signal. Detect stdin EOF ourselves so we tear down the upstream
+        // streamable-HTTP session instead of leaving a zombie bridge.
+        // See https://github.com/modelcontextprotocol/typescript-sdk/issues/2002
+        if (process.stdin.readableEnded === true ||
+            process.stdin.destroyed === true) {
+            onStdinGone();
+            return;
+        }
+        process.stdin.once("end", onStdinGone);
+        process.stdin.once("close", onStdinGone);
+        Promise.all([remote.start(), local.start()]).catch((error) => {
+            fail(`Cargo MCP: failed to start bridge: ${describe(error)}`);
+        });
+    });
+};
+const describe = (error) => error instanceof Error ? error.message : String(error);

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/index.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { createRequire } from "node:module";
-import { registerCommands as registerCdkCommands } from "@cargo-ai/cdk/cli";
+import { registerCommands as registerCdkCommands, registerManifestCommands, } from "@cargo-ai/cdk/cli";
 import { Command } from "commander";
 import { createApi } from "./api.js";
 import { registerAiCommands } from "./commands/ai/index.js";
@@ -12,6 +12,7 @@ import { registerContextCommands } from "./commands/context/index.js";
 import { registerExpressionCommands } from "./commands/expression/index.js";
 import { registerHostingCommands } from "./commands/hosting/index.js";
 import { registerInitCommand } from "./commands/init.js";
+import { registerMcpCommand } from "./commands/mcp.js";
 import { registerOrchestrationCommands } from "./commands/orchestration/index.js";
 import { registerRevenueOrganizationCommands } from "./commands/revenueOrganization/index.js";
 import { ExitCodes, failWith } from "./commands/runHandler.js";
@@ -73,9 +74,13 @@ registerSystemOfRecordIntegrationCommands(program, getApi);
 registerUserManagementCommands(program, getApi);
 registerAiCommands(program, getApi);
 registerHostingCommands(program, getApi);
+registerMcpCommand(program, getApi);
 registerCdkCommands(program
     .command("cdk")
     .description("Cargo CDK — define resources in code and deploy them (plan/deploy)"), getApi);
+registerManifestCommands(program
+    .command("manifest")
+    .description("Manifest — scaffold a GTM repo (context, infra, skills, evals, outputs) and install cookbook modules into it"));
 program
     .parseAsync()
     .then(() => maybeNotifyUpdate(version))

package/build/proxy.d.ts

@@ -14,4 +14,16 @@ import type { ClientTransport } from "@cargo-ai/api";
  * default direct-egress behavior.
  */
 export declare const getProxyTransport: (targetUrl: string) => ClientTransport | undefined;
+/**
+ * Build a `fetch` implementation that tunnels through an HTTP/HTTPS proxy
+ * when one is configured via the same env vars as {@link getProxyTransport}.
+ *
+ * Node's built-in `fetch` (and therefore MCP's `StreamableHTTPClientTransport`)
+ * does not honor `HTTPS_PROXY` / `HTTP_PROXY` on its own. Callers that need
+ * proxied egress should pass the result as the transport's `fetch` option.
+ *
+ * Returns `undefined` when no proxy applies, so the caller can keep the
+ * default global `fetch`.
+ */
+export declare const getProxyFetch: (targetUrl: string) => ((url: string | URL, init?: RequestInit) => Promise<Response>) | undefined;
 //# sourceMappingURL=proxy.d.ts.map

package/build/proxy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"proxy.d.ts","sourceRoot":"","sources":["../src/proxy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AA4CrD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,iBAAiB,cACjB,MAAM,KAChB,eAAe,GAAG,SAoBpB,CAAC"}
+{"version":3,"file":"proxy.d.ts","sourceRoot":"","sources":["../src/proxy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAmErD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,iBAAiB,cACjB,MAAM,KAChB,eAAe,GAAG,SAWpB,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,aAAa,cACb,MAAM,YAER,MAAM,GAAG,GAAG,SAAS,WAAW,KAAK,QAAQ,QAAQ,CAAC,aAchE,CAAC"}

package/build/proxy.js

@@ -1,5 +1,6 @@
 import { HttpProxyAgent } from "http-proxy-agent";
 import { HttpsProxyAgent } from "https-proxy-agent";
+import { fetch as undiciFetch, ProxyAgent, } from "undici";
 const getEnv = (...names) => {
     for (const name of names) {
         const value = process.env[name];
@@ -32,6 +33,21 @@ const shouldBypassProxy = (targetUrl, noProxy) => {
         return hostname === normalized || hostname.endsWith(`.${normalized}`);
     });
 };
+/**
+ * Resolve the proxy URL for a target from the standard proxy env vars
+ * (`HTTPS_PROXY`, `HTTP_PROXY`, `ALL_PROXY`, honoring `NO_PROXY`).
+ *
+ * Returns `undefined` when no proxy applies.
+ */
+const resolveProxyUrl = (targetUrl) => {
+    if (shouldBypassProxy(targetUrl, getEnv("NO_PROXY", "no_proxy"))) {
+        return undefined;
+    }
+    const isHttps = targetUrl.startsWith("https:");
+    return isHttps
+        ? getEnv("HTTPS_PROXY", "https_proxy", "ALL_PROXY", "all_proxy")
+        : getEnv("HTTP_PROXY", "http_proxy", "ALL_PROXY", "all_proxy");
+};
 /**
  * Build Axios transport overrides that tunnel requests through an
  * HTTP/HTTPS proxy when one is configured via the standard proxy env
@@ -47,13 +63,7 @@ const shouldBypassProxy = (targetUrl, noProxy) => {
  * default direct-egress behavior.
  */
 export const getProxyTransport = (targetUrl) => {
-    if (shouldBypassProxy(targetUrl, getEnv("NO_PROXY", "no_proxy"))) {
-        return undefined;
-    }
-    const isHttps = targetUrl.startsWith("https:");
-    const proxyUrl = isHttps
-        ? getEnv("HTTPS_PROXY", "https_proxy", "ALL_PROXY", "all_proxy")
-        : getEnv("HTTP_PROXY", "http_proxy", "ALL_PROXY", "all_proxy");
+    const proxyUrl = resolveProxyUrl(targetUrl);
     if (proxyUrl === undefined) {
         return undefined;
     }
@@ -63,3 +73,25 @@ export const getProxyTransport = (targetUrl) => {
         proxy: false,
     };
 };
+/**
+ * Build a `fetch` implementation that tunnels through an HTTP/HTTPS proxy
+ * when one is configured via the same env vars as {@link getProxyTransport}.
+ *
+ * Node's built-in `fetch` (and therefore MCP's `StreamableHTTPClientTransport`)
+ * does not honor `HTTPS_PROXY` / `HTTP_PROXY` on its own. Callers that need
+ * proxied egress should pass the result as the transport's `fetch` option.
+ *
+ * Returns `undefined` when no proxy applies, so the caller can keep the
+ * default global `fetch`.
+ */
+export const getProxyFetch = (targetUrl) => {
+    const proxyUrl = resolveProxyUrl(targetUrl);
+    if (proxyUrl === undefined) {
+        return undefined;
+    }
+    const agent = new ProxyAgent(proxyUrl);
+    return (url, init) => undiciFetch(url, {
+        ...init,
+        dispatcher: agent,
+    });
+};

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.30",
+  "version": "1.0.32",
   "private": false,
   "license": "UNLICENSED",
   "description": "Command-line interface for the Cargo API",
@@ -31,14 +31,16 @@
   },
   "dependencies": {
     "@cargo-ai/api": "^1.0.40",
-    "@cargo-ai/types": "*",
-    "@cargo-ai/app-sdk": "^1.0.3",
+    "@cargo-ai/app-sdk": "^1.0.5",
     "@cargo-ai/cdk": "*",
+    "@cargo-ai/types": "*",
     "@cargo-ai/worker-sdk": "^1.0.6",
+    "@modelcontextprotocol/sdk": "1.29.0",
     "commander": "^12.1.0",
     "http-proxy-agent": "^9.1.0",
     "https-proxy-agent": "^9.1.0",
-    "tsx": "^4.19.2"
+    "tsx": "^4.19.2",
+    "undici": "^7.24.8"
   },
   "devDependencies": {
     "@cargo-ai/eslint-config": "*",