@frontera-sdk/cli 1.52.38 → 1.52.40

package/src/local/local-media-sets.ts

@@ -8,24 +8,104 @@
  * extracted text or passages is still left off (`local-portability.ts`).
  */
 
+import type { LocalCredentials } from './local-state'
+
 type Call = (method: string, path: string, body?: unknown) => Promise<{ status: number; body: unknown }>
 
+/** One file into a local Media Set, as the runtime's owner (multipart, so not through a JSON call). */
+export function mediaUpload(serviceUrl: string, creds: LocalCredentials, fetcher: typeof fetch = fetch) {
+  return async (mediaSetId: string, file: { bytes: Uint8Array; mime: string; filename: string; logicalPath: string }): Promise<{ status: number; body: unknown }> => {
+    const form = new FormData()
+    form.set('file', new File([new Blob([file.bytes.slice().buffer as ArrayBuffer])], file.filename, { type: file.mime }))
+    form.set('logicalPath', file.logicalPath)
+    const res = await fetcher(new URL(`/v1/media/sets/${encodeURIComponent(mediaSetId)}/items`, serviceUrl), {
+      method: 'POST',
+      headers: { authorization: `Bearer ${creds.session}`, 'x-org-id': creds.organizationId, 'x-workspace-id': creds.workspaceId },
+      body: form,
+    })
+    const text = await res.text()
+    let body: unknown = text
+    try {
+      body = text ? JSON.parse(text) : null
+    } catch {
+      // Keep the text.
+    }
+    return { status: res.status, body }
+  }
+}
+
 const dataOf = (body: unknown) => ((body as { data?: unknown } | null)?.data ?? body) as unknown
 
+export interface MediaSetsReady {
+  /** Why one could not be made or read, or null. */
+  why: string | null
+  /**
+   * Each set's catalog dataset on the runtime, by the set's API name. It is
+   * `media_<set>` unless that name was taken when the set was made (a sample
+   * dataset of the same name): the runtime then names the catalog otherwise.
+   */
+  catalogs: Record<string, string>
+  /** What could not be done and is said, not stopped on: a set the workspace could not be granted. */
+  warnings: string[]
+}
+
+/**
+ * The workspace's `read` + `write` grant on a stand-in set, so `local dev`
+ * can browse it and put placeholder files in it. A runtime grants a set made
+ * from a workspace to it as it makes it; a set an earlier `local dev` made
+ * on an older runtime has none, and its `/items` answers 404. A refusal is a
+ * warning: the set's type is applied, without rows here.
+ */
+async function grantWorkspace(call: Call, apiName: string, id: string, workspaceId: string): Promise<string | null> {
+  const granted = await call('POST', `/v1/media/sets/${encodeURIComponent(id)}/grants`, { workspaceId, permissions: ['read', 'write'] })
+  if (granted.status < 400) return null
+  const message = (granted.body as { message?: unknown } | null)?.message
+  return `the workspace couldn’t be granted the stand-in Media Set ${apiName} (${granted.status}${typeof message === 'string' ? ` ${message.slice(0, 160)}` : ''}), so its files can’t be listed or added here`
+}
+
 /**
- * Make each Media Set the runtime lacks, by API name, as the runtime's owner.
- * Returns why one could not be made, or null.
+ * Make each Media Set the runtime lacks, by API name, as the runtime's owner,
+ * and read the dataset each one's catalog is. The project's own runtime only
+ * (`local dev`): each set it makes, and each it finds the workspace can't
+ * read, is granted to the workspace (`workspaceId`).
  */
