@threahq/bot-runtime-client 0.1.0

package/sealed.d.ts

@@ -0,0 +1,305 @@
+/**
+ * Sealed (E2EE) turn support for bot-runtime harnesses.
+ *
+ * A harness that serves an end-to-end-encrypted scratchpad holds a keyring of
+ * BIKs (Bot Identity Keys): X25519 keypairs the owner wraps the stream's
+ * symmetric key (SSK) to. One key per host is the default, so every runtime on
+ * a box shares it; a key can also be pinned to a single stream. On a winning
+ * claim the backend hands the harness a
+ * `sealedContext` — SSK wraps addressed to one of its keys plus the sealed
+ * trigger and history ciphertext — and the harness seals every reply and trace step back
+ * under the same SSK. The server never sees plaintext (INV-E7); the owner's
+ * client opens the harness's output exactly as it opens the enclave's.
+ *
+ * This module is pure crypto + a small keystore; it does no HTTP. Transport
+ * routing lives in `BotRuntimeTransport` (sealed steps) and each harness's own
+ * HTTP client (sealed complete / interim messages, low-frequency writes).
+ */
+import type { E2eKeyRecord, E2eKeyring } from "./keyring.js";
+import { type WebCryptoKey, type AttachmentRef, type SealedPayloadExtras, type StreamEnvelope } from "./crypto.js";
+/**
+ * Per-claim secret (model A) the backend hands a sealed turn in `sealedContext`;
+ * echoed on every sealed callback so the backend can bind it to that session.
+ */
+export declare const THREA_CALLBACK_TOKEN_HEADER = "X-Threa-Callback-Token";
+/** This install's registered Bot Identity Key — held in memory; the private key never re-exports once loaded. */
+export interface BotIdentityKey {
+    publicKeyId: string;
+    publicKeyBase64: string;
+    privateKey: WebCryptoKey;
+}
+/** One SSK wrap addressed to this bot's BIK (wire shape from the claim's `sealedContext`). */
+export interface SealedSskWrap {
+    keyGeneration: number;
+    wrapEnc: string;
+    wrapCt: string;
+}
+/** One SSK-sealed message: base64 ciphertext + its envelope (wire shape). */
+export interface SealedMessageWire {
+    ciphertext: string;
+    envelope: StreamEnvelope;
+}
+/**
+ * The sealed work handed to an owner-granted external bot on a winning claim
+ * when the delivery verdict is `sealed`. Mirrors `@threahq/types`' `SealedTurnContext`
+ * (which standalone extensions can't import). The backend never decrypts: it
+ * ships ciphertext + SSK wraps addressed to this bot's BIK; the bot unwraps
+ * with its identity private key, opens history/prompt, runs its turn, and seals
+ * each reply/step back under the same SSK.
+ */
+export interface SealedTurnContext {
+    callbackToken: string;
+    wraps: SealedSskWrap[];
+    history: (SealedMessageWire & {
+        role: "user" | "assistant";
+        sequence: string;
+    })[];
+    prompt: SealedMessageWire;
+    reply: {
+        keyGeneration: number;
+        senderId: string;
+    };
+    trigger?: {
+        messageId: string;
+        authorName: string;
+        authorType: string;
+        createdAt: string;
+    };
+}
+/** Everything a sealed turn needs to seal its replies/steps back under the stream key. */
+export interface SealingState {
+    /** E2E root stream id — bound into every wrap/message/step AAD. */
+    streamId: string;
+    replyKeyGeneration: number;
+    replySenderId: string;
+    /** The recovered SSK for `replyKeyGeneration`; replies and steps seal under it. */
+    replySsk: Uint8Array;
+    callbackToken: string;
+}
+/** One decrypted prior message, oldest→newest. Formatting into a prompt is the harness's job. */
+export interface DecryptedHistoryItem {
+    role: "user" | "assistant";
+    sequence: string;
+    contentMarkdown: string;
+    /** Per-file keys for the message's E2E attachments — download + decrypt is the harness's job. */
+    attachmentRefs: AttachmentRef[];
+}
+export interface OpenedSealedTurn {
+    promptMarkdown: string;
+    /** Refs sealed into the trigger message's payload (the files attached to the request itself). */
+    promptAttachmentRefs: AttachmentRef[];
+    history: DecryptedHistoryItem[];
+    sealing: SealingState;
+}
+/** The body of a sealed reply or interim message: `msg_…` id in clear, content sealed. */
+export interface SealedReplyBody {
+    messageId: string;
+    ciphertext: string;
+    envelope: StreamEnvelope;
+}
+/** One sealed trace step (the `/sealed-steps` wire shape; `stepId` keys the row, content is ciphertext). */
+export interface SealedStepFrame {
+    stepId: string;
+    stepType: string;
+    messageId?: string;
+    ciphertext: string;
+    envelope: StreamEnvelope;
+    durationMs?: number;
+}
+/** Mint a fresh identity key record: a `bik_…` id and an X25519 keypair, base64. */
+export declare function mintE2eKeyRecord(): Promise<E2eKeyRecord>;
+/**
+ * This install's identity keys, ready to open sealed turns. The records live in
+ * an {@link E2eKeyring} (keychain or file); this adds the WebCrypto import and
+ * caches the result for the process.
+ *
+ * The public halves must ride EVERY `bot:hello` and presence update: the
+ * server reads an advertised keyring as the instance's complete set, so a
+ * heartbeat that omits it unregisters every key and breaks sealed-claim wrap
+ * coverage.
+ */
+export declare class BotKeyring {
+    private readonly buildRecords;
+    private readonly log;
+    private records;
+    private cached;
+    private queue;
+    private loaded;
+    constructor(opts: {
+        keyring: () => E2eKeyring;
+        log?: (message: string) => void;
+    });
+    /** The loaded keys, if `ensure()` has resolved. */
+    get identities(): BotIdentityKey[];
+    /**
+     * Load or create this install's keys, caching them for the process. Returns
+     * an empty keyring when the store or WebCrypto fails, logged loudly: the
+     * harness then serves plaintext streams only, rather than sealed turns
+     * becoming unservable with no clue why. Nothing is downgraded by that — a
+     * runtime with no registered key cannot claim a sealed stream at all.
+     */
+    ensure(): Promise<BotIdentityKey[]>;
+    /**
+     * The key this install reads `streamId` with, imported alongside the rest.
+     * Under the default policy one key already covers every stream and this is
+     * the plain `ensure()`; under the per-stream policy it mints this stream's
+     * key, so presence can advertise it before the owner re-wraps.
+     */
+    ensureForStream(streamId: string): Promise<BotIdentityKey[]>;
+    /**
+     * The identity a wrap for `streamId` must be addressed to, minting it first
+     * if this install does not hold it yet. Undefined when no key could be
+     * created at all, which is the one case a caller must treat as "sealed is
+     * unavailable here" rather than falling back to another key.
+     */
+    identityForStream(streamId: string): Promise<BotIdentityKey | undefined>;
+    /**
+     * Forget the key held for a stream this bot was just revoked from, so the
+     * next presence write stops advertising it. A no-op under every policy but
+     * per-stream, where the key exists for that one scratchpad and nothing else.
+     */
+    dropStream(streamId: string): Promise<BotIdentityKey[]>;
+    /** The fields to spread into every `bot:hello` and presence body. Empty until `ensure()` resolves. */
+    presenceFields(): ReturnType<E2eKeyring["presenceFields"]>;
+    /**
+     * One key operation at a time. Boot presence, `bot:hello` and a grant can all
+     * land together, and each rebuilds the imported set from the keyring's whole
+     * record list — interleaved, the slower one would publish a set missing the
+     * key the other had just added.
+     */
+    private enqueue;
+}
+/**
+ * Validate a claim response's `sealedContext` field. The claim body is untyped
+ * JSON at the harness boundary; a malformed context returns `undefined` so the
+ * caller can fail the invocation loudly instead of crashing mid-hydration.
+ */
+export declare function parseSealedTurnContext(raw: unknown): SealedTurnContext | undefined;
+/**
+ * Open a sealed claim with this bot's keyring: recover the SSK for every generation
+ * the backend wrapped to us (AAD-bound to our key id), open the trigger + prior
+ * history, and return the decrypted prompt plus the {@link SealingState} the turn
+ * seals replies/steps with. `streamId` is the E2E root stream — wraps and the
+ * owner's message AAD both bind to it. A wrap or history row we can't open is
+ * skipped (a generation predating our invite), never fatal; a missing reply or
+ * prompt key is fatal (the turn can't be served).
+ */
+export declare function openSealedTurnContext(params: {
+    sealed: SealedTurnContext;
+    identities: BotIdentityKey[];
+    streamId: string;
+}): Promise<OpenedSealedTurn>;
+/**
+ * Seal a reply (or interim message) under the stream key, bound to a fresh
+ * `msg_…` id — the body of the sealed `/complete` reply and of a sealed
+ * interim `/sealed-messages` post.
+ */
+export declare function sealReply(sealing: SealingState, markdown: string, extras?: SealedPayloadExtras): Promise<SealedReplyBody>;
+/**
+ * Seal one trace step under the stream key, bound to a fresh `step_…` id — the
+ * sealed `/steps` wire shape. The `step_…` id rides the `messageId` slot of the
+ * message AAD, exactly as the enclave's trace-observer binds its steps.
+ * Content is sealed as-given: clamping oversized tool output is the caller's
+ * policy, not hidden truncation here.
+ */
+export declare function sealStep(sealing: SealingState, stepType: string, content: string, opts?: {
+    durationMs?: number;
+}): Promise<SealedStepFrame>;
+/** The words a sealed decision card carries; the wire row holds placeholders in their place. */
+export interface SealedDecisionContent {
+    title: string;
+    bodyMarkdown?: string;
+    /** Option id → the label to show on its button. Ids and tones stay in the clear. */
+    optionLabels: Record<string, string>;
+}
+/** The sealed half of a decision card, with the id its AAD is bound to. */
+export interface SealedDecisionCard {
+    decisionId: string;
+    ciphertext: string;
+    envelope: StreamEnvelope;
+}
+/**
+ * Seal a decision card's question under the stream key, bound to a fresh
+ * `dreq_…` id — the `decisionId` + `sealed` half of a sealed create.
+ *
+ * The AAD names the stream the CARD lives on, which on a thread is not
+ * `sealing.streamId` (that is the root the key hangs off, and what every wrap
+ * and message AAD binds to). Pass the stream being posted to; the server checks
+ * the same string and refuses a card sealed to another slot.
+ */
+export declare function sealDecision(sealing: SealingState, card: {
+    streamId: string;
+    requesterBotId: string;
+}, content: SealedDecisionContent): Promise<SealedDecisionCard>;
+/**
+ * Open the sealed note a member attached to their answer. Returns null when the
+ * envelope names another slot, or a key generation this turn does not hold — a
+ * rotation between opening the card and answering it leaves the answer readable
+ * and its note not, and losing the note beats losing the answer.
+ */
+export declare function openSealedDecisionNote(sealing: SealingState, note: {
+    streamId: string;
+    decisionId: string;
+    decidedBy: string;
+    ciphertext: string;
+    envelope: StreamEnvelope;
+}): Promise<string | null>;
+/** Error text for a sealed `/fail`: class name only, never the message — it could echo decrypted content. */
+export declare function scrubSealedError(error: unknown): string;
+/**
+ * The minimal sealed material a claim carries for a session-control command
+ * (e.g. `/model`) on an E2E scratchpad: the current-generation SSK wraps
+ * addressed to this bot's BIK plus the reply binding. No trigger/history — the
+ * command name is cleartext dispatch metadata, so only the ack needs sealing.
+ * Absent when the bot can't seal (no key / wrap race); the harness then closes
+ * the command silently.
+ */
+export interface SealedAckContext {
+    wraps: SealedSskWrap[];
+    reply: {
+        keyGeneration: number;
+        senderId: string;
+    };
+}
+/** Validate a claim's `sealedAck` field (untyped JSON at the harness boundary). */
+export declare function parseSealedAckContext(raw: unknown): SealedAckContext | undefined;
+/**
+ * Open a session-control sealed ack: unwrap the SSK for the reply generation
+ * with this bot's BIK and return the {@link SealingState} `sealReply` seals the
+ * ack with. `callbackToken` is empty — a session-control ack authorizes with the
+ * claim token on `/complete`, not a per-turn callback token. Throws when no wrap
+ * covers the reply generation (a key race); the caller falls back to a silent close.
+ */
+export declare function openSealedAck(params: {
+    ack: SealedAckContext;
+    identities: BotIdentityKey[];
+    streamId: string;
+}): Promise<SealingState>;
+/** One recipient a freshly-minted stream key is wrapped to. */
+export interface ProvisionRecipient {
+    recipientKind: "user" | "bot";
+    /** UIK/BIK key id — the AAD binds the wrap to this slot. */
+    recipientKeyId: string;
+    /** Base64 raw X25519 public key. */
+    publicKeyBase64: string;
+}
+export interface ProvisionedWrap {
+    recipientKind: "user" | "bot";
+    recipientKeyId: string;
+    wrapEnc: string;
+    wrapCt: string;
+}
+/**
+ * Mint a fresh generation-0 stream key for a harness-created E2E scratchpad and
+ * wrap it to each recipient (the owner's UIK + this install's BIK) — the wire
+ * body of the phase-two provisioning POST. The SSK itself is returned only so
+ * the caller can drop it deliberately: future turns recover it from the claim's
+ * wraps, so nothing needs (or should) persist it locally.
+ */
+export declare function mintStreamKeyWraps(params: {
+    streamId: string;
+    keyGeneration: number;
+    recipients: ProvisionRecipient[];
+}): Promise<{
+    wraps: ProvisionedWrap[];
+}>;

