@agentskit/doc-bridge 1.7.45 → 1.10.0

package/src/query/handoff.ts

@@ -0,0 +1,326 @@
+import type { DocBridgeConfigV1 } from '../config/schema.js'
+import { defaultChecksForTarget } from '../lib/package-manager.js'
+import { normalizeAgentHandoff, type AgentHandoffV1, type HandoffRelated } from '../schemas/agent-handoff.js'
+import type { DocBridgeIndexV1 } from '../schemas/doc-bridge-index.js'
+import type { RetrievalEntry, RetrievalIndexV1 } from '../schemas/retrieval-index.js'
+
+/**
+ * A handoff for any entity the projection knows.
+ *
+ * `handoffForPackage` could answer for an ownership record and nothing else: an agent asking
+ * about a module, an area or a document got "unknown package". Now the answer is derived from
+ * the graph — which documents cover the target, which mention it, what its code depends on — and
+ * every field says which relations produced it, so a handoff that points somewhere odd is a
+ * finding about the repository rather than a mystery about the tool.
+ */
+
+export type HandoffOptions = {
+  /** The project root, for the package-script fallback when nothing declares checks. */
+  readonly root?: string
+}
+
+type OwnershipRecord = NonNullable<NonNullable<DocBridgeIndexV1['lookup']>['ownership']>[string]
+
+const MAX_RELATED = 3
+const MAX_READ_BEFORE = 2
+const MAX_RELATED_EVIDENCE = 3
+
+const dirname = (path: string): string => path.split('/').slice(0, -1).join('/') || '.'
+
+const isHttp = (value: string): boolean => /^https?:\/\//.test(value)
+
+const bridgeFor = (config: DocBridgeConfigV1, id: string, humanDoc: string | undefined): AgentHandoffV1['bridge'] | undefined =>
+  humanDoc
+    ? { humanDoc: isHttp(humanDoc) ? 'external' : 'linked' }
+    : config.corpus.human
+      ? { humanDoc: 'missing', action: 'ak-docs bootstrap agent-docs', bootstrap: `docs/for-agents/human/${id}.md` }
+      : undefined
+
+/**
+ * The handoff for an index built before the projection existed: an ownership record, or nothing.
+ */
+const legacyHandoff = (index: DocBridgeIndexV1, id: string, config: DocBridgeConfigV1): AgentHandoffV1 => {
+  const fromIndex = index.handoffs?.[id]
+  if (fromIndex) return normalizeAgentHandoff(fromIndex)
+
+  const owner = index.lookup?.ownership?.[id]
+  if (!owner) throw new Error(`Unknown package/ownership id "${id}". Try: ak-docs list packages`)
+  const bridge = bridgeFor(config, id, owner.humanDoc)
+
+  return normalizeAgentHandoff({
+    type: 'agent-handoff',
+    source: config.index?.outFile ?? '.doc-bridge/index.json',
+    target: {
+      type: 'package',
+      id,
+      path: owner.path,
+      ...(owner.group ? { group: owner.group } : {}),
+      ...(owner.layer ? { layer: owner.layer } : {}),
+    },
+    startHere: owner.agentDoc ?? config.corpus.agent.index ?? '',
+    readBeforeEditing: [owner.agentDoc, 'AGENTS.md'].filter(Boolean),
+    editRoots: [owner.path],
+    checks: [...owner.checks],
+    ...(owner.humanDoc ? { humanDoc: owner.humanDoc } : {}),
+    ...(bridge ? { bridge } : {}),
+    notes: [
+      ...(owner.purpose ? [owner.purpose] : []),
+      ...(!owner.humanDoc && config.corpus.human ? [`Human guide missing for ${id}. Run: ak-docs bootstrap agent-docs`] : []),
+    ],
+  })
+}
+
+/**
+ * Which entry an identifier names: an entity id, an ownership id, an alias, or a path.
+ *
+ * Ownership ids win over aliases because they are what a routing command has always accepted;
+ * a path is accepted last, since `src/query` is a directory before it is a name.
+ */
+export const resolveHandoffEntry = (projection: RetrievalIndexV1, id: string): RetrievalEntry | undefined => {
+  const trimmed = id.replace(/\/$/, '')
+  return (
+    projection.entries.find((entry) => entry.id === trimmed) ??
+    projection.entries.find((entry) => entry.ownershipId === trimmed) ??
+    projection.entries.find((entry) => entry.aliases.includes(trimmed)) ??
+    projection.entries.find((entry) => entry.path === trimmed && (entry.kind === 'area' || entry.kind === 'package')) ??
+    projection.entries.find((entry) => entry.path === trimmed)
+  )
+}
+
+type DocumentPick = { readonly path: string; readonly reason: string }
+
+/**
+ * Where to start reading, and why.
+ *
+ * Order of authority: a document that declares it covers the target; one that mentions it; one
+ * that links to those; and, failing all of that, the most canonical document the unit's
+ * ownership names. Within each tier the more canonical page comes first, so the entry point
+ * other pages point at beats the leaf note that happens to mention the target too.
+ */
+const documentsFor = (
+  projection: RetrievalIndexV1,
+  byId: ReadonlyMap<string, RetrievalEntry>,
+  target: RetrievalEntry,
+  ownership: OwnershipRecord | undefined,
+): DocumentPick[] => {
+  const picks: DocumentPick[] = []
+  const seen = new Set<string>()
+  const add = (entry: RetrievalEntry | undefined, reason: string): void => {
+    if (!entry || entry.kind !== 'document' || seen.has(entry.path)) return
+    seen.add(entry.path)
+    picks.push({ path: entry.path, reason })
+  }
+  const byRank = (ids: readonly string[]): RetrievalEntry[] =>
+    ids
+      .map((id) => byId.get(id))
+      .filter((entry): entry is RetrievalEntry => Boolean(entry))
+      .sort((a, b) => b.graph.pagerank - a.graph.pagerank || a.id.localeCompare(b.id))
+
+  if (ownership?.agentDoc) add(projection.entries.find((entry) => entry.path === ownership.agentDoc), `ownership ${ownership.id} names it as the agent document`)
+  for (const entry of byRank(target.graph.coveredBy)) add(entry, `covers ${target.id}`)
+  for (const entry of byRank(target.graph.mentionedBy)) add(entry, `mentions ${target.id}`)
+  if (target.kind === 'document') {
+    add(target, 'the target itself')
+    for (const edge of target.graph.outbound.filter((item) => item.kind === 'links-to')) add(byId.get(edge.id), `${target.id} links to it`)
+  }
+
+  // One links-to hop from what covers or mentions the target: the page that introduces the page.
+  for (const near of [...picks]) {
+    const document = projection.entries.find((entry) => entry.path === near.path)
+    for (const edge of document?.graph.inbound.filter((item) => item.kind === 'links-to') ?? []) add(byId.get(edge.id), `links to ${document?.id}`)
+  }
+
+  return picks
+}
+
+/** The strongest import relationships between this unit and the other areas, both directions. */
+const relatedAreas = (projection: RetrievalIndexV1, byId: ReadonlyMap<string, RetrievalEntry>, target: RetrievalEntry): HandoffRelated[] => {
+  const unitOf = (entry: RetrievalEntry): string | undefined =>
+    target.kind === 'package' ? entry.graph.packageId : (entry.graph.areaId ?? entry.graph.packageId)
+  const mine = target.kind === 'module' ? unitOf(target) : target.id
+  if (!mine) return []
+
+  const crossings = new Map<string, { direction: HandoffRelated['direction']; count: number; examples: string[] }>()
+  const note = (unit: string, direction: HandoffRelated['direction'], example: string): void => {
+    const key = `${direction}:${unit}`
+    const existing = crossings.get(key)
+    if (existing) {
+      existing.count += 1
+      if (existing.examples.length < MAX_RELATED_EVIDENCE) existing.examples.push(example)
+    } else crossings.set(key, { direction, count: 1, examples: [example] })
+  }
+
+  for (const module of projection.entries) {
+    if (module.kind !== 'module') continue
+    const from = unitOf(module)
+    if (!from) continue
+    for (const edge of module.graph.outbound) {
+      if (edge.kind !== 'imports' && edge.kind !== 're-exports') continue
+      const imported = byId.get(edge.id)
+      const to = imported ? unitOf(imported) : undefined
+      if (!to || to === from) continue
+      if (from === mine) note(to, 'imports', `${module.path} → ${imported?.path ?? edge.id}`)
+      else if (to === mine) note(from, 'imported-by', `${module.path} → ${imported?.path ?? edge.id}`)
+    }
+  }
+
+  const rows = [...crossings.entries()]
+    .map(([key, value]) => ({ unit: key.slice(key.indexOf(':') + 1), ...value }))
+    .sort((a, b) => b.count - a.count || a.unit.localeCompare(b.unit))
+  const pick = (direction: HandoffRelated['direction']): HandoffRelated[] =>
+    rows
+      .filter((row) => row.direction === direction)
+      .slice(0, MAX_RELATED)
+      .map((row) => ({
+        id: row.unit,
+        path: byId.get(row.unit)?.path ?? row.unit,
+        direction,
+        strength: row.count,
+        evidence: row.examples,
+      }))
+  return [...pick('imports'), ...pick('imported-by')]
+}
+
+type Checks = { readonly checks: readonly string[]; readonly source: string; readonly reason: string }
+
+/**
+ * Which checks to run, and where that answer came from.
+ *
+ * An ownership override wins; then whatever the index recorded when it merged frontmatter,
+ * package scripts and defaults (it recorded the source at the time); then the package-manager
+ * default for the unit's package, which needs the project root to read package.json.
+ */
+const checksFor = (
+  index: DocBridgeIndexV1,
+  config: DocBridgeConfigV1,
+  target: RetrievalEntry,
+  ownership: OwnershipRecord | undefined,
+  unitPath: string,
+  packageEntry: RetrievalEntry | undefined,
+  options: HandoffOptions,
+): Checks => {
+  const override = ownership ? config.routing?.options?.ownership?.[ownership.id]?.checks : undefined
+  if (override?.length) return { checks: override, source: 'ownership', reason: `routing.options.ownership.${ownership?.id}.checks` }
+  if (ownership?.checks.length) {
+    const source = ownership.checksSource ?? 'default'
+    return { checks: ownership.checks, source, reason: `ownership ${ownership.id} recorded its checks from ${source}` }
+  }
+  // A module or area inside an owned package inherits that package's checks.
+  const owningRecord = packageEntry?.ownershipId ? index.lookup?.ownership?.[packageEntry.ownershipId] : undefined
+  if (owningRecord?.checks.length) {
+    const source = owningRecord.checksSource ?? 'default'
+    return { checks: owningRecord.checks, source, reason: `inherited from ownership ${owningRecord.id} (${source})` }
+  }
+  if (options.root) {
+    const strict = (config.gates?.preset ?? 'minimal') !== 'minimal'
+    const packageName = packageEntry?.aliases.find((alias) => alias.includes('/')) ?? packageEntry?.title
+    const checks = defaultChecksForTarget(options.root, {
+      packageId: packageEntry?.id ?? target.id,
+      packagePath: packageEntry?.path ?? unitPath,
+      ...(packageName ? { packageName } : {}),
+      strict,
+    })
+    return { checks, source: 'default', reason: 'package-manager default for the unit\'s package' }
+  }
+  return { checks: [], source: 'default', reason: 'nothing declares checks and no project root was given to read package scripts' }
+}
+
+const targetType = (kind: RetrievalEntry['kind']): AgentHandoffV1['target']['type'] =>
+  kind === 'area' ? 'area' : kind === 'document' ? 'document' : kind === 'module' ? 'module' : 'package'
+
+/**
+ * Build the handoff for a package, an area, a module or a document.
+ *
+ * `editRoots` is the unit an agent may write in: the area or package itself, a module's area,
+ * a document's own path. `startHere` and `readBeforeEditing` come from the documentation graph.
+ * `related` names the areas this unit's code depends on and that depend on it, with the import
+ * that proves each. `explain` says which relation produced each field.
+ */
+export const handoffForEntity = (index: DocBridgeIndexV1, id: string, config: DocBridgeConfigV1, options: HandoffOptions = {}): AgentHandoffV1 => {
+  const projection = index.projection
+  if (!projection) return legacyHandoff(index, id, config)
+
+  const target = resolveHandoffEntry(projection, id)
+  if (!target) {
+    const fallback = index.lookup?.ownership?.[id] ? legacyHandoff(index, id, config) : undefined
+    if (fallback) return fallback
+    throw new Error(`Unknown entity "${id}". Try: ak-docs list packages, or ak-docs search "${id}"`)
+  }
+  if (target.kind === 'intent' || target.kind === 'change') {
+    throw new Error(`"${id}" is a ${target.kind} route. Try: ak-docs query ${target.kind} ${target.id} --agent`)
+  }
+
+  const byId = new Map(projection.entries.map((entry) => [entry.id, entry]))
+  const ownership = target.ownershipId ? index.lookup?.ownership?.[target.ownershipId] : undefined
+  const area = target.graph.areaId ? byId.get(target.graph.areaId) : undefined
+  const packageEntry = target.graph.packageId ? byId.get(target.graph.packageId) : target.kind === 'package' ? target : undefined
+  const explain: Record<string, string[]> = {}
+
+  // The unit an agent may write in.
+  const unit =
+    target.kind === 'module'
+      ? area
+        ? { path: area.path, reason: `contained by area ${area.id}` }
+        : packageEntry
+          ? { path: packageEntry.path, reason: `contained by package ${packageEntry.id}` }
+          : { path: dirname(target.path), reason: 'the directory of the module; no area or package contains it' }
+      : { path: ownership?.path ?? target.path, reason: ownership ? `ownership ${ownership.id} path` : `the ${target.kind} itself` }
+  explain.editRoots = [unit.reason]
+
+  const documents = documentsFor(projection, byId, target, ownership)
+  const startHere = documents[0]?.path ?? config.corpus.agent.index ?? target.path
+  explain.startHere = [documents[0] ? documents[0].reason : 'no document covers, mentions or links to the target; the corpus index is the fallback']
+  const readBefore = documents.slice(1, 1 + MAX_READ_BEFORE)
+  explain.readBeforeEditing = readBefore.map((pick) => `${pick.path}: ${pick.reason}`)
+
+  const checks = checksFor(index, config, target, ownership, unit.path, packageEntry, options)
+  explain.checks = [checks.reason]
+
+  const related = target.kind === 'document' ? [] : relatedAreas(projection, byId, target)
+  if (related.length) explain.related = related.map((row) => `${row.direction} ${row.id}: ${row.strength} import(s), e.g. ${row.evidence[0] ?? ''}`.trim())
+
+  const humanDoc = ownership?.humanDoc
+  const bridge = bridgeFor(config, ownership?.id ?? target.id, humanDoc)
+  const evidence: NonNullable<AgentHandoffV1['evidence']> = [
+    {
+      source: target.kind === 'module' ? 'code' : target.kind === 'document' ? 'documentation' : 'derived',
+      path: target.path,
+      contentHash: target.contentHash,
+      context: `${target.kind} ${target.id}`,
+    },
+    ...documents.slice(0, 1 + MAX_READ_BEFORE).map((pick) => ({ source: 'documentation' as const, path: pick.path, context: pick.reason })),
+  ]
+
+  return normalizeAgentHandoff({
+    type: 'agent-handoff',
+    source: config.index?.outFile ?? '.doc-bridge/index.json',
+    target: {
+      type: targetType(target.kind),
+      id: ownership?.id ?? target.id,
+      path: target.path,
+      ...(ownership?.group ? { group: ownership.group } : {}),
+      ...(ownership?.layer ? { layer: ownership.layer } : {}),
+    },
+    startHere,
+    readBeforeEditing: [...new Set([...readBefore.map((pick) => pick.path), 'AGENTS.md'])],
+    editRoots: [unit.path],
+    checks: [...checks.checks],
+    ...(humanDoc ? { humanDoc } : {}),
+    ...(bridge ? { bridge } : {}),
+    notes: [
+      ...(target.summary ? [target.summary] : []),
+      ...(!humanDoc && config.corpus.human && ownership ? [`Human guide missing for ${ownership.id}. Run: ak-docs bootstrap agent-docs`] : []),
+    ],
+    ...(related.length ? { related } : {}),
+    explain,
+    evidence,
+    metadata: {
+      entityId: target.id,
+      kind: target.kind,
+      checksSource: checks.source,
+      confidence: target.confidence,
+      ...(area ? { areaId: area.id } : {}),
+      ...(packageEntry ? { packageId: packageEntry.id } : {}),
+    },
+  })
+}

