@frontera-sdk/cli 1.53.23 → 1.53.24

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

@@ -20,6 +20,8 @@ import { projectModels } from './local-sync-models'
 import { deepEqual, sameContent } from './local-sync-merge'
 import { portableNotes, sameDocumentText, toLocal, toWorkspace } from './local-sync-portable'
 import { itemTitle } from './local-sync-names'
+import { KNOWLEDGE_BASE_DIR, KNOWLEDGE_BASE_FILE, KNOWLEDGE_BASE_SETTINGS_FILE, KNOWLEDGE_BASE_SOURCES_DIR } from './local-knowledge-base-files'
+import { KNOWLEDGE_BASES_FEATURE, KNOWLEDGE_SETTINGS_NAME, KNOWLEDGE_SETTINGS_REF, knowledgeBaseDocuments, platformRefName } from './local-knowledge-base-pull'
 import { isScaffoldSample } from './local-scaffold'
 import { hash, itemHash, readLocal, safePath, writeLock, type LockEntry, type PlanItem, type RemoteItem, type SyncKind, type SyncLock } from './local-sync-plan'
 import { dropBase, SYNC_DIR, writeBase, type RemoteSnapshot } from './local-sync-snapshot'
@@ -44,7 +46,7 @@ import { dropBase, SYNC_DIR, writeBase, type RemoteSnapshot } from './local-sync
  */
 
 /** The kinds a change request carries. */
