Nicky LeachandPaperclip
6204239cfc
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Storage plugins already own project storage and task checkout preparation. > - Core only selected these plugins through an explicit project policy. > - Installation could therefore leave new and existing projects on incompatible Core preparation. > - This pull request adds one generic manifest declaration and one shared effective-policy resolver. > - Project configuration shows inheritance while durable workspace bindings retain their owners. ## Linked Issues or Issue Description **Subsystem affected** Plugin contracts, project configuration, and execution workspace preparation. **Problem or motivation** An installed storage provider cannot become the company default. Projects without an explicit provider keep Core preparation, even when their execution environment cannot use a Core Git checkout. **Proposed solution** A provider declares supported `workspaceProvider.defaultForProjects` mode and strategy. Company-enabled installations supply inherited defaults. Explicit plugin selections and explicit Core/local (`storageProviderPluginId: null`) win. Conflicting defaults require an operator choice. The declaration and implementation contain no provider-specific identifiers. **Alternatives considered** Rewriting every project would lose the distinction between inheritance and overrides. Selecting by worker health would silently change storage on an outage. **Roadmap alignment** Extends the existing workspace and sandbox provider contracts. The roadmap has no duplicate default-provider implementation. Related public work includes #17243, which covers prepared execution directories rather than provider selection. ## What Changed - Add a validated generic default-provider declaration and document it in the SDK. - Resolve provider selection and Git defaults consistently in project responses, source selection, heartbeat source resolution, reservation, and preparation. - Keep stored policy separate from effective configuration. Add the normal project configuration selector for inheritance, explicit plugins, and Core/local. - Preserve existing local and plugin workspace ownership. Pin selection through preparation and keep provider failures visible. - Add database, API, manifest, heartbeat, and UI regressions. Update the verification maps. ## Verification - Targeted Vitest runs cover manifest validation, project defaults and API access, explicit overrides, existing ownership, new/imported task inheritance, heartbeat routing, source-free tasks, selection pinning during setup, and UI configuration. - Combined policy, provider integration, and heartbeat run: 58 tests pass; 60 unrelated cases excluded. After the final shared-provider fallback fix, all 47 policy tests pass, including shared and operator-mode regressions. - Server and UI TypeScript checks, SDK build, verification-map validation, credential-pattern scan, added-comment scan, and `git diff --check` pass. - A downstream integration uses this Core resolver and preparation service with a real storage hook and mocked remote infrastructure. A new Git project reaches the hook without a stored provider ID. - Standard Greptile and Apex both scored 5/5 on5d42998466. All review threads are resolved. - Final GitHub CI is fully green on5d42998466. Browser shard 3 initially hit a PostgreSQL deadlock during cleanup cancellation, which left an experiment flag enabled for a later test. A failed-job retry passed all 26 browser tests. The workflow completed successfully on attempt 2. Full final verification was delegated to CI at the user's request. - No live provider or hosted tenant run was performed. ## Risks - Installing one default-claiming provider changes effective selection for unconfigured projects. Existing explicit settings and workspace ownership remain intact; incompatible explicit settings fail clearly. - Each configuration/admission resolution reads installed plugin metadata and the selected company's enablement. Project list reads share one catalog query. Selection does not call workers or external providers. - Deploy the Core contract before any downstream manifest uses the declaration. No migration or backfill is required. A downstream immutable image pin must include this change before packaging its declaration. - No merge or deployment is authorized by this PR. ## Model Used OpenAI GPT-6 through Codex, with reasoning, repository tools, and code execution. The exact served model ID and context-window size 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 described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links - [x] My branch name describes the change and contains no internal ticket id - [x] I have run targeted tests locally and they pass; full gates are delegated to CI at the user's request - [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 on 5d42998466ad42400564ba34f48124f40c53fbc5; the branch has no merge conflicts - [x] Standard Greptile is 5/5 on5d4299846after all fixes, with no unresolved threads - [x] Apex is 5/5 on5d42998466, after standard Greptile 5/5 on that same head - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>
6.1 KiB
navigation
| navigation | ||||||
|---|---|---|---|---|---|---|
|
Projects and repositories
People group tasks into projects, attach goals and repositories, and configure the context and defaults used by project work.
Feature ID: projects.
Implementation: project list, project detail.
Agent access: companion.
Sub-features
lifecycle:projects/lifecycle— create, name, organize, and archive projects.task-context:projects/task-context— inspect project tasks and create work in the selected project.repositories:projects/repositories— configure repository/workspace sources and verify usable checkouts.defaults:projects/defaults— maintain project instructions, environment, goal, and budget context where offered.privacy:projects/privacy— create private projects, inspect access members, and manage their audience without publishing protected tasks.
How to get to it (user POV)
project-list
Open /projects, create a project, and enter its overview or Issues view.
repository-settings
Open /projects/:projectId/configuration and its repository/workspace settings.
Workspace storage shows the inherited installed default and allows an explicit
provider or Core/local choice. Conflicting defaults remain visible for repair.
project-access
Open /projects/:projectId/configuration, use Private project, and choose Manage access or View access according to your authority. Create a private project through the supported creation surface or API when needed for a fixture.
Driving it with Playwright and the Paperclip CLI
Preconditions: follow the baseline. Use a disposable project and a small repository you can access; record checkout and credential ownership.
project-list
Automated: projects UI and project detail are component tests.
Manual: Create a project, add a task from its view, and reload. Verify the task belongs to that project, list counts are plausible, and links preserve company scope. Archive only the disposable project and inspect list/task behavior.
repository-settings
Automated: provider defaults and API overrides and storage selection UI cover inherited choices, explicit overrides, and configuration errors. These offline checks do not qualify live provider storage.
Automated: repository persistence and repository browser suite cover configured repository workflows.
Manual: Attach a small repository, save, and create a project task. Inspect the actual checkout/revision used by its run. Test an invalid repository and missing credentials without treating a saved URL as a working workspace.
project-access
Automated: Privacy production review covers persisted project audience changes, task inheritance, and actor intersections. Privacy controls covers UI controls and task-cache invalidation after membership removal. These tests do not prove both people’s live navigation.
Manual: As an ordinary authenticated project owner, create a private project and task. Add another company person and an eligible agent through Manage access, reload, and inspect their project discovery and task reads. The added person can view members but cannot change the audience. Remove them, reload their session, and retry direct project/task links. Confirm removing the owner is unavailable or rejected. Add a direct grant for one private task, then open the project to the company after inspecting the confirmation. Verify the project becomes discoverable, protected tasks remain private, and project-derived task access no longer substitutes for direct task access. Test the agent and its responsible person separately.
Sources: Project properties, access members, project routes, and authorization.
Gotchas
-
A private project’s member list is readable to an authorized project reader. Task access-grant inspection has a stricter management boundary.
-
/overviewnow selects Configuration, not a distinct overview page. Personal join/leave and star controls have their own persistence and should be checked when affected; Star/Unstar {project name} is the visible star action. -
Project name slugs change on rename and have no historical alias lookup. Reopen a renamed project through its stable UUID route, wait for the current Configuration form, and record the newly normalized URL before reloading.
-
Project repository configuration and a provisioned execution workspace are different records.
-
See workspaces, goals, and budgets for those features.
-
Do not assume a deleted or archived project should erase its historical task evidence.
Automatic repository skills
Creating or attaching a GitHub repository enqueues skill import without another setup step. Check Skills → Sources and the installed library afterward. Ordinary edits to older projects do not adopt their repositories; explicit adoption belongs in Sources. Removing a repository retains installed skills and originating project access but stops its automatic tracking. Changing the ref does not retarget existing skill references.
Documentation scope: Projects and execution workspaces
Provider-specific provisioning, multi-repository/submodule edge cases, Git reconciliation variants, and all service exposure combinations require deeper recipes.