Specification: Org Chart & Agents

Overview

Agents live in a company-scoped strict reporting tree. Each agent carries adapter/runtime configuration, a status state machine, a monthly budget, and one or more hashed API keys. Hiring may go through a board approval. Built-in adapters cover process, http, local CLI tools (claude/codex/gemini/opencode/pi/cursor), and the OpenClaw gateway; external adapters load via the plugin flow.

Architecture

BoardThe human operator(s) with full control across all companies in a deployment. In `local_trusted` mode this is implicit; in authenticated mode it is session-based. ──► /api/agents (CRUD, pause/resume/terminate, keys)
AgentAn AI employee registered in the org tree with a role, title, reporting line, budget, and adapter configuration.  ──► /api/agents/:id/heartbeat/invoke  (via API key)
              │
              ▼
         agents table (company_id, reports_to, status, adapter_config, budget)
              │
              ▼
         agent_api_keys (hashed) + approvals(hire_agent)

Data Models

agents

agent_api_keys

API Contracts

POST /companies/:companyId/agents, GET /agents/:agentId, PATCH /agents/:agentId

AgentAn AI employee registered in the org tree with a role, title, reporting line, budget, and adapter configuration. CRUD.

POST /agents/:agentId/pause | /resume | /terminate

Lifecycle transitions (terminate board-only).

POST /agents/:agentId/keys, POST /agents/:agentId/heartbeat/invoke

Key management and heartbeat invocation.

Error Responses

Sequences

Hire via approval

AgentAn AI employee registered in the org tree with a role, title, reporting line, budget, and adapter configuration. → approvals(hire_agent, pending) → BoardThe human operator(s) with full control across all companies in a deployment. In `local_trusted` mode this is implicit; in authenticated mode it is session-based. approve → create agent row + optional key → activity_log

Technical Decisions

Risks and Unknowns

1. Graceful-cancel-then-force-kill semantics during pause of an active run need careful adapter coordination.

Out of Scope

• Multi-board governance or role-based human permission granularity.

Vocabulary

Domain Terms

Technical Terms

Acronyms and Abbreviations

Specification: TaskUsed interchangeably with "issue" in agent/operator contexts (the task system is the issues table). System (Issues)

Overview

Issues are company-scoped tasks with a strict status state machine, single-assignee ownership, and atomic checkout. Rich collaboration (comments, documents, work products, attachments, labels, blockers, thread interactions) is layered on top. Execution locks and checkout/execution-run fields prevent double-work. A non-terminal liveness rule keeps work from silently stalling.

Architecture

AgentAn AI employee registered in the org tree with a role, title, reporting line, budget, and adapter configuration./BoardThe human operator(s) with full control across all companies in a deployment. In `local_trusted` mode this is implicit; in authenticated mode it is session-based. ──► /api/issues (CRUD, checkout, release, force-release)
                    │
                    ▼
               issues (status, assignee, checkout/execution locks, parent_id, goal_id)
                    ├── issue_comments
                    ├── issue_documents ← documents / document_revisions
                    ├── issue_attachments ← assets
                    ├── issue_work_products
                    ├── issue_relations (blockers)
                    ├── issue_thread_interactions / issue_approvals
                    └── activity_log (every mutation)

Data Models

issues (core fields)

API Contracts

POST /issues/:issueId/checkout

Atomic checkout. Request: { agentId, expectedStatuses }. Single guarded SQL update; 409 on conflict.

POST /issues/:issueId/release | /issues/:issueId/admin/force-release

Release locks; force-release is board-only and writes issue.admin_force_release activity.

Documents, comments, attachments

GET/PUT /issues/:issueId/documents/:key (+lock/unlock/revisions), POST/GET /issues/:issueId/comments, POST /companies/:companyId/issues/:issueId/attachments, GET /attachments/:attachmentId/content, DELETE /attachments/:attachmentId.

Error Responses

Sequences

Atomic checkout

AgentAn AI employee registered in the org tree with a role, title, reporting line, budget, and adapter configuration. → checkout(expectedStatuses) → UPDATE issues SET status=in_progress, assignee, locks WHERE id AND status IN(?) AND (assignee IS NULL OR assignee=agent) → rowcount 0 ? 409 : ok

Technical Decisions

Risks and Unknowns

1. Non-terminal liveness enforcement touches scheduler, watchdogs, and recovery actions; semantics are detailed in doc/execution-semantics.md.

Out of Scope

• ProjectA company-scoped grouping that may link to a goal and carry lead agent, target date, and secret-aware env./issue-level privacy ACLs (Pro/Enterprise).

Vocabulary

Domain Terms

Technical Terms

Acronyms and Abbreviations

