@chusky/sdk 1.7.0 → 1.8.0

package/cookbook/README.md

@@ -0,0 +1,52 @@
+# Chusky SDK Cookbook
+
+Each recipe is a complete, standalone TypeScript file. Every recipe creates
+its own Chusky client so you can copy one into a server project without
+importing a hidden client helper.
+
+Set an API key created in the Chusky dashboard before running a recipe:
+
+~~~bash
+$env:CHUSKY_API_KEY = "chsk_..."
+npx tsx cookbook/run-and-wait.ts
+~~~
+
+Check every recipe without making an API request:
+
+~~~bash
+npx tsc -p cookbook/tsconfig.json
+~~~
+
+The examples make real API requests. Use a development project, a test
+identity, and an idempotency key that is unique to the operation.
+
+## Recipes
+
+| Recipe | Use it when |
+| --- | --- |
+| [run-and-wait.ts](run-and-wait.ts) | You need one bounded agent result |
+| [streaming.ts](streaming.ts) | A UI should show progress and approval events |
+| [company-agent.ts](company-agent.ts) | A company needs a governed specialist |
+| [mission.ts](mission.ts) | Work has multiple steps, waits, and proof |
+| [approvals.ts](approvals.ts) | A person must approve or deny a pending action |
+| [context-and-department-handoff.ts](context-and-department-handoff.ts) | Teams need shared context and a typed handoff |
+| [files-and-image-attachment.ts](files-and-image-attachment.ts) | Work starts with a document or image |
+| [webhooks.ts](webhooks.ts) | Your server needs durable delivery notifications |
+| [connect-business-app.ts](connect-business-app.ts) | A user must connect Gmail, HubSpot, or another app |
+| [a2a-delegation.ts](a2a-delegation.ts) | One agent delegates durable work to another |
+| [scheduled-follow-up.ts](scheduled-follow-up.ts) | A reminder or recurring job should continue later |
+| [native-tool-health-check.ts](native-tool-health-check.ts) | You want to inspect or run one reliability capability |
+| [workflow-composer.ts](workflow-composer.ts) | You want reusable dependency-aware stages |
+
+Every recipe uses the same core configuration values:
+
+- CHUSKY_API_KEY — an API key kept on the server.
+- CHUSKY_USER_ID — optional; a stable application-owned identity.
+
+The SDK uses the hosted Chusky API by default. Set `CHUSKY_BASE_URL` only when
+targeting staging or a self-hosted API, and pass that value as `baseUrl` when
+constructing a client.
+
+Keep provider credentials, approval decisions, and file bytes on trusted
+server boundaries. Read the run, task, or mission by ID after a timeout before
+retrying.

package/cookbook/a2a-delegation.ts

@@ -0,0 +1,33 @@
+import { Chusky } from "@chusky/sdk";
+
+const apiKey = process.env.CHUSKY_API_KEY;
+if (!apiKey) throw new Error("Set CHUSKY_API_KEY before running this recipe.");
+
+const chusky = new Chusky({
+  apiKey,
+  userId: process.env.CHUSKY_USER_ID ?? "cookbook-a2a",
+});
+
+const card = await chusky.a2a.card();
+console.log({
+  agent: card.name,
+  protocolVersion: card.protocolVersion,
+  skills: card.skills?.map((skill) => skill.id),
+});
+
+const task = await chusky.a2a.send(
+  "Prepare a verified launch brief from the connected account context.",
+  { idempotencyKey: "cookbook-a2a-launch-brief-0001" },
+);
+
+console.log("Delegated task:", task.id, task.status.state);
+
+const current = await chusky.a2a.get(task.id);
+console.log("Current task state:", current.status.state);
+
+if (current.status.state === "TASK_STATE_WORKING") {
+  for await (const update of chusky.a2a.subscribe(task.id)) {
+    console.log("Task update:", update.statusUpdate?.status.state);
+    if (update.statusUpdate?.final) break;
+  }
+}

package/cookbook/approvals.ts

