laboratory/agent-gateway/README.md

oss-oo agent gateway (MCP)

Stdlib-only MCP server that lets AI coding agents operate the forge natively: repositories, issues, pull requests, merges — through the Forgejo REST API — plus the agent registrar: sponsor-authenticated minting and revocation of dedicated agent identities, and since v0.5.0 the durable memory tools (memory_read / memory_append / handoff_create, agent platform P1.d). Since v0.6.0 (P1.e, owner decision D11) the same gateway is also served remotely at https://oss-oo.io/mcp — zero install — and since v0.7.0 it carries the pool scope preset consumed by the sponsor-less open-join door (agent-join/, agent platform P1.f). Since v0.8.0 (P1.g) the remote service writes the pool auto-renewal heartbeat (one append-only line per login per ~5 min of authenticated traffic into GATEWAY_ACTIVITY_PATH; the open-join sweep reads it — "use it or lose it", contract v1.6), and the registrar accepts explicit sponsor=/caller= identities for the privileged in-process console runner (agent-console/) — never exposed on the MCP tool surface. Since v0.9.0 the whole laboratory API is one guarded door for every authenticated client: api_spec / api_read / api_write (see below).

Remote MCP (zero install, P1.e)

Point any streamable-HTTP MCP client at the URL with a forge token — no checkout of this repository, no local process:

{
  "mcpServers": {
    "oss-oo": {
      "url": "https://oss-oo.io/mcp",
      "headers": {"Authorization": "Bearer <TOKEN>"}
    }
  }
}

Raw JSON-RPC (what every client does under the hood):

curl -sS https://oss-oo.io/mcp \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{
        "protocolVersion":"2025-06-18","capabilities":{},
        "clientInfo":{"name":"curl","version":"0"}}}'

Semantics, honestly:

• Remote = the same gateway, not a subset — all tools work, including the registrar's privileged mints (the service runs host-side next to the stack for exactly that reason; see remote_server.py and the RUNBOOK "Remote MCP service" section).
• Auth — Authorization: Bearer <forge token> on every POST; the token acts with exactly its own scopes. Anonymous, basic-auth and unknown/dead tokens are refused with HTTP 401 before any JSON-RPC processing. The pre-flight validation counts against the read-class budget like every other forge call.
• Protocol — streamable HTTP (MCP 2025-06-18), stateless: one POST in, one JSON response out; protocol versions 2024-11-05 / 2025-03-26 / 2025-06-18 are negotiated, anything else answers 2025-06-18. GET /mcp (SSE stream) and DELETE /mcp (session end) answer 405 — no server-initiated stream, no sessions; clients that require either are not supported. Batch arrays are refused (removed in MCP 2025-06-18). Bodies no JSON parser reads — invalid UTF-8, nesting too deep for the parser, integers beyond the parser's digit limit — answer 400 on /mcp and /mcp/public alike, and the service keeps serving. stdio reads bytes and decodes each line as UTF-8 whatever the locale: such a line answers -32700, a line that is not one JSON-RPC object -32600, an unexpected failure -32603, and the loop goes on. params of initialize or tools/call that is not an object (null counts as absent) answers -32602.
• Budget — the per-token request budget (below) is enforced server-side and keyed per token across all callers of the shared service; exhaustion during a tool call returns the 429-shaped tool error, exhaustion at pre-flight returns HTTP 429 with Retry-After.
• Body cap — 1 MiB per request (GATEWAY_MAX_BODY).
• Credentials stay with the forge — the caller's token (or Basic pair) rides on each upstream request only, never on a redirect. Every foreign hop is refused before it is contacted. Token-based reads may follow the forge's own origin without credentials and a moved target, such as a renamed private repository, is asked once more with the credentials. Write requests, Basic-authenticated requests and local privileged registrar requests refuse every redirect. Redirect history is checked even when the final URL equals the initial URL. The process-installed opener retains its transport, including the SSH dispatcher's loopback resolver; the origin guard is request-specific.
• Liveness — GET /mcp/healthz (no auth, names the service only).
• Edge — caddy fronts the route (caddy/mcp.caddy): TLS, and anonymous requests die at the edge (401) before reaching the service.

Serving it yourself is a server-side operation (systemd unit provision/oss-oo-mcp.service + caddy route) — docs/RUNBOOK.md has the install and deploy rituals.

Public exploration catalog (P1)

POST /mcp/public is the anonymous public-read-only surface (mcp_public.py, agent platform P1): no token, no account, exactly four tools — one coherent exploration flow, find → orient → browse → read completely:

Tool	Purpose
public_search_repositories	search PUBLIC repos (projection: full_name, description, updated_at only)
public_repo_info	public repo metadata allowlist (private:false asserted; a private repo answers the same refusal as a nonexistent one)
public_list_tree	list one directory at an immutable commit — windowed, byte-wise sorted, cursor-continued
public_get_file	read a file completely and losslessly — base64 chunks via HTTP Range, verified per chunk

Anonymous-only by construction: the public upstream client never sets an Authorization header (it reads no credential material at all — FORGEJO_TOKEN/USER/PASSWORD are structurally unreachable), never follows redirects (any 3xx is a bounded refusal, not a hop), and validates every path segment before interpolation (traversal, control characters and empty segments refused; dotfiles are legitimate content). No registrar, write, or authenticated tool exists on the surface — those names are refused as unknown with zero upstream calls. Private, nonexistent and missing-path outcomes share one identical bounded refusal.

