@chusky/sdk 0.1.2 → 0.2.0

package/docs/api-contract.md

@@ -20,6 +20,22 @@ scopes, rotate, and revoke project keys. They never accept or return
 Each verified account may have at most 10 active projects. Root-created projects
 remain ownerless operator records and are not visible through account routes.
 
+Company projects attach to a Better Auth organization ID. Owners/admins can
+create and manage project credentials, policy, and up to 20 agent profiles;
+verified members can list those project resources. Default company scopes are
+least-privilege and intentionally exclude `approvals:write`, so a project key
+cannot approve its own external tool actions. Composio app/OAuth and trigger
+endpoints remain the existing integration surface and retain the stable Chusky
+end-user identity supplied in `X-Chusky-User-Id`.
+
+Company telemetry is project-scoped rather than caller-scoped: keys with the
+`company:read` scope can read status-only run summaries, bounded audit events,
+and monthly completed-run/model-cost totals at `/v1/company/runs`,
+`/v1/company/audit-events`, and `/v1/company/usage`. The authenticated
+workspace dashboard exposes the same views only to organization owners/admins.
+Run inputs/outputs and user/provider payloads are never copied into this shared
+ledger. Durable run completion accounting is idempotent by project and run ID.
+
 ## Resources
 
 | Resource | Endpoint | Notes |
@@ -27,6 +43,8 @@ remain ownerless operator records and are not visible through account routes.
 | Threads | `POST /v1/threads`, `GET /v1/threads/:threadId` | Conversation/memory boundary for one explicit SDK end user. |
 | Projects | `GET/POST /v1/admin/projects`, `DELETE /v1/admin/projects/:id` | Root-key-only project provisioning and key revocation. |
 | Dashboard projects | `GET/POST /v1/account/projects`, `PATCH /v1/account/projects/:id`, `POST .../rotate-key`, `DELETE .../:id` | Better-Auth-cookie-only, verified-user project management. |
+| Company policy | `GET/PUT /v1/account/projects/:id/policy` | Organization members may read; only owners/admins may change bounded tool grants and per-run budgets. |
+| Company agents | `GET/POST/PATCH/DELETE /v1/account/projects/:id/agents` and `/v1/agents` | Dashboard management is role-checked; SDK routes require project `agents:read/write` scopes. Templates are listed at `GET /v1/agents/templates`. |
 | Runs | `POST /v1/threads/:threadId/runs` | Executes durable Chusky work. `wait` is bounded. |
 | Run stream | `POST /v1/threads/:threadId/runs/stream` | `application/x-ndjson`; emits typed run events. |
 | Runs | `GET /v1/threads/:threadId/runs/:runId`, `POST .../cancel` | Cancellation is request-specific; durable task results stay queryable. |
@@ -35,7 +53,16 @@ remain ownerless operator records and are not visible through account routes.
 | Files | `POST /v1/files`, `POST /v1/files/:fileId/complete`, `GET/DELETE /v1/files/:fileId` | Direct R2 upload URLs are short-lived; a `HEAD` verification must succeed before download; deletion is owner-scoped. |
 | Webhooks | `POST /v1/webhooks`, `GET /v1/webhooks`, `DELETE /v1/webhooks/:id` | HTTPS-only subscription; secret is encrypted at rest and returned only on creation. |
 | Delivery history | `GET /v1/webhooks/:id/deliveries` | Bounded, safe delivery status for operational diagnosis; delete disables future deliveries. |
+| Trigger catalogue | `GET /v1/triggers/catalog/toolkits`, `GET /v1/triggers/catalog/toolkits/:toolkit` | Composio-backed, paginated trigger types for connected apps; the dashboard uses the same catalogue as Telegram. `POST /v1/triggers` can pin creation to a verified `connectedAccountId`. |
 | Observability | `GET /v1/audit-events`, `GET /v1/usage` | Bounded per-user audit trail and current usage snapshot. |
