@retinue/agentkit 0.1.0

package/dist/persistence/index.js

@@ -0,0 +1,226 @@
+/**
+ * Storage and infrastructure ports — `docs/02-core-and-persistence.md`.
+ *
+ * Small interfaces rather than one database adapter. Every read and write receives
+ * `tenantId` explicitly: `findById(id)` is forbidden, `findById({ tenantId, id })` is
+ * the shape. Ports never import adapters.
+ *
+ * Method bodies are intentionally sparse at this stage — each port is filled in as its
+ * phase in `docs/08-migration-plan.md` lands, against the shared conformance suite.
+ */
+/**
+ * The ceiling on session state, defined here rather than in an adapter (#97). It is a domain limit —
+ * session state is bounded working memory, not a document store — and every adapter must enforce the
+ * same one. It previously lived in `adapters/memory/sessions.ts`, which made two adapters agreeing on
+ * it a coincidence rather than a property.
+ */
+export const DEFAULT_SESSION_STATE_MAX_BYTES = 64 * 1024;
+/**
+ * Rollup granularities (#139).
+ *
+ * Hour, day, week and month, and nothing finer than an hour. A minute bucket multiplies the row count
+ * sixty-fold to answer a question nobody asks.
+ *
+ * Week and month were added by #175, because they are the periods a *person's* allowance is actually expressed
+ * in — "500k tokens a month" is a plan, "500k tokens a day" is not. They cannot be derived by summing days
+ * either: a month is 28 to 31 days and a week crosses month boundaries, so a caller summing day buckets has to
+ * reimplement calendar arithmetic, and two callers doing it differently is two answers to what a month cost.
+ *
+ * A week starts **Monday**, in UTC, following ISO 8601 — chosen rather than defaulted, because a Sunday start
+ * would split a working week across two buckets and every weekly figure would describe half of one week and half
+ * of another.
+ */
+export const ROLLUP_PERIODS = ["hour", "day", "week", "month"];
+/**
+ * Admin-configured spend limits — #175.
+ *
+ * `principalId` absent is the **tenant default**; present overrides it for one person. One store rather than
+ * two, because "the default" and "an override" are the same kind of fact and resolution is then a single query
+ * ordered by specificity rather than two queries and a merge.
+ *
+ * Every limit is optional and an omitted one is **unbounded**, not zero — matching `QuotaLimits`, and for the
+ * reason stated there: a misconfigured quota that blocks everything is an outage, and one that blocks nothing is
+ * a bill that the rollups make visible.
+ */
+/**
+ * A window as one storable string, and back — #181.
+ *
+ * `usage_limits` keys its unique indexes on this single column, so the two kinds of window have to share one
+ * value space. A calendar window is its own period; a rolling one is `rolling:<minutes>`. Both spellings are
+ * pinned by the table's CHECK constraint, so a value that would not round-trip cannot be stored in the first
+ * place.
+ *
+ * The codec lives here, beside the type, rather than in each adapter: two adapters spelling a key differently is
+ * two stores that cannot read each other's rows, and conformance would pass because each is self-consistent.
+ */
+export const windowKey = (window) => window.kind === "calendar" ? window.period : `rolling:${window.minutes}`;
+/**
+ * `null` for anything this does not recognise — a row written by a newer version, or by hand.
+ *
+ * Null rather than a thrown error or a calendar fallback. A fallback would silently enforce the wrong window,
+ * which for a spend limit means either refusing people wrongly or charging them wrongly; null makes the caller
+ * decide, and every caller here treats it as "no limit I can honour", which fails towards *not* pretending.
+ */
+export const parseWindowKey = (key) => {
+    if (ROLLUP_PERIODS.includes(key))
+        return { kind: "calendar", period: key };
+    const match = /^rolling:([1-9][0-9]{0,5})$/.exec(key);
+    if (match === null)
+        return null;
+    return { kind: "rolling", minutes: Number(match[1]) };
+};
+// ---------------------------------------------------------------------------
+// Artifacts (#133) — REQ-028. Substantial assistant output as a named, versioned thing rather than
+// text buried in a thread.
+// ---------------------------------------------------------------------------
+/**
+ * What an artifact is.
+ *
+ * Markdown and structured content first, per `docs/05` → Document writing. Rendered formats — PDF, DOCX — are
+ * *exports* of an artifact rather than kinds of one, which is why they are absent here: an artifact exported
+ * twice is one artifact, and making PDF a kind would make it two things that drift.
+ */
+export const ARTIFACT_KINDS = ["markdown", "html", "json", "csv", "code", "diagram"];
+/**
+ * A rendered export of one artifact version (#134).
+ *
+ * **Not an artifact version.** #133's versions are versions of the *content*; a PDF is a rendering of one.
+ * Making a render a new version would bump `latestVersion` for a reason unrelated to the content, and
+ * "the newest version" would stop meaning "the newest thing the assistant wrote". The issue's wording said
+ * artifact version; this is the deviation, and the reason.
+ *
+ * Keyed on `(artifactId, version, format)`, which is what makes "re-downloaded without re-rendering" a
+ * constraint rather than a cache someone remembers to check.
+ */
+export const EXPORT_FORMATS = ["pdf", "markdown"];
+export const EXPORT_STATES = ["pending", "rendering", "rendered", "failed"];
+// ---------------------------------------------------------------------------
+// Files (`docs/05-knowledge-and-documents.md`, REQ-026). Two ports, not one.
+//
+// `BlobStore` below is `put(value) -> ref` / `get(ref) -> value` — JSON, for spilled tool output. It has
+// no content type, no size and no stream, so it cannot hold a file: bytes through a `jsonb` column means
+// base64, which is the "inject rather than reference" failure the platform forbids everywhere else. #102
+// recorded this in the `0011` migration when it declined to make `blobs` a pointer table.
+//
+// So metadata and bytes are separate ports. They also have genuinely different lifecycles: metadata is
+// transactional and soft-deleted, bytes are eventually deleted by a sweep, and the gap between the two is
+// where orphans live.
+// ---------------------------------------------------------------------------
+/**
+ * Where a file is in its lifecycle.
+ *
+ * `pending` exists because an upload is two writes — metadata, then bytes — and the window between them is
+ * real. A file stuck in `pending` is metadata with no bytes, which is one of the two orphan directions
+ * reconciliation looks for.
+ *
+ * `deleting` is the same window in reverse: the metadata is gone from the user's view and the bytes are
+ * not yet gone from storage. Deleting them in one transaction is not available — object storage does not
+ * join a database transaction — so the intermediate state is named rather than pretended away.
+ */
+export const FILE_STATES = ["pending", "stored", "deleting", "deleted"];
+/**
+ * What a file records about its derived text (#131).
+ *
+ * Declared here rather than imported from `documents/`: a store port that depended on the extraction pipeline
+ * would make the pipeline a prerequisite for storing a file, and `persistence` is the layer nothing above it
+ * gets to reach into.
+ *
+ * Separate from the file's own `state` on purpose. A file is perfectly `stored` while its extraction has
+ * `failed`, and conflating the two would make an unreadable document look like a lost upload.
+ */
+/**
+ * Below this, a recognised extraction is flagged rather than presented as certain (#132).
+ *
+ * Here rather than in `documents/` because two layers interpret the same field and neither may import the
+ * other: `documents/vision.ts` sets the flag, and `files/context.ts` marks the reference line so a model
+ * choosing between attachments knows before it reads any of them. A copy in each is a copy that drifts, and
+ * the port that declares `confidence` is the right place for the number that gives it meaning.
+ *
+ * 0.7 because that is roughly where OCR stops being "a few wrong characters" and becomes "wrong words" — and
+ * a wrong word is worse than a gap, because the sentence still reads.
+ */
+export const LOW_CONFIDENCE_THRESHOLD = 0.7;
+/**
+ * Knowledge chunks and the vector index — REQ-029 (#135).
+ *
+ * Two ports rather than one, because they answer different questions and can be backed by different systems:
+ * `KnowledgeStore` owns the *rows* (content, provenance, which embedding produced them) and `VectorIndex` owns
+ * the *similarity search*. A deployment on pgvector satisfies both with one table; a deployment on a dedicated
+ * vector database satisfies them with two systems, and nothing above this layer changes.
+ *
+ * **The authorisation subject is on the chunk row.** That is the single most important decision here. The SPEC
+ * says filtering happens *inside* the query, and the reason is precise: filtering after retrieval leaks through
+ * result counts. Ask for ten chunks, get three back, and you have learned that seven exist that you may not
+ * see — and with a few queries, roughly what they are about. So `authSubject` travels with the chunk and every
+ * search takes it as a required filter.
+ */
+/**
+ * The embedding width every adapter stores.
+ *
+ * On the port, not in an adapter, for the reason `DEFAULT_SESSION_STATE_MAX_BYTES` is (#97): a vector column has
+ * one width and a vector index cannot span widths, so "every adapter agrees on the size" must be a property
+ * rather than a coincidence. The reference adapter accepted 768 while pgvector refused it, which is exactly the
+ * laxness that turns a production write failure into a passing test.
+ *
+ * 1536 is OpenAI's `text-embedding-3-small` and `-large` at its default reduction, and Cohere's v3 — the sizes
+ * a deployment is most likely to have. Changing it is a **migration**, not a re-index, which is why
+ * `EmbeddingModelRef` carries `dimensions` and a mismatch is refused rather than queued for re-embedding.
+ */
+export const EMBEDDING_DIMENSIONS = 1536;
+export const KNOWLEDGE_SOURCE_TYPES = ["file", "artifact", "message", "external"];
+/**
+ * The floor above which a vector hit is worth having (#136).
+ *
+ * 0.5 is orthogonal — see `VectorSearchHit.score` — so anything at or below it shares nothing with the query.
+ * 0.55 is comfortably above that and still admits a weak-but-real match. Without a floor, retrieval always
+ * returns *something*, and a model handed the least-bad chunk cites it: this constant is what makes an honest
+ * empty result possible at all.
+ *
+ * Deliberately absolute, unlike the fusion floor which is relative to the best hit. They answer different
+ * questions — "is this hit any good" and "is this hit much worse than the best" — and one instrument cannot do
+ * both: a relative floor can never reject a result set that is uniformly poor, because something is always the
+ * best of it.
+ */
+export const SEMANTIC_RELEVANCE_FLOOR = 0.55;
+/**
+ * Words a keyword query drops (#136).
+ *
+ * On the port, like `EMBEDDING_DIMENSIONS`, because both adapters need the same list and a copy in each is a
+ * copy that drifts.
+ *
+ * **Why the query and not the index.** Postgres's `simple` text configuration is chosen deliberately over
+ * `english`: `english` stems, and stemming is exactly what destroys `ERR-4021` and `Q3-2026` — the terms
+ * keyword retrieval exists to find. But `simple` also keeps stopwords, so `was the site down` matches whichever
+ * document says `the` most often. Found by measuring hybrid against semantic-only, where a decoy sharing only
+ * `was` and `the` outranked the document that actually answered the question.
+ *
+ * Stripping them from the *query* keeps identifiers intact in the index while removing the terms that carry no
+ * retrieval signal. Small and English-only, which is honest: a deployment in another language needs its own
+ * list, and pretending otherwise would be worse than the list being visibly incomplete.
+ */
+export const KEYWORD_STOPWORDS = new Set([
+    "a", "about", "all", "also", "an", "and", "any", "are", "as", "at", "be", "been", "but", "by", "can",
+    "did", "do", "does", "for", "from", "had", "has", "have", "how", "i", "if", "in", "into", "is", "it",
+    "its", "just", "me", "my", "no", "not", "of", "on", "or", "our", "out", "over", "so", "some", "than",
+    "that", "the", "their", "them", "then", "there", "these", "they", "this", "to", "up", "us", "was",
+    "we", "were", "what", "when", "where", "which", "who", "why", "will", "with", "would", "you", "your",
+]);
+/**
+ * A keyword query with its stopwords removed.
+ *
+ * Returns the empty string when nothing survives, which callers treat as "no query" — a search for `the` is a
+ * search for nothing, and returning every document would be the worst possible answer.
+ */
+export const stripStopwords = (query) => (query.toLowerCase().match(/[a-z0-9]+(?:-[a-z0-9]+)*/g) ?? [])
+    .filter((term) => !KEYWORD_STOPWORDS.has(term))
+    .join(" ");
+export const ADAPTER_CAPABILITIES = [
+    "transactions",
+    "row-level-security",
+    "full-text-search",
+    "vector-search",
+    "realtime",
+    "distributed-locking",
+    "durable-jobs",
+];
+//# sourceMappingURL=index.js.map

