You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Attribute Paperclip agents by paperclip.agent.id (schema v13) - #165
Paperclip agents have shown up as Anonymous since the ingest-key rollout (#164). The ADR-0028 route — a per-agent COTEL_ACTOR_TOKEN sent as X-Cotel-Actor-Token by Claude Code's otelHeadersHelper — cannot reach them:
Settings are never read. Paperclip runs agents through the Claude Agent SDK with --setting-sources=project,local, so they never read the user settings.json the helper is registered in. This was verified on a live agent process: the right COTEL_ACTOR_TOKEN was in its env, and nothing sent it.
Managed settings break export. With the helper in managed settings, Claude Code drops OTEL_EXPORTER_OTLP_TRACES_ENDPOINT from lower-trust sources, which is where Paperclip puts it. All rpi5 telemetry stopped until the file was removed.
Header values are literal. Paperclip's company header values are sent as-is, and agents can't edit their own env (403 since Paperclip #15283).
Paperclip does tag every agent span with paperclip.agent.id. This PR maps that id to an actor (ADR-0029).
What
Mapping field.actors.paperclip_agent_id (schema v13) is returned on GET /actors[/{id}] and set or cleared with PATCH /api/v1/actors/{id} ({"paperclip_agent_id": "<uuid>"|""}). One actor per agent id; assigning an id that another actor holds moves it.
Ingest order:
An actor token wins.
Otherwise, only if an ingest key authorized the request, the actor mapped to the span's paperclip.agent.id. The id is read from the resource attributes, else from the span's own.
Otherwise Anonymous.
Unauthenticated senders cannot claim an agent. Lookups are memoized per request.
UI. A "Paperclip agent" card on the actor page and a tag in the Actors list.
Docs. ADR-0029 (amends 0028 for agents), the auth guide (Paperclip setup), the API reference and CHANGELOG. agent-set-cotel-token.sh is marked obsolete.
Verification
go vet and TZ=UTC go test ./.... New tests cover:
storage: set, move, clear, deleted actor;
ingest: resource vs span attribute, token wins, no ingest key → ignored, one lookup per agent per batch;
middleware: only ingest-key requests are marked;
API: PATCH validation and normalisation, 404s.
tsc, frontend build, vitepress build.
End-to-end on a local build: key + resource attr → mapped actor; key + span attr → mapped actor; no auth + attr → Anonymous. The card was checked in a browser.
After merge
Map the 14 Paperclip agents to their actors (names match; Clio = Summarizer, Argus = Reflection Coach). The X-Cotel-Actor-Token header row in Paperclip's company settings can be removed.
Link Paperclip agent IDs to actors to attribute eligible incoming spans. Actor-token identity takes precedence; unmapped agents remain anonymous.
Manage an actor’s Paperclip agent ID from the actor details page, including setting or clearing the mapping. The actors list labels actors with a mapping.
Documentation
Added guidance on Paperclip attribution, actor mappings, and the actor update API.
…a v13)
The ADR-0028 helper route could not reach Paperclip agents: Paperclip
runs them through the Claude Agent SDK with --setting-sources=project,local,
so they never read the user settings.json the otelHeadersHelper lives in;
registering the helper in managed settings instead makes Claude Code drop
the OTLP endpoint Paperclip sets ("lower-trust scopes cannot redirect the
traces signal"); Paperclip header values are literal; and agents cannot
change their own env. Paperclip does tag every agent span with
paperclip.agent.id, so cotel maps that id to an actor (ADR-0029).
- actors.paperclip_agent_id (schema v13), returned on GET /actors[/{id}]
and set or cleared with PATCH /api/v1/actors/{id}. One actor per agent
id, kept in a transaction (no UNIQUE constraint: DuckDB has raised false
duplicate-key errors on updates of such rows).
- Ingest: an actor token still wins; otherwise, only when an ingest key
authorized the request, the span goes to the actor mapped to its
paperclip.agent.id (resource attributes, else the span's own); otherwise
Anonymous. Unauthenticated senders cannot claim an agent. Lookups are
memoized per request.
- Actor page: a "Paperclip agent" card to set the id; Actors list tags
mapped actors.
- Docs: ADR-0029 (amends 0028 for Paperclip agents), auth guide, API
reference, CHANGELOG; agent-set-cotel-token.sh marked obsolete.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This change adds Paperclip agent IDs to actor records and exposes mapping updates through the actor API and frontend. Ingest requests authenticated with a shared ingest key can use mapped IDs to attribute spans when no actor token identifies the actor.
Changes: Paperclip agent attribution
Layer / File(s)
Summary
Persist and resolve agent mappings internal/storage/schema.sql, internal/storage/actors.go, internal/storage/*test.go
The schema adds a nullable paperclip_agent_id actor field. Storage supports retrieving, assigning, clearing, and resolving mappings. Tests cover reassignment, clearing, and deleted actors.
Resolve identity during ingestion internal/ingest/*, internal/api/auth/middleware.go, internal/api/auth/ingest_middleware_test.go
Ingest-key authentication marks request context. The handler checks resource attributes before span attributes, caches agent lookups per request, and preserves actor-token precedence. Tests cover attribution conditions and lookup behavior.
Manage mappings through the actor API and UI internal/api/actors.go, internal/api/actors_list_test.go, frontend/src/api/index.ts, frontend/src/pages/ActorDetail.*, frontend/src/pages/Actors.*
The actor API returns and updates mappings, with UUID validation and clear support. The actor detail page provides mapping controls, and the actors list marks mapped actors.
Document attribution and setup CHANGELOG.md, docs/decisions/*, docs/operations/actors-and-auth.md, docs/operations/api-reference.md, docs/.vitepress/config.js, scripts/agent-set-cotel-token.sh
The documentation describes the attribution rules, mapping setup, and actor PATCH endpoint. The script comments note that Paperclip agents use agent-ID attribution.
sequenceDiagram
participant IngestMiddleware
participant IngestHandler
participant AgentResolver
participant DB
IngestMiddleware->>IngestHandler: Forward request context with ingest-key authorization and optional actor name
IngestHandler->>AgentResolver: Resolve resource agent ID, then span agent ID if needed
AgentResolver->>DB: Look up actor name by Paperclip agent ID
DB-->>AgentResolver: Return mapped actor name or empty name
AgentResolver-->>IngestHandler: Return cached resolution
IngestHandler->>IngestHandler: Decode spans with resolved actor identity
Loading
Merge Risk: Low · up to 3d403
Spans from ingest-key-authorized Paperclip agents may be attributed through the span-level agent ID when the resource-level ID is set but unmapped. This differs from the stated "resource, else span" intent. The impact is bounded to attribution accuracy, so the author should confirm or clarify the intended fallback before merging.
Pre-merge checks: 4
Check name
Status
Explanation
Description Check
Check skipped - CodeRabbit’s high-level summary is enabled.
Title check
The title "Attribute Paperclip agents by paperclip.agent.id (schema v13)" matches the main change. The PR adds a paperclip_agent_id field to actors, a PATCH endpoint to set it, ingest attribution by p…
Linked Issues check
Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check
Check skipped because no linked issues were found for this pull request.
Full details: Title check
Explanation
The title "Attribute Paperclip agents by paperclip.agent.id (schema v13)" matches the main change. The PR adds a paperclip_agent_id field to actors, a PATCH endpoint to set it, ingest attribution by paperclip.agent.id for ingest-key requests, and the schema bump to v13. The title is specific and does not list files.
Finishing Touches
Generate unit tests (beta)
Commit to this branch
Create a new PR
Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.
The reason will be displayed to describe this comment to others. Learn more.
Additional comments: 1
internal/ingest/handler.go-117-117: 1
117-117: Major · Data Integrity & Integration · Quick win
Unverified finding
Verification ran but could not confirm this finding. It is shown for review, not as a verified issue.
Use the resource attribute's presence to control span fallback.
With a valid ingest key, an unmapped resource agent ID resolves to "". This condition then accepts a mapped span agent ID and attributes the span to that actor.
The required fallback applies only when the resource agent ID is absent. Preserve the resource agent ID and check its absence before resolving the span attribute. An unmapped resource agent ID must remain Anonymous.
Review info
Run configuration
Source mode: Auto
Repository: Unavailable
Branch: Unavailable
File: No configuration file from this repository applied
Commit: Unavailable
Layers: defaults
Review profile: CHILL
Plan: Advanced
Run ID: f4679da1-6b9e-4820-8a32-69f296f49e1a
Commits
Reviewing files that changed from the base of the PR and between 474672a and 3d40349.
Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
Paperclip agents have shown up as Anonymous since the ingest-key rollout (#164). The ADR-0028 route — a per-agent
COTEL_ACTOR_TOKENsent asX-Cotel-Actor-Tokenby Claude Code'sotelHeadersHelper— cannot reach them:--setting-sources=project,local, so they never read the usersettings.jsonthe helper is registered in. This was verified on a live agent process: the rightCOTEL_ACTOR_TOKENwas in its env, and nothing sent it.OTEL_EXPORTER_OTLP_TRACES_ENDPOINTfrom lower-trust sources, which is where Paperclip puts it. All rpi5 telemetry stopped until the file was removed.Paperclip does tag every agent span with
paperclip.agent.id. This PR maps that id to an actor (ADR-0029).What
Mapping field.
actors.paperclip_agent_id(schema v13) is returned onGET /actors[/{id}]and set or cleared withPATCH /api/v1/actors/{id}({"paperclip_agent_id": "<uuid>"|""}). One actor per agent id; assigning an id that another actor holds moves it.Ingest order:
paperclip.agent.id. The id is read from the resource attributes, else from the span's own.Unauthenticated senders cannot claim an agent. Lookups are memoized per request.
UI. A "Paperclip agent" card on the actor page and a tag in the Actors list.
Docs. ADR-0029 (amends 0028 for agents), the auth guide (Paperclip setup), the API reference and CHANGELOG.
agent-set-cotel-token.shis marked obsolete.Verification
go vetandTZ=UTC go test ./.... New tests cover:PATCHvalidation and normalisation, 404s.tsc, frontend build,vitepress build.After merge
Map the 14 Paperclip agents to their actors (names match; Clio = Summarizer, Argus = Reflection Coach). The
X-Cotel-Actor-Tokenheader row in Paperclip's company settings can be removed.🤖 Generated with Claude Code
Summary by CodeRabbit