-export const PUSH_KINDS: readonly SyncKind[] = ['blueprint', 'dataset', 'skill', 'knowledge', 'plugin', 'function', 'workflow', 'agent', 'evaluation', 'chat-app', 'lessons', 'app']
+export const PUSH_KINDS: readonly SyncKind[] = ['blueprint', 'dataset', 'skill', 'knowledge', 'knowledge-base', 'plugin', 'function', 'workflow', 'agent', 'evaluation', 'chat-app', 'lessons', 'app']
 
 /** Why the other kinds are not proposed, in the reader's words. */
 export const NOT_PROPOSED: Partial<Record<SyncKind, string>> = {
@@ -65,7 +67,7 @@ const NOT_DELETED: Partial<Record<SyncKind, string>> = {
  * lacks and `sync.models` maps to none; `refused`: the workspace's checks
  * would refuse it (`POST /v1/change-requests/check`), said before proposing.
  */
-export type BlockCode = 'moved' | 'conflicts' | 'deleted' | 'workspace-deleted' | 'kind' | 'shape' | 'model' | 'refused'
+export type BlockCode = 'moved' | 'conflicts' | 'deleted' | 'workspace-deleted' | 'kind' | 'shape' | 'model' | 'refused' | 'sign-in'
 
 /** A skill's file that is not text (an image, a font, a template): uploaded as a skill asset when proposed. */
 export interface PushAsset {
@@ -238,6 +240,20 @@ export function itemFiles(root: string, kind: SyncKind, name: string, entry?: Lo
       if (documents.length && !opts.documents) notes.push(`Its ${documents.length} document${documents.length === 1 ? '' : 's'} stay${documents.length === 1 ? 's' : ''} as the workspace has them unless you bring them; the request carries the knowledge base’s settings`)
       break
     }
+    case 'knowledge-base': {
+      if (name === KNOWLEDGE_SETTINGS_NAME) {
+        if (existsSync(join(root, KNOWLEDGE_BASE_DIR, name, KNOWLEDGE_BASE_FILE))) return { files: {}, notes, problem: `${KNOWLEDGE_BASE_DIR}/${name}/ is named like the organization’s Knowledge settings (${KNOWLEDGE_BASE_DIR}/${KNOWLEDGE_BASE_SETTINGS_FILE}): rename the folder to propose that knowledge base` }
+        paths = [`${KNOWLEDGE_BASE_DIR}/${KNOWLEDGE_BASE_SETTINGS_FILE}`]
+        break
+      }
+      // The base and every one of its sources: a source with no file here is one the request removes.
+      const dir = `${KNOWLEDGE_BASE_DIR}/${name}`
+      paths = [`${dir}/${KNOWLEDGE_BASE_FILE}`, ...filesUnder(root, `${dir}/${KNOWLEDGE_BASE_SOURCES_DIR}`).filter((p) => /^[^/]+\.json$/.test(p.slice(`${dir}/${KNOWLEDGE_BASE_SOURCES_DIR}/`.length)))]
+      const { documents, nested } = knowledgeBaseDocuments(root, name)
+      if (documents.length && !opts.documents) notes.push(`Its ${documents.length} document${documents.length === 1 ? '' : 's'} stay${documents.length === 1 ? 's' : ''} as the workspace has them unless you bring them: push with \`--documents ${dir}\``)
+      if (nested.length) notes.push(`${nested.map((n) => `${dir}/documents/${n}/`).join(', ')} stay${nested.length === 1 ? 's' : ''} here: a knowledge base has no folders, so put its files directly in ${dir}/documents/`)
+      break
+    }
     case 'blueprint':
       paths = [`blueprint/${name}.yaml`, `blueprint/${name}.yml`, `blueprint/${name}.json`]
       break
@@ -257,7 +273,7 @@ export function itemFiles(root: string, kind: SyncKind, name: string, entry?: Lo
       return { files: {}, notes }
   }
   // What the last pull wrote for it comes along when it is still here (an agent's files are fixed; the rest may not be).
-  if (kind !== 'agent' && kind !== 'knowledge' && kind !== 'app') for (const p of Object.keys(entry?.files ?? {})) if (!paths.includes(p)) paths.push(p)
+  if (kind !== 'agent' && kind !== 'knowledge' && kind !== 'knowledge-base' && kind !== 'app') for (const p of Object.keys(entry?.files ?? {})) if (!paths.includes(p)) paths.push(p)
   const files: Record<string, string> = {}
   const here: Record<string, string> = {}
   const models = projectModels(root)
@@ -283,10 +299,11 @@ export function itemFiles(root: string, kind: SyncKind, name: string, entry?: Lo
  * The items the project holds, by ref, as a request names them: Agents,
  * workflows, Functions (a file or a folder of their own), skills, knowledge
  * bases, Blueprint files, and plugins (listed so a push can say why not).
+ * `file` is the file that makes it an item, and names it.
  */
-export function projectRefs(root: string): Map<string, { kind: SyncKind; name: string }> {
-  const out = new Map<string, { kind: SyncKind; name: string }>()
-  const add = (kind: SyncKind, name: string) => out.set(`${kind}/${name}`, { kind, name })
+export function projectRefs(root: string): Map<string, { kind: SyncKind; name: string; file: string }> {
+  const out = new Map<string, { kind: SyncKind; name: string; file: string }>()
+  const add = (kind: SyncKind, name: string, file: string) => out.set(`${kind}/${name}`, { kind, name, file })
   const dirs = (rel: string) => {
     try {
       return readdirSync(join(root, rel)).filter((n) => !isIgnoredName(n) && !SKIP_DIRS.has(n)).sort()
@@ -294,30 +311,33 @@ export function projectRefs(root: string): Map<string, { kind: SyncKind; name: s
       return []
     }
   }
-  for (const slug of dirs('agents')) if (existsSync(join(root, 'agents', slug, 'agent.json'))) add('agent', slug)
+  for (const slug of dirs('agents')) if (existsSync(join(root, 'agents', slug, 'agent.json'))) add('agent', slug, `agents/${slug}/agent.json`)
   for (const f of dirs('workflows')) {
     const m = /^(.+?)(?:\.workflow)?\.(ya?ml|json)$/.exec(f)
-    if (m) add('workflow', m[1]!)
+    if (m) add('workflow', m[1]!, `workflows/${f}`)
   }
   for (const f of dirs('functions')) {
-    if (/\.ts$/.test(f) && !/\.(test|d)\.ts$/.test(f)) add('function', f.replace(/\.ts$/, ''))
-    else if (existsSync(join(root, 'functions', f, 'package.json'))) add('function', f)
+    if (/\.ts$/.test(f) && !/\.(test|d)\.ts$/.test(f)) add('function', f.replace(/\.ts$/, ''), `functions/${f}`)
+    else if (existsSync(join(root, 'functions', f, 'package.json'))) add('function', f, `functions/${f}/package.json`)
   }
-  for (const n of dirs('skills')) if (existsSync(join(root, 'skills', n, 'SKILL.md'))) add('skill', n)
-  for (const n of dirs('knowledge')) if (existsSync(join(root, 'knowledge', n, 'knowledge.json'))) add('knowledge', n)
-  for (const dir of BLUEPRINT_DIRS) for (const f of dirs(`blueprint/${dir}`)) if (/\.(ya?ml|json)$/.test(f)) add('blueprint', `${dir}/${f.replace(/\.(ya?ml|json)$/, '')}`)
+  for (const n of dirs('skills')) if (existsSync(join(root, 'skills', n, 'SKILL.md'))) add('skill', n, `skills/${n}/SKILL.md`)
+  for (const n of dirs('knowledge')) if (existsSync(join(root, 'knowledge', n, 'knowledge.json'))) add('knowledge', n, `knowledge/${n}/knowledge.json`)
+  // The Knowledge app's bases, and the organization's Knowledge settings (`knowledge-base/settings`).
+  for (const n of dirs(KNOWLEDGE_BASE_DIR)) if (existsSync(join(root, KNOWLEDGE_BASE_DIR, n, KNOWLEDGE_BASE_FILE))) add('knowledge-base', n, `${KNOWLEDGE_BASE_DIR}/${n}/${KNOWLEDGE_BASE_FILE}`)
+  if (existsSync(join(root, KNOWLEDGE_BASE_DIR, KNOWLEDGE_BASE_SETTINGS_FILE))) add('knowledge-base', KNOWLEDGE_SETTINGS_NAME, `${KNOWLEDGE_BASE_DIR}/${KNOWLEDGE_BASE_SETTINGS_FILE}`)
+  for (const dir of BLUEPRINT_DIRS) for (const f of dirs(`blueprint/${dir}`)) if (/\.(ya?ml|json)$/.test(f)) add('blueprint', `${dir}/${f.replace(/\.(ya?ml|json)$/, '')}`, `blueprint/${dir}/${f}`)
   // The workspace's own grants beyond read: one Blueprint item, `blueprint/workspace-grants`.
-  if (existsSync(join(root, WORKSPACE_GRANTS_FILE))) add('blueprint', WORKSPACE_GRANTS_NAME)
-  for (const f of dirs('mcp')) if (f.endsWith('.plugin.json') && f !== '.plugin.json') add('plugin', f.slice(0, -'.plugin.json'.length))
-  for (const f of dirs('datasets')) if (f.endsWith('.json') && f !== '.json') add('dataset', f.slice(0, -'.json'.length))
-  for (const f of dirs('chat-apps')) if (f.endsWith('.json') && f !== '.json') add('chat-app', f.slice(0, -'.json'.length))
+  if (existsSync(join(root, WORKSPACE_GRANTS_FILE))) add('blueprint', WORKSPACE_GRANTS_NAME, WORKSPACE_GRANTS_FILE)
+  for (const f of dirs('mcp')) if (f.endsWith('.plugin.json') && f !== '.plugin.json') add('plugin', f.slice(0, -'.plugin.json'.length), `mcp/${f}`)
+  for (const f of dirs('datasets')) if (f.endsWith('.json') && f !== '.json') add('dataset', f.slice(0, -'.json'.length), `datasets/${f}`)
+  for (const f of dirs('chat-apps')) if (f.endsWith('.json') && f !== '.json') add('chat-app', f.slice(0, -'.json'.length), `chat-apps/${f}`)
   // A Custom App's settings file (X6); its code is the folder beside it, and its release a request's own file.
-  for (const f of dirs('apps')) if (/^[a-z0-9][a-z0-9-]*\.json$/.test(f) && !f.endsWith('.release.json')) add('app', f.slice(0, -'.json'.length))
-  for (const slug of dirs('agents')) if (existsSync(join(root, lessonsPath(slug)))) add('lessons', slug)
+  for (const f of dirs('apps')) if (/^[a-z0-9][a-z0-9-]*\.json$/.test(f) && !f.endsWith('.release.json')) add('app', f.slice(0, -'.json'.length), `apps/${f}`)
+  for (const slug of dirs('agents')) if (existsSync(join(root, lessonsPath(slug)))) add('lessons', slug, lessonsPath(slug))
   for (const slug of dirs('agents')) {
     for (const f of dirs(`agents/${slug}/evals`)) {
       const m = /^([^.]+)\.ya?ml$/.exec(f)
-      if (m) add('evaluation', `${slug}.${m[1]}`)
+      if (m) add('evaluation', `${slug}.${m[1]}`, `agents/${slug}/evals/${f}`)
     }
   }
   return out
@@ -339,7 +359,9 @@ export interface CandidateInput {
   remote: RemoteItem[]
   /**
    * Knowledge bases whose documents are brought (opt-in, as for a pull):
-   * what the pull wrote of each (`documents.json`) and what the workspace has now.
+   * what the pull wrote of each (`documents.json`) and what the workspace has
+   * now. Agent knowledge by its name; a Knowledge app base by its ref
+   * (`knowledge-base/<folder>`), as `documents.json` records it.
    */
   documents?: {
     names: Set<string>
@@ -348,7 +370,7 @@ export interface CandidateInput {
   }
 }
 
-const BLOCK_REASON: Record<Exclude<BlockCode, 'kind' | 'shape' | 'model' | 'refused'>, string> = {
+const BLOCK_REASON: Record<Exclude<BlockCode, 'kind' | 'shape' | 'model' | 'refused' | 'sign-in'>, string> = {
   moved: 'Changed in the workspace too since your last pull: pull and merge it first',
   conflicts: 'Has conflicts from a pull: resolve them first',
   deleted: 'Deleted here',
@@ -400,8 +422,71 @@ export function skillAssets(root: string, name: string, paths: string[], theirs:
   return { assets, removed, changed: removed.length > 0 || assets.some((a) => a.change !== 'same') }
 }
 
+/**
+ * Source files named otherwise than the workspace names their source. Apply
+ * matches a base's sources by file name, and the workspace names a source after
+ * its `name` (numbered `-2` and on when two share one), so a file named
+ * otherwise would be taken for a new source on the next push, and the one
+ * before removed with its documents.
+ */
+export function misnamedSources(files: Record<string, string>): Array<{ path: string; want: string }> {
+  return Object.entries(files).flatMap(([path, text]) => {
+    const m = new RegExp(`/${KNOWLEDGE_BASE_SOURCES_DIR}/([^/]+)\\.json$`).exec(path)
+    if (!m) return []
+    let name: unknown
+    try {
+      name = (JSON.parse(text) as { name?: unknown }).name
+    } catch {
+      return []
+    }
+    if (typeof name !== 'string') return []
+    const want = platformRefName(name)
+    const key = m[1]!
+    const numbered = key.startsWith(`${want}-`) && /^\d+$/.test(key.slice(want.length + 1))
+    return key === want || numbered ? [] : [{ path, want: `${path.slice(0, -m[0].length)}/${KNOWLEDGE_BASE_SOURCES_DIR}/${want}.json` }]
+  })
+}
+
 const kb = (n: number) => (n < 1024 ? `${n} B` : n < 1024 * 1024 ? `${Math.round(n / 1024)} KB` : `${(n / 1024 / 1024).toFixed(1)} MB`)
 
+/**
+ * An Agent's files as a request sends them: its `knowledgeBases` name each
+ * base kept in a folder of its own by the name the workspace's index gives it
+ * (`platformName`), which is how Apply finds it.
+ */
+export function withPlatformPicks(files: Record<string, string>, names: ReadonlyMap<string, string>): Record<string, string> {
+  if (!names.size) return files
+  return Object.fromEntries(Object.entries(files).map(([path, text]) => {
+    if (!path.endsWith('/agent.json')) return [path, text]
+    let doc: { knowledgeBases?: unknown }
+    try {
+      doc = JSON.parse(text) as { knowledgeBases?: unknown }
+    } catch {
+      return [path, text]
+    }
+    if (!Array.isArray(doc.knowledgeBases)) return [path, text]
+    const picks = doc.knowledgeBases.map((p) => {
+      const folder = typeof p === 'string' && p.startsWith(`${KNOWLEDGE_BASE_DIR}/`) ? p.slice(KNOWLEDGE_BASE_DIR.length + 1) : null
+      return folder && names.has(folder) ? `${KNOWLEDGE_BASE_DIR}/${names.get(folder)}` : p
+    })
+    return [path, `${JSON.stringify({ ...doc, knowledgeBases: picks }, null, 2)}\n`]
+  }))
+}
+
+const NOT_TAKEN = 'this workspace’s platform does not take knowledge bases from a project yet'
+const BASES_NOT_TAKEN_FIX = `update the platform, or leave ${KNOWLEDGE_BASE_DIR}/ out of this push`
+
+/** An agent.json without its `knowledgeBases`, for a platform that does not take them; the text as it is when it has none. */
+function withoutPicks(text: string | null): string | null {
+  if (text === null) return null
+  try {
+    const { knowledgeBases, ...rest } = JSON.parse(text) as { knowledgeBases?: unknown }
+    return knowledgeBases === undefined ? text : `${JSON.stringify(rest, null, 2)}\n`
+  } catch {
+    return text
+  }
+}
+
 /**
  * What a push would propose, item by item: every item changed here or only
  * here, with what it sends, or why it cannot be proposed now. Items that
@@ -414,6 +499,10 @@ export function pushCandidates(input: CandidateInput): PushItem[] {
   const byPlan = new Map(plan.map((p) => [p.ref, p]))
   const here = projectRefs(root)
   const refs = new Set<string>([...plan.map((p) => p.ref), ...here.keys()])
+  // Knowledge bases filed in a folder other than the name the workspace gives them, by folder.
+  const platformNames = new Map(input.remote.flatMap((r) => (r.kind === 'knowledge-base' && r.platformName ? [[r.name, r.platformName] as const] : [])))
+  // An older platform runs the Knowledge app but refuses a request that carries a base, and drops an Agent's picks.
+  const takesBases = !!snapshot?.capabilities.includes(KNOWLEDGE_BASES_FEATURE)
   const out: PushItem[] = []
   for (const ref of [...refs].sort((a, b) => (String(a) < String(b) ? -1 : String(a) > String(b) ? 1 : 0))) {
     const slash = ref.indexOf('/')
@@ -422,8 +511,6 @@ export function pushCandidates(input: CandidateInput): PushItem[] {
     const p = byPlan.get(ref)
     const entry = lock?.items[ref]
     const theirs = remote.get(ref)
-    // A plan's "only here" for a Function in its own folder is named after its entry file: the folder names it here.
-    if (p?.status === 'local-only' && !entry && !here.has(ref)) continue
     // An Agent's lessons are never in the plan: they are proposed while the file differs from what the last pull wrote.
     const lessons = kind === 'lessons' ? lessonsProposal(root, input.lock?.workspace ?? snapshot?.workspace ?? '', name) : null
     if (kind === 'lessons' && !lessons) continue
@@ -431,12 +518,14 @@ export function pushCandidates(input: CandidateInput): PushItem[] {
     const status = p?.status ?? 'local-only'
     if (status === 'new' || status === 'changed') continue
     const deleted = status === 'deleted-local'
-    const bringDocuments = kind === 'knowledge' && !!input.documents?.names.has(name)
+    // Agent knowledge's are keyed by name, a Knowledge app base's by its ref.
+    const documentsKey = kind === 'knowledge' ? name : ref
+    const bringDocuments = (kind === 'knowledge' || (kind === 'knowledge-base' && ref !== KNOWLEDGE_SETTINGS_REF)) && !!input.documents?.names.has(documentsKey)
     const { files, notes, problem, assets: assetPaths } = deleted ? { files: {} as Record<string, string>, notes: [] as string[], problem: undefined, assets: undefined } : itemFiles(root, kind, name, entry, { documents: bringDocuments, ...(theirs ? { upstream: theirs.files } : {}) })
     // What a file hash does not cover: a skill's assets, and a knowledge base's documents when they are brought.
     const assetState = kind === 'skill' && !deleted && (assetPaths?.length || theirs?.assets?.length) ? skillAssets(root, name, assetPaths ?? [], theirs) : null
     const docs = bringDocuments && !deleted && input.documents
-      ? documentChanges(localDocuments(root, name), input.documents.pulled[name] ?? {}, input.documents.platform.get(name) ?? [])
+      ? documentChanges(kind === 'knowledge' ? localDocuments(root, name) : knowledgeBaseDocuments(root, name).documents, input.documents.pulled[documentsKey] ?? {}, input.documents.platform.get(documentsKey) ?? [])
       : null
     const extra = Boolean(assetState?.changed) || Boolean(docs && (docs.upload.length || docs.remove.length))
     // `same` in the plan reads the base's paths; a file added to the item since is still a change here.
@@ -466,7 +555,7 @@ export function pushCandidates(input: CandidateInput): PushItem[] {
       reason: null,
       id: entry?.id ?? theirs?.id ?? null,
       baseRevision: null,
-      files,
+      files: kind === 'agent' ? withPlatformPicks(files, platformNames) : files,
       diff,
       base: baseFiles,
       notes,
@@ -492,9 +581,22 @@ export function pushCandidates(input: CandidateInput): PushItem[] {
       if (lessons.removed.length) notes.push(`${lessons.removed.length} rule${lessons.removed.length === 1 ? '' : 's'} removed here ${lessons.removed.length === 1 ? 'isn’t' : 'aren’t'} proposed: an active rule is retired on the platform, where rules are reviewed`)
       if (!lessons.added.length && !lessons.removed.length) notes.push('Proposes the rules the workspace doesn’t have yet, for review')
     }
+    const agentPath = `agents/${name}/agent.json`
+    const sentAgent = kind === 'agent' && !takesBases && item.files[agentPath] !== undefined ? withoutPicks(item.files[agentPath]!)! : null
+    const picksLeftOut = sentAgent !== null && sentAgent !== item.files[agentPath]
+    if (picksLeftOut) {
+      item.files = { ...item.files, [agentPath]: sentAgent }
+      item.diff = item.diff.map((f) => (f.path === agentPath ? { ...f, base: withoutPicks(f.base), local: sentAgent } : f)).filter((f) => f.base !== f.local && !(f.base !== null && f.local !== null && sameContent(f.path, f.base, f.local)))
+      notes.push(`Its knowledgeBases are not sent: ${NOT_TAKEN}, so the Agent keeps the knowledge bases it searches there`)
+    }
     const block = (code: BlockCode, reason: string) => Object.assign(item, { proposable: false, blocked: code, reason })
+    const misnamed = kind === 'knowledge-base' ? misnamedSources(files) : []
     if (NOT_PROPOSED[kind]) block('kind', NOT_PROPOSED[kind]!)
     else if (!PUSH_KINDS.includes(kind)) block('kind', 'Not a kind a change request carries')
+    else if ((kind === 'knowledge-base' || (picksLeftOut && !item.diff.length)) && !takesBases) {
+      block('kind', kind === 'knowledge-base' ? 'This workspace’s platform does not take knowledge bases from a project yet' : `Its only change is knowledgeBases, and ${NOT_TAKEN}`)
+      item.fix = kind === 'knowledge-base' ? BASES_NOT_TAKEN_FIX : 'update the platform, then push it again'
+    }
     else if (status === 'conflict') block('moved', BLOCK_REASON.moved)
     else if (status === 'unresolved') block('conflicts', BLOCK_REASON.conflicts)
     else if (deleted && NOT_DELETED[kind]) block('shape', NOT_DELETED[kind]!)
@@ -502,6 +604,7 @@ export function pushCandidates(input: CandidateInput): PushItem[] {
     // A saved object set is saved by Apply, never removed: what else names it would stop resolving (X6).
     else if (deleted && ref.startsWith('blueprint/object-sets/')) block('shape', 'A change request doesn’t remove a saved object set: remove it on the platform, or put its file back')
     else if (deleted && ref === WORKSPACE_GRANTS_REF) block('shape', `Deleting ${WORKSPACE_GRANTS_FILE} changes no grant: to take read_sensitive away, put the file back and list the type with \`permissions: [read]\``)
+    else if (deleted && ref === KNOWLEDGE_SETTINGS_REF) block('shape', `Deleting ${KNOWLEDGE_BASE_DIR}/${KNOWLEDGE_BASE_SETTINGS_FILE} changes no setting: put it back with the settings you want (a part it leaves out stays as the workspace has it)`)
     else if (status === 'deleted-remote') block('workspace-deleted', BLOCK_REASON['workspace-deleted'])
     else if (deleted) {
       // Proposable: Apply deletes it there, after everything that names it is updated.
@@ -509,6 +612,16 @@ export function pushCandidates(input: CandidateInput): PushItem[] {
     else if (!Object.keys(files).length) block('shape', 'No files to propose')
     else if (kind === 'blueprint' && Object.keys(files).length > 1) block('shape', `${Object.keys(files).join(' and ')}: keep one file per Blueprint artifact`)
     else if (ref === WORKSPACE_GRANTS_REF && readWorkspaceGrants(root)?.problems.length) block('shape', readWorkspaceGrants(root)!.problems.join('; '))
+    else if (misnamed.length) {
+      block('shape', `${misnamed.map((w) => w.path).join(', ')}: the workspace names ${misnamed.length === 1 ? 'this source' : 'these sources'} by ${misnamed.length === 1 ? 'its' : 'their'} name, and a file named otherwise is taken for a new source, the one before removed with its documents`)
+      item.fix = `rename ${misnamed.map((w) => `${w.path} to ${w.want}`).join(', ')}`
+    }
+    // A request carries every source a base has: one the read could not file would be removed.
+    else if (theirs?.keptOnPlatform?.length) {
+      const kept = theirs.keptOnPlatform.map((n) => `“${n}”`).join(', ')
+      block('shape', `Its source${theirs.keptOnPlatform.length === 1 ? '' : 's'} ${kept} ${theirs.keptOnPlatform.length === 1 ? 'is' : 'are'} on the platform but not in ${KNOWLEDGE_BASE_SOURCES_DIR}/, and a change request would remove ${theirs.keptOnPlatform.length === 1 ? 'it' : 'them'}`)
+      item.fix = 'propose it signed in as someone who reads every source of the knowledge base (a Knowledge steward for an organization knowledge base), after a pull brings them'
+    }
     else if (assetState?.changed && entry?.revision && theirs?.revision && entry.revision !== theirs.revision && textSame) {
       // A pull never writes over an asset the folder has, so one the workspace changed since reads as a change here.
       block('moved', 'Its assets changed in the workspace since your last pull: delete the copies here to bring the workspace’s, then propose')
@@ -915,7 +1028,8 @@ export const KIND_WORD: Record<SyncKind, string> = {
   workflow: 'Workflow',
   function: 'Function',
   skill: 'Skill',
-  knowledge: 'Knowledge base',
+  knowledge: 'Agent knowledge',
+  'knowledge-base': 'Knowledge base',
   blueprint: 'Blueprint',
   plugin: 'Plugin',
   evaluation: 'Evaluation',
@@ -962,6 +1076,7 @@ export function changedParts(kind: SyncKind, name: string, paths: string[], file
     } else if (kind === 'workflow') parts.add('definition')
     else if (kind === 'function') parts.add('code')
     else if (kind === 'knowledge') parts.add(path.endsWith(`/${QUALITY_CHECKS_FILE}`) ? 'quality checks' : 'settings')
+    else if (kind === 'knowledge-base') parts.add(path.includes(`/${KNOWLEDGE_BASE_SOURCES_DIR}/`) ? 'sources' : 'settings')
     else if (kind === 'plugin') parts.add('settings and policy')
     else if (kind === 'evaluation') parts.add('cases')
     else if (kind === 'chat-app') parts.add('experience')
@@ -975,12 +1090,17 @@ function joinWords(words: string[]): string {
   return `${words.slice(0, -1).join(', ')} and ${words[words.length - 1]}`
 }
 
-/** One line per item, as the Overview says it: "Agent Support Concierge: behavior settings changed". */
-export function itemLine(item: { kind: SyncKind; name: string; title: string; change: 'changed' | 'new' | 'deleted'; changedPaths?: string[]; changedFiles?: PushFile[]; assetsChanged?: boolean; documentsChanged?: boolean }): string {
+/** An item as a line names it: "Agent Support Concierge"; a Blueprint file says what it is ("Object type Ticket"). */
+export function itemLabel(item: { kind: SyncKind; name: string; title: string }): string {
   const [dir, apiName] = item.name.split('/')
   const word = BLUEPRINT_WORD[dir ?? '']
-  // A Blueprint file says what it is: "Object type Ticket".
-  const label = item.kind === 'blueprint' ? (word && apiName ? `${word[0]!.toUpperCase()}${word.slice(1)} ${item.title}` : `Blueprint ${item.title}`) : `${KIND_WORD[item.kind]} ${item.title}`
+  if (item.kind === 'blueprint') return word && apiName ? `${word[0]!.toUpperCase()}${word.slice(1)} ${item.title}` : `Blueprint ${item.title}`
+  return item.kind === 'knowledge-base' && item.name === KNOWLEDGE_SETTINGS_NAME ? item.title : `${KIND_WORD[item.kind]} ${item.title}`
+}
+
+/** One line per item, as the Overview says it: "Agent Support Concierge: behavior settings changed". */
+export function itemLine(item: { kind: SyncKind; name: string; title: string; change: 'changed' | 'new' | 'deleted'; changedPaths?: string[]; changedFiles?: PushFile[]; assetsChanged?: boolean; documentsChanged?: boolean }): string {
+  const label = itemLabel(item)
   if (item.change === 'deleted') return `${label}: delete`
   // The platform keeps no lessons file, so "new" or "changed" depends only on
   // whether this project pulled one; what the request does is the same either way.
@@ -1073,11 +1193,22 @@ export function failedName(outcome: ApplyOutcome, titles: Record<string, string>
   return titles[failed.ref] ?? outcome.steps.find((s) => s.key === failed.key)?.label ?? failed.ref
 }
 
+/**
+ * A step's words with Agent knowledge and a knowledge base named as the lines
+ * name them: the platform calls both "Knowledge base <folder>".
+ */
+function stepWords(text: string, ref: string, titles: Record<string, string>): string {
+  const [kind, ...rest] = ref.split('/')
+  const name = rest.join('/')
+  if ((kind !== 'knowledge' && kind !== 'knowledge-base') || !name) return text
+  return text.split(`Knowledge base ${name}`).join(`${KIND_WORD[kind]} ${titles[ref] ?? name}`)
+}
+
 /** Apply's steps, and after a failure what was put back, as `request apply` prints them. */
 export function describeOutcome(outcome: ApplyOutcome, titles: Record<string, string> = {}): string[] {
   const lines = outcome.steps.flatMap((s) => [
-    `  ${STEP_MARK[s.status]} ${s.label}${s.status === 'not-run' && !outcome.ok ? '  (not run)' : ''}`,
-    ...(s.notes ?? []).map((n) => `      · ${n}`),
+    `  ${STEP_MARK[s.status]} ${stepWords(s.label, s.ref, titles)}${s.status === 'not-run' && !outcome.ok ? '  (not run)' : ''}`,
+    ...(s.notes ?? []).map((n) => `      · ${stepWords(n, s.ref, titles)}`),
   ])
   if (outcome.ok) return [`Applied ${outcome.steps.length} step${outcome.steps.length === 1 ? '' : 's'}:`, ...lines]
   const failed = outcome.failure

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

@@ -20,8 +20,10 @@ import { slugify } from './local-project'
 /**
  * `object` is an object definition an Agent's object tools work on
  * (`object/claim_ticket`), by slug; its fields travel in the Agent's file.
+ * `knowledge-base` is a Knowledge app knowledge base an Agent searches
+ * (`knowledgeBases` in agent.json), by its folder under `knowledge-base/`.
  */
-export const REF_KINDS = ['function', 'workflow', 'agent', 'knowledge', 'plugin', 'objectType', 'action', 'model', 'skill', 'objectSet', 'object'] as const
+export const REF_KINDS = ['function', 'workflow', 'agent', 'knowledge', 'knowledge-base', 'plugin', 'objectType', 'action', 'model', 'skill', 'objectSet', 'object'] as const
 export type RefKind = (typeof REF_KINDS)[number]
 
 /** Names as resources are named: slugs, API names, install names. */

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

@@ -28,6 +28,7 @@ import { missingImportNote, missingImportWarning, recoverMissingImports, type Mi
 import { attachDefinitions, type ObjectDefinitionRow } from './local-objects'
 import { checksFromFixtures, fixtureRows, qualityChecksPath, qualityChecksText, sourcePaths, sourceRows } from './local-quality-checks'
 import { readableName } from './local-sync-names'
+import { agentPicks, knowledgeReach, readKnowledgeBases, type KnowledgeReach } from './local-knowledge-base-pull'
 import { WORKSPACE_GRANTS_FILE, WORKSPACE_GRANTS_NAME } from './local-workspace-grants'
 import { governedActionIds, invert, itemRef, referencesIn, refName as refNameOf, toNames, type Directory, type RefKind } from './local-sync-refs'
 
@@ -47,6 +48,14 @@ export interface SyncSource {
   workspaceId: string
   /** The person signed in, when they read nothing at organization grain (no Blueprint Steward) and no key reads for them. */
   notSteward?: string
+  /** The person signed in for the link (the device session): the Knowledge app's bases are read as them, never with a key. */
+  person?: PersonClients
+}
+
+/** One session, standing in the linked workspace or at its organization: what a person reads depends on where they stand. */
+export interface PersonClients {
+  workspace: SyncClient
+  organization: SyncClient
 }
 
 /** Envelopes come single (`{data}`) or double (`{data:{data}}`); lists are what is inside. */
@@ -275,6 +284,12 @@ export interface ReadOptions {
    * sync index says changed. The Blueprint and evaluations are read whole.
    */
   only?: Set<string>
+  /** The folder each knowledge base was pulled into, by its id (`lockedFolders`), so a base keeps its folder. */
+  knowledgeBaseFolders?: ReadonlyMap<string, string>
+  /** The Knowledge app as a fetch already read it, so the bases and the Agents' picks agree on folders. */
+  knowledge?: KnowledgeReach
+  /** The platform's sync features, as a fetch read them: knowledge bases are read only where it takes them. */
+  capabilities?: readonly string[]
 }
 
 const wanted = (opts: ReadOptions, ref: string) => !opts.only || opts.only.has(ref)
@@ -581,25 +596,24 @@ export async function agentOperatingConfig(
 }
 
 /**
- * The Knowledge app's bases an Agent searches are platform settings, not part
- * of its files: a local runtime has no Knowledge app, and a base belongs to
- * one installation. Said, so what the Agent answers locally is not taken for
- * what it answers on the platform. Nothing to say where the platform has no
- * Knowledge app, the Agent searches none, or the route is not there.
+ * The Knowledge app's bases an Agent searches, said where the platform does
+ * not take knowledge bases from a project: agent.json cannot name them there,
+ * so what the Agent answers locally is not taken for what it answers on the
+ * platform. Nothing to say where it searches none, or the route is not there.
  */
-export async function knowledgeBasesNote(source: SyncSource, agentId: string): Promise<string | null> {
+async function knowledgeBasesNote(source: SyncSource, agentId: string): Promise<string | null> {
   const answer = await source.workspace.get(`/v1/config/agents/${encodeURIComponent(agentId)}/knowledge-bases`).catch(() => null)
   const bases = answer ? one<{ bases?: Array<{ name?: unknown; searched?: unknown }> } | null>(answer)?.bases ?? [] : []
   const names = bases.filter((base) => base.searched === true && typeof base.name === 'string').map((base) => `“${base.name as string}”`)
   if (!names.length) return null
   const which = names.length === 1 ? `the knowledge base ${names[0]}` : `${names.length} knowledge bases (${names.join(', ')})`
-  return `Searches ${which} from the Knowledge app on the platform. A local runtime has no Knowledge app, so here it answers without them: test this Agent’s Knowledge on the platform`
+  return `Searches ${which} from the Knowledge app on the platform. This workspace’s platform does not take knowledge bases from a project yet, so knowledgeBases is not pulled and the local runtime answers without them: update the platform, or test this Agent’s Knowledge on the platform`
 }
 
 /** An Agent's record (`/v1/config/agents/:id`): its published version, and its behavior settings, scrubbed. */
 interface AgentDetail { currentVersion?: { versionNumber?: number } | null; operatingConfig?: unknown }
 
-async function readAgents(source: SyncSource, lists: Lists, directory: Directory, opts: ReadOptions, warnings: string[], tools: () => Promise<PluginTools>): Promise<RemoteItem[]> {
+async function readAgents(source: SyncSource, lists: Lists, directory: Directory, opts: ReadOptions, warnings: string[], tools: () => Promise<PluginTools>, knowledge: () => Promise<KnowledgeReach>): Promise<RemoteItem[]> {
   const out: RemoteItem[] = []
   const agents = lists.agents.filter((row) => wanted(opts, `agent/${row.agentId}`))
   if (!agents.length) return out
@@ -637,6 +651,13 @@ async function readAgents(source: SyncSource, lists: Lists, directory: Directory
     const agentDoc = projectAgent(snapshot, it.notes, toolSettings)
     // Its object tools carry the definitions they work on, named by slug below.
     it.notes.push(...attachDefinitions(agentDoc, lists.objectDefinitions ?? null))
+    // The knowledge bases it searches; left out (the picks left alone) when they could not be read, or the platform does not take them.
+    const picks = await knowledge().then(async (reach) => (reach.state === 'not-taken' ? { refs: [], notes: [await knowledgeBasesNote(source, row.id)].filter((n): n is string => !!n) } : agentPicks(reach, row.id))).catch((err: Error) => {
+      warnings.push(`Agent ${row.agentId} knowledge bases: ${err.message}`)
+      return null
+    })
+    if (picks?.refs.length) agentDoc.knowledgeBases = picks.refs
+    if (picks) it.notes.push(...picks.notes)
     const docs: Array<{ path: string; doc: unknown; format: 'json' }> = [{ path: `agents/${row.agentId}/agent.json`, doc: agentDoc, format: 'json' }]
     if (operating) docs.push({ path: `agents/${row.agentId}/operating.json`, doc: operating, format: 'json' })
     const bound: AgentBindings = { ...(bindings.get(row.agentId) ?? { functions: [], workflows: [] }) }
@@ -650,10 +671,11 @@ async function readAgents(source: SyncSource, lists: Lists, directory: Directory
       it.notes.push(`Its Context and data couldn’t be read on the platform: ${context.unread}. Until it can be read, local dev gives it read access to the object types the project holds, as an adaptation, so locally it may read more than on the platform`)
     }
     if (bound.functions.length || bound.workflows.length || bound.blueprint?.length || bound.blueprintUnread) docs.push({ path: `agents/${row.agentId}/bindings.json`, doc: bound, format: 'json' })
-    const knowledgeBases = await knowledgeBasesNote(source, row.id)
-    if (knowledgeBases) it.notes.push(knowledgeBases)
     await nameUnknownAgents(source, directory, docs)
-    out.push(finish(it, directory, docs))
+    finish(it, directory, docs)
+    // Pulling the Agent brings the bases it searches.
+    if (picks?.refs.length) it.requires = [...new Set([...(it.requires ?? []), ...picks.refs])].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0))
+    out.push(it)
   }
   return out
 }
@@ -1670,6 +1692,9 @@ export async function readWorkspace(source: SyncSource, opts: ReadOptions = {}):
   // Each Plugin's tools, read once and only when a Plugin file or an Agent's tool settings need them.
   let toolsRead: Promise<PluginTools> | null = null
   const tools = () => (toolsRead ??= readPluginTools(source, lists.apps, warnings))
+  // The Knowledge app, read once and only when its bases or an Agent's picks are wanted.
+  let knowledgeRead: Promise<KnowledgeReach> | null = opts.knowledge ? Promise.resolve(opts.knowledge) : null
+  const knowledge = () => (knowledgeRead ??= knowledgeReach(source, opts.knowledgeBaseFolders, warnings, opts.capabilities))
   const pluginsWanted = want('plugin') && lists.apps.some((a) => a.install && (a.catalog?.kind ?? '').toLowerCase() === 'mcp' && wanted(opts, `plugin/${a.install.installName}`))
   const groups = await Promise.all([
     want('blueprint')
@@ -1679,8 +1704,15 @@ export async function readWorkspace(source: SyncSource, opts: ReadOptions = {}):
     want('function') ? readFunctions(source, lists, opts, warnings) : [],
     pluginsWanted ? tools().then((t) => readPlugins(lists, opts, t)) : [],
     want('knowledge') ? readKnowledge(source, lists, opts, warnings) : [],
+    // The Knowledge app's bases and settings: those `only` names, or every one.
+    want('knowledge-base')
+      ? knowledge().then((reach) => readKnowledgeBases(reach, warnings, opts.only)).then((read) => {
+          notes.push(...read.notes)
+          return read.items
+        })
+      : [],
     want('workflow') ? readWorkflows(source, lists, directory, opts, warnings) : [],
-    want('agent') ? readAgents(source, lists, directory, opts, warnings, tools) : [],
+    want('agent') ? readAgents(source, lists, directory, opts, warnings, tools, knowledge) : [],
     want('evaluation') ? quietly(warnings, 'Evaluations', () => readEvaluations(source, lists, directory, warnings), []) : [],
     // Slide themes: the workspace's own; a platform without the route has none to bring.
     want('theme')