@frontera-sdk/cli 1.52.39 → 1.52.40

package/src/local/local-actions.ts

@@ -1,5 +1,6 @@
 import { randomUUID } from 'node:crypto'
 
+import { issueLines } from '../api/governed-action-api'
 import { deriveOntologyEditPlan, PlanDerivationError, type ObjectTypeShape, type PublishedActionDefinition } from '../blueprint/ontology-edit-plan'
 import type { ActionFit } from './local-portability'
 import type { LocalCredentials } from './local-state'
@@ -71,13 +72,37 @@ function data<T>(answer: Answer): T {
 }
 
 function message(answer: Answer): string {
-  const b = answer.body as { message?: unknown; error?: unknown } | null
+  const b = answer.body as { message?: unknown; error?: unknown; details?: unknown } | null
   const text = typeof b?.message === 'string' ? b.message : typeof b === 'string' ? b : JSON.stringify(b)
-  return `${answer.status} ${String(text).replace(/\s+/g, ' ').slice(0, 240)}`
+  // The reason a generic refusal ("Mutation Plan is invalid.") keeps in its issues.
+  const issues = b && typeof b === 'object' ? issueLines(b.details) : []
+  return `${answer.status} ${String(text).replace(/\s+/g, ' ').slice(0, 240)}${issues.length ? ` ${issues.join('; ').slice(0, 400)}` : ''}`
 }
 
 const ADMIN = '/v1/blueprint/governed-actions/admin'
 
