@frontera-sdk/cli 1.52.39 → 1.52.41

package/src/local/local-empty-workflows.ts

@@ -0,0 +1,92 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { parse as parseYaml } from 'yaml'
+
+import { allTargets } from './local-dev-sync'
+import { readSnapshot } from './local-sync-snapshot'
+
+/**
+ * Workflows with no steps. One applies (the runtime takes an empty workflow
+ * as written) and every surface would mark it Applied, but a run does
+ * nothing: a placeholder made in Studio and never filled in, or a pull of
+ * one. Said as a warning beside its state, with what fixes it, by
+ * `local status`, `local dev`, Forge's home and Activity alike.
+ */
+export function emptyWorkflows(root: string): string[] {
+  const slugs = new Set<string>()
+  for (const target of allTargets(root)) {
+    if (target.kind !== 'workflow') continue
+    try {
+      const text = readFileSync(join(root, target.file), 'utf8')
+      const doc = (target.file.endsWith('.json') ? JSON.parse(text) : parseYaml(text)) as { nodes?: unknown; steps?: unknown } | null
+      if (!doc || typeof doc !== 'object') continue
+      const steps = doc.nodes ?? doc.steps
+      if (steps === undefined || steps === null || (Array.isArray(steps) && steps.length === 0)) slugs.add(target.slug)
+    } catch {
+      // A file that doesn't parse fails its apply, which says why.
+    }
+  }
+  return [...slugs].sort()
+}
+
+/**
+ * The workflows of the workspace this project was pulled from, as its pull
+ * index (`.frontera/sync/remote.json`) knows them at the last fetch: how
+ * many it has (archived ones aside) and which are not in the project. Null
+ * when there is no index, or it never read workflows: then nothing is said.
+ */
+export interface WorkspaceWorkflows {
+  total: number
+  pulled: number
+  /** How many workflows the project holds now, pulled or made here: the count its home lists. */
+  here: number
+  /** Listed by the index without their file here, by slug; with no definition to file (`empty`) or not pulled. */
+  notHere: Array<{ slug: string; why: 'not-pulled' | 'no-definition' }>
+  fetchedAt: string
+}
+
+export function workspaceWorkflows(root: string): WorkspaceWorkflows | null {
+  const snap = readSnapshot(root)
+  if (!snap || !snap.kinds?.includes('workflow')) return null
+  const notHere: WorkspaceWorkflows['notHere'] = []
+  let pulled = 0
+  for (const [ref, item] of Object.entries(snap.items)) {
+    if (item.kind !== 'workflow') continue
+    if (item.files.length && item.files.every((f) => existsSync(join(root, f)))) pulled++
+    else notHere.push({ slug: ref.replace(/^workflow\//, ''), why: 'not-pulled' })
+  }
+  for (const ref of Object.keys(snap.skipped ?? {})) if (ref.startsWith('workflow/') && !snap.items[ref]) notHere.push({ slug: ref.slice('workflow/'.length), why: 'no-definition' })
+  const here = Math.max(pulled, new Set(allTargets(root).filter((t) => t.kind === 'workflow').map((t) => t.slug)).size)
+  return { total: pulled + notHere.length, pulled, here, notHere: notHere.sort((a, b) => a.slug.localeCompare(b.slug)), fetchedAt: snap.fetchedAt }
+}
+
+/**
+ * Where the project's workflows came from, counted from the project's side so
+ * the number matches the home's ("Workflows 2"): "1 of this project's 2
+ * workflows came from the workspace it was pulled from (at the last fetch,
+ * …); the other was made here, and the workspace has no other workflow to
+ * pull." Run 8 read "has 1 workflow …; 1 is in this project" as a wrong count
+ * beside a home listing 2.
+ */
+export function workspaceWorkflowsWords(w: WorkspaceWorkflows): string {
+  const fetched = `(at the last fetch, ${w.fetchedAt.slice(0, 10)})`
+  const made = w.here - w.pulled
+  const from = 'came from the workspace it was pulled from'
+  const lead =
+    w.pulled === w.here
+      ? `${w.here === 1 ? 'This project’s workflow' : `All ${w.here} of this project’s workflows`} ${from} ${fetched}`
+      : `${w.pulled === 0 ? 'None' : w.pulled} of this project’s ${w.here} workflows ${from} ${fetched}; ${made === 1 ? 'the other was' : `the other ${made} were`} made here`
+  if (!w.notHere.length) return `${lead}, and the workspace has no other workflow to pull.`
+  const notPulled = w.notHere.filter((n) => n.why === 'not-pulled').map((n) => n.slug)
+  const empty = w.notHere.filter((n) => n.why === 'no-definition').map((n) => n.slug)
+  return `${lead}. ${[
+    notPulled.length ? `Not pulled from the workspace: ${notPulled.join(', ')} (\`frontera local sync pull ${notPulled.map((s) => `workflow/${s}`).join(' ')}\` brings ${notPulled.length === 1 ? 'it' : 'them'})` : '',
+    empty.length ? `${notPulled.length ? 'listed' : 'Listed'} there without a definition to file: ${empty.join(', ')}` : '',
+  ].filter(Boolean).join('; ')}.`
+}
+
+/** The warning for one, as a row's warning line: "workflow/x: … Fix: …", with the workspace's other workflows when the pull index knows them. */
+export function emptyWorkflowLine(slug: string, workspace: WorkspaceWorkflows | null = null): string {
+  return `workflow/${slug}: has no steps, so it does nothing when it runs. Fix: add its steps (Studio's Workflows page, or nodes: in its file under workflows/), or delete the file if it is a placeholder${workspace ? `. ${workspaceWorkflowsWords(workspace)}` : ''}`
+}

package/src/local/local-env.ts

@@ -135,7 +135,7 @@ export function serviceEnv(args: {
   runnerEnabled: boolean
   jobsEnabled: boolean
   storageEnabled: boolean
-  /** Embed with the keyless local embeddings (no OpenAI or OpenRouter key stored). */
+  /** Point the service's OpenAI client at the keyless local embeddings (no OpenAI key stored). */
   keylessEmbeddings?: boolean
   /** The customer documentation publication the service serves to coding agents. */
   documentationBundle?: string | null
@@ -145,6 +145,8 @@ export function serviceEnv(args: {
   const studio = `http://127.0.0.1:${ports.studio}`
   const env: Record<string, string> = {
     NODE_ENV: 'development',
+    // A local runtime: the service admits exact loopback origins (a Custom App's dev server on any port).
+    FRONTERA_LOCAL_RUNTIME: '1',
     PORT: String(ports.service),
     DATABASE_URL: databaseUrl(secrets, ports),
     AGENT_CONFIG_REDIS_URL: `redis://127.0.0.1:${ports.cache}`,
@@ -164,9 +166,22 @@ export function serviceEnv(args: {
     FUNCTIONS_ALLOW_LOCAL_HTTP: '1',
     // Every local Agent is a draft: a Chat App's draft preview offers them, each run on its draft.
     CHAT_APP_PREVIEW_DRAFT_AGENTS: '1',
+    // App previews load from this machine (`*.localhost` is loopback), never a public domain a
+    // checkout's own .env.local names; the empty values switch the public address zones off.
+    APPS_WILDCARD_DOMAIN: `http://apps.localhost:${ports.service}`,
+    APPS_ADDRESS_ZONE: '',
+    CHAT_APPS_ADDRESS_ZONE: '',
+    SITES_WILDCARD_DOMAIN: '',
     // So are the MCP servers an FDE is building: the operator's exemption from
     // the private-address rule, and on a laptop the FDE is the operator.
     MCP_ALLOWED_PRIVATE_HOSTS: `127.0.0.1,localhost,${HOST_FROM_CONTAINER}`,
+    // No Agent computer: a checkout's .env can name a Daytona account (the service loads it from
+    // its directory), and Agents here would run bash, files and a browser on that remote machine
+    // while `local status` says they have none. Empty values win over the file; a release image
+    // has none either.
+    DAYTONA_API_KEY: '',
+    DAYTONA_API_URL: '',
+    DAYTONA_TARGET: '',
     // Traces go to the runtime's own local traces, read back by Studio.
     LANGFUSE_BASE_URL: `http://127.0.0.1:${ports.traces}`,
     LANGFUSE_PUBLIC_KEY: LOCAL_TRACE_KEYS.publicKey,

package/src/local/local-file-checks.ts

@@ -0,0 +1,104 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import matter from 'gray-matter'
+
+import { checkAgainstSchema, type SchemaProblem } from './local-schema-check'
+import { cliSchema, type SchemaKind } from './local-schemas'
+
+/**
+ * A Chat App file, a knowledge base's `knowledge.json` and a skill's
+ * `SKILL.md` front matter, checked against `frontera local schema <kind>`
+ * before `local dev` applies them.
+ *
+ * The platform keeps only the keys it knows and drops the rest without a word
+ * (a Chat App's `experience` block applied "✓" and was gone), so a key the
+ * format does not have is a warning that says it was left out. A value of the
+ * wrong shape (`roster.agents.0.agent` where `agentConfigId` belongs) is an
+ * error with its path, refused before the call rather than after it as a bare
+ * "Invalid configuration".
+ */
+
+export interface FileChecks {
+  errors: string[]
+  warnings: string[]
+}
+
+const UNKNOWN_KEY = /^`([^`]+)` is not a key this file takes/
+
+/** Split schema problems: an unknown key is left out (a warning); anything else is refused. */
+export function splitProblems(file: string, problems: SchemaProblem[], what: string): FileChecks {
+  const errors: string[] = []
+  const warnings: string[] = []
+  for (const p of problems) {
+    const unknown = UNKNOWN_KEY.exec(p.message)
+    if (unknown) {
+      const takes = /\(it takes (.*)\)$/.exec(p.message)?.[1]
+      warnings.push(`  warning: ${file} ${p.path}: ${what} has no \`${unknown[1]}\`, so it is left out${takes ? ` (it takes ${takes})` : ''}`)
+    } else errors.push(`${file} ${p.path || '(the file)'}: ${p.message}`)
+  }
+  return { errors, warnings }
+}
+
+function check(kind: SchemaKind, file: string, doc: unknown, what: string): FileChecks {
+  const schema = cliSchema(kind)
+  if (!schema) return { errors: [], warnings: [] }
+  return splitProblems(file, checkAgainstSchema(doc, schema), what)
+}
+
+/** A Chat App document (`chat-apps/<slug>.json`). */
+export function chatAppFileChecks(file: string, doc: unknown): FileChecks {
+  return check('chat-app', file, doc, 'a Chat App')
+}
+
+/**
+ * A knowledge base's file. Unlike a Chat App's, nothing in it is refused
+ * here: `local dev` sends only the settings it knows, so a wrong value is a
+ * warning and the platform's answer decides.
+ */
+export function knowledgeFileChecks(file: string, doc: unknown): FileChecks {
+  const { errors, warnings } = check('knowledge', file, doc, 'knowledge.json')
+  return { errors: [], warnings: [...warnings, ...errors.map((e) => `  warning: ${e}`)] }
+}
+
+/** A skill's front matter. A missing name refuses the push (it is the skill's identity); the rest are warnings. */
+export function skillFileChecks(file: string, text: string): FileChecks {
+  let data: Record<string, unknown>
+  try {
+    data = matter(text).data as Record<string, unknown>
+  } catch (err) {
+    return { errors: [`${file}: its front matter is not valid YAML: ${(err as Error).message}`], warnings: [] }
+  }
+  const schema = cliSchema('skill')!
+  const known = Object.keys((schema.properties ?? {}) as Record<string, unknown>)
+  const warnings = Object.keys(data)
+    .filter((k) => !known.includes(k))
+    .map((k) => `  warning: ${file}: the front matter has no \`${k}\`, so it is ignored (it takes ${known.map((n) => `\`${n}\``).join(', ')})`)
+  const errors: string[] = []
+  for (const p of checkAgainstSchema(data, schema)) {
+    if (p.message.includes('`name` is required')) errors.push(`${file}: its front matter needs \`name\`: the skill's identity, what agent.json binds as skill/<name>`)
+    else warnings.push(`  warning: ${file} ${p.path || 'front matter'}: ${p.message}`)
+  }
+  return { errors, warnings }
+}
+
+/** The checks for one target's file, read from the project; nothing for a kind these do not cover. */
+export function projectFileChecks(root: string, target: { kind: string; file?: string }): FileChecks {
+  const none = { errors: [], warnings: [] }
+  if (!target.file || !['chat-app', 'knowledge', 'skill'].includes(target.kind)) return none
+  let text: string
+  try {
+    text = readFileSync(join(root, target.file), 'utf8')
+  } catch {
+    return none
+  }
+  if (target.kind === 'skill') return skillFileChecks(target.file, text)
+  let doc: unknown
+  try {
+    doc = JSON.parse(text)
+  } catch {
+    // Unreadable: the apply says so with the file's own error.
+    return none
+  }
+  return target.kind === 'chat-app' ? chatAppFileChecks(target.file, doc) : knowledgeFileChecks(target.file, doc)
+}