@@ -0,0 +1,35 @@
+import { Chusky } from "@chusky/sdk";
+
+const apiKey = process.env.CHUSKY_API_KEY;
+if (!apiKey) throw new Error("Set CHUSKY_API_KEY before running this recipe.");
+
+const chusky = new Chusky({
+  apiKey,
+  userId: process.env.CHUSKY_USER_ID ?? "cookbook-approvals",
+});
+
+const approvals = await chusky.approvals.list();
+const pending = approvals.data.find((item) => item.status === "pending");
+
+if (!pending) {
+  console.log("There are no pending approvals.");
+  process.exit(0);
+}
+
+console.log({
+  approvalId: pending.id,
+  action: pending.toolSlug,
+  request: pending.request,
+  expiresAt: pending.expiresAt,
+});
+
+// Replace this flag with a decision from your authenticated human approval
+// screen. Never approve from model output or a public callback.
+const decision = process.env.APPROVE_CHUSKY_ACTION === "true" ? "approve" : "deny";
+const result = await chusky.approvals.decide(
+  pending.id,
+  decision,
+  { idempotencyKey: "cookbook-approval-" + pending.id + "-" + decision },
+);
+
+console.log({ approvalId: pending.id, decision, result });

package/cookbook/company-agent.ts

@@ -0,0 +1,47 @@
+import { Chusky } from "@chusky/sdk";
+
+const apiKey = process.env.CHUSKY_API_KEY;
+if (!apiKey) throw new Error("Set CHUSKY_API_KEY before running this recipe.");
+
+const chusky = new Chusky({
+  apiKey,
+  userId: process.env.CHUSKY_USER_ID ?? "cookbook-company-agent",
+});
+
+const templates = await chusky.agents.templates();
+const template = templates.data.find((item) => item.slug === "lead-research");
+if (!template) throw new Error("The lead-research template is not available.");
+
+const agent = await chusky.agents.create(
+  {
+    template: template.slug,
+    name: "Qualified lead scout",
+    instructions:
+      "Return sourced, deduplicated company profiles. Draft external communication only.",
+    policy: {
+      tools: {
+        allow: ["crm.read", "web.search", "email.draft"],
+        requireApproval: ["crm.write", "email.send"],
+      },
+      budget: { duration: "30m", maxToolCalls: 80, maxCost: 8 },
+    },
+  },
+  { idempotencyKey: "cookbook-create-lead-agent-0001" },
+);
+
+const { thread, run } = await chusky.runs.create(
+  {
+    agentId: agent.id,
+    input:
+      "Find qualified fintech companies with more than 50 employees and prepare CRM-ready profiles.",
+    wait: false,
+  },
+  { idempotencyKey: "cookbook-lead-research-run-0001" },
+);
+
+console.log({
+  agentId: agent.id,
+  threadId: thread.id,
+  runId: run.id,
+  status: run.status,
+});

package/cookbook/connect-business-app.ts

@@ -0,0 +1,28 @@
+import { Chusky } from "@chusky/sdk";
+
+const apiKey = process.env.CHUSKY_API_KEY;
+if (!apiKey) throw new Error("Set CHUSKY_API_KEY before running this recipe.");
+
+const toolkit = process.env.CHUSKY_TOOLKIT ?? "gmail";
+const chusky = new Chusky({
+  apiKey,
+  userId: process.env.CHUSKY_USER_ID ?? "cookbook-connect-app",
+});
+
+const available = await chusky.apps.list();
+const match = available.data.find((app) => app.toolkit === toolkit);
+if (!match) throw new Error("The requested toolkit is not available: " + toolkit);
+
+const consent = await chusky.apps.connect(
+  toolkit,
+  process.env.CHUSKY_APP_ALIAS,
+  { idempotencyKey: "cookbook-connect-" + toolkit + "-0001" },
+);
+
+console.log("Complete provider consent at:", consent.url);
+console.log("After consent, run this recipe again to read connections.");
+
+const connections = await chusky.apps.connections();
+console.log({
+  connected: connections.data.filter((connection) => connection.toolkit === toolkit),
+});

package/cookbook/context-and-department-handoff.ts

