From 3d40349cf2860d3b2d5953c5b6d2d8a29fb3156f Mon Sep 17 00:00:00 2001 From: FlopBut Date: Sun, 15 Nov 2026 15:36:18 +0100 Subject: [PATCH] feat(ingest): attribute Paperclip agents by paperclip.agent.id (schema 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 --- CHANGELOG.md | 1 + docs/.vitepress/config.js | 1 + .../0028-ingest-keys-and-actor-tokens.md | 2 +- .../0029-paperclip-agents-by-agent-id.md | 75 ++++++++++++ docs/decisions/index.md | 1 + docs/operations/actors-and-auth.md | 16 ++- docs/operations/api-reference.md | 14 ++- frontend/src/api/index.ts | 15 +++ frontend/src/pages/ActorDetail.module.css | 94 +++++++++++++++ frontend/src/pages/ActorDetail.tsx | 113 +++++++++++++++++- frontend/src/pages/Actors.module.css | 10 ++ frontend/src/pages/Actors.tsx | 9 +- internal/api/actors.go | 47 ++++++++ internal/api/actors_list_test.go | 45 +++++++ internal/api/auth/ingest_middleware_test.go | 43 +++++++ internal/api/auth/middleware.go | 5 +- internal/ingest/context.go | 17 +++ internal/ingest/handler.go | 55 ++++++++- internal/ingest/handler_test.go | 82 +++++++++++++ internal/storage/actors.go | 84 +++++++++++-- internal/storage/ingest_keys_test.go | 4 +- internal/storage/paperclip_agent_test.go | 85 +++++++++++++ internal/storage/schema.sql | 8 +- scripts/agent-set-cotel-token.sh | 5 + 24 files changed, 810 insertions(+), 21 deletions(-) create mode 100644 docs/decisions/0029-paperclip-agents-by-agent-id.md create mode 100644 internal/storage/paperclip_agent_test.go diff --git a/CHANGELOG.md b/CHANGELOG.md index ec61cfb..f6ec803 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] ### Added +- **Paperclip agents are attributed by `paperclip.agent.id`** ([ADR-0029](docs/decisions/0029-paperclip-agents-by-agent-id.md)). Each actor gets an optional Paperclip agent id (schema v13; the actor page, or `PATCH /api/v1/actors/{id}` with `{"paperclip_agent_id"}`), and a span authorized by an ingest key with no actor token is attributed to the actor whose id matches the `paperclip.agent.id` Paperclip puts on every agent span - from the resource attributes, else the span's. Paperclip's company observability then needs only the ingest key, and agents on remote machines are covered too. The ADR-0028 helper route could not reach agents: Paperclip runs them through the Claude Agent SDK with `--setting-sources=project,local`, so they never read the user `settings.json` the helper is registered in, and putting the helper in managed settings makes Claude Code drop the endpoint Paperclip sets. The attribute is honoured only behind an ingest key, so an unauthenticated sender cannot claim an agent; an actor token still wins; lookups are memoized per request - **Ingest keys: one shared key authorizes, each sender's actor token identifies** ([ADR-0028](docs/decisions/0028-ingest-keys-and-actor-tokens.md)). Paperclip now strips every `OTEL_*` and `CLAUDE_CODE_*TELEMETRY*` variable from an agent's env and applies one company-wide set of OTLP headers, so a per-agent `Authorization: Bearer ` can no longer be configured, and with that setting empty it turns telemetry off, which is why agent telemetry stopped on 2026-11-07. An ingest key (`cotel_ik_<64 hex>`, created, copied and revoked under Setup → Settings → Ingest keys, stored in plaintext like actor tokens) authorizes OTLP ingest and nothing else, never export/import or the dashboard; the existing actor token, unchanged and not reissued, rides next to it in `X-Cotel-Actor-Token`. A valid key with a missing or unknown actor token is accepted as Anonymous even when allow-anonymous is off, because the request was authorized; `X-Cotel-Actor-Token` without a bearer never identifies anyone, and a bearer actor token works exactly as before. Schema v12 adds `ingest_keys`; the dashboard API gains `GET`/`POST /api/v1/ingest-keys` and `DELETE /api/v1/ingest-keys/{id}`. `POST /v1/logs` accepts and discards OTLP logs (`200 {}`), so Paperclip's log exporter stops getting 404. `scripts/otel-headers-helper.py` is a Claude Code `otelHeadersHelper` that prints the complete header set — `OTEL_EXPORTER_OTLP_HEADERS` overlaid with `OTEL_EXPORTER_OTLP_TRACES_HEADERS`, plus `X-Cotel-Actor-Token` from `COTEL_ACTOR_TOKEN` — and always exits 0 with one JSON object, since a failing helper stops Claude Code's exports. Docs → [Actors and Authentication](docs/operations/actors-and-auth.md#ingest-keys-one-key-for-many-senders) - `cotel --backfill-cost` (dry run) and `--backfill-cost-apply` recompute `cost_usd` for every span of a priced model from its stored token counts at today's rates, revived from the closed PR #67 as reviewed there (FLO-551/552). Spans with an unknown or empty model are counted and left alone; `daily_usage` is not touched, because a day rolled up after the backfill derives its cost from the corrected spans. The apply needs the database to itself, so it runs while the server is stopped; the dry run restores the newest snapshot into a throwaway file instead of copying a live one. README → Maintenance commands has both procedures for the current compose deploy, with `--entrypoint` set so a one-off does not start a second Cloudflare tunnel connector - A synthetic reproducer for the ART-index corruption that took production down in September 2026: `TestARTIndexSurvivesAddedColumnAndBulkReplace` in `internal/storage/art_repro_test.go`, built from the schema with no production bytes — every value is derived from the row number, so it carries no user id, session id or span attribute that belonged to anyone. It rebuilds the trigger rather than a statement from it: `spans` as it stood at schema version 2 — without `user_id`, and *with* the mid-table `duration_ms` generated column, so that the one ALTER production ran on a long-lived filled table (v9 → v10, six weeks before the abort) runs here too instead of passing over a column the fixture never had, and so the indexes are built over the logical/physical column skew they were built over in production — with that era's three ART indexes, filled across the 30-day retention boundary; `storage.Open` then runs the real `schema.sql`, which adds `user_id VARCHAR` to the filled indexed table and puts `idx_spans_user_id` on that added column; a bulk `UPDATE` writes the column, cotel's own retention roll-up supplies the large replace transaction (the `INSERT INTO daily_usage` and the `DELETE FROM spans` are one transaction, so it is the real mutation and not an imitation); then checkpoint, close, reopen, checkpoint, ingest more, repeat. The repetition is the point — the damage accumulates and production ran for weeks after its migration before an open aborted — and so is the restart: this class of fault is only ever reported by the checkpoint that folds the index or the open that reads it back. Each pass asserts that `duration_ms` was there before the migration and is gone after it (a `DROP COLUMN IF EXISTS` that no-ops must not be able to come back unnoticed), that the reopen succeeds, that both checkpoints fold — a present-but-empty `.wal` counts as folded, so an engine that truncates rather than unlinks is not reported as this defect — that all four indexes survive, that a bare `user_id = ` folded into the scan agrees with the same predicate wrapped in an expression, which is not, and that re-inserting a stored `span_id` is still rejected while an unused one is accepted. The last two are the silent form of the damage: a wrong answer rather than an error. They are phrased that way because no `SELECT` over `spans` is planned as an ART index scan on this engine — measured, including on the primary key and on a textbook unique match with the thresholds raised — so an “indexed probe agrees with an unindexed probe” assertion would have been two sequential scans agreeing; the pushdown pair is what [ADR-0013](docs/decisions/0013-spans-has-no-derived-columns.md)'s wrong answers actually came out of, and unique-constraint enforcement is the one path that provably traverses an ART index. It runs in the ordinary test set rather than behind a build tag, because the moment it most needs to run is a driver or engine bump and that is exactly when an optional test is forgotten; `COTEL_ART_REPRO_SPANS` and `COTEL_ART_REPRO_CYCLES` scale it past the defaults (20 000 spans, 2 cycles, 4.1 s). Against the engine the tree links today — `duckdb-go/v2 v2.10506.0`, `SELECT version()` → `v1.5.6` — it did **not** reproduce, at the defaults or at 200 000 spans over 6 cycles. That measures the half of the forensic volume's release condition that was previously unevaluable, and measures it negative rather than exonerating: upstream reports the same class of fault on 1.5.5 against a ~19 GB database, the file that was damaged here took weeks of ingest to get there, and two clean runs at our scale are not absence ([docs/operations/duckdb-recovery.md](docs/operations/duckdb-recovery.md)) diff --git a/docs/.vitepress/config.js b/docs/.vitepress/config.js index 2240585..f2bfc85 100644 --- a/docs/.vitepress/config.js +++ b/docs/.vitepress/config.js @@ -69,6 +69,7 @@ export default defineConfig({ { text: 'ADR-0026 - The Deploy Host Asks /healthz on a Schedule', link: '/decisions/0026-scheduled-loopback-probe-with-a-pager' }, { text: 'ADR-0027 - Users Become Actors', link: '/decisions/0027-users-become-actors' }, { text: 'ADR-0028 - Ingest Keys Authorize, Actor Tokens Identify', link: '/decisions/0028-ingest-keys-and-actor-tokens' }, + { text: 'ADR-0029 - Paperclip Agents by paperclip.agent.id', link: '/decisions/0029-paperclip-agents-by-agent-id' }, ], }, ], diff --git a/docs/decisions/0028-ingest-keys-and-actor-tokens.md b/docs/decisions/0028-ingest-keys-and-actor-tokens.md index d842d96..9fd89d8 100644 --- a/docs/decisions/0028-ingest-keys-and-actor-tokens.md +++ b/docs/decisions/0028-ingest-keys-and-actor-tokens.md @@ -1,7 +1,7 @@ # ADR 0028 — Ingest keys authorize, actor tokens identify **Date:** 2026-11-15 -**Status:** Accepted +**Status:** Accepted; amended by [ADR-0029](./0029-paperclip-agents-by-agent-id.md) for Paperclip agents **Deciders:** Flop (board) --- diff --git a/docs/decisions/0029-paperclip-agents-by-agent-id.md b/docs/decisions/0029-paperclip-agents-by-agent-id.md new file mode 100644 index 0000000..cf27898 --- /dev/null +++ b/docs/decisions/0029-paperclip-agents-by-agent-id.md @@ -0,0 +1,75 @@ +# ADR 0029 — Paperclip agents are identified by `paperclip.agent.id` + +**Date:** 2026-11-15 +**Status:** Accepted +**Deciders:** Flop (board) +**Amends:** [ADR-0028](./0028-ingest-keys-and-actor-tokens.md) for Paperclip agents + +--- + +## Context + +ADR-0028 split authorization from identity: a shared ingest key authorizes, and +each sender's actor token, sent as `X-Cotel-Actor-Token`, identifies it. For +Paperclip agents the token was meant to travel as the env var +`COTEL_ACTOR_TOKEN`, turned into a header by Claude Code's `otelHeadersHelper`. +On production that did not work, for reasons on Paperclip's and Claude Code's +side that cotel cannot change: + +- **Paperclip runs agents through the Claude Agent SDK with + `--setting-sources=project,local`**, so `~/.claude/settings.json` - where the + helper was registered - is never read by an agent. The agent's process did + carry the right `COTEL_ACTOR_TOKEN`; nothing sent it. +- **Registering the helper in managed settings breaks export.** When + `otelHeadersHelper` comes from managed settings, Claude Code drops + `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` from every lower-trust source ("lower-trust + scopes cannot redirect the traces signal"), which is where Paperclip puts the + endpoint. Traces from the whole host stopped until the file was removed. +- **Paperclip header values are literal.** The company destination's headers are + one secret for every agent; `$COTEL_ACTOR_TOKEN` is sent as that literal text. +- **Agents cannot set their own env.** Since Paperclip #15283 an agent key gets + `403` on any env change to a `*_local` agent, its own included; only the board + can. +- The feature covers Claude Code and Codex only; per-host Claude Code settings + would never have reached Codex or the other harnesses anyway. + +What Paperclip does provide is identity: it sets `OTEL_RESOURCE_ATTRIBUTES` for +every agent run, so each span carries `paperclip.agent.id` (the agent's UUID). + +## Decision + +**cotel maps Paperclip agent ids to actors.** Each actor has an optional +`paperclip_agent_id` (schema v13, set on the actor page or with +`PATCH /api/v1/actors/{id}`). On ingest: + +1. An actor token - `Authorization: Bearer `, or + `X-Cotel-Actor-Token` next to an ingest key - names the actor, as before. +2. Otherwise, **if and only if an ingest key authorized the request**, the span + is attributed to the actor whose `paperclip_agent_id` equals the span's + `paperclip.agent.id` - read from the resource attributes, falling back to the + span's own attributes. +3. Otherwise the span is Anonymous. + +The attribute is honoured only behind an ingest key: an unauthenticated sender +(with `allow_anonymous` on) could otherwise claim any agent's identity by +setting an attribute. An agent maps to at most one actor; assigning an id that +another actor holds moves it. There is no `UNIQUE` constraint on the column +(DuckDB has raised false duplicate-key errors on updates of such rows); storage +keeps one actor per id in a transaction. Lookups are memoized per request, so a +batch from one agent costs one query. + +ADR-0028 is unchanged for everything else: ingest keys, actor tokens, the header +and the helper still serve people and machines whose Claude Code reads user +settings (a developer's laptop, a host's interactive shell). + +## Consequences + +- Paperclip's company observability needs only the ingest key in + `Authorization`. No helper, managed settings or per-agent env is needed on the + Paperclip host, and remote agents (another machine) are covered the same way. +- Each agent's id is entered once per actor. A new Paperclip agent stays + Anonymous until its actor is mapped - visible on the Actors page. +- The `COTEL_ACTOR_TOKEN` already written into the agents' Paperclip env is + harmless and unused. +- Spans ingested before an agent was mapped stay Anonymous; the mapping is not + applied retroactively. diff --git a/docs/decisions/index.md b/docs/decisions/index.md index 624fb3d..f5c6706 100644 --- a/docs/decisions/index.md +++ b/docs/decisions/index.md @@ -36,3 +36,4 @@ New ADRs go in this directory as `NNNN-short-title.md`, numbered sequentially. | [ADR-0026](./0026-scheduled-loopback-probe-with-a-pager) | The deploy host asks `/healthz` on a schedule, and it pages | Accepted | | [ADR-0027](./0027-users-become-actors) | Users become actors, down to the schema | Accepted | | [ADR-0028](./0028-ingest-keys-and-actor-tokens) | Ingest keys authorize, actor tokens identify | Accepted | +| [ADR-0029](./0029-paperclip-agents-by-agent-id) | Paperclip agents are identified by `paperclip.agent.id` | Accepted | diff --git a/docs/operations/actors-and-auth.md b/docs/operations/actors-and-auth.md index e934a4d..d6010b5 100644 --- a/docs/operations/actors-and-auth.md +++ b/docs/operations/actors-and-auth.md @@ -116,7 +116,8 @@ There is no last-used time: ingest does not write to the database to record whic | Request | Result | |---|---| | `Authorization: Bearer ` + `X-Cotel-Actor-Token: ` | Accepted, attributed to that actor | -| Valid ingest key, actor token missing, empty or unknown | Accepted as **Anonymous** — even with allow-anonymous off, because the key authorized the request | +| Valid ingest key, no valid actor token, span carries `paperclip.agent.id` mapped to an actor | Accepted, attributed to that actor ([Paperclip agents](#paperclip-agents)) | +| Valid ingest key, no valid actor token and no mapped `paperclip.agent.id` | Accepted as **Anonymous** — even with allow-anonymous off, because the key authorized the request | | Unknown `cotel_ik_` key | `401` | | `Authorization: Bearer ` | Accepted, attributed to that actor; `X-Cotel-Actor-Token` is ignored | | Any other unknown `cotel_` bearer | `401` | @@ -126,9 +127,20 @@ A wrong actor token is not an error. A typo, a rotated token or a deleted actor `POST /v1/logs` accepts the same credentials and discards the body (`200 {}`). It exists so that a sender exporting logs as well as traces, as Paperclip does, does not get `404`; cotel stores spans only. +### Paperclip agents + +Paperclip sends every agent's telemetry with one company-wide header set, so its agents cannot each send an actor token. Instead, Paperclip tags every span with `paperclip.agent.id`, and cotel maps that id to an actor ([ADR-0029](../decisions/0029-paperclip-agents-by-agent-id.md)): + +1. In Paperclip, **Company Settings → General → Agent observability**: destination **Custom OTLP**, base URL of your ingest endpoint (e.g. `https://otlp.example.com`), one header `Authorization` = `Bearer cotel_ik_`, **Enable export** on. Leave the content-capture switches off unless you want prompts and tool output stored in span attributes; **Additional tool details** is useful (it gives the Tools page command detail). +2. In cotel, open each agent's actor page and fill in **Paperclip agent** with the agent's UUID (from its Paperclip page URL), or `PATCH /api/v1/actors/{id}` with `{"paperclip_agent_id": ""}`. + +That is all: no helper, managed settings or per-agent env is needed on the Paperclip host, and agents on remote machines are covered the same way. The id is honoured only when an ingest key authorized the request, so an unauthenticated sender cannot claim an agent by setting the attribute. An actor token still wins when one is sent. A new agent shows up as Anonymous until its actor is mapped. + +The helper approach below does **not** work for Paperclip agents: Paperclip starts them through the Claude Agent SDK with `--setting-sources=project,local`, so they never read the user `settings.json` the helper is registered in, and registering it in managed settings makes Claude Code drop the endpoint Paperclip sets. ADR-0029 has the details. + ### Configuring a sender -Each sender needs three things: +For a person's or a host's own Claude Code, which reads the user `settings.json`. Each sender needs three things: 1. **The ingest key** in its OTLP headers: `Authorization=Bearer cotel_ik_` in `OTEL_EXPORTER_OTLP_HEADERS` or `OTEL_EXPORTER_OTLP_TRACES_HEADERS`. With Paperclip this is the company-wide header set; Paperclip puts it in the per-signal header vars. 2. **Its own actor token** in the env var `COTEL_ACTOR_TOKEN`, in that sender's own process env (for a Paperclip agent, its adapter env). Do not put it in the `env` block of a shared `settings.json`: that block applies to every launch and overrides the inherited env, so every sender would claim the same actor. diff --git a/docs/operations/api-reference.md b/docs/operations/api-reference.md index ebd051a..7a471d0 100644 --- a/docs/operations/api-reference.md +++ b/docs/operations/api-reference.md @@ -247,7 +247,19 @@ delete are still accepted as aliases; response bodies use the new names only (`actors`, `actor_id`, `actors_count`). Its rows are returned under `actors` rather than `items`. `GET /actors/{id}` -returns one actor in the same shape and accepts `range`. See +returns one actor in the same shape and accepts `range`. Each actor carries +`paperclip_agent_id` (a UUID or `null`): the Paperclip agent whose spans are +attributed to it ([ADR-0029](../decisions/0029-paperclip-agents-by-agent-id.md)). + +### `PATCH /actors/{id}` + +Sets or clears the actor's Paperclip agent mapping, the only writable field. +Body: `{"paperclip_agent_id": ""}`, or `""` to clear. The value is trimmed +and lower-cased; anything but a UUID or `""` is `400`. Assigning an id another +actor holds moves it to this one. Answers `200` with the actor, as `GET` would; +`404` for an unknown or deleted actor and for `__anonymous__`. + +See [Actors and Authentication](./actors-and-auth.md) for the management endpoints (create, rotate, delete). diff --git a/frontend/src/api/index.ts b/frontend/src/api/index.ts index 3636b84..d171c9b 100644 --- a/frontend/src/api/index.ts +++ b/frontend/src/api/index.ts @@ -176,6 +176,9 @@ export interface Actor { cost: number sessions: number last_seen: string | null + // Paperclip agent UUID mapped to this actor: spans sent with an ingest key and + // no actor token are attributed here when their paperclip.agent.id matches. + paperclip_agent_id: string | null } export interface ActorsListResponse { @@ -303,6 +306,18 @@ export async function rotateActorToken(id: string): Promise { return res.json() } +// setActorPaperclipAgentId maps a Paperclip agent UUID to the actor; an empty +// string clears it. Setting an id another actor has moves it to this actor. +export async function setActorPaperclipAgentId(id: string, paperclipAgentId: string): Promise { + const res = await fetch(`/api/v1/actors/${encodeURIComponent(id)}`, { + method: 'PATCH', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify({ paperclip_agent_id: paperclipAgentId }), + }) + if (!res.ok) throw await responseError(res) + return res.json() +} + export type DeleteMode = 'actor_only' | 'actor_and_history' export async function deleteActor(id: string, mode?: DeleteMode): Promise { diff --git a/frontend/src/pages/ActorDetail.module.css b/frontend/src/pages/ActorDetail.module.css index de59832..ed624f5 100644 --- a/frontend/src/pages/ActorDetail.module.css +++ b/frontend/src/pages/ActorDetail.module.css @@ -174,3 +174,97 @@ .hintLink:hover { text-decoration: underline; } + +.cardDesc { + margin: 0 0 var(--space-3); + font-size: var(--text-xs); + color: var(--color-text-2); + line-height: 1.7; +} + +.fieldRow { + display: flex; + flex-wrap: wrap; + align-items: center; + gap: var(--space-2); +} + +.textInput { + flex: 1 1 320px; + min-width: 0; + max-width: 380px; + padding: var(--space-2) var(--space-3); + font-family: var(--font-mono); + font-size: var(--text-mono-sm); + border: 1px solid var(--color-border); + border-radius: var(--radius-sm); + background: var(--color-surface); + color: var(--color-text-1); + transition: border-color var(--duration-fast) var(--easing-default); +} + +.textInput:focus { + outline: none; + border-color: var(--color-accent); +} + +.textInput:disabled { + opacity: 0.6; + cursor: not-allowed; +} + +.textInputInvalid, +.textInputInvalid:focus { + border-color: var(--color-danger); + box-shadow: 0 0 0 1px var(--color-danger); +} + +.fieldError { + margin-top: var(--space-2); + font-size: var(--text-sm); + color: var(--color-danger); +} + +.primaryBtn { + display: inline-flex; + align-items: center; + gap: var(--space-1); + padding: var(--space-2) var(--space-4); + background: var(--color-accent); + color: #fff; + border: 1px solid var(--color-accent); + border-radius: var(--radius-sm); + font-size: var(--text-sm); + font-weight: 500; + cursor: pointer; +} + +.primaryBtn:hover:not(:disabled) { + opacity: 0.9; +} + +.primaryBtn:disabled, +.linkBtn:disabled { + opacity: 0.6; + cursor: not-allowed; +} + +.savedNote { + display: inline-flex; + align-items: center; + gap: var(--space-1); + font-size: var(--text-xs); + color: var(--color-success); +} + +.srOnly { + position: absolute; + width: 1px; + height: 1px; + padding: 0; + margin: -1px; + overflow: hidden; + clip: rect(0, 0, 0, 0); + white-space: nowrap; + border: 0; +} diff --git a/frontend/src/pages/ActorDetail.tsx b/frontend/src/pages/ActorDetail.tsx index 06bd232..41ae976 100644 --- a/frontend/src/pages/ActorDetail.tsx +++ b/frontend/src/pages/ActorDetail.tsx @@ -1,7 +1,7 @@ -import { useState, useCallback } from 'react' +import { useState, useCallback, useEffect, useRef } from 'react' import { Link, useNavigate, useParams } from 'react-router-dom' import { Copy, Check, RotateCcw, Trash2, Activity, ListTree } from 'lucide-react' -import { useActor, rotateActorToken, deleteActor } from '../api' +import { useActor, rotateActorToken, deleteActor, setActorPaperclipAgentId } from '../api' import type { Actor } from '../api' import { Card, KpiCard, LoadingSkeleton, ErrorState, SegmentedControl, DeleteActorModal } from '../components' import { getCookie, setCookie } from '../lib/cookie' @@ -29,6 +29,106 @@ const RANGE_SUFFIX: Record = { day: '24h', } +const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i + +interface PaperclipAgentCardProps { + actorId: string + value: string | null + onSaved: () => Promise +} + +// PaperclipAgentCard maps a Paperclip agent UUID to the actor, so spans that +// Paperclip sends with the shared ingest key land on this actor. +function PaperclipAgentCard({ actorId, value, onSaved }: PaperclipAgentCardProps) { + const [input, setInput] = useState(value ?? '') + const [invalid, setInvalid] = useState(false) + const [saving, setSaving] = useState(false) + const [saved, setSaved] = useState(false) + const [saveError, setSaveError] = useState(null) + const savedTimer = useRef | null>(null) + + useEffect(() => { setInput(value ?? '') }, [value]) + useEffect(() => () => { if (savedTimer.current) clearTimeout(savedTimer.current) }, []) + + const submit = async (next: string) => { + setSaving(true) + setSaved(false) + setSaveError(null) + try { + const actor = await setActorPaperclipAgentId(actorId, next) + setInput(actor.paperclip_agent_id ?? '') + await onSaved() + setSaved(true) + if (savedTimer.current) clearTimeout(savedTimer.current) + savedTimer.current = setTimeout(() => setSaved(false), 3000) + } catch (err) { + setSaveError(err instanceof Error ? err.message : 'Save failed') + } finally { + setSaving(false) + } + } + + const handleSave = (e: React.FormEvent) => { + e.preventDefault() + const trimmed = input.trim() + if (!UUID_RE.test(trimmed)) { + setInvalid(true) + return + } + setInvalid(false) + void submit(trimmed) + } + + const handleClear = () => { + setInvalid(false) + void submit('') + } + + return ( + +

