@adjudicate/adapter-core 0.1.0

package/src/persistence-redis.ts

@@ -0,0 +1,158 @@
+/**
+ * Redis-backed `ConfirmationStore` — restart-durable pending confirmations.
+ *
+ * The in-memory `createInMemoryConfirmationStore` (see `./persistence.ts`)
+ * is suitable for tests and the quickstart, but a process restart loses
+ * every pending confirmation. Adopters running the adapter loop in a
+ * production process need restart durability so user-held tokens
+ * (REQUEST_CONFIRMATION flows that block for hours) survive deploys.
+ *
+ * This module ships a Redis-backed implementation that uses the same
+ * minimal `RedisLedgerClient` surface (`get`/`set`) as the rest of the
+ * audit + ledger stack. The store is generic over `H` (the conversation-
+ * history shape) — the caller supplies a serializer for their provider's
+ * history type.
+ *
+ * # Wire format
+ *
+ * Each pending confirmation is JSON-encoded under the key
+ * `${prefix}:confirm:${token}`. The TTL on the key matches the
+ * adopter-supplied `ttlSeconds` from `put()`.
+ *
+ * # Get-and-delete (take semantics)
+ *
+ * `take()` is single-use: a successful take deletes the key. Two
+ * concurrent `take(token)` calls race — Redis `GET` + `DEL` is not atomic
+ * without scripting, so at most one caller receives the pending
+ * confirmation. Production adopters needing strict at-most-once semantics
+ * across replicas should wire a Lua script; the JS implementation here
+ * accepts a tiny race window where two `take` calls might both return
+ * the same pending (the LATER one's adjudication then fails on
+ * `REPLAY_SUPPRESSED` via the kernel's ledger — fail-closed by design).
+ *
+ * # Replay safety
+ *
+ * Confirmation tokens are NOT inputs to the kernel's adjudication —
+ * they're externally-held opaque references. The kernel's
+ * `confirmationReceipt` (which IS adjudicated against) is reconstructed
+ * from the persisted envelope, not from the token. So storing them in
+ * Redis does not change replay determinism.
+ */
+
+import type { IntentEnvelope } from "@adjudicate/core";
+import type {
+  ConfirmationStore,
+  PendingConfirmation,
+} from "./persistence.js";
+
+/**
+ * Minimal Redis surface required by the Redis confirmation store. Same
+ * shape as `@adjudicate/audit`'s `RedisLedgerClient` so adopters can
+ * reuse the same connection.
+ */
+export interface ConfirmationRedisClient {
+  set(
+    key: string,
+    value: string,
+    options?: { NX?: boolean; EX?: number },
+  ): Promise<string | null>;
+  get(key: string): Promise<string | null>;
+  del(key: string): Promise<unknown>;
+}
+
+export interface CreateRedisConfirmationStoreOptions<H> {
+  readonly client: ConfirmationRedisClient;
+  /**
+   * Adopter-supplied key namespacer. Adjudicate convention: wrap the
+   * raw suffix into a tenant/env-namespaced key (e.g.,
+   * `${APP_ENV}:adjudicate:${suffix}`). Defaults to identity.
+   */
+  readonly keyFor?: (suffix: string) => string;
+  /**
+   * Serializer for the assistant history snapshot. Required because `H`
+   * is the provider's opaque history shape — Anthropic's MessageParam[]
+   * and OpenAI's ChatCompletionMessageParam[] are both JSON-serializable
+   * by default. Adopters who use richer types (Date, BigInt) should plug
+   * in a custom serializer.
+   *
+   * Default: `JSON.stringify` / `JSON.parse`.
+   */
+  readonly serializeHistory?: (h: H) => string;
+  readonly deserializeHistory?: (s: string) => H;
+}
+
+interface WireFormat {
+  readonly envelope: IntentEnvelope;
+  readonly sessionId: string;
+  readonly historyJson: string;
+  readonly toolUseId: string;
+  readonly prompt: string;
+}
+
+/**
+ * Redis-backed `ConfirmationStore<H>`. Wraps the minimal `set/get/del`
+ * surface. `put` writes with EX (TTL); `take` does GET then DEL.
+ *
+ * Adopters share the underlying Redis client across the ledger, the
+ * kill switch, and the confirmation store — one connection per role
+ * (read/write vs subscribe) is the typical production wiring.
+ */
+export function createRedisConfirmationStore<H = unknown>(
+  opts: CreateRedisConfirmationStoreOptions<H>,
+): ConfirmationStore<H> {
+  const keyFor = opts.keyFor ?? ((s: string) => s);
+  const serialize =
+    opts.serializeHistory ?? ((h: H) => JSON.stringify(h));
+  const deserialize =
+    opts.deserializeHistory ?? ((s: string) => JSON.parse(s) as H);
+
+  return {
+    async put(
+      token: string,
+      pending: PendingConfirmation<H>,
+      ttlSeconds: number,
+    ) {
+      const wire: WireFormat = {
+        envelope: pending.envelope,
+        sessionId: pending.sessionId,
+        historyJson: serialize(pending.assistantHistorySnapshot),
+        toolUseId: pending.toolUseId,
+        prompt: pending.prompt,
+      };
+      await opts.client.set(
+        keyFor(`confirm:${token}`),
+        JSON.stringify(wire),
+        { EX: ttlSeconds },
+      );
+    },
+
+    async take(token: string) {
+      const key = keyFor(`confirm:${token}`);
+      const raw = await opts.client.get(key);
+      if (raw === null) return null;
+      // Get-and-delete: a single use. Concurrent takes may race; the
+      // kernel's ledger backstops with REPLAY_SUPPRESSED on the second
+      // adjudication.
+      await opts.client.del(key);
+      let wire: WireFormat;
+      try {
+        wire = JSON.parse(raw) as WireFormat;
+      } catch {
+        return null;
+      }
+      let history: H;
+      try {
+        history = deserialize(wire.historyJson);
+      } catch {
+        return null;
+      }
+      return {
+        envelope: wire.envelope,
+        sessionId: wire.sessionId,
+        assistantHistorySnapshot: history,
+        toolUseId: wire.toolUseId,
+        prompt: wire.prompt,
+      };
+    },
+  };
+}

