@frontera-sdk/cli 1.52.39 → 1.52.41

package/src/local/local-orphans.ts

@@ -0,0 +1,321 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { writeFileAtomic } from '../fs-atomic'
+import { loadHashes } from './local-applied'
+import { allTargets } from './local-dev-sync'
+import { functionSlugOf } from './local-function-state'
+import type { LocalProject } from './local-project'
+import type { LocalCredentials } from './local-state'
+
+/**
+ * What the local runtime holds that the project's files don't (e2e G3).
+ *
+ * `local dev` applies files; until now nothing happened when one was
+ * deleted: an Agent whose folder was removed stayed on the runtime, `status`
+ * never named it, and only `local reset` (every row gone) took it away.
+ *
+ * An Agent, workflow, Function or knowledge base on the runtime with no file
+ * in the project is an **orphan**. `status` lists each with its fix. One the
+ * project applied before (its key is in the applied record) had its file
+ * deleted, and `local dev` takes it out of service the safest way the runtime
+ * offers, reversibly, and puts it back when the file returns:
+ *
+ *   Agent           archived (the platform's delete is an archive: its versions
+ *                   and conversations stay) — restored when its folder returns
+ *   workflow        archived (versions and runs stay) — restored before its next push
+ *   Function        switched off: the runtime has no way to remove a Function —
+ *                   switched on again when its file is deployed again
+ *   knowledge base  left as it is: deleting one takes its documents with it and
+ *                   cannot be undone, so `status` only says it
+ *
+ * An orphan the project never had (made in Studio, say) is only said: it may
+ * be work someone means to pull into the files. A Function switched off with
+ * no file is not one: it doesn't run, and there is nothing left to do.
+ */
+
+export type OrphanKind = 'agent' | 'workflow' | 'function' | 'knowledge'
+
+export interface Orphan {
+  /** `agent/assistant`, `workflow/hello`, `function/word-count`, `knowledge/Field desk policies`. */
+  ref: string
+  kind: OrphanKind
+  name: string
+  /** The runtime's id, where the kind is addressed by one (an Agent, a knowledge base). */
+  id?: string
+  /** The project applied it from a file that is gone: `local dev` takes it out of service. */
+  deleted: boolean
+  /** What is wrong, in a sentence. */
+  problem: string
+  /** What fixes it. */
+  fix: string
+}
+
+/** What the runtime holds of the kinds files make, by name; a kind the runtime didn't list is absent. */
+export interface RuntimeItems {
+  agents?: Array<{ id: string; slug: string }>
+  workflows?: Array<{ slug: string }>
+  functions?: Array<{ slug: string; enabled: boolean | null }>
+  knowledge?: Array<{ id: string; name: string }>
+}
+
+function rowsOf<T>(body: unknown): T[] {
+  let v = body
+  for (let i = 0; i < 3 && v && !Array.isArray(v) && typeof v === 'object' && 'data' in (v as object); i++) v = (v as { data: unknown }).data
+  if (v && !Array.isArray(v) && typeof v === 'object' && Array.isArray((v as { items?: unknown }).items)) v = (v as { items: unknown[] }).items
+  return Array.isArray(v) ? (v as T[]) : []
+}
+
+type Call = (path: string, init?: { method?: string; body?: unknown }) => Promise<{ ok: boolean; status: number; body: unknown }>
+
+/** Calls to the runtime with the workspace key; null without one. */
+export function orphanCalls(serviceUrl: string, creds: Pick<LocalCredentials, 'workspaceKey'>): Call | null {
+  if (!creds.workspaceKey) return null
+  return async (path, init = {}) => {
+    try {
+      const res = await fetch(new URL(path, serviceUrl), {
+        method: init.method ?? 'GET',
+        headers: { authorization: `Bearer ${creds.workspaceKey}`, 'content-type': 'application/json' },
+        body: init.body === undefined ? undefined : JSON.stringify(init.body),
+        signal: AbortSignal.timeout(10_000),
+      })
+      const text = await res.text()
+      let body: unknown = text
+      try {
+        body = text ? JSON.parse(text) : null
+      } catch {
+        // Not JSON: the text is the body.
+      }
+      return { ok: res.ok, status: res.status, body }
+    } catch (err) {
+      return { ok: false, status: 0, body: (err as Error).message }
+    }
+  }
+}
+
+/** The Agents, workflows, Functions and knowledge bases on the runtime; each kind that didn't answer is left out. */
+export async function runtimeItems(call: Call, workspaceId: string): Promise<RuntimeItems> {
+  const [agents, workflows, functions, knowledge] = await Promise.all([
+    // The sync listing: drafts never published included, archived and platform Agents left out.
+    call('/v1/sync/agents'),
+    // Archived workflows are left out of the listing.
+    call('/v1/workflows'),
+    call('/v1/functions'),
+    call(`/v1/workspace-knowledge?workspaceId=${encodeURIComponent(workspaceId)}`),
+  ])
+  const out: RuntimeItems = {}
+  if (agents.ok) {
+    out.agents = rowsOf<{ id?: string; agentId?: string; lifecycleStatus?: string }>(agents.body)
+      // A preview clone is the runtime's machinery for a draft chat, never an Agent of the project's.
+      .filter((a) => a.id && a.agentId && !a.agentId.startsWith('preview_') && a.lifecycleStatus !== 'archived')
+      .map((a) => ({ id: a.id!, slug: a.agentId! }))
+  }
+  if (workflows.ok) out.workflows = rowsOf<{ slug?: string; archivedAt?: string | null }>(workflows.body).filter((w) => w.slug && !w.archivedAt).map((w) => ({ slug: w.slug! }))
+  if (functions.ok) out.functions = rowsOf<{ slug?: string; enabled?: boolean | null }>(functions.body).filter((f) => f.slug).map((f) => ({ slug: f.slug!, enabled: f.enabled ?? null }))
+  if (knowledge.ok) out.knowledge = rowsOf<{ id?: string; name?: string }>(knowledge.body).filter((k) => k.id && k.name).map((k) => ({ id: k.id!, name: k.name! }))
+  return out
+}
+
+/** The names the project's files give each kind: an Agent's folder, a workflow's file, a Function's file or folder, a knowledge base's `name`. */
+export function projectNames(root: string): Record<OrphanKind, Set<string>> {
+  const out: Record<OrphanKind, Set<string>> = { agent: new Set(), workflow: new Set(), function: new Set(), knowledge: new Set() }
+  for (const t of allTargets(root)) {
+    if (t.kind === 'agent') out.agent.add(t.slug)
+    else if (t.kind === 'workflow') out.workflow.add(t.slug)
+    else if (t.kind === 'function') {
+      const slug = functionSlugOf(t.key)
+      if (slug) out.function.add(slug)
+    } else if (t.kind === 'knowledge') {
+      out.knowledge.add(t.name)
+      try {
+        const name = (JSON.parse(readFileSync(join(root, t.file), 'utf8')) as { name?: unknown }).name
+        if (typeof name === 'string' && name) out.knowledge.add(name)
+      } catch {
+        // Unreadable: its folder's name is the one it goes by.
+      }
+    }
+  }
+  return out
+}
+
+/** The applied-record keys a deleted item's files went by, of a kind and name. */
+export function appliedKeysOf(kind: OrphanKind, name: string): string[] {
+  if (kind === 'agent') return [`agent:${name}`, `operating:${name}`, `bindings:${name}`, `lessons:${name}`]
+  if (kind === 'workflow') return [`workflow:${name}`]
+  if (kind === 'function') return [`function:${name}.ts`, `function:${name}/`]
+  return []
+}
+
+/** Whether the project applied this item from a file before: a key its file went by is in the applied record. */
+function wasApplied(kind: OrphanKind, name: string, applied: ReadonlySet<string>): boolean {
+  // An Agent is its agent.json: behavior settings or tools alone never made one.
+  if (kind === 'agent') return applied.has(`agent:${name}`)
+  return appliedKeysOf(kind, name).some((k) => applied.has(k))
+}
+
+const WORDS: Record<OrphanKind, string> = { agent: 'Agent', workflow: 'workflow', function: 'Function', knowledge: 'knowledge base' }
+
+/** The file an item of a kind would have in the project. */
+function fileOf(kind: OrphanKind, name: string): string {
+  if (kind === 'agent') return `agents/${name}/agent.json`
+  if (kind === 'workflow') return `workflows/${name}.yaml`
+  if (kind === 'function') return `functions/${name}.ts`
+  return 'knowledge/<folder>/knowledge.json'
+}
+
+/**
+ * Each item on the runtime with no file in the project, with its fix.
+ * `applied`: the keys of the files the project applied (`applied-hashes.json`).
+ */
+export function findOrphans(root: string, items: RuntimeItems, applied: ReadonlySet<string>): Orphan[] {
+  const names = projectNames(root)
+  const out: Orphan[] = []
+  const add = (kind: OrphanKind, name: string, id?: string) => {
+    if (names[kind].has(name)) return
+    const deleted = kind !== 'knowledge' && wasApplied(kind, name, applied)
+    const what = `${WORDS[kind]} ${name}`
+    const base = deleted ? `${what} is on the local runtime, but its file is gone from the project` : `${what} is on the local runtime, but the project has no ${fileOf(kind, name)}`
+    const problem = base
+    let fix: string
+    if (kind === 'agent') fix = deleted ? '`frontera local dev` archives it (or `frontera agent archive ' + name + '` now)' : `add its folder to the project, or \`frontera agent archive ${name}\` if it isn’t wanted`
+    else if (kind === 'workflow') fix = deleted ? '`frontera local dev` archives it (or `frontera workflow archive ' + name + '` now)' : `add its file to the project, or \`frontera workflow archive ${name}\` if it isn’t wanted`
+    else if (kind === 'function') {
+      fix = deleted
+        ? `\`frontera local dev\` switches it off (the runtime can’t remove a Function), or \`frontera function disable ${name}\` now`
+        : `add its file to the project, or \`frontera function disable ${name}\` to switch it off (the runtime can’t remove a Function)`
+    } else fix = 'add its folder to the project, or delete it from its page in Studio if it isn’t wanted: deleting a knowledge base takes its documents with it, so `frontera local dev` never does'
+    out.push({ ref: `${kind}/${name}`, kind, name, ...(id ? { id } : {}), deleted, problem, fix })
+  }
+  for (const a of items.agents ?? []) add('agent', a.slug, a.id)
+  for (const w of items.workflows ?? []) add('workflow', w.slug)
+  // A Function switched off and with no file: it doesn't run, and the runtime can't remove it, so there is nothing to fix.
+  for (const f of items.functions ?? []) if (f.enabled !== false) add('function', f.slug)
+  for (const k of items.knowledge ?? []) add('knowledge', k.name, k.id)
+  return out
+}
+
+/** The orphans of a running runtime, as `status` lists them; null when it didn't answer. */
+export async function projectOrphans(project: LocalProject, serviceUrl: string, creds: LocalCredentials): Promise<Orphan[] | null> {
+  const call = orphanCalls(serviceUrl, creds)
+  if (!call) return null
+  const items = await runtimeItems(call, creds.workspaceId)
+  if (!Object.keys(items).length) return null
+  return findOrphans(project.root, items, new Set(loadHashes(project, creds.organizationId).keys()))
+}
+
+/** An orphan as `status` says it: the problem, then the fix. */
+export function orphanLine(o: Orphan): string {
+  return `${o.problem}: ${o.fix}`
+}
+
+// ── What `local dev` took out of service, so a returning file puts it back ──
+
+interface RetiredFile {
+  organizationId: string
+  /** By `kind/name`: when it was taken out, and how. */
+  items: Record<string, { how: 'archived' | 'switched-off'; id?: string; at: string }>
+}
+
+const retiredPath = (project: Pick<LocalProject, 'stateDir'>) => join(project.stateDir, 'retired.json')
+
+export function readRetired(project: Pick<LocalProject, 'stateDir'>, organizationId: string): RetiredFile['items'] {
+  try {
+    const saved = JSON.parse(readFileSync(retiredPath(project), 'utf8')) as Partial<RetiredFile>
+    if (saved.organizationId === organizationId && saved.items) return saved.items
+  } catch {
+    // None yet.
+  }
+  return {}
+}
+
+function writeRetired(project: Pick<LocalProject, 'stateDir'>, organizationId: string, items: RetiredFile['items']): void {
+  try {
+    if (!Object.keys(items).length && !existsSync(retiredPath(project))) return
+    writeFileAtomic(retiredPath(project), `${JSON.stringify({ organizationId, items }, null, 2)}\n`, 0o644)
+  } catch {
+    // Losing it only means a returning Function is not switched on by itself.
+  }
+}
+
+/**
+ * Take each orphan whose file was deleted out of service (see the top of the
+ * file). Returns the lines to say and the applied-record keys to forget, so
+ * the file, when it comes back, is applied again even unchanged.
+ */
+export async function retireDeleted(project: Pick<LocalProject, 'stateDir'>, organizationId: string, call: Call, orphans: readonly Orphan[]): Promise<{ lines: string[]; forget: string[] }> {
+  const lines: string[] = []
+  const forget: string[] = []
+  const retired = { ...readRetired(project, organizationId) }
+  const at = new Date().toISOString()
+  const said = (res: { status: number; body: unknown }) => `${res.status || 'no answer'} ${typeof res.body === 'string' ? res.body.slice(0, 160) : JSON.stringify(res.body).slice(0, 160)}`
+  for (const o of orphans) {
+    if (!o.deleted) continue
+    if (o.kind === 'agent' && o.id) {
+      const res = await call(`/v1/config/agents/${encodeURIComponent(o.id)}`, { method: 'DELETE' })
+      if (!res.ok) {
+        lines.push(`  warning: Agent ${o.name}’s folder is gone, but it couldn’t be archived here: ${said(res)}; \`frontera agent archive ${o.name}\` archives it`)
+        continue
+      }
+      retired[o.ref] = { how: 'archived', id: o.id, at }
+      lines.push(`  archived Agent ${o.name}: its folder is gone from the project (its versions and conversations are kept; it is restored if agents/${o.name}/ comes back)`)
+    } else if (o.kind === 'workflow') {
+      const res = await call(`/v1/workflows/${encodeURIComponent(o.name)}/archive`, { method: 'POST' })
+      if (!res.ok) {
+        lines.push(`  warning: workflow ${o.name}’s file is gone, but it couldn’t be archived here: ${said(res)}; \`frontera workflow archive ${o.name}\` archives it`)
+        continue
+      }
+      retired[o.ref] = { how: 'archived', at }
+      lines.push(`  archived workflow ${o.name}: its file is gone from the project (its versions and runs are kept; it is restored if the file comes back)`)
+    } else if (o.kind === 'function') {
+      const res = await call(`/v1/functions/${encodeURIComponent(o.name)}/enabled`, { method: 'POST', body: { enabled: false } })
+      if (!res.ok) {
+        lines.push(`  warning: Function ${o.name}’s file is gone, but it couldn’t be switched off here: ${said(res)}; \`frontera function disable ${o.name}\` switches it off`)
+        continue
+      }
+      retired[o.ref] = { how: 'switched-off', at }
+      lines.push(`  switched off Function ${o.name}: its file is gone from the project, and the runtime can’t remove a Function (it is switched on again if the file comes back)`)
+    } else continue
+    forget.push(...appliedKeysOf(o.kind, o.name))
+  }
+  writeRetired(project, organizationId, retired)
+  return { lines, forget }
+}
+
+/**
+ * Before an Agent's or workflow's file is applied: one `local dev` archived
+ * (its file was deleted, and is back), or archived by hand, is restored, so
+ * the file reaches a working item. Returns the line to say, or null.
+ */
+export async function restoreIfArchived(project: Pick<LocalProject, 'stateDir'>, organizationId: string, call: Call, kind: 'agent' | 'workflow', name: string): Promise<string | null> {
+  const retired = readRetired(project, organizationId)
+  const ref = `${kind}/${name}`
+  let line: string | null = null
+  if (kind === 'agent') {
+    const row = await call(`/v1/config/agents/${encodeURIComponent(name)}`)
+    const agent = (row.ok ? ((row.body as { data?: unknown })?.data ?? row.body) : null) as { id?: string; lifecycleStatus?: string } | null
+    if (agent?.id && agent.lifecycleStatus === 'archived') {
+      const res = await call(`/v1/config/agents/${encodeURIComponent(agent.id)}/restore`, { method: 'POST', body: {} })
+      line = res.ok ? `  note: restored Agent ${name}: it was archived here, and its folder is in the project` : `  warning: Agent ${name} is archived here and couldn’t be restored (${res.status}): \`frontera agent restore ${name}\``
+    }
+  } else if (retired[ref]) {
+    const res = await call(`/v1/workflows/${encodeURIComponent(name)}/restore`, { method: 'POST' })
+    line = res.ok ? `  note: restored workflow ${name}: it was archived here when its file was deleted, and the file is back` : null
+  }
+  if (retired[ref]) {
+    const { [ref]: _gone, ...rest } = retired
+    writeRetired(project, organizationId, rest)
+  }
+  return line
+}
+
+/** After a Function's file is deployed again: one `local dev` switched off when its file was deleted is switched on. */
+export async function reviveFunction(project: Pick<LocalProject, 'stateDir'>, organizationId: string, call: Call, slug: string): Promise<string | null> {
+  const retired = readRetired(project, organizationId)
+  const ref = `function/${slug}`
+  if (retired[ref]?.how !== 'switched-off') return null
+  const res = await call(`/v1/functions/${encodeURIComponent(slug)}/enabled`, { method: 'POST', body: { enabled: true } })
+  if (!res.ok) return `  warning: Function ${slug} was switched off here when its file was deleted, and couldn’t be switched on again (${res.status}): \`frontera function enable ${slug}\``
+  const { [ref]: _gone, ...rest } = retired
+  writeRetired(project, organizationId, rest)
+  return `  note: switched on Function ${slug}: it was switched off here when its file was deleted, and the file is back`
+}

