@retinue/agentkit 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,103 @@
+/**
+ * `@retinue/agentkit`
+ *
+ * The root is the **semver boundary** (REQ-040): what is exported here is API, and what is not exported here
+ * cannot be broken. That is why there are five values on it rather than three hundred and ninety-two.
+ *
+ * ## The rule
+ *
+ * **The root exports what a host uses on its first day; everything else is behind a documented subpath.**
+ *
+ * The root used to be every `create*` in the package, and nothing in the shape distinguished the four calls a
+ * host makes from the three hundred an adapter author makes once. A surface that large is not a promise anyone
+ * can keep: every name on it is something we cannot remove without a major version, including the ones nobody
+ * outside this repository has ever called.
+ *
+ * ## Types stay, and cost nothing
+ *
+ * Every type in the package is still exported from here, by `export type *` — which emits no import at all, so
+ * the root's runtime weight is unchanged (`ai` and `zod`, asserted by `root-import-weight.test.ts`). Types could
+ * not be subpathed without making the package unusable: a consumer holding an `ExecutionContext` should not have
+ * to know which layer defined it, and a type cannot be broken by being imported.
+ *
+ * So the split is: **types by subject, values by consumer**.
+ *
+ * ## Where everything went
+ *
+ * | Subpath | Who calls it |
+ * |---|---|
+ * | `./runtime` | A host composing its own engine rather than taking `createRuntime`'s defaults |
+ * | `./tools` | Anyone writing or dispatching a tool, plus the first-party library |
+ * | `./persistence` | A host wiring storage, and anything using the in-memory adapters |
+ * | `./context` | Prompt assembly, skills, per-principal memory, citations |
+ * | `./knowledge` | Retrieval, documents, files, artifacts, export |
+ * | `./hitl` | Approvals, questions, authorization |
+ * | `./usage` | Spend, quotas, rollups |
+ * | `./mcp` | Importing another server's tools |
+ * | `./observability` | Telemetry, retention, the security review, the harnesses |
+ * | `./server` | The reference GraphQL host, the SSE route, the worker |
+ * | `./providers` | The model providers |
+ * | `./adapters/{postgres,redis,bullmq,otel}` | One driver each |
+ */
+export type * from "./core/index.js";
+export type * from "./capabilities/index.js";
+export type * from "./capabilities/runtime.js";
+export type * from "./models/index.js";
+export type * from "./agents/index.js";
+export type * from "./runtime/index.js";
+export type * from "./tools/index.js";
+export type * from "./tools/library/index.js";
+export type * from "./toolkit/index.js";
+export type * from "./mcp/index.js";
+export type * from "./authorization/index.js";
+export type * from "./usage/index.js";
+export type * from "./idempotency/index.js";
+export type * from "./skills/index.js";
+export type * from "./context/index.js";
+export type * from "./hitl/index.js";
+export type * from "./persistence/index.js";
+export type * from "./adapters/memory/index.js";
+export type * from "./worker/main.js";
+export type * from "./worker/extraction.js";
+export type * from "./worker/export.js";
+export type * from "./principal-memory/index.js";
+export type * from "./files/index.js";
+export type * from "./files/context.js";
+export type * from "./files/read-tool.js";
+export type * from "./files/turn-parts.js";
+export type * from "./documents/index.js";
+export type * from "./artifacts/index.js";
+export type * from "./export/index.js";
+export type * from "./export/pdf.js";
+export type * from "./export/markdown.js";
+export type * from "./knowledge/index.js";
+export type * from "./citations/index.js";
+export type * from "./evaluation/index.js";
+export type * from "./telemetry/index.js";
+export type * from "./security/index.js";
+export type * from "./retention/index.js";
+export type * from "./loadtest/index.js";
+export type * from "./flows/index.js";
+export type * from "./flows/interpreter.js";
+export type * from "./flows/runner.js";
+export type * from "./teams/index.js";
+export type * from "./graphql/index.js";
+/**
+ * The five.
+ *
+ * - `createRuntime` composes one and gates access to what was actually wired.
+ * - `resolveCapabilities` is how a host declares what it enables, and is cross-checked against the wiring in
+ *   both directions — a capability declared and unwired is as much a bug as one wired and undeclared.
+ * - `defineAgent` declares the agent. `defineTool` is deliberately *not* here: an agent is the thing you
+ *   declare, a tool is a component of one, and everything about tools is at `./tools`.
+ * - `asId` builds a branded id. Every other export takes one, so a consumer that could not build one would be
+ *   reduced to casting — which is opting out of the guarantee for everybody downstream.
+ * - `AgentPlatformError` and its guard are what a consumer catches. An error class reachable only by subpath
+ *   means a `catch` block importing from somewhere the happy path never mentions.
+ */
+export { createRuntime } from "./capabilities/runtime.js";
+export { resolveCapabilities } from "./capabilities/index.js";
+export { defineAgent } from "./agents/define.js";
+export { asId } from "./core/ids.js";
+export { AgentPlatformError, isAgentPlatformError } from "./core/errors.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,60 @@
+/**
+ * `@retinue/agentkit`
+ *
+ * The root is the **semver boundary** (REQ-040): what is exported here is API, and what is not exported here
+ * cannot be broken. That is why there are five values on it rather than three hundred and ninety-two.
+ *
+ * ## The rule
+ *
+ * **The root exports what a host uses on its first day; everything else is behind a documented subpath.**
+ *
+ * The root used to be every `create*` in the package, and nothing in the shape distinguished the four calls a
+ * host makes from the three hundred an adapter author makes once. A surface that large is not a promise anyone
+ * can keep: every name on it is something we cannot remove without a major version, including the ones nobody
+ * outside this repository has ever called.
+ *
+ * ## Types stay, and cost nothing
+ *
+ * Every type in the package is still exported from here, by `export type *` — which emits no import at all, so
+ * the root's runtime weight is unchanged (`ai` and `zod`, asserted by `root-import-weight.test.ts`). Types could
+ * not be subpathed without making the package unusable: a consumer holding an `ExecutionContext` should not have
+ * to know which layer defined it, and a type cannot be broken by being imported.
+ *
+ * So the split is: **types by subject, values by consumer**.
+ *
+ * ## Where everything went
+ *
+ * | Subpath | Who calls it |
+ * |---|---|
+ * | `./runtime` | A host composing its own engine rather than taking `createRuntime`'s defaults |
+ * | `./tools` | Anyone writing or dispatching a tool, plus the first-party library |
+ * | `./persistence` | A host wiring storage, and anything using the in-memory adapters |
+ * | `./context` | Prompt assembly, skills, per-principal memory, citations |
+ * | `./knowledge` | Retrieval, documents, files, artifacts, export |
+ * | `./hitl` | Approvals, questions, authorization |
+ * | `./usage` | Spend, quotas, rollups |
+ * | `./mcp` | Importing another server's tools |
+ * | `./observability` | Telemetry, retention, the security review, the harnesses |
+ * | `./server` | The reference GraphQL host, the SSE route, the worker |
+ * | `./providers` | The model providers |
+ * | `./adapters/{postgres,redis,bullmq,otel}` | One driver each |
+ */
+/**
+ * The five.
+ *
+ * - `createRuntime` composes one and gates access to what was actually wired.
+ * - `resolveCapabilities` is how a host declares what it enables, and is cross-checked against the wiring in
+ *   both directions — a capability declared and unwired is as much a bug as one wired and undeclared.
+ * - `defineAgent` declares the agent. `defineTool` is deliberately *not* here: an agent is the thing you
+ *   declare, a tool is a component of one, and everything about tools is at `./tools`.
+ * - `asId` builds a branded id. Every other export takes one, so a consumer that could not build one would be
+ *   reduced to casting — which is opting out of the guarantee for everybody downstream.
+ * - `AgentPlatformError` and its guard are what a consumer catches. An error class reachable only by subpath
+ *   means a `catch` block importing from somewhere the happy path never mentions.
+ */
+export { createRuntime } from "./capabilities/runtime.js";
+export { resolveCapabilities } from "./capabilities/index.js";
+export { defineAgent } from "./agents/define.js";
+export { asId } from "./core/ids.js";
+export { AgentPlatformError, isAgentPlatformError } from "./core/errors.js";
+//# sourceMappingURL=index.js.map