Specification: HeartbeatA scheduled or triggered wakeup that invokes an agent's adapter to do work. Execution & Adapters

Overview

A lightweight in-process scheduler wakes agents; the heartbeat execution service resolves workspace, injects secrets, loads skills, and invokes the agent's adapter. Adapters implement a common interface (invoke, status, cancel). Built-ins cover process, http, local CLI, and the OpenClaw gateway; external adapters are loaded as plugins with zero hardcoded core imports.

Architecture

Scheduler ──► heartbeat service ──► adapter.invoke(agent, context)
   (skip rules)     (workspace, secrets, skills)        │
                                                       ├─ process: spawn, stream, SIGTERM/SIGKILL
                                                       ├─ http: outbound req, callback
                                                       ├─ local CLI: claude/codex/gemini/opencode/pi/cursor
                                                       ├─ openclaw gateway
                                                       └─ external plugin
                  heartbeat_runs (status, context_snapshot) + heartbeat_run_events

Data Models

heartbeat_runs

Supporting tables: heartbeat_run_events, heartbeat_run_watchdog_decisions, agent_wakeup_requests, agent_runtime_state, agent_task_sessions.

API Contracts

POST /agents/:agentId/heartbeat/invoke

Triggers a heartbeat run (manual source). Returns the run record.

AdapterTranslates a heartbeat into a concrete runtime invocation (process, HTTP, CLI session, gateway, or external plugin). interface

interface AgentAdapter {
  invoke(agent: AgentAn AI employee registered in the org tree with a role, title, reporting line, budget, and adapter configuration., context: InvocationContext): Promise<InvokeResult>;
  status(run: HeartbeatRun): Promise<RunStatus>;
  cancel(run: HeartbeatRun): Promise<void>;
}

Error Responses

Sequences

Scheduled heartbeat

Scheduler tick → skip rules check → heartbeat service → adapter.invoke → run status + events + cost events → activity_log

Technical Decisions

Risks and Unknowns

1. Cheap-model profile lane must be tightly constrained to status-only recovery to avoid deliverable work on a low-cost model.

Out of Scope

• Cloud-grade orchestration or external queue infrastructure.

Vocabulary

Domain Terms

Technical Terms

Acronyms and Abbreviations

Specification: Governance & Approvals

Overview

Governance is enforced through the approvals table, execution policies, budget hard-stops, board override authority, and the scoped task-watchdog contract. BoardThe human operator(s) with full control across all companies in a deployment. In `local_trusted` mode this is implicit; in authenticated mode it is session-based. approvals are transactional (no lost decisions). Watchdogs are a narrow, persisted-configuration-derived capacity confined to one watched issue subtree.

Architecture

BoardThe human operator(s) with full control across all companies in a deployment. In `local_trusted` mode this is implicit; in authenticated mode it is session-based. ──► /api/approvals (approve/reject/cancel)
AgentAn AI employee registered in the org tree with a role, title, reporting line, budget, and adapter configuration.  ──► approvals(hire_agent | approve_ceo_strategy | request_board_approval)
              │
              ▼
         approvals table → activity_log
Watchdog ──► scoped mutations within watched subtree (comments, child issues, status,
             blockers, eligible request_confirmation) → activity (watchdog metadata)

Data Models

approvals

Supporting tables: approval_comments, issue_approvals, issue_execution_decisions, issue_watchdogs, heartbeat_run_watchdog_decisions, issue_recovery_actions.

API Contracts

GET/POST /companies/:companyId/approvals, POST /approvals/:approvalId/approve | /reject

ApprovalA governance request (`hire_agent`, `approve_ceo_strategy`, budget override, `request_board_approval`) the board approves/rejects. listing, creation, and decisions.

Error Responses

Sequences

Hire approval

AgentAn AI employee registered in the org tree with a role, title, reporting line, budget, and adapter configuration. → approvals(hire_agent, pending) → BoardThe human operator(s) with full control across all companies in a deployment. In `local_trusted` mode this is implicit; in authenticated mode it is session-based. approve (transactional) → create agent + optional key → activity_log

Technical Decisions

Risks and Unknowns

1. Ensuring watchdog capability discovery comes only from wake metadata/denials (no probe issues) requires careful server enforcement and tests.

Out of Scope

• Multi-board governance or RBAC granularity for humans.

Vocabulary

Domain Terms

Technical Terms

Acronyms and Abbreviations

Specification: Budget & Cost Control

Overview

Cost events are the atomic input; all spend figures are aggregations. Budgets are monthly UTC windows scoped to company and agent (project optional). Enforcement runs in the heartbeat scheduler/checkout path: at the hard limit the agent is paused and invocations are blocked. A soft threshold warns at 80%.

Architecture

