@frontera-sdk/cli 1.52.22 → 1.52.24

package/src/local/local-supervisor.ts

@@ -0,0 +1,561 @@
+import type { ChildProcess } from 'node:child_process'
+import { appendFileSync, existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+import {
+  containerState,
+  copyFromContainer,
+  execInContainer,
+  followLogs,
+  imagePresent,
+  pullImage,
+  removeContainer,
+  runContainer,
+  startContainer,
+  stopContainer,
+} from './local-docker'
+import {
+  CATALOG_DB,
+  databaseUrl,
+  fromContainer,
+  RUNNER_OUTBOUND,
+  SERVICE_OUTBOUND,
+  HOST_FROM_CONTAINER,
+  loadOrCreateSecrets,
+  POSTGRES_DB,
+  POSTGRES_USER,
+  readConfig,
+  runnerEnv,
+  serviceEnv,
+  type LocalConfig,
+  type LocalSecrets,
+} from './local-env'
+import { keylessEmbeddings, providerEnv } from './local-keys'
+import { applyProviderSetup, readProviderSetup, rememberSlugs, writeProviderSetup } from './local-providers'
+import type { PortBlock } from './local-ports'
+import { startProcess, stopProcess, waitForHttp } from './local-process'
+import type { LocalProject } from './local-project'
+import { startLocalEmbeddings } from './local-embeddings'
+import { LOCAL_TRACE_KEYS, startLocalTraces } from './local-traces'
+import { copyDocs, customerDocsBundle, IMAGE_DOCS_PATH } from './local-docs'
+import { keepSchemas, type SchemaSource } from './local-schemas'
+import { applyModelKeys, ensureBlueprint, ensureOrgKey, ensureProviderModels, retireLocalModel, seedLocalRuntime, signIn } from './local-seed'
+import {
+  logPath,
+  readState,
+  updateComponent,
+  writeState,
+  type ComponentName,
+  type ComponentState,
+  type LocalState,
+} from './local-state'
+import { newSessionToken, startStudioServer } from './local-studio-server'
+import { buildStudio, studioAssetsDir, studioBuildStale } from './local-studio-assets'
+
+/**
+ * The local runtime's supervisor: one detached process per solution directory.
+ *
+ * It starts the components in dependency order, waits for each to be healthy
+ * before starting the next, seeds the runtime once, serves Studio, and on
+ * SIGTERM stops everything it started. Containers are stopped, not removed
+ * with their volumes, so `start` after `stop` comes back with the same data —
+ * the way `supabase stop` keeps volumes unless asked not to.
+ *
+ * Images are pinned: Postgres with pgvector and the Inngest dev server at the
+ * versions the platform's own compose files and chart use.
+ */
+
+/** The registry the release workflow publishes the platform images to. */
+export const DEFAULT_REGISTRY = 'ghcr.io/sebati-ai'
+
+export const IMAGES = {
+  postgres: 'pgvector/pgvector:pg17',
+  cache: 'redis:7-alpine',
+  storage: 'rustfs/rustfs:1.0.0',
+  jobs: 'inngest/inngest:v1.45.1',
+  service: (version: string, registry = DEFAULT_REGISTRY) => `${registry}/agents-service:${version}`,
+  runner: (version: string, registry = DEFAULT_REGISTRY) => `${registry}/agents-automation-runner:${version}`,
+} as const
+
+export const containerName = (project: LocalProject, component: ComponentName) =>
+  `frontera-${project.id}-${component}`
+
+export const volumeName = (project: LocalProject) => `frontera-${project.id}-db`
+
+interface Running {
+  children: Map<ComponentName, ChildProcess>
+  containers: Set<string>
+  studio?: ReturnType<typeof startStudioServer>
+  embeddings?: ReturnType<typeof startLocalEmbeddings>
+  traces?: ReturnType<typeof startLocalTraces>
+}
+
+export async function runSupervisor(project: LocalProject, ports: PortBlock, sessionToken = newSessionToken()): Promise<void> {
+  const config = readConfig(project)
+  if (!config) throw new Error('no local runtime config; run `frontera local start`')
+  const secrets = loadOrCreateSecrets(project)
+  const previous = readState(project)
+  const enabled = (c: ComponentName) => !config.exclude.includes(c)
+
+  let state: LocalState = {
+    version: 1,
+    projectId: project.id,
+    root: project.root,
+    mode: config.mode,
+    platformVersion: config.platformVersion,
+    supervisorPid: process.pid,
+    phase: 'starting',
+    startedAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+    ports,
+    components: (['postgres', 'storage', 'service', 'jobs', 'runner', 'studio'] as ComponentName[]).map(
+      (name): ComponentState => ({
+        name,
+        status: enabled(name) ? 'starting' : 'off',
+        kind: name === 'studio' ? 'supervisor' : name === 'postgres' || name === 'jobs' || name === 'storage' ? 'container' : config.mode === 'source' ? 'process' : 'container',
+        port: ports[name],
+        detail: enabled(name) ? undefined : 'excluded',
+      }),
+    ),
+    credentials: previous?.credentials,
+  }
+  const save = () => writeState(project, state)
+  const set = (name: ComponentName, patch: Partial<ComponentState>) => {
+    const current = state.components.find((c) => c.name === name)!
+    state = updateComponent(state, { ...current, ...patch })
+    save()
+  }
+  save()
+
+  const running: Running = { children: new Map(), containers: new Set() }
+  let stopping = false
+
+  const shutdown = async (code: number) => {
+    if (stopping) return
+    stopping = true
+    state = { ...state, phase: 'stopping' }
+    save()
+    running.studio?.stop(true)
+    running.embeddings?.stop(true)
+    running.traces?.server.stop(true)
+    for (const [name, child] of [...running.children].reverse()) {
+      await stopProcess(child.pid)
+      set(name, { status: 'stopped', pid: undefined })
+    }
+    for (const name of [...running.containers].reverse()) stopContainer(name)
+    for (const c of state.components) if (c.status === 'running' || c.status === 'starting') set(c.name, { status: 'stopped' })
+    state = { ...state, phase: 'stopped', supervisorPid: undefined }
+    save()
+    process.exit(code)
+  }
+  process.on('SIGTERM', () => void shutdown(0))
+  process.on('SIGINT', () => void shutdown(0))
+
+  const fail = async (name: ComponentName, detail: string) => {
+    set(name, { status: 'failed', detail })
+    state = { ...state, phase: 'failed', error: `${name}: ${detail}` }
+    save()
+    await shutdown(1)
+  }
+
+  try {
+    // 1. Postgres
+    await startPostgres(project, ports, secrets, running, set)
+    // Object storage before anything that uploads to it.
+    if (enabled('storage')) await startStorage(project, ports, secrets, running, set)
+    // 2. Job engine (before the service, so the service's registration lands)
+    if (enabled('jobs')) await startJobs(project, ports, running, set)
+    // Keyless embeddings answer before the service needs them.
+    running.embeddings = startLocalEmbeddings({
+      port: ports.embeddings,
+      log: (line) => {
+        try {
+          appendFileSync(logPath(project, 'studio'), `[local-embeddings] ${line}\n`)
+        } catch {
+          // Logging never fails a request.
+        }
+      },
+    })
+    // Local traces receive the service's spans and answer Studio's trace reads.
+    running.traces = startLocalTraces({
+      port: ports.traces,
+      file: join(project.stateDir, 'traces.jsonl'),
+      log: (line) => {
+        try {
+          appendFileSync(logPath(project, 'studio'), `[local-traces] ${line}\n`)
+        } catch {
+          // Logging never fails a request.
+        }
+      },
+    })
+    // 3. Service
+    await startService(project, ports, secrets, config, running, set, enabled('runner'), enabled('jobs'), enabled('storage'))
+    // The service has migrated; the catalog it reads is seeded per environment.
+    seedPluginCatalog(project)
+    // 4. Function runner
+    if (enabled('runner')) await startRunner(project, ports, secrets, config, running, set, enabled('storage'))
+    // 5. Seed once
+    if (!state.credentials) {
+      state = { ...state, phase: 'seeding' }
+      save()
+      const credentials = await seedLocalRuntime({
+        serviceUrl: `http://127.0.0.1:${ports.service}`,
+        password: secrets.ownerPassword,
+        databaseUrl: databaseUrl(secrets, ports),
+        logFile: logPath(project, 'service'),
+      })
+      state = { ...state, credentials }
+      save()
+    }
+    // Trace reads are per workspace: the local workspace reads local traces.
+    seedTraceKeys(project, state.credentials!.workspaceId)
+    // Every start: a fresh owner session for Studio, and the FDE's current model keys.
+    const serviceUrl = `http://127.0.0.1:${ports.service}`
+    const session = await signIn(serviceUrl, secrets.ownerPassword)
+    state = { ...state, credentials: await ensureOrgKey(serviceUrl, session, state.credentials!, logPath(project, 'service')) }
+    const modelProviders = await applyModelKeys({
+      serviceUrl,
+      password: secrets.ownerPassword,
+      organizationId: state.credentials!.organizationId,
+      logFile: logPath(project, 'service'),
+    })
+    await ensureProviderModels({
+      serviceUrl,
+      password: secrets.ownerPassword,
+      organizationId: state.credentials!.organizationId,
+      providers: modelProviders,
+      logFile: logPath(project, 'service'),
+    })
+    await retireLocalModel({
+      serviceUrl,
+      password: secrets.ownerPassword,
+      organizationId: state.credentials!.organizationId,
+      workspaceId: state.credentials!.workspaceId,
+      logFile: logPath(project, 'service'),
+    })
+    // The FDE's own providers, models and defaults (`frontera local providers`).
+    const setup = readProviderSetup()
+    const provided = await applyProviderSetup(
+      {
+        serviceUrl,
+        password: secrets.ownerPassword,
+        organizationId: state.credentials!.organizationId,
+        workspaceId: state.credentials!.workspaceId,
+        containerHost: config.mode === 'image' ? HOST_FROM_CONTAINER : undefined,
+      },
+      setup,
+    )
+    for (const error of provided.errors) appendFileSync(logPath(project, 'service'), `[local-providers] ${error}\n`)
+    modelProviders.push(...provided.custom.map((slug) => `custom:${slug}`))
+    const remembered = rememberSlugs(setup, provided)
+    if (JSON.stringify(remembered) !== JSON.stringify(setup)) writeProviderSetup(remembered)
+    await ensureBlueprint({
+      serviceUrl,
+      password: secrets.ownerPassword,
+      organizationId: state.credentials!.organizationId,
+      logFile: logPath(project, 'service'),
+    })
+    state = { ...state, credentials: { ...state.credentials!, session, modelProviders } }
+    save()
+    // The formats of the project's files, for the release the service runs.
+    await keepFileSchemas(project, { serviceUrl, token: state.credentials!.workspaceKey ?? session }, logPath(project, 'service'))
+    // 6. Studio. From a checkout, rebuild it first when its sources changed
+    // since the last build, so a pulled change is never served stale.
+    if (studioBuildStale(config)) {
+      set('studio', { status: 'starting' })
+      const studioLog = logPath(project, 'studio')
+      appendFileSync(studioLog, `[studio] sources changed since the last build; building Studio\n`)
+      const built = await buildStudio(config.platformSource!, studioLog)
+      if (!built) appendFileSync(studioLog, `[studio] the build failed; serving the previous build, if any\n`)
+    }
+    running.studio = startStudioServer({
+      project,
+      port: ports.studio,
+      serviceUrl: `http://127.0.0.1:${ports.service}`,
+      assetsDir: () => studioAssetsDir(config),
+      sessionToken,
+    })
+    set('studio', { status: 'running', startedAt: new Date().toISOString(), pid: process.pid })
+    state = { ...state, phase: 'ready', error: undefined }
+    save()
+  } catch (err) {
+    const failing = state.components.find((c) => c.status === 'starting')?.name ?? 'service'
+    await fail(failing, (err as Error).message)
+    return
+  }
+
+  // Watch native children: a crash is reported, not hidden.
+  for (const [name, child] of running.children) {
+    child.on('exit', (code) => {
+      if (stopping) return
+      set(name, { status: 'failed', pid: undefined, detail: `exited with code ${code ?? 'signal'}; see \`frontera local logs ${name}\`` })
+    })
+  }
+}
+
+type SetFn = (name: ComponentName, patch: Partial<ComponentState>) => void
+
+async function ensureImage(image: string, project: LocalProject, component: ComponentName): Promise<void> {
+  if (imagePresent(image)) return
+  await pullImage(image, logPath(project, component))
+}
+
+/**
+ * The Plugin catalog is seeded per environment, and a fresh database has none,
+ * so a local MCP server could not be installed. One generic "MCP server" entry,
+ * the same values the service's own tests seed; kept if it already exists.
+ */
+const MCP_CATALOG_SQL = `INSERT INTO app_catalog
+  (kind, name, display_name, description, auth_type, config_schema, multi_install, category, transport, auth_scheme,
+   supported_account_modes, oauth_metadata, binding_interaction, trigger_types, inbound_secrets)
+VALUES
+  ('mcp', 'MCP', 'MCP Server', 'External Model Context Protocol server.', 'custom', '{"type":"object","properties":{}}', true,
+   'custom', 'mcp_http', 'api_key', '["agent_owned"]', NULL, 'none', '[]', '[]')
+ON CONFLICT (kind) DO NOTHING;`
+
+function seedTraceKeys(project: LocalProject, workspaceId: string): void {
+  if (!/^[0-9a-f-]{36}$/i.test(workspaceId)) return
+  const sql = `UPDATE workspaces SET langfuse_public_key = '${LOCAL_TRACE_KEYS.publicKey}', langfuse_secret_key = '${LOCAL_TRACE_KEYS.secretKey}' WHERE id = '${workspaceId}' AND langfuse_public_key IS DISTINCT FROM '${LOCAL_TRACE_KEYS.publicKey}'`
+  execInContainer(containerName(project, 'postgres'), ['psql', '-U', POSTGRES_USER, '-d', POSTGRES_DB, '-c', sql])
+}
+
+function seedPluginCatalog(project: LocalProject): void {
+  execInContainer(containerName(project, 'postgres'), ['psql', '-U', POSTGRES_USER, '-d', POSTGRES_DB, '-c', MCP_CATALOG_SQL])
+}
+
+async function startPostgres(project: LocalProject, ports: PortBlock, secrets: LocalSecrets, running: Running, set: SetFn) {
+  const name = containerName(project, 'postgres')
+  await ensureImage(IMAGES.postgres, project, 'postgres')
+  const current = containerState(name)
+  if (current === 'exited') startContainer(name)
+  else if (current !== 'running') {
+    if (current !== 'missing') removeContainer(name)
+    runContainer({
+      name,
+      image: IMAGES.postgres,
+      projectId: project.id,
+      ports: [{ host: ports.postgres, container: 5432 }],
+      env: { POSTGRES_USER, POSTGRES_PASSWORD: secrets.postgresPassword, POSTGRES_DB },
+      volumes: [{ name: volumeName(project), path: '/var/lib/postgresql/data' }],
+      memory: '768m',
+      cpus: '1.5',
+      // Postgres defaults are sized for a server; a laptop runtime needs far less.
+      args: ['postgres', '-c', 'shared_buffers=128MB', '-c', 'max_connections=60', '-c', 'fsync=off', '-c', 'synchronous_commit=off'],
+    })
+  }
+  running.containers.add(name)
+  followLogs(name, logPath(project, 'postgres'))
+
+  // The service's agent-config cache. Without it the service works but retries
+  // a connection on every request; a 32 MB Redis is cheaper than the noise.
+  const cache = `frontera-${project.id}-cache`
+  await ensureImage(IMAGES.cache, project, 'postgres')
+  if (containerState(cache) === 'exited') startContainer(cache)
+  else if (containerState(cache) !== 'running') {
+    removeContainer(cache)
+    runContainer({
+      name: cache,
+      image: IMAGES.cache,
+      projectId: project.id,
+      ports: [{ host: ports.cache, container: 6379 }],
+      memory: '64m',
+      cpus: '0.5',
+      args: ['redis-server', '--save', '', '--appendonly', 'no', '--maxmemory', '32mb'],
+    })
+  }
+  running.containers.add(cache)
+
+  const deadline = Date.now() + 60_000
+  while (Date.now() < deadline) {
+    if (execInContainer(name, ['pg_isready', '-U', POSTGRES_USER, '-d', POSTGRES_DB])) {
+      // The vector extension the platform's migrations expect.
+      execInContainer(name, ['psql', '-U', POSTGRES_USER, '-d', POSTGRES_DB, '-c', 'CREATE EXTENSION IF NOT EXISTS vector;'])
+      // The managed datasets' catalog database; "already exists" on later starts is expected.
+      execInContainer(name, ['psql', '-U', POSTGRES_USER, '-d', POSTGRES_DB, '-c', `CREATE DATABASE ${CATALOG_DB};`])
+      set('postgres', { status: 'running', container: name, startedAt: new Date().toISOString() })
+      return
+    }
+    await Bun.sleep(500)
+  }
+  throw new Error('Postgres did not become ready within 60 s')
+}
+
+async function startStorage(project: LocalProject, ports: PortBlock, secrets: LocalSecrets, running: Running, set: SetFn) {
+  const name = containerName(project, 'storage')
+  await ensureImage(IMAGES.storage, project, 'storage')
+  const current = containerState(name)
+  if (current === 'exited') startContainer(name)
+  else if (current !== 'running') {
+    if (current !== 'missing') removeContainer(name)
+    runContainer({
+      name,
+      image: IMAGES.storage,
+      projectId: project.id,
+      ports: [{ host: ports.storage, container: 9000 }],
+      env: { RUSTFS_ACCESS_KEY: secrets.storageAccessKey, RUSTFS_SECRET_KEY: secrets.storageSecretKey },
+      volumes: [{ name: `frontera-${project.id}-storage`, path: '/data' }],
+      memory: '256m',
+      cpus: '0.5',
+      args: ['server', '/data'],
+    })
+  }
+  running.containers.add(name)
+  followLogs(name, logPath(project, 'storage'))
+  // RustFS answers its S3 API with 403 to an anonymous request once it is up.
+  const deadline = Date.now() + 45_000
+  while (Date.now() < deadline) {
+    try {
+      const res = await fetch(`http://127.0.0.1:${ports.storage}/`, { signal: AbortSignal.timeout(2000) })
+      if (res.status > 0) {
+        set('storage', { status: 'running', container: name, startedAt: new Date().toISOString() })
+        return
+      }
+    } catch {
+      // Not up yet.
+    }
+    await Bun.sleep(500)
+  }
+  throw new Error('object storage did not answer within 45 s')
+}
+
+async function startJobs(project: LocalProject, ports: PortBlock, running: Running, set: SetFn) {
+  const name = containerName(project, 'jobs')
+  await ensureImage(IMAGES.jobs, project, 'jobs')
+  if (containerState(name) !== 'missing') removeContainer(name)
+  runContainer({
+    name,
+    image: IMAGES.jobs,
+    projectId: project.id,
+    ports: [{ host: ports.jobs, container: 8288 }],
+    flags: ['--add-host', `${HOST_FROM_CONTAINER}:host-gateway`],
+    memory: '384m',
+    cpus: '1',
+    args: ['inngest', 'dev', '--no-discovery', '-u', `http://${HOST_FROM_CONTAINER}:${ports.service}/api/inngest`],
+  })
+  running.containers.add(name)
+  followLogs(name, logPath(project, 'jobs'))
+  if (!(await waitForHttp(`http://127.0.0.1:${ports.jobs}/health`, 45_000)) && !(await waitForHttp(`http://127.0.0.1:${ports.jobs}/`, 5_000))) {
+    throw new Error('the job engine did not answer within 50 s')
+  }
+  set('jobs', { status: 'running', container: name, startedAt: new Date().toISOString() })
+}
+
+function serviceDir(config: LocalConfig): string {
+  return join(config.platformSource!, 'packages', 'service')
+}
+
+async function startService(
+  project: LocalProject,
+  ports: PortBlock,
+  secrets: LocalSecrets,
+  config: LocalConfig,
+  running: Running,
+  set: SetFn,
+  runnerEnabled: boolean,
+  jobsEnabled: boolean,
+  storageEnabled: boolean,
+) {
+  const env = serviceEnv({
+    secrets,
+    ports,
+    providerEnv: providerEnv(),
+    runnerEnabled,
+    jobsEnabled,
+    storageEnabled,
+    keylessEmbeddings: keylessEmbeddings(),
+    documentationBundle: config.mode === 'source' ? customerDocsBundle(config.platformSource) : null,
+  })
+  const log = logPath(project, 'service')
+  if (config.mode === 'source') {
+    const cwd = serviceDir(config)
+    if (!existsSync(join(cwd, 'src', 'index.ts'))) throw new Error(`no service source at ${cwd}`)
+    // Migrations first, synchronously, so a broken migration is the error shown.
+    const migrate = startProcess({ name: 'migrate', command: 'bun', args: ['scripts/migrate.ts'], cwd, env, logFile: log })
+    const code: number = await new Promise((r) => migrate.on('exit', (c) => r(c ?? 1)))
+    if (code !== 0) throw new Error(`migrations failed (exit ${code}); see \`frontera local logs service\``)
+    const child = startProcess({ name: 'service', command: 'bun', args: ['src/index.ts'], cwd, env, logFile: log })
+    running.children.set('service', child)
+    const ok = await waitForHttp(`http://127.0.0.1:${ports.service}/health`, 120_000, () => child.exitCode === null)
+    if (!ok) throw new Error('the service did not become healthy; see `frontera local logs service`')
+    set('service', { status: 'running', pid: child.pid, startedAt: new Date().toISOString() })
+    keepDocs(project, { bundle: customerDocsBundle(config.platformSource) }, log)
+    return
+  }
+  const name = containerName(project, 'service')
+  const image = IMAGES.service(config.platformVersion, config.registry)
+  await ensureImage(image, project, 'service')
+  if (containerState(name) !== 'missing') removeContainer(name)
+  const containerEnv = fromContainer(env, SERVICE_OUTBOUND)
+  runContainer({
+    name,
+    image,
+    projectId: project.id,
+    ports: [{ host: ports.service, container: ports.service }],
+    env: containerEnv,
+    flags: ['--add-host', `${HOST_FROM_CONTAINER}:host-gateway`],
+    memory: '1536m',
+    cpus: '2',
+  })
+  running.containers.add(name)
+  followLogs(name, log)
+  const ok = await waitForHttp(`http://127.0.0.1:${ports.service}/health`, 180_000)
+  if (!ok) throw new Error('the service did not become healthy; see `frontera local logs service`')
+  set('service', { status: 'running', container: name, startedAt: new Date().toISOString() })
+  keepDocs(project, { fromContainer: (dest) => copyFromContainer(name, IMAGE_DOCS_PATH, dest) }, log)
+}
+
+/** The release's documentation, for the solution's coding agents (`local docs-mcp`). */
+function keepDocs(project: LocalProject, from: { bundle?: string | null; fromContainer?: (dest: string) => boolean }, log: string): void {
+  if (!from.bundle && !from.fromContainer) {
+    appendFileSync(log, '[docs] no customer documentation in the platform checkout; run `bun run docs:build` there\n')
+    return
+  }
+  const problem = copyDocs({ project, ...from })
+  if (problem) appendFileSync(log, `[docs] the documentation for coding agents was not copied: ${problem}\n`)
+}
+
+/** The formats of the project's files, for its coding agents and editors (`local schema`). Logged, never a reason to fail start. */
+async function keepFileSchemas(project: LocalProject, source: SchemaSource, log: string): Promise<void> {
+  for (const problem of await keepSchemas(project, source)) appendFileSync(log, `[schemas] not kept: ${problem}\n`)
+}
+
+async function startRunner(
+  project: LocalProject,
+  ports: PortBlock,
+  secrets: LocalSecrets,
+  config: LocalConfig,
+  running: Running,
+  set: SetFn,
+  storageEnabled: boolean,
+) {
+  const env = runnerEnv({ secrets, ports, storageEnabled })
+  const log = logPath(project, 'runner')
+  if (config.mode === 'source') {
+    const cwd = config.platformSource!
+    const child = startProcess({ name: 'runner', command: 'bun', args: ['packages/automation-runner/src/index.ts'], cwd, env, logFile: log })
+    running.children.set('runner', child)
+    const ok = await waitForHttp(`http://127.0.0.1:${ports.runner}/healthz`, 60_000, () => child.exitCode === null)
+    if (!ok) throw new Error('the Function runner did not become healthy; see `frontera local logs runner`')
+    set('runner', { status: 'running', pid: child.pid, startedAt: new Date().toISOString() })
+    return
+  }
+  const name = containerName(project, 'runner')
+  const image = IMAGES.runner(config.platformVersion, config.registry)
+  await ensureImage(image, project, 'runner')
+  if (containerState(name) !== 'missing') removeContainer(name)
+  runContainer({
+    name,
+    image,
+    projectId: project.id,
+    ports: [{ host: ports.runner, container: ports.runner }],
+    env: fromContainer(env, RUNNER_OUTBOUND),
+    flags: ['--add-host', `${HOST_FROM_CONTAINER}:host-gateway`],
+    memory: '768m',
+    cpus: '1',
+  })
+  running.containers.add(name)
+  followLogs(name, log)
+  const ok = await waitForHttp(`http://127.0.0.1:${ports.runner}/healthz`, 90_000)
+  if (!ok) throw new Error('the Function runner did not become healthy; see `frontera local logs runner`')
+  set('runner', { status: 'running', container: name, startedAt: new Date().toISOString() })
+}

package/src/local/local-test-cases.ts

@@ -0,0 +1,58 @@
+import { appendFileSync, existsSync, mkdirSync } from 'node:fs'
+import { dirname, join, relative } from 'node:path'
+
+/**
+ * Write a conversation into the solution as a regression case.
+ *
+ * The file is `agents/<slug>/evals/regression.yaml` under the solution root,
+ * the layout the solution delivery design uses for an Agent's evaluations. A
+ * case is appended, never rewritten, so an FDE's hand edits survive; the
+ * expected outcome is the Agent's last reply, which the FDE refines in the
+ * file before committing.
+ */
+
+interface ChatMessage {
+  role?: string
+  content?: unknown
+  parts?: Array<{ type?: string; text?: string }>
+}
+
+function textOf(message: ChatMessage): string {
+  if (typeof message.content === 'string') return message.content
+  return (message.parts ?? [])
+    .filter((p) => p.type === 'text' && typeof p.text === 'string')
+    .map((p) => p.text)
+    .join('\n')
+    .trim()
+}
+
+/** A YAML block scalar, indented, that survives any text. */
+function block(text: string, indent: string): string {
+  return `|-\n${text.split('\n').map((line) => `${indent}${line}`).join('\n')}`
+}
+
+export function renderTestCase(args: { conversationId: string; messages: ChatMessage[]; savedAt: string }): string {
+  const turns = args.messages.filter((m) => (m.role === 'user' || m.role === 'assistant') && textOf(m))
+  const lastReply = [...turns].reverse().find((m) => m.role === 'assistant')
+  const inputs = turns.slice(0, lastReply ? turns.lastIndexOf(lastReply) : turns.length)
+  const lines = [
+    `- name: conversation-${args.conversationId.slice(0, 8)}`,
+    `  savedFrom: studio ${args.savedAt}`,
+    '  conversation:',
+    ...inputs.map((m) => `    - ${m.role}: ${block(textOf(m), '        ')}`),
+    `  expected: ${block(lastReply ? textOf(lastReply) : '', '    ')}`,
+    '',
+  ]
+  return lines.join('\n')
+}
+
+export function appendTestCase(root: string, agentSlug: string, yaml: string): string {
+  const safe = agentSlug.replace(/[^a-z0-9._-]/gi, '-')
+  const file = join(root, 'agents', safe, 'evals', 'regression.yaml')
+  mkdirSync(dirname(file), { recursive: true })
+  if (!existsSync(file)) {
+    appendFileSync(file, `# Regression cases for ${agentSlug}. Each case: the conversation, then what a good reply does.\ncases:\n`)
+  }
+  appendFileSync(file, yaml.replace(/^/gm, '  ').replace(/ +$/gm, ''))
+  return relative(root, file)
+}