@frontera-sdk/cli 1.52.45 → 1.52.47

package/src/local/local-apply-error.ts

@@ -1,3 +1,5 @@
+import { oneLine } from './local-applied'
+
 /**
  * A failed apply command's error, as `frontera local dev` prints it: the error
  * line and the detail lines under it (validation issues, the hint), at most
@@ -33,3 +35,27 @@ export function applyErrorText(output: string): string {
   if (!shown.length) return 'failed with no output'
   return [shown[0], ...shown.slice(1).map((l) => `      ${l}`)].join('\n')
 }
+
+/** Error lines that say only that something failed, and need the line under them to say why. */
+const GENERIC = /^(invalid workflow definition|blueprint validation is blocked|validation failed|the request is invalid|bad request|invalid definition)\b/i
+
+/**
+ * A failed item's reason in one line, as `local dev` records it and `local
+ * status` and the MCP `apply` say it (Forge improvement plan N9): the error's
+ * first line, and when that line only says it failed ("Invalid workflow
+ * definition", "Blueprint validation is blocked"), the first line under it
+ * that says why: a blocker, a definition error, the hint.
+ */
+export function applyFailureReason(output: string): string {
+  const text = applyErrorText(output)
+  const head = oneLine(text)
+  if (!GENERIC.test(head)) return head
+  const detail = text
+    .split('\n')
+    .slice(1)
+    .map((l) => l.trim().replace(/^(hint:|✕)\s*/i, '').trim())
+    .find((l) => l && !/^frontera\s/.test(l) && !/^`frontera/.test(l) && !/^\(\d+ steps? applied/.test(l))
+  if (!detail) return head
+  const joined = `${head.replace(/[.:]\s*$/, '')}: ${detail}`
+  return joined.length > 300 ? `${joined.slice(0, 297)}…` : joined
+}

package/src/local/local-apps.ts

@@ -27,6 +27,7 @@ export interface AppRow {
   slug: string
   name: string
   description?: string | null
+  icon?: string | null
   hosting?: 'platform' | 'external' | null
   version?: string | null
   manifest?: { routing?: unknown; connectDomains?: unknown; resourceDomains?: unknown } | null
@@ -37,6 +38,8 @@ export interface AppRow {
 export interface AppFile {
   name: string
   description?: string
+  /** An icon from the platform's set, by name (X6). */
+  icon?: string
   hosting?: 'external'
   version?: string
   routing?: string
@@ -57,6 +60,7 @@ export function appDocument(row: AppRow): AppFile {
   return {
     name: row.name,
     ...(row.description ? { description: row.description } : {}),
+    ...(row.icon ? { icon: row.icon } : {}),
     ...(row.hosting === 'external' ? { hosting: 'external' as const } : {}),
     ...(row.version ? { version: row.version } : {}),
     ...(m && typeof m.routing === 'string' && m.routing !== 'spa' ? { routing: m.routing } : {}),
@@ -120,12 +124,14 @@ export async function applyApp(root: string, slug: string, call: Call, provides:
   }
   const name = typeof doc.name === 'string' && doc.name.trim() ? doc.name.trim() : slug
   const description = typeof doc.description === 'string' ? doc.description : null
-  const ensured = await call('POST', '/v1/platform-apps/ensure', { slug, displayName: name, kind: 'code', ...(description ? { description } : {}) })
+  const icon = typeof doc.icon === 'string' && doc.icon.trim() ? doc.icon.trim() : null
+  const ensured = await call('POST', '/v1/platform-apps/ensure', { slug, displayName: name, kind: 'code', ...(description ? { description } : {}), ...(icon ? { icon } : {}) })
   if (ensured.status >= 400) return { ok: false, output: `error [APP]: ${errorOf(ensured)}` }
   const lines: string[] = []
   if (!dataOf(ensured.body)?.created) {
-    const renamed = await call('PATCH', `/v1/platform-apps/${encodeURIComponent(String(dataOf(ensured.body)?.id ?? ''))}`, { displayName: name, description })
-    if (renamed.status >= 400) lines.push(`  warning: Its name and description could not be set here (${errorOf(renamed)})`)
+    // A file with no icon leaves the App's as it is.
+    const renamed = await call('PATCH', `/v1/platform-apps/${encodeURIComponent(String(dataOf(ensured.body)?.id ?? ''))}`, { displayName: name, description, ...(icon ? { icon } : {}) })
+    if (renamed.status >= 400) lines.push(`  warning: Its name, description and icon could not be set here (${errorOf(renamed)})`)
   }
   const bindings = Array.isArray(doc.functions) ? doc.functions : []
   const named = new Set<string>()

package/src/local/local-blueprint-schemas.ts

@@ -495,6 +495,20 @@ const ACTION: JsonSchema = {
       required: ['invokeCapability', 'approval', 'reason', 'sensitivity'],
       additionalProperties: false,
     },
+    attachment: {
+      type: 'object',
+      description:
+        'How a deployment attaches the file the Action takes, for an Action over a Media Set’s records: the input the file arrives in (a staged upload’s id, which `frontera media stage` prints, or a run’s file), and the media reference property it fills, the text property that keeps the item’s id, or both. `local dev` deploys the Action with it on the local runtime. It is a deployment choice, not part of the Action: it stays in this project when the Action is proposed, and in the workspace the person who deploys the Action chooses (`frontera action deploy <apiName> --attach <property> --file-input <input>`).',
+      properties: {
+        fileInput: { type: 'string', description: 'The input the file arrives in, by apiName: a string input no expected change sets.' },
+        property: { type: 'string', description: 'The media reference property the file fills.' },
+        itemIdProperty: { type: 'string', description: 'A text property that keeps the item’s id.' },
+        mediaSet: { type: 'string', description: 'The Media Set the file joins, by API name; the property’s own set when left out.' },
+      },
+      required: ['fileInput'],
+      anyOf: [{ required: ['property'] }, { required: ['itemIdProperty'] }],
+      additionalProperties: false,
+    },
   },
   required: ['apiName', 'displayName', 'description', 'subject', 'effect', 'inputs', 'businessOutcomes', 'concurrency', 'impact', 'submissionCriteria', 'governance'],
 }
@@ -521,7 +535,7 @@ const OBJECT_SET: JsonSchema = {
   $schema: DRAFT,
   title: 'Blueprint saved object set (blueprint/object-sets/<name>.yaml)',
   description:
-    'A named set of one object type’s records that workflows, Agents and Apps reuse: dynamic (a definition, re-evaluated on every read) or static (a fixed list of primary keys). `frontera local dev` saves each file on the local runtime once the Blueprint is published there, so a reset brings it back. Other files name it `objectSet/<name>`, where the name is the set’s `name` (spaces allowed: `objectSet/Open work orders`) or the file’s name (`objectSet/open-work-orders`).',
+    'A named set of one object type’s records that workflows, Agents and Apps reuse: dynamic (a definition, re-evaluated on every read) or static (a fixed list of primary keys). `frontera local dev` saves each file on the local runtime once the Blueprint is published there, so a reset brings it back; `frontera local sync push` proposes it, and Apply saves it in the workspace after the Blueprint, before the workflows that name it (a static set’s records are made once; a change request does not remove a set). Other files name it `objectSet/<name>`, where the name is the set’s `name` (spaces allowed: `objectSet/Open work orders`) or the file’s name (`objectSet/open-work-orders`).',
   type: 'object',
   properties: {
     name: text('What people call it ("Open work orders"); the file’s name when absent.'),

package/src/local/local-confidential.ts

@@ -0,0 +1,81 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { parse as parseYaml } from 'yaml'
+
+import { readWorkspaceGrants } from './local-workspace-grants'
+
+/**
+ * Confidential fields no one in the project may read (Forge improvement plan
+ * X7, T14 step 7). A field classified confidential or restricted reads as
+ * hidden to an Agent or a workflow without `read_sensitive` on its type; with
+ * no Agent's `bindings.json` and no `blueprint/workspace-grants.yaml`
+ * granting it, every reader sees it hidden, which reads as a mistake once an
+ * Agent says it can't see a lead's email. Said as a warning when the
+ * Blueprint applies, never a refusal: keeping a field from everyone may be
+ * the point.
+ */
+export interface UnreadConfidential {
+  objectType: string
+  fields: string[]
+}
+
+const SENSITIVE = new Set(['confidential', 'restricted'])
+
+function readDoc(path: string): Record<string, unknown> | null {
+  try {
+    const text = readFileSync(path, 'utf8')
+    const doc = path.endsWith('.json') ? JSON.parse(text) : parseYaml(text)
+    return doc && typeof doc === 'object' && !Array.isArray(doc) ? (doc as Record<string, unknown>) : null
+  } catch {
+    return null
+  }
+}
+
+/** Each object type's confidential or restricted fields, by its own classification or the type's. */
+export function confidentialFields(root: string): Map<string, string[]> {
+  const out = new Map<string, string[]>()
+  const dir = join(root, 'blueprint', 'object-types')
+  if (!existsSync(dir)) return out
+  for (const file of readdirSync(dir).sort()) {
+    if (!/\.(ya?ml|json)$/.test(file)) continue
+    const doc = readDoc(join(dir, file))
+    if (!doc || typeof doc.apiName !== 'string') continue
+    const typeClass = ((doc.governance as { sensitivity?: { classification?: unknown } } | undefined)?.sensitivity?.classification) ?? 'internal'
+    const fields = (Array.isArray(doc.properties) ? doc.properties : []).flatMap((p) => {
+      const prop = p as { apiName?: unknown; sensitivity?: unknown }
+      const own = typeof prop.sensitivity === 'string' ? prop.sensitivity : typeClass
+      return typeof prop.apiName === 'string' && SENSITIVE.has(String(own)) ? [prop.apiName] : []
+    })
+    if (fields.length) out.set(doc.apiName, fields)
+  }
+  return out
+}
+
+/** The object types something in the project may read in full: an Agent's `read_sensitive`, or the workspace's. */
+export function clearedTypes(root: string): Set<string> {
+  const cleared = new Set<string>()
+  for (const g of readWorkspaceGrants(root)?.grants ?? []) if (g.permissions.includes('read_sensitive')) cleared.add(g.objectType)
+  const agents = join(root, 'agents')
+  if (!existsSync(agents)) return cleared
+  for (const slug of readdirSync(agents)) {
+    const bindings = readDoc(join(agents, slug, 'bindings.json'))
+    for (const entry of Array.isArray(bindings?.blueprint) ? bindings!.blueprint : []) {
+      const e = entry as { objectType?: unknown; permissions?: unknown }
+      if (typeof e.objectType === 'string' && Array.isArray(e.permissions) && e.permissions.includes('read_sensitive')) cleared.add(e.objectType.replace(/^objectType\//, ''))
+    }
+  }
+  return cleared
+}
+
+export function unreadConfidential(root: string): UnreadConfidential[] {
+  const cleared = clearedTypes(root)
+  return [...confidentialFields(root)].filter(([type]) => !cleared.has(type)).map(([objectType, fields]) => ({ objectType, fields }))
+}
+
+/** One warning line per object type, as `local dev` prints its others. */
+export function unreadConfidentialLines(found: UnreadConfidential[]): string[] {
+  return found.map(({ objectType, fields }) => {
+    const shown = fields.length > 4 ? `${fields.slice(0, 4).join(', ')} and ${fields.length - 4} more` : fields.join(', ')
+    return `  warning: ${objectType}'s confidential field${fields.length === 1 ? '' : 's'} (${shown}) no Agent or workspace here may read: each reads as hidden. If one should, give it read_sensitive in its bindings.json, or the workspace in blueprint/workspace-grants.yaml`
+  })
+}

