@adjudicate/adapter-core 0.1.0 → 0.1.1

package/dist/persistence.d.ts

@@ -0,0 +1,72 @@
+/**
+ * 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";
+/**
+ * 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>;
+}
+/**
+ * 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 declare function createInMemoryDeferStore(): DeferRedis & ParkRedis;
+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>;
+}
+export declare function createInMemoryConfirmationStore<H = unknown>(): ConfirmationStore<H>;
+//# sourceMappingURL=persistence.d.ts.map

package/dist/persistence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistence.d.ts","sourceRoot":"","sources":["../src/persistence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAIvD;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACzC,GAAG,CACD,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,OAAO,EAAE;QAAE,EAAE,EAAE,IAAI,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,GAChC,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC1B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACnC,IAAI,CAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACpC,IAAI,CAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACpC,MAAM,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACzD;AAED;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACnC,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACnC,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACpE,GAAG,CACD,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,OAAO,EAAE;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,GACtB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC1B,aAAa,CAAC,CACZ,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,MAAM,CAAC,CAAC;CACpB;AAOD;;;;GAIG;AACH,wBAAgB,wBAAwB,IAAI,UAAU,GAAG,SAAS,CAwDjE;AAID,MAAM,WAAW,mBAAmB,CAAC,CAAC,GAAG,OAAO;IAC9C,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,wBAAwB,EAAE,CAAC,CAAC;IACrC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB,CAAC,CAAC,GAAG,OAAO;IAC5C,GAAG,CACD,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,mBAAmB,CAAC,CAAC,CAAC,EAC/B,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;CAC7D;AAOD,wBAAgB,+BAA+B,CAAC,CAAC,GAAG,OAAO,KAAK,iBAAiB,CAAC,CAAC,CAAC,CAiBnF"}

package/dist/persistence.js

@@ -0,0 +1,92 @@
+/**
+ * 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.
+ */
+/**
+ * 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() {
+    const store = new Map();
+    const counters = new Map();
+    const isAlive = (entry) => entry !== undefined && entry.expiresAt > Date.now();
+    function setRaw(key, value, options) {
+        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, value, options) {
+            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, _seconds, _mode) {
+            return 1;
+        },
+    };
+}
+export function createInMemoryConfirmationStore() {
+    const store = new Map();
+    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;
+        },
+    };
+}
+//# sourceMappingURL=persistence.js.map

package/dist/persistence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistence.js","sourceRoot":"","sources":["../src/persistence.ts"],"names":[],"mappings":"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"}

package/dist/trace.d.ts

@@ -0,0 +1,76 @@
+/**
+ * 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 declare const noopTraceSink: TraceSink;
+/**
+ * In-memory trace sink for tests. Captures every event in
+ * registration order.
+ */
+export declare function createInMemoryTraceSink(): TraceSink & {
+    readonly events: ReadonlyArray<AdapterTraceEvent>;
+    reset(): void;
+};
+//# sourceMappingURL=trace.d.ts.map

package/dist/trace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace.d.ts","sourceRoot":"","sources":["../src/trace.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAEjD,MAAM,MAAM,iBAAiB,GACzB,iBAAiB,GACjB,kBAAkB,GAClB,QAAQ,GACR,WAAW,GACX,yBAAyB,CAAC;AAE9B,MAAM,MAAM,kBAAkB,GAC1B,UAAU,GACV,uBAAuB,GACvB,WAAW,CAAC;AAEhB;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC;IAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,4DAA4D;IAC5D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,oDAAoD;IACpD,QAAQ,CAAC,YAAY,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IACzC,mCAAmC;IACnC,QAAQ,CAAC,WAAW,CAAC,EAAE,kBAAkB,CAAC;CAC3C;AAED,mDAAmD;AACnD,MAAM,WAAW,SAAS;IACxB,OAAO,CAAC,KAAK,EAAE,iBAAiB,GAAG,IAAI,CAAC;CACzC;AAED;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,SAI3B,CAAC;AAEF;;;GAGG;AACH,wBAAgB,uBAAuB,IAAI,SAAS,GAAG;IACrD,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,iBAAiB,CAAC,CAAC;IAClD,KAAK,IAAI,IAAI,CAAC;CACf,CAWA"}

package/dist/trace.js

@@ -0,0 +1,65 @@
+/**
+ * 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.
+ */
+/**
+ * No-op trace sink. Default when none is supplied. Zero allocation,
+ * zero overhead.
+ */
+export const noopTraceSink = {
+    onTrace() {
+        /* no-op */
+    },
+};
+/**
+ * In-memory trace sink for tests. Captures every event in
+ * registration order.
+ */
+export function createInMemoryTraceSink() {
+    const events = [];
+    return {
+        events,
+        onTrace(event) {
+            events.push(event);
+        },
+        reset() {
+            events.length = 0;
+        },
+    };
+}
+//# sourceMappingURL=trace.js.map

package/dist/trace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace.js","sourceRoot":"","sources":["../src/trace.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAsCH;;;GAGG;AACH,MAAM,CAAC,MAAM,aAAa,GAAc;IACtC,OAAO;QACL,WAAW;IACb,CAAC;CACF,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,uBAAuB;IAIrC,MAAM,MAAM,GAAwB,EAAE,CAAC;IACvC,OAAO;QACL,MAAM;QACN,OAAO,CAAC,KAAK;YACX,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACrB,CAAC;QACD,KAAK;YACH,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC;QACpB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,219 @@
+/**
+ * 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 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 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;
+}
+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;
+}
+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 };
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,14 @@
+/**
+ * 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.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adjudicate/adapter-core",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "publishConfig": {
     "access": "public"
   },
@@ -15,9 +15,9 @@
     }
   },
   "dependencies": {
+    "@adjudicate/audit": "1.0.1",
     "@adjudicate/core": "1.0.0",
-    "@adjudicate/audit": "1.0.0",
-    "@adjudicate/runtime": "0.1.0"
+    "@adjudicate/runtime": "0.1.1"
   },
   "devDependencies": {
     "@eslint/eslintrc": "^3.0.0",
@@ -25,8 +25,8 @@
     "eslint": "^9.0.0",
     "typescript": "^5.9.0",
     "vitest": "^3.2.0",
-    "@adjudicate/pack-payments-pix": "0.1.0",
-    "@adjudicate/eslint-config": "0.0.1"
+    "@adjudicate/eslint-config": "0.0.1",
+    "@adjudicate/pack-payments-pix": "0.1.1"
   },
   "scripts": {
     "build": "tsc --outDir dist",