@frontera-sdk/cli 1.52.23 → 1.52.25

package/src/commands/local/providers.ts

@@ -0,0 +1,245 @@
+import { readFileSync } from 'node:fs'
+
+import { UsageError } from '../../errors'
+import { promptSecret } from '../../prompt'
+import { configuredProviders, getKey, LOCAL_PROVIDERS, removeKey, setKey } from '../../local/local-keys'
+import {
+  applyProviderSetup,
+  availableModels,
+  CUSTOM_SLUG,
+  customKeyId,
+  modelSlug,
+  readProviderSetup,
+  rememberSlugs,
+  removeRuntimeModel,
+  removeRuntimeProvider,
+  runningTarget,
+  runtimeCatalog,
+  runtimeJudge,
+  writeProviderSetup,
+  type ProviderSetup,
+  type RuntimeTarget,
+} from '../../local/local-providers'
+import { flagBool, flagString, type Command, type CommandContext } from '../types'
+
+/**
+ * `frontera local providers` and its verbs: the model providers and models an
+ * FDE's local runtimes use, beyond the built-in providers' keys (`key-set`).
+ * Each change is kept for every project's runtime and, when this project's
+ * runtime is up, applied to it at once. Keys arrive on stdin or at a hidden
+ * prompt, never as a flag.
+ */
+
+/** Apply the setup to the running runtime, if any, and keep the slugs it gave back. */
+async function applyNow(ctx: CommandContext, setup: ProviderSetup): Promise<{ applied: boolean; errors: string[] }> {
+  const target = runningTarget(ctx.cwd)
+  if (!target) {
+    writeProviderSetup(setup)
+    return { applied: false, errors: [] }
+  }
+  const result = await applyProviderSetup(target, setup)
+  writeProviderSetup(rememberSlugs(setup, result))
+  return { applied: true, errors: result.errors }
+}
+
+function needRuntime(ctx: CommandContext): RuntimeTarget {
+  const target = runningTarget(ctx.cwd)
+  if (!target) throw new UsageError('the local runtime is not running', 'frontera local start')
+  return target
+}
+
+async function readSecret(ctx: CommandContext, label: string): Promise<string> {
+  return flagBool(ctx, 'stdin') ? readFileSync(0, 'utf8').trim() : (await promptSecret(`${label} API key (Enter for none): `)).trim()
+}
+
+const afterward = (r: { applied: boolean; errors: string[] }) =>
+  r.errors.length ? `\nThe runtime refused part of it:\n${r.errors.map((e) => `  ${e}`).join('\n')}` : r.applied ? '' : '\nIt applies when the runtime starts.'
+
+export const localProviders: Command = {
+  meta: {
+    noun: 'local',
+    verb: 'providers',
+    args: [],
+    flags: {},
+    summary: 'List the model providers, models and default models of your local runtimes',
+    examples: ['frontera local providers', 'frontera local providers --json'],
+    offline: true,
+    internal: true,
+  },
+  async run(ctx) {
+    const setup = readProviderSetup()
+    const keyed = new Set(configuredProviders())
+    const target = runningTarget(ctx.cwd)
+    const [catalog, judge] = target ? await Promise.all([runtimeCatalog(target).catch(() => null), runtimeJudge(target).catch(() => null)]) : [null, null]
+    const data = {
+      builtIn: LOCAL_PROVIDERS.map((p) => ({ id: p.id, label: p.label, key: keyed.has(p.id) })),
+      custom: setup.custom.map((c) => ({ ...c, provider: `custom:${c.slug}`, key: getKey(customKeyId(c.slug)) !== null })),
+      models: setup.models,
+      defaults: setup.defaults,
+      runtime: target ? { running: true, catalog: catalog ?? [], judgeModel: judge } : { running: false, catalog: [], judgeModel: null },
+    }
+    const lines = [
+      'Providers',
+      ...data.builtIn.map((p) => `  ${p.key ? '●' : '○'} ${p.label.padEnd(22)} ${p.key ? 'key stored' : '—'}`),
+      ...data.custom.map((c) => `  ● ${c.label.padEnd(22)} ${c.baseUrl}${c.key ? '' : ' (no key)'}`),
+      '',
+      'Models Agents can use',
+      ...(target ? (catalog ?? []).map((m) => `  ${m.slug.padEnd(28)} ${m.name}`) : setup.models.map((m) => `  ${(m.slug ?? '').padEnd(28)} ${m.name}`)),
+      '',
+      `New Agents use   ${setup.defaults.agentModel ?? '(not chosen)'}`,
+      `Tests graded by  ${judge ?? setup.defaults.judgeModel ?? '(not chosen)'}`,
+    ]
+    return { data, text: lines.join('\n') }
+  },
+}
+
+export const localProviderAdd: Command = {
+  meta: {
+    noun: 'local',
+    verb: 'provider-add',
+    args: [{ name: 'slug', required: true, description: 'lowercase id, e.g. acme-gateway (the provider becomes custom:<slug>)' }],
+    flags: { 'base-url': 'string', label: 'string', stdin: 'boolean' },
+    summary: 'Add an OpenAI-compatible model provider (a gateway, Azure, a model served on this machine)',
+    examples: ['frontera local provider-add ollama --base-url http://127.0.0.1:11434/v1', 'frontera local provider-add acme --base-url https://acme.example/v1 --stdin'],
+    offline: true,
+    internal: true,
+  },
+  async run(ctx) {
+    const slug = ctx.positional[0] ?? ''
+    if (!CUSTOM_SLUG.test(slug)) throw new UsageError(`\`${slug}\` is not a provider id`, 'use 2–40 lowercase letters, digits and hyphens, e.g. acme-gateway')
+    const baseUrl = flagString(ctx, 'base-url') ?? ''
+    if (!/^https?:\/\/\S+$/.test(baseUrl)) throw new UsageError('the provider needs its base URL', '--base-url https://host/v1 (the OpenAI-compatible root, ending before /chat/completions)')
+    const label = flagString(ctx, 'label') ?? slug
+    const key = await readSecret(ctx, label)
+    if (key) setKey(customKeyId(slug), key)
+    const setup = readProviderSetup()
+    const spec = { slug, label, baseUrl: baseUrl.replace(/\/+$/, '') }
+    setup.custom = [...setup.custom.filter((c) => c.slug !== slug), spec]
+    const result = await applyNow(ctx, setup)
+    return { data: { provider: `custom:${slug}`, ...spec, key: !!key, applied: result.applied, errors: result.errors }, text: `Added ${label} (custom:${slug}).${afterward(result)}` }
+  },
+}
+
+export const localProviderRemove: Command = {
+  meta: {
+    noun: 'local',
+    verb: 'provider-remove',
+    args: [{ name: 'slug', required: true, description: 'the custom provider id' }],
+    flags: {},
+    summary: 'Remove an OpenAI-compatible provider, its key and its models',
+    examples: ['frontera local provider-remove acme-gateway'],
+    offline: true,
+    internal: true,
+  },
+  async run(ctx) {
+    const slug = ctx.positional[0] ?? ''
+    const setup = readProviderSetup()
+    const spec = setup.custom.find((c) => c.slug === slug)
+    if (!spec) throw new UsageError(`no provider \`${slug}\``, 'frontera local providers')
+    const gone = new Set(setup.models.filter((m) => m.provider === `custom:${slug}`).map((m) => m.slug))
+    setup.custom = setup.custom.filter((c) => c.slug !== slug)
+    setup.models = setup.models.filter((m) => m.provider !== `custom:${slug}`)
+    if (setup.defaults.agentModel && gone.has(setup.defaults.agentModel)) delete setup.defaults.agentModel
+    if (setup.defaults.judgeModel && gone.has(setup.defaults.judgeModel)) delete setup.defaults.judgeModel
+    removeKey(customKeyId(slug))
+    writeProviderSetup(setup)
+    const target = runningTarget(ctx.cwd)
+    if (target) await removeRuntimeProvider(target, slug)
+    return { data: { provider: `custom:${slug}`, removed: true }, text: `Removed ${spec.label}.` }
+  },
+}
+
+export const localModelsAvailable: Command = {
+  meta: {
+    noun: 'local',
+    verb: 'models-available',
+    args: [{ name: 'provider', required: true, description: 'anthropic | openai | openrouter | google | custom:<slug>' }],
+    flags: {},
+    summary: "List the models a provider offers (needs the runtime running and the provider's key)",
+    examples: ['frontera local models-available openrouter', 'frontera local models-available custom:acme-gateway --json'],
+    offline: true,
+    internal: true,
+  },
+  async run(ctx) {
+    const provider = ctx.positional[0] ?? ''
+    const models = await availableModels(needRuntime(ctx), provider)
+    return { data: models, text: models.length ? models.map((m) => `  ${m.id.padEnd(44)} ${m.name}`).join('\n') : `${provider} offered no models: check its key or base URL.` }
+  },
+}
+
+export const localModelAdd: Command = {
+  meta: {
+    noun: 'local',
+    verb: 'model-add',
+    args: [
+      { name: 'provider', required: true, description: 'anthropic | openai | openrouter | google | custom:<slug>' },
+      { name: 'model', required: true, description: "the provider's model id, e.g. anthropic/claude-sonnet-5.5" },
+    ],
+    flags: { name: 'string', slug: 'string' },
+    summary: 'Make a model available to Agents in your local runtimes',
+    examples: ['frontera local model-add openrouter openai/gpt-6-luna --name "GPT-6 Luna"', 'frontera local model-add custom:acme-gateway llama-4-70b'],
+    offline: true,
+    internal: true,
+  },
+  async run(ctx) {
+    const [provider = '', modelId = ''] = ctx.positional
+    if (!provider || !modelId) throw new UsageError('name the provider and its model id', 'frontera local model-add openrouter openai/gpt-6-luna')
+    const name = flagString(ctx, 'name') ?? modelId.split('/').pop() ?? modelId
+    const setup = readProviderSetup()
+    setup.models = [...setup.models.filter((m) => !(m.provider === provider && m.modelId === modelId)), { provider, modelId, name, slug: flagString(ctx, 'slug') ?? modelSlug(name) }]
+    const result = await applyNow(ctx, setup)
+    const slug = readProviderSetup().models.find((m) => m.provider === provider && m.modelId === modelId)?.slug
+    return { data: { provider, modelId, name, slug, applied: result.applied, errors: result.errors }, text: `Added ${name}: Agents name it \`${slug}\` in agent.json.${afterward(result)}` }
+  },
+}
+
+export const localModelRemove: Command = {
+  meta: {
+    noun: 'local',
+    verb: 'model-remove',
+    args: [{ name: 'slug', required: true, description: 'the catalog slug' }],
+    flags: {},
+    summary: 'Stop offering a model to Agents in your local runtimes',
+    examples: ['frontera local model-remove gpt-6-luna'],
+    offline: true,
+    internal: true,
+  },
+  async run(ctx) {
+    const slug = ctx.positional[0] ?? ''
+    const setup = readProviderSetup()
+    setup.models = setup.models.filter((m) => m.slug !== slug)
+    if (setup.defaults.agentModel === slug) delete setup.defaults.agentModel
+    if (setup.defaults.judgeModel === slug) delete setup.defaults.judgeModel
+    writeProviderSetup(setup)
+    const target = runningTarget(ctx.cwd)
+    if (target) await removeRuntimeModel(target, slug)
+    return { data: { slug, removed: true }, text: `Removed ${slug}.` }
+  },
+}
+
+export const localModelDefault: Command = {
+  meta: {
+    noun: 'local',
+    verb: 'model-default',
+    args: [{ name: 'slug', required: true, description: 'the catalog slug' }],
+    flags: { for: 'string' },
+    summary: 'Choose the model new Agents start with and the one that grades tests',
+    examples: ['frontera local model-default claude-sonnet-5-5', 'frontera local model-default gpt-6-luna --for tests'],
+    offline: true,
+    internal: true,
+  },
+  async run(ctx) {
+    const slug = ctx.positional[0] ?? ''
+    if (!slug) throw new UsageError('name the model', 'frontera local model-default <slug>')
+    const which = flagString(ctx, 'for') ?? 'both'
+    if (!['agents', 'tests', 'both'].includes(which)) throw new UsageError(`--for ${which}?`, 'use agents, tests or both')
+    const setup = readProviderSetup()
+    if (which !== 'tests') setup.defaults.agentModel = slug
+    if (which !== 'agents') setup.defaults.judgeModel = slug
+    const result = await applyNow(ctx, setup)
+    return {
+      data: { ...setup.defaults, applied: result.applied, errors: result.errors },
+      text: `${which === 'tests' ? 'Tests are' : which === 'agents' ? 'New Agents are' : 'New Agents and tests are'} now on ${slug}.${afterward(result)}`,
+    }
+  },
+}

