@belticlabs/agent-risk-sdk 0.3.0 → 0.5.0

package/dist/chunk-JSE6JQJC.js

@@ -0,0 +1,530 @@
+import {
+  Chain
+} from "./chunk-X3W2Z5GC.js";
+
+// src/core/api-client.ts
+var TIMEOUT_MS = 1e4;
+var BelticApiError = class extends Error {
+  constructor(status, code, message, details, requestId) {
+    super(message);
+    this.status = status;
+    this.code = code;
+    this.details = details;
+    this.requestId = requestId;
+    this.name = "BelticApiError";
+  }
+  /** 5xx, 429 and network failures are retried by the transport and absorbed by `failOpen`; 4xx are neither (GAP-70). */
+  get retryable() {
+    return this.status === 0 || this.status >= 500 || this.status === 429;
+  }
+};
+var ApiClient = class {
+  baseUrl;
+  fetchImpl;
+  headers;
+  constructor(opts) {
+    this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
+    this.fetchImpl = opts.fetch ?? globalThis.fetch.bind(globalThis);
+    this.headers = {
+      authorization: `Bearer ${opts.apiKey}`,
+      "content-type": "application/json",
+      "user-agent": opts.userAgent ?? "@belticlabs/agent-risk-sdk"
+    };
+  }
+  post(path, body, headers = {}) {
+    return this.request("POST", path, JSON.stringify(body), headers);
+  }
+  get(path, query = {}) {
+    const qs = Object.entries(query).filter((e) => e[1] !== void 0).map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`).join("&");
+    return this.request("GET", qs ? `${path}?${qs}` : path, void 0, {});
+  }
+  async request(method, path, body, extra) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+    let res;
+    try {
+      res = await this.fetchImpl(`${this.baseUrl}${path}`, {
+        method,
+        headers: { ...this.headers, ...extra },
+        ...body !== void 0 ? { body } : {},
+        signal: controller.signal
+      });
+    } catch (err) {
+      throw new BelticApiError(
+        0,
+        "NETWORK",
+        `request to ${path} failed: ${err.message}`
+      );
+    } finally {
+      clearTimeout(timer);
+    }
+    const text = await res.text();
+    let json = null;
+    try {
+      json = text ? JSON.parse(text) : null;
+    } catch {
+      json = null;
+    }
+    if (!res.ok) {
+      const e = json?.error;
+      throw new BelticApiError(
+        res.status,
+        e?.code ?? `HTTP_${res.status}`,
+        e?.message ?? res.statusText,
+        e?.details,
+        e?.request_id
+      );
+    }
+    return json;
+  }
+};
+
+// src/core/config-error.ts
+var BelticConfigError = class extends Error {
+  code = "CONFIG";
+  constructor(message) {
+    super(`Beltic: ${message}`);
+    this.name = "BelticConfigError";
+  }
+};
+
+// src/core/record.ts
+function errorOf(err) {
+  const e = err;
+  return { name: String(e?.name ?? "Error"), message: String(e?.message ?? err) };
+}
+function openCall(session, kind, callId, start) {
+  const started = Date.now();
+  const opened = session.emit(`${kind}.start`, { callId, ...start });
+  const close = async (outcome) => {
+    await opened;
+    return session.emit(
+      `${kind}.end`,
+      { callId, ...outcome, durationMs: Date.now() - started }
+    );
+  };
+  return {
+    callId,
+    opened,
+    end: (outcome = {}) => close(outcome),
+    fail: (error, outcome = {}) => close({ error: errorOf(error), ...outcome })
+  };
+}
+async function recordCall(session, kind, callId, start, run, end = () => ({})) {
+  const span = openCall(session, kind, callId, start);
+  await span.opened;
+  try {
+    const result = await run();
+    await span.end(await end(result));
+    return result;
+  } catch (err) {
+    await span.fail(err);
+    throw err;
+  }
+}
+
+// src/core/transport.ts
+var MAX_BATCH = 50;
+var DEFAULT_TUNING = {
+  flushMs: 1e3,
+  maxBuffered: 5e3,
+  backoff: { baseMs: 200, maxMs: 3e4, maxAttempts: Number.POSITIVE_INFINITY }
+};
+var ChainRejectedError = class extends Error {
+  constructor(sessionId, source, result, options) {
+    super(
+      `chain ${sessionId}:${source} halted at seq ${result.seq}: ${result.status}${result.code ? ` ${result.code}` : ""}`,
+      options
+    );
+    this.sessionId = sessionId;
+    this.source = source;
+    this.result = result;
+    this.name = "ChainRejectedError";
+  }
+  /** Halted by retries exhausted on an outage — not by anything the platform rejected (GAP-70). */
+  get transient() {
+    return this.cause instanceof BelticApiError && this.cause.retryable;
+  }
+};
+var TransportClosedError = class extends Error {
+  constructor() {
+    super("transport is closed");
+    this.name = "TransportClosedError";
+  }
+};
+var Transport = class {
+  constructor(api, opts = {}) {
+    this.api = api;
+    this.opts = {
+      ...DEFAULT_TUNING,
+      ...opts,
+      backoff: { ...DEFAULT_TUNING.backoff, ...opts.backoff }
+    };
+  }
+  opts;
+  chains = /* @__PURE__ */ new Map();
+  buffered = 0;
+  timer = null;
+  closed = false;
+  inFlightCount = 0;
+  drainWaiters = [];
+  /**
+   * What `failOpen` may absorb (GAP-70): the platform could not be reached
+   * or failed on its side — a network error, a 5xx, a 429, or a chain
+   * halted after exhausting its retries on those. Everything the platform
+   * *rejected* (a 4xx: bad key, unknown session, invalid payload; a `fork`
+   * or `rejected` ack) is a fault of the client and throws in both modes.
+   */
+  static outage(err) {
+    if (err instanceof BelticApiError) return err.retryable;
+    if (err instanceof ChainRejectedError) return err.transient;
+    return false;
+  }
+  get size() {
+    return this.buffered;
+  }
+  hasRoom() {
+    return !this.closed && this.buffered < this.opts.maxBuffered;
+  }
+  haltedError(sessionId, source) {
+    return this.chains.get(`${sessionId}:${source}`)?.halted ?? null;
+  }
+  /** Callers check `hasRoom()` first and assign `seq` only then (GAP-38). */
+  enqueue(ev) {
+    if (this.closed) throw new TransportClosedError();
+    const key = `${ev.sessionId}:${ev.source}`;
+    let chain = this.chains.get(key);
+    if (!chain) {
+      chain = { key, pending: [], inFlight: null, attempts: 0, halted: null };
+      this.chains.set(key, chain);
+    }
+    if (chain.halted) throw chain.halted;
+    if (!this.hasRoom()) throw new Error("transport buffer is full");
+    chain.pending.push(ev);
+    this.buffered++;
+    if (chain.pending.length >= MAX_BATCH) void this.flushChain(chain);
+    else this.schedule();
+  }
+  /** Send everything pending and wait for every in-flight batch to settle (ack or halt). */
+  async flush() {
+    this.unschedule();
+    for (const chain of this.chains.values()) void this.flushChain(chain);
+    await this.drained();
+  }
+  async close() {
+    await this.flush();
+    this.closed = true;
+  }
+  schedule() {
+    if (this.timer) return;
+    this.timer = setTimeout(() => {
+      this.timer = null;
+      for (const chain of this.chains.values()) void this.flushChain(chain);
+    }, this.opts.flushMs);
+    this.timer.unref?.();
+  }
+  unschedule() {
+    if (!this.timer) return;
+    clearTimeout(this.timer);
+    this.timer = null;
+  }
+  drained() {
+    if (this.inFlightCount === 0 && [...this.chains.values()].every((c) => c.pending.length === 0 || c.halted)) {
+      return Promise.resolve();
+    }
+    return new Promise((resolve) => this.drainWaiters.push(resolve));
+  }
+  settleWaiters() {
+    if (this.inFlightCount > 0) return;
+    if (![...this.chains.values()].every((c) => c.pending.length === 0 || c.halted)) return;
+    const waiters = this.drainWaiters;
+    this.drainWaiters = [];
+    for (const w of waiters) w();
+  }
+  async flushChain(chain) {
+    if (chain.inFlight || chain.halted || chain.pending.length === 0) {
+      this.settleWaiters();
+      return;
+    }
+    const batch = chain.pending.splice(0, MAX_BATCH);
+    chain.inFlight = batch;
+    this.inFlightCount++;
+    try {
+      const ack = await this.send(chain, batch);
+      this.buffered -= batch.length;
+      const bad = ack.results.find((r) => r.status === "fork" || r.status === "rejected");
+      if (bad) {
+        const first = batch[0];
+        chain.halted = new ChainRejectedError(first.sessionId, first.source, bad);
+        this.buffered -= chain.pending.length;
+        chain.pending = [];
+        this.opts.onChainHalted?.(chain.halted);
+      }
+    } catch (err) {
+      this.buffered -= batch.length + chain.pending.length;
+      chain.pending = [];
+      const first = batch[0];
+      chain.halted = new ChainRejectedError(
+        first.sessionId,
+        first.source,
+        {
+          index: 0,
+          sessionId: first.sessionId,
+          source: first.source,
+          seq: first.seq,
+          status: "rejected",
+          code: "DELIVERY_FAILED"
+        },
+        { cause: err }
+      );
+      this.opts.onError?.(err);
+      this.opts.onChainHalted?.(chain.halted);
+    } finally {
+      chain.inFlight = null;
+      this.inFlightCount--;
+    }
+    if (chain.pending.length > 0 && !chain.halted) void this.flushChain(chain);
+    else this.settleWaiters();
+  }
+  async send(chain, batch) {
+    const { baseMs, maxMs, maxAttempts } = this.opts.backoff;
+    for (let attempt = 0; ; attempt++) {
+      try {
+        const ack = await this.api.post("/v1/evidence", batch);
+        chain.attempts = 0;
+        return ack;
+      } catch (err) {
+        const retryable = err instanceof BelticApiError ? err.retryable : true;
+        if (!retryable || attempt + 1 >= maxAttempts) throw err;
+        this.opts.onError?.(err);
+        const delay = Math.min(maxMs, baseMs * 2 ** attempt) * (0.5 + Math.random() / 2);
+        await new Promise((r) => setTimeout(r, delay));
+      }
+    }
+  }
+};
+
+// src/core/session.ts
+var Session = class {
+  constructor(deps, id, source, expiresAt, born) {
+    this.deps = deps;
+    this.id = id;
+    this.source = source;
+    this.expiresAt = expiresAt;
+    this.born = born;
+    this.chain = Chain.genesis(id, source);
+    this.now = deps.now ?? (() => /* @__PURE__ */ new Date());
+  }
+  chain;
+  building = Promise.resolve();
+  dropped = 0;
+  droppedFirstTs = null;
+  droppedLastTs = null;
+  closed = false;
+  now;
+  get head() {
+    return this.chain.head;
+  }
+  get droppedCount() {
+    return this.dropped;
+  }
+  get isClosed() {
+    return this.closed;
+  }
+  /**
+   * Resolves once the event is sequenced and buffered — not once it is
+   * acknowledged. `false` when the event was dropped, or (fail-open) when
+   * the chain halted on an outage.
+   */
+  async emit(kind, payload) {
+    try {
+      return await this.chainEvent(kind, payload);
+    } catch (err) {
+      if (!this.deps.failOpen || !Transport.outage(err)) throw err;
+      this.deps.onError?.(err);
+      return false;
+    }
+  }
+  /** The tool call whose `execute` the host runs itself; see `ToolCallSpan`. */
+  toolCall(call) {
+    const { callId, ...start } = call;
+    return openCall(this, "tool_call", callId, { transport: "local", ...start });
+  }
+  async chainEvent(kind, payload) {
+    const halted = this.deps.transport.haltedError(this.id, this.source);
+    if (halted) throw halted;
+    const ts = this.now().toISOString();
+    if (!this.deps.transport.hasRoom()) {
+      this.dropped++;
+      this.droppedFirstTs ??= ts;
+      this.droppedLastTs = ts;
+      return false;
+    }
+    if (this.dropped > 0) {
+      this.deps.transport.enqueue(
+        await this.next(
+          "transport.gap",
+          { dropped: this.dropped, firstTs: this.droppedFirstTs, lastTs: this.droppedLastTs },
+          ts
+        )
+      );
+      this.dropped = 0;
+      this.droppedFirstTs = this.droppedLastTs = null;
+    }
+    this.deps.transport.enqueue(await this.next(kind, payload, ts));
+    return true;
+  }
+  async close(reason = "completed", extra = {}) {
+    if (this.closed) return;
+    this.closed = true;
+    await this.emit("session.close", { reason, ...extra });
+    await this.flush();
+    this.deps.onClosed?.(this);
+  }
+  /** Read-your-writes: the platform must hold the evidence before anyone judges it (GAP-16/66). */
+  flush() {
+    return this.deps.transport.flush();
+  }
+  /** Serialized: two concurrent emits get consecutive seqs, never the same one. */
+  next(kind, payload, ts) {
+    const run = this.building.then(async () => {
+      const built = await this.chain.append({ ts, kind, payload }, this.deps.signer);
+      this.chain = built.chain;
+      return built.event;
+    });
+    this.building = run.catch(() => void 0);
+    return run;
+  }
+};
+var DEFAULT_OPEN_RETRY_MS = 6e4;
+var Sessions = class {
+  constructor(deps) {
+    this.deps = deps;
+  }
+  /**
+   * One session object per (session, source) per process: a chain's head
+   * lives in it, so two objects for the same chain would both start at
+   * seq 0 and fork it. Closed sessions are forgotten; a process restart
+   * mid-session still loses the head (GAP-67).
+   */
+  attached = /* @__PURE__ */ new Map();
+  /** Buyer sessions by the host's own key (GAP-71). */
+  opened = /* @__PURE__ */ new Map();
+  retryAt = 0;
+  /** The session behind a source: itself, or the one the run opens (null when the run has none). */
+  static resolve(source) {
+    return source instanceof Session ? Promise.resolve(source) : source.session();
+  }
+  /**
+   * Buyer half: the evidence session for a key of the host's own (its
+   * session, run or conversation id), opened on first use and reused
+   * after. A halted chain is reopened as a fresh session that continues
+   * the same key; a closed key is forgotten. When the platform cannot be
+   * reached, a fail-open client resolves null — the host runs without
+   * evidence — until `openRetryMs` has passed (GAP-71); otherwise, and
+   * whenever the platform refused, the error is thrown and the next call
+   * tries again. The identity is configuration: missing, it throws either
+   * way.
+   */
+  open(key, input = {}) {
+    const prior = this.opened.get(key) ?? Promise.resolve(null);
+    const next = prior.catch(() => null).then(
+      (session) => session && !session.isClosed && !this.deps.transport.haltedError(session.id, session.source) ? session : this.openFresh(input, () => this.forget(key, next))
+    );
+    this.opened.set(key, next);
+    next.catch(() => this.forget(key, next));
+    return next;
+  }
+  forget(key, entry) {
+    if (this.opened.get(key) === entry) this.opened.delete(key);
+  }
+  async openFresh(input, onClosed) {
+    const identity = this.identityFor("open");
+    const create = async () => this.create(identity, typeof input === "function" ? await input() : input, onClosed);
+    if (!this.deps.failOpen) return create();
+    if (Date.now() < this.retryAt) return null;
+    try {
+      const session = await create();
+      this.retryAt = 0;
+      return session;
+    } catch (err) {
+      if (!Transport.outage(err)) throw err;
+      this.retryAt = Date.now() + (this.deps.openRetryMs ?? DEFAULT_OPEN_RETRY_MS);
+      this.deps.onError?.(err);
+      return null;
+    }
+  }
+  /** Buyer half: create an AGENT_TRACE session bound to the agent identity, then announce it on the chain. */
+  async start(input = {}) {
+    return this.create(this.identityFor("start"), input);
+  }
+  identityFor(entry) {
+    const identity = this.deps.identity;
+    if (!identity)
+      throw new BelticConfigError(
+        `sessions.${entry} needs an agent identity (new Beltic({ identity }))`
+      );
+    return identity;
+  }
+  async create(identity, input, onClosed) {
+    const body = {
+      source: "AGENT_TRACE",
+      agent: { did: identity.did, credential: identity.credential ?? identity.did },
+      ...input.intent ? { intent: input.intent } : {}
+    };
+    const out = await this.deps.api.post("/v1/sessions", body);
+    const session = this.attach(out.sessionId, "AGENT_TRACE", out.expiresAt, "buyer", onClosed);
+    await session.emit("session.open", {
+      runtime: {
+        sdk: "@belticlabs/agent-risk-sdk",
+        version: this.deps.sdkVersion,
+        ...input.runtime
+      },
+      ...input.attestations ? { attestations: input.attestations } : {}
+    });
+    if (input.intent) await session.emit("intent.declared", input.intent);
+    return session;
+  }
+  /** Seller half: emit INTERNAL_NETWORK evidence into a session the buyer bound, or open a seller-born one. */
+  async ensure(sessionId) {
+    if (sessionId) return this.attach(sessionId, "INTERNAL_NETWORK", null, "buyer");
+    const out = await this.deps.api.post("/v1/sessions", {
+      source: "INTERNAL_NETWORK"
+    });
+    return this.attach(out.sessionId, "INTERNAL_NETWORK", out.expiresAt, "seller");
+  }
+  attach(id, source, expiresAt, born, onClosed) {
+    const key = `${id}:${source}`;
+    const existing = this.attached.get(key);
+    if (existing) return existing;
+    const session = new Session(
+      {
+        transport: this.deps.transport,
+        signer: source === "AGENT_TRACE" ? this.deps.identity?.signer : void 0,
+        failOpen: this.deps.failOpen,
+        onError: this.deps.onError,
+        onClosed: () => {
+          this.attached.delete(key);
+          onClosed?.();
+        }
+      },
+      id,
+      source,
+      expiresAt,
+      born
+    );
+    this.attached.set(key, session);
+    return session;
+  }
+};
+
+export {
+  BelticApiError,
+  ApiClient,
+  BelticConfigError,
+  recordCall,
+  ChainRejectedError,
+  Transport,
+  Session,
+  Sessions
+};

package/dist/index.d.ts

@@ -1,39 +1,17 @@
-import { a as Session } from './session-DsBWEP8d.js';
-export { A as AgentIdentity, b as ApiClient, c as ApiClientOptions, B as Beltic, d as BelticApiError, e as BelticOptions, C as ChainRejectedError, f as CorrelationStore, D as DEFAULT_OPEN_RETRY_MS, g as DEFAULT_TRANSPORT, h as DecideOptions, i as Decision, E as Env, j as Evaluation, H as HumanDecisionInput, M as MemoryCorrelationStore, O as OpenSessionInput, R as RedactFn, k as Run, l as RunOptions, m as SDK_VERSION, n as SessionBorn, S as SessionSource, o as Sessions, p as StartSessionInput, T as ToolCallSpan, q as Transport, r as TransportClosedError, s as TransportOptions, t as createBeltic, u as ephemeralIdentity, v as fileIdentity, w as identityFromSeed } from './session-DsBWEP8d.js';
-import { a as PaymentSummary, J as JsonObject, P as PaymentMomentPayload } from './verdict-6vCyoAHE.js';
+export { A as AgentIdentity, a as ApiClient, b as ApiClientOptions, B as Beltic, c as BelticApiError, d as BelticOptions, C as ChainRejectedError, D as DecideOptions, e as Decision, E as Env, f as Evaluation, F as FromEnvOptions, H as HumanDecisionInput, O as OpenSessionInput, R as Run, g as RunOptions, h as SDK_VERSION, i as Session, j as SessionBorn, S as SessionSource, k as Sessions, l as StartSessionInput, T as ToolCallSpan, m as Transport, n as TransportOptions, o as TransportTuning, p as identityFromSeed } from './session-D9E-efc0.js';
+import './verdict-DMnbFuS5.js';
 import 'zod';
 
 /**
- * Thrown by the two primitives that cannot fail open (`sessions.start`,
- * `sessions.ensure`) when the client is disabled: a `Beltic.fromEnv` with
- * no `BELTIC_*` configured is a client that records nothing (GAP-78), and
- * a caller that insists on a session gets told so rather than a `null`.
+ * A client that is not configured is a fault of the host, not a state the
+ * SDK runs in: an empty API key, a base URL that does not parse, a buyer
+ * entry with no agent identity, a `BELTIC_*` variable missing. Thrown at
+ * construction or at the first entry that needs the missing piece, and
+ * never absorbed by `failOpen` (GAP-78).
  */
-declare class BelticDisabledError extends Error {
-    readonly code = "SDK_DISABLED";
-    constructor(entry: string);
+declare class BelticConfigError extends Error {
+    readonly code = "CONFIG";
+    constructor(message: string);
 }
 
-/**
- * The shape the platform judges (`PaymentSummary`) and the shape the record
- * keeps (`PaymentMomentPayload`) share their comparable core: payee, amount,
- * payer. Every protocol adapter builds moments through here so the two
- * sides of one purchase compare (`EVIDENCE_MISMATCH`, GAP-50).
- */
-
-declare function summaryOf(m: PaymentSummary | PaymentMomentPayload): PaymentSummary;
-/** A presentation the seller side saw as a signed payment, in any protocol. */
-declare function presentedFrom(summary: PaymentSummary, raw: JsonObject): PaymentMomentPayload;
-
-/**
- * One instrumented call = a `*.start` event, the work, a `*.end` event
- * carrying the outcome or the error (GAP-07 correlates them by `callId`).
- * `openCall` is the span; `recordCall` runs the work inside one. The AI
- * middleware, the tool wrapper, the MCP client and a host's own tool loop
- * (`Session.toolCall`) all record the same way.
- */
-
-type CallKind = 'llm_call' | 'tool_call';
-declare function recordCall<T>(session: Session, kind: CallKind, callId: string, start: JsonObject, run: () => PromiseLike<T>, end?: (result: T) => Promise<JsonObject> | JsonObject): Promise<T>;
-
-export { BelticDisabledError, type CallKind, Session, presentedFrom, recordCall, summaryOf };
+export { BelticConfigError };