@belticlabs/agent-risk-sdk 0.2.0 → 0.3.0

package/dist/index.js

@@ -1,14 +1,19 @@
 import {
-  openCall,
+  BelticDisabledError,
+  DEFAULT_OPEN_RETRY_MS,
+  Session,
+  Sessions,
   recordCall
-} from "./chunk-GSH5APZW.js";
+} from "./chunk-4MG6VNAU.js";
 import {
-  Chain,
+  canonicalBytes,
+  canonicalize,
   didKeyFromEd25519,
   fromHex,
   memorySigner,
+  sha256,
   toHex
-} from "./chunk-SFGM7KOG.js";
+} from "./chunk-X3W2Z5GC.js";
 import {
   Verdict
 } from "./chunk-46QN2KEZ.js";
@@ -115,212 +120,256 @@ var MemoryCorrelationStore = class {
   }
 };
 
-// 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;
+// 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 });
   }
-  get droppedCount() {
-    return this.dropped;
+  return identityFromSeed(seed, credential);
+}
+
+// src/core/decision.ts
+var Decision = class _Decision {
+  constructor(evaluation) {
+    this.evaluation = evaluation;
   }
-  /**
-   * 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 can no longer take it.
-   */
-  async emit(kind, payload) {
-    if (!this.deps.failOpen) return this.chainEvent(kind, payload);
-    try {
-      return await this.chainEvent(kind, payload);
-    } catch (err) {
-      this.deps.onError?.(err);
-      return false;
-    }
+  static ABSENT = new _Decision(null);
+  static of(evaluation) {
+    return new _Decision(evaluation);
   }
-  /** 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;
-    }
-    const body = payload;
-    this.deps.transport.enqueue(
-      await this.next(kind, this.deps.redact ? this.deps.redact(kind, body) : body, ts)
-    );
-    return true;
+  static absent() {
+    return _Decision.ABSENT;
   }
-  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);
+  get value() {
+    return this.evaluation?.decision ?? null;
   }
-  /** 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;
+  get reasonCodes() {
+    return this.evaluation?.reasonCodes ?? [];
+  }
+  get decisionId() {
+    return this.evaluation?.decisionId ?? null;
+  }
+  get allowed() {
+    return this.value === "ALLOW";
+  }
+  get denied() {
+    return this.value === "DENY";
+  }
+  get review() {
+    return this.value === "REVIEW";
+  }
+  get absent() {
+    return this.evaluation === null;
+  }
+  /** Whether a gate must stop the payment (GAP-52); an absent verdict never blocks. */
+  blocks(onReview) {
+    return this.evaluation ? Verdict.of(this.evaluation.decision).blocks(onReview) : false;
+  }
+  /** One sentence for the agent or the person: what Beltic said and why. */
+  explain() {
+    if (!this.evaluation) return "Beltic could not be asked about this payment.";
+    const verb = this.denied ? "denied" : this.review ? "asked for review of" : "allowed";
+    const why = this.reasonCodes.length > 0 ? ` (${this.reasonCodes.join(", ")})` : "";
+    return `Beltic ${verb} this payment${why}.`;
+  }
+};
+
+// src/core/run.ts
+var MEMORY = 256;
+var Memory = class {
+  map = /* @__PURE__ */ new Map();
+  get(key) {
+    return this.map.get(key);
+  }
+  set(key, value) {
+    this.map.delete(key);
+    this.map.set(key, value);
+    if (this.map.size > MEMORY) this.map.delete(this.map.keys().next().value);
   }
 };
-var DEFAULT_OPEN_RETRY_MS = 6e4;
-var Sessions = class {
-  constructor(deps) {
+var Run = class _Run {
+  constructor(deps, key, opts = {}) {
     this.deps = deps;
+    this.key = key;
+    this.opts = opts;
+  }
+  opened = null;
+  current = null;
+  /** JCS hash of the mandate on the chain, and of the one the open input carried. */
+  declared = null;
+  openedWith = null;
+  closed = false;
+  timer = null;
+  calls = new Memory();
+  decisions = new Memory();
+  byPayment = new Memory();
+  /** The session this run records into — opened on first use, `null` when there is none. */
+  session() {
+    const next = this.deps.sessions.open(this.key, this.opener);
+    this.opened = next;
+    return next.then((session) => {
+      if (session !== this.current) {
+        this.current = session;
+        this.declared = this.openedWith;
+      }
+      return session;
+    });
+  }
+  opener = async () => {
+    const open = this.opts.open;
+    const input = typeof open === "function" ? await open() : open ?? {};
+    this.openedWith = input.intent ? _Run.hash(input.intent) : null;
+    return input;
+  };
+  /** `intent.declared`, unless the mandate is the one already on the chain. */
+  async declare(intent) {
+    const session = await this.session();
+    if (!session) return false;
+    const hash = _Run.hash(intent);
+    if (hash === this.declared) return false;
+    const ok = await session.emit("intent.declared", intent);
+    if (ok) this.declared = hash;
+    this.touch();
+    return ok;
   }
   /**
-   * 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).
+   * The platform's verdict on a payment about to be presented. Asked once
+   * per call id: a host that re-runs its approval step reads the same
+   * `Decision`. An absent verdict is not memoized, so the next attempt
+   * asks again.
    */
-  attached = /* @__PURE__ */ new Map();
-  /** Buyer sessions by the host's own key (GAP-71). */
-  opened = /* @__PURE__ */ new Map();
-  retryAt = 0;
+  async decide(payment, opts = {}) {
+    const known = opts.callId ? this.decisions.get(opts.callId) : void 0;
+    if (known) return known;
+    const session = await this.session();
+    if (!session) return Decision.absent();
+    if (opts.intent) await this.declare(opts.intent);
+    const summary = summaryOf(payment);
+    const evaluation = await this.deps.evaluate(session.id, summary);
+    if (!evaluation) return Decision.absent();
+    const decision = Decision.of(evaluation);
+    if (opts.callId) this.decisions.set(opts.callId, decision);
+    for (const key of _Run.paymentKeys(summary)) this.byPayment.set(key, decision);
+    const call = opts.callId ? this.calls.get(opts.callId)?.call : void 0;
+    await session.emit("gateway.decision", {
+      gateway: "beltic",
+      call: _Run.callOf(call),
+      decision: evaluation.decision,
+      reasonCodes: [...evaluation.reasonCodes],
+      record: {
+        decisionId: evaluation.decisionId,
+        callId: opts.callId ?? null,
+        payment: summary
+      }
+    });
+    this.touch();
+    return decision;
+  }
+  /** The decision given for a call id, or absent. */
+  decision(callId) {
+    return this.decisions.get(callId) ?? Decision.absent();
+  }
   /**
-   * 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 refuses to
-   * open one, a fail-open client resolves null — the host runs without
-   * evidence — until `openRetryMs` has passed (GAP-71); otherwise the
-   * refusal is thrown and the next call tries again. The identity is
-   * required either way: that is configuration.
+   * The decision given for a payment with the same comparable core (payee,
+   * amount, payer — or payee and amount when one side names no payer), or
+   * absent.
    */
-  open(key, input = {}) {
-    const prior = this.opened.get(key) ?? Promise.resolve(null);
-    const next = prior.catch(() => null).then(
-      (session) => session && !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) {
-    this.identityFor("open");
-    const create = async () => this.create(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) {
-      this.retryAt = Date.now() + (this.deps.openRetryMs ?? DEFAULT_OPEN_RETRY_MS);
-      this.deps.onError?.(err);
-      return null;
+  decisionFor(payment) {
+    for (const key of _Run.paymentKeys(summaryOf(payment))) {
+      const known = this.byPayment.get(key);
+      if (known) return known;
     }
-  }
-  /** Buyer half: create an AGENT_TRACE session bound to the agent identity, then announce it on the chain. */
-  start(input = {}) {
-    return this.create(input);
-  }
-  identityFor(entry) {
-    const identity = this.deps.identity;
-    if (!identity)
-      throw new Error(`sessions.${entry} needs an agent identity (createBeltic({ identity }))`);
-    return identity;
-  }
-  async create(input, onClosed) {
-    const identity = this.identityFor("start");
-    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 Decision.absent();
+  }
+  /** A tool call the host runs itself, reported as two events by its own call id. */
+  tools = {
+    start: async (call) => {
+      const session = await this.session();
+      if (!session) return false;
+      const span = session.toolCall(call);
+      this.calls.set(call.callId, { call, span });
+      this.touch();
+      return span.opened;
+    },
+    end: async (callId, outcome) => {
+      const span = this.take(callId);
+      if (!span) return false;
+      this.touch();
+      return span.end(outcome);
+    },
+    fail: async (callId, error, outcome) => {
+      const span = this.take(callId);
+      if (!span) return false;
+      this.touch();
+      return span.fail(error, outcome);
+    }
+  };
+  /** A person's answer about a call, as the decision it was (GAP-75). */
+  async humanDecided(callId, input) {
+    const session = await this.session();
+    if (!session) return false;
+    const ok = await session.emit("gateway.decision", {
+      gateway: "human",
+      call: _Run.callOf(this.calls.get(callId)?.call),
+      decision: input.allowed ? "ALLOW" : "DENY",
+      reasonCodes: [`USER_${input.outcome.toUpperCase().replace(/[^A-Z0-9]+/g, "_")}`],
+      record: {
+        callId,
+        outcome: input.outcome,
+        responder: input.responder ?? null,
+        ...input.record ?? {}
+      }
     });
-    return this.attach(out.sessionId, "INTERNAL_NETWORK", out.expiresAt, "seller");
+    this.touch();
+    return ok;
   }
-  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,
-        redact: this.deps.redact,
-        now: this.deps.now,
-        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;
+  async close(reason = "completed") {
+    if (this.closed) return;
+    this.closed = true;
+    if (this.timer) clearTimeout(this.timer);
+    this.deps.onClosed(this);
+    const session = this.opened ? await this.opened.catch(() => null) : null;
+    await session?.close(reason);
+  }
+  take(callId) {
+    const known = this.calls.get(callId);
+    if (!known?.span) return null;
+    const { span } = known;
+    known.span = null;
+    return span;
+  }
+  touch() {
+    if (!this.opts.idleMs || this.closed) return;
+    if (this.timer) clearTimeout(this.timer);
+    this.timer = setTimeout(() => void this.close("expired"), this.opts.idleMs);
+    this.timer.unref?.();
+  }
+  static hash(intent) {
+    return toHex(sha256(canonicalBytes(intent)));
+  }
+  /** With the payer first, then without it. */
+  static paymentKeys(summary) {
+    const { payer, ...core } = summary;
+    return payer ? [canonicalize(summary), canonicalize(core)] : [canonicalize(core)];
+  }
+  static callOf(call) {
+    return call ? { tool: call.toolName, args: call.input } : { tool: "unknown" };
   }
 };
 
@@ -486,8 +535,10 @@ var Transport = class {
 };
 
 // src/client.ts
-var SDK_VERSION = "0.2.0";
-var Beltic = class {
+var SDK_VERSION = "0.3.0";
+var ENV_REQUIRED = ["BELTIC_API_KEY", "BELTIC_BASE_URL", "BELTIC_AGENT_SEED"];
+var ENV_CREDENTIAL = "BELTIC_AGENT_CREDENTIAL";
+var Beltic = class _Beltic {
   api;
   transport;
   sessions;
@@ -495,8 +546,43 @@ var Beltic = class {
   correlation;
   onReview;
   failOpen;
+  /** `false` for a disabled client (GAP-78): nothing is posted, `run`/`sessions.open` answer without a session. */
+  enabled;
   onError;
+  runs = /* @__PURE__ */ new Map();
+  /**
+   * The client the environment describes: `BELTIC_API_KEY`,
+   * `BELTIC_BASE_URL`, `BELTIC_AGENT_SEED` (64 hex) and optionally
+   * `BELTIC_AGENT_CREDENTIAL`, fail-open by default. None set → a disabled
+   * client; some set → a configuration error, thrown (GAP-78).
+   */
+  static fromEnv(env = _Beltic.processEnv(), opts = {}) {
+    const missing = ENV_REQUIRED.filter((name) => !env[name]);
+    if (missing.length === ENV_REQUIRED.length) return _Beltic.disabled(opts);
+    if (missing.length > 0)
+      throw new Error(
+        `Beltic.fromEnv: ${missing.join(", ")} missing \u2014 set all of ${ENV_REQUIRED.join(", ")}, or none to disable`
+      );
+    return new _Beltic({
+      failOpen: true,
+      ...opts,
+      apiKey: env.BELTIC_API_KEY,
+      baseUrl: env.BELTIC_BASE_URL,
+      identity: identityFromSeed(fromHex(env.BELTIC_AGENT_SEED), env[ENV_CREDENTIAL])
+    });
+  }
+  /** A client that records nothing and never throws into the work: the null object for "no evidence stream" (GAP-78). */
+  static disabled(opts = {}) {
+    return new _Beltic({
+      ...opts,
+      apiKey: "",
+      baseUrl: "http://beltic.disabled.invalid",
+      failOpen: true,
+      enabled: false
+    });
+  }
   constructor(opts) {
+    this.enabled = opts.enabled ?? true;
     this.failOpen = opts.failOpen ?? false;
     this.onError = opts.onError ?? ((err) => console.error("[beltic]", err));
     this.api = new ApiClient({ ...opts, userAgent: `@belticlabs/agent-risk-sdk/${SDK_VERSION}` });
@@ -514,7 +600,8 @@ var Beltic = class {
       now: opts.now,
       failOpen: this.failOpen,
       onError: this.onError,
-      openRetryMs: opts.openRetryMs
+      openRetryMs: opts.openRetryMs,
+      enabled: this.enabled
     });
     this.identity = opts.identity;
     this.correlation = opts.correlation ?? new MemoryCorrelationStore();
@@ -529,6 +616,7 @@ var Beltic = class {
    * platform could not be asked.
    */
   async evaluate(sessionId, payment) {
+    if (!this.enabled) return null;
     const input = { sessionId, payment: summaryOf(payment) };
     if (!this.failOpen) return this.decide(input);
     try {
@@ -543,48 +631,52 @@ var Beltic = class {
     const out = await this.api.post("/v1/evaluate", input);
     return { ...out, verdict: Verdict.of(out.decision) };
   }
+  /**
+   * The run for a key of the host's own — one object per key until it
+   * closes (the options count on the first call only). See `Run`.
+   */
+  run(key, opts = {}) {
+    const existing = this.runs.get(key);
+    if (existing) return existing;
+    const run = new Run(
+      {
+        sessions: this.sessions,
+        evaluate: (sessionId, payment) => this.evaluate(sessionId, payment),
+        onClosed: (closed) => {
+          if (this.runs.get(key) === closed) this.runs.delete(key);
+        }
+      },
+      key,
+      opts
+    );
+    this.runs.set(key, run);
+    return run;
+  }
   flush() {
     return this.transport.flush();
   }
   shutdown() {
     return this.transport.close();
   }
+  /** `process.env` where there is a `process` (Node); `{}` on workerd, where the shell passes its `env`. */
+  static processEnv() {
+    return globalThis.process?.env ?? {};
+  }
 };
 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,
+  BelticDisabledError,
   ChainRejectedError,
   DEFAULT_OPEN_RETRY_MS,
   DEFAULT_TRANSPORT,
+  Decision,
   MemoryCorrelationStore,
+  Run,
   SDK_VERSION,
   Session,
   Sessions,

package/dist/mcp/index.d.ts

@@ -1,8 +1,6 @@
-import { a as PaymentSummary, P as PaymentMomentPayload } from '../index-Bjs3BPPU.js';
-import { B as Beltic } from '../client-C-mV_3A0.js';
-import { S as Session } from '../session-5TClPLI4.js';
+import { a as PaymentSummary, P as PaymentMomentPayload } from '../verdict-6vCyoAHE.js';
+import { B as Beltic, S as SessionSource } from '../session-DsBWEP8d.js';
 import 'zod';
-import '../verdict-BAahb5po.js';
 
 interface CallToolParams {
     name: string;
@@ -13,7 +11,7 @@ interface CallToolParams {
 interface McpClientLike {
     callTool(params: CallToolParams, ...rest: unknown[]): Promise<unknown>;
 }
-declare function wrapClient<C extends McpClientLike>(session: Session | null | undefined, client: C, opts?: {
+declare function wrapClient<C extends McpClientLike>(source: SessionSource, client: C, opts?: {
     server?: string;
 }): C;
 /**