package/src/query/load-index.ts

@@ -4,6 +4,10 @@ import { join, resolve } from 'node:path'
 import type { DocBridgeConfigV1 } from '../config/schema.js'
 import type { DocBridgeIndexV1 } from '../schemas/doc-bridge-index.js'
 import { parseDocBridgeIndex } from '../validate.js'
+import { buildDocBridgeIndex } from '../index-builder/build-index.js'
+import { repositoryInputs } from '../index-builder/project-corpus.js'
+import { GRAPH_ANALYZER_VERSION } from '../graph/build.js'
+import { SEARCH_LEXICON_VERSION } from './text.js'
 
 export class IndexNotFoundError extends Error {
   constructor(readonly path: string) {
@@ -12,6 +16,13 @@ export class IndexNotFoundError extends Error {
   }
 }
 
+export class IndexStaleError extends Error {
+  constructor(readonly path: string, readonly actual: string, readonly expected: string) {
+    super(`Index is stale at ${path}. Run: ak-docs index`)
+    this.name = 'IndexStaleError'
+  }
+}
+
 export const indexFilePath = (root: string, config: DocBridgeConfigV1): string =>
   join(root, config.index?.outFile ?? '.doc-bridge/index.json')
 
@@ -22,4 +33,45 @@ export const loadDocBridgeIndex = (root: string, config: DocBridgeConfigV1): Doc
   return parseDocBridgeIndex(raw)
 }
 
