@belticlabs/agent-risk-sdk 0.1.0

package/dist/index.js

@@ -0,0 +1,499 @@
+import {
+  recordCall
+} from "./chunk-5TWO73OD.js";
+import {
+  Chain,
+  didKeyFromEd25519,
+  fromHex,
+  memorySigner,
+  toHex
+} from "./chunk-SFGM7KOG.js";
+import {
+  presentedFrom,
+  summaryOf
+} from "./chunk-7G5EHNVW.js";
+import "./chunk-GCKCAKHA.js";
+
+// src/core/api-client.ts
+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 and network failures are retried by the transport; 4xx are not. */
+  get retryable() {
+    return this.status === 0 || this.status >= 500 || this.status === 429;
+  }
+};
+var ApiClient = class {
+  baseUrl;
+  fetchImpl;
+  timeoutMs;
+  headers;
+  constructor(opts) {
+    this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
+    this.fetchImpl = opts.fetch ?? globalThis.fetch.bind(globalThis);
+    this.timeoutMs = opts.timeoutMs ?? 1e4;
+    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(), this.timeoutMs);
+    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/correlation.ts
+var MemoryCorrelationStore = class {
+  constructor(defaultTtlMs = 60 * 60 * 1e3) {
+    this.defaultTtlMs = defaultTtlMs;
+  }
+  entries = /* @__PURE__ */ new Map();
+  async bind(key, sessionId, ttlMs = this.defaultTtlMs) {
+    this.entries.set(key, { sessionId, expiresAt: Date.now() + ttlMs });
+  }
+  async resolve(key) {
+    const e = this.entries.get(key);
+    if (!e) return null;
+    if (e.expiresAt < Date.now()) {
+      this.entries.delete(key);
+      return null;
+    }
+    return e.sessionId;
+  }
+};
+
+// 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;
+  }
+  /** Resolves once the event is sequenced and buffered — not once it is acknowledged. */
+  async emit(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;
+    }
+    const body = payload;
+    this.deps.transport.enqueue(
+      await this.next(kind, this.deps.redact ? this.deps.redact(kind, body) : body, 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 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 half: create an AGENT_TRACE session bound to the agent identity, then announce it on the chain. */
+  async start(input = {}) {
+    const identity = this.deps.identity;
+    if (!identity)
+      throw new Error("sessions.start needs an agent identity (createBeltic({ identity }))");
+    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");
+    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) {
+    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,
+        redact: this.deps.redact,
+        now: this.deps.now,
+        onClosed: () => this.attached.delete(key)
+      },
+      id,
+      source,
+      expiresAt,
+      born
+    );
+    this.attached.set(key, session);
+    return session;
+  }
+};
+
+// src/core/transport.ts
+var DEFAULT_TRANSPORT = {
+  maxBatch: 50,
+  flushMs: 1e3,
+  maxBuffered: 5e3,
+  backoff: { baseMs: 200, maxMs: 3e4, maxAttempts: Number.POSITIVE_INFINITY }
+};
+var ChainRejectedError = class extends Error {
+  constructor(sessionId, source, result) {
+    super(
+      `chain ${sessionId}:${source} halted at seq ${result.seq}: ${result.status}${result.code ? ` ${result.code}` : ""}`
+    );
+    this.sessionId = sessionId;
+    this.source = source;
+    this.result = result;
+    this.name = "ChainRejectedError";
+  }
+};
+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_TRANSPORT,
+      ...opts,
+      backoff: { ...DEFAULT_TRANSPORT.backoff, ...opts.backoff }
+    };
+  }
+  opts;
+  chains = /* @__PURE__ */ new Map();
+  buffered = 0;
+  timer = null;
+  closed = false;
+  inFlightCount = 0;
+  drainWaiters = [];
+  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 >= this.opts.maxBatch) 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;
+    const st = this.opts.setTimeout ?? globalThis.setTimeout;
+    this.timer = st(() => {
+      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;
+    (this.opts.clearTimeout ?? globalThis.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, this.opts.maxBatch);
+    chain.inFlight = batch;
+    this.inFlightCount++;
+    try {
+      const ack = await this.send(chain, batch);
+      this.buffered -= batch.length;
+      this.opts.onAck?.(ack);
+      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"
+      });
+      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) => (this.opts.setTimeout ?? globalThis.setTimeout)(r, delay));
+      }
+    }
+  }
+};
+
+// src/client.ts
+var SDK_VERSION = "0.1.0";
+var Beltic = class {
+  api;
+  transport;
+  sessions;
+  identity;
+  correlation;
+  onReview;
+  constructor(opts) {
+    this.api = new ApiClient({ ...opts, userAgent: `@belticlabs/agent-risk-sdk/${SDK_VERSION}` });
+    this.transport = new Transport(this.api, opts.transport);
+    this.sessions = new Sessions({
+      api: this.api,
+      transport: this.transport,
+      sdkVersion: SDK_VERSION,
+      identity: opts.identity,
+      redact: opts.redact,
+      now: opts.now
+    });
+    this.identity = opts.identity;
+    this.correlation = opts.correlation ?? new MemoryCorrelationStore();
+    this.onReview = opts.onReview ?? "abort";
+  }
+  /** Read-your-writes: the platform must hold the evidence before it judges it (GAP-16). */
+  async evaluate(sessionId, payment) {
+    await this.transport.flush();
+    return this.api.post("/v1/evaluate", {
+      sessionId,
+      payment
+    });
+  }
+  flush() {
+    return this.transport.flush();
+  }
+  shutdown() {
+    return this.transport.close();
+  }
+};
+function createBeltic(opts) {
+  return new Beltic(opts);
+}
+
+// src/core/identity.ts
+import { mkdirSync, readFileSync, writeFileSync } from "fs";
+import { dirname } from "path";
+function identityFromSeed(seed, credential) {
+  const signer = memorySigner(seed);
+  const did = didKeyFromEd25519(signer.publicKey);
+  return { did, signer: { ...signer, keyId: did }, ...credential ? { credential } : {} };
+}
+function ephemeralIdentity(credential) {
+  return identityFromSeed(memorySigner().seed, credential);
+}
+function fileIdentity(path, credential) {
+  let seed;
+  try {
+    seed = fromHex(JSON.parse(readFileSync(path, "utf8")).seed);
+  } catch {
+    seed = memorySigner().seed;
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify({ seed: toHex(seed) })}
+`, { mode: 384 });
+  }
+  return identityFromSeed(seed, credential);
+}
+export {
+  ApiClient,
+  Beltic,
+  BelticApiError,
+  ChainRejectedError,
+  DEFAULT_TRANSPORT,
+  MemoryCorrelationStore,
+  SDK_VERSION,
+  Session,
+  Sessions,
+  Transport,
+  TransportClosedError,
+  createBeltic,
+  ephemeralIdentity,
+  fileIdentity,
+  identityFromSeed,
+  presentedFrom,
+  recordCall,
+  summaryOf
+};

package/dist/mcp/index.d.ts

@@ -0,0 +1,59 @@
+import { PaymentSummary, PaymentMomentPayload } from './api.js';
+import { B as Beltic } from '../client-CVx9LgJC.js';
+import { S as Session } from '../session-BMNB1N1g.js';
+import './base58.js';
+
+interface CallToolParams {
+    name: string;
+    arguments?: Record<string, unknown> | undefined;
+    _meta?: Record<string, unknown> | undefined;
+}
+/** Structural: `Client` from `@modelcontextprotocol/sdk/client` satisfies it. */
+interface McpClientLike {
+    callTool(params: CallToolParams, ...rest: unknown[]): Promise<unknown>;
+}
+declare function wrapClient<C extends McpClientLike>(session: Session, client: C, opts?: {
+    server?: string;
+}): C;
+/**
+ * An in-band payment ask: any object in the result carrying an x402-style
+ * `accepts` array (MRTR `input_required`, or a `_meta` envelope). One
+ * moment, two artifacts — either becomes the same `payment.requested`.
+ */
+declare function findPaymentAsk(result: unknown): PaymentMomentPayload | null;
+interface ServerCallExtra {
+    _meta?: Record<string, unknown> | undefined;
+    sessionId?: string | undefined;
+}
+interface WithBelticOptions<Args> {
+    toolName: string;
+    /** Return the payment this call moves, or null when the call is not value-moving. */
+    valueMoving?: (args: Args) => PaymentSummary | null;
+    gateway?: string;
+}
+type ToolHandler<Args, R> = (args: Args, extra: ServerCallExtra) => Promise<R> | R;
+interface McpErrorResult {
+    isError: true;
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+}
+/**
+ * Wraps a tool handler on the seller side. Value-moving calls are evaluated
+ * synchronously (DENY ⇒ isError result); every decided call is recorded
+ * as `gateway.decision` in the buyer's session, or a seller-born one.
+ */
+declare function withBeltic<Args, R>(beltic: Beltic, handler: ToolHandler<Args, R>, opts: WithBelticOptions<Args>): ToolHandler<Args, R | McpErrorResult>;
+/** Structural: `McpServer` from `@modelcontextprotocol/sdk/server/mcp` satisfies it. */
+interface McpServerLike {
+    registerTool(name: string, config: unknown, cb: (...a: never[]) => unknown): unknown;
+}
+interface WrapServerOptions {
+    valueMoving?: (toolName: string, args: unknown) => PaymentSummary | null;
+    gateway?: string;
+}
+/** Patches `registerTool` so every tool goes through `withBeltic`; `valueMoving` decides per tool. */
+declare function wrapServer<S extends McpServerLike>(beltic: Beltic, server: S, opts?: WrapServerOptions): S;
+
+export { type CallToolParams, type McpClientLike, type McpErrorResult, type McpServerLike, type ServerCallExtra, type ToolHandler, type WithBelticOptions, type WrapServerOptions, findPaymentAsk, withBeltic, wrapClient, wrapServer };

package/dist/mcp/index.js

@@ -0,0 +1,127 @@
+import {
+  recordCall
+} from "../chunk-5TWO73OD.js";
+import {
+  SESSION_EXTENSION
+} from "../chunk-VM7MK43J.js";
+import {
+  uuidv7
+} from "../chunk-SFGM7KOG.js";
+import {
+  x402Moments
+} from "../chunk-U5Z5Z2BQ.js";
+import {
+  presentedFrom
+} from "../chunk-7G5EHNVW.js";
+import {
+  toJson,
+  toJsonObject
+} from "../chunk-FQDHFTVR.js";
+import {
+  Verdict
+} from "../chunk-GCKCAKHA.js";
+
+// src/mcp/index.ts
+function wrapClient(session, client, opts = {}) {
+  const original = client.callTool.bind(client);
+  const callTool = (params, ...rest) => recordCall(
+    session,
+    "tool_call",
+    uuidv7(),
+    {
+      toolName: params.name,
+      input: toJson(params.arguments ?? {}),
+      transport: "mcp",
+      ...opts.server ? { server: opts.server } : {}
+    },
+    async () => {
+      await session.flush();
+      return original(
+        { ...params, _meta: { ...params._meta ?? {}, [SESSION_EXTENSION]: session.id } },
+        ...rest
+      );
+    },
+    async (result) => {
+      const ask = findPaymentAsk(result);
+      if (ask) await session.emit("payment.requested", ask);
+      return { output: toJson(result) };
+    }
+  );
+  return new Proxy(client, {
+    get(target, prop, receiver) {
+      return prop === "callTool" ? callTool : Reflect.get(target, prop, receiver);
+    }
+  });
+}
+function findPaymentAsk(result) {
+  const seen = /* @__PURE__ */ new Set();
+  const walk = (v, depth) => {
+    if (!v || typeof v !== "object" || seen.has(v) || depth > 6) return null;
+    seen.add(v);
+    const o = v;
+    const first = Array.isArray(o.accepts) ? o.accepts[0] : void 0;
+    if (typeof first?.payTo === "string") {
+      return x402Moments.ask(first, toJsonObject(o));
+    }
+    for (const child of Array.isArray(o) ? o : Object.values(o)) {
+      const hit = walk(child, depth + 1);
+      if (hit) return hit;
+    }
+    return null;
+  };
+  return walk(result, 0);
+}
+function withBeltic(beltic, handler, opts) {
+  const gateway = opts.gateway ?? "sdk-mcp";
+  return async (args, extra) => {
+    const bound = extra?._meta?.[SESSION_EXTENSION];
+    const session = await beltic.sessions.ensure(typeof bound === "string" ? bound : null);
+    const payment = opts.valueMoving?.(args) ?? null;
+    let verdict = Verdict.ALLOW;
+    let reasonCodes = [];
+    if (payment) {
+      await session.emit(
+        "payment.presented",
+        presentedFrom(payment, { tool: opts.toolName, args: toJson(args) })
+      );
+      const out = await beltic.evaluate(session.id, payment);
+      verdict = Verdict.of(out.decision);
+      reasonCodes = out.reasonCodes;
+    }
+    await session.emit("gateway.decision", {
+      gateway,
+      call: { tool: opts.toolName, args: toJson(args) },
+      decision: verdict.effective(beltic.onReview),
+      reasonCodes,
+      record: { valueMoving: payment !== null, bound: typeof bound === "string" }
+    });
+    if (verdict.blocks(beltic.onReview)) {
+      return {
+        isError: true,
+        content: [
+          { type: "text", text: `Beltic ${verdict.value}: ${reasonCodes.join(",") || "denied"}` }
+        ]
+      };
+    }
+    return handler(args, extra);
+  };
+}
+function wrapServer(beltic, server, opts = {}) {
+  const original = server.registerTool.bind(server);
+  server.registerTool = ((name, config, cb) => original(
+    name,
+    config,
+    withBeltic(beltic, cb, {
+      toolName: name,
+      ...opts.gateway ? { gateway: opts.gateway } : {},
+      valueMoving: (args) => opts.valueMoving?.(name, args) ?? null
+    })
+  ));
+  return server;
+}
+export {
+  findPaymentAsk,
+  withBeltic,
+  wrapClient,
+  wrapServer
+};