From 9cd29031217386025f27e9700845529c5c2004ee Mon Sep 17 00:00:00 2001
From: reoring
Date: Thu, 12 Nov 2026 11:04:25 +0900
Subject: [PATCH 1/3] design: agent self-registration contract, migration 014
(0.1.14)
---
README.md | 10 ++---
cmd/server/internal/api/openapi.json | 2 +-
.../014_agent_self_registration.sql | 2 +
cmd/server/internal/store/projects_test.go | 2 +-
design/API.md | 44 ++++++++++++++++++-
web/package.json | 2 +-
6 files changed, 53 insertions(+), 9 deletions(-)
create mode 100644 cmd/server/internal/store/migrations/014_agent_self_registration.sql
diff --git a/README.md b/README.md
index 58f9d31..2df2e97 100644
--- a/README.md
+++ b/README.md
@@ -169,14 +169,14 @@ a required BuildKit secret, never through build arguments or committed files.
## Catalog and release
-The next app release is **0.1.13**, also recorded in `web/package.json`.
+The next app release is **0.1.14**, also recorded in `web/package.json`.
`catalog/entry.yaml` carries no committed version: the first tag (`v0.1.0`)
created `versions[]` with `ghcr.io/appthrust/tracker@sha256:`,
stream `0.1`; later tags append at publication time. Do not add a version with
an unbuilt or placeholder image digest. OpenAPI's `info.version` describes the
API schema, not the app release. This repository has no hand-maintained changelog.
-After the release prerequisites are available, push the SemVer tag `v0.1.13`.
+After the release prerequisites are available, push the SemVer tag `v0.1.14`.
The tag workflow:
1. Performs one multi-platform build on `ubuntu-24.04` for Linux amd64 and arm64,
@@ -196,8 +196,8 @@ The tag workflow:
Publication commands used by the workflow:
```sh
-bun hack/publish-entry.ts submit --version 0.1.13 --digest sha256:
-bun hack/publish-entry.ts await --version 0.1.13 --digest sha256:
+bun hack/publish-entry.ts submit --version 0.1.14 --digest sha256:
+bun hack/publish-entry.ts await --version 0.1.14 --digest sha256:
```
Writers are serialized by `tracker-catalog-publish`; the workflow is guarded to
@@ -218,7 +218,7 @@ After publication, each estate's `AppCatalogSource` syncs the signed catalog.
Install Issues from the Project Marketplace (Directory is an automatic
dependency). Existing `follow` installations on stream `0.1` roll to the new
version; `pinned` installations show `UpdateAvailable` and require an explicit
-version update. Confirm the installation is Ready, `/releasez` reports `0.1.13`,
+version update. Confirm the installation is Ready, `/releasez` reports `0.1.14`,
the Project lists the `tracker` Access Key space as Ready, and an exchanged key reads `/api/tracker/v1/me`. These are release steps,
not actions performed by a source-only version bump.
diff --git a/cmd/server/internal/api/openapi.json b/cmd/server/internal/api/openapi.json
index 1161d1c..4eacfbf 100644
--- a/cmd/server/internal/api/openapi.json
+++ b/cmd/server/internal/api/openapi.json
@@ -2,7 +2,7 @@
"openapi": "3.1.0",
"info": {
"title": "Tracker API",
- "version": "0.1.13",
+ "version": "0.1.14",
"description": "Contract: design/API.md. One workspace per PLATFORM_PROJECT_ID. The bearer is the signed-in user's token or an Access Key assertion (audience tracker; scope tracker:read for GET, tracker:write otherwise). External-subject assertions resolve by immutable registered agent handle. GET scopes tracker:read; other methods tracker:write; missing scope is 403 insufficient_scope. Every key is refused on Admin routes. See /agent-guide for the collaboration protocol."
},
"servers": [
diff --git a/cmd/server/internal/store/migrations/014_agent_self_registration.sql b/cmd/server/internal/store/migrations/014_agent_self_registration.sql
new file mode 100644
index 0000000..5b5dbdb
--- /dev/null
+++ b/cmd/server/internal/store/migrations/014_agent_self_registration.sql
@@ -0,0 +1,2 @@
+-- Access Key name that self-registered the agent; NULL = registered by an Admin.
+ALTER TABLE tracker_agent ADD COLUMN registered_key text CHECK (char_length(registered_key) BETWEEN 1 AND 253);
diff --git a/cmd/server/internal/store/projects_test.go b/cmd/server/internal/store/projects_test.go
index 23d3d0b..0f4907a 100644
--- a/cmd/server/internal/store/projects_test.go
+++ b/cmd/server/internal/store/projects_test.go
@@ -250,7 +250,7 @@ func TestProjectsMigrationFromV010(t *testing.T) {
}
var versions int
require.NoError(t, tx.SQL.QueryRowContext(t.Context(), `SELECT count(*) FROM tracker_schema_migrations`).Scan(&versions))
- require.Equal(t, 13, versions)
+ require.Equal(t, 14, versions)
var reporterIndex string
require.NoError(t, tx.SQL.QueryRowContext(t.Context(), `SELECT indexdef FROM pg_indexes WHERE schemaname=current_schema() AND indexname='tracker_issue_reporter'`).Scan(&reporterIndex))
require.Contains(t, reporterIndex, "USING btree (workspace_id, reporter_sub) WHERE (deleted_at IS NULL)")
diff --git a/design/API.md b/design/API.md
index 896635e..a557640 100644
--- a/design/API.md
+++ b/design/API.md
@@ -485,7 +485,7 @@ An **Actor** is a person or an agent. Everything a person can be on an issue
| Entity | Owner (sole writer) | Lifecycle | Invariants |
| --- | --- | --- | --- |
-| **Agent** | Admin | `active ⇄ disabled`; never deleted (history refers to it) | has an immutable `id` and an immutable, unique `handle` (see "Identifiers"); `name` and `description` are editable; exactly one `owner` Person, who is accountable for what it does; an Assertion whose `external` subject equals no active agent's handle is refused (403 `key_subject`). |
+| **Agent** | Admin; the agent itself, once, to come into existence ("Self-registration") | `active ⇄ disabled`; never deleted (history refers to it) | has an immutable `id` and an immutable, unique `handle` (see "Identifiers"); `name` and `description` are editable; exactly one `owner` Person, who is accountable for what it does; an Assertion whose `external` subject equals no active agent's handle is refused (403 `key_subject`) on every route except self-registration and `GET /agent-guide`. |
| **Delegation** (fields on Issue) | whoever assigns | set when the assignee becomes an agent, cleared when it becomes a person or nobody | `delegator` is a Person: the person who assigned, or the agent's owner when an agent assigned (itself or another agent). The delegator is who the agent answers to on this issue. |
| **Run** | the agent that started it; a person may cancel | `running ⇄ waiting → succeeded \| failed \| canceled` | only the issue's assignee starts a run; at most one non-terminal run per issue; holds a lease (`leaseExpiresAt`, 10 minutes, renewed by heartbeat, compared at microsecond precision); a run whose lease has passed is `stalled` (derived at read time). A stalled run blocks nothing and is never revived: heartbeat and finish are refused, and the next start on the issue closes it as `failed/lease_expired`. Changing the assignee away from the agent cancels its non-terminal run (`reassigned`) in the same transaction. Whatever ends a run without success (cancel, reassignment, expiry closure) withdraws its open requests. |
| **Request** | requester creates and withdraws; addressee answers | `open → answered \| withdrawn` | `kind ∈ {question, approval, review}`; directed from one actor to one actor, or to "any person"; `approval` and `review` are answered only by people; a `review` exists only as the result of a finished run; only a run's own agent attaches a request to that run, and the run must belong to the same issue (otherwise anyone could force a run into `waiting`). |
@@ -521,6 +521,7 @@ identifier of its own: it is the free-text `session` of a Run.
| Answer `approval` / `review` | addressee, or any person when unaddressed; Admin | never |
| Cancel a run | any | its own |
| Assign to an agent | any | itself, on issues it reported |
+| Register itself | n/a | `tracker:write`, with an external key whose handle is not registered |
| Delete, settings, statuses, labels, shared views, sprint start/close/delete, manage agents | as today | never |
| `GET /people` (Directory) | any | empty, `source: unavailable` (Directory accepts only user bearers) |
@@ -538,6 +539,7 @@ type Actor = Person & { kind: ActorKind; agent?: { id: string; handle: string; o
type Agent = { id: string; handle: string /* immutable; also the external subject of its Access Keys */
name: string; description: string /* ≤ 4096 bytes: what to delegate to it */
owner: Person; disabled: boolean
+ registeredByKey: string | null /* Access Key name that self-registered it; null = registered by an Admin */
activeRuns: number; openRequests: number; lastSeenAt: string | null; createdAt: string; updatedAt: string }
type RunState = 'running' | 'waiting' | 'stalled' | 'succeeded' | 'failed' | 'canceled'
@@ -598,6 +600,7 @@ Changes to existing shapes:
| `GET /agents?includeDisabled=` | → `{ items: Agent[] }` | any |
| `POST /agents` | `{ handle, name, description?, ownerSub }` → `Agent` 201; duplicate handle → 409 | Admin |
| `PATCH /agents/{id}` | `{ name?, description?, ownerSub?, disabled? }` → `Agent`; disabling cancels its non-terminal runs | Admin |
+| `POST /agents/register` | `{ name, description?, ownerSub }` → `Agent` 201; already registered and active → that `Agent` 200, body not applied; see "Self-registration" | external key |
| `GET /inbox` | → `{ items: InboxItem[] }` for the caller, requests first | any |
| `POST /inbox/ack` | `{ answers?: string[] /* request ids */; mentions?: string[] /* comment ids */ }` → 204 | any |
| `GET /events?after=&limit=` | → `{ items: Event[]; next: number }`, ascending, limit default 100 max 500; `after` omitted = from now | any |
@@ -624,6 +627,40 @@ Agent actors are stored in the existing `*_sub` columns as `agent:`, so no
existing column changes type. Expired idempotency rows are deleted
opportunistically by the write that inserts a new one.
+
+### Self-registration (v0.1.14)
+
+An agent brings itself into existence: the first call of a new external key
+is `POST /agents/register`. No Admin registers the handle beforehand.
+
+Why this is safe to allow: only a Project admin can mint an external-subject
+key (`apth access-keys create --external `). Holding such a key for
+this Project and the `tracker` audience is therefore the admission decision;
+requiring a Tracker Admin to type the same handle again added a second
+approval by the same class of person and nothing else.
+
+| Rule | Result when violated |
+| --- | --- |
+| The caller is an external-subject key with `tracker:write`. People (signed-in or user key) register agents with `POST /agents` | 403 `forbidden` |
+| The handle is the assertion's external subject, never a body field: an agent registers only itself. It must match the handle pattern | 400 `invalid` |
+| `ownerSub` is a person with a signed-in write in this workspace (`store.KnownName` is non-empty); the stored `owner.name` is that name. A key cannot ask Directory, so this is the only source of a real name, and it keeps the owner someone who uses this workspace | 400 `invalid`, path `ownerSub` |
+| `name` 1–200 chars, `description` ≤ 4096 bytes, as for `POST /agents` | 400 `invalid` |
+| The handle belongs to a disabled agent: an Admin's decision is not undone by the agent | 403 `key_subject` |
+| The handle is already registered and active | 200 with the existing `Agent`; nothing is written, so an agent may call this on every start |
+
+The owner is **claimed, not verified**: the agent names its owner and the
+owner did not consent in Tracker. `registeredByKey` records the Access Key name
+from the assertion, the Agents page marks such agents, and an Admin corrects
+the owner or disables the agent with `PATCH /agents/{id}`. `registeredByKey`
+never changes afterwards, including when an Admin edits the agent.
+
+An unregistered external key is refused everywhere else with 403
+`key_subject`, whose message names `POST /agents/register`. `GET /agent-guide`
+is the one read it may make, because the guide is where an agent learns to
+register. Registration is not an Event (the feed describes issues).
+
+Storage (migration `014_agent_self_registration.sql`):
+`tracker_agent.registered_key`, null for Admin-registered agents.
### UI
- **Actor rendering**: an agent shows its own glyph and a tooltip "owned by
@@ -646,5 +683,10 @@ opportunistically by the write that inserts a new one.
last seen, active runs, open requests and the median time a request waited
for a person. (Runs by outcome needs a cross-issue run listing and a
Dashboard link needs the Dashboard URL; neither exists, so neither is shown.)
+ Self-registered agents carry a mark naming the key that registered them, so
+ an Admin can check the claimed owner. "Let an agent register itself" shows
+ the key command and the `POST /agents/register` body with the viewer's own
+ subject as `ownerSub`, because a person has no other place to read their
+ subject.
- **Settings**: completion policy.
- Copy in Japanese and English (`web/src/copy/agents.ts`).
diff --git a/web/package.json b/web/package.json
index d455053..85227bb 100644
--- a/web/package.json
+++ b/web/package.json
@@ -1,6 +1,6 @@
{
"name": "@appthrust/tracker",
- "version": "0.1.13",
+ "version": "0.1.14",
"private": true,
"type": "module",
"scripts": {
From c0905fa950ce270768b9d70027c0738c564550e6 Mon Sep 17 00:00:00 2001
From: reoring
Date: Thu, 12 Nov 2026 11:10:27 +0900
Subject: [PATCH 2/3] Agents settings: mark self-registered agents, show how an
agent registers itself
---
README.md | 21 ++--
design/API.md | 10 +-
web/src/api/tracker.ts | 2 +
web/src/copy/agents.ts | 31 +++++
web/src/dev/mock-tracker.test.ts | 12 +-
web/src/dev/mock-tracker.ts | 14 ++-
web/src/features/agents/agents-settings.tsx | 121 +++++++++++++++-----
web/src/model/agents.test.ts | 16 +++
web/src/model/agents.ts | 22 +++-
9 files changed, 197 insertions(+), 52 deletions(-)
diff --git a/README.md b/README.md
index 2df2e97..5195f5c 100644
--- a/README.md
+++ b/README.md
@@ -98,13 +98,20 @@ keys act as their user with the Viewer role. External-subject keys act as an
active registered agent whose immutable handle equals the subject.
The rules are in [`design/API.md`](design/API.md#access-keys-v0111).
-### Agent protocol (0.1.13)
-
-An Admin registers agents through `POST /api/tracker/v1/agents`, with a handle,
-display name, description and accountable person owner. Keys are issued and
-revoked by the platform, never by Tracker. Disabling an agent rejects all its
-keys, cancels its non-terminal runs and withdraws its open requests. Names and
-owners may change; handles cannot. Existing issue attribution is not rewritten.
+### Agent protocol (0.1.14)
+
+An agent registers itself: the first call of a new external-subject key is
+`POST /api/tracker/v1/agents/register` with a display name, description and
+its accountable person owner; the handle is the key's subject. Minting that
+key needs a Project admin, which is the admission decision. The owner is
+claimed by the agent, so the Agents page marks self-registered agents with the
+key that registered them. An Admin can also register an agent directly through
+`POST /api/tracker/v1/agents`. Keys are issued and revoked by the platform,
+never by Tracker. Disabling an agent rejects all its keys (it cannot register
+again), cancels its non-terminal runs and withdraws its open requests. Names
+and owners may change; handles cannot. Existing issue attribution is not
+rewritten. The rules are in
+[`design/API.md`](design/API.md#self-registration-v0114).
Agents poll `/inbox` and `/events`. Initialize the event cursor without `after`,
then poll with `after=next`; sequence allocation and the represented write
diff --git a/design/API.md b/design/API.md
index a557640..92dcc33 100644
--- a/design/API.md
+++ b/design/API.md
@@ -580,7 +580,8 @@ Changes to existing shapes:
- `POST`/`PATCH /issues`: `assigneeSub` accepts `agent:`; a disabled agent
→ 400 (path `assigneeSub`). `PATCH` accepts `expectedUpdatedAt?`; a mismatch
→ 409 `conflict`. An agent setting a `completed` status under `review` → 403.
-- All `POST` routes except the multipart attachment upload honour
+- All `POST` routes except the multipart attachment upload and
+ `POST /agents/register` honour
`Idempotency-Key` (≤ 128 chars): the first handler status and body are kept
24 h per (actor, key) and replayed for the identical request (method, URI,
content type, body bytes); a different request under the same key → 409.
@@ -646,7 +647,7 @@ approval by the same class of person and nothing else.
| `ownerSub` is a person with a signed-in write in this workspace (`store.KnownName` is non-empty); the stored `owner.name` is that name. A key cannot ask Directory, so this is the only source of a real name, and it keeps the owner someone who uses this workspace | 400 `invalid`, path `ownerSub` |
| `name` 1–200 chars, `description` ≤ 4096 bytes, as for `POST /agents` | 400 `invalid` |
| The handle belongs to a disabled agent: an Admin's decision is not undone by the agent | 403 `key_subject` |
-| The handle is already registered and active | 200 with the existing `Agent`; nothing is written, so an agent may call this on every start |
+| The handle is already registered and active | 200 with the existing `Agent`; the body is not applied and the agent is not changed (the call still counts as the agent being seen), so an agent may call this on every start |
The owner is **claimed, not verified**: the agent names its owner and the
owner did not consent in Tracker. `registeredByKey` records the Access Key name
@@ -657,10 +658,13 @@ never changes afterwards, including when an Admin edits the agent.
An unregistered external key is refused everywhere else with 403
`key_subject`, whose message names `POST /agents/register`. `GET /agent-guide`
is the one read it may make, because the guide is where an agent learns to
-register. Registration is not an Event (the feed describes issues).
+register. Registration is not an Event (the feed describes issues). The route
+is idempotent by its own rule and ignores `Idempotency-Key`: a stored 201
+replayed after an Admin disabled the agent would contradict the row above.
Storage (migration `014_agent_self_registration.sql`):
`tracker_agent.registered_key`, null for Admin-registered agents.
+
### UI
- **Actor rendering**: an agent shows its own glyph and a tooltip "owned by
diff --git a/web/src/api/tracker.ts b/web/src/api/tracker.ts
index d45d720..a20cd79 100644
--- a/web/src/api/tracker.ts
+++ b/web/src/api/tracker.ts
@@ -29,6 +29,8 @@ export type Agent = {
description: string
owner: Person
disabled: boolean
+ /** The Access Key name (`ak-…`) the agent registered itself with; null when an Admin registered it. Never changes. */
+ registeredByKey: string | null
/** Live (running or waiting, not stalled) runs. */
activeRuns: number
/** Open requests the agent raised. */
diff --git a/web/src/copy/agents.ts b/web/src/copy/agents.ts
index 475955e..21ac00e 100644
--- a/web/src/copy/agents.ts
+++ b/web/src/copy/agents.ts
@@ -190,6 +190,37 @@ export const agentMessages = defineDashboardMessages({
'tracker.agents.copy': { defaultMessage: 'Copy command', translations: { ja: 'コマンドをコピー' } },
'tracker.agents.copied': { defaultMessage: 'Command copied', translations: { ja: 'コマンドをコピーしました' } },
'tracker.agents.showKey': { defaultMessage: 'Key command for {name}', translations: { ja: '{name} のキー発行コマンド' } },
+ 'tracker.agents.selfRegistered': { defaultMessage: 'Self-registered · {key}', translations: { ja: '自己登録 · {key}' } },
+ 'tracker.agents.selfRegisteredHint': {
+ defaultMessage: 'This agent registered itself with the Access Key {key} and named its responsible person, who has not confirmed it. Check the owner, and edit or disable the agent if it is wrong.',
+ translations: { ja: 'アクセスキー {key} で自分で登録したエージェントです。責任者はエージェントが名乗ったもので、本人は確認していません。違っていれば編集するか無効にしてください。' },
+ },
+ 'tracker.agents.ownerClaimed': { defaultMessage: 'Owned by {name} (claimed by the agent, not confirmed)', translations: { ja: '責任者: {name}(エージェントの申告・未確認)' } },
+ 'tracker.agents.selfRegister.toggle': { defaultMessage: 'Let an agent register itself', translations: { ja: 'エージェントに自分で登録させる' } },
+ 'tracker.agents.selfRegister.lead': {
+ defaultMessage: 'Give an agent a key and it registers itself; no one registers it here first. You become its responsible person, and admins see that it registered itself.',
+ translations: { ja: 'キーを渡せば、エージェントが自分で登録します。ここで先に登録する必要はありません。責任者はあなたになり、管理者には自己登録と表示されます。' },
+ },
+ 'tracker.agents.selfRegister.handle': { defaultMessage: 'Agent handle', translations: { ja: 'エージェントのハンドル' } },
+ 'tracker.agents.selfRegister.handleHint': {
+ defaultMessage: 'Lowercase letters, digits and hyphens, starting with a letter. It becomes the agent’s @handle and cannot be changed later.',
+ translations: { ja: '英小文字・数字・ハイフン(先頭は英字)。エージェントの @ハンドル になり、あとから変更できません。' },
+ },
+ 'tracker.agents.selfRegister.keyStep': { defaultMessage: 'A Project admin issues the key', translations: { ja: 'プロジェクト管理者がキーを発行する' } },
+ 'tracker.agents.selfRegister.keyStepBody': { defaultMessage: 'Run this with the apth CLI and hand the key it shows to the agent.', translations: { ja: 'apth CLI で実行し、表示されたキーをエージェントに渡します。' } },
+ 'tracker.agents.selfRegister.keyStepEmpty': { defaultMessage: 'Enter a handle to see the command.', translations: { ja: 'ハンドルを入力するとコマンドが表示されます。' } },
+ 'tracker.agents.selfRegister.registerStep': { defaultMessage: 'The agent registers itself', translations: { ja: 'エージェントが自分で登録する' } },
+ 'tracker.agents.selfRegister.registerStepBody': {
+ defaultMessage: 'With that key, the agent sends this as its first call. It may change the name.',
+ translations: { ja: 'エージェントはそのキーで、最初にこのリクエストを送ります。name は変えてかまいません。' },
+ },
+ 'tracker.agents.selfRegister.ownerNote': {
+ defaultMessage: 'ownerSub is your own ID ({sub}). It is accepted only if you have already written in this workspace while signed in, such as an issue or a comment.',
+ translations: { ja: 'ownerSub はあなた自身の ID({sub})です。サインインしてこのワークスペースで課題やコメントを書いたことがないと受け付けられません。' },
+ },
+ 'tracker.agents.selfRegister.nameExample': { defaultMessage: 'Agent name', translations: { ja: 'エージェント名' } },
+ 'tracker.agents.selfRegister.copy': { defaultMessage: 'Copy request', translations: { ja: 'リクエストをコピー' } },
+ 'tracker.agents.selfRegister.copied': { defaultMessage: 'Request copied', translations: { ja: 'リクエストをコピーしました' } },
// Settings: completion policy
'tracker.completion.title': { defaultMessage: 'Finishing agent work', translations: { ja: 'エージェントの作業の完了' } },
diff --git a/web/src/dev/mock-tracker.test.ts b/web/src/dev/mock-tracker.test.ts
index f39f811..df01af8 100644
--- a/web/src/dev/mock-tracker.test.ts
+++ b/web/src/dev/mock-tracker.test.ts
@@ -878,11 +878,11 @@ describe('tracker mock: agents fixture', () => {
const active = (await call('GET', '/agents')).body.items as Agent[]
expect(active.map((agent) => agent.handle)).toEqual(['astra', 'claude', 'opus-ui'])
const all = await agentsByHandle()
- expect([...all.values()].map((agent) => [agent.handle, agent.name, agent.owner.sub, agent.disabled, agent.activeRuns, agent.openRequests])).toEqual([
- ['astra', 'Astra', 'dev-sam', false, 1, 1],
- ['claude', 'Claude', 'dev-jordan', false, 0, 1],
- ['legacy-bot', 'Legacy bot', 'dev-alex', true, 0, 0],
- ['opus-ui', 'Opus UI', 'dev-alex', false, 1, 1],
+ expect([...all.values()].map((agent) => [agent.handle, agent.name, agent.owner.sub, agent.disabled, agent.registeredByKey, agent.activeRuns, agent.openRequests])).toEqual([
+ ['astra', 'Astra', 'dev-sam', false, null, 1, 1],
+ ['claude', 'Claude', 'dev-jordan', false, null, 0, 1],
+ ['legacy-bot', 'Legacy bot', 'dev-alex', true, null, 0, 0],
+ ['opus-ui', 'Opus UI', 'dev-alex', false, 'ak-md8mw', 1, 1],
])
expect(all.get('astra')!.lastSeenAt).toEqual(expect.any(String))
})
@@ -1147,7 +1147,7 @@ describe('tracker mock: delegation, runs and requests', () => {
expect((await call('POST', '/agents', { handle: 'astra', name: 'X', ownerSub: 'dev-alex' })).status).toBe(409)
expect((await call('POST', '/agents', { handle: 'scout', name: 'Scout', ownerSub: 'agent:x' })).body.issues[0].path).toBe('ownerSub')
const created = await call('POST', '/agents', { handle: 'scout', name: 'Scout', description: 'Finds flaky tests.', ownerSub: 'dev-jordan' })
- expect(created).toMatchObject({ status: 201, body: { handle: 'scout', owner: { sub: 'dev-jordan', name: 'Jordan Lee' }, activeRuns: 0, openRequests: 0, lastSeenAt: null } })
+ expect(created).toMatchObject({ status: 201, body: { handle: 'scout', owner: { sub: 'dev-jordan', name: 'Jordan Lee' }, registeredByKey: null, activeRuns: 0, openRequests: 0, lastSeenAt: null } })
expect((await call('PATCH', `/agents/${created.body.id}`, { name: 'Scout 2', ownerSub: 'dev-sam' })).body).toMatchObject({ name: 'Scout 2', owner: { sub: 'dev-sam' } })
const guide = await call('GET', '/agent-guide')
expect(guide.headers.get('Content-Type')).toContain('text/markdown')
diff --git a/web/src/dev/mock-tracker.ts b/web/src/dev/mock-tracker.ts
index 4ceaf17..18ba0c6 100644
--- a/web/src/dev/mock-tracker.ts
+++ b/web/src/dev/mock-tracker.ts
@@ -14,7 +14,8 @@
// one; 17 work items carry a size. The exact fixture (shared authority with
// the server seed) is `SPRINT_FIXTURE` below.
// Agents (API.md "Agents"): four registered agents (astra, opus-ui, claude,
-// legacy-bot disabled), delegations, runs (running, waiting, stalled,
+// legacy-bot disabled; opus-ui registered itself with the key `ak-md8mw`,
+// the others were registered by an Admin), delegations, runs (running, waiting, stalled,
// succeeded), requests, a mention and two agent-reported issues (APT-41/42),
// all relative to the moment of seeding — the shared fixture is
// `.tmp/agents-ui/fixture.md`, mirrored by `seedAgents` below. Leases are
@@ -253,7 +254,7 @@ type StoredIssue = {
sprintId: string | null
}
type StoredComment = Omit & { deleted: boolean }
-type StoredAgent = { id: string; handle: string; name: string; description: string; owner: Person; disabled: boolean; createdAt: string; updatedAt: string; lastSeenAt: string | null }
+type StoredAgent = { id: string; handle: string; name: string; description: string; owner: Person; disabled: boolean; registeredByKey: string | null; createdAt: string; updatedAt: string; lastSeenAt: string | null }
/** `state` never holds `stalled`: it is derived from `leaseExpiresAt` on read, as on the server. */
type StoredRun = Omit & { issueId: string; agentId: string; state: StoredRunState }
type StoredRequest = {
@@ -572,14 +573,14 @@ function seedTracker({ withProjects = process.env.MOCK_PROJECTS !== 'none' }: {
type MockState = ReturnType
-/** One agent of the fixture (`.tmp/agents-ui/fixture.md`, "Agents"); times are offsets from the moment of seeding. */
-type AgentFixture = { handle: string; name: string; owner: Person; disabled: boolean; description: string; created: number; updated: number; seen: number }
+/** One agent of the fixture (`.tmp/agents-ui/fixture.md`, "Agents"); times are offsets from the moment of seeding. `registeredByKey`: the key it registered itself with (absent: an Admin registered it). */
+type AgentFixture = { handle: string; name: string; owner: Person; disabled: boolean; description: string; created: number; updated: number; seen: number; registeredByKey?: string }
const MINUTE = 60_000
const DAY = 24 * HOUR
export const AGENT_FIXTURE = {
agents: [
{ handle: 'astra', name: 'Astra', owner: MOCK_PEOPLE.sam, disabled: false, description: 'Backend implementer. Go handlers, store queries, migrations and their tests. Delegate issues with a clear acceptance check.', created: -14 * DAY, updated: -14 * DAY, seen: -2 * MINUTE },
- { handle: 'opus-ui', name: 'Opus UI', owner: MOCK_PEOPLE.alex, disabled: false, description: 'UI implementer. React screens, copy and accessibility in the SPA. Delegate issues that include the expected screen or a screenshot.', created: -7 * DAY, updated: -7 * DAY, seen: -1 * MINUTE },
+ { handle: 'opus-ui', name: 'Opus UI', owner: MOCK_PEOPLE.alex, disabled: false, description: 'UI implementer. React screens, copy and accessibility in the SPA. Delegate issues that include the expected screen or a screenshot.', created: -7 * DAY, updated: -7 * DAY, seen: -1 * MINUTE, registeredByKey: 'ak-md8mw' },
{ handle: 'claude', name: 'Claude', owner: MOCK_PEOPLE.jordan, disabled: false, description: 'Planner and triage. Reads new reports, finds duplicates, proposes priority and sprint. Does not change code.', created: -14 * DAY, updated: -14 * DAY, seen: -2 * HOUR },
{ handle: 'legacy-bot', name: 'Legacy bot', owner: MOCK_PEOPLE.alex, disabled: true, description: 'Old nightly triage script. Replaced by claude.', created: -60 * DAY, updated: -30 * DAY, seen: -32 * DAY },
] as AgentFixture[],
@@ -622,6 +623,7 @@ function seedAgents(seeded: MockState) {
description: fixture.description,
owner: fixture.owner,
disabled: fixture.disabled,
+ registeredByKey: fixture.registeredByKey ?? null,
createdAt: at(fixture.created),
updatedAt: at(fixture.updated),
lastSeenAt: at(fixture.seen),
@@ -1896,7 +1898,7 @@ async function agentRoutes(request: Request, url: URL, route: string): Promise agent.handle === input.handle)) return conflict('an agent with this handle exists')
const time = now()
- const agent: StoredAgent = { id: nextId(), handle: input.handle as string, name: (input.name as string).trim(), description: (input.description as string | undefined) ?? '', owner: personFor(input.ownerSub as string), disabled: false, createdAt: time, updatedAt: time, lastSeenAt: null }
+ const agent: StoredAgent = { id: nextId(), handle: input.handle as string, name: (input.name as string).trim(), description: (input.description as string | undefined) ?? '', owner: personFor(input.ownerSub as string), disabled: false, registeredByKey: null, createdAt: time, updatedAt: time, lastSeenAt: null }
state.agents.push(agent)
return json(agentView(agent), 201)
}
diff --git a/web/src/features/agents/agents-settings.tsx b/web/src/features/agents/agents-settings.tsx
index a72fd2f..94f4971 100644
--- a/web/src/features/agents/agents-settings.tsx
+++ b/web/src/features/agents/agents-settings.tsx
@@ -6,14 +6,19 @@
// says the agent's work in progress is stopped — and copy the exact `apth`
// command that mints a key. The key is shown once by the platform, never by
// Tracker. Runs by outcome are not shown: no route lists runs across issues.
+// An agent that registered itself (API.md "Self-registration") carries a mark
+// naming its key and says its owner is claimed, not confirmed, so an Admin
+// checks it. "Let an agent register itself", open to everyone, shows the key
+// command for a typed handle and the request the agent sends with the
+// viewer's own subject as `ownerSub`: a person has no other place to read it.
import { useQuery } from '@tanstack/react-query'
-import { Bot, Check, Copy, KeyRound, Pencil, Plus, Power, PowerOff } from 'lucide-react'
+import { Bot, Check, CircleHelp, Copy, KeyRound, Pencil, Plus, Power, PowerOff } from 'lucide-react'
import { useId, useMemo, useState, type FormEvent } from 'react'
import { peopleQuery, requestsQuery, useAgentMutations, useUpdateWorkspace } from '../../api/queries'
import { isTrackerError, type Agent, type AgentCompletion, type Person } from '../../api/tracker'
import { useText } from '../../i18n'
-import { accessKeyCommand, AGENT_COMPLETIONS, AGENT_DESCRIPTION_MAX_BYTES, AGENT_HANDLE_PATTERN, AGENT_NAME_MAX, medianWaitMs } from '../../model/agents'
-import { ActionError, Avatar, Button, cn, ConfirmDialog, Dialog, Field, formatDateTime, formatDuration, formatRelative, Notice, Section, SelectInput, showToast, TextArea, TextInput } from '../../ui'
+import { accessKeyCommand, accessKeyCommandFor, AGENT_COMPLETIONS, AGENT_DESCRIPTION_MAX_BYTES, AGENT_HANDLE_PATTERN, AGENT_NAME_MAX, medianWaitMs, selfRegisterRequest } from '../../model/agents'
+import { ActionError, Avatar, Badge, Button, cn, ConfirmDialog, Dialog, Field, formatDateTime, formatDuration, formatRelative, Notice, Section, SelectInput, showToast, TextArea, TextInput } from '../../ui'
import { useReference } from '../issues/use-reference'
import { AgentTag } from './actor'
@@ -25,6 +30,8 @@ export function AgentSettings() {
const [editing, setEditing] = useState(null)
const [disabling, setDisabling] = useState(null)
const [keyFor, setKeyFor] = useState(null)
+ const [helpOpen, setHelpOpen] = useState(false)
+ const helpId = useId()
const waits = useMemo(() => {
const byAgent = new Map()
for (const agent of agents) byAgent.set(agent.id, medianWaitMs((answered.data ?? []).filter((request) => request.from.sub === `agent:${agent.id}`)))
@@ -53,13 +60,19 @@ export function AgentSettings() {
title={t('tracker.settings.agents')}
className="mt-6"
actions={
- me.isAdmin ? (
- } onClick={() => setEditing('new')}>
- {t('tracker.agents.register')}
+ <>
+ } aria-expanded={helpOpen} aria-controls={helpId} onClick={() => setHelpOpen((open) => !open)}>
+ {t('tracker.agents.selfRegister.toggle')}
- ) : undefined
+ {me.isAdmin ? (
+ } onClick={() => setEditing('new')}>
+ {t('tracker.agents.register')}
+
+ ) : null}
+ >
}
>
+ {helpOpen ? : null}
{active.length === 0 ? (
+ )
+}
+
+/** Text to paste as is (a command, a request) beside its copy button; the check shows until the text changes. */
+function CopySnippet({ text, copyLabel, copiedLabel }: { text: string; copyLabel: string; copiedLabel: string }) {
+ const { t } = useText()
+ const [copied, setCopied] = useState(null)
+ return (
+