@retinue/agentkit 0.1.0

package/dist/citations/index.js

@@ -0,0 +1,182 @@
+/**
+ * Citations and per-claim provenance — REQ-030 (#137).
+ *
+ * `research-and-citation` already says what should happen. This makes it structural, and the structure carries
+ * four decisions worth stating.
+ *
+ * **A citation is a snapshot, not a pointer.** `excerpt`, `title` and `retrievedAt` live on the part. AC-4
+ * requires an answer given months ago to stay auditable *after the source is gone* — a document deleted, a URL
+ * dead, a chunk re-indexed under a new id — and a citation that resolved by fetching would stop being evidence
+ * exactly when someone needs it. The duplication is the feature.
+ *
+ * **Groundedness is derived from the citation graph**, not flagged on the text. A text part is grounded exactly
+ * when some citation names it in `supports`. A boolean on the text part would be a second place for the same
+ * fact, and the two would drift the first time a citation was withheld — leaving a claim that says "grounded"
+ * with nothing behind it, which is worse than an honestly ungrounded one.
+ *
+ * **Permission is re-checked at citation time.** AC-5, and the reason is precise: retrieval and rendering are
+ * different moments, and a permission can change between them. A citation emitted on the strength of a
+ * retrieval check is a citation that can outlive the access that justified it.
+ *
+ * **One shape for retrieval and web research.** AC-6. Two part types would mean two renderers, two schemas and
+ * eventually two behaviours for "click the citation".
+ */
+import { AgentPlatformError } from "../core/errors.js";
+import { asId } from "../core/ids.js";
+import { MAX_CITATION_EXCERPT } from "../core/validation.js";
+/** The current citation payload version. Bumped from 1 by #137, which added origin, excerpt and supports. */
+export const CITATION_SCHEMA_VERSION = 2;
+/**
+ * Trim an excerpt to the cap without cutting a word in half.
+ *
+ * A citation ending mid-word reads as corrupt, and a reader cannot tell whether the source said something else.
+ * The ellipsis is explicit so a truncated excerpt is visibly truncated rather than silently shorter than what
+ * was read.
+ */
+export const boundExcerpt = (text, max = MAX_CITATION_EXCERPT) => {
+    const collapsed = text.replace(/\s+/g, " ").trim();
+    if (collapsed.length <= max)
+        return collapsed;
+    const cut = collapsed.slice(0, max - 1);
+    const lastSpace = cut.lastIndexOf(" ");
+    return `${lastSpace > max * 0.6 ? cut.slice(0, lastSpace) : cut}…`;
+};
+/** A citation built from a retrieval hit. The passage fields come from the hit, so they cannot disagree. */
+export const citationFromRetrieval = (input) => ({
+    origin: {
+        kind: "retrieval",
+        sourceType: input.hit.reference.sourceType,
+        sourceId: input.hit.reference.sourceId,
+        chunkId: input.hit.reference.chunkId,
+        chunkIndex: input.hit.reference.chunkIndex,
+        ...(input.hit.reference.locator === undefined ? {} : { locator: input.hit.reference.locator }),
+    },
+    // The chunk's own content, bounded. Not a re-read of the source: what was *used* is what must be cited.
+    excerpt: boundExcerpt(input.hit.chunk.content),
+    retrievedAt: input.retrievedAt,
+    supports: input.supports,
+    ...(input.charRange === undefined ? {} : { charRange: input.charRange }),
+    // The chunk's auth subject, so the emission check asks about the same thing retrieval filtered on.
+    authSubject: input.hit.chunk.authSubject,
+});
+/**
+ * A citation built from a web passage.
+ *
+ * Shaped to accept ShareFlow's `SourcePassage` without adaptation — `url`, `retrievedAt`, `excerpt` — because
+ * AC-6 is only true if the two paths really do produce one thing rather than two things that look alike.
+ */
+export const citationFromWeb = (input) => ({
+    origin: {
+        kind: "web",
+        url: input.passage.url,
+        ...(input.title === undefined ? {} : { title: input.title }),
+    },
+    excerpt: boundExcerpt(input.passage.excerpt),
+    retrievedAt: input.passage.retrievedAt,
+    supports: input.supports,
+});
+export const createCitationEmitter = (deps) => {
+    const clock = deps.clock ?? (() => new Date().toISOString());
+    const newId = deps.partId ?? (() => `cite_${crypto.randomUUID()}`);
+    return {
+        /**
+         * Turn candidates into parts, dropping any the reader may not open.
+         *
+         * Checked here and not only at retrieval, because the two are different moments. A permission revoked in
+         * between is exactly the case the test steps name, and a citation emitted on a retrieval-time check would
+         * survive it.
+         */
+        async emit(context, candidates) {
+            const parts = [];
+            let withheld = 0;
+            for (const candidate of candidates) {
+                if (!(await this.mayCite(context, candidate))) {
+                    withheld += 1;
+                    continue;
+                }
+                parts.push({
+                    id: asId(newId()),
+                    type: "citation",
+                    schemaVersion: CITATION_SCHEMA_VERSION,
+                    createdAt: clock(),
+                    origin: candidate.origin,
+                    excerpt: candidate.excerpt,
+                    retrievedAt: candidate.retrievedAt,
+                    supports: candidate.supports,
+                    ...(candidate.charRange === undefined ? {} : { charRange: candidate.charRange }),
+                });
+            }
+            return { parts, withheld };
+        },
+        /**
+         * Whether this reader may be shown this citation.
+         *
+         * A web citation needs no check: its URL is public by construction, and asking a policy about it would be
+         * asking about a resource the policy has never heard of — which most policies answer by denying, silently
+         * suppressing every web citation.
+         */
+        async mayCite(context, candidate) {
+            if (candidate.origin.kind === "web")
+                return true;
+            if (candidate.authSubject === undefined)
+                // A retrieval citation with no subject cannot be checked, so it is not emitted. Failing closed here is
+                // the only safe direction: the alternative emits an excerpt nobody authorised.
+                return false;
+            const decision = await deps.authorization.can(context, "read", {
+                type: "conversation",
+                id: candidate.authSubject,
+            });
+            return decision.allow;
+        },
+    };
+};
+/**
+ * The parts a message's citations ground — AC-3.
+ *
+ * Derived from the citation graph, so there is one source of truth. A caller renders a text part differently
+ * when its id is in this set; nothing has to inspect the prose.
+ */
+export const groundedPartIds = (parts) => {
+    const grounded = new Set();
+    for (const part of parts) {
+        if (part.type !== "citation")
+            continue;
+        for (const supported of part.supports)
+            grounded.add(supported);
+    }
+    return grounded;
+};
+/** Citations that ground a given part, in the order they appear. For rendering markers next to a claim. */
+export const citationsFor = (parts, partId) => parts.filter((p) => p.type === "citation" && p.supports.includes(partId));
+/**
+ * A citation that grounds nothing.
+ *
+ * Worth finding, because it is the shape a bug takes: a producer that emitted citations without wiring them to
+ * the claims they support leaves an answer that *looks* cited — markers in a list at the bottom — while no
+ * individual statement is traceable, which is the failure REQ-030 exists to prevent.
+ */
+export const danglingCitations = (parts) => {
+    const ids = new Set(parts.map((p) => p.id));
+    return parts.filter((p) => p.type === "citation" && (p.supports.length === 0 || !p.supports.some((s) => ids.has(s))));
+};
+export const resolveCitation = (part) => ({
+    excerpt: part.excerpt,
+    retrievedAt: part.retrievedAt,
+    label: part.origin.kind === "retrieval"
+        ? // The heading path when the chunker found one; otherwise the passage's position, which is still more
+            // specific than the document. A bare document name would be AC-2 unmet.
+            (part.origin.locator ?? `${part.origin.sourceId} — passage ${part.origin.chunkIndex + 1}`)
+        : (part.origin.title ?? part.origin.url),
+    target: part.origin.kind === "retrieval" ? part.origin.chunkId : part.origin.url,
+    kind: part.origin.kind,
+});
+/** Thrown when a producer tries to cite without an excerpt. A citation with no text is not evidence. */
+export const assertCitable = (candidate) => {
+    if (candidate.excerpt.trim() === "")
+        throw new AgentPlatformError({
+            code: "invalid_input",
+            message: "a citation must carry the excerpt it is evidence for",
+            retryable: false,
+        });
+};
+//# sourceMappingURL=index.js.map