package/src/local/local-function-ids.ts

@@ -0,0 +1,141 @@
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import { join, relative, sep } from 'node:path'
+
+import type { Directory } from './local-sync-refs'
+
+/**
+ * Object type ids a pulled Function's code hard-codes (pull D-3).
+ *
+ * A Function written against the workspace sometimes names an object type by
+ * the platform's id (`const SERVICE_REQUEST = 'b17f…'`), most often for an
+ * Action's `subjectRef`. The local runtime gives every object type its own
+ * id, so that code names a type the runtime doesn't have: an edit submitted
+ * there is refused, or worse, read as the wrong record. The pull knows the
+ * workspace's ids (the snapshot's directory), so it can say where.
+ *
+ * Two things are done with them:
+ *
+ * - **Said**, at pull and at each `local dev` apply: `<file>:<line>
+ *   hard-codes <Type>’s platform id`, with the fix (read the id from the
+ *   query result: `subjectOf`, or the result's `objectTypeId`).
+ * - **Adapted**, in the bundle `local dev` deploys and nowhere else: each
+ *   quoted platform id becomes the local runtime's id for the same type
+ *   (`bundleIdMap`, applied by `function deploy` when `local dev` passes the
+ *   map in FRONTERA_BUNDLE_ID_MAP). The files keep the platform's ids, so
+ *   what is pushed or deployed to the workspace is what was pulled.
+ *
+ * Only an exact match of a whole UUID the workspace gave an object type is
+ * touched: nothing else in the code can be that string by accident.
+ */
+
+const UUID = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi
+
+/** One hard-coded platform id: the project file, its 1-based line, the id and the object type it names. */
+export interface HardCodedId {
+  file: string
+  line: number
+  id: string
+  objectType: string
+}
+
+/** The workspace's object type ids, id → apiName, from a pull's directory. */
+export function platformObjectTypeIds(directory: Directory | undefined): Map<string, string> {
+  const out = new Map<string, string>()
+  for (const [name, id] of directory?.objectType ?? []) out.set(id.toLowerCase(), name)
+  return out
+}
+
+const isCode = (path: string) => /\.(ts|tsx|mts|js|mjs)$/.test(path) && !/\.test\.[a-z]+$/.test(path) && !path.endsWith('.d.ts')
+
+/** Each platform object type id the files' code (not their tests) hard-codes, in file and line order. */
+export function hardCodedObjectTypeIds(files: Record<string, string>, platformIds: ReadonlyMap<string, string>): HardCodedId[] {
+  if (!platformIds.size) return []
+  const out: HardCodedId[] = []
+  for (const [file, text] of Object.entries(files).sort(([a], [b]) => a.localeCompare(b))) {
+    if (!isCode(file)) continue
+    text.split('\n').forEach((line, i) => {
+      for (const m of line.matchAll(UUID)) {
+        const objectType = platformIds.get(m[0].toLowerCase())
+        if (objectType) out.push({ file, line: i + 1, id: m[0], objectType })
+      }
+    })
+  }
+  return out
+}
+
+/** One sentence per hard-coded id, as the pull and `local dev` say it. */
+export function hardCodedIdLine(hit: HardCodedId, adapted = false): string {
+  return `${hit.file}:${hit.line} hard-codes ${hit.objectType}’s platform id${adapted ? '; the bundle applied here uses this runtime’s id for it instead (the file is unchanged)' : ', which the local runtime doesn’t have'}. Take the id from the query result instead (\`subjectOf(result, row, id)\`, or \`result.objectTypeId\`), so the code holds on any runtime`
+}
+
+/** A Function's code files by project path: its file, or every file in its folder (`functions/<slug>/`). */
+export function functionCodeFiles(root: string, file: string, folder: boolean): Record<string, string> {
+  const out: Record<string, string> = {}
+  const read = (rel: string) => {
+    try {
+      out[rel] = readFileSync(join(root, rel), 'utf8')
+    } catch {
+      // Gone since it was listed: nothing to say about it.
+    }
+  }
+  if (!folder) {
+    read(file)
+    return out
+  }
+  const parts = file.split(/[\\/]/)
+  const dir = join(root, parts[0]!, parts[1]!)
+  const walk = (at: string) => {
+    for (const name of readdirSync(at)) {
+      if (name === 'node_modules' || name.startsWith('.')) continue
+      const path = join(at, name)
+      if (statSync(path).isDirectory()) walk(path)
+      else if (isCode(name)) read(relative(root, path).split(sep).join('/'))
+    }
+  }
+  if (existsSync(dir)) walk(dir)
+  return out
+}
+
+/**
+ * Platform id → this runtime's id, for each object type both know by the
+ * same apiName and whose ids differ: what `function deploy` puts in the bundle
+ * in place of the hard-coded one. Lowercase keys.
+ */
+export function bundleIdMap(hits: readonly HardCodedId[], localIds: ReadonlyMap<string, string> | undefined): Record<string, string> {
+  const out: Record<string, string> = {}
+  for (const h of hits) {
+    const local = localIds?.get(h.objectType)
+    if (local && local.toLowerCase() !== h.id.toLowerCase()) out[h.id.toLowerCase()] = local
+  }
+  return out
+}
+
+/** The environment variable `local dev` hands `function deploy` the map in. */
+export const BUNDLE_ID_MAP_ENV = 'FRONTERA_BUNDLE_ID_MAP'
+
+/**
+ * The built code with each quoted platform id (`'…'`, `"…"` or a template
+ * literal) replaced by its local one, case kept as the map's value gives it.
+ * Unquoted text (a comment) is left as it is.
+ */
+export function mapBundleIds(code: string, map: Readonly<Record<string, string>>): string {
+  if (!Object.keys(map).length) return code
+  return code.replace(/(['"`])([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})\1/g, (whole, quote: string, id: string) => {
+    const local = map[id.toLowerCase()]
+    return local ? `${quote}${local}${quote}` : whole
+  })
+}
+
+/** The map from FRONTERA_BUNDLE_ID_MAP, or empty when unset or not a map of ids. */
+export function bundleIdMapFromEnv(env: Record<string, string | undefined> = process.env): Record<string, string> {
+  const raw = env[BUNDLE_ID_MAP_ENV]
+  if (!raw) return {}
+  try {
+    const parsed = JSON.parse(raw) as unknown
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return {}
+    const ok = (v: unknown): v is string => typeof v === 'string' && /^[0-9a-fA-F-]{36}$/.test(v)
+    return Object.fromEntries(Object.entries(parsed).filter(([k, v]) => ok(k) && ok(v)).map(([k, v]) => [k.toLowerCase(), v as string]))
+  } catch {
+    return {}
+  }
+}

package/src/local/local-function-recovery.ts

@@ -0,0 +1,141 @@
+import { posix } from 'node:path'
+
+import { mergeRecovered, recoverFromBundle, recoveredFiles, type RecoveredModule } from './function-bundle-recovery'
+import type { RemoteItem } from './local-sync-plan'
+
+/**
+ * A pull's Functions whose source archive lacks a module their code imports,
+ * and what it does about them once every Function is read.
+ *
+ * In order: a copy another Function's source holds (the same file, kept by a
+ * current deploy); else the module cut back out of the Function's deployed
+ * bundle (`function-bundle-recovery.ts`), one file for every Function that
+ * needs it; else the reason, with today's remedy (deploy again from its source
+ * with a current CLI). A platform without the bundle route gets today's note.
+ */
+export interface MissingImports {
+  it: RemoteItem
+  slug: string
+  version: number
+  /** Its source archive, by archive path. */
+  files: ReadonlyMap<string, string>
+  entry: string
+  /** By path from its folder, without extension (`../shared/eligibility`). */
+  missing: string[]
+  /** Whether a pull may write this project path (without extension). */
+  writable: (projectPath: string) => boolean
+}
+
+const list = (paths: string[]) => (paths.length > 3 ? `${paths.slice(0, 3).join(', ')} and ${paths.length - 3} more` : paths.length > 1 ? `${paths.slice(0, -1).join(', ')} and ${paths[paths.length - 1]}` : paths.join(''))
+
+export function missingImportNote(lacking: string[], why?: string): string {
+  return `Imports ${list(lacking)}, which its source in the workspace doesn’t hold${why ? ` and its deployed bundle couldn’t give back (${why})` : ''}: it was deployed before a deploy kept the files a Function imports from beside its folder, so it can’t build here until the project has ${lacking.length === 1 ? 'that file' : 'those files'}. Deploy it again from its source with a current CLI, then pull it`
+}
+
+export function missingImportWarning(slug: string, lacking: string[], why?: string): string {
+  return `Function ${slug}: imports ${list(lacking)}, which its source in the workspace doesn’t hold${why ? ` and its deployed bundle couldn’t give back (${why})` : ''}; deploy it again from its source with a current CLI, then pull it`
+}
+
+/** A 404 from a platform that has no bundle route, rather than one that refused this version. */
+function olderPlatform(err: unknown): boolean {
+  const message = (err as Error)?.message ?? ''
+  return /answered 404/.test(message) && (/Route not found/i.test(message) || /answered 404: (NOT_FOUND)?\s*$/.test(message))
+}
+
+export async function recoverMissingImports(
+  pending: MissingImports[],
+  items: RemoteItem[],
+  getBytes: (path: string) => Promise<Uint8Array>,
+  warnings: string[],
+): Promise<void> {
+  const project = (p: MissingImports, m: string) => posix.normalize(posix.join('functions', p.slug, m))
+  // A real copy of the file in another Function's source wins over anything recovered.
+  const real = (path: string): { file: string; content: string; by: RemoteItem }[] => {
+    for (const ext of ['.ts', '.tsx', '/index.ts', '.js', '/index.js']) {
+      const by = items.find((i) => i.kind === 'function' && i.files[`${path}${ext}`] !== undefined && !i.recovered?.includes(`${path}${ext}`))
+      if (!by) continue
+      const file = `${path}${ext}`
+      const types = file.endsWith('.js') ? `${file.slice(0, -'.js'.length)}.d.ts` : null
+      return [{ file, content: by.files[file]!, by }, ...(types && by.files[types] !== undefined ? [{ file: types, content: by.files[types]!, by }] : [])]
+    }
+    return []
+  }
+
+  // What the pull holds as source, from any Function's archive: a recovered module imports it rather than recovering it.
+  const elsewhere = new Map<string, string>()
+  for (const i of items) {
+    if (i.kind !== 'function') continue
+    for (const [file, content] of Object.entries(i.files)) {
+      if (/\.(ts|tsx|mts)$/.test(file) && !file.endsWith('.d.ts') && !i.recovered?.includes(file)) elsewhere.set(file.replace(/\.[^./]+$/, ''), content)
+    }
+  }
+  const recovered = new Map<string, RecoveredModule>()
+  const holders = new Map<string, MissingImports[]>()
+  const failed = new Map<MissingImports, Record<string, string>>()
+  const unread = new Map<MissingImports, string | null>()
+  for (const p of pending) {
+    const fromOthers: string[] = []
+    const remaining = p.missing.filter((m) => {
+      const copies = real(project(p, m))
+      if (!copies.length) return true
+      for (const c of copies) p.it.files[c.file] = c.content
+      fromOthers.push(`${copies[0]!.file} (from Function ${copies[0]!.by.name})`)
+      return false
+    })
+    if (fromOthers.length) p.it.notes.push(`Brings ${list(fromOthers)}, which it imports from beside its folder and another Function’s source in the workspace holds`)
+    if (!remaining.length) continue
+    let bundle: string
+    try {
+      bundle = new TextDecoder().decode(await getBytes(`/v1/functions/${encodeURIComponent(p.slug)}/versions/${p.version}/bundle`))
+    } catch (err) {
+      unread.set(p, olderPlatform(err) ? null : `its deployed bundle couldn’t be read: ${(err as Error).message}`)
+      continue
+    }
+    const result = recoverFromBundle({ slug: p.slug, version: p.version, bundle, folder: posix.join('functions', p.slug), files: p.files, entry: p.entry, missing: remaining, writable: p.writable, elsewhere })
+    failed.set(p, result.failed)
+    for (const [path, names] of Object.entries(result.testOnly)) {
+      p.it.notes.push(`Its tests import ${names.map((n) => `\`${n}\``).join(', ')} from ${path}, which its deployed bundle doesn’t hold (the bundle holds only what the Function runs): those tests need the original source`)
+    }
+    for (const mod of result.modules) {
+      const had = recovered.get(mod.path)
+      const merged = had ? mergeRecovered(had, mod) : mod
+      if (!merged) {
+        result.failed[mod.path] = `the deployed bundles of ${had!.from.join(', ')} and ${p.slug} hold code for it that can’t be one file`
+        continue
+      }
+      recovered.set(mod.path, merged)
+      holders.set(mod.path, [...(holders.get(mod.path) ?? []), p])
+    }
+  }
+
+  // One file for every Function that needs it: the union of what their bundles held.
+  const wrote = new Map<MissingImports, string[]>()
+  for (const [path, mod] of recovered) {
+    const files = recoveredFiles(mod)
+    for (const p of holders.get(path) ?? []) {
+      Object.assign(p.it.files, files)
+      p.it.recovered = [...new Set([...(p.it.recovered ?? []), ...Object.keys(files)])].sort()
+      wrote.set(p, [...(wrote.get(p) ?? []), ...Object.keys(files).filter((f) => f.endsWith('.js'))])
+    }
+  }
+
+  for (const p of pending) {
+    const done = wrote.get(p) ?? []
+    if (done.length) {
+      p.it.notes.push(`Recovered ${list(done.sort())} from its deployed bundle (v${p.version}): its source in the workspace doesn’t hold ${done.length === 1 ? 'that file' : 'those files'}. ${done.length === 1 ? 'It is' : 'They are'} bundled JavaScript with a .d.ts typing each export \`any\`, so it builds and runs here; the original types are gone, so code that relied on them may not typecheck (\`local check\` counts those errors as inherited while the files are as pulled). Replace ${done.length === 1 ? 'it' : 'them'} with the original source when you have it, or deploy the Function again from its source with a current CLI`)
+    }
+    if (unread.has(p)) {
+      const why = unread.get(p) ?? undefined
+      const lacking = p.missing.map((m) => project(p, m)).filter((m) => !Object.keys(p.it.files).some((f) => f.startsWith(`${m}.`) || f.startsWith(`${m}/index.`)))
+      if (lacking.length) {
+        p.it.notes.push(missingImportNote(lacking, why))
+        warnings.push(missingImportWarning(p.slug, lacking, why))
+      }
+      continue
+    }
+    for (const [path, why] of Object.entries(failed.get(p) ?? {})) {
+      p.it.notes.push(missingImportNote([path], why))
+      warnings.push(missingImportWarning(p.slug, [path], why))
+    }
+  }
+}

package/src/local/local-function-state.ts

@@ -32,3 +32,90 @@ export async function mirrorFunctionState(project: LocalProject, key: string, se
   }
   return state.enabled ? [] : [`  switched off Function ${slug}: it is off in the workspace`]
 }
+
+/** `GET /v1/functions/registry-status`: what the service has deployed, and what a runner has registered with the job engine. */
+interface RegistryStatus {
+  generation: number
+  registeredGeneration: number | null
+}
+
+/**
+ * After a Function deploy: wait until the job engine can run it. A deploy
+ * moves the service's registry generation (the deploy answers it as
+ * `registryGeneration`); the Function is runnable once a runner has registered
+ * that generation (`registeredGeneration >= registryGeneration`, the check
+ * `frontera function run` makes before it sends its event). Until then a
+ * workflow or Agent that starts it fails with "could not find function". On
+ * the local runtime the runner is asked to sync at once (`POST
+ * /internal/reload` on its loopback port) rather than at its next poll.
+ * Says "registering…" once through `note` while it waits; returns a
+ * `warning:` line when it is still not runnable at the cap (60 s), nothing
+ * when it is.
+ */
+export async function waitUntilRunnable(
+  serviceUrl: string,
+  creds: LocalCredentials,
+  slug: string,
+  opts: RunnableOptions = {},
+): Promise<string[]> {
+  return (await checkRunnable(serviceUrl, creds, slug, opts)).lines
+}
+
+type RunnableOptions = { note?: (line: string) => void; timeoutMs?: number; pollMs?: number; fetcher?: typeof fetch; now?: () => number; runnerUrl?: string; generation?: number }
+
+/**
+ * `waitUntilRunnable`, and whether it saw the Function runnable: true when a
+ * runner registered its generation (a runner is alive and the job engine can
+ * run it), false when it still was not at the cap, null when the runtime
+ * could not say.
+ */
+export async function checkRunnable(serviceUrl: string, creds: LocalCredentials, slug: string, opts: RunnableOptions = {}): Promise<{ lines: string[]; runnable: boolean | null }> {
+  if (!creds.workspaceKey) return { lines: [], runnable: null }
+  const fetcher = opts.fetcher ?? fetch
+  const now = opts.now ?? Date.now
+  const deadline = now() + (opts.timeoutMs ?? 60_000)
+  const read = async (): Promise<RegistryStatus | null> => {
+    try {
+      const res = await fetcher(new URL('/v1/functions/registry-status', serviceUrl), { headers: { authorization: `Bearer ${creds.workspaceKey}`, 'x-workspace-id': creds.workspaceId } })
+      if (!res.ok) return null
+      const body = (await res.json()) as { data?: RegistryStatus } & Partial<RegistryStatus>
+      const status = body.data ?? body
+      return typeof status.generation === 'number' ? { generation: status.generation, registeredGeneration: typeof status.registeredGeneration === 'number' ? status.registeredGeneration : null } : null
+    } catch {
+      return null
+    }
+  }
+  // The deploy's own generation when it said one; else what the service has now, which is at least that.
+  const caughtUp = (st: RegistryStatus) => st.registeredGeneration !== null && st.registeredGeneration >= (opts.generation ?? st.generation)
+  let status = await read()
+  // A runtime that cannot say (an older service): nothing to wait on.
+  if (!status) return { lines: [], runnable: null }
+  if (caughtUp(status)) return { lines: [], runnable: true }
+  opts.note?.(`  Function ${slug} is registering with the job engine…`)
+  if (opts.runnerUrl) {
+    try {
+      await fetcher(new URL('/internal/reload', opts.runnerUrl), { method: 'POST', signal: AbortSignal.timeout(15_000) })
+    } catch {
+      // The runner's own poll registers it; the reload only makes that sooner.
+    }
+  }
+  const started = now()
+  for (;;) {
+    const next = await read()
+    if (next) status = next
+    if (caughtUp(status)) {
+      opts.note?.(`  Function ${slug} is runnable (${Math.round((now() - started) / 1000)} s)`)
+      return { lines: [], runnable: true }
+    }
+    if (now() >= deadline) break
+    await new Promise((r) => setTimeout(r, opts.pollMs ?? 1000))
+  }
+  return {
+    runnable: false,
+    lines: [
+    status.registeredGeneration === null
+      ? `  warning: Function ${slug} is deployed, but no runner has registered with the job engine, so nothing can run it yet: see \`frontera local logs runner\``
+      : `  warning: Function ${slug} is deployed but still registering with the job engine: a workflow or Agent that starts it now fails with "could not find function"; \`frontera function run ${slug}\` waits for it`,
+    ],
+  }
+}

