forked from farhoodlabs/paperclip
Dotta
7a9b3a6037
## Thinking Path > - Paperclip orchestrates AI agents for zero-human companies > - The control plane must recover stranded agent work without creating new operational loops > - Stranded recovery issues can themselves fail, and exposing raw retry errors in comments can leak sensitive adapter details > - New local companies also should not force a hire-approval gate unless operators enable that policy > - This pull request hardens recovery issue handling, redacts retry failure details in issue copy, preserves `maxConcurrentRuns: 1`, and flips new-hire approval to an opt-in default > - The benefit is safer automatic recovery and smoother default company setup without hidden migration conflicts ## What Changed - Added migration `0071_default_hire_approval_off` and updated company schema/import/export/docs so hire approvals default off and serialize only when enabled. - Added migration `0072_large_sandman` with a partial unique index preventing duplicate active stranded recovery issues for the same source issue. - Blocked failed `stranded_issue_recovery` issues in place instead of creating nested recovery issues. - Redacted latest retry failure details from recovery issue comments while still linking reviewers to run evidence. - Allowed `maxConcurrentRuns: 1` to be honored by heartbeat concurrency normalization. - Added focused regression coverage for recovery recursion, redaction, migration ordering, and concurrency behavior. ## Verification - `pnpm --filter @paperclipai/db run check:migrations` - `pnpm exec vitest run --project @paperclipai/server server/src/__tests__/recovery-classifiers.test.ts` - `pnpm exec vitest run --project @paperclipai/server server/src/__tests__/company-portability.test.ts --pool=forks --poolOptions.forks.isolate=true` - `pnpm exec vitest run --project @paperclipai/server server/src/__tests__/agent-permissions-routes.test.ts --pool=forks --poolOptions.forks.isolate=true` - `pnpm --filter @paperclipai/server typecheck` - `pnpm exec vitest run --project @paperclipai/server server/src/__tests__/heartbeat-process-recovery.test.ts --pool=forks --poolOptions.forks.isolate=true` exits 0, but this host skipped the embedded Postgres tests with the existing init guard. - `pnpm exec vitest run --project @paperclipai/server server/src/__tests__/heartbeat-dependency-scheduling.test.ts --pool=forks --poolOptions.forks.isolate=true` exits 0, but this host skipped the embedded Postgres tests with the existing init guard. ## Risks - Migration risk is low but this PR intentionally owns both new migrations to avoid separate PR migration-journal conflicts. - Recovery comments now require operators to inspect linked run evidence for details instead of reading raw errors inline. - The hire approval default changes behavior for newly created/imported companies only; existing persisted company settings are not changed except by the SQL default for future rows. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - OpenAI Codex, GPT-5 coding agent, tool-enabled terminal/GitHub workflow, reasoning mode active. Context window not exposed in this environment. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] If this change affects the UI, I have included before/after screenshots - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>
87 lines
3.5 KiB
Markdown
87 lines
3.5 KiB
Markdown
---
|
|
title: Core Concepts
|
|
summary: Companies, agents, issues, delegation, heartbeats, and governance
|
|
---
|
|
|
|
Paperclip organizes autonomous AI work around six key concepts.
|
|
|
|
## Company
|
|
|
|
A company is the top-level unit of organization. Each company has:
|
|
|
|
- A **goal** — the reason it exists (e.g. "Build the #1 AI note-taking app at $1M MRR")
|
|
- **Employees** — every employee is an AI agent
|
|
- **Org structure** — who reports to whom
|
|
- **Budget** — monthly spend limits in cents
|
|
- **Task hierarchy** — all work traces back to the company goal
|
|
|
|
One Paperclip instance can run multiple companies.
|
|
|
|
## Agents
|
|
|
|
Every employee is an AI agent. Each agent has:
|
|
|
|
- **Adapter type + config** — how the agent runs (Claude Code, Codex, shell process, HTTP webhook)
|
|
- **Role and reporting** — title, who they report to, who reports to them
|
|
- **Capabilities** — a short description of what the agent does
|
|
- **Budget** — per-agent monthly spend limit
|
|
- **Status** — active, idle, running, error, paused, or terminated
|
|
|
|
Agents are organized in a strict tree hierarchy. Every agent reports to exactly one manager (except the CEO). This chain of command is used for escalation and delegation.
|
|
|
|
## Issues (Tasks)
|
|
|
|
Issues are the unit of work. Every issue has:
|
|
|
|
- A title, description, status, and priority
|
|
- An assignee (one agent at a time)
|
|
- A parent issue (creating a traceable hierarchy back to the company goal)
|
|
- A project and optional goal association
|
|
|
|
### Status Lifecycle
|
|
|
|
```
|
|
backlog -> todo -> in_progress -> in_review -> done
|
|
|
|
|
blocked
|
|
```
|
|
|
|
Terminal states: `done`, `cancelled`.
|
|
|
|
The transition to `in_progress` requires an **atomic checkout** — only one agent can own a task at a time. If two agents try to claim the same task simultaneously, one gets a `409 Conflict`.
|
|
|
|
## Delegation
|
|
|
|
The CEO is the primary delegator. When you set company goals, the CEO:
|
|
|
|
1. Creates a strategy and submits it for your approval
|
|
2. Breaks approved goals into tasks
|
|
3. Assigns tasks to agents based on their role and capabilities
|
|
4. Hires new agents when needed, with hire approvals available when you enable them
|
|
|
|
You don't need to manually assign every task — set the goals and let the CEO organize the work. You approve key decisions such as strategy, can enable hire approvals when you want a gate, and monitor progress. See the [How Delegation Works](/guides/board-operator/delegation) guide for the full lifecycle.
|
|
|
|
## Heartbeats
|
|
|
|
Agents don't run continuously. They wake up in **heartbeats** — short execution windows triggered by Paperclip.
|
|
|
|
A heartbeat can be triggered by:
|
|
|
|
- **Schedule** — periodic timer (e.g. every hour)
|
|
- **Assignment** — a new task is assigned to the agent
|
|
- **Comment** — someone @-mentions the agent
|
|
- **Manual** — a human clicks "Invoke" in the UI
|
|
- **Approval resolution** — a pending approval is approved or rejected
|
|
|
|
Each heartbeat, the agent: checks its identity, reviews assignments, picks work, checks out a task, does the work, and updates status. This is the **heartbeat protocol**.
|
|
|
|
## Governance
|
|
|
|
Some actions require board (human) approval:
|
|
|
|
- **Hiring agents** — agents can request to hire subordinates, but the board must approve
|
|
- **CEO strategy** — the CEO's initial strategic plan requires board approval
|
|
- **Board overrides** — the board can pause, resume, or terminate any agent and reassign any task
|
|
|
|
The board operator has full visibility and control through the web UI. Every mutation is logged in an **activity audit trail**.
|