@frontera-sdk/cli 1.52.43 → 1.52.45

package/src/local/local-scaffold.ts

@@ -587,6 +587,53 @@ export function ensureProjectBunfig(root: string): boolean {
   return true
 }
 
+/** The example Agent, workflow, Function, evaluation and object type, with the sample dataset they use. */
+function sampleFiles(name: string, agentModel?: string): Record<string, string> {
+  return {
+    'agents/assistant/agent.json': AGENT(name, agentModel),
+    'agents/assistant/operating.json': OPERATING,
+    'agents/assistant/bindings.json': BINDINGS,
+    'agents/assistant/evals/regression.yaml': EVALS,
+    'workflows/hello.yaml': WORKFLOW,
+    'workflows/tests/hello.yaml': WORKFLOW_TESTS,
+    'functions/word-count.ts': FUNCTION,
+    'functions/word-count.test.ts': FUNCTION_TEST,
+    'datasets/tickets.json': DATASET,
+    'datasets/tickets.csv': DATASET_ROWS,
+    'blueprint/object-types/Ticket.yaml': OBJECT_TYPE,
+  }
+}
+
+/** The sample Agent as compared: its model and the project's name in its description are set per project. */
+function sampleAgent(text: string): unknown {
+  try {
+    const doc = JSON.parse(text) as { config?: Record<string, unknown>; modelConfigs?: unknown }
+    const { description: _description, defaultMode: _defaultMode, ...config } = doc.config ?? {}
+    const { modelConfigs: _models, ...rest } = doc
+    return { ...rest, config }
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Whether an item's files are still exactly what setting up the project wrote
+ * for its sample: the example, not the project's own work, so a linked
+ * project does not propose it by default: the sample Ticket type would
+ * otherwise overwrite a workspace's own. Edited, it is the project's.
+ */
+export function isScaffoldSample(files: Record<string, string>): boolean {
+  const sample = sampleFiles('')
+  const paths = Object.keys(files)
+  if (!paths.length) return false
+  return paths.every((path) => {
+    const expected = sample[path]
+    if (expected === undefined) return false
+    if (path === 'agents/assistant/agent.json') return JSON.stringify(sampleAgent(files[path]!)) === JSON.stringify(sampleAgent(expected))
+    return files[path] === expected
+  })
+}
+
 /** `samples: false` leaves out the example Agent, workflow, Function and object type: a project started from a workspace gets the workspace's own. */
 export function solutionScaffoldFiles(name: string, opts: { agentModel?: string; samples?: boolean } = {}): Record<string, string> {
   const sdk = vendored.files as Record<string, string>
@@ -610,19 +657,7 @@ export function solutionScaffoldFiles(name: string, opts: { agentModel?: string;
   out['.codex/config.toml'] = CODEX_MCP_TOML
   out['fixtures/README.md'] = FIXTURES_README
   out['bunfig.toml'] = PROJECT_BUNFIG
-  if (opts.samples !== false) {
-    out['agents/assistant/agent.json'] = AGENT(name, opts.agentModel)
-    out['agents/assistant/operating.json'] = OPERATING
-    out['agents/assistant/bindings.json'] = BINDINGS
-    out['agents/assistant/evals/regression.yaml'] = EVALS
-    out['workflows/hello.yaml'] = WORKFLOW
-    out['workflows/tests/hello.yaml'] = WORKFLOW_TESTS
-    out['functions/word-count.ts'] = FUNCTION
-    out['functions/word-count.test.ts'] = FUNCTION_TEST
-    out['datasets/tickets.json'] = DATASET
-    out['datasets/tickets.csv'] = DATASET_ROWS
-    out['blueprint/object-types/Ticket.yaml'] = OBJECT_TYPE
-  }
+  if (opts.samples !== false) Object.assign(out, sampleFiles(name, opts.agentModel))
   out['package.json'] =
     JSON.stringify(
       {

package/src/local/local-schemas.ts

@@ -134,7 +134,7 @@ const EVALS_SCHEMA: JsonSchema = {
           conversation: {
             type: 'array',
             minItems: 1,
-            description: 'One turn per item. Only the user turns are sent, in order, each as soon as the reply before it ends; an assistant turn is kept for whoever reads the case. `waitSeconds` on a user turn keeps a gap before it (`- { user: "Still there?", waitSeconds: 60 }` sends it a minute after the reply before).',
+            description: 'One turn per item. Only the user turns are sent, in order, each as soon as the reply before it ends; an assistant turn is kept for whoever reads the case. `waitSeconds` on a user turn keeps a gap before it (`- { user: "Still there?", waitSeconds: 60 }` sends it a minute after the reply before). A case of more than one turn runs on this computer only: the workspace\'s evaluation datasets hold single questions, so `frontera local sync push` proposes the file\'s single-question cases and keeps the rest here.',
             items: {
               type: 'object',
               properties: {

package/src/local/local-seed.ts

@@ -166,7 +166,7 @@ export async function seedLocalRuntime(args: SeedArgs): Promise<LocalCredentials
 }
 
 /** Provider ids the service stores as organization credentials, each with an `apiKey` field. */
-const CREDENTIAL_PROVIDERS = new Set(['anthropic', 'openai', 'openrouter', 'google'])
+const CREDENTIAL_PROVIDERS = new Set(['anthropic', 'openai', 'openrouter', 'google', 'openrouter-web-search'])
 
 /** Embedding defaults by provider, in preference order; the service requires 1536-wide vectors. */
 const EMBEDDING: Array<{ provider: string; model: string }> = [

package/src/local/local-studio-server.ts

@@ -299,7 +299,7 @@ export function startStudioServer(opts: StudioServerOptions) {
         if (!(file instanceof Blob)) return json({ error: 'send the document as the multipart field "file"' }, 400)
         const name = checkUpload((file as File).name ?? '', file.size)
         const replace = url.searchParams.get('replace') === '1'
-        // Replacing: the runtime's copy goes first, so the apply uploads the new content (it only adds what the runtime lacks).
+        // Replacing: the runtime's copy goes first, so the apply uploads the new content as a document the runtime lacks.
         if (replace && id && documentInFolder(project.root, folder, name)) {
           const call = serviceCall()
           if (call) {
@@ -386,14 +386,20 @@ export function startStudioServer(opts: StudioServerOptions) {
     if (state?.credentials?.workspaceId && !headers.has('x-workspace-id')) {
       headers.set('x-workspace-id', state.credentials.workspaceId)
     }
+    // A page sends the session token it kept (`bearer_token`) itself. After
+    // `frontera local reset` that session is gone, so a session the service
+    // refuses is answered as the owner; an API key or a signed token is not.
+    const kept = headers.get('authorization')?.match(/^Bearer ([A-Za-z0-9]{32})$/)?.[1]
+    const fallback = kept && bearer && kept !== bearer ? bearer : null
+    const hasBody = req.method !== 'GET' && req.method !== 'HEAD'
+    const body = hasBody && fallback ? await req.arrayBuffer() : hasBody ? req.body : undefined
     try {
-      const res = await fetch(target, {
-        method: req.method,
-        headers,
-        body: req.method === 'GET' || req.method === 'HEAD' ? undefined : req.body,
-        redirect: 'manual',
-        duplex: 'half',
-      })
+      const send = () => fetch(target, { method: req.method, headers, body, redirect: 'manual', duplex: 'half' })
+      let res = await send()
+      if (res.status === 401 && fallback) {
+        headers.set('authorization', `Bearer ${fallback}`)
+        res = await send()
+      }
       const out = new Headers(res.headers)
       out.delete('content-encoding')
       out.delete('content-length')

package/src/local/local-supervisor.ts

@@ -32,6 +32,7 @@ import {
   type LocalConfig,
   type LocalSecrets,
 } from './local-env'
+import { runtimeKeyCustodianProblem } from './local-key-custodian'
 import { localEmbeddingsReachable, providerEnv } from './local-keys'
 import { applyProviderSetup, readProviderSetup, rememberSlugs, writeProviderSetup } from './local-providers'
 import type { PortBlock } from './local-ports'
@@ -484,6 +485,7 @@ async function startService(
     running.children.set('service', child)
     const ok = await waitForHttp(`http://127.0.0.1:${ports.service}/health`, 120_000, () => child.exitCode === null)
     if (!ok) throw new Error('the service did not become healthy; see `frontera local logs service`')
+    await refuseBrokenKeyCustodian(ports)
     set('service', { status: 'running', pid: child.pid, startedAt: new Date().toISOString() })
     keepDocs(project, { bundle: customerDocsBundle(config.platformSource) }, log)
     refreshCheckoutDocs(project, config.platformSource, log)
@@ -508,10 +510,21 @@ async function startService(
   followLogs(name, log)
   const ok = await waitForHttp(`http://127.0.0.1:${ports.service}/health`, 180_000)
   if (!ok) throw new Error('the service did not become healthy; see `frontera local logs service`')
+  await refuseBrokenKeyCustodian(ports)
   set('service', { status: 'running', container: name, startedAt: new Date().toISOString() })
   keepDocs(project, { fromContainer: (dest) => copyFromContainer(name, IMAGE_DOCS_PATH, dest) }, log)
 }
 
+/**
+ * A service whose encryption keys can't be read fails every secret and
+ * governed Action record later with a 500: the start stops here instead, with
+ * the fix (`local-key-custodian.ts`).
+ */
+async function refuseBrokenKeyCustodian(ports: PortBlock): Promise<void> {
+  const problem = await runtimeKeyCustodianProblem(`http://127.0.0.1:${ports.service}`)
+  if (problem) throw new Error(problem)
+}
+
 /** The release's documentation, for the solution's coding agents (`frontera mcp`). */
 function keepDocs(project: LocalProject, from: { bundle?: string | null; fromContainer?: (dest: string) => boolean }, log: string): void {
   if (!from.bundle && !from.fromContainer) {

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

@@ -1,5 +1,5 @@
 import { spawnSync } from 'node:child_process'
-import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { existsSync, readFileSync, statSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
 
 import { parseDocument } from 'yaml'
@@ -28,6 +28,11 @@ export interface SyncLink {
   /** Names shown in Forge and `sync status`; refreshed on connect. */
   workspaceName?: string
   organizationName?: string
+  /**
+   * A model this computer names (a local provider's, by catalog slug) and the
+   * workspace's model it goes as when proposed (`local-sync-portable.ts`).
+   */
+  models?: Record<string, string>
 }
 
 export function projectFile(root: string): string {
@@ -40,6 +45,9 @@ export function readLink(root: string): SyncLink | null {
   const doc = parseDocument(readFileSync(file, 'utf8')).toJS() as { sync?: Partial<SyncLink> } | null
   const s = doc?.sync
   if (!s || typeof s.platform !== 'string' || typeof s.workspace !== 'string') return null
+  const models = s.models && typeof s.models === 'object' && !Array.isArray(s.models)
+    ? Object.fromEntries(Object.entries(s.models as Record<string, unknown>).filter((e): e is [string, string] => typeof e[1] === 'string' && !!e[0] && !!e[1]))
+    : {}
   return {
     platform: s.platform,
     workspace: s.workspace,
@@ -47,9 +55,41 @@ export function readLink(root: string): SyncLink | null {
     blueprint: s.blueprint === 'organization' ? 'organization' : 'workspace',
     workspaceName: typeof s.workspaceName === 'string' ? s.workspaceName : undefined,
     organizationName: typeof s.organizationName === 'string' ? s.organizationName : undefined,
+    ...(Object.keys(models).length ? { models } : {}),
   }
 }
 
+const mapped = new Map<string, { mtimeMs: number; models: Record<string, string> }>()
+
+/** The project's model mapping (`sync.models`), empty when it has none or no link; read once per change of the file. */
+export function modelMap(root: string): Record<string, string> {
+  const file = projectFile(root)
+  let mtimeMs = -1
+  try {
+    mtimeMs = statSync(file).mtimeMs
+  } catch {
+    return {}
+  }
+  const known = mapped.get(file)
+  if (known && known.mtimeMs === mtimeMs) return known.models
+  const models = readLink(root)?.models ?? {}
+  mapped.set(file, { mtimeMs, models })
+  return models
+}
+
+/** Map a local model to a workspace model when proposed, or (`workspace` null) stop mapping it. */
+export function setModelMapping(root: string, local: string, workspace: string | null): SyncLink {
+  const link = readLink(root)
+  if (!link) throw new Error('the project is not linked to a workspace')
+  const models = { ...(link.models ?? {}) }
+  if (workspace) models[local] = workspace
+  else delete models[local]
+  const next: SyncLink = { ...link, models }
+  if (!Object.keys(models).length) delete next.models
+  writeLink(root, next)
+  return next
+}
+
 /** Write the link into `frontera.yaml`, keeping the rest of the file and its comments. */
 export function writeLink(root: string, link: SyncLink | null): void {
   const file = projectFile(root)
@@ -58,11 +98,12 @@ export function writeLink(root: string, link: SyncLink | null): void {
   if (!link) {
     doc.delete('sync')
   } else {
-    const value: Record<string, string> = { platform: link.platform, workspace: link.workspace }
+    const value: Record<string, unknown> = { platform: link.platform, workspace: link.workspace }
     if (link.workspaceName) value.workspaceName = link.workspaceName
     if (link.organization) value.organization = link.organization
     if (link.organizationName) value.organizationName = link.organizationName
     value.blueprint = link.blueprint
+    if (link.models && Object.keys(link.models).length) value.models = link.models
     const existing = doc.get('sync', true) as { commentBefore?: string } | undefined
     const node = doc.createNode(value) as unknown as { commentBefore?: string }
     node.commentBefore = existing?.commentBefore ?? ' The platform workspace this project pulls from (`frontera local sync`). Keys are in your keychain, not here.'

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)