Skip to content

Attribute Paperclip agents by paperclip.agent.id (schema v13) - #165

Merged
Fl0p merged 1 commit into
mainfrom
paperclip-agent-mapping
Nov 15, 2026
Merged

Fl0p merged 1 commit into
mainfrom
paperclip-agent-mapping

Conversation

@Fl0p

@Fl0p Fl0p commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

Why

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:

    1. An actor token wins.
    2. 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.
    3. 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.

🤖 Generated with Claude Code

Summary by CodeRabbit

  • New Features
    • 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>
@coderabbitai

coderabbitai Bot commented Nov 15, 2026 •

Copy link
Copy Markdown

Explain Change →

Walkthrough

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.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Feature

Sequence Diagram(s)

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: Passed 4

Check name Status Explanation
Description Check Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check Passed 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 Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed 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.

Share

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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.

Files selected for processing: 24

  • CHANGELOG.md
  • docs/.vitepress/config.js
  • docs/decisions/0028-ingest-keys-and-actor-tokens.md
  • docs/decisions/0029-paperclip-agents-by-agent-id.md
  • docs/decisions/index.md
  • docs/operations/actors-and-auth.md
  • docs/operations/api-reference.md
  • frontend/src/api/index.ts
  • frontend/src/pages/ActorDetail.module.css
  • frontend/src/pages/ActorDetail.tsx
  • frontend/src/pages/Actors.module.css
  • frontend/src/pages/Actors.tsx
  • internal/api/actors.go
  • internal/api/actors_list_test.go
  • internal/api/auth/ingest_middleware_test.go
  • internal/api/auth/middleware.go
  • internal/ingest/context.go
  • internal/ingest/handler.go
  • internal/ingest/handler_test.go
  • internal/storage/actors.go
  • internal/storage/ingest_keys_test.go
  • internal/storage/paperclip_agent_test.go
  • internal/storage/schema.sql
  • scripts/agent-set-cotel-token.sh

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

@Fl0p
Fl0p merged commit 8c88d83 into main Nov 15, 2026
12 checks passed
@Fl0p
Fl0p deleted the paperclip-agent-mapping branch November 15, 2026 14:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant