@chusky/sdk 0.1.1 → 0.2.0

package/dist/widget.js

@@ -0,0 +1,137 @@
+const HTMLElementBase = globalThis.HTMLElement ?? class {
+};
+/** A dependency-free chat element. The host owns auth and keeps the API key server-side. */
+export class ChuskyChatElement extends HTMLElementBase {
+    messages = [];
+    busy = false;
+    conversationId;
+    connectedCallback() {
+        if (!this.shadowRoot)
+            this.attachShadow({ mode: "open" });
+        this.render();
+    }
+    options() {
+        return {
+            endpoint: this.getAttribute("endpoint") ?? "/api/chusky/chat",
+            title: this.getAttribute("title") ?? "Chat with us",
+            greeting: this.getAttribute("greeting") ?? "How can I help?",
+            accentColor: this.getAttribute("accent-color") ?? "#111111",
+        };
+    }
+    render() {
+        if (!this.shadowRoot)
+            return;
+        const options = this.options();
+        const messages = this.messages.length ? this.messages.map((message) => `
+      <div class="message ${message.role}" aria-label="${message.role === "user" ? "You" : "Chusky"}">${escapeHtml(message.text).replace(/\n/g, "<br />")}</div>`).join("") : `<p class="greeting">${escapeHtml(options.greeting ?? "How can I help?")}</p>`;
+        const accent = escapeHtml(options.accentColor ?? "#111111");
+        this.shadowRoot.innerHTML = `
+      <style>
+        :host { color: #1d1d1b; font: 14px/1.45 system-ui, sans-serif; }
+        .shell { width: min(360px, calc(100vw - 32px)); border: 1px solid #d9d9d2; border-radius: 16px; background: #fff; box-shadow: 0 16px 45px rgb(0 0 0 / 12%); overflow: hidden; }
+        header { padding: 14px 16px; color: #fff; background: ${accent}; }
+        header strong { font-size: 14px; }
+        .messages { display: grid; gap: 9px; max-height: 320px; overflow: auto; padding: 16px; background: #f7f7f4; }
+        .greeting { margin: 0; color: #696963; }
+        .message { max-width: 84%; padding: 9px 11px; border-radius: 11px; overflow-wrap: anywhere; }
+        .message.user { justify-self: end; color: #fff; background: ${accent}; }
+        .message.assistant { justify-self: start; border: 1px solid #deded7; background: #fff; }
+        form { display: flex; gap: 8px; padding: 12px; border-top: 1px solid #e3e3dd; background: #fff; }
+        textarea { flex: 1; min-height: 38px; max-height: 110px; resize: vertical; border: 1px solid #cfcfc7; border-radius: 9px; padding: 9px; font: inherit; }
+        button { align-self: end; border: 0; border-radius: 9px; padding: 10px 12px; color: #fff; background: ${accent}; cursor: pointer; }
+        button:disabled { cursor: wait; opacity: .55; }
+        textarea:focus-visible, button:focus-visible { outline: 2px solid #6a8cff; outline-offset: 2px; }
+      </style>
+      <section class="shell" aria-label="${escapeHtml(options.title ?? "Chat")}">
+        <header><strong>${escapeHtml(options.title ?? "Chat with us")}</strong></header>
+        <div class="messages" role="log" aria-live="polite">${messages}</div>
+        <form>
+          <textarea name="message" maxlength="4000" aria-label="Message" placeholder="Write a message…" required></textarea>
+          <button type="submit" ${this.busy ? "disabled" : ""}>${this.busy ? "…" : "Send"}</button>
+        </form>
+      </section>`;
+        this.shadowRoot.querySelector("form")?.addEventListener("submit", (event) => {
+            event.preventDefault();
+            const input = this.shadowRoot?.querySelector("textarea");
+            if (input?.value.trim())
+                void this.send(input.value.trim());
+        });
+        const log = this.shadowRoot.querySelector(".messages");
+        if (log)
+            log.scrollTop = log.scrollHeight;
+    }
+    async send(message) {
+        if (this.busy)
+            return;
+        this.busy = true;
+        this.messages.push({ role: "user", text: message });
+        this.messages.push({ role: "assistant", text: "" });
+        this.render();
+        try {
+            const response = await fetch(this.options().endpoint, {
+                method: "POST",
+                credentials: "include",
+                headers: { "Content-Type": "application/json", Accept: "application/x-ndjson, application/json" },
+                body: JSON.stringify({ message, conversationId: this.conversationId }),
+            });
+            if (!response.ok)
+                throw new Error("The assistant could not respond.");
+            await this.consume(response);
+        }
+        catch (error) {
+            this.messages[this.messages.length - 1] = { role: "assistant", text: error instanceof Error ? error.message : "The assistant could not respond." };
+        }
+        finally {
+            this.busy = false;
+            this.render();
+        }
+    }
+    async consume(response) {
+        const contentType = response.headers.get("content-type") ?? "";
+        if (!contentType.includes("ndjson") || !response.body) {
+            const body = await response.json().catch(async () => ({ text: await response.text() }));
+            if (body.conversationId)
+                this.conversationId = body.conversationId;
+            this.messages[this.messages.length - 1].text = body.text ?? body.message ?? "";
+            return;
+        }
+        const reader = response.body.getReader();
+        const decoder = new TextDecoder();
+        let pending = "";
+        while (true) {
+            const { value, done } = await reader.read();
+            pending += decoder.decode(value, { stream: !done });
+            const lines = pending.split("\n");
+            pending = lines.pop() ?? "";
+            for (const line of lines)
+                this.consumeEvent(line);
+            if (done)
+                break;
+        }
+        if (pending.trim())
+            this.consumeEvent(pending);
+    }
+    consumeEvent(line) {
+        if (!line.trim())
+            return;
+        const event = JSON.parse(line);
+        if (event.conversationId)
+            this.conversationId = event.conversationId;
+        if (event.type === "run.delta" || event.type === "message.delta")
+            this.messages[this.messages.length - 1].text += event.text ?? "";
+        if (event.type === "run.approval_required" || event.type === "approval_required")
+            this.messages[this.messages.length - 1].text += "\nThis action is waiting for approval.";
+        if (event.type === "error")
+            this.messages[this.messages.length - 1].text += event.error ?? event.message ?? "The assistant encountered an error.";
+        this.render();
+    }
+}
+export function defineChuskyChat(tagName = "chusky-chat") {
+    if (typeof customElements === "undefined" || customElements.get(tagName))
+        return;
+    customElements.define(tagName, ChuskyChatElement);
+}
+function escapeHtml(value) {
+    return value.replace(/[&<>\"']/g, (character) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", "\"": "&quot;", "'": "&#39;" })[character] ?? character);
+}
+//# sourceMappingURL=widget.js.map