AgentAn AI employee registered in the org tree with a role, title, reporting line, budget, and adapter configuration. → POST /cost-events → cost_events (validated) → rollups (read-time aggregation)
Scheduler/checkout → budget check → hard limit? → pause agent + block + activity
BoardThe human operator(s) with full control across all companies in a deployment. In `local_trusted` mode this is implicit; in authenticated mode it is session-based. → PATCH /budgets, resume → override

Data Models

cost_events

Supporting tables: budget_policies, budget_incidents, finance_events.

API Contracts

POST /companies/:companyId/cost-events

Ingest a cost event with ownership checks and validation.

GET /companies/:companyId/costs/summary | /by-agent | /by-project

Read-time aggregate rollups.

PATCH /companies/:companyId/budgets | PATCH /agents/:agentId/budgets

Set company/agent budgets.

Error Responses

Sequences

Hard-stop auto-pause

cost event ingest → spend crosses 100% → agent.status=paused → block checkout/invocation → high-priority activity

Technical Decisions

Risks and Unknowns

1. Concurrent cost ingestion near the threshold must not double-spend or miss the pause.

Out of Scope

• Revenue/expense accounting beyond model/token costs.

Vocabulary

Domain Terms

Technical Terms

Acronyms and Abbreviations

Specification: Routines & Schedules

Overview

Routines are recurring definitions stored with their triggers, env, and revision history. A trigger fires a routine run that materializes an issue (with routine-scoped env overlay) and wakes the assigned agent. Routines are first-class company-scoped entities.

Architecture

Trigger (cron/webhook/API) → routine run → create issue (routine env overlay) → wake assigned agent
                                  │
                                  └─► routine_runs + activity_log
routine_revisions (snapshotted env) ← routine_triggers ← routines (company-scoped)

Data Models

routines / routine_revisions / routine_triggers / routine_runs

API Contracts

/api/routines (CRUD + triggers)

RoutineA recurring task definition with cron/webhook/API triggers; each execution creates a tracked issue and wakes the assigned agent. management and trigger configuration. Route handler: server/src/routes/routines.ts, service: server/src/services/routines.ts.

Sequences

RoutineA recurring task definition with cron/webhook/API triggers; each execution creates a tracked issue and wakes the assigned agent. execution

trigger fires → routine run → issue created (routine env overlay after project env, before runtime keys) → wake agent → routine_runs + activity_log

Technical Decisions

Risks and Unknowns

1. Overlapping executions and catch-up behavior need precise documented semantics.

Out of Scope

• External calendar/scheduling integrations beyond cron/webhook/API.

Vocabulary

Domain Terms

Technical Terms

Acronyms and Abbreviations

Specification: Workspaces & Runtime

Overview

Workspaces split into project workspaces (shared project state) and execution workspaces (isolated git worktrees per run). Runtime services run dev servers/preview URLs; environments bind secret-aware env to execution targets via leases. WorkspaceEither a project workspace or an isolated execution workspace (git worktree) where an agent runs. operations expose commands, diffs, and uploads to agents under authorization.

Architecture

IssueThe core task entity. Carries company/project/goal/parent links, single assignee, atomic checkout locks, comments, documents, work products, and attachments. (execution_workspace_*) ──► execution_workspaces (git worktree)
                                          │
ProjectA company-scoped grouping that may link to a goal and carry lead agent, target date, and secret-aware env. workspace ──────────► project_workspaces
Environments (secret-aware env) ──► environment_leases ──► execution target
Runtime services ──► workspace_runtime_services (dev servers, preview URLs)
WorkspaceEither a project workspace or an isolated execution workspace (git worktree) where an agent runs. operations ──► commands, diffs, uploads (authz-gated)

Data Models

execution_workspaces / project_workspaces / workspace_runtime_services / workspace_operations / environments / environment_leases

API Contracts

/api/execution-workspaces, environment-selection, environments, workspace-command-authz, workspace-runtime-service-authz

WorkspaceEither a project workspace or an isolated execution workspace (git worktree) where an agent runs./runtime management and authorization. Routes under server/src/routes/, services under server/src/services/execution-workspaces.ts, environments.ts, etc.

Error Responses

Sequences

Execution workspace checkout

checkout → resolve execution_workspace (preference/settings) → create/reuse worktree (base origin/master) → run agent → operations/diffs/uploads (authz)

Technical Decisions

Risks and Unknowns

1. Sandbox provider lease reuse (e.g. Daytona) and large-upload reliability need careful handling.

Out of Scope

• Cloud sandbox marketplaces beyond supported providers.

Vocabulary

Domain Terms

Technical Terms

Acronyms and Abbreviations

Specification: PluginInstance-wide out-of-process extension with capability-gated host services, jobs, tools, and UI contributions. System

