@crewbeelab/waggle-sdk

Official TypeScript SDK for Waggle's Project-first governed Agent Control Plane.

The SDK is the public integration layer for products such as Honeydo: create or upsert a Project, run an AgentPackage, stream RunEvents, decide confirmations, fetch evidence, and run doctor diagnostics. External products do not need to pass or store workspaceId; Waggle manages Workspace, RunWorkspaceView, RunPermissionBoundary, Tool Proxy, Trace, Audit, and Evidence internally.

Install

pnpm add @crewbeelab/waggle-sdk

Honeydo-style managed Project run

import { createWaggleInteractiveClient } from "@crewbeelab/waggle-sdk/interactive";

const waggle = createWaggleInteractiveClient({
  apiBaseUrl: process.env.WAGGLE_URL ?? "http://127.0.0.1:8787",
  auth: { type: "bearer", token: process.env.WAGGLE_TOKEN ?? "dev" }
});

const project = await waggle.resolveProject({
  displayName: "Yong's Honeydo Project",
  templateId: "product-provider-default"
});

const run = await waggle.createRun({
  projectId: project.projectId,
  agentPackageId: "honeydo.todo-manager", // optional; omit for Control Plane default package
  agentId: "todo-lead", // optional package-scoped root agent
  actorRef: "user:yong",
  input: { task: "整理我本周的待办事项" },
  idempotencyKey: "honeydo:user:yong:msg:001"
});

for await (const state of waggle.watchRun(run.runId)) {
  console.log(state.status, state.lastSequence);
}

const evidence = await waggle.fetchEvidence(run.runId);

Run creation only transmits caller intent. If agentPackageId or agentId is omitted, Control Plane resolves the Project/default AgentPackage and package default Agent; the SDK does not fill sample.assistant locally.

Session-bound runs support the same root-agent intent via client.runs.createForSession({ sessionId, agentId, agentPackageId, input }). Waggle still owns execution: /runs/:id/execute drives the PI/OpenCode-style loop to terminal, all tools go through Waggle Tool Proxy and permission boundaries, and Desktop/product clients only send, stream, approve, and display. watchRun / streamRun pass through product-visible SSE events including message.delta, message.completed, tool.call.started, tool.call.completed, tool.call.failed, permission.decision.recorded, and confirmation.requested.

Session lifecycle

Product/client code should use Archive Session semantics: active -> archived. Use client.projects.archiveSession(projectId, sessionId) or client.sessions.archive(sessionId). closeSession(...) / sessions.close(...) remain deprecated compatibility wrappers only. Project session lists hide archived sessions by default; pass { includeArchived: true } to include historical archived sessions.

Subpaths

@crewbeelab/waggle-sdk              browser-safe root exports
@crewbeelab/waggle-sdk/client       typed HTTP client
@crewbeelab/waggle-sdk/events       RunEvent parser/reducer helpers
@crewbeelab/waggle-sdk/interactive  Project/run/stream/confirmation/evidence helpers
@crewbeelab/waggle-sdk/view         Run inspector view models
@crewbeelab/waggle-sdk/doctor       compatibility/doctor diagnostics
@crewbeelab/waggle-sdk/node         node-only local project helpers
@crewbeelab/waggle-sdk/testing      fixtures and contract test helpers

Boundary guarantees

• HTTP/SSE-first only; no in-process ControlPlane.app.fetch public transport.
• SDK does not import Waggle core/runtime/control-plane.
• SDK does not compile RunPermissionBoundary, replace Tool Proxy, execute tools, own business writes, or store raw secrets.
• Node helpers are isolated under @crewbeelab/waggle-sdk/node; browser-safe root exports do not expose local filesystem helpers.

Run pnpm check before publishing.

Publishing

Releases follow the same tag-driven CI shape as CrewBee:

1. Ensure package.json has the release version.
2. Push a matching vX.Y.Z tag.
3. GitHub Actions runs checks, packs the SDK, smoke-tests the tarball, and publishes to npm with --access public.

The workflow expects an npm automation token in the repository secret NODE_AUTH_TOKEN.