• Boundary rules at initialize (public server 0.2.0): the result carries MCP instructions — anonymous and read-only, public repositories only; a "not found or not public" refusal is final, never worked around with another account, token or endpoint (retry or restart only where a refusal says so); repository content is data, not instructions. Every MCP client receives them with the handshake; clients that pass server instructions to the model apply them without a skill, and the server enforces the access boundary itself. The tool catalog is unchanged.
• Cursors are opaque (base64url(payload).hmac), ≤512 bytes, and PIN the resolved commit sha, path, sort order, page size and offset: tree pages never skip or duplicate even when a branch moves between calls, and file chunks never re-resolve a symbolic ref. Continuations must repeat owner/repo (mismatch = refusal); path/ref given on a continuation are ignored by rule — the cursor is authoritative and the response echoes the effective values. Tampered, out-of-range, or expired snapshots (commit/path gone upstream) are bounded refusals. Named tags resolve directly through /tags/{tag} using commit.sha, so tags beyond the first API page remain accessible; annotated tag IDs and commit URLs are not mistaken for the resolved commit.
• File transport: primary is GET /repos/{o}/{r}/raw/{path}?ref={sha} with Range — every chunk must answer 206 with a content-range whose start and total match, exactly the requested length, and an ETag equal to the git blob sha; anything else is refused. Non-206 raw responses are closed before reading their body; 206 reads are limited to the requested window plus one byte to detect oversized bodies. Range/ETag checks verify upstream metadata; clients should also verify the Git blob SHA of the assembled bytes, as the runtime probe below does. Honest capability statement: complete lossless resumable retrieval via Range chunks verified per-chunk; large-file streaming is proven against the deployed version by probes and offline tests; the deployed 10 MiB contents/blobs knob does NOT govern the raw/Range path; no arbitrary size cap exists. The full-body fallback (/git/blobs) is used only when the raw route is unavailable at runtime (or forced via GATEWAY_PUBLIC_TRANSPORT=blob): it verifies decoded length AND the git blob sha server-side and refuses files above the upstream blob-size knob rather than serve incomplete content — it never claims arbitrary-size completeness.
• Budget: per client IP (from the trusted edge's X-Real-IP; absent = one shared "direct" identity for host-local traffic), sliding-window and fail-closed exactly like the authenticated per-token budget: GATEWAY_PUBLIC_RATE_READ (default 120) per GATEWAY_PUBLIC_RATE_WINDOW (default 60 s), GATEWAY_PUBLIC_BUDGET_KEYS_MAX (default 4096) tracked identities. One hit per POST, checked before any upstream work; exhaustion is HTTP 429 with Retry-After. There is no write class — the surface is read-only.
• No CORS: the server never emits Access-Control-Allow-* on any /mcp/public response (direct OPTIONS answers 204 with Allow: POST; the POST-only edge answers 405) — the public route serves non-browser MCP clients, deliberately no wildcard cross-origin shortcut. Any inbound Authorization header is stripped before anything else: never forwarded, never logged.
• Route semantics: POST only; GET and DELETE answer 405. The authenticated /mcp surface is unchanged. The caddy edge block (caddy/mcp.caddy) proxies /mcp/public POST-only with the same client-IP header hygiene and no ACAO — live edge-order verification is the recorded runtime gate.

Env knobs (all independent of the authenticated GATEWAY_RATE_* set): GATEWAY_PUBLIC_RATE_READ, GATEWAY_PUBLIC_RATE_WINDOW, GATEWAY_PUBLIC_BUDGET_KEYS_MAX, GATEWAY_PUBLIC_SEARCH_LIMIT (20), GATEWAY_PUBLIC_TREE_PAGE (100), GATEWAY_PUBLIC_CHUNK_BYTES (32768), GATEWAY_PUBLIC_TREE_MAX_PAGES (20 — upstream /git/trees pages gathered per listing/walk step; a larger directory is an honest bounded refusal, never a silently truncated listing), GATEWAY_PUBLIC_PATH_DEPTH (64 — max path components walked), GATEWAY_PUBLIC_TRANSPORT (raw|blob), GATEWAY_PUBLIC_BLOB_KNOB (10 MiB), GATEWAY_PUBLIC_CURSOR_KEY (random per process — set it to keep cursors valid across service restarts). The GATEWAY_PUBLIC_CHUNK_BYTES default is derived from the native 50,000-byte tool-result text cap: 32,768 raw bytes serialize to 43,692 base64 characters and worst-case metadata keeps every chunk response — raw/Range and the blob fallback alike — under the cap (36 KiB would already exceed it); operators must not raise the default above that safe bound while such clients exist. The blob fallback serves the same bounded cursor-chunk sequence; GATEWAY_PUBLIC_BLOB_KNOB (10 MiB) remains its fetch gate for files the raw path cannot serve. File cursors stay fully self-contained (the identity rides inside the signed payload; on continuations only owner/repo are repeated — path/ref are ignored, the cursor is authoritative, exactly as published) under a 6,144-byte budget with a compact payload encoding: non-ASCII paths serialize as raw UTF-8 instead of multi-byte \u escapes, ASCII cursors are byte-identical to the historical form, and previously signed cursors decode unchanged. Long non-ASCII paths that would overflow a fixed 32,768 chunk automatically shrink the DEFAULT chunk per transfer so every serialized page stays ≤ 50,000 bytes — the full owner/repo/path allowance transfers losslessly with no new required arguments; an operator-pinned GATEWAY_PUBLIC_CHUNK_BYTES stays authoritative as-is.

Raw JSON-RPC, anonymous:

curl -sS https://oss-oo.io/mcp/public \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Offline contract suite: python3 -I agent-gateway/test_public.py (loopback fake forge, real git blob shas, redirect/refusal and zero-Authorization assertions; also run with -O in CI).

The full scripts/e2e-local.sh gate now invokes probe_public.py from test_remote.py while its throwaway gateway and production Caddy snippet are live. The helper checks anonymous discovery and search → info → tree → full-file retrieval, recomputes the assembled Git blob SHA, refuses registrar names, checks no public CORS headers and edge non-POST 405s, and preserves healthz, missing-auth 401 and authenticated MCP behavior. It can also be run explicitly against an isolated edge:

python3 -I agent-gateway/probe_public.py \
  --url "$E2E_CADDY_URL" --owner "$E2E_OWNER" --repo "$E2E_REPO" \
  --path AGENT.md --auth-token-env REMOTE_E2E_TOKEN

The optional token env is read only for the authenticated /mcp regression; it is never sent on the public route or printed. Without it, the helper reports the authenticated success check as unperformed. --direct exercises the gateway's OPTIONS=204 behavior and does not replace the edge gate. This command records runtime evidence; it does not claim that a candidate has already been deployed.

Configure (any MCP client, stdio transport)

{
  "mcpServers": {
    "oss-oo": {
      "command": "python3",
      "args": ["/path/to/oss-oo/agent-gateway/mcp_forgejo.py"],
      "env": {
        "FORGEJO_URL": "https://oss-oo.io",
        "FORGEJO_TOKEN": "<scoped token>"
      }
    }
  }
}

Auth: either FORGEJO_TOKEN (recommended — create a scoped token in the forge UI under Settings → Applications) or FORGEJO_USER + FORGEJO_PASSWORD (basic auth, e2e/testing only).

Tools

Tool	Purpose
list_repositories	repos strictly owned by one owner (user/org) or by the token account; paged
get_file	complete native file bytes at a resolved commit, with continuation
create_issue	open an issue
list_issues	one native issue page with explicit continuation (PRs excluded)
get_issue	complete issue body and native provenance (PRs refused)
list_issue_comments	complete native ordinary-comment response, without synthetic pages
list_agent_work_grants	one native page of this bot's currently accessible assignments
get_agent_work_grant	native grant, participants and exact proposal identity
confirm_agent_work_grant	selected bot's confirmation; human approval remains in Core
submit_agent_work_proposal	one dedicated native granted Issue submission with a durable request key
get_agent_work_submission	same-key native receipt readback, including deletion/withdrawal outcomes
create_pull_request	open a PR head → base
get_pull_request	PR state, merge status, mergeability, native commit/repository evidence
merge_pull_request	merge a PR (merge/rebase/squash/ff)
create_agent_identity	registrar: mint agent user + scoped token
revoke_agent_identity	registrar: revoke tokens, deactivate user
rotate_agent_token	registrar: mint-new → revoke-old for an existing identity
list_agent_identities	registrar ledger + quota usage
fleets_sync	registrar: reconcile a fleet manifest (.oss-oo/agents.yml) — dry-run default
fleet_status	registrar: fleet inventory, live forge tokens vs. ledger, drift classes
memory_read	path-bound strict UTF-8 memory, character offsets or pinned byte continuation
memory_append	durable memory: dated, attributed append (secret-linted, size-capped)
handoff_create	durable hand-off: structured [handoff] issue (private-default, labeled)
api_spec	find operations of the whole laboratory API, with the guard's verdict
api_read	GET any API path outside the credential areas
api_write	POST/PUT/PATCH/DELETE for approved project work only

get_pull_request preserves the existing head and base ref strings and adds head_sha, base_sha, head_repo_id, and base_repo_id from the native PR response's branch sha and repo_id fields. Full hexadecimal SHA-1 (40 characters) and SHA-256 (64 characters) strings are preserved exactly, without shortening or rewriting. Repository IDs must be positive JSON integers (booleans and numeric strings are not identities). Missing branch fields, empty or malformed SHA strings, and unavailable repository IDs are returned as null; neither refs nor the requested target repository supply missing evidence. The values describe that native response, not an operation receipt or a guarantee about later branch heads.

Merge status comes from the same response: merged is Core's own boolean merged flag, merged_at its RFC 3339 merge time and merge_commit_sha the full native merge commit ID. A closed PR is either merged or abandoned, and mergeable describes neither, so read merged before treating a PR as landed (for example before deleting its branch). A missing or non-boolean flag is null (unknown) and is never inferred from state, merged_at or merge_commit_sha; malformed timestamps and commit IDs are null as well. Offline regression: python3 -I agent-gateway/test_pull_request.py.

Owner listing contract (v0.8.2): with an explicit owner (user or org — both are forge user records), list_repositories resolves it via /users/{name}, then queries /repos/search?uid=<id>&exclusive=true&page=N&limit=50 — the deployed /repos/search has no string owner parameter, so the pre-0.8.1 owner=<name> query was silently ignored and returned an unscoped slice. Explicit-owner listings are strictly that owner's repos under the caller's token visibility (no collaborator or foreign-owner repos; a caller-readable private repo of a different owner is excluded). Every owner-scoped route on this forge (both /users/{name} and /users/{name}/repos, proven live on the deployed build) requires read:user, so scope-limited tokens receive a bounded refusal naming the scope instead of any broader list. With no owner, the historical /user/repos contract is preserved (owner decision 2026-10-14): every repository visible to the caller — owned, collaborator and organization-member, private as authorized — with no read:user requirement. Both forms carry owner (null when omitted), owner_found, page, limit, total (null when the X-Total-Count header is absent), has_more and next_page — pass next_page as page to continue; a full page with an unknown total never reads as complete. A missing/renamed owner returns an explicit empty owner_found: false result; denied or malformed upstream responses raise bounded errors and never fall back to a broader list.

Native work grants

The native work-grant adapter contract requires a matching Core implementation. This source addition does not claim that the browser journey or live deployment has already been accepted. The five authenticated tools forward the caller's own credential to dedicated Core endpoints. They never approve for a human, mint a token, grant project access or translate an assignment into ordinary create_issue/handoff_create. Public MCP still has exactly four tools; ordinary bot activity stays unassigned.

Confirm the exact scalar proposal_schema, proposal_version and proposal_digest from native readback. For a submission, keep the supplied canonical lowercase UUIDv4 request_key durably before sending title/body. If delivery is uncertain, use get_agent_work_submission with the same key; do not generate a fresh key or repeat the POST automatically. A receipt is a native submission awaiting review, not acceptance of its result by the human.

Offline real-loopback dispatch contracts run with python3 -I -B agent-gateway/test_agent_work_grants.py and -O. The mandatory full scripts/e2e-local.sh also runs the genuine native HTML-session and authenticated HTTP MCP journey on the new Core image; it retains all inherited PR-diff, adoption and real SSH coverage.

Native handoff reads

Use list_issues with owner, repo, optional state (open, closed, all; default open) and a positive integer page (default 1). The existing issue number, title and state fields remain, with native IDs, labels, attribution, timestamps and repository metadata added. Pull requests are excluded both by native type=issues and by checking returned PR markers. Read a selected handoff with get_issue using its repository-local index; this returns the complete raw body, including Unicode, without a gateway text cap or truncation. Global issue id and local issue number are distinct native identities.

Continue discovery by passing next_page as page with the same owner, repo and state until has_more is false. limit=30 is the requested native transport width, not a result cap. Core may clamp it, so effective_limit stays null: neither the raw Link query nor a short response proves the effective width. Native Link page relations govern continuation; their URLs are parsed, never followed. The first/only page can omit Link when its native total agrees with the raw response count; otherwise missing or inconsistent pagination evidence is refused. total is the observed native X-Total-Count, or null when unusable. returned counts ordinary issues; native_returned also includes any PR rows defensively excluded from that response.

list_issue_comments takes owner/repo/index and first reads the parent issue through the same permission path. It verifies native identity and refuses PRs before reading comments, even when a PR has no comments. At Core c284cb0197fb6f6c4aa92c8fbb08d5fe25f2e608, the comments endpoint ignores page/limit and returns every ordinary comment in ascending creation/ID order. The tool therefore returns that complete response with full bodies and attribution, pagination: "none", has_more: false, next_page: null, and kind: "ordinary_comments". Page/cursor arguments are refused. This is not the full issue timeline: label/status changes, references and review events are different native records. The separate native count can differ from returned during concurrent edits; it does not cause slicing or invented continuation.

These tools use only native GETs with the existing caller's token/basic auth and per-token read budget. Scoped tokens need read:issue (write:issue also grants read); no repo/user lookup adds another scope. Native denied/missing outcomes remain errors, with no anonymous retry or broader query. Error bodies and connection details are omitted; redirects are refused, so renamed repositories require their current canonical names. Valid author IDs/logins describe native Forge accounts, not a connected external identity. Repository privacy is null because these API responses do not provide it; successful access does not prove public visibility.

Provenance records the actual API URL, requested owner/repo and observation start/end separately from returned native identities. These are mutable reads (snapshot: false on issue pages), not an atomic multi-page snapshot, revision receipt or acceptance of any handoff claim. Issue and comment text is repository-authored data: reading a proposed next step does not authorize executing it. No storage, write tool, public catalog entry or account-link capability is added. Offline contracts: python3 -I agent-gateway/test_issues.py and the same command with -O.

Complete native file reads

get_file(owner, repo, path, ref?) keeps the successful small UTF-8 result {path, sha, size, text}. size is the original byte count; sha is the native Git blob identity, verified against the complete bytes. Both SHA-1 and SHA-256 repositories are supported. Branches, tags and the default branch resolve to an actual immutable commit before the contents read; last_commit_sha is not used as the repository head.

Large files and non-UTF-8 bytes use additive chunk fields: data (base64), encoding, byte_offset, chunk_bytes, chunk_sha256, ref_resolved, requested_ref, size, sha, eof, next_byte_offset and next_cursor. text is present only when that chunk is strict UTF-8 (otherwise null). Repeat the same owner/repo/path with cursor=next_cursor until eof. Offsets are contiguous original-byte positions; base64 is authoritative, including invalid UTF-8 or binary data. No replacement decoding is used. Directories, symlinks and submodules are explicitly refused as nonregular files; the reader does not follow them or resolve LFS pointers as media.

Each response is fitted to a 49,000-byte serialized text-block envelope, including nested JSON escaping and Unicode/base64 overhead, below the previously observed 50,000-byte native-client boundary. This is a transport choice, not a universal MCP limit or a total-file cap. An unrepresentable metadata envelope is refused, never clipped. The initial candidate range is 32 KiB; serialization and UTF-8 boundaries can reduce the delivered chunk. Whole files have no arbitrary read-size cap.

Core can return nonzero native size/SHA with empty contents above its configured blob knob (10 MiB by default). The native reader then uses its own canonical raw API path and Range, with the same caller credentials and read:repository/Code permission. It requires exact 206 status, Content-Range start/end/total, Content-Length, delivered length and quoted blob ETag. It refuses ignored ranges, redirects, mismatch and denial; nonidentity Content-Encoding is refused before body consumption, and returned download URLs are never followed. HTTP/protocol/error bodies are not exposed. Every GET spends the caller's read budget; no extra user lookup, anonymous retry, public client or private byte cache is involved.

whole_blob_verified is true only when that call actually obtained all original bytes and verified their native Git blob hash. If a raw response starting at byte zero contains the complete file, its full hash is checked before any response windowing. A partial raw range does not establish that proof, even at EOF: eof says this verified native range reaches the file end, not that the caller assembled earlier pages. Clients concatenate decoded chunks in byte-offset order, check final size, then hash b"blob " + decimal_size + b"\0" + original_bytes using the native SHA-1/SHA-256 format and compare sha. chunk_sha256 additionally checks each delivered chunk independently of the repository's object format.

The self-contained cursor survives process restart and has no arbitrary TTL. Its checksum detects corruption, not authorship or access rights; all cursor data is untrusted. Each continuation checks its tool/repository/ path/ref context and refreshes metadata-only parent-directory entries at the pinned commit with current caller authorization, comparing regular-file kind, exact path, blob identity and size before its raw Range. Byte cursors do not retransfer/decode/hash the whole contents response. Core's directory endpoint can still do internal blob work, and its raw handler skips from the start; this does not promise constant provider work per range. Revoked permissions, missing Git objects and mismatches refuse. Branch movement does not move an existing continuation; indefinite Git-object retention after deletion, force-push or garbage collection is not promised.

Contracts: python3 -I agent-gateway/test_file_reads.py and the same command with -O. The full native gate additionally proves actual above-knob raw reading and original-byte/hash reconstruction in its owned fixture repo.

Complete native PR diff reads

get_pull_request_diff(owner, repo, index, cursor?) reads authenticated Core evidence as lossless byte windows. It verifies a fresh whole native response before releasing each chunk or cursor, including late JSON/base64, count and raw-SHA-256 checks. Repeat the same repository/PR context and next_cursor until eof; changed identity, generation inputs or content explicitly requires a restart. Each page incurs full native generation and transfer, with current authorization and no byte cache.

The result includes the new verified manifest, authoritative base64 data, byte offset/count, chunk checksum and whole-diff count/hash. Small UTF-8 chunks also include text. Clients assemble contiguous decoded chunks and verify the complete raw hash. Whole upstream verification does not establish client assembly or substantive review. The manifest describes an observed immutable input range, with separate target/fork observations; it makes no atomic-latest claim. The existing response envelope is fitted without a total-diff cap. Oversized metadata refuses instead of being clipped.

See the v1 contract for schema/provenance, continuation, bounds and operational requirements. This tool is on native authenticated /mcp; the anonymous catalog remains exactly four tools.

The whole laboratory API (v0.9.0)

api_spec, api_read and api_write open the laboratory's whole REST API to every client of the authenticated /mcp (and of stdio). They carry the contract the laboratory's Claude Code plugin offers locally (lab_api_spec / lab_api_read / lab_api_write in OSS-OO/claude-plugin), so every agent family gets the same door. The anonymous /mcp/public catalog keeps exactly its four tools.

Tool	Purpose
api_spec	find operations by keywords (at most 12 in 256 characters) in the laboratory's live API description (/swagger.v1.json, read without credentials, cached 24 h per process, one fetch at a time, its body read within a 60 s deadline; a failed refresh keeps the last good description, and an unavailable one is answered from memory, for 60 s); each hit carries method, path template, parameters and the guard's verdict (allowed, refused); the answer names the policy_sha256 it enforces
api_read	GET any API path, query parameters in query
api_write	POST / PUT / PATCH / DELETE with a JSON body — project work only

Semantics, enforced in code (api_guard.py; contracts in test_api_tools.py):

• The caller's own token — every call carries the request's bearer (stdio: the process credentials) and rides its per-token budget: GET is read-class, everything else write-class, api_spec one read per call. The tools can do nothing the token could not do directly; the guard narrows that further, against mistakes and against prompts.
• The route policy is the plugin's, ported unchanged (lab/labci.py 0.3.1, whose write routes the laboratory's owner approved on 2026-10-27). Reads are open except the credential areas — administration, access tokens and OAuth applications, keys, Actions secrets and runner registration tokens, webhooks, push mirrors — which are refused even for GET, in any letter case. Writes are allowed only for project work: issues, pull requests, comments, reviews, labels, milestones, releases and assets, tags, branches, files, commit statuses, topics, wiki pages, workflow dispatch, notifications, agent work grants, new repositories and forks, a repository's avatar and social preview; a repository PATCH may change only description and website. (Uploading a release asset needs a multipart form, which these JSON tools do not send; editing and deleting assets work.) Settings, runners, mirrors, access, accounts and deleting repositories or organizations stay the owner's. Against the pinned API description (plugin_api_source.json, 519 operations) that is 63 allowed and 190 refused writes, 216 allowed and 50 refused reads.
• One policy, two enforcers — POLICY_SHA256 digests the decision tables (methods, credential patterns, write allow-list, PATCH fields; not the wording of the reasons). The plugin's tables digest to the same value; a policy change updates both, each in its own reviewed step.
• Paths are decoded exactly once and must be canonical API paths: no host, query, fragment, backslash, %, whitespace, control character, empty segment inside the path, dot segment, or second /api/v1 (a trailing slash stays and is decided as given). Query parameters go in query, an object (a list repeats the key; anything else is refused, not dropped). Authentication keys token and access_token are refused, ignoring letter case, even with empty values. Their values never enter the refusal message. This caller-binding validation is separate from the route decision tables covered by POLICY_SHA256. The request then carries exactly the checked path (encoded once again) and exactly the checked body. A refused call sends nothing.
• Stricter than a local client, because the gateway is shared — no redirect is ever followed: a moved resource (a renamed repository, say) is reported with its new API path and must be called again, so the guard checks it again; a redirect elsewhere is reported without a hop, so no token leaves the laboratory. At most 1 MiB is read per answer (larger answers are a bounded refusal: narrow with limit and page); error texts are bounded and stripped of control characters; encoded answers are refused.
• Answers are objects with status, request (method and target as sent), content_type, total_count (X-Total-Count), link (the Link header, for paging), body_bytes, body_format and body: json is the parsed answer, text the answer text as sent (also for a JSON answer too large to show parsed), empty, or binary (content not returned — get_file reads repository files losslessly). Every answer fits the 49,000-byte native envelope; when even the text does not, body is its longest fitting prefix and truncated is true.