package/dist/widget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"widget.js","sourceRoot":"","sources":["../src/widget.ts"],"names":[],"mappings":"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"}

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/architecture.mdx

@@ -0,0 +1,32 @@
+---
+title: How the platform works
+description: Understand request boundaries, durable execution, storage, and delivery.
+---
+
+## Request boundaries
+
+Every SDK request is scoped by two values: the project key in `Authorization` and your application user ID in `X-Chusky-User-Id`. The user ID is the ownership boundary for threads, runs, files, approvals, tasks, artifacts, channel connections, and activity. Private credentials and internal tool implementations stay on the server.
+
+The API is versioned under `/v1`. POST operations that create or change durable state accept `Idempotency-Key`; reuse the same key only when retrying the exact same operation. A mismatch returns a conflict instead of creating a duplicate.
+
+## Synchronous and durable runs
+
+`runs.create()` waits for a terminal result by default. `wait: false` persists the run and creates a task before returning `202`. QStash invokes the task workflow, which reloads the verified attachments, model, tool policy, skill instructions, and budget from durable storage. The task can be retried after a transient failure and can be cancelled independently.
+
+The run’s duration budget is a wall-clock limit across continuations. Tool-call and cost ceilings are checked inside the agent loop. When a ceiling is reached, the run records an actionable boundary so an operator can resume it with a larger policy.
+
+## Capability and approval flow
+
+The server resolves the requested native and Composio tools, then applies allow and deny rules before sending the catalog to the model. `requireApproval` adds an explicit approval gate for selected tools, including tools that are not classified as risky by default. Risky tools still require approval automatically. Approval decisions are scoped to the user, expire, and bind to the arguments that the reviewer saw.
+
+Skills are read from the trusted project `.chusky/skills` catalog. A skill’s `SKILL.md` is loaded as bounded instructions, and supporting files can be discovered through the skills API. Unknown or removed skills are ignored safely so a run can still complete with the remaining instructions.
+
+## Files and artifacts
+
+Uploads go directly to Cloudflare R2 using a five-minute presigned URL. Chusky verifies the object’s size and content type before marking it available. Runs refer to file IDs; the server resolves those IDs to bytes or signed URLs and never accepts arbitrary object keys from the client.
+
+Artifacts are outputs registered by the Daytona workspace. The artifact record is scoped to the owning user; the download endpoint checks ownership and returns verified bytes with a safe filename. This makes generated PDFs, documents, presentations, spreadsheets, images, videos, and ZIP files addressable after the original run has ended.
+
+## Webhooks and operational views
+
+Terminal run events are written to the durable webhook outbox before delivery. The outbox leases work, retries interrupted deliveries, and exposes delivery records for inspection and retry. `activity`, `deliveries`, `usage`, and `channels` are read-only control-plane views suitable for an operator dashboard.

