@haikeilabs/agentware 0.1.0 → 0.2.1

package/dist/kei/runtimeLink.js

@@ -0,0 +1,591 @@
+/**
+ * RuntimeLink contract: the harness → Agentware → kei-connector-runtime heartbeat.
+ *
+ * TypeScript mirror of the Go reference `go/kei/runtimelink` for
+ * `docs/specs/runtime-heartbeat-liveness.md` (HAI-141). Contract types only:
+ * configuration, status, identity, failure classes, the child's JSONL wire
+ * events, and redacted lifecycle events. It never spawns a process, opens a
+ * network connection, or reads a credential value. The only heartbeat path is
+ * harness → RuntimeLink → kei-connector-runtime; nothing here talks to the
+ * catalog.
+ *
+ * All three SDK languages share `testing/contracts/runtime-link`. Durations
+ * are milliseconds here (`intervalMs`), seconds in Python, and
+ * `time.Duration` in Go.
+ */
+/** The child stdout event version ("v") this SDK accepts. */
+export const RUNTIME_LINK_CONTRACT_VERSION = 1;
+/** Bound on one child stdout line, excluding the newline. */
+export const MAX_CHILD_LINE_BYTES = 4096;
+/** Capacity of the RuntimeLink event ring. */
+export const RUNTIME_LINK_EVENT_BUFFER_SIZE = 64;
+export const RUNTIME_LINK_SDK_LANG = "typescript";
+export const HARNESS_KINDS = [
+    "assistant",
+    "pde",
+    "chat-discord",
+    "chat-slack",
+    "chat-teams",
+    "cli",
+];
+export const LINK_STATES = [
+    "disabled",
+    "starting",
+    "connected",
+    "degraded",
+    "reconnecting",
+    "terminal",
+    "stopped",
+];
+/**
+ * Closed failure taxonomy (spec §6.3). Separates harness↔runtime failures
+ * from runtime↔catalog failures so alerts route to the right owner.
+ */
+export const FAILURE_CLASSES = [
+    "config_invalid",
+    "runtime_unavailable",
+    "runtime_crashloop",
+    "runtime_unresponsive",
+    "contract_mismatch",
+    "catalog_unreachable",
+    "catalog_timeout",
+    "catalog_error",
+    "catalog_backpressure",
+    "installation_unauthorized",
+    "installation_stale",
+    "installation_offline",
+    "audit_backlog",
+    "legacy_runtime_unverified",
+];
+export const BEAT_OUTCOMES = [
+    "ok",
+    "catalog_unreachable",
+    "catalog_timeout",
+    "catalog_error",
+    "catalog_backpressure",
+    "catalog_rejected",
+    "unauthorized",
+];
+export const LIFECYCLE_EVENT_NAMES = [
+    "runtime.link.started",
+    "runtime.link.connected",
+    "runtime.link.degraded",
+    "runtime.link.reconnecting",
+    "runtime.link.terminal",
+    "runtime.link.stopped",
+];
+export const SDK_LANGS = ["go", "python", "typescript"];
+/** The exact environment a runtime child may receive; never `process.env`. */
+export const CHILD_ENV_ALLOWLIST = [
+    "KEI_RUNTIME_TOKEN",
+    "KEI_RUNTIME_CONTROL_PLANE_URL",
+    "KEI_HARNESS_KIND",
+    "KEI_HARNESS_VERSION",
+    "KEI_DEPLOYMENT_ENV",
+    "KEI_AGENTWARE_SDK_LANG",
+    "KEI_AGENTWARE_SDK_VERSION",
+    "KEI_HEARTBEAT_RUN_ID",
+    "PATH",
+    "HOME",
+    "TZ",
+];
+function isOneOf(set, value) {
+    return (typeof value === "string" && set.includes(value));
+}
+// ---------------------------------------------------------------------------
+// Configuration (spec §3.1, §3.2)
+// ---------------------------------------------------------------------------
+/** Environment variables. KEI_PROXY_* keep their legacy names (runtime contract). */
+export const RUNTIME_LINK_ENV = {
+    enabled: "KEI_RUNTIME_ENABLED",
+    token: "KEI_RUNTIME_TOKEN",
+    legacyToken: "KEI_HARNESS_TOKEN",
+    controlPlaneUrl: "KEI_RUNTIME_CONTROL_PLANE_URL",
+    proxyPath: "KEI_PROXY_PATH",
+    proxySha: "KEI_PROXY_SHA",
+    interval: "KEI_HEARTBEAT_INTERVAL",
+    timeout: "KEI_HEARTBEAT_TIMEOUT",
+    restartMin: "KEI_HEARTBEAT_RESTART_MIN",
+    restartMax: "KEI_HEARTBEAT_RESTART_MAX",
+    stableSeconds: "KEI_HEARTBEAT_STABLE_SECONDS",
+    logCount: "KEI_HEARTBEAT_LOG_COUNT",
+    harnessKind: "KEI_HARNESS_KIND",
+    harnessVersion: "KEI_HARNESS_VERSION",
+    deploymentEnv: "KEI_DEPLOYMENT_ENV",
+};
+/** The distribution keeps the kei-proxy name; the repo is kei-connector-runtime. */
+export const DEFAULT_RUNTIME_BINARY_PATH = "kei-proxy";
+/**
+ * Bounds. Interval is clamped; everything else is rejected when out of range
+ * so a typo fails closed instead of silently changing behavior.
+ */
+export const RUNTIME_LINK_BOUNDS = {
+    minIntervalMs: 15_000,
+    maxIntervalMs: 300_000,
+    maxGraceMs: 300_000,
+    minRestartMs: 1_000,
+    maxRestartMs: 3_600_000,
+    minStableResetMs: 1_000,
+    maxStableResetMs: 3_600_000,
+    minStopTimeoutMs: 1_000,
+    maxStopTimeoutMs: 60_000,
+    maxLogCount: 100,
+};
+export const RUNTIME_LINK_CONFIG_ERROR_CODES = [
+    "invalid_value",
+    "out_of_range",
+    "beat_timeout",
+    "harness_kind",
+    "envelope",
+    "legacy_token",
+    "token_missing",
+    "control_plane_url",
+    "binary",
+];
+/**
+ * Invalid RuntimeLink configuration. Carries the offending field and a stable
+ * code, never the offending value, so a misplaced secret cannot leak.
+ */
+export class RuntimeLinkConfigError extends Error {
+    code;
+    field;
+    constructor(code, field) {
+        super(`runtimeLink: invalid config: ${field}: ${code}`);
+        this.code = code;
+        this.field = field;
+        this.name = "RuntimeLinkConfigError";
+    }
+}
+/** The spec defaults with the link disabled. */
+export function defaultRuntimeLinkConfig() {
+    return {
+        enabled: false,
+        binary: { path: DEFAULT_RUNTIME_BINARY_PATH, sha256: "" },
+        controlPlaneUrl: "",
+        token: { env: RUNTIME_LINK_ENV.token },
+        intervalMs: 60_000,
+        beatTimeoutMs: 10_000,
+        graceMs: 15_000,
+        restart: { minMs: 1_000, maxMs: 300_000, stableResetMs: 300_000 },
+        stopTimeoutMs: 10_000,
+        logCount: 3,
+        harness: { kind: "", version: "", deploymentEnv: "" },
+    };
+}
+const VERSION_RE = /^[A-Za-z0-9._+-]{1,64}$/;
+const ENV_NAME_RE = /^[A-Za-z0-9._-]{1,32}$/;
+const SHA256_RE = /^[0-9a-f]{64}$/;
+const ID_RE = /^[A-Za-z0-9._:-]{1,128}$/;
+const REASON_RE = /^[a-z0-9_]{1,64}$/;
+const TIMESTAMP_RE = /^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2})(\.\d{1,9})?(Z|[+-]\d{2}:\d{2})$/;
+const ENV_INT_RE = /^[0-9]{1,9}$/;
+/**
+ * Clamp `intervalMs` to [15s, 300s] and validate every other field, throwing
+ * RuntimeLinkConfigError on the first violation. A disabled link (local-only
+ * mode) is valid, but its declared envelope and timings are still checked so
+ * typos fail loudly.
+ */
+export function normalizeRuntimeLinkConfig(cfg) {
+    const b = RUNTIME_LINK_BOUNDS;
+    const h = cfg.harness;
+    if ((h.kind && !isOneOf(HARNESS_KINDS, h.kind)) || (cfg.enabled && !h.kind)) {
+        throw new RuntimeLinkConfigError("harness_kind", "harness.kind");
+    }
+    if (h.version && !VERSION_RE.test(h.version)) {
+        throw new RuntimeLinkConfigError("envelope", "harness.version");
+    }
+    if (h.deploymentEnv && !ENV_NAME_RE.test(h.deploymentEnv)) {
+        throw new RuntimeLinkConfigError("envelope", "harness.deploymentEnv");
+    }
+    if (cfg.enabled) {
+        if (cfg.token.env === RUNTIME_LINK_ENV.legacyToken) {
+            throw new RuntimeLinkConfigError("legacy_token", "token");
+        }
+        if (cfg.token.env !== RUNTIME_LINK_ENV.token) {
+            throw new RuntimeLinkConfigError("invalid_value", "token");
+        }
+        validateControlPlaneUrl(cfg.controlPlaneUrl);
+        if (!cfg.binary.path || cfg.binary.path.includes("\0")) {
+            throw new RuntimeLinkConfigError("binary", "binary.path");
+        }
+        if (!cfg.binary.sha256 && h.deploymentEnv === "prod") {
+            throw new RuntimeLinkConfigError("binary", "binary.sha256");
+        }
+    }
+    if (cfg.binary.sha256 && !SHA256_RE.test(cfg.binary.sha256)) {
+        throw new RuntimeLinkConfigError("binary", "binary.sha256");
+    }
+    const intervalMs = Math.min(Math.max(cfg.intervalMs, b.minIntervalMs), b.maxIntervalMs);
+    if (!(cfg.beatTimeoutMs > 0) || 2 * cfg.beatTimeoutMs >= intervalMs) {
+        throw new RuntimeLinkConfigError("beat_timeout", "beatTimeoutMs");
+    }
+    if (!inRange(cfg.graceMs, 0, b.maxGraceMs)) {
+        throw new RuntimeLinkConfigError("out_of_range", "graceMs");
+    }
+    const r = cfg.restart;
+    if (!(r.minMs >= b.minRestartMs) ||
+        !(r.maxMs <= b.maxRestartMs) ||
+        r.minMs > r.maxMs) {
+        throw new RuntimeLinkConfigError("out_of_range", "restart");
+    }
+    if (!inRange(r.stableResetMs, b.minStableResetMs, b.maxStableResetMs)) {
+        throw new RuntimeLinkConfigError("out_of_range", "restart.stableResetMs");
+    }
+    if (!inRange(cfg.stopTimeoutMs, b.minStopTimeoutMs, b.maxStopTimeoutMs)) {
+        throw new RuntimeLinkConfigError("out_of_range", "stopTimeoutMs");
+    }
+    if (!Number.isInteger(cfg.logCount) ||
+        !inRange(cfg.logCount, 0, b.maxLogCount)) {
+        throw new RuntimeLinkConfigError("out_of_range", "logCount");
+    }
+    return { ...cfg, intervalMs };
+}
+function inRange(v, lo, hi) {
+    return v >= lo && v <= hi;
+}
+function validateControlPlaneUrl(raw) {
+    let ok = false;
+    try {
+        const u = new URL(raw);
+        ok =
+            (u.protocol === "http:" || u.protocol === "https:") &&
+                u.hostname !== "" &&
+                u.username === "" &&
+                u.password === "";
+    }
+    catch {
+        ok = false;
+    }
+    if (!ok)
+        throw new RuntimeLinkConfigError("control_plane_url", "controlPlaneUrl");
+}
+/**
+ * Build a normalized config from the spec §3.2 variables. Non-empty fields of
+ * `harness` override the KEI_HARNESS_* variables. The runtime token is only
+ * checked for presence; its value is never retained.
+ */
+export function runtimeLinkConfigFromEnv(env = process.env, harness = {}) {
+    const E = RUNTIME_LINK_ENV;
+    const get = (key) => (env[key] ?? "").trim();
+    const seconds = (key) => {
+        const raw = get(key);
+        if (raw === "")
+            return undefined;
+        if (!ENV_INT_RE.test(raw))
+            throw new RuntimeLinkConfigError("invalid_value", key);
+        return Number(raw) * 1000;
+    };
+    const cfg = defaultRuntimeLinkConfig();
+    cfg.intervalMs = seconds(E.interval) ?? cfg.intervalMs;
+    cfg.beatTimeoutMs = seconds(E.timeout) ?? cfg.beatTimeoutMs;
+    cfg.restart.minMs = seconds(E.restartMin) ?? cfg.restart.minMs;
+    cfg.restart.maxMs = seconds(E.restartMax) ?? cfg.restart.maxMs;
+    cfg.restart.stableResetMs =
+        seconds(E.stableSeconds) ?? cfg.restart.stableResetMs;
+    const logCount = get(E.logCount);
+    if (logCount !== "") {
+        if (!ENV_INT_RE.test(logCount))
+            throw new RuntimeLinkConfigError("invalid_value", E.logCount);
+        cfg.logCount = Number(logCount);
+    }
+    const hasToken = get(E.token) !== "";
+    if (!hasToken && get(E.legacyToken) !== "") {
+        throw new RuntimeLinkConfigError("legacy_token", E.legacyToken);
+    }
+    cfg.enabled = hasToken;
+    const enabled = get(E.enabled).toLowerCase();
+    if (enabled !== "") {
+        if (enabled === "true" || enabled === "1") {
+            if (!hasToken)
+                throw new RuntimeLinkConfigError("token_missing", E.token);
+            cfg.enabled = true;
+        }
+        else if (enabled === "false" || enabled === "0") {
+            cfg.enabled = false;
+        }
+        else {
+            throw new RuntimeLinkConfigError("invalid_value", E.enabled);
+        }
+    }
+    cfg.controlPlaneUrl = get(E.controlPlaneUrl);
+    cfg.binary = {
+        path: get(E.proxyPath) || DEFAULT_RUNTIME_BINARY_PATH,
+        sha256: get(E.proxySha),
+    };
+    cfg.harness = {
+        kind: harness.kind || get(E.harnessKind),
+        version: harness.version || get(E.harnessVersion),
+        deploymentEnv: harness.deploymentEnv || get(E.deploymentEnv),
+    };
+    return normalizeRuntimeLinkConfig(cfg);
+}
+// ---------------------------------------------------------------------------
+// Backoff and cancellation
+// ---------------------------------------------------------------------------
+const MAX_JITTER_SAMPLE = 1 - Number.EPSILON / 2;
+/**
+ * Full-jitter restart delay for attempt n (0-based):
+ * `floor(r × min(maxMs, minMs × 2^n))`. `r` is clamped to [0, 1); negative
+ * attempts count as 0.
+ */
+export function backoffDelayMs(backoff, attempt, r) {
+    const n = Math.min(Math.max(Math.trunc(attempt), 0), 30);
+    const capMs = Math.min(backoff.maxMs, backoff.minMs * 2 ** n);
+    const sample = Math.min(Math.max(r, 0), MAX_JITTER_SAMPLE);
+    return Math.floor(sample * capMs);
+}
+/**
+ * Sleep for the jittered delay, or reject with the signal's abort reason as
+ * soon as `signal` aborts, so a stop during backoff never waits out the delay.
+ */
+export function waitBackoff(backoff, attempt, options = {}) {
+    const { signal, random = Math.random } = options;
+    return new Promise((resolve, reject) => {
+        const abortReason = () => signal?.reason ?? new Error("aborted");
+        if (signal?.aborted) {
+            reject(abortReason());
+            return;
+        }
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(abortReason());
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, backoffDelayMs(backoff, attempt, random()));
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+/** A child line the SDK must drop and count. */
+export class ChildLineError extends Error {
+    kind;
+    constructor(kind, detail) {
+        super(`runtimeLink: child line ${kind}: ${detail}`);
+        this.kind = kind;
+        this.name = "ChildLineError";
+    }
+}
+const MAX_SEQ = Number.MAX_SAFE_INTEGER;
+const MAX_LATENCY_MS = 3_600_000;
+const MAX_NEXT_IN_MS = 3_600_000;
+class FieldReader {
+    raw;
+    constructor(raw) {
+        this.raw = raw;
+    }
+    text(key, required) {
+        if (!Object.hasOwn(this.raw, key)) {
+            if (required)
+                throw new ChildLineError("malformed", key);
+            return "";
+        }
+        const v = this.raw[key];
+        if (typeof v !== "string")
+            throw new ChildLineError("malformed", key);
+        return v;
+    }
+    id(key, required) {
+        const v = this.text(key, required);
+        if ((v !== "" || required) && !ID_RE.test(v))
+            throw new ChildLineError("malformed", key);
+        return v;
+    }
+    timestamp(key) {
+        const v = this.text(key, true);
+        if (!TIMESTAMP_RE.test(v))
+            throw new ChildLineError("malformed", key);
+        return v;
+    }
+    integer(key, required, lo, hi) {
+        if (!Object.hasOwn(this.raw, key)) {
+            if (required)
+                throw new ChildLineError("malformed", key);
+            return 0;
+        }
+        const v = this.raw[key];
+        if (typeof v !== "number" || !Number.isSafeInteger(v) || v < lo || v > hi) {
+            throw new ChildLineError("malformed", key);
+        }
+        return v;
+    }
+}
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+/**
+ * Parse one line of child stdout (a trailing "\n" / "\r\n" is ignored). Only
+ * allowlisted fields survive; payloads, results, reasoning, tokens, or any
+ * other key the runtime might emit are dropped. Throws ChildLineError for
+ * lines the SDK must drop and count.
+ */
+export function parseChildLine(line) {
+    let text = typeof line === "string" ? line : decoder.decode(line);
+    if (text.endsWith("\n"))
+        text = text.slice(0, -1);
+    if (text.endsWith("\r"))
+        text = text.slice(0, -1);
+    if (encoder.encode(text).length > MAX_CHILD_LINE_BYTES) {
+        throw new ChildLineError("line_too_long", "line");
+    }
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        throw new ChildLineError("malformed", "not json");
+    }
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new ChildLineError("malformed", "not an object");
+    }
+    const obj = raw;
+    if (obj.v !== RUNTIME_LINK_CONTRACT_VERSION) {
+        throw new ChildLineError("contract_mismatch", "v");
+    }
+    if (typeof obj.event !== "string")
+        throw new ChildLineError("malformed", "event");
+    const f = new FieldReader(obj);
+    switch (obj.event) {
+        case "identity":
+            return {
+                kind: "identity",
+                identity: {
+                    runId: f.id("run_id", true),
+                    installationId: f.id("installation_id", true),
+                    orgId: f.id("org_id", true),
+                    workspaceId: f.id("workspace_id", false),
+                    platform: f.id("platform", false),
+                    status: f.id("status", false),
+                    bindingStatus: f.id("binding_status", false),
+                    runtimeVersion: f.id("runtime_version", false),
+                },
+            };
+        case "beat": {
+            const runId = f.id("run_id", true);
+            const seq = f.integer("seq", false, 0, MAX_SEQ);
+            const at = f.timestamp("at");
+            const outcome = f.text("outcome", true);
+            const latencyMs = f.integer("latency_ms", false, 0, MAX_LATENCY_MS);
+            const nextInMs = f.integer("next_in_ms", false, 0, MAX_NEXT_IN_MS);
+            const httpStatus = f.integer("http_status", false, 0, 599);
+            if (httpStatus > 0 && httpStatus < 100)
+                throw new ChildLineError("malformed", "http_status");
+            if (!isOneOf(BEAT_OUTCOMES, outcome))
+                throw new ChildLineError("contract_mismatch", "outcome");
+            return {
+                kind: "beat",
+                beat: { runId, seq, at, outcome, httpStatus, latencyMs, nextInMs },
+            };
+        }
+        case "terminal": {
+            const runId = f.id("run_id", true);
+            const reason = f.text("reason", true);
+            if (!REASON_RE.test(reason))
+                throw new ChildLineError("malformed", "reason");
+            return { kind: "terminal", terminal: { runId, reason } };
+        }
+        default:
+            return { kind: "ignored" };
+    }
+}
+// ---------------------------------------------------------------------------
+// Redacted lifecycle events (spec §5.3)
+// ---------------------------------------------------------------------------
+/** A lifecycle event has a value outside its closed set or bounds. */
+export class InvalidLinkEventError extends Error {
+    constructor(detail) {
+        super(`runtimeLink: invalid lifecycle event: ${detail}`);
+        this.name = "InvalidLinkEventError";
+    }
+}
+function isCount(v) {
+    return typeof v === "number" && Number.isSafeInteger(v) && v >= 0;
+}
+/** Throws InvalidLinkEventError unless every closed set and bound holds. */
+export function validateLinkEvent(ev) {
+    const h = ev.harness;
+    const ok = isOneOf(LIFECYCLE_EVENT_NAMES, ev.name) &&
+        isOneOf(LINK_STATES, ev.state) &&
+        (ev.reason === "" || isOneOf(FAILURE_CLASSES, ev.reason)) &&
+        ev.at instanceof Date &&
+        !Number.isNaN(ev.at.getTime()) &&
+        (ev.runId === "" || ID_RE.test(ev.runId)) &&
+        ID_RE.test(ev.sdkInstanceId) &&
+        isOneOf(HARNESS_KINDS, h.kind) &&
+        isOneOf(SDK_LANGS, h.sdkLang) &&
+        (h.version === "" || VERSION_RE.test(h.version)) &&
+        (h.deploymentEnv === "" || ENV_NAME_RE.test(h.deploymentEnv)) &&
+        (h.sdkVersion === "" || VERSION_RE.test(h.sdkVersion)) &&
+        isCount(ev.seq) &&
+        isCount(ev.restarts) &&
+        isCount(ev.consecutiveFails);
+    if (!ok)
+        throw new InvalidLinkEventError("value outside contract");
+    return ev;
+}
+function str(v, fallback = "") {
+    if (v === undefined)
+        return fallback;
+    if (typeof v !== "string")
+        throw new InvalidLinkEventError("expected string");
+    return v;
+}
+function parseEventTimestamp(v) {
+    const m = typeof v === "string" ? TIMESTAMP_RE.exec(v) : null;
+    if (!m)
+        throw new InvalidLinkEventError("at");
+    const fraction = (m[2] ?? ".000").slice(0, 4);
+    return new Date(`${m[1]}${fraction}${m[3]}`);
+}
+/** Build an event from allowlisted wire keys only; everything else is dropped. */
+export function linkEventFromWire(raw) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new InvalidLinkEventError("not an object");
+    }
+    const o = raw;
+    const hRaw = o.harness ?? {};
+    if (hRaw === null || typeof hRaw !== "object" || Array.isArray(hRaw)) {
+        throw new InvalidLinkEventError("harness");
+    }
+    const h = hRaw;
+    return validateLinkEvent({
+        name: str(o.name),
+        at: parseEventTimestamp(o.at),
+        state: str(o.state),
+        reason: str(o.reason),
+        runId: str(o.run_id),
+        seq: (o.seq ?? 0),
+        sdkInstanceId: str(o.sdk_instance_id),
+        harness: {
+            kind: str(h.kind),
+            version: str(h.version),
+            deploymentEnv: str(h.deployment_env),
+            sdkLang: str(h.sdk_lang),
+            sdkVersion: str(h.sdk_version),
+        },
+        restarts: (o.restarts ?? 0),
+        consecutiveFails: (o.consecutive_fails ?? 0),
+    });
+}
+/** Validate and emit exactly the allowlisted keys; `at` is UTC with millisecond precision. */
+export function linkEventToWire(ev) {
+    validateLinkEvent(ev);
+    const h = ev.harness;
+    return {
+        name: ev.name,
+        at: ev.at.toISOString(),
+        state: ev.state,
+        reason: ev.reason,
+        run_id: ev.runId,
+        seq: ev.seq,
+        sdk_instance_id: ev.sdkInstanceId,
+        harness: {
+            kind: h.kind,
+            version: h.version,
+            deployment_env: h.deploymentEnv,
+            sdk_lang: h.sdkLang,
+            sdk_version: h.sdkVersion,
+        },
+        restarts: ev.restarts,
+        consecutive_fails: ev.consecutiveFails,
+    };
+}