package/src/commands/local/schema.ts

@@ -0,0 +1,46 @@
+import { CliError, UsageError } from '../../errors'
+import { localProject } from '../../local/local-project'
+import { cliSchema, isSchemaKind, resolveSchema, runtimeSource, SCHEMA_FILES, SCHEMA_KINDS } from '../../local/local-schemas'
+import type { Command } from '../types'
+
+/**
+ * `frontera local schema <kind>`: the exact format of one kind of project file,
+ * as JSON Schema, for the coding agents and editors working in the project.
+ * The guides describe the product; this is the contract a file is checked
+ * against, for the release the local runtime runs. Without a kind it lists
+ * the kinds and the files each describes.
+ */
+export const localSchema: Command = {
+  meta: {
+    noun: 'local',
+    verb: 'schema',
+    args: [{ name: 'kind', required: false, description: SCHEMA_KINDS.join(' | ') }],
+    flags: {},
+    summary: 'Print the JSON Schema of a project file (operating, agent, workflow, evals, dataset) for the runtime\'s release',
+    examples: ['frontera local schema', 'frontera local schema operating', "frontera local schema workflow | jq '.\"$defs\" | keys'"],
+    offline: true,
+    internal: true,
+  },
+  async run(ctx) {
+    const kind = ctx.positional[0]
+    if (!kind) {
+      const kinds = SCHEMA_KINDS.map((k) => ({ kind: k, file: SCHEMA_FILES[k], from: cliSchema(k) ? 'cli' : 'service' }))
+      return {
+        data: kinds,
+        text: [
+          'Project file formats, as JSON Schema: `frontera local schema <kind>`.',
+          ...kinds.map((k) => `  ${k.kind.padEnd(10)} ${k.file}`),
+          '`frontera local start` keeps them in .frontera/local/schemas/<kind>.schema.json.',
+        ].join('\n'),
+      }
+    }
+    if (!isSchemaKind(kind)) {
+      throw new UsageError(`unknown file kind \`${kind}\``, `use one of: ${SCHEMA_KINDS.join(', ')}`)
+    }
+    const project = localProject(ctx.cwd)
+    const answer = await resolveSchema(project, kind, runtimeSource(project))
+    if (!answer.ok) throw new CliError(answer.reason, { code: 'LOCAL_SCHEMA_UNAVAILABLE', hint: answer.hint })
+    if (answer.note) ctx.output.note(answer.note)
+    return { data: answer.schema, text: JSON.stringify(answer.schema, null, 2) }
+  },
+}

