@belticlabs/agent-risk-sdk 0.4.0 → 0.6.0

package/dist/session-gK51QVAM.d.ts

@@ -1,484 +0,0 @@
-import { G as EvidenceAck, y as EventResult, M as EvidenceEvent, w as EvaluateOutput, ax as Verdict, a4 as OnReview, a as PaymentSummary, P as PaymentMomentPayload, D as Decision$1, r as DeclaredIntent, at as ToolCallStartPayload, b as JsonValue, J as JsonObject, aj as SessionClosePayload, R as EvidenceSource, aA as WireEvidenceKind, C as ChainHead, a7 as PayloadByKind } from './verdict-CDAsxktI.js';
-
-/**
- * The edge signs event digests (Fraud SDK RFC › Modules › Identity Module);
- * the platform signs its own PLATFORM chain. Both are the same operation
- * over different keys, so one interface.
- */
-interface Signer {
-    /** Raw 32-byte Ed25519 public key. */
-    readonly publicKey: Uint8Array;
-    /** Stable identifier for logs and key rotation; `did:key` for agents. */
-    readonly keyId: string;
-    sign(message: Uint8Array): Promise<Uint8Array>;
-}
-
-interface ApiClientOptions {
-    baseUrl: string;
-    apiKey: string;
-    fetch?: typeof globalThis.fetch;
-    timeoutMs?: number;
-    userAgent?: string;
-}
-declare class BelticApiError extends Error {
-    readonly status: number;
-    readonly code: string;
-    readonly details?: unknown | undefined;
-    readonly requestId?: string | undefined;
-    constructor(status: number, code: string, message: string, details?: unknown | undefined, requestId?: string | undefined);
-    /** 5xx and network failures are retried by the transport; 4xx are not. */
-    get retryable(): boolean;
-}
-declare class ApiClient {
-    private readonly baseUrl;
-    private readonly fetchImpl;
-    private readonly timeoutMs;
-    private readonly headers;
-    constructor(opts: ApiClientOptions);
-    post<T>(path: string, body: unknown, headers?: Record<string, string>): Promise<T>;
-    get<T>(path: string, query?: Record<string, string | undefined>): Promise<T>;
-    private request;
-}
-
-interface AgentIdentity {
-    did: string;
-    signer: Signer;
-    /** Opaque credential presented at session start (stored, not verified this phase). */
-    credential?: string;
-}
-declare function identityFromSeed(seed: Uint8Array, credential?: string): AgentIdentity;
-declare function ephemeralIdentity(credential?: string): AgentIdentity;
-/** A JSON keystore on disk: `{ "seed": "<64 hex>" }`, created 0600 when missing. */
-declare function fileIdentity(path: string, credential?: string): AgentIdentity;
-
-/**
- * Correlation without binding (Fraud SDK RFC › Protocol Adapter — x402:
- * "binding travels on the call that initiates the purchase, not
- * necessarily on the payment artifact"). The merchant binds a key it will
- * see again (a checkout session id, a challenge nonce) to the buyer's
- * session; the adapter resolves it when the settlement arrives (GAP-31).
- */
-interface CorrelationStore {
-    bind(key: string, sessionId: string, ttlMs?: number): Promise<void>;
-    resolve(key: string): Promise<string | null>;
-}
-declare class MemoryCorrelationStore implements CorrelationStore {
-    private readonly defaultTtlMs;
-    private readonly entries;
-    constructor(defaultTtlMs?: number);
-    bind(key: string, sessionId: string, ttlMs?: number): Promise<void>;
-    resolve(key: string): Promise<string | null>;
-}
-
-/**
- * Transport (Fraud SDK RFC › Modules: "buffering, batching, chained delivery
- * to the Collector"). Contract as assumed in GAP-18/38: one FIFO per
- * chain; at most one batch in flight per chain, so order is preserved;
- * exponential backoff on network / 5xx; a `fork` or `rejected` ack halts
- * the chain and surfaces `ChainRejectedError` — an SDK must not silently
- * keep chaining onto a head the platform never accepted.
- */
-
-interface TransportOptions {
-    maxBatch: number;
-    flushMs: number;
-    /** Total buffered events across chains; beyond this new events are dropped (GAP-38). */
-    maxBuffered: number;
-    backoff: {
-        baseMs: number;
-        maxMs: number;
-        maxAttempts: number;
-    };
-    onAck?: (ack: EvidenceAck) => void;
-    onError?: (err: Error) => void;
-    onChainHalted?: (err: ChainRejectedError) => void;
-    setTimeout?: typeof globalThis.setTimeout;
-    clearTimeout?: typeof globalThis.clearTimeout;
-}
-declare const DEFAULT_TRANSPORT: TransportOptions;
-declare class ChainRejectedError extends Error {
-    readonly sessionId: string;
-    readonly source: string;
-    readonly result: EventResult;
-    constructor(sessionId: string, source: string, result: EventResult);
-}
-declare class TransportClosedError extends Error {
-    constructor();
-}
-declare class Transport {
-    private readonly api;
-    private readonly opts;
-    private readonly chains;
-    private buffered;
-    private timer;
-    private closed;
-    private inFlightCount;
-    private drainWaiters;
-    constructor(api: ApiClient, opts?: Partial<TransportOptions>);
-    get size(): number;
-    hasRoom(): boolean;
-    haltedError(sessionId: string, source: string): ChainRejectedError | null;
-    /** Callers check `hasRoom()` first and assign `seq` only then (GAP-38). */
-    enqueue(ev: EvidenceEvent): void;
-    /** Send everything pending and wait for every in-flight batch to settle (ack or halt). */
-    flush(): Promise<void>;
-    close(): Promise<void>;
-    private schedule;
-    private unschedule;
-    private drained;
-    private settleWaiters;
-    private flushChain;
-    private send;
-}
-
-/**
- * One SDK, two halves (Fraud SDK RFC › Summary). `Beltic` is the single
- * client: sessions and evidence for both halves, `evaluate` for whichever
- * half is about to let a payment through. Protocol integrations are plain
- * functions behind subpath exports, each pulling exactly one optional peer:
- *
- *   @belticlabs/agent-risk-sdk/ai    → middleware(session), wrapTools(session, …)
- *   @belticlabs/agent-risk-sdk/x402  → belticFetch(session), x402Summary(…), attachX402(beltic, …)
- *   @belticlabs/agent-risk-sdk/hono  → belticPaymentMiddleware(beltic, …)
- *
- * Neither half decides risk locally: verdicts are platform-side.
- *
- * A host that runs its own agent loop takes `beltic.run(key)` — a `Run`
- * keyed by its own session id that owns spans, verdicts and the mandate
- * (GAP-79); every integration above accepts a `Run` where it accepts a
- * `Session`. `Beltic.fromEnv()` reads `BELTIC_*` and, when none is set,
- * answers a disabled client that records nothing and never throws into
- * the work (GAP-78), so a host wires Beltic unconditionally.
- *
- * Evidence is a side channel of the work it observes. With `failOpen`
- * nothing the SDK does throws into that work: `Session.emit` reports and
- * answers `false`, `sessions.open` answers `null`, `evaluate` answers
- * `null` — never an invented verdict; the host decides what to do without
- * one (GAP-70). `sessions.start` and `sessions.ensure` throw either way:
- * they are the primitives the fail-open entries are built on.
- */
-
-declare const SDK_VERSION = "0.4.0";
-type Env = Record<string, string | undefined>;
-interface BelticOptions extends Omit<ApiClientOptions, 'userAgent'> {
-    /** Buyer half. Without it, `sessions.start` is unavailable; the seller half works. */
-    identity?: AgentIdentity | undefined;
-    transport?: Partial<TransportOptions> | undefined;
-    /** What a synchronous seller hook does with REVIEW (GAP-52). */
-    onReview?: OnReview | undefined;
-    correlation?: CorrelationStore | undefined;
-    redact?: RedactFn | undefined;
-    now?: (() => Date) | undefined;
-    /** Evidence never fails the work it observes; see the module note (GAP-70). */
-    failOpen?: boolean | undefined;
-    /** Where fail-open failures go (and transport delivery failures unless `transport` names its own). Default: `console.error`. */
-    onError?: ((err: Error) => void) | undefined;
-    /** Fail-open only: how long `sessions.open` answers null after the platform refused to open a session (GAP-71). */
-    openRetryMs?: number | undefined;
-    /** `false` is what `Beltic.disabled()` sets: no platform is ever called (GAP-78). */
-    enabled?: boolean | undefined;
-}
-/** The platform's answer, with the verdict as a value the caller can ask `blocks(onReview)`. */
-type Evaluation = EvaluateOutput & {
-    verdict: Verdict;
-};
-declare class Beltic {
-    readonly api: ApiClient;
-    readonly transport: Transport;
-    readonly sessions: Sessions;
-    readonly identity: AgentIdentity | undefined;
-    readonly correlation: CorrelationStore;
-    readonly onReview: OnReview;
-    readonly failOpen: boolean;
-    /** `false` for a disabled client (GAP-78): nothing is posted, `run`/`sessions.open` answer without a session. */
-    readonly enabled: boolean;
-    private readonly onError;
-    private readonly runs;
-    /**
-     * 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?: Env, opts?: Partial<BelticOptions>): Beltic;
-    /** A client that records nothing and never throws into the work: the null object for "no evidence stream" (GAP-78). */
-    static disabled(opts?: Partial<BelticOptions>): Beltic;
-    constructor(opts: BelticOptions);
-    /**
-     * The platform's verdict on a payment — the seller's before it verifies,
-     * the buyer's before it presents. Read-your-writes: the buffered evidence
-     * is flushed first so the platform judges what the caller already saw
-     * (GAP-16). A recorded moment is accepted as is: only its comparable core
-     * (payee, amount, payer) is sent. `null` only under `failOpen`, when the
-     * platform could not be asked.
-     */
-    evaluate(sessionId: string, payment: PaymentSummary | PaymentMomentPayload): Promise<Evaluation | null>;
-    private decide;
-    /**
-     * 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: string, opts?: RunOptions): Run;
-    flush(): Promise<void>;
-    shutdown(): Promise<void>;
-    /** `process.env` where there is a `process` (Node); `{}` on workerd, where the shell passes its `env`. */
-    private static processEnv;
-}
-declare function createBeltic(opts: BelticOptions): Beltic;
-
-/**
- * The platform's verdict on one payment as a value the host can ask
- * questions of (Fraud Engine RFC › API: ALLOW | DENY | REVIEW). `absent`
- * is the fail-open case: the platform could not be asked (GAP-70), and no
- * verdict was invented — the host decides what to do without one. A
- * `Run` memoizes decisions by the host's call id, so a re-run approval
- * reads the verdict already given (GAP-79).
- */
-
-declare class Decision {
-    readonly evaluation: Evaluation | null;
-    private static readonly ABSENT;
-    private constructor();
-    static of(evaluation: Evaluation): Decision;
-    static absent(): Decision;
-    get value(): Decision$1 | null;
-    get reasonCodes(): readonly string[];
-    get decisionId(): string | null;
-    get allowed(): boolean;
-    get denied(): boolean;
-    get review(): boolean;
-    get absent(): boolean;
-    /** Whether a gate must stop the payment (GAP-52); an absent verdict never blocks. */
-    blocks(onReview: OnReview): boolean;
-    /** One sentence for the agent or the person: what Beltic said and why. */
-    explain(): string;
-}
-
-interface RunOptions {
-    /** What `sessions.open` sends when this run actually opens a session. */
-    open?: OpenSessionInput | undefined;
-    /** Close the session (`expired`) after this long without evidence; unset = only the host closes. */
-    idleMs?: number | undefined;
-}
-interface HumanDecisionInput {
-    /** Whether the person let the call proceed. */
-    allowed: boolean;
-    /** The host's own word for what happened: `approved`, `answered`, `rejected`, `cancelled`… */
-    outcome: string;
-    responder?: string | undefined;
-    /** The host's record of what was asked and chosen — a black box to the platform (GAP-75). */
-    record?: JsonObject | undefined;
-}
-interface DecideOptions {
-    /** The host's id for the call the verdict applies to: memoizes the decision and links it to the span. */
-    callId?: string | undefined;
-    /** The mandate as of now; declared first when it differs from the last one. */
-    intent?: DeclaredIntent | undefined;
-}
-interface RunDeps {
-    sessions: Sessions;
-    evaluate: (sessionId: string, payment: PaymentSummary | PaymentMomentPayload) => Promise<Evaluation | null>;
-    /** Called once the run closed, so the registry forgets it. */
-    onClosed: (run: Run) => void;
-}
-declare class Run {
-    private readonly deps;
-    readonly key: string;
-    private readonly opts;
-    private opened;
-    private current;
-    /** JCS hash of the mandate on the chain, and of the one the open input carried. */
-    private declared;
-    private openedWith;
-    private closed;
-    private timer;
-    private readonly calls;
-    private readonly decisions;
-    private readonly byPayment;
-    constructor(deps: RunDeps, key: string, opts?: RunOptions);
-    /** The session this run records into — opened on first use, `null` when there is none. */
-    session(): Promise<Session | null>;
-    private readonly opener;
-    /** `intent.declared`, unless the mandate is the one already on the chain. */
-    declare(intent: DeclaredIntent): Promise<boolean>;
-    /**
-     * 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.
-     */
-    decide(payment: PaymentSummary | PaymentMomentPayload, opts?: DecideOptions): Promise<Decision>;
-    /** The decision given for a call id, or absent. */
-    decision(callId: string): Decision;
-    /**
-     * 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.
-     */
-    decisionFor(payment: PaymentSummary | PaymentMomentPayload): Decision;
-    /** A tool call the host runs itself, reported as two events by its own call id. */
-    readonly tools: {
-        start: (call: ToolCallStartPayload) => Promise<boolean>;
-        end: (callId: string, outcome?: {
-            output?: JsonValue;
-        }) => Promise<boolean>;
-        fail: (callId: string, error: unknown, outcome?: {
-            output?: JsonValue;
-        }) => Promise<boolean>;
-    };
-    /** A person's answer about a call, as the decision it was (GAP-75). */
-    humanDecided(callId: string, input: HumanDecisionInput): Promise<boolean>;
-    close(reason?: SessionClosePayload['reason']): Promise<void>;
-    private take;
-    private touch;
-    private static hash;
-    /** With the payer first, then without it. */
-    private static paymentKeys;
-    private static callOf;
-}
-
-/**
- * A risk session as the SDK sees it: one chain per (sessionId, source),
- * built at the edge (Fraud SDK RFC › Wire contract). The buyer half opens
- * AGENT_TRACE sessions and announces them with `session.open` (seq 0) and
- * `intent.declared` (seq 1; GAP-23/60); the seller half attaches to a bound
- * session or opens its own INTERNAL_NETWORK session (GAP-13).
- *
- * `seq` is handed out only when the transport has room for the event
- * (GAP-38): a dropped event never leaves a hole — the next accepted event
- * is preceded by a `transport.gap` that counts the drops. `redact` is off
- * by default (GAP-33).
- *
- * Evidence is a side channel of the agent's work: with `failOpen` an emit
- * that cannot be chained (halted chain, closed transport) is reported and
- * returns `false` instead of throwing into the model or tool call it
- * observes (GAP-70).
- */
-
-type RedactFn = (kind: WireEvidenceKind, payload: JsonObject) => JsonObject;
-/** Who created the session — the seller half treats a bound session as buyer-born. */
-type SessionBorn = 'buyer' | 'seller';
-interface SessionDeps {
-    transport: Transport;
-    signer?: Signer | undefined;
-    redact?: RedactFn | undefined;
-    now?: (() => Date) | undefined;
-    /** Called once the session closed, so the registry can forget it. */
-    onClosed?: ((session: Session) => void) | undefined;
-    /** Report instead of throw when an event cannot be chained (GAP-70). */
-    failOpen?: boolean | undefined;
-    onError?: ((err: Error) => void) | undefined;
-}
-/**
- * One tool call as a span: `tool_call.start` now, `tool_call.end` with the
- * outcome and the elapsed time when the host reports it. For hosts that run
- * their own tool loop and cannot hand the SDK an `execute` to wrap.
- */
-interface ToolCallSpan {
-    readonly callId: string;
-    /** Resolves once `tool_call.start` is sequenced; `end` and `fail` wait for it. */
-    readonly opened: Promise<boolean>;
-    end(outcome?: {
-        output?: JsonValue;
-    }): Promise<boolean>;
-    fail(error: unknown, outcome?: {
-        output?: JsonValue;
-    }): Promise<boolean>;
-}
-declare class Session {
-    private readonly deps;
-    readonly id: string;
-    readonly source: EvidenceSource;
-    readonly expiresAt: string | null;
-    readonly born: SessionBorn;
-    private chain;
-    private building;
-    private dropped;
-    private droppedFirstTs;
-    private droppedLastTs;
-    private closed;
-    private readonly now;
-    constructor(deps: SessionDeps, id: string, source: EvidenceSource, expiresAt: string | null, born: SessionBorn);
-    get head(): ChainHead | null;
-    get droppedCount(): number;
-    get isClosed(): boolean;
-    /**
-     * 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.
-     */
-    emit<K extends WireEvidenceKind>(kind: K, payload: PayloadByKind[K]): Promise<boolean>;
-    /** The tool call whose `execute` the host runs itself; see `ToolCallSpan`. */
-    toolCall(call: ToolCallStartPayload): ToolCallSpan;
-    private chainEvent;
-    close(reason?: SessionClosePayload['reason'], extra?: JsonObject): Promise<void>;
-    /** Read-your-writes: the platform must hold the evidence before anyone judges it (GAP-16/66). */
-    flush(): Promise<void>;
-    /** Serialized: two concurrent emits get consecutive seqs, never the same one. */
-    private next;
-}
-interface StartSessionInput {
-    intent?: DeclaredIntent;
-    runtime?: {
-        framework?: string;
-        model?: string;
-    };
-    attestations?: JsonObject;
-}
-/** What `open` sends when it actually opens: a value, or a resolver run only then. */
-type OpenSessionInput = StartSessionInput | (() => StartSessionInput | Promise<StartSessionInput>);
-/** What an integration takes: a session, or the run that owns one — resolved by `Sessions.resolve`. */
-type SessionSource = Session | Run | null | undefined;
-interface SessionsDeps {
-    api: ApiClient;
-    transport: Transport;
-    /** A disabled client (GAP-78): `open` answers null, `start`/`ensure` throw, nothing is posted. */
-    enabled?: boolean | undefined;
-    identity?: AgentIdentity | undefined;
-    redact?: RedactFn | undefined;
-    now?: (() => Date) | undefined;
-    sdkVersion: string;
-    failOpen?: boolean | undefined;
-    onError?: ((err: Error) => void) | undefined;
-    /** Fail-open only: after the platform refused to open a session, `open` resolves null for this long (GAP-71). */
-    openRetryMs?: number | undefined;
-}
-declare const DEFAULT_OPEN_RETRY_MS = 60000;
-declare class Sessions {
-    private readonly 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).
-     */
-    private readonly attached;
-    /** Buyer sessions by the host's own key (GAP-71). */
-    private readonly opened;
-    private retryAt;
-    constructor(deps: SessionsDeps);
-    /** The session behind a source: itself, or the one the run opens (null when there is none). */
-    static resolve(source: SessionSource): Promise<Session | null>;
-    /**
-     * 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.
-     */
-    open(key: string, input?: OpenSessionInput): Promise<Session | null>;
-    private forget;
-    private openFresh;
-    /** Buyer half: create an AGENT_TRACE session bound to the agent identity, then announce it on the chain. */
-    start(input?: StartSessionInput): Promise<Session>;
-    private identityFor;
-    private create;
-    /** Seller half: emit INTERNAL_NETWORK evidence into a session the buyer bound, or open a seller-born one. */
-    ensure(sessionId?: string | null): Promise<Session>;
-    private attach;
-}
-
-export { type AgentIdentity as A, Beltic as B, ChainRejectedError as C, DEFAULT_OPEN_RETRY_MS as D, type Env as E, type HumanDecisionInput as H, MemoryCorrelationStore as M, type OpenSessionInput as O, type RedactFn as R, type SessionSource as S, type ToolCallSpan as T, Session as a, ApiClient as b, type ApiClientOptions as c, BelticApiError as d, type BelticOptions as e, type CorrelationStore as f, DEFAULT_TRANSPORT as g, type DecideOptions as h, Decision as i, type Evaluation as j, Run as k, type RunOptions as l, SDK_VERSION as m, type SessionBorn as n, Sessions as o, type StartSessionInput as p, Transport as q, TransportClosedError as r, type TransportOptions as s, createBeltic as t, ephemeralIdentity as u, fileIdentity as v, identityFromSeed as w };