package/dist/context/assembler.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Prompt assembly & budgeting — `docs/03-intelligence-runtime.md` → Prompt assembly.
+ *
+ * Turns the sections gathered from context providers into a budgeted, previewable prompt. Each
+ * section draws from an explicit budget bucket (base policy, user/app context, tools, skills,
+ * knowledge, history) rather than one undifferentiated window. When the prompt exceeds the model's
+ * limit, sections are pruned in a fixed order — old reasoning, old tool detail, old knowledge, old
+ * turns — while recent semantic turns and open tool continuity (sections with no `pruneStage`) are
+ * preserved. Base policy is never pruned: if it cannot fit, assembly fails loudly rather than
+ * silently dropping critical instructions.
+ */
+import type { ExecutionContext } from "../core/context.js";
+import { PRUNE_ORDER } from "./index.js";
+import { type ContextBudget, type ContextKind, type ContextProvider, type ContextSection, type PromptPreview } from "./index.js";
+/** Gather sections from every provider, in provider order. Providers that fail are surfaced, not hidden. */
+export declare const gatherSections: (context: ExecutionContext, providers: readonly ContextProvider[]) => Promise<readonly ContextSection[]>;
+export type AssembledPrompt = {
+    /** Included sections, highest priority first within each bucket. */
+    readonly sections: readonly ContextSection[];
+    readonly preview: PromptPreview;
+    readonly totalTokens: number;
+    /**
+     * The model's hard input limit this prompt was assembled against — #168.
+     *
+     * Echoed back rather than left to the caller to remember. It is the denominator of every useful question about
+     * a prompt — how full is the window, how much is left, is this turn near the edge — and a caller holding the
+     * numerator while the limit lives somewhere else is a caller computing utilization against the wrong model the
+     * first time a policy resolves a different one.
+     */
+    readonly modelContextTokens: number;
+    /** Sections dropped, with why — for observability and the context inspector. */
+    readonly pruned: readonly {
+        readonly section: ContextSection;
+        readonly reason: "bucket-overflow" | PromptPruneStage;
+    }[];
+};
+type PromptPruneStage = (typeof PRUNE_ORDER)[number];
+/**
+ * Assemble a budgeted prompt from already-gathered sections. Pure and deterministic, so composition
+ * is previewable: the returned `preview` lists every section with its token estimate and whether it
+ * was included. `modelContextTokens` is the hard input limit the assembled prompt must fit within.
+ */
+export declare const assemblePrompt: (input: {
+    readonly sections: readonly ContextSection[];
+    readonly budget: ContextBudget;
+    readonly modelContextTokens: number;
+}) => AssembledPrompt;
+/** A section's inspector view — enough for the Context panel to explain what shaped a turn. */
+export type InspectedSection = {
+    readonly title: string;
+    readonly providerId: string;
+    readonly kind: ContextKind;
+    readonly provenance: string;
+    readonly estimatedTokens: number;
+    readonly sensitivity: ContextSection["sensitivity"];
+    readonly included: boolean;
+    /** Set when the section was dropped: why. */
+    readonly prunedReason?: string;
+};
+export type ContextInspection = {
+    readonly sections: readonly InspectedSection[];
+    readonly totalTokens: number;
+    readonly budget: ContextBudget;
+    /** The model's hard input limit — the denominator for utilization (#168). */
+    readonly modelContextTokens: number;
+    /**
+     * What is left for history and the model's reply.
+     *
+     * Derived here rather than by each client, because `max(0, limit - used)` is the kind of arithmetic that gets
+     * written twice and clamped once. Never negative: the assembler refuses to overflow, so a negative remainder
+     * would be a bug reported as a number.
+     */
+    readonly remainingTokens: number;
+};
+/**
+ * Derive the context-inspector view from an assembled prompt: every section (included and pruned)
+ * with its bucket, provenance and token cost — so the UI can attribute which context (and which
+ * memory entries, via provenance) influenced a turn, and show what was dropped and why.
+ */
+export declare const inspectAssembledPrompt: (assembled: AssembledPrompt) => ContextInspection;
+export {};
+//# sourceMappingURL=assembler.d.ts.map

