Files
PaperClipAI/doc/project-environment-compatibility.md
T
7ef731ec7e fix(workspaces): name incompatible project storage when a volume-free server refuses a run (#22398)
## 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>
2026-11-20 05:17:37 -08:00

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.