@zanii/blackbox 0.0.0-stage → 0.2.0

package/dist/session/index.d.ts

@@ -0,0 +1,275 @@
+import { type Attestation } from "../attest/index.ts";
+export interface SessionOptions {
+    /** The gateway, e.g. http://127.0.0.1:8787 */
+    url: string;
+    /** An existing gateway session: its id and token… */
+    sessionId?: string;
+    token?: string;
+    /** …or open a new one with the admin key. */
+    adminKey?: string;
+    /** Audit S25: the same as `adminKey`; a tenant's `bbxt_` key works too. */
+    apiKey?: string;
+    label?: string;
+    mode?: "strict" | "available";
+    /** Audit S2: what else the gateway takes when it opens a session (spec/api.md). */
+    flightPlan?: FlightPlan;
+    /** Idea C4: rules that narrow this session (deny / require_approval); a child inherits them. */
+    policy?: {
+        rules: unknown[];
+    };
+    /** A decimal string, e.g. "2.50" (spec/control.md §2). */
+    budgetUsd?: string;
+    maxLlmCalls?: number;
+    /** spec/agents.md §2: the session that handed this one its work, and why. */
+    parent?: string;
+    handoff?: string;
+    /** spec/replay.md: replay (or fork) a recorded session. */
+    replay?: {
+        of: string;
+        fork?: boolean;
+        fork_after?: number;
+    };
+    /** The operator opens a session for a tenant (spec/tenancy.md). */
+    tenant?: string;
+    /** spec/authority.md: `supervised` from the start (risky actions wait for a second person). */
+    authority?: "agent" | "supervised";
+    /** spec/preflight.md: the equipment the run needs. A no-go returns a disabled session (and
+     * `stats.lastError` says why); optional items that are down show in `state().degraded`. */
+    preflight?: {
+        require?: string[];
+        optional?: string[];
+    };
+    /** Audit K12, spec/drills.md: failures the gateway injects on purpose, to test the agent. */
+    drill?: {
+        faults: Array<Record<string, unknown>>;
+    };
+    /** Default: $BLACKBOX_SPOOL_DIR, else <tmp>/zanii-blackbox-spool. */
+    spoolDir?: string;
+    flushMs?: number;
+    /** 0 turns the heartbeat off. */
+    heartbeatMs?: number;
+    closeTimeoutMs?: number;
+    /** Compact the spool once everything is acknowledged and this many bytes are behind (default 1 MB). */
+    compactBytes?: number;
+    logger?: (message: string) => void;
+}
+export interface SessionStats {
+    recorded: number;
+    acked: number;
+    errors: number;
+    dropped: number;
+    /** Audit S23: the latest failure, by kind, so an app can alert on the right thing. */
+    lastError?: SessionError;
+}
+export interface SessionError {
+    /** `network`: the gateway is unreachable · `rejected`: it answered with an error ·
+     * `disk`: the spool can't be written · `invalid`: an event was dropped as invalid. */
+    kind: "network" | "rejected" | "disk" | "invalid";
+    message: string;
+    at: string;
+}
+export interface FlightPlan {
+    objective: string;
+    expected_tools?: string[];
+    criteria?: unknown[];
+    [key: string]: unknown;
+}
+/** Audit S17: what the gateway says about this session right now (GET /v1/sessions/:id/state). */
+/** What `land()` found (spec/findings.md §5). */
+export interface EgressCheck {
+    url: string;
+    /** The request got any answer: the agent can reach the internet around the gateway. */
+    open: boolean;
+}
+/** spec/data.md §6: a direct HTTPS request to `url` (default https://example.com). Never throws. */
+export declare function checkEgress(options?: {
+    url?: string;
+    timeoutMs?: number;
+}): Promise<EgressCheck>;
+export interface LandingResult {
+    /** Only a `satisfied` verdict lands: `unverified` never counts as a pass. */
+    landed: boolean;
+    verdict: "satisfied" | "failed" | "unverified" | "error";
+    /** One line per criterion that didn't pass, to hand back to the model. */
+    feedback: string[];
+    /** How many more tries `maxAttempts` allows; at 0, stop and report. */
+    attemptsLeft: number;
+}
+export interface SessionState {
+    session_id: string;
+    closed: boolean;
+    events: number;
+    /** spec/authority.md: who is flying now. */
+    authority: "agent" | "supervised" | "human";
+    /** spec/preflight.md: optional equipment the session left without. */
+    degraded: string[];
+    control: {
+        state: "open" | "blocked";
+        blocked_by?: string;
+    };
+    findings: Array<{
+        code: string;
+        severity: string;
+        count: number;
+        [key: string]: unknown;
+    }>;
+}
+export interface LlmCallIds {
+    provider?: string;
+    request_id?: string;
+    message_id?: string;
+    /** An OpenAI Chat Completions id (`chatcmpl-…`); audit, also found. */
+    completion_id?: string;
+    response_id?: string;
+    model?: string;
+}
+/** N4 (idea R6): the same parts always give the same event id (sha256, 128 bits). */
+export declare function stableEventId(...parts: readonly string[]): string;
+/** Opens (or joins) a session. Never throws: on failure it returns a disabled session and logs why. */
+export declare function session(options: SessionOptions): Promise<BlackboxSession>;
+export declare class BlackboxSession {
+    readonly stats: SessionStats;
+    readonly enabled: boolean;
+    private readonly spool;
+    private readonly ackFile;
+    private nextSeq;
+    private ack;
+    /** The spool's size after our own last change; anything else means another process wrote. */
+    private knownSize;
+    private shipping;
+    private retryAt;
+    private backoff;
+    private timers;
+    private closed;
+    private landings;
+    /** A session that records nothing. `reason`, when opening failed, goes to `stats.lastError` (audit K1). */
+    static disabled(options: SessionOptions, reason?: string): BlackboxSession;
+    private readonly options;
+    readonly id: string;
+    readonly token: string;
+    constructor(options: SessionOptions, id: string, token: string, enabled?: boolean, 
+    /** Audit K5: this SDK opened the session, so only it knows the token: keep it by the spool. */
+    keepToken?: boolean);
+    event(type: string, name?: string, data?: Record<string, unknown>, options?: {
+        eventId?: string;
+    }): void;
+    step(name: string, data?: Record<string, unknown>): void;
+    toolCall(name: string, args?: unknown): void;
+    toolResult(name: string, result?: {
+        ok?: boolean;
+        [key: string]: unknown;
+    }): void;
+    /** spec/data.md §7: a subject's consent for a purpose. The subject is fingerprinted at capture,
+     *  so it must be an identifier the deployment knows (an e-mail, an Emirates ID, a pack's own). */
+    consent(subject: string, purpose: string, granted: boolean): void;
+    /** spec/data.md §6: tries the internet directly, outside the gateway, and records the answer.
+     *  `open: true` means the gateway isn't the only way out (EGRESS_OPEN). */
+    egressCheck(options?: {
+        url?: string;
+        timeoutMs?: number;
+    }): Promise<EgressCheck>;
+    llmCall(ids: LlmCallIds): void;
+    note(text: string): void;
+    /** Files the flight plan (spec/findings.md §5), unless one was filed when the session opened. */
+    flightPlan(plan: {
+        objective: string;
+        expected_tools?: string[];
+        criteria?: unknown[];
+    }): void;
+    /** A completion claim; the server judges it against the recorded tool calls. */
+    claim(summary: string, asserts?: unknown[]): void;
+    /** N2 (idea C10): claims it's done and reads the gateway's verdict, so a failed check goes back
+     * to the model as feedback, a bounded number of times. Never throws. */
+    land(summary: string, asserts?: unknown[], options?: {
+        maxAttempts?: number;
+    }): Promise<LandingResult>;
+    /** N4 (idea R8): the context the model sees changed (summarised, trimmed, a tool result moved
+     * aside), so a replay knows what the model saw. */
+    contextChange(change: {
+        kind: "summarized" | "trimmed" | "offloaded" | "edited";
+        before_tokens?: number;
+        after_tokens?: number;
+        cutoff_index?: number;
+        summary?: string;
+        file_path?: string;
+    }): void;
+    /** Stage 2 R3: the result of one of the customer's own checks (tests, a schema, a policy, a
+     * partial goal), mid-run or at the end. A pass then a fail is VERIFY_REGRESSION; a success whose last
+     * check failed is FALSE_SUCCESS (spec/findings.md §6). */
+    verify(check: string, ok: boolean, detail?: string): void;
+    /** N4 (idea R10): one more attempt at a model or tool call. */
+    retry(kind: "llm" | "tool", target: string, info: {
+        attempt: number;
+        error?: string;
+        delayMs?: number;
+    }): void;
+    /** N4 (idea R10): a call moved to another model or provider. */
+    fallback(from: string, to: string, reason?: string): void;
+    /** N4 (idea R5): how the run is configured: LangGraph's `durability` (sync, async, exit), retry,
+     * timeout and cache policies. */
+    runConfig(config: {
+        durability?: "sync" | "async" | "exit";
+        [key: string]: unknown;
+    }): void;
+    /** The agent reports something it almost got wrong (spec/fleet.md §3): a NEAR_MISS finding. */
+    nearMiss(description: string): void;
+    /** spec/attestation.md: re-runs a read-only command and records whether the output matches. */
+    attest(argv: string[], claimed: string, cwd?: string, claimedExit?: number): Attestation | undefined;
+    /** spec/agents.md §1: the agent's memory store wrote, revoked or returned memories. */
+    memoryWrite(memoryId: string, summary?: string): void;
+    memoryRevoke(memoryId: string, reason?: string): void;
+    memoryRead(memoryIds: string[], query?: string): void;
+    /** Ships what's pending now. Resolves true when everything recorded is acknowledged. With
+     * `timeoutMs` (audit S24) it keeps trying until then, and never waits longer. */
+    flush(options?: {
+        timeoutMs?: number;
+    }): Promise<boolean>;
+    /** Audit S17: the gateway's view of this session (blocked? findings?), or null if it can't be
+     * read. Lets an agent react to its own block before its next model call. Never throws. */
+    state(): Promise<SessionState | null>;
+    /** spec/approvals.md §2: asks a second person before running one of the agent's own risky tools,
+     * and waits (polling) for the answer. Never throws. Only `"approved"` means go ahead; anything
+     * else (`rejected`, `timeout`, or `error` when the gateway can't be asked) means don't. */
+    requestApproval(tool: string, options?: {
+        /** Audit K8: what the tool would be called with, so the approver sees what they approve. */
+        args?: Record<string, unknown>;
+        reason?: string;
+        timeoutMs?: number;
+        pollMs?: number;
+    }): Promise<"approved" | "rejected" | "timeout" | "error">;
+    /** N2 (idea C2): asks a person to let this session use a gateway tool its policy denies (the
+     * denial's `requires.tool`, e.g. `mcp__files__delete`). A yes is a standing grant for the
+     * session: retry the call. Answers like `requestApproval`. Never throws. */
+    requestPermission(tool: string, options?: {
+        reason?: string;
+        timeoutMs?: number;
+        pollMs?: number;
+    }): Promise<"approved" | "rejected" | "timeout" | "error">;
+    private ask;
+    /** Audit S8: `await using s = await session(…)` closes the session when the scope ends. */
+    [Symbol.asyncDispose](): Promise<void>;
+    /** Drains the spool (up to closeTimeoutMs), then closes the gateway session. Never throws.
+     * `outcome` labels the run for the waste ledger (spec/cost.md §5); `note` says why (audit S7).
+     * Audit K9: true only when the gateway closed it (or it was closed already); otherwise
+     * `stats.lastError` says why. */
+    close(outcome?: "success" | "failure" | "abandoned", note?: string): Promise<boolean>;
+    /** Stops shipping and heartbeats without closing the gateway session (for `drain`). */
+    stop(): void;
+    /** The kept token (K5) is no longer needed once everything is shipped and the session closed. */
+    private forgetToken;
+    private tick;
+    private ship;
+    /** L2.2.3: once everything is acknowledged and enough is behind, empty the spool. The ack is
+     * written first: a crash in between only resends acknowledged lines, which the server ignores. */
+    private compact;
+    /** Runs `fn` holding the session's spool lock (a lock file), after catching up with any other
+     * process's writes. A stale lock (a crashed holder) is broken after LOCK_STALE_MS. */
+    private withLock;
+    /** Catches up with the files if another process changed them since our own last change. */
+    private refresh;
+    private heartbeat;
+    private guard;
+    /** Records the latest failure (audit S23) and logs it. */
+    private fail;
+    private log;
+}