Overview

Plugins are out-of-process workers registered instance-wide. A capability-gated host exposes services (tools, jobs, webhooks, UI contributions, database namespaces) to plugins. The adapter plugin loader is the dynamic-loading path for external adapters and external adapter plugins. An SDK and scaffolder (create-paperclip-plugin) support authoring.

Architecture

Operator ──► /api/plugins (install/config/state)
                │
                ▼
           plugins table + plugin_config/state/entities/jobs/logs/webhooks
                │
                ▼
           plugin-loader (dynamic) ──► external adapters (zero hardcoded imports)
Host services (capability-gated) ◄── plugin worker ──► plugin_database namespaces/migrations
SDK (packages/plugins/sdk) + create-paperclip-plugin scaffolder

Data Models

plugins and plugin support tables

API Contracts

/api/plugins, /api/plugin-ui-static

PluginInstance-wide out-of-process extension with capability-gated host services, jobs, tools, and UI contributions. installation, configuration, state, jobs, logs, webhooks, and UI static assets. Route: server/src/routes/plugins.ts.

Adapter pluginAn external adapter loaded dynamically via `~/.paperclip/adapter-plugins.json` (no hardcoded core imports). loading

External adapters via ~/.paperclip/adapter-plugins.json; createServerAdapter() includes all optional fields. Loader: server/src/adapters/plugin-loader.ts, store: server/src/services/adapter-plugin-store.ts.

Sequences

External adapter install

operator → AdapterTranslates a heartbeat into a concrete runtime invocation (process, HTTP, CLI session, gateway, or external plugin). manager → adapter-plugins.json entry → plugin-loader dynamic load → createServerAdapter (all fields) → adapter registered

Technical Decisions

Risks and Unknowns

1. Built-in UI parsers can shadow external plugin parsers; removing built-ins when externalized needs coordination.

Out of Scope

• Cloud-grade plugin marketplace and packaged public distribution.

Vocabulary

Domain Terms

Technical Terms

Acronyms and Abbreviations

Specification: Secrets Management

Overview

Secrets are company-scoped, versioned, and provider-backed. A pluggable provider architecture (local encrypted, AWS Secrets Manager, GCP, Vault) stores the material. Bindings attach secrets to agents/projects/routines via config paths. Inline secret references in JSON configs are resolved at runtime. Every access is audited via secret_access_events.

Architecture

User → /api/secrets (CRUD + versions + bindings)
           │
           ▼
      company_secrets (name, key, provider, status)
           │
           ├── company_secret_versions (SHA256 fingerprint)
           ├── company_secret_bindings (target: agent/project, config path)
           ├── company_secret_provider_configs (vault config)
           └── secret_access_events (audit)
           │
           ▼
      Provider layer: local-encrypted | aws-secrets-manager | gcp | vault
           │
           ▼
      Runtime resolution: inline ${{ secrets.ref }} → resolved value → env injection

Data Models

company_secrets

company_secret_versions

company_secret_bindings

API Contracts

POST /companies/:companyId/secrets

Request: { name, key, provider, value }

Response (201): { id, name, key, provider, status, version } — value NOT returned.

GET/PATCH/DELETE /companies/:companyId/secrets/:secretId

Standard CRUD. GET never returns value.

POST /companies/:companyId/secrets/:secretId/versions

Create new version of existing secret.

GET /companies/:companyId/secrets/:secretId/bindings, POST /companies/:companyId/secrets/bindings

Binding management.

GET /companies/:companyId/secrets/access-events

Audit log of secret accesses.

Error Responses

Sequences

Secret creation and binding

BoardThe human operator(s) with full control across all companies in a deployment. In `local_trusted` mode this is implicit; in authenticated mode it is session-based. → POST /secrets (value) → store in provider vault → return metadata (no value)
BoardThe human operator(s) with full control across all companies in a deployment. In `local_trusted` mode this is implicit; in authenticated mode it is session-based. → POST /bindings (secretKey, targetType, targetId, configPath) → binding row
AgentAn AI employee registered in the org tree with a role, title, reporting line, budget, and adapter configuration. → runtime resolution → resolve bindings + inline refs → fetch from provider → env injection → ${{ secrets.ref }} replaced

Technical Decisions

Risks and Unknowns

1. Vault provider may not be available in all deployment modes; fallback behavior must be graceful.
2. Inline secret referenceThe `${{ secrets.key }}` syntax used in JSONB configs to reference a secret that is resolved at runtime. resolution ordering in nested env overlays (project env → routine env → runtime keys) needs clear documentation.

Out of Scope

• Automatic secret rotation or expiry notification.
• Cross-company secret sharing.

Vocabulary

Domain Terms

Technical Terms