@frontera-sdk/cli 1.52.43 → 1.52.45

package/src/commands/local/sync.ts

@@ -35,6 +35,8 @@ import {
   type SyncKind,
 } from '../../local/local-sync-plan'
 import { readWorkspace, type SyncSource } from '../../local/local-sync-remote'
+import { rememberLocalCatalog } from '../../local/local-sync-models'
+import { runningTarget, runtimeCatalog } from '../../local/local-providers'
 import { buildStatusText, projectBuildSummary } from '../../local/local-build-summary'
 import { kindTitle } from '../../local/local-sync-names'
 import { describeUnresolved } from '../../local/local-sync-refs'
@@ -59,7 +61,7 @@ import {
 } from '../../local/local-sync-snapshot'
 import { flagBool, flagString, type Command, type CommandContext } from '../types'
 import { currentRequest, readRequests } from '../../local/local-sync-push'
-import { syncPush, syncRequest } from './sync-request'
+import { syncMapModel, syncPush, syncRequest } from './sync-request'
 
 /**
  * `frontera local sync`: a local project's link to one platform workspace.
@@ -231,7 +233,16 @@ function sourceIfKeyed(project: LocalProject, link: SyncLink): SyncSource | unde
  * unchanged copies only, `online` from the platform too, at the lock's
  * revision. `bases` says what was found and what was not.
  */