package/dist/principal-memory/index.d.ts

@@ -0,0 +1,106 @@
+/**
+ * User-level (principal) memory — `docs/15` (referenced by REQ-006).
+ *
+ * Durable working memory scoped to a principal within a tenant: it persists across that principal's
+ * conversations, and is never visible to another principal or tenant. Memories are *extracted* from
+ * model output through a deterministic, validated, deduplicated step — raw model output is never
+ * stored directly. A budgeted context provider retrieves only the relevant entries and tags each
+ * with its provenance, so the context inspector can attribute which memories influenced a turn, and
+ * so it can never crowd out recent turns or session state (it draws from the user-context bucket).
+ */
+import { AgentPlatformError } from "../core/errors.js";
+import type { ExecutionContext, Page, PageRequest, TenantScope } from "../core/context.js";
+import type { PrincipalId } from "../core/ids.js";
+import type { ContextProvider } from "../context/index.js";
+export type PrincipalMemoryEntry = {
+    readonly id: string;
+    readonly tenantId: string;
+    readonly principalId: string;
+    readonly text: string;
+    readonly tags: readonly string[];
+    /** Higher wins when retrieval is budget-limited. */
+    readonly salience: number;
+    readonly version: number;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    /** Set when the user disables the entry; disabled entries are never retrieved for prompts. */
+    readonly disabledAt?: string;
+};
+export type MemoryPatch = {
+    readonly text?: string;
+    readonly tags?: readonly string[];
+    readonly salience?: number;
+    /** true disables, false re-enables. */
+    readonly disabled?: boolean;
+};
+/**
+ * Principal-scoped memory. Every method takes `{ tenantId, principalId }` explicitly, so a query can
+ * never reach another principal's or tenant's memory. `delete` is a hard delete — a deleted entry
+ * cannot resurface in a later prompt.
+ */
+export interface PrincipalMemoryStore {
+    put(input: TenantScope & {
+        principalId: PrincipalId;
+        id?: string;
+        text: string;
+        tags?: readonly string[];
+        salience?: number;
+    }): Promise<PrincipalMemoryEntry>;
+    get(input: TenantScope & {
+        principalId: PrincipalId;
+        id: string;
+    }): Promise<PrincipalMemoryEntry | null>;
+    list(input: TenantScope & {
+        principalId: PrincipalId;
+    } & PageRequest): Promise<Page<PrincipalMemoryEntry>>;
+    update(input: TenantScope & {
+        principalId: PrincipalId;
+        id: string;
+        expectedVersion: number;
+        patch: MemoryPatch;
+    }): Promise<PrincipalMemoryEntry>;
+    delete(input: TenantScope & {
+        principalId: PrincipalId;
+        id: string;
+    }): Promise<void>;
+    /** Active (not disabled) entries relevant to `query`, most salient first, capped at `limit`. */
+    retrieve(input: TenantScope & {
+        principalId: PrincipalId;
+        query?: string;
+        limit: number;
+    }): Promise<readonly PrincipalMemoryEntry[]>;
+}
+export declare const MEMORY_LIMITS: {
+    readonly textMaxLength: 1000;
+    readonly maxTagsPerEntry: 8;
+};
+export type MemoryCandidate = {
+    readonly text: string;
+    readonly tags?: readonly string[];
+    readonly salience?: number;
+};
+/**
+ * The deterministic gate between model output and durable memory: trims, enforces bounds, and dedupes
+ * candidates against each other and existing entries by normalized text. Returns the accepted
+ * candidates to commit — so raw model output is never stored, only validated, unique memories.
+ */
+export declare const validateAndDedupe: (candidates: readonly MemoryCandidate[], existing: readonly PrincipalMemoryEntry[]) => readonly MemoryCandidate[];
+/** Commit extracted candidates, skipping duplicates. Returns the entries actually stored. */
+export declare const commitExtractedMemories: (store: PrincipalMemoryStore, input: TenantScope & {
+    principalId: PrincipalId;
+    candidates: readonly MemoryCandidate[];
+}) => Promise<readonly PrincipalMemoryEntry[]>;
+/**
+ * A budgeted context provider over principal memory. Retrieves only relevant, active entries under
+ * `maxEntries`, and emits them as `user-context` sections — so they never crowd out recent turns
+ * (history bucket) or session state. Each section's provenance carries the entry id for attribution.
+ */
+export declare const createPrincipalMemoryProvider: (config: {
+    readonly store: PrincipalMemoryStore;
+    readonly maxEntries?: number;
+    readonly estimateTokens?: (text: string) => number;
+    /** Optional query derived from the turn (e.g. the latest user message) to focus retrieval. */
+    readonly queryOf?: (context: ExecutionContext) => string | undefined;
+}) => ContextProvider;
+export declare const memoryConflict: (message: string) => AgentPlatformError;
+//# sourceMappingURL=index.d.ts.map