package/transport-test-helpers.d.ts

@@ -0,0 +1,53 @@
+import { mock } from "bun:test";
+import type { InvocationControlScheduler } from "./invocation-control.js";
+import type { BotRuntimeTransport } from "./transport.js";
+import type { BotRuntimeHello, BotRuntimeTransportOptions } from "./types.js";
+export declare const TEST_TRANSPORT_REQUEST_CONFIG: {
+    readonly baseUrl: "https://app.example.test";
+    readonly workspaceId: "ws_1";
+    readonly apiKey: "threa_bk_test";
+};
+export declare function testTransportOptions(hello: BotRuntimeHello, overrides?: Partial<BotRuntimeTransportOptions>): BotRuntimeTransportOptions;
+export declare function waitFor(predicate: () => boolean, timeoutMs?: number): Promise<void>;
+export declare function deferred<T>(): {
+    promise: Promise<T>;
+    resolve: (value: T) => void;
+};
+export declare class FakeScheduler implements InvocationControlScheduler {
+    private nowMs;
+    private nextId;
+    private readonly tasks;
+    private fired;
+    get pendingCount(): number;
+    get firedCount(): number;
+    get pendingDelays(): number[];
+    setTimeout(callback: () => void, delayMs: number): unknown;
+    clearTimeout(handle: unknown): void;
+    advanceBy(ms: number): void;
+}
+export interface CapturedRequest {
+    url: string;
+    method: string;
+    body?: Record<string, unknown>;
+}
+export declare function json(data: unknown, status?: number): Response;
+export declare function stubFetch(responder: (request: CapturedRequest) => Response | Promise<Response>): CapturedRequest[];
+/** Restores `global.fetch` after each test; push spies onto the returned array to have them restored too. */
+export declare function restoreFetchAfterEach(): {
+    mockRestore(): void;
+}[];
+export interface FakeSocket {
+    handlers: Record<string, (...args: unknown[]) => void>;
+    timeout: () => {
+        emit: (...args: unknown[]) => void;
+    };
+    emit: (...args: unknown[]) => void;
+    on: (event: string, callback: (...args: unknown[]) => void) => FakeSocket;
+    connect: ReturnType<typeof mock>;
+    disconnect: ReturnType<typeof mock>;
+    removeAllListeners: ReturnType<typeof mock>;
+}
+type FakeSocketResponder = (event: string, payload: unknown, callback: (error: unknown, ack?: unknown) => void) => void;
+export declare function fakeSocket(responder?: FakeSocketResponder): FakeSocket;
+export declare function attachReadySocket(transport: BotRuntimeTransport, socket: unknown): void;
+export {};