package/src/local/local-data-load.ts

@@ -0,0 +1,130 @@
+import { createHash } from 'node:crypto'
+import { readFileSync } from 'node:fs'
+import { parse as parseYaml } from 'yaml'
+
+import { CliError } from '../errors'
+
+/**
+ * Records loaded through the project's governed Actions (Forge improvement
+ * plan L2, T12; P4 2.3: about 45 tool calls and a throwaway workflow).
+ * `frontera local data load <file> --via-actions` submits each record as
+ * the Action the file names, as the local `submitter` persona, so the
+ * records arrive the way the platform makes them: through the Action's
+ * contract, its criteria and its effect. The local runtime only.
+ *
+ * The file (JSON or YAML) is a list of groups, run in its order, so a group
+ * whose records name another's comes after it:
+ *
+ *   - action: createCustomer
+ *     records:
+ *       - { name: Acme, tier: gold }
+ *   - action: openTicket
+ *     records:
+ *       - input: { title: Broken pump }
+ *         subject: CUST-1        # for an Action on an existing record
+ */
+
+export interface LoadGroup {
+  action: string
+  records: Array<{ input: Record<string, unknown>; subject?: string | number }>
+}
+
+export function readLoadFile(path: string): LoadGroup[] {
+  let doc: unknown
+  try {
+    const text = readFileSync(path, 'utf8')
+    doc = /\.json$/i.test(path) ? JSON.parse(text) : parseYaml(text)
+  } catch (err) {
+    throw new CliError(`${path} could not be read: ${(err as Error).message}`, { code: 'USAGE', hint: 'a list of { action, records } (`frontera local data --help`)' })
+  }
+  if (!Array.isArray(doc)) throw new CliError(`${path} is not a list of { action, records }`, { code: 'USAGE', hint: '- action: createCustomer\n    records:\n      - { name: Acme }' })
+  return doc.map((g, i) => {
+    const group = g as { action?: unknown; records?: unknown }
+    if (typeof group?.action !== 'string' || !/^[a-z][A-Za-z0-9]*$/.test(group.action)) throw new CliError(`${path}: group ${i + 1} names no Action (\`action: <apiName>\`)`, { code: 'USAGE', hint: '`frontera local schema` describes the file: each group is `action: <apiName>` with its `records` list' })
+    if (!Array.isArray(group.records)) throw new CliError(`${path}: group ${i + 1} (${group.action}) has no records list`, { code: 'USAGE', hint: 'list the records under `records:`, one per Action submission' })
+    return {
+      action: group.action,
+      records: group.records.map((r) => {
+        const rec = r as { input?: unknown; subject?: unknown }
+        const wrapped = rec && typeof rec === 'object' && 'input' in rec && typeof rec.input === 'object' && rec.input !== null
+        return wrapped
+          ? { input: rec.input as Record<string, unknown>, ...(typeof rec.subject === 'string' || typeof rec.subject === 'number' ? { subject: rec.subject } : {}) }
+          : { input: (rec ?? {}) as Record<string, unknown> }
+      }),
+    }
+  })
+}
+
+/** The same record of the same file submits once: the key a second load sends is the first's. */
+export function loadKey(file: string, action: string, index: number, record: unknown): string {
+  return `load-${createHash('sha256').update(JSON.stringify([file, action, index, record])).digest('hex').slice(0, 32)}`
+}
+
+export interface LoadSubmit {
+  (action: string, invocation: Record<string, unknown>, idempotencyKey: string): Promise<{ lifecycle?: string; status?: string; requestId?: string; id?: string }>
+}
+
+export interface LoadOutcome {
+  action: string
+  submitted: number
+  applied: number
+  waiting: number
+  /** Submitted, and settled without applying (refused by its criteria, rejected, failed): by lifecycle. */
+  notApplied: Array<{ index: number; lifecycle: string }>
+  refused: Array<{ index: number; reason: string }>
+}
+
+/** What each lifecycle comes to: applied, waiting on a person, or neither. */
+function outcomeOf(answer: { lifecycle?: string; status?: string }): 'applied' | 'waiting' | 'other' {
+  const state = String(answer.lifecycle ?? answer.status ?? '')
+  if (/not_applied|rejected|failed|cancel|refused|unknown/.test(state)) return 'other'
+  if (/succeeded|applied|completed/.test(state)) return 'applied'
+  if (/awaiting|pending|ready|dispatch|running|queued/.test(state)) return 'waiting'
+  return 'other'
+}
+
+/** Submit each group's records in batches, group after group; a refused record is said, not retried. */
+export async function loadViaActions(
+  file: string,
+  groups: LoadGroup[],
+  submit: LoadSubmit,
+  opts: { batch?: number; subjectType?: (action: string) => Promise<string | null>; onGroup?: (o: LoadOutcome) => void } = {},
+): Promise<LoadOutcome[]> {
+  const batch = Math.max(1, Math.min(16, opts.batch ?? 4))
+  const out: LoadOutcome[] = []
+  for (const group of groups) {
+    const outcome: LoadOutcome = { action: group.action, submitted: 0, applied: 0, waiting: 0, notApplied: [], refused: [] }
+    const subjectTypeId = group.records.some((r) => r.subject !== undefined) ? await opts.subjectType?.(group.action) ?? null : null
+    for (let start = 0; start < group.records.length; start += batch) {
+      await Promise.all(group.records.slice(start, start + batch).map(async (record, offset) => {
+        const index = start + offset
+        const invocation: Record<string, unknown> = { input: record.input }
+        if (record.subject !== undefined) {
+          if (!subjectTypeId) {
+            outcome.refused.push({ index, reason: `${group.action} acts on no existing record, or its object type couldn't be read; leave subject out` })
+            return
+          }
+          invocation.subjectRef = { objectTypeId: subjectTypeId, objectId: String(record.subject) }
+        }
+        try {
+          const answer = await submit(group.action, invocation, loadKey(file, group.action, index, record))
+          outcome.submitted++
+          const kind = outcomeOf(answer)
+          if (kind === 'applied') outcome.applied++
+          else if (kind === 'waiting') outcome.waiting++
+          else outcome.notApplied.push({ index, lifecycle: String(answer.lifecycle ?? answer.status ?? 'unknown') })
+        } catch (err) {
+          outcome.refused.push({ index, reason: (err as Error).message.replace(/\s+/g, ' ').slice(0, 300) })
+        }
+      }))
+    }
+    opts.onGroup?.(outcome)
+    out.push(outcome)
+  }
+  return out
+}
+
+export function loadWords(o: LoadOutcome): string {
+  const parts = [`${o.applied} applied`, ...(o.waiting ? [`${o.waiting} waiting on a person (an approval step, or still running)`] : []), ...(o.notApplied.length ? [`${o.notApplied.length} not applied (${[...new Set(o.notApplied.map((n) => n.lifecycle))].join(', ')})`] : []), ...(o.refused.length ? [`${o.refused.length} refused`] : [])]
+  return `${o.action}: ${o.submitted + o.refused.length} record${o.submitted + o.refused.length === 1 ? '' : 's'}, ${parts.join(', ')}`
+}

