DOCUMENTATION · v0.12.2

Agent harness support (evidence-based)

Status: living evidence register, not a compatibility guarantee. Last reviewed: 2026-11-20 (local, EST; 2026-11-21 03:32 UTC). Source: the dated notes already recorded in Agents and MCP, the transport contract in MCP command, the lifecycle rules in Session and connection lifecycle, plus a live verification executed from the terminal of this OpenCode harness (see "Live verification in this environment" below). No CI run, desktop chat-app session or interactive harness MCP session was executed; the live checks are terminal-run repository commands and tests, one of which drives a headless Chromium page.

Scope and honesty rules#

A static GitHub Pages page cannot install, start or configure a local process by itself. AI Auth has no trusted local installer component that performs an install and confirms it, so automatic local install does not exist and is not promised. Every supported path below still requires a real local action by the person and an explicit verification step.

This register reports two kinds of evidence: dated notes in docs/agents.md, and the live terminal checks recorded below. "Verified" for a dated note means the note describes that specific outcome; it does not mean current behavior, a completed CI run, or a reproducible session on a current client version. "Verified live" means a command was executed in this environment on the recorded date with the recorded output; it does not mean an interactive session of that client or a call that reached a peer. Where the underlying note omits the OS or client version, this matrix records NO REGISTRADO instead of guessing.

No version number is introduced by this register. Product and package version labels come from each package's package.json, with the root package.json as the single release source; version strings in nontechnical UI are generated from that source or omitted. See P2-16 below.

Support matrix#

Cliente / harnessVarianteOSVersión clienteFechaTransporteResultadoEvidencia
Claude Codedesktop / CLINO REGISTRADONO REGISTRADO2026-11-15MCP stdio (default) → WebRTC data channelVERIFICADO (parcial): una llamada de herramienta llegó a un pardocs/agents.md, "Harness notes": _"a tool call reached a peer over WebRTC"_.
Codexdesktop / CLINO REGISTRADONO REGISTRADO2026-11-15MCP stdio (default)NO VERIFICADO: el servidor registró y listó herramientas; ninguna llamada completódocs/agents.md, "Harness notes" (2026-11-15).
OpenCodedesktop / CLINO REGISTRADONO REGISTRADO2026-11-15MCP stdio (default)NO VERIFICADO (sesión interactiva): el servidor registró y listó herramientas; ninguna llamada completó. La comprobación automatizada de 2026-11-20 completó ai_auth_status, pero no fue una sesión interactiva del harness.docs/agents.md, "Harness notes" (2026-11-15); sección "Live verification in this environment".
OpenCodeeste entorno: comprobación automatizada por terminalmacOS (darwin); node v22.23.4OpenCode (harness donde se ejecutó); cliente = SDK MCP del repo, no UI de chat2026-11-20 (EST) / 2026-11-21 UTCMCP stdio (default) y --http 0VERIFICADO EN VIVO (automatizado), PARCIAL — tools/list y tool call completado: ai_auth_status devolvió connection=idle, capabilities=["presence.read"], room=null; sin par WebRTC ni identidad esperada verificada.Sección "Live verification in this environment": npm test --prefix packages/mcp 97/97; dos pruebas focalizadas 1/1 cada una.
ChatGPTdesktop appNO REGISTRADONO REGISTRADO2026-11-16MCP HTTP (--http, endpoints en 127.0.0.1)PARCIAL: tres agentes compartieron sala; un cambio de endpoint requirió re-añadir manualmente en el clientedocs/agents.md, "Harness notes" (2026-11-16).
ChatGPTweb (browser)N/A (web)NO REGISTRADO—Sin transporte local evidenciadoNO VERIFICADO / SIN SOPORTE DEMOSTRADOSin evidencia en el repositorio. Debe probarse por separado de la app de escritorio.
Otros clientescualquieraNO REGISTRADONO REGISTRADO—Según el cliente; no evidenciadoNO VERIFICADOSin nota fechada en el repositorio. No se afirma compatibilidad.