package/docs/budgets.mdx

@@ -0,0 +1,41 @@
+---
+title: Usage and budget limits
+description: Keep model, tool, file, and workflow costs predictable.
+---
+
+Budget policies can be set on each run and should also be constrained by the project and user policy in your application.
+
+```ts
+const budget = {
+  maxToolCalls: 20,
+  maxCost: 0.25,
+};
+```
+
+The server enforces `maxToolCalls` and `maxCost` during the run. A tool-call ceiling produces a resumable boundary with an actionable message; a cost ceiling stops additional tool work. Durable runs also accept `budget.duration` values of `5m`, `30m`, `1h`, `3h`, `6h`, `3d`, or `1w`.
+
+Recommended responses:
+
+- `402 spend_limit` when a budget is exhausted
+- `429 rate_limited` when request throughput is exceeded
+- `409 policy_violation` when a run requests a disallowed capability
+
+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

@@ -0,0 +1,48 @@
+---
+title: Capabilities, skills, and artifacts
+description: Give runs the right tools and move generated work safely through the platform.
+---
+
+## Tool and skill discovery
+
+Use `tools.list()` to discover the Composio and native capabilities available to a project. Use `skills.list()` to inspect the trusted `.chusky/skills` catalog and `skills.files()` or `skills.readFile()` when a skill references supporting scripts, templates, or assets.
+
+```ts
+const tools = await chusky.tools.list({ query: "Gmail" });
+const skills = await chusky.skills.list();
+
+const run = await chusky.threads.runs(thread.id).create({
+  input: "Research the customer and prepare a report.",
+  tools: { allow: tools.data.slice(0, 5).map((tool) => tool.slug) },
+  skills: skills.data.filter((skill) => skill.name === "research").map((skill) => skill.name),
+  wait: false,
+  budget: { duration: "3h", maxToolCalls: 60, maxCost: 2 },
+});
+```
+
+Allow and deny rules are checked before the model sees the catalog and again immediately before execution. A missing connected account is surfaced as a connection requirement; it does not silently grant a credential.
+
+## Generated artifacts and video jobs
+
+Artifacts are verified outputs produced in the Daytona workspace. List them, inspect metadata, and download the bytes through the SDK:
+
+```ts
+const artifacts = await chusky.artifacts.list({ type: "report" });
+const file = await chusky.artifacts.download(artifacts.data[0].id);
+await writeFile("report.pdf", Buffer.from(file.bytes));
+```
+
+Video generation is durable and independently cancellable. Submit a job with `videos.create()`, observe it with `videos.get()`, and deliver the completed artifact through the channel or your own storage policy.
+
+## 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/fallbacks.mdx

@@ -0,0 +1,23 @@
+---
+title: Fallback models
+description: Keep runs available when a model is unavailable or unsuitable.
+---
+
+Fallbacks are an ordered list of models used only for retryable failures such as provider outages, rate limits, or unsupported input modalities.
+
+```ts
+// Planned SDK shape
+const chusky = new Chusky({
+  apiKey: process.env.CHUSKY_API_KEY!,
+  userId: "customer_123",
+  model: "openai/gpt-5.6-luna",
+  fallbackModels: [
+    "deepseek/deepseek-v4-flash",
+    "anthropic/claude-sonnet-4",
+  ],
+});
+```
+
+Fallbacks must not retry invalid input, denied permissions, expired approvals, or destructive tool calls. The final selected model should be recorded in the run and webhook metadata. A fallback must preserve the same conversation and idempotency context.
+
+> **Status:** Planned public API. The current SDK supports a configured model and per-run model override; ordered fallback execution is not yet exposed.

package/docs/files.mdx

@@ -19,6 +19,13 @@ await fetch(intent.uploadUrl, {
 });
 
 const verified = await chusky.files.complete(intent.id);
+
+// For Node.js Buffers, Uint8Arrays, or browser Blobs:
+const uploaded = await chusky.files.upload({
+  name: "logo.png",
+  contentType: "image/png",
+  bytes,
+});
 ```
 
 Only verified files can be attached or downloaded. Upload URLs expire quickly; do not persist them. The backend enforces type, size, ownership, and content-type verification.

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