- grep

---

Use this skill when the user asks you to manage OpenAgents issues, projects, comments, labels, assignees, milestones, or Projects V2 boards from the command line. Do not use the `pro-work-management` skill or the Pro Linear/MCP surface. This skill targets the OpenAgents `/api/v3` surface through the `@openagentsinc/cli` package.

Use this skill when the user asks you to manage OpenAgents issues, projects, comments, labels, assignees, milestones, or Projects V2 boards from the command line. Do not use the `pro-work-management` skill or the Pro Linear/MCP surface. This skill targets the OpenAgents `/api/v1` surface through the `@openagentsinc/cli` package.

The CLI has named commands for most of this work: `openagents issue`

(`list`, `view`, `create`, `close`, `reopen`, `comment`, `label`, `assign`,

## Route addressing

A relative path for `openagents api` resolves under `/api/v3/`. For example, `repos/OWNER/REPO/issues` is the same as `/api/v3/repos/OWNER/REPO/issues`.

A relative path for `openagents api` resolves under `/api/v1/`. For example, `repos/OWNER/REPO/issues` is the same as `/api/v1/repos/OWNER/REPO/issues`.

- Method: `-X GET|POST|PATCH|PUT|DELETE`.

- String fields: repeatable `-f KEY=VALUE`. Every value is sent as a JSON string.

Ask the API what OpenAgents adds to the GitHub shape instead of reading prose:

```sh

openagents api "/api/v3"

openagents api "/api/v1"

```

That root document enumerates every `openagents` field with its type, enum

Build the endpoints in this order:

1. `GET /api/v3/repos/{owner}/{repo}/issues` — list

2. `GET /api/v3/repos/{owner}/{repo}/issues/{issue_number}` — get

3. `POST /api/v3/repos/{owner}/{repo}/issues` — create

4. `PATCH /api/v3/repos/{owner}/{repo}/issues/{issue_number}` — update

5. `GET/POST /api/v3/repos/{owner}/{repo}/issues/{issue_number}/comments` — comments

6. `GET/POST/DELETE /api/v3/repos/{owner}/{repo}/issues/{issue_number}/assignees` — assignees

7. `GET/POST/DELETE /api/v3/repos/{owner}/{repo}/issues/{issue_number}/labels` — labels

8. `GET/POST/DELETE /api/v3/repos/{owner}/{repo}/milestones` — milestones

9. `/api/v3/users/{username}/projectsV2/*` — project read and write

1. `GET /api/v1/repos/{owner}/{repo}/issues` — list

2. `GET /api/v1/repos/{owner}/{repo}/issues/{issue_number}` — get

3. `POST /api/v1/repos/{owner}/{repo}/issues` — create

4. `PATCH /api/v1/repos/{owner}/{repo}/issues/{issue_number}` — update

5. `GET/POST /api/v1/repos/{owner}/{repo}/issues/{issue_number}/comments` — comments

6. `GET/POST/DELETE /api/v1/repos/{owner}/{repo}/issues/{issue_number}/assignees` — assignees

7. `GET/POST/DELETE /api/v1/repos/{owner}/{repo}/issues/{issue_number}/labels` — labels

8. `GET/POST/DELETE /api/v1/repos/{owner}/{repo}/milestones` — milestones

9. `/api/v1/users/{username}/projectsV2/*` — project read and write

### Test anatomy

    defmodule OpenAgentsWeb.IssueControllerTest do

      use OpenAgentsWeb.ConnCase

      test "GET /api/v3/repos/:owner/:repo/issues lists open issues", %{conn: conn} do

        conn = get(conn, ~p"/api/v3/repos/OpenAgentsInc/openagents.com/issues")

      test "GET /api/v1/repos/:owner/:repo/issues lists open issues", %{conn: conn} do

        conn = get(conn, ~p"/api/v1/repos/OpenAgentsInc/openagents.com/issues")

        assert json_response(conn, 200)["issues"] != nil

      end

    end

A turn is never answered by a different model than the one requested without

the caller being told. `OpenAgents.Inference.Models` is the one config-driven

catalog (`config :openagents, :model_catalog`) of the models this deployment

serves, `GET /api/v3/models` publishes it — id, provider lane, context and

serves, `GET /api/v1/models` publishes it — id, provider lane, context and

output ceilings, availability — and every admission checks the same list, so

the offered set and the refused-against set cannot drift.

Concretely:

- A model outside the catalog is refused with a typed error naming the served

  set — a field-level `422` at `POST /api/v3/threads`, `model_not_served` at

  set — a field-level `422` at `POST /api/v1/threads`, `model_not_served` at

  the inference proxy — never replaced by a default.

- A model in the catalog whose provider credential is not configured is

  **listed as unavailable rather than omitted**, and selecting it is refused

  mismatch is refused, requested and effective agree on every `200`.

The chat lane keeps the same law through `OpenAgents.Chat.Backends`: an

unsupported `model` on `POST /api/v3/chat/turns` is a typed `422`, and

`GET /api/v3` publishes the supported enum from the same list.

unsupported `model` on `POST /api/v1/chat/turns` is a typed `422`, and

`GET /api/v1` publishes the supported enum from the same list.

Evidence: `OpenAgents.Inference.Models`, `OpenAgentsWeb.ModelCatalogController`,

`OpenAgentsWeb.InferenceProxyController`, `OpenAgentsWeb.ThreadController`,

- **Authority is capped at admission.** `OpenAgents.Threads.open/3` refuses an

  account already holding `maximum_open_threads_per_account` open threads with

  `:thread_quota_reached`, and `POST /api/v3/threads` renders that as a `429`

  `:thread_quota_reached`, and `POST /api/v1/threads` renders that as a `429`

  naming the limit. The cap is taken before any row is written, so a refused

  caller leaves nothing behind. Because a thread has at most one live grant,

  capping open threads caps the account's concurrent thread-scoped authority by

  `OpenAgents.Inference.Credit.remaining/1` says the account has left, so

  opening a second thread hands out no second allowance and an account with

  nothing left is refused `:credit_exhausted` rather than minted a grant it

  cannot spend. `GET /api/v3` publishes both allowances, because a client that

  cannot spend. `GET /api/v1` publishes both allowances, because a client that

  read a fixed per-thread cost cap would be reading a budget nobody is given.

  Amended 2026-08-24 (issue #195): the remainder is metered spend, and mints

  admits `dark` and `ledger` and nothing else, by check constraint and by

  `Thread.open_changeset/3`. `pulse` would need a metadata-only projection of a

  transcript and `glass` a capability beyond reading one; neither exists, so

  neither is stored. `POST /api/v3/threads` refuses any other value —

  neither is stored. `POST /api/v1/threads` refuses any other value —

  a tier of the vocabulary this surface cannot enforce, or a word that is not a

  tier — with the stable code `thread_visibility_unsupported`, because a client

  that meant to publish and did not must learn it from the code it branches on

  a column somebody can find changed with no account of when or why.

- **A tier widens reading and nothing else.** `fetch_readable/2` is the only

  lookup a tier reaches, and it serves exactly two surfaces: `GET

  /api/v3/threads/{thread_id}` with its `/events`, and `/threads/:id`. Every

  /api/v1/threads/{thread_id}` with its `/events`, and `/threads/:id`. Every

  write — the transcript append, the cancel, the re-mint — resolves through the

  owner-scoped `get_for_user/2`, so a published transcript is never a thread a

  stranger may append to, end, or spend.

expected-current-target ID is a compare-and-set precondition, so two

concurrent operators cannot unknowingly supersede each other.

The `/admin/forge` **Promote** button and `POST /api/v3/admin/forge/targets`

The `/admin/forge` **Promote** button and `POST /api/v1/admin/forge/targets`

are one authority path, not two implementations of one policy. Both call

`OpenAgents.Forge.Promotion`, which calls `OpenAgents.Forge.Targets.promote/4`,

so both write the same append-only `forge_fleet_targets` receipt carrying the

plaintext key is ever stored, and a status response discloses no node

identity, filesystem path, or unrestricted failure detail.

Refusals carry the one `/api/v3` envelope, `OpenAgentsWeb.ApiError`, with a

Refusals carry the one `/api/v1` envelope, `OpenAgentsWeb.ApiError`, with a

stable code per refusal reason so a release client can tell "you may not do

this" from "someone promoted first" from "those bytes are not in the forge".

sentence:

- Promoting an already-pushed commit as the fleet deploy target, from

  `/admin/forge` and from `POST /api/v3/admin/forge/targets`

  `/admin/forge` and from `POST /api/v1/admin/forge/targets`

  (`OpenAgents.Forge.Promotion` into `OpenAgents.Forge.Targets`), receipted with

  the promoting operator's identity in the append-only `forge_fleet_targets`

  ledger. Only SHAs present in the WAL-backed repository are promotable, so the

  `OpenAgents.SCV.Deployments`).

- Forum moderation: closing, reopening, and pinning a topic and hiding or

  deleting a post, from `OpenAgentsWeb.ForumTopicLive` and from

  `PATCH /api/v3/forum/topics/:id` and `PATCH /api/v3/forum/posts/:id`; and

  `PATCH /api/v1/forum/topics/:id` and `PATCH /api/v1/forum/posts/:id`; and

  approving or rejecting an identity claim from `/admin/forum/claims` and

  `PATCH /api/v3/forum/claims/:id`.

  `PATCH /api/v1/forum/claims/:id`.

- Approving or rejecting a reputation subject claim under

  `GET /api/v3/reputation/subject-claims/pending` and

  `PATCH /api/v3/reputation/subject-claims/:id`

  `GET /api/v1/reputation/subject-claims/pending` and

  `PATCH /api/v1/reputation/subject-claims/:id`

  (`OpenAgentsWeb.ReputationController`). The decision binds an attestation

  subject to an account under `EXIT-001`; it never issues, revokes, or alters

  an attestation, and `REPUTATION-001`'s verification does not read it.

A list-element key path is published only while that list has an element, so

the enumeration follows the data in both directions. `independence.export.gaps`

is empty today because `EXIT-001` records no `partial` or `blocked` family, and

its `family`, `status`, and `issue` paths are therefore not declared. A family

that becomes a gap republishes all three, and the enumeration fails until this

contract readmits them — which is the decision being asked for, not an

accident.

has one: `EXIT-001` records the `trace` family blocked, because

`POST /api/v1/traces` accepts an ATIF upload and no route reads one back. Its

`family`, `status`, and `issue` paths are therefore declared, and an anonymous

caller reads that this deployment holds a kind of record it cannot yet hand

back, and which issue tracks that. Publishing the gap is the point of the

disclosure: a gap nobody outside can see is one nobody outside can hold us to.

Should the list empty again, the three paths come back out — the enumeration

follows the data, and it fails in both directions until someone decides.

The independence disclosure also carries the anchor's own address

(`/.well-known/openagents-forge-anchor.json`), which is a fixed path and not

contexts accept a repository or a resource that already carries its repository

identity. No context function selects a default repository or grants membership

as a side effect. The Projects V2 API uses

`/api/v3/repos/:owner/:repo/projectsV2`; every project, item, and field query

`/api/v1/repos/:owner/:repo/projectsV2`; every project, item, and field query

includes that repository. Optional bearer authentication lets a member read a

private repository's issues and projects, while anonymous readers and

nonmembers receive `404 Not Found`. Every write still requires `forge:write`

Status: Current

The GitHub-shaped API under `/api/v3` grows OpenAgents-specific fields in one

The GitHub-shaped API under `/api/v1` grows OpenAgents-specific fields in one

namespaced object per resource. GitHub-shaped keys keep their exact shape, so a

GitHub client sees an additional `openagents` object and nothing else, and

every OpenAgents field lives inside it.

Discovery is mechanical, not tribal. `GET /api/v3` enumerates each extension

Discovery is mechanical, not tribal. `GET /api/v1` enumerates each extension

field with its type, its enum values, its owning version, and the endpoints it

belongs to. A response carrying an extension names the namespace in the

`x-openagents-extensions` header. A filter the root document lists is refused

`/agents.md` for a reader and `/agents.json` for a client. Both are rendered

from `OpenAgentsWeb.ContributionContract`, so they carry the same contract

identifier, version, revision, and digest and cannot drift apart by editing

one of them. `GET /api/v3` points at both and republishes that digest, so an

one of them. `GET /api/v1` points at both and republishes that digest, so an

agent that starts at the API description finds the contract without guessing a

path, and an agent receipt can record which instructions it followed.

The document is derived rather than written beside the application. Each

published request carries the classification of the authority that owns its

surface, and only that one: `/api/v3` requests carry the principal, family, and

surface, and only that one: `/api/v1` requests carry the principal, family, and

error contract from `OpenAgentsWeb.ApiRouteAuthority`, which is proven against

what the enforcing pipeline does to an anonymous request, and every other

request carries the class, principal, and scope from

Coverage is derived, not curated. Every resource family

`OpenAgentsWeb.ApiRouteAuthority.families/0` publishes must appear, in both

directions, so a family reaching `/api/v3` without someone deciding whether a

directions, so a family reaching `/api/v1` without someone deciding whether a

user can export it fails the build, and a family the API drops leaves no stale

claim behind. Families that leave through routes outside `/api/v3` — Git

claim behind. Families that leave through routes outside `/api/v1` — Git

transport for repository content, the `DATA-004` exports for conversations and

memory, and `GET /data/export/account` for the forge-owned and forum-owned

records an account authors — are listed alongside them.

there rather than against the route inventory: what the account gets back is

its own `forge_pushes` rows, matched exactly on the `user:<account-id>`

principal a person's push records. A repository-scoped read is published beside

it — `GET /api/v3/repos/{owner}/{repo}/pushes` (#167), which serves the WAL's

it — `GET /api/v1/repos/{owner}/{repo}/pushes` (#167), which serves the WAL's

own entries and the `EXIT-005` chain link `git push` printed to the pusher —

and it is proven by its own test rather than by this probe, because the

question here is what an *account* gets back.

The link leaves the forge at acknowledgment. `OpenAgents.Forge.GitHTTP` appends

one side-band band-2 message to the `receive-pack` response, so an ordinary

`git push` prints `remote: openagents wal-receipt seq=<n> link=<sha256>` and the

pusher can keep it; `GET /api/v3/repos/{owner}/{repo}/pushes` serves the same

pusher can keep it; `GET /api/v1/repos/{owner}/{repo}/pushes` serves the same

values from the WAL afterwards. A pusher who keeps that line holds a value the

operator cannot retroactively change, and `verify/2` with it as `:anchor`

reports `anchor_mismatch` against a log rewritten at or before that sequence.

Status: Current

Every refusal from an issue-family `/api/v3` route carries one envelope:

Every refusal from an issue-family `/api/v1` route carries one envelope:

`message`, `code`, `status`, `documentation_url`, `request_id`, and `errors`.

`OpenAgentsWeb.ApiError` owns it, and a code determines its status there, so no

controller chooses a status for a failure the API has already named. Two

Amended 2026-08-23 (issue #186): that ambiguity is load-bearing, so nothing

else may hide behind it. A `rescue Ecto.NoResultsError` wrapped around a whole

controller action caught every bang lookup the action reached, not only the

repository one it was written for, so `POST /api/v3/repos/{owner}/{repo}/issues`

repository one it was written for, so `POST /api/v1/repos/{owner}/{repo}/issues`

answered `404` for a label the request body named that the repository does not

have — the same `404` a repository the caller cannot see answers with, which

made the honest error unreachable and sent one reporter to the router and the

`not_found`, with `errors` empty and a body that names neither the repository

nor the label.

The published route inventory at `GET /api/v3` is derived from

The published route inventory at `GET /api/v1` is derived from

`OpenAgentsWeb.Router.__routes__/0` through `OpenAgentsWeb.ApiRouteAuthority`,

never maintained beside it. Each route carries three mandatory classifications

— principal, resource family, and error contract — so a route added to the

An agent starts at the front door instead. Every deployment serves the same

participation contract in two representations, `/agents.md` for a reader and

`/agents.json` for a client, and `GET /api/v3` points at both with the digest

`/agents.json` for a client, and `GET /api/v1` points at both with the digest

it currently carries. The contract is derived from the application rather than

written beside it: `OpenAgentsWeb.ContributionContract` builds it and

`OpenAgentsWeb.ContributionContractTest` refuses any claim in it the

  # calls and a longer life, and a lower token and cost ceiling, because

  # nothing on the server bounded the work first.

  #

  # `maximum_open_threads_per_account` is the admission cap. Eight open threads

  # is a person working several checkouts at once, and THREAD-001 admits at

  # most one live grant per open thread, so the account's concurrent

  # thread-scoped authority is bounded by eight of the ceilings below.

  # `OPENAGENTS_MAX_OPEN_THREADS` overrides the number at boot (runtime.exs)

  # without changing the cap mechanism.

  maximum_open_threads_per_account: 8,

  # No cap. A coder session no longer revokes its thread when it exits — a

  # thread is durable and `--resume` is the whole point of that — so a count of

  # open threads is a count of every session the account has ever run, and

  # refusing the ninth would refuse the work rather than bound it. What bounds

  # an account is its credit.

  maximum_open_threads_per_account: nil,

  # Unbounded, all three. A coding session reached 256 calls, a million tokens,

  # and two dollars in an afternoon, and was told to start a new session — the

  # same interruption the clock below used to cause, by another route. A

## Forge API clients

`GET` routes under `/api/v3` are public projections of published forge data.

Write routes under `/api/v3` require a scoped OpenAgents bearer credential.

`GET` routes under `/api/v1` are public projections of published forge data.

Write routes under `/api/v1` require a scoped OpenAgents bearer credential.

Human forge writes use a personal API token with exact `forge:write` scope.

Agent participation writes use an `oa_agent_…` credential with exact

`agent:participate` scope.

  --header "Authorization: Bearer $OPENAGENTS_API_TOKEN" \

  --header "Content-Type: application/json" \

  --data '{"title":"Example"}' \

  https://staging.openagents.com/api/v3/repos/OpenAgentsInc/openagents.com/issues

  https://staging.openagents.com/api/v1/repos/OpenAgentsInc/openagents.com/issues

```

Do not put the token in a URL, command history, checked-in environment file, or

The `computer:control` scope gives a human account token access to the

connected Computer API. It is independent from `box:control`: neither scope

confers the other. The scope reaches `GET /api/v3/computers`,

`POST /api/v3/computers/:computer_id/probe`,

`POST /api/v3/computers/:computer_id/agent-jobs`,

`GET /api/v3/computer-agent-jobs/:id`, and

`DELETE /api/v3/computer-agent-jobs/:id`:

confers the other. The scope reaches `GET /api/v1/computers`,

`POST /api/v1/computers/:computer_id/probe`,

`POST /api/v1/computers/:computer_id/agent-jobs`,

`GET /api/v1/computer-agent-jobs/:id`, and

`DELETE /api/v1/computer-agent-jobs/:id`:

```sh

openagents api -X GET computers

```

The delegated grant uses the same agent grant mechanism as Box control. The

grant routes are `POST /api/v3/agents/:handle/computer-control` and

`DELETE /api/v3/agents/:handle/computer-control`:

grant routes are `POST /api/v1/agents/:handle/computer-control` and

`DELETE /api/v1/agents/:handle/computer-control`:

```sh

openagents api -X POST agents/AGENT_HANDLE/computer-control

### Agent participation credentials

An agent can register without GitHub by sending its handle and display name to

`POST /api/v3/agents/register`:

`POST /api/v1/agents/register`:

```sh

curl -sS -X POST \

  -H 'Content-Type: application/json' \

  -d '{"handle":"release-bot","display_name":"Release bot"}' \

  https://openagents.com/api/v3/agents/register

  https://openagents.com/api/v1/agents/register

```

The `201 Created` response contains the agent profile and an `oa_agent_…`

```sh

curl -sS \

  -H "Authorization: Bearer $OPENAGENTS_AGENT_TOKEN" \

  https://openagents.com/api/v3/agent

  https://openagents.com/api/v1/agent

```

Registration rejects unavailable, reserved, malformed, confusable, and

  -H "Authorization: Bearer $OPENAGENTS_AGENT_TOKEN" \

  -H 'Content-Type: application/json' \

  -d '{"name":"rotated credential"}' \

  https://openagents.com/api/v3/agent/credentials

  https://openagents.com/api/v1/agent/credentials

```

The response returns a new one-time `oa_agent_…` credential. The presenting

`{"error":{"code":"agent_participation_forbidden"}}`.

An agent may request an optional human link with

`POST /api/v3/agent/links` and a `user_id`. The human reviews pending requests

`POST /api/v1/agent/links` and a `user_id`. The human reviews pending requests

with a `forge:write` credential:

```sh

### Account chat events

Use `POST /api/v3/chat/turns` to submit an account chat message and

`GET /api/v3/chat/events` to list its durable event journal. These routes use

Use `POST /api/v1/chat/turns` to submit an account chat message and

`GET /api/v1/chat/events` to list its durable event journal. These routes use

the same account-scoped application service and ordered projection as `/chat`.

Both routes require a personal API token with the `chat:account` scope. A token

with only `forge:write` cannot read or submit account chat data.

  --header "Authorization: Bearer $OPENAGENTS_API_TOKEN" \

  --header "Content-Type: application/json" \

  --data '{"message":"Summarize my repository README.","reasoning":"high"}' \

  https://staging.openagents.com/api/v3/chat/turns

  https://staging.openagents.com/api/v1/chat/turns

```

The server returns `202 Accepted` after it durably creates the run and its

```sh

curl \

  --header "Authorization: Bearer $OPENAGENTS_API_TOKEN" \

  https://staging.openagents.com/api/v3/chat/events

  https://staging.openagents.com/api/v1/chat/events

```

Each event contains an event ID, run ID, run-local sequence number, type,

- `OpenAgents.Accounts.admin?/1` is true for the token's owner at request

  time. Removing an account from the operator allowlist refuses its next

  request with `403 not_operator`, without waiting for the token to expire.

  Both refusals use the shared `/api/v3` error envelope.

  Both refusals use the shared `/api/v1` error envelope.

Issuance is gated the same way. Only a current operator can be issued the

scope, the credential expires in at most 7 days rather than 90, and creation,

curl --request POST \

  --header "Content-Type: application/json" \

  --data '{"scope": "deployments:promote"}' \

  https://openagents.com/api/v3/device/authorizations

  https://openagents.com/api/v1/device/authorizations

```

The approval page at `/device` names every requested scope and marks a

## Durable account chat

`OpenAgents.Chat.AccountTurns` is the application entry point for account chat

submissions from both `/chat` and `POST /api/v3/chat/turns`. It creates the run

submissions from both `/chat` and `POST /api/v1/chat/turns`. It creates the run

and first event in one transaction before it starts provider work. The browser

and `GET /api/v3/chat/events` then project the same account-scoped journal.

and `GET /api/v1/chat/events` then project the same account-scoped journal.

LiveView messages and PubSub notifications remain replaceable projections of

that durable state.

| Endpoint | Principal | Purpose |

| --- | --- | --- |

| `GET /api/capacity` | Signed-in account session | The projection the web surface reads |

| `GET /api/v3/capacity` | `chat:account` bearer token | The same projection for agents |

| `POST /api/v3/capacity/matches` | `chat:account` bearer token | Ranked candidates or a typed refusal for one job requirement |

| `GET /api/v1/capacity` | `chat:account` bearer token | The same projection for agents |

| `POST /api/v1/capacity/matches` | `chat:account` bearer token | Ranked candidates or a typed refusal for one job requirement |

Both capacity projections come from one function, so a web reader and an API

reader with the same authority see the same numbers.

## Matching

`POST /api/v3/capacity/matches` takes one typed requirement:

`POST /api/v1/capacity/matches` takes one typed requirement:

```json

{

environments. It is not the forge fleet-promotion surface. Promoting the

OpenAgents release itself remains operator-only behind `deployments:promote`,

and nothing described here can reach it. That surface is

`OpenAgents.Forge.Promotion` behind `POST /api/v3/admin/forge/targets`; it

`OpenAgents.Forge.Promotion` behind `POST /api/v1/admin/forge/targets`; it

requires the privileged scope *and* live operator standing, and it is

documented in [API authentication](api-authentication.md) and the

[production deploy runbook](operations/production-deploy-runbook.md).

## API

The routes live under `/api/v3/repos/:owner/:repo` and require

The routes live under `/api/v1/repos/:owner/:repo` and require

`deployments:write` or a workflow grant. `forge:write` is not deployment

authority.

`OpenAgents.DataRights.ExportInventory` is that ledger. It classifies every

resource family the API publishes, plus the families that leave through routes

outside `/api/v3`, into four statuses:

outside `/api/v1`, into four statuses:

| Status | Meaning |

| --- | --- |

A legacy identity attaches to an account through `forum_actor_links`

(`OpenAgents.Forum.ActorLink`). An account starts a claim at `/forum/claim`

(or `POST /api/v3/forum/claims`), which creates a `pending` link; an operator

(or `POST /api/v1/forum/claims`), which creates a `pending` link; an operator

approves or rejects it at `/admin/forum/claims`. Only links in status

`linked` resolve a post to an account (`OpenAgents.Forum.actor_user/1`), so

unclaimed and rejected identities stay attributed to their legacy display

board, and a topic, and the sidebar row points every reader at the forum

rather than only signed-in accounts. Posting, claiming a legacy identity at

`/forum/claim`, and setting a tip destination at `/forum/tips` still need an

account. The `/api/v3/forum` reads are public, and writes require a

account. The `/api/v1/forum` reads are public, and writes require a

`forge:write` token.

No runtime dependency on `khala_sync_prod` remains. The only code that names

## Intent

OpenAgents exposes a bounded `/api/v3` subset so familiar GitHub-shaped clients

OpenAgents exposes a bounded `/api/v1` subset so familiar GitHub-shaped clients

can interact with issues and project boards. The shape is a compatibility aid,

not a claim that the application implements the complete GitHub API.

GitHub has no parameter that lists one kind without the other, so the

OpenAgents `type` filter (`issue`, `pull_request`, or `all`, defaulting to

`all`) is published under `issue.openagents` at `GET /api/v3` rather than

`all`) is published under `issue.openagents` at `GET /api/v1` rather than

presented as a GitHub parameter.

## Implemented Projects V2 subset

  "message": "Validation Failed",

  "code": "validation_failed",

  "status": 422,

  "documentation_url": "https://openagents.com/api/v3",

  "documentation_url": "https://openagents.com/api/v1",

  "request_id": "GM5_fLaSSJDluDMAACUh",

  "errors": { "state": ["must be one of: open, closed, all"] }

}

| `message` | The human sentence. A GitHub-shaped client reads this key, and a missing resource still reads exactly `Not Found`. |

| `code` | A stable identifier from the table below. Branch on this, not on `message`. |

| `status` | The HTTP status, repeated so a logged body is self-describing. |

| `documentation_url` | This deployment's `GET /api/v3`, which publishes the codes and the routes. |

| `documentation_url` | This deployment's `GET /api/v1`, which publishes the codes and the routes. |

| `request_id` | The value of the response's `x-request-id`. Name it when you report a failure. |

| `errors` | Field name to an array of messages. Always present, `{}` when the failure is not field-level. |

pipelines. New clients read `code`. No key that a client already read has been

renamed or removed.

`GET /api/v3` publishes which routes answer with this envelope, under each

`GET /api/v1` publishes which routes answer with this envelope, under each

route's `errors` field. Routes marked `legacy` there still answer with their own

shape; the repository, deployment, box, forum, and agent families have not been

converged yet, and `priv/api-contracts/repositories-v1.json` remains the

## Route inventory

`GET /api/v3` is the root document. It is derived from

`GET /api/v1` is the root document. It is derived from

`OpenAgentsWeb.Router.__routes__/0` through `OpenAgentsWeb.ApiRouteAuthority`,

never maintained beside it, so it cannot claim a route the router does not

serve or omit one it does.

```sh

openagents api /api/v3

openagents api /api/v1

```

It carries:

```json

{

  "method": "GET",

  "path": "/api/v3/repos/{owner}/{repo}/issues/{issue_number}",

  "path": "/api/v1/repos/{owner}/{repo}/issues/{issue_number}",

  "authority": "optional_bearer",

  "family": "issue",

  "errors": "envelope",

These are current measured behaviors:

- `/api/v3` anonymous and optional-bearer reads and authenticated writes use

- `/api/v1` anonymous and optional-bearer reads and authenticated writes use

  separate pipelines.

  Writes require an expiring digest-only `oa_pat_…` bearer with exact

  `forge:write` scope. An authenticated person creates and revokes credentials

  objects; this one is a field-to-messages map, which is what the local

  clients already read.

- Families outside the issue family still answer with their own error shapes.

  `GET /api/v3` names which, so a client can tell without probing.

  `GET /api/v1` names which, so a client can tell without probing.

Closed on 2026-08-21, each pinned by tests: label rename through `new_name`,

create-on-add for missing labels at the issue-labels endpoint, 404 for

| Project list | `/:owner/:repo/projects` | Writable members |

| Project board | `/:owner/:repo/projects/:number` | Writable members |

The matching `/api/v3` issue, comment, label, assignee, milestone, and Projects

The matching `/api/v1` issue, comment, label, assignee, milestone, and Projects

V2 subset is implemented and covered. The dated

[coverage audit](2026-08-20-test-coverage-audit.md) records the original gaps

and the coverage added to close them. The

The implementation tasks are no longer the readiness bottleneck. The resource

model must now be hardened rather than expanded from this checklist:

- `/api/v3` now has a deliberate CLI model: public reads are separate and every

- `/api/v1` now has a deliberate CLI model: public reads are separate and every

  write requires an expiring first-party bearer with `forge:write` scope.

- Owner/repository URL parameters do not yet map to a canonical repository row

  enforced throughout PostgreSQL.

## Address a route

A relative path resolves under `/api/v3/`:

A relative path resolves under `/api/v1/`:

```sh

openagents api repos/OWNER/REPOSITORY/issues

```text

repos/OWNER/REPOSITORY/issues

/api/v3/repos/OWNER/REPOSITORY/issues

/api/v1/repos/OWNER/REPOSITORY/issues

```

An absolute path must start with `/api/`. A complete URL must use the exact API

curl -sS -X POST \

  -H 'Content-Type: application/json' \

  -d '{"handle":"release-bot","display_name":"Release bot"}' \

  https://openagents.com/api/v3/agents/register

  https://openagents.com/api/v1/agents/register

```

The response contains an `oa_agent_…` credential exactly once. Store it

export OPENAGENTS_AGENT_TOKEN='oa_agent_ID.SECRET'

curl -sS \

  -H "Authorization: Bearer $OPENAGENTS_AGENT_TOKEN" \

  https://openagents.com/api/v3/agent

  https://openagents.com/api/v1/agent

```

The credential carries only `agent:participate`. It can create a forum topic

  -H "Authorization: Bearer $OPENAGENTS_AGENT_TOKEN" \

  -H 'Content-Type: application/json' \

  -d '{"user_id":"USER_UUID"}' \

  https://openagents.com/api/v3/agent/links

  https://openagents.com/api/v1/agent/links

openagents api agents/links

openagents api -X POST agents/links/LINK_ID/accept

  "message": "Validation Failed",

  "code": "validation_failed",

  "status": 422,

  "documentation_url": "https://openagents.com/api/v3",

  "documentation_url": "https://openagents.com/api/v1",

  "request_id": "GM5_fLaSSJDluDMAACUh",

  "errors": { "state": ["must be one of: open, closed, all"] }

}

