@frontera-sdk/cli 1.52.48 → 1.53.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontera-sdk/cli",
-  "version": "1.52.48",
+  "version": "1.53.1",
   "description": "The frontera CLI — scaffold, pull, save and deploy Frontera apps and automations.",
   "keywords": [
     "frontera",
@@ -40,8 +40,8 @@
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.251",
     "@faker-js/faker": "10.6.0",
-    "@frontera-sdk/core": "1.52.48",
-    "@frontera-sdk/functions": "1.52.48",
+    "@frontera-sdk/core": "1.53.1",
+    "@frontera-sdk/functions": "1.53.1",
     "ai": "^6.0.116",
     "axe-core": "4.12.1",
     "gray-matter": "^4.0.3",
@@ -49,7 +49,7 @@
     "yaml": "^2.9.0"
   },
   "devDependencies": {
-    "@frontera-sdk/forge-contracts": "1.52.48",
+    "@frontera-sdk/forge-contracts": "1.53.1",
     "@types/bun": "^1.3.14",
     "typescript": "^5.9.3"
   }

package/src/api/platform-api.ts

@@ -280,6 +280,22 @@ export class PlatformApi {
     return this.get<unknown>(`/v1/chat-apps/${encodeURIComponent(appId)}/editor`)
   }
 
