@retinue/agentkit 0.1.0

package/dist/core/events.js

@@ -0,0 +1,99 @@
+/**
+ * Transport events — `docs/04-durable-runtime-and-hitl.md`.
+ *
+ * Transports map these to GraphQL subscriptions, SSE or another channel without
+ * changing runtime semantics. Events carry a monotonic sequence per run so a client
+ * can resume from a cursor after reconnecting.
+ */
+export const RUN_EVENT_TYPES = [
+    "run.queued",
+    "run.started",
+    "run.checkpointed",
+    "run.completed",
+    "run.failed",
+    "run.cancelled",
+    "run.retry-pending",
+    "part.added",
+    "part.updated",
+    "tool.started",
+    "tool.completed",
+    "tool.failed",
+    "question.requested",
+    "question.answered",
+    "approval.requested",
+    "approval.decided",
+    "usage.updated",
+    "context.compacted",
+];
+export const EMPTY_RUN_STREAM_STATE = {
+    parts: [],
+    pendingToolCalls: [],
+    usage: { inputTokens: 0, outputTokens: 0, costMinorUnits: 0 },
+    sequence: 0,
+    terminal: false,
+};
+/** Fold one event into the projection. Pure; ignores events with a sequence already folded. */
+export const reduceRunEvent = (state, event) => {
+    if (event.sequence <= state.sequence && state.sequence > 0)
+        return state; // idempotent replay
+    const base = {
+        ...state,
+        sequence: event.sequence,
+        lastEventType: event.type,
+        // Any forward progress clears a pending retry banner.
+        ...(event.type === "run.retry-pending" ? {} : { retry: undefined }),
+    };
+    switch (event.type) {
+        case "part.added":
+            return { ...base, parts: [...state.parts, event.part] };
+        case "part.updated": {
+            const exists = state.parts.some((p) => p.id === event.part.id);
+            return {
+                ...base,
+                parts: exists
+                    ? state.parts.map((p) => (p.id === event.part.id ? event.part : p))
+                    : [...state.parts, event.part],
+            };
+        }
+        case "tool.started":
+            return {
+                ...base,
+                pendingToolCalls: [
+                    ...state.pendingToolCalls,
+                    { toolCallId: event.toolCallId, toolName: event.toolName, startedAt: event.occurredAt },
+                ],
+            };
+        case "tool.completed":
+        case "tool.failed":
+            return { ...base, pendingToolCalls: state.pendingToolCalls.filter((t) => t.toolCallId !== event.toolCallId) };
+        case "usage.updated":
+            return {
+                ...base,
+                usage: {
+                    inputTokens: state.usage.inputTokens + event.inputTokens,
+                    outputTokens: state.usage.outputTokens + event.outputTokens,
+                    costMinorUnits: state.usage.costMinorUnits + (event.costMinorUnits ?? 0),
+                },
+            };
+        case "run.retry-pending":
+            return {
+                ...base,
+                retry: { attempt: event.attempt, maxAttempts: event.maxAttempts, nextAttemptAt: event.nextAttemptAt },
+            };
+        case "run.failed":
+            return { ...base, error: event.error, terminal: true };
+        case "run.completed":
+        case "run.cancelled":
+            return { ...base, terminal: true };
+        default:
+            return base;
+    }
+};
+/** Project a full (or partial) event sequence into `RunStreamState`. */
+export const reduceRunEvents = (events, initial = EMPTY_RUN_STREAM_STATE) => {
+    let state = initial;
+    for (const event of events)
+        state = reduceRunEvent(state, event);
+    return state;
+};
+//# sourceMappingURL=events.js.map

