Jannik/PaperClipAI
1
0 Fork 0
mirror of https://github.com/paperclipai/paperclip.git synced 2026-10-23 09:07:46 +02:00
Code Issues Packages Projects Releases Wiki Activity
Files
cb2d6e80d3f7ccb6cb6fb1ebbca528a608a9dd0e
PaperClipAI/maps/agent-access-map/instance-operations.md
T
DottaandPaperclip 3bbc2104b6 docs: map missing product and operator capabilities (#16990) 
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - The feature map records product entry points and verification
recipes.
> - The paired agent access map records APIs and permission boundaries
for the same capability IDs.
> - The new index in #16987 made several missing capabilities easier to
find.
> - Those gaps hid existing assistant, privacy, cost, and operator
workflows.
> - This pull request adds 15 capabilities with source references, test
scope, and manual checks.
> - Readers can find these workflows without treating documentation or
structural checks as live proof.

## Linked Issues or Issue Description

Refs: #16987. Related map work: #16025 and #16214. A search of related
pull requests found no duplicate of these additions.

**Issue type**

Missing documentation.

**Where is the issue?**

`maps/feature-map/` and `maps/agent-access-map/`.

**What's wrong?**

The maps omit public assistant MCP connections, private task and project
sharing, subscription fees, cost-recording recovery, agent API keys,
keyboard entry points, and several operator CLI workflows.

**Suggested fix**

Add product recipes and matching access records. Show the full
capability IDs in the README index and each page. Keep the existing ID
format and all 175 existing IDs. Exclude AI account pools.

## What Changed

- Add the `assistant-connections` family with setup, consent, device
login, client use, and revocation.
- Add `tasks/privacy`, `projects/privacy`,
`budgets-costs/subscriptions`, and `budgets-costs/accounting-recovery`.
- Add `agents/api-keys`, `agents/managed-agent-setup`, and
`navigation-preferences/command-palette`.
- Add `cli-operations/feedback-export`, `chat-channels/outbound-email`,
and `instance-operations/runtime-setup`.
- Pair all 15 additions with access rules, source evidence, manual
checks, and explicit coverage gaps. Update the visible index to 35
families and 190 capability IDs.
- Add cross-links from existing access, connection setup, search, and
CLI recipes. Do not change the schema or add AI account pools.
- Clarify that the task Share sheet displays direct and inherited
access. Manage inherited access at its ancestor or project source.

## Verification

- `node scripts/check-maps.mjs` passes: 35 areas and 190 paired
capability IDs, with valid references and contract fields.
- `node --test scripts/check-maps.test.mjs
scripts/storybook-feature-index.test.mjs` passes: 17 tests.
- `node scripts/storybook-feature-index.mjs` and `git diff --check`
pass.
- A comparison with the base confirms all 175 existing IDs remain and
exactly the intended 15 IDs were added. The README index matches the
discovered feature metadata.
- `node scripts/storybook-catalog.mjs` cannot run because this checkout
lacks `storybook/internal/csf-tools` and installed workspace
dependencies.
- `pnpm -r typecheck`, `pnpm test:run`, and `pnpm build` were attempted.
All stopped before their task ran: the pnpm 9.15.4 bootstrap could not
fetch and verify its registry packages in this environment.
- Source review covers the documented UI, CLI, routes, services, and
existing tests. No live browser, provider, or authorization journey was
run. New access records remain `baseline`, `source-only`, and `not-run`.
- Greptile and the Paperclip reviewer both rate current commit
`bb8eb797b0a1dc26256faf2f0e57cbe7abc9adcf` 5/5. The inherited-access
review thread is resolved.
- [GitHub
CI](https://github.com/paperclipai/paperclip/actions/runs/39466772379)
passes for that commit, including typecheck, build, unit tests, Runner
checks, and browser tests. Browser shard 7 passed after one retry for a
runner shutdown. All PR checks are successful, neutral, or skipped.

## Risks

- Low runtime risk: this change only edits maps. No application
behavior, API, dependency, or schema changes.
- Source-reviewed recipes can drift or miss deployment-specific
behavior. The records state their limits and require live checks before
a capability is marked verified.

> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.

## Model Used

- OpenAI Codex, model ID `gpt-6.1-sol`, 475,000-token context window,
xhigh reasoning effort, with tool use and code execution.

## 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>
2026-10-20 12:47:41 -05:00

192 lines
8.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Installation, configuration, updates, and backups — agent access
Product map: [Installation, configuration, updates, and
backups](../feature-map/instance-operations.md).
Feature ID: `instance-operations`.
Review date: 2026-10-12. Source commit: `f981fa3cc10cb8663a87dec60345fbff46d54d0a`.
This is a source-reviewed baseline of representative operations and known gaps.
Each capability needs operation-level review before its entire scope can be
qualified. No live agent execution is claimed. Follow the [map contract](../README.md)
for format, permission checks, evidence and maintenance.
## `install-update`
Capability ID: `instance-operations/install-update`.
Review: `baseline`.
API: `not-applicable` — No uniform company REST updater API. Treat pre-start
installation as an operator exception or design an explicit delegated operator API.
Agent access: `operator-only` — Existing CLI install/update/rollback commands.
Policy: Local machine operator and instance-administrator authority; distinct from
company-scoped agent keys.
Evidence: `source-only` — [implementation](../../cli/src/index.ts#L91) at the reviewed
commit above.
Verification: `not-run` — exercise the listed local workflow in an authorized, owned
operator environment. Verify its isolation and result; do not count local machine
authority as company-agent API access.
Gaps: No uniform company REST updater API. Treat pre-start installation as an operator
exception or design an explicit delegated operator API.
## `server-service`
Capability ID: `instance-operations/server-service`.
Review: `baseline`.
API: `present` — representative operation IDs:
- `GET /api/health`.
Agent access: `operator-only` — Existing CLI service/dev controls; health REST; owned
workspace services have separate agent APIs.
Policy: Local machine operator and instance-administrator authority; distinct from
company-scoped agent keys.
Evidence: `source-only` — [implementation](../../cli/src/index.ts#L91) at the reviewed
commit above.
Verification: `not-run` — exercise the listed local workflow in an authorized, owned
operator environment. Verify its isolation and result; do not count local machine
authority as company-agent API access.
Gaps: Instance start/stop and task workspace start/stop are different capabilities.
Local service control is not agent company authority.
## `configuration`
Capability ID: `instance-operations/configuration`.
Review: `baseline`.
API: `present` — representative operation IDs:
- `GET /api/instance/settings`.
- `PATCH /api/instance/settings`.
- `GET /api/instance/settings/experimental`.
- `PATCH /api/instance/settings/experimental`.
Agent access: `restricted` — Board/admin instance settings; CLI configure/env; local
configuration files.
Policy: Local machine operator and instance-administrator authority; distinct from
company-scoped agent keys.
Evidence: `source-only` — [implementation](../../cli/src/index.ts#L91) at the reviewed
commit above.
Verification: `not-run` — assert the documented agent denial with an owned test fixture;
verify any listed agent request/result path separately. A delegated operation needs its
own policy and access review.
Gaps: Settings APIs cover parts of configuration; pre-start database/binding/storage
configuration is local operator tooling.
Cloud stack Admins may update experimental settings through the trusted Cloud
actor without receiving other instance-admin powers. This uses the current
stack role on each request; company membership alone does not grant it.
Members, Support users, agents, and ordinary self-hosted sessions remain denied.
Cloud staging exposes experimental controls to instance admins and stack Admins.
It permits saved overrides of Cloud-disabled experimental defaults. Cloud-enabled
features remain true on every managed stack, including staging, and the settings
service rejects attempts to disable them with 403 before saving.
This exception requires a managed instance
and a provisioner-supplied `*.staging.paperclip.app` primary hostname; request
headers do not establish staging. Ordinary board members and agents still cannot
mutate instance settings. Only an explicit feature allowlist is editable on staging. Cloud
owner-admin elevation and managed-sandbox execution policy remain managed, and
production policy and other Cloud floors remain.
Local [route tests](../../server/src/__tests__/instance-settings-routes.test.ts)
cover stack Admin experiment access and auditing, denial for other instance
controls and actor sources, hidden-setting restrictions, and a spoofed request hostname;
the [Cloud actor tests](../../server/src/middleware/cloud-tenant-actor.test.ts)
cover role changes and preserved instance-admin isolation;
no live Cloud or agent-credential verification is claimed.
## `diagnostics`
Capability ID: `instance-operations/diagnostics`.
Review: `baseline`.
API: `present` — representative operation IDs:
- `GET /api/health`.
- `GET /api/liveness` and `HEAD /api/liveness` — public process startup status
and build commit only; no database readiness or workspace identity.
Liveness is anonymous and runs before actor/session resolution. Hostname and
signed-bootstrap endpoint validation still apply. It grants no instance control
authority. [Liveness tests](../../server/src/__tests__/liveness.test.ts) cover idle
drain, invalid ambient credentials, unavailable SQL, and startup recovery with
local Express fixtures; no live provider or agent access is claimed.
Agent access: `partial` — REST health plus local CLI doctor.
Policy: Local machine operator and instance-administrator authority; distinct from
company-scoped agent keys.
Evidence: `source-only` — [implementation](../../cli/src/index.ts#L91) at the reviewed
commit above.
Verification: `not-run` — exercise a listed permitted operation with actual agent
credentials/run context; inspect its result and applicable persistence/attribution.
Assert the relevant denied actor, owner, company or mode from Policy. Review the
remaining operations before qualifying the whole capability.
Gaps: Health is an API; full local doctor/repair inspects host configuration and is not
equivalent to that response.
## `backup`
Capability ID: `instance-operations/backup`.
Review: `baseline`.
API: `present` — representative operation IDs:
- `POST /api/instance/database-backups`.
Agent access: `restricted` — Board/admin backup API; local CLI db:backup; restore into
an authorized separate target.
Policy: Local machine operator and instance-administrator authority; distinct from
company-scoped agent keys.
Evidence: `source-only` — [implementation](../../cli/src/index.ts#L91) at the reviewed
commit above.
Verification: `not-run` — assert the documented agent denial with an owned test fixture;
verify any listed agent request/result path separately. A delegated operation needs its
own policy and access review.
Gaps: API creation exists. Restore/lifecycle are operator workflows rather than ordinary
company agent capabilities.
## `runtime-setup`
Capability ID: `instance-operations/runtime-setup`.
Review: `baseline`.
API: `not-applicable` — these commands provision an operator-owned published package and local filesystem cache. They have no company-domain REST equivalent and deliberately bypass instance config, environment, and credential initialization.
Agent access: `operator-only` — explicit host/package provisioning through the runtime CLI, with the installed release’s verified assets. A company agent grant does not authorize another host’s installation or private operator cache.
Policy: Host setup verifies public pinned assets without model calls and requires the published server package layout/identity. Import requires a trusted manifest digest, exact installed source/profile identity, Linux x64 companion inventory/pack/ELF integrity, and a private operator-owned cache. Import performs no downloads or executable probes. A Pi companion does not enable remote Cursor or qualify credentials.
Evidence: `source-only` — reviewed at `9ef434fe79c57d976b8b03b14c5242db270b8320`. [Runtime CLI](../../cli/src/commands/runtime.ts), [instance-config bypass](../../cli/src/index.ts), [Pi provisioning](../../packages/paperclip-runner/scripts/provision-pi.mjs), [Cursor provisioning](../../packages/paperclip-runner/scripts/provision-cursor.mjs), and [companion importer](../../server/src/services/native-runtime/remote-pi-companion.ts).
Verification: `not-run` — Inspect setup identity/path and repeat reuse on an owned disposable published installation. Verify a matching trusted companion import and reject altered/cross-release/linked inventory while preserving unrelated files. Check no instance credentials are loaded and no model is called. Qualify actual adapter/account task execution separately.
Gaps: Source-checkout setup, different platforms, remote Cursor, provider execution, and published-package acceptance remain separate scopes. Local fixture materialization does not establish remote model readiness.
Reference in new issue View Git Blame Copy Permalink