-export async function ensureMediaSets(sets: Record<string, string>, call: Call): Promise<string | null> {
+export async function ensureMediaSets(sets: Record<string, string>, call: Call, workspaceId?: string): Promise<MediaSetsReady> {
+  const catalogs: Record<string, string> = {}
+  const warnings: string[] = []
   const names = Object.keys(sets)
-  if (!names.length) return null
+  if (!names.length) return { why: null, catalogs, warnings }
   const listed = await call('GET', '/v1/media/sets')
-  if (listed.status >= 400) return `the runtime’s Media Sets couldn’t be read (${listed.status})`
-  const here = new Set(((dataOf(listed.body) as { mediaSets?: Array<{ apiName?: string }> } | null)?.mediaSets ?? []).map((s) => s.apiName))
+  if (listed.status >= 400) return { why: `the runtime’s Media Sets couldn’t be read (${listed.status})`, catalogs, warnings }
+  const here = new Map(((dataOf(listed.body) as { mediaSets?: Array<{ id?: string; apiName?: string }> } | null)?.mediaSets ?? []).map((s) => [s.apiName, s.id] as const))
   for (const apiName of names) {
-    if (here.has(apiName)) continue
-    const made = await call('POST', '/v1/media/sets', { apiName, displayName: sets[apiName], description: 'An empty stand-in for the platform’s Media Set: its files stay on the platform.' })
-    if (made.status >= 400) return `the Media Set ${apiName} couldn’t be made (${made.status} ${JSON.stringify(made.body).slice(0, 160)})`
+    const id = here.get(apiName)
+    if (!id) {
+      const made = await call('POST', '/v1/media/sets', { apiName, displayName: sets[apiName], description: 'A stand-in for the platform’s Media Set: its files stay on the platform. `frontera local dev` puts placeholder files in it while it is empty.' })
+      if (made.status >= 400) return { why: `the Media Set ${apiName} couldn’t be made (${made.status} ${JSON.stringify(made.body).slice(0, 160)})`, catalogs, warnings }
+      const created = dataOf(made.body) as { mediaSet?: { id?: unknown }; dataset?: { apiName?: unknown } } | null
+      const dataset = created?.dataset?.apiName
+      if (typeof dataset === 'string') catalogs[apiName] = dataset
+      // A runtime that grants a new set to its workspace already has; an older one has not, and this is the same grant.
+      const madeId = created?.mediaSet?.id
+      if (workspaceId && typeof madeId === 'string') {
+        const warning = await grantWorkspace(call, apiName, madeId, workspaceId)
+        if (warning) warnings.push(warning)
+      }
+      continue
+    }
+    // Made by an earlier run on an older runtime, without the workspace's grant: its items answer 404.
+    if (workspaceId) {
+      const items = await call('GET', `/v1/media/sets/${encodeURIComponent(id)}/items`)
+      if (items.status === 404) {
+        const warning = await grantWorkspace(call, apiName, id, workspaceId)
+        if (warning) warnings.push(warning)
+      }
+    }
+    // Made earlier: its catalog, made now if the set predates catalogs.
+    let read = await call('GET', `/v1/media/sets/${encodeURIComponent(id)}/dataset`)
+    if (read.status < 400 && !(dataOf(read.body) as { dataset?: unknown } | null)?.dataset) read = await call('POST', `/v1/media/sets/${encodeURIComponent(id)}/dataset`)
+    const dataset = read.status < 400 ? (dataOf(read.body) as { dataset?: { apiName?: unknown } } | null)?.dataset?.apiName : undefined
+    if (typeof dataset === 'string') catalogs[apiName] = dataset
   }
-  return null
+  return { why: null, catalogs, warnings }
 }

package/src/local/local-model-parameters.ts

@@ -0,0 +1,89 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { parse as parseYaml } from 'yaml'
+
+import { PROVIDER_MODELS } from './local-seed'
+
+/**
+ * A workflow `llm` node's `temperature` that its model refuses (e2e G5).
+ *
+ * The runtime's model catalog does not record which sampling parameters a
+ * model takes, so such a node passes `validate` and `apply`, and its runs
+ * fail at the step with `model_parameter`. The local catalog's own models
+ * are known here (`PROVIDER_MODELS`): the ones served directly by Anthropic
+ * that refuse `temperature` are said at apply, as a validation warning of the
+ * node, with the fix.
+ *
+ * Only direct Anthropic models: through OpenRouter a parameter can be handled
+ * differently, and what is not known is not said.
+ */
+
+/** How a model takes `temperature`: any value refused, or any but its default (1). */
+type TemperatureRule = 'refused' | 'default-only'
+
+/** Anthropic's models by id, newest first: those that refuse sampling parameters. */
+const ANTHROPIC_TEMPERATURE: Array<{ match: RegExp; rule: TemperatureRule }> = [
+  { match: /^claude-(sonnet|haiku)-5-5\b/, rule: 'default-only' },
+  { match: /^claude-(fable-5|mythos-5|opus-5|opus-4-[78]|sonnet-5)(-|$)/, rule: 'refused' },
+]
+
+/** The model a catalog slug names, when it is one the local catalog adds directly from Anthropic. */
+function directAnthropic(slug: string): { name: string; rule: TemperatureRule } | null {
+  const model = PROVIDER_MODELS.anthropic?.find((m) => m.slug === slug)
+  if (!model) return null
+  const rule = ANTHROPIC_TEMPERATURE.find((r) => r.match.test(model.modelId))?.rule
+  return rule ? { name: model.name.replace(/\s*\([^)]*\)$/, ''), rule } : null
+}
+
+/** Whether `temperature` set to `value` is refused by the model `slug` names, with the model's name; null when it is taken or not known. */
+export function temperatureRefusal(slug: string, value: unknown): { name: string; rule: TemperatureRule } | null {
+  const known = directAnthropic(slug)
+  if (!known) return null
+  if (known.rule === 'default-only' && value === 1) return null
+  return known
+}
+
+/** The `llm` nodes of a workflow at any depth (branches, loops, parallel arms): id, the model reference and the temperature set. */
+export function llmNodes(doc: unknown): Array<{ id: string; model: string | null; temperature: unknown }> {
+  const out: Array<{ id: string; model: string | null; temperature: unknown }> = []
+  const visit = (v: unknown) => {
+    if (Array.isArray(v)) return v.forEach(visit)
+    if (!v || typeof v !== 'object') return
+    const o = v as Record<string, unknown>
+    if (o.kind === 'llm' && typeof o.id === 'string') {
+      const params = (o.params ?? {}) as Record<string, unknown>
+      out.push({ id: o.id, model: typeof o.resourceId === 'string' ? o.resourceId : null, temperature: params.temperature })
+    }
+    for (const [k, x] of Object.entries(o)) if (k !== 'trigger' && k !== 'layout') visit(x)
+  }
+  visit((doc as Record<string, unknown> | null)?.nodes ?? [])
+  return out
+}
+
+/**
+ * The warnings for a workflow file's `llm` nodes whose model refuses their
+ * `temperature`, as `workflow push` prints a node's validation warning.
+ * `models` maps catalog slugs to ids, so a file whose references were
+ * resolved to this runtime's ids is read too.
+ */
+export function llmParameterNotes(root: string, file: string, models?: ReadonlyMap<string, string>): string[] {
+  let doc: unknown
+  try {
+    const text = readFileSync(join(root, file), 'utf8')
+    doc = /\.json$/.test(file) ? JSON.parse(text) : parseYaml(text)
+  } catch {
+    return []
+  }
+  const slugOf = new Map([...(models ?? [])].map(([slug, id]) => [id, slug]))
+  const lines: string[] = []
+  for (const node of llmNodes(doc)) {
+    if (node.temperature === undefined || !node.model) continue
+    const ref = node.model.startsWith('model/') ? node.model.slice('model/'.length) : (slugOf.get(node.model) ?? node.model)
+    const refused = temperatureRefusal(ref, node.temperature)
+    if (!refused) continue
+    const what = refused.rule === 'refused' ? 'doesn’t take `temperature`' : 'takes no `temperature` but its default, 1'
+    lines.push(`  warning: node "${node.id}": the model ${ref} (${refused.name}) ${what}, so every run fails at this step (\`model_parameter\`): remove \`temperature\` from its params`)
+  }
+  return lines
+}

