@frontera-sdk/cli 1.53.23 → 1.53.25

package/src/local/local-sync-snapshot.ts

@@ -8,6 +8,7 @@ import { hash, itemHash, safePath, SYNC_KINDS, type RemoteItem, type SyncKind, t
 import { readOrgSettings, type OrgSettings } from './local-org-settings'
 import type { Portability } from './local-portability'
 import { readWorkspace, type SyncSource, type WorkspaceCatalogModel } from './local-sync-remote'
+import { agentPicks, isKnowledgeBaseNote, KNOWLEDGE_BASES_FEATURE, KNOWLEDGE_SETTINGS_REF, KNOWLEDGE_SIGN_IN, knowledgeBaseFolders, knowledgeReach, lockedFolders, readKnowledgeBases, type KnowledgeReach } from './local-knowledge-base-pull'
 import { REF_KINDS, type Directory, type RefKind, type Unresolved } from './local-sync-refs'
 
 /**
@@ -56,6 +57,10 @@ export interface SnapshotItem {
   assets?: string[]
   /** Its files recovered from the deployed bundle, not its source (`RemoteItem.recovered`). */
   recovered?: string[]
+  /** `RemoteItem.keptOnPlatform`. */
+  keptOnPlatform?: string[]
+  /** `RemoteItem.platformName`. */
+  platformName?: string
 }
 
 export interface RemoteSnapshot {
@@ -106,6 +111,12 @@ export interface RemoteSnapshot {
    * where the runtime differs. Absent on a platform without the route.
    */
   settings?: OrgSettings
+  /**
+   * The index listed knowledge bases that moved, and no one signed in could
+   * read them: the next fetch reads the whole index, so a sign-in brings them
+   * even though the cursor has moved past.
+   */
+  knowledgeUnread?: true
 }
 
 /**
@@ -196,7 +207,7 @@ export function snapshotItems(root: string, snap: RemoteSnapshot): RemoteItem[]
       files[path] = content
     }
     const assets = (s.assets ?? []).map((path) => ({ path, from: underDir(root, ASSETS_DIR, path) }))
-    return [{ ref, kind: s.kind, name: s.name, title: s.title, files, version: s.version, id: s.id, revision: s.revision, unresolved: s.unresolved, notes: s.notes, requires: s.requires, ...(s.portability ? { portability: s.portability } : {}), ...(s.state ? { state: s.state } : {}), ...(assets.length ? { assets } : {}), ...(s.recovered?.length ? { recovered: s.recovered } : {}) }]
+    return [{ ref, kind: s.kind, name: s.name, title: s.title, files, version: s.version, id: s.id, revision: s.revision, unresolved: s.unresolved, notes: s.notes, requires: s.requires, ...(s.portability ? { portability: s.portability } : {}), ...(s.state ? { state: s.state } : {}), ...(assets.length ? { assets } : {}), ...(s.recovered?.length ? { recovered: s.recovered } : {}), ...(s.keptOnPlatform?.length ? { keptOnPlatform: s.keptOnPlatform } : {}), ...(s.platformName ? { platformName: s.platformName } : {}) }]
   })
 }
 
@@ -243,6 +254,8 @@ function toSnapshotItem(item: RemoteItem, revision?: string): SnapshotItem {
     ...(item.state ? { state: item.state } : {}),
     ...(item.assets?.length ? { assets: item.assets.map((a) => a.path).sort((a, b) => (String(a) < String(b) ? -1 : String(a) > String(b) ? 1 : 0)) } : {}),
     ...(item.recovered?.length ? { recovered: [...item.recovered].sort((a, b) => (String(a) < String(b) ? -1 : String(a) > String(b) ? 1 : 0)) } : {}),
+    ...(item.keptOnPlatform?.length ? { keptOnPlatform: item.keptOnPlatform } : {}),
+    ...(item.platformName ? { platformName: item.platformName } : {}),
   }
 }
 
@@ -346,16 +359,46 @@ export interface FetchOptions {
   /** Read the whole index, and with it every deletion, even when the cursor is recent. */
   full?: boolean
   now?: Date
+  /** Knowledge bases' folders by id beyond the lock's: those an Apply just created, filed where the project has them. */
+  knowledgeBaseFolders?: ReadonlyMap<string, string>
 }
 
 const isKind = (k: string): k is SyncKind => (SYNC_KINDS as readonly string[]).includes(k)
 
