DottaandPaperclip
0a5f1546ee
## Thinking Path > - Paperclip manages AI agents and their work. > - Cases keep facts, documents, and one primary task across agent handoffs. > - Each case currently needs its own procedure text. > - Agents need to reuse procedures and move cases between them without replacing the task. > - This change adds company workflow definitions with a name and Markdown prompt. > - Existing handoff and document transactions preserve authority, revisions, and recovery. > - Cases remain behind `experimental.enableCases`. ## Linked Issues or Issue Description Refs #16959. Related proposal: #3951 uses task graphs and a visual editor. This change extends existing Cases with prompt definitions and keeps its current handoff model. **Problem or motivation** Agents cannot share a reusable procedure across cases or inspect a case's movement between procedures. **Proposed solution** Add name-and-prompt workflow definitions. Adopt a prompt into the primary task's revisioned workflow document through a handoff. Keep phases as free text. **Alternatives considered** Defer graphs, workflow versions, run entities, role schemas, authoring screens, and Spec Kit integration. **Roadmap alignment** This extends the existing Cases experiment and same-task review flow. It adds no work queue or new execution engine. The maintainer approved this scope in the implementation plan. ## What Changed - Add company-scoped definition storage, shared request schemas, REST routes, and four optional Cases tools. - Accept a workflow ID at kickoff. Agent handoffs can adopt, refresh, preserve, or detach a workflow. - Capture prompt text and the document base revision at acceptance. Apply workflow, phase, and document revision together after outgoing execution settles. - Hold conflicting document edits for recovery. Preserve cancellation, replay, and restart behavior. - Show current workflow names and captured transition names/phases in Work, history, and Audit. - Update instructions, API/tool contracts, capability maps, and the isolated workflow journey. - Pin bounded workflow prompt reads to a content fingerprint; continuation conflicts on edits and can restart safely. - Remove experimental Cases/workflow/Mermaid guidance from the always-on native prompt. Extract runtime-context prompt strings into a CODEOWNERS-protected constants file while preserving the public imports. - Refresh Copilot’s pinned source identity to v57, including the extracted prompt file and retaining historical identities. ## Verification Local checks: repository `pnpm -r typecheck` and `pnpm build` pass on the prompt-extraction tree (`88222d45d8`). Full repository coverage previously completed through the supported isolated shard groups (1,082 general server suites, 161 serialized suites, and all three workspace groups). The earlier default serial run was interrupted and remains incomplete. The first sharded run retained the failures described below; targeted corrections and separate limited-concurrency reruns pass. All CI jobs, security checks, and the 5/5 Greptile review passed on `fc1bd79c28`. Fresh CI and review are pending for the prompt extraction in `88222d45d8`. Focused verification passes: real-database handoff recovery and reuse; 2,002 native-tool/API contract checks; 144 Runner catalog/discovery checks; 27 Runner context/coverage checks; 37 case/Audit UI checks; and Product E2E oracle calibration. Token gates, migration safety/numbering, module boundaries, capability maps, and generated tool/Storybook catalogs pass. The final route/context corrections pass 49 API/native-tool tests, 90 real-database handoff tests, and server typecheck; 142 Copilot installation/sidecar tests pass with the refreshed identity. Greptile’s first review found that successive prompt pages could mix definitions after an edit. The fix returns a content fingerprint, requires it for continuation, and rejects edits with 409. Strict live/catalog schemas pass (171 Runner checks). The 2,005 API/OpenAPI tests pass; the initial native regression caught compression’s weak ETag prefix, and all 23 native integration tests pass after handling it. The regression covers same-length edits and a four-byte restart window. No stored version fields or entities were added. The prompt extraction passes all 462 checks across six focused suites, including persisted-context recovery and provider transport. The first local transport attempt lacked the required debug Runner binaries (102 failures, retained); after building the normal prerequisites, all 283 tests in that suite pass without source or assertion changes. Existing saved snapshots retain their recorded prompt text, and new executions use core-only prompt v7. The extracted prompt source is now covered by both CODEOWNERS and Copilot’s source fingerprint. Live-provider evidence is separate from those simulated checks: the isolated API-key campaign `reusable-workflows-api-final-2026-10-21` passed with local code matching `a1d73b4652`. Four actual Codex API runs read the adopted task documents, moved one case A → B → A on the same task, completed normally, and passed all nine durable checks. Browser assertions verified the current workflow/phase, historical names/phases, five handoff records including terminal completion, and the completed original task. Cleanup passed. The local report remains under `tests/runner-e2e/results/reusable-workflows-api-final-2026-10-21/`; no credentials or screenshots are committed. CI initially caught an omitted route-inventory entry and a stale pinned instruction-source hash; both are corrected and separately verified. Local serialized coverage also recorded an unrelated environment-route socket disconnect and activity-route timeout; their separate 11-test and 17-test suites passed without code or timeout changes. An unchanged chunked-webhook check also passed its separate four-test rerun. The initial adapter/database workspace groups hit time and resource limits under default worker counts; complete reruns with `VITEST_MAX_WORKERS=2` pass, including all 55 database files and 211 tests. The UI/CLI groups passed 837 files and 9,442 tests in the original run. Original failures remain retained and are not regraded. Earlier failed live campaigns remain unchanged: subscription HTTP 429 before agent execution; an obsolete exact-four-row oracle that rejected the valid terminal fifth row; and a chat-marker expectation that did not account for the existing explicit-comment presentation policy. The final fixture requires terminal completion and places the marker in its authoritative comment. Positive/negative oracle tests and the fresh live campaign pass. ## Risks - The additive migration adds a table and nullable case/handoff fields. Existing rows keep null workflow metadata; no assignments are inferred. - Adoption can wait on an intervening task-document edit. Recovery must cancel the old intent and accept a new one after readback. - Shared definition edits affect future adoptions. Existing case copies keep their revisions. - The feature remains experimental. This PR does not merge or deploy the change. - Live acceptance covers native Codex before the prompt extraction; this cleanup has contract/transport verification rather than a new live-provider campaign. The refreshed Copilot identity has static compatibility evidence, not new live-provider qualification. ## Model Used OpenAI Codex, configured model ID `gpt-6-astra`, xhigh reasoning. Used terminal execution, file editing, and tool calls. The active context-window size is not exposed. ## 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 - [x] 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 --------- Co-authored-by: Paperclip <noreply@paperclip.ing>
14 KiB
Cases and structured work records — agent access
Product map: Cases and structured work records.
Feature ID: cases.
Review date: 2026-10-12. Source commit: f981fa3cc10cb8663a87dec60345fbff46d54d0a.
This is a source-reviewed baseline of representative operations and known gaps. Each capability needs operation-level review before its entire scope can be qualified. Scoped working-tree and live evidence is recorded below; it does not qualify every operation in the baseline tables. Follow the map contract for format, permission checks, evidence and maintenance.
browse
Capability ID: cases/browse.
Review: baseline.
API: present — representative operation IDs:
GET /api/companies/{companyId}/cases(search/status/type/project filters,sortField=updated|created|title|status|type,sortDir=asc|desc,groupBy=none|status|type|project, and offset after authorization). Sorting and group ordering apply to the full authorized result before pagination. Defaults retain newest-updated ordering; status uses lifecycle order and project groups use stable project IDs with unassigned cases last.GET /api/companies/{companyId}/cases/types(distinct types from accessible standalone cases).
Agent access: available — REST / native call_api; dedicated native read_case
for an authorized standalone case or the task's primary case; agent cases reference.
Native read_case has bounded UTF-8 JSON paging through the same authorized
case GET (agentRead=true). Small cases remain structured; large cases and
section: "fields" expose exact readPage.text chunks. Continuations require
offsetBytes and the returned snapshot; a changed case/task version or selected
projection returns 409. Every successful page retains handoff/task versions.
Generic call_api remains optional and is not needed to recover large fields.
section: "document" with documentKey reads a historical case-owned document;
adding documentIssueId selects a current primary or linked task document.
Bodies use the same bounded JSON pages without generic API tools. Each page
rechecks source-task access and linkage, excludes system/quarantined documents,
and binds the snapshot to the selected document identity, revision and body.
Policy: enableCases gate; company/case/task boundaries, active run where required, source trust, and checked-out mutation ownership.
Evidence: source-only — implementation at the
reviewed commit above.
Verification: not-run — exercise a listed permitted operation with actual agent
credentials/run context; inspect its result and applicable persistence/attribution.
Assert the relevant denied actor, owner, company or mode from Policy. Review the
remaining operations before qualifying the whole capability.
Gaps: No dedicated production list_cases binding is required because the REST fallback exists. Case pages are read-only; this does not remove agent mutation APIs.
structure
Capability ID: cases/structure.
Review: baseline.
API: present — representative operation IDs:
POST /api/companies/{companyId}/cases.PATCH /api/cases/{id}.
Agent access: available — REST / native call_api; native create_case creates a
fresh case and its first task through required kickoff and
workflow_document_text; new-case handoff API calls require the same text.
It is saved verbatim as ordinary task document workflow before delivery,
with create-only revision semantics and task mutation authority when binding.
Tool prompts, API schema descriptions and the case guide recommend both a Mermaid
stateDiagram-v2 map and prose defining transition triggers, evidence, next
agents, human waits and correction/escalation rules. Diagram labels are advisory.
initialDocuments writes ordinary task documents before dispatch.
update_case changes title, summary and whole-object fields. Reads/updates
default to the primary workflow case and retain REST authorization. Standard
read_document / write_document operate on the active task; rollup references
identify other accessible tasks and their authenticated REST read paths. Native
read_case document selection can open those references without call_api.
Policy: enableCases gate; company/case/task boundaries, active run where required, source trust, and checked-out mutation ownership.
Evidence: source-only — implementation at the
reviewed commit above.
Verification: not-run — exercise a listed permitted operation with actual agent
credentials/run context; inspect its result and applicable persistence/attribution.
Assert the relevant denied actor, owner, company or mode from Policy. Review the
remaining operations before qualifying the whole capability.
Gaps: Structured case data is supported; grouping/rendering is presentation, not a new endpoint requirement.
Dedicated native CRUD is standard-mode/enableCases gated and has strict schemas;
fact updates cannot change status, routing or permissions. Update receipts are
run-scoped; creation always delegates to the principal-scoped
handoff receipt. Missing kickoff or workflow text is rejected before any writes.
Workflow text and other seeds share a bounded budget; extra seeds cannot replace
the workflow key. Later transfers use ordinary revision tools for edits. Documents use ordinary task revision checks. Historical
case-document REST/storage remains compatible, but separate native case-document
tools are retired. Deterministic production-boundary tests are in
native case tools
and the assembled native journey;
the real-provider campaign local-2026-10-19T19-57-00-135Z also passed all 12
receipt workflow checks using the dedicated tools. This scoped evidence does not
qualify every generic case REST operation or subsequent tool replacements.
The newer create_case/initialDocuments/task-rollup implementation has its own
scoped deterministic verification in that record, including native creation and
authenticated HTTP replay/denial tests. The later campaign
local-2026-10-19T21-39-45-440Z passed all 13 live workflow checks using seeded
ordinary task documents and task-document reads/writes. Its returning builder
reused its own persisted session. Kickoff was initiated through the harness API;
provider-generated native create_case kickoff remains deterministically
verified rather than live-provider qualified. See the
verification record.
The subsequent required workflow-document contract has authenticated HTTP, real-database/API schema and assembled native-runner coverage. Receiving context prioritizes its authorized reference, and fresh-session recovery keeps workflow text reference-only as well. These controlled-provider tests verify required creation, atomic task document persistence, replay and no automatic body injection; the earlier live campaign predates this requirement and is not requalified.
history
Capability ID: cases/history.
Review: baseline.
API: present — representative operation IDs:
GET /api/cases/{id}/events.GET /api/cases/{id}/documents/{key}/revisions.GET /api/issues/{id}/documents/{key}/revisionsfor task-owned rollup documents.
Agent access: available — REST / native call_api.
Policy: enableCases gate; company/case/task boundaries, active run where required, source trust, and checked-out mutation ownership.
Evidence: source-only — implementation at the
reviewed commit above.
Verification: not-run — exercise a listed permitted operation with actual agent
credentials/run context; inspect its result and applicable persistence/attribution.
Assert the relevant denied actor, owner, company or mode from Policy. Review the
remaining operations before qualifying the whole capability.
Gaps: Source-backed access only; case visibility and document locks still apply.
task-links
Capability ID: cases/task-links.
Review: baseline.
API: present — representative operation IDs:
POST /api/cases/{id}/links.GET /api/issues/{issueId}/cases.
Agent access: available — REST / native call_api.
Policy: enableCases gate; company/case/task boundaries, active run where required, source trust, and checked-out mutation ownership.
Evidence: source-only — implementation at the
reviewed commit above.
Verification: not-run — exercise a listed permitted operation with actual agent
credentials/run context; inspect its result and applicable persistence/attribution.
Assert the relevant denied actor, owner, company or mode from Policy. Review the
remaining operations before qualifying the whole capability.
Gaps: Case/task association exists; source trust and issue visibility must be tested with agent credentials.
handoffs
Capability ID: cases/handoffs.
Reusable workflow extension (2026-10-21): GET/POST /api/companies/{companyId}/workflows
and GET/PATCH /api/workflows/{id} expose company-scoped metadata/Markdown prompts.
Native list_workflows, read_workflow, create_workflow, update_workflow use
the optional Cases group, including with generic API tools disabled. Writes use
existing run/source-trust fences and mutation receipts. Bounded prompt reads use
the native API JSON text paging path; every page checks current company access.
Continuation pages require the first page's content snapshot; edits return 409
and require restarting the read, so pages cannot silently combine definitions.
Kickoff accepts either a workflow ID or inline text. Agent handoffs omit the ID
to preserve, explicitly name an ID to adopt/refresh, or pass null to detach.
Acceptance snapshots the prompt; transfer checks its task-document base revision
before atomically adopting workflow/phase/instructions. Generic case updates
cannot alter routing. Repeated visits and captured names remain in handoff history.
The real-database/native-tool tests prove reuse, refresh, conflict/cancel/restart,
cross-company denial, stopped writes, flag-off execution, and inline compatibility.
Configured-provider acceptance of the extended journey is recorded separately.
Review: baseline.
API: present — POST /api/companies/{companyId}/case-handoffs; GET /api/cases/{id}/handoffs; POST /api/cases/{id}/handoffs/{handoffId}/retry and /cancel.
Agent access: available — live native handoff_case, native API discovery/call_api, and authenticated agent REST. Initial kickoff creates or explicitly binds an ordinary task; subsequent calls reuse it.
Terminal destination: to: "done" records closure intent for an existing primary task, using case read/mutation and normal task mutation authority. It does not assign, wake, yield, or satisfy completion evidence. Normal accepted task completion atomically closes the case; a current execution's Stop, task cancellation, or reassignment invalidates the intent. Run-scoped Stop preserves newer work; cancelling terminal intent without a source run requires fenced current task ownership. Waiting on review or user input preserves it. Ordinary completion without a terminal intent leaves case status unchanged.
Retention: whole-company deletion removes case history before dependent tasks/agents. Individual agent purge returns 409 agent_case_history_retained when handoffs reference the agent; termination preserves its attribution.
Policy: enableCases; standard mode; ordinary task creation/assignment authority; agents transfer only their own work; current case/task versions; company and retained task/project access intersection; existing review, Stop, budget, and workspace gates. Idempotency belongs to the authenticated principal, not a provider run. Cancellation remains available while the feature is disabled.
Delayed assignment rechecks the original caller's current assignment authority using internal, server-derived provenance. The context is not returned by history or recovery APIs. Missing historical provenance fails closed. After an assignment is applied, delivery checks recipient admission rather than requiring the former assignee to retain task access.
Cloud-user transfers confirm current stack membership through the uncached tenant portfolio API before taking task locks. The short-lived proof is bound to the original user and configured stack identity. Owner elevation also requires the current managed feature setting. Missing membership, a viewer role, an unavailable lookup, or a changed configuration holds the transfer. No Cloud role or administrator grant is stored in the handoff context.
Evidence: verified — 2026-10-19 working-tree implementation. The assembled native integration passed with actual runnerd and a controlled provider; legacy HTTP integration and real-database authority/recovery tests passed. The later API-key campaign local-2026-10-19T19-14-18-642Z completed four real native runs and terminal case closure. The earlier subscription HTTP 429 remains recorded as a failed attempt; it was not regraded. See the verification record.
Verification: passed — deterministic boundaries include native tool acceptance/yield, process settlement, same-task successor context, authenticated HTTP replay, denied private sources, version conflicts, review gates and restart/acknowledgment recovery. The configured-provider correction round trip passed using API credentials. The latest local-2026-10-19T21-39-45-440Z campaign passed 13 checks with task-owned documents, four nonoverlapping runs, same-task transfers, returning-builder session reuse and terminal case closure. The earlier local-2026-10-19T21-32-43-612Z campaign remains failed because the task revision API omitted stored writer-run attribution; the subsequent authorized projection fix was qualified by the new campaign. Compact context content/omission assertions retain separate deterministic evidence.
Gaps: Full provider qualification is recorded separately from source presence and deterministic service tests.