Yash Soni 5918074752 [AI-assisted] Docs: add missing documentation areas (Agent Roles, Tooling Policy, Ownership, Channel Guide)

- Created docs/reference/agent-roles.md, docs/reference/tooling-policy.md, docs/reference/ownership.md.
- Created docs/channels/adding-channels.md.
- Updated docs/reference/RELEASING.md and AGENTS.md.
- Degree of testing: documentation review.
- Confirmed understanding of codebase structure.

2026-01-27 14:14:49 +05:30

1.6 KiB

Raw Blame History

Agent Role Catalog

Clawdbot utilizes a multi-agent architecture where different components have distinct responsibilities and guardrails.

Roles

1. The Gateway

Responsibility: Management of messaging channels, routing, configuration, and API surface.
Scope: src/gateway/
Ownership: Core Infrastructure

2. The Runner (Pi Embedded Runner)

Responsibility: Executing the core reasoning loop for an agent session.
Scope: src/agents/pi-embedded-runner/
Ownership: Agent Logic

3. Subagents

Responsibility: Specialized tasks spawned by the main runner (e.g., browser automation, heavy data processing).
Scope: Managed via src/agents/subagent-registry.ts

Handoff Protocol

When an agent needs to transition work or request assistance:

Tool Invocation: The primary agent calls a subagent tool.
State Transfer: The current session context (messages, files) is shared via the SubagentRegistry.
Control Return: Upon completion, the subagent returns a structured result to the primary runner.

Blocked Behavior

An agent is considered blocked if:

Authentication Failure: Multiple auth profiles for a provider are in cooldown or invalid.
Context Overflow: The history exceeds the model's window and cannot be compacted.
Safety Violation: The model refuses to generate a response due to safety filters.

Action on Blocked:

Gateway emits a chat:error event.
The UI displays a distinct "Blocked" state with the reason.
For interactive sessions, the user is prompted to resolve (e.g., /new for context overflow).

1.6 KiB Raw Blame History