From d052dd666b41cfe1f99e6f0d8d592204c000a615 Mon Sep 17 00:00:00 2001 From: Ben Brandt Date: Wed, 4 Feb 2026 13:11:24 +0100 Subject: [PATCH 1/2] docs(rfd): Move registry RFD to preview Updates the rfd to match the current implementation. --- docs/docs.json | 3 +- docs/rfds/acp-agent-registry.mdx | 210 +++++++++++++++++++++---------- 2 files changed, 147 insertions(+), 66 deletions(-) diff --git a/docs/docs.json b/docs/docs.json index 406b75d5..d0fd8828 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -116,14 +116,13 @@ "rfds/proxy-chains", "rfds/mcp-over-acp", "rfds/session-usage", - "rfds/acp-agent-registry", "rfds/auth-methods", "rfds/rust-sdk-v1", "rfds/logout-method", "rfds/session-delete" ] }, - { "group": "Preview", "pages": [] }, + { "group": "Preview", "pages": ["rfds/acp-agent-registry"] }, { "group": "Completed", "pages": [ diff --git a/docs/rfds/acp-agent-registry.mdx b/docs/rfds/acp-agent-registry.mdx index c24c1d27..5a10b752 100644 --- a/docs/rfds/acp-agent-registry.mdx +++ b/docs/rfds/acp-agent-registry.mdx @@ -15,112 +15,194 @@ There is no canonical listing of ACP-compatible agents. Information lives in sca - Let users discover agents directly inside ACP-aware clients. - Ensure protocol-version compatibility or capability coverage. -- Keep metadata consistent (auth requirements, hosting model, license, etc.). +- Keep metadata consistent (hosting model, license, etc.). Every editor builds bespoke manifests or scrapes GitHub, leading to duplication and stale data. ## Agent manifest format (core proposal) -Each agent advertises itself via `agent.json` stored under `/` in the registry repo. JSONC keeps things close to ACP’s JSON-centric schemas while remaining human-friendly during authoring. Fields (required unless noted): - -| Field | Description | -| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `id` | Lowercase slug, unique across registry (also the folder name). | -| `name` | Human-readable label. | -| `version` | Agent release version surfaced to users. | -| `schema_version` | Semver of the manifest schema. Allows future breaking changes. | -| `description` | Description of the agent's functionality and purpose. | -| `homepage` | URL for docs/marketing. | -| `repository` | Source repository URL. | -| `authors` | Array of author/organization names (mirrors `authors` in the TOML example). | -| `license` | Licence (string). | -| `capabilities` | Array of ACP method names implemented (e.g. `["terminal/new","files/read"]`). | -| `auth` | Array of auth options for authentication. This is the trickiest part of the schema. | -| `distribution` | Object mapping target platforms to download/execution info. Each target key follows `-` format (e.g., `darwin-aarch64`, `linux-x86_64`, `windows-x86_64`). Each target specifies `archive` (download URL), `cmd` (executable path), optional `args` (array of command-line arguments), and optional `env` (object of environment variables). | - -Example skeleton: +Each agent or extension advertises itself via a manifest stored under `/` in the registry repo. Agents use `agent.json`; extensions use `extension.json`. A directory must contain one or the other, but not both. Both file types share the same schema. + +Fields marked with **\*** are required: + +| Field | Description | +| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `id` **\*** | Unique agent identifier. Lowercase letters, digits, and hyphens; must start with a letter (pattern: `^[a-z][a-z0-9-]*$`). Also the folder name in the registry repo. | +| `name` **\*** | Human-readable display name. | +| `version` **\*** | Semantic version of the agent release (e.g. `1.0.0`). | +| `description` **\*** | Brief description of the agent's functionality and purpose. | +| `distribution` **\*** | Object describing how to obtain and run the agent. Supports three distribution types: `binary` (platform-specific archives), `npx` (Node packages), and `uvx` (Python packages). At least one distribution type must be provided. See [Distribution](#distribution) for details. | +| `repository` | Source code repository URL. | +| `authors` | Array of author/organization names. | +| `license` | SPDX license identifier or `"proprietary"`. | +| `icon` | Path to icon file (relative path or absolute URL). Must be SVG format, 16×16, monochrome using `currentColor` (enables light/dark theme adaptation). See [Icon requirements](#icon-requirements). | + +### Distribution + +The `distribution` object supports three mutually independent strategies. An agent may provide one or more: + +#### `binary` + +Platform-specific archive downloads. Keyed by `-` targets: + +| Target | OS | Architecture | +| ----------------- | ------- | ------------ | +| `darwin-aarch64` | macOS | ARM64 | +| `darwin-x86_64` | macOS | x86-64 | +| `linux-aarch64` | Linux | ARM64 | +| `linux-x86_64` | Linux | x86-64 | +| `windows-aarch64` | Windows | ARM64 | +| `windows-x86_64` | Windows | x86-64 | + +When using `binary` distribution, builds **must be provided for all three operating systems** (darwin, linux, windows). CI will reject entries that only cover a subset. + +Each target is an object with: + +| Field | Required | Description | +| --------- | -------- | ----------------------------------- | +| `archive` | Yes | URL to download archive | +| `cmd` | Yes | Command to execute after extraction | +| `args` | No | Array of command-line arguments | +| `env` | No | Object of environment variables | + +#### `npx` / `uvx` + +Package-manager-based distribution (Node via `npx`, Python via `uvx`). Each is an object with: + +| Field | Required | Description | +| --------- | -------- | ----------------------------------------- | +| `package` | Yes | Package name (with optional version spec) | +| `args` | No | Array of command-line arguments | +| `env` | No | Object of environment variables | + +### Icon requirements + +Icons must meet the following requirements to pass CI validation: + +- **SVG format** — only `.svg` files are accepted. +- **16×16 dimensions** — via `width`/`height` attributes or `viewBox`. +- **Monochrome using `currentColor`** — all `fill` and `stroke` values must use `currentColor` or `none`. Hardcoded colors (e.g. `fill="#FF5500"`, `fill="red"`) are rejected. + +Using `currentColor` lets icons adapt automatically to the client's light or dark theme. + +### Example: binary distribution ```jsonc { "id": "someagent", "name": "SomeAgent", "version": "1.0.0", - "schema_version": "1", "description": "Agent for code editing", - "homepage": "https://github.com/example/someagent", "repository": "https://github.com/example/someagent", "authors": ["Example Team"], "license": "MIT", - "capabilities": ["terminal", "fs/read", "fs/write"], - "auth": [ - { - "type": "api_key", - }, - ], + "icon": "icon.svg", "distribution": { - "darwin-aarch64": { - "archive": "https://github.com/example/someagent/releases/latest/download/someagent-darwin-arm64.zip", - "cmd": "./someagent", - "args": ["acp"], - }, - "darwin-x86_64": { - "archive": "https://github.com/example/someagent/releases/latest/download/someagent-darwin-x64.zip", - "cmd": "./someagent", - "args": ["acp"], - }, - "linux-aarch64": { - "archive": "https://github.com/example/someagent/releases/latest/download/someagent-linux-arm64.zip", - "cmd": "./someagent", - "args": ["acp"], - }, - "linux-x86_64": { - "archive": "https://github.com/example/someagent/releases/latest/download/someagent-linux-x64.zip", - "cmd": "./someagent", - "args": ["acp"], - }, - "windows-x86_64": { - "archive": "https://github.com/example/someagent/releases/latest/download/someagent-windows-x64.zip", - "cmd": "./someagent.exe", - "args": ["acp"], - "env": { - "SOMEAGENT_MODE_KEY": "", + "binary": { + "darwin-aarch64": { + "archive": "https://github.com/example/someagent/releases/latest/download/someagent-darwin-arm64.zip", + "cmd": "./someagent", + "args": ["acp"], + }, + "darwin-x86_64": { + "archive": "https://github.com/example/someagent/releases/latest/download/someagent-darwin-x64.zip", + "cmd": "./someagent", + "args": ["acp"], + }, + "linux-aarch64": { + "archive": "https://github.com/example/someagent/releases/latest/download/someagent-linux-arm64.zip", + "cmd": "./someagent", + "args": ["acp"], + }, + "linux-x86_64": { + "archive": "https://github.com/example/someagent/releases/latest/download/someagent-linux-x64.zip", + "cmd": "./someagent", + "args": ["acp"], + }, + "windows-x86_64": { + "archive": "https://github.com/example/someagent/releases/latest/download/someagent-windows-x64.zip", + "cmd": "./someagent.exe", + "args": ["acp"], + "env": { + "SOMEAGENT_MODE_KEY": "", + }, }, }, }, } ``` +### Example: package distribution + +```jsonc +{ + "id": "pyagent", + "name": "PyAgent", + "version": "2.1.0", + "description": "A Python-based ACP agent", + "repository": "https://github.com/example/pyagent", + "license": "Apache-2.0", + "distribution": { + "uvx": { + "package": "pyagent@latest", + "args": ["--mode", "acp"], + }, + }, +} +``` + +## Registry schema + +The aggregated `registry.json` file conforms to the registry schema and contains: + +| Field | Description | +| ------------ | --------------------------------------------------------------------------------------------------------- | +| `version` | Registry schema version (semver, e.g. `1.0.0`). | +| `agents` | Array of agent entries (each following the agent manifest schema above, sourced from `agent.json` files). | +| `extensions` | Array of extension entries (same schema as agents, sourced from `extension.json` files). | + +## Authentication requirements + +To be listed in the registry, an agent **must support at least one** of the following authentication methods: + +- **Agent Auth** — the agent handles the OAuth flow independently (opens the user's browser, runs a local callback server, exchanges the authorization code for tokens). +- **Terminal Auth** — the agent provides an interactive terminal-based setup experience (launched with additional args/env specified in the auth method). + +CI verifies this by checking that the agent returns an `authMethods` array in its `initialize` response, with at least one method. See the [ACP auth methods RFD](./auth-methods) for the full specification. + ## What we propose to do about it 1. **Manifest spec** (above) becomes normative; we publish the JSON Schema and validator script so maintainers can lint locally. 2. **Registry repository** `github.com/agentclientprotocol/registry`: - - Structure: `/agent.json`, optional `icon.svg` (or `icon-light.svg` and `icon-dark.svg` for theme-specific variants), optional `README.md`. - - Icons should be SVG format for scalability. If providing theme-specific icons, both light and dark variants must be included. - - CI: validate manifests, enforce slug uniqueness, check asset sizes, generate aggregate artifacts. + - Structure: `/agent.json` (or `extension.json`), optional `icon.svg`, optional `README.md`. + - CI validates manifests on every PR: schema compliance, slug uniqueness, icon format (16×16 SVG, monochrome `currentColor`), URL accessibility for all distribution URLs, authentication support via ACP handshake, and binary OS coverage. + - Push to `main` triggers a build that aggregates all entries into `registry.json` and publishes versioned + `latest` GitHub releases. 3. **Aggregated outputs**: - - `registry.json`: deterministic list of all agents with JSONC stripped. + - `registry.json`: deterministic list of all agents and extensions with icons copied to `dist/.svg`. 4. **Distribution & search**: - - Clients fetch `registry.json` from a pinned release or `https://agentclientprotocol.com/registry.json` or `https://registry.agentclientprotocol.com`. - - Static site offers filters for capability, protocol version, deployment, auth model, and tags. + - Clients fetch `registry.json` from `https://cdn.agentclientprotocol.com/registry/v1/latest/registry.json`. + - Static site offers filters for deployment model, license, and distribution type. ## Shiny future - Agent maintainers make PRs to update their manifests; CI keeps data clean. +- Automated version updates run hourly, checking npm, PyPI, and GitHub releases for new versions of registered agents and opening PRs automatically. - Editors/clients can bootstrap ACP support by fetching one JSON file and filtering locally. - The ACP website displays the same data for humans, ensuring consistency. -- Protocol-version mismatches are visible immediately; clients can warn or hide incompatible agents. +- Package-based distribution (`npx`, `uvx`) lowers the barrier for agents that don't need platform-specific binaries. ## Implementation details and plan **Phase 1 – Spec & repo bootstrap** -- Think about the auth options. - Finalize JSON Schema and documentation. -- Ask agent developers to contribute their thoughts on the spec. -- Create registry repo with CI (GitHub Actions) that runs validation on PRs. -- Seed with a few reference agents to prove the workflow. +- Create registry repo with CI (GitHub Actions) that validates on PRs and publishes on merge. +- Seed with reference agents. +- Implement automated version update workflow (hourly cron via GitHub Actions). +- Enforce authentication requirements via CI handshake verification. ## Revision history - 2025-11-28: Initial draft. - 2025-12-16: Minors. +- 2026-02-04: Updated to match latest schema — removed `schema_version`, `homepage`, `capabilities`, and `auth` fields; added `icon` field; restructured `distribution` into `binary`, `npx`, and `uvx` types; added `extensions` to registry schema. From 6a5573b6b86943b44a30923e55936c87046b9a4e Mon Sep 17 00:00:00 2001 From: Ben Brandt Date: Wed, 4 Feb 2026 14:58:55 +0100 Subject: [PATCH 2/2] Remove mention of extensions for now --- docs/rfds/acp-agent-registry.mdx | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/docs/rfds/acp-agent-registry.mdx b/docs/rfds/acp-agent-registry.mdx index 5a10b752..1b7d93c7 100644 --- a/docs/rfds/acp-agent-registry.mdx +++ b/docs/rfds/acp-agent-registry.mdx @@ -21,7 +21,7 @@ Every editor builds bespoke manifests or scrapes GitHub, leading to duplication ## Agent manifest format (core proposal) -Each agent or extension advertises itself via a manifest stored under `/` in the registry repo. Agents use `agent.json`; extensions use `extension.json`. A directory must contain one or the other, but not both. Both file types share the same schema. +Each agent advertises itself via a manifest stored as `/agent.json` in the registry repo. Fields marked with **\*** are required: @@ -155,11 +155,10 @@ Using `currentColor` lets icons adapt automatically to the client's light or dar The aggregated `registry.json` file conforms to the registry schema and contains: -| Field | Description | -| ------------ | --------------------------------------------------------------------------------------------------------- | -| `version` | Registry schema version (semver, e.g. `1.0.0`). | -| `agents` | Array of agent entries (each following the agent manifest schema above, sourced from `agent.json` files). | -| `extensions` | Array of extension entries (same schema as agents, sourced from `extension.json` files). | +| Field | Description | +| --------- | --------------------------------------------------------------------------------------------------------- | +| `version` | Registry schema version (semver, e.g. `1.0.0`). | +| `agents` | Array of agent entries (each following the agent manifest schema above, sourced from `agent.json` files). | ## Authentication requirements @@ -174,11 +173,11 @@ CI verifies this by checking that the agent returns an `authMethods` array in it 1. **Manifest spec** (above) becomes normative; we publish the JSON Schema and validator script so maintainers can lint locally. 2. **Registry repository** `github.com/agentclientprotocol/registry`: - - Structure: `/agent.json` (or `extension.json`), optional `icon.svg`, optional `README.md`. + - Structure: `/agent.json`, optional `icon.svg`, optional `README.md`. - CI validates manifests on every PR: schema compliance, slug uniqueness, icon format (16×16 SVG, monochrome `currentColor`), URL accessibility for all distribution URLs, authentication support via ACP handshake, and binary OS coverage. - Push to `main` triggers a build that aggregates all entries into `registry.json` and publishes versioned + `latest` GitHub releases. 3. **Aggregated outputs**: - - `registry.json`: deterministic list of all agents and extensions with icons copied to `dist/.svg`. + - `registry.json`: deterministic list of all agents with icons copied to `dist/.svg`. 4. **Distribution & search**: - Clients fetch `registry.json` from `https://cdn.agentclientprotocol.com/registry/v1/latest/registry.json`. - Static site offers filters for deployment model, license, and distribution type. @@ -205,4 +204,4 @@ CI verifies this by checking that the agent returns an `authMethods` array in it - 2025-11-28: Initial draft. - 2025-12-16: Minors. -- 2026-02-04: Updated to match latest schema — removed `schema_version`, `homepage`, `capabilities`, and `auth` fields; added `icon` field; restructured `distribution` into `binary`, `npx`, and `uvx` types; added `extensions` to registry schema. +- 2026-02-04: Updated to match latest schema — removed `schema_version`, `homepage`, `capabilities`, and `auth` fields; added `icon` field; restructured `distribution` into `binary`, `npx`, and `uvx` types.