package/src/persistence.ts

@@ -0,0 +1,176 @@
+/**
+ * In-memory persistence shims for the adapter loop.
+ *
+ * Two stores live here:
+ * - **DeferRedis + ParkRedis** — implements the combined runtime persistence
+ *   surface so `parkDeferredIntent` (write) and `resumeDeferredIntent`
+ *   (read + idempotent claim) both work against a single backing object.
+ *   Production wires real Redis; the in-memory shim is for tests + the
+ *   quickstart.
+ *
+ * - **ConfirmationStore** — separate by design. DEFER persists by
+ *   `(session, intentHash)`; REQUEST_CONFIRMATION persists by a
+ *   user-held token (the user clicks "yes/no" at an arbitrary later time).
+ *   Conflating them muddles both shapes.
+ *
+ * The persistence layer is provider-neutral — the `assistantHistorySnapshot`
+ * on pending confirmations is typed as a generic `H` so adapters thread
+ * their SDK's conversation-history shape through unchanged.
+ */
+
+import type { IntentEnvelope } from "@adjudicate/core";
+
+// ── Defer / Park Redis surface ──────────────────────────────────────────────
+
+/**
+ * Read + claim surface used by `resumeDeferredIntent`. Mirrors the
+ * `DeferRedis` interface in `@adjudicate/runtime`.
+ */
+export interface DeferRedis {
+  get(key: string): Promise<string | null>;
+  set(
+    key: string,
+    value: string,
+    options: { NX: true; EX: number },
+  ): Promise<string | null>;
+  del(key: string): Promise<unknown>;
+  incr?(key: string): Promise<number>;
+  decr?(key: string): Promise<number>;
+  expire?(key: string, seconds: number): Promise<unknown>;
+}
+
+/**
+ * Write + counter surface used by `parkDeferredIntent`. Mirrors the
+ * `ParkRedis` interface in `@adjudicate/runtime`.
+ */
+export interface ParkRedis {
+  incr(key: string): Promise<number>;
+  decr(key: string): Promise<number>;
+  expire(key: string, seconds: number, mode?: "NX"): Promise<unknown>;
+  set(
+    key: string,
+    value: string,
+    options: { EX: number },
+  ): Promise<string | null>;
+  evalIncrCheck?(
+    counterKey: string,
+    ttlSeconds: number,
+    max: number,
+  ): Promise<number>;
+}
+
+interface Entry {
+  readonly value: string;
+  expiresAt: number;
+}
+
+/**
+ * Combined in-memory implementation of `DeferRedis` AND `ParkRedis`.
+ * Suitable for tests and the quickstart. NOT suitable for production —
+ * lacks persistence, fan-out, and cross-process coordination.
+ */
+export function createInMemoryDeferStore(): DeferRedis & ParkRedis {
+  const store = new Map<string, Entry>();
+  const counters = new Map<string, number>();
+
+  const isAlive = (entry: Entry | undefined): entry is Entry =>
+    entry !== undefined && entry.expiresAt > Date.now();
+
+  function setRaw(
+    key: string,
+    value: string,
+    options: { NX?: true; EX: number },
+  ): "OK" | null {
+    const existing = store.get(key);
+    if (options.NX && isAlive(existing)) return null;
+    store.set(key, {
+      value,
+      expiresAt: Date.now() + options.EX * 1000,
+    });
+    return "OK";
+  }
+
+  return {
+    async get(key) {
+      const entry = store.get(key);
+      if (!isAlive(entry)) {
+        if (entry !== undefined) store.delete(key);
+        return null;
+      }
+      return entry.value;
+    },
+    async set(
+      key: string,
+      value: string,
+      options: { NX?: true; EX: number },
+    ) {
+      return setRaw(key, value, options);
+    },
+    async del(key) {
+      const had = store.delete(key);
+      counters.delete(key);
+      return had ? 1 : 0;
+    },
+    async incr(key) {
+      const next = (counters.get(key) ?? 0) + 1;
+      counters.set(key, next);
+      return next;
+    },
+    async decr(key) {
+      const next = (counters.get(key) ?? 0) - 1;
+      counters.set(key, next);
+      return next;
+    },
+    async expire(_key: string, _seconds: number, _mode?: "NX") {
+      return 1;
+    },
+  };
+}
+
+// ── Confirmation store ──────────────────────────────────────────────────────
+
+export interface PendingConfirmation<H = unknown> {
+  readonly envelope: IntentEnvelope;
+  readonly sessionId: string;
+  readonly assistantHistorySnapshot: H;
+  readonly toolUseId: string;
+  readonly prompt: string;
+}
+
+/**
+ * Persistence for REQUEST_CONFIRMATION pauses. `take()` is get-and-delete:
+ * a confirmation token is single-use. A repeated take after the first
+ * resolution returns `null` (idempotent yes-then-yes).
+ */
+export interface ConfirmationStore<H = unknown> {
+  put(
+    token: string,
+    pending: PendingConfirmation<H>,
+    ttlSeconds: number,
+  ): Promise<void>;
+  take(token: string): Promise<PendingConfirmation<H> | null>;
+}
+
+interface ConfirmationEntry<H> {
+  readonly pending: PendingConfirmation<H>;
+  readonly expiresAt: number;
+}
+
+export function createInMemoryConfirmationStore<H = unknown>(): ConfirmationStore<H> {
+  const store = new Map<string, ConfirmationEntry<H>>();
+  return {
+    async put(token, pending, ttlSeconds) {
+      store.set(token, {
+        pending,
+        expiresAt: Date.now() + ttlSeconds * 1000,
+      });
+    },
+    async take(token) {
+      const entry = store.get(token);
+      if (entry === undefined) return null;
+      store.delete(token);
+      if (entry.expiresAt <= Date.now()) return null;
+      return entry.pending;
+    },
+  };
+}

