@agentskit/doc-bridge 1.7.45 → 1.9.0

package/src/budget/compile.ts

@@ -0,0 +1,91 @@
+/**
+ * Token budgets, in the shape `@agentskit/core` gives them.
+ *
+ * `compileBudget` and `approximateCounter` below mirror the functions of the same name in
+ * `@agentskit/core`, restricted to what a deterministic payload needs: the `drop-oldest`
+ * strategy over plain role/content messages, with no system prompt, tools or summariser. The
+ * core package is an optional peer and every query surface must answer with no peer installed,
+ * so the algorithm lives here and a test runs the real `compileBudget` over the same messages
+ * and asserts the two agree on every token count, every dropped message and `fits`.
+ *
+ * The mirror is synchronous where the original is a promise: nothing here can await, and the
+ * MCP handlers that call it answer in one turn.
+ */
+
+export type BudgetMessage = {
+  readonly role: string
+  readonly content: string
+}
+
+export type BudgetTokenCounter = {
+  readonly name: string
+  readonly count: (messages: readonly BudgetMessage[]) => number
+}
+
+/**
+ * Four characters per token, plus two per message, over role and content — the rule of thumb
+ * `@agentskit/core` uses. Good enough for budget planning, and reported as such.
+ */
+export const approximateCounter: BudgetTokenCounter = {
+  name: 'approximate',
+  count: (messages) => messages.reduce((total, message) => total + Math.ceil((message.role.length + message.content.length) / 4) + 2, 0),
+}
+
+export const TOKEN_METHOD = 'approximate' as const
+
+export type CompileBudgetInput = {
+  /** Hard upper bound on the tokens of what is kept. */
+  readonly budget: number
+  /** Oldest first: the front of the list is dropped first. */
+  readonly messages: readonly BudgetMessage[]
+  readonly counter?: BudgetTokenCounter
+  /** Never drop below this many messages, counted from the end. Default 1. */
+  readonly keepRecent?: number
+  readonly reserveForOutput?: number
+}
+
+export type CompileBudgetResult = {
+  readonly messages: readonly BudgetMessage[]
+  readonly tokens: {
+    readonly system: number
+    readonly messages: number
+    readonly tools: number
+    readonly total: number
+    readonly budget: number
+  }
+  readonly dropped: readonly BudgetMessage[]
+  readonly fits: boolean
+  readonly strategy: 'drop-oldest'
+}
+
+/**
+ * Drop the oldest messages until the rest fits the budget, keeping at least `keepRecent`.
+ *
+ * The last message is never dropped by default, which is what makes the strategy usable for a
+ * payload: the section that must survive is placed last, and the sections that may go are placed
+ * first, in the order they may go. `fits` is false only when what could not be dropped still
+ * exceeds the budget — an honest answer rather than a truncated one.
+ */
+export const compileBudget = (input: CompileBudgetInput): CompileBudgetResult => {
+  const counter = input.counter ?? approximateCounter
+  const keepRecent = Math.max(1, input.keepRecent ?? 1)
+  const reserve = input.reserveForOutput ?? 0
+  const budget = input.budget - reserve
+  if (budget <= 0) throw new Error(`Budget must exceed reserveForOutput (${input.budget} ≤ ${reserve})`)
+
+  const messages = [...input.messages]
+  const dropped: BudgetMessage[] = []
+  let total = counter.count(messages)
+  while (messages.length > keepRecent && total > budget) {
+    dropped.push(messages.shift() as BudgetMessage)
+    total = counter.count(messages)
+  }
+
+  return {
+    messages,
+    tokens: { system: 0, messages: total, tools: 0, total, budget },
+    dropped,
+    fits: total <= budget,
+    strategy: 'drop-oldest',
+  }
+}

package/src/budget/sections.ts

@@ -0,0 +1,70 @@
+import { BUDGET_SECTION_ORDER, type BudgetReport, type BudgetSection } from '../schemas/budget.js'
+import { compileBudget, TOKEN_METHOD, type BudgetMessage } from './compile.js'
+
+/**
+ * One droppable section of a payload: what it contributes, and the payload without it.
+ *
+ * `content` is what the section costs — the strings a reader would lose — and `strip` removes
+ * exactly that from the payload, so the payload with the section stripped and the section's
+ * content together are the whole payload. A section whose content is empty is absent from the
+ * report rather than reported kept: nothing was there to keep.
+ */
+export type BudgetedSection<T> = {
+  readonly name: BudgetSection
+  readonly content: unknown
+  readonly strip: (payload: T) => T
+}
+
+/** Every message wears the same role, so the role's length never favours one section over another. */
+const ROLE = 'user'
+
+const isEmpty = (value: unknown): boolean =>
+  value === undefined ||
+  value === null ||
+  (Array.isArray(value) && value.length === 0) ||
+  (typeof value === 'object' && Object.keys(value as object).length === 0) ||
+  (typeof value === 'string' && value.length === 0)
+
+/**
+ * Trim a payload to a token budget, section by section, in the declared order.
+ *
+ * Each present section becomes one message, oldest first in the order they may be dropped, and
+ * the payload with every section stripped becomes the last message — the one `compileBudget`
+ * never drops. The result is the payload with the dropped sections stripped and a report of what
+ * it cost, what was dropped and whether it fits. Two calls over the same payload and budget give
+ * the same report: the counter is arithmetic over the serialised sections.
+ */
+export const applyBudget = <T>(payload: T, sections: readonly BudgetedSection<T>[], budgetTokens: number): { readonly payload: T; readonly budget: BudgetReport } => {
+  const present = BUDGET_SECTION_ORDER.map((name) => sections.find((section) => section.name === name)).filter(
+    (section): section is BudgetedSection<T> => section !== undefined && !isEmpty(section.content),
+  )
+  const core = present.reduce((value, section) => section.strip(value), payload)
+  const messages: BudgetMessage[] = [
+    ...present.map((section) => ({ role: ROLE, content: JSON.stringify(section.content) })),
+    { role: ROLE, content: JSON.stringify(core) },
+  ]
+  const compiled = compileBudget({ budget: budgetTokens, messages, keepRecent: 1 })
+
+  const droppedNames = present.slice(0, compiled.dropped.length).map((section) => section.name)
+  const keptSections = present.slice(compiled.dropped.length)
+  const tokensOf = (message: BudgetMessage): number => compileBudget({ budget: budgetTokens, messages: [message] }).tokens.total
+  const sectionTokens = Object.fromEntries(present.map((section, position) => [section.name, tokensOf(messages[position] as BudgetMessage)])) as Record<BudgetSection, number>
+
+  return {
+    payload: present.slice(0, compiled.dropped.length).reduce((value, section) => section.strip(value), payload),
+    budget: {
+      budgetTokens,
+      tokens: {
+        total: compiled.tokens.total,
+        budget: compiled.tokens.budget,
+        core: tokensOf(messages[messages.length - 1] as BudgetMessage),
+        sections: sectionTokens,
+      },
+      fits: compiled.fits,
+      order: [...BUDGET_SECTION_ORDER],
+      kept: keptSections.map((section) => section.name),
+      dropped: droppedNames,
+      tokenMethod: TOKEN_METHOD,
+    },
+  }
+}