mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-17 13:01:05 +01:00
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - `AGENTS.md` tells every contributor and agent to read `doc/DEVELOPING.md` for setup, commands, testing, and worktrees > - That file grew to 5,495 lines. Most of it was notes on how one subsystem behaves, added one pull request at a time > - Readers could not find the commands. Agents also read behavior notes as rules > - This pull request cuts `doc/DEVELOPING.md` to a 660-line setup and workflow guide. It moves the subsystem notes to focused docs > - The benefit is a guide that a person or an agent can read in full, and a clear place for each kind of note ## Linked Issues or Issue Description **Issue type** Outdated or confusing documentation. **Where is the issue?** `doc/DEVELOPING.md` **What's wrong?** The file was 5,495 lines. It opened with 112 lines about case handoffs before it reached Prerequisites. Unrelated sections sat below the "OpenClaw Docker UI One-Command Script" heading. Statements about current behavior read like policy. **Suggested fix** Keep setup, commands, and workflow in `doc/DEVELOPING.md`. Move each subsystem note to a doc for that subsystem. Add an index. ## What Changed - `doc/DEVELOPING.md` is now 660 lines: prerequisites, start dev, health checks, local run, test drive, Docker, instance layout, database, storage, secrets, worktrees, test commands, Storybook, CLI, and an index of the other docs. - 15 new docs hold the moved text without wording changes: `ci-workflows`, `test-infrastructure`, `worktrees`, `hot-restart-deploys`, `heartbeat-internals`, `runner-internals`, `workspace-repositories`, `workspace-storage`, `skills-and-teams-catalog`, `ui-internals`, `case-handoffs`, `chat-connector-development`, `instance-configuration`, `integration-api-notes`, `database-backups`. - "Publish a branch Storybook" moved to `doc/STORYBOOK-DEPLOYMENT.md`. The privacy rollout notes moved to `doc/ISSUE-PRIVACY.md`. - Deleted about 280 lines: the story-by-story Storybook notes, "Agent Artifact Uploads" (a copy of `doc/AGENT-ARTIFACTS.md`), two pointer-only sections, "Workspace feature checks (2026-10-09)", and "Chat and task navigation caching". The test-drive build-lock paragraph is now four lines. - Repointed every inbound link and every script or workflow comment that named a moved section. - `AGENTS.md` now says where a behavior note goes, so the guide does not grow again. ## Verification - A script split the file by line range. It asserts that each of the 5,495 source lines is kept, moved, or dropped exactly one time. - A link check on every changed Markdown file found 0 missing files and 0 missing anchors. - `node scripts/check-maps.mjs` passes. - `node --test .github/scripts/tests/*.test.mjs`: 808 pass, 0 fail. - `node --check` passes on the three scripts with changed comments. - `pnpm verify` was not run. This worktree has no installed dependencies, and the change has no runtime code. ## Risks - Low risk. The change is documentation and comments only. - A link to a moved section from outside this repository will land on the top of `doc/DEVELOPING.md`. - The new docs are not in the audited prose list in `.github/scripts/ci-inputs.mjs`. An edit to one of them runs full CI. An edit to `doc/DEVELOPING.md` does not. This PR does not change that list. ## Model Used - Claude Fable 5.2 (`claude-fable-5-2`), Claude Code desktop, with tool use. ## 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 searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [ ] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
130 lines
8.1 KiB
Plaintext
130 lines
8.1 KiB
Plaintext
---
|
|
description: Keep heartbeat a clear lifecycle coordinator with cohesive modules, explicit execution authority, and safe resource ownership.
|
|
globs: "server/src/services/heartbeat.ts,server/src/services/heartbeat/**,server/src/services/heartbeat-*.ts,server/src/__tests__/heartbeat-*.test.ts"
|
|
alwaysApply: false
|
|
---
|
|
|
|
# Heartbeat execution boundaries
|
|
|
|
## Scope and purpose
|
|
|
|
This rule covers the heartbeat entry point, its extracted modules,
|
|
heartbeat-prefixed sibling services, and heartbeat regression tests. Keep the
|
|
code organized so a reader can follow whether work may start, who owns the
|
|
execution, and how its outcome and resources settle.
|
|
|
|
## Folder structure and module responsibilities
|
|
|
|
`server/src/services/heartbeat.ts` is the public entry point and lifecycle
|
|
coordinator. Heartbeat-specific modules and their focused `*.test.ts` tests belong
|
|
in `server/src/services/heartbeat/`. Tests that exercise the assembled heartbeat
|
|
service also live in `server/src/__tests__/heartbeat-*.test.ts`. Keep these roles
|
|
distinct: the entry point should make the lifecycle readable, while modules own
|
|
the behavior of a particular phase or domain.
|
|
|
|
Use these existing boundaries when deciding where a change belongs. Paths below
|
|
are relative to `server/src/services/heartbeat/`:
|
|
|
|
| Modules | Responsibility |
|
|
| --- | --- |
|
|
| `queue.ts`, `scheduling.ts` | Queue admission, coalescing, and dispatch; timer and monitor scheduling. |
|
|
| `run-preparation.ts`, `execution-configuration.ts` | Run context and tool access; effective execution configuration and credentials. |
|
|
| `session-preparation.ts`, `run-state.ts` | Session selection and resume preparation; persisted run/session state and retrieval. |
|
|
| `workspaces.ts`, `workspace-preparation.ts` | Workspace resolution, reuse, and validation; preparing the selected workspace and acquiring its environment. |
|
|
| `environment-selection.ts`, `runtime-selection.ts` | Execution environment policy; selecting or restoring the execution runtime. |
|
|
| `runtime-execution.ts` | Dispatching prepared work through the runtime and handling its execution result. |
|
|
| `run-completion.ts`, `run-lifecycle.ts` | Success/failure settlement; shared status transitions, events, and completion handoffs. |
|
|
| `run-control.ts`, `retries.ts`, `recovery.ts` | Stop and cancellation; retry scheduling; restart recovery and unfinished cleanup. |
|
|
| `task-context.ts`, `task-markdown.ts` | Assembling task context and rendering assignment text. |
|
|
| `run-output.ts`, `run-log.ts` | Per-run output handling; log formatting, redaction, and payload bounds. |
|
|
|
|
This is a responsibility map, not an exhaustive API inventory. See the
|
|
[developer module map](../doc/heartbeat-internals.md#heartbeat-service-extractions) for
|
|
additional modules and implementation context. Update these descriptions when
|
|
ownership changes.
|
|
|
|
## Keep the coordinator from growing back
|
|
|
|
- Keep `heartbeat.ts` roughly stable or smaller as features are added. Small
|
|
wiring and lifecycle-ordering changes belong there; substantial new policy,
|
|
preparation, provider handling, or result processing belongs in a module.
|
|
Access to convenient local variables is not a reason to add another large
|
|
block to the coordinator.
|
|
- Extend the existing module that owns the behavior before creating another.
|
|
If a new responsibility has no owner, add a clearly named module under
|
|
`heartbeat/`. Avoid generic `helpers.ts` or `utils.ts` buckets and a separate
|
|
file for every small function.
|
|
- When a change would substantially grow the coordinator, extract the affected
|
|
responsibility in the same PR, backed by characterization tests. If an extracted
|
|
module begins accumulating unrelated responsibilities, split it at a cohesive
|
|
boundary too. Moving a large block into another file without clarifying its
|
|
contract is not enough.
|
|
- Preserve visible lifecycle ordering and resource ownership across extractions.
|
|
Keep coupled decisions together when splitting them would obscure correctness;
|
|
explain that tradeoff when substantial growth is necessary. Size is a signal
|
|
to review the boundary, not a reason to split an otherwise cohesive operation.
|
|
- Keep provider protocols and environment mechanics in their adapter/runtime
|
|
services. Heartbeat should coordinate through their contracts. Small dispatch
|
|
branches are appropriate; backend details should not spread into shared policy.
|
|
- Use narrow, typed contracts that make inputs, outcomes, and resource ownership
|
|
clear. Avoid passing the whole service closure or a generic mutable context.
|
|
Production dependencies should flow from the facade into its modules, without
|
|
modules importing the facade back.
|
|
|
|
## Design principles
|
|
|
|
- **Execution requires current authority.** Queue acceptance is not permission
|
|
to execute indefinitely. Admission and dispatch must respect company scope,
|
|
responsible-user authority, budgets, pause/Stop, and task eligibility, including
|
|
when these change during preparation. Retries and recovery must not become
|
|
alternate paths around those controls.
|
|
- **Ownership must be explicit.** Every execution and resource needs an owner,
|
|
a lifetime, and a defined handoff or release condition. These contracts must
|
|
hold across service instances, cancellation, partial startup, and restart.
|
|
Process-local coordination cannot establish authority over another process.
|
|
- **Completion has several independent obligations.** A result being accepted,
|
|
a provider stopping, a workspace being saved, and cleanup finishing are distinct
|
|
facts. Keep enough state to represent them honestly. Do not infer that resources
|
|
are safe to destroy or that successor work may start from a terminal status alone.
|
|
- **Recovery preserves intent and completed work.** Resume the admitted work
|
|
under its recorded execution contract. New configuration belongs to a new
|
|
admission decision, not a silent reinterpretation of an existing run. Repair
|
|
incomplete persistence or cleanup without repeating already completed provider
|
|
work. Automatic recovery should be bounded and safe to retry.
|
|
- **Durable state governs competing effects.** Claims and transitions must remain
|
|
correct when Stop, completion, and recovery race. A losing operation must respect
|
|
the winning outcome. Persist authoritative state before publishing notifications;
|
|
notification failures must not change the execution result or duplicate effects.
|
|
- **Uncertainty stays visible.** Missing ownership or termination evidence must
|
|
remain pending, held, or explicitly failed until reconciled. Preserve recoverable
|
|
work through failures. Keep security and sandbox requirements intact rather than
|
|
silently choosing a weaker execution path. Optional diagnostics must not prevent
|
|
essential settlement.
|
|
|
|
## Examples and allowed exceptions
|
|
|
|
- Retrying workspace copy-back after an accepted result is recovery work; it
|
|
should not start another provider turn merely to repeat the completed task.
|
|
- A shared checkout cache and per-run preparation state have different lifetimes.
|
|
Organize them by the ownership they need, rather than making all state local to
|
|
whichever factory happens to use it.
|
|
- Keep coupled admission or cleanup decisions together when splitting them would
|
|
hide their ordering. A large cohesive module can be appropriate. Apply these
|
|
principles to new or materially changed behavior without requiring unrelated
|
|
restructuring or a generic orchestration framework.
|
|
|
|
## Verification and review
|
|
|
|
Test the affected contract through observable behavior, including relevant
|
|
cancellation, concurrency, partial-failure, and restart cases. Exercise the public
|
|
heartbeat path when a module change could alter lifecycle coordination; use an
|
|
assembled-app journey for changes to dispatch, Stop, workspace recovery, or saved
|
|
agent files. Assert execution and persisted outcomes, not only helper calls.
|
|
|
|
Flag changes that give one policy competing owners, hide lifecycle ordering,
|
|
weaken execution authority, lose recoverable work, or confuse completion with
|
|
resource settlement. Explain the violated principle and the responsible boundary.
|
|
Also flag substantial coordinator growth or modules collecting unrelated behavior;
|
|
identify the existing owner or cohesive extraction that would keep the code
|
|
tractable. Do not freeze current variable names or helper layouts as policy.
|