+const KNOWLEDGE_BASE_PREFIX = 'knowledge-base/'
+const isBaseRef = (ref: string) => ref.startsWith(KNOWLEDGE_BASE_PREFIX) && ref !== KNOWLEDGE_SETTINGS_REF
+
+/**
+ * The index's knowledge bases filed by folder (`knowledgeBaseFolders`): the
+ * index names each as the platform does, and a project keeps the folder it
+ * holds. Returns the entries with their refs moved, every base's folder by id
+ * (those the snapshot holds unlisted too), and the platform's name of each ref
+ * filed under another.
+ */
+function fileIndexedBases(entries: IndexItem[], items: Record<string, SnapshotItem>, held: ReadonlyMap<string, string>, full: boolean) {
+  const listed = entries.filter((e) => e.kind === 'knowledge-base' && isBaseRef(e.ref))
+  const ids = new Set(listed.map((e) => e.id))
+  // An unlisted base keeps its folder; after a whole index it is gone, and its folder is free.
+  const kept = full ? [] : Object.values(items).filter((it) => it.kind === 'knowledge-base' && it.id && !ids.has(it.id) && it.name !== 'settings')
+  const folders = knowledgeBaseFolders(new Map(listed.map((e) => [e.id, e.ref.slice(KNOWLEDGE_BASE_PREFIX.length)])), held, kept.map((it) => it.name))
+  const platformNames = new Map<string, string>()
+  const filed = entries.map((e) => {
+    if (!ids.has(e.id) || !isBaseRef(e.ref)) return e
+    const ref = `${KNOWLEDGE_BASE_PREFIX}${folders.get(e.id)!}`
+    if (ref !== e.ref) platformNames.set(ref, e.ref.slice(KNOWLEDGE_BASE_PREFIX.length))
+    return { ...e, ref }
+  })
+  for (const it of kept) folders.set(it.id!, it.name)
+  return { entries: filed, folders, platformNames }
+}
+
 const WARNING_LABEL: Partial<Record<SyncKind, [string, string]>> = {
   agent: ['Agent', 'Agents'],
   workflow: ['Workflow', 'Workflows'],
   function: ['Function', 'Functions'],
   skill: ['Skill', 'Skills'],
   knowledge: ['Knowledge', 'Knowledge'],
+  'knowledge-base': ['Knowledge base', 'Knowledge bases'],
   plugin: ['Plugin', 'Plugins'],
 }
 