package/dist/principal-memory/index.js

@@ -0,0 +1,89 @@
+/**
+ * User-level (principal) memory — `docs/15` (referenced by REQ-006).
+ *
+ * Durable working memory scoped to a principal within a tenant: it persists across that principal's
+ * conversations, and is never visible to another principal or tenant. Memories are *extracted* from
+ * model output through a deterministic, validated, deduplicated step — raw model output is never
+ * stored directly. A budgeted context provider retrieves only the relevant entries and tags each
+ * with its provenance, so the context inspector can attribute which memories influenced a turn, and
+ * so it can never crowd out recent turns or session state (it draws from the user-context bucket).
+ */
+import { AgentPlatformError } from "../core/errors.js";
+import { estimateTokens } from "../core/tokens.js";
+export const MEMORY_LIMITS = { textMaxLength: 1_000, maxTagsPerEntry: 8 };
+const normalize = (text) => text.trim().toLowerCase().replace(/\s+/g, " ");
+/**
+ * The deterministic gate between model output and durable memory: trims, enforces bounds, and dedupes
+ * candidates against each other and existing entries by normalized text. Returns the accepted
+ * candidates to commit — so raw model output is never stored, only validated, unique memories.
+ */
+export const validateAndDedupe = (candidates, existing) => {
+    const seen = new Set(existing.map((e) => normalize(e.text)));
+    const accepted = [];
+    for (const candidate of candidates) {
+        const text = candidate.text.trim();
+        if (text.length === 0 || text.length > MEMORY_LIMITS.textMaxLength)
+            continue;
+        const key = normalize(text);
+        if (seen.has(key))
+            continue; // duplicate of an existing or already-accepted memory
+        seen.add(key);
+        const tags = (candidate.tags ?? []).slice(0, MEMORY_LIMITS.maxTagsPerEntry);
+        accepted.push({ text, tags, ...(candidate.salience === undefined ? {} : { salience: candidate.salience }) });
+    }
+    return accepted;
+};
+/** Commit extracted candidates, skipping duplicates. Returns the entries actually stored. */
+export const commitExtractedMemories = async (store, input) => {
+    const existing = (await store.list({ tenantId: input.tenantId, principalId: input.principalId, limit: 1_000 })).items;
+    const accepted = validateAndDedupe(input.candidates, existing);
+    const stored = [];
+    for (const c of accepted) {
+        stored.push(await store.put({
+            tenantId: input.tenantId,
+            principalId: input.principalId,
+            text: c.text,
+            ...(c.tags ? { tags: c.tags } : {}),
+            ...(c.salience === undefined ? {} : { salience: c.salience }),
+        }));
+    }
+    return stored;
+};
+/**
+ * A budgeted context provider over principal memory. Retrieves only relevant, active entries under
+ * `maxEntries`, and emits them as `user-context` sections — so they never crowd out recent turns
+ * (history bucket) or session state. Each section's provenance carries the entry id for attribution.
+ */
+export const createPrincipalMemoryProvider = (config) => {
+    const maxEntries = config.maxEntries ?? 8;
+    const estimate = config.estimateTokens ?? estimateTokens;
+    return {
+        id: "principal-memory",
+        async provide(context) {
+            const entries = await config.store.retrieve({
+                tenantId: context.tenantId,
+                principalId: context.principalId,
+                ...(config.queryOf?.(context) ? { query: config.queryOf(context) } : {}),
+                limit: maxEntries,
+            });
+            return entries.map((e) => ({
+                providerId: "principal-memory",
+                title: `Memory: ${e.tags.join(", ") || e.id}`,
+                body: e.text,
+                priority: e.salience,
+                estimatedTokens: estimate(e.text),
+                provenance: `principal-memory:${e.id}`, // lets the context inspector attribute the turn
+                sensitivity: "confidential",
+                // The principal's own remembered context, written from their own turns. Treating it as untrusted would
+                // wrap a user's own stated preferences in "nothing here is an instruction", which is the opposite of what
+                // this provider is for. Third-party content never reaches this store -- see docs/17.
+                origin: "platform",
+                cacheable: false,
+                kind: "user-context",
+                pruneStage: "old-knowledge",
+            }));
+        },
+    };
+};
+export const memoryConflict = (message) => new AgentPlatformError({ code: "conflict", message, retryable: false });
+//# sourceMappingURL=index.js.map