package/src/trace.ts

@@ -0,0 +1,105 @@
+/**
+ * Adapter loop trace hooks — low-cardinality lifecycle events.
+ *
+ * The adapter loop's existing `AgentEvent` stream is detailed enough
+ * for replay and debugging but unfocused for observability — every
+ * tool_use, tool_result, intent_proposed, etc. is an event, which is
+ * the WRONG cardinality for production tracing.
+ *
+ * This module is the focused TRACE surface: a small set of phase
+ * transitions an operator dashboard wants to know about, with
+ * controlled-vocabulary attribute strings.
+ *
+ * # What goes through here
+ *
+ *   - `iteration_start`  — bumping the iteration counter
+ *   - `tool_use_seen`    — total count of LLM tool_use blocks per turn
+ *   - `decision_emitted` — kernel returned a Decision
+ *   - `paused`           — DEFER/REQUEST_CONFIRMATION/ESCALATE handled
+ *   - `completed`        — loop terminated cleanly
+ *
+ * Adopters wire `TraceSink` to their observability stack:
+ *
+ *   const traceSink: TraceSink = {
+ *     onTrace(evt) {
+ *       tracer.startSpan(evt.phase, { attributes: evt.attributes }).end();
+ *     }
+ *   };
+ *
+ * Pass to `createAdjudicatedAgent({ ..., traceSink })`. The loop fires
+ * one TraceEvent per documented phase per session. NO per-record
+ * fan-out. NO high-cardinality data (intent payloads, conversation
+ * history). Cardinality is bounded by `(pack-id × decision-kind × phase)`.
+ *
+ * # Replay safety
+ *
+ * Trace emission is fire-and-forget. The sink MUST NOT throw — the loop
+ * does not try/catch around it. If the sink misbehaves, adjudication
+ * still completes; only telemetry is lost.
+ */
+
+import type { Decision } from "@adjudicate/core";
+
+export type AdapterTracePhase =
+  | "iteration_start"
+  | "decision_emitted"
+  | "paused"
+  | "completed"
+  | "max_iterations_exceeded";
+
+export type AdapterPauseReason =
+  | "deferred"
+  | "awaiting_confirmation"
+  | "escalated";
+
+/**
+ * A single trace event from the adapter loop. The attributes are
+ * deliberately small + controlled-vocabulary; adopters MUST NOT add
+ * per-payload data here. (For replayable forensic detail use the
+ * AgentEvent stream, which is record-grained.)
+ */
+export interface AdapterTraceEvent {
+  readonly phase: AdapterTracePhase;
+  readonly sessionId: string;
+  /** 1-based iteration counter, capped by `maxIterations`. */
+  readonly iteration: number;
+  /** Set when the event corresponds to a Decision. */
+  readonly decisionKind?: Decision["kind"];
+  /** Set on `phase === "paused"`. */
+  readonly pauseReason?: AdapterPauseReason;
+}
+
+/** Adopter-supplied trace sink. MUST NOT throw. */
+export interface TraceSink {
+  onTrace(event: AdapterTraceEvent): void;
+}
+
+/**
+ * No-op trace sink. Default when none is supplied. Zero allocation,
+ * zero overhead.
+ */
+export const noopTraceSink: TraceSink = {
+  onTrace() {
+    /* no-op */
+  },
+};
+
+/**
+ * In-memory trace sink for tests. Captures every event in
+ * registration order.
+ */
+export function createInMemoryTraceSink(): TraceSink & {
+  readonly events: ReadonlyArray<AdapterTraceEvent>;
+  reset(): void;
+} {
+  const events: AdapterTraceEvent[] = [];
+  return {
+    events,
+    onTrace(event) {
+      events.push(event);
+    },
+    reset() {
+      events.length = 0;
+    },
+  };
+}