@@ -411,7 +454,8 @@ export async function fetchWorkspace(root: string, source: SyncSource, opts: Fet
   // Read on every fetch: small, and it has no revision of its own.
   const settings = capabilities.includes('settings') ? await readOrgSettings(source.workspace) : null
   if (!capabilities.includes('index')) {
-    const read = stopIfUnanswered(await readWorkspace(source, { blueprint: opts.blueprint }))
+    const read = stopIfUnanswered(await readWorkspace(source, { blueprint: opts.blueprint, knowledgeBaseFolders: lockedFolders(root), capabilities }))
+    if (!capabilities.includes(KNOWLEDGE_BASES_FEATURE)) for (const it of read.items) if (it.kind === 'agent') keepPicks(root, it)
     const items = Object.fromEntries(read.items.map((i) => [i.ref, toSnapshotItem(i)]))
     const next: RemoteSnapshot = {
       version: 1,
@@ -440,10 +484,15 @@ export async function fetchWorkspace(root: string, source: SyncSource, opts: Fet
   }
 
   const recentFull = previous?.fullIndexAt && now.getTime() - Date.parse(previous.fullIndexAt) < FULL_INDEX_EVERY_MS
-  const since = !opts.full && !keysChanged && previous && !previous.full && previous.cursor && recentFull ? previous.cursor : null
-  const index = await source.workspace.get<IndexAnswer>(`/v1/sync/index${since ? `?since=${encodeURIComponent(since)}` : ''}`)
-  const kinds = index.kinds.filter(isKind)
+  const since = !opts.full && !keysChanged && previous && !previous.full && previous.cursor && recentFull && !previous.knowledgeUnread ? previous.cursor : null
+  const answered = await source.workspace.get<IndexAnswer>(`/v1/sync/index${since ? `?since=${encodeURIComponent(since)}` : ''}`)
+  const kinds = answered.kinds.filter(isKind)
   const items: Record<string, SnapshotItem> = previous && !previous.full && !keysChanged ? { ...previous.items } : {}
+  // Knowledge bases the index lists are filed by the project's folders before anything reads the entries.
+  const indexedBases = kinds.includes('knowledge-base')
+  const held = new Map([...lockedFolders(root), ...(opts.knowledgeBaseFolders ?? [])])
+  const filedBases = indexedBases ? fileIndexedBases(answered.items, items, held, answered.full) : null
+  const index: IndexAnswer = filedBases ? { ...answered, items: filedBases.entries } : answered
   const groups: Partial<Record<SyncKind, string>> = previous && !previous.full && !keysChanged ? { ...previous.groups } : {}
   const skipped: Record<string, string> = previous && !previous.full && !keysChanged ? { ...previous.skipped } : {}
   const removed = new Set<string>()
@@ -485,10 +534,52 @@ export async function fetchWorkspace(root: string, source: SyncSource, opts: Fet
     for (const ref of Object.keys(skipped)) if (!listed.has(ref)) delete skipped[ref]
   }
 
+  // An Agent's picks are set outside its draft, so its revision does not move with them: an Agent whose picks moved
+  // is read again. Where the index lists knowledge bases, a pick moves its base's revision, so only then are they compared.
+  const knowledgeWarnings: string[] = []
+  const knowledgeNotes: string[] = []
+  let knowledge: KnowledgeReach | null = null
+  let bases: (Awaited<ReturnType<typeof readKnowledgeBases>> & { warnings: string[] }) | null = null
+  let picksMayMove = false
+  let knowledgeUnread = false
+  if (filedBases) {
+    const movedBases = [...only].filter((r) => r.startsWith(KNOWLEDGE_BASE_PREFIX))
+    picksMayMove = movedBases.some(isBaseRef) || [...removed].some(isBaseRef)
+    // An Agent read again needs the reach too: its picks are read with the bases' folders.
+    if (movedBases.length || picksMayMove || readKinds.has('agent')) {
+      knowledge = await knowledgeReach(source, filedBases.folders, knowledgeWarnings, capabilities)
+      stopIfUnanswered({ warnings: knowledgeWarnings })
+    }
+    if (knowledge && knowledge.state !== 'read') {
+      // Read when someone signed in can: kept as last read until then, and never taken as having nothing to file.
+      for (const ref of movedBases) only.delete(ref)
+      readKinds.delete('knowledge-base')
+      for (const [ref, it] of Object.entries(previous?.items ?? {})) {
+        if (it.kind === 'knowledge-base' && !(ref in items) && (!index.full || listed.has(ref))) items[ref] = it
+      }
+      knowledgeUnread = movedBases.length > 0
+      if (knowledgeUnread && knowledge.state === 'signed-out') knowledgeNotes.push(KNOWLEDGE_SIGN_IN)
+      picksMayMove = false
+    }
+  } else {
+    // The index has no entry for knowledge bases: read whole on every fetch, as the settings are.
+    knowledge = await knowledgeReach(source, held, knowledgeWarnings, capabilities)
+    bases = stopIfUnanswered({ ...(await readKnowledgeBases(knowledge, knowledgeWarnings)), warnings: knowledgeWarnings })
+    picksMayMove = true
+  }
+  if (knowledge?.state === 'read' && picksMayMove) {
+    for (const ref of await picksMoved(root, items, only, knowledge)) {
+      only.add(ref)
+      readKinds.add('agent')
+    }
+  }
+
   let read: Awaited<ReturnType<typeof readWorkspace>> | null = null
   if (readKinds.size) {
     // The Blueprint and evaluations are read whole whatever `only` says.
-    read = stopIfUnanswered(await readWorkspace(source, { kinds: readKinds, only, blueprint: opts.blueprint }))
+    read = stopIfUnanswered(await readWorkspace(source, { kinds: readKinds, only, blueprint: opts.blueprint, knowledgeBaseFolders: filedBases?.folders ?? held, capabilities, ...(knowledge ? { knowledge } : {}) }))
+    // Picks no one could read, or a platform does not take, are not "none": an Agent read again keeps those it had.
+    if (knowledge?.state === 'signed-out' || knowledge?.state === 'unread' || knowledge?.state === 'not-taken') for (const it of read.items) if (it.kind === 'agent') keepPicks(root, it)
   }
   const revisionOf = new Map(index.items.map((e) => [e.ref, e.revision]))
   const got = read?.items ?? []
@@ -502,10 +593,20 @@ export async function fetchWorkspace(root: string, source: SyncSource, opts: Fet
     if (!regroup.has(it.kind) && !only.has(it.ref)) continue
     // A kind read whole carries its group's revision (the Blueprint's release), so a pull records it
     // in the lock and a lost base can be read again at it.
-    items[it.ref] = toSnapshotItem(it, regroup.has(it.kind) ? groups[it.kind] : revisionOf.get(it.ref))
+    const platformName = filedBases?.platformNames.get(it.ref)
+    items[it.ref] = { ...toSnapshotItem(it, regroup.has(it.kind) ? groups[it.kind] : revisionOf.get(it.ref)), ...(platformName ? { platformName } : {}) }
     removed.delete(it.ref)
     delete skipped[it.ref]
   }
+  // The bases read whole replace the kind's items; a read that was not whole (signed out, failed) keeps the last.
+  const basesChanged = bases?.listed ? bases.items.filter((it) => previous?.items[it.ref]?.hash !== itemHash(it.files)) : []
+  if (bases?.listed) {
+    for (const [ref, it] of Object.entries(items)) if (it.kind === 'knowledge-base' && !bases.items.some((b) => b.ref === ref)) drop(ref)
+    for (const it of bases.items) {
+      items[it.ref] = toSnapshotItem(it)
+      removed.delete(it.ref)
+    }
+  }
   // Listed but nothing came back and nothing failed: a thing with no files (a workflow without a
   // definition). Remembered by revision so it is not read again until it changes; a failed read is retried.
   for (const ref of only) {
@@ -522,18 +623,61 @@ export async function fetchWorkspace(root: string, source: SyncSource, opts: Fet
     full: false,
     platformVersion,
     capabilities,
-    kinds,
+    // Every base the workspace reads was listed: one missing from the snapshot is deleted.
+    // Bases no one could read are not known to be gone: the kind is not covered until they are read.
+    kinds: knowledgeUnread ? kinds.filter((k) => k !== 'knowledge-base') : bases?.listed && knowledge?.state === 'read' ? [...kinds, 'knowledge-base'] : kinds,
     groups,
     skipped,
     items,
-    warnings: read?.warnings ?? [],
-    notes: read ? read.notes : previous?.notes ?? [],
+    warnings: [...(read?.warnings ?? []), ...knowledgeWarnings],
+    // Knowledge's own notes (a sign-in, settings left out) stay until the bases are read again.
+    notes: [
+      ...(read ? read.notes : (previous?.notes ?? []).filter((n) => !isKnowledgeBaseNote(n))),
+      ...(bases?.notes ?? []),
+      ...knowledgeNotes,
+      ...(filedBases && !readKinds.has('knowledge-base') && !knowledgeNotes.length ? (previous?.notes ?? []).filter((n) => isKnowledgeBaseNote(n) && !(read?.notes ?? []).includes(n)) : []),
+    ],
     ...(read ? { names: namesOf(read.directory) } : previous?.names ? { names: previous.names } : {}),
     ...(read?.models.length ? { models: read.models } : previous?.models ? { models: previous.models } : {}),
     organizationKey: !!source.organization,
     reader: SNAPSHOT_READER,
     ...(settings ? { settings } : previous?.settings ? { settings: previous.settings } : {}),
+    ...(knowledgeUnread ? { knowledgeUnread: true as const } : {}),
+  }
+  writeSnapshot(root, previous, next, [...got.filter((g) => g.ref in items), ...(bases?.listed ? bases.items : [])])
+  return { snapshot: next, changed: [...got.filter((g) => g.ref in items), ...basesChanged].map((g) => g.ref), removed: [...removed], fullIndex: index.full }
+}
+
+/** An Agent's `knowledgeBases` as the last fetch had them, else as the last pull wrote them, when this read could not see any. */
+function keepPicks(root: string, it: RemoteItem): void {
+  const path = `agents/${it.name}/agent.json`
+  const picksOf = (text: string | null | undefined) => {
+    try {
+      return (JSON.parse(text ?? '') as { knowledgeBases?: unknown }).knowledgeBases
+    } catch {
+      return undefined
+    }
   }
-  writeSnapshot(root, previous, next, got.filter((g) => g.ref in items))
-  return { snapshot: next, changed: got.filter((g) => g.ref in items).map((g) => g.ref), removed: [...removed], fullIndex: index.full }
+  const text = it.files[path]
+  if (text === undefined || picksOf(text) !== undefined) return
+  const had = picksOf(readUnder(root, REMOTE_DIR, path)) ?? picksOf(readBase(root, path))
+  if (!Array.isArray(had)) return
+  it.files[path] = `${JSON.stringify({ ...(JSON.parse(text) as Record<string, unknown>), knowledgeBases: had }, null, 2)}\n`
+}
+
+/** The Agents the snapshot holds whose picks on the platform differ from their agent.json's `knowledgeBases`. */
+async function picksMoved(root: string, items: Record<string, SnapshotItem>, only: ReadonlySet<string>, knowledge: KnowledgeReach): Promise<string[]> {
+  const agents = Object.entries(items).filter(([ref, it]) => it.kind === 'agent' && it.id && !only.has(ref))
+  const moved = await Promise.all(agents.map(async ([ref, it]) => {
+    const now = await agentPicks(knowledge, it.id!).catch(() => null)
+    if (!now) return null
+    let held: unknown = []
+    try {
+      held = (JSON.parse(readUnder(root, REMOTE_DIR, `agents/${it.name}/agent.json`) ?? '{}') as { knowledgeBases?: unknown }).knowledgeBases ?? []
+    } catch {
+      return ref
+    }
+    return JSON.stringify(held) === JSON.stringify(now.refs) ? null : ref
+  }))
+  return moved.filter((r): r is string => r !== null)
 }

package/src/main.ts

@@ -370,6 +370,19 @@ async function main(): Promise<number> {
       output.note(`acting as ${acting.persona.displayName} (${acting.persona.key}), a local persona`)
     }
 
+    // On the project's own local runtime, a command that acts as a person acts as its owner when it says so.
+    if (command.meta.localOwner && !personaToken && credential.token.startsWith('sk-') && !process.env.FRONTERA_TOKEN?.trim()) {
+      const local = localRuntimeAt(cwd, credential.apiUrl)
+      if (local?.creds.session) {
+        personaToken = local.creds.session
+        credential = { apiUrl: credential.apiUrl, token: local.creds.session }
+        token = local.creds.session
+        if (!workspaceFlag && commandScope(command.meta) === 'workspace') workspaceFlag = local.creds.workspaceId
+        orgFlag ??= local.creds.organizationId
+        output.note(`acting as ${local.creds.email}, the local runtime's owner`)
+      }
+    }
+
     /**
      * `--workspace` is global — same reasoning as `--profile`: an escape hatch
      * that exists on six commands and not the seventh is useless when the

package/src/mcp/mcp-server.ts

@@ -8,6 +8,7 @@ import { agentTools, createMemory } from './tools/agent-tools'
 import { appTools } from './tools/app-tools'
 import { browserTools } from './tools/browser-tools'
 import { docsTools } from './tools/docs-tools'
+import { knowledgeBaseTools } from './tools/knowledge-base-tools'
 import { projectTools } from './tools/project-tools'
 import { testTools } from './tools/test-tools'
 import { workflowTools } from './tools/workflow-tools'
@@ -29,6 +30,7 @@ See what you built, scoped to what you changed:
 - After changing an Agent: apply, then agent_chat with it and trace_get the trace; test_run its cases. newlyFailing are what your change broke; couldNotRun are cases the model provider or the runtime kept from running, not a regression: give the person their fix. Save a case with test_save_case and say what a good reply does (expectedContains, checks), not what this one said.
 - When agent_chat answers with pendingDecision, the turn waits on the person's card (a tool approval or a Function's confirmation): decide it with agent_decide, each decision deliberately, as the person would. Typed words never answer a card.
 - After changing a workflow: apply, then workflow_run it with version "draft". A webhook trigger: workflow_webhook_test sends a request to the draft's test door and reads the run it started.
+- After changing a knowledge base (knowledge-base/): apply, then knowledge_base_status until reading is 0, then knowledge_base_search; search with as: "outsider" to check who may not read it.
 - After changing an App embedded in Studio: browser_open its preview; the snapshot reads the App's frame, and its refs click and type inside it.
 - After changing an App: app_render the pages you touched and read the console and failed requests; browser_open to click through a flow. app_deploy builds it and says in evidence whether the render it carries was clean.
 - When you report back, include the screenshot path or the trace link.
@@ -53,6 +55,7 @@ function projectToolset(project: LocalProject): McpTool[] {
     ...agentTools(project, memory),
     ...testTools(project, memory),
     ...workflowTools(project),
+    ...knowledgeBaseTools(project),
     ...appTools(project),
     ...browserTools(project),
     ...docsTools(project, (kind) => cliSchema(kind) ?? readKeptSchema(project, kind)),

package/src/mcp/tools/docs-tools.ts

@@ -12,7 +12,7 @@ const DOCS_TOOLS = [
   { name: 'search_documentation', description: "Search Frontera's documentation for the release the local runtime runs. Returns guides with the best matching heading and a snippet; read one with read_documentation." },
   { name: 'read_documentation', description: 'Read a guide by its slug from a search result, whole or one heading of it.' },
   { name: 'list_documentation', description: 'List every guide: slug, title and description. Use it to browse an area, e.g. everything under "workflows/".' },
-  { name: 'read_file_schema', description: 'The exact format of a kind of project file (agent.json, operating.json, a workflow, an MCP server, the Blueprint), as JSON Schema, for the runtime\'s release. Read it before writing such a file.' },
+  { name: 'read_file_schema', description: 'The exact format of a kind of project file (agent.json, operating.json, a workflow, an MCP server, the Blueprint, a knowledge base in knowledge-base/<name>/, its sources and knowledge-base/settings.json), as JSON Schema, for the runtime\'s release. Read it before writing such a file.' },
 ] as const
 
 export function docsTools(project: LocalProject, schemaFor: SchemaLookup): McpTool[] {

package/src/mcp/tools/knowledge-base-tools.ts

@@ -0,0 +1,85 @@
+import { citation, KnowledgeBaseApi, plainSnippet, scopeOf } from '../../api/knowledge-base-api'
+import { resolveBase } from '../../commands/knowledge-base/index-commands'
+import { CliError } from '../../errors'
+import { actAsLocalPersona, KNOWLEDGE_PERSONAS } from '../../local/local-personas'
+import type { LocalProject } from '../../local/local-project'
+import { errorResult, intArg, jsonResult, stringArg, type McpTool, type ToolResult } from '../mcp-protocol'
+import { requireRuntime } from '../mcp-runtime'
+
+/**
+ * The Knowledge app's knowledge bases (`knowledge-base/<name>/`) on the local
+ * runtime, read as its owner, or as a local persona with `as`. Reads only:
+ * the files are applied by `apply`, and sources and stewards change through
+ * `frontera knowledge-base`.
+ */
+
+const PERSONAS = KNOWLEDGE_PERSONAS.map((p) => p.key).join(', ')
+
+async function client(project: LocalProject, as?: string): Promise<KnowledgeBaseApi> {
+  const link = requireRuntime(project)
+  if (!as) return new KnowledgeBaseApi(link.serviceUrl, link.creds.session!, link.creds.workspaceId, true, link.creds.organizationId)
+  const acting = await actAsLocalPersona({ meta: { noun: 'knowledge-base', verb: 'search' }, cwd: project.root, apiUrl: link.serviceUrl, wanted: as })
+  return new KnowledgeBaseApi(link.serviceUrl, acting.token, acting.workspaceId, true, acting.organizationId)
+}
+
+/** A CLI refusal as the agent reads it: what happened, then what to do. */
+async function answer(run: () => Promise<unknown>): Promise<ToolResult> {
+  try {
+    return jsonResult(await run())
+  } catch (err) {
+    if (err instanceof CliError) return errorResult(err.hint ? `${err.message}. Next: ${err.hint}` : err.message)
+    throw err
+  }
+}
+
+export function knowledgeBaseTools(project: LocalProject): McpTool[] {
+  return [
+    {
+      name: 'knowledge_base_list',
+      description: 'The knowledge bases of the Knowledge app on the local runtime (the project\'s knowledge-base/ folders once applied), with their scope and sharing. Not Agent knowledge (knowledge/).',
+      inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+      annotations: { title: 'Knowledge bases', readOnlyHint: true, openWorldHint: false },
+      run: () => answer(async () => (await (await client(project)).bases()).map((b) => ({ id: b.id, name: b.name, scope: scopeOf(b), sharing: b.sharing }))),
+    },
+    {
+      name: 'knowledge_base_status',
+      description: 'Each knowledge base\'s documents on the local runtime: ready (searchable), reading (still being checked or read) and failed. Call it after apply until reading is 0, before searching.',
+      inputSchema: { type: 'object', properties: { base: { type: 'string', description: 'One knowledge base, by name, id or project folder; all when absent.' } }, additionalProperties: false },
+      annotations: { title: 'Knowledge base status', readOnlyHint: true, openWorldHint: false },
+      run: (input) => answer(async () => {
+        const api = await client(project)
+        const ref = stringArg(input, 'base')
+        const rows = await api.statuses(ref ? [await resolveBase(api, project.root, ref)] : await api.bases())
+        return rows.map(({ base, ...counts }) => ({ id: base.id, name: base.name, ...counts }))
+      }),
+    },
+    {
+      name: 'knowledge_base_search',
+      description: `Search the knowledge bases on the local runtime as a person would, with a citation for each result (title, base, page). \`as\` searches as a local persona (${PERSONAS}) to check who reads what: outsider reads nothing in the workspace's bases.`,
+      inputSchema: {
+        type: 'object',
+        properties: {
+          query: { type: 'string', description: 'What to search for.' },
+          base: { type: 'string', description: 'Search only this knowledge base, by name, id or project folder.' },
+          limit: { type: 'number', description: 'How many results (1 to 50, default 10).' },
+          as: { type: 'string', description: `A local persona to search as: ${PERSONAS}.` },
+        },
+        required: ['query'],
+        additionalProperties: false,
+      },
+      annotations: { title: 'Search knowledge bases', readOnlyHint: true, openWorldHint: false },
+      run: (input) => answer(async () => {
+        const query = stringArg(input, 'query', { required: true })
+        const api = await client(project, stringArg(input, 'as'))
+        const ref = stringArg(input, 'base')
+        const only = ref ? [(await resolveBase(api, project.root, ref)).id] : undefined
+        const found = await api.search({ query, limit: intArg(input, 'limit', 10, 1, 50), ...(only ? { knowledgeBaseIds: only } : {}) })
+        return {
+          query,
+          ...(found.correctedQuery ? { correctedQuery: found.correctedQuery } : {}),
+          results: found.results.map((r) => ({ citation: citation(r), title: r.title, knowledgeBase: r.knowledgeBase?.name ?? null, page: r.page, snippet: plainSnippet(r.snippet), documentId: r.documentId })),
+        }
+      }),
+    },
+  ]
+}