@frontera-sdk/cli 1.52.42 → 1.52.44

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

@@ -0,0 +1,118 @@
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+import { modelMap, projectFile } from './local-sync-link'
+import type { ModelMap } from './local-sync-portable'
+
+/**
+ * Which model a project's model slug is, on this computer and in the
+ * workspace. A catalog slug is each catalog's own name for a model (this
+ * computer's provider calls it `deepseek-deepseek-v4-1-flash`, the
+ * workspace's `deepseek-v4-1-flash`), so models are matched by what they are:
+ * the provider's model id (`deepseek/deepseek-v4.1-flash`).
+ *
+ *   the same model in the workspace   the file's slug is written as the workspace's when proposed, and the
+ *                                     workspace's as this computer's on pull: nothing to choose
+ *   no such model in the workspace    which model an Agent runs on stays the workspace's choice: the Agent
+ *                                     keeps the workspace's model there (its default, for a new one), and the
+ *                                     local one is this computer's own, never proposed (`local-sync-portable.ts`)
+ *   `sync.models` in frontera.yaml    an explicit choice, over the match
+ *
+ * This computer's catalog is kept when a sync command finds the runtime
+ * running (`.frontera/local/model-catalog.json`), so status and push match
+ * models offline; the workspace's comes with the snapshot.
+ */
+
+export interface CatalogEntry {
+  slug: string
+  name?: string
+  kind?: string
+  provider?: string
+  modelId?: string
+}
+
+const LOCAL_CATALOG = join('.frontera', 'local', 'model-catalog.json')
+const REMOTE_JSON = join('.frontera', 'sync', 'remote.json')
+
+/** Keep this computer's catalog, as the running runtime listed it. */
+export function rememberLocalCatalog(root: string, models: CatalogEntry[]): void {
+  const file = join(root, LOCAL_CATALOG)
+  try {
+    mkdirSync(dirname(file), { recursive: true })
+    writeFileSync(file, `${JSON.stringify({ version: 1, models: models.map(({ slug, name, kind, provider, modelId }) => ({ slug, name, kind, provider, modelId })) }, null, 2)}\n`)
+  } catch {
+    // Matching then falls back to the last copy, or to slugs alone.
+  }
+}
+
+function readJson<T>(file: string): T | null {
+  try {
+    return existsSync(file) ? (JSON.parse(readFileSync(file, 'utf8')) as T) : null
+  } catch {
+    return null
+  }
+}
+
+/** The provider's id as two catalogs write it alike: case and spaces aside. */
+const sameModelId = (id: string | undefined) => (id ?? '').trim().toLowerCase()
+
+export interface ProjectModels {
+  /** A local slug and the workspace slug it goes as: matched by model, then `sync.models` over it. */
+  map: ModelMap
+  /** The workspace's model slugs; null when no snapshot lists them (then nothing is judged missing). */
+  workspace: Set<string> | null
+  /** The workspace's models by slug, for words. */
+  names: Record<string, string>
+}
+
+const cached = new Map<string, { stamp: string; value: ProjectModels }>()
+
+const stampOf = (...files: string[]) =>
+  files
+    .map((f) => {
+      try {
+        return String(statSync(f).mtimeMs)
+      } catch {
+        return '-'
+      }
+    })
+    .join('|')
+
+/** The project's models as push and status read them; read again only when one of their files changes. */
+export function projectModels(root: string): ProjectModels {
+  const files = [projectFile(root), join(root, LOCAL_CATALOG), join(root, REMOTE_JSON)]
+  const stamp = stampOf(...files)
+  const known = cached.get(root)
+  if (known && known.stamp === stamp) return known.value
+  const remote = readJson<{ models?: CatalogEntry[]; names?: { model?: Record<string, string> } }>(join(root, REMOTE_JSON))
+  const theirs = remote?.models ?? Object.keys(remote?.names?.model ?? {}).map((slug) => ({ slug }) as CatalogEntry)
+  const ours = readJson<{ models?: CatalogEntry[] }>(join(root, LOCAL_CATALOG))?.models ?? []
+  const value = matchModels(ours, theirs.length ? theirs : null, modelMap(root))
+  cached.set(root, { stamp, value })
+  return value
+}
+
+/** The match itself: each local model the workspace has under another slug, by the provider's id; the explicit choices over it. */
+export function matchModels(ours: CatalogEntry[], theirs: CatalogEntry[] | null, explicit: ModelMap = {}): ProjectModels {
+  if (!theirs) return { map: { ...explicit }, workspace: null, names: {} }
+  const workspace = new Set(theirs.map((m) => m.slug))
+  const byId = new Map<string, CatalogEntry[]>()
+  for (const m of theirs) {
+    if ((m.kind ?? 'text') !== 'text' || !m.modelId) continue
+    byId.set(sameModelId(m.modelId), [...(byId.get(sameModelId(m.modelId)) ?? []), m])
+  }
+  // A platform that lists its models without the provider's id (older than these fields): a slug made from the
+  // provider's id, whole or its model part (`deepseek/deepseek-v4.1-flash` → `deepseek-v4-1-flash`), is the same model.
+  const slugify = (s: string) => s.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '')
+  const bySlug = new Map(theirs.filter((t) => !t.modelId).map((t) => [slugify(t.slug), t]))
+  const map: ModelMap = {}
+  for (const m of ours) {
+    if (workspace.has(m.slug) || !m.modelId) continue
+    const guessed = [slugify(m.modelId), slugify(m.modelId.split('/').pop() ?? '')].map((s) => bySlug.get(s)).find(Boolean)
+    const same = byId.get(sameModelId(m.modelId)) ?? (guessed ? [guessed] : [])
+    // One model under two of the workspace's providers: the one named alike, else the first.
+    const pick = same.find((w) => w.name && w.name === m.name) ?? same[0]
+    if (pick) map[m.slug] = pick.slug
+  }
+  return { map: { ...map, ...explicit }, workspace, names: Object.fromEntries(theirs.map((m) => [m.slug, m.name ?? m.slug])) }
+}

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