package/src/types.ts

@@ -0,0 +1,236 @@
+/**
+ * Provider-neutral types for the adapter loop.
+ *
+ * The shapes in this module describe what the loop needs to know, NOT
+ * what any specific LLM SDK ships. Provider adapters
+ * (`@adjudicate/anthropic`, `@adjudicate/openai`, …) translate between
+ * their SDK's wire types and these.
+ *
+ * History `H` is opaque: the loop never inspects it. The provider bridge
+ * appends user messages, assistant turns, and tool results in whatever
+ * shape the SDK consumes.
+ */
+
+import type {
+  AuditSink,
+  Decision,
+  IntentEnvelope,
+  Ledger,
+  PackV0,
+  Taint,
+} from "@adjudicate/core";
+import type { PromptRenderer, ToolSchema } from "@adjudicate/core/llm";
+import type { RuntimeContext } from "@adjudicate/core/kernel";
+import type {
+  ConfirmationStore,
+  DeferRedis,
+  ParkRedis,
+} from "./persistence.js";
+import type { TraceSink } from "./trace.js";
+
+// ── Provider-neutral wire shapes ──────────────────────────────────────────────
+
+/**
+ * Provider-neutral representation of a tool-use request emitted by the
+ * model. Anthropic adapters map `ToolUseBlock` → `ToolUseRequest`; OpenAI
+ * adapters map `function_call` / `tool_calls[].function` similarly.
+ */
+export interface ToolUseRequest {
+  readonly id: string;
+  readonly name: string;
+  readonly input: unknown;
+}
+
+/**
+ * Provider-neutral representation of a single assistant turn (text and
+ * any tool-use blocks). The bridge fans out the SDK-specific response.
+ */
+export interface AssistantTurn {
+  readonly textBlocks: ReadonlyArray<string>;
+  readonly toolUses: ReadonlyArray<ToolUseRequest>;
+}
+
+/**
+ * Provider-neutral tool-result payload returned to the model. The bridge
+ * encodes this into whatever shape the SDK consumes (Anthropic
+ * `tool_result` block; OpenAI `role: "tool"` message).
+ */
+export interface ToolResultBlock {
+  readonly toolUseId: string;
+  readonly content: string;
+  readonly isError?: boolean;
+}
+
+// ── Adopter-supplied executor (carried through to translateDecision) ────────
+
+/**
+ * Adopter-supplied side-effect runner. Called only after the kernel
+ * returns EXECUTE (or REWRITE — the executor receives the rewritten
+ * envelope, NOT the original).
+ *
+ * READ tools that the LLM proposes go through `invokeRead`; intent
+ * executions that the kernel authorized go through `invokeIntent`.
+ */
+export interface AdopterExecutor<K extends string, P, S> {
+  invokeRead(name: string, input: unknown, state: S): Promise<unknown>;
+  invokeIntent(envelope: IntentEnvelope<K, P>, state: S): Promise<unknown>;
+}
+
+export interface AgentLogger {
+  info?: (obj: Record<string, unknown>, msg?: string) => void;
+  warn?: (obj: Record<string, unknown>, msg?: string) => void;
+  debug?: (obj: Record<string, unknown>, msg?: string) => void;
+}
+
+// ── Provider bridge contract ─────────────────────────────────────────────────
+
+export interface ProviderRequest {
+  readonly systemPrompt: string;
+  readonly maxTokens: number;
+  readonly toolSchemas: ReadonlyArray<ToolSchema>;
+}
+
+/**
+ * The provider-neutral driver for the LLM call. Provider adapters
+ * implement this against their SDK; the loop calls it once per
+ * iteration. `H` is the opaque conversation-history shape — provider
+ * adapters choose what `H` is (typically `MessageParam[]` for Anthropic,
+ * `ChatCompletionMessageParam[]` for OpenAI). The loop never inspects it.
+ */
+export interface ProviderBridge<H> {
+  /** Construct the empty initial history. */
+  emptyHistory(): H;
+
+  /** Append a user message to the history. */
+  appendUserMessage(history: H, text: string): H;
+
+  /**
+   * Send the prompt + history; receive the assistant turn back. The
+   * bridge appends the raw assistant response to history before
+   * returning. The provider-neutral `turn` describes what the loop
+   * actually needs to know about the response.
+   */
+  send(
+    history: H,
+    request: ProviderRequest,
+  ): Promise<{ history: H; turn: AssistantTurn }>;
+
+  /**
+   * Append a list of tool-result blocks to the history (typically a
+   * user-role message containing tool_result blocks for Anthropic; a
+   * series of `role: "tool"` messages for OpenAI).
+   */
+  appendToolResults(
+    history: H,
+    results: ReadonlyArray<ToolResultBlock>,
+  ): H;
+}
+
+// ── Public agent surface (generic over history) ──────────────────────────────
+
+export interface AdjudicatedAgentOptions<K extends string, P, S, C, H> {
+  /**
+   * Pack the agent adjudicates against. MUST already be the output of
+   * `installPack(...)` or `withBasisAudit(...)`. The adapter does NOT
+   * double-wrap — Pack-author convention applies.
+   */
+  readonly pack: PackV0<K, P, S, C>;
+  /** Renderer producing system prompt + tool schemas for each iteration. */
+  readonly renderer: PromptRenderer<S, C>;
+  /** Provider bridge wrapping the SDK. */
+  readonly bridge: ProviderBridge<H>;
+  /** Persistence for DEFER. Combined park + resume surface. */
+  readonly deferStore: DeferRedis & ParkRedis;
+  /** Persistence for REQUEST_CONFIRMATION pauses (generic over H). */
+  readonly confirmationStore: ConfirmationStore<H>;
+  readonly auditSink?: AuditSink;
+  /** Required: Execution Ledger for replay suppression. */
+  readonly ledger: Ledger;
+  /** Optional tenant context. */
+  readonly runtimeContext?: RuntimeContext;
+  /** Hard cap on assistant↔tool ping-pong per .send() call. Defaults to 8. */
+  readonly maxIterations?: number;
+  /** Adopter-owned executor. Required. */
+  readonly executor: AdopterExecutor<K, P, S>;
+  /** `rk()` namespacer for the deferStore. Defaults to identity. */
+  readonly rk?: (raw: string) => string;
+  /** Override the nonce derived from each tool_use block. */
+  readonly deriveNonce?: (args: {
+    sessionId: string;
+    toolUseId: string;
+    payload: unknown;
+  }) => string;
+  readonly log?: AgentLogger;
+  /** Hash-verification policy for parked envelope blobs at resume. */
+  readonly verifyParkedHash?: "strict" | "warn" | "off";
+  /**
+   * Optional low-cardinality trace sink. The loop emits one event per
+   * iteration/decision/pause; sink must NOT throw. Defaults to no-op.
+   * See `./trace.ts` for the controlled-vocabulary event shape.
+   */
+  readonly traceSink?: TraceSink;
+}
+
+export interface SendInput<S, C, H> {
+  readonly sessionId: string;
+  readonly userMessage: string;
+  readonly state: S;
+  readonly context: C;
+  readonly history?: H;
+}
+
+export interface ResumeArgs<S, C, H> {
+  readonly sessionId: string;
+  readonly signal: string;
+  readonly state: S;
+  readonly context: C;
+  readonly history?: H;
+}
+
+export interface ConfirmArgs<S, C> {
+  readonly confirmationToken: string;
+  readonly accepted: boolean;
+  readonly state: S;
+  readonly context: C;
+}
+
+export type AgentOutcome =
+  | { kind: "completed"; assistantText: string }
+  | { kind: "deferred"; signal: string; intentHash: string }
+  | {
+      kind: "awaiting_confirmation";
+      prompt: string;
+      confirmationToken: string;
+    }
+  | { kind: "escalated"; to: "human" | "supervisor"; reason: string }
+  | { kind: "max_iterations_exceeded"; lastDecision: Decision | null };
+
+export interface AgentTurnResult<H> {
+  readonly events: ReadonlyArray<AgentEvent>;
+  readonly history: H;
+  readonly outcome: AgentOutcome;
+}
+
+export type AgentEvent =
+  | { kind: "user_message"; text: string }
+  | { kind: "assistant_text"; text: string }
+  | { kind: "tool_use"; toolUseId: string; toolName: string; input: unknown }
+  | { kind: "intent_proposed"; envelope: IntentEnvelope }
+  | { kind: "decision"; decision: Decision; envelope: IntentEnvelope }
+  | { kind: "handler_result"; toolUseId: string; result: unknown }
+  | {
+      kind: "tool_result";
+      toolUseId: string;
+      payload: ToolResultBlock;
+    };
+
+export interface AdjudicatedAgent<_K extends string, _P, S, C, H> {
+  /** One user message + (state, context) snapshot → resolved turn. */
+  send(input: SendInput<S, C, H>): Promise<AgentTurnResult<H>>;
+  /** Resume a parked DEFER (typically from an adopter's webhook handler). */
+  resume(args: ResumeArgs<S, C, H>): Promise<AgentTurnResult<H>>;
+  /** Resume a REQUEST_CONFIRMATION with a yes/no from the user. */
+  confirm(args: ConfirmArgs<S, C>): Promise<AgentTurnResult<H>>;
+}
+
+export type { Taint };