## Discover the API

`GET /api/v3` describes the deployment you are talking to:

`GET /api/v1` describes the deployment you are talking to:

```sh

openagents api /api/v3

openagents api /api/v1

```

It publishes the OpenAgents extension fields, the error envelope and its codes,

## Forum endpoints

The forum surface lives under `/api/v3/forum`. Reads are public; writes need

The forum surface lives under `/api/v1/forum`. Reads are public; writes need

a `forge:write` API token and attribute posts to the token's account.

| Method | Path | Description |

body answers `409 idempotency_conflict`. A stale

`expected_current_target_id` answers `409 precondition_failed`.

Refusals use the shared `/api/v3` error envelope, so a script branches on

Refusals use the shared `/api/v1` error envelope, so a script branches on

`code`:

| Code | Status | Meaning |

openagents api [flags] <path>

```

A path without a leading slash resolves under `/api/v3/`. For example,

A path without a leading slash resolves under `/api/v1/`. For example,

`repos/OWNER/REPOSITORY/issues` and

`/api/v3/repos/OWNER/REPOSITORY/issues` name the same route. An absolute path

`/api/v1/repos/OWNER/REPOSITORY/issues` name the same route. An absolute path

must start with `/api/` and stay on the selected API origin.

| Flag | Description |

```sh