package/dist/context/assembler.js

@@ -0,0 +1,129 @@
+/**
+ * Prompt assembly & budgeting — `docs/03-intelligence-runtime.md` → Prompt assembly.
+ *
+ * Turns the sections gathered from context providers into a budgeted, previewable prompt. Each
+ * section draws from an explicit budget bucket (base policy, user/app context, tools, skills,
+ * knowledge, history) rather than one undifferentiated window. When the prompt exceeds the model's
+ * limit, sections are pruned in a fixed order — old reasoning, old tool detail, old knowledge, old
+ * turns — while recent semantic turns and open tool continuity (sections with no `pruneStage`) are
+ * preserved. Base policy is never pruned: if it cannot fit, assembly fails loudly rather than
+ * silently dropping critical instructions.
+ */
+import { AgentPlatformError } from "../core/errors.js";
+import { PRUNE_ORDER } from "./index.js";
+import {} from "./index.js";
+const BUCKET_FIELD = {
+    "base-policy": "basePolicyTokens",
+    "user-context": "userContextTokens",
+    tools: "toolTokens",
+    skills: "skillTokens",
+    knowledge: "knowledgeTokens",
+    history: "historyTokens",
+};
+const kindOf = (section) => section.kind ?? "user-context";
+/** Gather sections from every provider, in provider order. Providers that fail are surfaced, not hidden. */
+export const gatherSections = async (context, providers) => {
+    const sections = [];
+    for (const provider of providers)
+        sections.push(...(await provider.provide(context)));
+    return sections;
+};
+const overflow = (message) => new AgentPlatformError({ code: "context_overflow", message, retryable: false });
+/**
+ * Assemble a budgeted prompt from already-gathered sections. Pure and deterministic, so composition
+ * is previewable: the returned `preview` lists every section with its token estimate and whether it
+ * was included. `modelContextTokens` is the hard input limit the assembled prompt must fit within.
+ */
+export const assemblePrompt = (input) => {
+    const { budget, modelContextTokens } = input;
+    const pruned = [];
+    // 1. Per-bucket budgeting: within each bucket, keep the highest-priority sections that fit.
+    const byKind = new Map();
+    for (const section of input.sections) {
+        const list = byKind.get(kindOf(section)) ?? [];
+        list.push(section);
+        byKind.set(kindOf(section), list);
+    }
+    let included = [];
+    for (const [kind, sections] of byKind) {
+        const limit = budget[BUCKET_FIELD[kind]];
+        const ordered = [...sections].sort((a, b) => b.priority - a.priority);
+        let used = 0;
+        for (const section of ordered) {
+            if (used + section.estimatedTokens <= limit) {
+                used += section.estimatedTokens;
+                included.push(section);
+            }
+            else if (kind === "base-policy") {
+                // Critical instructions must fit their budget; refuse rather than truncate.
+                throw overflow(`Base policy needs more than its ${limit}-token budget`);
+            }
+            else {
+                pruned.push({ section, reason: "bucket-overflow" });
+            }
+        }
+    }
+    // 2. Global limit: if still over the model's window, prune in the fixed stage order.
+    let total = included.reduce((sum, s) => sum + s.estimatedTokens, 0);
+    for (const stage of PRUNE_ORDER) {
+        if (total <= modelContextTokens)
+            break;
+        // Drop lowest-priority sections tagged for this stage first. Base policy is never eligible,
+        // even if a section carried a pruneStage — critical instructions are never dropped.
+        const eligible = included
+            .filter((s) => s.pruneStage === stage && s.kind !== "base-policy")
+            .sort((a, b) => a.priority - b.priority);
+        for (const section of eligible) {
+            if (total <= modelContextTokens)
+                break;
+            included = included.filter((s) => s !== section);
+            pruned.push({ section, reason: stage });
+            total -= section.estimatedTokens;
+        }
+    }
+    if (total > modelContextTokens) {
+        throw overflow(`Prompt needs ${total} tokens but the model allows ${modelContextTokens}, and nothing further is prunable`);
+    }
+    const includedSet = new Set(included);
+    const preview = {
+        sections: input.sections.map((s) => ({
+            title: s.title,
+            estimatedTokens: s.estimatedTokens,
+            included: includedSet.has(s),
+        })),
+        totalTokens: total,
+        budget,
+    };
+    return { sections: included, preview, totalTokens: total, pruned, modelContextTokens };
+};
+/**
+ * Derive the context-inspector view from an assembled prompt: every section (included and pruned)
+ * with its bucket, provenance and token cost — so the UI can attribute which context (and which
+ * memory entries, via provenance) influenced a turn, and show what was dropped and why.
+ */
+export const inspectAssembledPrompt = (assembled) => {
+    const prunedReason = new Map(assembled.pruned.map((p) => [p.section, p.reason]));
+    const view = (section, included) => ({
+        title: section.title,
+        providerId: section.providerId,
+        kind: section.kind ?? "user-context",
+        provenance: section.provenance,
+        estimatedTokens: section.estimatedTokens,
+        sensitivity: section.sensitivity,
+        included,
+        ...(prunedReason.has(section) ? { prunedReason: prunedReason.get(section) } : {}),
+    });
+    return {
+        sections: [
+            ...assembled.sections.map((s) => view(s, true)),
+            ...assembled.pruned.map((p) => view(p.section, false)),
+        ],
+        totalTokens: assembled.totalTokens,
+        budget: assembled.preview.budget,
+        modelContextTokens: assembled.modelContextTokens,
+        // Clamped at zero. The assembler refuses to overflow, so a negative remainder would be a bug reported as a
+        // number — and a UI drawing a negative bar is a UI nobody believes again.
+        remainingTokens: Math.max(0, assembled.modelContextTokens - assembled.totalTokens),
+    };
+};
+//# sourceMappingURL=assembler.js.map

