mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-22 16:51:28 +02:00
DottaandPaperclip
8b6a06ee25
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Operators need first-party agent capabilities for repeatable company work, not just manually created one-off agents. > - Built-in agents need to behave like normal company-scoped agents while preserving approval gates, permissions, budgets, and audit trails. > - Reflection and coaching work also needs bundled instructions, skill content, and a routine so the feature can be installed and reset predictably. > - The API, database, UI, portability, and tests all need to agree on the built-in lifecycle from not provisioned through setup, approval, ready, paused, and reset. > - This pull request adds built-in agent provisioning and the Reflection Coach bundle end-to-end. > - The benefit is a safer first-party path for Paperclip-managed agents without bypassing the same governance model used for operator-created agents. ## Linked Issues or Issue Description No public GitHub issue was found for this exact built-in agent and Reflection Coach bundle work. Problem/motivation: - Paperclip did not have a first-party built-in agent lifecycle for product-owned agents. - Bundled agent resources such as default instructions, skills, and routines needed managed ownership and reset semantics. - Approval-gated companies needed built-in setup to preserve requested adapter, budget, manager, and permission state through board approval. - The board UI needed clear built-in badges, setup affordances, readiness state, and bundle status without exposing secrets. Proposed solution: - Add a company-scoped built-in agent registry, provisioning/reset/reconcile/status APIs, and Reflection Coach bundled resources. - Track bundled managed resources in the database with idempotent migration behavior. - Reuse existing agent approval, authorization, budget, and activity-log paths instead of creating a bypass. - Add UI setup, badges, gates, bundle panels, and route coverage for built-in agents. Duplicate search: - Searched GitHub PRs for `built-in agents Reflection Coach repo:paperclipai/paperclip`; only this PR was returned. - Searched GitHub issues for the same query; no public issues were returned. ## What Changed - Added built-in agent definitions, lifecycle state derivation, provisioning, reset, reconcile, status, and routine-control routes. - Added the `built_in_managed_resources` migration and schema exports for bundled instructions, skill, and routine ownership. - Added the Reflection Coach built-in bundle with default instructions, skill catalog content, routine template, default permissions, and managed-resource drift handling. - Added approval-aware provisioning behavior that preserves requested adapter config, budgets, manager assignment, and built-in permissions through hire approval. - Added authorization and mutation gates for built-in agent and skill changes, including consented Reflection Coach change paths. - Added UI surfaces for built-in agent setup, roster/detail badges, readiness gates, bundle status, routine controls, and route filtering. - Added company import/export and validator coverage for built-in managed resources and low-trust/red-team presets. - Addressed Greptile follow-ups for pending approval reconciliation, consent-gate error propagation, config-read authorization fallback, approval-path manager preservation, and non-model adapter provisioning. ## Verification Local verification: - `git diff --check public/master..HEAD` passed. - `pnpm check:token-gates` passed with all gates clean. - `pnpm exec vitest run ui/src/components/ConfigureBuiltInAgentModal.test.tsx` passed: 1 file, 4 tests. - `pnpm exec vitest run ui/src/components/EntityRow.test.tsx ui/src/pages/Agents.test.tsx ui/src/components/BuiltInAgentGate.test.tsx ui/src/components/ConfigureBuiltInAgentModal.test.tsx ui/src/components/BuiltInBundlePanel.test.tsx ui/src/pages/InstanceExperimentalSettings.test.tsx ui/src/pages/Routines.test.tsx` passed: 7 files, 64 tests. - `pnpm --filter @paperclipai/server exec vitest run src/__tests__/built-in-agents.test.ts src/__tests__/authorization-service.test.ts src/__tests__/company-skills-routes.test.ts` passed: 3 files, 91 tests. - `pnpm --filter @paperclipai/db check:migrations` passed. - `pnpm -r typecheck` passed after the rebase; `pnpm --filter ui typecheck` passed after the final UI review fix. Remote verification on latest head `1c61f693a4ec881d739022b0e75a8ca8bf8c2cd8`: - Merge state: `CLEAN`. - Greptile: `5/5`, zero unresolved Greptile threads. - PR check rollup: all checks successful, neutral, or skipped as expected. - Passing gates include Build, Typecheck + Release Registry, all server shards, all workspace shards, all serialized server suites, e2e, Canary Dry Run, policy, review, verify, Socket, Superagent, and Snyk. ## Risks - This adds a new managed-resource table and migration; the migration uses idempotent create/add/index guards and passed migration safety checks. - Built-in agent provisioning touches approval and authorization paths; tests cover pending approval preservation, stale retry rejection, consent gates, and config-read fallback behavior. - Reflection Coach creates managed instructions, skill, and routine resources; drift/reset behavior is covered by service tests and redacted API responses. - Non-model adapter setup now provisions a `needs_setup` built-in row before command/endpoint fields are complete; this matches the server lifecycle and is covered by the setup modal regression test. ## Model Used OpenAI Codex coding agent based on GPT-5. Exact hosted model ID, context-window size, and reasoning-mode labels are not exposed in this runtime; tool use, shell execution, GitHub CLI/API access, and local code editing 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>
60 lines
2.7 KiB
Markdown
60 lines
2.7 KiB
Markdown
# Low-Trust Presets
|
|
|
|
Paperclip ships core trust preset names so containment decisions are enforced in
|
|
Community Edition even when EE policy editing is unavailable.
|
|
|
|
## Presets
|
|
|
|
- `standard`: the default V1 company-visible collaboration model. This preserves
|
|
existing behavior for normal agents.
|
|
- `low_trust_review`: an opt-in containment preset for automated work that may
|
|
consume hostile or prompt-injected input, such as untrusted pull requests,
|
|
external tickets, dependency diffs, or generated review output.
|
|
|
|
## Boundary Model
|
|
|
|
`low_trust_review` is resolved from existing JSON policy fields:
|
|
|
|
- agent permissions: `permissions.trustPreset` and
|
|
`permissions.authorizationPolicy.trustBoundary`
|
|
- project policy:
|
|
`executionWorkspacePolicy.authorizationPolicy.trustBoundary`
|
|
- issue/run policy: `executionPolicy.authorizationPolicy.trustBoundary`
|
|
|
|
The resolver intersects those sources. Narrower wins. A low-trust preset must
|
|
resolve to a concrete company-local project, root issue, or issue-id scope. If a
|
|
policy source names another company, uses an unsupported preset, or lacks that
|
|
scope for risky access, Paperclip fails closed.
|
|
|
|
## Containment, Not Privacy
|
|
|
|
This is containment for hostile automated work. It is not a general project,
|
|
issue, or human privacy system.
|
|
|
|
V1 standard work remains company-visible by default: board users and in-company
|
|
actors can inspect company work objects unless a separate access-control feature
|
|
changes that behavior. Low-trust containment instead limits what the low-trust
|
|
agent can read or mutate through the Paperclip API and prevents raw untrusted
|
|
output from being automatically promoted into higher-trust agent context.
|
|
|
|
Low-trust agents cannot read or mutate agent configuration, instruction bundles,
|
|
or company skill configuration through direct grants. Configuration changes from
|
|
low-trust work must go through higher-trust review and promotion paths instead.
|
|
|
|
## Runtime Containment
|
|
|
|
Managed `low_trust_review` runs fail closed unless Paperclip can enforce the
|
|
runtime boundary:
|
|
|
|
- the selected execution environment must use the `sandbox` driver
|
|
- the effective execution workspace mode must be `isolated_workspace`
|
|
- the issue being run must be inside the resolved low-trust boundary
|
|
- secret references must use binding ids explicitly allowed by the boundary
|
|
- inline sensitive environment values such as API keys and tokens are rejected
|
|
- workspace runtime-service mutations are denied unless the boundary explicitly
|
|
grants the `runtime.manage` tool class
|
|
|
|
The Docker workflow in `doc/UNTRUSTED-PR-REVIEW.md` remains useful for manual
|
|
local review, but Paperclip-managed low-trust execution requires a sandboxed
|
|
environment instead of a host-local adapter process.
|