@frontera-sdk/cli 1.52.43 → 1.52.45

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
+}

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

@@ -16,8 +16,11 @@ import { lessonsPath, lessonsProposal } from './local-lessons'
 import { importedFiles } from './local-function-shared'
 import { isIgnoredName } from './local-dev-sync'
 import { comparableText, withoutSecrets } from './local-secrets'
+import { projectModels } from './local-sync-models'
 import { deepEqual } from './local-sync-merge'
+import { portableNotes, sameDocumentText, toLocal, toWorkspace } from './local-sync-portable'
 import { itemTitle } from './local-sync-names'
+import { isScaffoldSample } from './local-scaffold'
 import { hash, itemHash, readLocal, safePath, writeLock, type LockEntry, type PlanItem, type RemoteItem, type SyncKind, type SyncLock } from './local-sync-plan'
 import { dropBase, SYNC_DIR, writeBase, type RemoteSnapshot } from './local-sync-snapshot'
 
@@ -55,8 +58,12 @@ const NOT_DELETED: Partial<Record<SyncKind, string>> = {
   lessons: 'An Agent’s rules are retired on the platform, where they are reviewed: a change request only proposes new ones',
 }
 
-/** Why an item cannot be proposed now. */
-export type BlockCode = 'moved' | 'conflicts' | 'deleted' | 'workspace-deleted' | 'kind' | 'shape'
+/**
+ * Why an item cannot be proposed now. `model`: it names a model the workspace
+ * lacks and `sync.models` maps to none; `refused`: the workspace's checks
+ * would refuse it (`POST /v1/change-requests/check`), said before proposing.
+ */
+export type BlockCode = 'moved' | 'conflicts' | 'deleted' | 'workspace-deleted' | 'kind' | 'shape' | 'model' | 'refused'
 
 /** A skill's file that is not text (an image, a font, a template): uploaded as a skill asset when proposed. */
 export interface PushAsset {
@@ -96,6 +103,15 @@ export interface PushItem {
   /** Why not, when it is not. */
   blocked: BlockCode | null
   reason: string | null
+  /** What makes it proposable, when something here can: the command or the choice. */
+  fix?: string | null
+  /**
+   * Still exactly the sample setting up the project wrote (`isScaffoldSample`):
+   * proposable, but left out unless named or ticked.
+   */
+  sample?: boolean
+  /** The models it names that the workspace lacks and `sync.models` maps to none, by local slug. */
+  missingModels?: string[]
   /** The platform's id, from the lock (or the snapshot). */
   id: string | null
   /** The revision the item was changed from; for a Blueprint file, the Blueprint's. */
@@ -165,7 +181,7 @@ function functionImports(root: string, entry: string): string[] {
  * service). The lock's paths that still exist come along, so nothing the
  * last pull wrote is left behind.
  */
-export function itemFiles(root: string, kind: SyncKind, name: string, entry?: LockEntry, opts: { documents?: boolean } = {}): { files: Record<string, string>; notes: string[]; problem?: string; assets?: string[] } {
+export function itemFiles(root: string, kind: SyncKind, name: string, entry?: LockEntry, opts: { documents?: boolean; upstream?: Record<string, string> } = {}): { files: Record<string, string>; notes: string[]; problem?: string; assets?: string[] } {
   const notes: string[] = []
   let paths: string[] = []
   const assets: string[] = []
@@ -228,6 +244,8 @@ export function itemFiles(root: string, kind: SyncKind, name: string, entry?: Lo
   // What the last pull wrote for it comes along when it is still here (an agent's files are fixed; the rest may not be).
   if (kind !== 'agent' && kind !== 'knowledge') for (const p of Object.keys(entry?.files ?? {})) if (!paths.includes(p)) paths.push(p)
   const files: Record<string, string> = {}
+  const here: Record<string, string> = {}
+  const models = projectModels(root)
   for (const path of [...new Set(paths)].sort((a, b) => (String(a) < String(b) ? -1 : String(a) > String(b) ? 1 : 0))) {
     if (path.endsWith('.workspace') || assets.includes(path)) continue
     const text = readLocal(root, path)
@@ -236,8 +254,13 @@ export function itemFiles(root: string, kind: SyncKind, name: string, entry?: Lo
       const clean = withoutSecrets(text)
       files[path] = clean.text
       notes.push(...clean.notes)
-    } else files[path] = text
+    } else {
+      // As the workspace will have it: a mapped model swapped, the multi-turn evaluation cases left here.
+      files[path] = toWorkspace(path, text, models, opts.upstream?.[path] ?? null).text
+      here[path] = text
+    }
   }
+  notes.push(...portableNotes(here, models, models.names, opts.upstream))
   return { files, notes, ...(kind === 'skill' ? { assets } : {}) }
 }
 
@@ -305,7 +328,7 @@ export interface CandidateInput {
   }
 }
 
-const BLOCK_REASON: Record<Exclude<BlockCode, 'kind' | 'shape'>, string> = {
+const BLOCK_REASON: Record<Exclude<BlockCode, 'kind' | 'shape' | 'model' | 'refused'>, string> = {
   moved: 'Changed in the workspace too since your last pull: pull and merge it first',
   conflicts: 'Has conflicts from a pull: resolve them first',
   deleted: 'Deleted here',
@@ -389,7 +412,7 @@ export function pushCandidates(input: CandidateInput): PushItem[] {
     if (status === 'new' || status === 'changed') continue
     const deleted = status === 'deleted-local'
     const bringDocuments = kind === 'knowledge' && !!input.documents?.names.has(name)
-    const { files, notes, problem, assets: assetPaths } = deleted ? { files: {} as Record<string, string>, notes: [] as string[], problem: undefined, assets: undefined } : itemFiles(root, kind, name, entry, { documents: bringDocuments })
+    const { files, notes, problem, assets: assetPaths } = deleted ? { files: {} as Record<string, string>, notes: [] as string[], problem: undefined, assets: undefined } : itemFiles(root, kind, name, entry, { documents: bringDocuments, ...(theirs ? { upstream: theirs.files } : {}) })
     // What a file hash does not cover: a skill's assets, and a knowledge base's documents when they are brought.
     const assetState = kind === 'skill' && !deleted && (assetPaths?.length || theirs?.assets?.length) ? skillAssets(root, name, assetPaths ?? [], theirs) : null
     const docs = bringDocuments && !deleted && input.documents
@@ -422,6 +445,10 @@ export function pushCandidates(input: CandidateInput): PushItem[] {
       base: baseFiles,
       notes,
     }
+    if (!deleted && isScaffoldSample(files)) {
+      item.sample = true
+      notes.push('A sample from setting up the project, not your work: it stays here unless you tick it (or name it to `frontera local sync push`)')
+    }
     if (assetState) {
       item.assets = assetState.assets
       for (const a of assetState.assets) if (a.change !== 'same') notes.push(`Asset ${a.path}: ${a.change === 'new' ? 'new' : 'changed'} (${kb(a.bytes)})`)
@@ -770,9 +797,20 @@ export function adoptApplied(root: string, workspace: string, refs: string[], re
     if (!item) continue
     for (const [path, text] of Object.entries(item.files)) {
       const here = readLocal(root, path)
-      if (here !== null && here !== text && sameDocument(path, here, text)) {
+      if (here === null || here === text) continue
+      if (sameDocument(path, here, text)) {
         writeFileSync(safePath(root, path), text)
         rewritten.push(path)
+        continue
+      }
+      // What the workspace now holds, with this computer's parts kept (a mapped model, the multi-turn cases).
+      const portable = toWorkspace(path, here, projectModels(root), text).text
+      if (portable !== here && (sameDocument(path, portable, text) || sameDocumentText(path, portable, text))) {
+        const local = toLocal(path, text, here, projectModels(root))
+        if (local !== here) {
+          writeFileSync(safePath(root, path), local)
+          rewritten.push(path)
+        }
       }
     }
     next.items[ref] = {

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

@@ -164,7 +164,8 @@ async function listActions(org: SyncClient): Promise<ActionRow[]> {
     const d = ((row as { definition?: unknown } | null)?.definition ?? row) as Partial<ActionRow> | null
     return d && typeof d.id === 'string' && typeof d.apiName === 'string' ? [{ id: d.id, apiName: d.apiName }] : []
   }
-  const draft = rows<unknown>(await org.get('/v1/blueprint/actions?view=draft')).flatMap(pick)
+  // An organization that has never published a Blueprint has no draft to read: no Actions (404).
+  const draft = rows<unknown>(await org.find('/v1/blueprint/actions?view=draft')).flatMap(pick)
   const published = rows<unknown>(await org.get('/v1/blueprint/actions').catch(() => null)).flatMap(pick)
   return [...new Map([...published, ...draft].map((a) => [a.id, a])).values()]
 }
@@ -191,8 +192,8 @@ export async function buildDirectory(source: SyncSource, warnings: string[] = []
     quietly(warnings, 'Blueprint object types', async () => rows<{ id: string; apiName: string }>(await ws.get('/v1/blueprint/object-types')), []),
     // The model catalog is organization-grain: a workspace key reads its names only, where the platform offers them.
     source.organization
-      ? quietly(warnings, 'Models', async () => rows<{ id: string; slug: string }>(await source.organization!.get('/v1/config/models/catalog')), [])
-      : quietly(warnings, 'Models', async () => rows<{ id: string; slug: string }>(await ws.find<unknown>('/v1/sync/models')), []),
+      ? quietly(warnings, 'Models', async () => rows<CatalogModelRow>(await source.organization!.get('/v1/config/models/catalog')), [])
+      : quietly(warnings, 'Models', async () => rows<CatalogModelRow>(await ws.find<unknown>('/v1/sync/models')), []),
     // So are governed Actions' definitions: without the organization key they are not listed.
     source.organization ? quietly<ActionRow[] | null>(warnings, 'Governed Actions', () => listActions(source.organization!), null) : Promise.resolve(null),
     // A platform without the route has none to name: absent, as for Actions.
@@ -221,7 +222,28 @@ export async function buildDirectory(source: SyncSource, warnings: string[] = []
     ...(objectSets ? { objectSet: new Map((objectSets ?? []).map((o) => [setNames.get(o.id)!, o.id])) } : {}),
     ...(objectDefinitions ? { object: new Map(objectDefinitions.map((o) => [o.slug, o.id])) } : {}),
   }
-  return { directory, lists: { agents, workflows, functions, knowledge, apps, skills, objectSets: objectSets ?? [], objectDefinitions } }
+  const catalog = models.map((m) => ({ slug: m.slug, name: m.name ?? m.slug, kind: m.kind ?? 'text', ...(m.provider ? { provider: m.provider } : {}), ...(m.modelId ? { modelId: m.modelId } : {}) }))
+  return { directory, lists: { agents, workflows, functions, knowledge, apps, skills, objectSets: objectSets ?? [], objectDefinitions, models: catalog } }
+}
+
+/** A model of the organization's catalog as the workspace lists it; the provider's model id tells two slugs for one model apart. */
+interface CatalogModelRow {
+  id: string
+  slug: string
+  name?: string
+  kind?: string
+  provider?: string
+  modelId?: string
+}
+
+/** A model of the workspace's catalog, kept with the snapshot: what a project's model can be matched against. */
+export interface WorkspaceCatalogModel {
+  slug: string
+  name: string
+  kind: string
+  provider?: string
+  /** The provider's id for it (`deepseek/deepseek-v4.1-flash`): the same model under another slug has the same one. */
+  modelId?: string
 }
 
 export interface Lists {
@@ -235,6 +257,8 @@ export interface Lists {
   objectSets?: ObjectSetRow[]
   /** The object definitions an Agent's object tools work on; null when the platform doesn't list them. */
   objectDefinitions?: ObjectDefinitionRow[] | null
+  /** The organization's model catalog, as far as the key reads it. */
+  models?: WorkspaceCatalogModel[]
 }
 
 export interface ReadOptions {
@@ -1251,7 +1275,13 @@ async function readBlueprint(
   // The workspace's grants beyond read, from its slice (the organization's model has none of a workspace's).
   let grants: RemoteItem | null = null
   if (mode === 'organization' && source.organization) {
-    const lifecycle = one<Lifecycle>(await source.organization.get('/v1/blueprint/lifecycle'))
+    // None (404) for an organization that has never published or drafted a Blueprint: nothing to pull.
+    const found = await source.organization.find<unknown>('/v1/blueprint/lifecycle')
+    if (!found) {
+      notes.push('The organization has no Blueprint yet; nothing was pulled into blueprint/')
+      return []
+    }
+    const lifecycle = one<Lifecycle>(found)
     fromDraft = !!lifecycle.draft?.definition && (!!opts.draft || !lifecycle.activeRelease?.definition)
     answer = { definition: (fromDraft ? lifecycle.draft?.definition : lifecycle.activeRelease?.definition) ?? null, datasetNames: await datasetNames(source.organization) }
     if (fromDraft) notes.push(opts.draft ? 'The Blueprint was read from its unpublished draft, as asked' : 'The Blueprint has no published release; its draft was read')
@@ -1270,7 +1300,8 @@ async function readBlueprint(
     if (opts.draft && !source.organization) notes.push('Reading the Blueprint’s unpublished draft takes an organization key; its published release was read')
     if (opts.draft && source.organization && answer) {
       // The draft, cut to the object types the workspace's slice holds now.
-      const lifecycle = one<Lifecycle>(await source.organization.get('/v1/blueprint/lifecycle'))
+      const found = await source.organization.find<unknown>('/v1/blueprint/lifecycle')
+      const lifecycle = found ? one<Lifecycle>(found) : ({} as Lifecycle)
       const granted = new Set(((answer.definition as { objects?: Array<{ apiName: string }> } | null)?.objects ?? []).map((o) => o.apiName))
       if (lifecycle.draft?.definition) {
         answer = { definition: sliceDraft(lifecycle.draft.definition, granted), datasetNames: { ...(answer.datasetNames ?? {}), ...(await datasetNames(source.organization)) } }
@@ -1606,7 +1637,7 @@ async function readEvaluations(source: SyncSource, lists: Lists, directory: Dire
  * collects what could not be read (a kind the key may not see, a platform
  * too old for an export), so the plan says so instead of failing.
  */
-export async function readWorkspace(source: SyncSource, opts: ReadOptions = {}): Promise<{ items: RemoteItem[]; warnings: string[]; notes: string[]; directory: Directory }> {
+export async function readWorkspace(source: SyncSource, opts: ReadOptions = {}): Promise<{ items: RemoteItem[]; warnings: string[]; notes: string[]; directory: Directory; models: WorkspaceCatalogModel[] }> {
   const warnings: string[] = []
   const notes: string[] = []
   const { directory, lists } = await buildDirectory(source, warnings)
@@ -1694,7 +1725,7 @@ export async function readWorkspace(source: SyncSource, opts: ReadOptions = {}):
       ? 'Governed Actions are named only with an organization key (they are organization-wide); an Action step shows as an id until you connect one'
       : 'Models and governed Actions are named only with an organization key (both are organization-wide); an LLM step’s model or an Action step shows as an id until you connect one')
   }
-  return { items, warnings, notes, directory }
+  return { items, warnings, notes, directory, models: lists.models ?? [] }
 }
 
 /**

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

@@ -7,7 +7,7 @@ import { writeFileAtomic } from '../fs-atomic'
 import { hash, itemHash, safePath, SYNC_KINDS, type RemoteItem, type SyncKind, type SyncLock } from './local-sync-plan'
 import { readOrgSettings, type OrgSettings } from './local-org-settings'
 import type { Portability } from './local-portability'
-import { readWorkspace, type SyncSource } from './local-sync-remote'
+import { readWorkspace, type SyncSource, type WorkspaceCatalogModel } from './local-sync-remote'
 import { REF_KINDS, type Directory, type RefKind, type Unresolved } from './local-sync-refs'
 
 /**
@@ -86,6 +86,12 @@ export interface RemoteSnapshot {
    * now written `action/resetLine`) from a change.
    */
   names?: Partial<Record<RefKind, Record<string, string>>>
+  /**
+   * The organization's model catalog as of the last read, with each model's
+   * provider id, so a model this computer names under another slug is known
+   * as the workspace's (`local-sync-models.ts`).
+   */
+  models?: WorkspaceCatalogModel[]
   /**
    * Read with an organization key as well: it brings governed Actions (and,
    * for older platforms, the Blueprint). A snapshot read with other keys is
@@ -423,6 +429,7 @@ export async function fetchWorkspace(root: string, source: SyncSource, opts: Fet
       warnings: read.warnings,
       notes: read.notes,
       names: namesOf(read.directory),
+      ...(read.models.length ? { models: read.models } : {}),
       organizationKey: !!source.organization,
       reader: SNAPSHOT_READER,
       ...(settings ? { settings } : {}),
@@ -522,6 +529,7 @@ export async function fetchWorkspace(root: string, source: SyncSource, opts: Fet
     warnings: read?.warnings ?? [],
     notes: read ? read.notes : previous?.notes ?? [],
     ...(read ? { names: namesOf(read.directory) } : previous?.names ? { names: previous.names } : {}),
+    ...(read?.models.length ? { models: read.models } : previous?.models ? { models: previous.models } : {}),
     organizationKey: !!source.organization,
     reader: SNAPSHOT_READER,
     ...(settings ? { settings } : previous?.settings ? { settings: previous.settings } : {}),