@@ -0,0 +1,48 @@
+import { Chusky } from "@chusky/sdk";
+
+const apiKey = process.env.CHUSKY_API_KEY;
+if (!apiKey) throw new Error("Set CHUSKY_API_KEY before running this recipe.");
+
+const customerId = process.env.CUSTOMER_ID ?? "customer_123";
+const chusky = new Chusky({
+  apiKey,
+  userId: process.env.CHUSKY_USER_ID ?? customerId,
+});
+
+await chusky.context.save(
+  {
+    scope: "customer",
+    scopeId: customerId,
+    kind: "preference",
+    key: "renewal_window",
+    value: "Customer prefers renewal discussions in October.",
+    source: "crm",
+    confidence: 0.9,
+    sensitivity: "normal",
+  },
+  { idempotencyKey: "cookbook-context-renewal-" + customerId },
+);
+
+const context = await chusky.context.list({
+  scope: "customer",
+  scopeId: customerId,
+  purpose: "renewal",
+});
+
+const packet = await chusky.departments.handoff(
+  "customer-success",
+  {
+    objective: "Prepare a renewal risk review for the account team.",
+    inputs: { customerId },
+    constraints: ["Use verified CRM facts only."],
+    evidenceRequired: ["account health source", "open risk owner"],
+    approvalBoundary: "Draft only; do not contact the customer.",
+  },
+  { idempotencyKey: "cookbook-renewal-handoff-" + customerId },
+);
+
+console.log({
+  contextNodes: context.data.length,
+  handoffId: packet.id,
+  status: packet.status,
+});

package/cookbook/files-and-image-attachment.ts

@@ -0,0 +1,40 @@
+import { readFile } from "node:fs/promises";
+import { Chusky } from "@chusky/sdk";
+
+const apiKey = process.env.CHUSKY_API_KEY;
+if (!apiKey) throw new Error("Set CHUSKY_API_KEY before running this recipe.");
+
+const imagePath = process.env.IMAGE_PATH ?? "launch.png";
+const imageBytes = new Uint8Array(await readFile(imagePath));
+const chusky = new Chusky({
+  apiKey,
+  userId: process.env.CHUSKY_USER_ID ?? "cookbook-image-post",
+});
+
+const image = await chusky.files.upload(
+  {
+    name: imagePath,
+    contentType: "image/png",
+    data: imageBytes,
+  },
+  { idempotencyKey: "cookbook-upload-image-0001" },
+);
+
+const { thread, run } = await chusky.runs.create(
+  {
+    input:
+      "Prepare a social post using the attached image. Verify the image is available, draft the caption, and stop before publishing.",
+    attachments: [image.id],
+    wait: false,
+    budget: { duration: "5m", maxToolCalls: 10, maxCost: 1 },
+  },
+  { idempotencyKey: "cookbook-image-post-run-0001" },
+);
+
+console.log({
+  fileId: image.id,
+  fileStatus: image.status,
+  threadId: thread.id,
+  runId: run.id,
+  status: run.status,
+});

package/cookbook/mission.ts

@@ -0,0 +1,59 @@
+import { Chusky } from "@chusky/sdk";
+
+const apiKey = process.env.CHUSKY_API_KEY;
+if (!apiKey) throw new Error("Set CHUSKY_API_KEY before running this recipe.");
+
+const chusky = new Chusky({
+  apiKey,
+  userId: process.env.CHUSKY_USER_ID ?? "cookbook-mission",
+});
+
+const mission = await chusky.missions.create(
+  {
+    title: "Turn a qualified inquiry into a confirmed order",
+    objective:
+      "Research the buyer, answer questions, prepare an offer, and stop for approval before purchase.",
+    definitionOfDone:
+      "The CRM record is updated, the offer is prepared, and no purchase is made without approval.",
+    verificationMode: "strict",
+    requiredEvidence: ["CRM record", "buyer requirements", "approval-ready offer"],
+    steps: [
+      {
+        id: "research",
+        title: "Research buyer",
+        objective: "Collect verified facts and current requirements.",
+      },
+      {
+        id: "qualify",
+        title: "Qualify opportunity",
+        objective: "Check fit, budget, and decision timeline.",
+        dependsOn: ["research"],
+      },
+      {
+        id: "offer",
+        title: "Prepare offer",
+        objective: "Draft a bounded offer for human review.",
+        dependsOn: ["qualify"],
+      },
+    ],
+    maxDurationSeconds: 3 * 60 * 60,
+    maxSteps: 30,
+    maxToolCalls: 100,
+    maxCost: 15,
+  },
+  { idempotencyKey: "cookbook-buyer-inquiry-mission-0001" },
+);
+
+console.log("Mission started:", mission.id, mission.status);
+
+const proof = await chusky.missions.proof(mission.id);
+console.log({
+  status: proof.status,
+  nextAction: proof.nextAction,
+  completedSteps: proof.steps.filter((step) => step.status === "completed").length,
+  evidence: proof.evidence.length,
+});
+
+if (proof.status === "paused" || proof.status === "blocked") {
+  console.log("Resolve the dependency, then call chusky.missions.resume(mission.id).");
+}