+| Company telemetry | `GET /v1/company/runs`, `/v1/company/audit-events`, `/v1/company/usage`; dashboard `GET /v1/account/projects/:id/company/{runs,audit-events,usage}` | Requires `company:read` for project keys; dashboard reads require workspace owner/admin. Run summaries contain no prompt or output. |
+| Calls | `GET/POST /v1/account/calls` | Lists redacted call metadata and creates an approval-gated outbound call request. SDK callers use `calls:read/write`; dashboard callers must be verified and Telegram-linked. |
+| Voice | `GET /v1/account/voice-options`, `PATCH /v1/account/preferences` | Lists Flux and optional Bland catalogue entries and stores the account's live voice preference. Use `voice:read` for the catalogue and `account:write` for preferences. |
+| Meetings | `GET/POST /v1/meetings`, `POST /v1/meetings/prepare`, `GET/PATCH /v1/meetings/profile`, `POST /v1/meetings/preparations/:id/join`, `GET /v1/meetings/:id`, `POST /v1/meetings/:id/leave`, `GET /v1/meetings/:id/context`, `DELETE /v1/meetings/contacts/:id` | Recall lifecycle for Zoom, Google Meet, Microsoft Teams, and Webex. SDK callers use `meetings:read/write`; meeting URLs and sealed calendar links are never returned by list endpoints. |
+| Connected apps | `GET /v1/apps`, `POST /v1/apps/:toolkit/connect`, `GET /v1/apps/connections`, `DELETE /v1/apps/connections/:id` | Composio toolkit discovery, OAuth connection links, connected-account listing, and disconnect. Credentials remain server-side. |
+| Native schedules | `GET/POST/DELETE /v1/reminders`, `GET/POST/DELETE /v1/jobs` | One-time reminders and recurring QStash schedules owned by the SDK user. |
+| Memory and scratchpad | `GET/POST/DELETE /v1/memory`, `GET/PUT/DELETE /v1/scratchpad` | Explicit structured memory and temporary working notes; both are user-scoped. |
+| Channel and device management | `GET/POST/PATCH/DELETE /v1/channels`, `GET/DELETE /v1/devices` | Link supported channels, control proactive delivery, and revoke CLI devices without exposing credentials. |
 
 ## Event stream
 

package/docs/budgets.mdx

@@ -23,3 +23,19 @@ Recommended responses:
 Expose usage through the usage endpoint and include bounded cost metadata in run and webhook records. Never trust a client-provided cost value.
 
 For asynchronous work, combine the budget with `wait: false`; the QStash-backed task resumes from persisted state after a process restart. Treat the returned task as the source of truth for progress and retry state.
+
+## Inspecting a durable trace
+
+Every synchronous SDK run is also checkpointed as a provider-neutral agent run.
+Use the trace endpoint to inspect model turns, tool starts/results, approvals,
+failures, and completion without loading the transcript into the normal run
+response:
+
+```http
+GET /v1/threads/{threadId}/runs/{runId}/trace
+```
+
+Pass `?include_state=true` only when the checkpointed messages and tool results
+are needed for debugging. The trace is owner-scoped, versioned for optimistic
+concurrency, and retained independently from chat history. Worker handoffs use
+the same trace model and expose their `runId` through the worker endpoints.

package/docs/calls.mdx

@@ -0,0 +1,58 @@
+---
+title: Calls and live voice
+description: Request approval-gated outbound calls and configure Chusky's live voices.
+---
+
+## Providers
+
+Chusky supports outbound calls through the configured provider: Twilio for the
+private live voice bridge, or Bland when Bland is enabled and fully configured.
+The provider is selected by the Chusky deployment; application code does not
+receive provider credentials.
+
+```ts
+const voices = await chusky.account.voiceOptions();
+console.log(voices.fluxVoices.map((voice) => voice.id), voices.blandVoices);
+const current = await chusky.account.getPreferences();
+
+await chusky.account.preferences({
+  liveVoice: { provider: "meetings", voice: "flux-haley-en" },
+});
+```
+
+`provider` may be `twilio`, `meetings`, or `bland`. Flux voice options include an
+`id`, display `name`, and accent;
+Bland selections use the `{ id, name }` object returned by `voiceOptions()`.
+Set `voice: null` to restore the deployment default.
+
+## Requesting a call
+
+Call creation creates the same exact, one-time approval used by Chusky's other
+surfaces. It does not place the call until an authenticated owner approves it.
+
+```ts
+const approval = await chusky.calls.request({
+  phoneNumber: "+14155550123",
+  purpose: "Confirm the test-drive appointment and answer final questions.",
+  profile: {
+    mode: "scheduling",
+    tone: "warm",
+    capabilities: ["memory_lookup", "schedule_lookup"],
+  },
+}, { idempotencyKey: "test-drive-call-2026-09-15" });
+
+if (approval.status === "pending") {
+  // Show the exact recipient, purpose, and profile to your authenticated owner.
+  await chusky.approvals.decide(approval.id, "approve", {
+    idempotencyKey: "approve-test-drive-call-2026-09-15",
+  });
+}
+```
+
+Use `chusky.calls.list()` to inspect safe call metadata. Phone numbers are not
+used as identity keys, and call transcripts/audio are not exposed through this
+resource.
+
+The SDK endpoint requires the `calls:write` scope for requests and
+`calls:read` for listing. On dashboard sessions, the Chusky account must be
+verified and linked to its Telegram workspace.