package/dist/core/ids.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Branded identifiers.
+ *
+ * Every durable record in `docs/02-core-and-persistence.md` gets a distinct ID type so
+ * a run ID can never be passed where a conversation ID is expected.
+ */
+declare const brand: unique symbol;
+/**
+ * Exported so a downstream package can mint its own IDs with the same mechanism rather than a second,
+ * incompatible one. `asId` is generic over this, so an integration package's `PostDraftId` gets the
+ * same "cannot be passed where another ID is expected" guarantee the platform's own IDs have.
+ */
+export type Branded<T, B extends string> = T & {
+    readonly [brand]: B;
+};
+export type TenantId = Branded<string, "TenantId">;
+export type PrincipalId = Branded<string, "PrincipalId">;
+export type MembershipId = Branded<string, "MembershipId">;
+export type RoleId = Branded<string, "RoleId">;
+export type RequestId = Branded<string, "RequestId">;
+export type AgentId = Branded<string, "AgentId">;
+export type SkillId = Branded<string, "SkillId">;
+export type ConversationId = Branded<string, "ConversationId">;
+export type RunId = Branded<string, "RunId">;
+export type MessageId = Branded<string, "MessageId">;
+export type MessagePartId = Branded<string, "MessagePartId">;
+export type CheckpointId = Branded<string, "CheckpointId">;
+export type InteractionId = Branded<string, "InteractionId">;
+export type ApprovalGrantId = Branded<string, "ApprovalGrantId">;
+export type UsageEventId = Branded<string, "UsageEventId">;
+export type EvaluationCaseId = Branded<string, "EvaluationCaseId">;
+export type EvaluationRunId = Branded<string, "EvaluationRunId">;
+export type FileId = Branded<string, "FileId">;
+export type FileVersionId = Branded<string, "FileVersionId">;
+export type KnowledgeCollectionId = Branded<string, "KnowledgeCollectionId">;
+export type KnowledgeSourceId = Branded<string, "KnowledgeSourceId">;
+export type KnowledgeChunkId = Branded<string, "KnowledgeChunkId">;
+export type ArtifactId = Branded<string, "ArtifactId">;
+export type ArtifactVersionId = Branded<string, "ArtifactVersionId">;
+export type ToolCallId = Branded<string, "ToolCallId">;
+export type BlobRef = Branded<string, "BlobRef">;
+export type AuditEventId = Branded<string, "AuditEventId">;
+/** Opaque cursor for the stable pagination every list method uses. */
+export type Cursor = Branded<string, "Cursor">;
+/**
+ * Casts a raw string to a branded ID. Reserved for boundaries that have already
+ * validated the value — adapters reading a database row, or a resolver that has
+ * authenticated the caller. Never call this on model-generated input.
+ */
+export declare const asId: <T extends Branded<string, string>>(value: string) => T;
+export {};
+//# sourceMappingURL=ids.d.ts.map

package/dist/core/ids.js

@@ -0,0 +1,13 @@
+/**
+ * Branded identifiers.
+ *
+ * Every durable record in `docs/02-core-and-persistence.md` gets a distinct ID type so
+ * a run ID can never be passed where a conversation ID is expected.
+ */
+/**
+ * Casts a raw string to a branded ID. Reserved for boundaries that have already
+ * validated the value — adapters reading a database row, or a resolver that has
+ * authenticated the caller. Never call this on model-generated input.
+ */
+export const asId = (value) => value;
+//# sourceMappingURL=ids.js.map

package/dist/core/index.d.ts

@@ -0,0 +1,9 @@
+export * from "./ids.js";
+export * from "./tokens.js";
+export * from "./context.js";
+export * from "./content-parts.js";
+export * from "./errors.js";
+export * from "./events.js";
+export * from "./validation.js";
+export * from "./env.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/core/index.js

@@ -0,0 +1,9 @@
+export * from "./ids.js";
+export * from "./tokens.js";
+export * from "./context.js";
+export * from "./content-parts.js";
+export * from "./errors.js";
+export * from "./events.js";
+export * from "./validation.js";
+export * from "./env.js";
+//# sourceMappingURL=index.js.map