package/cookbook/native-tool-health-check.ts

@@ -0,0 +1,39 @@
+import { Chusky } from "@chusky/sdk";
+
+const apiKey = process.env.CHUSKY_API_KEY;
+if (!apiKey) throw new Error("Set CHUSKY_API_KEY before running this recipe.");
+
+const chusky = new Chusky({
+  apiKey,
+  userId: process.env.CHUSKY_USER_ID ?? "cookbook-native-tool-check",
+});
+
+const nativeTools = await chusky.tools.list({ source: "native" });
+console.log({
+  tools: nativeTools.data.map((tool) => ({
+    slug: tool.slug,
+    approval: tool.approval,
+    execution: tool.execution,
+  })),
+});
+
+const tool = await chusky.tools.get("CHUCK_INTEGRATION_HEALTH");
+console.log("Selected capability:", tool.description);
+
+const { thread, run } = await chusky.tools.run(
+  {
+    tool: "CHUCK_INTEGRATION_HEALTH",
+    arguments: { operation: "all" },
+  },
+  { idempotencyKey: "cookbook-integration-health-0001" },
+);
+
+const completed = await chusky.runs.wait(thread.id, run.id, {
+  timeoutMs: 120_000,
+});
+
+console.log({
+  runId: run.id,
+  status: completed.status,
+  output: completed.output,
+});

package/cookbook/run-and-wait.ts

@@ -0,0 +1,30 @@
+import { Chusky } from "@chusky/sdk";
+
+const apiKey = process.env.CHUSKY_API_KEY;
+if (!apiKey) throw new Error("Set CHUSKY_API_KEY before running this recipe.");
+
+const chusky = new Chusky({
+  apiKey,
+  userId: process.env.CHUSKY_USER_ID ?? "cookbook-run-and-wait",
+});
+
+const { thread, run } = await chusky.runs.create(
+  {
+    input:
+      "Concisely list the tools currently available to you, grouped by category. Give category names and a few representative tool names only; do not enumerate the full catalogue. If you need a tool catalogue lookup to answer accurately, use at most one tool call.",
+    wait: true,
+    budget: {
+      duration: "5m",
+      maxToolCalls: 1,
+      maxCost: 0.25,
+    },
+  },
+  { idempotencyKey: "cookbook-tool-list-20260930-0001" },
+);
+
+console.log({
+  threadId: thread.id,
+  runId: run.id,
+  status: run.status,
+  output: run.output,
+});

package/cookbook/scheduled-follow-up.ts

@@ -0,0 +1,40 @@
+import { Chusky } from "@chusky/sdk";
+
+const apiKey = process.env.CHUSKY_API_KEY;
+if (!apiKey) throw new Error("Set CHUSKY_API_KEY before running this recipe.");
+
+const chusky = new Chusky({
+  apiKey,
+  userId: process.env.CHUSKY_USER_ID ?? "cookbook-scheduled-follow-up",
+});
+
+const reminder = await chusky.reminders.create(
+  {
+    text: "Check whether the buyer replied and prepare the next sales step.",
+    delaySeconds: 60 * 60 * 24,
+    mode: "check_in",
+    nextAction: "Read the latest buyer reply, update the CRM, and draft a response.",
+    preconditions: ["The buyer inquiry is still open."],
+    postconditions: ["The next action is recorded or the owner is notified."],
+  },
+  { idempotencyKey: "cookbook-buyer-follow-up-0001" },
+);
+
+console.log({
+  reminderId: reminder.id,
+  status: reminder.status,
+  runAt: reminder.runAt,
+});
+
+// The same pattern can be recurring:
+const job = await chusky.jobs.create(
+  {
+    text: "Review open support conversations and prepare a daily handoff.",
+    cron: "0 9 * * 1-5",
+    mode: "notify",
+    nextAction: "Summarize only conversations that changed since the last run.",
+  },
+  { idempotencyKey: "cookbook-daily-support-handoff-0001" },
+);
+
+console.log({ jobId: job.id, cron: job.cron, status: job.status });

