mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-16 03:31:44 +01:00
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Tasks need a clear way to resume after a setup failure. > - A shared repository can contain another task that the assigned agent cannot read. > - Paperclip correctly stops before the agent starts, but the user must then understand workspace settings to recover. > - This pull request gives that failure a single Retry button and selects a clean copy of the configured repository through normal admission. > - The task keeps its assigned agent and execution settings, while access checks and existing work remain protected. ## Linked Issues or Issue Description Related: #16895 classifies the restricted source failure. This change adds the user recovery action. #16906 handles retained files after execution; this change handles a setup failure before execution starts. **What existing behavior does this improve?** Recovery of a task whose shared repository includes a task workspace the assigned agent cannot read. **Current behavior** The task stops before provider work and asks the user to understand workspace choices or access grants. **Proposed behavior** Show Retry above the task message box, independent of loaded conversation history. One click requests one attempt using a clean checkout of the configured remote. Show Retrying while the request is pending. Show an error only if the request fails. **Reason and benefit** The user can resume work without understanding repository isolation or changing access to another task. **Breaking changes** None. The recovery source value is server-owned. The public workspace selection request does not accept it. No migration is required. ## What Changed - Add one Retry control above the composer in both task conversation views. It stays available when an older notice is outside the loaded comment pages. - Bind recovery to the latest failed run, current assignee, and recorded proof that provider work did not start. - Use the existing atomic recovery route and pending workspace selection. Normal admission clears the old session and creates the isolated checkout. - Choose a fresh task-owned branch for recovery, including fixed project branches, existing task branches, and adapter branch overrides. Preserve the model, environment, setup commands, pending user workspace choices, previous files, and all execution gates. - Update execution documentation and both workspace maps. ## Verification - Passed all 461 tests in the eight affected database, Git, HTTP, workspace binding, and conversation suites after the review fixes. An additional 292 tests passed after the final compatibility fixes, including IssueDetail and recovery action routing. - Concurrent HTTP retries produce one wakeup. Paused projects and runs that started provider work reject recovery without changing the workspace. - Real Git tests exclude private files, private commits, and unpublished original files from the clean checkout, preserve the original, and exercise reuse, cleanup, and reopen. - Verified in a running local app: a task failed twice, displayed only Retry, and reached Done after one click. A second browser test put the failure notice behind 501 newer comments and used a fixed project branch. Retry stayed visible and the task reached Done. The credential-free process worker used the selected checkout and wrote its result there. This does not claim a live model-provider run. - The first manual fixture lacked a responsible-user membership and failed after successful workspace recovery. Corrected the fixture, retained that failure evidence, and verified the full flow with ordinary authorization. - Full typecheck, build, token gates, and map checks passed. The full local suite was stopped after review changed its source during execution; current-head CI provides the complete suite result. - An earlier unrelated peer-comment read test hit a socket hangup. The next complete affected-suite run passed; the first failure is retained in local evidence. - Current-head CI hit an unchanged runner credential-concurrency test failure. That lane passed on the preceding commit, and all 42 credential tests passed locally. The original failed job is retained; the one-time rerun passed. All latest-head CI checks are green (55 success, 2 skipped, 1 neutral), and Greptile is 5/5 with both review threads resolved. ## Risks - A remote repository outage can still prevent the next attempt. Retry does not grant access or copy unpublished files from the old checkout. - Recovery accepts only the latest recorded pre-provider failure and preserves normal execution gates. This limits duplicate work and stale recovery requests. - No database migration, dependency, or lockfile change. - The first review found fixed-branch retry loops and dependence on paginated notice history. Both had failing regressions before the fixes and now pass targeted tests and the combined browser journey. - Full CI then caught assumptions about missing run evidence and unrelated recovery actions. The final changes tolerate absent evidence and scope the new lookup to board-owned actions with valid run IDs. The previously failing suites now pass locally. ## Model Used OpenAI Codex, GPT-6 family, with reasoning, repository tools, code execution, and browser verification. The exact serving model ID and context window are not exposed in this session. ## 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 - [x] All Paperclip CI gates are green - [x] 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>
264 lines
15 KiB
Markdown
264 lines
15 KiB
Markdown
# Execution workspaces, services, and files — agent access
|
|
|
|
Product map: [Execution workspaces, services, and files](../feature-map/workspaces.md).
|
|
|
|
Lost-source reconstruction adds the board-only
|
|
`POST /api/issues/{id}/recovery-actions/reconstruct-workspace` action. It requires
|
|
`runtime:manage` and ordinary task visibility. Agents cannot authorize it. The
|
|
result is a durable fresh-session admission request, subject to current execution
|
|
gates. It grants no additional tool access, budget, work window or permission to
|
|
repeat completed actions. Attachments must belong to the same task and company.
|
|
The original failed run and lost-export evidence remain unchanged.
|
|
Later native run-only cancellations can coexist only with confirmed lease stops,
|
|
board file-only repair and an external-action outcome of `not_performed`.
|
|
Their immutable evidence is checked again at dispatch. Historical cancellation
|
|
retention runs internally and grants no new agent operation or authority.
|
|
|
|
Review date: 2026-10-12. Source commit: `58e16dbddfc9c8d0cf60867f9d9847f0feda055b`.
|
|
Native REST transport reconciled in this change; see the
|
|
[shared transport contract](README.md#native-rest-transport).
|
|
|
|
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. No live agent execution is claimed. Follow the [map contract](../README.md)
|
|
for format, permission checks, evidence and maintenance.
|
|
|
|
## `binding`
|
|
|
|
Review: `baseline`.
|
|
|
|
API: `present` — representative operation IDs:
|
|
|
|
- `GET /api/issues/{id}/heartbeat-context`.
|
|
- `GET /api/execution-workspaces/{id}`.
|
|
- `GET /api/issues/{id}/workspace` inspects the durable task binding.
|
|
- `PUT /api/issues/{id}/workspace` requests the next binding.
|
|
- `GET /api/companies/{companyId}/execution-workspaces?summary=true&selectableForTask=true`
|
|
lists authorized task-selectable workspaces.
|
|
|
|
Agent access: `available` — Native get_task_context / REST / CLI / MCP workspace read.
|
|
|
|
The task-bound native tools `get_workspace`, `list_workspaces`, and
|
|
`select_workspace` use the ordinary authenticated APIs. Legacy agents can call
|
|
those APIs with their admitted run token. These paths do not require a project.
|
|
|
|
Policy: Company/project/workspace visibility and runtime authority; active run, trust
|
|
preset and task ownership where required.
|
|
|
|
Task workspace writes require `issue:mutate`, an active owned task/run for agents,
|
|
and current source visibility. Shared physical roots also require source-project
|
|
workspace write authority. Accepting a new pending choice advances its binding
|
|
revision; superseded retries fail while current-choice retries remain idempotent.
|
|
Binding revisions and request keys fence retries;
|
|
selection applies at the next normal admission without interrupting a live run.
|
|
|
|
Fresh standard-trust tasks with an implicit repository default can use an owned
|
|
remote clone when the shared default source fails the restricted-task workspace
|
|
guard. This does not grant access to the private local checkout or its Git metadata.
|
|
The normal admitted Git identity must already authorize the configured remote.
|
|
Creation of an automatic fallback source is unavailable for explicit, parent/channel, reused
|
|
or low-trust selections, or branch templates without a task-derived placeholder;
|
|
an existing verified owned source remains reusable. Literal branch selections
|
|
retain the original denial without cloning or replacing their unpublished commits.
|
|
New implicit Git defaults record project-source provenance. Untyped explicit,
|
|
inherited and older ambiguous checkout bindings retain the denial; admission reads
|
|
the current company-scoped binding before considering the fallback.
|
|
A retained denial blocks the task as `configuration_incomplete`
|
|
(`workspace_source_restricted`) before dispatch; it grants no access and offers Retry.
|
|
The same blocker applies when shared project workspace repository admission finds
|
|
the restricted source. The existing binding and files stay intact; no provider
|
|
starts and no automatic failure retry is queued.
|
|
An authorized board recovery through `POST /api/issues/{id}/recovery-actions/resolve`
|
|
can schedule a server-owned `recovery` selection for the latest restricted-source
|
|
failure only when its saved evidence proves provider work never started. The
|
|
selection requires task mutation and configured-source access and applies at normal
|
|
admission. It keeps task environment settings and never reads or deletes the denied
|
|
checkout. Pause, budget, approval, interaction, dependency, and ownership gates
|
|
remain effective. Repeated resolution of the same action does not enqueue another
|
|
run. Agents cannot mint recovery provenance through the workspace selection API;
|
|
they can observe the existing recovery action and request board recovery.
|
|
Local paths, unsupported transports and credential-bearing URLs are not fallback
|
|
sources. Company/task/remote bindings, real paths, Git storage and the exact origin
|
|
are revalidated for reuse, cleanup and reopening. A failed save removes only the
|
|
owned task worktree. The [isolated-source service](../../server/src/services/isolated-remote-workspace-source.ts)
|
|
and its local regression tests establish source and lifecycle boundaries; live
|
|
agent/provider qualification remains separate.
|
|
Reconstructable Git expiration adds no agent endpoint or permission. It records
|
|
company/workspace/repository identity and an exact commit before removing owned
|
|
cache files. Existing task/workspace reopening retains current company, source,
|
|
and trust checks. Missing upstream access returns a retryable error; it does not
|
|
choose a newer commit or grant access to another company's source. Shared project
|
|
bases and unresolved recovery remain protected. Local lifecycle evidence is in
|
|
[expiration tests](../../server/src/__tests__/git-workspace-expiration.test.ts).
|
|
|
|
Writable aliases must also be compatible with current and retained physical
|
|
source projects' trust boundaries. Incompatible choices are rejected before
|
|
dispatch; a projectless alias cannot bypass required sandbox containment.
|
|
Source-copy checks apply the same trust boundary before provisioning. The
|
|
authoritative sandbox or SSH selection suppresses configured and built-in
|
|
controller worktree and runtime provisioning regardless of task trust, source
|
|
write grants or board sponsorship. Genuine isolated worktrees still permit
|
|
authorized read-only source copying. Source write permission does not authorize
|
|
controller execution. Explicit, channel, inherited, foreign or nondefault isolated
|
|
source choices remain copy-only for controller provisioning even on local runs.
|
|
Their deny-only workspace marker survives metadata and binding changes; a board
|
|
reopen does not turn it into approval. Implicit trusted local defaults and explicit
|
|
SSH remote provisioning retain their existing placement; no new sandbox provision transport
|
|
is claimed. The implicit default follows task creation: configured policy pointer,
|
|
then primary source, creation time and ID. A missing or foreign configured source
|
|
does not authorize controller hooks. This precedence neither changes existing
|
|
creation validation nor rotates bindings or clears retained copy-only markers.
|
|
Closed-worktree reopening checks current task, agent, organizational and source policies without assuming a future driver. Effective low-trust reopens suppress configured and built-in host scripts. Returned checkpoints must have directory parents for every nested entry before merging, including unchanged entries; invalid output leaves retained host files intact and keeps recovery evidence.
|
|
|
|
Skipping the host scan for a fully unchanged returned snapshot grants no new
|
|
access. The merge still holds its canonical writer lock and runs both authority
|
|
and publication hooks. Denials still propagate, and checkpoint/archive validation
|
|
is unchanged. [Regression coverage](../../packages/adapter-utils/src/workspace-restore-unchanged.test.ts)
|
|
is source-level evidence only.
|
|
Child creation by an admitted agent checks an explicit prospective-task context before the child is saved. The creator run must have an authoritative saved policy and a verified company/agent/parent lineage. Current parent, prospective child and physical source policies must fit that boundary. This creation path does not relax exact task/run checks for existing-task writes. The [child trust regression](../../server/src/__tests__/task-workspace-child-trust.test.ts) is automated source-level evidence, not live agent qualification.
|
|
Source review for these additions: PR #15749 and
|
|
[task workspace routes](../../server/src/routes/task-workspaces.ts),
|
|
[native authority](../../server/src/services/native-runtime/paperclip-runner-tool-authority.ts),
|
|
and [semantic transport](../../server/src/services/task-workspace-tools.ts).
|
|
|
|
Evidence: `source-only` —
|
|
[implementation](../../server/src/routes/workspace-runtime-service-authz.ts#L76) 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: Run/task context identifies its actual realized workspace; record existence is not
|
|
a running service.
|
|
|
|
## `provisioning`
|
|
|
|
Review: `baseline`.
|
|
|
|
API: `present` — representative operation IDs:
|
|
|
|
- `GET /api/execution-workspaces/{id}`.
|
|
- `GET /api/execution-workspaces/{id}/workspace-operations`.
|
|
- `POST /api/issues/{id}/workspace/repositories` requests repository preparation.
|
|
|
|
Agent access: `partial` — REST / native call_api reads; task/project assignment triggers
|
|
server provisioning.
|
|
|
|
Native `prepare_repository` and admitted legacy REST callers can request a
|
|
catalog repository or validated repository URL for their current task.
|
|
Preparation occurs at normal admission; the agent cannot supply a host path or
|
|
controller identity. Current source permissions, responsible-user intersection,
|
|
trust restrictions, immutable receipts, and retained physical-root ownership are
|
|
checked before acquisition and publication. Low-trust callers cannot trigger a
|
|
new controller-side Git acquisition. Evidence remains source-only here; focused
|
|
[repository tests](../../server/src/__tests__/task-workspace-repositories-trust.test.ts)
|
|
are separate from live agent qualification.
|
|
|
|
Policy: Company/project/workspace visibility and runtime authority; active run, trust
|
|
preset and task ownership where required.
|
|
|
|
Evidence: `source-only` —
|
|
[implementation](../../server/src/routes/workspace-runtime-service-authz.ts#L76) 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: Observing readiness exists. Creating host commands or arbitrary provision targets
|
|
is a separate protected operation.
|
|
|
|
## `services`
|
|
|
|
Review: `baseline`.
|
|
|
|
API: `present` — representative operation IDs:
|
|
|
|
- `POST /api/execution-workspaces/{id}/runtime-services/{action}`.
|
|
|
|
Agent access: `available` — Authorized agent REST / native `call_api` / CLI runtime
|
|
service controls and existing stdio MCP controls.
|
|
|
|
Policy: Company/project/workspace visibility and runtime authority; active run, trust
|
|
preset and task ownership where required.
|
|
|
|
Evidence: `source-only` —
|
|
[implementation](../../server/src/routes/workspace-runtime-service-authz.ts#L76) 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 control_workspace_service binding. Generic native
|
|
calls retain runtime trust and workspace/task scope checks. Optional MCP availability
|
|
must be recorded.
|
|
|
|
## `files-git`
|
|
|
|
Review: `baseline`.
|
|
|
|
API: `present` — representative operation IDs:
|
|
|
|
- `GET /api/issues/{issueId}/file-resources/content`.
|
|
- `GET /api/issues/{issueId}/file-resources/list`.
|
|
|
|
Agent access: `partial` — Authorized workspace filesystem tools; Dot workspace bridge
|
|
when enabled; board file-resource HTTP UI.
|
|
|
|
Policy: Company/project/workspace visibility and runtime authority; active run, trust
|
|
preset and task ownership where required.
|
|
|
|
Evidence: `source-only` —
|
|
[implementation](../../server/src/routes/workspace-runtime-service-authz.ts#L76) 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: Files panel HTTP requires board. Agents can use their admitted workspace file
|
|
tools; remote/Dot scope and Git command availability differ.
|
|
|
|
File reads also enforce retained source privacy after local copy, configuration
|
|
move/removal, reopen, and project deletion. A task assignment or repository
|
|
receipt does not grant access to private files from another physical owner.
|
|
|
|
Authorized Git-source capture also retains ownership on the actual shared Git
|
|
storage. Source checks use verified checkout identities, including company-known
|
|
owners when separate metadata has no primary-checkout registration. Removing that
|
|
checkout does not release its private committed files in surviving worktrees.
|
|
|
|
## `closure`
|
|
|
|
Review: `baseline`.
|
|
|
|
API: `present` — representative operation IDs:
|
|
|
|
- `PATCH /api/execution-workspaces/{id}`.
|
|
- `GET /api/execution-workspaces/{id}/close-readiness`.
|
|
- `POST /api/execution-workspaces/{id}/reconcile-branch`.
|
|
|
|
Agent access: `partial` — REST / native fallback for permitted update; CLI workspace;
|
|
reconcile-branch requires board.
|
|
|
|
Policy: Company/project/workspace visibility and runtime authority; active run, trust
|
|
preset and task ownership where required.
|
|
|
|
Evidence: `source-only` —
|
|
[implementation](../../server/src/routes/workspace-runtime-service-authz.ts#L76) 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: Closure/readiness exists; not every workspace can be reopened, and branch
|
|
reconciliation has a board boundary.
|