@data-club/ai-hub-server 0.0.1

package/dist/letta/tpmRecovery.d.ts

@@ -0,0 +1,202 @@
+/**
+ * TPM-recovery primitives — provider-429 retry/continuation loop (§6.5).
+ *
+ * The orchestration lives in `state/turnRunner.ts`. This file contains the
+ * pure helpers + the per-agent config resolver + the continuation prompt
+ * text + a cancellable sleep, in one place so the runner stays focused on
+ * the state-machine narrative and the helpers stay unit-testable in
+ * isolation.
+ *
+ * ## Detection (§17 question 3)
+ *
+ * The Letta TypeScript SDK exposes a typed `RateLimitError extends APIError<429, Headers>`
+ * (see `@letta-ai/letta-client/core/error`). When a provider 429 surfaces
+ * through `messages.create`, the SDK throws an error whose `status === 429`
+ * — either before the iterator yields its first event (pre-stream) or
+ * mid-iteration (mid-stream). `is429(err)` is the single detection
+ * predicate; it tolerates both the canonical `RateLimitError` instance and
+ * plain `{ status: 429, headers }` objects so tests can craft fakes
+ * without importing the SDK class directly.
+ *
+ * `readRetryAfterSeconds(err, fallback)` consults `err.headers.get("retry-after")`
+ * — the spec calls for "Honor the `Retry-After` header when present;
+ * otherwise use `default_retry_after_seconds`" (§6.5). Per RFC 9110 the
+ * header value is either delta-seconds (e.g. `"60"`) or an HTTP-date; we
+ * parse both. Anything malformed falls back to the per-agent default.
+ *
+ * ## The continuation prompt
+ *
+ * `CONTINUATION_PROMPT` is the exact text §6.5 specifies for mid-stream
+ * recovery. Wording is load-bearing — changing it would change how the
+ * agent resumes — so the constant lives here, not as a magic string in the
+ * runner.
+ *
+ * ## Cancellation safety (§6.9)
+ *
+ * `cancelableSleep(ms, signal)` resolves on either the timer firing OR the
+ * signal aborting. On abort the pending `setTimeout` is cleared so the
+ * Node event loop doesn't keep the process alive past cancel. The runner's
+ * AbortController is composed with `signal` so a `POST /chat/:id/cancel`
+ * mid-wait clears the pending recovery in one step.
+ *
+ * @see SPECIFICATIONS.md §6.5 — TPM recovery
+ * @see SPECIFICATIONS.md §6.9 — cancellation
+ * @see SPECIFICATIONS.md §17 question 3 — 429 surface
+ */
+import type { DrizzleDB } from "../db/connection.js";
+/**
+ * Per-agent recovery config as resolved at the top of a turn run.
+ *
+ * Carried into the runner without re-reading the DB on every retry so a
+ * concurrent `PATCH /admin/agents/:id` doesn't change the contract
+ * mid-recovery (operationally surprising; the in-flight turn keeps the
+ * settings it started with).
+ */
+export interface TpmRecoveryConfig {
+    /** Master toggle. When `false`, the runner never sleeps + retries on 429 — the turn fails fast with `tpm_exhausted`. */
+    enabled: boolean;
+    /** Effective ceiling on the *recovery* attempts (the double-failure abort condition in §6.5). Default 2. */
+    maxRecoveryAttempts: number;
+    /** Fallback when a 429 carries no `Retry-After`. Default 65 (§6.5 — Anthropic's TPM window + buffer). */
+    defaultRetryAfterSeconds: number;
+}
+/**
+ * The continuation message the runner sends to Letta after a successful
+ * mid-stream sleep. Wording verbatim from §6.5; **do not edit** without
+ * updating the spec.
+ *
+ * @see SPECIFICATIONS.md §6.5
+ */
+export declare const CONTINUATION_PROMPT = "The previous response was interrupted by an API rate limit. Continue exactly where you left off \u2014 do not restart, do not summarize, just continue.";
+/**
+ * Resolves the per-agent TPM-recovery config for the agent that owns
+ * `sessionId`. The runner calls this once before opening the Letta stream
+ * — settings are pinned for the duration of the turn (see file-level
+ * comment).
+ *
+ * Returns the disabled-default config if the session or agent row can't be
+ * found (defensive — handlers above already validate ownership, so a miss
+ * here means concurrent deletion, which is impossible in v1 since neither
+ * agent nor session can be hard-deleted (§6.3.1 / §6.3.4)).
+ *
+ * @param db - Drizzle handle.
+ * @param sessionId - the session's id (from the request body / runner opts).
+ * @returns the per-agent recovery config.
+ *
+ * @see SPECIFICATIONS.md §11 — `agent` table fields
+ */
+export declare function resolveTpmConfig(db: DrizzleDB, sessionId: string): TpmRecoveryConfig;
+/**
+ * Resolves the per-agent `stream_idle_timeout_seconds` for the agent
+ * owning `sessionId`. The runner calls this once before opening the
+ * Letta stream — settings are pinned for the duration of the turn (same
+ * pin-at-start contract as `resolveTpmConfig`).
+ *
+ * Returns the v1 default when no row is found (defensive).
+ *
+ * @param db - Drizzle handle.
+ * @param sessionId - the session's id.
+ * @returns the idle timeout in seconds.
+ */
+export declare function resolveStreamIdleTimeout(db: DrizzleDB, sessionId: string): number;
+/**
+ * Detects a provider 429 surfaced through the Letta SDK.
+ *
+ * Tolerates three shapes, in order of decreasing specificity:
+ *
+ * 1. **Canonical** — `RateLimitError` instance from
+ *    `@letta-ai/letta-client/core/error`. The SDK-typed path; matches
+ *    when Letta forwards the upstream 429 as an HTTP-level 429 on the
+ *    `messages.create` connection.
+ * 2. **Status-shaped** — plain `{ status: 429, ... }` objects. Tests
+ *    craft these via `makeFake429`; production also sees them when the
+ *    SDK has serialized a typed error into a plain object boundary.
+ * 3. **Message-shaped fallback** — plain `Error` instances whose
+ *    `.message` contains "rate limit" / "429" / "too many requests".
+ *    This catches the [letta-ai/letta#3310](https://github.com/letta-ai/letta/issues/3310)
+ *    wrapped surface that the **live investigation** observed against
+ *    `letta/letta:latest` (server 0.16.7) + Anthropic Claude Haiku 4.5:
+ *    Letta threw a plain Error with the upstream message text and no
+ *    `status` field. The SDK-source-of-truth `RateLimitError` shape
+ *    exists in `.d.ts` but is not the surface that actually fires.
+ *
+ * The match excludes context-window-style messages to avoid the obvious
+ * "limit" false-positive — see `looksLikeProviderRateLimitMessage`.
+ *
+ * @param err - the thrown value.
+ * @returns `true` iff the error represents a provider 429.
+ *
+ * @see SPECIFICATIONS.md §17 question 3
+ */
+export declare function is429(err: unknown): boolean;
+/**
+ * Predicate that matches a string containing a provider-rate-limit
+ * indicator while excluding common false-positives.
+ *
+ * Used by both `is429` (caught Error → "is this a 429?") and the
+ * translator's `error_message` handler (Letta wrapped event → "is this a
+ * 429?"). Centralized here so both detection paths apply the same
+ * matching rules.
+ *
+ * **Matches** (case-insensitive substring): `rate limit`, `rate-limit`,
+ * `rate_limit`, `ratelimit`, `429`, `too many requests`.
+ *
+ * **Excludes**: messages containing `context_window` / `context window`
+ * (those are size-limit errors, not rate limits) and `usage limit` /
+ * `usage_limit` (those are billing-cap exhaustions, not transient rate
+ * limits — recovering doesn't help).
+ *
+ * @param text - the message text to inspect.
+ * @returns `true` when `text` looks like a provider rate limit.
+ *
+ * @see SPECIFICATIONS.md §17 question 3
+ */
+export declare function looksLikeProviderRateLimitMessage(text: string): boolean;
+/**
+ * Reads the `Retry-After` header off a 429-shaped error.
+ *
+ * Per RFC 9110 §10.2.3 the header is either delta-seconds (`"60"`) or an
+ * `IMF-fixdate`; we handle both. Malformed / missing → `fallbackSeconds`.
+ * A `Date.now()`-relative date in the past clamps to 0 (the server is
+ * already past the suggested retry window).
+ *
+ * @param err - the 429-shaped error.
+ * @param fallbackSeconds - what to return when no usable header is found.
+ * @returns the suggested wait in *seconds* (not ms — the caller multiplies).
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc9110#section-10.2.3
+ */
+export declare function readRetryAfterSeconds(err: unknown, fallbackSeconds: number): number;
+/**
+ * Promise wrapper around `setTimeout` that resolves when the timer fires
+ * OR rejects with the supplied `AbortError` shape when the signal fires.
+ * Clears the pending `setTimeout` on abort so the Node event loop doesn't
+ * keep the process alive past the cancel.
+ *
+ * Cancellation-safety is the load-bearing property: §6.9 calls for "any
+ * in-flight `setTimeout` for TPM recovery is cleared" on cancel, and the
+ * Step-6 acceptance criteria has a test that asserts no continuation
+ * request fires after a cancel during the wait.
+ *
+ * @param ms - the delay in milliseconds.
+ * @param signal - the abort signal to honor.
+ * @returns a promise resolved on timer fire; rejected with `AbortError` on abort.
+ *
+ * @see SPECIFICATIONS.md §6.9 — cancellation
+ */
+export declare function cancelableSleep(ms: number, signal: AbortSignal | undefined): Promise<void>;
+/**
+ * Adds a small jitter (0..200 ms) to the suggested wait in seconds so two
+ * recovering turns don't both wake up at the exact same millisecond and
+ * thunder against the provider again.
+ *
+ * The jitter is *added*, not subtracted, so we never come in earlier than
+ * the provider's suggested window. v1 keeps it deterministic across tests
+ * by reading from `Math.random()` — fake-timer tests assert behavior at
+ * the boundary, not the exact jitter offset.
+ *
+ * @param baseSeconds - the value returned by `readRetryAfterSeconds`.
+ * @returns the actual delay in milliseconds.
+ */
+export declare function withJitter(baseSeconds: number): number;
+//# sourceMappingURL=tpmRecovery.d.ts.map