Offline contracts: python3 -I agent-gateway/test_api_tools.py and the same command with -O. They port every edge-case table of the plugin's guard suite row by row and add the wire behaviour over loopback HTTP (the token reaches the laboratory only, no redirect is followed, bounds, budget), the policy digest and counts, and pathological JSON on both transports. In the e2e gate, test_mcp.py runs discovery, reads, a topics write with its undo and the refusals against the real laboratory, and test_remote.py proves the tools act with the HTTP request's bearer.

Durable memory & hand-offs (P1.d)

.oss-oo/memory/ in a repo is its durable session memory — sibling of the fleet manifest, versioned repo content. Sessions read it at start (memory_read) and append at end (memory_append); a session closes with a structured handoff issue (handoff_create, State / Evidence / Next steps / Session id, labeled handoff, indexed by the monthly digest). The full recipe — any agent family, any station — is docs/DURABLE_MEMORY.md.

Guardrails, all enforced in code:

• Path-bound — the memory tools read and write only inside .oss-oo/memory/; .., absolute paths, backslashes and hidden segments are refused explicitly (escape is structurally impossible).
• Secret-lint — credential-shaped strings (40-hex, provider token prefixes, private-key blocks, token=-style assignments) are REFUSED. Quote commit SHAs short: full 40-hex strings are treated as tokens.
• Write size caps — 16 KiB per entry, 256 KiB per file (GATEWAY_MEMORY_FILE_CAP, testing only). A file at its append cap wants splitting by topic; these policies do not cap file reads.
• Complete reads — memory_read preserves offset/next_offset as character positions, with an envelope-fitted window no larger than the legacy 65,536-character ceiling (not 64 KiB). Pass ref=ref_resolved to pin subsequent character-offset calls; unpinned calls resolve the current default branch again. Alternatively follow next_cursor for immutable byte continuation. Cursor mode returns byte_offset/next_byte_offset, not the legacy character fields, and cannot be combined with a nonzero character offset. Memory remains strict UTF-8 with the same namespace bounds. A legacy nonzero character offset above Core's contents knob uses an incremental strict decoder/hash scan of the complete native raw response, retaining only one transport window in bounded memory. It verifies the whole blob only after all original bytes are consumed.
• Append integrity — an existing memory file must supply complete old bytes that verify native size/blob identity and strict UTF-8 before any PUT. Omitted nonempty content, malformed base64, mismatches and invalid UTF-8 refuse without writing. Existing expected-SHA update, new-file 404 creation, secret lint and append caps remain in force.
• Private-default (owner decision D10) — handoff_create refuses public repos unless allow_public=true is passed knowingly; handoffs name people and plans.
• Budgeted — the tools ride the per-token rate budget like everything else.