package/dist/context/compaction.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Long-thread compaction — `docs/13-sessions-and-threads.md` → Long-thread compaction.
+ *
+ * When a thread's history outgrows the context budget, older turns are compacted into a durable,
+ * versioned thread summary rather than dropped. Recent turns and open tool continuity are preserved
+ * verbatim; only the older prefix is summarized. Compaction emits the `context.compacted` transport
+ * event so a client can show that history was condensed. The summarizer itself is injected, so this
+ * stays provider-neutral.
+ */
+import type { Message } from "../core/content-parts.js";
+import type { ConversationId, TenantId } from "../core/ids.js";
+import type { ThreadSummary, ThreadSummaryStore } from "../persistence/index.js";
+import type { ContextCompactedEvent } from "../core/events.js";
+/** Produces the condensed text for a batch of older messages, layering on any prior summary. */
+export interface ThreadSummarizer {
+    summarize(input: {
+        priorSummary?: string;
+        messages: readonly Message[];
+    }): Promise<string>;
+}
+export type CompactionResult = {
+    readonly summary: ThreadSummary;
+    /** Recent turns kept verbatim — these plus the summary feed the next prompt. */
+    readonly kept: readonly Message[];
+    /** The transport event to publish (worker stamps runId/sequence/occurredAt). */
+    readonly event: Omit<ContextCompactedEvent, "runId" | "sequence" | "occurredAt">;
+};
+/**
+ * Compact a thread's history. Returns null when there is nothing worth compacting (history at or
+ * under `keepRecent`, or no older messages survive the tool-continuity split). Otherwise summarizes
+ * the older prefix, appends a versioned `ThreadSummary`, and reports what was reclaimed.
+ */
+export declare const compactThread: (input: {
+    readonly tenantId: TenantId;
+    readonly conversationId: ConversationId;
+    /** Full history, oldest first. */
+    readonly messages: readonly Message[];
+    /** How many trailing messages to keep verbatim. */
+    readonly keepRecent: number;
+    readonly summaries: ThreadSummaryStore;
+    readonly summarizer: ThreadSummarizer;
+    /** Token estimate for a set of messages, used to report tokensReclaimed. */
+    readonly estimateTokens: (messages: readonly Message[]) => number;
+}) => Promise<CompactionResult | null>;
+//# sourceMappingURL=compaction.d.ts.map