-export const resolveRoot = (cwd?: string): string => resolve(cwd ?? process.cwd())
+/**
+ * Load only an index whose content matches the current repository inputs.
+ *
+ * Every query goes through here, so the check has to be cheap. An index that records its inputs
+ * is verified by re-hashing those inputs — one walk — instead of rebuilding the whole index,
+ * which on a repository of any size meant projecting and parsing the corpus on every search. The
+ * hash covers the input files and the configuration, and the recorded lexicon version is checked
+ * too, because a changed stopword list changes ranking without changing a single file.
+ *
+ * An index built before inputs were recorded falls back to the full rebuild, so an older artifact
+ * is still validated rather than trusted.
+ */
+export const loadFreshDocBridgeIndex = (root: string, config: DocBridgeConfigV1): DocBridgeIndexV1 => {
+  const index = loadDocBridgeIndex(root, config)
+
+  if (index.inputs && index.retrieval) {
+    const inputs = repositoryInputs(root, config)
+    /*
+     * The projection is a function of the snapshot, the overlay and the configuration under a
+     * given lexicon and graph-metrics version; a change to either version changes ranking without
+     * changing a file, so both are checked next to the inputs.
+     */
+    const projectionFresh =
+      !index.projection ||
+      (index.projection.lexiconVersion === SEARCH_LEXICON_VERSION && index.projection.graphMetricsVersion === GRAPH_ANALYZER_VERSION)
+    const fresh =
+      index.inputs.hash === inputs.hash &&
+      index.inputs.projectionVersion === inputs.projectionVersion &&
+      index.retrieval.lexiconVersion === SEARCH_LEXICON_VERSION &&
+      projectionFresh
+    if (!fresh) throw new IndexStaleError(indexFilePath(root, config), index.inputs.hash, inputs.hash)
+    return index
+  }
+
+  const expected = buildDocBridgeIndex({ root, config, write: false }).index
+  if (index.contentHash !== expected.contentHash) {
+    throw new IndexStaleError(indexFilePath(root, config), index.contentHash, expected.contentHash)
+  }
+  return index
+}
+
+export const resolveRoot = (cwd?: string): string => resolve(cwd ?? process.cwd())