package/cookbook/streaming.ts

@@ -0,0 +1,43 @@
+import { Chusky } from "@chusky/sdk";
+
+const apiKey = process.env.CHUSKY_API_KEY;
+if (!apiKey) throw new Error("Set CHUSKY_API_KEY before running this recipe.");
+
+const chusky = new Chusky({
+  apiKey,
+  userId: process.env.CHUSKY_USER_ID ?? "cookbook-streaming",
+});
+
+const thread = await chusky.threads.create(
+  { metadata: { source: "sdk-cookbook", recipe: "streaming" } },
+  { idempotencyKey: "cookbook-stream-thread-0001" },
+);
+
+const controller = new AbortController();
+const timeout = setTimeout(() => controller.abort(), 60_000);
+
+try {
+  for await (const event of chusky.threads.runs(thread.id).stream(
+    {
+      input:
+        "Review the latest customer context and give a three-bullet account summary. Ask for approval before any external write.",
+      budget: { duration: "5m", maxToolCalls: 8, maxCost: 1 },
+    },
+    { signal: controller.signal },
+  )) {
+    if (event.type === "run.status") console.error(event.text);
+    if (event.type === "run.delta") process.stdout.write(event.text);
+    if (event.type === "run.tool_started") {
+      console.error("\nUsing " + event.toolSlug + "...");
+    }
+    if (event.type === "run.approval_required") {
+      console.error("\nApproval required: " + event.approval.id);
+    }
+    if (event.type === "run.failed") throw new Error(event.error.message);
+    if (event.type === "run.completed") {
+      console.error("\nCompleted: " + event.run.status);
+    }
+  }
+} finally {
+  clearTimeout(timeout);
+}

package/cookbook/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "baseUrl": "..",
+    "rootDir": "..",
+    "noEmit": true,
+    "paths": {
+      "@chusky/sdk": ["src/index.ts"],
+      "@chusky/sdk/widget": ["src/widget.ts"]
+    }
+  },
+  "include": ["./*.ts"]
+}

package/cookbook/webhooks.ts

@@ -0,0 +1,27 @@
+import { Chusky } from "@chusky/sdk";
+
+const apiKey = process.env.CHUSKY_API_KEY;
+if (!apiKey) throw new Error("Set CHUSKY_API_KEY before running this recipe.");
+
+const chusky = new Chusky({
+  apiKey,
+  userId: process.env.CHUSKY_USER_ID ?? "cookbook-webhooks",
+});
+
+const webhook = await chusky.webhooks.create(
+  "https://app.example.com/api/chusky/events",
+  { idempotencyKey: "cookbook-register-events-0001" },
+);
+
+console.log({
+  webhookId: webhook.id,
+  secretReturnedOnce: Boolean(webhook.secret),
+});
+
+const deliveries = await chusky.webhooks.deliveries(webhook.id);
+console.log({
+  deliveryStatuses: deliveries.data.map((delivery) => delivery.status),
+});
+
+// The receiving endpoint must verify the Chusky signature, persist the
+// delivery ID before applying the event, and return 2xx after that write.

package/cookbook/workflow-composer.ts