Cómo leer el resultado#

  • VERIFICADO (parcial): la nota fechada describe el desenlace indicado, pero no registra OS, versión del cliente ni una sesión reproducible hoy. No equivale a compatibilidad certificada.
  • PARCIAL: se observó parte del camino (por ejemplo, registro de herramientas o sala compartida) sin la prueba completa de llamada, prueba firmada o canal autenticado para la identidad esperada.
  • NO VERIFICADO: no hay nota fechada en el repositorio que respalde el desenlace. Registrar herramientas no es prueba de una llamada completada.
  • SIN SOPORTE DEMOSTRADO: no existe evidencia de un adaptador local para esa variante. Un cliente puramente de navegador no puede instalar un proceso local.
  • VERIFICADO EN VIVO (automatizado): un comando del repositorio se ejecutó en este entorno en la fecha registrada y produjo la salida registrada. No equivale a una sesión interactiva del cliente ni a una llamada que haya llegado a un par.

Desktop y web se mantienen como filas independientes: un resultado en ChatGPT desktop no dice nada sobre ChatGPT web. Una comprobación automatizada por terminal tampoco dice nada sobre una sesión interactiva de OpenCode, Claude Code, Codex o ChatGPT.

Live verification in this environment (2026-11-20/21)#

Executed from the terminal of the OpenCode harness in which this register was updated. This is not a claim that OpenCode (or Claude Code, Codex or ChatGPT) was configured with ai-auth-mcp and driven as a chat client: no harness MCP config was edited and no tool was invoked through a chat UI. What ran was the repository's own commands and tests; some of them start a real MCP server and connect a real MCP client to it.