package/dist/context/compaction.js

@@ -0,0 +1,55 @@
+/**
+ * Long-thread compaction — `docs/13-sessions-and-threads.md` → Long-thread compaction.
+ *
+ * When a thread's history outgrows the context budget, older turns are compacted into a durable,
+ * versioned thread summary rather than dropped. Recent turns and open tool continuity are preserved
+ * verbatim; only the older prefix is summarized. Compaction emits the `context.compacted` transport
+ * event so a client can show that history was condensed. The summarizer itself is injected, so this
+ * stays provider-neutral.
+ */
+import { estimateTokens } from "../core/tokens.js";
+const partCount = (messages) => messages.reduce((sum, m) => sum + m.parts.length, 0);
+/**
+ * Choose the split so the kept (recent) side never *starts* with a dangling tool result whose
+ * tool-call would be summarized away. Walk the boundary earlier while the first kept message is a
+ * tool message, preserving tool-call ↔ tool-result continuity.
+ */
+const splitPreservingToolContinuity = (messages, keepRecent) => {
+    let boundary = Math.max(0, messages.length - keepRecent);
+    while (boundary > 0 && messages[boundary]?.role === "tool")
+        boundary -= 1;
+    return { older: messages.slice(0, boundary), recent: messages.slice(boundary) };
+};
+/**
+ * Compact a thread's history. Returns null when there is nothing worth compacting (history at or
+ * under `keepRecent`, or no older messages survive the tool-continuity split). Otherwise summarizes
+ * the older prefix, appends a versioned `ThreadSummary`, and reports what was reclaimed.
+ */
+export const compactThread = async (input) => {
+    if (input.messages.length <= input.keepRecent)
+        return null;
+    const { older, recent } = splitPreservingToolContinuity(input.messages, input.keepRecent);
+    if (older.length === 0)
+        return null;
+    const prior = await input.summaries.latest({ tenantId: input.tenantId, conversationId: input.conversationId });
+    const text = await input.summarizer.summarize({
+        ...(prior ? { priorSummary: prior.summary } : {}),
+        messages: older,
+    });
+    const coversUpToMessageId = older[older.length - 1].id;
+    const summary = await input.summaries.append({
+        tenantId: input.tenantId,
+        conversationId: input.conversationId,
+        summary: text,
+        coversUpToMessageId,
+    });
+    // Tokens saved by replacing the older messages with the (smaller) summary text.
+    const summaryTokens = estimateTokens(text);
+    const tokensReclaimed = Math.max(0, input.estimateTokens(older) - summaryTokens);
+    return {
+        summary,
+        kept: recent,
+        event: { type: "context.compacted", droppedParts: partCount(older), tokensReclaimed },
+    };
+};
+//# sourceMappingURL=compaction.js.map