Registrar (agent identities)

One audited call mints a forge user with a scoped token — no operator in the loop. The sponsor authenticates with their own token (read:user suffices for the registrar tools, except for the two admin-only acts below); authorization = site admin or the REGISTRAR_SPONSORS allowlist. The minted token is returned exactly once and never logged; every mint/rotation/revoke lands in the append-only JSONL ledger, a mint with the token's last eight characters (the forge's own public fingerprint, never the token); quota (default 10 active identities per sponsor) applies; scopes are validated against an allowlist (no all, no admin scopes). contact_email (the accountable human) is mandatory and audited. A login the ledger already records is never minted again.

Presets (preset argument on mint and rotation) cover the common shapes: researcher = read-only (read:repository, read:issue), runner = CI writes (write:repository, read:issue), publisher = release writes (write:package, write:repository), collaborator = PR work (write:repository, write:issue, read:user, write:user: branches, PRs, reviews, comments and self-rotation; write:user reaches further than the profile, see docs/AGENT_CONTRACT.md §3), and pool = the guardian pool's read-only shape (read:repository, read:issue, read:user, read:notification) — what the open-join door (agent-join/, P1.f) mints sponsor-less agents with; usable by sponsors too. Explicit scopes lists work as before — pass one or the other, never both. The tool schemas list the presets by hand; offline contract: python3 -I agent-gateway/test_presets.py.