package/src/local/local-keys.ts

@@ -106,10 +106,12 @@ export function providerEnv(): Record<string, string> {
 }
 
 /**
- * With no OpenAI or OpenRouter key, the runtime embeds with the local model:
- * the service's OpenAI client is pointed at it, and the organization gets a
- * placeholder OpenAI credential. A real key of either turns this off.
+ * With no OpenAI key, the service's OpenAI client is pointed at the local
+ * keyless embeddings, so the runtime can embed with them: with no OpenAI or
+ * OpenRouter key, or when the provider refuses the key stored for it (the
+ * organization then gets a placeholder OpenAI credential). A real OpenAI key
+ * turns this off, and a key the provider takes replaces their model.
  */
-export function keylessEmbeddings(): boolean {
-  return !getKey('openai') && !getKey('openrouter')
+export function localEmbeddingsReachable(): boolean {
+  return !getKey('openai')
 }

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

@@ -179,7 +179,7 @@ export function documentPaths(root: string, kb: string): string[] {
     }
   }
   if (existsSync(top)) walk('', 0)
-  return out.sort()
+  return out.sort((a, b) => (String(a) < String(b) ? -1 : String(a) > String(b) ? 1 : 0))
 }
 
 /** The documents in a knowledge base's folder and its subfolders, by path. */