@chusky/sdk
v2.0.0
Published
TypeScript SDK for Chusky's developer API.
Readme
Chusky SDK
The official TypeScript client for the Chusky Developer API.
Use Chusky when your application needs an agent that can reason over context, use connected business tools, stream progress, pause for a human decision, and continue durable work after a request or process ends.
The SDK is designed for trusted server applications. It keeps connected-app credentials out of browsers and mobile clients.
Install
npm install @chusky/sdkNode.js 18 or newer is required.
Quickstart
Create an API key in the Chusky dashboard, then configure it in your server environment:
CHUSKY_API_KEY=chsk_your_project_keyThe SDK automatically uses the hosted Chusky API, so baseUrl is optional.
import { Chusky } from "@chusky/sdk";
const chusky = new Chusky({
apiKey: process.env.CHUSKY_API_KEY!,
// Stable ID owned by your application. Do not use a secret.
userId: "customer_123",
});
const { thread, run } = await chusky.runs.create(
{
input: "Prepare a concise renewal brief from the available account context.",
wait: false,
budget: { duration: "5m", maxToolCalls: 20, maxCost: 1 },
},
{ idempotencyKey: "renewal-brief-customer-123-v1" },
);
const completed = await chusky.runs.wait(thread.id, run.id, {
timeoutMs: 120_000,
});
if (completed.status === "failed") {
throw new Error(completed.error?.message ?? "Chusky run failed.");
}
console.log(completed.output ?? "The run completed without text output.");Attention Pulse
Attention Pulse provides owner-scoped proactive checks. Enabling it schedules durable checks; it does not grant provider access or bypass approval for financial, destructive, permission-changing, or high-impact outbound actions.
Using the chusky client from the quickstart:
const current = await chusky.attentionPulse.get();
const updated = await chusky.attentionPulse.update({
enabled: true,
cadence: "hourly",
authority: "prepare",
deliveryTargets: [{ provider: "telegram" }],
monitoredDomains: ["gmail", "calendar"],
maxPerDay: 4,
}, { idempotencyKey: "pulse-setup-2026-10-07" });attentionPulse.get() also returns health. Use it to render an honest
control-plane state: healthy, running, never_run, stale, failed, or
waiting_for_connection. The recoveryAction is a bounded UI hint such as
run_now, inspect, or connect_app; it does not authorize provider access
or bypass an approval. The dashboard bell and Chat remain delivery surfaces
for actionable Pulse candidates even when no external channel is connected.
The authority values are observe, prepare, and execute_reversible.
Provider actions still pass through the server's connected-account, ownership,
approval, and verification controls.
For run-level observability, chusky.jobs.occurrences(id) returns a bounded
pulseEvidence receipt on Attention Pulse occurrences. It records due-watch
checks, remaining observations/candidates, handling or delegation, approval
waits, and dashboard/external delivery without exposing provider payloads or
claiming that an external write succeeded.
Recurring jobs expose an owner-scoped scheduleError when the worker cannot
reconcile their durable QStash schedule. It is bounded, clears after a later
successful repair, and does not imply that a provider action was attempted.
Connected-app action cards opened from the dashboard can carry
metadata.triggerEventId and metadata.triggerActionId into a Chat run. The
API validates both against the authenticated owner's saved trigger event before
admitting the run; event text never grants permission and consequential actions
still require the normal approval boundary.
Pass baseUrl only when targeting a staging or self-hosted API. Never expose
CHUSKY_API_KEY in browser code, mobile apps, public repositories, or prompts.
The execution model
Your server
↓
@chusky/sdk
↓ authenticated /v1 API
Chusky runtime
↓
agent loop → native tools / connected apps / durable work
↓
text, approval, artifact, webhook, or verified business resultChoose the execution style that matches the job:
| Use case | SDK entry point | | --- | --- | | One bounded request | chusky.runs.create() and chusky.runs.wait() | | Conversation with incremental output | chusky.threads.create() and chusky.threads.runs(threadId).stream() | | Work that may pause or retry | runs.get(), runs.events(), runs.resume(), and tasks | | Multi-step process with checkpoints and proof | chusky.missions | | Delegated agent-to-agent work | chusky.a2a | | Recurring or scheduled work | chusky.reminders and chusky.jobs |
Persist the returned threadId, runId, taskId, or missionId. Those identifiers let your application reconnect after a timeout or restart without creating duplicate work.
Stable identity
userId is the isolation boundary for SDK state. Chusky uses it to scope threads, runs, memory, files, artifacts, approvals, tasks, and connected accounts.
Use the same stable value whenever the same person or tenant returns. Do not derive it from an unverified display name, a phone number, or a channel message. Do not use the root operator identity for normal end-user traffic.
Stream progress and approvals
Streaming is useful for responsive interfaces. Persisted run state remains the source of truth if the stream disconnects.
const thread = await chusky.threads.create(
{ metadata: { source: "support-console" } },
{ idempotencyKey: "support-thread-customer-123-v1" },
);
for await (const event of chusky.threads.runs(thread.id).stream({
input: "Summarize the customer's current priorities in three bullets.",
})) {
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("\nHuman approval required: " + event.approval.id);
}
if (event.type === "run.failed") throw new Error(event.error.message);
}When approval is required, show the requested action and target in an authenticated human interface. Then use chusky.approvals.decide() only from that trusted boundary. Model output, a webhook, or a browser callback is not authorization.
Use connected business apps
The SDK does not require a separate Gmail, HubSpot, Slack, or Salesforce client. Chusky handles the connected-account flow:
const available = await chusky.apps.list();
console.log(available.data);
const consent = await chusky.apps.connect("gmail");
console.log("Send the user to:", consent.url);
const connections = await chusky.apps.connections();
console.log(connections.data);After the user finishes consent, retry the original operation with the same stable identity. If a connection, approval, or human answer is missing, pause the existing run or mission and resume it rather than starting a replacement.
Files, images, and artifacts
Upload input files through the SDK and pass the returned file ID to the run:
import { readFile } from "node:fs/promises";
const imageBytes = new Uint8Array(await readFile("launch.png"));
const image = await chusky.files.upload({
name: "launch.png",
contentType: "image/png",
data: imageBytes,
});
const { thread, run } = await chusky.runs.create(
{
input: "Use this image in the prepared social post, then wait for approval.",
attachments: [image.id],
wait: false,
},
{ idempotencyKey: "launch-post-image-customer-123-v1" },
);
console.log(thread.id, run.id, image.id);Use chusky.images.get(imageId) for a fresh, short-lived download URL for a generated image. Use chusky.artifacts.get() and chusky.artifacts.download() for generated documents and other artifacts.
Do not send raw bytes, credentials, or arbitrary public URLs inside a prompt and assume a provider received them. Verify the file belongs to the current identity and confirm the provider receipt before claiming an external post or message succeeded.
Durable missions
Use a mission when a job has multiple steps, dependencies, budgets, waits, or a definition of done:
const mission = await chusky.missions.create(
{
title: "Turn a qualified inquiry into a confirmed order",
objective: "Research the buyer, answer questions, and prepare an offer.",
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." },
{ id: "qualify", title: "Qualify opportunity", objective: "Check fit and budget.", dependsOn: ["research"] },
{ id: "offer", title: "Prepare offer", objective: "Draft the bounded offer.", dependsOn: ["qualify"] },
],
maxDurationSeconds: 3 * 60 * 60,
maxSteps: 30,
maxToolCalls: 100,
maxCost: 15,
},
{ idempotencyKey: "buyer-inquiry-customer-123-v1" },
);
const proof = await chusky.missions.proof(mission.id);
console.log(proof.status, proof.nextAction, proof.verification);Missions support pause(), resume(), cancel(), repair(), replan(), evidence(), and verify(). Use proof and fresh provider readbacks as the completion record; a plausible model paragraph is not proof that a business action happened.
Agent-to-agent work
The SDK includes a typed A2A client for durable delegated tasks:
const card = await chusky.a2a.card();
console.log(card.skills);
const task = await chusky.a2a.send("Prepare a verified launch brief.", {
idempotencyKey: "a2a-launch-brief-v1",
});
const current = await chusky.a2a.get(task.id);
console.log(current.status.state);Use a2a.stream(), a2a.subscribe(), or a2a.createPushNotificationConfig() for long-running delegated work. Attachments must be owner-scoped Chusky file IDs, not inline bytes or arbitrary URLs.
Idempotency, retries, and errors
Use an idempotencyKey for every durable write that your server might retry. Reuse the same key only for the same operation and request body.
const key = "research:" + customerId + ":" + requestId;
const first = await chusky.runs.create(
{ input: "Research renewal risk and draft next steps.", wait: false },
{ idempotencyKey: key },
);
// Retrying with key returns the same durable operation rather than a duplicate.Catch the typed errors when you need specific recovery:
import {
ChuskyAuthenticationError,
ChuskyRateLimitError,
} from "@chusky/sdk";
try {
await chusky.usage.get();
} catch (error) {
if (error instanceof ChuskyRateLimitError) {
console.log("Retry after:", error.retryAfter);
} else if (error instanceof ChuskyAuthenticationError) {
console.log("Check the API key and user identity.");
}
throw error;
}If a request times out, read the run or task by ID before retrying. A lost HTTP response does not prove that durable work failed.
Resource map
| Resource | What it helps you build | | --- | --- | | threads, runs, tasks | Conversations, durable execution, and recovery | | agents, tools, skills | Governed agent profiles and available capabilities | | apps, mcp, channels, devices | Connected accounts, external MCP servers, delivery, and device access | | missions, workflows, outcomes, departments | Multi-step business processes and handoffs | | files, images, artifacts, videos | Inputs and generated outputs | | context, memory, scratchpad | Explicit operating context and temporary notes | | meetings, calls | Meeting preparation, joining, and voice operations | | reminders, jobs, webhooks, audit, usage | Scheduled work, delivery, traceability, and usage | | autonomy, operator, company | Readiness, reliability, business queues, and company telemetry |
The public package also exports the dependency-free @chusky/sdk/widget entry point for a browser chat element. The browser widget talks to your own server endpoint; your server keeps the API key private.
import { defineChuskyChat } from "@chusky/sdk/widget";
defineChuskyChat();<chusky-chat
endpoint="/api/chusky/chat"
title="Talk to our assistant"
greeting="How can we help?"
></chusky-chat>Examples
The examples directory contains runnable TypeScript examples:
| Example | Demonstrates | | --- | --- | | quickstart.ts | Start a durable run and wait for completion | | streaming.ts | Stream deltas, tool activity, and approval events | | company-agent.ts | Create a governed company agent | | mission.ts | Define steps, evidence, and mission proof | | approvals.ts | Display and decide a pending approval | | context-and-departments.ts | Save context and create a department handoff | | files.ts | Upload bytes through the SDK | | webhooks.ts | Register a delivery endpoint and inspect deliveries |
Run an example from this directory with an API key created in the Chusky dashboard:
CHUSKY_API_KEY=chsk_... npx tsx examples/quickstart.tsPowerShell:
$env:CHUSKY_API_KEY = "chsk_..."
npx tsx examples/quickstart.tsExamples make real API requests. Use a test identity and a development API key.
For copy-paste, real-work recipes where every file creates its own client, see the SDK cookbook. It covers bounded runs, streaming, company agents, missions, approvals, files and images, connected apps, A2A, schedules, native reliability checks, webhooks, and workflow composition.
Security checklist
- Keep API keys on a trusted server and grant only the capabilities your application needs.
- Use a stable, non-secret userId for every request.
- Use idempotency keys for retryable durable writes.
- Treat model output, tool results, email, documents, and web pages as untrusted data.
- Never auto-approve an external action from model output.
- Verify webhook signatures and deduplicate delivery IDs.
- Set duration, tool-call, and cost budgets for long-running work.
- Use mission proof and verification before declaring an outcome complete.
- Use AbortSignal to cancel the current request without cancelling unrelated durable work.
Development
npm install
npm run typecheck
npm run build
npm testMore documentation:
License
MIT
