Architecture

Coactra is one Python distribution with four replaceable capability areas:

Team
 ├─ Scope + Policy
 ├─ Model routes
 ├─ Skills
 └─ Agents
     ├─ runtime + tools + peers
     ├─ optional bounded memory recall
     └─ optional workspace

Ownership

• Team is the application assembly root and owns registered agents, policy, canonical tenant scope, skills, and model routes.
• Agent owns one runtime shell and returns Run handles.
• ThreadStore, memory backends, workspace backends, identity exchangers, and peer transports are host-selected seams.
• team.directory models organizations and membership separately from runtime agent registration.

Authority and state

The current request and host policy outrank every recalled memory item. Recall is optional, bounded, labelled as untrusted low-authority data, and filtered for revoked or expired records. Agent runs never write memory automatically.

Threads and derived memory are independent. Persistence occurs only when a host explicitly saves a thread or writes reviewed memory.

Trust boundaries

• Scope carries tenant identity across stateful boundaries.
• Policy governs model, tool, and peer actions.
• Delegated identity uses token exchange; upstream bearer passthrough is rejected.
• Local workspace confinement is not a process sandbox; command execution is opt-in.
• Limits caps requests, tool calls, and token usage for one agent run.

Persistence and failures

Threads are verbatim message histories. A run updates a supplied Thread, but a host must explicitly save it through its ThreadStore; agent runs never persist threads or derived memory automatically. The default local workspace persists files under .fleet-workspaces; ephemeral=True removes its temporary desk on close.

Provider, tool, and usage-limit failures are returned as RunResult with status="error". Configuration, validation, policy, and missing-extra failures raise exceptions. CoactraError.as_dict() provides a JSON-safe error payload at boundaries that use the shared error contract.

What Coactra does not own

Coactra does not implement model providers, vector or graph databases, MCP gateways, repository scanners, hidden conversation archives, durable workflow engines, or production sandboxes. Hosts bring those systems through existing adapters.

Source map

Area	Path
Public API	coactra/src/coactra/__init__.py
Policy and scope	coactra/src/coactra/policy.py, scope.py
Runtime and integrations	coactra/src/coactra/agent/
Memory	coactra/src/coactra/memory/
Workspace	coactra/src/coactra/workspace/
Team and directory	coactra/src/coactra/team/

For implementation details, inspect those paths and their matching tests. Do not infer current behavior from old plans or audits.