@frontera-sdk/cli 1.52.27 → 1.52.29

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

@@ -0,0 +1,1132 @@
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml'
+
+import type { LocalAction } from './local-actions'
+import { absentWhy, adaptOperating, plainLinks, projectProvides } from './local-adapt'
+import { applyAgentGrants, type AgentGrant } from './local-agent-grants'
+import { oneLine, refWords } from './local-applied'
+import { readableName } from './local-sync-names'
+import { ensureObjectDefinitions } from './local-objects'
+import { applyQualityChecks, QUALITY_CHECKS_FILE, readQualityChecks, sourcePaths, sourceRows } from './local-quality-checks'
+import { readLock } from './local-sync-plan'
+import { applyErrorText } from './local-apply-error'
+import { localAdaptation } from './local-blueprint-outline'
+import { actionFit, classify, objectTypeFit, objectTypeNeeds } from './local-portability'
+import type { SyncProfiles, SyncTarget } from './local-dev-sync'
+import type { LocalProject } from './local-project'
+import { syncClient } from './local-sync-client'
+import { readProviderSetup } from './local-providers'
+import { fillPluginSecrets, localSecretNames, needsValueLine, NON_SECRET_HEADERS, pluginSecretInputs, pluginSecretName } from './local-secrets'
+import { describeUnresolved, governedActionIds, isUuid, kindsIn, parseRef, referencesIn, toIds, type Directory } from './local-sync-refs'
+import { buildDirectory, rows } from './local-sync-remote'
+import type { LocalCredentials } from './local-state'
+import { addStandInServers, dropPlatformOnly, dropStandInTriggers, platformOnlyNames, standInNames } from './local-stand-ins'
+
+/**
+ * Project files name other resources by `kind/name`; a runtime wants its own
+ * ids. Before `local dev` applies an Agent, a workflow or an Agent's behavior
+ * settings, the names are looked up on the local runtime and a resolved copy
+ * is applied (`.frontera/local/resolved/`), so the file in the project keeps
+ * the names and stays portable.
+ *
+ * A file that names something the project holds but the runtime does not
+ * have yet waits for it: the message names the field and what is missing,
+ * and `local dev` applies it again once that is there. What nothing in the
+ * project provides is applied around (`local-adapt.ts`): an Agent goes without
+ * the Knowledge, Skill or Plugin, a link in guidance stays as plain words, and
+ * behavior settings lose only the procedure step, action or scope entry that
+ * names it. Each says so, so one missing piece does not keep the Agent from
+ * running.
+ */
+
+export interface RunResult {
+  ok: boolean
+  output: string
+}
+
+/** The local runtime's resources by name, read with its own keys. */
+export async function localDirectory(serviceUrl: string, creds: LocalCredentials): Promise<Directory> {
+  if (!creds.workspaceKey) return {}
+  const client = syncClient(serviceUrl, creds.workspaceKey)
+  const { directory, lists } = await buildDirectory({
+    workspace: client,
+    organization: creds.orgKey ? syncClient(serviceUrl, creds.orgKey) : undefined,
+    workspaceId: creds.workspaceId,
+  })
+  // The Agent list leaves out Agents never published, and locally every Agent is a
+  // draft: one the list does not have is looked up by name when a file names it.
+  agentLookups.set(directory, client)
+  if (creds.session) ownerCalls.set(directory, ownerCall(serviceUrl, creds))
+  if (creds.orgKey) orgLookups.set(directory, syncClient(serviceUrl, creds.orgKey))
+  functionVersions.set(directory, new Map(lists.functions.flatMap((f) => (f.liveVersion ? [[f.slug, f.liveVersion] as const] : []))))
+  return directory
+}
+
+/** Calls as the runtime's owner, for routes a workspace key may not use (object definitions). */
+const ownerCalls = new WeakMap<Directory, (method: string, path: string, body?: unknown) => Promise<{ status: number; body: unknown }>>()
+
+function ownerCall(serviceUrl: string, creds: LocalCredentials) {
+  return async (method: string, path: string, body?: unknown) => {
+    const res = await fetch(new URL(path, serviceUrl), {
+      method,
+      headers: { authorization: `Bearer ${creds.session}`, 'x-org-id': creds.organizationId, 'x-workspace-id': creds.workspaceId, ...(body === undefined ? {} : { 'content-type': 'application/json' }) },
+      body: body === undefined ? undefined : JSON.stringify(body),
+    })
+    const text = await res.text()
+    let parsed: unknown = text
+    try {
+      parsed = JSON.parse(text)
+    } catch {
+      // Not JSON: kept as text for the message.
+    }
+    return { status: res.status, body: parsed }
+  }
+}
+
+/** The runtime's organization key client, for reads a workspace key may not make (the model catalog's kinds). */
+const orgLookups = new WeakMap<Directory, ReturnType<typeof syncClient>>()
+
+/** The runtime's voice models by slug; null when they could not be read. */
+async function runtimeVoices(dir: Directory): Promise<string[] | null> {
+  const client = orgLookups.get(dir)
+  if (!client) return null
+  try {
+    return rows<{ slug?: string; kind?: string }>(await client.get('/v1/config/models/catalog')).flatMap((m) => (m.kind === 'voice' && m.slug ? [m.slug] : []))
+  } catch {
+    return null
+  }
+}
+
+/**
+ * An Agent's voice names a voice in the organization's catalog
+ * (`config.voice.voiceSlug`). The runtime resolves a slug it lacks to no
+ * voice at all, silently, so here it is swapped for the runtime's first
+ * voice, as a missing model is, or left out when the runtime has none; each
+ * says so, as an adaptation.
+ */
+export function substituteVoice(doc: unknown, voices: string[] | null, warnings: string[], label: string): void {
+  const config = (doc as { config?: { voice?: Record<string, unknown> | null } } | null)?.config
+  const slug = typeof config?.voice?.voiceSlug === 'string' ? config.voice.voiceSlug.trim() : ''
+  if (!slug || !voices || voices.includes(slug)) return
+  const usable = voices[0]
+  if (usable) {
+    config!.voice = { ...config!.voice, voiceSlug: usable }
+    warnings.push(`  warning: ${label} speaks with the voice ${slug}, which this runtime does not have; it uses ${usable} here`)
+    return
+  }
+  const { voiceSlug: _missing, ...rest } = config!.voice!
+  config!.voice = rest
+  warnings.push(`  warning: ${label} speaks with the voice ${slug}, and this runtime has no voices: it has no voice here`)
+}
+
+const agentLookups = new WeakMap<Directory, ReturnType<typeof syncClient>>()
+/** Each Function's live version on the runtime, by slug: a workflow step's version pin is rewritten to it. */
+const functionVersions = new WeakMap<Directory, Map<string, number>>()
+
+/** The person the runtime's workspace key acts as (its owner), for a Plugin trigger's account. */
+async function localOwner(dir: Directory): Promise<string | null> {
+  const me = await agentLookups.get(dir)?.find<{ principal?: string | null }>('/v1/whoami').catch(() => null)
+  return me?.principal ?? null
+}
+
+/**
+ * What a workflow names that only means something on the workspace, made to
+ * mean the same here (design §8):
+ * - A Function step pinned to a version (`params.version`) runs that
+ *   Function's version on this runtime, where numbering starts again: the one
+ *   deployed from the project. A pin to a version older than the one pulled
+ *   says so, as the project holds only the pulled code.
+ * - A Plugin trigger acting as a person of the workspace (`account.userId`)
+ *   acts as this runtime's owner.
+ */
+async function localizeWorkflow(doc: unknown, dir: Directory, root: string, warnings: string[]): Promise<void> {
+  if (!doc || typeof doc !== 'object') return
+  const versions = functionVersions.get(dir) ?? new Map<string, number>()
+  const lock = readLock(root)
+  const visit = (v: unknown) => {
+    if (Array.isArray(v)) return v.forEach(visit)
+    if (!v || typeof v !== 'object') return
+    const o = v as Record<string, unknown>
+    const params = o.params as Record<string, unknown> | undefined
+    const ref = typeof o.resourceId === 'string' ? parseRef(o.resourceId) : null
+    if (o.kind === 'function' && ref?.kind === 'function' && params && typeof params.version === 'number') {
+      const here = versions.get(ref.name)
+      const pulled = Number(lock?.items[`function/${ref.name}`]?.version?.replace(/^v/, ''))
+      if (here) {
+        if (Number.isFinite(pulled) && pulled !== params.version) warnings.push(`  warning: Step ${String(o.id)} pins Function ${ref.name} v${params.version}; here it runs the project’s copy (v${pulled} in the workspace)`)
+        params.version = here
+      } else delete params.version
+    }
+    for (const x of Object.values(o)) visit(x)
+  }
+  visit((doc as Record<string, unknown>).nodes)
+  const triggers = Array.isArray((doc as Record<string, unknown>).trigger) ? ((doc as Record<string, unknown>).trigger as Array<Record<string, unknown>>) : []
+  const asPerson = triggers.filter((t) => t?.kind === 'plugin' && (t.account as { kind?: string } | undefined)?.kind === 'user')
+  if (asPerson.length) {
+    const owner = await localOwner(dir)
+    for (const t of asPerson) t.account = owner ? { kind: 'user', userId: owner } : { kind: 'workspace' }
+  }
+}
+
+/** Look up, by name, the Agents a document names that the directory has not seen. */
+async function fillAgents(doc: unknown, dir: Directory): Promise<void> {
+  const client = agentLookups.get(dir)
+  if (!client) return
+  dir.agent ??= new Map()
+  for (const ref of referencesIn(doc)) {
+    if (ref.kind !== 'agent' || dir.agent.has(ref.name)) continue
+    const found = await client.find<{ id?: string }>(`/v1/config/agents/${encodeURIComponent(ref.name)}`).catch(() => null)
+    if (found?.id) dir.agent.set(ref.name, found.id)
+  }
+}
+
+/** Relation lists on an Agent whose rows can be left out when what they point at is missing. */
+const OPTIONAL_RELATIONS: Array<(doc: Record<string, unknown>) => { rows: unknown[]; set: (rows: unknown[]) => void } | null> = [
+  (d) => {
+    const skills = d.skills as { workspaceBindings?: unknown[] } | undefined
+    return Array.isArray(skills?.workspaceBindings) ? { rows: skills!.workspaceBindings!, set: (rows) => (skills!.workspaceBindings = rows) } : null
+  },
+  ...['knowledgeAttachments', 'appInstalls', 'functions', 'objectBindings'].map((key) => (d: Record<string, unknown>) =>
+    Array.isArray(d[key]) ? { rows: d[key] as unknown[], set: (rows: unknown[]) => (d[key] = rows) } : null,
+  ),
+]
+
+/** A Plugin's tools on this runtime, by name → capability id, read with the runtime's workspace key. */
+async function localTools(dir: Directory, installId: string): Promise<Map<string, string>> {
+  const client = agentLookups.get(dir)
+  if (!client) return new Map()
+  const listed = await client.get(`/v1/apps/${encodeURIComponent(installId)}/capabilities`).catch(() => null)
+  return new Map(rows<{ id?: string; name?: string }>(listed).flatMap((r) => (r.id && r.name ? [[r.name, r.id] as const] : [])))
+}
+
+/**
+ * An Agent's own settings for Plugin tools (`pluginTools`: a sensitive tool
+ * granted to it, an approval it overrides), named by Plugin and tool, become
+ * the runtime's capability rows (`appCapabilities`). A Plugin the runtime does
+ * not have is already left off the Agent, with its warning; a tool the
+ * runtime's Plugin does not list is said once.
+ */
+async function applyPluginTools(doc: Record<string, unknown>, dir: Directory, warnings: string[]): Promise<void> {
+  if (!Array.isArray(doc.pluginTools)) return
+  const out: Array<Record<string, unknown>> = []
+  const byInstall = new Map<string, Map<string, string>>()
+  for (const row of doc.pluginTools as Array<Record<string, unknown>>) {
+    const ref = typeof row.plugin === 'string' ? parseRef(row.plugin) : null
+    const installId = ref?.kind === 'plugin' ? dir.plugin?.get(ref.name) : undefined
+    if (!ref || !installId || typeof row.tool !== 'string') continue
+    if (!byInstall.has(installId)) byInstall.set(installId, await localTools(dir, installId))
+    const capabilityId = byInstall.get(installId)!.get(row.tool)
+    if (!capabilityId) {
+      warnings.push(`  warning: Plugin ${ref.name} has no tool ${row.tool} here, so the Agent’s setting for it is not applied`)
+      continue
+    }
+    const { plugin: _plugin, tool: _tool, ...rest } = row
+    out.push({ capabilityId, ...rest })
+  }
+  delete doc.pluginTools
+  doc.appCapabilities = out
+}
+
+/** Whether a workflow has something `localizeWorkflow` changes: a Function version pin, a Plugin trigger acting as a person. */
+function workflowNeedsLocalizing(doc: unknown): boolean {
+  const d = (doc ?? {}) as Record<string, unknown>
+  const triggers = Array.isArray(d.trigger) ? (d.trigger as Array<Record<string, unknown>>) : []
+  if (triggers.some((t) => t?.kind === 'plugin' && (t.account as { kind?: string } | undefined)?.kind === 'user')) return true
+  let pinned = false
+  const visit = (v: unknown) => {
+    if (pinned) return
+    if (Array.isArray(v)) return v.forEach(visit)
+    if (!v || typeof v !== 'object') return
+    const o = v as Record<string, unknown>
+    if (o.kind === 'function' && typeof (o.params as Record<string, unknown> | undefined)?.version === 'number') pinned = true
+    for (const x of Object.values(o)) visit(x)
+  }
+  visit(d.nodes)
+  return pinned
+}
+
+/**
+ * A workflow without the triggers that name what nothing in the project
+ * provides (a Plugin trigger on a built-in connection): the workflow still
+ * runs from its other triggers, by hand or from an Agent. Changes `doc`.
+ */
+function dropTriggers(doc: Record<string, unknown>, items: Array<{ path: string; value: string }>): string[] {
+  const triggers = doc.trigger as Array<Record<string, unknown>> | undefined
+  if (!Array.isArray(triggers) || !items.length) return []
+  const gone = new Map<number, string>()
+  for (const u of items) gone.set(Number(u.path.split('.')[1]), u.value)
+  doc.trigger = triggers.filter((_, i) => !gone.has(i))
+  return [...gone].map(([i, ref]) => {
+    const t = triggers[i] ?? {}
+    const what = t.kind === 'plugin' && typeof t.event === 'string' ? `Plugin trigger ${t.event}` : `${String(t.kind ?? 'A')} trigger`
+    return `  warning: Its ${what} is left out here: it uses ${refWords(ref)}, which ${absentWhy(ref)}`
+  })
+}
+
+function readDoc(path: string): unknown {
+  const text = readFileSync(path, 'utf8')
+  return /\.json$/.test(path) ? JSON.parse(text) : parseYaml(text)
+}
+
+export interface Resolved {
+  ok: boolean
+  /** Project-relative path to apply instead of the target's own file; absent when the file names nothing. */
+  file?: string
+  /** The resolved document, for behavior settings sent over the API. */
+  doc?: unknown
+  /** Warnings and, when not ok, the reasons. */
+  output: string
+  /** Not ok because it names these (`workflow/telco-fault-triage`), which the runtime does not have yet. */
+  missing?: string[]
+  /** Not ok because it names this many governed Actions by the platform's id. */
+  unnamedActions?: number
+}
+
+/**
+ * Resolve a target's `kind/name` references against the runtime. Returns the
+ * file unchanged (no `file`) when it names nothing.
+ */
+/**
+ * A model the runtime's catalog does not have (a pulled Agent on the platform's
+ * own model) runs on the model chosen for new Agents here, and says so:
+ * the Agent and its workflows work locally instead of failing on a name.
+ */
+function substituteModels(doc: unknown, dir: Directory, warnings: string[], label: string): unknown {
+  const models = dir.model
+  if (!models?.size) return doc
+  // The model chosen for new Agents, or else the first the runtime offers.
+  const fallback = readProviderSetup().defaults.agentModel
+  const usable = fallback && models.has(fallback) ? fallback : ([...models.keys()][0] ?? null)
+  const swap = (slug: string): string | null => {
+    if (models.has(slug) || !usable) return null
+    warnings.push(`  warning: ${label} names the model ${slug}, which this runtime does not have; it uses ${usable} here`)
+    return usable
+  }
+  const walk = (v: unknown, key: string): unknown => {
+    if (typeof v === 'string') {
+      const ref = parseRef(v)
+      if (ref?.kind === 'model') {
+        const next = swap(ref.name)
+        return next ? `model/${next}` : v
+      }
+      if (key === 'modelSlug') return swap(v) ?? v
+      return v
+    }
+    if (Array.isArray(v)) return v.map((x) => walk(x, key))
+    if (v && typeof v === 'object') return Object.fromEntries(Object.entries(v as Record<string, unknown>).map(([k, x]) => [k, walk(x, k)]))
+    return v
+  }
+  return walk(doc, '')
+}
+
+export async function resolveTarget(
+  project: LocalProject,
+  target: SyncTarget,
+  directory: () => Promise<Directory>,
+  workspaceId?: string,
+  organizationId?: string,
+): Promise<Resolved> {
+  if (target.kind !== 'agent' && target.kind !== 'workflow' && target.kind !== 'operating') return { ok: true, output: '' }
+  const path = join(project.root, target.file)
+  let doc: unknown
+  try {
+    doc = readDoc(path)
+  } catch (err) {
+    return { ok: false, output: `error [USAGE]: ${target.file} could not be read: ${(err as Error).message}` }
+  }
+  const modelSlugs = target.kind === 'agent' && (Array.isArray((doc as { modelConfigs?: unknown[] })?.modelConfigs) || typeof (doc as { config?: { voice?: { voiceSlug?: unknown } } })?.config?.voice?.voiceSlug === 'string')
+  const mcpServers = target.kind === 'agent' && Array.isArray((doc as { mcpServers?: unknown[] })?.mcpServers) && (doc as { mcpServers: unknown[] }).mcpServers.length > 0
+  const objectTools = target.kind === 'agent' && Array.isArray((doc as { objectBindings?: unknown[] })?.objectBindings) && (doc as { objectBindings: unknown[] }).objectBindings.length > 0
+  if (!kindsIn(doc).size && !modelSlugs && !mcpServers && !objectTools && !governedActionIds(doc).length && !(target.kind === 'workflow' && workflowNeedsLocalizing(doc))) return { ok: true, output: '', doc }
+  const dir = await directory()
+  const warnings: string[] = []
+  // Built-in connections the project has stand-ins for (`local-stand-ins.ts`).
+  const standIns = standInNames(project.root)
+  // A trigger on a stand-in, or on the platform-only analytics Plugin, answers no events here.
+  if (target.kind === 'workflow') warnings.push(...dropStandInTriggers(project.root, doc, new Set([...standIns, ...platformOnlyNames(project.root)])))
+  if (target.kind === 'agent' && doc && typeof doc === 'object') {
+    // The workspace's analytics stays on the platform: the Agent runs here without those tools.
+    warnings.push(...dropPlatformOnly(doc as Record<string, unknown>, platformOnlyNames(project.root)))
+    addStandInServers(project, doc as Record<string, unknown>, standIns)
+  }
+  await fillAgents(doc, dir)
+  doc = substituteModels(doc, dir, warnings, target.file)
+  if (target.kind === 'agent') substituteVoice(doc, await runtimeVoices(dir), warnings, target.file)
+  if (target.kind === 'workflow') await localizeWorkflow(doc, dir, project.root, warnings)
+  if (target.kind === 'agent' && doc && typeof doc === 'object') {
+    // A skill binding names the workspace the skill lives in: here, the runtime's own.
+    const bindings = (doc as { skills?: { workspaceBindings?: Array<Record<string, unknown>> } }).skills?.workspaceBindings
+    if (workspaceId) for (const b of bindings ?? []) b.workspaceId ??= workspaceId
+    await applyPluginTools(doc as Record<string, unknown>, dir, warnings)
+    if (mcpServers) fillMcpServerHeaders(project, doc as Record<string, unknown>)
+    // Its object tools: each definition made or brought up to date here, then bound by this runtime's id.
+    if (objectTools) warnings.push(...(await ensureObjectDefinitions(doc as Record<string, unknown>, dir, ownerCalls.get(dir) ?? null, target.file)))
+    for (const relation of OPTIONAL_RELATIONS) {
+      const found = relation(doc as Record<string, unknown>)
+      if (!found) continue
+      const kept = found.rows.filter((row) => {
+        const { unresolved } = toIds(row, dir)
+        if (unresolved.length) warnings.push(`  warning: ${unresolved.map((u) => u.value).join(', ')} is not on this runtime; the Agent is applied without it`)
+        return !unresolved.length
+      })
+      found.set(kept)
+    }
+  }
+  const ids = toIds(doc, dir)
+  const resolved = ids.doc
+  let unresolved = ids.unresolved
+  // What nothing in the project provides (a built-in connection, a knowledge base not pulled, an
+  // object type the runtime leaves off) would be waited for forever: it is applied around instead,
+  // and each omission is an adaptation (`local-adapt.ts`). What the project holds but has not
+  // applied yet is still waited for, so the retry applies the file whole once it is there.
+  if (unresolved.length) {
+    const provides = projectProvides(project, organizationId)
+    const named = (u: (typeof unresolved)[number]) => !!u.kind && !isUuid(u.value)
+    if (!unresolved.some((u) => named(u) && provides(u.value))) {
+      const links = unresolved.filter((u) => u.link && named(u))
+      const adapted = plainLinks(resolved, links)
+      unresolved = unresolved.filter((u) => !links.includes(u))
+      if (target.kind === 'operating' && resolved && typeof resolved === 'object') {
+        adapted.unshift(...adaptOperating(resolved as Record<string, unknown>, unresolved.filter(named)))
+        unresolved = unresolved.filter((u) => !named(u))
+      }
+      if (target.kind === 'workflow' && resolved && typeof resolved === 'object') {
+        const inTrigger = unresolved.filter((u) => named(u) && /^trigger\.\d+(\.|$)/.test(u.path))
+        adapted.unshift(...dropTriggers(resolved as Record<string, unknown>, inTrigger))
+        unresolved = unresolved.filter((u) => !inTrigger.includes(u))
+      }
+      warnings.push(...adapted)
+    }
+  }
+  // A node still naming a governed Action by the platform's id, when this runtime's
+  // Actions are known and it is not one of them: say so here, not as the runtime's
+  // "does not exist in this workspace" about an id nobody can place.
+  const localActions = new Set(dir.action?.values() ?? [])
+  const byPlatformId = dir.action ? governedActionIds(doc).filter((a) => !localActions.has(a.id)) : []
+  if (unresolved.length || byPlatformId.length) {
+    const actions = unresolved.filter((u) => u.kind === 'action').length
+    const others = unresolved.length - actions
+    const missing = [...new Set(unresolved.flatMap((u) => (u.kind && !isUuid(u.value) ? [u.value.includes('/') ? u.value : `${u.kind}/${u.value}`] : [])))]
+    return {
+      ok: false,
+      missing,
+      ...(byPlatformId.length ? { unnamedActions: byPlatformId.length } : {}),
+      output: [
+        `error [UNRESOLVED_REFERENCE]: ${target.file} names what this runtime does not have`,
+        ...describeUnresolved(unresolved).map((l) => `  ${l}`),
+        ...byPlatformId.map((a) => `  ${a.path}: a governed Action named by its platform id (${a.id}), which this runtime does not have`),
+        ...(byPlatformId.length ? ['  hint: pull the workflow again with an organization key connected (`frontera local sync connect`) to name its Actions'] : []),
+        ...(actions ? [`  hint: governed Actions come with the Blueprint (pulled with an organization key) and are deployed on this runtime when it applies; ${actions === 1 ? 'this one is' : 'these are'} not in the project's blueprint/actions/`] : []),
+        ...(others ? ['  hint: pull it from the workspace (`frontera local sync pull <kind/name>`) or add its file to the project'] : []),
+      ].join('\n'),
+    }
+  }
+  if (target.kind === 'operating') return { ok: true, doc: resolved, output: warnings.join('\n') }
+  if (!kindsIn(doc).size && !warnings.length && JSON.stringify(resolved) === JSON.stringify(readDoc(path))) return { ok: true, output: '', doc }
+  const copy = join('.frontera', 'local', 'resolved', target.file)
+  mkdirSync(dirname(join(project.root, copy)), { recursive: true })
+  writeFileSync(join(project.root, copy), /\.json$/.test(target.file) ? `${JSON.stringify(resolved, null, 2)}\n` : stringifyYaml(resolved, { lineWidth: 0 }))
+  return { ok: true, file: copy, output: warnings.join('\n') }
+}
+
+function parseJson<T>(output: string): T | null {
+  const start = output.search(/[[{]/)
+  if (start < 0) return null
+  try {
+    return JSON.parse(output.slice(start)) as T
+  } catch {
+    return null
+  }
+}
+
+/** How the runtime holds one object type of the Blueprint it was given. */
+export interface ObjectBuild {
+  status: 'built' | 'adapted' | 'stubbed' | 'left-off'
+  adaptations?: string[]
+}
+
+export interface ResolvedBlueprint {
+  /** The runtime's copy, when the project's files needed changing; unset otherwise. */
+  dir?: string
+  warnings: string[]
+  /** Each object type as the runtime holds it, by apiName. */
+  objects: Record<string, ObjectBuild>
+  /** The governed Actions the runtime is given, with whether each runs here. */
+  actions: LocalAction[]
+  /** Actions left off the copy, with why: they act on what the runtime leaves off. */
+  leftOffActions: Record<string, string>
+  /** The Media Sets the runtime needs, empty, for the media-backed types it holds: API name → display name. */
+  mediaSets?: Record<string, string>
+}
+
+/**
+ * The Blueprint as this runtime can hold it, in a copy under
+ * `.frontera/local/resolved/blueprint`; the project's files stay as pulled.
+ * The rules are `objectTypeFit` and `actionFit` (`local-portability.ts`):
+ * - An object type backed by the platform's media files (a `media_reference`
+ *   property) cannot be read from a local file dataset: it is left out, with
+ *   the link types, metrics and governed Actions that name it.
+ * - An object type whose rows are read by markings, with no markings column
+ *   named, relies on a column the platform's media datasets publish; over a
+ *   local file dataset it reads with organization row access instead.
+ * - A calculated property is left off the type, and an Action that sets it.
+ * Each says so. `dir` is unset when nothing needed changing.
+ */
+export function resolveBlueprint(project: LocalProject): ResolvedBlueprint {
+  const source = join(project.root, 'blueprint')
+  const types = join(source, 'object-types')
+  const none: ResolvedBlueprint = { warnings: [], objects: {}, actions: [], leftOffActions: {} }
+  if (!existsSync(types)) return none
+  const yamlIn = (dir: string) => (existsSync(join(source, dir)) ? readdirSync(join(source, dir)).filter((n) => /\.ya?ml$/.test(n) && !n.startsWith('.')) : [])
+  const read = (dir: string, name: string) => {
+    try {
+      return parseYaml(readFileSync(join(source, dir, name), 'utf8')) as Record<string, any> | null
+    } catch {
+      return null
+    }
+  }
+  const patched = new Map<string, string>()
+  const dropped = new Set<string>()
+  /** Calculated properties left off, as `Type.property`. */
+  const droppedFields = new Set<string>()
+  const removed: string[] = []
+  const warnings: string[] = []
+  const objects: Record<string, ObjectBuild> = {}
+  const mediaSets: Record<string, string> = {}
+  const hasLocalDataset = (dataset: string) => existsSync(join(project.root, 'datasets', `${dataset}.json`))
+  for (const name of yamlIn('object-types')) {
+    const doc = read('object-types', name)
+    if (!doc || typeof doc.apiName !== 'string') continue
+    const fit = localAdaptation(doc, hasLocalDataset)
+    const adaptations = classify(objectTypeNeeds(doc, hasLocalDataset)).adaptations
+    if (fit.leftOff) {
+      dropped.add(doc.apiName)
+      removed.push(join('object-types', name))
+      objects[doc.apiName] = { status: 'left-off', adaptations }
+      warnings.push(`  warning: ${doc.apiName} is left off this runtime: it reads the platform's media files`)
+      continue
+    }
+    objects[doc.apiName] = fit.mediaStub ? { status: 'stubbed', adaptations } : adaptations.length ? { status: 'adapted', adaptations } : { status: 'built' }
+    let next = doc
+    // Over a Media Set's catalog: an empty Media Set of that name stands in, made before the apply.
+    // A property's set is the platform's id; the runtime derives its own from the dataset.
+    if (fit.mediaStub) {
+      mediaSets[fit.mediaStub] ??= readableName(fit.mediaStub)
+      const properties = (doc.properties as Array<Record<string, unknown>> | undefined) ?? []
+      next = { ...next, properties: properties.map(({ mediaSetId: _set, ...p }) => p) }
+      warnings.push(`  warning: ${doc.apiName}’s files stay on the platform: an empty Media Set, ${fit.mediaStub}, stands in for them here`)
+    }
+    // A calculated property (a location from latitude and longitude) reads no column, and
+    // `blueprint apply` cannot create one yet: the runtime holds the type without it.
+    if (fit.calculated.length) {
+      const properties = (doc.properties as Array<{ calculation?: unknown }> | undefined) ?? []
+      next = { ...next, properties: properties.filter((p) => !p.calculation) }
+      for (const f of fit.calculated) droppedFields.add(`${doc.apiName}.${f}`)
+      warnings.push(`  warning: ${doc.apiName}.${fit.calculated.join(`, ${doc.apiName}.`)} is left off this runtime: calculated fields are not applied locally yet`)
+    }
+    if (fit.readsEveryRow) {
+      next = { ...next, rowAccess: 'organization' }
+      warnings.push(`  warning: ${doc.apiName ?? name} reads every row here: its markings come from the platform's dataset, and ${doc.backing?.dataset} has none`)
+    }
+    if (next !== doc) patched.set(join('object-types', name), stringifyYaml(next, { lineWidth: 0 }))
+  }
+  if (dropped.size) {
+    for (const name of yamlIn('link-types')) {
+      const doc = read('link-types', name)
+      if (dropped.has(doc?.from?.objectType) || dropped.has(doc?.to?.objectType)) removed.push(join('link-types', name))
+    }
+    for (const name of yamlIn('metrics')) {
+      if (dropped.has(read('metrics', name)?.objectType)) removed.push(join('metrics', name))
+    }
+  }
+  const actions: LocalAction[] = []
+  const leftOffActions: Record<string, string> = {}
+  for (const name of yamlIn('actions')) {
+    const doc = read('actions', name)
+    if (!doc || typeof doc.apiName !== 'string') continue
+    const fit = actionFit(doc)
+    const changes = (Array.isArray(doc.businessOutcomes) ? doc.businessOutcomes : []).flatMap((o: Record<string, any>) => (Array.isArray(o?.expectedChanges) ? o.expectedChanges : [])) as Array<Record<string, any>>
+    const inputs = (Array.isArray(doc.inputs) ? doc.inputs : []) as Array<Record<string, any>>
+    const touches = [fit.subject, ...changes.map((c) => c?.objectType), ...inputs.map((i) => i?.valueType?.objectType)].filter((t): t is string => typeof t === 'string')
+    const offType = touches.find((t) => dropped.has(t))
+    const offField = changes.map((c) => `${c?.objectType ?? fit.subject}.${c?.property}`).find((f) => droppedFields.has(f))
+    if (offType || offField) {
+      leftOffActions[doc.apiName] = offType ? `it acts on ${offType}, which reads the platform’s media files` : `it sets ${offField}, a calculated field the runtime leaves off`
+      removed.push(join('actions', name))
+      warnings.push(`  warning: governed Action ${doc.apiName} is left off this runtime: ${leftOffActions[doc.apiName]}`)
+      continue
+    }
+    const capability = doc.governance?.invokeCapability
+    actions.push({ apiName: doc.apiName, fit, ...(typeof capability === 'string' ? { invokeCapability: capability } : {}) })
+  }
+  const out: ResolvedBlueprint = { warnings, objects, actions, leftOffActions, ...(Object.keys(mediaSets).length ? { mediaSets } : {}) }
+  if (!patched.size && !removed.length) return out
+  const copy = join('.frontera', 'local', 'resolved', 'blueprint')
+  rmSync(join(project.root, copy), { recursive: true, force: true })
+  cpSync(source, join(project.root, copy), { recursive: true })
+  for (const [rel, text] of patched) writeFileSync(join(project.root, copy, rel), text)
+  for (const rel of removed) rmSync(join(project.root, copy, rel), { force: true })
+  return { ...out, dir: copy }
+}
+
+/**
+ * The properties each object type lets a governed Action write
+ * (`backing.editable`), for the types those Actions act on. `blueprint apply`
+ * leaves backings to `bind`, so `local dev` declares them itself
+ * (`blueprint editable`) before an Action's write path is built.
+ */
+export function editableSets(dir: string, subjects: ReadonlySet<string>): Map<string, string[]> {
+  const out = new Map<string, string[]>()
+  const at = join(dir, 'object-types')
+  if (!existsSync(at)) return out
+  for (const name of readdirSync(at)) {
+    if (!/\.ya?ml$/.test(name) || name.startsWith('.')) continue
+    try {
+      const doc = parseYaml(readFileSync(join(at, name), 'utf8')) as { apiName?: unknown; backing?: { editable?: unknown } } | null
+      const editable = doc?.backing?.editable
+      if (typeof doc?.apiName === 'string' && subjects.has(doc.apiName) && Array.isArray(editable) && editable.length) out.set(doc.apiName, editable.map(String).sort())
+    } catch {
+      // A file that does not parse is refused by the apply itself.
+    }
+  }
+  return out
+}
+
+/**
+ * A copy of a Blueprint folder without some governed Actions, under
+ * `.frontera/local/resolved/blueprint-without`: applied with `--prune`, it
+ * takes them out of the runtime's draft so the full folder can author them
+ * again under new ids. Returns the copy's absolute path.
+ */
+export function blueprintWithout(project: LocalProject, dir: string, actions: string[]): string {
+  const copy = join(project.root, '.frontera', 'local', 'resolved', 'blueprint-without')
+  rmSync(copy, { recursive: true, force: true })
+  cpSync(dir, copy, { recursive: true })
+  const at = join(copy, 'actions')
+  if (existsSync(at)) {
+    for (const name of readdirSync(at)) {
+      if (!/\.ya?ml$/.test(name)) continue
+      try {
+        const doc = parseYaml(readFileSync(join(at, name), 'utf8')) as { apiName?: unknown } | null
+        if (typeof doc?.apiName === 'string' && actions.includes(doc.apiName)) rmSync(join(at, name), { force: true })
+      } catch {
+        // A file that does not parse is applied as it is, and refused there.
+      }
+    }
+  }
+  return copy
+}
+
+/** The settings a knowledge base's file holds that decide how it chunks, searches and reads (`knowledge.json`). */
+const KNOWLEDGE_SETTINGS = ['retrieval', 'chunker', 'chunkSize', 'chunkOverlap', 'topK', 'similarityThreshold', 'hybridConfig', 'extractorConfig', 'ocrConfig'] as const
+
+/** The files `local dev` uploads into a knowledge base: those the runtime ingests. */
+export const KNOWLEDGE_DOCUMENT = /\.(md|markdown|txt|pdf|docx|html)$/i
+
+/**
+ * A knowledge base's settings as the runtime can hold them. A model it names
+ * (the reranker, the extractor's, OCR's) that the runtime's catalog does not
+ * have is left off here, so documents are read and searched without that
+ * step instead of failing; each says so. `models` is the catalog, or null
+ * when it could not be read (the settings then go as they are).
+ */
+export function knowledgeSettings(doc: Record<string, unknown>, models: ReadonlySet<string> | null, label: string): { settings: Record<string, unknown>; warnings: string[] } {
+  const settings: Record<string, unknown> = {}
+  for (const key of KNOWLEDGE_SETTINGS) if (doc[key] !== undefined && doc[key] !== null) settings[key] = doc[key]
+  // The platform keeps the threshold as a decimal, which its list sends as a string ("0.7"); the update takes numbers.
+  for (const key of ['chunkSize', 'chunkOverlap', 'topK', 'similarityThreshold']) {
+    if (typeof settings[key] === 'string' && Number.isFinite(Number(settings[key]))) settings[key] = Number(settings[key])
+  }
+  const warnings: string[] = []
+  const has = (model: unknown) => typeof model !== 'string' || !model.trim() || !models || models.has(model) || models.has(model.split('/').pop()!)
+  const hybrid = settings.hybridConfig as Record<string, unknown> | undefined
+  if (hybrid?.rerank === true && !has(hybrid.rerankerModel)) {
+    settings.hybridConfig = { ...hybrid, rerank: false }
+    warnings.push(`  warning: Knowledge base ${label} searches without reranking here: its reranker ${String(hybrid.rerankerModel)} isn’t on this runtime`)
+  }
+  for (const [key, what] of [['extractorConfig', 'extraction'], ['ocrConfig', 'OCR']] as const) {
+    const step = settings[key] as Record<string, unknown> | undefined
+    if (step?.enabled === true && !has(step.model)) {
+      settings[key] = { ...step, enabled: false }
+      warnings.push(`  warning: Knowledge base ${label} reads documents without ${what} here: its model ${String(step.model)} isn’t on this runtime`)
+    }
+  }
+  return { settings, warnings }
+}
+
+/** The runtime's model catalog, by slug and by provider/model id; null when it could not be read. */
+async function localModels(local: { serviceUrl: string; creds: LocalCredentials }): Promise<Set<string> | null> {
+  try {
+    const listed = await syncClient(local.serviceUrl, local.creds.orgKey).get('/v1/config/models/catalog')
+    const out = new Set<string>()
+    for (const m of rows<{ slug?: string; modelId?: string; provider?: string }>(listed)) {
+      for (const v of [m.slug, m.modelId, m.provider && m.modelId ? `${m.provider}/${m.modelId}` : undefined]) if (v) out.add(v)
+    }
+    return out
+  } catch {
+    return null
+  }
+}
+
+/**
+ * A knowledge base: created when the runtime has none by its name, given the
+ * file's settings (retrieval mode, chunking, top-K and threshold, hybrid
+ * search and reranking, extraction and OCR), then the folder's documents the
+ * base does not hold yet are uploaded.
+ */
+export async function applyKnowledge(
+  project: LocalProject,
+  target: Extract<SyncTarget, { kind: 'knowledge' }>,
+  profiles: SyncProfiles,
+  run: (args: string[]) => Promise<RunResult>,
+  local?: { serviceUrl: string; creds: LocalCredentials },
+): Promise<RunResult> {
+  let doc: Record<string, unknown> & { name?: string; description?: string }
+  try {
+    doc = JSON.parse(readFileSync(join(project.root, target.file), 'utf8')) as Record<string, unknown> & { name?: string; description?: string }
+  } catch (err) {
+    return { ok: false, output: `error [USAGE]: ${target.file} is not valid JSON: ${(err as Error).message}` }
+  }
+  const name = doc.name || target.name
+  const p = ['--profile', profiles.workspace]
+  const list = async () => parseJson<Array<{ id?: string; name: string }>>((await run(['knowledge', 'list', '--json', ...p])).output) ?? []
+  const listed = await run(['knowledge', 'list', '--json', ...p])
+  if (!listed.ok) return listed
+  let bases = parseJson<Array<{ id?: string; name: string }>>(listed.output) ?? []
+  if (!bases.some((b) => b.name === name)) {
+    const created = await run(['knowledge', 'create', name, ...(doc.description ? ['--description', doc.description] : []), ...p])
+    if (!created.ok) return created
+    bases = await list()
+  }
+  const notes: string[] = []
+  const id = bases.find((b) => b.name === name)?.id
+  if (local?.creds.workspaceKey && id) {
+    const { settings, warnings } = knowledgeSettings(doc, await localModels(local), name)
+    notes.push(...warnings)
+    if (Object.keys(settings).length) {
+      const failed = await fetch(new URL(`/v1/workspace-knowledge/${encodeURIComponent(id)}`, local.serviceUrl), {
+        method: 'PUT',
+        headers: { authorization: `Bearer ${local.creds.workspaceKey}`, 'content-type': 'application/json' },
+        body: JSON.stringify(settings),
+      })
+        .then(async (res) => (res.ok ? null : `${res.status} ${(await res.text()).slice(0, 200)}`))
+        .catch((err: Error) => err.message)
+      if (failed) notes.push(`  warning: Knowledge base ${name} keeps the runtime’s own retrieval settings: its settings were refused (${failed})`)
+    }
+  } else if (KNOWLEDGE_SETTINGS.some((k) => doc[k] !== undefined)) {
+    notes.push(`  warning: Knowledge base ${name} keeps the runtime’s own retrieval settings: the runtime has no workspace key yet`)
+  }
+  const finished = (r: RunResult): RunResult => (notes.length ? { ...r, output: [...notes, r.output.trim()].filter(Boolean).join('\n') } : r)
+  // Its quality checks, once its documents are there: they name documents by path.
+  const done = async (r: RunResult): Promise<RunResult> => {
+    if (!r.ok || !existsSync(join(project.root, 'knowledge', target.name, QUALITY_CHECKS_FILE))) return finished(r)
+    if (!local?.creds.workspaceKey || !id) {
+      notes.push(`  warning: Knowledge base ${name}’s quality checks wait until the runtime has a workspace key`)
+      return finished(r)
+    }
+    const checked = await applyKnowledgeChecks(project, target.name, name, id, local)
+    return finished({ ...r, output: [r.output.trim(), ...checked].filter(Boolean).join('\n') })
+  }
+  // The documents, the knowledge base's folders as subfolders (`Policies/Returns/terms.pdf`).
+  const { documentPath, documentPaths, folderPaths, splitDocumentPath } = await import('./local-knowledge-documents')
+  const documents = documentPaths(project.root, target.name)
+  if (!documents.length) return await done({ ok: true, output: '' })
+  const sources = await run(['knowledge', 'sources', name, '--json', ...p])
+  const listedSources = parseJson<Array<{ fileName?: string; folderId?: string | null }>>(sources.output) ?? []
+  const key = local?.creds.workspaceKey
+  const http = async (method: string, path: string, body?: FormData | Record<string, unknown>) => {
+    const res = await fetch(new URL(path, local!.serviceUrl), {
+      method,
+      headers: { authorization: `Bearer ${key}`, ...(body && !(body instanceof FormData) ? { 'content-type': 'application/json' } : {}) },
+      ...(body ? { body: body instanceof FormData ? body : JSON.stringify(body) } : {}),
+    })
+    const text = await res.text()
+    if (!res.ok) throw new Error(`${res.status} ${text.slice(0, 200)}`)
+    const parsed = text ? (JSON.parse(text) as { data?: unknown }) : null
+    return (parsed?.data ?? parsed) as Record<string, unknown> | null
+  }
+  const nested = documents.some((d) => d.includes('/'))
+  const folders = nested && key && id && listedSources.some((s) => s.folderId)
+    ? folderPaths((((await http('GET', `/v1/workspace-knowledge/${encodeURIComponent(id)}/folders`).catch(() => null))?.folders ?? []) as Array<{ id: string; parentId?: string | null; name: string }>))
+    : new Map<string, string>()
+  const have = new Set(listedSources.map((s) => documentPath(s.folderId ? folders.get(s.folderId) : null, s.fileName ?? '')))
+  const fresh = documents.filter((f) => !have.has(f))
+  if (!fresh.length) return await done({ ok: true, output: '' })
+  const top = fresh.filter((f) => !f.includes('/'))
+  const filed = fresh.filter((f) => f.includes('/'))
+  const lines: string[] = []
+  if (top.length) {
+    const uploaded = await run(['knowledge', 'upload', name, ...top.map((f) => join(dirname(target.file), f)), ...p])
+    if (!uploaded.ok) return await done(uploaded)
+    if (uploaded.output.trim()) lines.push(uploaded.output.trim())
+  }
+  if (filed.length && (!key || !id)) {
+    notes.push(`  warning: Knowledge base ${name}: ${filed.length} document${filed.length === 1 ? ' in a folder waits' : 's in folders wait'} until the runtime has a workspace key`)
+  } else if (filed.length) {
+    // Each folder made as the uploader makes a dropped directory's (the same name under the same parent is the same folder).
+    const made = new Map<string, string>()
+    const folderFor = async (path: string): Promise<string> => {
+      let parentId: string | null = null
+      let at = ''
+      for (const segment of path.split('/')) {
+        at = at ? `${at}/${segment}` : segment
+        const known = made.get(at)
+        if (known) {
+          parentId = known
+          continue
+        }
+        const created = await http('POST', `/v1/workspace-knowledge/${encodeURIComponent(id!)}/folders`, { name: segment, parentId })
+        parentId = String((created?.folder as { id?: unknown } | undefined)?.id ?? '')
+        if (!parentId) throw new Error('the runtime did not return the folder')
+        made.set(at, parentId)
+      }
+      return parentId!
+    }
+    for (const path of filed) {
+      const { folder, fileName } = splitDocumentPath(path)
+      try {
+        const form = new FormData()
+        form.append('file', new File([readFileSync(join(project.root, dirname(target.file), path))], fileName))
+        form.append('folderId', await folderFor(folder!))
+        await http('POST', `/v1/workspace-knowledge/${encodeURIComponent(id!)}/sources`, form)
+        lines.push(`  uploaded ${path}`)
+      } catch (err) {
+        notes.push(`  warning: Knowledge base ${name}: ${path} wasn’t uploaded (${(err as Error).message})`)
+      }
+    }
+  }
+  return await done({ ok: true, output: lines.join('\n') })
+}
+
+/**
+ * A knowledge base's quality checks on the runtime (`local-quality-checks.ts`),
+ * their documents by this runtime's ids. Returns the lines for the build.
+ */
+async function applyKnowledgeChecks(project: LocalProject, folder: string, name: string, id: string, local: { serviceUrl: string; creds: LocalCredentials }): Promise<string[]> {
+  const rel = join('knowledge', folder, QUALITY_CHECKS_FILE)
+  let checks
+  try {
+    checks = readQualityChecks(readFileSync(join(project.root, rel), 'utf8'))
+  } catch (err) {
+    return [`  warning: ${rel} doesn’t parse, so its quality checks weren’t applied: ${(err as Error).message.split('\n')[0]}`]
+  }
+  const call = async (method: string, path: string, body?: unknown) => {
+    const res = await fetch(new URL(path, local.serviceUrl), {
+      method,
+      headers: { authorization: `Bearer ${local.creds.workspaceKey}`, ...(body === undefined ? {} : { 'content-type': 'application/json' }) },
+      ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+    })
+    const text = await res.text()
+    let parsed: unknown = text
+    try {
+      parsed = text ? JSON.parse(text) : null
+    } catch {
+      // Kept as text.
+    }
+    return { status: res.status, body: parsed }
+  }
+  const { readFolders } = await import('./local-knowledge-documents')
+  const sources = await call('GET', `/v1/workspace-knowledge/${encodeURIComponent(id)}/sources`)
+  const byPath = new Map([...sourcePaths(sourceRows(sources.body), await readFolders({ get: async (path: string) => (await call('GET', path)).body }, id))].map(([sourceId, path]) => [path, sourceId] as const))
+  const applied = await applyQualityChecks(id, name, checks, byPath, call)
+  return applied.lines
+}
+
+/** What a Plugin may do, as its file's `policy` holds it (`pluginPolicy` in `local-sync-remote.ts`). */
+interface PluginPolicyDoc {
+  enabled?: boolean
+  actions?: string
+  newTools?: string
+  tools?: Record<string, { enabled?: boolean; requiresApproval?: boolean; paramConstraints?: Record<string, unknown> }>
+}
+
+/**
+ * An MCP Plugin: installed under the file's name, or its configuration
+ * replaced when it is installed already; then what it may do.
+ *
+ * A pulled file carries the workspace's `policy` (on or off, its Action
+ * policy, what a new tool starts as, each tool's own setting), and the
+ * runtime is given the same, so an Agent cannot call a tool here that the
+ * workspace keeps read-only or behind an approval. The policy is not part of
+ * the connection's configuration: the runtime is given the file without it.
+ * A file written by hand, with no policy, has its tools enabled, as a local
+ * runtime has one person trying them.
+ */
+export async function applyPlugin(
+  project: LocalProject,
+  target: Extract<SyncTarget, { kind: 'plugin' }>,
+  profiles: SyncProfiles,
+  run: (args: string[]) => Promise<RunResult>,
+  local?: { serviceUrl: string; creds: LocalCredentials },
+): Promise<RunResult> {
+  let doc: Record<string, unknown>
+  try {
+    doc = JSON.parse(readFileSync(join(project.root, target.file), 'utf8')) as Record<string, unknown>
+  } catch (err) {
+    return { ok: false, output: `error [USAGE]: ${target.file} is not valid JSON: ${(err as Error).message}` }
+  }
+  // Its description and icon are the Plugin's own, not connection settings: set after it is there.
+  const { policy, description, icon, ...declared } = doc
+  const p = ['--profile', profiles.workspace]
+  const find = async () => {
+    const listed = await run(['plugin', 'list', '--json', ...p])
+    const rows = parseJson<Array<{ install?: { id: string; installName: string; config?: Record<string, unknown> | null } }>>(listed.output) ?? []
+    return rows.find((r) => r.install?.installName === target.name)?.install
+  }
+  const existing = await find()
+  let id = existing?.id
+  // Settings declared empty (`""`, secrets) are filled with a reference to this runtime's secret
+  // named after them (`local-secrets.ts`), resolved when the Plugin connects, so setting the secret
+  // later needs no new apply. One that already has a value on this install and no such secret is
+  // sent empty instead, which keeps that value: the platform keeps a stored secret an update leaves blank.
+  const inputs = pluginSecretInputs(target.name, declared)
+  const have = inputs.length && local ? ((await localSecretNames(local.serviceUrl, local.creds)) ?? new Set<string>()) : new Set<string>()
+  const stored = (existing?.config ?? {}) as Record<string, unknown>
+  const storedHeaders = (stored.headers && typeof stored.headers === 'object' ? stored.headers : {}) as Record<string, unknown>
+  const hasStored = (i: (typeof inputs)[number]) => !!(i.header ? storedHeaders[i.field] : stored[i.field])
+  const filled = inputs.filter((i) => have.has(i.secret) || !hasStored(i))
+  const config = fillPluginSecrets(declared, filled)
+  const needs = inputs
+    .filter((i) => !have.has(i.secret) && !hasStored(i))
+    .map((i) => needsValueLine(i.secret, `Plugin ${target.name}, ${i.header ? 'header ' : ''}${i.field}`))
+  let file = target.file
+  if (policy !== undefined || filled.length || description !== undefined || icon !== undefined) {
+    file = join('.frontera', 'local', 'resolved', target.file)
+    mkdirSync(dirname(join(project.root, file)), { recursive: true })
+    writeFileSync(join(project.root, file), `${JSON.stringify(config, null, 2)}\n`)
+  }
+  const step = id ? await run(['plugin', 'configure', id, '--file', file, ...p]) : await run(['plugin', 'add', 'mcp', '--name', target.name, '--file', file, ...p])
+  if (!step.ok) return step
+  id ??= (await find())?.id
+  if (!id) return { ok: false, output: `error [NOT_FOUND]: ${target.name} was added but is not listed` }
+  const about = local && (description !== undefined || icon !== undefined) ? await applyPluginAbout(project, local, id, target.name, description, icon) : []
+  if (!policy || typeof policy !== 'object') {
+    const open = await run(['plugin', 'policy', id, '--enable', '--actions', 'allow_all', '--new-capability', 'enabled', ...p])
+    return open.ok ? { ok: true, output: [step.output.trim(), ...needs, ...about].filter(Boolean).join('\n') } : { ok: true, output: `  warning: ${target.name} is installed, but its tools could not be enabled:\n${open.output}` }
+  }
+  const want = policy as PluginPolicyDoc
+  const notes: string[] = [...needs, ...about]
+  const set = await run(['plugin', 'policy', id, want.enabled === false ? '--disable' : '--enable', '--actions', want.actions ?? 'read_only', '--new-capability', want.newTools ?? 'disabled', ...p])
+  if (!set.ok) notes.push(`  warning: ${target.name}’s policy could not be set as the workspace has it: ${oneLine(applyErrorText(set.output))}`)
+  const tools = Object.entries(want.tools ?? {})
+  if (tools.length) {
+    const listed = await run(['capability', 'available', id, '--json', ...p])
+    const here = new Map((parseJson<Array<{ id?: string; name?: string }>>(listed.output) ?? []).flatMap((r) => (r.id && r.name ? [[r.name, r.id] as const] : [])))
+    for (const [name, setting] of tools) {
+      const capability = here.get(name)
+      if (!capability) {
+        notes.push(`  warning: ${target.name} has no tool ${name} here, so its setting from the workspace is not applied`)
+        continue
+      }
+      const failed = local ? await setToolPolicy(local, id, capability, setting) : 'the runtime has no owner session'
+      if (failed) notes.push(`  warning: ${target.name}’s tool ${name} could not be set as the workspace has it: ${failed}`)
+    }
+  }
+  return { ok: true, output: [step.output.trim(), ...notes].filter(Boolean).join('\n') }
+}
+
+/**
+ * An Agent's MCP servers with the headers its Plugin has on this runtime.
+ *
+ * A draft Agent (every local one) runs its MCP servers from its own
+ * `mcpServers` list, not from the Plugin installs as a published one does, and
+ * a pull leaves their headers out. So each server named like a Plugin of the
+ * project takes that Plugin file's headers: a value the file gives, or, for
+ * one declared empty, a reference to the local secret that fills the Plugin's
+ * header (`local-secrets.ts`), which the runtime resolves when it connects
+ * (empty until the secret is set; the Plugin's apply says it needs a value).
+ * Headers the server already lists stay unless the Plugin gives one.
+ */
+export function fillMcpServerHeaders(project: LocalProject, doc: Record<string, unknown>): void {
+  const servers = Array.isArray(doc.mcpServers) ? (doc.mcpServers as Array<Record<string, unknown>>) : []
+  for (const server of servers) {
+    const name = typeof server?.name === 'string' ? server.name : null
+    const file = name ? join(project.root, 'mcp', `${name}.plugin.json`) : null
+    if (!name || !file || !existsSync(file)) continue
+    let plugin: Record<string, unknown>
+    try {
+      plugin = JSON.parse(readFileSync(file, 'utf8')) as Record<string, unknown>
+    } catch {
+      continue
+    }
+    const declared = plugin.headers && typeof plugin.headers === 'object' && !Array.isArray(plugin.headers) ? (plugin.headers as Record<string, unknown>) : {}
+    const headers: Record<string, string> = {}
+    for (const [h, value] of Object.entries(declared)) {
+      if (typeof value === 'string' && value !== '') {
+        headers[h] = value
+        continue
+      }
+      if (!NON_SECRET_HEADERS.has(h.toLowerCase())) headers[h] = `{{vault.${pluginSecretName(name, h)}}}`
+    }
+    if (Object.keys(headers).length) server.headers = { ...((server.headers as Record<string, unknown> | undefined) ?? {}), ...headers }
+  }
+}
+
+/** One tool's own setting on an install. The route takes a person's session: the owner's, as Studio has it. */
+const ICON_MIME: Record<string, string> = { png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', webp: 'image/webp', gif: 'image/gif', svg: 'image/svg+xml' }
+
+/**
+ * A Plugin's description and icon on the runtime, as its file has them:
+ * the icon (a project file beside the Plugin's, `mcp/<name>.icon.png`) is
+ * uploaded as the workspace's Plugin icons are, then both are set on the
+ * install. Returns warning lines for what could not be set; never fails the
+ * Plugin, which works without them.
+ */
+async function applyPluginAbout(project: LocalProject, local: { serviceUrl: string; creds: LocalCredentials }, installId: string, name: string, description: unknown, icon: unknown): Promise<string[]> {
+  const { creds } = local
+  if (!creds.session) return [`  warning: ${name}’s description and icon are not set: the runtime has no owner session; restart it`]
+  const headers = { authorization: `Bearer ${creds.session}`, 'x-org-id': creds.organizationId, 'x-workspace-id': creds.workspaceId }
+  const out: string[] = []
+  const patch: Record<string, unknown> = {}
+  if (description === null || typeof description === 'string') patch.description = typeof description === 'string' && description.trim() ? description.trim() : null
+  if (typeof icon === 'string' && icon) {
+    const at = join(project.root, icon)
+    const ext = icon.split('.').pop()?.toLowerCase() ?? ''
+    if (!at.startsWith(project.root) || !existsSync(at) || !ICON_MIME[ext]) out.push(`  warning: ${name}’s icon ${icon} is not an image file in the project, so it has none here`)
+    else {
+      try {
+        const form = new FormData()
+        form.set('file', new File([readFileSync(at)], icon.split('/').pop()!, { type: ICON_MIME[ext] }))
+        form.set('purpose', 'app-icon')
+        const res = await fetch(new URL('/v1/upload', local.serviceUrl), { method: 'POST', headers, body: form })
+        const body = (await res.json().catch(() => null)) as { data?: { storagePath?: string } } | null
+        if (!res.ok || !body?.data?.storagePath) throw new Error(`upload answered ${res.status}`)
+        patch.iconPath = body.data.storagePath
+      } catch (err) {
+        out.push(`  warning: ${name}’s icon could not be set: ${(err as Error).message}`)
+      }
+    }
+  } else if (icon === null) patch.iconPath = null
+  if (!Object.keys(patch).length) return out
+  try {
+    const res = await fetch(new URL(`/v1/apps/${encodeURIComponent(installId)}`, local.serviceUrl), { method: 'PUT', headers: { ...headers, 'content-type': 'application/json' }, body: JSON.stringify(patch) })
+    if (!res.ok) out.push(`  warning: ${name}’s description and icon could not be set: ${res.status} ${(await res.text()).slice(0, 200)}`)
+  } catch (err) {
+    out.push(`  warning: ${name}’s description and icon could not be set: ${(err as Error).message}`)
+  }
+  return out
+}
+
+async function setToolPolicy(local: { serviceUrl: string; creds: LocalCredentials }, installId: string, capabilityId: string, setting: NonNullable<PluginPolicyDoc['tools']>[string]): Promise<string | null> {
+  if (!local.creds.session) return 'the runtime has no owner session; restart it'
+  try {
+    const res = await fetch(new URL(`/v1/workspace/installs/${encodeURIComponent(installId)}/capability-policies/${encodeURIComponent(capabilityId)}`, local.serviceUrl), {
+      method: 'PATCH',
+      headers: { authorization: `Bearer ${local.creds.session}`, 'x-org-id': local.creds.organizationId, 'x-workspace-id': local.creds.workspaceId, 'content-type': 'application/json' },
+      body: JSON.stringify({ enabled: setting.enabled ?? null, requiresApprovalOverride: setting.requiresApproval ?? null, paramConstraints: setting.paramConstraints ?? null }),
+    })
+    return res.ok ? null : `${res.status} ${(await res.text()).slice(0, 200)}`
+  } catch (err) {
+    return (err as Error).message
+  }
+}
+
+/**
+ * Promote a workflow's latest draft to live on the local runtime. Returns the
+ * version promoted, or null when there was none or it was refused.
+ */
+export async function promoteWorkflow(serviceUrl: string, creds: LocalCredentials, slug: string): Promise<number | null> {
+  if (!creds.workspaceKey) return null
+  const call = (path: string, method: string) =>
+    fetch(new URL(path, serviceUrl), { method, headers: { authorization: `Bearer ${creds.workspaceKey}`, 'content-type': 'application/json' }, body: method === 'POST' ? '{}' : undefined })
+  const res = await call(`/v1/workflows/${encodeURIComponent(slug)}`, 'GET')
+  if (!res.ok) return null
+  const n = ((await res.json()) as { data?: { latestDraftNumber?: number | null } }).data?.latestDraftNumber
+  if (!n) return null
+  const promoted = await call(`/v1/workflows/${encodeURIComponent(slug)}/versions/${n}/promote`, 'POST')
+  return promoted.ok ? n : null
+}
+
+/** The project's object type files by API name, parsed; unreadable ones are left out. */
+function projectObjectTypes(root: string): Map<string, Record<string, unknown>> {
+  const dir = join(root, 'blueprint', 'object-types')
+  const out = new Map<string, Record<string, unknown>>()
+  if (!existsSync(dir)) return out
+  for (const name of readdirSync(dir)) {
+    if (!/\.(ya?ml|json)$/.test(name) || name.startsWith('.')) continue
+    try {
+      const doc = parseYaml(readFileSync(join(dir, name), 'utf8')) as Record<string, unknown> | null
+      if (doc && typeof doc.apiName === 'string') out.set(doc.apiName, doc)
+    } catch {
+      // A file that does not parse names nothing here; `blueprint apply` reports it.
+    }
+  }
+  return out
+}
+
+/**
+ * What an Agent may use (`agents/<slug>/bindings.json`): each Function and
+ * workflow it names is bound to the Agent with the settings in the file, and
+ * each object type in its `blueprint` list is granted to it (its Context and
+ * data, `local-agent-grants.ts`). Bindings already there are updated, not
+ * duplicated; one the runtime cannot make (the Function is not deployed yet)
+ * is reported and the rest go on.
+ */
+export async function applyBindings(project: LocalProject, target: Extract<SyncTarget, { kind: 'bindings' }>, serviceUrl: string, creds: LocalCredentials): Promise<RunResult> {
+  let doc: { functions?: Array<Record<string, unknown>>; workflows?: Array<Record<string, unknown>>; blueprint?: unknown }
+  try {
+    doc = JSON.parse(readFileSync(join(project.root, target.file), 'utf8'))
+  } catch (err) {
+    return { ok: false, output: `error [USAGE]: ${target.file} is not valid JSON: ${(err as Error).message}` }
+  }
+  if (!creds.workspaceKey) return { ok: false, output: 'error [LOCAL_NOT_SEEDED]: the runtime has no workspace key yet; restart it' }
+  const call = (path: string, method: string, body?: Record<string, unknown>) =>
+    fetch(new URL(path, serviceUrl), {
+      method,
+      headers: { authorization: `Bearer ${creds.workspaceKey}`, 'content-type': 'application/json' },
+      body: body === undefined ? undefined : JSON.stringify(body),
+    })
+  const put = async (path: string, body: Record<string, unknown>) => {
+    const res = await call(path, 'PUT', body)
+    return res.ok ? null : `${res.status} ${(await res.text()).slice(0, 200)}`
+  }
+  const notes: string[] = []
+  // An Agent runs only a workflow's live version, and local dev pushes drafts: on this
+  // one-person runtime, a workflow an Agent may start is promoted so the binding holds.
+  const promote = async (slug: string): Promise<boolean> => {
+    const n = await promoteWorkflow(serviceUrl, creds, slug)
+    if (n) notes.push(`  warning: promoted workflow ${slug} v${n} so ${target.slug} can start it`)
+    return n !== null
+  }
+  const failures: string[] = []
+  const settings = (row: Record<string, unknown>, keys: string[]) => Object.fromEntries(keys.filter((k) => row[k] !== undefined).map((k) => [k, row[k]]))
+  for (const row of doc.functions ?? []) {
+    const ref = typeof row.function === 'string' ? parseRef(row.function) : null
+    if (!ref || ref.kind !== 'function') continue
+    const failed = await put(`/v1/functions/${encodeURIComponent(ref.name)}/bindings/${encodeURIComponent(target.slug)}`, settings(row, ['enabled', 'requiresApproval', 'waitSeconds']))
+    if (failed) failures.push(`  ${row.function}: ${failed}`)
+  }
+  for (const row of doc.workflows ?? []) {
+    const ref = typeof row.workflow === 'string' ? parseRef(row.workflow) : null
+    if (!ref || ref.kind !== 'workflow') continue
+    const path = `/v1/workflows/${encodeURIComponent(ref.name)}/bindings/${encodeURIComponent(target.slug)}`
+    const body = settings(row, ['enabled', 'access', 'requiresApproval', 'waitSeconds'])
+    let failed = await put(path, body)
+    if (failed && /no live version/i.test(failed) && (await promote(ref.name))) failed = await put(path, body)
+    if (failed) failures.push(`  ${row.workflow}: ${failed}`)
+  }
+  // Context and data: the object types it may read, granted with the organization key.
+  // One the pull could not read is assumed as read on every object type the project
+  // holds and the runtime keeps (an adaptation the build names, from the file).
+  const unread = !Array.isArray(doc.blueprint) && (doc as { blueprintUnread?: unknown }).blueprintUnread === true
+  if (Array.isArray(doc.blueprint) || unread) {
+    const types = projectObjectTypes(project.root)
+    const keptHere = [...types].filter(([, type]) => !objectTypeFit(type, () => true).leftOff).map(([apiName]) => apiName).sort()
+    const granted = await applyAgentGrants({
+      slug: target.slug,
+      grants: unread ? keptHere.map((apiName) => ({ objectType: `objectType/${apiName}`, permissions: ['read'] })) : (doc.blueprint as AgentGrant[]),
+      serviceUrl,
+      creds,
+      leftOff: (apiName) => {
+        const type = types.get(apiName)
+        return type && objectTypeFit(type, () => true).leftOff ? 'it reads the platform’s media files' : null
+      },
+      inProject: (apiName) => types.has(apiName),
+    })
+    failures.push(...granted.failures)
+    notes.push(...granted.notes)
+  }
+  return failures.length ? { ok: false, output: [`error [BINDING_FAILED]: ${target.slug} could not be given every tool`, ...failures, ...notes].join('\n') } : { ok: true, output: notes.join('\n') }
+}