@cargo-ai/cdk 1.0.5 → 1.0.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cargo-ai/cdk",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "Cargo CDK — define every Cargo resource (connectors, models, plays, tools, agents, MCP servers, folders, files, workers, apps) in code and deploy it declaratively: plan, apply, refresh, import and destroy over a repo of definitions.",
   "keywords": [
     "cargo",
@@ -57,10 +57,10 @@
     "format:check": "prettier --check ."
   },
   "dependencies": {
-    "@cargo-ai/api": "^1.0.34",
-    "@cargo-ai/types": "^1.0.37",
-    "@cargo-ai/worker-sdk": "^1.0.4",
-    "@cargo-ai/workflow-sdk": "^1.0.1",
+    "@cargo-ai/api": "^1.0.37",
+    "@cargo-ai/types": "^1.0.39",
+    "@cargo-ai/worker-sdk": "^1.0.6",
+    "@cargo-ai/workflow-sdk": "^1.0.3",
     "commander": "^12.1.0",
     "http-proxy-agent": "^9.1.0",
     "https-proxy-agent": "^9.1.0",

package/templates/blank/cargo.ts

@@ -1,28 +1,9 @@
-import {
-  defineConnector,
-  defineModel,
-  defineTool,
-  defineWorkflow,
-  secret,
-} from "@cargo-ai/cdk";
+import { defineTool, defineWorkflow } from "@cargo-ai/cdk";
 import { z } from "zod";
 
-// A data-source connector. After `cargo-ai cdk types`, `config` is typed against
-// the integration's schema and `secret()` reads the value from the environment
-// at deploy time (kept out of the committed state + content hash).
-export const hubspot = defineConnector("hubspot", {
-  integration: "hubspot",
-  config: { method: "privateApp", accessToken: secret("HUBSPOT_API_KEY") },
-});
-
-// A data model sourced from the connector's dataset by one of its extractors.
-export const contacts = defineModel("contacts", {
-  dataset: hubspot,
-  extractSlug: "fetchRecords",
-});
-
 // A tool backed by a workflow. The body is parsed at build time and lowered to
-// workflow nodes — never executed here. `ai(...)` becomes an inference node.
+// workflow nodes — never executed here. `ai(...)` becomes an inference node, so
+// this deploys and runs with nothing but your Cargo login — no provider keys.
 const enrichFlow = defineWorkflow(
   "enrich-contact",
   {
@@ -42,3 +23,17 @@ export const enrich = defineTool("enrich", {
   description: "Enrich a contact with firmographic data.",
   emojiSlug: "mag",
 });
+
+// Next: wire a data source. A connector + model make rows from your CRM or
+// warehouse available to plays, agents, and tools — see the `full` template
+// (`cargo-ai cdk init --template full`) or https://docs.getcargo.ai/connectors/overview
+//
+//   export const hubspot = defineConnector("hubspot", {
+//     integration: "hubspot",
+//     config: { method: "privateApp", accessToken: secret("HUBSPOT_API_KEY") },
+//   });
+//
+//   export const contacts = defineModel("contacts", {
+//     dataset: hubspot,
+//     extractSlug: "fetchRecords",
+//   });

package/templates/full/README.md

@@ -3,8 +3,9 @@
 A complete, runnable Cargo workspace defined entirely in code (the `full` CDK
 template — `cargo-ai cdk init <dir> --template full`). It exercises every resource
 type and wires them together with **handles** — you pass a `define*` handle
-(e.g. `dataset: hubspot`, `models: [{ ref: contacts }]`) into another builder,
-and the reconciler deploys them in dependency order and injects the real uuids.
+(e.g. `dataset: hubspot`, or an agent's `uses: [{ ref: contacts }, enrich]`) into
+another builder, and the reconciler deploys them in dependency order and injects
+the real uuids.
 
 ## The graph
 
@@ -13,6 +14,7 @@ hubspot (connector) ──dataset──▶ contacts (model) ──model───
                                                                     ├─▶ sdr (agent)
 openai (connector) ──connector──▶ enricher (agent) ──subAgent──▶ sdr│
                     └────────connector──────────────────▶ sdr ─────┘
+hunter (connector) ──hunter.actions.findEmail (connector action)──────────▶ sdr
 enrich (tool, backed by a workflow) ─┐
 sdr (agent) ─────────────────────────┼─▶ crm (mcpServer)
 contacts (model) ────────────────────┘
@@ -25,13 +27,14 @@ playbook (file)   webhook (worker)   dashboard (app)
 | --------------------------------------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
 | `connectors/hubspot.ts`                 | `defineConnector`               | discriminated-union config + `secret()`; auto-creates a dataset                                                               |
 | `connectors/openai.ts`                  | `defineConnector`               | `adopt: true` to link an existing OAuth connector                                                                             |
+| `connectors/hunter.ts`                  | `defineConnector`               | an enrichment connector; its actions (`hunter.actions.findEmail`) feed the agent's `uses`                                     |
 | `folders/crm.ts`                        | `defineFolder`                  | per-kind folders (model vs agent)                                                                                             |
 | `models/contacts.ts`                    | `defineModel`                   | `dataset` handle + `extractSlug` + cron schedule                                                                              |
 | `tools/enrich.ts`                       | `defineWorkflow` + `defineTool` | a tool backed by a workflow, with a cron trigger                                                                              |
 | `agents/enricher.ts`                    | `defineAgent`                   | a focused sub-agent (LLM via `connector`)                                                                                     |
-| `agents/sdr.ts`                         | `defineAgent`                   | data model, sub-agent, trigger, evaluator                                                                                     |
+| `agents/sdr.ts`                         | `defineAgent`                   | one `uses` array — model + tool + sub-agent + connector action; trigger, evaluator                                            |
 | `plays/onboarding.ts`                   | `definePlay` + `defineWorkflow` | runs a per-row workflow as contacts change                                                                                    |
-| `mcp/crm.ts`                            | `defineMcpServer`               | bundles tool + agent + model behind one endpoint                                                                              |
+| `mcp/crm.ts`                            | `defineMcpServer`               | bundles tool + agent + model (one `uses` array) behind one endpoint                                                           |
 | `context/context.ts` (+ `context/*.md`) | `defineContext`                 | syncs the GTM knowledge base (markdown/MDX) into the workspace's context repo                                                 |
 | `files/playbook.ts`                     | `defineFile`                    | content uploaded from a local path                                                                                            |
 | `workers/webhook.ts` (+ `webhook/`)     | `defineWorker`                  | the worker _resource_; points at a TS source bundle (`src/index.ts` + `manifest.json` + `package.json` + `package-lock.json`) |

package/templates/full/agents/sdr.ts

@@ -1,15 +1,17 @@
 import { defineAgent } from "@cargo-ai/cdk";
 
+import { hunter } from "../connectors/hunter";
 import { openai } from "../connectors/openai";
 import { agentsFolder } from "../folders/crm";
 import { contacts } from "../models/contacts";
 import { enrich } from "../tools/enrich";
 import { enricher } from "./enricher";
 
-// The main agent. It references a data model (`models`), a tool (`tools`), a
-// sub-agent (`subAgents`), a connector action (`connectorActions`), and the LLM
-// connector — each passed as a handle (bare, or `{ ref, …options }` when it needs
-// per-call options), so the reconciler deploys them first and injects the uuids.
+// The main agent. Everything it can call or read is one `uses` array — a data
+// model, a tool, a sub-agent, and a connector action (`hunter.actions.findEmail`) — each
+// a handle, bare or `{ ref, …options }` when it needs per-call options. The
+// reconciler deploys each first and injects its uuid. `connector` is separate:
+// it's the LLM provider, not something the agent "uses".
 export const sdr = defineAgent("sdr", {
   color: "blue",
   connector: openai,
@@ -18,10 +20,12 @@ export const sdr = defineAgent("sdr", {
     "You qualify inbound leads, enrich missing contact info, and route hot leads to Slack.",
   maxSteps: 12,
   capabilities: ["webSearch", "memory"],
-  models: [{ ref: contacts, readOnly: true }],
-  tools: [enrich],
-  subAgents: [{ ref: enricher, waitUntilFinished: true }],
-  connectorActions: [{ integration: "hunter", actionSlug: "emailFinder" }],
+  uses: [
+    { ref: contacts, readOnly: true }, // a data model
+    enrich, //                            a tool (bare handle)
+    { ref: enricher, waitUntilFinished: true }, // a sub-agent
+    hunter.actions.findEmail, //                  a connector action
+  ],
   folder: agentsFolder,
   triggers: [{ type: "cron", cron: "0 9 * * *", text: "Daily qualification" }],
   evaluator: { rubric: "Did it correctly qualify the lead?", threshold: 0.8 },

package/templates/full/connectors/hunter.ts

@@ -0,0 +1,10 @@
+import { defineConnector } from "@cargo-ai/cdk";
+
+// An enrichment connector. Its actions are exposed under `hunter.actions.*`
+// (`hunter.actions.findEmail`, `hunter.actions.verifyEmail`, …), so an agent or
+// MCP server can reference a specific connector action in its `uses`. Adopted
+// (OAuth/key auth lives outside the repo), like the LLM connector.
+export const hunter = defineConnector("hunter", {
+  integration: "hunter",
+  adopt: true,
+});

package/templates/full/mcp/crm.ts

@@ -4,12 +4,15 @@ import { sdr } from "../agents/sdr";
 import { contacts } from "../models/contacts";
 import { enrich } from "../tools/enrich";
 
-// An MCP server bundles tools, agents, and data models behind one MCP endpoint.
-// Each is referenced by handle (bare, or `{ ref, …options }` for options), so
-// the reconciler resolves each to its deployed action/resource.
+// An MCP server bundles tools, agents, and data models behind one MCP endpoint —
+// all in one `uses` array (the same surface as an agent). Each is a handle, bare
+// or `{ ref, …options }`, so the reconciler resolves each to its deployed
+// action/resource.
 export const crmServer = defineMcpServer("crm", {
   description: "CRM tools and data for assistants.",
-  tools: [enrich],
-  agents: [sdr],
-  models: [{ ref: contacts, readOnly: true }],
+  uses: [
+    enrich, //                           a tool
+    sdr, //                              an agent
+    { ref: contacts, readOnly: true }, // a data model
+  ],
 });

package/templates/full/tools/enrich.ts

@@ -2,27 +2,46 @@ import { defineTool, defineWorkflow } from "@cargo-ai/cdk";
 import { z } from "zod";
 
 import { enricher } from "../agents/enricher";
+import { hunter } from "../connectors/hunter";
 
 // A tool is backed by a workflow. `defineWorkflow` compiles the logic; `defineTool`
 // creates the tool + deploys that workflow as its release.
 //
-// `uses` forward-references other resources by handle — here the `enricher` agent.
-// The body calls it as `uses.enricher(...)`, and because the handle carries a
-// deferred `uuid` token, the CDK both orders the deploy (enricher first) and
-// injects the real uuid into the emitted node. The body is parsed and lowered to
-// workflow nodes — never executed at build time.
+// `uses` forward-references other resources by handle — here an agent (`enricher`)
+// and a connector (`hunter`). The body calls a tool/agent as `uses.<key>(input)`
+// and a connector's action as `uses.<key>.<action>(input)`. Each handle carries a
+// deferred `uuid` token, so the CDK orders the deploy (dependencies first) and
+// injects the real uuid into the emitted node. Run `cargo-ai cdk types` and a
+// connector's action slugs + their input/output type against your workspace.
+// The body is parsed and lowered to workflow nodes — never executed at build time.
 const enrichFlow = defineWorkflow(
   "enrich-contact",
   {
     input: z.object({ email: z.string() }),
-    output: z.object({ company: z.string(), enriched: z.boolean() }),
-    uses: { enricher },
+    output: z.object({
+      company: z.string(),
+      verification: z.unknown(),
+      enriched: z.boolean(),
+    }),
+    uses: { enricher, hunter },
   },
   ({ input, uses }) => {
+    // A connector action, called right in the workflow body.
+    const verification = uses.hunter.verifyEmail({ email: input.email });
+
+    // An agent, called by handle. An agent call resolves to `{ answer, evaluation? }`
+    // (agents aren't output-schema-typed), so read `.answer` for the response.
     const company = uses.enricher({
       prompt: `Which company owns the email domain of ${input.email}? Reply with just the company name.`,
-    });
-    return { company, enriched: true };
+    }).answer;
+
+    // Idiomatic `if/else`, lowered to real branching: each arm returns via its own
+    // `end` node. `company`/`verification` are the same in both; only `enriched`
+    // differs (`{{ true }}` vs `{{ false }}`).
+    if (!company) {
+      return { company, verification, enriched: false };
+    }
+    return { company, verification, enriched: true };
   },
 );