package/dist/letta/tpmRecovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tpmRecovery.d.ts","sourceRoot":"","sources":["../../src/letta/tpmRecovery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAOH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAErD;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IAChC,wHAAwH;IACxH,OAAO,EAAE,OAAO,CAAC;IACjB,4GAA4G;IAC5G,mBAAmB,EAAE,MAAM,CAAC;IAC5B,yGAAyG;IACzG,wBAAwB,EAAE,MAAM,CAAC;CAClC;AAED;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,4JACsH,CAAC;AAEvJ;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAC9B,EAAE,EAAE,SAAS,EACb,SAAS,EAAE,MAAM,GAChB,iBAAiB,CAuBnB;AAYD;;;;;;;;;;;GAWG;AACH,wBAAgB,wBAAwB,CACtC,EAAE,EAAE,SAAS,EACb,SAAS,EAAE,MAAM,GAChB,MAAM,CAQR;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,KAAK,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAU3C;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,iCAAiC,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAYvE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,OAAO,EACZ,eAAe,EAAE,MAAM,GACtB,MAAM,CAaR;AAkBD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAC7B,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,WAAW,GAAG,SAAS,GAC9B,OAAO,CAAC,IAAI,CAAC,CAgBf;AASD;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAGtD"}

package/dist/letta/tpmRecovery.js

