Escribir un adapter
Un adapter es una clase TypeScript que implementa la interfaz AgentRuntimeAdapter de @taia/runtime. Antes de empezar, conviene leer la visión general de la arquitectura.
Un adapter tiene tres responsabilidades:
- Hablar con el runtime (HTTP, WebSocket, subproceso…).
- Traducir los tipos del runtime a los tipos canónicos de TAIA (
RuntimeAgent,RuntimeSession,RuntimeMessage,RuntimeCronJob,RuntimeHealth). - Declarar sus capacidades.
Nada más. La lógica de tareas, workspaces, costos o alertas vive en @taia/core.
1. Estructura
Sección titulada «1. Estructura»packages/runtime/src/adapters/<runtime>/├── index.ts # exports y registro del factory├── adapter.ts # class MyAdapter implements AgentRuntimeAdapter├── client.ts # transporte├── mappers.ts # forma nativa → forma canónica└── types.ts # tipos del protocolo (internos)Los adapters de CLI comparten GenericCliProtocol (adapters/cli/); para un CLI nuevo, conviene partir de adapters/aider/.
2. La superficie mínima
Sección titulada «2. La superficie mínima»import { CapabilitySet, RuntimeCapability, type AgentRuntimeAdapter, type RuntimeAgent, type RuntimeConnectionState, type RuntimeConnectionTest, type RuntimeHealth,} from '@taia/runtime'
export class MyAdapter implements AgentRuntimeAdapter { readonly id = 'my-runtime' readonly capabilities = new CapabilitySet([ RuntimeCapability.Sessions, RuntimeCapability.Health, // solo lo que de verdad implementás ])
async isAvailable(): Promise<boolean> { /* … */ } getConnectionState(): RuntimeConnectionState { /* … */ } onConnectionStateChange(handler: (state: RuntimeConnectionState) => void): () => void { /* … */ } async listAgents(): Promise<RuntimeAgent[]> { /* … */ } async getHealth(): Promise<RuntimeHealth> { /* … */ }
// Opcional, pero recomendado: lo usa "Probar conexión". Nunca lanza: // devuelve { ok: false, reason, error }. Sin él, TAIA usa getHealth(). async testConnection(): Promise<RuntimeConnectionTest> { /* … */ }}Las sesiones que devuelve listSessions tienen que traer agentId (el agente de TAIA dueño de la sesión): TAIA agrupa por ese campo.
3. Métodos por capacidad
Sección titulada «3. Métodos por capacidad»Si declarás una capacidad, tenés que implementar sus métodos. Si no la declarás, no los implementes.
| Capacidad | Métodos |
|---|---|
Sessions |
spawnSession, listSessions (awaitSessionComplete y sendToSession, opcionales) |
Transcripts |
getSessionHistory |
Cron |
listCrons, cronAction |
LiveEvents |
on(event, handler) |
Approvals |
flujo de aprobaciones del runtime (ver el adapter de Anthropic) |
Messaging |
sendChannelMessage({ channel, target, text }) |
ContextSync |
projectAgentContext(bundle), syncAgentContext(request), para runtimes que guardan el contexto como archivos (ADR-005) |
RuntimeSettingsRead |
getRuntimeSettings() |
AgentProvisioning |
provisionAgent, updateAgentSettings, deprovisionAgent (setRuntimeDefaults, opcional). provisionAgent no toca un agente que ya existe y nunca lanza: los errores vuelven como { status: 'failed', manualHint }. En updateAgentSettings, null vuelve un campo al default del runtime |
NativeConfig |
getNativeConfig, patchNativeConfig |
4. Tipos canónicos
Sección titulada «4. Tipos canónicos»Los métodos públicos nunca devuelven la forma nativa del runtime: la traducción va en mappers.ts. Los nombres canónicos no se negocian: sessionKey (no childSessionKey), runId, agentId.
Si el runtime tiene convenciones de filesystem (una raíz de workspaces, por ejemplo), descríbelas con getProviderDefaults(). El core nunca arma rutas del runtime: cuando provisiona un agente sin workspace, el runtime elige uno.
5. Contexto del agente
Sección titulada «5. Contexto del agente»Si declarás Sessions, tenés que traducir el AgentContextBundle (capas agent, project, user, task, memory) a lo que el runtime entiende:
context-renderer.tsimplementaAgentContextRenderer. RecibeRenderOptions.trigger(heartbeat,taskoprompt) y arma con eso el primer mensaje. Los bloques de markdown compartidos están encontext-markdown.ts.- Si el runtime guarda el contexto en archivos, declará
ContextSync.projectAgentContextrenderiza los archivos con sus hashes ysyncAgentContextlos escribe, sin pisar un archivo que el agente cambió salvo que se fuerce. - Si el runtime tiene herramientas propias, mapeá las capacidades del agente (
read_tasks, etc.) a esas herramientas, como haceadapters/anthropic/capabilities.ts.
Ejemplos: OpenClaw (archivos), Anthropic (bloques de system prompt) y los CLI (un solo prompt). Ver Modelo de contexto.
6. Registrarlo en TAIA
Sección titulada «6. Registrarlo en TAIA»-
Factory, en
index.ts:import { registerRuntimeFactory, type RuntimeProviderConfig } from '../../registry'import { MyAdapter } from './adapter'registerRuntimeFactory('my-runtime', (config: RuntimeProviderConfig) => new MyAdapter(/* … */)) -
Export del subpath en
packages/runtime/package.json("./adapters/my-runtime": "./src/adapters/my-runtime/index.ts"). -
Import del módulo en
packages/core/src/runtime.ts, junto a los demás adapters (el import registra el factory). -
Provider en
RUNTIME_PROVIDERS(packages/runtime/src/providers.ts): qué campos pide, cuál es obligatorio y los defaults. Si es un CLI, declarácommandscon los binarios permitidos. -
Labels de la UI en
apps/web/messages/es.jsonypt.json(runtime.providers.<id>).
7. Tests de contrato
Sección titulada «7. Tests de contrato»import { runAdapterContract } from './adapter-contract'import { MyAdapter } from '@taia/runtime/adapters/my-runtime'
runAdapterContract({ name: 'MyAdapter', makeAdapter: () => new MyAdapter(/* fixture */) })Verifica los invariantes de todo adapter: nombres canónicos, coherencia entre capacidades y métodos, getHealth que no lanza. El adapter mínimo que lo pasa es packages/runtime/__tests__/contract/mock-adapter.ts; conviene leerlo antes de escribir el propio.
Errores
Sección titulada «Errores»| Situación | Qué hacer |
|---|---|
| Falla de red en un método de lectura | Lanzar: el core decide si cae a los datos de la base |
getHealth no llega al runtime |
Devolver { ok: false }, nunca lanzar |
| Falla al crear o enviar una sesión | Lanzar con un mensaje que nombre la operación |
Timeout en awaitSessionComplete |
Lanzar Error('awaitSessionComplete: timeout') |
Qué no asumir
Sección titulada «Qué no asumir»- Que hay una URL. El runtime puede ser un subproceso.
RuntimeProviderConfigacepta campos propios; documentalos. - Que hay cron. Si no lo tiene, no declares
Cron. - Que el adapter escribe en la base. Los adapters nunca tocan las tablas de TAIA: devuelven datos y el core decide qué guardar.
- Que hay lógica de negocio en el adapter. Si te encontrás programando tareas o columnas ahí, frená y repensalo.
Checklist del PR
Sección titulada «Checklist del PR»- El adapter vive en
packages/runtime/src/adapters/<runtime>/y no importa@taia/core,@taia/domainni@taia/web. - Los métodos públicos devuelven tipos canónicos.
- Las capacidades declaradas coinciden con los métodos implementados.
-
getHealthnunca lanza. - Factory, export, import en core,
RUNTIME_PROVIDERSy labels (paso 6). -
__tests__/contract/<runtime>.contract.test.tspasa. - Hay una página en
apps/docs/src/content/docs/runtimes/y una columna en la matriz de capacidades.