package/src/commands/registry.ts

@@ -46,6 +46,7 @@ import { authCommands } from './auth/index-commands'
 import { kitCommands } from './kit/index-commands'
 import { workspaceCommands } from './workspace/index-commands'
 import { forgeCommands } from './forge/index-commands'
+import { localCommands } from './local/index-commands'
 
 /**
  * Flags every command accepts. Declared once so a caller never has to wonder
@@ -86,6 +87,7 @@ export const COMMANDS: readonly Command[] = [
   ...kitCommands,
   ...workspaceCommands,
   ...forgeCommands,
+  ...localCommands,
 
   appInit,
   appList,
@@ -149,8 +151,8 @@ export function findCommand(noun: string, verb: string | undefined): Command | n
   )
 }
 
-export function nouns(): string[] {
-  return [...new Set(COMMANDS.map((c) => c.meta.noun))]
+export function nouns(includeInternal = false): string[] {
+  return [...new Set(COMMANDS.filter((c) => includeInternal || !c.meta.internal).map((c) => c.meta.noun))]
 }
 
 /**
@@ -307,7 +309,7 @@ export function renderHelp(): string {
 
   // Setup first and ungrouped: these are the two commands someone runs before
   // any noun makes sense.
-  const setup = COMMANDS.filter((c) => c.meta.verb === '')
+  const setup = COMMANDS.filter((c) => c.meta.verb === '' && !c.meta.internal)
   if (setup.length > 0) {
     lines.push('', heading('Getting started'))
     lines.push(
@@ -514,7 +516,7 @@ export function describeCommand(meta: CommandMeta): CommandDescriptor {
 }
 
 export function describeCommands(noun?: string): CommandDescriptor[] {
-  return COMMANDS.filter((c) => !noun || c.meta.noun === noun).map((c) => describeCommand(c.meta))
+  return COMMANDS.filter((c) => (noun ? c.meta.noun === noun : !c.meta.internal)).map((c) => describeCommand(c.meta))
 }
 
 /** Levenshtein distance, iterative with one row — enough for a typo check. */