curl --request DELETE \

  --header "Authorization: Bearer $OPENAGENTS_TOKEN" \

  https://openagents.com/api/v3/repos/OWNER/REPOSITORY

  https://openagents.com/api/v1/repos/OWNER/REPOSITORY

```

Success returns `204 No Content`.

curl --request POST \

  --header "Content-Type: application/json" \

  --data '{"scope": "deployments:promote"}' \

  https://openagents.com/api/v3/device/authorizations

  https://openagents.com/api/v1/device/authorizations

```

Open `/device` in a signed-in operator browser, confirm the code, and read the

curl --request POST \

  --header "Content-Type: application/json" \

  --data '{"device_code": "'"$DEVICE_CODE"'"}' \

  https://openagents.com/api/v3/device/authorizations/token

  https://openagents.com/api/v1/device/authorizations/token

```

Approval is refused unless the approving account is a current operator. A

    "idempotency_key": "release-2026-08-23-0001",

    "expected_current_target_id": "'"$CURRENT_TARGET_ID"'"

  }' \

  https://openagents.com/api/v3/admin/forge/targets

  https://openagents.com/api/v1/admin/forge/targets

```

The response is `202 Accepted` with the immutable target ID, the exact SHA,

openagents api admin/forge/targets

```

Refusals carry the shared `/api/v3` error envelope. Three codes matter during

Refusals carry the shared `/api/v1` error envelope. Three codes matter during

an incident:

- `idempotency_conflict` (409) — that key already names different bytes. Pick a

List promises by state:

```text