CampoValor observado
OS / plataformamacOS (darwin)
date (local)Fri Nov 20 22:32:42 EST 2026
date -uSat Nov 21 03:32:42 UTC 2026
node --versionv22.23.4
npm --version10.9.9
Harness donde corrióOpenCode (terminal de la sesión de trabajo); no se modificó su configuración MCP
Paquetes del reporoot @enzovezzaro/ai-auth-wallet 0.12.2; @enzovezzaro/ai-auth-mcp 0.3.9 (según package.json)
Comando exacto ejecutadoResultadoSalida real relevante
date && date -uPASSFri Nov 20 22:32:42 EST 2026 / Sat Nov 21 03:32:42 UTC 2026
node --version && npm --versionPASSv22.23.4 / 10.9.9
npm run test:mcp-consentPASS (0)MCP consent window E2E passed: the URL-carried request opened the wallet, approval was created, and the signed consent reached the loopback callback.
npm run test:connect-agentPASS (0)PASS connect-agent E2E: instructions copied, unexpected peer refused, real signed proof verified, live peer present and Connected shown with granted scopes only.
node packages/mcp/cli.js --helpPASS (0)Imprime USAGE con los comandos `serve\
npm test --prefix packages/mcpPASS (0)# tests 97 / # pass 97 / # fail 0
node --test --test-name-pattern="serve with an exact subset exposes only the approved tools over stdio MCP" packages/mcp/test/cli.test.mjsPASSok 1 - serve with an exact subset exposes only the approved tools over stdio MCP; # pass 1 / # fail 0
node --test --test-name-pattern="serve --http exposes the approved tools over Streamable HTTP at a secret path" packages/mcp/test/cli.test.mjsPASSok 1 - serve --http exposes the approved tools over Streamable HTTP at a secret path; # pass 1 / # fail 0

What these checks prove, and what they do not:

  • They prove that in this environment Node 22 boots the ai-auth-mcp CLI, creates/reuses a keystore, serves MCP over stdio and over Streamable HTTP on 127.0.0.1, lists the approved tools and completes a tool call. In the focused stdio test the client asserts ai_auth_status → connection=idle, capabilities=["presence.read"], room=null (assertions in packages/mcp/test/cli.test.mjs).
  • That completed call is a local status read with no peer. It is not the same thing as the 2026-11-15 Claude Code note ("a tool call reached a peer over WebRTC"), and it does not prove a live data channel, expected-wallet/instance binding or a fresh authorization.
  • The headless Chromium run in test:mcp-consent is a browser test of the wallet approval callback, not a ChatGPT/desktop chat-app session and not a desktop app window brought forward for approval.
  • Approval in the automated MCP sessions is explicit --approve in a non-TTY; no wallet UI approval was involved in those sessions.
  • Nothing here verifies Claude Code, Codex, ChatGPT desktop or ChatGPT web interactively, and nothing here is a CI result. The historical notes keep their own dates; this live check does not backdate or upgrade them.
  • npm run verify:docs PASS (Verified 38 styled docs pages and their raw Markdown). npm run format:check FAILS only on files outside this change that other workers were editing concurrently (at the final run: packages/agent/pairing.js, packages/agent/test/pairing.test.mjs, tests/approval-copy-lifetime.test.mjs, tests/connect-agent-pairing.test.mjs, tests/session-lifetime.test.mjs, docs/site-integration.md, apps/p2p/app.js). The three documents edited for P1-13 pass npx prettier --check docs/AGENT_HARNESS_SUPPORT.md docs/agents.md CHANGELOG.md.

Adapter capability registry#

This is a contract for what may be claimed, not a statement that every path is implemented end to end.

CapacidadEstado en el repositorioQué existe realmenteQué NO se debe prometer
Instalación local automáticaNO IMPLEMENTADO / NO PROMETIDONingún componente local de confianza ejecuta y confirma una instalación. La persona ejecuta el CLI ai-auth-mcp."Instalación en un clic", que el navegador instale un proceso local.
Skill portableMANUAL.agents/skills/ai-auth-connect/SKILL.md: instrucciones que la persona instala en su cliente.Que instalar la skill conceda acceso o reemplace la aprobación del propietario.
MCP stdioSOPORTADO (default)Es el transporte por defecto del CLI; sustenta la nota de Claude Code del 2026-11-15.Que listar herramientas signifique que una llamada se completó.
MCP HTTPPARCIAL--http PORT en 127.0.0.1 con URL secreta; sustenta la nota de ChatGPT desktop del 2026-11-16.Exponer el endpoint públicamente o copiar el secreto en un enlace compartido.
Configuración manualSIEMPRE DISPONIBLEComandos y banderas documentados en Agents and MCP y MCP command.Prerrequisitos ocultos (por ejemplo, un init no documentado).
Cliente solo navegador / webSIN SOPORTE DE INSTALACIÓN LOCALLa verificación de prueba sigue siendo obligatoria; la página estática no puede instalar ni iniciar el agente.Mostrar "Conectado" sin prueba firmada y par autenticado para la identidad esperada.

The UI should choose a known path from this registry, ask for local permission, and otherwise give short copyable steps plus an explicit proof action. Verification is mandatory whatever the adapter.

What a result does and does not prove#

  • The dated notes record self-reported runtime and environment metadata. They do not prove a particular OS, client version, model, vendor or physical machine.
  • A note about a WebRTC tool call proves a peer received traffic on that session; it does not by itself prove expected-wallet/instance binding, nonce freshness or a current authorization. Those checks are specified in Connect Agent E2E acceptance.
  • connected is true only while a real authenticated data channel is open for the expected identity and session; a saved key, a discovered tool catalog or a reachable MCP endpoint is not a connection (lifecycle).
  • There is no TURN server. A restrictive NAT can block the direct path; report that honestly instead of claiming universal connectivity.
  • Verify each live session with ai_auth_status. Do not treat this register as a substitute for that check.

Evidence required to upgrade a row#

To move a cell from NO VERIFICADO or PARCIAL to VERIFICADO, record: OS and client version, the observation date, the exact command and transport, a redacted ai_auth_status result showing connection state and effective granted scopes, and a sanitized screenshot or log. Test ChatGPT web independently from ChatGPT desktop. Do not call a listed MCP server proof of a completed tool call.

P2-16: version source of truth#

The canonical release source is the root package.json (0.12.2 for this repository). Package-specific tables in the README and site integration mirror each package's own package.json: @enzovezzaro/ai-auth-agent 0.2.0, @enzovezzaro/ai-auth-mcp 0.3.9 and @enzovezzaro/ai-auth-runtime 0.1.3. Any version rendered in a UI surface is generated from that source at build time or omitted from nontechnical UI; this document does not hardcode or invent a product version. Changes to UI version labels live with the UI owners and are resolved in the 0.12.1 changelog.

On this page