0 Fork 0

mirror of https://github.com/paperclipai/paperclip.git synced 2026-10-07 07:23:08 +02:00

Files

T

DottaandPaperclip ba396c608c feat(server): configure shared workspace concurrency (#10759 )

<!-- Write all pull request text in Simplified Technical English
(ASD-STE100): short sentences, one instruction per sentence, simple
approved vocabulary, and the active voice. -->

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - The heartbeat service starts agent runs in local, SSH, sandbox,
plugin, or Kubernetes environments.
> - Runs can share one project working tree.
> - PR #10699 made every shared working tree single-file, including
trusted local and SSH hosts that support coordinated concurrent work.
> - Operators need a policy that keeps remote environments safe and
restores local multi-agent work.
> - This pull request adds an `auto`, `serialize`, or `allow`
concurrency policy and applies it to the final execution environment.
> - The benefit is safe serialization by default for sandboxed targets
and useful concurrency by default for persistent local targets.

## Linked Issues or Issue Description

Related work: #10699 introduced the busy gate that this change makes
configurable. #7852 covers a separate environment-lease race and does
not provide this dispatch policy.

**Subsystem affected**

`server/` heartbeat orchestration and `packages/shared/` workspace
policy contracts.

**Problem or motivation**

The shared-workspace busy gate always defers a second run. This behavior
prevents local multi-agent projects from running concurrently even when
operators expect agents to coordinate through commits.

**Proposed solution**

Add `sharedWorkspaceConcurrency` with `auto`, `serialize`, and `allow`
values. Default `auto` permits local and SSH concurrency. It serializes
sandbox, plugin, and forced Kubernetes execution.

**Alternatives considered**

Keeping unconditional serialization is too restrictive for persistent
host working trees. Always allowing overlap removes the protection that
sandboxed and remote targets need.

**Roadmap alignment**

This is a focused correction to the shipped cloud and sandbox execution
milestone. It does not add a new roadmap feature.

## What Changed

- Added the optional tri-state field to project policy and issue
override contracts and validators.
- Added a pure resolver with issue override, project policy, and `auto`
default precedence.
- Moved final environment and Kubernetes resolution before the
shared-workspace busy gate.
- Kept the existing deferral and retry behavior for every path that
resolves to serialization.
- Added a task-context warning and a structured log when a run
dispatches beside a live holder.
- Added policy and heartbeat coverage for all requested policy and
environment combinations.
- Documented the new policy and its default behavior.

## Verification

- `pnpm --filter @paperclipai/server exec vitest run
src/__tests__/execution-workspace-policy.test.ts
src/__tests__/heartbeat-workspace-busy.test.ts` — 32 tests passed.
- `pnpm -r typecheck` — passed.
- `PAPERCLIP_IN_WORKTREE=false
PAPERCLIP_DATABASE_RESTORE_IN_PROGRESS=false
PAPERCLIP_RESTORE_IN_PROGRESS=false pnpm test:run` — all 3,528 server
tests passed. The later UI/workspace phase passed 3,384 tests and hit
one unrelated `CompanyEnvironments` navigation timing failure.
- `pnpm --filter @paperclipai/ui exec vitest run
src/pages/CompanyEnvironments.test.tsx -t "opens the edit form on a
standalone page with existing values and closes after save"` — the
unrelated UI test passed in isolation.
- `pnpm build` — passed.

Policy matrix:

| Policy | Final target | Expected result | Result |
| --- | --- | --- | --- |
| `auto` | local | Dispatch with holder note | Passed |
| `auto` | sandbox | Defer with `workspace_busy` | Passed |
| `auto` | instance-forced Kubernetes | Defer with `workspace_busy` |
Passed |
| `serialize` | local | Defer with `workspace_busy` | Passed |
| `allow` | sandbox | Dispatch with holder note | Passed |

Existing serialization, retry, and stale-holder tests also pass.

## Risks

- `auto` changes the post-#10699 local and SSH behavior back to
concurrent dispatch. Concurrent agents can mutate the same working tree,
so each dispatched run receives an explicit coordination warning.
- `allow` is an operator override and can permit overlap in sandbox or
plugin environments.
- Unknown environment drivers serialize in `auto` mode. This keeps the
fallback conservative.
- There is no database migration. An absent field resolves to `auto`.

> 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 GPT-5 (Codex). The exact API snapshot and context-window size are
not exposed to the agent. Reasoning, repository editing, terminal tool
use, and local code execution were enabled.

## 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>

2026-08-03 14:25:05 -05:00

3.3 KiB

Raw Blame History

Issue worktree support

Status: experimental, runtime-only, not shipping as a user-facing feature yet.

This branch contains the runtime and seeding work needed for issue-scoped worktrees:

project execution workspace policy support
issue-level execution workspace settings
git worktree realization for isolated issue execution
optional command-based worktree provisioning
seeded worktree fixes for secrets key compatibility
seeded project workspace rebinding to the current git worktree

We are intentionally not shipping the UI for this yet. The runtime code remains in place, but the main UI entrypoints are hard-gated off for now.

What works today

projects can carry execution workspace policy in the backend
issues can carry execution workspace settings in the backend
heartbeat execution can realize isolated git worktrees
runtime can run a project-defined provision command inside the derived worktree
seeded worktree instances can keep local-encrypted secrets working
seeded worktree instances can rebind same-repo project workspace paths onto the current git worktree

Shared workspace concurrency policy

Projects and individual issues can set sharedWorkspaceConcurrency in their execution workspace policy/settings:

auto (the default when absent): allow concurrent shared-workspace runs on local and ssh environments, and serialize runs on sandbox and plugin environments. An instance forced to Kubernetes always serializes in auto mode.
serialize: defer a run while another live run holds the same project workspace, using the workspace_busy retry path.
allow: dispatch alongside a live holder on every environment.

Issue settings override the project policy, which overrides the default auto. When concurrency is allowed and a live holder exists, Paperclip adds the holder run and issue to the dispatched task context so agents can coordinate concurrent mutations through commits. The setting is optional JSON policy data, so existing databases require no migration.

Hidden UI entrypoints

These are the current user-facing UI surfaces for the feature, now intentionally disabled:

project settings:
- ui/src/components/ProjectProperties.tsx
- execution workspace policy controls
- git worktree base ref / branch template / parent dir
- provision / teardown command inputs
issue creation:
- ui/src/components/NewIssueDialog.tsx
- isolated issue checkout toggle
- defaulting issue execution workspace settings from project policy
issue editing:
- ui/src/components/IssueProperties.tsx
- issue-level workspace mode toggle
- defaulting issue execution workspace settings when project changes
agent/runtime settings:
- ui/src/adapters/runtime-json-fields.tsx
- runtime services JSON field, which is part of the broader workspace-runtime support surface

Why the UI is hidden

the runtime behavior is still being validated
the workflow and operator ergonomics are not final
we do not want to expose a partially-baked user-facing feature in issues, projects, or settings

Re-enable plan

When this is ready to ship:

re-enable the gated UI sections in the files above
review wording and defaults for project and issue controls
decide which agent/runtime settings should remain advanced-only
add end-to-end product-level verification for the full UI workflow

3.3 KiB Raw Blame History