package/src/local/local-object-sets.ts

@@ -6,7 +6,7 @@ import { parse as parseYaml } from 'yaml'
 import { isIgnoredName } from './local-dev-sync'
 import type { LocalCredentials } from './local-state'
 import { objectSetNames, rows, type ObjectSetRow } from './local-sync-remote'
-import { parseRef, referencesIn, toIds } from './local-sync-refs'
+import { lookupRef, parseRef, referencesIn, refName, toIds } from './local-sync-refs'
 
 /**
  * Saved object sets on the local runtime, from `blueprint/object-sets/`.
@@ -82,6 +82,8 @@ export interface ObjectSetsApplied {
   warnings: string[]
   /** Sets created again under a new id: what names them is applied again. */
   recreated: string[]
+  /** Each project set's id on the runtime, by its file's reference (`open-work-orders`): what `status` shows. */
+  ids: Record<string, string>
 }
 
 /**
@@ -90,7 +92,7 @@ export interface ObjectSetsApplied {
  * left off too, with why.
  */
 export async function applyObjectSets(root: string, call: Fetcher, leftOff: ReadonlySet<string> = new Set()): Promise<ObjectSetsApplied> {
-  const out: ObjectSetsApplied = { lines: [], warnings: [], recreated: [] }
+  const out: ObjectSetsApplied = { lines: [], warnings: [], recreated: [], ids: {} }
   const files = readObjectSetFiles(root)
   if (!files.length) return out
   const listed = await call('GET', '/v1/sync/object-sets')
@@ -124,7 +126,7 @@ export async function applyObjectSets(root: string, call: Fetcher, leftOff: Read
         continue
       }
       // A set naming another waits for that one.
-      const waits = referencesIn(doc.definition).filter((r) => r.kind === 'objectSet' && !ids.has(r.name))
+      const waits = referencesIn(doc.definition).filter((r) => r.kind === 'objectSet' && !lookupRef(ids, 'objectSet', r.name))
       if (waits.length) {
         next.push(f)
         continue
@@ -132,7 +134,9 @@ export async function applyObjectSets(root: string, call: Fetcher, leftOff: Read
       const { doc: definition } = toIds(doc.definition, { objectSet: ids })
       const description = typeof doc.description === 'string' ? doc.description : undefined
       const records = Array.isArray(doc.records) ? (doc.records as Array<string | number>) : []
-      const have = byRef.get(f.ref)
+      // By its file's name, or by its own name as a reference holds it (a pull names the file so).
+      const have = byRef.get(f.ref) ?? byRef.get(refName(name))
+      if (have && !ids.has(f.ref)) ids.set(f.ref, have.id)
       let saved: { status: number; body: unknown }
       if (have && kind === 'dynamic' && have.kind === 'dynamic') {
         if (have.name === name && (have.description ?? undefined) === description && same(have.definition, definition)) continue
@@ -160,18 +164,26 @@ export async function applyObjectSets(root: string, call: Fetcher, leftOff: Read
         continue
       }
       const row = ((saved.body as { data?: unknown })?.data ?? saved.body) as { id?: string }
-      if (row?.id) ids.set(f.ref, row.id)
+      if (row?.id) {
+        ids.set(f.ref, row.id)
+        // Named in words elsewhere (`objectSet/Open work orders`): found by its name too.
+        if (!ids.has(refName(name))) ids.set(refName(name), row.id)
+      }
       out.lines.push(`  saved object set ${f.ref}`)
     }
     if (next.length === pending.length) {
       for (const f of next) {
-        const missing = referencesIn(f.doc.definition).filter((r) => r.kind === 'objectSet' && !ids.has(r.name)).map((r) => `objectSet/${r.name}`)
+        const missing = referencesIn(f.doc.definition).filter((r) => r.kind === 'objectSet' && !lookupRef(ids, 'objectSet', r.name)).map((r) => `objectSet/${r.name}`)
         out.warnings.push(`  warning: saved object set ${f.ref} was not saved here: it names ${missing.join(', ')}, which isn't in the project`)
       }
       break
     }
     pending = next
   }
+  for (const f of files) {
+    const id = ids.get(f.ref)
+    if (id) out.ids[f.ref] = id
+  }
   return out
 }
 

package/src/local/local-operating.ts

@@ -15,6 +15,39 @@ import type { LocalCredentials } from './local-state'
 interface Result {
   ok: boolean
   output: string
+  /**
+   * The `warning:` lines of `output` that are the platform's own findings on
+   * the settings (`handoff_needs_inbox`, a placeholder no variable fills):
+   * they hold wherever the Agent runs, so they are not adaptations to this
+   * runtime.
+   */
+  validationWarnings?: string[]
+}
+
+interface Issue {
+  severity?: string
+  code?: string
+  path?: string
+  message?: string
+}
+
+/**
+ * The issues a saved draft still has, one `warning:` line each, named by the
+ * project file and the setting's path
+ * (`agents/customer-care/operating.json procedures.3.actions.0`). Saving
+ * refuses only a malformed document; a cross-reference error is returned
+ * with the warnings and refuses publishing, so it is said too, as that.
+ */
+export function operatingIssueLines(slug: string, body: unknown): string[] {
+  const data = ((body as { data?: unknown } | null)?.data ?? body) as { issues?: unknown } | null
+  const issues = Array.isArray(data?.issues) ? (data.issues as Issue[]) : []
+  return issues.map((issue) => {
+    const path = typeof issue.path === 'string' ? issue.path : ''
+    // The Agent's instructions are its agent.json prompts, not its behavior settings.
+    const file = path === 'instructions' || path.startsWith('instructions.') ? `agents/${slug}/agent.json` : `agents/${slug}/operating.json`
+    const blocks = issue.severity === 'error' ? ' (publishing is refused until this is fixed)' : ''
+    return `  warning: ${file}${path ? ` ${path}` : ''}: ${issue.message ?? issue.code ?? 'see the Agent’s settings'}${blocks}`
+  })
 }
 
 function describeError(status: number, body: unknown): string {
@@ -79,7 +112,8 @@ export async function applyOperatingConfig(args: {
     if (agent.status !== 200 || !id) return { ok: false, output: describeError(agent.status, agent.body) }
     const put = await call(`/v1/config/agents/${id}/operating`, { method: 'PUT', body: { operatingConfig } })
     if (put.status >= 400) return { ok: false, output: describeError(put.status, put.body) }
-    return { ok: true, output: '' }
+    const warnings = operatingIssueLines(args.slug, put.body)
+    return { ok: true, output: warnings.join('\n'), ...(warnings.length ? { validationWarnings: warnings } : {}) }
   } catch (err) {
     return { ok: false, output: `error [UNAVAILABLE]: the local service did not answer: ${(err as Error).message}` }
   }

package/src/local/local-org-settings.ts

@@ -40,18 +40,105 @@ const pair = (p?: { provider: string | null; model: string | null }) => (p?.prov
 
 const onOff = (v?: boolean) => (v ? 'on' : 'off')
 
+type Embedding = { provider: string | null; model: string | null }
+
+/**
+ * One embedding model through each provider that serves it, in the order a
+ * runtime takes them: the vectors are the same, so knowledge search ranks the
+ * same whichever one embeds. Gemini's through Vertex, a Gemini key or
+ * OpenRouter; OpenAI's small model directly or through OpenRouter.
+ */
+const EMBEDDING_FAMILIES: Array<Array<{ provider: string; model: string }>> = [
+  [
+    { provider: 'vertex', model: 'gemini-embedding-001' },
+    { provider: 'google', model: 'gemini-embedding-001' },
+    { provider: 'openrouter', model: 'google/gemini-embedding-001' },
+  ],
+  [
+    { provider: 'openai', model: 'text-embedding-3-small' },
+    { provider: 'openrouter', model: 'openai/text-embedding-3-small' },
+  ],
+]
+
+/**
+ * The platform's default embedding model: the one an organization is seeded
+ * with, and the one a knowledge base's default threshold is tuned for. A copy
+ * of the service's `DEFAULT_EMBEDDING_PROVIDER` / `DEFAULT_EMBEDDING_MODEL`
+ * (packages/service/src/internal/embedding-defaults.ts), without the
+ * deployment's environment override, which the CLI cannot see.
+ */
+export const PLATFORM_DEFAULT_EMBEDDING = { provider: 'vertex', model: 'gemini-embedding-001' } as const
+
+/** The platform's default knowledge threshold (a maximum cosine distance: lower is stricter). */
+export const DEFAULT_KNOWLEDGE_THRESHOLD = 0.5
+
+/** The threshold a local runtime searches a knowledge base with when it embeds with another model than the one the default is tuned for. */
+export const WIDENED_KNOWLEDGE_THRESHOLD = 0.8
+
+/**
+ * The threshold every knowledge base searches with on the keyless local
+ * embeddings (`local-embeddings.ts`), whatever its file sets: a threshold is
+ * tuned for a model's distances, and these are on another scale.
+ *
+ * Derived from how those vectors behave. Each word is a ±1 at a hashed
+ * position, so the cosine of a question of q words and a passage of c words
+ * is about (the words they share) / √(q·c), and a text that shares none
+ * sits at a distance of about 1 (orthogonal). One shared word in a 6-word
+ * question and a 2,048-character chunk (some 300 words) is a cosine of
+ * 1/√1800 ≈ 0.024, a distance of 0.976: the platform's 0.5, or the 0.8 a
+ * model's base is widened to, cuts it, and nearly every short question.
+ * 0.99 keeps a passage that shares a word with the question in chunks of up
+ * to some 1,600 words (q·c ≤ 10⁴, cosine ≥ 0.01) and leaves out the ones
+ * that share none; the base's top-K then keeps the passages that share the most.
+ * A word hashed onto another's position can let in a passage sharing none
+ * (the hashing's noise is about one such word), so this is approximate
+ * retrieval, said as that. Never used for a model's embeddings.
+ */
+export const KEYLESS_KNOWLEDGE_THRESHOLD = 0.99
+
+/**
+ * What a reader is told where knowledge search runs on the keyless local
+ * embeddings (`local status`, `knowledge get` and `search`, the apply's
+ * warning): the retrieval is approximate, and what gives the platform's.
+ */
+export const KEYLESS_RETRIEVAL_NOTE = `retrieval here runs on approximate local embeddings (words hashed into vectors): a passage is found by the words it shares with the question, not by its meaning, and each knowledge base searches with threshold ${KEYLESS_KNOWLEDGE_THRESHOLD}, set for these vectors (its file keeps its own threshold for the workspace). A key the provider accepts for an embedding model gives the platform's retrieval: \`frontera local key-set <provider>\` (openai or openrouter; google when the workspace embeds with Gemini's model), then \`frontera local stop\` and \`frontera local start\`; the next \`frontera local dev\` sets each base's threshold for that model`
+
+/** How a difference line says the runtime refused the workspace's model through this computer's key (`mirrorOrgSettings`). */
+const KEY_REFUSED = /; the runtime refused it through this computer’s (\S+) key/
+
+/** The provider's name as a key is named, for the line that says which key embeds. */
+const KEY_NAME: Record<string, string> = { google: 'Gemini', openrouter: 'OpenRouter', openai: 'OpenAI', vertex: 'Vertex' }
+
+const familyOf = (e?: Embedding | null) => (e?.provider && e.model ? EMBEDDING_FAMILIES.find((f) => f.some((m) => m.provider === e.provider && m.model === e.model)) : undefined)
+
+/** The choices that embed as this one does: itself first, then the same model through other providers. */
+export function embeddingEquivalents(e: Embedding): Array<{ provider: string; model: string }> {
+  if (!e.provider || !e.model) return []
+  const self = { provider: e.provider, model: e.model }
+  return [self, ...(familyOf(e) ?? []).filter((m) => m.provider !== self.provider || m.model !== self.model)]
+}
+
+/** Whether two choices embed alike: the same choice, or the same model through another provider. */
+export function sameEmbedding(a?: Embedding | null, b?: Embedding | null): boolean {
+  if ((a?.provider ?? null) === (b?.provider ?? null) && (a?.model ?? null) === (b?.model ?? null)) return true
+  const family = familyOf(a)
+  return !!family && family === familyOf(b)
+}
+
 /**
  * Where the runtime's settings differ from the workspace's, one line each,
  * the timezone left out (`local dev` sets it). A flag or setting only one
  * side reports (an older runtime) is left out too: nothing to compare.
  */
-export function settingsDifferences(workspace: OrgSettings, local: OrgSettings): string[] {
+export function settingsDifferences(workspace: OrgSettings, local: OrgSettings, opts: { localEmbeddings?: boolean } = {}): string[] {
   const out: string[] = []
   const differs = (a: unknown, b: unknown) => JSON.stringify(a ?? null) !== JSON.stringify(b ?? null)
   const both = (k: keyof OrgSettings) => k in workspace && k in local
   if (both('computerMode') && differs(workspace.computerMode, local.computerMode)) out.push(`Computer mode is ${onOff(workspace.computerMode)} in the workspace and ${onOff(local.computerMode)} here`)
   if (both('memoryTree') && differs(workspace.memoryTree, local.memoryTree)) out.push(`The memory tree is ${onOff(workspace.memoryTree)} in the workspace and ${onOff(local.memoryTree)} here`)
-  if (both('embedding') && differs(workspace.embedding, local.embedding)) out.push(`Embeddings use ${pair(workspace.embedding)} in the workspace and ${pair(local.embedding)} here, so knowledge search ranks differently`)
+  // The keyless local embeddings are set as OpenAI's model: said as what they are.
+  const embeddingHere = opts.localEmbeddings && local.embedding?.provider === 'openai' ? 'the keyless local embeddings' : pair(local.embedding)
+  if (both('embedding') && !sameEmbedding(workspace.embedding, local.embedding)) out.push(`Embeddings use ${pair(workspace.embedding)} in the workspace and ${embeddingHere} here, so knowledge search ranks differently`)
   if (both('memoryEmbedding') && differs(workspace.memoryEmbedding, local.memoryEmbedding)) out.push(`Memory embeddings use ${pair(workspace.memoryEmbedding)} in the workspace and ${pair(local.memoryEmbedding)} here`)
   if (both('webSearch') && differs(workspace.webSearch, local.webSearch)) out.push(`Web search is ${workspace.webSearch ?? DEFAULT} in the workspace and ${local.webSearch ?? DEFAULT} here`)
   if (both('imageModel') && differs(workspace.imageModel, local.imageModel)) out.push(`Images are made with ${pair(workspace.imageModel)} in the workspace and ${pair(local.imageModel)} here`)
@@ -59,11 +146,75 @@ export function settingsDifferences(workspace: OrgSettings, local: OrgSettings):
   const ws = workspace.featureFlags ?? {}
   const here = local.featureFlags ?? {}
   for (const key of Object.keys(ws).sort()) {
+    if (NOT_A_DIFFERENCE_HERE.has(key)) continue
     if (key in here && ws[key] !== here[key]) out.push(`Feature ${key} is ${onOff(ws[key])} in the workspace and ${onOff(here[key])} here`)
   }
   return out
 }
 
+/**
+ * What one difference changes when the project is tested on this runtime,
+ * and whether it can be made to match: `effect` in one line, `align` the
+ * step that matches it, or why it stays the runtime's. Read from the line
+ * `settingsDifferences` wrote, so a build recorded by an earlier CLI is said
+ * the same way. Null for a line it does not know.
+ */
+export interface SettingEffect {
+  effect: string
+  align: string
+}
+
+const KEEPS = '`local dev` keeps this runtime’s setting'
+
+export function settingEffect(line: string): SettingEffect | null {
+  const both = (re: RegExp) => re.exec(line)
+  let m = both(/^Computer mode is (on|off) in the workspace and (on|off) here/)
+  if (m) {
+    return m[2] === 'off'
+      ? { effect: 'Agents with computer access run without it here: no browser, files or shell, and attachments go to the model', align: 'Can’t be aligned: the local runtime has no Agent computer; test computer work in the workspace' }
+      : { effect: 'Agents may use a computer here that they can’t in the workspace', align: KEEPS }
+  }
+  m = both(/^The memory tree is (on|off) in the workspace and (on|off) here/)
+  if (m) {
+    return m[2] === 'off'
+      ? { effect: 'Agents remember without the memory tree here, so what they recall across conversations differs from the workspace', align: KEEPS }
+      : { effect: 'Agents remember with the memory tree here, unlike the workspace', align: KEEPS }
+  }
+  if (/^Embeddings use /.test(line)) {
+    const effect = 'Knowledge search ranks passages differently here, so an Agent may cite other passages than in the workspace'
+    // The key is there, and the provider refused it: another key is the step, not "give it a key".
+    const refused = KEY_REFUSED.exec(line)
+    if (refused) {
+      const key = refused[1]!
+      const id = Object.entries(KEY_NAME).find(([, name]) => name === key)?.[0] ?? key.toLowerCase()
+      return { effect, align: `Can be aligned: the provider refused this computer’s ${key} key for it (\`frontera local logs service\` shows its answer after \`[embedding] preflight failed\`): store one it takes with \`frontera local key-set ${id}\`, then \`frontera local dev\` sets it` }
+    }
+    return { effect, align: 'Can be aligned: give this computer a key for the workspace’s model (`frontera local key-set google` or `openrouter`), then `frontera local dev` sets it' }
+  }
+  if (/^Memory embeddings use /.test(line)) {
+    return { effect: 'Agents recall their memories with another model here, so what they recall can differ', align: KEEPS }
+  }
+  m = both(/^Web search is (.+) in the workspace and (.+) here$/)
+  if (m) {
+    return { effect: 'Agents that search the web get results from another provider here, so their answers can cite other pages', align: `${KEEPS}: its provider is set up per deployment` }
+  }
+  if (/^Images are made with /.test(line)) return { effect: 'Images an Agent makes come from another model here', align: KEEPS }
+  if (/^Voice speed is /.test(line)) return { effect: 'Spoken replies play at another speed here', align: KEEPS }
+  m = both(/^Feature (\S+) is (on|off) in the workspace and (on|off) here/)
+  if (m) return { effect: `Whatever ${m[1]} switches is ${m[3]} here and ${m[2]} in the workspace`, align: KEEPS }
+  if (/^The timezone is /.test(line)) return { effect: 'Dates in Blueprint queries and usage windows resolve in another timezone here', align: 'Can be aligned: `frontera local dev` sets it; it failed last time, so run it again' }
+  return null
+}
+
+/**
+ * Feature flags that change nothing about how the project runs locally, so a
+ * different value is not a difference to report. `workflows.enabled` only
+ * shows or hides the Workflows entry in the platform's navigation; the local
+ * runtime applies and runs workflows whatever its value (always on locally
+ * for development).
+ */
+export const NOT_A_DIFFERENCE_HERE: ReadonlySet<string> = new Set(['workflows.enabled'])
+
 type Call = (method: string, path: string, body?: unknown) => Promise<{ status: number; body: unknown }>
 
 export function settingsCalls(serviceUrl: string, creds: LocalCredentials, fetcher: typeof fetch = fetch): Call {
@@ -96,23 +247,70 @@ export interface SettingsMirror {
   differences: string[]
 }
 
+/**
+ * The workspace's embedding model on the runtime, or the same model through
+ * a provider this computer has a key for (the runtime's credentialed
+ * providers, as `/v1/config/embedding` lists them): Gemini's through a Gemini
+ * key, then OpenRouter. Null when none is credentialed here or the runtime
+ * refused it (an older one, whose catalog lacks the model); the difference is
+ * said then.
+ */
+async function mirrorEmbedding(workspace: Embedding, call: Call, opts: MirrorOptions): Promise<{ set: { provider: string; model: string } } | { refused: { provider: string; model: string } } | null> {
+  const read = await call('GET', '/v1/config/embedding')
+  if (read.status >= 400) return null
+  const body = read.body as { data?: { providers?: unknown } } & { providers?: unknown }
+  const providers = (body?.data?.providers ?? body?.providers) as Array<{ id?: unknown }> | undefined
+  const credentialed = new Set((Array.isArray(providers) ? providers : []).map((p) => p?.id).filter((id): id is string => typeof id === 'string'))
+  // The keyless local embeddings answer as OpenAI: their vectors are not OpenAI's model's.
+  if (opts.localEmbeddings) credentialed.delete('openai')
+  const pick = embeddingEquivalents(workspace).find((e) => credentialed.has(e.provider))
+  if (!pick) return null
+  const set = await call('PUT', '/v1/config/embedding', pick)
+  // A refusal here is the provider's answer to this computer's key (the service checks the model before it sets it).
+  return set.status < 400 ? { set: pick } : set.status === 400 ? { refused: pick } : null
+}
+
+export interface MirrorOptions {
+  /** The runtime embeds with the keyless local embeddings, which the service sees as an OpenAI credential. */
+  localEmbeddings?: boolean
+}
+
 /**
  * Make the runtime's organization settings match the workspace's where that
- * is safe, and say where they still differ. Only the timezone is taken (the
+ * is safe, and say where they still differ. The timezone is taken (the
  * owner sets it, as Settings → Usage does): it decides how dates resolve in
- * Blueprint queries and usage windows. The rest stays the runtime's: a
+ * Blueprint queries and usage windows. So is the embedding model, when this
+ * computer has a key for it or for the same model through another provider,
+ * so knowledge search ranks as there. The rest stays the runtime's: a
  * provider or model there needs this computer's own credentials.
  */
-export async function mirrorOrgSettings(workspace: OrgSettings, call: Call): Promise<SettingsMirror> {
+export async function mirrorOrgSettings(workspace: OrgSettings, call: Call, opts: MirrorOptions = {}): Promise<SettingsMirror> {
   const out: SettingsMirror = { lines: [], differences: [] }
   const read = await call('GET', '/v1/sync/settings')
   if (read.status >= 400) return out
-  const local = ((read.body as { data?: unknown })?.data ?? read.body) as OrgSettings
+  let local = ((read.body as { data?: unknown })?.data ?? read.body) as OrgSettings
   if (workspace.timezone && local.timezone && workspace.timezone !== local.timezone) {
     const set = await call('PUT', '/v1/usage-limits/windows', { timezone: workspace.timezone })
     if (set.status < 400) out.lines.push(`  timezone set to ${workspace.timezone}, as in the workspace`)
     else out.differences.push(`The timezone is ${workspace.timezone} in the workspace and ${local.timezone} here; it could not be set (${set.status})`)
   }
-  out.differences.push(...settingsDifferences(workspace, local))
+  let refused: { provider: string; model: string } | null = null
+  if (workspace.embedding?.provider && workspace.embedding.model && 'embedding' in local && !sameEmbedding(workspace.embedding, local.embedding)) {
+    const mirrored = await mirrorEmbedding(workspace.embedding, call, opts).catch(() => null)
+    if (mirrored && 'set' in mirrored) {
+      const set = mirrored.set
+      const same = set.provider === workspace.embedding.provider && set.model === workspace.embedding.model
+      out.lines.push(`  embeddings set to ${pair(set)}${same ? ', as in the workspace' : `, the workspace’s ${pair(workspace.embedding)} through this computer’s ${KEY_NAME[set.provider] ?? set.provider} key`}`)
+      local = { ...local, embedding: set }
+    } else if (mirrored) refused = mirrored.refused
+  }
+  // The key is stored and the provider refused it: said on the line, so its fix is another key, not "give it a key".
+  const keyRefused = refused ? `; the runtime refused it through this computer’s ${KEY_NAME[refused.provider] ?? refused.provider} key (${pair(refused)})` : ''
+  out.differences.push(...settingsDifferences(workspace, local, opts).map((d) => (keyRefused && /^Embeddings use /.test(d) ? `${d}${keyRefused}` : d)))
   return out
 }
+
+/** What `local status --json` and the MCP `status` say of a runtime on the keyless local embeddings. */
+export function keylessEmbeddingsStatus() {
+  return { kind: 'keyless-local', approximate: true, knowledgeThreshold: KEYLESS_KNOWLEDGE_THRESHOLD, note: KEYLESS_RETRIEVAL_NOTE } as const
+}