+/** This computer's model catalog, kept while its runtime runs, so models are matched by what they are offline too. */
+async function refreshLocalCatalog(project: LocalProject): Promise<void> {
+  const target = runningTarget(project.root)
+  if (!target) return
+  const models = await runtimeCatalog(target).catch(() => null)
+  if (models?.length) rememberLocalCatalog(project.root, models)
+}
+
 export async function planFor(project: LocalProject, link: SyncLink, opts: { kinds?: Set<SyncKind>; drafts?: Set<string>; fetch?: 'auto' | 'always' | 'never'; repair?: 'offline' | 'online' } = {}) {
+  await refreshLocalCatalog(project)
   const local = localItems(project).filter((l) => !opts.kinds || opts.kinds.has(l.kind))
   const readFromBase = (path: string) => readBase(project.root, path)
   const noBases: BaseRepair[] = []
@@ -397,8 +408,12 @@ async function checkKeys(platform: string, keys: { workspace: string; organizati
     org = syncClient(platform, keys.organization)
     const orgMe = await org.find<WhoAmI>('/v1/whoami').catch(() => null)
     if (orgMe?.orgId && orgMe.orgId !== me.orgId) throw new CliError('the organization key belongs to another organization than the workspace', { code: 'USAGE', hint: 'use a key from the organization that owns the workspace' })
-    // The lifecycle is what an organization key is for here; reading it proves the key.
-    await org.get('/v1/blueprint/lifecycle')
+    // The lifecycle is what an organization key is for here; reading it proves the key. The read is authorized before
+    // the lookup, so a 404 (an organization that has never published a Blueprint: no lifecycle yet) proves it too.
+    await org.find('/v1/blueprint/lifecycle').catch((err: Error) => {
+      if (err instanceof CliError && (err.code === 'UNAUTHORIZED' || err.code === 'FORBIDDEN')) throw err
+      throw new CliError(`the organization key couldn’t read the organization’s Blueprint: ${err.message.split('\n')[0]}`, { code: 'SYNC_ORG_KEY_UNREADABLE', hint: 'check the key is a current organization key (sk-org-…) for this platform, then connect again' })
+    })
   }
   return { me, identity }
 }
@@ -425,6 +440,8 @@ const connect = async (ctx: CommandContext) => {
     organization: keys.organization ? me.orgId! : previous?.organization,
     organizationName: identity?.organization.name ?? previous?.organizationName,
     blueprint: (blueprintFlag as SyncLink['blueprint'] | undefined) ?? (previous?.blueprint === 'organization' && keys.organization ? 'organization' : 'workspace'),
+    // The models mapped for this workspace stay; another workspace has its own catalog.
+    ...(previous?.models && previous.workspace === me.workspaceId ? { models: previous.models } : {}),
   }
   // A folder that is not a project yet gets the project file the link lives in.
   if (!existsSync(projectFile(project.root))) writeFileSync(projectFile(project.root), `# A Frontera project. \`frontera local dev\` applies agents/, workflows/, functions/ and blueprint/.\nname: ${basename(project.root)}\n`)
@@ -948,6 +965,7 @@ const SUBCOMMANDS: Record<string, (ctx: CommandContext) => Promise<{ data: unkno
   // Called through, not referenced: `sync-request.ts` imports this module back.
   push: (ctx) => syncPush(ctx),
   request: (ctx) => syncRequest(ctx),
+  'map-model': (ctx) => syncMapModel(ctx),
 }
 
 export const localSync: Command = {
@@ -955,8 +973,8 @@ export const localSync: Command = {
     noun: 'local',
     verb: 'sync',
     args: [
-      { name: 'action', required: true, description: 'connect | fetch | status | pull | diff | resolve | push | request | disconnect' },
-      { name: 'items', required: false, description: 'kind/name … to pull or push, the one to diff or resolve, or show | apply | close after request' },
+      { name: 'action', required: true, description: 'connect | fetch | status | pull | diff | resolve | push | request | map-model | disconnect' },
+      { name: 'items', required: false, description: 'kind/name … to pull or push, the one to diff or resolve, show | apply | close after request, or the local and workspace models after map-model' },
     ],
     flags: {
       platform: 'string',
@@ -994,6 +1012,7 @@ export const localSync: Command = {
       renders: 'boolean',
       screenshots: 'string',
       trace: 'string',
+      remove: 'boolean',
     },
     aliases: { t: 'title', d: 'description' },
     summary: 'Link the project to a platform workspace, pull and merge what you choose, and propose changes back',
@@ -1024,6 +1043,8 @@ export const localSync: Command = {
       'frontera local sync request apply',
       'frontera local sync request apply --force --reason "hotfix, checked by hand"',
       'frontera local sync request close',
+      'frontera local sync map-model llama-4-70b claude-haiku-5-5',
+      'frontera local sync map-model llama-4-70b --remove',
       'frontera local sync disconnect --forget-link',
     ],
     offline: true,
@@ -1032,7 +1053,7 @@ export const localSync: Command = {
     const action = ctx.positional[0]
     const run = action ? SUBCOMMANDS[action] : undefined
     const named = action ? `\`${action}\`` : '(none given)'
-    if (!run) throw new UsageError(`unknown sync action ${named}`, 'use connect, fetch, status, pull, diff, resolve, push, request or disconnect')
+    if (!run) throw new UsageError(`unknown sync action ${named}`, 'use connect, fetch, status, pull, diff, resolve, push, request, map-model or disconnect')
     return run(ctx)
   },
 }

package/src/commands/registry.ts

@@ -222,7 +222,8 @@ export function nounSummary(noun: string): string {
 
 const KEYS_ARE_SETTINGS_ONLY =
   'organization keys are managed in Organization settings → API Keys, workspace keys in '
-  + 'Workspace settings → API Keys — by a signed-in administrator, never by the CLI: a '
+  + 'Workspace settings → API Keys, and an agent’s server and public website keys under the '
+  + 'agent’s API keys — by a signed-in administrator, never by the CLI: a '
   + 'credential that mints credentials is the escalation that separation exists to prevent'
 
 /**

package/src/flag-help.ts

@@ -276,6 +276,7 @@ export const FLAG_HELP: Readonly<Record<string, string>> = {
   conflicts: 'the conflicts the picks were chosen against, as `diff --json` names them; refused if they moved',
   'from-workspace': 'start the project from a platform workspace instead of the examples',
   'no-sample-data': 'do not generate sample rows for the pulled Blueprint',
+  'no-kit': 'leave out the Frontera skills (the kit) that local init vendors into the project; for a machine that uses the installed plugin instead',
   'keep-sample-data': 'leave the sample datasets as they are; by default they are made again (same seed, rows and day) after a pull that brings Blueprint items, or when an older generator made them',
   'remake-sample-data': 'make the sample datasets again with the newest sample rules (same seed, rows and day), even the ones a pull wrote, which local dev otherwise keeps as pulled',
   synthetic: 'generate sample rows for the Blueprint: values fit each property, links stay consistent',

package/src/local/local-case-evidence.ts

@@ -11,8 +11,9 @@ import type { CaseResult } from './local-test-runner'
  * matching traces by their time.
  *
  * Traces are kept by the local traces store, outside the platform database:
- * `local check` rolls back the database after its tests (the conversation goes
- * with it), and the trace stays readable (`trace_get`, Studio's Traces page).
+ * `local check` rolls back the database after its tests, keeping the run
+ * history (the conversation included) unless that fails, and the trace stays
+ * readable either way (`trace_get`, Studio's Traces page).
  */
 export interface CaseEvidence {
   conversationId?: string

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

@@ -6,6 +6,7 @@ import { writeFileAtomic } from '../fs-atomic'
 import { loadHashes } from './local-applied'
 import { appDeployments, appsLostByRestore, appsLostWords, markAppsLostByRestore, type AppLostByRestore } from './local-app-restore'
 import { execInContainer, queryInContainer } from './local-docker'
+import { dumpHistory, historyWords, loadHistory, type HistoryCarried } from './local-history-carry'
 import { POSTGRES_DB, POSTGRES_USER } from './local-env'
 import type { LocalProject } from './local-project'
 import { carrySecrets, readSecrets, type QueryFn, type SecretsCarried } from './local-secret-carry'
@@ -34,6 +35,12 @@ import { containerName } from './local-supervisor'
  * encrypted under, copied as stored), unless it is asked for the baseline's
  * (`secrets: 'baseline'`, `frontera local snapshot restore --exact`).
  *
+ * The run history is what happened, not test data either: conversations,
+ * Agent sessions and runs, workflow and Function runs and evaluation runs are
+ * kept as they are now (`local-history-carry.ts`), so a change's results can be
+ * compared with the last ones, unless the baseline's are asked for
+ * (`history: 'baseline'`, `--exact`). The records those runs wrote go back.
+ *
  * The service, job engine and runner keep running: connections to the
  * database are refused for the second or two it takes (`ALLOW_CONNECTIONS
  * false`), the open ones ended (`pg_terminate_backend`), and the pools
@@ -103,6 +110,8 @@ export interface SnapshotOutcome {
   appsLost?: AppLostByRestore[]
   /** restore: the workspace secrets kept as they were before it, or `baseline` when the baseline's were put back. */
   secrets?: (SecretsCarried & { mode: 'keep' }) | { mode: 'baseline' }
+  /** restore: the run history kept as it was before it, or `baseline` when the baseline's was put back. */
+  history?: (HistoryCarried & { mode: 'keep' }) | { mode: 'baseline' }
 }
 
 /** The secrets part of a restore's line: what was kept, what has to be set again, or that the baseline's are back. */
@@ -284,11 +293,12 @@ function changedSince(baseline: string | null, current: string | null): number {
  * ended, the database dropped and made again from the baseline, the cache
  * emptied. The CLI's record of what is applied is put back with it.
  */
-export async function restoreBaseline(project: LocalProject, organizationId: string, deps: SnapshotDeps = {}, opts: { secrets?: RestoreSecrets } = {}): Promise<SnapshotOutcome> {
+export async function restoreBaseline(project: LocalProject, organizationId: string, deps: SnapshotDeps = {}, opts: { secrets?: RestoreSecrets; history?: RestoreSecrets } = {}): Promise<SnapshotOutcome> {
   const exec = deps.exec ?? execInContainer
   // A stand-in `exec` without a stand-in `query` carries nothing: tests never reach docker.
   const query = deps.query ?? (deps.exec ? undefined : queryInContainer)
   const keepSecrets = (opts.secrets ?? 'keep') === 'keep'
+  const keepHistory = (opts.history ?? 'keep') === 'keep'
   const now = deps.now ?? Date.now
   const psql = psqlFor(project, exec)
   const stored = readBaseline(project, organizationId)
@@ -299,14 +309,18 @@ export async function restoreBaseline(project: LocalProject, organizationId: str
     // The secrets as they are now, read before the database goes: configuration, kept across the restore.
     const pg = containerName(project, 'postgres')
     const held = keepSecrets && query ? readSecrets(query, pg) : null
+    // What happened since the baseline, dumped in the container: kept across the restore too.
+    const happened = keepHistory && query ? dumpHistory(query, pg) : null
     psql(refuse(POSTGRES_DB, false))
     psql(terminate(POSTGRES_DB))
     if (!psql(`DROP DATABASE ${POSTGRES_DB} WITH (FORCE)`)) {
       psql(refuse(POSTGRES_DB, true))
+      if (happened && query && !('problem' in happened)) query(pg, ['rm', '-f', happened.file])
       return { ok: false, ms: now() - started, note: `couldn’t drop ${POSTGRES_DB} to restore it; the database is as the tests left it (see \`frontera local logs postgres\`)` }
     }
     // A new database takes connections: nothing is left refused, whichever way this ends.
     if (!copyWhileHeld(psql, POSTGRES_DB, BASELINE_DB)) {
+      if (happened && query && !('problem' in happened)) query(pg, ['rm', '-f', happened.file])
       return { ok: false, ms: now() - started, note: `the database was dropped and couldn’t be made again from ${BASELINE_DB}: run \`frontera local snapshot restore\` to try again, or \`frontera local reset\`` }
     }
     // Before the cache is emptied and the service reads them: the secrets as they were.
@@ -315,6 +329,11 @@ export async function restoreBaseline(project: LocalProject, organizationId: str
       : held && query
         ? { mode: 'keep', ...('problem' in held ? { ok: false, kept: 0, notKept: [], problem: held.problem } : carrySecrets(query, pg, held)) }
         : undefined
+    const history: SnapshotOutcome['history'] = !keepHistory
+      ? { mode: 'baseline' }
+      : happened && query
+        ? { mode: 'keep', ...('problem' in happened ? { ok: false, rows: 0, notKept: 0, problem: happened.problem } : loadHistory(query, pg, happened)) }
+        : undefined
     // The service's cache holds rows of the database that was dropped.
     exec(`frontera-${project.id}-cache`, ['redis-cli', 'FLUSHALL'])
     await settle(deps)
@@ -335,9 +354,10 @@ export async function restoreBaseline(project: LocalProject, organizationId: str
     // Written last: a watching `local dev` reads it to take the record above.
     writeBaseline(project, { ...stored, restoredAt, restoreMs: ms })
     const kept = secretsWords(secrets)
+    const ran = historyWords(history)
     const lostApps = appsLostWords(appsLost)
-    const tail = `${reapply ? `; ${reapply} item${reapply === 1 ? '' : 's'} applied after the baseline will apply again on the next \`frontera local dev\`` : ''}${lostApps ? `; ${lostApps}` : ''}${kept ? `; ${kept}` : ''}`
-    const withSecrets = secrets ? { secrets } : {}
+    const tail = `${reapply ? `; ${reapply} item${reapply === 1 ? '' : 's'} applied after the baseline will apply again on the next \`frontera local dev\`` : ''}${lostApps ? `; ${lostApps}` : ''}${kept ? `; ${kept}` : ''}${ran ? `; ${ran}` : ''}`
+    const withSecrets = { ...(secrets ? { secrets } : {}), ...(history ? { history } : {}) }
     const counted = { reapply: reapply + appsLost.length, ...(appsLost.length ? { appsLost } : {}) }
     if (!answering) return { ok: false, ms, ...counted, ...withSecrets, note: `restored the database (${ms} ms), but the service isn’t answering since: see \`frontera local logs service\`${tail}` }
     return { ok: true, ms, ...counted, ...withSecrets, note: `restored the database as applied (${ms} ms)${tail}` }

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

@@ -875,7 +875,8 @@ async function localModels(local: { serviceUrl: string; creds: LocalCredentials
  * A knowledge base: created when the runtime has none by its name, given the
  * file's settings (retrieval mode, chunking, top-K and threshold, hybrid
  * search and reranking, extraction and OCR), then the folder's documents the
- * base does not hold yet are uploaded.
+ * base does not hold yet are uploaded, and those edited here since are
+ * uploaded again in place of the runtime's older copy.
  */
 /**
  * What to say of a knowledge base with no documents in its folder: an Agent
@@ -987,7 +988,7 @@ export async function applyKnowledge(
     return await done({ ok: true, output: '' })
   }
   const sources = await run(['knowledge', 'sources', name, '--json', ...p])
-  const listedSources = parseJson<Array<{ id?: string; fileName?: string; folderId?: string | null; status?: string; updatedAt?: string }>>(sources.output) ?? []
+  const listedSources = parseJson<Array<{ id?: string; fileName?: string; folderId?: string | null; status?: string; updatedAt?: string; sizeBytes?: number | null }>>(sources.output) ?? []
   const key = local?.creds.workspaceKey
   const http = async (method: string, path: string, body?: FormData | Record<string, unknown>) => {
     const res = await fetch(new URL(path, local!.serviceUrl), {
@@ -1008,15 +1009,54 @@ export async function applyKnowledge(
   // A document the runtime holds pending or processing with no ingestion behind it (a rollback took its
   // reading with the database it replaced) is queued to be read again: uploading it again would add a second.
   if (key && id) notes.push(...(await requeueStuckDocuments(project, local!, name, id, listedSources)))
-  const fresh = documents.filter((f) => !have.has(f))
-  if (!fresh.length) return await done({ ok: true, output: '' })
+  // A document edited in place keeps its name: the runtime's older copy is found by content, uploaded over, then taken off.
+  const { loadUploadedDocuments, saveUploadedDocuments, staleDocuments } = await import('./local-knowledge-uploads')
+  const { sha256Of } = await import('./local-knowledge-documents')
+  const contents = documents.flatMap((path) => {
+    try {
+      const bytes = readFileSync(join(project.root, dirname(target.file), path))
+      return [{ path, sha256: sha256Of(bytes), bytes: bytes.byteLength }]
+    } catch {
+      return []
+    }
+  })
+  const onRuntime = listedSources.flatMap((s) => (s.id ? [{ id: s.id, path: documentPath(s.folderId ? folders.get(s.folderId) : null, s.fileName ?? ''), sizeBytes: s.sizeBytes }] : []))
+  const uploaded = key && id ? loadUploadedDocuments(project.stateDir, local!.creds.organizationId, id) : {}
+  const stale = staleDocuments(contents, onRuntime, uploaded)
+  if (stale.length && (!key || !id)) {
+    notes.push(`  warning: Knowledge base ${name}: ${stale.map((s) => s.path).join(', ')} changed here, but the runtime keeps ${stale.length === 1 ? 'its older copy' : 'their older copies'} until it has a workspace key`)
+  }
+  const replacing = key && id ? stale : []
+  // What the runtime now holds for each document, recorded so the next apply tells an edit from no change.
+  const record = async () => {
+    if (!key || !id) return
+    const now = rows<{ id?: string; fileName?: string; folderId?: string | null; createdAt?: string }>(await http('GET', `/v1/workspace-knowledge/${encodeURIComponent(id)}/sources`).catch(() => null))
+    // Folders this apply made are not in `folders` yet.
+    const filedNow = now.some((s) => s.folderId && !folders.has(s.folderId))
+      ? folderPaths((((await http('GET', `/v1/workspace-knowledge/${encodeURIComponent(id)}/folders`).catch(() => null))?.folders ?? []) as Array<{ id: string; parentId?: string | null; name: string }>))
+      : folders
+    const next: typeof uploaded = {}
+    for (const doc of contents) {
+      const copies = now.filter((s) => s.id && documentPath(s.folderId ? filedNow.get(s.folderId) : null, s.fileName ?? '') === doc.path)
+      const newest = copies.sort((a, b) => String(b.createdAt ?? '').localeCompare(String(a.createdAt ?? '')))[0]
+      if (newest?.id) next[doc.path] = { sourceId: newest.id, sha256: doc.sha256 }
+    }
+    saveUploadedDocuments(project.stateDir, local!.creds.organizationId, id, next)
+  }
+  const fresh = [...documents.filter((f) => !have.has(f)), ...replacing.map((s) => s.path)]
+  if (!fresh.length) {
+    await record()
+    return await done({ ok: true, output: '' })
+  }
   const top = fresh.filter((f) => !f.includes('/'))
   const filed = fresh.filter((f) => f.includes('/'))
   const lines: string[] = []
+  const sent = new Set<string>()
   if (top.length) {
-    const uploaded = await run(['knowledge', 'upload', name, ...top.map((f) => join(dirname(target.file), f)), ...p])
-    if (!uploaded.ok) return await done(uploaded)
-    if (uploaded.output.trim()) lines.push(uploaded.output.trim())
+    const uploadedTop = await run(['knowledge', 'upload', name, ...top.map((f) => join(dirname(target.file), f)), ...p])
+    if (!uploadedTop.ok) return await done(uploadedTop)
+    if (uploadedTop.output.trim()) lines.push(uploadedTop.output.trim())
+    for (const f of top) sent.add(f)
   }
   if (filed.length && (!key || !id)) {
     notes.push(`  warning: Knowledge base ${name}: ${filed.length} document${filed.length === 1 ? ' in a folder waits' : 's in folders wait'} until the runtime has a workspace key`)
@@ -1048,11 +1088,23 @@ export async function applyKnowledge(
         form.append('folderId', await folderFor(folder!))
         await http('POST', `/v1/workspace-knowledge/${encodeURIComponent(id!)}/sources`, form)
         lines.push(`  uploaded ${path}`)
+        sent.add(path)
       } catch (err) {
         notes.push(`  warning: Knowledge base ${name}: ${path} wasn’t uploaded (${(err as Error).message})`)
       }
     }
   }
+  // The older copies come off only once the new content is up, so the base is never without the document.
+  for (const doc of replacing) {
+    if (!sent.has(doc.path)) continue
+    try {
+      for (const sourceId of doc.replaces) await http('DELETE', `/v1/workspace-knowledge/${encodeURIComponent(id!)}/sources/${encodeURIComponent(sourceId)}`)
+      lines.push(`  replaced ${doc.path}: it changed here`)
+    } catch (err) {
+      notes.push(`  warning: Knowledge base ${name}: ${doc.path}’s older copy wasn’t taken off (${(err as Error).message}); search may find both`)
+    }
+  }
+  await record()
   return await done({ ok: true, output: lines.join('\n') })
 }
 

package/src/local/local-env.ts

@@ -118,6 +118,21 @@ export const SERVICE_OUTBOUND = [
   'AUTOMATION_RUNNER_URL',
 ] as const
 
+/** The service's settings for a hosted key custodian (OpenBao / Vault transit), blanked on the local runtime. */
+export const KEY_CUSTODIAN_SETTINGS = [
+  'BAO_ADDR',
+  'BAO_TOKEN',
+  'BAO_CACERT',
+  'VAULT_ADDR',
+  'VAULT_TOKEN',
+  'SECRETS_TRANSIT_AUTH',
+  'SECRETS_TRANSIT_MOUNT',
+  'SECRETS_TRANSIT_KEY',
+  'SECRETS_TRANSIT_K8S_ROLE',
+  'SECRETS_TRANSIT_K8S_MOUNT',
+  'SECRETS_TRANSIT_K8S_TOKEN_FILE',
+] as const
+
 /** What the Function runner dials on this machine. */
 export const RUNNER_OUTBOUND = ['SERVICE_URL', 'S3_ENDPOINT', 'INNGEST_BASE_URL'] as const
 
@@ -182,6 +197,12 @@ export function serviceEnv(args: {
     DAYTONA_API_KEY: '',
     DAYTONA_API_URL: '',
     DAYTONA_TARGET: '',
+    // The runtime holds its own keys: ENCRYPTION_KEY from its secrets.json wraps every data key.
+    // A checkout's .env can name a hosted OpenBao instead (the service loads it from its
+    // directory), and every data key wrapped there is unreadable once that OpenBao goes away.
+    // Empty values win over the file.
+    SECRETS_KEY_PROVIDER: 'env',
+    ...Object.fromEntries(KEY_CUSTODIAN_SETTINGS.map((key) => [key, ''])),
     // 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-history-carry.ts

@@ -0,0 +1,103 @@
+import { randomBytes } from 'node:crypto'
+
+import { POSTGRES_DB, POSTGRES_USER } from './local-env'
+import type { QueryFn } from './local-secret-carry'
+
+/**
+ * The run history carried across a database restore.
+ *
+ * A restore (`local check`'s rollback, `frontera local snapshot restore`)
+ * throws away what was written since the baseline. What happened is not test
+ * data: the conversations (an Agent test case's included), Agent sessions and
+ * runs, workflow and Function runs and evaluation runs are how a change is
+ * compared with the one before it. So a restore keeps them as they are now,
+ * unless asked for the baseline's (`--exact`). The records those runs wrote
+ * are still rolled back.
+ *
+ * The rows are dumped inside the database container before the database is
+ * dropped (`pg_dump --data-only --inserts --on-conflict-do-nothing`), then
+ * loaded into the restored one, a row a statement: a row the baseline holds
+ * stays as the baseline holds it, and a row that names something the restore
+ * took away (a work item a test made) is left out and counted. Nothing leaves
+ * the container, and the dump is removed once loaded.
+ */
+
+/** The tables that hold what happened, parents before children (pg_dump orders them by their keys too). */
+export const HISTORY_TABLES = [
+  'conversations',
+  'messages',
+  'message_feedback',
+  'conversation_labels',
+  'conversation_files',
+  'trace_annotations',
+  'session_handoffs',
+  'agent_sessions',
+  'agent_session_events',
+  'agent_session_analyses',
+  'agent_timeline_events',
+  'agent_exchanges',
+  'pi_runs',
+  'pi_run_events',
+  'pi_model_calls',
+  'workflow_runs',
+  'workflow_run_nodes',
+  'workflow_step_test_results',
+  'function_runs',
+  'function_run_steps',
+  'ctx_agent_turns',
+  'dataset_runs',
+  'dataset_run_items',
+  'knowledge_eval_runs',
+  'knowledge_eval_run_fixtures',
+  'scheduled_task_runs',
+  'agent_routine_runs',
+] as const
+
+/** The history dumped from the current database, waiting in the container for the restored one. */
+export interface HistoryHeld {
+  file: string
+  rows: number
+}
+
+export interface HistoryCarried {
+  ok: boolean
+  /** Rows dumped before the restore (those the baseline already held included). */
+  rows: number
+  /** Rows left out: they name something the restored database lacks. */
+  notKept: number
+  /** Why nothing was carried, when it failed. */
+  problem?: string
+}
+
+const sh = (script: string) => ['sh', '-c', script]
+
+/** Dump the history tables as they are now into a file in the container, or why it could not be. */
+export function dumpHistory(query: QueryFn, container: string): HistoryHeld | { problem: string } {
+  const file = `/tmp/frontera-history-${randomBytes(6).toString('hex')}.sql`
+  const tables = HISTORY_TABLES.map((t) => `-t public.${t}`).join(' ')
+  const res = query(container, sh(`pg_dump -U ${POSTGRES_USER} -d ${POSTGRES_DB} --data-only --inserts --on-conflict-do-nothing ${tables} -f ${file} || exit 1; grep -c '^INSERT INTO' ${file}; exit 0`))
+  const rows = Number.parseInt(res.out.trim().split('\n').pop() ?? '', 10)
+  if (!res.ok || !Number.isFinite(rows)) {
+    query(container, sh(`rm -f ${file}`))
+    return { problem: 'the run history could not be read' }
+  }
+  return { file, rows }
+}
+
+/** Load the dumped history into the restored database, then remove the dump. */
+export function loadHistory(query: QueryFn, container: string, held: HistoryHeld): HistoryCarried {
+  // No ON_ERROR_STOP: each row is its own statement, and one the restored database refuses is counted, not fatal.
+  const res = query(container, sh(`psql -U ${POSTGRES_USER} -d ${POSTGRES_DB} -q -f ${held.file} 2>&1 | grep -c 'ERROR:'; rm -f ${held.file}`))
+  const notKept = Number.parseInt(res.out.trim().split('\n').pop() ?? '', 10)
+  if (!res.ok || !Number.isFinite(notKept)) return { ok: false, rows: held.rows, notKept: 0, problem: 'the run history could not be written back' }
+  return { ok: true, rows: held.rows, notKept }
+}
+
+/** What a restore does with the run history, in words. */
+export function historyWords(history: (HistoryCarried & { mode: 'keep' }) | { mode: 'baseline' } | undefined): string {
+  if (!history) return ''
+  if (history.mode === 'baseline') return 'the run history is as the baseline holds it (--exact)'
+  if (!history.ok) return `the run history couldn’t be kept (${history.problem ?? 'unknown'}), so conversations and runs are as the baseline holds them`
+  const kept = 'kept the run history (conversations, runs and evaluations)'
+  return history.notKept ? `${kept}, except ${history.notKept} row${history.notKept === 1 ? '' : 's'} naming records the rollback took away` : kept
+}

package/src/local/local-key-custodian.ts

@@ -0,0 +1,64 @@
+import { withFix } from './fix-words'
+
+/**
+ * The local runtime's key custodian, as its service reports it on
+ * `/v1/health`: whether the keys that lock its secrets and governed Action
+ * records answer. A runtime holds its own keys (`serviceEnv` pins the env
+ * custodian); one whose data keys were wrapped by a hosted OpenBao it no
+ * longer reaches cannot read them again, so the only fix is a clean runtime.
+ * Read by `local start` (which refuses), `local status`, `local check` and
+ * Forge's Runtime page. The report carries categories and a count, never a
+ * key, token or address.
+ */
+
+export interface KeyCustodianReport {
+  state: 'ready' | 'failed' | 'none'
+  provider: 'env' | 'transit' | null
+  reason?: 'unreachable' | 'misconfigured' | 'unreadable-keys'
+  foreignKeys: number
+}
+
+/** What fixes a broken custodian: nothing else can unwrap those data keys. */
+export const KEY_CUSTODIAN_FIX = 'run `frontera local reset` for a clean runtime that holds its own keys (it wipes this runtime’s data)'
+
+/** How every custodian problem starts, so a failed start's error is recognised as one. */
+export const KEY_CUSTODIAN_LEAD = 'the runtime’s encryption keys can’t be read'
+
+/** The problem a report describes, with its fix; null when the keys answer (or the report is from a service that has none). */
+export function keyCustodianProblem(report: KeyCustodianReport | null | undefined): string | null {
+  if (!report) return null
+  const what = 'so its secrets and governed Action records can’t be read or saved'
+  if (report.foreignKeys > 0) {
+    const keys = report.foreignKeys === 1 ? '1 data key was' : `${report.foreignKeys} data keys were`
+    return withFix(`${KEY_CUSTODIAN_LEAD}: ${keys} locked by a key service it doesn’t hold (an OpenBao named in a checkout’s .env), ${what}`, KEY_CUSTODIAN_FIX)
+  }
+  if (report.state !== 'failed') return null
+  const why =
+    report.reason === 'unreachable'
+      ? 'its key service doesn’t answer'
+      : report.reason === 'unreadable-keys'
+        ? 'its stored data keys don’t open with the keys in .frontera/local/secrets.json'
+        : 'its key service is set up wrong'
+  return withFix(`${KEY_CUSTODIAN_LEAD}: ${why}, ${what}`, KEY_CUSTODIAN_FIX)
+}
+
+/** Whether a failed start's error is a custodian problem (its fix is a reset, not a restart). */
+export function isKeyCustodianProblem(error: string | null | undefined): boolean {
+  return !!error && error.includes(KEY_CUSTODIAN_LEAD)
+}
+
+/**
+ * The custodian problem the running service reports, or null: its keys
+ * answer, it can't be reached (other checks say so), or it is a release from
+ * before the report.
+ */
+export async function runtimeKeyCustodianProblem(serviceUrl: string, doFetch: (url: string, init?: RequestInit) => Promise<Response> = fetch): Promise<string | null> {
+  try {
+    const res = await doFetch(`${serviceUrl.replace(/\/+$/, '')}/v1/health`, { signal: AbortSignal.timeout(3000) })
+    if (!res.ok) return null
+    const body = (await res.json().catch(() => null)) as { data?: { keyCustodian?: KeyCustodianReport | null } } | null
+    return keyCustodianProblem(body?.data?.keyCustodian)
+  } catch {
+    return null
+  }
+}

package/src/local/local-keys.ts

@@ -21,8 +21,8 @@ const SERVICE = 'frontera-local-model-key'
 export interface ProviderSpec {
   id: string
   label: string
-  /** The variable the service reads for this provider. */
-  envVar: string
+  /** The variable the service reads for this provider; none for a key only an organization holds. */
+  envVar?: string
 }
 
 /** Providers the local runtime can pass a key to; mirrors the service's built-in providers. */
@@ -32,6 +32,8 @@ export const LOCAL_PROVIDERS: readonly ProviderSpec[] = [
   { id: 'openrouter', label: 'OpenRouter', envVar: 'OPENROUTER_API_KEY' },
   { id: 'google', label: 'Google Gemini', envVar: 'GOOGLE_GENERATIVE_AI_API_KEY' },
   { id: 'cohere', label: 'Cohere (reranking)', envVar: 'COHERE_API_KEY' },
+  // Agents' web search; stored as the local organization's own key, never an environment variable.
+  { id: 'openrouter-web-search', label: 'OpenRouter web search' },
 ]
 
 export function findProvider(id: string): ProviderSpec | undefined {
@@ -100,7 +102,7 @@ export function providerEnv(): Record<string, string> {
   const env: Record<string, string> = {}
   for (const p of LOCAL_PROVIDERS) {
     const key = getKey(p.id)
-    if (key) env[p.envVar] = key
+    if (key && p.envVar) env[p.envVar] = key
   }
   return env
 }

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

@@ -1,5 +1,5 @@
 import { randomBytes } from 'node:crypto'
-import { existsSync, lstatSync, readdirSync, readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync } from 'node:fs'
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync } from 'node:fs'
 import { dirname, join, resolve, sep } from 'node:path'
 
 import { KNOWLEDGE_DOCUMENT } from './local-dev-references'
@@ -23,10 +23,10 @@ import { rows } from './local-sync-remote'
  * - a name already in the folder, unless the request says to replace it;
  * - a folder or file that is a symbolic link, or resolves outside `knowledge/`.
  *
- * Removing a document takes its file out of the folder. The apply only adds
- * what the runtime lacks, so the server takes the runtime's copy off first
- * (`removeRuntimeCopies`), as it does before a replaced file is written, so
- * the next apply uploads the new content.
+ * Removing a document takes its file out of the folder, and the server takes
+ * the runtime's copy off (`removeRuntimeCopies`), as it does before a replaced
+ * file is written. A file edited in place (by a coding agent, say) the apply
+ * uploads again itself, then takes the older copy off (`staleDocuments`).
  */
 
 /** The extensions `local dev` uploads into a knowledge base, as `KNOWLEDGE_DOCUMENT` matches them. */
@@ -211,6 +211,63 @@ export async function removeRuntimeCopies(call: ServiceCall, knowledgeId: string
   return copies.length
 }
 
+/** What the last apply uploaded for each document, by its path: the runtime's copy and the content it was. */
+export type UploadedDocuments = Record<string, { sourceId: string; sha256: string }>
+
+const uploadsPath = (stateDir: string) => join(stateDir, 'knowledge-uploads.json')
+
+/** The documents the apply uploaded into one knowledge base on this runtime; nothing after a reset (another organization). */
+export function loadUploadedDocuments(stateDir: string, organizationId: string, knowledgeId: string): UploadedDocuments {
+  try {
+    const saved = JSON.parse(readFileSync(uploadsPath(stateDir), 'utf8')) as { organizationId?: string; bases?: Record<string, UploadedDocuments> }
+    if (saved.organizationId === organizationId) return saved.bases?.[knowledgeId] ?? {}
+  } catch {
+    // Missing or unreadable: no copy counts as recorded.
+  }
+  return {}
+}
+
+export function saveUploadedDocuments(stateDir: string, organizationId: string, knowledgeId: string, uploaded: UploadedDocuments): void {
+  let bases: Record<string, UploadedDocuments> = {}
+  try {
+    const saved = JSON.parse(readFileSync(uploadsPath(stateDir), 'utf8')) as { organizationId?: string; bases?: Record<string, UploadedDocuments> }
+    if (saved.organizationId === organizationId && saved.bases) bases = saved.bases
+  } catch {
+    // Starts afresh.
+  }
+  try {
+    mkdirSync(stateDir, { recursive: true })
+    writeFileSync(uploadsPath(stateDir), `${JSON.stringify({ organizationId, bases: { ...bases, [knowledgeId]: uploaded } })}\n`, { mode: 0o600 })
+  } catch {
+    // Losing this only means the next apply judges an edit by the copy's size.
+  }
+}
+
+/**
+ * The documents the runtime holds an older copy of, each with the copies to
+ * take off once the new content is up. A copy the last apply recorded is
+ * older when the file's content differs from what was uploaded; a copy no
+ * apply here recorded (uploaded before the record, or by hand) is older when
+ * its size differs, and otherwise taken as the file's.
+ */
+export function staleDocuments(
+  local: Array<{ path: string; sha256: string; bytes: number }>,
+  runtime: Array<{ id: string; path: string; sizeBytes?: number | null }>,
+  uploaded: UploadedDocuments,
+): Array<{ path: string; replaces: string[] }> {
+  const out: Array<{ path: string; replaces: string[] }> = []
+  for (const doc of local) {
+    const copies = runtime.filter((s) => s.path === doc.path)
+    if (!copies.length) continue
+    const was = uploaded[doc.path]
+    const stale = was && copies.some((c) => c.id === was.sourceId)
+      ? was.sha256 !== doc.sha256
+      : copies.length === 1 && typeof copies[0]!.sizeBytes === 'number' && copies[0]!.sizeBytes !== doc.bytes
+    if (stale) out.push({ path: doc.path, replaces: copies.map((c) => c.id) })
+  }
+  return out
+}
+
 /** The project's documents for a knowledge base, each with whether the runtime holds it yet. */
 export function projectDocuments(root: string, folder: string, onRuntime: ReadonlySet<string> | null): Array<{ path: string; onRuntime: boolean | null }> {
   return documentPaths(root, folder).map((path) => ({ path, onRuntime: onRuntime ? onRuntime.has(path) : null }))