package/src/local/local-dev-references.ts

@@ -13,9 +13,10 @@ import { applyQualityChecks, QUALITY_CHECKS_FILE, readQualityChecks, sourcePaths
 import { readLock } from './local-sync-plan'
 import { applyErrorText } from './local-apply-error'
 import { localAdaptation } from './local-blueprint-outline'
-import { actionFit, classify, objectTypeFit, objectTypeNeeds } from './local-portability'
+import { actionAttachment, actionFit, classify, objectTypeFit, objectTypeNeeds } from './local-portability'
 import { actionSemanticConflicts, semanticFactsOf } from '../blueprint/action-semantic-fit'
 import { inheritedConflictLine } from '../blueprint/action-rules'
+import { parseProblem } from '../blueprint/tree'
 import { inheritedFromPull, unchangedSincePull } from './local-check-inherited'
 import type { SyncProfiles, SyncTarget } from './local-dev-sync'
 import type { LocalProject } from './local-project'
@@ -554,6 +555,26 @@ export function resolveBlueprint(project: LocalProject, refused: BlueprintRefusa
   const mediaSets: Record<string, string> = {}
   const mediaTypes: Record<string, { set: string; file: string }> = {}
   const hasLocalDataset = (dataset: string) => existsSync(join(project.root, 'datasets', `${dataset}.json`))
+  // A file that doesn't parse is left off, said with its line and column, and the rest of the
+  // Blueprint applies (N9): one YAML error used to fail every item, naming no file. What names it
+  // is refused by the runtime next, and left off as any refusal is.
+  const leftOffActions: Record<string, string> = {}
+  const refusedActions: string[] = []
+  for (const [folder, part] of [['object-types', null], ['link-types', 'linkType'], ['metrics', 'metric'], ['semantic-types', 'semanticType'], ['shared-fields', 'sharedField'], ['actions', null]] as const) {
+    for (const name of yamlIn(folder)) {
+      const problem = parseProblem(join('blueprint', folder, name), readFileSync(join(source, folder, name), 'utf8'))
+      if (!problem) continue
+      const stem = name.replace(/\.ya?ml$/, '')
+      removed.push(join(folder, name))
+      warnings.push(`  warning: ${problem}; it is left off this runtime until it parses`)
+      const reason = `the file doesn't parse: ${problem}`
+      if (folder === 'object-types') objects[stem] = { status: 'left-off', adaptations: [`is left off: ${reason}`], refused: reason }
+      else if (folder === 'actions') {
+        leftOffActions[stem] = reason
+        refusedActions.push(stem)
+      } else parts[`${part}/${stem}`] = { reason, refused: true }
+    }
+  }
   for (const name of yamlIn('object-types')) {
     const doc = read('object-types', name)
     if (!doc || typeof doc.apiName !== 'string') continue
@@ -630,8 +651,6 @@ export function resolveBlueprint(project: LocalProject, refused: BlueprintRefusa
     }
   }
   const actions: LocalAction[] = []
-  const leftOffActions: Record<string, string> = {}
-  const refusedActions: string[] = []
   // A value an Action offers that the semantic type it writes refuses, in an Action and files still as
   // pulled: the workspace's, so the apply takes it (`action-rules.ts`), and it is said here as inherited.
   const inheritedWarnings: Record<string, string[]> = {}
@@ -662,7 +681,8 @@ export function resolveBlueprint(project: LocalProject, refused: BlueprintRefusa
       continue
     }
     const capability = doc.governance?.invokeCapability
-    actions.push({ apiName: doc.apiName, fit, ...(typeof capability === 'string' ? { invokeCapability: capability } : {}) })
+    const attachment = actionAttachment(doc)
+    actions.push({ apiName: doc.apiName, fit, ...(typeof capability === 'string' ? { invokeCapability: capability } : {}), ...(attachment ? { attachment } : {}) })
     const conflicts = semantic && inheritedConflict ? actionSemanticConflicts(doc, semantic) : []
     if (conflicts.length && conflicts.every((c) => inheritedConflict!(doc.apiName, c.refs))) {
       inheritedWarnings[doc.apiName] = conflicts.map((c) => inheritedConflictLine(c.message))

package/src/local/local-embedding-setup.ts

@@ -0,0 +1,62 @@
+import { embeddingEquivalents, PLATFORM_DEFAULT_EMBEDDING } from './local-org-settings'
+
+/**
+ * Real embeddings on the local runtime from a key the person already has
+ * (Forge improvement plan L9, T12 step 7). Without one, the runtime embeds
+ * with the keyless local vectors, which find passages by shared words, not
+ * meaning. `frontera local embeddings` says which providers can embed here,
+ * which of them have a key stored, and which have one in this shell's
+ * environment (by the variable's name; a value is never read into output),
+ * and recommends the one that embeds as the workspace does.
+ * `frontera local embeddings use <provider>` stores that provider's key from
+ * the environment, as `local key-set` would from a prompt.
+ */
+
+/** The providers whose key gives the runtime an embedding model, and the variables a key for each is usually kept in. */
+export const EMBEDDING_KEY_SOURCES: ReadonlyArray<{ provider: 'openai' | 'openrouter' | 'google'; label: string; vars: readonly string[] }> = [
+  { provider: 'openai', label: 'OpenAI', vars: ['OPENAI_API_KEY'] },
+  { provider: 'openrouter', label: 'OpenRouter', vars: ['OPENROUTER_API_KEY'] },
+  { provider: 'google', label: 'Google Gemini', vars: ['GOOGLE_GENERATIVE_AI_API_KEY', 'GEMINI_API_KEY', 'GOOGLE_API_KEY'] },
+]
+
+export interface EmbeddingKeyOption {
+  provider: 'openai' | 'openrouter' | 'google'
+  label: string
+  stored: boolean
+  /** The environment variable that holds a key for it, when one does; never its value. */
+  envVar: string | null
+  /** Whether it embeds with the workspace's model (or the platform's default when the project isn't linked). */
+  matchesWorkspace: boolean
+}
+
+type Embedding = { provider: string | null; model: string | null }
+
+/** Each provider that could embed here, with where a key for it is. */
+export function embeddingKeyOptions(env: Record<string, string | undefined>, stored: readonly string[], workspace: Embedding | null = PLATFORM_DEFAULT_EMBEDDING): EmbeddingKeyOption[] {
+  const same = new Set(workspace ? embeddingEquivalents(workspace).map((m) => m.provider) : [])
+  return EMBEDDING_KEY_SOURCES.map((s) => ({
+    provider: s.provider,
+    label: s.label,
+    stored: stored.includes(s.provider),
+    envVar: s.vars.find((v) => !!env[v]?.trim()) ?? null,
+    matchesWorkspace: same.has(s.provider),
+  }))
+}
+
+/** The provider to use: a key already stored first, then one in the environment; one that embeds as the workspace does before one that doesn't. */
+export function recommendedEmbeddingKey(options: readonly EmbeddingKeyOption[]): EmbeddingKeyOption | null {
+  const usable = options.filter((o) => o.stored || o.envVar)
+  const rank = (o: EmbeddingKeyOption) => (o.matchesWorkspace ? 0 : 2) + (o.stored ? 0 : 1)
+  return [...usable].sort((a, b) => rank(a) - rank(b))[0] ?? null
+}
+
+/** What `local embeddings` says to do next. */
+export function embeddingNextStep(options: readonly EmbeddingKeyOption[], keyless: boolean): string {
+  const best = recommendedEmbeddingKey(options)
+  const restart = '`frontera local stop`, then `frontera local start`; the next `frontera local dev` sets each knowledge base’s threshold for that model'
+  if (!keyless) return 'the runtime already embeds with a provider’s model'
+  if (!best) return `no OpenAI, OpenRouter or Gemini key is stored or in this shell: store one with \`frontera local key-set openai\` (or openrouter, google), then ${restart}`
+  const why = best.matchesWorkspace ? 'it embeds as the workspace does' : 'the workspace embeds with another model, so retrieval here ranks a little differently'
+  if (best.stored) return `a ${best.label} key is stored but the runtime started before it: ${restart} (${why})`
+  return `${best.envVar} in this shell holds a ${best.label} key: \`frontera local embeddings use ${best.provider}\` stores it, then ${restart} (${why})`
+}

package/src/local/local-jobs.ts

@@ -0,0 +1,108 @@
+import { containerState, followLogs, startContainer, stopContainer } from './local-docker'
+import type { LocalProject } from './local-project'
+import { waitForHttp } from './local-process'
+import { recordRuntime } from './local-runtime-history'
+import { logPath, type LocalCredentials, type LocalState } from './local-state'
+
+/**
+ * Restarting the local runtime's jobs engine on its own (Forge improvement
+ * plan X2, T12; P4 2.4). The engine crashed twice while `local status` said it
+ * was running, its lost runs held the queue, and the only way back was
+ * restarting the whole runtime, which stopped the App dev servers too.
+ *
+ * `frontera local restart jobs`, and the supervisor when the engine stops
+ * answering, restart its container alone: the service, Studio and every App
+ * dev server keep running. The engine registers the service's functions again
+ * as it starts. It keeps runs in memory, so each run still open from before
+ * has no executor any more: they are marked failed on the runtime
+ * (`POST /v1/local/jobs/lost-runs`), saying why, so they stop holding the queue.
+ */
+
+export interface JobsRestart {
+  ms: number
+  /** Runs it lost, marked failed; null when they couldn't be (the reason is in `note`). */
+  lost: number | null
+  note?: string
+}
+
+export interface JobsDeps {
+  stop: (name: string) => void
+  start: (name: string) => void
+  state: (name: string) => ReturnType<typeof containerState>
+  answers: (url: string, timeoutMs: number) => Promise<boolean>
+  fetcher: typeof fetch
+  now: () => Date
+  /** Follow the restarted container's logs into the jobs log again: the old follow ended with it. */
+  follow: (name: string, logFile: string) => void
+}
+
+const defaultDeps: JobsDeps = { stop: stopContainer, start: startContainer, state: containerState, answers: (url, ms) => waitForHttp(url, ms), fetcher: fetch, now: () => new Date(), follow: followLogs }
+
+/** The jobs engine's container and port, from the runtime's state; null when the runtime runs it off. */
+export function jobsComponent(project: LocalProject, state: LocalState): { container: string; port: number } | null {
+  const c = state.components.find((x) => x.name === 'jobs')
+  if (!c || c.status === 'off') return null
+  return { container: c.container ?? `frontera-${project.id}-jobs`, port: state.ports.jobs }
+}
+
+/** Mark the runs the engine lost failed, on the runtime, with its organization key. */
+export async function failLostRuns(serviceUrl: string, creds: LocalCredentials, startedBefore: Date, fetcher: typeof fetch = fetch): Promise<{ lost: number | null; note?: string }> {
+  try {
+    const res = await fetcher(new URL('/v1/local/jobs/lost-runs', serviceUrl), {
+      method: 'POST',
+      headers: { authorization: `Bearer ${creds.orgKey}`, 'x-org-id': creds.organizationId, 'x-workspace-id': creds.workspaceId, 'content-type': 'application/json' },
+      body: JSON.stringify({ startedBefore: startedBefore.toISOString() }),
+      signal: AbortSignal.timeout(30_000),
+    })
+    if (res.status === 404) return { lost: null, note: 'this runtime is older than lost-run cleanup, so runs it had open stay open: `frontera local start --update`' }
+    if (!res.ok) return { lost: null, note: `the runs it had open couldn't be marked failed: ${res.status} ${(await res.text()).slice(0, 160)}` }
+    const body = (await res.json()) as { data?: { failed?: number } }
+    return { lost: body.data?.failed ?? 0 }
+  } catch (err) {
+    return { lost: null, note: `the runs it had open couldn't be marked failed: ${(err as Error).message}` }
+  }
+}
+
+/** Restart the jobs engine alone, wait for it, and fail the runs it lost. */
+export async function restartJobs(project: LocalProject, state: LocalState, why: string, deps: Partial<JobsDeps> = {}): Promise<JobsRestart> {
+  const d = { ...defaultDeps, ...deps }
+  const jobs = jobsComponent(project, state)
+  if (!jobs) throw new Error('this runtime runs without its jobs engine (`frontera local start` with jobs on brings it)')
+  if (d.state(jobs.container) === 'missing') throw new Error('its container is gone: `frontera local start` brings the runtime back with its data')
+  const started = d.now()
+  if (d.state(jobs.container) === 'running') d.stop(jobs.container)
+  d.start(jobs.container)
+  d.follow(jobs.container, logPath(project, 'jobs'))
+  const url = `http://127.0.0.1:${jobs.port}`
+  if (!(await d.answers(`${url}/health`, 45_000)) && !(await d.answers(`${url}/`, 5_000))) throw new Error('the jobs engine did not answer within 50 s after restarting: `frontera local logs jobs` says why')
+  const ms = d.now().getTime() - started.getTime()
+  const { lost, note } = state.credentials ? await failLostRuns(`http://127.0.0.1:${state.ports.service}`, state.credentials, started, d.fetcher) : { lost: null, note: 'the runtime has no credentials yet, so runs it had open stay open' }
+  recordRuntime(project, { event: 'jobs-restarted', at: d.now().toISOString(), detail: `${why}${lost ? `; ${lost} run${lost === 1 ? '' : 's'} it had open marked failed` : ''}` })
+  return { ms, lost, ...(note ? { note } : {}) }
+}
+
+/**
+ * The supervisor's watch on the jobs engine: every `everyMs`, its port is
+ * probed; after `misses` probes in a row with no answer it is restarted
+ * alone, and the runs it lost failed. Returns the timer's stop.
+ */
+export function watchJobs(opts: { probe: () => Promise<boolean>; restart: () => Promise<unknown>; everyMs?: number; misses?: number; log?: (line: string) => void }): () => void {
+  let missed = 0
+  let busy = false
+  const timer = setInterval(async () => {
+    if (busy) return
+    busy = true
+    try {
+      if (await opts.probe()) missed = 0
+      else if (++missed >= (opts.misses ?? 2)) {
+        missed = 0
+        opts.log?.('the jobs engine stopped answering: restarting it alone')
+        await opts.restart().catch((err) => opts.log?.(`restarting the jobs engine failed: ${(err as Error).message}`))
+      }
+    } finally {
+      busy = false
+    }
+  }, opts.everyMs ?? 30_000)
+  timer.unref?.()
+  return () => clearInterval(timer)
+}