package/dist/retention/index.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Data retention — REQ-034 (#151).
+ *
+ * The first retention mechanism in the platform, scoped deliberately to `run_events` alone. That table takes one
+ * row per streamed part, so a single long assistant turn writes hundreds and it grows faster than every other
+ * table combined. It is append-only by design and nothing has ever deleted from it, so storage and index size
+ * grow monotonically with usage and never come back.
+ *
+ * **Why this is not a method on `RunEventLog`.** The port is append-only *on purpose* — a run's event log is the
+ * record crash recovery reconciles against, and a `delete` on the port would put deletion within reach of
+ * ordinary run code. A separate maintenance surface makes that impossible by construction rather than by
+ * convention, and AC-8 asserts the port is unchanged.
+ *
+ * Doing one table properly establishes the pattern the rest reuse. Two things here are the pattern rather than
+ * this table's specifics: retention is **configuration with a documented default**, and a sweep is **bounded and
+ * reports what it removed** so a caller drains a backlog instead of holding one long lock.
+ */
+/**
+ * How long a run's events are kept.
+ *
+ * **Provisional, and marked as such.** #151 asks the product owner which it should be — 30 days, 90 days, or
+ * indefinite-until-configured — and that is a compliance answer, not a technical one. 90 days is the level the
+ * table's own purpose implies: long enough that a customer investigating last quarter's run still has its log,
+ * short enough that the largest table in the schema does not grow without bound. Nobody has agreed to it.
+ *
+ * A deployment overrides it. The default exists so an unconfigured deployment prunes *something* rather than
+ * nothing — the failure direction being "an old log was removed" rather than "the disk filled".
+ */
+export declare const DEFAULT_RUN_EVENT_RETENTION_DAYS = 90;
+/**
+ * The statuses whose events may be pruned.
+ *
+ * Terminal only, and this is the safety property AC-2 names. A `running`, `queued`, `waiting-for-*` or
+ * `retry-pending` run can still be reconciled against its log — that is precisely what #93/#94 exist to provide
+ * — so deleting its events breaks crash recovery for a run that is still alive. Age is irrelevant to that: a
+ * run waiting on a human approval for four months is old *and* still needs its log.
+ *
+ * Written here rather than inlined in SQL so the list has one home, and so a new non-terminal status cannot
+ * silently become prunable by not being mentioned.
+ */
+export declare const PRUNABLE_RUN_STATUSES: readonly string[];
+export type PruneRequest = {
+    /** Delete events created strictly before this instant. ISO-8601. */
+    readonly olderThan: string;
+    /**
+     * Rows per call. Bounded, because an unbounded `DELETE` over this table takes a long-lived lock and blocks the
+     * live appends that are the reason the table exists.
+     */
+    readonly limit: number;
+};
+export type PruneResult = {
+    /**
+     * Rows actually removed.
+     *
+     * The caller's loop condition. Returning it rather than a boolean is what lets `drain` know whether a full
+     * batch means "more to do" — and it is the number an operator needs to see that retention is running at all.
+     */
+    readonly deleted: number;
+};
+/**
+ * The maintenance surface. Narrow on purpose: one operation, and nothing that reads or writes a run.
+ */
+export interface RunEventPruner {
+    prune(input: PruneRequest): Promise<PruneResult>;
+}
+/** The cutoff for a retention period, from a clock. Exported so a caller does not recompute the arithmetic. */
+export declare const cutoffFor: (input: {
+    readonly now: number;
+    readonly retentionDays: number;
+}) => string;
+/**
+ * Drain a backlog by calling `prune` until it stops removing rows.
+ *
+ * A helper rather than a loop inside `prune`, because the two have different failure modes: one long call that
+ * dies halfway leaves an operator with no idea how far it got, whereas a loop over bounded calls has made
+ * durable progress after every iteration.
+ *
+ * `maxBatches` is a required ceiling, not an optional one. A loop whose termination depends on the database
+ * eventually returning zero is a loop that runs forever the day a bug makes `prune` return a positive count
+ * without deleting anything — and it would run forever *inside a maintenance job*, where nobody is watching.
+ */
+export declare const drain: (pruner: RunEventPruner, input: PruneRequest & {
+    readonly maxBatches: number;
+}) => Promise<{
+    readonly deleted: number;
+    readonly batches: number;
+    readonly drained: boolean;
+}>;
+//# sourceMappingURL=index.d.ts.map

package/dist/retention/index.js

@@ -0,0 +1,70 @@
+/**
+ * Data retention — REQ-034 (#151).
+ *
+ * The first retention mechanism in the platform, scoped deliberately to `run_events` alone. That table takes one
+ * row per streamed part, so a single long assistant turn writes hundreds and it grows faster than every other
+ * table combined. It is append-only by design and nothing has ever deleted from it, so storage and index size
+ * grow monotonically with usage and never come back.
+ *
+ * **Why this is not a method on `RunEventLog`.** The port is append-only *on purpose* — a run's event log is the
+ * record crash recovery reconciles against, and a `delete` on the port would put deletion within reach of
+ * ordinary run code. A separate maintenance surface makes that impossible by construction rather than by
+ * convention, and AC-8 asserts the port is unchanged.
+ *
+ * Doing one table properly establishes the pattern the rest reuse. Two things here are the pattern rather than
+ * this table's specifics: retention is **configuration with a documented default**, and a sweep is **bounded and
+ * reports what it removed** so a caller drains a backlog instead of holding one long lock.
+ */
+/**
+ * How long a run's events are kept.
+ *
+ * **Provisional, and marked as such.** #151 asks the product owner which it should be — 30 days, 90 days, or
+ * indefinite-until-configured — and that is a compliance answer, not a technical one. 90 days is the level the
+ * table's own purpose implies: long enough that a customer investigating last quarter's run still has its log,
+ * short enough that the largest table in the schema does not grow without bound. Nobody has agreed to it.
+ *
+ * A deployment overrides it. The default exists so an unconfigured deployment prunes *something* rather than
+ * nothing — the failure direction being "an old log was removed" rather than "the disk filled".
+ */
+export const DEFAULT_RUN_EVENT_RETENTION_DAYS = 90;
+/**
+ * The statuses whose events may be pruned.
+ *
+ * Terminal only, and this is the safety property AC-2 names. A `running`, `queued`, `waiting-for-*` or
+ * `retry-pending` run can still be reconciled against its log — that is precisely what #93/#94 exist to provide
+ * — so deleting its events breaks crash recovery for a run that is still alive. Age is irrelevant to that: a
+ * run waiting on a human approval for four months is old *and* still needs its log.
+ *
+ * Written here rather than inlined in SQL so the list has one home, and so a new non-terminal status cannot
+ * silently become prunable by not being mentioned.
+ */
+export const PRUNABLE_RUN_STATUSES = ["completed", "failed", "cancelled"];
+/** The cutoff for a retention period, from a clock. Exported so a caller does not recompute the arithmetic. */
+export const cutoffFor = (input) => new Date(input.now - input.retentionDays * 86_400_000).toISOString();
+/**
+ * Drain a backlog by calling `prune` until it stops removing rows.
+ *
+ * A helper rather than a loop inside `prune`, because the two have different failure modes: one long call that
+ * dies halfway leaves an operator with no idea how far it got, whereas a loop over bounded calls has made
+ * durable progress after every iteration.
+ *
+ * `maxBatches` is a required ceiling, not an optional one. A loop whose termination depends on the database
+ * eventually returning zero is a loop that runs forever the day a bug makes `prune` return a positive count
+ * without deleting anything — and it would run forever *inside a maintenance job*, where nobody is watching.
+ */
+export const drain = async (pruner, input) => {
+    let deleted = 0;
+    let batches = 0;
+    for (; batches < input.maxBatches; batches += 1) {
+        const result = await pruner.prune({ olderThan: input.olderThan, limit: input.limit });
+        deleted += result.deleted;
+        // A short batch means the backlog is exhausted. Checking the count rather than issuing one more empty call
+        // saves a full index scan per drain, which on this table is not free.
+        if (result.deleted < input.limit)
+            return { deleted, batches: batches + 1, drained: true };
+    }
+    // `drained: false` says the ceiling was hit, so a caller can log that there is more to do rather than assuming
+    // the table is clean. Silence here would look identical to a finished sweep.
+    return { deleted, batches, drained: false };
+};
+//# sourceMappingURL=index.js.map

package/dist/runtime/checkpoint.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Run checkpoints — `docs/04-durable-runtime-and-hitl.md` → Durable execution.
+ *
+ * A checkpoint is the durable snapshot the worker writes as a run streams. It is what lets a page
+ * refresh lose no output and a crashed worker recover: a new claim reloads the latest checkpoint,
+ * finalizes any tool calls that were mid-flight, and continues from there.
+ */
+import type { MessagePart } from "../core/content-parts.js";
+import type { RunId, ToolCallId } from "../core/ids.js";
+/** A tool call the runtime started but has not yet seen complete — reconciled on recovery. */
+export type PendingToolCall = {
+    readonly toolCallId: ToolCallId;
+    readonly toolName: string;
+    readonly startedAt: string;
+};
+/** Running token/cost totals, checkpointed so a recovered run keeps accounting continuity. */
+export type RunUsageTotals = {
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly costMinorUnits: number;
+};
+export declare const EMPTY_USAGE_TOTALS: RunUsageTotals;
+export type RunCheckpoint = {
+    readonly runId: RunId;
+    /** Highest event sequence durably persisted. A reconnecting client resumes with `after: sequence`. */
+    readonly sequence: number;
+    /** Accumulated parts of the assistant message being produced, in order. */
+    readonly parts: readonly MessagePart[];
+    /** Step index reached in the agent loop, bounded by `ExecutionLimits.maxSteps`. */
+    readonly step: number;
+    /** Tool calls started but not yet completed. Non-empty after a crash → finalized on recovery. */
+    readonly pendingToolCalls: readonly PendingToolCall[];
+    readonly usage: RunUsageTotals;
+    readonly updatedAt: string;
+};
+export declare const emptyCheckpoint: (runId: RunId, updatedAt: string) => RunCheckpoint;
+//# sourceMappingURL=checkpoint.d.ts.map

package/dist/runtime/checkpoint.js

@@ -0,0 +1,22 @@
+/**
+ * Run checkpoints — `docs/04-durable-runtime-and-hitl.md` → Durable execution.
+ *
+ * A checkpoint is the durable snapshot the worker writes as a run streams. It is what lets a page
+ * refresh lose no output and a crashed worker recover: a new claim reloads the latest checkpoint,
+ * finalizes any tool calls that were mid-flight, and continues from there.
+ */
+export const EMPTY_USAGE_TOTALS = {
+    inputTokens: 0,
+    outputTokens: 0,
+    costMinorUnits: 0,
+};
+export const emptyCheckpoint = (runId, updatedAt) => ({
+    runId,
+    sequence: 0,
+    parts: [],
+    step: 0,
+    pendingToolCalls: [],
+    usage: EMPTY_USAGE_TOTALS,
+    updatedAt,
+});
+//# sourceMappingURL=checkpoint.js.map