@@ -0,0 +1,49 @@
+import { Chusky } from "@chusky/sdk";
+
+const apiKey = process.env.CHUSKY_API_KEY;
+if (!apiKey) throw new Error("Set CHUSKY_API_KEY before running this recipe.");
+
+const chusky = new Chusky({
+  apiKey,
+  userId: process.env.CHUSKY_USER_ID ?? "cookbook-workflow",
+});
+
+const workflow = await chusky.workflows.create(
+  {
+    name: "Research then prepare follow-up",
+    description: "A reusable two-stage sales workflow.",
+    stages: [
+      {
+        id: "research",
+        title: "Research account",
+        objective: "Collect current, source-backed account facts.",
+      },
+      {
+        id: "prepare",
+        title: "Prepare follow-up",
+        objective: "Draft the next message using the research result.",
+        dependsOn: ["research"],
+        requiresApproval: true,
+      },
+    ],
+  },
+  { idempotencyKey: "cookbook-sales-workflow-0001" },
+);
+
+console.log({
+  workflowId: workflow.id,
+  status: workflow.status,
+  stages: workflow.stages.map((stage) => stage.id),
+});
+
+const started = await chusky.workflows.start(
+  workflow.id,
+  { idempotencyKey: "cookbook-sales-workflow-run-0001" },
+);
+
+console.log({
+  workflowId: started.id,
+  status: started.status,
+  taskId: started.taskId,
+  workflowRunId: started.workflowRunId,
+});

package/dist/client.d.ts

@@ -1,5 +1,6 @@
 import type { A2AMessageInput } from "./types.js";
 import type { ImageDownload } from "./types.js";
+import type { McpConnectionCredentials } from "./types.js";
 import type { A2AAgentCard, A2APushNotificationConfig, A2AStreamEvent, A2ATask, A2ATaskPage, AccountPreferences, Activity, AddCustomMcpServerParams, AppConnection, Approval, ApprovalDecision, ApprovalEscalation, Artifact, AuditEvent, AutonomySnapshot, CallRecord, CallsResponse, ChannelConnection, ChuskyClientOptions, CliDevice, CompanyAgent, CompanyAgentCreateParams, CompanyAgentTemplate, CompanyAuditEvent, CompanyBranding, CompanyRunSummary, CompanyUsage, ComposerStageInput, Compensation, ContextNode, CreateRunParams, CreateThreadParams, DepartmentCatalogItem, DepartmentSpace, DeveloperProject, Delivery, FileDownload, FileRecord, FileUpload, JobOccurrence, JoinMeetingParams, LinkableChannelProvider, LiveVoicePreference, McpCatalogEntry, McpConnection, MeetingBrief, MeetingContext, MeetingProfile, MeetingRecord, MeetingsResponse, MemoryFact, Mission, MissionCreateParams, MissionEvidence, MissionProof, OperatorReadiness, OperatorTraceEvent, OutcomePackage, OutcomePlan, OutcomeVerification, Page, RecurringJob, ReliabilityHealth, Reminder, RequestOptions, Run, RunEvent, RunStreamEvent, ScratchpadEntry, Skill, SkillFile, Task, Thread, Tool, ToolReliabilitySlug, Trigger, TriggerCatalogueItem, TriggerCreateParams, TriggerToolkit, Usage, VideoJob, VoiceCallProfile, VoiceOptions, Webhook, WebhookDelivery, WorkflowComposerRecord, WorkPacket, Worker } from "./types.js";
 export declare class Chusky {
     readonly threads: ThreadsResource;
@@ -66,7 +67,7 @@ export declare class Chusky {
         dispose: () => void;
     }>;
 }
-/** Trusted-server client for provisioning project keys. */
+/** Trusted-server client for administrative API operations. */
 export declare function createChuskyAdmin(options: Omit<ChuskyClientOptions, "userId"> & {
     userId?: string;
 }): Chusky;
@@ -381,7 +382,7 @@ export declare class McpResource {
         data: McpConnection[];
     }>;
     addServer(params: AddCustomMcpServerParams, options?: RequestOptions): Promise<McpConnection>;
-    connect(serverId: string, accessToken?: string, options?: RequestOptions): Promise<McpConnection>;
+    connect(serverId: string, credentials?: string | McpConnectionCredentials, options?: RequestOptions): Promise<McpConnection>;
     disconnect(serverId: string, options?: RequestOptions): Promise<void>;
 }
 export declare class RemindersResource {