@frontera-sdk/cli 1.52.27 → 1.52.29

package/src/local/local-knowledge-documents.ts

@@ -0,0 +1,302 @@
+import { createHash } from 'node:crypto'
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs'
+import { basename, dirname, join } from 'node:path'
+
+import { KNOWLEDGE_DOCUMENT } from './local-dev-references'
+import type { SyncClient } from './local-sync-client'
+import { readLink } from './local-sync-link'
+import { rows } from './local-sync-remote'
+
+/**
+ * A knowledge base's documents, brought from the workspace when asked
+ * (`frontera local sync pull --documents faq`, or "Bring documents" in
+ * Forge's Pull dialog). Off by default: documents can be large and are often
+ * the customer's own content.
+ *
+ * They are not merged or tracked as the other pulled files are. Each lands
+ * in `knowledge/<name>/` under its own file name, as a document added by hand
+ * would, and `local dev` uploads it the same way. A file already in the
+ * folder is never overwritten, so a second pull brings only what is new.
+ * Only the kinds `local dev` uploads are brought; the rest are listed.
+ *
+ * The knowledge base's folders are subfolders, as the platform's uploader
+ * turns a dropped directory into folders: a document filed in Policies ›
+ * Returns lands in `knowledge/<name>/Policies/Returns/`, and `local dev`
+ * and a change request file it there again. A document is known by its path
+ * under the knowledge base's folder (`Policies/Returns/terms.pdf`).
+ */
+
+interface SourceRow {
+  id?: string
+  fileName?: string | null
+  mimeType?: string | null
+  storageKey?: string | null
+  folderId?: string | null
+}
+
+/** A knowledge base folder as `GET …/folders` lists it. */
+export interface FolderRow {
+  id: string
+  parentId?: string | null
+  name: string
+}
+
+/** A folder's name as a project folder: no path separator, no leading dot. */
+export const folderSegment = (name: string) => name.replace(/[\\/]/g, '-').replace(/^\.+/, '').trim() || 'folder'
+
+/** Each folder's path from the top (`Policies/Returns`), by id; a folder whose parents do not lead to the top has none. */
+export function folderPaths(folders: FolderRow[]): Map<string, string> {
+  const byId = new Map(folders.map((f) => [f.id, f]))
+  const out = new Map<string, string>()
+  const pathOf = (id: string, seen: Set<string>): string | null => {
+    const known = out.get(id)
+    if (known !== undefined) return known
+    const f = byId.get(id)
+    if (!f || seen.has(id)) return null
+    seen.add(id)
+    const parent = f.parentId ? pathOf(f.parentId, seen) : ''
+    if (parent === null) return null
+    const path = parent ? `${parent}/${folderSegment(f.name)}` : folderSegment(f.name)
+    out.set(id, path)
+    return path
+  }
+  for (const f of folders) pathOf(f.id, new Set())
+  return out
+}
+
+/** A knowledge base's folders by id, or none (an older platform, or no folders). */
+export async function readFolders(client: { get: (path: string) => Promise<unknown> }, kbId: string): Promise<Map<string, string>> {
+  try {
+    const listed = (await client.get(`/v1/workspace-knowledge/${encodeURIComponent(kbId)}/folders`)) as { folders?: unknown; data?: { folders?: unknown } } | null
+    const rows = (listed?.folders ?? listed?.data?.folders ?? []) as FolderRow[]
+    return folderPaths(Array.isArray(rows) ? rows : [])
+  } catch {
+    return new Map()
+  }
+}
+
+/** A document's path under its knowledge base's folder. */
+export const documentPath = (folder: string | null | undefined, fileName: string) => (folder ? `${folder}/${fileName}` : fileName)
+
+/** A document path's folder (null at the top) and file name. */
+export function splitDocumentPath(path: string): { folder: string | null; fileName: string } {
+  const at = path.lastIndexOf('/')
+  return at < 0 ? { folder: null, fileName: path } : { folder: path.slice(0, at), fileName: path.slice(at + 1) }
+}
+
+export interface DocumentsPulled {
+  /** Project-relative paths written. */
+  written: string[]
+  /** Already in the folder: left as they are. */
+  present: string[]
+  /** Not a kind `local dev` uploads (a spreadsheet, an image), by file name. */
+  skipped: string[]
+  /** Could not be read, with why. */
+  failed: string[]
+}
+
+/** A document's name as a file in the folder: no path, no leading dot. */
+function fileNameOf(source: SourceRow): string | null {
+  const name = basename(String(source.fileName ?? '').replace(/\\/g, '/')).replace(/^\.+/, '').trim()
+  return name && name !== 'knowledge.json' ? name : null
+}
+
+// ── What the project brought, for proposing back ─────────────────────────────
+
+/** A document a pull wrote: the platform's copy it came from, and its content's digest then. */
+export interface PulledDocument {
+  sourceId: string
+  sha256: string
+  bytes: number
+  at: string
+}
+
+/**
+ * `.frontera/sync/documents.json` (not committed, with the rest of `sync/`):
+ * per knowledge base, the documents a pull wrote, by their path under the
+ * knowledge base's folder (a file name at the top). A push reads
+ * it to tell a document changed here from one new here, and to take off the
+ * platform only a document the project pulled and then removed.
+ */
+export interface DocumentsFile {
+  version: 1
+  workspace: string
+  bases: Record<string, Record<string, PulledDocument>>
+}
+
+const DOCUMENTS_JSON = join('.frontera', 'sync', 'documents.json')
+
+export function readPulledDocuments(root: string, workspace: string): DocumentsFile {
+  const empty: DocumentsFile = { version: 1, workspace, bases: {} }
+  try {
+    const file = join(root, DOCUMENTS_JSON)
+    if (!existsSync(file)) return empty
+    const parsed = JSON.parse(readFileSync(file, 'utf8')) as DocumentsFile
+    return parsed?.version === 1 && parsed.workspace === workspace && parsed.bases && typeof parsed.bases === 'object' ? parsed : empty
+  } catch {
+    return empty
+  }
+}
+
+/** Record documents for one knowledge base: an entry sets it, null forgets it. */
+export function recordPulledDocuments(root: string, workspace: string, kb: string, entries: Record<string, PulledDocument | null>): void {
+  const file = readPulledDocuments(root, workspace)
+  const base = { ...(file.bases[kb] ?? {}) }
+  for (const [name, entry] of Object.entries(entries)) {
+    if (entry) base[name] = entry
+    else delete base[name]
+  }
+  file.bases[kb] = base
+  mkdirSync(join(root, '.frontera', 'sync'), { recursive: true })
+  writeFileSync(join(root, DOCUMENTS_JSON), `${JSON.stringify(file, null, 2)}\n`)
+}
+
+export const sha256Of = (bytes: Uint8Array) => createHash('sha256').update(bytes).digest('hex')
+
+/** The documents' paths under a knowledge base's folder, its subfolders included: the files `local dev` uploads. */
+export function documentPaths(root: string, kb: string): string[] {
+  const top = join(root, 'knowledge', kb)
+  const out: string[] = []
+  const walk = (rel: string, depth: number) => {
+    if (depth > 16) return
+    let names: string[]
+    try {
+      names = readdirSync(join(top, rel))
+    } catch {
+      return
+    }
+    for (const name of names) {
+      if (name.startsWith('.') || name === 'node_modules') continue
+      const path = rel ? `${rel}/${name}` : name
+      let st
+      try {
+        st = statSync(join(top, path))
+      } catch {
+        continue
+      }
+      if (st.isDirectory()) walk(path, depth + 1)
+      else if (st.isFile() && KNOWLEDGE_DOCUMENT.test(name) && path !== 'knowledge.json') out.push(path)
+    }
+  }
+  if (existsSync(top)) walk('', 0)
+  return out.sort()
+}
+
+/** The documents in a knowledge base's folder and its subfolders, by path. */
+export function localDocuments(root: string, kb: string): Array<{ fileName: string; bytes: Uint8Array }> {
+  const dir = join(root, 'knowledge', kb)
+  return documentPaths(root, kb).flatMap((f) => {
+    try {
+      return [{ fileName: f, bytes: new Uint8Array(readFileSync(join(dir, f))) }]
+    } catch {
+      return []
+    }
+  })
+}
+
+/** `fileName` is the document's path under the knowledge base's folder (`Policies/terms.pdf`); a push sends its folder apart. */
+export interface DocumentChange {
+  upload: Array<{ fileName: string; sha256: string; bytes: number; mime: string; replaces: string | null; change: 'new' | 'changed'; content: Uint8Array }>
+  remove: Array<{ fileName: string; sourceId: string }>
+  /** What is left as it is, in words: a document named like one the workspace has that this project did not pull. */
+  notes: string[]
+}
+
+const DOCUMENT_MIME: Record<string, string> = {
+  md: 'text/markdown',
+  markdown: 'text/markdown',
+  txt: 'text/plain',
+  pdf: 'application/pdf',
+  docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+  html: 'text/html',
+}
+
+/** The largest document a change request carries (the platform's limit). */
+export const MAX_DOCUMENT_BYTES = 25 * 1024 * 1024
+
+/**
+ * What proposing a knowledge base's documents sends, against the documents
+ * the pull wrote (`documents.json`) and those the workspace has now:
+ *
+ *   new here           uploaded
+ *   pulled, changed    uploaded, and the pulled copy taken off once Apply's other steps are done
+ *   pulled, removed    taken off the platform
+ *   unchanged          nothing
+ *   named like one the workspace has that the project did not pull: left alone, said
+ */
+export function documentChanges(local: Array<{ fileName: string; bytes: Uint8Array }>, pulled: Record<string, PulledDocument>, platform: Array<{ id: string; fileName: string }>): DocumentChange {
+  const out: DocumentChange = { upload: [], remove: [], notes: [] }
+  const onPlatform = new Map(platform.map((p) => [p.id, p]))
+  const names = new Set(platform.map((p) => p.fileName))
+  for (const doc of local) {
+    const sha256 = sha256Of(doc.bytes)
+    const mime = DOCUMENT_MIME[doc.fileName.split('.').pop()?.toLowerCase() ?? ''] ?? 'application/octet-stream'
+    const was = pulled[doc.fileName]
+    if (doc.bytes.byteLength > MAX_DOCUMENT_BYTES) {
+      out.notes.push(`${doc.fileName} stays here: larger than ${MAX_DOCUMENT_BYTES / 1024 / 1024} MB`)
+      continue
+    }
+    if (was) {
+      if (was.sha256 === sha256) continue
+      out.upload.push({ fileName: doc.fileName, sha256, bytes: doc.bytes.byteLength, mime, replaces: onPlatform.has(was.sourceId) ? was.sourceId : null, change: 'changed', content: doc.bytes })
+      continue
+    }
+    if (names.has(doc.fileName)) {
+      out.notes.push(`${doc.fileName} is named like a document the workspace has that this project didn't bring; it stays as it is (bring the documents to compare)`)
+      continue
+    }
+    out.upload.push({ fileName: doc.fileName, sha256, bytes: doc.bytes.byteLength, mime, replaces: null, change: 'new', content: doc.bytes })
+  }
+  const here = new Set(local.map((d) => d.fileName))
+  for (const [fileName, was] of Object.entries(pulled)) {
+    if (here.has(fileName) || !onPlatform.has(was.sourceId)) continue
+    out.remove.push({ fileName, sourceId: was.sourceId })
+  }
+  return out
+}
+
+export async function pullDocuments(root: string, client: SyncClient, kb: { name: string; id: string }): Promise<DocumentsPulled> {
+  const out: DocumentsPulled = { written: [], present: [], skipped: [], failed: [] }
+  const folder = join('knowledge', kb.name)
+  let sources: SourceRow[]
+  try {
+    sources = rows<SourceRow>(await client.get(`/v1/workspace-knowledge/${encodeURIComponent(kb.id)}/sources`))
+  } catch (err) {
+    out.failed.push(`the list of documents: ${(err as Error).message}`)
+    return out
+  }
+  // The knowledge base's folders become subfolders; a document in none sits at the top.
+  const folders = sources.some((s) => s.folderId) ? await readFolders(client, kb.id) : new Map<string, string>()
+  mkdirSync(join(root, folder), { recursive: true })
+  const recorded: Record<string, PulledDocument> = {}
+  for (const source of sources) {
+    let name = fileNameOf(source)
+    if (!source.id || !name) continue
+    // Kept only as its indexed text (added inline, not uploaded as a file): it comes as that text.
+    const textOnly = 'storageKey' in source && (!source.storageKey || source.storageKey.includes('://'))
+    if (textOnly && !/\.(md|markdown|txt)$/i.test(name)) name = `${name}.txt`
+    if (!KNOWLEDGE_DOCUMENT.test(name)) {
+      out.skipped.push(name)
+      continue
+    }
+    const rel = documentPath(source.folderId ? (folders.get(source.folderId) ?? null) : null, name)
+    const path = join(folder, rel)
+    if (existsSync(join(root, path))) {
+      out.present.push(path)
+      continue
+    }
+    try {
+      const bytes = await client.getBytes(`/v1/workspace-knowledge/${encodeURIComponent(kb.id)}/sources/${encodeURIComponent(source.id)}/preview`)
+      mkdirSync(dirname(join(root, path)), { recursive: true })
+      writeFileSync(join(root, path), bytes)
+      out.written.push(path)
+      recorded[rel] = { sourceId: source.id, sha256: sha256Of(bytes), bytes: bytes.byteLength, at: new Date().toISOString() }
+    } catch (err) {
+      out.failed.push(`${name}: ${(err as Error).message}`)
+    }
+  }
+  // What the pull wrote, so proposing back tells a changed document from a new one.
+  const workspace = readLink(root)?.workspace
+  if (workspace && Object.keys(recorded).length) recordPulledDocuments(root, workspace, kb.name, recorded)
+  return out
+}