package/dist/core/tokens.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The token estimate, in one place (#135).
+ *
+ * Five copies of `Math.ceil(text.length / 4)` had accumulated — in `files/context.ts`, `knowledge/chunking.ts`,
+ * `context/compaction.ts`, `usage/recorder.ts` and `principal-memory/index.ts`. Two of them exported the same
+ * name, which is what surfaced it: the package barrel refused to re-export both, the same collision
+ * `DEFAULT_SESSION_STATE_MAX_BYTES` caused before #97 moved it to its port.
+ *
+ * They agreed by coincidence rather than by construction, and the coincidence mattered: 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. One definition, in the lowest layer, so agreement is structural.
+ *
+ * **Deliberately not a real tokeniser.** A tokeniser is a dependency, it is model-specific, and it is wrong the
+ * moment the model changes. Every caller here uses the estimate to size something — a chunk boundary, a budget
+ * bucket, a cost projection — where being 10% out moves a boundary rather than breaking anything. Where an
+ * exact count matters, the provider's own reported usage is authoritative and this is not consulted.
+ */
+/** Characters over four — the industry rule of thumb for English text with a BPE tokeniser. */
+export declare const CHARS_PER_TOKEN = 4;
+/** An estimate of how many tokens `text` occupies. Never negative, never fractional. */
+export declare const estimateTokens: (text: string) => number;
+//# sourceMappingURL=tokens.d.ts.map

package/dist/core/tokens.js

@@ -0,0 +1,22 @@
+/**
+ * The token estimate, in one place (#135).
+ *
+ * Five copies of `Math.ceil(text.length / 4)` had accumulated — in `files/context.ts`, `knowledge/chunking.ts`,
+ * `context/compaction.ts`, `usage/recorder.ts` and `principal-memory/index.ts`. Two of them exported the same
+ * name, which is what surfaced it: the package barrel refused to re-export both, the same collision
+ * `DEFAULT_SESSION_STATE_MAX_BYTES` caused before #97 moved it to its port.
+ *
+ * They agreed by coincidence rather than by construction, and the coincidence mattered: 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. One definition, in the lowest layer, so agreement is structural.
+ *
+ * **Deliberately not a real tokeniser.** A tokeniser is a dependency, it is model-specific, and it is wrong the
+ * moment the model changes. Every caller here uses the estimate to size something — a chunk boundary, a budget
+ * bucket, a cost projection — where being 10% out moves a boundary rather than breaking anything. Where an
+ * exact count matters, the provider's own reported usage is authoritative and this is not consulted.
+ */
+/** Characters over four — the industry rule of thumb for English text with a BPE tokeniser. */
+export const CHARS_PER_TOKEN = 4;
+/** An estimate of how many tokens `text` occupies. Never negative, never fractional. */
+export const estimateTokens = (text) => Math.ceil(text.length / CHARS_PER_TOKEN);
+//# sourceMappingURL=tokens.js.map

package/dist/core/validation.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Runtime validation for the core wire contracts — `docs/02-core-and-persistence.md`.
+ *
+ * Every message part is JSON-runtime validated and carries a `schemaVersion`. `providerMetadata`
+ * is namespaced and **non-authoritative**: it is preserved on round-trip but never participates
+ * in discrimination or any branching — a part's `type` is the only source of truth.
+ */
+import type { ExecutionContext } from "./context.js";
+import type { MessagePart } from "./content-parts.js";
+import { type RunEvent } from "./events.js";
+/**
+ * The most a reference part's provider bag may hold (#130).
+ *
+ * Small on purpose. `providerMetadata` is `Record<string, unknown>`, which is exactly the shape a base64
+ * payload fits into — and a file part carrying its own content would satisfy every other rule in this file
+ * while breaking the one that matters. 2 KiB is room for a provider's ids and flags and no room for a
+ * document.
+ */
+export declare const MAX_REFERENCE_METADATA_BYTES = 2048;
+/**
+ * The longest excerpt a citation may carry (#137).
+ *
+ * A citation is evidence for a claim, not a copy of the source. Unbounded, it becomes a way to store a document
+ * inside a message — bypassing every limit that applies to documents — and a transcript whose size grows with
+ * the corpus. 2000 characters is several paragraphs: far more than a claim needs and far less than a document.
+ */
+export declare const MAX_CITATION_EXCERPT = 2000;
+/** Validate an unknown JSON value into a typed message part, or throw `invalid_input`. */
+export declare const parseMessagePart: (value: unknown) => MessagePart;
+/** JSON-safe wire form. `parseMessagePart(serializeMessagePart(x))` round-trips to `x`. */
+export declare const serializeMessagePart: (part: MessagePart) => unknown;
+export declare const parseExecutionContext: (value: unknown) => ExecutionContext;
+export declare const parseRunEvent: (value: unknown) => RunEvent;
+//# sourceMappingURL=validation.d.ts.map

package/dist/core/validation.js

@@ -0,0 +1,176 @@
+/**
+ * Runtime validation for the core wire contracts — `docs/02-core-and-persistence.md`.
+ *
+ * Every message part is JSON-runtime validated and carries a `schemaVersion`. `providerMetadata`
+ * is namespaced and **non-authoritative**: it is preserved on round-trip but never participates
+ * in discrimination or any branching — a part's `type` is the only source of truth.
+ */
+import { z } from "zod";
+import { AgentPlatformError, ERROR_CODES } from "./errors.js";
+import { RUN_EVENT_TYPES } from "./events.js";
+const idString = z.string().min(1);
+const providerMetadata = z.record(z.string(), z.unknown()).optional();
+/**
+ * The most a reference part's provider bag may hold (#130).
+ *
+ * Small on purpose. `providerMetadata` is `Record<string, unknown>`, which is exactly the shape a base64
+ * payload fits into — and a file part carrying its own content would satisfy every other rule in this file
+ * while breaking the one that matters. 2 KiB is room for a provider's ids and flags and no room for a
+ * document.
+ */
+export const MAX_REFERENCE_METADATA_BYTES = 2048;
+/**
+ * The longest excerpt a citation may carry (#137).
+ *
+ * A citation is evidence for a claim, not a copy of the source. Unbounded, it becomes a way to store a document
+ * inside a message — bypassing every limit that applies to documents — and a transcript whose size grows with
+ * the corpus. 2000 characters is several paragraphs: far more than a claim needs and far less than a document.
+ */
+export const MAX_CITATION_EXCERPT = 2000;
+/** A `data:` URI is bytes wearing a string's clothes, so it is refused wherever it appears in the bag. */
+const carriesInlineData = (value) => typeof value === "string"
+    ? /^\s*data:[^,]*,/i.test(value)
+    : Array.isArray(value)
+        ? value.some(carriesInlineData)
+        : typeof value === "object" && value !== null
+            ? Object.values(value).some(carriesInlineData)
+            : false;
+/**
+ * `providerMetadata` for a part that must stay a reference.
+ *
+ * Two checks rather than one, because they fail differently: a size cap catches bulk however it is encoded,
+ * and the `data:` check catches a small payload that would slip under the cap — a 1 KB inline image is still
+ * content in a part that promises not to carry any.
+ */
+const referenceMetadata = z
+    .record(z.string(), z.unknown())
+    .refine((bag) => JSON.stringify(bag).length <= MAX_REFERENCE_METADATA_BYTES, {
+    message: `providerMetadata on a reference part must be at most ${MAX_REFERENCE_METADATA_BYTES} bytes; file contents are referenced, not inlined`,
+})
+    .refine((bag) => !carriesInlineData(bag), {
+    message: "providerMetadata on a reference part must not contain a data: URI; file contents are referenced, not inlined",
+})
+    .optional();
+/** Fields on every part. `providerMetadata` is optional and never authoritative. */
+const base = {
+    id: idString,
+    schemaVersion: z.number().int().nonnegative(),
+    createdAt: z.string().min(1),
+    providerMetadata,
+};
+const platformErrorSchema = z.object({
+    code: z.enum([...ERROR_CODES]),
+    message: z.string(),
+    retryable: z.boolean(),
+    details: z.record(z.string(), z.unknown()).optional(),
+    retryAfterMs: z.number().optional(),
+});
+const messagePartSchema = z.discriminatedUnion("type", [
+    z.object({ ...base, type: z.literal("text"), text: z.string() }),
+    z.object({ ...base, type: z.literal("reasoning"), text: z.string(), redacted: z.boolean().optional() }),
+    z.object({ ...base, type: z.literal("tool-call"), toolCallId: idString, toolName: z.string(), input: z.unknown() }),
+    z.object({
+        ...base, type: z.literal("tool-result"), toolCallId: idString, toolName: z.string(),
+        output: z.unknown().optional(), spilledOutputRef: idString.optional(), truncated: z.boolean(),
+    }),
+    z.object({
+        ...base, type: z.literal("question"), interactionId: idString,
+        questions: z.array(z.object({ key: z.string(), prompt: z.string(), options: z.array(z.string()).optional() })),
+        answeredAt: z.string().optional(),
+    }),
+    z.object({
+        ...base, type: z.literal("approval"), interactionId: idString, toolName: z.string(),
+        summary: z.string(), riskCategory: z.string(), decidedAt: z.string().optional(),
+    }),
+    // #130. A reference, and structurally incapable of being anything else: no field holds content, and
+    // `referenceMetadata` refuses the two ways bytes could arrive anyway — a `data:` URI, or a payload smuggled
+    // into the non-authoritative provider bag. Governing principle 6 is a property of the schema here rather
+    // than a rule the assembler has to enforce downstream.
+    z.object({
+        ...base, type: z.literal("file"), providerMetadata: referenceMetadata,
+        fileId: idString, filename: z.string(), mediaType: z.string(), byteSize: z.number().int().nonnegative(),
+    }),
+    z.object({
+        ...base, type: z.literal("image"), providerMetadata: referenceMetadata,
+        fileId: idString, mediaType: z.string(), width: z.number().optional(), height: z.number().optional(),
+        altText: z.string().optional(),
+    }),
+    // #137. `excerpt` has a length cap because a citation is *evidence* for a claim, not a copy of the source:
+    // unbounded, it becomes a way to store a document inside a message and bypass every limit on documents.
+    z.object({
+        ...base,
+        type: z.literal("citation"),
+        origin: z.discriminatedUnion("kind", [
+            z.object({
+                kind: z.literal("retrieval"),
+                sourceType: z.enum(["file", "artifact", "message", "external"]),
+                sourceId: idString,
+                chunkId: idString,
+                chunkIndex: z.number().int().nonnegative(),
+                locator: z.string().optional(),
+            }),
+            z.object({
+                kind: z.literal("web"),
+                // Absolute, and http(s) only. A `data:` or `file:` citation is not a source anyone can open, and a
+                // relative URL resolves against whatever page happens to render it.
+                url: z.string().url().refine((u) => /^https?:\/\//i.test(u), {
+                    message: "a web citation's url must be http or https",
+                }),
+                title: z.string().optional(),
+            }),
+        ]),
+        excerpt: z.string().min(1).max(MAX_CITATION_EXCERPT),
+        retrievedAt: z.string(),
+        supports: z.array(idString),
+        charRange: z
+            .object({ start: z.number().int().nonnegative(), end: z.number().int().nonnegative() })
+            // An inverted range is a bug that would silently produce an empty highlight, which reads as "the passage
+            // is not in the source".
+            .refine((r) => r.end > r.start, { message: "charRange.end must be greater than charRange.start" })
+            .optional(),
+    }),
+    z.object({ ...base, type: z.literal("source"), sourceId: z.string(), title: z.string(), url: z.string().optional() }),
+    z.object({ ...base, type: z.literal("artifact"), artifactId: idString, versionId: idString, title: z.string() }),
+    z.object({ ...base, type: z.literal("status"), status: z.string(), detail: z.string().optional() }),
+    z.object({ ...base, type: z.literal("error"), error: platformErrorSchema }),
+]);
+const executionContextSchema = z.object({
+    tenantId: idString,
+    principalId: idString,
+    membershipId: z.string().optional(),
+    roleIds: z.array(z.string()),
+    locale: z.string(),
+    timezone: z.string(),
+    conversationId: z.string().optional(),
+    runId: z.string().optional(),
+    requestId: idString,
+});
+const runEventSchema = z.object({
+    type: z.enum([...RUN_EVENT_TYPES]),
+    runId: idString,
+    sequence: z.number().int().nonnegative(),
+    occurredAt: z.string().min(1),
+}).passthrough();
+const fail = (what, error) => {
+    throw new AgentPlatformError({
+        code: "invalid_input",
+        message: `Invalid ${what}: ${error.issues.map((i) => `${i.path.join(".")} ${i.message}`).join("; ")}`,
+        retryable: false,
+    });
+};
+/** Validate an unknown JSON value into a typed message part, or throw `invalid_input`. */
+export const parseMessagePart = (value) => {
+    const r = messagePartSchema.safeParse(value);
+    return r.success ? r.data : fail("message part", r.error);
+};
+/** JSON-safe wire form. `parseMessagePart(serializeMessagePart(x))` round-trips to `x`. */
+export const serializeMessagePart = (part) => JSON.parse(JSON.stringify(part));
+export const parseExecutionContext = (value) => {
+    const r = executionContextSchema.safeParse(value);
+    return r.success ? r.data : fail("execution context", r.error);
+};
+export const parseRunEvent = (value) => {
+    const r = runEventSchema.safeParse(value);
+    return r.success ? r.data : fail("run event", r.error);
+};
+//# sourceMappingURL=validation.js.map