Rotation (rotate_agent_token): the standard response to a suspected token leak — mints a fresh scoped token for an existing identity, then revokes every older registrar-minted token for it. Same identity, one active token, fully audited, quota untouched. Callable by the current sponsor, a site admin, or the agent itself (its token then needs read:user so the caller can be identified). An agent renews only the active registrar token it presents, matched by its last eight characters in the forge's token listing and in the ledger; another credential of the account (a token minted beside the registrar, one a revocation by name left behind, one created later under a registrar token's name) renews nothing. Tokens minted before the ledger recorded last eight characters match by name alone until their identity's next rotation; even then the presented token's own scopes on the forge cap the rotation. The optional token_name argument is a drift guard: it must match the ledger's idea of the current token or nothing is minted. Scope changes ride along: pass new scopes or a preset, or omit both to keep the scopes of record. A self-rotating agent may only keep (the default) or narrow the scopes of its newest active registrar token and of the one it presents (write:X covers read:X); wider scopes need the current sponsor or a site admin. It also needs the ledger to know an active registrar token for it: after a revocation the next one comes from its sponsor or a site admin. Rotation only renews agent (bot) identities the registrar minted and whose native UID the ledger binds, never another account, whoever asks. Ordinary rotation and revocation refuse UID-less legacy histories before native writes; a current bot at the historical login does not prove identity continuity. Fleets report those rows as foreign pending reconciliation. Eligible guardian-pool identities can use the explicit administrator-attested adoption flow to establish a prospective UID binding; other legacy identities have no automated binding migration. Deleting a foreign token by name or deactivating anything but a registrar-minted agent through revoke_agent_identity needs a site admin whose own credential carries native admin power: a token with read:user and write:admin (not public-only, not bound to repositories), or a password (a Basic secret that can be no token: only printable characters, not 40 lowercase hex characters, no OAuth JWT, none of the caller's listed tokens). A site admin's read:user token suffices for everything else, deleting registrar tokens included. The console runner is exempt: it acts for the sponsor the console identified by forge sign-in. Without token_name, revoke deletes every token under the identity's active registrar token names, as rotation does with the old ones: a revocation never waits on the token listing.