package/src/local/local-lessons.ts

@@ -0,0 +1,278 @@
+import { createHash } from 'node:crypto'
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml'
+
+import { writeFileAtomic } from '../fs-atomic'
+import type { SyncClient } from './local-sync-client'
+import { rows } from './local-sync-remote'
+
+/**
+ * An Agent's lessons: the reviewed rules it learned from customer feedback
+ * on the platform (feedback rules someone approved), which its prompt
+ * carries there. Brought only when asked (`frontera local sync pull
+ * --lessons`, or "Bring lessons" in Forge's Pull dialog), as they come from
+ * customers' feedback; the feedback itself is never brought.
+ *
+ * They are kept in `agents/<slug>/lessons.yaml`, and `local dev` gives them
+ * to the local Agent so its prompt reads as the platform's does. A pull
+ * rewrites the file only while it is as the last pull wrote it: one edited
+ * here is kept, and said.
+ */
+
+const LESSONS_JSON = join('.frontera', 'sync', 'lessons.json')
+
+export const lessonsPath = (slug: string) => `agents/${slug}/lessons.yaml`
+
+const HEADER = '# Reviewed rules this Agent learned from customer feedback on the platform (frontera local sync pull --lessons).\n# frontera local dev gives them to the local Agent, as the platform’s prompt carries them.\n'
+
+export interface Lesson {
+  rule: string
+  approvedAt?: string
+}
+
+/** One Agent's lessons as `/v1/sync/lessons` lists them. */
+export interface LessonsRow {
+  agent: string
+  rules: Array<{ text: string; approvedAt?: string | null }>
+}
+
+export function lessonsText(rules: LessonsRow['rules']): string {
+  const lessons: Lesson[] = rules.map((r) => ({ rule: r.text, ...(r.approvedAt ? { approvedAt: r.approvedAt } : {}) }))
+  return HEADER + stringifyYaml({ lessons }, { lineWidth: 0 })
+}
+
+/** The rules a lessons file holds, in order, once each. */
+export function readLessons(text: string): string[] {
+  const doc = parseYaml(text) as { lessons?: Array<{ rule?: unknown } | string> } | null
+  const out: string[] = []
+  for (const l of Array.isArray(doc?.lessons) ? doc!.lessons : []) {
+    const rule = typeof l === 'string' ? l : typeof l?.rule === 'string' ? l.rule : ''
+    if (rule.trim() && !out.includes(rule.trim())) out.push(rule.trim())
+  }
+  return out
+}
+
+const sha = (text: string) => createHash('sha256').update(text).digest('hex')
+
+interface LessonsFile {
+  version: 1
+  workspace: string
+  /** What the last pull wrote, by Agent slug: the file's digest. */
+  files: Record<string, string>
+  /** The rules the last pull wrote, by Agent slug: what a change request compares the file with. */
+  rules?: Record<string, string[]>
+}
+
+function readRecord(root: string, workspace: string): LessonsFile {
+  try {
+    const parsed = JSON.parse(readFileSync(join(root, LESSONS_JSON), 'utf8')) as LessonsFile
+    if (parsed?.version === 1 && parsed.workspace === workspace && parsed.files) return parsed
+  } catch {
+    // None yet.
+  }
+  return { version: 1, workspace, files: {} }
+}
+
+export interface LessonsPulled {
+  /** Agents whose lessons file was written. */
+  written: string[]
+  /** Agents whose file was removed: the workspace has no reviewed rules for them any more. */
+  removed: string[]
+  /** Agents whose file was edited here since the last pull: kept as it is. */
+  kept: string[]
+  /** How many rules came, in all. */
+  rules: number
+}
+
+/**
+ * Bring the reviewed rules of these Agents (the project's own, by slug).
+ * Returns null when the platform has no lessons route (an older one).
+ */
+export async function pullLessons(root: string, workspace: string, ws: SyncClient, agents: string[]): Promise<LessonsPulled | null> {
+  const found = await ws.find<unknown>('/v1/sync/lessons')
+  if (found === null) return null
+  const byAgent = new Map(rows<LessonsRow>(found).map((r) => [r.agent, r.rules]))
+  const record = readRecord(root, workspace)
+  const out: LessonsPulled = { written: [], removed: [], kept: [], rules: 0 }
+  for (const slug of [...new Set(agents)].sort()) {
+    const path = join(root, lessonsPath(slug))
+    const here = existsSync(path) ? readFileSync(path, 'utf8') : null
+    const editedHere = here !== null && record.files[slug] !== sha(here)
+    const rules = byAgent.get(slug) ?? []
+    if (!rules.length) {
+      if (here !== null && !editedHere) {
+        rmSync(path, { force: true })
+        delete record.files[slug]
+        out.removed.push(slug)
+      }
+      continue
+    }
+    const text = lessonsText(rules)
+    out.rules += rules.length
+    if (here === text) {
+      record.files[slug] = sha(text)
+      ;(record.rules ??= {})[slug] = rules.map((r) => r.text)
+      continue
+    }
+    if (editedHere) {
+      out.kept.push(slug)
+      continue
+    }
+    mkdirSync(join(root, 'agents', slug), { recursive: true })
+    writeFileSync(path, text)
+    record.files[slug] = sha(text)
+    ;(record.rules ??= {})[slug] = rules.map((r) => r.text)
+    out.written.push(slug)
+  }
+  mkdirSync(join(root, '.frontera', 'sync'), { recursive: true })
+  writeFileAtomic(join(root, LESSONS_JSON), `${JSON.stringify(record, null, 2)}\n`, 0o644)
+  return out
+}
+
+// ── Proposing them back ──────────────────────────────────────────────────────
+
+/** What a change request would carry of an Agent's lessons file, or null when it is as the last pull (or Apply) left it. */
+export function lessonsProposal(root: string, workspace: string, slug: string): { rules: string[]; added: string[]; removed: string[]; pulled: boolean } | null {
+  const path = join(root, lessonsPath(slug))
+  if (!existsSync(path)) return null
+  const text = readFileSync(path, 'utf8')
+  const record = readRecord(root, workspace)
+  if (record.files[slug] === sha(text)) return null
+  let rules: string[]
+  try {
+    rules = readLessons(text)
+  } catch {
+    rules = []
+  }
+  const before = record.rules?.[slug] ?? []
+  return { rules, added: rules.filter((r) => !before.includes(r)), removed: before.filter((r) => !rules.includes(r)), pulled: slug in record.files }
+}
+
+/**
+ * The Agents whose lessons a change request would carry now, as `push` finds
+ * them. A fetch never lists lessons, so `status` (and Forge's card) count
+ * these beside the plan's changes.
+ */
+export function lessonsToPropose(root: string, workspace: string): string[] {
+  const agents = join(root, 'agents')
+  if (!existsSync(agents)) return []
+  return readdirSync(agents)
+    .filter((slug) => lessonsProposal(root, workspace, slug) !== null)
+    .sort()
+}
+
+/**
+ * After an Apply proposed an Agent's rules: the file is taken as the last pull
+ * left it, so it is not proposed again, and the next pull brings the rules the
+ * platform's reviewers approved (a rule still waiting for review leaves it
+ * until then).
+ */
+export function adoptProposedLessons(root: string, workspace: string, slugs: string[]): void {
+  if (!slugs.length) return
+  const record = readRecord(root, workspace)
+  for (const slug of slugs) {
+    const path = join(root, lessonsPath(slug))
+    if (!existsSync(path)) continue
+    const text = readFileSync(path, 'utf8')
+    record.files[slug] = sha(text)
+    try {
+      ;(record.rules ??= {})[slug] = readLessons(text)
+    } catch {
+      // A file that doesn't parse proposed nothing.
+    }
+  }
+  mkdirSync(join(root, '.frontera', 'sync'), { recursive: true })
+  writeFileAtomic(join(root, LESSONS_JSON), `${JSON.stringify(record, null, 2)}\n`, 0o644)
+}
+
+type Call = (method: string, path: string, body?: unknown) => Promise<{ status: number; body: unknown }>
+
+/** Why an efficient-prompts Agent's lessons don't reach its prompt here, as the build says it. */
+export const LESSONS_NOT_EMBEDDED = 'Its lessons don’t reach its prompt here: with efficient prompts they are retrieved by similarity, and this runtime couldn’t embed them (it has no embedding model set)'
+
+const dataOf = (body: unknown) => ((body as { data?: unknown } | null)?.data ?? body) as unknown
+
+const errorOf = (a: { status: number; body: unknown }) => {
+  const b = a.body as { message?: unknown } | null
+  return `${a.status} ${String(typeof b?.message === 'string' ? b.message : JSON.stringify(b)).replace(/\s+/g, ' ').slice(0, 200)}`
+}
+
+/** The names the runtime's prompt reads an Agent's rules under: its name (the chat's) and its slug (memory retrieval's). */
+function agentKeys(root: string, slug: string): { keys: string[]; efficient: boolean } {
+  try {
+    const doc = JSON.parse(readFileSync(join(root, 'agents', slug, 'agent.json'), 'utf8')) as { config?: { name?: unknown; features?: { efficientPrompts?: unknown } } }
+    const name = typeof doc.config?.name === 'string' && doc.config.name.trim() ? doc.config.name.trim() : null
+    return { keys: [...new Set([slug, ...(name ? [name] : [])])], efficient: doc.config?.features?.efficientPrompts === true }
+  } catch {
+    return { keys: [slug], efficient: false }
+  }
+}
+
+/**
+ * Give an Agent its lessons on the runtime: each rule in the file is an
+ * active feedback rule there, and an active rule the file no longer has is
+ * expired. The runtime's chat reads rules by the Agent's name and its
+ * memory retrieval by its slug, so each is saved under both.
+ *
+ * Each rule is saved embedded (`embed`), with the runtime's embedding model,
+ * as efficient prompts retrieve rules by similarity. For an Agent with
+ * efficient prompts, a rule saved earlier without an embedding is saved
+ * again with one. When the runtime cannot embed, the build says the lessons
+ * don't reach that prompt.
+ */
+export async function applyLessons(root: string, slug: string, call: Call): Promise<{ ok: boolean; output: string }> {
+  const path = join(root, lessonsPath(slug))
+  if (!existsSync(path)) return { ok: false, output: `error [LESSONS]: ${lessonsPath(slug)} is missing` }
+  let wanted: string[]
+  try {
+    wanted = readLessons(readFileSync(path, 'utf8'))
+  } catch (err) {
+    return { ok: false, output: `error [USAGE]: ${lessonsPath(slug)} does not parse: ${(err as Error).message.split('\n')[0]}` }
+  }
+  const { keys, efficient } = agentKeys(root, slug)
+  let added = 0
+  let expired = 0
+  let notEmbedded = 0
+  for (const agentName of keys) {
+    const listed = await call('GET', `/v1/feedback/rules?agentName=${encodeURIComponent(agentName)}&status=active`)
+    if (listed.status >= 400) return { ok: false, output: `error [LESSONS]: ${errorOf(listed)}` }
+    const active = (dataOf(listed.body) as Array<{ id: string; ruleText: string; workspaceId?: string | null; embedding?: unknown }> | null) ?? []
+    // The runtime's own rules for this Agent; one every workspace shares is not the project's to expire.
+    const own = active.filter((r) => r.workspaceId)
+    // Efficient prompts retrieve rules by similarity: a rule of the project's saved here without
+    // an embedding (before the runtime embedded them) is saved again, with one.
+    const unembedded = efficient ? own.filter((r) => wanted.includes(r.ruleText) && (r.embedding === null || r.embedding === undefined)) : []
+    for (const rule of wanted) {
+      const again = unembedded.find((r) => r.ruleText === rule)
+      if (active.some((r) => r.ruleText === rule) && !again) continue
+      const made = await call('POST', '/v1/feedback/rules', { agentName, ruleText: rule, confidence: '1', sourceFeedbackIds: [], status: 'active', embed: true })
+      if (made.status >= 400) return { ok: false, output: `error [LESSONS]: ${errorOf(made)}` }
+      const embedded = (dataOf(made.body) as { embedded?: unknown } | null)?.embedded === true
+      if (!embedded) notEmbedded += 1
+      if (again) {
+        // The new copy is there; the old one goes, unless the new one has no embedding either.
+        if (!embedded) {
+          const dropped = await call('PATCH', `/v1/feedback/rules/${encodeURIComponent(String(((dataOf(made.body) as { id?: unknown } | null)?.id) ?? ''))}`, { status: 'expired' })
+          if (dropped.status >= 400) return { ok: false, output: `error [LESSONS]: ${errorOf(dropped)}` }
+          continue
+        }
+        const gone = await call('PATCH', `/v1/feedback/rules/${encodeURIComponent(again.id)}`, { status: 'expired' })
+        if (gone.status >= 400) return { ok: false, output: `error [LESSONS]: ${errorOf(gone)}` }
+        continue
+      }
+      added += 1
+    }
+    for (const r of own.filter((x) => !wanted.includes(x.ruleText))) {
+      const gone = await call('PATCH', `/v1/feedback/rules/${encodeURIComponent(r.id)}`, { status: 'expired' })
+      if (gone.status >= 400) return { ok: false, output: `error [LESSONS]: ${errorOf(gone)}` }
+      expired += 1
+    }
+  }
+  const lines = [`  ${wanted.length} lesson${wanted.length === 1 ? '' : 's'} for Agent ${slug}${added || expired ? ` (${[added ? `${added} saved` : '', expired ? `${expired} expired` : ''].filter(Boolean).join(', ')})` : ''}`]
+  // With efficient prompts the platform retrieves the rules closest to each message by their
+  // embeddings; a rule the runtime could not embed doesn't reach that prompt.
+  if (efficient && notEmbedded) lines.push(`  warning: ${LESSONS_NOT_EMBEDDED}`)
+  return { ok: true, output: lines.join('\n') }
+}