mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-18 14:35:55 +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>
107 lines
7.3 KiB
Markdown
107 lines
7.3 KiB
Markdown
# Persistent case handoffs
|
||
|
||
Developer notes for the Cases experiment: handoff delivery, native case tools, and where the tests live.
|
||
|
||
The Cases experiment supports prompt-driven agent workflows on one ordinary task.
|
||
The application service owns transaction/idempotency and assignment policy;
|
||
`case-handoff-delivery.ts` owns durable retry/lease and wake admission;
|
||
`heartbeat/case-handoff-lifecycle.ts` owns execution release proof and stale-run
|
||
mutation fencing. Keep network/process work outside the acceptance transaction.
|
||
`heartbeat/process-settlement.ts` checks local process-tree absence independently
|
||
of scratch-directory preparation. A local process handoff stays pending while
|
||
the owned PID or process group is alive, or termination evidence is missing.
|
||
HTTP adapters use their awaited nonprocess invocation contract instead of host
|
||
PID probes. Stopping a run cancels its own intents; cancelling an unbound
|
||
terminal intent additionally requires fenced, current task ownership.
|
||
`case-context.ts` builds the bounded authorized case snapshot shared by native
|
||
and legacy task preparation, including resumed sessions.
|
||
|
||
Native case tools are `create_case`, `read_case`, `update_case`, and
|
||
`handoff_case`. Native creation requires `kickoff` and delegates to the same
|
||
principal-idempotent handoff service. Both `kickoff` and nonblank
|
||
`workflow_document_text` are mandatory; missing either fails before any writes.
|
||
The text is preserved in ordinary Markdown task document `workflow`, title
|
||
`Workflow`, in the acceptance transaction. New-case handoff API requests require
|
||
the same field. The workflow plus optional document seeds share a 200,000-character
|
||
budget; `workflow` cannot appear in `initialDocuments`. Later phase handoffs omit
|
||
the text; normal revision tools manage changes. Read `workflow` before routing:
|
||
its reference is prioritized in case context, without injecting its full body.
|
||
Recommend both a Mermaid `stateDiagram-v2` map and prose defining each transition's
|
||
trigger, evidence, next agent, human wait/resume behavior and correction/escalation
|
||
limits. State IDs match phase names and prose defines named edge outcomes.
|
||
This guidance adds no server-enforced transition semantics. There is
|
||
no passive creation branch or `createOnly` REST extension. Historical
|
||
generic REST upsert semantics remain compatible. `initialDocuments` is valid only for
|
||
new first-task kickoff; ordinary task documents and audit are committed before
|
||
delivery. Case detail/context roll up authorized task document metadata through
|
||
`case-task-documents.ts`; system keys and inaccessible task documents are
|
||
excluded before the document limit. Standard task document tools handle new
|
||
documents; historical case document REST/storage remains intact.
|
||
`read_case` keeps small responses structured. Large responses return bounded
|
||
`readPage.text` JSON chunks with case/task routing versions on every page. Use
|
||
`section: "fields"` to retrieve the entire fields object, including large keys,
|
||
strings, and arrays. Continue with the same `section` and `snapshot`, passing
|
||
`offsetBytes: readPage.nextOffsetBytes` until it is null; concatenate the text
|
||
before parsing JSON. A 409 means facts, accessible references, or routing changed:
|
||
restart at offset zero without the old snapshot. Each page reauthorizes current case access through
|
||
`GET /api/cases/:id?agentRead=true`; no generic API tool or asset grant is needed.
|
||
`limitBytes` is 4–8192 UTF-8 bytes. Ordinary REST reads retain their existing full
|
||
response, and ordinary `update_case` mutation receipts remain unchanged.
|
||
Use `section: "document"` and `documentKey` for a historical case-owned body;
|
||
add `documentIssueId` for a primary or currently linked task document. This
|
||
selection retains the same bounded JSON paging and does not enable generic API
|
||
tools. Each page checks current case access, task access, linkage, and document
|
||
trust. System and quarantined documents are excluded. Document edits and routing
|
||
changes invalidate the snapshot; restart from zero after a 409.
|
||
Each page reloads case metadata and the complete selected body to check access
|
||
and compute its snapshot. These limits bound the response, not total database
|
||
work; the read cost grows with source size and the number of pages.
|
||
|
||
Keep native schemas aligned with their services/routes. Transactional source
|
||
run checks must precede case writes, so Stop or an accepted handoff cannot race
|
||
an HTTP request into a late mutation. Generic API rollout settings do not remove
|
||
these dedicated tools; case, mode and resource authorization still apply.
|
||
Company deletion removes cases before task/agent dependencies. Individual agent
|
||
purge preserves handoff attribution and returns `agent_case_history_retained`
|
||
before destructive cleanup when history references that agent. Termination stays available.
|
||
|
||
The native constructor preserves full case context for bootstrap and resume
|
||
failure. Compatible continuations carry a versioned case projection tied to the
|
||
actual prior native input and exact agent/task/session. Stable facts fingerprints
|
||
include document revisions and accessible references, while phase/version and
|
||
incoming instructions are refreshed separately. Do not use a prepared
|
||
`contextSnapshot.paperclipCase` as proof that a compact provider turn received
|
||
those facts. Legacy adapters continue to receive their bounded case snapshot.
|
||
|
||
Start work through `handoff_case` or
|
||
`POST /api/companies/:companyId/case-handoffs`. Subsequent calls use the same
|
||
primary task and observed case/task revisions. GET the case's `/handoffs` for
|
||
history; `/handoffs/:handoffId/retry` retries delivery without creating new work,
|
||
and `/cancel` cancels pending delivery without reversing an applied assignment.
|
||
Ordinary task completion leaves the case unchanged. For an existing primary
|
||
task, `to: "done"` records a non-yielding terminal handoff; its `awaiting_completion`
|
||
intent is settled atomically by the normal issue-service completion transaction.
|
||
The case remains open during review or user waits. Stop/cancel/reassignment
|
||
invalidate the intent. Keep terminal intents outside agent-transfer mutation
|
||
fencing, outgoing yield detection and recipient dispatch.
|
||
|
||
The board case list/detail pages are read-only. URL query parameters retain
|
||
search/status/type/project filters through detail navigation; list paging and
|
||
the `GET /api/companies/:companyId/cases/types` read use authorized server data.
|
||
Storybook's Cases / Read-only pages stories mount those same production pages
|
||
with HTTP fixtures, including document previews, waiting handoffs and mobile.
|
||
|
||
Cases do not have a quarantine/promotion contract. Low-trust runs must save
|
||
findings through their governed task/review path rather than write case data.
|
||
Historical low-trust case provenance also blocks automatic execution context
|
||
and handoffs; operator reads remain available for review. Skill-test runs omit
|
||
workflow context to preserve their task-only scope. Cancelled or unapplied
|
||
handoff intent is history, not an incoming phase instruction.
|
||
|
||
Focused verification lives in the case route, handoff service, native handoff,
|
||
durable admission, and legacy process integration tests. Run the explicit-only
|
||
case-handoffs Product E2E workflow for provider/browser qualification; fixture
|
||
and service tests do not establish that a live model followed the workflow.
|
||
See [implementation and acceptance](plans/2026-10-19-persistent-case-handoffs.md)
|
||
and the [agent case reference](../skills/paperclip/references/cases.md).
|