package/dist/documents/extraction.d.ts

@@ -0,0 +1,121 @@
+/**
+ * The extraction pipeline (#131).
+ *
+ * The parsers do the reading; this decides *when*, *within what bounds*, and *what is recorded when it goes
+ * wrong* — which is the part that makes extraction safe to run on a shared worker tier.
+ *
+ * Four properties, each answering an AC:
+ *
+ * - **It never throws for a document problem** (AC-4). Every outcome is recorded on the file: `extracted` with
+ *   a reference, or `failed` with a typed reason and a sentence the user reads. An extractor that threw would
+ *   leave the file looking unextracted, which is indistinguishable from "not got round to it yet" — and the
+ *   user would see an empty document rather than a reason.
+ * - **It is bounded in every dimension a document can grow** (AC-3): bytes read, pages, extracted text,
+ *   blocks, and wall clock. The timeout is enforced *here* rather than trusted to the parser, because a
+ *   parser stuck in a loop is exactly the case a parser-side check does not catch.
+ * - **It is enqueued, not awaited** (AC-2). `requestExtraction` puts a job on the queue and returns; an
+ *   enqueue failure marks the file `pending` and is reported, never propagated — an attachment that uploaded
+ *   fine must not fail because the extraction queue was briefly unreachable.
+ * - **The result is stored by reference and read in windows** (AC-6). The `ExtractedDocument` goes to
+ *   `BlobStore` and the file carries the ref. Nothing loads it into context; `read_document` reads a bounded
+ *   window, exactly as #130 established for the raw bytes.
+ */
+import type { ExecutionContext } from "../core/context.js";
+import type { FileId, TenantId } from "../core/ids.js";
+import type { BlobStore, FileContentStore, FileExtraction, FileMetadataStore } from "../persistence/index.js";
+import { type DocumentParser, type ExtractedDocument, type ExtractionDispatcher, type ExtractionJob, type ExtractionLimits } from "./index.js";
+export type ExtractionServiceDeps = {
+    readonly metadata: FileMetadataStore;
+    readonly content: FileContentStore;
+    /** Where the extracted document goes. `BlobStore` stores JSON, which is what an `ExtractedDocument` is. */
+    readonly blobs: BlobStore;
+    readonly parsers: readonly DocumentParser[];
+    /**
+     * Parsers to try when the primary one reports `no-text-layer` (#132).
+     *
+     * Keyed by media type like `parsers`, and separate because the dispatch table holds one parser per type:
+     * both the text-layer PDF parser and the OCR one claim `application/pdf`. This is where #131's insistence
+     * that `no-text-layer` be its own reason becomes load-bearing — the fallback triggers on exactly that
+     * answer and on nothing else. An encrypted or malformed document is *not* retried through OCR, because
+     * OCR will not decrypt it and the second attempt would cost money to reach the same conclusion.
+     */
+    readonly fallbackParsers?: readonly DocumentParser[];
+    /**
+     * Bills a vision or OCR call (#132, AC-4).
+     *
+     * A callback rather than a `UsageRecorder`, so `documents` does not depend on `usage`. The pipeline knows
+     * *when* a priced operation happened; what it costs is the caller's pricing model.
+     */
+    readonly onPricedOperation?: (input: {
+        readonly tenantId: TenantId;
+        readonly fileId: FileId;
+        readonly usage: PricedExtractionUsage;
+    }) => Promise<void>;
+    readonly limits?: ExtractionLimits;
+    readonly clock?: () => string;
+    /**
+     * The queue. Optional, and its absence means extraction runs only when something calls `extract` directly.
+     *
+     * Optional rather than required because a single-process deployment is a real configuration, and requiring a
+     * queue there would mean standing up Redis to attach a text file. What is *not* optional is that `upload`
+     * never blocks on extraction — that holds either way.
+     */
+    readonly dispatcher?: ExtractionDispatcher;
+    readonly log?: (message: string, detail?: Readonly<Record<string, unknown>>) => void;
+};
+/** What a priced extraction step consumed. Vision calls are the expensive kind, so they are reported. */
+export type PricedExtractionUsage = {
+    readonly kind: "vision" | "ocr";
+    readonly modelId: string;
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly cachedInputTokens: number;
+};
+export declare const createExtractionService: (deps: ExtractionServiceDeps) => {
+    limits: ExtractionLimits;
+    /** Types this pipeline can read at all. Exposed so an upload path can decide not to enqueue at all. */
+    supportedMediaTypes(): readonly string[];
+    /**
+     * Ask for extraction, without waiting for it — AC-2.
+     *
+     * Marks the file `pending` first, then enqueues. That order matters: the reverse would let a worker pick
+     * the job up, extract, and record its outcome *before* this function overwrote it with `pending`, losing a
+     * completed extraction to a race that only shows up under load.
+     */
+    requestExtraction(context: {
+        readonly tenantId: TenantId;
+    }, id: FileId, mediaType: string): Promise<{
+        readonly enqueued: boolean;
+        readonly state: FileExtraction["state"];
+    }>;
+    /**
+     * Do the extraction. Called by the worker, and directly by a single-process host.
+     *
+     * Returns the record it wrote rather than throwing, for every document-shaped problem. The only throw is
+     * for a *file* that is not there, which is a caller error rather than a document one.
+     */
+    extract(job: ExtractionJob): Promise<FileExtraction>;
+    /** The extracted document, or null when there is none to read. */
+    getExtracted(context: ExecutionContext, id: FileId): Promise<{
+        readonly document: ExtractedDocument | null;
+        readonly extraction?: FileExtraction;
+    }>;
+    /**
+     * Re-enqueue extractions that never finished.
+     *
+     * Two shapes, and both are silent without this: a `pending` file whose enqueue was lost, and a `running`
+     * file whose worker died. Both are re-requested rather than repaired — the pipeline is idempotent, so
+     * running it again is the repair.
+     */
+    sweepStuckExtractions(context: {
+        readonly tenantId: TenantId;
+    }, input: {
+        readonly olderThan: string;
+        readonly limit: number;
+    }): Promise<{
+        readonly requeued: number;
+        readonly states: Readonly<Record<string, number>>;
+    }>;
+};
+export type ExtractionService = ReturnType<typeof createExtractionService>;
+//# sourceMappingURL=extraction.d.ts.map