package/src/local/local-personas.ts

@@ -0,0 +1,296 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { parse as parseYaml } from 'yaml'
+
+import { CliError, UsageError } from '../errors'
+import { isIgnoredName } from './local-dev-sync'
+import { localRuntimeAt } from './local-runtime-target'
+import type { LocalCredentials } from './local-state'
+
+/**
+ * Local personas: seeded people on the LOCAL runtime only, so an agent can
+ * walk a governed Action's approval chain end to end without a person's
+ * session (the service's `/v1/local/personas`, which answers 404 anywhere
+ * else and takes only the runtime's organization key).
+ *
+ * `local dev` seeds one persona per approval step the project's Action files
+ * name, keyed by the step (`dispatch_lead`), plus a `submitter`: the
+ * approver may not be the submitter, and a chain needs one person per step.
+ * The submitter is an `owner` (an Action grants its invoke capability to
+ * owners only); approvers are `admin`s. `frontera action available|submit|approve|reject --as
+ * <persona>` then runs as that persona. The session it uses is minted for the
+ * one command, sent only to the local runtime, and never printed or logged.
+ */
+
+/** The persona that raises requests, apart from every approver. */
+export const SUBMITTER = 'submitter'
+
+/** The commands `--as` works on. */
+export const ACT_AS_COMMANDS = ['action available', 'action submit', 'action approve', 'action reject'] as const
+
+const KEY = /^[a-z][a-z0-9_-]{0,62}$/
+/** The most personas one seed takes (the route's limit). */
+const MAX_PERSONAS = 20
+
+/** A persona key from what a person types or a step is named: `Dispatch lead` → `dispatch_lead`. */
+export function personaKey(name: string): string {
+  const key = name.trim().toLowerCase().replace(/[^a-z0-9_-]+/g, '_').replace(/^[^a-z]+/, '').replace(/_+$/, '').slice(0, 63)
+  return KEY.test(key) ? key : ''
+}
+
+export interface PersonaSpec {
+  key: string
+  displayName: string
+  /**
+   * The organization role it holds: `owner` for the submitter (an Action
+   * grants its invoke capability to owners only), `admin` for an approver.
+   */
+  orgRole: 'owner' | 'admin'
+  /** What the persona is for, in words: "decides step dispatch_lead of escalateWorkOrder". */
+  decides: string[]
+}
+
+export interface PersonaPlan {
+  personas: PersonaSpec[]
+  /** What could not be seeded, one line each (a step decided by an App role). */
+  notes: string[]
+}
+
+const words = (key: string) => {
+  const w = key.replace(/[_-]+/g, ' ').trim()
+  return w.charAt(0).toUpperCase() + w.slice(1)
+}
+
+type Doc = Record<string, unknown>
+const isRecord = (v: unknown): v is Doc => !!v && typeof v === 'object' && !Array.isArray(v)
+
+/** The project's Action files' documents, parsed; unreadable ones are left out. */
+function actionDocs(root: string): Array<{ file: string; doc: Doc }> {
+  const dir = join(root, 'blueprint', 'actions')
+  if (!existsSync(dir)) return []
+  return readdirSync(dir).sort().flatMap((name) => {
+    if (isIgnoredName(name) || !/\.(ya?ml|json)$/.test(name)) return []
+    try {
+      const doc = parseYaml(readFileSync(join(dir, name), 'utf8'))
+      return isRecord(doc) ? [{ file: join('blueprint', 'actions', name), doc }] : []
+    } catch {
+      return []
+    }
+  })
+}
+
+/**
+ * The personas the project's Actions need: one per approval step (a chain's
+ * stage key; `approver` for an Action approved in one step), and a submitter
+ * when any Action asks for approval. A step decided by an App role is said,
+ * not seeded: a persona holds an organization role, not an App's.
+ */
+export function personaPlan(root: string): PersonaPlan {
+  const byKey = new Map<string, PersonaSpec>()
+  const notes: string[] = []
+  const add = (key: string, decides: string) => {
+    const at = byKey.get(key) ?? { key, displayName: words(key), orgRole: key === SUBMITTER ? ('owner' as const) : ('admin' as const), decides: [] }
+    at.decides.push(decides)
+    byKey.set(key, at)
+  }
+  for (const { file, doc } of actionDocs(root)) {
+    const apiName = typeof doc.apiName === 'string' ? doc.apiName : file
+    const approval = (isRecord(doc.governance) ? doc.governance.approval : undefined) ?? doc.approval
+    if (!isRecord(approval) || approval.mode === undefined || approval.mode === 'none') continue
+    if (approval.mode === 'chain' && Array.isArray(approval.stages)) {
+      for (const stage of approval.stages.filter(isRecord)) {
+        const raw = typeof stage.key === 'string' ? stage.key : ''
+        const key = personaKey(raw)
+        if (!key || key === SUBMITTER) {
+          notes.push(`${file}: step "${raw}" has no key a persona can take (a lowercase letter, then letters, digits, "_" or "-")`)
+          continue
+        }
+        if (isRecord(stage.approver) && typeof stage.approver.role === 'string') {
+          notes.push(`${file}: step ${raw} is decided by the App-user role ${stage.approver.role}, which local personas don't cover; decide it as an App user in the App`)
+          continue
+        }
+        add(key, `step ${raw} of ${apiName}`)
+      }
+    } else {
+      add('approver', `approval of ${apiName}`)
+    }
+    add(SUBMITTER, `requests for ${apiName}`)
+  }
+  // The submitter first, then the approvers as their steps come.
+  const personas = [...byKey.values()].sort((a, b) => Number(b.key === SUBMITTER) - Number(a.key === SUBMITTER))
+  if (personas.length > MAX_PERSONAS) notes.push(`${personas.length - MAX_PERSONAS} more approval steps than the ${MAX_PERSONAS} personas a runtime seeds at once: the rest were left out`)
+  return { personas: personas.slice(0, MAX_PERSONAS), notes }
+}
+
+export interface LocalPersona {
+  key: string
+  displayName: string
+  orgRole?: string
+}
+
+type Fetch = typeof fetch
+
+/** Calls to `/v1/local/personas` with the runtime's organization key. */
+function personaCall(serviceUrl: string, creds: LocalCredentials, fetcher: Fetch) {
+  return async (method: string, path: string, body?: unknown): Promise<{ status: number; body: unknown }> => {
+    const res = await fetcher(new URL(`/v1/local/personas${path}`, serviceUrl), {
+      method,
+      headers: {
+        authorization: `Bearer ${creds.orgKey}`,
+        '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 = text ? JSON.parse(text) : null
+    } catch {
+      // Keep the text.
+    }
+    return { status: res.status, body: parsed }
+  }
+}
+
+const inner = (body: unknown): unknown => (isRecord(body) && 'data' in body ? body.data : body)
+
+function personasOf(body: unknown): LocalPersona[] {
+  const data = inner(body)
+  const rows = Array.isArray(data) ? data : isRecord(data) && Array.isArray(data.personas) ? data.personas : []
+  return rows.filter(isRecord).flatMap((p) => (typeof p.key === 'string' ? [{ key: p.key, displayName: typeof p.displayName === 'string' ? p.displayName : words(p.key), ...(typeof p.orgRole === 'string' ? { orgRole: p.orgRole } : {}) }] : []))
+}
+
+const messageOf = (answer: { status: number; body: unknown }) => {
+  const m = isRecord(answer.body) && typeof answer.body.message === 'string' ? answer.body.message : typeof answer.body === 'string' ? answer.body : ''
+  return `${answer.status}${m ? ` ${m.replace(/\s+/g, ' ').slice(0, 200)}` : ''}`
+}
+
+/** The personas on the runtime; null when it has none to list (it predates them) or did not answer. */
+export async function listPersonas(serviceUrl: string, creds: LocalCredentials, fetcher: Fetch = fetch): Promise<LocalPersona[] | null> {
+  try {
+    const answer = await personaCall(serviceUrl, creds, fetcher)('GET', '/')
+    return answer.status < 300 ? personasOf(answer.body) : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Seed the project's personas on the runtime (idempotent). Lines for the
+ * apply's output: what was seeded, or why not; never a failure of the build.
+ */
+export async function seedPersonas(root: string, serviceUrl: string, creds: LocalCredentials, fetcher: Fetch = fetch): Promise<string[]> {
+  const plan = personaPlan(root)
+  const lines = plan.notes.map((n) => `  note: ${n}`)
+  if (!plan.personas.length) return lines
+  let answer: { status: number; body: unknown }
+  try {
+    answer = await personaCall(serviceUrl, creds, fetcher)('POST', '/', { personas: plan.personas.map((p) => ({ key: p.key, displayName: p.displayName, orgRole: p.orgRole })) })
+  } catch (err) {
+    return [...lines, `  note: local personas could not be seeded: ${(err as Error).message}`]
+  }
+  if (answer.status === 404) return [...lines, '  note: this runtime has no local personas (its platform predates them), so approval chains can only be decided by a person here']
+  if (answer.status >= 300) return [...lines, `  note: local personas could not be seeded: ${messageOf(answer)}`]
+  const keys = plan.personas.map((p) => p.key)
+  const approver = keys.find((k) => k !== SUBMITTER)
+  return [...lines, `  local personas ${keys.join(', ')}: act as one with \`--as\`${approver ? ` (\`frontera action approve <requestId> --as ${approver}\`)` : ''}`]
+}
+
+export interface PersonaSession {
+  /** The persona's session: sent only as this command's bearer, never printed. */
+  token: string
+  persona: LocalPersona
+  organizationId: string
+  workspaceId: string
+}
+
+/**
+ * The session `--as <persona>` runs a command with: refused for any other
+ * command, and anywhere but the project's own local runtime (never a hosted
+ * deployment, whatever the credential). `wanted` is a persona key or the
+ * approval step it was seeded for.
+ */
+export async function actAsLocalPersona(opts: {
+  meta: { noun: string; verb: string }
+  cwd: string
+  apiUrl: string
+  wanted: string
+  fetcher?: Fetch
+}): Promise<PersonaSession> {
+  const label = `${opts.meta.noun} ${opts.meta.verb}`
+  if (!(ACT_AS_COMMANDS as readonly string[]).includes(label)) {
+    throw new UsageError(`--as does nothing on \`${label}\``, `--as acts as a local persona on ${ACT_AS_COMMANDS.map((c) => `\`${c}\``).join(', ')}`)
+  }
+  const local = localRuntimeAt(opts.cwd, opts.apiUrl)
+  if (!local) {
+    throw new CliError(`--as acts as a local persona, and ${opts.apiUrl} is not this project's local runtime`, {
+      code: 'LOCAL_ONLY',
+      hint: 'personas exist only on a local runtime: run the command in its project folder while it runs (`frontera local status`); on a deployment, a person signs in (`frontera login`)',
+    })
+  }
+  const key = personaKey(opts.wanted)
+  if (!key) throw new UsageError(`"${opts.wanted}" names no persona`, 'pass a persona key or approval step, as `frontera local status` lists them')
+  const call = personaCall(local.serviceUrl, local.creds, opts.fetcher ?? fetch)
+  const answer = await call('POST', `/${encodeURIComponent(key)}/session`)
+  if (answer.status === 404) {
+    const known = await listPersonas(local.serviceUrl, local.creds, opts.fetcher ?? fetch)
+    throw new CliError(known ? `no local persona is named ${key}` : 'this runtime has no local personas', {
+      code: 'PERSONA_NOT_FOUND',
+      hint: known
+        ? `${known.length ? `the personas here are ${known.map((p) => p.key).join(', ')}; ` : ''}\`frontera local dev\` seeds one per approval step in blueprint/actions/, plus ${SUBMITTER}`
+        : 'its platform predates them: start the runtime from a release that has them (`frontera local start`)',
+    })
+  }
+  const data = inner(answer.body)
+  const token = isRecord(data) && typeof data.token === 'string' ? data.token : ''
+  if (answer.status >= 300 || !token) throw new CliError(`a session for persona ${key} could not be started`, { code: 'PERSONA_SESSION_FAILED', hint: messageOf({ status: answer.status, body: isRecord(answer.body) ? { message: answer.body.message } : null }) })
+  const persona = isRecord(data) && isRecord(data.persona) ? personasOf({ data: [data.persona] })[0] : undefined
+  return { token, persona: persona ?? { key, displayName: words(key) }, organizationId: local.creds.organizationId, workspaceId: local.creds.workspaceId }
+}
+
+/** `value` with every occurrence of `secret` replaced: what an error says after a persona's session ran. */
+export function redact<T>(value: T, secret: string, seen = new WeakSet<object>()): T {
+  if (!secret) return value
+  if (typeof value === 'string') return value.split(secret).join('[persona session]') as T
+  if (!value || typeof value !== 'object' || seen.has(value as object)) return value
+  seen.add(value as object)
+  if (Array.isArray(value)) {
+    value.forEach((v, i) => ((value as unknown[])[i] = redact(v, secret, seen)))
+    return value
+  }
+  for (const k of Object.getOwnPropertyNames(value)) {
+    try {
+      const v = (value as Record<string, unknown>)[k]
+      if (typeof v === 'string' || (v && typeof v === 'object')) (value as Record<string, unknown>)[k] = redact(v, secret, seen)
+    } catch {
+      // A read-only property keeps its value.
+    }
+  }
+  return value
+}
+
+/**
+ * What a key refused on a command that acts as a person is told on the
+ * project's own local runtime, instead of the deployment's "set FRONTERA_TOKEN
+ * to your session token": a local runtime has personas, and an agent is never
+ * sent to fetch a person's session. On a command `--as` works on it names the
+ * persona to act as (the submitter to see or raise requests, an approver to
+ * decide one) and the personas the runtime has (`personas`, null when they
+ * could not be read); on any other it says `--as` does not reach it.
+ */
+export function localPersonaHint(meta: { noun: string; verb: string }, personas: readonly LocalPersona[] | null): string {
+  const label = `${meta.noun} ${meta.verb}`
+  const approvers = (personas ?? []).filter((p) => p.key !== SUBMITTER).map((p) => p.key)
+  const approver = approvers[0] ?? 'approver'
+  const listed = personas?.length ? `the personas here are ${personas.map((p) => p.key).join(', ')}` : '`frontera local status` lists the personas (Personas)'
+  const never = 'never a person’s session token'
+  if (!(ACT_AS_COMMANDS as readonly string[]).includes(label)) {
+    return `on this local runtime no person signs in, and \`--as <persona>\` acts as a local persona only on ${ACT_AS_COMMANDS.map((c) => `\`${c}\``).join(', ')}; \`${label}\` runs against a deployment, where a person signs in (${never} here)`
+  }
+  const deciding = meta.verb === 'approve' || meta.verb === 'reject'
+  const example = deciding ? `frontera ${label} <requestId> --as ${approver}` : `frontera ${label}${meta.verb === 'submit' ? ' <apiName>' : ''} --as ${SUBMITTER}`
+  return `on this local runtime, act as a local persona: \`--as ${SUBMITTER}\` sees and raises requests, \`--as ${approver}\` approves or rejects them (\`${example}\`); ${listed}: ${never}`
+}