@oscharko-dev/keiko 0.1.0-beta.0

package/dist/gateway/openai-adapter.js

@@ -0,0 +1,263 @@
+// Zero-dependency OpenAI-compatible HTTP adapter built on globalThis.fetch and
+// AbortSignal. fetch, clock, request-id, and cost class are injected so tests run
+// with no network I/O and no real time. The raw provider body is never echoed into
+// an error; only a redacted, status-level summary is surfaced.
+import { request as httpsRequest } from "node:https";
+import { rootCertificates } from "node:tls";
+import { AuthenticationError, CancelledError, ContextOverflowError, ModelRefusalError, ProviderError, RateLimitError, TimeoutError, TransportError, } from "./errors.js";
+import { normalizeChatResponse } from "./normalize.js";
+import { redact } from "./redaction.js";
+function headersFromNode(headers) {
+    const out = new Headers();
+    for (const [name, value] of Object.entries(headers)) {
+        if (Array.isArray(value)) {
+            for (const item of value)
+                out.append(name, item);
+        }
+        else if (value !== undefined) {
+            out.set(name, value);
+        }
+    }
+    return out;
+}
+function isMissingIssuerError(error) {
+    const cause = isRecord(error) ? error.cause : undefined;
+    const candidates = [error, cause];
+    return candidates.some((item) => {
+        if (!isRecord(item))
+            return false;
+        return item.code === "UNABLE_TO_GET_ISSUER_CERT_LOCALLY";
+    });
+}
+function usesHttps(url) {
+    try {
+        return new URL(url).protocol === "https:";
+    }
+    catch {
+        return false;
+    }
+}
+function buildMessage(message) {
+    const toolCalls = message.toolCalls?.map((call) => ({
+        id: call.id,
+        type: "function",
+        function: { name: call.name, arguments: JSON.stringify(call.arguments) },
+    }));
+    return {
+        role: message.role,
+        content: message.role === "assistant" && toolCalls !== undefined && toolCalls.length > 0
+            ? null
+            : message.content,
+        ...(message.role === "tool" && message.toolCallId !== undefined
+            ? { tool_call_id: message.toolCallId }
+            : {}),
+        ...(toolCalls !== undefined && toolCalls.length > 0 ? { tool_calls: toolCalls } : {}),
+    };
+}
+function buildBody(request) {
+    const messages = request.messages.map(buildMessage);
+    const base = { model: request.modelId, messages };
+    const tools = request.tools === undefined
+        ? undefined
+        : request.tools.map((t) => ({
+            type: "function",
+            function: { name: t.name, description: t.description, parameters: t.parameters },
+        }));
+    const responseFormat = request.responseFormat?.type === "json_schema"
+        ? { type: "json_schema", json_schema: { schema: request.responseFormat.schema } }
+        : undefined;
+    return {
+        ...base,
+        ...(tools ? { tools } : {}),
+        ...(responseFormat ? { response_format: responseFormat } : {}),
+    };
+}
+function retryAfterMs(response) {
+    const header = response.headers.get("retry-after");
+    if (header === null) {
+        return null;
+    }
+    const seconds = Number(header);
+    return Number.isFinite(seconds) && seconds >= 0 ? seconds * 1000 : null;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function redactUnknown(value, secrets) {
+    if (typeof value === "string") {
+        return redact(value, secrets);
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => redactUnknown(item, secrets));
+    }
+    if (isRecord(value)) {
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, redactUnknown(item, secrets)]));
+    }
+    return value;
+}
+function redactRecord(value, secrets) {
+    return value === null ? null : redactUnknown(value, secrets);
+}
+function redactToolCall(call, secrets) {
+    return {
+        ...call,
+        name: redact(call.name, secrets),
+        arguments: redactUnknown(call.arguments, secrets),
+    };
+}
+function redactResponse(response, secrets) {
+    return {
+        ...response,
+        content: redact(response.content, secrets),
+        toolCalls: response.toolCalls.map((call) => redactToolCall(call, secrets)),
+        structuredOutput: redactRecord(response.structuredOutput, secrets),
+    };
+}
+function errorSignal(payload) {
+    const error = isRecord(payload) && isRecord(payload.error) ? payload.error : payload;
+    if (!isRecord(error)) {
+        return "";
+    }
+    return [error.code, error.type, error.message]
+        .filter((value) => typeof value === "string")
+        .join(" ")
+        .toLowerCase();
+}
+function isContextOverflow(response, payload) {
+    if (response.status !== 400 && response.status !== 413 && response.status !== 422) {
+        return false;
+    }
+    return /context[_ -]?length[_ -]?exceeded|context window|context.*exceed|maximum context|too many tokens|prompt too long|context overflow/.test(errorSignal(payload));
+}
+function isModelRefusal(payload) {
+    return /content[_ -]?filter|refus|safety|policy/.test(errorSignal(payload));
+}
+function mapHttpError(response, modelId, secrets, payload) {
+    if (isContextOverflow(response, payload)) {
+        throw new ContextOverflowError(`provider reported context overflow for '${modelId}'`, secrets);
+    }
+    if (isModelRefusal(payload)) {
+        throw new ModelRefusalError(`provider refused the request for '${modelId}'`, secrets);
+    }
+    if (response.status === 401 || response.status === 403) {
+        throw new AuthenticationError(`provider rejected credentials for '${modelId}'`, secrets);
+    }
+    if (response.status === 429) {
+        throw new RateLimitError(`provider rate limited '${modelId}'`, retryAfterMs(response), secrets);
+    }
+    throw new ProviderError(`provider returned HTTP ${String(response.status)} for '${modelId}'`, response.status, secrets);
+}
+export class OpenAiAdapter {
+    deps;
+    fetchImpl;
+    now;
+    useBundledCaFallback;
+    constructor(deps) {
+        this.deps = deps;
+        this.fetchImpl = deps.fetchImpl ?? globalThis.fetch;
+        this.now = deps.now ?? Date.now;
+        this.useBundledCaFallback = deps.fetchImpl === undefined;
+    }
+    call = async (request, config) => {
+        const secrets = [config.apiKey, config.baseUrl];
+        if (request.cancellationSignal?.aborted === true) {
+            throw new CancelledError(`request for '${config.modelId}' cancelled before dispatch`, secrets);
+        }
+        const start = this.now();
+        const response = await this.dispatch(request, config, secrets);
+        if (!response.ok) {
+            const errorPayload = await this.readErrorBody(response);
+            mapHttpError(response, config.modelId, secrets, errorPayload);
+        }
+        const payload = await this.readBody(response, config, secrets);
+        return redactResponse(normalizeChatResponse(payload, config.modelId, {
+            requestId: this.deps.requestId,
+            latencyMs: this.now() - start,
+            costClass: this.deps.costClass,
+        }, request.responseFormat?.type === "json_schema"), secrets);
+    };
+    async dispatch(request, config, secrets) {
+        const timeoutSignal = AbortSignal.timeout(config.timeoutMs);
+        const cancel = request.cancellationSignal;
+        const signal = cancel ? AbortSignal.any([timeoutSignal, cancel]) : timeoutSignal;
+        const url = `${config.baseUrl}/chat/completions`;
+        const body = JSON.stringify(buildBody(request));
+        const headers = {
+            "content-type": "application/json",
+            authorization: `Bearer ${config.apiKey}`,
+        };
+        try {
+            return await this.fetchImpl(url, {
+                method: "POST",
+                headers,
+                body,
+                signal,
+            });
+        }
+        catch (error) {
+            if (this.useBundledCaFallback && usesHttps(url) && isMissingIssuerError(error)) {
+                try {
+                    // Some shared-OpenSSL Node builds do not use Node's bundled public CA set by default.
+                    return await this.dispatchWithBundledCa(url, headers, body, signal);
+                }
+                catch (fallbackError) {
+                    throw this.mapDispatchError(fallbackError, config, cancel, timeoutSignal, secrets);
+                }
+            }
+            throw this.mapDispatchError(error, config, cancel, timeoutSignal, secrets);
+        }
+    }
+    dispatchWithBundledCa(url, headers, body, signal) {
+        return new Promise((resolve, reject) => {
+            const req = httpsRequest(url, {
+                method: "POST",
+                headers,
+                ca: Array.from(rootCertificates),
+                signal,
+            }, (res) => {
+                const chunks = [];
+                res.on("data", (chunk) => {
+                    chunks.push(chunk);
+                });
+                res.on("end", () => {
+                    resolve(new Response(Buffer.concat(chunks), {
+                        status: res.statusCode ?? 500,
+                        statusText: res.statusMessage ?? "",
+                        headers: headersFromNode(res.headers),
+                    }));
+                });
+                res.on("error", reject);
+            });
+            req.on("error", reject);
+            req.end(body);
+        });
+    }
+    mapDispatchError(error, config, cancel, timeout, secrets) {
+        if (cancel?.aborted === true) {
+            return new CancelledError(`request for '${config.modelId}' cancelled`, secrets);
+        }
+        if (timeout.aborted) {
+            return new TimeoutError(`request for '${config.modelId}' timed out`, secrets);
+        }
+        if (error instanceof DOMException && error.name === "TimeoutError") {
+            return new TimeoutError(`request for '${config.modelId}' timed out`, secrets);
+        }
+        return new TransportError(`transport failure contacting '${config.modelId}'`, secrets);
+    }
+    async readBody(response, config, secrets) {
+        try {
+            return await response.json();
+        }
+        catch {
+            throw new TransportError(`provider sent an unreadable body for '${config.modelId}'`, secrets);
+        }
+    }
+    async readErrorBody(response) {
+        try {
+            return await response.json();
+        }
+        catch {
+            return null;
+        }
+    }
+}