@@ -9,6 +9,8 @@ import { conflictsId, deepEqual, mergeItemFiles, type Choice, type Side } from '
 import { itemTitle } from './local-sync-names'
 import { toNames, type Directory, type Unresolved } from './local-sync-refs'
 import { comparableText, isPluginFile, withLocalSecrets } from './local-secrets'
+import { projectModels } from './local-sync-models'
+import { comparablePortable, toLocal } from './local-sync-portable'
 
 /**
  * A pull is a plan first. Each item in the workspace (an Agent with its
@@ -314,17 +316,24 @@ export function statusFor(base: string | null, local: string | null, remote: str
   return 'same'
 }
 
-/** A working file as it compares with the workspace's: a Plugin's secret values, this computer's own, left out. */
-function readComparable(root: string, rel: string, base?: (path: string) => string | null): string | null {
+/**
+ * A working file as it compares with the workspace's: what is this
+ * computer's own left out (a Plugin's secret values, a model mapped in
+ * `sync.models`, multi-turn evaluation cases), and written as the
+ * workspace's or the base's text when it then says the same.
+ */
+function readComparable(root: string, rel: string, base?: (path: string) => string | null, remote?: string | null): string | null {
   const text = readLocal(root, rel)
-  return text === null ? null : comparableText(rel, text, isPluginFile(rel) ? (base?.(rel) ?? null) : null)
+  if (text === null) return null
+  if (isPluginFile(rel)) return comparableText(rel, text, base?.(rel) ?? null)
+  return comparablePortable(rel, text, projectModels(root), [remote, base?.(rel)])
 }
 
 /** Hash of the working files at these paths, or null when none of them exist. */
-function localHash(root: string, paths: string[], base?: (path: string) => string | null): string | null {
+function localHash(root: string, paths: string[], base?: (path: string) => string | null, remote: Record<string, string> = {}): string | null {
   const files: Record<string, string> = {}
   for (const p of paths) {
-    const content = readComparable(root, p, base)
+    const content = readComparable(root, p, base, remote[p])
     if (content !== null) files[p] = content
   }
   return Object.keys(files).length ? itemHash(files) : null
@@ -401,7 +410,7 @@ export function computePlan(root: string, remote: RemoteItem[], lock: SyncLock |
     seen.add(item.ref)
     const entry = lock?.items[item.ref]
     const paths = [...new Set([...Object.keys(item.files), ...Object.keys(entry?.files ?? {})])].sort((a, b) => (String(a) < String(b) ? -1 : String(a) > String(b) ? 1 : 0))
-    const files: FileChange[] = paths.map((path) => ({ path, local: readComparable(root, path, opts.base), remote: item.files[path] ?? null }))
+    const files: FileChange[] = paths.map((path) => ({ path, local: readComparable(root, path, opts.base, item.files[path] ?? null), remote: item.files[path] ?? null }))
     // An Agent's file that neither the base nor the workspace has but the folder does (its first tools, in a new
     // `bindings.json`) is a change here too, as push reads it: otherwise status says nothing while push proposes it.
     const added = item.kind === 'agent' ? AGENT_FILES.map((f) => `agents/${item.name}/${f}`).filter((p) => !paths.includes(p) && existsSync(join(root, p))) : []
@@ -409,7 +418,7 @@ export function computePlan(root: string, remote: RemoteItem[], lock: SyncLock |
     // The files as they stand over the base's paths, plus any path only the workspace has that is
     // already in the folder: a file the pull would overwrite counts as a change here.
     const basePaths = entry ? [...Object.keys(entry.files), ...files.filter((f) => !(f.path in entry.files) && f.local !== null).map((f) => f.path), ...added] : Object.keys(item.files)
-    const found = statusFor(entry?.remote ?? null, localHash(root, basePaths, opts.base), itemHash(item.files), matches) ?? 'same'
+    const found = statusFor(entry?.remote ?? null, localHash(root, basePaths, opts.base, item.files), itemHash(item.files), matches) ?? 'same'
     // Pulled with conflicts and not resolved: it stays so until `resolve`, whatever the files say.
     const status: ItemStatus = entry?.conflict && found !== 'same' ? 'unresolved' : found
     let merge: PlanItem['merge']
@@ -579,8 +588,9 @@ export function applyItems(root: string, workspace: string, items: RemoteItem[],
     for (const [path, remote] of Object.entries(item.files)) {
       const full = safePath(root, path)
       mkdirSync(dirname(full), { recursive: true })
-      // A Plugin's secret values set here stay: they are this computer's configuration.
-      const content = isPluginFile(path) ? withLocalSecrets(remote, readLocal(root, path)) : remote
+      // A Plugin's secret values set here stay: they are this computer's configuration. So do a mapped model and
+      // the multi-turn evaluation cases (`local-sync-portable.ts`).
+      const content = isPluginFile(path) ? withLocalSecrets(remote, readLocal(root, path)) : toLocal(path, remote, readLocal(root, path), projectModels(root), opts.base?.(path) ?? null)
       if (readLocal(root, path) !== content) {
         writeFileSync(full, content)
         written.push(path)

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

@@ -0,0 +1,269 @@
+import { isMap, isSeq, parseDocument, type Document } from 'yaml'
+
+import { deepEqual } from './local-sync-merge'
+
+/**
+ * What of a project file is this computer's only, and how the file reads in
+ * the workspace without it. Two things stay here:
+ *
+ *   this computer's model slugs   a model the workspace has under another slug is written as the
+ *                                 workspace's (matched by the provider's model id, `local-sync-models.ts`,
+ *                                 or `sync.models` in frontera.yaml). An Agent names models in agent.json
+ *                                 (`modelSlug`), a workflow as `model/<slug>`.
+ *   a model the workspace lacks   which model an Agent runs on is the workspace's choice: the Agent keeps
+ *                                 the workspace's model selection (its modes and default), a new Agent
+ *                                 takes the workspace's default, and the local model stays this computer's.
+ *   a multi-turn evaluation case  `frontera local test` runs a conversation of several turns; the workspace's
+ *                                 evaluation datasets hold single questions, so those cases stay in the file here.
+ *
+ * `toWorkspace` is the file as the workspace has it: what Propose sends, and
+ * what status and push compare with the workspace. `toLocal` is the
+ * workspace's file as a pull writes it here, with this computer's parts put
+ * back. Like a Plugin's secret values (`local-secrets.ts`), they never
+ * leave the folder and never read as a change.
+ */
+
+/** A local model slug and the workspace model it goes as, from `sync.models`. */
+export type ModelMap = Record<string, string>
+
+const AGENT_FILE = /^agents\/[^/]+\/agent\.json$/
+const WORKFLOW_FILE = /^workflows\/[^/]+\.ya?ml$/
+const EVAL_FILE = /^agents\/[^/]+\/evals\/[^/]+\.ya?ml$/
+
+const escape = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+
+/** Each slug in `text` swapped as `map` says, where the file names a model. */
+function swapModels(path: string, text: string, map: ModelMap): { text: string; swapped: Array<[string, string]> } {
+  const swapped: Array<[string, string]> = []
+  let out = text
+  for (const [from, to] of Object.entries(map)) {
+    if (!from || !to || from === to) continue
+    const pattern = AGENT_FILE.test(path)
+      ? new RegExp(`("modelSlug"\\s*:\\s*")${escape(from)}(")`, 'g')
+      : WORKFLOW_FILE.test(path)
+        ? new RegExp(`(\\bmodel/)${escape(from)}(?![\\w.-])()`, 'g')
+        : null
+    if (!pattern) continue
+    const next = out.replace(pattern, `$1${to}$2`)
+    if (next !== out) swapped.push([from, to])
+    out = next
+  }
+  return { text: out, swapped }
+}
+
+/** The workspace model each local one goes as, read the other way; a workspace model two local ones go as stays as it is. */
+function reversed(map: ModelMap): ModelMap {
+  const count = new Map<string, number>()
+  for (const to of Object.values(map)) count.set(to, (count.get(to) ?? 0) + 1)
+  return Object.fromEntries(Object.entries(map).filter(([, to]) => count.get(to) === 1).map(([from, to]) => [to, from]))
+}
+
+interface CaseNode {
+  toJSON(): unknown
+}
+
+/** An evaluation file's cases, each with whether it is a conversation of more than one turn. */
+function evaluationCases(doc: Document): Array<{ node: CaseNode; multiTurn: boolean; name: string | null; question: string | null }> {
+  const cases = doc.get('cases', true)
+  if (!isSeq(cases)) return []
+  return cases.items.map((node) => {
+    const value = (isMap(node) ? node.toJSON() : null) as { name?: unknown; conversation?: unknown; scenario?: unknown } | null
+    const turns = Array.isArray(value?.conversation) ? (value!.conversation as Array<{ user?: unknown }>) : []
+    return {
+      node: node as CaseNode,
+      multiTurn: value?.scenario === undefined && turns.length > 1,
+      name: typeof value?.name === 'string' ? value.name : null,
+      question: typeof turns[0]?.user === 'string' ? (turns[0]!.user as string).trim() : null,
+    }
+  })
+}
+
+export interface Portable {
+  text: string
+  /** Models swapped for the workspace's, as `[local, workspace]`. */
+  models: Array<[string, string]>
+  /** Evaluation cases that stay here (more than one turn), by name. */
+  keptHere: string[]
+  /** Models the workspace lacks that the file names here; the workspace keeps its own selection (`upstream`: its models, none for a new Agent). */
+  localModels?: { slugs: string[]; upstream: string[] }
+}
+
+/** What the workspace's models are, for the files that name models. */
+export interface ModelContext {
+  map?: ModelMap
+  /** The workspace's slugs; null or absent: unknown, so nothing is judged missing. */
+  workspace?: ReadonlySet<string> | null
+}
+
+interface AgentDoc {
+  config?: Record<string, unknown>
+  modelConfigs?: Array<Record<string, unknown>>
+  [key: string]: unknown
+}
+
+const slugsOf = (doc: AgentDoc | null) => (doc?.modelConfigs ?? []).flatMap((m) => (typeof m?.modelSlug === 'string' ? [m.modelSlug] : []))
+
+function parseAgent(text: string | null | undefined): AgentDoc | null {
+  if (!text) return null
+  try {
+    const doc = JSON.parse(text) as AgentDoc
+    return doc && typeof doc === 'object' && !Array.isArray(doc) ? doc : null
+  } catch {
+    return null
+  }
+}
+
+const agentText = (doc: AgentDoc) => `${JSON.stringify(doc, null, 2)}\n`
+
+/**
+ * An Agent naming a model the workspace lacks, as the workspace would have
+ * it: its model selection (modes and default) is the workspace's Agent's, or,
+ * for a new Agent, its modes on models the workspace has. Null when every
+ * model it names is the workspace's.
+ */
+function agentAsWorkspace(text: string, workspace: ReadonlySet<string>, upstream: string | null | undefined): { text: string; slugs: string[]; upstream: string[] } | null {
+  const doc = parseAgent(text)
+  if (!doc) return null
+  const missing = slugsOf(doc).filter((s) => !workspace.has(s))
+  if (!missing.length) return null
+  const theirs = parseAgent(upstream)
+  const config = { ...(doc.config ?? {}) }
+  let modelConfigs: Array<Record<string, unknown>>
+  if (theirs) {
+    modelConfigs = theirs.modelConfigs ?? []
+    if (theirs.config && 'defaultMode' in theirs.config) config.defaultMode = theirs.config.defaultMode
+    else delete config.defaultMode
+  } else {
+    modelConfigs = (doc.modelConfigs ?? []).filter((m) => !(typeof m?.modelSlug === 'string' && missing.includes(m.modelSlug)))
+    if (!modelConfigs.some((m) => m.modeKey === config.defaultMode)) config.defaultMode = (modelConfigs[0]?.modeKey as string | undefined) ?? null
+  }
+  return { text: agentText({ ...doc, config, modelConfigs }), slugs: missing, upstream: slugsOf({ modelConfigs }) }
+}
+
+/** The file as the workspace has it. Unchanged text when nothing in it is this computer's. */
+export function toWorkspace(path: string, text: string, models: ModelMap | ModelContext = {}, upstream?: string | null): Portable {
+  const ctx: ModelContext = 'map' in models || 'workspace' in models ? (models as ModelContext) : { map: models as ModelMap }
+  const map = ctx.map ?? {}
+  if (EVAL_FILE.test(path)) {
+    let doc: Document
+    try {
+      doc = parseDocument(text)
+    } catch {
+      return { text, models: [], keptHere: [] }
+    }
+    if (doc.errors.length) return { text, models: [], keptHere: [] }
+    const cases = evaluationCases(doc)
+    const kept = cases.filter((c) => c.multiTurn)
+    if (!kept.length) return { text, models: [], keptHere: [] }
+    const seq = doc.get('cases', true) as { items: unknown[] }
+    seq.items = seq.items.filter((_, i) => !cases[i]!.multiTurn)
+    return { text: doc.toString(), models: [], keptHere: kept.map((c) => c.name ?? `case ${cases.indexOf(c) + 1}`) }
+  }
+  const { text: swapped, swapped: done } = swapModels(path, text, map)
+  if (AGENT_FILE.test(path) && ctx.workspace) {
+    const local = agentAsWorkspace(swapped, ctx.workspace, upstream)
+    if (local) return { text: local.text, models: done, keptHere: [], localModels: { slugs: local.slugs, upstream: local.upstream } }
+  }
+  return { text: swapped, models: done, keptHere: [] }
+}
+
+/**
+ * The workspace's file as a pull writes it here: a model it names that this
+ * project maps is written as the local one, and the evaluation cases that
+ * stay here are kept after the workspace's. An Agent this computer runs on a
+ * model the workspace lacks keeps it while the workspace's model selection is
+ * as the last pull left it (`base`); one the workspace changed comes here.
+ */
+export function toLocal(path: string, remote: string, local: string | null, models: ModelMap | ModelContext = {}, base?: string | null): string {
+  const ctx: ModelContext = 'map' in models || 'workspace' in models ? (models as ModelContext) : { map: models as ModelMap }
+  const map = ctx.map ?? {}
+  if (EVAL_FILE.test(path)) {
+    if (local === null) return remote
+    let ours: Document
+    let theirs: Document
+    try {
+      ours = parseDocument(local)
+      theirs = parseDocument(remote)
+    } catch {
+      return remote
+    }
+    if (ours.errors.length || theirs.errors.length) return remote
+    const kept = evaluationCases(ours).filter((c) => c.multiTurn)
+    if (!kept.length) return remote
+    const present = evaluationCases(theirs)
+    const seq = theirs.get('cases', true)
+    if (!isSeq(seq)) return remote
+    for (const c of kept) {
+      // Already there (a merge kept it): not added twice.
+      if (present.some((p) => (c.name !== null && p.name === c.name) || deepEqual(p.node.toJSON(), c.node.toJSON()))) continue
+      seq.items.push(c.node as never)
+    }
+    return theirs.toString()
+  }
+  const written = swapModels(path, remote, reversed(map)).text
+  // An Agent this computer runs on a model the workspace lacks keeps it, while the workspace's selection is as it was.
+  if (AGENT_FILE.test(path) && local !== null && base && ctx.workspace) {
+    const ours = parseAgent(local)
+    const theirs = parseAgent(written)
+    const before = parseAgent(base)
+    const localOnly = agentAsWorkspace(swapModels(path, local, map).text, ctx.workspace, base)
+    if (ours && theirs && before && localOnly && deepEqual(before.modelConfigs ?? [], parseAgent(remote)?.modelConfigs ?? []) && deepEqual(before.config?.defaultMode ?? null, parseAgent(remote)?.config?.defaultMode ?? null)) {
+      return agentText({ ...theirs, config: { ...(theirs.config ?? {}), defaultMode: ours.config?.defaultMode ?? null }, modelConfigs: ours.modelConfigs ?? [] })
+    }
+  }
+  return written
+}
+
+/** Whether two versions of a file say the same document (key order and formatting aside). */
+export function sameDocumentText(path: string, a: string, b: string): boolean {
+  if (a === b) return true
+  try {
+    if (/\.json$/i.test(path)) return deepEqual(JSON.parse(a), JSON.parse(b))
+    if (/\.ya?ml$/i.test(path)) return deepEqual(parseDocument(a).toJS(), parseDocument(b).toJS())
+  } catch {
+    return false
+  }
+  return false
+}
+
+/**
+ * The file as it compares with the workspace: its workspace form, written as
+ * the workspace's or the base's text when it says the same, so this
+ * computer's parts and a re-serialized file never read as a change.
+ */
+export function comparablePortable(path: string, text: string, models: ModelMap | ModelContext, others: Array<string | null | undefined>): string {
+  // The workspace's text, else the base's: the upstream an Agent's model selection is kept from.
+  const portable = toWorkspace(path, text, models, others.find((o) => o != null) ?? null).text
+  if (portable === text) return text
+  for (const other of others) if (other != null && sameDocumentText(path, portable, other)) return other
+  return portable
+}
+
+/** What stays here of an item's files, in words, for Propose's notes. */
+export function portableNotes(files: Record<string, string>, models: ModelMap | ModelContext, names: Record<string, string> = {}, upstream: Record<string, string> = {}): string[] {
+  const notes: string[] = []
+  const swapped = new Map<string, string>()
+  for (const [path, text] of Object.entries(files)) {
+    const p = toWorkspace(path, text, models, upstream[path] ?? null)
+    for (const [from, to] of p.models) swapped.set(from, to)
+    if (p.localModels) {
+      const here = p.localModels.slugs.map((s) => names[s] ?? s).join(' and ')
+      const there = p.localModels.upstream.map((s) => names[s] ?? s)
+      notes.push(`Runs on ${here} here, a model the workspace doesn’t have: ${upstream[path] ? `the workspace keeps its own model selection${there.length ? ` (${there.join(', ')})` : ''}` : there.length ? `the workspace runs it on ${there.join(', ')}` : 'the workspace runs it on its default model'}`)
+    }
+    if (p.keptHere.length) {
+      const n = p.keptHere.length
+      notes.push(`${n} multi-turn case${n === 1 ? '' : 's'} stay${n === 1 ? 's' : ''} here (${p.keptHere.slice(0, 3).join(', ')}${n > 3 ? ', …' : ''}): the workspace’s evaluation datasets hold single questions, so \`frontera local test\` runs ${n === 1 ? 'it' : 'them'} on this computer only`)
+    }
+  }
+  for (const [from, to] of swapped) notes.push(`Uses ${from} here; the workspace has the same model as ${names[to] ?? to}`)
+  return notes
+}
+
+/** Every model slug a file names, as the workspace would read it: an Agent's `modelSlug`s and a workflow's `model/<slug>` references. */
+export function modelsNamed(path: string, text: string): string[] {
+  const out = new Set<string>()
+  if (AGENT_FILE.test(path)) for (const m of text.matchAll(/"modelSlug"\s*:\s*"([^"]+)"/g)) out.add(m[1]!)
+  else if (WORKFLOW_FILE.test(path)) for (const m of text.matchAll(/\bmodel\/([A-Za-z0-9][\w.-]*)/g)) out.add(m[1]!)
+  return [...out]
+}

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

@@ -0,0 +1,94 @@
+import { modelsNamed } from './local-sync-portable'
+import type { Check, PushItem } from './local-sync-push'
+
+/**
+ * What Propose knows before it is pressed, so an item the workspace would
+ * refuse is left out with its reason and its fix instead of refusing the
+ * whole request:
+ *
+ *   a model the workspace lacks   an item names a model only this computer has, and `sync.models`
+ *                                 maps it to none: choose the workspace model it goes as
+ *   the workspace's checks        the request's items sent to `POST /v1/change-requests/check`, which runs
+ *                                 the checks a proposal meets and records nothing (a Function without its
+ *                                 build: its manifest is checked when it is proposed)
+ *
+ * Pure: the platform call is the command's (`commands/local/sync-request.ts`).
+ */
+
+/** A model of the workspace's catalog, as `/v1/sync/models` lists it. */
+export interface WorkspaceModel {
+  slug: string
+  name: string
+  kind: string
+}
+
+/**
+ * Block each item that names a model the workspace lacks, and return those
+ * models (local slugs) with the items that name them. The files are already
+ * the workspace's form, so a mapped model reads as the workspace's.
+ */
+export function markMissingModels(items: PushItem[], workspace: ReadonlySet<string>): Map<string, string[]> {
+  const missing = new Map<string, string[]>()
+  for (const item of items) {
+    if (!item.proposable || item.change === 'deleted') continue
+    const named = [...new Set(Object.entries(item.files).flatMap(([path, text]) => modelsNamed(path, text)))].filter((slug) => !workspace.has(slug))
+    if (!named.length) continue
+    for (const slug of named) missing.set(slug, [...(missing.get(slug) ?? []), item.ref])
+    item.missingModels = named
+    Object.assign(item, {
+      proposable: false,
+      blocked: 'model',
+      reason: `Uses ${named.join(' and ')}, which the workspace doesn’t have`,
+      fix: `choose the workspace model it goes as (\`frontera local sync map-model ${named[0]} <workspace model>\`); it keeps using ${named.length === 1 ? 'it' : 'them'} here`,
+    })
+  }
+  return missing
+}
+
+/** The request's items as the check takes them: no Function build and no skill assets, which are made only when proposed. */
+export function checkBody(items: PushItem[]): Array<Record<string, unknown>> {
+  return items
+    .filter((i) => i.proposable)
+    .map((i) => ({
+      ref: i.ref,
+      ...(i.id ? { id: i.id } : {}),
+      ...(i.baseRevision ? { baseRevision: i.baseRevision } : {}),
+      files: i.files,
+      ...(i.change === 'deleted' ? { deleted: true } : {}),
+      ...(i.documents ? { documents: { upload: i.documents.upload.map(({ change: _change, ...d }) => d), remove: i.documents.remove } } : {}),
+    }))
+}
+
+/** What makes a refused item proposable, in words, by the check's code and message; null when only the file can say. */
+export function fixFor(check: Check): string | null {
+  const ref = check.ref
+  if (check.code === 'stale_base' || check.code === 'exists' || check.code === 'gone') return `pull it first (\`frontera local sync pull ${ref}\`), then propose`
+  if (check.code === 'unpublished_draft') return 'publish or discard its draft on the platform, then fetch and propose'
+  if (check.code === 'blueprint_backing') return 'leave it out: a dataset binding is set on the platform'
+  if (check.code === 'blueprint_draft') return 'publish or discard the Blueprint’s draft on the platform, then propose'
+  const model = /the model (\S+) is not in this workspace/.exec(check.message)
+  if (model) return `choose the workspace model it goes as (\`frontera local sync map-model ${model[1]} <workspace model>\`)`
+  if (check.code === 'unresolved') return 'propose what it names too, or create that in the workspace first'
+  return null
+}
+
+/** The message without the file it names, and the file: a row says why first. */
+export function splitCheckMessage(message: string): { why: string; file: string | null } {
+  const m = /^((?:agents|workflows|functions|skills|knowledge|blueprint|mcp|chat-apps|apps)\/[^:\s]+):\s+(.*)$/s.exec(message)
+  if (!m) return { why: message, file: null }
+  return { why: m[2]!.charAt(0).toUpperCase() + m[2]!.slice(1), file: m[1]! }
+}
+
+/** Block each item the workspace's checks would refuse, with the reason first and its fix. Returns the refs refused. */
+export function markRefused(items: PushItem[], checks: Check[]): string[] {
+  const byRef = new Map(items.map((i) => [i.ref, i]))
+  const refused: string[] = []
+  for (const check of checks) {
+    const item = byRef.get(check.ref)
+    if (!item || !item.proposable) continue
+    const { why, file } = splitCheckMessage(check.message)
+    Object.assign(item, { proposable: false, blocked: 'refused', reason: file ? `${why} (${file})` : why, fix: fixFor(check) })
+    refused.push(item.ref)
+  }
+  return refused
+}