package/dist/context/index.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Context providers and prompt budgeting — `docs/03-intelligence-runtime.md`.
+ */
+import type { ExecutionContext } from "../core/context.js";
+import type { ContextOrigin } from "../security/prompt-safety.js";
+export type ContextSensitivity = "public" | "internal" | "confidential" | "restricted";
+/** Budget bucket a section draws from. Mirrors the fields of `ContextBudget`. */
+export type ContextKind = "base-policy" | "user-context" | "tools" | "skills" | "knowledge" | "history";
+export type ContextSection = {
+    readonly providerId: string;
+    readonly title: string;
+    readonly body: string;
+    /** Higher priority survives pruning longer. */
+    readonly priority: number;
+    readonly estimatedTokens: number;
+    /** Where this came from, so a claim in the output can be traced back. */
+    readonly provenance: string;
+    readonly sensitivity: ContextSensitivity;
+    /**
+     * Whether this content may instruct the agent (#145, AC-4).
+     *
+     * **Required, with no default.** A provider has to decide, so "nobody thought about it" is a compile error
+     * rather than external content quietly reaching the system prompt as instruction.
+     *
+     * Not the same as `sensitivity`, and the difference matters in the worst direction. Sensitivity is
+     * *confidentiality* — who may see this. Origin is *provenance* — may this instruct. A page fetched off the
+     * public web is `public` sensitivity and the least trustworthy content in the system.
+     *
+     * `external` content is rendered inside a delimited envelope with delimiter forgery neutralised; see
+     * `security/prompt-safety.ts`. A `platform` section that *interpolates* untrusted values — a filename, a tool
+     * name, a user-supplied label — stays `platform` and neutralises those values itself, so the section's own
+     * instructions are not swallowed by an envelope that says nothing inside it is an instruction.
+     */
+    readonly origin: ContextOrigin;
+    readonly cacheable: boolean;
+    readonly expiresAt?: string;
+    /** Budget bucket. Defaults to `user-context` when a provider does not specify one. */
+    readonly kind?: ContextKind;
+    /** When set, this section is eligible for pruning in that stage. Unset ⇒ preserved (recent turns,
+     * open tool continuity, base policy). */
+    readonly pruneStage?: PruneStage;
+};
+export interface ContextProvider {
+    readonly id: string;
+    provide(context: ExecutionContext): Promise<readonly ContextSection[]>;
+}
+/** Explicit per-section budgets rather than one undifferentiated window. */
+export type ContextBudget = {
+    readonly basePolicyTokens: number;
+    readonly userContextTokens: number;
+    readonly toolTokens: number;
+    readonly skillTokens: number;
+    readonly knowledgeTokens: number;
+    readonly historyTokens: number;
+};
+/**
+ * Pruning order. Old reasoning and tool detail go first; recent semantic turns and tool
+ * continuity are preserved. If the prompt still will not fit, assembly fails loudly
+ * rather than silently truncating critical instructions.
+ */
+export declare const PRUNE_ORDER: readonly ["old-reasoning", "old-tool-detail", "old-knowledge", "old-turns"];
+export type PruneStage = (typeof PRUNE_ORDER)[number];
+/** Per-section token estimates, so prompt composition is previewable. */
+export type PromptPreview = {
+    readonly sections: readonly {
+        readonly title: string;
+        readonly estimatedTokens: number;
+        readonly included: boolean;
+    }[];
+    readonly totalTokens: number;
+    readonly budget: ContextBudget;
+};
+export * from "./assembler.js";
+export * from "./compaction.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/context/index.js

@@ -0,0 +1,17 @@
+/**
+ * Context providers and prompt budgeting — `docs/03-intelligence-runtime.md`.
+ */
+/**
+ * Pruning order. Old reasoning and tool detail go first; recent semantic turns and tool
+ * continuity are preserved. If the prompt still will not fit, assembly fails loudly
+ * rather than silently truncating critical instructions.
+ */
+export const PRUNE_ORDER = [
+    "old-reasoning",
+    "old-tool-detail",
+    "old-knowledge",
+    "old-turns",
+];
+export * from "./assembler.js";
+export * from "./compaction.js";
+//# sourceMappingURL=index.js.map