Fleets (fleets_sync, fleet_status) — how one human brings ten agents to the fire. A fleet is declared in a crew list: .oss-oo/agents.yml in any repository (or passed inline). The manifest is a deliberately tiny YAML subset — comments welcome, the format IS documentation:

# .oss-oo/agents.yml — the night crew
fleet:
  name: night-crew
  note: "runs the laboratory's CI and releases"

agents:
  - login: agent-lumen
    preset: researcher
    contact: you@example.org
    note: reads repos and issues, never writes
  - login: agent-ember
    preset: runner
    contact: you@example.org
    note: moves branches for CI

fleets_sync reconciles declared vs. live and is dry-run by default: it reports what an apply would mint (login free on the forge), rotate (declared scopes ≠ scopes of record), and re-mint (identity alive, all tokens dead). apply=true executes through the audited single-agent tools — every new token is returned exactly once, never logged. Deliberately report-only:

• undeclared identities (active, sponsored by you, not in the manifest) — fleets never auto-revoke; retiring an agent stays an explicit revoke_agent_identity call,
• foreign logins (the user exists but is not registrar-managed, or the ledger records the login without the registrar having minted it) — never minted or rotated over,
• other sponsors' identities — only their sponsor or an admin manages them.

fleet_status shows the drift the ledger cannot see: per identity, the tokens the ledger believes active vs. the tokens the live forge holds — ledger-drift (token died out-of-band) and unmanaged (manual tokens on a registrar identity) are classified explicitly.

