Waggle is CrewBeeLab's software-first, Project-first governed AI Agent Harness / Agent Control Plane for product-native agent governance. It turns product software into agent-operable skills and runs AgentPackages inside Projects with explicit RunPermissionBoundaries, Tool Proxy enforcement, product-owned confirmations, and audit evidence.
Agent soul, product control.
Product teams keep ownership of business data, business rules, final writes, confirmation UX, and the end-user experience. Waggle owns the governed run: Project, Session, Run, model resolution, tool enforcement, workspace access, events, evidence, and runtime hosting.
Not a chat backend.
Not a model gateway.
Not a workflow DAG engine.
Not an unlimited host-automation platform.
Available today: a TypeScript Control Plane with HTTP/SSE APIs, a CLI and reference clients, PI-backed agent execution, SQLite and PostgreSQL storage profiles, Docker Compose deployment, and the public @crewbeelab/waggle-sdk.
Giving an agent a model and a list of tools is enough for a demo. It is not enough for a product.
Real product integration needs answers to harder questions:
- Which product capabilities may this run use?
- Which files, commands, network targets, and models are in scope?
- Who owns confirmation for a high-impact action?
- Can a client reconnect without inventing a second run?
- What evidence explains what happened?
- Can the product add agent capability without handing over its database or credentials?
Waggle focuses on three current product differentiators:
- Software as a Skill - Products expose focused tools, context, callbacks, and confirmation semantics. Agents operate the product through that controlled surface; the product keeps business ownership.
- Enforced per-run governance - Every AgentRun receives a compiled
RunPermissionBoundary. Model calls go through the Model Gateway, tool calls go through the Tool Proxy, and workspace operations go through the Workspace Guard. - Project-first Agent Control Plane - Clients work with Projects, Sessions, Runs, events, confirmations, artifacts, and evidence over HTTP/SSE. Internal Workspace and worker details stay behind the control-plane boundary.
Waggle is governance-first, not automation-first. More capability is useful only when its authority, lifecycle, and evidence remain understandable.
flowchart LR
Client["Product UI / SDK / CLI / Desktop"] --> CP["Waggle Control Plane"]
CP --> Run["Project / Session / AgentRun"]
Run --> Model["RunModelSurface<br/>Model Gateway"]
Run --> Boundary["RunPermissionBoundary"]
Boundary --> Tool["Tool Proxy"]
Boundary --> Workspace["Workspace Guard"]
Tool --> Provider["Product Provider"]
Provider --> Backend["Product Backend"]
Run --> Evidence["Events / Confirmations / Artifacts / Evidence"]
Evidence --> Client
The runtime executes the agent loop. Waggle defines and enforces the product-facing governance semantics around that loop.
- Documentation index
- Build, deploy, and operate
- Run tasks through CLI or HTTP
- Configure providers, models, and credentials
- Integrate a product with the Waggle SDK
- Control Plane API contract
- Architecture
- Current implementation and known gaps
- Testing strategy
For Chinese operator documentation, start with PACKAGE-QUICKSTART.zh-CN.md or the Chinese guides under docs/.
- What Waggle Is
- What Waggle Solves
- Core Concepts
- Core Features
- Two Integration Modes
- How a Run Works
- Get Started
- Run Your First Task
- Integrate a Product
- Deployment Profiles
- Current Scope and Roadmap
- Repository Map
- Development
- Acknowledgements
Waggle is a Project-first governed Agent Harness for software products.
Its first-class public work unit is a Project. An AgentPackage defines a focused agent capability. An AgentRun executes that capability against a Project under a short-lived, explicit RunPermissionBoundary.
Waggle sits between product/client surfaces and the agent runtime:
Product UI / Product Backend / CLI / Desktop
-> Waggle HTTP/SSE API
-> Project / Session / AgentRun
-> RunModelSurface + RunPermissionBoundary
-> Runtime adapter
-> Model Gateway + Tool Proxy + Workspace Guard
-> Events / confirmations / artifacts / evidence
-> Product-owned result and final business commit
The stable responsibility split is:
| Layer | Owns |
|---|---|
| Product | Business data, business rules, user identity, confirmation UX, final writes, end-user experience |
| Waggle | AgentPackage loading, Project/Session/Run lifecycle, model and provider surfaces, permission compilation, tool/workspace enforcement, events, trace, audit, evidence |
| Runtime | Agent loop, model/tool call mechanics, streaming mechanics |
| Protocol and SDK | Versioned contracts and developer-facing integration ergonomics |
Waggle currently uses PI Core as its production execution substrate. Runtime semantics are kept behind an adapter boundary so product governance does not become a PI-specific configuration format.
Agents should not receive a product database, service credential, or arbitrary API client.
Waggle lets a product expose named tools, bounded context, callbacks, and confirmation descriptions through a Product Provider. The Tool Proxy invokes only the capability resolved for the current run.
A tool may exist in a catalog and still be unavailable to a particular Project, actor, AgentPackage, or Run.
Waggle resolves a run-scoped capability surface and compiles a RunPermissionBoundary. Catalog presence, provider installation, or model availability never grants execution authority by itself.
A desktop window, browser tab, or HTTP request should not become the authority for the run.
Waggle persists canonical Session, Run, event, confirmation, lease, and evidence state in the Control Plane. Clients can replay events and rebuild public task state from stable IDs and cursors.
Ordinary product users should not see internal questions such as Allow tool product.todo.propose_delta?
In Product-integrated Mode, Waggle emits a business effect proposal and confirmation event. The product renders a domain-specific confirmation, performs the deterministic final write, and records the result as evidence.
An LLM provider is not a Product Provider.
Waggle resolves provider, model, endpoint, settings, and a credential reference into a sanitized RunModelSurface. Raw keys are not stored in ordinary run records, prompts, trace, callbacks, or evidence.
| Concept | Meaning |
|---|---|
Project | Typeless public work unit and governance container. Clients operate on Projects; they do not need internal Workspace IDs. |
AgentPackage | Smallest versioned and releasable agent capability unit: mission, agents, tool needs, policy, output contract, and evals. |
AgentSession | Durable conversation/work context within a Project. |
AgentRun | One governed execution of an AgentPackage in a Project. |
RunModelSurface | Sanitized, immutable model execution snapshot for one Run. |
RunProviderSurface | Product capability snapshot dynamically resolved for one Run. |
RunPermissionBoundary | Final per-run execution boundary compiled from Project, package, actor, model, provider, tool, and global policy inputs. |
Tool Proxy | Mandatory exit for agent tool calls and their permission, confirmation, idempotency, redaction, trace, and audit checks. |
Workspace Guard | Enforcement boundary for governed file, patch, artifact, and shell operations. |
Evidence | Product-safe account of stages, decisions, tool outcomes, artifacts, confirmations, and terminal result. |
Three rules matter most:
Product owns business.
Waggle owns governance.
Runtime owns mechanics.
- Create or upsert typeless Projects.
- Create Project Sessions and AgentRuns.
- Use idempotency keys for product message/run mapping.
- Execute, cancel, inspect, and converge Runs to one canonical terminal state.
- Read active-task snapshots and a resumable attention feed across Projects.
- Register and version AgentPackage manifests.
- Validate, eval, release, roll back, and deprecate package versions.
- Select a package-level agent through a stable
agentId. - Keep package policy and runtime adapters separate from product business code.
- Default-deny Permission Guard decisions.
- Tool Proxy enforcement for every runtime tool call.
- Workspace Guard-backed file tree, read, search, patch, write, and shell tools.
- Diff-first file modification and confirmation-aware execution.
- Stable public tool previews without exposing raw internal payloads.
- Runtime-derived provider/model catalog.
- Reusable Model Connections with provider, model, endpoint, scope, and credential references.
- Run-scoped provider/model overrides and BYOK with
persist=false. - Separate Product Provider and LLM ModelProvider concepts.
- Secret references and public evidence redaction.
- Ordered HTTP/SSE RunEvent streams with replay cursors.
- Public conversation and tool lifecycle projections.
- Confirmations that pause and resume the same Run and ToolCall.
- Project Artifact Center with bounded, hash-verified preview/download.
- Typed Governed Run Evidence for ordinary product surfaces.
- Developer trace, audit, permissions, and explain APIs.
- Versioned Control Plane HTTP API and OpenAPI/schema endpoints.
- Public TypeScript SDK for browser, Node.js, Electron, and product backends.
- Provider authoring and HTTP Provider Protocol helpers.
- CLI for project, run, event, confirmation, evidence, and model workflows.
- SQLite local process and Docker Compose/PostgreSQL deployment profiles.
Waggle Desktop or CLI is the user-facing workbench.
This mode is appropriate for local projects, governed workspace changes, shell commands, and open-ended tasks. Waggle may ask the user to approve a command, file change, or network action. Approval resumes the same ToolCall; denial records a governed failure without executing it.
Waggle runs behind an existing product UI and backend.
The product exposes a small capability surface and keeps domain ownership. Waggle returns messages, progress, proposals, confirmations, artifacts, and evidence. The product renders business language and performs final business writes.
| Concern | Direct Mode | Product-integrated Mode |
|---|---|---|
| User-facing surface | Waggle CLI/Desktop | Product UI |
| Confirmation owner | Waggle client | Product |
| Typical confirmation | Allow this command or patch? | Apply this business change? |
| Final write | Governed workspace/tool | Product Backend |
| Model configuration | Local config, Connection, or run request | Package/profile default or run-scoped request |
- A client creates or resolves a
Project. - The client creates an
AgentRun, optionally inside an existing Session. - Waggle resolves the AgentPackage, agent, model, Product Provider capabilities, Workspace view, and actor context.
- Waggle compiles and persists the
RunPermissionBoundary. - The runtime starts the agent loop through the selected adapter.
- Model calls pass through the Model Gateway; tool calls pass through the Tool Proxy; workspace operations pass through the Workspace Guard.
- Waggle emits ordered public events and records permission, tool, confirmation, artifact, trace, and audit evidence.
- The Run succeeds, fails, is cancelled, expires, or waits for confirmation.
- A product may commit a confirmed business effect and attach that outcome to the Run evidence.
The client displays and controls the run. It does not implement a second tool loop or become the run authority.
- Node.js
>=24 - Corepack and pnpm
11.1.2 - Docker Desktop or Docker Engine with Compose for the PostgreSQL deployment
- An LLM provider credential for a real model-backed Run
From the repository root:
corepack enable
corepack prepare pnpm@11.1.2 --activate
corepack pnpm install --frozen-lockfile
corepack pnpm build:ts
node scripts/start.mjs \
--environment development \
--profile desktop-local \
--database sqlite \
--host 127.0.0.1 \
--port 8787Verify it in another terminal:
curl http://127.0.0.1:8787/waggle/v1/health
curl http://127.0.0.1:8787/waggle/v1/doctor
curl http://127.0.0.1:8787/waggle/v1/compatibilityBuild a fresh development package, then deploy that exact package:
corepack pnpm package:dev
cd dist/packages/waggle-0.7.0-development
node scripts/deploy.mjs \
--environment development \
--target compose \
--profile developer-lite \
--database postgres \
--applyThis is the recommended server-like local path. Building the package first ensures the image contains the current source rather than an older unpacked artifact.
Full instructions: Build, Deploy, and Operate Waggle.
With the Control Plane running, configure a credential reference:
export ZAI_API_KEY="your-key"
node apps/cli/dist/index.js connect zai \
--env ZAI_API_KEY \
--base-url https://open.bigmodel.cn/api/coding/paas/v4Create or open a Project:
node apps/cli/dist/index.js project open . \
--template desktop-default \
--server http://127.0.0.1:8787Run a real task:
node apps/cli/dist/index.js run \
"Inspect this project and summarize its purpose." \
--package waggle.default-assistant \
--server http://127.0.0.1:8787 \
--trace \
--permissionThe same lifecycle is available through direct HTTP:
POST /waggle/v1/projects
POST /waggle/v1/projects/:projectId/runs
POST /waggle/v1/runs/:runId/execute
GET /waggle/v1/runs/:runId/events:stream
GET /waggle/v1/runs/:runId/governed-evidence
See Task Execution by CLI or HTTP for complete curl and PowerShell examples.
Never commit a raw provider key. Use environment references, local auth, an external secret manager, a Model Connection, or run-scoped inline_api_key with persist=false.
Install the public SDK:
pnpm add @crewbeelab/waggle-sdkCreate an interactive client:
import{createWaggleInteractiveClient}from"@crewbeelab/waggle-sdk/interactive";constwaggle=createWaggleInteractiveClient({apiBaseUrl: process.env.WAGGLE_URL??"http://127.0.0.1:8787",auth: {type: "none"}});constproject=awaitwaggle.resolveProject({displayName: "Product workspace",templateId: "product-provider-default"});construn=awaitwaggle.createRun({projectId: project.projectId,agentPackageId: "product.todo-manager",actorRef: "user:123",input: {task: "Organize this week's tasks"},idempotencyKey: "message:123"});forawait(conststateofwaggle.watchRun(run.runId)){renderProductState(state);}A complete product integration normally adds:
- A focused AgentPackage.
- A Product Provider with named tools, context, callbacks, and confirmation descriptions.
- Provider contract tests.
- Project mapping and idempotency keys.
- Product-owned confirmation and deterministic final writes.
- Public event, artifact, and evidence rendering.
Start with the Waggle Integration Manual.
| Profile | Runtime | Storage | Intended use |
|---|---|---|---|
| Desktop Local | Local Node process | SQLite | Fast local development and desktop sidecar use |
| Advanced Local | Docker Compose | PostgreSQL | Private/local server-like deployment and integration verification |
| Server Single Node | Docker Compose | PostgreSQL | Dedicated VM/server deployment |
The Control Plane listens on port 8787 by default. PostgreSQL uses 5432 by default in Compose deployments.
Kubernetes, multi-node high availability, and a hosted Waggle cloud service are not current default deployment claims.
Waggle currently delivers the Project-first governed run baseline: real PI-backed runs, model and provider selection, governed tools/workspaces, confirmations, HTTP/SSE observation, SQLite/PostgreSQL persistence, artifacts, evidence, CLI/SDK integration, package validation, and single-node deployment.
The following remain active maturity work, not finished product claims:
- Full model-context reconstruction and continuation after a Control Plane process crash.
- Production multi-worker scheduling, authenticated remote runners, and high availability.
- Complete callback/outbox delivery guarantees across failures and deployments.
- Stronger secret-store integrations, model quota/cost accounting, and provider health policy.
- Container/process sandbox lifecycle beyond the current governed workspace boundary.
- Broader runtime adapter support beyond PI Core and the mock/debug paths.
- Kubernetes/Helm deployment and enterprise multi-tenant administration.
Longer-term direction includes durable long-running agent control, parent/child run orchestration with equal-or-narrower boundaries, richer memory/context governance, a broader AgentPackage ecosystem, and additional runtime adapters.
The current executable truth is maintained in Current Implementation.
apps/
cli/ HTTP-first CLI and local sidecar workflows
control-plane/ Fastify Control Plane API
dev-console/ Developer inspection surface
runner/ Runner/worker execution boundary
packages/
protocol/ Canonical public contracts and schemas
core/ Governance, lifecycle, storage, tools, evidence
runtime-pi/ PI runtime adapter and model catalog bridge
config/ Product-agnostic policy and registry samples
docs/
user-guides/ Build, deployment, task, and model guides
package/ Packaged operator and product integration docs
development/ Architecture, contracts, implementation, testing
examples/ AgentPackage and Product Provider examples
scripts/ Build, package, deploy, diagnostics, acceptance
test/ Unit, contract, integration, and runloop tests
Product-specific business code and AgentPackages belong in product repositories. Waggle core stays product-agnostic.
Common checks:
corepack pnpm diagnostics
corepack pnpm test
corepack pnpm typecheck
corepack pnpm build
corepack pnpm checkcorepack pnpm check is the full repository gate. Public protocol changes must also pass SDK contract-drift verification.
The CI baseline covers TypeScript build, diagnostics, tests, a complex tool Run E2E, typecheck, package build, contract tests, SQLite/PostgreSQL deployment smoke, and optional live model smoke when a provider key is available.
Waggle is built with appreciation for PI and the broader open-source agent ecosystem.
PI Core is Waggle's current production execution substrate. Waggle works from a different layer: it owns the Project, Run, permission, tool, workspace, event, confirmation, and evidence semantics that let software products use an agent runtime without surrendering product control.