mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-16 20:12:20 +01:00
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - `doc/observability.md` and `doc/run-log-events.md` described every OpenTelemetry span and every run-log event > - `rules/data-paths.mdc` told authors to update `doc/run-log-events.md` for each event, so both files only grew: 2,313 and 1,263 lines > - Each span and event is already defined next to the code that writes it, and its name is a literal string that a search finds in one step > - This pull request removes the per-span and per-event catalogs and keeps only what code does not say > - The benefit is two short docs that do not drift from the code, and no rule that makes them grow again ## Linked Issues or Issue Description Refs #21670, #21700, and #21743 (the same cleanup for other docs). **Issue type** Outdated or confusing documentation. **Where is the issue?** `doc/observability.md`, `doc/run-log-events.md`, and `rules/data-paths.mdc` **What's wrong?** The two docs repeated span names, span attributes, and event payloads that the code defines. Operator setup started at line 138 of `doc/observability.md`. The rule required a doc edit for every new run-log event. **Suggested fix** Keep operator setup and the Sentry privacy contract. Point to the code for span and event definitions. Remove the rule line that requires a doc entry per event. ## What Changed - `doc/observability.md` is now 619 lines. It keeps: how to enable tracing, `service.version` resolution, scope, how to enable Sentry, DSN delivery, environment attribution, privacy settings, server request data, the core of "Run failure context", browser data, fail-open behavior, the default capture set, and operator responsibilities. Kept text is unchanged except the intro and two sentences noted below. - Deleted from `doc/observability.md`: budget, Slack receipt, task detail, and browser tracing notes; controller preparation phases; native Runner spans; sandbox startup spans; sandbox duplex transport; shared skill preparation; invocation attribution; and about 500 lines of per-failure detail in "Run failure context". - Replaced that per-failure detail with one paragraph. It names the failures that `unexpected` mode keeps out of Sentry, and says the remaining diagnostic contexts are defined in `server/src/sentry.ts`. "Default capture set" now says the same. - `doc/run-log-events.md` is now 23 lines. It says what the run log is, where events are defined and appended, and keeps the payload storage note. - `rules/data-paths.mdc`: the run-log line now says to define an event where it is written, not in a doc. The span-allowlist line now says the allowlist is in the code that opens the span. The review levels and globs do not change. - Repointed links in two feature maps, two agent-access map files, `tests/runner-e2e/SUITES.md`, `doc/runner-api-tools.md`, and the Telemetry README. Updated the `honeycomb-tracing` skill and one code comment in `packages/adapter-utils/src/http2-bridge-server.ts`. ## Verification - A script built the new `doc/observability.md` from line ranges of the old file and asserts the first line of each range. - A link check on all changed Markdown files found 0 missing files and 0 missing anchors. The remaining inbound anchors (`#enabling-tracing`, `#sentry-error-monitoring`) still exist. - No test reads either doc. - `node scripts/check-maps.mjs` passes. - `node --test .github/scripts/tests/*.test.mjs`: 808 pass, 0 fail. - `pnpm verify` was not run. This worktree has no installed dependencies. The only code change is a comment. ## Risks - The privacy contract no longer lists each run-failure diagnostic context field. `server/src/sentry.ts` is now the list. A reviewer of a Sentry change must read that file. - No browsable list of span names or run-log event names remains. A search for the quoted name finds the producer. - `.greptile/files.json` still scopes `rules/data-paths.mdc` to both docs. Both files still exist, so it does not change. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`), Claude Code desktop, with tool use. Earlier analysis in this session used Claude Fable 5.2. ## 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 - [ ] 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 - [x] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
94 lines
5.8 KiB
Markdown
94 lines
5.8 KiB
Markdown
# Paperclip agent access map
|
|
|
|
This map accompanies the [feature map](../feature-map/README.md). It records APIs,
|
|
agent entry points, permission boundaries and verification for the same capability IDs.
|
|
The [shared contract](../README.md) defines the format and maintenance rules.
|
|
|
|
The [chat scenario catalog](../../tests/runner-e2e/chat-scenarios/README.md) uses
|
|
these same IDs for human requests and expected outcomes. Its scenarios retain
|
|
the access boundaries here; neither a CEO role nor a planned scenario grants
|
|
board authority or establishes a working production tool binding.
|
|
|
|
Use full capability IDs when referring to access contracts outside their file:
|
|
`onboarding/company` means the `company` capability in `onboarding.md` in both maps.
|
|
The [feature index](../feature-map/README.md#browse-features) lists feature and
|
|
capability IDs; [IDs and references](../feature-map/README.md#ids-and-references)
|
|
explains entry-point references and stable naming.
|
|
|
|
## Browse access contracts
|
|
|
|
The same-named feature recipes define navigation and capability IDs. Run
|
|
`node scripts/storybook-catalog.mjs` for the generated
|
|
`maps/generated/agent-access-map.md` index, or browse the
|
|
[published feature guide](https://d1p6rlowie26tp.cloudfront.net/storybook/branches/master/?path=/story/overview-storybook-guide--coverage-guide).
|
|
Add or update the affected companion; there is no central registration or count.
|
|
|
|
Existing baseline source references describe the original inspection, not current
|
|
verification. Record new executed evidence in the PR, issue, or CI artifact with
|
|
its revision and scope. Do not refresh unrelated headers as bookkeeping.
|
|
|
|
## Using an entry
|
|
|
|
Read its Policy and Gaps before selecting an agent path. Native fallback, legacy
|
|
REST/CLI, stdio MCP and a personal assistant connection can have different
|
|
authority and availability. Use a real admitted production binding; a scenario
|
|
declaration is not an installed tool. A `restricted` entry records current
|
|
enforcement and leaves any unresolved delegation decision visible.
|
|
|
|
For API catalog disagreements, follow the route/service authorization and record
|
|
discovery drift. For `not-applicable`, retain the concrete exception and local
|
|
path. Split shared business operations from client-only presentation.
|
|
|
|
Use `maintain-verification-skill` to reconcile changed source and both maps.
|
|
Use `verify-paperclip` and existing API/runner/MCP fixtures to collect the
|
|
permitted-agent and denial evidence; report blocked/not-run coverage honestly.
|
|
Run `node scripts/check-maps.mjs` after editing. The structural check does not
|
|
certify permissions, API catalog coverage, tool admission or live behavior.
|
|
|
|
## Native REST transport
|
|
|
|
The `call_api` parity change reconciles affected baselines against
|
|
`58e16dbddfc9c8d0cf60867f9d9847f0feda055b` and the changes in this PR. Ordinary
|
|
REST operations use the same route authorization as legacy agent REST. Dedicated
|
|
tools remain optional for those operations; protocol endpoints still need their
|
|
existing clients. Board-only routes remain restricted for agent identity.
|
|
|
|
Native `search_api` / `call_api` is enabled by default, but explicit server,
|
|
company-allowlist and binding settings can narrow admission. It requires a running
|
|
authorized native run, current task assignment and execution-run binding, company
|
|
and budget authority, task privacy, and a permitted work mode. Ask and Plan retain
|
|
mutation restrictions, and runs retain their admitted JWT scope during restart
|
|
recovery even when task mode changes. A waiting
|
|
agent does not gain independent native control just because a REST route exists.
|
|
Connection-management reads support Standard, Ask and Plan; mutations require
|
|
Standard. Skill-test runs and nonstandard task-bridge keys cannot administer
|
|
connections. These gates supplement each operation's grants, resolved resource
|
|
and target scope, and responsible-user authority. See the
|
|
[rollout policy](../../server/src/services/native-runtime/runner-api-rollout.ts)
|
|
and [connection authorization](../../server/src/services/connection-management.ts).
|
|
|
|
Credential-bearing replies, including company exports and their legacy alias,
|
|
stay inline under a 10 MiB limit and use encrypted mutation receipts. Other saved
|
|
API snapshots are limited to the issuing actor and responsible user, plus authorized
|
|
administrators. Artifact uploads enforce the same access checks as downloads;
|
|
private snapshots are excluded from company exports and public company logos.
|
|
Explicit deliverables use the existing sharing path. Native event history,
|
|
checkpoints and completion records omit API bodies while preserving receipt
|
|
metadata and replay digests. Restored webhook secrets use the same encrypted
|
|
receipt and inline response policy as newly created webhook secrets.
|
|
Task image access requires the company boundary and the task permission;
|
|
skill-test and low-trust agents do not need company-wide browsing authority.
|
|
Completion replay applies the same idempotent projection to stored and expected
|
|
payloads; its fields are defined where the [run-log event](../../doc/run-log-events.md) is written.
|
|
|
|
Sources: [API client](../../server/src/services/native-runtime/runner-api-client.ts),
|
|
[catalog](../../server/src/services/native-runtime/runner-api-catalog.ts),
|
|
[native authority](../../server/src/services/native-runtime/paperclip-runner-tool-authority.ts),
|
|
[credential storage classification](../../server/src/services/native-runtime/runner-api-sensitive-response.ts),
|
|
[snapshot access](../../server/src/services/asset-content-access.ts),
|
|
and [history redaction](../../server/src/services/native-runtime/runner-api-log-redaction.ts). The affected entries remain
|
|
`baseline` and `source-only`; this reconciliation does not certify every operation.
|
|
Targeted real-route proof lives in the
|
|
[API integration suite](../../server/src/services/native-runtime/runner-api.integration.test.ts),
|
|
including owned routines, skill tests, scoped secrets, proposals and private export replay.
|