+ Spans that Paperclip sends with the shared ingest key are attributed to this actor when their{' '} + paperclip.agent.id matches. Find the agent's ID in + Paperclip, in the agent page URL or the agent settings. +

+
+ + { + setInput(e.target.value) + setSaved(false) + if (UUID_RE.test(e.target.value.trim())) setInvalid(false) + }} + disabled={saving} + spellCheck={false} + autoComplete="off" + aria-invalid={invalid} + aria-describedby={invalid ? 'paperclip-agent-id-error' : undefined} + /> + + {value && ( + + )} + {saved && Saved} +
+ {invalid && ( +
+ Enter the agent's UUID, e.g. 3f2b8c1e-9a4d-4e6f-b7c2-1d5e8a9f0b3c. +
+ )} + {saveError &&
{saveError}
} +
+ ) +} + function isRangeKey(v: string | null): v is RangeKey { return v === 'all' || v === 'year' || v === 'month' || v === 'week' || v === 'day' } @@ -154,6 +254,15 @@ export default function ActorDetail() { )} + {!isAnon && ( + mutate()} + /> + )} +
diff --git a/frontend/src/pages/Actors.module.css b/frontend/src/pages/Actors.module.css index 34bc940..f576dd5 100644 --- a/frontend/src/pages/Actors.module.css +++ b/frontend/src/pages/Actors.module.css @@ -150,6 +150,16 @@ font-style: italic; } +.paperclipTag { + margin-left: var(--space-2); + padding: 0 6px; + font-size: var(--text-xs); + color: var(--color-text-2); + border: 1px solid var(--color-border); + border-radius: var(--radius-sm); + vertical-align: 1px; +} + .dimText { color: var(--color-text-2); } diff --git a/frontend/src/pages/Actors.tsx b/frontend/src/pages/Actors.tsx index 20ce6d3..2effa85 100644 --- a/frontend/src/pages/Actors.tsx +++ b/frontend/src/pages/Actors.tsx @@ -22,6 +22,7 @@ interface ActorVM { created_at: string last_seen: string | null isAnon: boolean + paperclip: boolean } function AddActorModal({ onClose, onCreated }: { onClose: () => void; onCreated: (u: Actor) => void }) { @@ -138,6 +139,7 @@ export default function Actors() { created_at: u.created_at, last_seen: u.last_seen, isAnon: u.id === ANON_ID, + paperclip: !!u.paperclip_agent_id, })) const suffix = RANGE_SUFFIX[range] @@ -166,7 +168,12 @@ export default function Actors() { label: 'Name', sortable: true, render: (_v, row) => ( - {row.name} + <> + {row.name} + {row.paperclip && ( + paperclip + )} + ), }, { diff --git a/internal/api/actors.go b/internal/api/actors.go index f0ef9d9..463ef45 100644 --- a/internal/api/actors.go +++ b/internal/api/actors.go @@ -4,6 +4,7 @@ import ( "encoding/json" "errors" "net/http" + "regexp" "strings" "time" @@ -21,8 +22,12 @@ type ActorStore interface { DeleteAnonymousData() error GetSetting(key string) (string, error) SetSetting(key, value string) error + SetActorPaperclipAgentID(actorID, agentID string) error } +// paperclipAgentIDRe is the shape of a Paperclip agent id (a UUID). +var paperclipAgentIDRe = regexp.MustCompile(`^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$`) + type actorItem struct { ID string `json:"id"` Name string `json:"name"` @@ -31,6 +36,8 @@ type actorItem struct { TotalCostUSD float64 `json:"cost"` Sessions int64 `json:"sessions"` LastSeen *string `json:"last_seen"` + // PaperclipAgentID is the Paperclip agent mapped to this actor (ADR-0029). + PaperclipAgentID *string `json:"paperclip_agent_id"` } type actorsListResponse struct { @@ -68,6 +75,10 @@ func toActorItem(u storage.ActorWithStats) actorItem { s := u.LastSeen.UTC().Format(time.RFC3339) item.LastSeen = &s } + if u.PaperclipAgentID != "" { + id := u.PaperclipAgentID + item.PaperclipAgentID = &id + } return item } @@ -109,6 +120,10 @@ func (h *Handler) handleActorByID(w http.ResponseWriter, r *http.Request, id str h.getActor(w, r, id) return } + if r.Method == http.MethodPatch { + h.patchActor(w, r, id) + return + } if r.Method != http.MethodDelete { jsonError(w, "method not allowed", http.StatusMethodNotAllowed) return @@ -238,3 +253,35 @@ func (h *Handler) createActor(w http.ResponseWriter, r *http.Request) { w.WriteHeader(http.StatusCreated) _ = json.NewEncoder(w).Encode(toActorItemPlain(u)) } + +// patchActor handles PATCH /api/v1/actors/{id}. The only writable field is +// paperclip_agent_id: a Paperclip agent UUID maps that agent's spans to this +// actor, and "" clears the mapping (ADR-0029). +func (h *Handler) patchActor(w http.ResponseWriter, r *http.Request, id string) { + if id == storage.AnonymousActorID { + jsonError(w, "not found", http.StatusNotFound) + return + } + var req struct { + PaperclipAgentID *string `json:"paperclip_agent_id"` + } + if err := json.NewDecoder(r.Body).Decode(&req); err != nil || req.PaperclipAgentID == nil { + jsonError(w, "body must be {\"paperclip_agent_id\": \"\" | \"\"}", http.StatusBadRequest) + return + } + agentID := strings.ToLower(strings.TrimSpace(*req.PaperclipAgentID)) + if agentID != "" && !paperclipAgentIDRe.MatchString(agentID) { + jsonError(w, "paperclip_agent_id must be a UUID", http.StatusBadRequest) + return + } + err := h.actorStore.SetActorPaperclipAgentID(id, agentID) + if errors.Is(err, storage.ErrNotFound) { + jsonError(w, "not found", http.StatusNotFound) + return + } + if err != nil { + jsonError(w, "update failed", http.StatusInternalServerError) + return + } + h.getActor(w, r, id) +} diff --git a/internal/api/actors_list_test.go b/internal/api/actors_list_test.go index 8456594..b0d4687 100644 --- a/internal/api/actors_list_test.go +++ b/internal/api/actors_list_test.go @@ -1,6 +1,10 @@ package api_test import ( + "encoding/json" + "net/http" + "net/http/httptest" + "strings" "testing" "time" @@ -165,3 +169,44 @@ func TestLegacyUserSpellings(t *testing.T) { t.Fatalf("mode=user_only alias: code %d, want 204", code) } } + +func patchActor(t *testing.T, h http.Handler, id, body string) (int, map[string]any) { + t.Helper() + req := httptest.NewRequest(http.MethodPatch, "/api/v1/actors/"+id, strings.NewReader(body)) + w := httptest.NewRecorder() + h.ServeHTTP(w, req) + var out map[string]any + _ = json.Unmarshal(w.Body.Bytes(), &out) + return w.Code, out +} + +// PATCH /actors/{id} sets, normalizes and clears paperclip_agent_id (ADR-0029). +func TestPatchActor_PaperclipAgentID(t *testing.T) { + db, ro := openTestDB(t) + h := newActorHandler(t, db, ro) + a := createAPIActor(t, db, "Wayland") + const id = "709C0DB6-7E36-42AE-89DF-EF06D7F1ACAD" + + code, body := patchActor(t, h, a.ID, `{"paperclip_agent_id":" `+id+` "}`) + if code != 200 || body["paperclip_agent_id"] != strings.ToLower(id) || body["name"] != "Wayland" { + t.Fatalf("set: %d %v", code, body) + } + if _, got := getJSON(t, h, "/api/v1/actors/"+a.ID); got["paperclip_agent_id"] != strings.ToLower(id) { + t.Fatalf("GET after set: %v", got["paperclip_agent_id"]) + } + if code, body = patchActor(t, h, a.ID, `{"paperclip_agent_id":""}`); code != 200 || body["paperclip_agent_id"] != nil { + t.Fatalf("clear: %d %v", code, body) + } + + for _, bad := range []string{`{"paperclip_agent_id":"not-a-uuid"}`, `{}`, `nope`} { + if code, _ := patchActor(t, h, a.ID, bad); code != 400 { + t.Errorf("body %s: code %d, want 400", bad, code) + } + } + if code, _ := patchActor(t, h, "no-such-actor", `{"paperclip_agent_id":""}`); code != 404 { + t.Errorf("unknown actor: code %d, want 404", code) + } + if code, _ := patchActor(t, h, "__anonymous__", `{"paperclip_agent_id":""}`); code != 404 { + t.Errorf("anonymous: code %d, want 404", code) + } +} diff --git a/internal/api/auth/ingest_middleware_test.go b/internal/api/auth/ingest_middleware_test.go index a39944a..de9f74c 100644 --- a/internal/api/auth/ingest_middleware_test.go +++ b/internal/api/auth/ingest_middleware_test.go @@ -198,3 +198,46 @@ func TestIngestMiddleware_RealStorage(t *testing.T) { t.Fatalf("deleted key: code %d, want 401", w.Code) } } + +// Only a request authorized by an ingest key is marked for attribution by +// paperclip.agent.id; actor-token and anonymous requests are not (ADR-0029). +func TestIngestMiddleware_MarksIngestKeyRequests(t *testing.T) { + db, err := storage.Open(":memory:") + if err != nil { + t.Fatal(err) + } + t.Cleanup(func() { db.Close() }) + actor, err := db.CreateActor("flop") + if err != nil { + t.Fatal(err) + } + key, err := db.CreateIngestKey("paperclip") + if err != nil { + t.Fatal(err) + } + mark := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + if ingest.IngestKeyAuthFromContext(r.Context()) { + w.Header().Set("X-Test-Ingest-Key", "1") + } + w.WriteHeader(http.StatusOK) + }) + h := auth.IngestMiddleware(db, mark) + for _, c := range []struct { + name, auth string + want string + }{ + {"ingest key", "Bearer " + key.Token, "1"}, + {"actor token", "Bearer " + actor.Token, ""}, + {"anonymous", "", ""}, + } { + req := httptest.NewRequest(http.MethodPost, "/v1/traces", nil) + if c.auth != "" { + req.Header.Set("Authorization", c.auth) + } + w := httptest.NewRecorder() + h.ServeHTTP(w, req) + if got := w.Header().Get("X-Test-Ingest-Key"); got != c.want { + t.Errorf("%s: ingest-key mark = %q, want %q", c.name, got, c.want) + } + } +} diff --git a/internal/api/auth/middleware.go b/internal/api/auth/middleware.go index 203c771..dc2e61c 100644 --- a/internal/api/auth/middleware.go +++ b/internal/api/auth/middleware.go @@ -88,12 +88,13 @@ func IngestMiddleware(db IngestAuthDB, next http.Handler) http.Handler { unauthorized(w) return } + ctx := ingest.WithIngestKeyAuth(r.Context()) if token := strings.TrimSpace(r.Header.Get(ActorTokenHeader)); token != "" { if actor, err := db.GetActorByToken(token); err == nil && actor != nil { - r = r.WithContext(ingest.WithActorName(r.Context(), actor.Name)) + ctx = ingest.WithActorName(ctx, actor.Name) } } - next.ServeHTTP(w, r) + next.ServeHTTP(w, r.WithContext(ctx)) }) } diff --git a/internal/ingest/context.go b/internal/ingest/context.go index eb2e8d8..ca398e1 100644 --- a/internal/ingest/context.go +++ b/internal/ingest/context.go @@ -18,3 +18,20 @@ func ActorNameFromContext(ctx context.Context) string { } return "" } + +// ctxKeyIngestKey marks a request authorized by a shared ingest key. +type ctxKeyIngestKey struct{} + +// WithIngestKeyAuth marks the request as authorized by a shared ingest key, which +// lets the handler attribute its spans by paperclip.agent.id when no actor token +// identified the sender (ADR-0029). Unauthenticated requests never get this mark, +// so an anonymous sender cannot claim an agent's identity through an attribute. +func WithIngestKeyAuth(ctx context.Context) context.Context { + return context.WithValue(ctx, ctxKeyIngestKey{}, true) +} + +// IngestKeyAuthFromContext reports whether WithIngestKeyAuth marked the request. +func IngestKeyAuthFromContext(ctx context.Context) bool { + v, _ := ctx.Value(ctxKeyIngestKey{}).(bool) + return v +} diff --git a/internal/ingest/handler.go b/internal/ingest/handler.go index 5df9cb1..36bea80 100644 --- a/internal/ingest/handler.go +++ b/internal/ingest/handler.go @@ -5,6 +5,7 @@ import ( "encoding/json" "fmt" "io" + "log" "net/http" "time" @@ -22,6 +23,17 @@ type Storer interface { InsertSpan(storage.Span) error } +// AgentResolver maps a Paperclip agent id to the name of the actor it belongs +// to ("" when none). *storage.DB implements it; a Storer that does not is simply +// never asked, and such spans stay anonymous. +type AgentResolver interface { + ActorNameByPaperclipAgentID(agentID string) (string, error) +} + +// PaperclipAgentIDAttr is the attribute Paperclip sets on every span it exports +// for an agent, via OTEL_RESOURCE_ATTRIBUTES (ADR-0029). +const PaperclipAgentIDAttr = "paperclip.agent.id" + type Handler struct { store Storer queue chan storage.Span @@ -83,17 +95,30 @@ func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request) { } } - // Actor identity comes from the auth middleware context, not OTEL attributes. + // Actor identity comes from the auth middleware context: an actor token wins. + // Only when a shared ingest key authorized the request and no actor token + // named the sender may the paperclip.agent.id attribute name it (ADR-0029). actorName := ActorNameFromContext(r.Context()) + byAgent := actorName == "" && IngestKeyAuthFromContext(r.Context()) + resolve := h.agentResolver(byAgent) for _, rs := range req.ResourceSpans { svcName := attrStr(rs.GetResource().GetAttributes(), "service.name") resAttrs := attrsToMap(rs.GetResource().GetAttributes()) resJSON, _ := json.Marshal(resAttrs) + resActor := actorName + if byAgent { + resActor = resolve(attrStr(rs.GetResource().GetAttributes(), PaperclipAgentIDAttr)) + } for _, ss := range rs.ScopeSpans { for _, sp := range ss.Spans { - h.queue <- decodeSpan(sp, svcName, resAttrs, string(resJSON), actorName) + spanActor := resActor + if byAgent && spanActor == "" { + // Some exporters put the attribute on the span, not the resource. + spanActor = resolve(attrStr(sp.GetAttributes(), PaperclipAgentIDAttr)) + } + h.queue <- decodeSpan(sp, svcName, resAttrs, string(resJSON), spanActor) } } } @@ -101,6 +126,32 @@ func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request) { writeOTLPSuccess(w, r) } +// agentResolver returns a per-request lookup from Paperclip agent id to actor +// name, memoized so a batch from one agent costs one query. When attribution by +// agent is not allowed, or the store cannot resolve agents, every lookup is "". +func (h *Handler) agentResolver(enabled bool) func(agentID string) string { + r, ok := h.store.(AgentResolver) + if !enabled || !ok { + return func(string) string { return "" } + } + seen := map[string]string{} + return func(agentID string) string { + if agentID == "" { + return "" + } + if name, hit := seen[agentID]; hit { + return name + } + name, err := r.ActorNameByPaperclipAgentID(agentID) + if err != nil { + log.Printf("ingest: resolve paperclip agent %s: %v", agentID, err) + name = "" + } + seen[agentID] = name + return name + } +} + // sessionIDKeys are the attribute key names Claude Code may use for the session // identifier, checked in order of preference. var sessionIDKeys = []string{"session.id", "claude.session.id", "cc.session.id"} diff --git a/internal/ingest/handler_test.go b/internal/ingest/handler_test.go index 5061637..c910cc7 100644 --- a/internal/ingest/handler_test.go +++ b/internal/ingest/handler_test.go @@ -340,3 +340,85 @@ func TestTracesResponseMatchesRequestEncoding(t *testing.T) { }) } } + +// resolvingStore is a Storer that also maps Paperclip agent ids to actors. +type resolvingStore struct { + memStore + agents map[string]string + lookups int +} + +func (r *resolvingStore) ActorNameByPaperclipAgentID(id string) (string, error) { + r.lookups++ + return r.agents[id], nil +} + +func agentPayload(resourceAgent, spanAgent string) []byte { + attr := func(v string) string { + if v == "" { + return "" + } + return `{"key":"paperclip.agent.id","value":{"stringValue":"` + v + `"}}` + } + return []byte(`{"resourceSpans":[{"resource":{"attributes":[` + attr(resourceAgent) + `]}, + "scopeSpans":[{"spans":[ + {"traceId":"00000000000000000000000000000001","spanId":"0000000000000001","name":"a", + "startTimeUnixNano":"1","endTimeUnixNano":"2","attributes":[` + attr(spanAgent) + `]}, + {"traceId":"00000000000000000000000000000001","spanId":"0000000000000002","name":"b", + "startTimeUnixNano":"1","endTimeUnixNano":"2","attributes":[` + attr(spanAgent) + `]}]}]}]}`) +} + +// Spans are attributed by paperclip.agent.id only on ingest-key requests with +// no actor token, the actor token wins, and unauthenticated requests never are. +func TestPaperclipAgentAttribution(t *testing.T) { + const wayland, daedalus = "709c0db6-7e36-42ae-89df-ef06d7f1acad", "386b876d-eeba-4bf9-bc10-0dec7b09ee8a" + cases := []struct { + name string + ingestKey bool + actorToken string // actor name injected by the middleware + resAgent string + spanAgent string + want string + wantLookupMax int + }{ + {"ingest key, resource attr", true, "", wayland, "", "Wayland", 1}, + {"ingest key, span attr only", true, "", "", daedalus, "Daedalus", 1}, + {"resource attr beats span attr", true, "", wayland, daedalus, "Wayland", 1}, + {"unknown agent stays anonymous", true, "", "11111111-1111-1111-1111-111111111111", "", "", 1}, + {"actor token wins", true, "flop", wayland, "", "flop", 0}, + {"no ingest key: attribute ignored", false, "", wayland, "", "", 0}, + } + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + store := &resolvingStore{agents: map[string]string{wayland: "Wayland", daedalus: "Daedalus"}} + h := ingest.New(store) + req := httptest.NewRequest(http.MethodPost, "/v1/traces", bytes.NewReader(agentPayload(c.resAgent, c.spanAgent))) + req.Header.Set("Content-Type", "application/json") + ctx := req.Context() + if c.ingestKey { + ctx = ingest.WithIngestKeyAuth(ctx) + } + if c.actorToken != "" { + ctx = ingest.WithActorName(ctx, c.actorToken) + } + w := httptest.NewRecorder() + h.ServeHTTP(w, req.WithContext(ctx)) + h.Flush() + if w.Code != http.StatusOK { + t.Fatalf("status %d: %s", w.Code, w.Body.String()) + } + if len(store.spans) != 2 { + t.Fatalf("stored %d spans, want 2", len(store.spans)) + } + for _, s := range store.spans { + if s.ActorID != c.want { + t.Errorf("span %s actor = %q, want %q", s.SpanID, s.ActorID, c.want) + } + } + // Two spans from one agent cost at most one lookup. + if store.lookups > c.wantLookupMax { + t.Errorf("lookups = %d, want <= %d", store.lookups, c.wantLookupMax) + } + }) + } +} diff --git a/internal/storage/actors.go b/internal/storage/actors.go index f0f97c0..51ae0f7 100644 --- a/internal/storage/actors.go +++ b/internal/storage/actors.go @@ -22,6 +22,10 @@ type Actor struct { Name string Token string CreatedAt time.Time + // PaperclipAgentID maps a Paperclip agent to this actor: spans authorized by + // an ingest key and tagged paperclip.agent.id = this value are attributed + // here (ADR-0029). Empty when unset. + PaperclipAgentID string } // ActorWithStats adds span-derived metrics to an Actor. @@ -164,7 +168,7 @@ func (db *DB) ListActorsPage(opts ListActorsOptions) ([]ActorWithStats, int, err cte := fmt.Sprintf(actorsPageCTE, rawSince, aggSince, AnonymousActorID) query := cte + fmt.Sprintf(` -SELECT id, name, token, created_at, cost, sessions, last_seen, +SELECT id, name, token, created_at, cost, sessions, last_seen, paperclip_agent_id, COUNT(*) OVER () AS total FROM all_actors WHERE TRUE%s @@ -181,14 +185,15 @@ ORDER BY %s %s NULLS LAST, name ASC%s var total int for rows.Next() { var u ActorWithStats - var token sql.NullString + var token, paperclipAgentID sql.NullString var createdAt, lastSeen sql.NullTime if err := rows.Scan( &u.ID, &u.Name, &token, &createdAt, - &u.TotalCostUSD, &u.Sessions, &lastSeen, &total, + &u.TotalCostUSD, &u.Sessions, &lastSeen, &paperclipAgentID, &total, ); err != nil { return nil, 0, err } + u.PaperclipAgentID = paperclipAgentID.String if token.Valid { u.Token = token.String } @@ -232,7 +237,8 @@ named AS ( SELECT u.id, u.name, u.token, u.created_at, COALESCE(ua.cost, 0) AS cost, COALESCE(ua.sessions, 0) AS sessions, - s.last_seen AS last_seen + s.last_seen AS last_seen, + u.paperclip_agent_id AS paperclip_agent_id FROM actors u LEFT JOIN usage_agg ua ON ua.actor_id = u.name LEFT JOIN seen s ON s.actor_id = u.name @@ -246,7 +252,8 @@ anon AS ( CAST(NULL AS TIMESTAMPTZ) AS created_at, COALESCE((SELECT cost FROM usage_agg WHERE actor_id IS NULL), 0) AS cost, COALESCE((SELECT sessions FROM usage_agg WHERE actor_id IS NULL), 0) AS sessions, - (SELECT last_seen FROM seen WHERE actor_id IS NULL) AS last_seen + (SELECT last_seen FROM seen WHERE actor_id IS NULL) AS last_seen, + CAST(NULL AS VARCHAR) AS paperclip_agent_id FROM (SELECT 1) d WHERE EXISTS (SELECT 1 FROM spans WHERE actor_id IS NULL) OR EXISTS (SELECT 1 FROM daily_usage WHERE actor_id IS NULL) @@ -276,9 +283,11 @@ func (db *DB) GetActorWithStats(id string, since *time.Time) (ActorWithStats, er } var u ActorWithStats + var paperclipAgentID sql.NullString err := db.rw.QueryRow( - `SELECT id, name, token, created_at FROM actors WHERE id = ? AND deleted_at IS NULL`, id, - ).Scan(&u.ID, &u.Name, &u.Token, &u.CreatedAt) + `SELECT id, name, token, created_at, paperclip_agent_id FROM actors WHERE id = ? AND deleted_at IS NULL`, id, + ).Scan(&u.ID, &u.Name, &u.Token, &u.CreatedAt, &paperclipAgentID) + u.PaperclipAgentID = paperclipAgentID.String if err != nil { if errors.Is(err, sql.ErrNoRows) { return ActorWithStats{}, ErrNotFound @@ -477,3 +486,64 @@ func (db *DB) DeleteAnonymousData() error { } return tx.Commit() } + +// SetActorPaperclipAgentID maps the Paperclip agent agentID to the actor +// actorID, or clears the mapping when agentID is empty. An agent maps to at most +// one actor, so the id is first cleared from any other actor that holds it - the +// latest assignment wins. Returns ErrNotFound for an unknown or deleted actor. +// +// There is deliberately no UNIQUE constraint on the column: DuckDB has raised +// false duplicate-key errors on UPDATEs of UNIQUE-constrained rows (see +// SoftDeleteActor), so uniqueness is kept here instead, in one transaction. +func (db *DB) SetActorPaperclipAgentID(actorID, agentID string) (err error) { + tx, err := db.rw.Begin() + if err != nil { + return err + } + defer func() { + if err != nil { + _ = tx.Rollback() + } + }() + + var n int + if err = tx.QueryRow( + `SELECT count(*) FROM actors WHERE id = ? AND deleted_at IS NULL`, actorID, + ).Scan(&n); err != nil { + return err + } + if n == 0 { + err = ErrNotFound + return err + } + if agentID != "" { + if _, err = tx.Exec( + `UPDATE actors SET paperclip_agent_id = NULL WHERE paperclip_agent_id = ? AND id <> ?`, + agentID, actorID, + ); err != nil { + return err + } + } + if _, err = tx.Exec( + `UPDATE actors SET paperclip_agent_id = ? WHERE id = ?`, nullableStr(agentID), actorID, + ); err != nil { + return err + } + return tx.Commit() +} + +// ActorNameByPaperclipAgentID returns the name of the live actor mapped to the +// Paperclip agent agentID, or "" when none is. +func (db *DB) ActorNameByPaperclipAgentID(agentID string) (string, error) { + if agentID == "" { + return "", nil + } + var name string + err := db.rw.QueryRow( + `SELECT name FROM actors WHERE paperclip_agent_id = ? AND deleted_at IS NULL LIMIT 1`, agentID, + ).Scan(&name) + if errors.Is(err, sql.ErrNoRows) { + return "", nil + } + return name, err +} diff --git a/internal/storage/ingest_keys_test.go b/internal/storage/ingest_keys_test.go index 0f4630c..84fa556 100644 --- a/internal/storage/ingest_keys_test.go +++ b/internal/storage/ingest_keys_test.go @@ -184,8 +184,8 @@ func TestSchemaV12_FromV11(t *testing.T) { if err != nil { t.Fatalf("open #%d: %v", i+1, err) } - if v := appliedVersion(t, db); v != 12 { - t.Fatalf("open #%d: schema version = %d, want 12", i+1, v) + if v := appliedVersion(t, db); v < 12 { + t.Fatalf("open #%d: schema version = %d, want >= 12", i+1, v) } if n := queryInt64(t, db, `SELECT count(*) FROM actors WHERE name = 'Daedalus'`); n != 1 { t.Fatalf("open #%d: v11 actor lost (%d rows)", i+1, n) diff --git a/internal/storage/paperclip_agent_test.go b/internal/storage/paperclip_agent_test.go new file mode 100644 index 0000000..c6930cc --- /dev/null +++ b/internal/storage/paperclip_agent_test.go @@ -0,0 +1,85 @@ +package storage + +import ( + "errors" + "testing" +) + +const agentA = "709c0db6-7e36-42ae-89df-ef06d7f1acad" + +func TestPaperclipAgentMapping(t *testing.T) { + db := openTestActorDB(t) + wayland, err := db.CreateActor("Wayland") + if err != nil { + t.Fatal(err) + } + other, err := db.CreateActor("Other") + if err != nil { + t.Fatal(err) + } + + if name, err := db.ActorNameByPaperclipAgentID(agentA); err != nil || name != "" { + t.Fatalf("unmapped agent resolved to %q (err %v)", name, err) + } + if err := db.SetActorPaperclipAgentID(wayland.ID, agentA); err != nil { + t.Fatalf("set: %v", err) + } + if name, _ := db.ActorNameByPaperclipAgentID(agentA); name != "Wayland" { + t.Fatalf("resolved to %q, want Wayland", name) + } + got, err := db.GetActorWithStats(wayland.ID, nil) + if err != nil || got.PaperclipAgentID != agentA { + t.Fatalf("GetActorWithStats.PaperclipAgentID = %q (err %v)", got.PaperclipAgentID, err) + } + list, _, err := db.ListActorsPage(ListActorsOptions{}) + if err != nil { + t.Fatal(err) + } + for _, a := range list { + if a.Name == "Wayland" && a.PaperclipAgentID != agentA { + t.Fatalf("list item PaperclipAgentID = %q", a.PaperclipAgentID) + } + } + + // Assigning the same agent to another actor moves it: one actor per agent. + if err := db.SetActorPaperclipAgentID(other.ID, agentA); err != nil { + t.Fatalf("move: %v", err) + } + if name, _ := db.ActorNameByPaperclipAgentID(agentA); name != "Other" { + t.Fatalf("after move resolved to %q, want Other", name) + } + if n := queryInt64(t, db, `SELECT count(*) FROM actors WHERE paperclip_agent_id = ?`, agentA); n != 1 { + t.Fatalf("%d actors hold the agent id, want 1", n) + } + + // Clearing removes the mapping. + if err := db.SetActorPaperclipAgentID(other.ID, ""); err != nil { + t.Fatalf("clear: %v", err) + } + if name, _ := db.ActorNameByPaperclipAgentID(agentA); name != "" { + t.Fatalf("after clear resolved to %q", name) + } +} + +func TestPaperclipAgentMapping_DeletedActor(t *testing.T) { + db := openTestActorDB(t) + a, err := db.CreateActor("Gone") + if err != nil { + t.Fatal(err) + } + if err := db.SetActorPaperclipAgentID(a.ID, agentA); err != nil { + t.Fatal(err) + } + if err := db.SoftDeleteActor(a.ID); err != nil { + t.Fatal(err) + } + if name, _ := db.ActorNameByPaperclipAgentID(agentA); name != "" { + t.Fatalf("soft-deleted actor still resolves: %q", name) + } + if err := db.SetActorPaperclipAgentID(a.ID, agentA); !errors.Is(err, ErrNotFound) { + t.Fatalf("set on deleted actor: err = %v, want ErrNotFound", err) + } + if err := db.SetActorPaperclipAgentID("no-such-id", agentA); !errors.Is(err, ErrNotFound) { + t.Fatalf("set on unknown actor: err = %v, want ErrNotFound", err) + } +} diff --git a/internal/storage/schema.sql b/internal/storage/schema.sql index a1ccf38..1f2d7fb 100644 --- a/internal/storage/schema.sql +++ b/internal/storage/schema.sql @@ -1,4 +1,4 @@ --- Schema version: 12 +-- Schema version: 13 -- Versioned; never silently rename columns. CREATE TABLE IF NOT EXISTS schema_version ( @@ -175,3 +175,9 @@ INSERT INTO schema_version (version) VALUES (10) ON CONFLICT DO NOTHING; -- duckdb.go runs it before this file is applied (ADR-0027). INSERT INTO schema_version (version) VALUES (11) ON CONFLICT DO NOTHING; INSERT INTO schema_version (version) VALUES (12) ON CONFLICT DO NOTHING; + +-- v13: map a Paperclip agent to an actor (ADR-0029). Spans that arrive with an +-- ingest key and no actor token are attributed by their paperclip.agent.id. +-- No UNIQUE constraint: storage keeps one actor per agent id in a transaction. +ALTER TABLE actors ADD COLUMN IF NOT EXISTS paperclip_agent_id VARCHAR; +INSERT INTO schema_version (version) VALUES (13) ON CONFLICT DO NOTHING; diff --git a/scripts/agent-set-cotel-token.sh b/scripts/agent-set-cotel-token.sh index 815bd99..61947b9 100755 --- a/scripts/agent-set-cotel-token.sh +++ b/scripts/agent-set-cotel-token.sh @@ -2,6 +2,11 @@ # # agent-set-cotel-token.sh — give the running agent its own cotel telemetry token. # +# OBSOLETE for Paperclip agents (ADR-0029): an agent key can no longer change any +# *_local agent's env (Paperclip #15283 returns 403), and agents are attributed by +# the paperclip.agent.id Paperclip puts on their spans, mapped to an actor in +# cotel. Kept for reference and for non-Paperclip setups. +# # cotel attributes OTLP spans to an actor by its actor token. Paperclip sends one # company-wide OTLP destination and Authorization header (a cotel ingest key) for # every agent and strips any per-agent OTEL_* env (ADR-0028), so the agent's