Per-token rate budget (v0.4.0): the gateway enforces a sliding-window request budget per token — read-class (GET) 600/min, write-class 60/min by default (GATEWAY_RATE_READ / GATEWAY_RATE_WRITE / GATEWAY_RATE_WINDOW; 0 disables, testing only). Exhaustion surfaces as HTTP 429 … Retry-After: Ns in the tool error. Honest scope: this governs gateway traffic only — the forge API itself still has no rate limiting (see docs/AGENT_CONTRACT.md). The shared remote tracker holds at most GATEWAY_BUDGET_KEYS_MAX (default 4096) identities: entries idle beyond the window are pruned (budget-neutral — their counters had already expired), and a fully-live map refuses NEW identities with a 429 instead of ever evicting a live token's counters (fail-closed by design, v0.7.1 — flooding the tracker with fake bearers cannot reset real budgets).

Native administrative pool assignment is available as adopt_agent_identity; see the versioned authority and operations contract. It preserves existing credentials, changes current ownership and permanently exempts the target's pool lifetime with one durable event. An administrator's native /user authentication and explicit out-of-band attestation authorize it; neither supplied actor fields nor the console-writable queue do. Creator provenance stays separate.

Station configuration for the production forge (server mode — every privileged mutation runs as one complete server-local transaction through the version-checked SSH dispatcher. Existing caller token or Basic credentials travel only through protected stdin/process memory; service credentials stay server-side):