package/dist/llm/backend.d.ts

@@ -1,4 +1,5 @@
 import type { Message } from "./request.js";
+import type { ToolDefinition } from "./request.js";
 import type { Response } from "./response.js";
 export interface Backend {
     complete(messages: Message[]): Response;
@@ -6,4 +7,10 @@ export interface Backend {
     modelName(): string;
     contextWindowSize(): number;
 }
+export interface AsyncBackend {
+    complete(messages: Message[], tools?: ToolDefinition[]): Promise<Response>;
+    supportsNativeToolCalling(): boolean;
+    modelName(): string;
+    contextWindowSize(): number;
+}
 //# sourceMappingURL=backend.d.ts.map

package/dist/llm/backend.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../../src/llm/backend.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,QAAQ,CAAC;IACxC,yBAAyB,IAAI,OAAO,CAAC;IACrC,SAAS,IAAI,MAAM,CAAC;IACpB,iBAAiB,IAAI,MAAM,CAAC;CAC7B"}
+{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../../src/llm/backend.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,QAAQ,CAAC;IACxC,yBAAyB,IAAI,OAAO,CAAC;IACrC,SAAS,IAAI,MAAM,CAAC;IACpB,iBAAiB,IAAI,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,KAAK,CAAC,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC3E,yBAAyB,IAAI,OAAO,CAAC;IACrC,SAAS,IAAI,MAAM,CAAC;IACpB,iBAAiB,IAAI,MAAM,CAAC;CAC7B"}

package/dist/llm/index.d.ts

@@ -1,4 +1,5 @@
-export { Backend } from "./backend.js";
+export { Backend, AsyncBackend } from "./backend.js";
 export { Message, Role, Request, ToolDefinition } from "./request.js";
 export { Response, ToolCall, TokenUsage } from "./response.js";
+export { OpenAIBackend, OpenAIBackendConfig, OpenAIError, FetchFn, FetchLikeInit, FetchLikeResponse, parseToolArguments, } from "./openai_backend.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/llm/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/llm/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACtE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/llm/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACtE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC/D,OAAO,EACL,aAAa,EACb,mBAAmB,EACnB,WAAW,EACX,OAAO,EACP,aAAa,EACb,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,qBAAqB,CAAC"}

package/dist/llm/index.js

@@ -1 +1,2 @@
 export { Role } from "./request.js";
+export { OpenAIBackend, OpenAIError, parseToolArguments, } from "./openai_backend.js";

package/dist/llm/openai_backend.d.ts

@@ -0,0 +1,51 @@
+import type { Message, ToolDefinition } from "./request.js";
+import type { Response } from "./response.js";
+import type { AsyncBackend } from "./backend.js";
+export interface FetchLikeResponse {
+    ok: boolean;
+    status: number;
+    text(): Promise<string>;
+}
+export interface FetchLikeInit {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+    signal?: AbortSignal;
+}
+export type FetchFn = (url: string, init?: FetchLikeInit) => Promise<FetchLikeResponse>;
+export declare class OpenAIError extends Error {
+    readonly status?: number;
+    constructor(message: string, status?: number);
+}
+export interface OpenAIBackendConfig {
+    model: string;
+    baseUrl?: string;
+    apiKey?: string;
+    fetchFn?: FetchFn;
+    timeoutMs?: number;
+    maxResponseBytes?: number;
+    maxToolArgBytes?: number;
+    contextWindowSize?: number;
+    temperature?: number;
+    maxTokens?: number;
+}
+export declare function parseToolArguments(raw: string | null | undefined, maxBytes: number): Record<string, unknown>;
+export declare class OpenAIBackend implements AsyncBackend {
+    private readonly model;
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly fetchFn;
+    private readonly timeoutMs;
+    private readonly maxResponseBytes;
+    private readonly maxToolArgBytes;
+    private readonly contextWindow;
+    private readonly temperature?;
+    private readonly maxTokens?;
+    constructor(config: OpenAIBackendConfig);
+    complete(messages: Message[], tools?: ToolDefinition[]): Promise<Response>;
+    private parseCompletion;
+    supportsNativeToolCalling(): boolean;
+    modelName(): string;
+    contextWindowSize(): number;
+}
+//# sourceMappingURL=openai_backend.d.ts.map

package/dist/llm/openai_backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai_backend.d.ts","sourceRoot":"","sources":["../../src/llm/openai_backend.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE5D,OAAO,KAAK,EAAE,QAAQ,EAAwB,MAAM,eAAe,CAAC;AACpE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjD,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;CACzB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,MAAM,OAAO,GAAG,CACpB,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE,aAAa,KACjB,OAAO,CAAC,iBAAiB,CAAC,CAAC;AAEhC,qBAAa,WAAY,SAAQ,KAAK;IACpC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;gBAEb,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM;CAK7C;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAwCD,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAC9B,QAAQ,EAAE,MAAM,GACf,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAczB;AAkDD,qBAAa,aAAc,YAAW,YAAY;IAChD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;IAClC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAS;gBAExB,MAAM,EAAE,mBAAmB;IAajC,QAAQ,CACZ,QAAQ,EAAE,OAAO,EAAE,EACnB,KAAK,CAAC,EAAE,cAAc,EAAE,GACvB,OAAO,CAAC,QAAQ,CAAC;IA2EpB,OAAO,CAAC,eAAe;IA2CvB,yBAAyB,IAAI,OAAO;IAIpC,SAAS,IAAI,MAAM;IAInB,iBAAiB,IAAI,MAAM;CAG5B"}