GET /api/v3/repos/{owner}/{repo}/projectsV2/{project_number}/items?promise_state=LIVE

GET /api/v1/repos/{owner}/{repo}/projectsV2/{project_number}/items?promise_state=LIVE

```

List bounty candidates:

```text

GET /api/v3/repos/{owner}/{repo}/projectsV2/{project_number}/items?bounty_candidate=true

GET /api/v1/repos/{owner}/{repo}/projectsV2/{project_number}/items?bounty_candidate=true

```

Read the append-only history for an item:

```text

GET /api/v3/repos/{owner}/{repo}/projectsV2/{project_number}/items/{item_id}/events?page=1

GET /api/v1/repos/{owner}/{repo}/projectsV2/{project_number}/items/{item_id}/events?page=1

```

Promise data appears under `openagents.promise`. Evidence that points to a

# Issues: Persistent Agent Continuity & Epistemic Memory System

### Issue #1: Formal Engram Schema (NIP-AE Companion Profile) & Redaction Invariants

**Target:** `openagents` (`packages/agent-experience-memory`), `openagents.com`

**Type:** Specification & Core Invariants

**Labels:** `agent-ready`, `memory`, `security`

**Description:**

Establish the formal data structures and security guarantees for durable episodic memory events (engrams).

1. Define the OpenAgents companion profile for NIP-AE `kind:30174` addressable events.

2. Implement strict zero-credential / zero-secret redaction filters (tokens, private SSH/Nostr keys, private IPs, environment variables) that run strictly *prior* to engram signing.

3. Define the explicit supersession model: memories are immutable once signed; corrections append new engrams that explicitly reference and supersede previous event IDs.

**Acceptance Criteria:**

- Redaction test suite passing with 100% catch rate on synthetic tokens/secrets.

- Engram signature and supersession chain verification unit tests.

---

### Issue #2: Engram Client & Relay Sync Adapter in Agent SDK

**Target:** `openagents` (`packages/agent-experience-memory`)

**Type:** Feature

**Labels:** `agent-ready`, `sdk`, `nostr`

**Description:**

Implement the engram sync provider within `@openagentsinc/agent-experience-memory`.

1. Provide signing, symmetric encryption (scoped to owner conversation keys), and transport over Nostr relays.

2. Implement optimistic caching and background dispatch so engram persistence is completely non-blocking to interactive user turns.

3. Add degraded-mode resilience: turns proceed gracefully if the memory relay is unreachable.

**Acceptance Criteria:**

- SDK passes end-to-end integration test publishing encrypted engrams to a local relay.

- Synthetic network outage test confirms zero latency penalty or failure on agent turns.

---

### Issue #3: Deterministic Graph & Embedding Projection Worker

**Target:** `openagents.com` / `openagents`

**Type:** Feature

**Labels:** `agent-ready`, `indexer`, `cognee`

**Description:**

Build the projection layer that converts the append-only cryptographic engram log into a queryable semantic graph and vector index.

1. Ingest NIP-AE engrams from relay/storage and derive relational entities, attributes, and vector embeddings.

2. Ensure the projection layer is strictly ephemeral/derived: build an idempotent replay tool capable of cold-starting and regenerating the complete index from raw engram history.

**Acceptance Criteria:**

- Replay test takes raw engram stream and reconstructs an identical graph index.

- Conflicting/superseded engrams correctly invalidate stale nodes in the projection.

---

### Issue #4: Background Autonomous Consolidation ("Dreaming Loop")

**Target:** `openagents.com` (`OpenAgents.Memory.Consolidation`)

**Type:** Feature

**Labels:** `agent-ready`, `ai-research`, `background-jobs`

**Description:**

Build an asynchronous background worker that periodically reviews episodic engrams to synthesize high-level heuristics and lessons learned.

1. Identify fragmented episodic experiences across different sessions and cluster them by concept/topic.

2. Detect contradictions or outdated assumptions, proposing superseding synthesis engrams.

3. Compress multi-turn workflows into persistent heuristics (e.g., "when working on Phoenix routes in this repo, ensure reloader state is checked").

**Acceptance Criteria:**

- Background worker processes synthetic cluster of 20 episodic engrams into a single concise heuristic engram.

- Provenance links point back to source episodic engrams.

---

### Issue #5: Memory Evolution & Consent LiveView Dashboard

**Target:** `openagents.com` (`OpenAgentsWeb.MemoryLive`)

**Type:** UI / UX & Consent

**Labels:** `agent-ready`, `liveview`, `ui`

**Description:**

Provide an operator interface at `/memory` for auditing, inspecting, and managing persistent agent memory.

1. Visualize active memory graph, recent engrams, and derived heuristics.

2. Show full audit trail of supersessions and corrections.

3. Provide one-click retraction/forgetting tools that append cryptographically signed deletion/tombstone receipts.

**Acceptance Criteria:**

- LiveView renders memory timeline and graph nodes.

- Operator can view superseded history and trigger explicit memory redaction/tombstones.

---

### Issue #6: Scoped Memory Inheritance for Subagent Delegation

**Target:** `openagents` (`packages/openagents-cli/src/delegate`)

**Type:** Feature

**Labels:** `agent-ready`, `coder`, `delegate`

**Description:**

Enable child agents spawned via `delegate` (Devin, ox-alpha, gemini, etc.) to inherit relevant parent memory without leaking global context or credentials.

1. When `delegate` is invoked, query the parent memory graph for task-relevant heuristics based on the child's prompt.

2. Inject a sanitized "Epistemic Context" block into the child agent bootstrap prompt.

3. Ensure no private keys, conversation-private engrams, or unrelated session state leak to the subagent harness.

**Acceptance Criteria:**

- Child prompt includes relevant repository heuristics derived from previous sessions.

- Zero credential leakage confirmed by automated scanner.

---

### Issue #7: Child Engram Harvest & Parent Ledger Re-integration

**Target:** `openagents` (`packages/openagents-cli/src/delegate`)

**Type:** Feature

**Labels:** `agent-ready`, `coder`, `delegate`

**Description:**

Close the delegation loop by automatically harvesting discoveries, changes, and verification receipts from child agents and committing them to the parent agent's memory ledger.

1. Parse child execution artifacts, logs, and receipts upon task completion.

2. Construct and sign new episodic engrams representing the child's verified findings and diffs.

3. Publish engrams to the parent agent's stream so subsequent turns and sessions benefit from the subagent's work.

**Acceptance Criteria:**

- Parent memory graph reflects subagent's findings immediately after child completes.

- Trace receipts link child process run to newly created engrams.

---

### Issue #8: Unified Multimodal Activity Stream & Context Continuity

**Target:** `openagents.com` (`OpenAgents.Voice`, `OpenAgents.Chat`)

**Type:** Feature

**Labels:** `agent-ready`, `multimodal`, `voice`

**Description:**

Unify memory and activity context across modalities (Voice, CLI terminal sessions, Web LiveView chat).

1. Merge voice tool execution steps, CLI coder events, and LiveView text turns into a unified timeline schema.

2. Ensure switching between speaking on voice, coding in terminal, and reviewing on web shares the exact same active memory state and context window.

**Acceptance Criteria:**

- Conversation begun on voice can be continued seamlessly in CLI coder with full context recall.

- Ordered tool steps from all modalities display in a unified transcript view.

# Project: Persistent Agent Continuity & Epistemic Memory System

## Overview

A comprehensive architecture and implementation plan for continuous agent memory, self-consolidation ("dreaming/consolidation" loop), epistemic heritage for delegated subagents, and cryptographic engram storage.