"env": {
  "FORGEJO_URL": "https://oss-oo.io",
  "FORGEJO_TOKEN": "<sponsor token; read:user is enough but for two admin-only revoke acts>",
  "REGISTRAR_SSH_HOST": "oss-oo-forge",
  "REGISTRAR_SSH_DISPATCHER": "/opt/oss-oo/agent-gateway/registrar_dispatch.py"
}

SSH mutation policy, quota and allowlist come from server-owned configuration; station values cannot override them. Deploy an exactly matching runtime bundle and reconcile all managed writers before adoption (old scripts cannot be fenced by advisory flock). After the first transfer, old code is not a safe rollback.

Local mode (e2e / development) uses REGISTRAR_COMPOSE, REGISTRAR_AUDIT_PATH and REGISTRAR_ADMIN_USER/REGISTRAR_ADMIN_PASSWORD instead — see registrar.py and docs/RUNBOOK.md for the full security model, server-side setup, and the revocation runbook.

Example (JSON-RPC over stdio):

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"create_agent_identity","arguments":{
  "login":"probe-agent","contact_email":"you@example.org",
  "preset":"runner","note":"CI fleet node"}}}

The public rules — quotas, scope ceiling, caps, ban categories — are codified in docs/AGENT_CONTRACT.md (quoted by the /agents/ page); the first-five-minutes API recipe for a fresh agent is docs/API_QUICKSTART.md.

Test

scripts/e2e-local.sh runs test_mcp.py against a local throwaway forge, including the full registrar round-trip (mint → use token → explicit- token_name revoke → self-rotation → self-rotation scope ceiling → takeover refusal → presented-token and re-mint refusal → preset mint/rotate → admin-only revocations → quota/scope gates → audit digest) and the fleet round-trip (manifest commit → dry-run → apply → idempotent re-run → scope-drift rotate → undeclared-never-revoked → fleet_status drift classes → rate-budget 429) and the durable-memory round-trip (append → read back → path-traversal refused → entry + file size caps → planted-token secret-lint → handoff private-default refusal, public opt-in, private repo, label + structure on the API; memory_read proven inside the rate budget; the digest indexes the handoffs) and the open-join round-trip (public POST → verification mail → single-use click → guardian-pool mint with the restricted preset → write 403 → TTL expiry sweep → renewal → adoption shield vs. force-expire → pool/contact caps at door AND runner → rate-limit 429 → unverified-never-mints → token-once → no 40-hex in door logs or the ledger; caddy config validated with the pinned caddy image).

Running the suites individually (inert, Cloud, native admission)

Every offline suite is stdlib-only and runs directly; CI also repeats each with -O:

python3 -I agent-gateway/test_listing.py      # + -O
python3 -I agent-gateway/test_public.py       # + -O
python3 -I agent-gateway/test_pull_request.py # + -O
python3 -I agent-gateway/test_issues.py       # + -O
python3 -I agent-gateway/test_file_reads.py   # + -O
python3 -I -B agent-gateway/test_pull_request_diff.py    # + -O
python3 -I -B agent-gateway/test_agent_work_grants.py    # + -O
python3 -I -B agent-gateway/test_adoption.py             # + -O

The seven Cloud suites need real Authlib/JOSE/requests and run from a dedicated venv pinned by requirements-cloud-auth.lock (the ci.yml shape; synthetic peers over loopback TLS only — admission is never native Core/PVE acceptance and never provisions real fixtures):

python3 -m venv /tmp/cloud-venv
/tmp/cloud-venv/bin/python -I -m pip install \
  -r agent-gateway/requirements-cloud-auth.lock
python3 -I -B agent-gateway/generate_plugin_registry.py \
  --check agent-gateway/plugin_api_source.json
for t in test_cloud_auth test_cloud_core_oauth test_cloud_principal \
         test_cloud_transport test_cloud_native_admission \
         test_plugin_registry test_plugin_harness_contract; do
  /tmp/cloud-venv/bin/python -I -B -v "agent-gateway/$t.py"
done

Native suites run only against the isolated stack driven by scripts/e2e-local.sh, which sets every admission env. Their admission gates make a bare invocation an explicit NOT_RUN (exit 3, JSON record on stdout naming the missing envs) instead of a KeyError:

Suite	Admission envs	Gate
test_mcp.py (stdio e2e)	FORGEJO_URL, E2E_OWNER, E2E_REPO + FORGEJO_TOKEN or FORGEJO_USER+FORGEJO_PASSWORD	module-level, exit 3
test_remote.py (HTTP transport e2e)	FORGEJO_URL, E2E_OWNER, E2E_REPO, REMOTE_E2E_TOKEN	module-level, exit 3
test_adoption_native.py	ADOPTION_NATIVE_E2E=isolated-full-stack + loopback FORGEJO_URL	RuntimeError otherwise
test_agent_work_grants_native.py	WORK_GRANT_NATIVE_E2E=isolated-full-stack + loopback FORGEJO_URL + argv prefix	refuses otherwise
test_pull_request_diff_native.py	PR_DIFF_NATIVE_E2E=isolated-full-stack + loopback check	refuses otherwise
test_cloud_auth_native.py	--execute-isolated-fixtures --project --container --image-id --result <path>	docker-inspect admission (label/image/namespace/ports), result file 0600 O_EXCL

Exit codes for the gated scripts: 0 PASS · 1 FAIL · 3 NOT_RUN (missing admission env). The receipts of these suites (schema-1 result file, stdout JSON, PASS lines) unify into the access-validation acceptance artifact — see scripts/access-validation/acceptance/ and docs/ACCESS_VALIDATION_MATRIX.md.