package/dist/gateway/redaction.d.ts

@@ -0,0 +1 @@
+export declare function redact(input: string, additionalSecrets?: readonly string[]): string;

package/dist/gateway/redaction.js

@@ -0,0 +1,51 @@
+// Secret redaction at the boundary. Every provider-derived string passes through
+// redact() before it can reach an error message, log call, or serialised artefact.
+const REDACTED = "[REDACTED]";
+// Bearer <token>: keep the scheme, drop the credential.
+const BEARER_PATTERN = /\bBearer\s+[\w.\-+/=]+/gi;
+const BASIC_AUTH_PATTERN = /\bBasic\s+[\w.\-+/=]+/gi;
+// OpenAI-style keys (sk-, sk-proj-, etc.): a prefix followed by >= 16 secret chars.
+const API_KEY_PATTERN = /\bsk-[A-Za-z0-9_-]{16,}/g;
+// Common third-party credential shapes. Each is a single linear character class with one
+// bounded/open quantifier (no nesting), so none can backtrack catastrophically — this keeps
+// CodeQL js/polynomial-redos satisfied while scrubbing non-OpenAI secrets from tool output.
+const GITHUB_TOKEN_PATTERN = /\bgh[pousr]_[A-Za-z0-9]{20,}/g;
+const AWS_ACCESS_KEY_PATTERN = /\bAKIA[0-9A-Z]{16}\b/g;
+const SLACK_TOKEN_PATTERN = /\bxox[baprs]-[A-Za-z0-9-]{10,}/g;
+const GOOGLE_API_KEY_PATTERN = /\bAIza[0-9A-Za-z_-]{20,}/g;
+const PEM_PRIVATE_KEY_BLOCK_PATTERN = /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g;
+const PEM_PRIVATE_KEY_HEADER_PATTERN = /-----BEGIN [A-Z ]*PRIVATE KEY-----/g;
+const GENERIC_API_KEY_HEADER_PATTERN = /\b(x-api-key\s*:\s*)[^\s"'`,;]+/gi;
+const GENERIC_API_KEY_ASSIGNMENT_PATTERN = /\b(api[_-]?key\s*[=:]\s*)[^\s"'`,;&]+/gi;
+const BUILTIN_PATTERNS = [
+    GITHUB_TOKEN_PATTERN,
+    AWS_ACCESS_KEY_PATTERN,
+    SLACK_TOKEN_PATTERN,
+    GOOGLE_API_KEY_PATTERN,
+    PEM_PRIVATE_KEY_BLOCK_PATTERN,
+    PEM_PRIVATE_KEY_HEADER_PATTERN,
+];
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+// Strips known secret shapes and any caller-supplied literal secrets from `input`.
+// `additionalSecrets` lets the gateway pass the exact apiKey/baseUrl values it holds
+// so even non-standard key formats are scrubbed.
+export function redact(input, additionalSecrets = []) {
+    let output = input
+        .replace(BEARER_PATTERN, `Bearer ${REDACTED}`)
+        .replace(BASIC_AUTH_PATTERN, `Basic ${REDACTED}`)
+        .replace(GENERIC_API_KEY_HEADER_PATTERN, `$1${REDACTED}`)
+        .replace(GENERIC_API_KEY_ASSIGNMENT_PATTERN, `$1${REDACTED}`)
+        .replace(API_KEY_PATTERN, REDACTED);
+    for (const pattern of BUILTIN_PATTERNS) {
+        output = output.replace(pattern, REDACTED);
+    }
+    for (const secret of additionalSecrets) {
+        if (secret.length === 0) {
+            continue;
+        }
+        output = output.replace(new RegExp(escapeRegExp(secret), "g"), REDACTED);
+    }
+    return output;
+}

package/dist/gateway/resilience.d.ts

@@ -0,0 +1,24 @@
+import type { CircuitBreakerConfig, CircuitBreakerStatus, Clock } from "./types.js";
+export declare const systemClock: Clock;
+export interface RetryConfig {
+    readonly maxRetries: number;
+    readonly retryBaseDelayMs: number;
+    readonly timeoutMs?: number | undefined;
+}
+export declare function executeWithRetry<T>(operation: (attemptTimeoutMs?: number) => Promise<T>, config: RetryConfig, clock: Clock, signal?: AbortSignal): Promise<T>;
+export declare class CircuitBreaker {
+    private readonly modelId;
+    private readonly config;
+    private readonly clock;
+    private state;
+    private consecutiveFailures;
+    private openedAt;
+    private probesRemaining;
+    constructor(modelId: string, config: CircuitBreakerConfig, clock: Clock);
+    assertAllowed(): void;
+    recordSuccess(): void;
+    recordFailure(): void;
+    status(modelId: string): CircuitBreakerStatus;
+    private open;
+    private close;
+}

package/dist/gateway/resilience.js

@@ -0,0 +1,166 @@
+// Resilience primitives: a real-time Clock, a bounded exponential-backoff retry
+// loop, and a per-(model,endpoint) circuit breaker. All time-dependent behaviour
+// flows through the injectable Clock so tests are deterministic and instant.
+import { CancelledError, CircuitOpenError, GatewayError, RateLimitError } from "./errors.js";
+const MAX_BACKOFF_MS = 30_000;
+export const systemClock = {
+    now: () => Date.now(),
+    sleep: (ms, signal) => {
+        if (signal?.aborted === true) {
+            return Promise.reject(new DOMException("cancelled", "AbortError"));
+        }
+        return new Promise((resolve, reject) => {
+            const timeout = setTimeout(() => {
+                signal?.removeEventListener("abort", onAbort);
+                resolve();
+            }, ms);
+            function onAbort() {
+                clearTimeout(timeout);
+                reject(new DOMException("cancelled", "AbortError"));
+            }
+            signal?.addEventListener("abort", onAbort, { once: true });
+        });
+    },
+};
+function backoffDelayMs(attempt, base) {
+    return Math.min(base * 2 ** (attempt - 1), MAX_BACKOFF_MS);
+}
+// A RateLimitError with an explicit retryAfterMs is honoured; otherwise the error's
+// own `retryable` flag decides. Non-GatewayErrors are never retried.
+function retryDelayMs(error, attempt, base) {
+    if (!(error instanceof GatewayError) || !error.retryable) {
+        return null;
+    }
+    if (error instanceof RateLimitError && error.retryAfterMs !== null && error.retryAfterMs > 0) {
+        return Math.min(error.retryAfterMs, MAX_BACKOFF_MS);
+    }
+    return backoffDelayMs(attempt, base);
+}
+function assertNotAborted(signal) {
+    if (signal?.aborted === true) {
+        throw new CancelledError("request cancelled during retry");
+    }
+}
+function remainingBudgetMs(start, timeoutMs, clock) {
+    if (timeoutMs === undefined) {
+        return Number.POSITIVE_INFINITY;
+    }
+    return Math.max(0, timeoutMs - (clock.now() - start));
+}
+function asError(error) {
+    if (error instanceof Error) {
+        return error;
+    }
+    return new Error(String(error));
+}
+async function sleepWithCancellation(clock, delayMs, signal) {
+    assertNotAborted(signal);
+    try {
+        await clock.sleep(delayMs, signal);
+    }
+    catch (error) {
+        if (signal?.aborted === true) {
+            throw new CancelledError("request cancelled during retry backoff");
+        }
+        throw error;
+    }
+    assertNotAborted(signal);
+}
+export async function executeWithRetry(operation, config, clock, signal) {
+    let lastError;
+    const start = clock.now();
+    for (let attempt = 1; attempt <= config.maxRetries + 1; attempt += 1) {
+        assertNotAborted(signal);
+        const attemptBudget = remainingBudgetMs(start, config.timeoutMs, clock);
+        if (attemptBudget <= 0) {
+            if (lastError) {
+                throw lastError;
+            }
+            throw new CancelledError("request timeout budget exhausted before provider call");
+        }
+        try {
+            return await operation(Number.isFinite(attemptBudget) ? Math.max(1, Math.floor(attemptBudget)) : undefined);
+        }
+        catch (error) {
+            lastError = asError(error);
+            const delay = attempt <= config.maxRetries
+                ? retryDelayMs(lastError, attempt, config.retryBaseDelayMs)
+                : null;
+            if (delay === null) {
+                throw lastError;
+            }
+            const remaining = remainingBudgetMs(start, config.timeoutMs, clock);
+            if (remaining <= 0) {
+                throw lastError;
+            }
+            await sleepWithCancellation(clock, Math.min(delay, remaining), signal);
+        }
+    }
+    throw lastError ?? new CancelledError("request timeout budget exhausted after retries");
+}
+export class CircuitBreaker {
+    modelId;
+    config;
+    clock;
+    state = "closed";
+    consecutiveFailures = 0;
+    openedAt = null;
+    probesRemaining = 0;
+    constructor(modelId, config, clock) {
+        this.modelId = modelId;
+        this.config = config;
+        this.clock = clock;
+    }
+    // Called before forwarding a request. Throws CircuitOpenError when the breaker is
+    // open and the cooldown has not elapsed; otherwise lets the call through (entering
+    // half-open as a side effect when cooldown has passed).
+    assertAllowed() {
+        if (this.state === "open") {
+            if (this.openedAt !== null && this.clock.now() - this.openedAt >= this.config.cooldownMs) {
+                this.state = "half-open";
+                this.probesRemaining = this.config.halfOpenProbes;
+                return;
+            }
+            throw new CircuitOpenError(`circuit open for model '${this.modelId}'`);
+        }
+    }
+    recordSuccess() {
+        if (this.state === "half-open") {
+            this.probesRemaining -= 1;
+            if (this.probesRemaining <= 0) {
+                this.close();
+            }
+            return;
+        }
+        this.consecutiveFailures = 0;
+    }
+    recordFailure() {
+        if (this.state === "half-open") {
+            this.open();
+            return;
+        }
+        this.consecutiveFailures += 1;
+        if (this.consecutiveFailures >= this.config.failureThreshold) {
+            this.open();
+        }
+    }
+    status(modelId) {
+        return {
+            modelId,
+            state: this.state,
+            consecutiveFailures: this.consecutiveFailures,
+            openedAt: this.openedAt,
+        };
+    }
+    open() {
+        this.state = "open";
+        this.openedAt = this.clock.now();
+        this.probesRemaining = 0;
+    }
+    close() {
+        this.state = "closed";
+        this.consecutiveFailures = 0;
+        this.openedAt = null;
+        this.probesRemaining = 0;
+    }
+}

package/dist/gateway/types.d.ts

@@ -0,0 +1,108 @@
+export type ModelKind = "chat" | "embedding" | "ocr-vision";
+export type CostClass = "low" | "medium" | "high";
+export type LatencyClass = "fast" | "standard" | "slow";
+export interface ModelCapability {
+    readonly id: string;
+    readonly kind: ModelKind;
+    readonly contextWindow: number;
+    readonly maxOutputTokens: number;
+    readonly toolCalling: boolean;
+    readonly structuredOutput: boolean;
+    readonly streaming: boolean;
+    readonly costClass: CostClass;
+    readonly latencyClass: LatencyClass;
+    readonly throughputHint: string;
+    readonly preferredUseCases: readonly string[];
+    readonly knownLimitations: readonly string[];
+}
+export interface ModelProviderConfig {
+    readonly modelId: string;
+    readonly baseUrl: string;
+    readonly apiKey: string;
+    readonly timeoutMs: number;
+    readonly maxRetries: number;
+    readonly retryBaseDelayMs: number;
+}
+export interface CircuitBreakerConfig {
+    readonly failureThreshold: number;
+    readonly cooldownMs: number;
+    readonly halfOpenProbes: number;
+}
+export interface GatewayConfig {
+    readonly providers: readonly ModelProviderConfig[];
+    readonly circuitBreaker: CircuitBreakerConfig;
+}
+export interface ChatMessage {
+    readonly role: "system" | "user" | "assistant" | "tool";
+    readonly content: string;
+    readonly toolCallId?: string | undefined;
+    readonly toolCalls?: readonly NormalizedToolCall[] | undefined;
+}
+export interface ToolDefinition {
+    readonly name: string;
+    readonly description: string;
+    readonly parameters: Record<string, unknown>;
+}
+export type ResponseFormat = {
+    readonly type: "text";
+} | {
+    readonly type: "json_schema";
+    readonly schema: Record<string, unknown>;
+};
+export interface GatewayRequest {
+    readonly modelId: string;
+    readonly messages: readonly ChatMessage[];
+    readonly tools?: readonly ToolDefinition[] | undefined;
+    readonly responseFormat?: ResponseFormat | undefined;
+    readonly stream?: boolean | undefined;
+    readonly cancellationSignal?: AbortSignal | undefined;
+}
+export interface NormalizedToolCall {
+    readonly id: string;
+    readonly name: string;
+    readonly arguments: Record<string, unknown>;
+}
+export interface UsageMetadata {
+    readonly requestId: string;
+    readonly promptTokens: number;
+    readonly completionTokens: number;
+    readonly latencyMs: number;
+    readonly costClass: CostClass;
+}
+export type FinishReason = "stop" | "tool_calls" | "length" | "content_filter" | "error" | "cancelled";
+export interface NormalizedResponse {
+    readonly modelId: string;
+    readonly content: string;
+    readonly finishReason: FinishReason;
+    readonly toolCalls: readonly NormalizedToolCall[];
+    readonly structuredOutput: Record<string, unknown> | null;
+    readonly usage: UsageMetadata;
+}
+export interface StreamDelta {
+    readonly role?: "assistant" | undefined;
+    readonly contentDelta?: string | undefined;
+    readonly toolCallDelta?: Partial<NormalizedToolCall> | undefined;
+    readonly finishReason?: FinishReason | undefined;
+    readonly usage?: UsageMetadata | undefined;
+}
+export type StreamEvent = {
+    readonly type: "delta";
+    readonly delta: StreamDelta;
+} | {
+    readonly type: "done";
+    readonly response: NormalizedResponse;
+};
+export interface ProviderAdapter {
+    readonly call: (request: GatewayRequest, config: ModelProviderConfig) => Promise<NormalizedResponse>;
+}
+export interface Clock {
+    readonly now: () => number;
+    readonly sleep: (ms: number, signal?: AbortSignal) => Promise<void>;
+}
+export type CircuitState = "closed" | "open" | "half-open";
+export interface CircuitBreakerStatus {
+    readonly modelId: string;
+    readonly state: CircuitState;
+    readonly consecutiveFailures: number;
+    readonly openedAt: number | null;
+}

package/dist/gateway/types.js

@@ -0,0 +1,2 @@
+// All gateway interfaces and type aliases. No runtime code lives here.
+export {};

package/dist/harness/adapters.d.ts

@@ -0,0 +1,23 @@
+import type { GatewayRequest, NormalizedResponse, ToolDefinition } from "../gateway/types.js";
+import type { ModelPort, ToolCallRequest, ToolCallResult, ToolPort } from "./ports.js";
+export interface ChatModel {
+    readonly chat: (request: GatewayRequest) => Promise<NormalizedResponse>;
+}
+export declare class GatewayModelPort implements ModelPort {
+    private readonly gateway;
+    constructor(gateway: ChatModel);
+    call(request: GatewayRequest, signal: AbortSignal): Promise<NormalizedResponse>;
+}
+export interface RecordedToolCall {
+    readonly toolCallId: string;
+    readonly toolName: string;
+    readonly arguments: Record<string, unknown>;
+}
+export declare class DryRunToolPort implements ToolPort {
+    private readonly tools;
+    private readonly recorded;
+    constructor(tools?: readonly ToolDefinition[]);
+    execute(request: ToolCallRequest): Promise<ToolCallResult>;
+    listTools(): readonly ToolDefinition[];
+    calls(): readonly RecordedToolCall[];
+}

package/dist/harness/adapters.js

@@ -0,0 +1,38 @@
+// Production-side port adapters. GatewayModelPort wraps the ADR-0003 Gateway and
+// propagates the run's AbortSignal as GatewayRequest.cancellationSignal. DryRunToolPort
+// records tool calls without executing them — the Wave-1 no-op executor that keeps the
+// CLI dry-run path free of any side effect (real executors land in issue #6).
+import { CancelledError } from "../gateway/errors.js";
+export class GatewayModelPort {
+    gateway;
+    constructor(gateway) {
+        this.gateway = gateway;
+    }
+    async call(request, signal) {
+        return this.gateway.chat({ ...request, cancellationSignal: signal });
+    }
+}
+export class DryRunToolPort {
+    tools;
+    recorded = [];
+    constructor(tools = []) {
+        this.tools = tools;
+    }
+    execute(request) {
+        if (request.signal.aborted) {
+            return Promise.reject(new CancelledError("tool execution aborted before start"));
+        }
+        this.recorded.push({
+            toolCallId: request.toolCallId,
+            toolName: request.toolName,
+            arguments: request.arguments,
+        });
+        return Promise.resolve({ toolCallId: request.toolCallId, output: "", durationMs: 0 });
+    }
+    listTools() {
+        return this.tools;
+    }
+    calls() {
+        return this.recorded;
+    }
+}