@@ -0,0 +1,314 @@
+/**
+ * TPM-recovery primitives — provider-429 retry/continuation loop (§6.5).
+ *
+ * The orchestration lives in `state/turnRunner.ts`. This file contains the
+ * pure helpers + the per-agent config resolver + the continuation prompt
+ * text + a cancellable sleep, in one place so the runner stays focused on
+ * the state-machine narrative and the helpers stay unit-testable in
+ * isolation.
+ *
+ * ## Detection (§17 question 3)
+ *
+ * The Letta TypeScript SDK exposes a typed `RateLimitError extends APIError<429, Headers>`
+ * (see `@letta-ai/letta-client/core/error`). When a provider 429 surfaces
+ * through `messages.create`, the SDK throws an error whose `status === 429`
+ * — either before the iterator yields its first event (pre-stream) or
+ * mid-iteration (mid-stream). `is429(err)` is the single detection
+ * predicate; it tolerates both the canonical `RateLimitError` instance and
+ * plain `{ status: 429, headers }` objects so tests can craft fakes
+ * without importing the SDK class directly.
+ *
+ * `readRetryAfterSeconds(err, fallback)` consults `err.headers.get("retry-after")`
+ * — the spec calls for "Honor the `Retry-After` header when present;
+ * otherwise use `default_retry_after_seconds`" (§6.5). Per RFC 9110 the
+ * header value is either delta-seconds (e.g. `"60"`) or an HTTP-date; we
+ * parse both. Anything malformed falls back to the per-agent default.
+ *
+ * ## The continuation prompt
+ *
+ * `CONTINUATION_PROMPT` is the exact text §6.5 specifies for mid-stream
+ * recovery. Wording is load-bearing — changing it would change how the
+ * agent resumes — so the constant lives here, not as a magic string in the
+ * runner.
+ *
+ * ## Cancellation safety (§6.9)
+ *
+ * `cancelableSleep(ms, signal)` resolves on either the timer firing OR the
+ * signal aborting. On abort the pending `setTimeout` is cleared so the
+ * Node event loop doesn't keep the process alive past cancel. The runner's
+ * AbortController is composed with `signal` so a `POST /chat/:id/cancel`
+ * mid-wait clears the pending recovery in one step.
+ *
+ * @see SPECIFICATIONS.md §6.5 — TPM recovery
+ * @see SPECIFICATIONS.md §6.9 — cancellation
+ * @see SPECIFICATIONS.md §17 question 3 — 429 surface
+ */
+import { eq } from "drizzle-orm";
+import { RateLimitError } from "@letta-ai/letta-client";
+import { agent, session } from "../db/schema.js";
+/**
+ * The continuation message the runner sends to Letta after a successful
+ * mid-stream sleep. Wording verbatim from §6.5; **do not edit** without
+ * updating the spec.
+ *
+ * @see SPECIFICATIONS.md §6.5
+ */
+export const CONTINUATION_PROMPT = "The previous response was interrupted by an API rate limit. Continue exactly where you left off — do not restart, do not summarize, just continue.";
+/**
+ * Resolves the per-agent TPM-recovery config for the agent that owns
+ * `sessionId`. The runner calls this once before opening the Letta stream
+ * — settings are pinned for the duration of the turn (see file-level
+ * comment).
+ *
+ * Returns the disabled-default config if the session or agent row can't be
+ * found (defensive — handlers above already validate ownership, so a miss
+ * here means concurrent deletion, which is impossible in v1 since neither
+ * agent nor session can be hard-deleted (§6.3.1 / §6.3.4)).
+ *
+ * @param db - Drizzle handle.
+ * @param sessionId - the session's id (from the request body / runner opts).
+ * @returns the per-agent recovery config.
+ *
+ * @see SPECIFICATIONS.md §11 — `agent` table fields
+ */
+export function resolveTpmConfig(db, sessionId) {
+    const row = db
+        .select({
+        enabled: agent.tpmRecoveryEnabled,
+        max: agent.maxRecoveryAttempts,
+        retryAfter: agent.defaultRetryAfterSeconds,
+    })
+        .from(session)
+        .innerJoin(agent, eq(session.agentId, agent.id))
+        .where(eq(session.id, sessionId))
+        .get();
+    if (!row) {
+        return {
+            enabled: false,
+            maxRecoveryAttempts: 2,
+            defaultRetryAfterSeconds: 65,
+        };
+    }
+    return {
+        enabled: row.enabled,
+        maxRecoveryAttempts: row.max,
+        defaultRetryAfterSeconds: row.retryAfter,
+    };
+}
+/**
+ * Default `streamIdleTimeoutSeconds` when no agent row can be found (e.g.
+ * concurrent deletion — impossible in v1 since agents are archive-only,
+ * but the defensive default keeps the runner well-behaved either way).
+ * Matches the column default in `agent` (Step-10 closeout). Independent
+ * of TPM defaults — TPM has its own 65s timer that doesn't share with
+ * this idle watchdog.
+ */
+const DEFAULT_STREAM_IDLE_TIMEOUT_SECONDS = 60;
+/**
+ * Resolves the per-agent `stream_idle_timeout_seconds` for the agent
+ * owning `sessionId`. The runner calls this once before opening the
+ * Letta stream — settings are pinned for the duration of the turn (same
+ * pin-at-start contract as `resolveTpmConfig`).
+ *
+ * Returns the v1 default when no row is found (defensive).
+ *
+ * @param db - Drizzle handle.
+ * @param sessionId - the session's id.
+ * @returns the idle timeout in seconds.
+ */
+export function resolveStreamIdleTimeout(db, sessionId) {
+    const row = db
+        .select({ idleTimeout: agent.streamIdleTimeoutSeconds })
+        .from(session)
+        .innerJoin(agent, eq(session.agentId, agent.id))
+        .where(eq(session.id, sessionId))
+        .get();
+    return row?.idleTimeout ?? DEFAULT_STREAM_IDLE_TIMEOUT_SECONDS;
+}
+/**
+ * Detects a provider 429 surfaced through the Letta SDK.
+ *
+ * Tolerates three shapes, in order of decreasing specificity:
+ *
+ * 1. **Canonical** — `RateLimitError` instance from
+ *    `@letta-ai/letta-client/core/error`. The SDK-typed path; matches
+ *    when Letta forwards the upstream 429 as an HTTP-level 429 on the
+ *    `messages.create` connection.
+ * 2. **Status-shaped** — plain `{ status: 429, ... }` objects. Tests
+ *    craft these via `makeFake429`; production also sees them when the
+ *    SDK has serialized a typed error into a plain object boundary.
+ * 3. **Message-shaped fallback** — plain `Error` instances whose
+ *    `.message` contains "rate limit" / "429" / "too many requests".
+ *    This catches the [letta-ai/letta#3310](https://github.com/letta-ai/letta/issues/3310)
+ *    wrapped surface that the **live investigation** observed against
+ *    `letta/letta:latest` (server 0.16.7) + Anthropic Claude Haiku 4.5:
+ *    Letta threw a plain Error with the upstream message text and no
+ *    `status` field. The SDK-source-of-truth `RateLimitError` shape
+ *    exists in `.d.ts` but is not the surface that actually fires.
+ *
+ * The match excludes context-window-style messages to avoid the obvious
+ * "limit" false-positive — see `looksLikeProviderRateLimitMessage`.
+ *
+ * @param err - the thrown value.
+ * @returns `true` iff the error represents a provider 429.
+ *
+ * @see SPECIFICATIONS.md §17 question 3
+ */
+export function is429(err) {
+    if (err instanceof RateLimitError)
+        return true;
+    if (err && typeof err === "object") {
+        const e = err;
+        if (e.status === 429)
+            return true;
+        if (typeof e.message === "string" && looksLikeProviderRateLimitMessage(e.message)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Predicate that matches a string containing a provider-rate-limit
+ * indicator while excluding common false-positives.
+ *
+ * Used by both `is429` (caught Error → "is this a 429?") and the
+ * translator's `error_message` handler (Letta wrapped event → "is this a
+ * 429?"). Centralized here so both detection paths apply the same
+ * matching rules.
+ *
+ * **Matches** (case-insensitive substring): `rate limit`, `rate-limit`,
+ * `rate_limit`, `ratelimit`, `429`, `too many requests`.
+ *
+ * **Excludes**: messages containing `context_window` / `context window`
+ * (those are size-limit errors, not rate limits) and `usage limit` /
+ * `usage_limit` (those are billing-cap exhaustions, not transient rate
+ * limits — recovering doesn't help).
+ *
+ * @param text - the message text to inspect.
+ * @returns `true` when `text` looks like a provider rate limit.
+ *
+ * @see SPECIFICATIONS.md §17 question 3
+ */
+export function looksLikeProviderRateLimitMessage(text) {
+    const l = text.toLowerCase();
+    if (l.includes("context_window") || l.includes("context window"))
+        return false;
+    if (l.includes("usage limit") || l.includes("usage_limit"))
+        return false;
+    return (l.includes("rate limit") ||
+        l.includes("rate-limit") ||
+        l.includes("rate_limit") ||
+        l.includes("ratelimit") ||
+        l.includes("429") ||
+        l.includes("too many requests"));
+}
+/**
+ * Reads the `Retry-After` header off a 429-shaped error.
+ *
+ * Per RFC 9110 §10.2.3 the header is either delta-seconds (`"60"`) or an
+ * `IMF-fixdate`; we handle both. Malformed / missing → `fallbackSeconds`.
+ * A `Date.now()`-relative date in the past clamps to 0 (the server is
+ * already past the suggested retry window).
+ *
+ * @param err - the 429-shaped error.
+ * @param fallbackSeconds - what to return when no usable header is found.
+ * @returns the suggested wait in *seconds* (not ms — the caller multiplies).
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc9110#section-10.2.3
+ */
+export function readRetryAfterSeconds(err, fallbackSeconds) {
+    const headers = extractHeaders(err);
+    if (!headers)
+        return fallbackSeconds;
+    const raw = headers.get("retry-after");
+    if (!raw)
+        return fallbackSeconds;
+    const asNumber = Number(raw);
+    if (Number.isFinite(asNumber) && asNumber >= 0)
+        return Math.round(asNumber);
+    const asDate = Date.parse(raw);
+    if (!Number.isNaN(asDate)) {
+        const delta = Math.round((asDate - Date.now()) / 1000);
+        return delta > 0 ? delta : 0;
+    }
+    return fallbackSeconds;
+}
+/** Pulls the `Headers` off either the typed SDK error or a plain mock. */
+function extractHeaders(err) {
+    if (!err || typeof err !== "object")
+        return null;
+    const e = err;
+    if (e.headers instanceof Headers)
+        return e.headers;
+    // Plain object support — tests build a `{ "retry-after": "1" }`-style record.
+    if (e.headers && typeof e.headers === "object") {
+        const h = new Headers();
+        for (const [k, v] of Object.entries(e.headers)) {
+            if (typeof v === "string")
+                h.set(k, v);
+        }
+        return h;
+    }
+    return null;
+}
+/**
+ * Promise wrapper around `setTimeout` that resolves when the timer fires
+ * OR rejects with the supplied `AbortError` shape when the signal fires.
+ * Clears the pending `setTimeout` on abort so the Node event loop doesn't
+ * keep the process alive past the cancel.
+ *
+ * Cancellation-safety is the load-bearing property: §6.9 calls for "any
+ * in-flight `setTimeout` for TPM recovery is cleared" on cancel, and the
+ * Step-6 acceptance criteria has a test that asserts no continuation
+ * request fires after a cancel during the wait.
+ *
+ * @param ms - the delay in milliseconds.
+ * @param signal - the abort signal to honor.
+ * @returns a promise resolved on timer fire; rejected with `AbortError` on abort.
+ *
+ * @see SPECIFICATIONS.md §6.9 — cancellation
+ */
+export function cancelableSleep(ms, signal) {
+    if (signal?.aborted) {
+        return Promise.reject(makeAbortError());
+    }
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            if (signal)
+                signal.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            if (signal)
+                signal.removeEventListener("abort", onAbort);
+            reject(makeAbortError());
+        };
+        if (signal)
+            signal.addEventListener("abort", onAbort, { once: true });
+    });
+}
+/** Constructs an `AbortError`-shaped Error consistent with the runner's existing sentinel. */
+function makeAbortError() {
+    const e = new Error("aborted");
+    e.name = "AbortError";
+    return e;
+}
+/**
+ * Adds a small jitter (0..200 ms) to the suggested wait in seconds so two
+ * recovering turns don't both wake up at the exact same millisecond and
+ * thunder against the provider again.
+ *
+ * The jitter is *added*, not subtracted, so we never come in earlier than
+ * the provider's suggested window. v1 keeps it deterministic across tests
+ * by reading from `Math.random()` — fake-timer tests assert behavior at
+ * the boundary, not the exact jitter offset.
+ *
+ * @param baseSeconds - the value returned by `readRetryAfterSeconds`.
+ * @returns the actual delay in milliseconds.
+ */
+export function withJitter(baseSeconds) {
+    const jitter = Math.floor(Math.random() * 200);
+    return Math.max(0, baseSeconds * 1000 + jitter);
+}
+//# sourceMappingURL=tpmRecovery.js.map

package/dist/letta/tpmRecovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tpmRecovery.js","sourceRoot":"","sources":["../../src/letta/tpmRecovery.ts"],"names":[],"mappings":"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"}

package/dist/letta/types.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Project-shaped Letta types.
+ *
+ * Re-exports only the SDK surfaces ai-hub uses, so the rest of the server
+ * code never has to traverse `@letta-ai/letta-client`'s deep namespace
+ * structure. **No raw HTTP, ever** — these are aliases over the SDK's own
+ * types, not parallel inventions (§6.4).
+ *
+ * If the SDK rev removes or renames one of these, the typechecker flags it
+ * at upgrade time and `letta/client.ts` is the single place to adapt.
+ *
+ * @see SPECIFICATIONS.md §6.4 — SDK-only access pattern
+ * @see SPECIFICATIONS.md §6.4.1 — first-class surfaces we depend on
+ */
+import type Letta from "@letta-ai/letta-client";
+import type { AssistantMessage, HiddenReasoningMessage, Message as LettaSdkMessage, ReasoningMessage, ToolCallMessage, UserMessage } from "@letta-ai/letta-client/resources/agents/messages.js";
+import type { LettaStreamingResponse } from "@letta-ai/letta-client/resources/agents/messages.js";
+import type { ToolReturnMessage } from "@letta-ai/letta-client/resources/tools.js";
+/**
+ * The underlying SDK client. We `import type` everywhere except in
+ * `letta/client.ts` (where the constructor actually runs) so the rest of the
+ * codebase stays SDK-version-agnostic in shape.
+ */
+export type LettaSdk = Letta;
+/**
+ * One streaming event from `client.conversations.messages.create({ streaming: true })`.
+ *
+ * The union spans every variant Letta emits in an SSE stream — assistant
+ * text, reasoning, tool calls, tool returns, errors, pings, stop reasons,
+ * usage stats. `letta/eventTranslator.ts` is the pure function from this
+ * union to ai-hub's wire-protocol events (§9).
+ *
+ * @see SPECIFICATIONS.md §9 — wire protocol
+ */
+export type LettaStreamEvent = LettaStreamingResponse;
+/**
+ * Alias for `AssistantMessage` — used by the translator + tests. See
+ * `letta/eventTranslator.ts` for the streamed-delta vs. cumulative-content
+ * note.
+ */
+export type LettaAssistantMessage = AssistantMessage;
+/** Alias for `ReasoningMessage` — see `eventTranslator.ts`. */
+export type LettaReasoningMessage = ReasoningMessage;
+/** Alias for `HiddenReasoningMessage` — see `eventTranslator.ts`. */
+export type LettaHiddenReasoningMessage = HiddenReasoningMessage;
+/** Alias for `ToolCallMessage` — see `eventTranslator.ts`. */
+export type LettaToolCallMessage = ToolCallMessage;
+/** Alias for `ToolReturnMessage` — see `eventTranslator.ts`. */
+export type LettaToolReturnMessage = ToolReturnMessage;
+/** Alias for `UserMessage` — only appears in history reads, not in streams. */
+export type LettaUserMessage = UserMessage;
+/** Full assembled Letta message (used by `messages.list`). */
+export type LettaMessage = LettaSdkMessage;
+//# sourceMappingURL=types.d.ts.map

package/dist/letta/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/letta/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,KAAK,MAAM,wBAAwB,CAAC;AAChD,OAAO,KAAK,EACV,gBAAgB,EAChB,sBAAsB,EACtB,OAAO,IAAI,eAAe,EAC1B,gBAAgB,EAChB,eAAe,EACf,WAAW,EACZ,MAAM,qDAAqD,CAAC;AAC7D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,qDAAqD,CAAC;AAClG,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2CAA2C,CAAC;AAEnF;;;;GAIG;AACH,MAAM,MAAM,QAAQ,GAAG,KAAK,CAAC;AAE7B;;;;;;;;;GASG;AACH,MAAM,MAAM,gBAAgB,GAAG,sBAAsB,CAAC;AAEtD;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,GAAG,gBAAgB,CAAC;AACrD,+DAA+D;AAC/D,MAAM,MAAM,qBAAqB,GAAG,gBAAgB,CAAC;AACrD,qEAAqE;AACrE,MAAM,MAAM,2BAA2B,GAAG,sBAAsB,CAAC;AACjE,8DAA8D;AAC9D,MAAM,MAAM,oBAAoB,GAAG,eAAe,CAAC;AACnD,gEAAgE;AAChE,MAAM,MAAM,sBAAsB,GAAG,iBAAiB,CAAC;AACvD,+EAA+E;AAC/E,MAAM,MAAM,gBAAgB,GAAG,WAAW,CAAC;AAE3C,8DAA8D;AAC9D,MAAM,MAAM,YAAY,GAAG,eAAe,CAAC"}

package/dist/letta/types.js

@@ -0,0 +1,16 @@
+/**
+ * Project-shaped Letta types.
+ *
+ * Re-exports only the SDK surfaces ai-hub uses, so the rest of the server
+ * code never has to traverse `@letta-ai/letta-client`'s deep namespace
+ * structure. **No raw HTTP, ever** — these are aliases over the SDK's own
+ * types, not parallel inventions (§6.4).
+ *
+ * If the SDK rev removes or renames one of these, the typechecker flags it
+ * at upgrade time and `letta/client.ts` is the single place to adapt.
+ *
+ * @see SPECIFICATIONS.md §6.4 — SDK-only access pattern
+ * @see SPECIFICATIONS.md §6.4.1 — first-class surfaces we depend on
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/letta/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/letta/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG"}

package/dist/observability/logger.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Structured logging via pino.
+ *
+ * Production: raw JSON to stdout, one line per record (§6.10 — twelve-factor
+ * pattern). Dev: piped through `pino-pretty` for human-readable output, gated
+ * on `NODE_ENV !== "production"` or `LOG_LEVEL=debug`.
+ *
+ * **Redaction is a load-bearing security control** (§13.3). pino's built-in
+ * `redact` option is the single point of truth — every log call goes through
+ * the configured logger, and a regression test asserts a known-secret value
+ * never appears in captured stdout.
+ *
+ * @see SPECIFICATIONS.md §6.10 — observability
+ * @see SPECIFICATIONS.md §13.3 — secrets
+ */
+import { type Logger as PinoLogger } from "pino";
+/** What the rest of the server consumes — keeps pino out of import surfaces. */
+export type Logger = PinoLogger;
+/**
+ * Optional shape passed to `createLogger`. The dev-mode pretty-print stream
+ * is set up by the caller (the dev/server entrypoint) — `createLogger` itself
+ * stays format-agnostic so tests can pass a writable stream.
+ */
+export interface CreateLoggerOptions {
+    /** pino level (`fatal | error | warn | info | debug | trace`). Default `info`. */
+    level?: string;
+    /**
+     * Optional destination. Tests pass a memory stream so they can assert on
+     * the captured output. Production passes nothing — pino writes to stdout
+     * by default.
+     */
+    destination?: NodeJS.WritableStream;
+}
+/**
+ * Builds a pino logger with the project's redaction policy applied.
+ *
+ * @param opts - level + optional destination override.
+ * @returns the pino logger instance.
+ */
+export declare function createLogger(opts?: CreateLoggerOptions): Logger;
+/**
+ * The redaction-path list — exposed for tests so a new path added in
+ * `REDACT_PATHS` is automatically covered without test churn.
+ *
+ * @returns a fresh array of the redaction paths used by `createLogger`.
+ */
+export declare function getRedactPaths(): string[];
+//# sourceMappingURL=logger.d.ts.map

package/dist/observability/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/observability/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAQ,KAAK,MAAM,IAAI,UAAU,EAAsB,MAAM,MAAM,CAAC;AAE3E,gFAAgF;AAChF,MAAM,MAAM,MAAM,GAAG,UAAU,CAAC;AAyChC;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,kFAAkF;IAClF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC,cAAc,CAAC;CACrC;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,GAAE,mBAAwB,GAAG,MAAM,CAUnE;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,IAAI,MAAM,EAAE,CAEzC"}