ACP Primitives

ACP primitives are the operations agents use to coordinate. They’re exposed through the waggle compound tool — one tool that batches multiple operations.

The waggle tool

Agents see a single tool called waggle. It accepts a dance array of operations and an optional wait directive:

{
  "dance": [
    { "do": "read_file", "path": "src/api.ts" },
    { "do": "publish", "type": "review.started" },
    { "do": "set_state", "key": "status", "value": "reviewing" }
  ],
  "wait": "review.complete"
}

One tool call, three operations, then sleep until review.complete. Zero coordination tokens.

Environment operations (13)

File, shell, git, and web tools provided by propolis.

File operations

Operation	Parameters	Description
read_file	path	Read file contents
write_file	path, content	Write file (create or overwrite)
patch_file	path, patches	Apply patches (search/replace)
list_files	path	List directory contents
glob	pattern, path?	Find files by pattern
grep	pattern, path?, glob?	Search file contents

Shell operations

Operation	Parameters	Description
shell	command, args?, cwd?	Execute a shell command

Git operations

Operation	Parameters	Description
git_status	—	Show working tree status
git_diff	staged?	Show changes
git_commit	message, files?	Create a commit
git_log	count?	Show recent commits

Web operations

Operation	Parameters	Description
fetch	url, method?, headers?, body?	HTTP request
scrape	url	Fetch and extract page content

ACP operations (5)

Coordination primitives — the core of multi-agent communication.

publish

Publish an event to all subscribed agents.

{ "do": "publish", "type": "task.complete", "data": { "task": "auth-module" } }

Events are the primary communication channel. Agents subscribe to event types and wake when matching events arrive.

claim

Atomically claim a resource (mutex lock).

{ "do": "claim", "resource": "file:src/api.ts" }

If the resource is already claimed by another agent, the claim fails. Claims auto-release if the agent’s heartbeat times out.

release

Release a previously claimed resource.

{ "do": "release", "resource": "file:src/api.ts" }

get_state

Read from the shared key-value store.

{ "do": "get_state", "key": "current_phase" }

Omit key to get all state.

set_state

Write to the shared key-value store.

{ "do": "set_state", "key": "current_phase", "value": "review" }

State changes trigger events — other agents are notified automatically.

Wait directive

After executing dance operations, agents can sleep until a condition is met:

Wait value	Behavior
true	Sleep until any event arrives
"event.type"	Sleep until a specific event type
["type.a", "type.b"]	Sleep until any of these types
5000	Sleep for 5 seconds
{ types: ["type.a"], timeout: 30000 }	Sleep for specific event with timeout

{
  "dance": [{ "do": "publish", "type": "review.submitted" }],
  "wait": { "types": ["revision.complete"], "timeout": 300000 }
}

The agent’s process sleeps. No tokens consumed. When the matching event arrives (or timeout expires), the agent wakes and the LLM continues.

Mapping to CLI commands

Every primitive maps to a wgl command:

Primitive	CLI Command
publish	wgl events publish --type task.complete --data '{}'
claim	wgl claim file:src/api.ts
release	wgl release file:src/api.ts
get_state	wgl state get current_phase
set_state	wgl state set current_phase review
Event subscription	wgl events tail --type task.*