package/docs/capabilities.mdx

@@ -37,3 +37,12 @@ Video generation is durable and independently cancellable. Submit a job with `vi
 ## Workers and channels
 
 Workers are durable scheduled routines. `workers.create()` accepts a schedule, task input, budget, and optional channel target. Channels and activity provide the control-plane view needed for dashboards and operational history.
+
+## Voice and meetings
+
+Voice calls and Recall meetings are first-class API resources rather than
+provider-specific SDK forks. Use `account.voiceOptions()` and
+`account.preferences()` for the deployment's Flux/Bland choices, `calls.request()`
+for an approval-gated outbound call, and `meetings.prepare()` plus
+`meetings.join()` for a meeting representative. See the [calls guide](/docs/calls)
+and [meetings guide](/docs/meetings) for provider details and lifecycle handling.

package/docs/company-workspaces.mdx

@@ -0,0 +1,76 @@
+---
+title: Company workspaces
+description: Configure shared Chusky agent projects and run governed business workflows.
+---
+
+Company workspaces use Better Auth organizations for membership and invitations. Workspace owners and admins create a company API project in the Chusky dashboard. Members can see project profiles and policy; only owners/admins can create or rotate keys or change policy.
+
+OAuth and connected-account lifecycle stay with Composio. Chusky calls its existing Composio integration for toolkit discovery, OAuth consent URLs, account listing, tool execution, and triggers. A company backend connects an app using the same stable Chusky identity it will later use to run the agent:
+
+```ts
+import { Chusky } from "@chusky/sdk";
+
+const chusky = new Chusky({
+  apiKey: process.env.CHUSKY_API_KEY!,
+  userId: "acme-crm-service",
+});
+
+const apps = await chusky.account.apps();
+const { url } = await chusky.account.connectApp("GMAIL");
+// Send the URL to an authorized company admin to complete Composio consent.
+```
+
+Use a stable server-side user identifier, not a browser-controlled header or a person's email address. Chusky's thread history, tasks, approvals, and Composio session are scoped to the API project plus that identity. For multi-user products, provide each authenticated end user with their own stable identifier.
+
+## Choose a specialist profile
+
+Built-in templates cover Sales Development, Lead Research, Competitive Intelligence, Customer Support, Executive Assistant, Recruiting, and Marketing Operations. Templates include bounded instructions, an allowlist, and default per-run limits. Project policy and saved profiles can further restrict tool use. The server applies the strictest budget and always requires approval before the Composio execution wrappers run.
+
+```ts
+const templates = await chusky.agents.templates();
+const leadAgent = await chusky.agents.create({
+  template: "lead-research",
+  name: "Fintech lead scout",
+  instructions: "Target companies with 50+ employees. Cite the source for headcount and prepare outreach drafts for review.",
+});
+```
+
+User-supplied company criteria are instructions/data for the profile, not tool permissions. A caller cannot expand the project or profile grant in a run request.
+
+## Run an outcome
+
+```ts
+const { thread, run } = await chusky.runs.create({
+  input: "Find fintech companies that match our ICP and prepare CRM-ready profiles and outreach drafts.",
+  agentId: leadAgent.id,
+  wait: false,
+  budget: { duration: "30m", maxToolCalls: 20, maxCost: 2 },
+}, { idempotencyKey: "acme-lead-research-2026-09-15" });
+
+const latest = await chusky.runs.get(thread.id, run.id);
+```
+
+The run is durable and task-backed when `wait: false` is used with the configured Redis/QStash execution service. Poll run/task status or receive signed webhook events. A human approves pending external actions through the authenticated dashboard or a separately authorized application. Company-project keys have approval-read scope, not approval-write scope, by default; the MCP server also cannot approve its own actions.
+
+## Read company-wide outcomes
+
+Run content and Composio sessions stay scoped to each stable caller identity. Workspace admins can still monitor shared execution status and spend without exposing prompts or outputs:
+
+```ts
+const [runs, events, usage] = await Promise.all([
+  chusky.company.runs({ limit: 20 }),
+  chusky.company.audit(),
+  chusky.company.usage(),
+]);
+
+console.log(runs.data.map(({ id, status, agentName }) => ({ id, status, agentName })));
+console.log(usage.currentMonth.completedRuns, usage.currentMonth.costUsd);
+```
+
+These reads require the project key's `company:read` scope. The dashboard shows the same project-scoped view to workspace owners/admins. Audit entries contain bounded action paths, status, request IDs, and timestamps—not request bodies. Successful durable completion is counted once per project/run even if a workflow completion is retried.
+
+## Integrate a company system
+
+Use the SDK in a trusted backend, call the versioned REST API directly, or connect the Cloudflare Streamable HTTP MCP server at `/mcp`. MCP clients pass the scoped `chsk_` key and the same stable `X-Chusky-User-Id` header. See [`cloudflare/chusky-mcp`](../../cloudflare/chusky-mcp/README.md) for tools and deployment configuration.
+
+Use existing Composio triggers or Chusky's scheduling facilities for event-driven and delayed work. Make the business instruction explicit—for example, draft a follow-up after three days—and keep sending gated by human approval. The standard agent profile does not itself create a prospect-facing recurring schedule.

package/docs/embedded-chat.mdx

@@ -0,0 +1,76 @@
+---
+title: Embedded chat
+description: Add a safe customer-facing Chusky chat without exposing project credentials.
+---
+
+The widget is a browser UI only. It never talks to Chusky with a project key.
+Your server owns the key, authenticates the visitor, chooses the stable Chusky
+user ID, and proxies the stream.
+
+## Add the widget
+
+```html
+<script type="module">
+  import { defineChuskyChat } from "@chusky/sdk/widget";
+  defineChuskyChat();
+</script>
+<chusky-chat
+  endpoint="/api/chusky/chat"
+  title="Acme assistant"
+  accent-color="#111111"
+></chusky-chat>
+```
+
+The element renders an accessible launcher, message list, loading state, retry
+state, and approval-pending notice. It accepts bounded NDJSON events with
+`run.delta`, `run.completed`, `run.requires_approval`, and `error` types.
+
+## Server route contract
+
+`POST /api/chusky/chat` receives:
+
+```json
+{ "message": "Prepare a sales brief", "conversationId": "optional-client-id" }
+```
+
+The route should:
+
+1. Authenticate the visitor using your own session.
+2. Derive a stable, non-PII customer identifier.
+3. Create or recover a Chusky thread for that customer.
+4. Call `threads.runs.stream()` with the server-side project key.
+5. Forward only bounded run events; never forward raw tool arguments, provider
+   payloads, prompts, tokens, or private account details.
+
+The route must reject missing sessions, cross-customer conversation IDs,
+oversized messages, and cross-origin requests. Add your own rate limit and
+CSRF/origin policy.
+
+## Example server flow
+
+```ts
+const chusky = new Chusky({
+  apiKey: process.env.CHUSKY_API_KEY!,
+  userId: `customer_${session.accountId}`,
+});
+
+const thread = await chusky.threads.create({ source: "embedded-chat" });
+const stream = chusky.threads.runs(thread.id).stream({ input: message });
+// Convert the SDK events to NDJSON and return a streaming Response.
+```
+
+For durable business work, use `runs.create({ wait: false })` instead of the
+interactive stream and show the widget a status link or task progress.
+
+## Approval behavior
+
+The widget cannot approve an external action. When Chusky emits
+`run.requires_approval`, show a neutral waiting state and direct the customer
+to the authenticated company console or your own approved operator workflow.
+
+## Domain and branding
+
+Workspace branding is configured by an owner/admin in Organizations. Custom
+domains require provider-side DNS/TLS routing; Chusky reports `pending_dns`
+until the operator has completed that step. Branding changes do not grant API
+access and do not change project scopes.

package/docs/index.mdx

@@ -17,6 +17,9 @@ Install the SDK, create a thread, and stream the first response.
 - Authenticated chat products with streaming responses
 - Human-in-the-loop workflows for sending, deleting, publishing, or changing data
 - File-aware assistants using verified Cloudflare R2 uploads
+- Company workspaces with specialist agent templates and project-scoped run policies
+- Voice workflows through Twilio or Bland, with deployment-supported voice selection
+- Recall meeting representatives for Zoom, Google Meet, Microsoft Teams, and Webex
 
 ## The execution model
 

package/docs/meetings.mdx

@@ -0,0 +1,73 @@
+---
+title: Meetings
+description: Prepare, join, participate in, and leave Recall meetings from the SDK.
+---
+
+## Supported platforms
+
+The meeting resource supports Recall links for Zoom, Google Meet, Microsoft
+Teams, and Webex. Chusky validates the link and platform before sending
+anything to Recall. Recall's optional shared-screen understanding is available
+only where the deployment and Recall support it.
+
+## Configure the representative
+
+The meeting profile controls how Chusky participates. It contains the display
+identity, communication guidance, approved knowledge, meeting tools, account
+aliases, and calendar auto-join preference.
+
+```ts
+const profile = await chusky.meetings.updateProfile({
+  representativeName: "Chusky",
+  organizationName: "Acme Motors",
+  role: "sales",
+  communicationStyle: "Natural, concise, curious, and helpful.",
+  approvedKnowledge: "Only use the approved product and pricing facts.",
+  allowedComposioTools: ["GOOGLECALENDAR_CREATE_EVENT"],
+  autoJoinCalendar: false,
+});
+```
+
+## Prepare and join
+
+Preparation searches the owner's saved relationship/business context and
+returns a private brief. It does not join a meeting. A direct join can receive
+that brief as `clientContext`; a calendar-prepared join uses the opaque
+preparation ID and never requires the caller to re-send the meeting URL.
+
+```ts
+const brief = await chusky.meetings.prepare({
+  clientName: "Jordan Lee",
+  objective: "Understand whether Acme Motors is a fit for the fleet program.",
+});
+
+const meeting = await chusky.meetings.join({
+  meetingUrl: "https://meet.google.com/example-room",
+  title: "Acme Motors fleet discussion",
+  interactionMode: "representative",
+  clientName: "Jordan Lee",
+  objective: "Understand whether Acme Motors is a fit for the fleet program.",
+}, { idempotencyKey: "acme-fleet-meeting-2026-09-15" });
+```
+
+`joinAt` schedules the Recall bot when the event is at least ten minutes in the
+future. For recurring calendar automation, use the preparation returned by
+`meetings.list()` and call `joinPreparation(preparation.id)`.
+
+## Roster, context, and lifecycle
+
+```ts
+const snapshot = await chusky.meetings.get(meeting.id);
+const context = await chusky.meetings.context(meeting.id, "What approved facts are relevant to pricing?");
+await chusky.meetings.leave(meeting.id);
+```
+
+The meeting snapshot includes the provider platform, lifecycle status, mission
+metadata, and safe retention state. Participant roster and outcomes are
+available in `meetings.list()` for the authenticated owner. Meeting context is
+available only for an active representative meeting and contains relevant
+owner-stored facts, not arbitrary private history.
+
+Use signed Recall webhooks and durable Redis/QStash in production. A successful
+join request means Chusky accepted and persisted the meeting lifecycle; use
+`get()` or `list()` to observe admission, in-call, ended, and failed states.

package/docs/production.mdx

@@ -17,6 +17,8 @@ description: Deploy a reliable Chusky integration.
 - Monitor webhook delivery failures, run failures, rate limits, and spend.
 - Rotate project keys and webhook secrets on a schedule or incident.
 - Test duplicate requests, expired approvals, unauthorized IDs, provider outages, and reconnects.
+- For calls, test provider-unavailable responses, redacted call history, approval expiry, and Bland/Twilio configuration separately.
+- For meetings, test direct joins and calendar-prepared joins against an authorized staging meeting for each enabled Recall platform. Verify scheduled joins, cancellation, participant updates, meeting-end reconciliation, and idempotent retries before production use.
 
 ## Local validation
 

package/docs.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://mintlify.com/docs.json",
+  "name": "Chusky",
+  "colors": { "primary": "#111111", "light": "#f7f7f4", "dark": "#111111" },
+  "navigation": {
+    "tabs": [
+      { "tab": "Documentation", "groups": [
+        { "group": "Start here", "pages": ["docs/index", "docs/quickstart", "docs/concepts"] },
+        { "group": "Build with Chusky", "pages": ["docs/company-workspaces", "docs/embedded-chat", "docs/calls", "docs/meetings", "docs/streaming", "docs/models", "docs/files", "docs/approvals", "docs/tasks", "docs/policies", "docs/structured-output", "docs/fallbacks", "docs/budgets", "docs/capabilities", "docs/architecture"] },
+        { "group": "Production", "pages": ["docs/webhooks", "docs/security", "docs/errors", "docs/releases", "docs/production"] }
+      ] },
+      { "tab": "API Reference", "openapi": "openapi.yaml", "pages": ["docs/api-contract"] }
+    ]
+  }
+}