mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-20 18:26:40 +01:00
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - A volume-free server admits a run only when its task files have
durable storage.
> - A project can keep its task files in plugin storage, such as an
agent-computers plugin. Only environments of that plugin can use that
storage.
> - A task keeps its selected source when it moves to another project.
So the source project's storage still applies after the move.
> - When an agent in a Daytona sandbox got such a task, the volume-free
check refused the run with a generic message. The message said "native
Paperclip Runner with remote workspace storage". The agent already used
native Paperclip Runner.
> - The run ended `setup_failed`. The task offered Retry, but Retry
always failed the same way. Sentry received the refusal as an unexpected
run failure.
> - This pull request finds the real cause with the existing
project-storage compatibility rule. It records the refusal as a
configuration problem that an owner must repair.
> - The benefit is a message that names the storage and the environment,
a task notice with the correct owner action, and no Sentry noise for
this known configuration state.
## Linked Issues or Issue Description
Related: #17552 (a task project and its selected workspace are separate
settings, so a moved task keeps its source).
**What happened?**
On a volume-free server, a task's source project used plugin storage.
The assigned agent used a sandbox environment that cannot use that
storage. Workspace preparation refused the run with "Volume-free servers
require native Paperclip Runner execution with remote workspace
storage." The run failed with `setup_failed`. The task notice told the
user to press Retry. Each retry failed the same way. Sentry received
each refusal as an unexpected run failure.
**Expected behavior**
The refusal names the real cause: the project's workspace storage does
not support the agent's environment. The run fails
`configuration_incomplete`. The task notice tells the owner to use an
agent in a compatible environment, or a source from a project for this
environment. Sentry does not receive this known configuration state.
**Steps to reproduce**
1. Start the server with `PAPERCLIP_EPHEMERAL_SERVER=true`.
2. Create a project whose storage is a plugin workspace provider.
3. Assign a task in that project to a Paperclip Runner agent in a
Daytona sandbox environment.
4. Wake the agent. The run fails `setup_failed` with the generic
volume-free message.
5. Move the task to a project without plugin storage and comment "try
again". The task keeps its source, and the run fails the same way.
**Paperclip version or commit**
Seen on a hosted volume-free staging server. The new regression test
fails on `master` at 201abacd6e and passes with this change.
## What Changed
- Workspace preparation keeps the volume-free admission rule. When that
rule refuses a run, it checks the task source project's storage provider
against the selected environment with the existing
`assertProjectStorageEnvironment` rule.
- On a mismatch, the run fails with `ConfigurationIncompleteFailure`,
reason `project_storage_environment_incompatible`. The message is the
existing message that names the storage and the environment. The payload
records the provider, the environment, and a stable fingerprint.
- Refusals with any other cause keep the original volume-free error.
- The configuration-incomplete task notice and the recovery next action
name this owner action. Before this change, an unknown reason fell back
to the "missing secret" text.
- Run-failure reporting skips this exact pre-dispatch outcome, like
`ai_connection_required` and `workspace_source_restricted`. A marker
after provider work started, during execution, or without
`configuration_incomplete` is still reported.
- `doc/project-environment-compatibility.md` and
`doc/workspace-storage.md` describe the new outcome.
## Verification
- Red before the fix, green after:
- `server/src/services/heartbeat/workspace-preparation.test.ts` › "names
an incompatible project storage environment when a volume-free server
rejects the run". Before the fix, the run failed with HTTP 422
`ephemeral_execution_configuration_required`. After the fix, it fails
with `configuration_incomplete` and the storage and environment message.
The same test confirms that an unavailable provider keeps the original
error. It also confirms that no workspace is resolved or acquired.
- `server/src/services/__tests__/run-failure-report.test.ts` › "keeps a
run refused for incompatible project workspace storage actionable on the
task". Before the fix, Sentry received the run.
- `server/src/services/recovery/stranded-notice.test.ts` › "names
incompatible project workspace storage instead of a missing secret".
Before the fix, the notice said that a secret was missing.
- Safety cases: three marker variants are still reported (executing
stage, `setup_failed`, provider work started).
- Commands (local, Node 25, embedded Postgres):
- `pnpm --filter @paperclipai/server exec vitest run
src/services/heartbeat/workspace-preparation.test.ts
src/services/__tests__/run-failure-report.test.ts
src/services/recovery/stranded-notice.test.ts` (482 passed)
- `pnpm --filter @paperclipai/server exec vitest run
src/__tests__/ephemeral-server-contract.test.ts
src/__tests__/project-environments.test.ts
src/__tests__/task-workspace-binding.test.ts
src/__tests__/agent-project-access.test.ts` (passed)
- `pnpm --filter @paperclipai/server typecheck`
## Risks
- Low risk. The new path runs only after the volume-free rule has
already refused the run, so no run that started before can fail now.
- The only behavior change for those refused runs is the failure code,
the message, the notice, and the Sentry decision.
- One extra plugin-provider read happens only on that refusal path.
- A task that moved projects still keeps its selected source. This
change does not alter that contract. The owner must choose a compatible
agent or a new source.
## Model Used
- Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, with tool use and code
execution in a sandboxed workspace.
## 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
- [ ] I will address all Greptile and reviewer comments before
requesting merge
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: paperclipbugbot <356415228+paperclipbugbot@users.noreply.github.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
101 lines
6.0 KiB
Markdown
101 lines
6.0 KiB
Markdown
# Project environments and repository storage
|
|
|
|
A repository project belongs to one storage owner. Creation shows **Available in**
|
|
when the configured environments require more than one owner. Each choice names
|
|
all environments that use that owner. The choice selects storage only. It is not
|
|
an allowlist, and it does not override an agent's run environment. A project has
|
|
no run environment of its own.
|
|
|
|
## Compatibility rule
|
|
|
|
Use the existing workspace execution contract, not environment names, driver
|
|
names alone, images, operating systems, endpoints, or complete config equality:
|
|
|
|
- Local, SSH, and sandbox environments use core repository staging. They can use
|
|
the same repository project even across driver types and sandbox providers.
|
|
- Plugin-managed storage belongs to an installed plugin ID. It can be consumed
|
|
only by that plugin's registered `environment_driver` with `supportsTasks: true`.
|
|
Its manifest must declare `environment.drivers.register`, `workspaces.manage`,
|
|
a workspace provider, and the project resource lifecycle.
|
|
- Two task environments from that installed plugin share its project storage
|
|
contract, even when their other settings differ. Storage operations are scoped
|
|
by company, project, and plugin; they do not take an environment configuration.
|
|
Separate installed storage plugins remain incompatible even when both use the
|
|
`plugin` driver. Core cannot transfer their managed bindings between them.
|
|
- Unknown plugin drivers and the probe-only fake sandbox do not establish a
|
|
compatible project storage contract. They are excluded from creation choices.
|
|
|
|
These are project repository compatibility rules. They do not assert that
|
|
arbitrary local paths exist remotely, that a retained task workspace can switch
|
|
hosts, or that an adapter, credential, image, or running worker is ready. Existing
|
|
run-time validation still checks those conditions. Cross-plugin storage sharing
|
|
would require a new execution/storage contract; matching config fields cannot
|
|
establish it.
|
|
|
|
## Defaults and validation
|
|
|
|
For an agent API request, use that agent's default environment. For a person,
|
|
use their primary agent's default environment when present. Fall back to the
|
|
instance default, then local execution. There is no separate user or company
|
|
`defaultEnvironmentId` setting today. Managed-only and forced Kubernetes policies
|
|
retain their execution restrictions and default redirection.
|
|
|
|
`GET /api/companies/:companyId/project-environments` returns environment IDs and
|
|
names grouped by storage owner, plus the caller's effective default. It excludes
|
|
archived environments, disabled/uninstalled storage plugins, and managed
|
|
environments bound only to another company. It does not contact workers or return
|
|
provider configs, credentials, endpoints, or host paths. A cold worker does not
|
|
change a durable storage choice.
|
|
|
|
`POST /api/companies/:companyId/projects` accepts an optional `environmentId`.
|
|
The server validates the choice again and stores only its storage owner. The
|
|
project is then available to the compatible environments in that group; no single
|
|
run environment is saved. An explicit `executionWorkspacePolicy.storageProviderPluginId`
|
|
continues to work. The UI sends both the environment and its observed storage
|
|
owner in `expectedStorageProviderPluginId`, so a changed environment cannot
|
|
silently select different storage. This guard does not create a workspace-mode
|
|
policy; instance task-isolation defaults remain inherited. An explicit policy
|
|
and environment must agree when both are supplied. Without either,
|
|
storage follows the caller's effective environment. A plugin's
|
|
`defaultForProjects` claim alone no longer attaches a project to that plugin.
|
|
|
|
The hidden repository-free “My private tasks” project is independent of
|
|
environment/storage availability, so creating a private note never requires
|
|
repairing an environment.
|
|
|
|
When the configured default is unavailable and only one storage owner is
|
|
available, that owner becomes the default, because there is nothing to choose.
|
|
When two or more owners are available, an unavailable default produces an error
|
|
and permits an explicit available choice. It does not silently select another
|
|
storage owner. The UI shows the **Available in** selector only when there are two
|
|
or more storage owners. Existing
|
|
projects keep their stored owner. This change does not migrate managed storage
|
|
or detach projects that contain existing work. A managed project run in an
|
|
incompatible environment fails with `project_environment_incompatible` before a
|
|
workspace provider operation, with a message naming the storage and environment.
|
|
On a volume-free server, execution admission refuses that run earlier. When the
|
|
task source's project storage cannot serve the selected environment, the run
|
|
fails `configuration_incomplete` with reason
|
|
`project_storage_environment_incompatible` and the same message. The task notice
|
|
names the owner action, and run-failure reporting does not send it to Sentry.
|
|
A task that moves to another project keeps its selected source, so the source
|
|
project's storage still decides compatibility.
|
|
|
|
## Project Configuration
|
|
|
|
Storage is fixed when the project is created. `PATCH /api/projects/:id` rejects a
|
|
change of `executionWorkspacePolicy.storageProviderPluginId` with `409`
|
|
`project_storage_locked`, in both directions: core to plugin and plugin to core.
|
|
A policy update that omits the storage owner keeps the stored owner.
|
|
|
|
Project Configuration has no storage or environment control. When a storage plugin
|
|
is installed, or the project uses one, it shows an advisory **Available in** list:
|
|
the environments that can use the project's storage. If the project's storage
|
|
plugin is no longer installed, it shows **Storage plugin unavailable**. Without a
|
|
storage plugin, the advisory is hidden.
|
|
|
|
Runs use the agent default, then the instance default, then local execution. An
|
|
operator-selected low-trust task sandbox and enforced sandbox policies retain
|
|
precedence. A project does not change run placement. Older clients may still send
|
|
`executionWorkspacePolicy.environmentId`; the service drops it.
|