+  // ── Workspace MCP servers ─────────────────────────────────────────────────
+
+  mcpServers(): Promise<{ servers: unknown[] }> {
+    return this.get<{ servers: unknown[] }>('/v1/mcp-servers')
+  }
+
+  /** One server, with the tools the caller cannot use now and why (`unavailable`). */
+  mcpServer(slug: string): Promise<{ server: unknown }> {
+    return this.get<{ server: unknown }>(`/v1/mcp-servers/${encodeURIComponent(slug)}`)
+  }
+
+  /** Archived, not deleted: the Function runs its tools started still name it. */
+  archiveMcpServer(slug: string): Promise<{ slug: string; archived: boolean }> {
+    return this.client.request<{ slug: string; archived: boolean }>(`/v1/mcp-servers/${encodeURIComponent(slug)}`, { method: 'DELETE' })
+  }
+
   /** Drafts are per principal: a key's draft is its own, not a person's. */
   saveChatAppDraft(appId: string, configuration: unknown) {
     return this.client.request<unknown>(`/v1/chat-apps/${encodeURIComponent(appId)}/draft`, {

package/src/commands/local/dev.ts

@@ -35,6 +35,7 @@ import { applyTheme, themeCalls } from '../../local/local-themes'
 import { ensureMediaSets, mediaUpload } from '../../local/local-media-sets'
 import { fillPlaceholderMedia } from '../../local/local-media-placeholders'
 import { applyChatApp, keyCalls } from '../../local/local-chat-apps'
+import { applyMcpServer } from '../../local/local-mcp-servers'
 import { applyLessons } from '../../local/local-lessons'
 import { applyStandIn, missingGrantInstalls, platformOnlyNames, readStandIn, standInNames, standInPath, writeGrantStandIn } from '../../local/local-stand-ins'
 import { projectProvides } from '../../local/local-adapt'
@@ -215,6 +216,11 @@ async function apply(project: LocalProject, target: SyncTarget, opts: ApplyOptio
     // The workspace key's draft too, so `frontera chat-app get` (which reads the key's own draft) shows what was applied.
     return withNotes(await applyChatApp(project.root, target.name, themeCalls(opts.serviceUrl, creds), lookup, projectProvides(project, creds.organizationId), creds.workspaceKey ? keyCalls(opts.serviceUrl, creds) : undefined))
   }
+  if (target.kind === 'mcp-server') {
+    // As the runtime's workspace key: the service checks each tool against what the runtime holds.
+    if (!creds?.workspaceKey) return { ok: false, output: 'error [LOCAL_NOT_SEEDED]: the runtime is not seeded yet' }
+    return withNotes(await applyMcpServer(project.root, target.name, target.file, keyCalls(opts.serviceUrl, creds)))
+  }
   if (target.kind === 'app') {
     if (!creds?.session) return { ok: false, output: 'error [LOCAL_NOT_SEEDED]: the runtime is not seeded yet' }
     return applyApp(project.root, target.name, themeCalls(opts.serviceUrl, creds), projectProvides(project, creds.organizationId))
@@ -1454,7 +1460,7 @@ async function dev(ctx: CommandContext) {
     return { data: { applied: done, unchanged, ...alreadyField, ...(warned.size ? { warnings: [...warned.values()] } : {}) }, text: `Applied ${done}${unchanged ? `, ${unchanged} unchanged` : ''}${alreadyText}` }
   }
 
-  ctx.output.note('Watching datasets/, blueprint/, knowledge/, skills/, mcp/, themes/, functions/, workflows/, agents/, chat-apps/, apps/, brand/ and library.json (Ctrl+C to stop)')
+  ctx.output.note('Watching datasets/, blueprint/, knowledge/, skills/, mcp/, themes/, functions/, workflows/, agents/, chat-apps/, apps/, mcp-servers/, brand/ and library.json (Ctrl+C to stop)')
   if (pending.size) schedule()
   // What failed while the runtime was down is applied once it answers again, not when its file next changes.
   const poller = setInterval(() => {

package/src/commands/mcp-server/index-commands.ts

@@ -0,0 +1,96 @@
+import { PlatformApi } from '../../api/platform-api'
+import { UsageError } from '../../errors'
+import { table } from '../../table'
+import type { Command } from '../types'
+
+/**
+ * A workspace's own MCP servers: what is on the workspace, and taking one out
+ * of service.
+ *
+ * A server is authored as `mcp-servers/<slug>.yaml` in a project and saved by
+ * `frontera local dev`, which also archives one whose file was removed. These
+ * commands cover the rest: seeing what a workspace serves and where a client
+ * connects, why a tool is left out for you, and archiving a server the project
+ * never had a file for.
+ */
+
+interface McpServerRow {
+  slug?: string
+  name?: string
+  url?: string
+  revision?: number
+  tools?: Array<{ name?: string; kind?: string; target?: string }>
+  unavailable?: Array<{ name?: string; reason?: string; temporary?: boolean }>
+}
+
+function serverRef(ctx: { positional: string[] }, verb: string): string {
+  const slug = ctx.positional[0]
+  if (!slug) throw new UsageError('missing <slug>', `frontera mcp-server list — then frontera mcp-server ${verb} <slug>`)
+  return slug
+}
+
+const list: Command = {
+  meta: {
+    noun: 'mcp-server',
+    verb: 'list',
+    args: [],
+    flags: {},
+    summary: 'List the MCP servers this workspace serves, and where a client connects to each',
+    examples: ['frontera mcp-server list', 'frontera mcp-server list --json'],
+  },
+  async run(ctx) {
+    const rows = ((await new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId).mcpServers()).servers ?? []) as McpServerRow[]
+    return {
+      data: rows,
+      text:
+        rows.length === 0
+          ? 'No MCP servers in this workspace. Add mcp-servers/<slug>.yaml to the project and run `frontera local dev` (`frontera local schema mcp-server` prints the format).'
+          : table(
+              ['slug', 'name', 'tools', 'url'],
+              rows.map((s) => [s.slug ?? '?', s.name ?? '', String(s.tools?.length ?? 0), s.url ?? '']),
+            ),
+    }
+  },
+}
+
+const get: Command = {
+  meta: {
+    noun: 'mcp-server',
+    verb: 'get',
+    args: [{ name: 'slug', required: true, description: 'MCP server slug' }],
+    flags: {},
+    summary: 'Show an MCP server: its tools, and any you cannot use now with the reason',
+    examples: ['frontera mcp-server get tracker'],
+  },
+  async run(ctx) {
+    const slug = serverRef(ctx, 'get')
+    const server = (await new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId).mcpServer(slug)).server as McpServerRow
+    const lines = [`${server.name ?? slug} (${slug}), revision ${server.revision ?? '?'}`, `  connect at ${server.url ?? '?'}`, '']
+    lines.push(table(['tool', 'kind', 'runs'], (server.tools ?? []).map((t) => [t.name ?? '?', t.kind ?? '', t.target ?? ''])))
+    for (const tool of server.unavailable ?? []) {
+      lines.push(`  ${tool.temporary ? 'for now, ' : ''}${tool.name ?? '?'} is left out for you: ${tool.reason ?? 'unavailable'}`)
+    }
+    return { data: server, text: lines.join('\n') }
+  },
+}
+
+const archive: Command = {
+  meta: {
+    noun: 'mcp-server',
+    verb: 'archive',
+    args: [{ name: 'slug', required: true, description: 'MCP server slug' }],
+    flags: {},
+    summary: 'Archive an MCP server: its URL stops answering at once, and its slug can be taken again',
+    examples: ['frontera mcp-server archive tracker'],
+  },
+  async run(ctx) {
+    const slug = serverRef(ctx, 'archive')
+    const result = await new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId).archiveMcpServer(slug)
+    return {
+      data: result,
+      text: `Archived MCP server ${slug}: clients connected to it get 404 from now on. Saving mcp-servers/${slug}.yaml again creates it anew.`,
+    }
+  },
+}
+
+export const mcpServerCommands: Command[] = [list, get, archive]

package/src/commands/registry.ts

@@ -41,6 +41,7 @@ import { mediaCommands } from './media/index-commands'
 import { packCommands } from './pack/index-commands'
 import { secretCommands } from './secret/index-commands'
 import { chatAppCommands } from './chat-app/index-commands'
+import { mcpServerCommands } from './mcp-server/index-commands'
 import { markingCommands } from './marking/index-commands'
 import { automationCommands } from './automation/index-commands'
 import { workflowCommands } from './workflow/index-commands'
@@ -133,6 +134,7 @@ export const COMMANDS: readonly Command[] = [
   ...packCommands,
   ...secretCommands,
   ...chatAppCommands,
+  ...mcpServerCommands,
   ...automationCommands,
   ...workflowCommands,
 
@@ -210,6 +212,7 @@ const NOUN_SUMMARY: Readonly<Record<string, string>> = {
   pack: 'Reusable skill bundles — author once, install per workspace',
   secret: 'Workspace secrets — named here, never printed back',
   'chat-app': 'Chat Apps — stage, publish and open an Agent roster',
+  'mcp-server': 'Workspace MCP servers — list, inspect and archive',
   function: 'Functions — TypeScript deployed here, run on a schedule',
   workflow: 'Workflows — declared steps, versioned, promoted, then run',
   blueprint: 'The shared model of the organization — what an app can read',

package/src/local/local-applied.ts

@@ -399,6 +399,8 @@ export function refOfTarget(target: SyncTarget): string {
       return `chat-app/${target.name}`
     case 'app':
       return `app/${target.name}`
+    case 'mcp-server':
+      return `mcp-server/${target.name}`
     case 'brand':
       return 'brand'
     case 'library':
@@ -419,6 +421,7 @@ const KIND_WORDS: Record<string, string> = {
   plugin: 'Plugin',
   model: 'model',
   dataset: 'dataset',
+  'mcp-server': 'MCP server',
 }
 
 /** `workflow/telco-fault-triage` → "workflow telco-fault-triage". */

package/src/local/local-apps.ts

@@ -167,7 +167,7 @@ export async function applyApp(root: string, slug: string, call: Call, provides:
 // ── A Custom App's code, in the project ─────────────────────────────────────
 
 /** Folders an App's code is never in: dependencies, build output, the project's state and its other kinds. */
-const NOT_APP_DIRS = new Set(['node_modules', '.git', '.frontera', '.next', 'dist', 'out', 'build', 'vendor', 'fixtures', 'datasets', 'blueprint', 'agents', 'workflows', 'functions', 'knowledge', 'skills', 'themes', 'mcp', 'chat-apps'])
+const NOT_APP_DIRS = new Set(['node_modules', '.git', '.frontera', '.next', 'dist', 'out', 'build', 'vendor', 'fixtures', 'datasets', 'blueprint', 'agents', 'workflows', 'functions', 'knowledge', 'skills', 'themes', 'mcp', 'mcp-servers', 'chat-apps'])
 
 export function readPackage(dir: string): { scripts?: Record<string, string>; frontera?: unknown } | null {
   try {

package/src/local/local-build-summary.ts

@@ -473,7 +473,7 @@ export function itemKindsText(rows: BuildRow[]): string {
     objectType: ['object type', 'object types'], linkType: ['link type', 'link types'], metric: ['metric', 'metrics'], semanticType: ['semantic type', 'semantic types'],
     sharedField: ['shared field', 'shared fields'], objectSet: ['saved object set', 'saved object sets'], action: ['governed Action', 'governed Actions'],
     knowledge: ['knowledge base', 'knowledge bases'], skill: ['skill', 'skills'], plugin: ['Plugin', 'Plugins'], theme: ['slide theme', 'slide themes'],
-    'chat-app': ['Chat App', 'Chat Apps'], app: ['Custom App', 'Custom Apps'],
+    'chat-app': ['Chat App', 'Chat Apps'], app: ['Custom App', 'Custom Apps'], 'mcp-server': ['MCP server', 'MCP servers'],
   }
   const counts = new Map<string, number>()
   for (const r of rows) {

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

@@ -27,6 +27,7 @@ import { widerGrants, type WorkspaceGrant } from './local-workspace-grants'
  *   themes/<name>/theme.json (+ images) → the slide theme saved on the runtime (replacing its copy)
  *   chat-apps/<slug>.json               → the Chat App saved on the runtime (the owner's draft; published when it can be)
  *   apps/<slug>.json                    → the Custom App made on the runtime, with the Functions it may start (not its code)
+ *   mcp-servers/<slug>.yaml|.yml|.json  → the workspace's MCP server of that slug, saved on the runtime (PUT /v1/mcp-servers/<slug>)
  *   brand/brand.json (+ logo)           → the organization's colors and logo on the runtime
  *   library.json                        → the library installations, checked against the runtime's library (not installed)
  *
@@ -53,9 +54,13 @@ export type SyncTarget =
   | { kind: 'theme'; key: string; name: string; file: string }
   | { kind: 'chat-app'; key: string; name: string; file: string }
   | { kind: 'app'; key: string; name: string; file: string }
+  | { kind: 'mcp-server'; key: string; name: string; file: string }
   | { kind: 'brand'; key: string; file: string }
   | { kind: 'library'; key: string; file: string }
 
+/** `mcp-servers/<slug>.yaml`: a slug as the service takes it (lowercase, digits, dashes; a letter first). */
+const MCP_SERVER_FILE = /^[a-z][a-z0-9-]{0,62}\.(ya?ml|json)$/
+
 const IGNORED_DIRS = new Set(['node_modules', '.frontera', '.git', 'dist', 'fixtures'])
 
 /** Hidden files and editor leftovers: `.#x.yaml` locks, `#x#` autosaves, `x~` backups, `.swp`. */
@@ -122,6 +127,11 @@ export function targetFor(root: string, absolute: string): SyncTarget | null {
     const name = second.slice(0, -'.json'.length)
     return { kind: 'app', key: `app:${name}`, name, file: rel }
   }
+  // A workspace MCP server: its file's name is its slug (the last segment of its URL).
+  if (top === 'mcp-servers' && parts.length === 2 && second && MCP_SERVER_FILE.test(second)) {
+    const name = second.replace(/\.(ya?ml|json)$/, '')
+    return { kind: 'mcp-server', key: `mcp-server:${name}`, name, file: rel }
+  }
   // The brand is its file and the logo beside it.
   if (top === 'brand' && parts.length === 2 && existsSync(join(root, 'brand', 'brand.json'))) return { kind: 'brand', key: 'brand', file: join('brand', 'brand.json') }
   if (rel === 'library.json') return { kind: 'library', key: 'library', file: 'library.json' }
@@ -219,7 +229,7 @@ export function allTargets(root: string): SyncTarget[] {
       }
     }
   }
-  for (const top of ['datasets', 'blueprint', 'knowledge', 'skills', 'mcp', 'themes', 'functions', 'workflows', 'agents', 'chat-apps', 'apps', 'brand']) walk(join(root, top), 1)
+  for (const top of ['datasets', 'blueprint', 'knowledge', 'skills', 'mcp', 'themes', 'functions', 'workflows', 'agents', 'chat-apps', 'apps', 'mcp-servers', 'brand']) walk(join(root, top), 1)
   if (existsSync(join(root, 'library.json'))) out.set('library', { kind: 'library', key: 'library', file: 'library.json' })
   // Datasets first (object types read them), then the Blueprint (Agents and
   // workflows read its objects), then what Agents use by name (knowledge
@@ -227,11 +237,12 @@ export function allTargets(root: string): SyncTarget[] {
   // Agents call them), then Agents (a workflow's agent step names one), then workflows, then what
   // each Agent may start, then the Agents' behavior settings (a procedure runs
   // only what its Agent may start), then the Chat Apps their Agents are used in and the Apps that
-  // start Functions. The brand first of all (it is how everything looks), the library record last.
+  // start Functions, and the MCP servers whose tools name Functions, workflows, Actions and object types.
+  // The brand first of all (it is how everything looks), the library record last.
   return [...out.values()].sort(byApplyOrder)
 }
 
-const ORDER = { brand: -1, dataset: 0, blueprint: 1, knowledge: 2, theme: 2, skill: 3, plugin: 4, function: 5, agent: 6, workflow: 7, bindings: 8, operating: 9, lessons: 9, 'chat-app': 10, app: 10, library: 11 }
+const ORDER = { brand: -1, dataset: 0, blueprint: 1, knowledge: 2, theme: 2, skill: 3, plugin: 4, function: 5, agent: 6, workflow: 7, bindings: 8, operating: 9, lessons: 9, 'chat-app': 10, app: 10, 'mcp-server': 10, library: 11 }
 
 /** Dependencies first: what a later kind reads or calls is applied before it. */
 export function byApplyOrder(a: SyncTarget, b: SyncTarget): number {
@@ -291,6 +302,7 @@ export function commandFor(target: SyncTarget, profiles: SyncProfiles): string[]
     case 'theme':
     case 'chat-app':
     case 'app':
+    case 'mcp-server':
     case 'brand':
     case 'library':
     case 'lessons':
@@ -435,6 +447,8 @@ export function describeTarget(target: SyncTarget): string {
       return `Chat App ${target.name}`
     case 'app':
       return `App ${target.name}`
+    case 'mcp-server':
+      return `MCP server ${target.name}`
     case 'brand':
       return 'the organization’s brand'
     case 'library':
@@ -496,6 +510,10 @@ export function unappliedReason(root: string, rel: string): string | null {
       return `skills/${second}/ has no SKILL.md, so it is not pushed`
     case 'chat-apps':
       return 'a Chat App is chat-apps/<slug>.json, directly in chat-apps/'
+    case 'mcp-servers':
+      if (parts.length > 2) return 'an MCP server is mcp-servers/<slug>.yaml, directly in mcp-servers/ (`frontera local schema mcp-server`)'
+      if (!/\.(ya?ml|json)$/.test(name)) return 'an MCP server is mcp-servers/<slug>.yaml (or .yml, .json)'
+      return `an MCP server's file is named by its slug: lowercase letters, digits and dashes, starting with a letter (mcp-servers/${name.replace(/\.(ya?ml|json)$/, '').toLowerCase().replace(/[^a-z0-9-]+/g, '-').replace(/^[^a-z]+/, '') || 'my-server'}.yaml)`
     case 'mcp':
       return 'a Plugin is mcp/<name>.plugin.json (a stand-in mcp/<name>.stand-in.json)'
     default:
@@ -544,6 +562,6 @@ export function unappliedFiles(root: string): string[] {
       }
     }
   }
-  for (const top of ['agents', 'blueprint', 'chat-apps', 'datasets', 'knowledge', 'mcp', 'skills', 'themes', 'workflows']) walk(join(root, top), 1)
+  for (const top of ['agents', 'blueprint', 'chat-apps', 'datasets', 'knowledge', 'mcp', 'mcp-servers', 'skills', 'themes', 'workflows']) walk(join(root, top), 1)
   return out
 }

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

@@ -14,7 +14,7 @@ import { join, posix } from 'node:path'
  */
 
 /** Top folders whose files are items of their own (or tooling), never a Function's shared file. */
-const ITEM_FOLDERS = new Set(['agents', 'workflows', 'skills', 'knowledge', 'blueprint', 'mcp', 'chat-apps', 'themes', 'datasets', 'apps', 'brand', 'functions', 'vendor', 'node_modules', 'dist'])
+const ITEM_FOLDERS = new Set(['agents', 'workflows', 'skills', 'knowledge', 'blueprint', 'mcp', 'mcp-servers', 'chat-apps', 'themes', 'datasets', 'apps', 'brand', 'functions', 'vendor', 'node_modules', 'dist'])
 
 /** Project files that are the project's own, never a Function's. */
 const PROJECT_FILES = new Set(['frontera.yaml', 'frontera.lock', 'package.json', 'tsconfig.json', 'bun.lock', 'bun.lockb', 'library.json'])

package/src/local/local-mcp-servers.ts

@@ -0,0 +1,66 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { parse as parseYaml } from 'yaml'
+
+import { errorOf } from './local-chat-apps'
+
+/**
+ * A workspace's own MCP servers: `mcp-servers/<slug>.yaml` (or .yml, .json),
+ * one server per file, named by its slug. `local dev` saves each on the local
+ * runtime (`PUT /v1/mcp-servers/<slug>`, as the runtime's workspace key), and
+ * the service checks every tool against what the runtime holds: the object
+ * types the workspace is granted, its Functions, workflows and governed
+ * Actions. A server whose file is deleted is archived on the runtime.
+ *
+ * Its format is the service's (`frontera local schema mcp-server`).
+ */
+
+type Call = (method: string, path: string, body?: unknown) => Promise<{ status: number; body: unknown }>
+
+export const mcpServerPath = (slug: string, ext = 'yaml') => `mcp-servers/${slug}.${ext}`
+
+export interface McpServerApplied {
+  ok: boolean
+  output: string
+}
+
+interface SavedServer {
+  server?: { slug?: string; name?: string; url?: string; tools?: unknown[] }
+  created?: boolean
+  warnings?: Array<{ name?: string; reason?: string }>
+}
+
+/** The file as the service takes it: YAML or JSON, a mapping at the top. */
+export function readMcpServerFile(root: string, file: string): { ok: true; doc: Record<string, unknown> } | { ok: false; output: string } {
+  const path = join(root, file)
+  if (!existsSync(path)) return { ok: false, output: `error [MCP_SERVER]: ${file} is missing` }
+  let doc: unknown
+  try {
+    const text = readFileSync(path, 'utf8')
+    doc = file.endsWith('.json') ? JSON.parse(text) : parseYaml(text)
+  } catch (err) {
+    return { ok: false, output: `error [MCP_SERVER]: ${file} can't be read: ${(err as Error).message.split('\n')[0]}` }
+  }
+  if (!doc || typeof doc !== 'object' || Array.isArray(doc)) {
+    return { ok: false, output: `error [MCP_SERVER]: ${file} must be a mapping with name, instructions and tools (\`frontera local schema mcp-server\`)` }
+  }
+  return { ok: true, doc: doc as Record<string, unknown> }
+}
+
+/** Save one server on the runtime; the line says where a client connects, or what the service refused. */
+export async function applyMcpServer(root: string, slug: string, file: string, call: Call): Promise<McpServerApplied> {
+  const read = readMcpServerFile(root, file)
+  if (!read.ok) return read
+  const res = await call('PUT', `/v1/mcp-servers/${encodeURIComponent(slug)}`, read.doc)
+  if (res.status !== 200 && res.status !== 201) {
+    return { ok: false, output: `error [MCP_SERVER]: MCP server ${slug} was refused: ${errorOf(res)}` }
+  }
+  const saved = ((res.body as { data?: unknown } | null)?.data ?? res.body) as SavedServer | null
+  const tools = saved?.server?.tools?.length ?? 0
+  const url = saved?.server?.url
+  const lines = [`  ${saved?.created ? 'created' : 'applied'} MCP server ${slug} (${tools} tool${tools === 1 ? '' : 's'})${url ? ` — connect at ${url}` : ''}`]
+  for (const warning of saved?.warnings ?? []) {
+    lines.push(`  warning: MCP server ${slug}: tool ${warning.name ?? '?'} is offered to nobody for now: ${warning.reason ?? 'unavailable'}`)
+  }
+  return { ok: true, output: lines.join('\n') }
+}

package/src/local/local-new.ts

@@ -88,7 +88,7 @@ export function writeNewFiles(root: string, files: Record<string, string>): stri
 // ── fmt ─────────────────────────────────────────────────────────────────────
 
 /** The folders whose JSON and YAML are project files; an App's own code and the tool state are left alone. */
-const FORMATTED_DIRS = ['agents', 'workflows', 'blueprint', 'knowledge', 'skills', 'chat-apps', 'themes', 'datasets', 'mcp']
+const FORMATTED_DIRS = ['agents', 'workflows', 'blueprint', 'knowledge', 'skills', 'chat-apps', 'themes', 'datasets', 'mcp', 'mcp-servers']
 const FORMATTED_ROOT_FILES = ['frontera.yaml']
 const FORMATTED = /\.(json|ya?ml)$/
 

package/src/local/local-operating.ts

@@ -4,7 +4,7 @@ import type { LocalCredentials } from './local-state'
 
 /**
  * An Agent's behavior settings (`agents/<slug>/operating.json`: harness,
- * procedures, variables, focus, reply checks) staged onto its draft.
+ * procedures, variables, focus, reply checks, handover reasons) staged onto its draft.
  *
  * There is no CLI command for these: the route takes a person's session, not
  * an API key. The local runtime has the owner's session, as Studio does, so
@@ -31,6 +31,26 @@ interface Issue {
   message?: string
 }
 
+const isRecord = (v: unknown): v is Record<string, unknown> => !!v && typeof v === 'object' && !Array.isArray(v)
+
+/**
+ * The keys of the handover reasons an Agent has while its operating.json sets
+ * none, as the service's `DEFAULT_HANDOVER_REASONS` (`handover-reasons.ts`)
+ * holds them: what a handoff action's `handoverReason` may name then.
+ */
+export const DEFAULT_HANDOVER_REASON_KEYS = ['asked_for_person', 'cannot_answer', 'needs_action', 'other'] as const
+
+/** The reason keys a saved configuration offers: its own, or the defaults. */
+function reasonKeys(config: unknown): string[] {
+  const own = isRecord(config) && Array.isArray(config.handoverReasons) ? (config.handoverReasons as unknown[]).flatMap((r) => (isRecord(r) && typeof r.key === 'string' ? [r.key] : [])) : []
+  return own.length ? own : [...DEFAULT_HANDOVER_REASON_KEYS]
+}
+
+/** What to do about a refused `handoverReasons` list, said once after its problems. */
+function handoverReasonsFix(slug: string): string {
+  return `  Fix: in agents/${slug}/operating.json give "handoverReasons" 1 to 15 reasons, each { "key", "name", "whenToUse" } with a unique lower_snake_case key (at most 40 characters), a name of 1 to 60 characters and whenToUse of 1 to 300, one of them with the key "other"; or leave "handoverReasons" out for the default reasons. \`frontera local schema operating\` gives the format`
+}
+
 /**
  * The issues a saved draft still has, one `warning:` line each, named by the
  * project file and the setting's path
@@ -39,31 +59,104 @@ interface Issue {
  * with the warnings and refuses publishing, so it is said too, as that.
  */
 export function operatingIssueLines(slug: string, body: unknown): string[] {
-  const data = ((body as { data?: unknown } | null)?.data ?? body) as { issues?: unknown } | null
+  const data = ((body as { data?: unknown } | null)?.data ?? body) as { issues?: unknown; draft?: unknown } | null
   const issues = Array.isArray(data?.issues) ? (data.issues as Issue[]) : []
   return issues.map((issue) => {
     const path = typeof issue.path === 'string' ? issue.path : ''
     // The Agent's instructions are its agent.json prompts, not its behavior settings.
     const file = path === 'instructions' || path.startsWith('instructions.') ? `agents/${slug}/agent.json` : `agents/${slug}/operating.json`
     const blocks = issue.severity === 'error' ? ' (publishing is refused until this is fixed)' : ''
-    return `  warning: ${file}${path ? ` ${path}` : ''}: ${issue.message ?? issue.code ?? 'see the Agent’s settings'}${blocks}`
+    // A handoff action naming a reason the Agent doesn't have: say which keys it has.
+    const fix = issue.code === 'unknown_handover_reason'
+      ? `; set "handoverReason" to one of ${reasonKeys(data?.draft).map((k) => `"${k}"`).join(', ')}, or add the reason to "handoverReasons"`
+      : ''
+    return `  warning: ${file}${path ? ` ${path}` : ''}: ${issue.message ?? issue.code ?? 'see the Agent’s settings'}${fix}${blocks}`
   })
 }
 
-function describeError(status: number, body: unknown): string {
+function describeError(status: number, body: unknown, slug?: string): string {
   const b = (body ?? {}) as { message?: string; code?: string; details?: unknown; issues?: unknown }
   const lines = [`error [${b.code ?? status}]: ${b.message ?? 'the behavior settings were refused'}`]
   const issues = (b.details as { issues?: unknown } | undefined)?.issues ?? b.issues ?? b.details
   if (Array.isArray(issues)) {
-    for (const issue of issues.slice(0, 6)) {
-      const i = issue as { path?: unknown; message?: string }
-      const path = Array.isArray(i.path) ? i.path.join('.') : typeof i.path === 'string' ? i.path : ''
-      lines.push(`  ${path ? `${path}: ` : ''}${i.message ?? JSON.stringify(issue)}`)
-    }
+    const paths = issues.map((issue) => {
+      const i = issue as { path?: unknown }
+      return Array.isArray(i.path) ? i.path.join('.') : typeof i.path === 'string' ? i.path : ''
+    })
+    issues.slice(0, 6).forEach((issue, n) => {
+      const path = paths[n]!
+      lines.push(`  ${path ? `${path}: ` : ''}${(issue as { message?: string }).message ?? JSON.stringify(issue)}`)
+    })
+    // The rules of the handover reasons, said once: the service's words name one problem each, not the whole rule.
+    if (slug && paths.some((p) => p === 'handoverReasons' || p.startsWith('handoverReasons.'))) lines.push(handoverReasonsFix(slug))
   }
   return lines.join('\n')
 }
 
+/**
+ * The settings the file has that the saved draft does not: a runtime on a
+ * release older than the file's format keeps only the keys it knows and
+ * drops the rest without an error. Each is a warning that says it is left
+ * out here and how to run the release that has it. The keys checked are the
+ * top-level settings and each action's `handoverReason`; nothing is said when
+ * the answer carries no draft to compare.
+ */
+export function droppedSettingLines(slug: string, sent: unknown, saved: unknown): string[] {
+  if (!isRecord(sent) || !isRecord(saved)) return []
+  const file = `agents/${slug}/operating.json`
+  const next = 'to use it here, run the runtime on the current release: `frontera local stop`, then `frontera local start`'
+  // Settings the service retired and drops on purpose (`dropRetiredKeys`).
+  const retired = new Set(['audience', 'conversation'])
+  const out = Object.keys(sent)
+    // `$schema` and other editor keys are not settings.
+    .filter((key) => !key.startsWith('$') && !retired.has(key) && !(key in saved))
+    .map((key) => key === 'handoverReasons'
+      ? `  warning: ${file} handoverReasons: this runtime's release has no handover reasons, so it left them out: here the Agent hands over without them; they still apply where the Agent runs on a release that has them. To use them here, run the runtime on the current release: \`frontera local stop\`, then \`frontera local start\``
+      : `  warning: ${file} ${key}: this runtime's format has no \`${key}\`, so it is left out here: check the name against \`frontera local schema operating\`, or, for a setting of a newer release, ${next}`)
+  const sentProcedures = Array.isArray(sent.procedures) ? sent.procedures : []
+  const savedProcedures = Array.isArray(saved.procedures) ? saved.procedures : []
+  sentProcedures.forEach((p, i) => {
+    const kept = savedProcedures[i]
+    if (!isRecord(p) || !isRecord(kept)) return
+    if (Array.isArray(p.actions) && Array.isArray(kept.actions)) {
+      p.actions.forEach((a, j) => {
+        const k = (kept.actions as unknown[])[j]
+        if (isRecord(a) && typeof a.handoverReason === 'string' && isRecord(k) && !('handoverReason' in k)) {
+          out.push(`  warning: ${file} procedures.${i}.actions.${j}.handoverReason: this runtime's release has no handover reasons, so the action hands over without "${a.handoverReason}" here; ${next}`)
+        }
+      })
+    }
+    // An End step that hands over, wherever it sits in the procedure's steps.
+    const endSteps = (sentSteps: unknown, keptSteps: unknown, path: string) => {
+      if (!Array.isArray(sentSteps) || !Array.isArray(keptSteps)) return
+      sentSteps.forEach((s, j) => {
+        const k = keptSteps[j]
+        if (!isRecord(s) || !isRecord(k)) return
+        const at = `${path}.${j}`
+        if (s.type === 'end' && typeof s.handoverReason === 'string' && !('handoverReason' in k)) {
+          out.push(`  warning: ${file} ${at}.handoverReason: this runtime's release has no handover reasons, so the step hands over without "${s.handoverReason}" here; ${next}`)
+        }
+        endSteps(s.onFailure, k.onFailure, `${at}.onFailure`)
+        endSteps(s.otherwise, k.otherwise, `${at}.otherwise`)
+        if (Array.isArray(s.arms) && Array.isArray(k.arms)) {
+          s.arms.forEach((arm, ai) => {
+            const keptArm = (k.arms as unknown[])[ai]
+            if (isRecord(arm) && isRecord(keptArm)) endSteps(arm.steps, keptArm.steps, `${at}.arms.${ai}.steps`)
+          })
+        }
+      })
+    }
+    endSteps(p.steps, kept.steps, `procedures.${i}.steps`)
+    if (Array.isArray(p.blocks) && Array.isArray(kept.blocks)) {
+      p.blocks.forEach((b, bi) => {
+        const keptBlock = (kept.blocks as unknown[])[bi]
+        if (isRecord(b) && isRecord(keptBlock)) endSteps(b.steps, keptBlock.steps, `procedures.${i}.blocks.${bi}.steps`)
+      })
+    }
+  })
+  return out
+}
+
 export async function applyOperatingConfig(args: {
   serviceUrl: string
   creds: LocalCredentials
@@ -111,9 +204,11 @@ export async function applyOperatingConfig(args: {
     }
     if (agent.status !== 200 || !id) return { ok: false, output: describeError(agent.status, agent.body) }
     const put = await call(`/v1/config/agents/${id}/operating`, { method: 'PUT', body: { operatingConfig } })
-    if (put.status >= 400) return { ok: false, output: describeError(put.status, put.body) }
+    if (put.status >= 400) return { ok: false, output: describeError(put.status, put.body, args.slug) }
     const warnings = operatingIssueLines(args.slug, put.body)
-    return { ok: true, output: warnings.join('\n'), ...(warnings.length ? { validationWarnings: warnings } : {}) }
+    // What this runtime's release left out is an adaptation to it, not a finding on the file.
+    const dropped = droppedSettingLines(args.slug, operatingConfig, (put.body as { data?: { draft?: unknown } } | null)?.data?.draft)
+    return { ok: true, output: [...warnings, ...dropped].join('\n'), ...(warnings.length ? { validationWarnings: warnings } : {}) }
   } catch (err) {
     return { ok: false, output: `error [UNAVAILABLE]: the local service did not answer: ${(err as Error).message}` }
   }