@frontera-sdk/cli 1.52.47 → 1.53.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontera-sdk/cli",
-  "version": "1.52.47",
+  "version": "1.53.0",
   "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.47",
-    "@frontera-sdk/functions": "1.52.47",
+    "@frontera-sdk/core": "1.53.0",
+    "@frontera-sdk/functions": "1.53.0",
     "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.47",
+    "@frontera-sdk/forge-contracts": "1.53.0",
     "@types/bun": "^1.3.14",
     "typescript": "^5.9.3"
   }

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}` }
   }

package/src/local/local-scaffold.ts

@@ -176,7 +176,7 @@ A Frontera project. Every file here is applied to a local runtime by
 | Path | What it is |
 |---|---|
 | \`agents/<slug>/agent.json\` | An Agent's draft: model, instructions, tools |
-| \`agents/<slug>/operating.json\` | Its behavior: procedures, variables, focus, reply checks |
+| \`agents/<slug>/operating.json\` | Its behavior: procedures, variables, focus, reply checks, handover reasons |
 | \`agents/<slug>/bindings.json\` | What it may use: Functions, workflows, Blueprint object types |
 | \`agents/<slug>/evals/*.yaml\` | Its test cases |
 | \`workflows/<slug>.yaml\` | A workflow |
@@ -301,7 +301,7 @@ Frontera deployment.
 | Path | What it is |
 |---|---|
 | \`agents/<slug>/agent.json\` | An Agent's draft: model, instructions, tools |
-| \`agents/<slug>/operating.json\` | Its behavior: procedures, variables, focus, reply checks |
+| \`agents/<slug>/operating.json\` | Its behavior: procedures, variables, focus, reply checks, handover reasons |
 | \`agents/<slug>/bindings.json\` | What it may use: the Functions and workflows it may start, the Blueprint object types it may query |
 | \`agents/<slug>/evals/*.yaml\` | Its test cases: a conversation and what a good reply does |
 | \`workflows/<slug>.yaml\` | A workflow |

package/src/local/local-schemas.ts

@@ -6,6 +6,7 @@ import { BLUEPRINT_SCHEMA_FILES, BLUEPRINT_SCHEMAS } from './local-blueprint-sch
 import type { LocalProject } from './local-project'
 import { isAlive, readState } from './local-state'
 import { PROCEDURE_TOOL_FORMS, PROCEDURE_TOOL_GROUPS } from './local-agent-checks'
+import { DEFAULT_HANDOVER_REASON_KEYS } from './local-operating'
 import { REF_KINDS, refPattern, type RefKind } from './local-sync-refs'
 
 /**
@@ -888,6 +889,27 @@ function describeProjectFields(props: Record<string, unknown>): void {
   if ('dataScopes' in props && 'variables' in props) {
     describe(props, 'dataScopes', 'Optional. Narrows what the Agent reads of an object type to the records of the conversation: `[{ "objectType": "WorkOrder", "property": "customerId", "equals": "{{customer_id}}" }]`, at most one per object type. Every read of that type (query, fetch, aggregate, saved sets, links, media and metrics) sees only rows whose property equals the conversation variable; a conversation without the variable sees none. The variable is one in `variables`, and the property and variable are text or numbers. The object type must be granted in bindings.json `blueprint`. In an eval case, `variables` gives the conversation its values.')
   }
+  // Behavior settings (operating.json): why the Agent hands a conversation to people.
+  if ('handoverReasons' in props && 'variables' in props) {
+    const reasons = props.handoverReasons
+    const item = isRecord(reasons) && isRecord(reasons.items) ? reasons.items : null
+    if (isRecord(reasons) && item && isRecord(item.properties)) {
+      const inner = { ...item.properties }
+      describe(inner, 'key', 'The reason’s id: lower snake case (`order_problem`), at most 40 characters, unique in the list. Hand-over reports count by it, so keep it once the Agent is published; a handoff action names it in `handoverReason`.')
+      describe(inner, 'name', 'What people see in hand-over reports and the inbox (`Order problem`), 1 to 60 characters.')
+      describe(inner, 'whenToUse', 'What the Agent reads to choose this reason (`The customer reports a late, wrong or damaged order.`), 1 to 300 characters.')
+      props.handoverReasons = { ...reasons, items: { ...item, properties: inner } }
+    }
+    describe(props, 'handoverReasons', `Optional. Why the Agent hands a conversation to people; hand-over reports count by these. 1 to 15 reasons, each \`{ "key", "name", "whenToUse" }\`, keys unique, names unique ignoring case, and one must have the key \`other\` (rename it, never remove it). Leave the key out to use the default reasons (${DEFAULT_HANDOVER_REASON_KEYS.map((k) => `\`${k}\``).join(', ')}); a pull writes it only when the Agent has its own. \`frontera local dev\` refuses a list that breaks these rules, with each problem's path.`)
+  }
+  // A procedure's action (operating.json `procedures[].actions[]`): the reason a handoff records.
+  if ('handoverReason' in props && 'requiresFields' in props) {
+    describe(props, 'handoverReason', 'Optional, for a `handoff` action: the `key` of one of the Agent’s `handoverReasons` (the defaults when the file has none), recorded on the hand-over when a Step by step procedure runs the action. Absent: `other`. A key the Agent doesn’t have is reported by `frontera local dev` and refuses publishing.')
+  }
+  // A Step by step End step (operating.json `procedures[].blocks[].steps[]`): the reason one that hands over records.
+  if ('handoverReason' in props && 'outcome' in props) {
+    describe(props, 'handoverReason', 'Optional, for an End step with `outcome` `handoff`: the `key` of one of the Agent’s `handoverReasons` (the defaults when the file has none), recorded on the hand-over. Absent: `other`. A key the Agent doesn’t have is reported by `frontera local dev` and refuses publishing.')
+  }
   // An Agent (agent.json): the lists that name other resources.
   if ('modelConfigs' in props && 'knowledgeAttachments' in props) {
     describe(props, 'knowledgeAttachments', 'The knowledge bases the Agent searches: `[{ "knowledgeConfigId": "knowledge/<name>" }]`, one per base in knowledge/<name>/knowledge.json (`retrievalOverride` optional). `local dev` resolves each to this runtime’s id. When the key is present it is the Agent’s whole list (a base it leaves out is detached); leave the key out to keep the attachments made with `frontera knowledge attach`.', {