package/dist/knowledge/chunking.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Chunking extracted documents for retrieval (#135).
+ *
+ * The input is #131's `DocumentBlock[]`, which is the whole payoff of extracting to structure rather than a
+ * flat string: a chunker that only sees text has to guess where a section ends, and a chunker that sees blocks
+ * knows.
+ *
+ * Three decisions, each with a failure it avoids:
+ *
+ * - **Chunks respect block boundaries.** A chunk never starts mid-sentence or mid-table, because a retrieved
+ *   fragment is quoted to a user and a half-sentence quoted as a citation is worse than no citation.
+ * - **A table is one chunk, whole.** Splitting a table separates a number from its column header, and a number
+ *   without its header is the specific failure this platform's extraction design exists to avoid — see #131.
+ *   A table too large for one chunk is split *by rows with its header repeated*, so every piece still says what
+ *   its columns mean.
+ * - **The nearest preceding heading is prepended** to every chunk. "Revenue rose 9%" is unretrievable on its
+ *   own and retrievable as "By region / EMEA / Revenue rose 9%" — and it is what makes a hit explicable.
+ *
+ * Overlap is by *block*, not by character: overlapping mid-sentence produces two chunks that both contain half
+ * a thought and neither contains the whole one.
+ */
+import type { DocumentBlock } from "../documents/index.js";
+export type ChunkingLimits = {
+    /** Target size in tokens. Chunks land near this, never far above it. */
+    readonly targetTokens: number;
+    /**
+     * Hard ceiling. A single block larger than this is split; nothing else is.
+     *
+     * Separate from the target because a block is indivisible in the good case, so "aim for 400" and "never
+     * exceed 800" are different statements and collapsing them would either split freely or overflow freely.
+     */
+    readonly maxTokens: number;
+    /** Blocks repeated at the start of the next chunk, so a thought spanning a boundary is retrievable. */
+    readonly overlapBlocks: number;
+};
+export declare const DEFAULT_CHUNKING_LIMITS: ChunkingLimits;
+/**
+ * A token estimate — one definition, in `core/tokens.ts`.
+ *
+ * Shared with the context assembler on purpose: a chunk sized against one estimate and budgeted against a
+ * different one is a chunk that does not fit the budget it was measured for.
+ */
+export type Chunk = {
+    readonly index: number;
+    readonly content: string;
+    readonly tokenCount: number;
+    /** The heading path this chunk sits under, for a citation that resolves. */
+    readonly locator?: string;
+};
+/**
+ * Chunk a document.
+ *
+ * Headings are not chunks of their own — a heading alone retrieves nothing useful. They become the locator and
+ * the prefix of the chunks beneath them, which is what makes an isolated sentence findable.
+ */
+export declare const chunkDocument: (blocks: readonly DocumentBlock[], limits?: ChunkingLimits) => readonly Chunk[];
+//# sourceMappingURL=chunking.d.ts.map

package/dist/knowledge/chunking.js

@@ -0,0 +1,158 @@
+/**
+ * Chunking extracted documents for retrieval (#135).
+ *
+ * The input is #131's `DocumentBlock[]`, which is the whole payoff of extracting to structure rather than a
+ * flat string: a chunker that only sees text has to guess where a section ends, and a chunker that sees blocks
+ * knows.
+ *
+ * Three decisions, each with a failure it avoids:
+ *
+ * - **Chunks respect block boundaries.** A chunk never starts mid-sentence or mid-table, because a retrieved
+ *   fragment is quoted to a user and a half-sentence quoted as a citation is worse than no citation.
+ * - **A table is one chunk, whole.** Splitting a table separates a number from its column header, and a number
+ *   without its header is the specific failure this platform's extraction design exists to avoid — see #131.
+ *   A table too large for one chunk is split *by rows with its header repeated*, so every piece still says what
+ *   its columns mean.
+ * - **The nearest preceding heading is prepended** to every chunk. "Revenue rose 9%" is unretrievable on its
+ *   own and retrievable as "By region / EMEA / Revenue rose 9%" — and it is what makes a hit explicable.
+ *
+ * Overlap is by *block*, not by character: overlapping mid-sentence produces two chunks that both contain half
+ * a thought and neither contains the whole one.
+ */
+import { estimateTokens } from "../core/tokens.js";
+import { renderBlock } from "../documents/render.js";
+export const DEFAULT_CHUNKING_LIMITS = {
+    // ~400 tokens is roughly two paragraphs: large enough to carry an argument, small enough that a hit is
+    // mostly relevant rather than mostly padding.
+    targetTokens: 400,
+    maxTokens: 800,
+    overlapBlocks: 1,
+};
+/** The heading trail at a point in the document, e.g. `Quarterly Review > By region`. */
+const headingPath = (trail) => trail.map((h) => h.text).join(" > ");
+/**
+ * Split one oversized block.
+ *
+ * A table splits by rows with its header repeated; anything else splits by sentence. Sentences rather than
+ * characters because a chunk boundary mid-word is a retrieved fragment that reads as corrupt.
+ */
+const splitBlock = (block, maxTokens) => {
+    if (block.kind === "table") {
+        const header = block.hasHeader ? block.rows[0] : undefined;
+        const body = block.hasHeader ? block.rows.slice(1) : block.rows;
+        const pieces = [];
+        let current = [];
+        const flush = () => {
+            if (current.length === 0)
+                return;
+            pieces.push(renderBlock({
+                kind: "table",
+                rows: header === undefined ? current : [header, ...current],
+                hasHeader: header !== undefined,
+            }));
+            current = [];
+        };
+        for (const row of body) {
+            current.push(row);
+            // The header counts against every piece's budget, which is the price of every piece being readable.
+            const rendered = renderBlock({
+                kind: "table",
+                rows: header === undefined ? current : [header, ...current],
+                hasHeader: header !== undefined,
+            });
+            if (estimateTokens(rendered) >= maxTokens)
+                flush();
+        }
+        flush();
+        return pieces.length === 0 ? [renderBlock(block)] : pieces;
+    }
+    const text = renderBlock(block);
+    // Split after sentence-ending punctuation followed by whitespace. Keeps the punctuation with its sentence.
+    const sentences = text.split(/(?<=[.!?])\s+/);
+    const pieces = [];
+    let current = "";
+    for (const sentence of sentences) {
+        const candidate = current === "" ? sentence : `${current} ${sentence}`;
+        if (estimateTokens(candidate) > maxTokens && current !== "") {
+            pieces.push(current);
+            current = sentence;
+        }
+        else
+            current = candidate;
+    }
+    if (current !== "")
+        pieces.push(current);
+    return pieces.length === 0 ? [text] : pieces;
+};
+/**
+ * Chunk a document.
+ *
+ * Headings are not chunks of their own — a heading alone retrieves nothing useful. They become the locator and
+ * the prefix of the chunks beneath them, which is what makes an isolated sentence findable.
+ */
+export const chunkDocument = (blocks, limits = DEFAULT_CHUNKING_LIMITS) => {
+    const chunks = [];
+    const trail = [];
+    let pending = [];
+    let pendingTokens = 0;
+    const emit = () => {
+        if (pending.length === 0)
+            return;
+        const path = headingPath(trail);
+        // The heading path is prepended, not merely recorded: "Revenue rose 9%" is unretrievable alone and
+        // retrievable as "By region / EMEA / Revenue rose 9%".
+        const body = pending.map((p) => p.rendered).join("\n\n");
+        const content = path === "" ? body : `${path}\n\n${body}`;
+        chunks.push({
+            index: chunks.length,
+            content,
+            tokenCount: estimateTokens(content),
+            ...(path === "" ? {} : { locator: path }),
+        });
+        // Overlap by block, so a thought spanning the boundary appears whole in one of the two chunks. Overlapping
+        // mid-sentence would give two chunks that each contain half a thought and neither the whole one.
+        const overlap = limits.overlapBlocks > 0 ? pending.slice(-limits.overlapBlocks) : [];
+        pending = [...overlap];
+        pendingTokens = overlap.reduce((n, p) => n + estimateTokens(p.rendered), 0);
+    };
+    for (const block of blocks) {
+        if (block.kind === "heading") {
+            // A heading ends the section above it: a chunk spanning two sections would carry the wrong locator for
+            // half its content.
+            emit();
+            pending = [];
+            pendingTokens = 0;
+            while (trail.length > 0 && (trail[trail.length - 1]?.level ?? 0) >= block.level)
+                trail.pop();
+            trail.push({ level: block.level, text: block.text });
+            continue;
+        }
+        const rendered = renderBlock(block);
+        const tokens = estimateTokens(rendered);
+        if (tokens > limits.maxTokens) {
+            // Oversized: flush what is pending, then split this block into pieces that each stand alone.
+            emit();
+            pending = [];
+            pendingTokens = 0;
+            const path = headingPath(trail);
+            for (const piece of splitBlock(block, limits.maxTokens)) {
+                const content = path === "" ? piece : `${path}\n\n${piece}`;
+                chunks.push({
+                    index: chunks.length,
+                    content,
+                    tokenCount: estimateTokens(content),
+                    ...(path === "" ? {} : { locator: path }),
+                });
+            }
+            continue;
+        }
+        if (pendingTokens + tokens > limits.targetTokens && pending.length > 0)
+            emit();
+        pending.push({ rendered, block });
+        pendingTokens += tokens;
+    }
+    emit();
+    // Re-index, because `emit` numbers as it goes and the overlap means the count is not the block count.
+    return chunks.map((c, i) => ({ ...c, index: i }));
+};
+//# sourceMappingURL=chunking.js.map

package/dist/knowledge/index.d.ts

@@ -0,0 +1,119 @@
+/**
+ * The embedding pipeline (#135).
+ *
+ * Chunk, embed in batches, write. What makes it worth a module rather than a loop is the three properties the
+ * ACs are actually about:
+ *
+ * - **Every chunk records the model that embedded it** (AC-1). Not a global "current model" setting: a setting
+ *   cannot tell you which rows are stale, which makes incremental re-indexing impossible.
+ * - **Re-indexing is derived from what is stored** (AC-5). `listStaleSources` asks the database which sources
+ *   were embedded by something other than the current model, so an interrupted re-index resumes by asking
+ *   again rather than by remembering where it was. There is no cursor to lose.
+ * - **Freshness is a stated target, measured** (AC-4). `FRESHNESS_TARGET_MS` is the number, `indexSource`
+ *   reports how long it took, and the test asserts the report against the target rather than against a hope.
+ */
+import type { TenantId } from "../core/ids.js";
+import type { DocumentBlock } from "../documents/index.js";
+import type { EmbeddingModelRef, KnowledgeSourceType, KnowledgeStore } from "../persistence/index.js";
+import { type ChunkingLimits } from "./chunking.js";
+/**
+ * How long newly added material may take to become findable — AC-4.
+ *
+ * Sixty seconds, and the number is a *commitment* rather than an observation: indexing runs on the worker tier,
+ * so the delay is queue latency plus embedding time, and a target far below queue latency would be a promise
+ * the architecture cannot keep. A user who attaches a document and asks about it immediately is the case this
+ * bounds, and a minute is what "shortly" honestly means for a document that has to be read, chunked and
+ * embedded.
+ */
+export declare const FRESHNESS_TARGET_MS = 60000;
+/** Chunks per embedding call. Providers cap batch size; 64 is comfortably inside every one of them. */
+export declare const DEFAULT_EMBEDDING_BATCH = 64;
+/**
+ * Turns text into vectors.
+ *
+ * A port, because the provider differs and because a test needs a deterministic one. `model` is on the provider
+ * rather than passed per call: a provider that could be asked for a different model per call would let two
+ * chunks of one document be embedded differently, and nothing downstream could tell.
+ */
+export interface EmbeddingProvider {
+    readonly model: EmbeddingModelRef;
+    /** One vector per input, in order. A provider returning a different count is a bug worth catching loudly. */
+    embed(texts: readonly string[]): Promise<readonly (readonly number[])[]>;
+}
+export type IndexSourceInput = {
+    readonly sourceType: KnowledgeSourceType;
+    readonly sourceId: string;
+    readonly blocks: readonly DocumentBlock[];
+    /**
+     * Who may retrieve this source's chunks.
+     *
+     * Required. An optional subject would default to something, and the something would either be too narrow
+     * (nothing retrievable) or too wide (everything retrievable by everyone) — and the second failure is silent.
+     */
+    readonly authSubject: string;
+};
+export type IndexResult = {
+    readonly written: number;
+    readonly removed: number;
+    readonly batches: number;
+    /** Wall-clock, so the freshness target can be measured rather than assumed. */
+    readonly elapsedMs: number;
+    readonly model: EmbeddingModelRef;
+};
+export type EmbeddingPipelineDeps = {
+    readonly knowledge: KnowledgeStore;
+    readonly embeddings: EmbeddingProvider;
+    readonly chunking?: ChunkingLimits;
+    readonly batchSize?: number;
+    readonly clock?: () => string;
+    /** Injectable so a test measures elapsed time without waiting for it. */
+    readonly now?: () => number;
+    readonly log?: (message: string, detail?: Readonly<Record<string, unknown>>) => void;
+};
+/** Deterministic chunk id, so re-indexing the same source overwrites its own rows rather than duplicating. */
+export declare const chunkId: (sourceType: string, sourceId: string, index: number) => string;
+export declare const createEmbeddingPipeline: (deps: EmbeddingPipelineDeps) => {
+    model: EmbeddingModelRef;
+    freshnessTargetMs: number;
+    /**
+     * Index one source, replacing whatever was there.
+     *
+     * Replace rather than append: a changed document's old chunks must stop being searchable, because a stale
+     * chunk is a citation pointing at text that is no longer in the document.
+     */
+    indexSource(context: {
+        readonly tenantId: TenantId;
+    }, input: IndexSourceInput): Promise<IndexResult>;
+    /**
+     * One page of a re-index — AC-5.
+     *
+     * Deliberately not a loop over everything. A caller runs this repeatedly and stops when `remaining` is
+     * zero, which means an interruption at any point loses at most one page's work and no bookkeeping: the
+     * next call re-derives the work list from what is stored. There is no cursor to persist and therefore no
+     * cursor to lose.
+     *
+     * `reload` fetches a source's current blocks. It is the caller's, because where a source's content lives
+     * differs by type — an attachment's is an extracted document, an artifact's is its content — and this
+     * module has no business knowing all of them.
+     */
+    reindexBatch(context: {
+        readonly tenantId: TenantId;
+    }, input: {
+        readonly limit: number;
+        readonly reload: (source: {
+            readonly sourceType: KnowledgeSourceType;
+            readonly sourceId: string;
+        }) => Promise<{
+            readonly blocks: readonly DocumentBlock[];
+            readonly authSubject: string;
+        } | null>;
+    }): Promise<{
+        readonly reindexed: number;
+        readonly skipped: number;
+        readonly remaining: number;
+    }>;
+};
+export type EmbeddingPipeline = ReturnType<typeof createEmbeddingPipeline>;
+export * from "./chunking.js";
+export * from "./retrieval.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/knowledge/index.js

@@ -0,0 +1,166 @@
+/**
+ * The embedding pipeline (#135).
+ *
+ * Chunk, embed in batches, write. What makes it worth a module rather than a loop is the three properties the
+ * ACs are actually about:
+ *
+ * - **Every chunk records the model that embedded it** (AC-1). Not a global "current model" setting: a setting
+ *   cannot tell you which rows are stale, which makes incremental re-indexing impossible.
+ * - **Re-indexing is derived from what is stored** (AC-5). `listStaleSources` asks the database which sources
+ *   were embedded by something other than the current model, so an interrupted re-index resumes by asking
+ *   again rather than by remembering where it was. There is no cursor to lose.
+ * - **Freshness is a stated target, measured** (AC-4). `FRESHNESS_TARGET_MS` is the number, `indexSource`
+ *   reports how long it took, and the test asserts the report against the target rather than against a hope.
+ */
+import { AgentPlatformError } from "../core/errors.js";
+import { DEFAULT_CHUNKING_LIMITS, chunkDocument } from "./chunking.js";
+/**
+ * How long newly added material may take to become findable — AC-4.
+ *
+ * Sixty seconds, and the number is a *commitment* rather than an observation: indexing runs on the worker tier,
+ * so the delay is queue latency plus embedding time, and a target far below queue latency would be a promise
+ * the architecture cannot keep. A user who attaches a document and asks about it immediately is the case this
+ * bounds, and a minute is what "shortly" honestly means for a document that has to be read, chunked and
+ * embedded.
+ */
+export const FRESHNESS_TARGET_MS = 60_000;
+/** Chunks per embedding call. Providers cap batch size; 64 is comfortably inside every one of them. */
+export const DEFAULT_EMBEDDING_BATCH = 64;
+/** Deterministic chunk id, so re-indexing the same source overwrites its own rows rather than duplicating. */
+export const chunkId = (sourceType, sourceId, index) => `${sourceType}:${sourceId}:${index}`;
+export const createEmbeddingPipeline = (deps) => {
+    const limits = deps.chunking ?? DEFAULT_CHUNKING_LIMITS;
+    const batchSize = Math.max(1, deps.batchSize ?? DEFAULT_EMBEDDING_BATCH);
+    const clock = deps.clock ?? (() => new Date().toISOString());
+    const now = deps.now ?? (() => Date.now());
+    const log = deps.log ?? (() => { });
+    return {
+        model: deps.embeddings.model,
+        freshnessTargetMs: FRESHNESS_TARGET_MS,
+        /**
+         * Index one source, replacing whatever was there.
+         *
+         * Replace rather than append: a changed document's old chunks must stop being searchable, because a stale
+         * chunk is a citation pointing at text that is no longer in the document.
+         */
+        async indexSource(context, input) {
+            const started = now();
+            const chunks = chunkDocument(input.blocks, limits);
+            if (chunks.length === 0) {
+                // An empty document still removes its old chunks: extracting a document down to nothing is a reason for
+                // its previous content to stop being findable, not a reason to leave it.
+                const cleared = await deps.knowledge.deleteSource({
+                    tenantId: context.tenantId,
+                    sourceType: input.sourceType,
+                    sourceId: input.sourceId,
+                });
+                return {
+                    written: 0,
+                    removed: cleared.removed,
+                    batches: 0,
+                    elapsedMs: now() - started,
+                    model: deps.embeddings.model,
+                };
+            }
+            const embedded = [];
+            let batches = 0;
+            for (let offset = 0; offset < chunks.length; offset += batchSize) {
+                const batch = chunks.slice(offset, offset + batchSize);
+                const vectors = await deps.embeddings.embed(batch.map((c) => c.content));
+                batches += 1;
+                // A provider returning a different count has silently misaligned every vector with the wrong chunk,
+                // which is unrecoverable and undetectable later. Caught here, loudly.
+                if (vectors.length !== batch.length)
+                    throw new AgentPlatformError({
+                        code: "provider_unavailable",
+                        message: `the embedding provider returned ${vectors.length} vectors for ${batch.length} inputs`,
+                        retryable: true,
+                    });
+                batch.forEach((chunk, i) => {
+                    embedded.push({
+                        id: chunkId(input.sourceType, input.sourceId, chunk.index),
+                        sourceType: input.sourceType,
+                        sourceId: input.sourceId,
+                        chunkIndex: chunk.index,
+                        content: chunk.content,
+                        tokenCount: chunk.tokenCount,
+                        authSubject: input.authSubject,
+                        embeddingModel: deps.embeddings.model,
+                        ...(chunk.locator === undefined ? {} : { locator: chunk.locator }),
+                        createdAt: clock(),
+                        embedding: vectors[i] ?? [],
+                    });
+                });
+            }
+            const written = await deps.knowledge.replaceSource({
+                tenantId: context.tenantId,
+                sourceType: input.sourceType,
+                sourceId: input.sourceId,
+                chunks: embedded,
+            });
+            const elapsedMs = now() - started;
+            if (elapsedMs > FRESHNESS_TARGET_MS)
+                // Reported rather than thrown: the material *is* indexed, and the useful action is to know the target
+                // was missed rather than to fail a job that succeeded.
+                log("indexing exceeded the freshness target", {
+                    sourceId: input.sourceId,
+                    elapsedMs,
+                    targetMs: FRESHNESS_TARGET_MS,
+                });
+            return { ...written, batches, elapsedMs, model: deps.embeddings.model };
+        },
+        /**
+         * One page of a re-index — AC-5.
+         *
+         * Deliberately not a loop over everything. A caller runs this repeatedly and stops when `remaining` is
+         * zero, which means an interruption at any point loses at most one page's work and no bookkeeping: the
+         * next call re-derives the work list from what is stored. There is no cursor to persist and therefore no
+         * cursor to lose.
+         *
+         * `reload` fetches a source's current blocks. It is the caller's, because where a source's content lives
+         * differs by type — an attachment's is an extracted document, an artifact's is its content — and this
+         * module has no business knowing all of them.
+         */
+        async reindexBatch(context, input) {
+            const stale = await deps.knowledge.listStaleSources({
+                tenantId: context.tenantId,
+                current: deps.embeddings.model,
+                limit: input.limit,
+            });
+            let reindexed = 0;
+            let skipped = 0;
+            for (const source of stale.items) {
+                const reloaded = await input.reload(source);
+                if (reloaded === null) {
+                    // The source is gone. Its chunks go with it rather than staying stale forever, which would make the
+                    // work list never drain and the re-index never finish.
+                    await deps.knowledge.deleteSource({
+                        tenantId: context.tenantId,
+                        sourceType: source.sourceType,
+                        sourceId: source.sourceId,
+                    });
+                    skipped += 1;
+                    continue;
+                }
+                await this.indexSource(context, {
+                    sourceType: source.sourceType,
+                    sourceId: source.sourceId,
+                    blocks: reloaded.blocks,
+                    authSubject: reloaded.authSubject,
+                });
+                reindexed += 1;
+            }
+            // Asked again rather than computed, because sources may have been added or removed while this page ran —
+            // and a stale "remaining" is how a loop stops early or never stops.
+            const after = await deps.knowledge.listStaleSources({
+                tenantId: context.tenantId,
+                current: deps.embeddings.model,
+                limit: 1,
+            });
+            return { reindexed, skipped, remaining: after.items.length };
+        },
+    };
+};
+export * from "./chunking.js";
+export * from "./retrieval.js";
+//# sourceMappingURL=index.js.map