package/src/commands/types.ts

@@ -81,6 +81,13 @@ export interface CommandMeta {
    * reason picks another route.
    */
   reserved?: string
+  /**
+   * Internal FDE tooling. It needs Frontera's private platform source or
+   * images, so it is left out of the top-level help, `help --json` and the
+   * CLI reference generated from it (which customers read). `frontera <noun>
+   * --help` and the commands themselves still work for anyone who knows them.
+   */
+  internal?: boolean
 }
 
 export interface CommandContext {

package/src/flag-help.ts

@@ -58,6 +58,9 @@ export const FLAG_HELP: Readonly<Record<string, string>> = {
     + 'and naming none is refused rather than guessed',
   output: 'project-relative .ts path for generated output',
   check: 'verify generated output is current without writing it',
+  'base-url': "OpenAI-compatible endpoint the provider's models are reached at, e.g. https://llm.acme.example/v1",
+  slug: 'id the runtime gives the model, used to choose it as a default; derived from its name when left out',
+  for: '"agents" (new Agents), "tests" (grading tests) or "both" (default)',
 
   // Forge daemon
   origin: 'browser origin allowed by CORS — the platform web origin; also FRONTERA_FORGE_ORIGIN',
@@ -73,6 +76,21 @@ export const FLAG_HELP: Readonly<Record<string, string>> = {
     'refuse the write unless the resource is still at this revision; exit 3 if it moved',
   notes: 'note recorded against the published version',
 
+  // Local runtime (internal FDE tooling)
+  source: 'platform checkout to run the local runtime from (default: the one this CLI runs from)',
+  image: 'run the local runtime from release images instead of a platform checkout',
+  exclude: 'optional components to leave out of the local runtime: jobs, runner, storage',
+  'no-backup': 'also delete the local database and secrets',
+  follow: 'keep printing new log lines as they are written',
+  lines: 'how many of the latest log lines to print (default 100)',
+  stdin: 'read the value from standard input instead of a hidden prompt',
+  live: 'test the published Agent instead of its draft',
+  once: 'apply the solution once and exit instead of watching for changes',
+  'no-publish': 'keep Blueprint changes as a draft instead of publishing them to the local workspace',
+  registry: 'the registry host and namespace image mode pulls the platform images from, such as registry.example.com/frontera',
+  reapply: 'apply every file again, including those unchanged since they were last applied',
+  stop: 'stop the local runtime when the check ends',
+
   // Apps
   framework: 'App scaffold to create: next (default) or react (legacy Vite)',
   port: 'loopback port to listen on — the App development server, or the Forge daemon (0: any free port)',

package/src/harness.ts

@@ -269,7 +269,7 @@ or click through when verifying your work — a screenshot of \`/\` is a screens
 of the refusal panel.
 `
 
-const AGENTS_MD = `# Frontera
+export const AGENTS_MD = `# Frontera
 
 This directory works with the Frontera platform through the \`frontera\` CLI.
 

package/src/local/local-agent-files.ts

@@ -0,0 +1,122 @@
+import { spawn } from 'node:child_process'
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { contentHash, loadHashes, saveHashes } from './local-applied'
+import { localProfileName } from './local-control'
+import { targetFor } from './local-dev-sync'
+import type { LocalProject } from './local-project'
+
+/**
+ * Studio's editor, the counterpart of Mastra Studio's: a change made in the
+ * browser is written into the project's `agents/<slug>/agent.json` and then
+ * applied, so the files stay the source and a commit carries the change.
+ * Only the fields Studio offers are touched; the rest of the file is kept.
+ */
+
+export interface AgentFileEdit {
+  description?: string
+  /** Instruction prompts by filename. */
+  prompts?: Array<{ filename: string; content: string }>
+  /** Model per mode, and its reasoning effort (null: the model's default). */
+  models?: Array<{ modeKey: string; modelSlug: string; reasoningEffort?: string | null }>
+}
+
+/** The efforts the chat runtime accepts (the service's reasoningEffortEnum). */
+export const REASONING_EFFORTS = ['none', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'] as const
+
+export class AgentFileError extends Error {
+  constructor(
+    message: string,
+    readonly status: number,
+  ) {
+    super(message)
+  }
+}
+
+const SLUG = /^[a-z0-9][a-z0-9-]*$/
+
+export function agentFilePath(root: string, slug: string): string {
+  if (!SLUG.test(slug)) throw new AgentFileError(`"${slug}" is not an Agent slug`, 400)
+  return join(root, 'agents', slug, 'agent.json')
+}
+
+/** Apply an edit to the file's document; returns the new text, or null when nothing changed. */
+export function editAgentDocument(text: string, edit: AgentFileEdit): string | null {
+  const doc = JSON.parse(text) as {
+    config?: Record<string, unknown>
+    prompts?: Array<{ filename?: string; content?: string }>
+    modelConfigs?: Array<{ modeKey?: string; modelSlug?: string; reasoningEffort?: string | null }>
+  }
+  if (edit.description !== undefined) {
+    doc.config = { ...(doc.config ?? {}), description: edit.description }
+  }
+  for (const p of edit.prompts ?? []) {
+    const prompt = doc.prompts?.find((x) => x.filename === p.filename)
+    if (!prompt) throw new AgentFileError(`agent.json has no prompt named ${p.filename}`, 400)
+    prompt.content = p.content
+  }
+  for (const m of edit.models ?? []) {
+    const mode = doc.modelConfigs?.find((x) => x.modeKey === m.modeKey)
+    if (!mode) throw new AgentFileError(`agent.json has no model mode ${m.modeKey}`, 400)
+    if (!m.modelSlug.trim()) throw new AgentFileError(`mode ${m.modeKey} needs a model`, 400)
+    mode.modelSlug = m.modelSlug.trim()
+    if (m.reasoningEffort !== undefined) {
+      if (m.reasoningEffort === null) delete mode.reasoningEffort
+      else if ((REASONING_EFFORTS as readonly string[]).includes(m.reasoningEffort)) mode.reasoningEffort = m.reasoningEffort
+      else throw new AgentFileError(`"${m.reasoningEffort}" is not a reasoning effort`, 400)
+    }
+  }
+  const next = `${JSON.stringify(doc, null, 2)}\n`
+  return next === text ? null : next
+}
+
+function applyWithCli(project: LocalProject, slug: string, file: string): Promise<{ ok: boolean; output: string }> {
+  const compiled = Bun.main.startsWith('/$bunfs') || Bun.main.startsWith('B:\\~BUN')
+  const self = compiled ? [process.execPath] : [process.execPath, Bun.main]
+  const args = ['agent', 'apply', slug, '-f', file, '--profile', localProfileName(project)]
+  return new Promise((resolve) => {
+    const child = spawn('nice', ['-n', '10', ...self, ...args], { cwd: project.root, stdio: ['ignore', 'pipe', 'pipe'], env: { ...process.env, NO_COLOR: '1' } })
+    let output = ''
+    child.stdout.on('data', (c) => (output += c))
+    child.stderr.on('data', (c) => (output += c))
+    child.on('error', (err) => resolve({ ok: false, output: err.message }))
+    child.on('close', (code) => resolve({ ok: code === 0, output }))
+  })
+}
+
+/**
+ * Write the edit into the file, then apply it as `local dev` would, and record
+ * it as applied so a running `local dev` does not apply it a second time.
+ */
+export async function saveAgentEdit(
+  project: LocalProject,
+  organizationId: string,
+  slug: string,
+  edit: AgentFileEdit,
+): Promise<{ path: string; changed: boolean; applied: boolean; output: string }> {
+  const path = agentFilePath(project.root, slug)
+  const rel = join('agents', slug, 'agent.json')
+  if (!existsSync(path)) {
+    throw new AgentFileError(`${rel} does not exist. Studio edits the project's files; this Agent has none.`, 404)
+  }
+  let next: string | null
+  try {
+    next = editAgentDocument(readFileSync(path, 'utf8'), edit)
+  } catch (err) {
+    if (err instanceof AgentFileError) throw err
+    throw new AgentFileError(`${rel} could not be read: ${(err as Error).message}`, 422)
+  }
+  if (next === null) return { path: rel, changed: false, applied: true, output: '' }
+  writeFileSync(path, next)
+  const result = await applyWithCli(project, slug, rel)
+  if (result.ok) {
+    const target = targetFor(project.root, path)
+    if (target) {
+      const applied = loadHashes(project, organizationId)
+      applied.set(target.key, contentHash(project, target))
+      saveHashes(project, organizationId, applied)
+    }
+  }
+  return { path: rel, changed: true, applied: result.ok, output: result.output.trim().split('\n').slice(0, 6).join('\n') }
+}

package/src/local/local-applied.ts

@@ -0,0 +1,135 @@
+import { createHash } from 'node:crypto'
+import { lstatSync, readdirSync, readFileSync } from 'node:fs'
+import { join, relative } from 'node:path'
+
+import { writeFileAtomic } from '../fs-atomic'
+import { allTargets, describeTarget, datasetDocument, isIgnoredName, type SyncTarget } from './local-dev-sync'
+import type { LocalProject } from './local-project'
+
+/**
+ * What `frontera local dev` has applied to this runtime, by content hash. It
+ * lets a new `local dev` skip files that have not changed (instead of piling up
+ * workflow and Function versions), and lets Studio show which files the
+ * runtime is behind on. Kept per local organization: after a reset the runtime
+ * is empty, and every file counts as not applied.
+ *
+ * Hashing never throws: editors leave lock files and dangling symlinks, files
+ * vanish between a listing and a read, and none of that may stop `local dev`.
+ */
+
+/** A file's digest, cached by size and modification time so Studio's polling stays cheap. */
+const digests = new Map<string, { size: number; mtimeMs: number; digest: string }>()
+
+function fileDigest(path: string): string | null {
+  try {
+    const stat = lstatSync(path)
+    if (!stat.isFile()) return null
+    const cached = digests.get(path)
+    if (cached && cached.size === stat.size && cached.mtimeMs === stat.mtimeMs) return cached.digest
+    const digest = createHash('sha256').update(readFileSync(path)).digest('hex')
+    digests.set(path, { size: stat.size, mtimeMs: stat.mtimeMs, digest })
+    return digest
+  } catch {
+    return null
+  }
+}
+
+/** Every regular file under a directory, by path and digest, in a stable order. Symlinks and dotfiles are skipped. */
+function treeHash(dir: string): string | null {
+  const hash = createHash('sha256')
+  let any = false
+  const walk = (at: string, depth: number) => {
+    if (depth > 8) return
+    let names: string[]
+    try {
+      names = readdirSync(at).sort()
+    } catch {
+      return
+    }
+    for (const name of names) {
+      if (isIgnoredName(name) || name === 'node_modules') continue
+      const path = join(at, name)
+      let stat
+      try {
+        stat = lstatSync(path)
+      } catch {
+        continue
+      }
+      if (stat.isDirectory()) walk(path, depth + 1)
+      else if (stat.isFile()) {
+        const digest = fileDigest(path)
+        if (!digest) continue
+        any = true
+        hash.update(relative(dir, path)).update('\0').update(digest).update('\0')
+      }
+    }
+  }
+  walk(dir, 0)
+  return any ? hash.digest('hex') : null
+}
+
+export function contentHash(project: LocalProject, target: SyncTarget): string | null {
+  // The Blueprint is applied as one tree, so it changes when any file in it does.
+  if (target.kind === 'blueprint') return treeHash(join(project.root, 'blueprint'))
+  const own = fileDigest(join(project.root, target.file))
+  if (!own) return null
+  const hash = createHash('sha256').update(own)
+  // A dataset is its definition and its rows.
+  if (target.kind === 'dataset') {
+    const csv = datasetDocument(project.root, target)?.csv
+    const rows = csv ? fileDigest(join(project.root, csv)) : null
+    if (rows) hash.update(rows)
+  }
+  // A Function is bundled with what it imports: the other files in functions/ and the vendored SDK.
+  if (target.kind === 'function') {
+    hash.update(treeHash(join(project.root, 'functions')) ?? '').update(treeHash(join(project.root, 'vendor')) ?? '')
+  }
+  return hash.digest('hex')
+}
+
+function hashesPath(project: LocalProject): string {
+  return join(project.stateDir, 'applied-hashes.json')
+}
+
+export function loadHashes(project: LocalProject, organizationId: string): Map<string, string | null> {
+  try {
+    const saved = JSON.parse(readFileSync(hashesPath(project), 'utf8')) as { organizationId?: string; hashes?: Record<string, string> }
+    if (saved.organizationId === organizationId && saved.hashes) return new Map(Object.entries(saved.hashes))
+  } catch {
+    // Missing or unreadable: nothing counts as applied.
+  }
+  return new Map()
+}
+
+export function saveHashes(project: LocalProject, organizationId: string, applied: Map<string, string | null>): void {
+  const hashes = Object.fromEntries([...applied].filter((e): e is [string, string] => typeof e[1] === 'string'))
+  try {
+    writeFileAtomic(hashesPath(project), `${JSON.stringify({ organizationId, hashes })}\n`, 0o600)
+  } catch {
+    // Losing this only means the next start applies everything again.
+  }
+}
+
+export interface SolutionItem {
+  kind: SyncTarget['kind']
+  name: string
+  /** Path in the solution (the Blueprint is its folder). */
+  path: string
+  /** `applied`: the runtime has this content; `changed`: edited since; `new`: never applied here. */
+  state: 'applied' | 'changed' | 'new'
+}
+
+/** Each file `local dev` applies, and whether the runtime has its current content. */
+export function solutionStatus(project: LocalProject, organizationId: string | null): SolutionItem[] {
+  const applied = organizationId ? loadHashes(project, organizationId) : new Map<string, string | null>()
+  return allTargets(project.root).map((target) => {
+    const was = applied.get(target.key)
+    const now = contentHash(project, target)
+    return {
+      kind: target.kind,
+      name: describeTarget(target),
+      path: target.kind === 'blueprint' ? 'blueprint/' : target.file,
+      state: was === undefined ? 'new' : was === now ? 'applied' : 'changed',
+    }
+  })
+}