package/transport.d.ts

@@ -0,0 +1,132 @@
+import { type SealedStepFrame } from "./sealed.js";
+import { type ObserveClaimParams, type ObservedClaimHandle } from "./invocation-control.js";
+import { type WsHint } from "./ws-hint.js";
+import type { BotRuntimeTransportOptions, StepFrame } from "./types.js";
+/**
+ * Owns the `/bot` WebSocket and the routing for a runtime's background writes.
+ *
+ * Why it exists: every `presence` / `renew` / `steps` POST goes through the edge
+ * Worker (`app.threa.io/api/*`) and is billed as a request; the same frame over
+ * the already-open socket (a direct CNAME to the regional backend) is free. A
+ * single agentic turn can fire 150+ step writes, so moving them off HTTP is the
+ * difference between an idle daemon costing nothing and one steadily burning the
+ * Cloudflare quota.
+ *
+ * Routing rule for the three write methods: prefer the socket; if the server
+ * acks (ok or a definitive failure) trust it; only a missing ack or a dead
+ * socket triggers the HTTP fallback. Steps are best-effort; presence is
+ * low-stakes.
+ *
+ * The transport owns ONLY these three ops + the socket. Durable, low-frequency
+ * writes (claim/complete/fail/session) stay on each extension's own HTTP client.
+ */
+export declare class BotRuntimeTransport {
+    private readonly base;
+    private readonly workspaceId;
+    private readonly apiKey;
+    private readonly hello;
+    private readonly beforeHello;
+    private readonly callbacks;
+    private readonly wsAckTimeoutMs;
+    private readonly reconnectionDelayMaxMs;
+    private readonly fetchTimeoutMs;
+    private readonly staleSocketRedialMs;
+    private readonly logFn;
+    private socket;
+    private connected;
+    private helloReady;
+    private helloInFlight;
+    private connecting;
+    private stopped;
+    private redialTimer;
+    /** When the current outage started: set at attach and on disconnect, cleared on connect. */
+    private disconnectedAt;
+    /** The cursor echoed by the last hello ack; re-sent on the next hello so the bootstrap only replays unseen events. */
+    private cursor;
+    private readonly controls;
+    constructor(opts: BotRuntimeTransportOptions);
+    /** Whether the `/bot` socket is currently connected. */
+    get socketConnected(): boolean;
+    /**
+     * Resolve the WS hint and open the socket (idempotent — a guard keeps the boot
+     * call and the first poll tick from opening two). The hint resolve is the only
+     * HTTP the transport does on the hot path; a failure leaves the socket closed
+     * and the caller keeps polling/HTTP-writing until the next `connect()`.
+     *
+     * An existing-but-disconnected socket is normally left to Socket.IO's own
+     * retry loop, EXCEPT when the outage has outlived `staleSocketRedialMs`: then
+     * the socket is wedged in a state retries can't fix (a stale ws hint after the
+     * backend moved, a dead retry loop) and the only cure is a teardown + fresh
+     * dial. Without this, one wedged socket leaves the runtime on the fast HTTP
+     * poll forever — the exact Cloudflare-quota burn the transport exists to avoid.
+     */
+    connect(): Promise<void>;
+    private attachSocket;
+    /** (Re)announce this instance + capabilities and pull the bootstrap snapshot. */
+    sendHello(): void;
+    /** Tear the socket down (idempotent). After this the transport is HTTP-only and won't reconnect. */
+    disconnect(): void;
+    private scheduleRedial;
+    /** Drop the current socket without stopping the transport — the next `connect()` dials fresh. */
+    private teardownSocket;
+    /** Own renewal and control synchronization for a claimed invocation. */
+    observeClaim(params: ObserveClaimParams): ObservedClaimHandle;
+    /**
+     * Record one or more trace steps. Best-effort: a turn's narration is nice to
+     * have, not load-bearing, so a failure is logged and dropped rather than
+     * surfaced. This is the high-volume op the whole exercise targets.
+     */
+    recordSteps(invocationId: string, claimToken: string, steps: StepFrame[], statusText?: string, instanceId?: string): Promise<void>;
+    /**
+     * Record one or more SEALED trace steps for an E2E turn. Same routing and
+     * best-effort semantics as {@link recordSteps} — WS frame first, per-step HTTP
+     * fallback — but the frames carry ciphertext + envelope instead of plaintext
+     * content, and auth is the per-claim callback token (model A), not
+     * `instanceId`/`claimToken`. `stepId` is the idempotency key: the server
+     * finalizes/upserts by it, so a duplicate delivery can't double-persist.
+     */
+    recordSealedSteps(invocationId: string, callbackToken: string, steps: SealedStepFrame[]): Promise<void>;
+    /**
+     * Renew a claim's lease. Correctness-critical, so the HTTP fallback is
+     * mandatory: a missing ack, a dead socket, or any non-`NOT_FOUND` server error
+     * all retry over HTTP. Returns `{ notFound: true }` when the claim is gone
+     * (the caller should drop it); the caller never lets it silently lapse.
+     * `renewed` is true only when the server confirmed the extension — a caller
+     * with side effects can stop work once a lease has gone unconfirmed for a
+     * full TTL rather than run on after another runtime may have claimed it.
+     */
+    renewClaim(invocationId: string, claimToken: string, claimTtlSeconds: number, instanceId?: string): Promise<{
+        notFound: boolean;
+        renewed: boolean;
+    }>;
+    /**
+     * Push a presence update. Low-stakes (the socket connection itself is the
+     * primary liveness signal); if the socket can't ack it, fall back to HTTP so
+     * the row still lands. `body` is the full presence body, identical to the HTTP
+     * `/bot-runtime/presence` payload.
+     */
+    updatePresence(body: Record<string, unknown>): Promise<void>;
+    /**
+     * Emit a write event and await its ack.
+     *
+     * `sent` distinguishes the two failure modes that look identical at the ack
+     * layer but must NOT be handled the same way: `sent: false` means the frame
+     * never left (no live socket / `emit` threw), so an HTTP retry is the only way
+     * the write lands and is safe; `sent: true, ack: null` means the frame IS in
+     * flight but the server didn't ack within the timeout. Steps carry a
+     * `client_step_id` so a re-POST would dedup rather than duplicate, but it would
+     * still bill an edge request the WS path exists to avoid — so a best-effort
+     * caller drops on `sent` instead of retrying. Idempotent writes (renew CAS,
+     * presence upsert) ignore the distinction and retry on either.
+     */
+    private emitWrite;
+    /** The wsUrl hint is served by the edge workspace-router at `/api/workspaces/:id/config` (NOT /api/v1). */
+    resolveWsHint(): Promise<WsHint | undefined>;
+    private httpRecordStepsFallback;
+    private httpRecordSealedStepsFallback;
+    private httpRenewFallback;
+    private syncObservedClaim;
+    private httpPresenceFallback;
+    private v1Path;
+    private httpRequest;
+}