+/**
+ * A validation report's failed findings, one line each, as the deployment
+ * router returns them (`findings: [{ source, code, passed, message }]`): the
+ * code and the platform's message. Empty when the report carries no such list
+ * (an older runtime), so the caller falls back to `failedChecks`.
+ */
+export function validationFindings(report: unknown): string[] {
+  const findings = (report as { findings?: unknown } | null)?.findings
+  if (!Array.isArray(findings)) return []
+  return [
+    ...new Set(
+      findings.flatMap((f) => {
+        if (!f || typeof f !== 'object') return []
+        const o = f as { code?: unknown; passed?: unknown; message?: unknown }
+        if (o.passed !== false) return []
+        const code = typeof o.code === 'string' ? o.code : 'check'
+        return [typeof o.message === 'string' && o.message ? `${code}: ${o.message}` : code]
+      }),
+    ),
+  ]
+}
+
 /** The checks a validation report failed, by name: its findings with `passed: false`, anywhere in it. */
 function failedChecks(report: unknown): string {
   const names: string[] = []
@@ -200,16 +225,33 @@ export interface ActionBuild {
   status: ActionBuildStatus
   /** Why it is not running, in words. */
   reason?: string
+  /** failed: the deployment validation's failed findings, `code: message` each, when the runtime gave them. */
+  findings?: string[]
+  /** left-off: the runtime refused the Action's own file (a failure to fix), not left off by design. */
+  refused?: boolean
+  /**
+   * Deployed as the workspace runs it, with these warnings inherited from the
+   * workspace: a value it offers that the semantic type it writes refuses.
+   */
+  inherited?: string[]
 }
 
 interface Deployable {
   definition: PublishedActionDefinition
   contractDigest: string
   deploymentStatus?: string
+  availability?: string
+  reason?: string | null
+}
+
+/** Why one Action's write path did not deploy: a sentence, and the validation's failed findings when it had any. */
+interface DeployFailure {
+  reason: string
+  findings?: string[]
 }
 
 /** The write path for one Action that writes the Blueprint's records: built, validated, reviewed, activated. */
-async function deployOne(call: Call, published: Deployable): Promise<string | null> {
+async function deployOne(call: Call, published: Deployable): Promise<string | DeployFailure | null> {
   const { definition, contractDigest } = published
   const types = data<Array<{ id?: string; apiName?: string }>>(await call('org', 'GET', '/v1/blueprint/object-types')) ?? []
   const subject = (Array.isArray(types) ? types : []).find((t) => t.id === definition.subject.objectTypeId)?.apiName
@@ -238,7 +280,11 @@ async function deployOne(call: Call, published: Deployable): Promise<string | nu
   const bindingRevisionId = data<{ id: string }>(binding).id
   const validation = await call('org', 'POST', `${ADMIN}/binding-revisions/${bindingRevisionId}/validate`, { expectedStateGeneration: 1 })
   const report = data<{ id?: string; status?: string; findings?: unknown }>(validation)
-  if (validation.status >= 300 || report?.status !== 'valid') return `its write path did not validate: ${validation.status >= 300 ? message(validation) : failedChecks(report)}`
+  if (validation.status >= 300 || report?.status !== 'valid') {
+    const findings = validation.status >= 300 ? [] : validationFindings(report)
+    if (findings.length) return { reason: `its write path did not validate (${findings.length} failed check${findings.length === 1 ? '' : 's'})`, findings }
+    return `its write path did not validate: ${validation.status >= 300 ? message(validation) : failedChecks(report)}`
+  }
   // A different principal from the key that built it: the service insists.
   const reviewed = await call('session', 'POST', `${ADMIN}/binding-revisions/${bindingRevisionId}/review`, { validationReportId: report.id, expectedStateGeneration: 2 })
   if (reviewed.status >= 300) return `its review was refused: ${message(reviewed)}`
@@ -288,19 +334,66 @@ export async function deployActions(call: Call, actions: LocalAction[]): Promise
       continue
     }
     const published = data<Deployable>(read)
-    let failure: string | null = null
-    if (published.deploymentStatus !== 'active') {
+    let failure: DeployFailure | null = null
+    // Not active, or active on a write path whose validation no longer holds: built again.
+    if (published.deploymentStatus !== 'active' || published.reason === 'ACTION_BINDING_VALIDATION_STALE') {
       try {
-        failure = await deployOne(call, published)
+        const why = await deployOne(call, published)
+        failure = typeof why === 'string' ? { reason: why } : why
       } catch (err) {
-        failure = (err as Error).message
+        failure = { reason: (err as Error).message }
       }
     }
     if (!failure && action.invokeCapability) {
       const granted = await call('session', 'POST', `${ADMIN}/capability-grants`, { capability: action.invokeCapability, role: 'owner', revoke: false })
-      if (granted.status >= 300) failure = `it is deployed, but the owner role could not be allowed to run it: ${message(granted)}`
+      if (granted.status >= 300) failure = { reason: `it is deployed, but the owner role could not be allowed to run it: ${message(granted)}` }
     }
-    out[action.apiName] = failure ? { status: 'failed', reason: failure } : { status: 'runs' }
+    out[action.apiName] = failure ? { status: 'failed', reason: failure.reason, ...(failure.findings?.length ? { findings: failure.findings } : {}) } : { status: 'runs' }
+  }
+  return out
+}
+
+/** One published Action's deployment on the runtime, as `?view=deployable` answers it: what `frontera action list` reads too. */
+export interface LiveAction {
+  deploymentStatus: string
+  availability?: string
+  reason?: string | null
+}
+
+/** Whether a live Action runs: deployed, active, and its deployment validated against its published contract. */
+export function liveActionRuns(live: LiveAction | undefined): boolean {
+  return !!live && live.deploymentStatus === 'active' && (live.availability === undefined || live.availability === 'available')
+}
+
+/**
+ * Every published Action's deployment on the local runtime, by apiName, from
+ * the same view `frontera action list` reads (`/v1/blueprint/actions?view=deployable`),
+ * so `local status`, `local dev` and `action list` say one thing. Null when it
+ * could not be read.
+ */
+export async function liveActionStates(call: Call): Promise<Map<string, LiveAction> | null> {
+  const listed = await call('org', 'GET', '/v1/blueprint/actions?view=deployable')
+  if (listed.status >= 300) return null
+  const rows = data<Array<{ definition?: { apiName?: string }; deploymentStatus?: string; availability?: string; reason?: string | null }>>(listed)
+  if (!Array.isArray(rows)) return null
+  const out = new Map<string, LiveAction>()
+  for (const r of rows) {
+    const name = r.definition?.apiName
+    if (typeof name === 'string' && typeof r.deploymentStatus === 'string') out.set(name, { deploymentStatus: r.deploymentStatus, ...(r.availability ? { availability: r.availability } : {}), reason: r.reason ?? null })
   }
   return out
 }
+
+/**
+ * Of the Actions that should run here, the ones the runtime does not run, each
+ * with why: a file left unchanged after a failed apply still needs its Action
+ * deployed again. Empty when the runtime could not be read (the apply decides).
+ */
+export function actionsNotRunning(expected: string[], live: Map<string, LiveAction> | null): Array<{ apiName: string; why: string }> {
+  if (!live) return []
+  return expected.flatMap((apiName) => {
+    const l = live.get(apiName)
+    if (liveActionRuns(l)) return []
+    return [{ apiName, why: !l ? 'it is not published on the runtime' : `its deployment is ${l.deploymentStatus}${l.availability && l.availability !== 'available' && l.availability !== l.deploymentStatus ? ` (${l.availability})` : ''}${l.reason ? `, ${l.reason}` : ''}` }]
+  })
+}

package/src/local/local-agent-action-grants.ts

@@ -0,0 +1,210 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { parse as parseYaml } from 'yaml'
+
+import { unchangedSincePull } from './local-check-inherited'
+
+/**
+ * Governed Actions an Agent's instructions tell it to submit that its
+ * Blueprint grants never offer it.
+ *
+ * An Agent is offered an Action only on an object type its grant lets it act
+ * on (`"act"` in `agents/<slug>/bindings.json`); with `read` alone it gets the
+ * query tools and no Action tool, here and on the platform alike. Nothing in
+ * the apply refuses an Agent whose instructions say "submit
+ * `draftBudgetScenario`" while its grant on BudgetScenario is `read`: the
+ * Agent simply never has the tool, and a conversation that needs it fails.
+ * This says so before a conversation does.
+ *
+ * Kept to few false alarms: only an Action's exact apiName counts (a word
+ * boundary on both sides, case kept), only Actions the project's Blueprint
+ * defines, and a sentence that names it with a negation ("never by submitting
+ * `raiseServiceRequest` yourself", "`publishExecutiveBrief` is not yours") or
+ * with one of the Agent's own Functions or workflows (which submit it in the
+ * Agent's place) does not count. An Agent whose grants the pull couldn't read
+ * (`blueprintUnread`), or whose grant on the type names no permissions (it
+ * keeps what the runtime already holds), is not judged.
+ */
+
+export interface AgentActionGap {
+  /** `leo`, from `agents/leo/`. */
+  agent: string
+  /** The object type the Actions act on (`BudgetScenario`). */
+  objectType: string
+  /** The Actions on it the instructions name, in the order they first appear. */
+  actions: string[]
+  /** What the Agent holds on the type: its permissions, or null without a grant. */
+  permissions: string[] | null
+  /** Where the instructions name them: `agents/leo/agent.json`, `agents/nova/operating.json`. */
+  files: string[]
+  /** The Agent's files are as the last pull wrote them: the workspace has the same gap. */
+  inherited: boolean
+}
+
+type Doc = Record<string, unknown>
+
+function entries(dir: string): string[] {
+  try {
+    return readdirSync(dir).filter((name) => !name.startsWith('.')).sort()
+  } catch {
+    return []
+  }
+}
+
+function readDoc(path: string): unknown {
+  try {
+    const text = readFileSync(path, 'utf8')
+    return path.endsWith('.json') ? JSON.parse(text) : parseYaml(text)
+  } catch {
+    return null
+  }
+}
+
+const isDoc = (v: unknown): v is Doc => !!v && typeof v === 'object' && !Array.isArray(v)
+
+/** Each governed Action the project's Blueprint defines, by apiName, with the object type it acts on. */
+export function projectActionSubjects(root: string): Map<string, string> {
+  const out = new Map<string, string>()
+  const dir = join(root, 'blueprint', 'actions')
+  for (const file of entries(dir)) {
+    if (!/\.(ya?ml|json)$/.test(file)) continue
+    const doc = readDoc(join(dir, file))
+    if (!isDoc(doc)) continue
+    const apiName = typeof doc.apiName === 'string' && doc.apiName ? doc.apiName : file.replace(/\.(ya?ml|json)$/, '')
+    const subject = isDoc(doc.subject) && typeof doc.subject.objectType === 'string' ? doc.subject.objectType.replace(/^objectType\//, '') : null
+    if (subject && /^[A-Za-z_][\w]*$/.test(apiName)) out.set(apiName, subject)
+  }
+  return out
+}
+
+/** Every string under a value: a procedure's description, instructions, guardrails, field descriptions… */
+function strings(v: unknown, out: string[] = []): string[] {
+  if (typeof v === 'string') out.push(v)
+  else if (Array.isArray(v)) for (const x of v) strings(x, out)
+  else if (isDoc(v)) for (const x of Object.values(v)) strings(x, out)
+  return out
+}
+
+/** The Agent's instructions (its enabled prompts) and its procedures' text, by the file each is in. */
+function instructionTexts(root: string, slug: string): Array<{ file: string; text: string }> {
+  const out: Array<{ file: string; text: string }> = []
+  const agentFile = `agents/${slug}/agent.json`
+  const agent = readDoc(join(root, agentFile))
+  if (isDoc(agent) && Array.isArray(agent.prompts)) {
+    const text = agent.prompts
+      .filter((p): p is Doc => isDoc(p) && p.enabled !== false && typeof p.content === 'string')
+      .map((p) => p.content as string)
+      .join('\n\n')
+    if (text) out.push({ file: agentFile, text })
+  }
+  const operatingFile = `agents/${slug}/operating.json`
+  const operating = readDoc(join(root, operatingFile))
+  if (isDoc(operating) && Array.isArray(operating.procedures)) {
+    const text = strings(operating.procedures).join('\n\n')
+    if (text) out.push({ file: operatingFile, text })
+  }
+  return out
+}
+
+/** The sentences of a text: split at line breaks and at a full stop, question or exclamation mark before a space. */
+function sentences(text: string): string[] {
+  return text.split(/\n+|(?<=[.!?])\s+/).map((s) => s.trim()).filter(Boolean)
+}
+
+/** A sentence that says not to submit it, or that it isn't the Agent's to submit. */
+const NEGATION = /\b(?:never|not|nor|cannot|without)\b|n['’]t\b/i
+
+const word = (name: string) => new RegExp(`(?<![\\w-])${name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?![\\w-])`)
+
+/** The Functions and workflows the Agent may start, by slug: a sentence naming one is about that tool. */
+function boundTools(bindings: Doc): string[] {
+  const refs: string[] = []
+  for (const key of ['functions', 'workflows'] as const) {
+    const rows = Array.isArray(bindings[key]) ? (bindings[key] as unknown[]) : []
+    for (const row of rows) {
+      const ref = isDoc(row) ? (row.function ?? row.workflow) : null
+      if (typeof ref === 'string' && ref.includes('/')) refs.push(ref.slice(ref.indexOf('/') + 1))
+    }
+  }
+  return refs.filter(Boolean)
+}
+
+/** The Actions a text tells the Agent to use, by apiName: named in a sentence that neither negates it nor hands it to a bound tool. */
+export function namedActions(text: string, actions: Iterable<string>, tools: readonly string[] = []): string[] {
+  const names = [...actions]
+  const found: Array<{ name: string; at: number }> = []
+  const toolWords = tools.map(word)
+  for (const sentence of sentences(text)) {
+    if (NEGATION.test(sentence) || toolWords.some((w) => w.test(sentence))) continue
+    for (const name of names) {
+      const m = word(name).exec(sentence)
+      if (m && !found.some((f) => f.name === name)) found.push({ name, at: text.indexOf(sentence) + m.index })
+    }
+  }
+  return found.sort((a, b) => a.at - b.at).map((f) => f.name)
+}
+
+/** What a bindings.json grants on each object type, by apiName; null when it can't be told (grants the pull couldn't read). */
+function grantsOf(bindings: Doc): Map<string, string[] | null> | null {
+  if (bindings.blueprintUnread === true && !Array.isArray(bindings.blueprint)) return null
+  const out = new Map<string, string[] | null>()
+  for (const row of Array.isArray(bindings.blueprint) ? bindings.blueprint : []) {
+    if (!isDoc(row) || typeof row.objectType !== 'string') continue
+    const type = row.objectType.replace(/^objectType\//, '')
+    out.set(type, Array.isArray(row.permissions) ? row.permissions.filter((p): p is string => typeof p === 'string') : null)
+  }
+  return out
+}
+
+/** Every Agent whose instructions or procedures name Actions it can't submit, one entry per Agent and object type. */
+export function agentActionGaps(root: string): AgentActionGap[] {
+  const subjects = projectActionSubjects(root)
+  if (!subjects.size) return []
+  const out: AgentActionGap[] = []
+  let unchanged: ReturnType<typeof unchangedSincePull> | null = null
+  for (const slug of entries(join(root, 'agents'))) {
+    if (!existsSync(join(root, 'agents', slug, 'agent.json'))) continue
+    const bindingsFile = `agents/${slug}/bindings.json`
+    const bindings = readDoc(join(root, bindingsFile))
+    const doc: Doc = isDoc(bindings) ? bindings : {}
+    const grants = grantsOf(doc)
+    if (!grants) continue
+    const tools = boundTools(doc)
+    const byType = new Map<string, AgentActionGap>()
+    for (const { file, text } of instructionTexts(root, slug)) {
+      for (const action of namedActions(text, subjects.keys(), tools)) {
+        const type = subjects.get(action)!
+        const held = grants.has(type) ? grants.get(type)! : null
+        // A grant that names no permissions keeps what the runtime holds: it may act, so it isn't judged.
+        if (grants.has(type) && held === null) continue
+        if (held?.includes('act')) continue
+        const gap = byType.get(type) ?? { agent: slug, objectType: type, actions: [], permissions: held, files: [], inherited: false }
+        if (!gap.actions.includes(action)) gap.actions.push(action)
+        if (!gap.files.includes(file)) gap.files.push(file)
+        byType.set(type, gap)
+      }
+    }
+    if (!byType.size) continue
+    unchanged ??= unchangedSincePull(root)
+    for (const gap of byType.values()) {
+      gap.inherited = [...gap.files, bindingsFile].every((f) => unchanged!.files.has(f))
+      out.push(gap)
+    }
+  }
+  return out
+}
+
+const list = (names: string[]) => (names.length <= 2 ? names.join(' and ') : `${names.slice(0, -1).join(', ')} and ${names[names.length - 1]}`)
+
+/** One gap in a line, with its fix: what `local dev`, `local status` and the MCP status say. */
+export function agentActionGapLine(g: AgentActionGap): string {
+  const one = g.actions.length === 1
+  const named = `${one ? 'the governed Action' : 'the governed Actions'} ${list(g.actions.map((a) => `\`${a}\``))}`
+  const held = g.permissions === null ? `it has no grant on ${g.objectType}` : `its grant on ${g.objectType} is ${list(g.permissions.length ? g.permissions : ['empty'])} without act`
+  const where = g.files.map((f) => (f.endsWith('operating.json') ? 'procedures (operating.json)' : 'instructions (agent.json)')).join(' and ')
+  const fix = g.permissions === null
+    ? `add { "objectType": "objectType/${g.objectType}", "permissions": ["read", "act"] } to agents/${g.agent}/bindings.json`
+    : `add "act" to objectType/${g.objectType}'s permissions in agents/${g.agent}/bindings.json`
+  return `agent/${g.agent}: its ${where} tell it to submit ${named}, but ${held}, so it is offered no Action on ${g.objectType}, here and on the platform. Fix: ${fix}, or take ${one ? 'it' : 'them'} out of its instructions${g.inherited ? ' (inherited: these files are as the pull wrote them, so the workspace’s Agent has the same gap)' : ''}`
+}

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

@@ -0,0 +1,232 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { parseRef } from './local-sync-refs'
+
+/**
+ * What an Agent's files say that `local dev` would otherwise apply without a
+ * word and the Agent would only trip over in a chat: a key in agent.json
+ * whose content belongs in another file, and a procedure's tool list naming
+ * a tool in a form the Agent cannot use, or one it is not bound to.
+ */
+
+const isRecord = (v: unknown): v is Record<string, unknown> => !!v && typeof v === 'object' && !Array.isArray(v)
+
+/** The tool groups a procedure may keep (`TOOL_GROUPS` in the service's operating config). */
+export const PROCEDURE_TOOL_GROUPS = ['plugins', 'blueprint', 'blueprint-actions', 'web'] as const
+
+/** The forms a procedure's `tools.ids` take, in words, for a schema description and an error. */
+export const PROCEDURE_TOOL_FORMS =
+  '`function:<slug>` (a Function bound to the Agent in agents/<slug>/bindings.json), `workflow:<slug>` (a workflow bound there), or `tool:plugins`, `tool:blueprint`, `tool:blueprint-actions`, `tool:web` (the Agent’s Plugins; its Blueprint query tools only; its governed Action tools, which list, submit and read Action requests; web search)'
+
+/**
+ * Keys in agent.json whose content does not do there what was meant: each a
+ * `warning:` line naming the file it belongs in. The Agent is still applied.
+ */
+export function agentFileWarnings(doc: unknown, slug: string): string[] {
+  if (!isRecord(doc)) return []
+  const out: string[] = []
+  const bindings = `agents/${slug}/bindings.json`
+  const file = `agents/${slug}/agent.json`
+  const rows = (key: string) => (Array.isArray(doc[key]) ? (doc[key] as unknown[]) : [])
+  // `objectBindings` binds workspace object definitions; an object type there grants nothing.
+  rows('objectBindings').forEach((row, i) => {
+    if (!isRecord(row)) return
+    const id = typeof row.objectDefinitionId === 'string' ? parseRef(row.objectDefinitionId) : null
+    if (id?.kind === 'object') return
+    const named = [row.objectType, row.objectTypeApiName, row.apiName, row.objectDefinitionId].find((v) => typeof v === 'string') as string | undefined
+    const type = named ? (parseRef(named)?.name ?? named) : '<ApiName>'
+    out.push(
+      `  warning: ${file} objectBindings.${i} is not applied: objectBindings binds an object definition (\`objectDefinitionId: object/<slug>\` with its \`definition\`). For Blueprint records the Agent may query, list the object type in ${bindings}: "blueprint": [{ "objectType": "objectType/${type}", "permissions": ["read"] }]`,
+    )
+  })
+  if (rows('functions').length) {
+    out.push(`  warning: ${file} functions is not applied: nothing runs those rows any more. The Functions the Agent may call are its bindings: ${bindings} "functions": [{ "function": "function/<slug>" }]`)
+  }
+  rows('knowledgeAttachments').forEach((row, i) => {
+    if (!isRecord(row)) return
+    const id = row.knowledgeConfigId
+    if (typeof id !== 'string' || (!parseRef(id) && !/^[0-9a-f-]{36}$/i.test(id))) {
+      out.push(`  warning: ${file} knowledgeAttachments.${i} names no knowledge base: write { "knowledgeConfigId": "knowledge/<name>" } (knowledge/<name>/knowledge.json)`)
+    }
+  })
+  return out
+}
+
+/** The keys agent.json may not carry at all: refused before the runtime says "unrecognized key". */
+export function agentFileErrors(doc: unknown, slug: string): string[] {
+  if (!isRecord(doc)) return []
+  const bindings = `agents/${slug}/bindings.json`
+  return ['workflows', 'workflowBindings', 'functionBindings', 'bindings', 'blueprint', 'grants', 'blueprintGrants', 'objectTypes']
+    .filter((key) => key in doc)
+    .map((key) => `agents/${slug}/agent.json: \`${key}\` is not an agent.json key; what an Agent may start and read goes in ${bindings} (\`frontera local schema bindings\`)`)
+}
+
+/** What `agents/<slug>/bindings.json` binds, by slug: the Functions and workflows. */
+export function boundTools(root: string, slug: string): { functions: Set<string>; workflows: Set<string>; blueprint: boolean; objectTypes?: Set<string>; acting?: Set<string> } | null {
+  const path = join(root, 'agents', slug, 'bindings.json')
+  if (!existsSync(path)) return { functions: new Set(), workflows: new Set(), blueprint: false, objectTypes: new Set(), acting: new Set() }
+  try {
+    const doc = JSON.parse(readFileSync(path, 'utf8')) as { functions?: Array<{ function?: unknown }>; workflows?: Array<{ workflow?: unknown }>; blueprint?: unknown[] }
+    const names = (rows: Array<Record<string, unknown>> | undefined, key: string, kind: string) =>
+      new Set((rows ?? []).flatMap((r) => {
+        const ref = typeof r?.[key] === 'string' ? parseRef(r[key] as string) : null
+        return ref?.kind === kind ? [ref.name] : []
+      }))
+    return {
+      functions: names(doc.functions as Array<Record<string, unknown>>, 'function', 'function'),
+      workflows: names(doc.workflows as Array<Record<string, unknown>>, 'workflow', 'workflow'),
+      blueprint: Array.isArray(doc.blueprint) && doc.blueprint.length > 0,
+      // The object types granted, by apiName (`objectType/WorkOrder`).
+      objectTypes: names(doc.blueprint as Array<Record<string, unknown>>, 'objectType', 'objectType'),
+      // Those it may submit governed Actions on (`act` in the grant's permissions); unknown when an entry
+      // names none (a pull that read names only), since that entry keeps whatever the grant holds.
+      acting: (doc.blueprint as Array<Record<string, unknown>> | undefined)?.some((g) => !Array.isArray(g?.permissions)) ? undefined : names((doc.blueprint as Array<Record<string, unknown>> | undefined)?.filter((g) => Array.isArray(g?.permissions) && (g.permissions as unknown[]).includes('act')), 'objectType', 'objectType'),
+    }
+  } catch {
+    return null
+  }
+}
+
+/**
+ * A procedure's `tools.ids` checked before the behavior settings are staged:
+ * an id in a form the Agent cannot use fails the apply (the runtime accepts
+ * it and the chat then refuses the procedure with "keeps a tool that does not
+ * exist"); one that names a Function or workflow the Agent is not bound to is
+ * a warning naming the bindings file. `bound` is null when bindings.json could
+ * not be read, and then only the forms are checked.
+ */
+/**
+ * The warning for an operating.json without `execution.toolScopes: 2`, or
+ * null when it has it. Without the marker the platform reads the file as
+ * before Blueprint Actions were their own choice: `tool:blueprint` keeps the
+ * Action tools, and a service Agent has them outside procedures.
+ */
+export function toolScopesProblem(doc: unknown, file: string): string | null {
+  if (!isRecord(doc)) return null
+  const execution = isRecord(doc.execution) ? doc.execution : {}
+  if (execution.toolScopes === 2) return null
+  const said = execution.toolScopes === undefined ? 'has no `execution.toolScopes`' : `has \`execution.toolScopes: ${JSON.stringify(execution.toolScopes)}\``
+  return `  warning: ${file} ${said}, so it is read as before Blueprint Actions were their own choice: \`tool:blueprint\` keeps the Action tools, and a service Agent has them outside procedures; add "toolScopes": 2 to "execution" to use the new meaning (\`tool:blueprint\` the query tools only, \`tool:blueprint-actions\` the Action tools, \`execution.blueprintActions\` for outside procedures)`
+}
+
+export function procedureToolProblems(doc: unknown, slug: string, bound: ReturnType<typeof boundTools>): { errors: string[]; warnings: string[] } {
+  const errors: string[] = []
+  const warnings: string[] = []
+  const procedures = isRecord(doc) && Array.isArray(doc.procedures) ? (doc.procedures as unknown[]) : []
+  const file = `agents/${slug}/operating.json`
+  // Once per Agent: a config without the marker keeps the meaning tool ids had before.
+  const scopes = toolScopesProblem(doc, file)
+  if (scopes) warnings.push(scopes)
+  // A data scope narrows reads of an object type the Agent is granted: one it is not granted is read by nothing.
+  const dataScopes = isRecord(doc) && Array.isArray(doc.dataScopes) ? (doc.dataScopes as unknown[]) : []
+  dataScopes.forEach((d, i) => {
+    if (!isRecord(d) || typeof d.objectType !== 'string' || !bound?.objectTypes) return
+    const type = parseRef(d.objectType)?.name ?? d.objectType
+    if (!bound.objectTypes.has(type)) warnings.push(`  warning: ${file}: dataScopes.${i} scopes ${type}, which agents/${slug}/bindings.json does not grant, so the Agent reads none of it and the scope does nothing: add { "objectType": "objectType/${type}", "permissions": ["read"] } to its "blueprint"`)
+  })
+  // The Action tools asked for (outside procedures, or kept by one) while no grant lets the Agent act: it is offered none.
+  const execution = isRecord(doc) && isRecord(doc.execution) ? doc.execution : {}
+  const keepsActions = procedures.some((p) => isRecord(p) && isRecord(p.tools) && p.tools.inherit === false && Array.isArray(p.tools.ids) && p.tools.ids.includes('tool:blueprint-actions'))
+  if ((execution.blueprintActions === true || keepsActions) && bound?.blueprint && bound.acting && bound.acting.size === 0) {
+    const types = [...(bound.objectTypes ?? [])].sort()
+    const on = types.length ? (types.length > 3 ? `${types.slice(0, 3).join(', ')} or another type it reads` : types.join(' or ')) : '<Type>'
+    warnings.push(`  warning: ${slug} can't submit Actions: give its grant on ${on} \`act\` in agents/${slug}/bindings.json ("permissions": ["read", "act"]). ${file} asks for the Action tools (${execution.blueprintActions === true ? '`execution.blueprintActions`' : '`tool:blueprint-actions`'}), and without act on the type an Action is on, it is offered none`)
+  }
+  procedures.forEach((p, i) => {
+    if (!isRecord(p)) return
+    const name = typeof p.name === 'string' ? p.name : `procedure ${i + 1}`
+    // An action that starts a Function or workflow needs the same binding as a kept tool.
+    if (bound && Array.isArray(p.actions)) {
+      ;(p.actions as unknown[]).forEach((a, k) => {
+        if (!isRecord(a)) return
+        for (const [key, kind] of [['functionId', 'function'], ['workflowId', 'workflow']] as const) {
+          const ref = typeof a[key] === 'string' ? parseRef(a[key] as string) : null
+          if (ref?.kind !== kind) continue
+          if (!(kind === 'function' ? bound.functions : bound.workflows).has(ref.name)) {
+            warnings.push(`  warning: ${file}: procedures.${i}.actions.${k}.${key}: "${name}" starts ${kind} ${ref.name}, which agents/${slug}/bindings.json does not bind, so the chat refuses the procedure: add { "${kind}": "${kind}/${ref.name}" } to its "${kind}s"`)
+          }
+        }
+      })
+    }
+    // Only a procedure that keeps its own tools (`inherit: false`) uses the list.
+    if (!isRecord(p.tools) || p.tools.inherit !== false || !Array.isArray(p.tools.ids)) return
+    ;(p.tools.ids as unknown[]).forEach((id, j) => {
+      const at = `${file}: procedures.${i}.tools.ids.${j}`
+      if (typeof id !== 'string') {
+        errors.push(`${at}: must be text, one of ${PROCEDURE_TOOL_FORMS}`)
+        return
+      }
+      const m = /^(function|workflow|tool):(.+)$/.exec(id)
+      if (!m) {
+        // A reference written the file way (`function/x`) is the same tool in the procedure's form.
+        const ref = parseRef(id)
+        const hint = ref && (ref.kind === 'function' || ref.kind === 'workflow') ? `; write \`${ref.kind}:${ref.name}\`` : ''
+        errors.push(`${at}: "${id}" is not a tool "${name}" can keep${hint}. A tool is ${PROCEDURE_TOOL_FORMS}`)
+        return
+      }
+      const [, kind, target] = m as unknown as [string, 'function' | 'workflow' | 'tool', string]
+      if (kind === 'tool') {
+        if (!(PROCEDURE_TOOL_GROUPS as readonly string[]).includes(target)) errors.push(`${at}: "${id}" is not a tool group; the groups are ${PROCEDURE_TOOL_GROUPS.map((g) => `tool:${g}`).join(', ')}`)
+        else if ((target === 'blueprint' || target === 'blueprint-actions') && bound && !bound.blueprint) warnings.push(`  warning: ${at}: "${name}" keeps the ${target === 'blueprint' ? 'Blueprint query tools' : 'governed Action tools'}, but agents/${slug}/bindings.json grants no object type ("blueprint": [{ "objectType": "objectType/<ApiName>" }]), so the Agent has none`)
+        return
+      }
+      // A runtime id passes: `local dev` writes names, and a pulled file may still hold one.
+      if (/^[0-9a-f]{8}-[0-9a-f]{4}-/i.test(target) || !bound) return
+      const set = kind === 'function' ? bound.functions : bound.workflows
+      if (!set.has(target)) {
+        warnings.push(
+          `  warning: ${at}: "${name}" keeps ${kind} ${target}, which agents/${slug}/bindings.json does not bind, so the chat refuses the procedure: add { "${kind}": "${kind}/${target}" } to its "${kind}s"`,
+        )
+      }
+    })
+  })
+  return { errors, warnings }
+}
+
+/**
+ * What `requiresApproval: false` on a binding does, said where it is written
+ * (agents/<slug>/bindings.json), so it is read as "never asks": the binding
+ * is Unattended, and the Agent runs the call without a card in every approval
+ * mode, attended or not, with or without an operating.json. Only a dataset run
+ * on the published Agent still asks before one that changes something. A
+ * Function that asks the person itself still shows its own question. Each
+ * line starts `<file>: requiresApproval false`, which `isApprovalNote` tells
+ * apart from an adaptation to this runtime: it holds everywhere.
+ */
+export function approvalBindingNotes(root: string, slug: string, doc: unknown): string[] {
+  if (!isRecord(doc)) return []
+  const file = `agents/${slug}/bindings.json`
+  const rows = (key: string) => (Array.isArray(doc[key]) ? (doc[key] as unknown[]).filter(isRecord) : [])
+  const ALWAYS = 'Runs without a card in every approval mode, whether or not someone is in the chat; only a dataset run on the published Agent still asks before it changes something. Keep it for an action that is safe to run unasked.'
+  const out: string[] = []
+  for (const row of rows('functions')) {
+    if (row.requiresApproval !== false || typeof row.function !== 'string') continue
+    const name = parseRef(row.function)?.name ?? row.function
+    const extra = functionAsksPerson(root, name) ? ['The Function still asks the person itself (its confirmation card).'] : []
+    out.push(`  warning: ${file}: requiresApproval false on function/${name}: ${[ALWAYS, ...extra].join(' ')}`)
+  }
+  for (const row of rows('workflows')) {
+    if (row.requiresApproval !== false || typeof row.workflow !== 'string') continue
+    const name = parseRef(row.workflow)?.name ?? row.workflow
+    out.push(`  warning: ${file}: requiresApproval false on workflow/${name}: ${ALWAYS} Each Workflow binding asks on its own.`)
+  }
+  return out
+}
+
+/** A note `approvalBindingNotes` made: said, but not an adaptation to this runtime. */
+export function isApprovalNote(line: string): boolean {
+  return /^\s*warning: agents\/[^/]+\/bindings\.json: requiresApproval false on /.test(line)
+}
+
+/** Whether a Function's source asks the person itself (`ctx.person.confirm`): a source search, as its file holds it. */
+function functionAsksPerson(root: string, name: string): boolean {
+  for (const path of [join(root, 'functions', `${name}.ts`), join(root, 'functions', name, 'index.ts'), join(root, 'functions', name, 'src', 'index.ts')]) {
+    try {
+      if (/\bperson\s*\.\s*confirm\s*\(/.test(readFileSync(path, 'utf8'))) return true
+    } catch {
+      // Not this path.
+    }
+  }
+  return false
+}