@belticlabs/agent-risk-sdk 0.5.0 → 0.6.0

package/dist/session-D9E-efc0.d.ts

@@ -1,462 +0,0 @@
-import { w as EventResult, K as EvidenceEvent, u as EvaluateOutput, ax as Verdict, a3 as OnReview, a8 as PaymentSummary, P as PaymentMomentPayload, D as Decision$1, p as DeclaredIntent, at as ToolCallStartPayload, J as JsonValue, Y as JsonObject, aj as SessionClosePayload, O as EvidenceSource, C as ChainHead, aA as WireEvidenceKind, a6 as PayloadByKind } from './verdict-DMnbFuS5.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 | undefined;
-    userAgent?: string | undefined;
-}
-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, 429 and network failures are retried by the transport and absorbed by `failOpen`; 4xx are neither (GAP-70). */
-    get retryable(): boolean;
-}
-declare class ApiClient {
-    private readonly baseUrl;
-    private readonly fetchImpl;
-    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;
-}
-
-/**
- * Identity Module (Fraud SDK RFC › Modules): the agent's credential (DID +
- * VC) and the event-signing key. Phase 1 is did:key over Ed25519 (GAP-11):
- * the DID *is* the public key, so the signer and the identity are one.
- */
-
-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;
-
-/**
- * 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.
- */
-
-/** What a host may tune; the defaults are `DEFAULT_TUNING`. */
-interface TransportTuning {
-    flushMs: number;
-    /** Total buffered events across chains; beyond this new events are dropped (GAP-38). */
-    maxBuffered: number;
-    backoff: {
-        baseMs: number;
-        maxMs: number;
-        maxAttempts: number;
-    };
-}
-interface TransportOptions extends TransportTuning {
-    onError?: ((err: Error) => void) | undefined;
-    onChainHalted?: ((err: ChainRejectedError) => void) | undefined;
-}
-declare class ChainRejectedError extends Error {
-    readonly sessionId: string;
-    readonly source: string;
-    readonly result: EventResult;
-    constructor(sessionId: string, source: string, result: EventResult, options?: {
-        cause?: unknown;
-    });
-    /** Halted by retries exhausted on an outage — not by anything the platform rejected (GAP-70). */
-    get transient(): boolean;
-}
-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>);
-    /**
-     * 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: unknown): boolean;
-    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_*`; a client is configured
- * or it is not constructed — there is no disabled client (GAP-78).
- *
- * Evidence is a side channel of the work it observes. With `failOpen` a
- * platform outage never 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. What the platform *rejects* (a 4xx, a forked chain) is the client's
- * fault and throws in both modes (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.5.0";
-type Env = Record<string, string | undefined>;
-interface BelticOptions {
-    apiKey: string;
-    baseUrl: string;
-    fetch?: typeof globalThis.fetch | undefined;
-    /** Buyer half. Without it, `sessions.start` and `open` are unavailable; the seller half works. */
-    identity?: AgentIdentity | undefined;
-    transport?: Partial<TransportTuning> | undefined;
-    /** What a synchronous seller hook does with REVIEW (GAP-52). */
-    onReview?: OnReview | undefined;
-    /** A platform outage never fails the work evidence observes; see the module note (GAP-70). */
-    failOpen?: boolean | undefined;
-    /** Where fail-open failures and transport delivery failures go. Default: `console.error`. */
-    onError?: ((err: Error) => void) | undefined;
-    /** Fail-open only: how long `sessions.open` answers null after the platform could not open a session (GAP-71). */
-    openRetryMs?: number | undefined;
-}
-/** What `fromEnv` takes besides the environment: everything the variables do not say. */
-type FromEnvOptions = Omit<BelticOptions, 'apiKey' | 'baseUrl' | 'identity'>;
-/** 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 transport: Transport;
-    readonly sessions: Sessions;
-    readonly identity: AgentIdentity | undefined;
-    readonly onReview: OnReview;
-    readonly failOpen: boolean;
-    private readonly api;
-    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`. Any of the three missing is a configuration
-     * error, thrown (GAP-78).
-     */
-    static fromEnv(env?: Env, opts?: FromEnvOptions): 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 reached.
-     */
-    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;
-}
-
-/**
- * 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. Payloads ship
- * whole (GAP-33).
- *
- * Evidence is a side channel of the agent's work: with `failOpen` an emit
- * refused because the platform is unreachable is reported and returns
- * `false` instead of throwing into the model or tool call it observes;
- * anything the platform rejected still throws (GAP-70).
- */
-
-/** 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;
-    now?: (() => Date) | undefined;
-    /** Called once the session closed, so the registry can forget it. */
-    onClosed?: ((session: Session) => void) | undefined;
-    /** Report instead of throw when the platform is unreachable (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 halted on an outage.
-     */
-    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;
-interface SessionsDeps {
-    api: ApiClient;
-    transport: Transport;
-    identity?: AgentIdentity | undefined;
-    sdkVersion: string;
-    failOpen?: boolean | undefined;
-    onError?: ((err: Error) => void) | undefined;
-    /** Fail-open only: after the platform could not open a session, `open` resolves null for this long (GAP-71). */
-    openRetryMs?: number | undefined;
-}
-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 the run has 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 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: 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, type DecideOptions as D, type Env as E, type FromEnvOptions as F, type HumanDecisionInput as H, type OpenSessionInput as O, Run as R, type SessionSource as S, type ToolCallSpan as T, ApiClient as a, type ApiClientOptions as b, BelticApiError as c, type BelticOptions as d, Decision as e, type Evaluation as f, type RunOptions as g, SDK_VERSION as h, Session as i, type SessionBorn as j, Sessions as k, type StartSessionInput as l, Transport as m, type TransportOptions as n, type TransportTuning as o, identityFromSeed as p };