Camada L1 · Adapters

Por baixo do capô

O pacote @alembic/adapters tem cerca de 30 arquivos .ts em src/ (incluindo os testes). Ele depende quase exclusivamente de @alembic/contracts, que é quem define a cintura: modelRunInputSchema, o modelRunResultSchema (uma união discriminada) e a interface ModelAdapter, todos em contracts/src/model.ts. O @alembic/adapters é quem a implementa.

O comentário de cabeçalho de model.ts é literal: "The narrow waist of Alembic. Every model invocation in the system flows through ModelAdapter.run." É a única camada que todo run de modelo (CLI, Factory, Council, Swarm, ETL) toca — por isso é também a única em que vale a pena concentrar tanta disciplina de confiabilidade.

O schema de entrada (resumido)

// contracts/src/model.ts
export const modelRunInputSchema = z.object({
  requestId:      z.string().min(1),
  modelId:        z.string().min(1),
  systemPrompt:   z.string(),
  userPrompt:     z.string(),
  maxOutputTokens: z.number().int().positive().optional(),
  temperature:    z.number().min(0).max(2).optional(),
  timeoutMs:      z.number().int().positive().optional(),
  roleId:         z.string().min(1).optional(),
  metadata:       z.record(z.string(), z.unknown()).optional(),
});
// signal?: AbortSignal — carregado FORA do schema (host object, não-validável)

A saída é uma união discriminada

export const modelRunResultSchema = z.discriminatedUnion('ok', [
  modelRunSuccessSchema,  // { ok:true,  text, usage?, costUsd?, durationMs, … }
  modelRunFailureSchema,  // { ok:false, error:{ code, message, retryable }, … }
]);

O comentário na própria interface ModelAdapter deixa o invariante explícito: "INVARIANT: ModelAdapter.run NEVER throws. Any error … MUST be returned as a ModelRunFailure … Callers therefore never need a try/catch around run; they branch on result.ok."

O contrato vivo (comentário do spine, adapter-core.ts)

/** The reusable spine that turns a "single attempt" into a
 *  compliant ModelAdapter `run`. It enforces, in order:
 *   1. boundary validation of ModelRunInput via Zod;
 *   2. the never-throws invariant (any escaped throw → failureFromThrown);
 *   3. an optional CircuitBreaker gate with correct success/failure feedback;
 *   4. withRetry backoff driven by each result's `retryable` flag.
 *  Adapters implement only the inner attempt(input) => Promise<Result>. */

guardedAttempt — onde o throw é domado

const guardedAttempt = async (...) => {
  if (breaker && !breaker.canExecute())          // (2) disjuntor aberto
    return { retry: true, value: breakerRejection(...), reason: 'circuit_open' };
  let result;
  try { result = await attempt(input); }            // (3) a tentativa do provider
  catch (cause) { result = failureFromThrown(..., cause); } // throw → Result
  if (result.ok) { breaker?.recordSuccess(); return { retry:false, value:result }; }
  breaker?.recordFailure();                          // (5) feedback
  return result.error.retryable
    ? { retry:true,  value:result, reason:result.error.code }  // (4) deixa o withRetry decidir
    : { retry:false, value:result };
};

E a entrada pública, runWithGuards, começa exatamente pela validação: const validation = validate(adapterId, input); if (!validation.ok) return validation.result; — invalidou? Devolve Result de falha CLIENT_ERROR sem nunca tocar o provider.

registry.ts — sempre o gateway, o resto condicional

export const createAdapterRegistry = (options = {}) => {
  const registry = new Map();
  registry.set(cliproxy.id, cliproxy);              // SEMPRE
  if (options.localOpenai?.baseUrl) registry.set(local.id, local);  // condicional
  if (options.piDev)      registry.set(piDev.id, piDev);
  if (options.codexOauth) registry.set(codex.id, codex);
  if (options.anthropic)  registry.set(anthropic.id, anthropic);
  if (options.localCli?.command) registry.set(cli.id, cli);
  if (options.offline) {
    registry.set(offline.id, offline);
    if (options.offline.asDefault)              // liga offline em TODOS os tiers
      for (const e of Object.values(MODEL_REGISTRY)) registry.set(e.adapterId, offline);
  }
  return registry;
};

router.ts — NO SILENT FALLBACK

export const pickAdapter = (tier, adapters, options = {}) => {
  const entry = pickCheapestForTier(tier, registry);
  if (!entry) return err({ kind: 'no_model_for_tier', tier });
  const adapter = adapters.get(entry.adapterId);
  if (!adapter) return err({ kind: 'adapter_not_registered', tier, modelId, adapterId });
  return ok({ entry, adapter });
};
// adapterForModel(modelId, …) ignora o tier e resolve um modelo específico (+ kind:'unknown_model')

O comentário do router é categórico: "NO SILENT FALLBACK. … A router that quietly substituted a different model would hide cost/capability regressions, so that is deliberately not done here."

Os oito (cada um exporta um create…Adapter)

// adapters/src/
cliproxyapi.ts      // gateway padrão (proxy fetch puro)
local-openai.ts     // servidor OpenAI-compatível local (MLX/Ollama)
offline.ts          // hermético $0, determinístico
anthropic.ts        // Anthropic de primeira classe
codex-oauth.ts      // Codex via OAuth
codex-exec.ts       // Codex via subprocess (CLI)
pi-dev.ts           // pi.dev
local-cli.ts        // CLI local genérico (presets em cli-presets.ts)

Há ainda openai-compatible.ts como base compartilhada para os providers que falam o dialeto OpenAI. Todos terminam construindo seu run com runWithGuards, então nenhum reimplementa "nunca lançar" ou retry.