mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-14 00:26:28 +01:00
Nicky LeachandPaperclip
98ce93dd4e
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Projects supply repository files to agent runs through core staging or a storage plugin. > - A storage plugin's default claim silently attached new projects even when their agents used a different environment. > - An environment name or driver type does not establish shared storage access. The existing binding and task-driver contracts do. > - This pull request groups creation choices by that contract and selects storage from the creator's effective environment. > - The benefit is a visible, validated choice and a clear error before an incompatible managed workspace operation. ## Linked Issues or Issue Description Fixes #20459. Related: #20156 covers a separate provider-failure diagnostic. The PR search found no other fix for #20459. ROADMAP.md has no duplicate project-creation change. ## What Changed - Show **Available in** when configured environments require different project storage. Each option names the environments that can use the same storage owner. Hide the selector when all choices are compatible. - Derive compatibility from repository staging and managed binding ownership. Local, SSH, and sandbox environments use core staging. Managed storage requires a registered task driver from the same installed storage plugin. Separate storage plugins remain incompatible. Unknown plugin contracts and the fake sandbox are excluded. - Follow the creating agent's environment, or the person's primary agent, then the instance default and local fallback. Apply managed-only and forced Kubernetes policy. The product has no separate user or company environment-default field today. - Add a company-authorized discovery endpoint and an optional creation `environmentId`. Validate the choice again on save. Store the storage owner without overriding agent run environments. Preserve explicit API storage choices and existing project ownership. - Keep the hidden repository-free private-task project independent of environment availability. Submit the observed storage owner as `expectedStorageProviderPluginId` so a changed contract fails at save without setting a workspace policy. Instance task-isolation defaults stay inherited. - Reject an incompatible managed workspace before a provider operation. Name the storage and selected environment in the error. Add regression tests, API documentation, creation-story fixtures, and minimal corrections to obsolete map text. ## Verification - **102 tests passed across 7 files:** project environment integration, installed storage policy, repository persistence, project environment routes, project creation telemetry routes, OpenAPI, and NewProjectDialog. Run with `node node_modules/vitest/vitest.mjs run server/src/__tests__/project-environments.test.ts server/src/__tests__/project-workspace-provider.integration.test.ts server/src/__tests__/project-repositories-persistence.test.ts server/src/__tests__/project-routes-env.test.ts server/src/__tests__/project-goal-telemetry-routes.test.ts server/src/__tests__/openapi-routes.test.ts ui/src/components/NewProjectDialog.test.tsx --silent`. - The review fixes cover both archived-default private-task cases and changed-storage rejection. With both instance isolation flags enabled, a new core repository project keeps a null policy and resolves to an isolated Git worktree. The complete affected set passes all 102 tests. - The CI query-error policy failure was fixed by using the shared query view. The form and shared query-view suites pass **24 tests**, including cached choices during a transient refetch failure. `node scripts/check-query-error-rendering.mjs --enforce --summary` reports zero findings. - CI exposed stale SDK source hashes and heartbeat fixtures that paired plugin storage with Local. Refreshed exactly four shared-source hashes with the maintained generator (runtime pins unchanged). All **53 SDK privacy/source-proof tests**, including real built SDK output, pass. All **7 corrected managed-storage heartbeat scenarios** pass; the fixtures declare the owning plugin's task environment and substitute transport at the existing execution seam. - Shared and UI TypeScript checks pass. The UI production build passes. `pnpm check:token-gates`, `node scripts/check-maps.mjs`, `node scripts/check-module-boundaries.mjs`, and diff checks pass. - Tested UI states: compatible choices, incompatible groups, default within a group, manual override, create failure, loading, discovery failure and retry, and an unavailable default. Tests use the production form and existing design tokens. - The integration tests use real isolated PostgreSQL on macOS arm64 with Node 26.12.0. They cover user/agent defaults, storage persistence, policy restrictions, company and authentication denials, and rejection before a provider call. Discovery uses saved configuration and makes no worker or provider requests. - Local verification limits: `pnpm -r typecheck` and `pnpm build` stop in unchanged adapter-utils code because the installed ACPX types lack `inheritProcessEnv`. A direct server check also finds an unchanged AI SDK type-version mismatch. The existing heartbeat test `inherits the instance default environment across companies while preserving explicit agent overrides` times out at line 518 on both this change and unmodified master with the same dependencies. The full `pnpm test:run` attempt passed all six chat shards (1,948 tests), then the Git workspace expiration suite reported 14 failures. I stopped that broad run. Two sampled failures reproduce on unchanged master with the same `unknown_worktree_git_files` refusal; the other expiration failures were not independently compared. A later broad workspace-preparation run also hit workspace validation failures and was stopped; the seven corrected fixture scenarios pass independently. These limits do not establish a full local suite pass. Hosted CI remains required. - Initial missing-package and loopback-denial failures were resolved by repairing isolated dependency links, building the SDK, and running database tests with loopback access. No deployed or live-provider execution is claimed. ## Risks - Creation defaults now follow the effective environment. A plugin's `defaultForProjects` claim alone no longer selects storage. This is the intended behavior change. - Compatibility covers repository project storage. It does not guarantee arbitrary host paths, retained-workspace moves, adapter/image support, credentials, or worker readiness. Matching provider configs cannot prove a cross-plugin storage contract. - A person's primary agent supplies the personal default because there is no separate personal environment setting. An unavailable configured default requires a valid explicit choice or a configuration repair. - No migration runs. Existing projects keep their storage owner. This change does not detach existing managed data or provide a storage migration. - Full local verification has the limits listed above. CI and standard Greptile review are pending. ## Model Used OpenAI Codex, based on GPT-6, with reasoning, tool use, and code execution. The exact serving snapshot and context-window size were 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>
71 lines
4.2 KiB
Markdown
71 lines
4.2 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. An environment choice selects storage; it
|
|
is not an allowlist or an override of an agent's run environment.
|
|
|
|
## 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 its storage owner. The project
|
|
is then available to the compatible environments in that group; no single run
|
|
environment is pinned. 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.
|
|
|
|
An unavailable configured default produces an error and permits an explicit
|
|
available choice. It does not silently select another storage owner. 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.
|