@littlebigbrain/client 0.14.0 → 0.16.0

package/dist/transport.d.ts

@@ -7,8 +7,13 @@ export interface CallOptions {
     maxRetries?: number;
     /** Override the client's deadline-based retry budget (ms) for this request. */
     retryBudgetMs?: number;
-    /** Override retry safety classification. Read-only POST namespaces set this automatically. */
-    retry?: boolean;
+    /**
+     * Override retry safety classification. Read-only POST namespaces set this
+     * automatically. `true` retries a `429`, a `5xx` and a network failure;
+     * `"rate_limited"` retries only a retryable `429`, which the server returns
+     * before it runs the request.
+     */
+    retry?: boolean | "rate_limited";
     /** Abort the request and suppress any further retries. */
     signal?: AbortSignal;
     /** Additional request headers. Values override SDK defaults intentionally. */
@@ -50,6 +55,16 @@ export type Query = Record<string, QueryValue>;
 export declare function sleep(ms: number): Promise<void>;
 export declare function retryableStatus(status: number): boolean;
 export declare function retryAllowed(method: string, idempotencyKey?: string): boolean;
+/**
+ * Whether a request's retry classification covers a network failure.
+ * `"rate_limited"` does not: the request may have run on the server.
+ */
+export declare function retriesNetworkFailure(retry: boolean | "rate_limited"): boolean;
+/**
+ * Whether a request's retry classification covers a retryable status.
+ * `"rate_limited"` covers only `429`.
+ */
+export declare function retriesStatus(retry: boolean | "rate_limited", status: number): boolean;
 /** Parse a Retry-After delta-seconds or HTTP-date value, capped at one minute. */
 export declare function parseRetryAfterMs(value: string | null | undefined, nowMs?: number): number | undefined;
 /**

package/dist/transport.js

@@ -69,6 +69,20 @@ export function retryAllowed(method, idempotencyKey) {
         upper === "OPTIONS" ||
         idempotencyKey !== undefined);
 }
+/**
+ * Whether a request's retry classification covers a network failure.
+ * `"rate_limited"` does not: the request may have run on the server.
+ */
+export function retriesNetworkFailure(retry) {
+    return retry === true;
+}
+/**
+ * Whether a request's retry classification covers a retryable status.
+ * `"rate_limited"` covers only `429`.
+ */
+export function retriesStatus(retry, status) {
+    return retry === "rate_limited" ? status === 429 : retry;
+}
 const MAX_RETRY_AFTER_MS = 60_000;
 /** Parse a Retry-After delta-seconds or HTTP-date value, capped at one minute. */
 export function parseRetryAfterMs(value, nowMs = Date.now()) {

package/dist/types.d.ts

@@ -138,12 +138,25 @@ export interface SparqlResultsJson {
     boolean?: boolean;
 }
 /** Parsed SPARQL results: the head vars, the ASK boolean (or null), the raw
- * typed bindings, and the bindings flattened to `{ variable: lexicalValue }`. */
+ * typed bindings, the bindings flattened to `{ variable: lexicalValue }`, and
+ * the served snapshot (or null). */
 export interface SparqlResults {
     vars: string[];
     boolean: boolean | null;
     bindings: Record<string, SparqlTerm>[];
     rows: Record<string, string>[];
+    /**
+     * The snapshot the rows were read from, for an eventual or pinned
+     * (`as_of_commit_seq`) read: `served_at_seq` is that commit. `null` for a
+     * plain strong read.
+     */
+    snapshot: Schemas["SnapshotView"] | null;
+    /**
+     * What the server measured for the request: timings, reads, plan counters
+     * and the join order with estimates. Present only when the request set
+     * `profile: true`.
+     */
+    profile?: Schemas["SparqlQueryProfile"];
 }
 /**
  * Parse a {@link Schemas.SparqlTextResponse} (whose `results` field carries the
@@ -151,6 +164,13 @@ export interface SparqlResults {
  * `{ variable: lexicalValue }` rows — the form most callers want, so they never
  * have to `JSON.parse` and zip `head.vars` with binding values by hand.
  */
+/**
+ * Send `profile` only when it is `true`. An answer without the field is the
+ * default, and a server that predates `profile` refuses unknown body fields.
+ */
+export declare function profileBody<B extends {
+    profile?: boolean;
+}>(body: B, profile?: boolean): B;
 export declare function parseSparqlResults(response: Schemas["SparqlTextResponse"]): SparqlResults;
 export declare function firstPatternVariable(patterns: Schemas["AnalyticTriplePattern"][]): string;
 export declare function attributeFilter(filter: AttributeFilter, defaultVar: string): Schemas["SparqlFilter"];

package/dist/types.js

@@ -4,15 +4,34 @@
  * `{ variable: lexicalValue }` rows — the form most callers want, so they never
  * have to `JSON.parse` and zip `head.vars` with binding values by hand.
  */
+/**
+ * Send `profile` only when it is `true`. An answer without the field is the
+ * default, and a server that predates `profile` refuses unknown body fields.
+ */
+export function profileBody(body, profile) {
+    const { profile: bodyProfile, ...rest } = body;
+    return (bodyProfile ?? profile) === true
+        ? { ...rest, profile: true }
+        : rest;
+}
 export function parseSparqlResults(response) {
     const doc = JSON.parse(response.results);
     const vars = doc.head?.vars ?? [];
+    const snapshot = response.snapshot ?? null;
+    const profile = response.profile ? { profile: response.profile } : {};
     if (typeof doc.boolean === "boolean") {
-        return { vars, boolean: doc.boolean, bindings: [], rows: [] };
+        return {
+            vars,
+            boolean: doc.boolean,
+            bindings: [],
+            rows: [],
+            snapshot,
+            ...profile,
+        };
     }
     const bindings = doc.results?.bindings ?? [];
     const rows = bindings.map((binding) => Object.fromEntries(Object.entries(binding).map(([name, term]) => [name, term.value])));
-    return { vars, boolean: null, bindings, rows };
+    return { vars, boolean: null, bindings, rows, snapshot, ...profile };
 }
 export function firstPatternVariable(patterns) {
     for (const pattern of patterns) {

package/dist/workflows.d.ts

@@ -0,0 +1,207 @@
+import type { LbbClient, Schemas } from "./client.js";
+import type { CallOptions } from "./transport.js";
+type Turn = Schemas["WorkflowTurn"];
+type Instance = Schemas["WorkflowInstance"];
+/** A permanent handler/replay error; ordinary thrown errors retry up to max_attempts. */
+export declare class WorkflowError extends Error {
+}
+export interface WorkflowResult<S, R = unknown, M = unknown> {
+    state: S;
+    result?: R;
+    continuation?: {
+        message: M;
+    };
+}
+export interface WorkflowStepOptions {
+    kind?: "step" | "model" | "tool";
+    /** Per-attempt execution limit, independent of worker lease renewal (default 5 minutes). */
+    timeoutMs?: number;
+    /** Require explicit progress from the operation, independent of worker liveness. */
+    heartbeatTimeoutMs?: number;
+}
+export interface WorkflowStepContext {
+    effectId: string;
+    signal: AbortSignal;
+    /** Last progress checkpoint from a previous attempt, or null. */
+    checkpoint: unknown;
+    heartbeat(details: unknown, options?: {
+        checkpoint?: unknown;
+    }): Promise<void>;
+}
+export type WorkflowSignalResult<T> = {
+    received: true;
+    value: T;
+} | {
+    received: false;
+    value: null;
+};
+export interface WorkflowContext {
+    readonly signal: AbortSignal;
+    readonly workflowId: string;
+    readonly messageId: string;
+    readonly turn: number;
+    /** Sequential named effects only. Pass effectId to the external service as its idempotency key. */
+    step<T>(key: string, effect: (context: WorkflowStepContext) => Promise<T>, options?: WorkflowStepOptions): Promise<T>;
+    /** Wait without holding a worker; signals can arrive before registration. */
+    waitForSignal<T = unknown>(key: string, options: {
+        name: string;
+        timeoutMs: number;
+    }): Promise<WorkflowSignalResult<T>>;
+    /** Checkpoint and release the worker until the timer is due. */
+    sleep(key: string, milliseconds: number): Promise<void>;
+    /** Commit state and append a new message at the inbox tail in one transaction. */
+    continue<S, M>(state: S, message: M): WorkflowResult<S, never, M>;
+}
+interface RegisteredWorkflow {
+    name: string;
+    version: string;
+    initialState: unknown;
+    execute(ctx: WorkflowContext, state: unknown, message: unknown): Promise<WorkflowResult<unknown>>;
+}
+export interface WorkflowDefinition<S, M> extends RegisteredWorkflow {
+    initialState: S;
+    start(client: LbbClient, id: string, options?: {
+        leaseMs?: number;
+        maxAttempts?: number;
+    }): Promise<WorkflowHandle<M>>;
+}
+/** Define a version-pinned message handler. Put I/O, clock reads and randomness inside ctx.step. */
+export declare function workflow<S, M, R = unknown>(definition: {
+    name: string;
+    version: string;
+    initialState: S;
+    onMessage(ctx: WorkflowContext, state: S, message: M): Promise<WorkflowResult<S, R, M>>;
+}): WorkflowDefinition<S, M>;
+export declare class WorkflowHandle<M = unknown> {
+    private readonly api;
+    readonly id: string;
+    constructor(api: WorkflowNamespace, id: string);
+    status(options?: CallOptions): Promise<Instance>;
+    /** Reuse id when retrying the same message, including after a client restart. */
+    send(message: M, options: {
+        id: string;
+    } & CallOptions): Promise<Turn>;
+    /** Deliver an approval, callback or other event to a specific run, including while it waits. */
+    signal(name: string, value: unknown, options: {
+        turn: number;
+        id: string;
+    } & CallOptions): Promise<Turn>;
+    history(options?: {
+        after?: number;
+        limit?: number;
+    } & CallOptions): Promise<{
+        next_after?: number | null;
+        turns: import("./schema.js").components["schemas"]["WorkflowTurn"][];
+    }>;
+    pause(options?: CallOptions): Promise<{
+        completed_turns: number;
+        created_at_ms: number;
+        current_turn?: null | import("./schema.js").components["schemas"]["WorkflowTurn"];
+        history_pruned_through?: number;
+        history_through: number;
+        id: string;
+        pending_messages: number;
+        sequence: number;
+        state: unknown;
+        status: import("./schema.js").components["schemas"]["WorkflowInstanceStatus"];
+        updated_at_ms: number;
+        version: string;
+        workflow_type: string;
+    }>;
+    resume(options?: CallOptions): Promise<{
+        completed_turns: number;
+        created_at_ms: number;
+        current_turn?: null | import("./schema.js").components["schemas"]["WorkflowTurn"];
+        history_pruned_through?: number;
+        history_through: number;
+        id: string;
+        pending_messages: number;
+        sequence: number;
+        state: unknown;
+        status: import("./schema.js").components["schemas"]["WorkflowInstanceStatus"];
+        updated_at_ms: number;
+        version: string;
+        workflow_type: string;
+    }>;
+    retry(turn: number, options?: CallOptions): Promise<{
+        completed_turns: number;
+        created_at_ms: number;
+        current_turn?: null | import("./schema.js").components["schemas"]["WorkflowTurn"];
+        history_pruned_through?: number;
+        history_through: number;
+        id: string;
+        pending_messages: number;
+        sequence: number;
+        state: unknown;
+        status: import("./schema.js").components["schemas"]["WorkflowInstanceStatus"];
+        updated_at_ms: number;
+        version: string;
+        workflow_type: string;
+    }>;
+    cancelTurn(turn: number, options?: CallOptions): Promise<{
+        completed_turns: number;
+        created_at_ms: number;
+        current_turn?: null | import("./schema.js").components["schemas"]["WorkflowTurn"];
+        history_pruned_through?: number;
+        history_through: number;
+        id: string;
+        pending_messages: number;
+        sequence: number;
+        state: unknown;
+        status: import("./schema.js").components["schemas"]["WorkflowInstanceStatus"];
+        updated_at_ms: number;
+        version: string;
+        workflow_type: string;
+    }>;
+}
+export declare class WorkflowNamespace {
+    private readonly client;
+    constructor(client: LbbClient);
+    handle<M = unknown>(id: string): WorkflowHandle<M>;
+    start<S, M>(definition: WorkflowDefinition<S, M>, id: string, options?: {
+        leaseMs?: number;
+        maxAttempts?: number;
+    }): Promise<WorkflowHandle<M>>;
+    create(request: Schemas["WorkflowInstanceCreateRequest"], options?: CallOptions): Promise<Instance>;
+    get(id: string, options?: CallOptions): Promise<Instance>;
+    list(options?: {
+        after?: string;
+        limit?: number;
+    } & CallOptions): Promise<Schemas["WorkflowInstanceListResponse"]>;
+    send(workflowId: string, message: unknown, options: {
+        id: string;
+    } & CallOptions): Promise<Turn>;
+    signal(workflowId: string, name: string, value: unknown, options: {
+        turn: number;
+        id: string;
+    } & CallOptions): Promise<Turn>;
+    history(id: string, options?: {
+        after?: number;
+        limit?: number;
+    } & CallOptions): Promise<Schemas["WorkflowTurnHistoryResponse"]>;
+    control(id: string, action: Schemas["WorkflowInstanceAction"], turn?: number, options?: CallOptions): Promise<Instance>;
+    /**
+     * Delete an instance with its turns and history. `deleted` is false when
+     * no instance had the id, or when a retry finished an earlier delete.
+     * The id can be created again once this returns.
+     */
+    deleteInstance(id: string, options?: CallOptions): Promise<Schemas["WorkflowInstanceDeleteResponse"]>;
+}
+/** One turn at a time per worker; run additional worker processes for concurrency. */
+export declare class WorkflowWorker {
+    private readonly client;
+    private readonly definitions;
+    private readonly options;
+    constructor(client: LbbClient, definitions: readonly RegisteredWorkflow[], options: {
+        worker: string;
+    });
+    run(options: {
+        signal: AbortSignal;
+    }): Promise<void>;
+    runOnce(options?: {
+        signal?: AbortSignal;
+        waitMs?: number;
+    }): Promise<boolean>;
+    private execute;
+}
+export {};