package/src/query/query.ts

@@ -1,11 +1,15 @@
 import type { DocBridgeConfigV1 } from '../config/schema.js'
 import {
   normalizeAgentHandoff,
+  AgentQueryModeSchema,
   type AgentHandoffV1,
+  type AgentQueryMode,
   type AgentSearchV1,
 } from '../schemas/agent-handoff.js'
 import type { DocBridgeIndexV1 } from '../schemas/doc-bridge-index.js'
+import { handoffForEntity, type HandoffOptions } from './handoff.js'
 import { searchIndex } from './search.js'
+import { Buffer } from 'node:buffer'
 
 export type QueryKind = 'package' | 'ownership' | 'intent' | 'change' | 'search'
 
@@ -14,6 +18,10 @@ export type QueryRequest = {
   readonly id?: string
   readonly term?: string
   readonly agent?: boolean
+  /** Attach the matched terms and scoring components to search results. Never changes the ranking. */
+  readonly explain?: boolean
+  readonly mode?: AgentQueryMode
+  readonly contextBudgetTokens?: number
 }
 
 export type QueryResult =
@@ -21,63 +29,91 @@ export type QueryResult =
   | AgentHandoffV1
   | AgentSearchV1
 
-const handoffForPackage = (
-  index: DocBridgeIndexV1,
-  id: string,
-  config: DocBridgeConfigV1,
-): AgentHandoffV1 => {
-  const fromIndex = index.handoffs?.[id]
-  if (fromIndex) return normalizeAgentHandoff(fromIndex)
-
-  const owner = index.lookup?.ownership?.[id]
-  if (!owner) throw new Error(`Unknown package/ownership id "${id}". Try: ak-docs list packages`)
+export const DEFAULT_AGENT_CONTEXT_BUDGET_TOKENS = 32
 
-  const bridge = owner.humanDoc
-    ? /^https?:\/\//.test(owner.humanDoc)
-      ? { humanDoc: 'external' as const }
-      : { humanDoc: 'linked' as const }
-    : config.corpus.human
-      ? {
-          humanDoc: 'missing' as const,
-          action: 'ak-docs bootstrap agent-docs',
-          bootstrap: `docs/for-agents/human/${id}.md`,
-        }
-      : undefined
+const modeLimits: Record<AgentQueryMode, { readonly matches: number; readonly nextCommands: number }> = {
+  discovery: { matches: 8, nextCommands: 5 },
+  editing: { matches: 5, nextCommands: 3 },
+  debugging: { matches: 6, nextCommands: 4 },
+  documentation: { matches: 6, nextCommands: 3 },
+}
 
-  return normalizeAgentHandoff({
-    type: 'agent-handoff',
-    source: config.index?.outFile ?? '.doc-bridge/index.json',
-    target: {
-      type: 'package',
-      id,
-      path: owner.path,
-      ...(owner.group ? { group: owner.group } : {}),
-      ...(owner.layer ? { layer: owner.layer } : {}),
-    },
-    startHere: owner.agentDoc ?? config.corpus.agent.index ?? '',
-    readBeforeEditing: [owner.agentDoc, 'AGENTS.md'].filter(Boolean),
-    editRoots: [owner.path],
-    checks: [...owner.checks],
-    ...(owner.humanDoc ? { humanDoc: owner.humanDoc } : {}),
-    ...(bridge ? { bridge } : {}),
-    notes: [
-      ...(owner.purpose ? [owner.purpose] : []),
-      ...(!owner.humanDoc && config.corpus.human
-        ? [`Human guide missing for ${id}. Run: ak-docs bootstrap agent-docs`]
-        : []),
-    ],
-  })
+const boundedAgentContext = (
+  matches: readonly AgentSearchV1['matches'][number][],
+  nextCommands: readonly string[],
+  contextBudgetTokens: number,
+): { readonly matches: AgentSearchV1['matches']; readonly nextCommands: string[]; readonly contextBytes: number; readonly truncated: boolean } => {
+  if (!Number.isInteger(contextBudgetTokens) || contextBudgetTokens < 1 || contextBudgetTokens > 1_000_000) throw new Error('contextBudgetTokens must be an integer between 1 and 1000000.')
+  const maxBytes = contextBudgetTokens * 4
+  let boundedMatches = matches.map((match) => ({ ...match }))
+  let boundedCommands = [...nextCommands]
+  let truncated = false
+  const contextBytes = () => Buffer.byteLength(JSON.stringify({ matches: boundedMatches, nextCommands: boundedCommands }), 'utf8')
+  while (contextBytes() > maxBytes) {
+    const summaryIndex = [...boundedMatches].map((match) => match.summary !== undefined).lastIndexOf(true)
+    if (summaryIndex >= 0) {
+      const match = boundedMatches[summaryIndex]
+      if (match) {
+        const { summary: _summary, ...withoutSummary } = match
+        boundedMatches[summaryIndex] = withoutSummary
+        truncated = true
+        continue
+      }
+    }
+    if (boundedCommands.length > 1) {
+      boundedCommands.pop()
+      truncated = true
+      continue
+    }
+    if (boundedMatches.length > 1) {
+      boundedMatches.pop()
+      truncated = true
+      continue
+    }
+    if (boundedCommands.length > 0) {
+      boundedCommands.pop()
+      truncated = true
+      continue
+    }
+    break
+  }
+  const finalContextBytes = contextBytes()
+  if (finalContextBytes > maxBytes) throw new Error(`contextBudgetTokens ${contextBudgetTokens} is too small for the minimum grounded result.`)
+  return { matches: boundedMatches, nextCommands: boundedCommands, contextBytes: finalContextBytes, truncated }
 }
 
 export const runQuery = (
   index: DocBridgeIndexV1,
   config: DocBridgeConfigV1,
   req: QueryRequest,
+  options: HandoffOptions = {},
 ): QueryResult => {
   if (req.kind === 'search') {
     const term = req.term ?? req.id ?? ''
-    const matches = searchIndex(index, term)
+    const matches = searchIndex(index, term, 20, { ...(req.explain ? { explain: true } : {}), ...(req.agent ? { agent: true } : {}) })
     if (req.agent) {
+      const mode = AgentQueryModeSchema.parse(req.mode ?? 'discovery')
+      const limits = modeLimits[mode]
+      const focusedMatches = matches[0] && (matches[0].type === 'intent' || matches[0].type === 'change')
+        ? matches.filter((match) => match.type === matches[0]?.type).slice(0, 3)
+        : matches.slice(0, limits.matches)
+      const agentMatches = focusedMatches.map((m) => ({
+        type: m.type,
+        id: m.id,
+        path: m.path,
+        ...(m.summary ? { summary: m.summary } : {}),
+      }))
+      const nextCommands = [...new Set(focusedMatches.slice(0, limits.nextCommands).map((m) =>
+        m.type === 'intent'
+          ? `ak-docs query intent ${m.id} --agent`
+          : m.type === 'change'
+            ? `ak-docs query change ${m.id} --agent`
+            : m.type === 'ownership' || index.lookup?.ownership?.[m.id]
+          ? `ak-docs query ownership ${m.id} --agent`
+          : 'ak-docs list knowledge --text',
+      ))]
+      const budget = req.contextBudgetTokens ?? DEFAULT_AGENT_CONTEXT_BUDGET_TOKENS
+      const bounded = boundedAgentContext(agentMatches, nextCommands, budget)
       const payload: AgentSearchV1 = {
         type: 'agent-search',
         schemaVersion: 1,
@@ -90,21 +126,18 @@ export const runQuery = (
               id: matches[0].id,
               path: matches[0].path,
               ...(matches[0].summary ? { summary: matches[0].summary } : {}),
-              score: matches[0].score,
             }
           : null,
-        matches: matches.slice(0, 8).map((m) => ({
-          type: m.type,
-          id: m.id,
-          path: m.path,
-          ...(m.summary ? { summary: m.summary } : {}),
-          score: m.score,
-        })),
-        nextCommands: [...new Set(matches.slice(0, 5).map((m) =>
-          m.type === 'ownership' || index.lookup?.ownership?.[m.id]
-            ? `ak-docs query ownership ${m.id} --agent`
-            : 'ak-docs list knowledge --text',
-        ))],
+        matches: bounded.matches,
+        nextCommands: bounded.nextCommands,
+        telemetry: {
+          contextBytes: bounded.contextBytes,
+          estimatedTokens: Math.ceil(bounded.contextBytes / 4),
+          tokenMethod: 'estimate',
+          contextBudgetTokens: budget,
+          mode,
+          truncated: bounded.truncated,
+        },
       }
       return payload
     }
@@ -115,7 +148,7 @@ export const runQuery = (
   if (!id) throw new Error(`Missing id for query kind "${req.kind}"`)
 
   if (req.kind === 'package' || req.kind === 'ownership') {
-    if (req.agent) return handoffForPackage(index, id, config)
+    if (req.agent) return handoffForEntity(index, id, config, options)
     const owner = index.lookup?.ownership?.[id]
     return { type: req.kind, data: owner ?? index.handoffs?.[id] ?? null }
   }