# Waggle — Governed AI Agent Harness & Agent Control Plane

[English](README.md) | [简体中文](README.zh-CN.md)

<p align="center">
  <img src="./WaggleIcon.png" alt="Waggle" width="180" />
</p>

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.<br />
Not a model gateway.<br />
Not a workflow DAG engine.<br />
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`](https://www.npmjs.com/package/@crewbeelab/waggle-sdk).

---

## Why Waggle

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.

### The control boundary

```mermaid
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.

---

## Quick Links

- [Documentation index](docs/README.md)
- [Build, deploy, and operate](docs/user-guides/build-deploy-operate.md)
- [Run tasks through CLI or HTTP](docs/user-guides/task-execution.md)
- [Configure providers, models, and credentials](docs/user-guides/model-configuration.md)
- [Integrate a product with the Waggle SDK](docs/package/waggle-integration-manual.md)
- [Control Plane API contract](docs/development/api-contract.md)
- [Architecture](docs/development/architecture.md)
- [Current implementation and known gaps](docs/development/current-implementation.md)
- [Testing strategy](docs/development/testing-strategy.md)

For Chinese operator documentation, start with [PACKAGE-QUICKSTART.zh-CN.md](PACKAGE-QUICKSTART.zh-CN.md) or the Chinese guides under `docs/`.

---

## Table of Contents

- [What Waggle Is](#what-waggle-is)
- [What Waggle Solves](#what-waggle-solves)
- [Core Concepts](#core-concepts)
- [Core Features](#core-features)
- [Two Integration Modes](#two-integration-modes)
- [How a Run Works](#how-a-run-works)
- [Get Started](#get-started)
- [Run Your First Task](#run-your-first-task)
- [Integrate a Product](#integrate-a-product)
- [Deployment Profiles](#deployment-profiles)
- [Current Scope and Roadmap](#current-scope-and-roadmap)
- [Repository Map](#repository-map)
- [Development](#development)
- [Acknowledgements](#acknowledgements)

---

## What Waggle Is

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:

```text
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.

---

## What Waggle Solves

### 1. Product capabilities need a safer shape than raw APIs

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.

### 2. A tool list is not an execution boundary

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.

### 3. Agent work must outlive one UI request

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.

### 4. High-impact actions need product semantics

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.

### 5. Model choice and credentials need their own boundary

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.

---

## Core Concepts

| 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:

```text
Product owns business.
Waggle owns governance.
Runtime owns mechanics.
```

---

## Core Features

### 1. Project-first run lifecycle

- 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.

### 2. AgentPackage registry and policy

- 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.

### 3. Governed tools and workspaces

- 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.

### 4. Provider and model configuration

- 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.

### 5. Observable and reviewable runs

- 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.

### 6. Product and client integration

- 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.

---

## Two Integration Modes

### Direct Mode

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.

### Product-integrated Mode

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 |

---

## How a Run Works

1. A client creates or resolves a `Project`.
2. The client creates an `AgentRun`, optionally inside an existing Session.
3. Waggle resolves the AgentPackage, agent, model, Product Provider capabilities, Workspace view, and actor context.
4. Waggle compiles and persists the `RunPermissionBoundary`.
5. The runtime starts the agent loop through the selected adapter.
6. Model calls pass through the Model Gateway; tool calls pass through the Tool Proxy; workspace operations pass through the Workspace Guard.
7. Waggle emits ordered public events and records permission, tool, confirmation, artifact, trace, and audit evidence.
8. The Run succeeds, fails, is cancelled, expires, or waits for confirmation.
9. 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.

---

## Get Started

### Requirements

- 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

### Fast local Control Plane with SQLite

From the repository root:

```bash
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 8787
```

Verify it in another terminal:

```bash
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/compatibility
```

### Complete local deployment with PostgreSQL

Build a fresh development package, then deploy that exact package:

```bash
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 \
  --apply
```

This 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](docs/user-guides/build-deploy-operate.md).

---

## Run Your First Task

With the Control Plane running, configure a credential reference:

```bash
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/v4
```

Create or open a Project:

```bash
node apps/cli/dist/index.js project open . \
  --template desktop-default \
  --server http://127.0.0.1:8787
```

Run a real task:

```bash
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 \
  --permission
```

The same lifecycle is available through direct HTTP:

```text
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](docs/user-guides/task-execution.md) 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`.

---

## Integrate a Product

Install the public SDK:

```bash
pnpm add @crewbeelab/waggle-sdk
```

Create an interactive client:

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

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

const project = await waggle.resolveProject({
  displayName: "Product workspace",
  templateId: "product-provider-default"
});

const run = await waggle.createRun({
  projectId: project.projectId,
  agentPackageId: "product.todo-manager",
  actorRef: "user:123",
  input: { task: "Organize this week's tasks" },
  idempotencyKey: "message:123"
});

for await (const state of waggle.watchRun(run.runId)) {
  renderProductState(state);
}
```

A complete product integration normally adds:

1. A focused AgentPackage.
2. A Product Provider with named tools, context, callbacks, and confirmation descriptions.
3. Provider contract tests.
4. Project mapping and idempotency keys.
5. Product-owned confirmation and deterministic final writes.
6. Public event, artifact, and evidence rendering.

Start with the [Waggle Integration Manual](docs/package/waggle-integration-manual.md).

---

## Deployment Profiles

| 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.

---

## Current Scope and Roadmap

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](docs/development/current-implementation.md).

---

## Repository Map

```text
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.

---

## Development

Common checks:

```bash
corepack pnpm diagnostics
corepack pnpm test
corepack pnpm typecheck
corepack pnpm build
corepack pnpm check
```

`corepack 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.

---

## Acknowledgements

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.