@frontera-sdk/cli 1.52.45 → 1.52.46

package/src/local/local-new.ts

@@ -0,0 +1,148 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs'
+import { dirname, join, relative, sep } from 'node:path'
+import { parseDocument } from 'yaml'
+
+import { CliError, UsageError } from '../errors'
+import { starterAgentFiles } from './local-scaffold'
+
+/**
+ * Starting and tidying project files without the web app (Forge improvement
+ * plan L8).
+ *
+ * `frontera local new agent <slug>` writes a new Agent's folder: the
+ * scaffold's starter, or with `--like <agent>` a copy of another Agent's
+ * files (its instructions, bindings, behavior settings and cases) under the
+ * new name. `frontera local fmt` writes the project's JSON and YAML files in
+ * one shape (two-space indents, a final newline, comments kept), so a diff
+ * shows what changed rather than how it was typed.
+ */
+
+const SLUG = /^[a-z][a-z0-9-]{0,62}$/
+
+export function titleOf(slug: string): string {
+  return slug.split('-').filter(Boolean).map((w) => w[0]!.toUpperCase() + w.slice(1)).join(' ')
+}
+
+function filesUnder(root: string, dir: string): string[] {
+  const out: string[] = []
+  const walk = (at: string) => {
+    for (const entry of readdirSync(at)) {
+      const full = join(at, entry)
+      if (statSync(full).isDirectory()) walk(full)
+      else out.push(relative(root, full).split(sep).join('/'))
+    }
+  }
+  if (existsSync(join(root, dir))) walk(join(root, dir))
+  return out.sort()
+}
+
+export interface NewAgentOptions {
+  like?: string
+  name?: string
+  description?: string
+  model?: string
+  customer?: boolean
+}
+
+/** The new Agent's files by project path; nothing is written. */
+export function newAgentFiles(root: string, slug: string, opts: NewAgentOptions = {}): Record<string, string> {
+  if (!SLUG.test(slug)) throw new UsageError(`"${slug}" is not an Agent slug`, 'lower-case letters, digits and hyphens, starting with a letter: `support-concierge`')
+  if (existsSync(join(root, 'agents', slug))) throw new CliError(`agents/${slug}/ is already there`, { code: 'USAGE', hint: 'choose another slug, or edit that Agent' })
+  const name = opts.name ?? titleOf(slug)
+  if (!opts.like) return starterAgentFiles(slug, { name, ...(opts.description ? { description: opts.description } : {}), ...(opts.model ? { model: opts.model } : {}), ...(opts.customer ? { customer: true } : {}) })
+
+  const from = `agents/${opts.like}`
+  const files = filesUnder(root, from)
+  if (!files.includes(`${from}/agent.json`)) throw new CliError(`there is no Agent at ${from}/ to start from`, { code: 'USAGE', hint: '`frontera local status` lists the project\'s Agents' })
+  if (opts.customer) throw new UsageError('--customer and --like together', 'the copy keeps the other Agent\'s behavior settings as they are; leave --customer out')
+  const out: Record<string, string> = {}
+  for (const rel of files) out[`agents/${slug}/${rel.slice(from.length + 1)}`] = readFileSync(join(root, rel), 'utf8')
+  // Its own name and description; the model only when one is given.
+  const agentPath = `agents/${slug}/agent.json`
+  let doc: { config?: Record<string, unknown>; modelConfigs?: Array<Record<string, unknown>> }
+  try {
+    doc = JSON.parse(out[agentPath]!) as typeof doc
+  } catch (err) {
+    throw new CliError(`${from}/agent.json could not be read: ${(err as Error).message}`, { code: 'USAGE', hint: 'fix that file, or start from the scaffold without --like' })
+  }
+  doc.config = { ...(doc.config ?? {}), name, description: opts.description ?? (doc.config?.description as string | null | undefined) ?? null }
+  if (opts.model) {
+    doc.modelConfigs = [{ modeKey: 'default', modelSlug: opts.model, displayName: 'Default', sortOrder: 0 }]
+    doc.config.defaultMode = 'default'
+  }
+  out[agentPath] = `${JSON.stringify(doc, null, 2)}\n`
+  return out
+}
+
+/** Write files that are not there; one that is would be the person's, so nothing is written then. */
+export function writeNewFiles(root: string, files: Record<string, string>): string[] {
+  const taken = Object.keys(files).filter((rel) => existsSync(join(root, rel)))
+  if (taken.length) throw new CliError(`${taken[0]} is already there`, { code: 'USAGE', hint: 'nothing was written' })
+  for (const [rel, text] of Object.entries(files)) {
+    mkdirSync(dirname(join(root, rel)), { recursive: true })
+    writeFileSync(join(root, rel), text)
+  }
+  return Object.keys(files).sort()
+}
+
+// ── fmt ─────────────────────────────────────────────────────────────────────
+
+/** The folders whose JSON and YAML are project files; an App's own code and the tool state are left alone. */
+const FORMATTED_DIRS = ['agents', 'workflows', 'blueprint', 'knowledge', 'skills', 'chat-apps', 'themes', 'datasets', 'mcp']
+const FORMATTED_ROOT_FILES = ['frontera.yaml']
+const FORMATTED = /\.(json|ya?ml)$/
+
+/** The project files `fmt` reads: under the project folders, apps/<slug>.json, and frontera.yaml. */
+export function formattableFiles(root: string): string[] {
+  const out = [...FORMATTED_DIRS.flatMap((d) => filesUnder(root, d)).filter((rel) => FORMATTED.test(rel) && !rel.split('/').includes('node_modules'))]
+  if (existsSync(join(root, 'apps'))) for (const entry of readdirSync(join(root, 'apps'))) if (entry.endsWith('.json') && statSync(join(root, 'apps', entry)).isFile()) out.push(`apps/${entry}`)
+  for (const f of FORMATTED_ROOT_FILES) if (existsSync(join(root, f))) out.push(f)
+  return out.sort()
+}
+
+/** The file in the project's shape, or an error naming where it can't be read. */
+export function formatted(rel: string, text: string): { text: string } | { error: string } {
+  if (rel.endsWith('.json')) {
+    try {
+      return { text: `${JSON.stringify(JSON.parse(text), null, 2)}\n` }
+    } catch (err) {
+      return { error: (err as Error).message }
+    }
+  }
+  const doc = parseDocument(text)
+  if (doc.errors.length) {
+    const e = doc.errors[0]!
+    return { error: `${e.linePos?.[0] ? `line ${e.linePos[0].line}, column ${e.linePos[0].col}: ` : ''}${e.message.split('\n')[0]}` }
+  }
+  // Comments and block text kept; long text never folded onto new lines.
+  const out = doc.toString({ indent: 2, lineWidth: 0, minContentWidth: 0 })
+  return { text: out.endsWith('\n') ? out : `${out}\n` }
+}
+
+export interface FmtOutcome {
+  changed: string[]
+  unchanged: number
+  failed: Array<{ path: string; error: string }>
+}
+
+/** Format the project's files; with `check`, write nothing and only say which would change. */
+export function formatProject(root: string, opts: { check?: boolean; only?: readonly string[] } = {}): FmtOutcome {
+  const all = formattableFiles(root)
+  const files = opts.only?.length ? all.filter((rel) => opts.only!.some((p) => rel === p || rel.startsWith(`${p.replace(/\/$/, '')}/`))) : all
+  const outcome: FmtOutcome = { changed: [], unchanged: 0, failed: [] }
+  for (const rel of files) {
+    const before = readFileSync(join(root, rel), 'utf8')
+    const after = formatted(rel, before)
+    if ('error' in after) {
+      outcome.failed.push({ path: rel, error: after.error })
+      continue
+    }
+    if (after.text === before) {
+      outcome.unchanged++
+      continue
+    }
+    outcome.changed.push(rel)
+    if (!opts.check) writeFileSync(join(root, rel), after.text)
+  }
+  return outcome
+}

package/src/local/local-org-settings.ts

@@ -101,7 +101,7 @@ export const KEYLESS_KNOWLEDGE_THRESHOLD = 0.99
  * embeddings (`local status`, `knowledge get` and `search`, the apply's
  * warning): the retrieval is approximate, and what gives the platform's.
  */
-export const KEYLESS_RETRIEVAL_NOTE = `retrieval here runs on approximate local embeddings (words hashed into vectors): a passage is found by the words it shares with the question, not by its meaning, and each knowledge base searches with threshold ${KEYLESS_KNOWLEDGE_THRESHOLD}, set for these vectors (its file keeps its own threshold for the workspace). A key the provider accepts for an embedding model gives the platform's retrieval: \`frontera local key-set <provider>\` (openai or openrouter; google when the workspace embeds with Gemini's model), then \`frontera local stop\` and \`frontera local start\`; the next \`frontera local dev\` sets each base's threshold for that model`
+export const KEYLESS_RETRIEVAL_NOTE = `retrieval here runs on approximate local embeddings (words hashed into vectors): a passage is found by the words it shares with the question, not by its meaning, and each knowledge base searches with threshold ${KEYLESS_KNOWLEDGE_THRESHOLD}, set for these vectors (its file keeps its own threshold for the workspace). A key the provider accepts for an embedding model gives the platform's retrieval (\`frontera local embeddings\` says which key you already have): \`frontera local key-set <provider>\` (openai or openrouter; google when the workspace embeds with Gemini's model), then \`frontera local stop\` and \`frontera local start\`; the next \`frontera local dev\` sets each base's threshold for that model`
 
 /** How a difference line says the runtime refused the workspace's model through this computer's key (`mirrorOrgSettings`). */
 const KEY_REFUSED = /; the runtime refused it through this computer’s (\S+) key/

package/src/local/local-person-steps.ts

@@ -0,0 +1,340 @@
+import { existsSync, mkdirSync, readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+import { writeFileAtomic } from '../fs-atomic'
+
+/**
+ * Person-steps (Forge improvement plan T4, N4): a step only the person may
+ * take (publishing, promoting, applying a change request, deciding for an
+ * Action, granting, setting a secret), prepared by the coding agent and run
+ * by the person, in their own terminal, with their own identity.
+ *
+ * The agent never approves its own work. Before, it could only say what was
+ * ready, so the person became its terminal: commands typed out by hand and
+ * their output pasted back, ten or more times in one delivery. Now the agent
+ * records the step (`person_step`, `frontera local steps add`): the command,
+ * why it is needed, what it changes and the credential it needs. Forge shows
+ * the steps as one delivery card, and **Run in my terminal** types the
+ * command into a shell without pressing Enter. The person reads it and
+ * presses Enter. Nothing here runs a command.
+ *
+ * Kept in `.frontera/sync/person-steps.json`, a file, so the list outlives
+ * the agent's context and a restart.
+ */
+
+export const PERSON_STEPS_FILE = join('.frontera', 'sync', 'person-steps.json')
+
+/** Who or what the step needs. */
+export const CREDENTIALS = ['workspace-key', 'organization-key', 'steward', 'admin', 'second-person', 'person'] as const
+export type Credential = (typeof CREDENTIALS)[number]
+
+/** Each credential in the person's words, as the card and the list say it. */
+export const CREDENTIAL_WORDS: Record<Credential, string> = {
+  'workspace-key': 'the project’s workspace key',
+  'organization-key': 'an organization key',
+  steward: 'a Blueprint Steward',
+  admin: 'a workspace admin',
+  'second-person': 'a second person (not whoever made the change)',
+  person: 'you, signed in (`frontera auth login --browser`)',
+}
+
+/**
+ * The read that proves a step done (N6): a read-only `frontera … --json`
+ * command, the list in its data (`in`, a property; the data itself when it
+ * is a list), the row whose fields equal `find`, and the fields that equal
+ * `expect` once the step is done.
+ */
+export interface StepCheck {
+  command: string
+  in?: string
+  find: Record<string, string | number | boolean>
+  expect: Record<string, string | number | boolean>
+}
+
+export interface PersonStep {
+  id: string
+  /** One `frontera` command, as the person runs it; null for a step done in the product. */
+  command: string | null
+  /** Why it is needed now. */
+  why: string
+  /** What it changes, in the workspace's words. */
+  changes: string
+  credential: Credential
+  /** The delivery it belongs to: steps with the same one show as one card, in order. */
+  delivery: string | null
+  status: 'pending' | 'done' | 'dismissed'
+  createdAt: string
+  doneAt?: string
+  /** Who saw it done: the person's mark, or its check. */
+  doneBy?: 'person' | 'check'
+  /** Where it came from: the coding agent, or what a change request left after Apply. */
+  source?: 'agent' | 'change-request'
+  /** A change request's own key for it (`action-deploy:qualifyLead`), so applying again updates it. */
+  key?: string
+  check?: StepCheck
+  lastCheckedAt?: string
+}
+
+interface StepsFile {
+  version: 1
+  steps: PersonStep[]
+}
+
+const MAX_STEPS = 200
+
+/**
+ * What would make a command unfit for the person to run from a card:
+ * anything but one `frontera` command on one line. A step is typed into the
+ * person's shell, so it never chains (`;`, `&&`, `|`), substitutes (`$(…)`,
+ * backticks) or redirects, and it never carries a secret: a value is piped
+ * in by the person (`… --from -`), never written into the step.
+ */
+export function commandProblem(command: string): string | null {
+  const c = command.trim()
+  if (!c) return 'the command is empty'
+  if (c.length > 500) return 'the command is longer than 500 characters'
+  if (/[\r\n]/.test(c)) return 'a step is one command on one line'
+  if (!/^frontera\s+\S/.test(c)) return 'a step is a `frontera` command'
+  if (/[;&|`<>]|\$\(/.test(c)) return 'a step is one command: no `;`, `&&`, `|`, redirects or `$(…)`'
+  if (looksSecret(c)) return 'the command carries what looks like a key, token or password; the person pipes a secret in (`--from -`), it is never written into a step'
+  return null
+}
+
+/** A key, token or password written into a command. */
+export function looksSecret(text: string): boolean {
+  return (
+    /\b(?:Bearer|Basic)\s+[A-Za-z0-9._~+/=-]{8,}/i.test(text) ||
+    /\b(?:sk|pk|rk|fk|fpk|fok|fwk|ghp|gho|xox[abpr])[-_][A-Za-z0-9_-]{12,}/.test(text) ||
+    /--(?:token|password|secret|api-key|key-value)[= ]\S+/i.test(text) ||
+    /\b[A-Fa-f0-9]{40,}\b/.test(text) ||
+    /\b[A-Za-z0-9+/]{48,}={0,2}(?![A-Za-z0-9+/=])/.test(text)
+  )
+}
+
+function filePath(root: string): string {
+  return join(root, PERSON_STEPS_FILE)
+}
+
+export function readPersonSteps(root: string): PersonStep[] {
+  const path = filePath(root)
+  if (!existsSync(path)) return []
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf8')) as Partial<StepsFile>
+    return Array.isArray(parsed.steps) ? parsed.steps.filter((s): s is PersonStep => !!s && typeof s.id === 'string' && (typeof s.command === 'string' || s.command === null)) : []
+  } catch {
+    return []
+  }
+}
+
+function writeSteps(root: string, steps: PersonStep[]): void {
+  const path = filePath(root)
+  mkdirSync(dirname(path), { recursive: true })
+  writeFileAtomic(path, `${JSON.stringify({ version: 1, steps } satisfies StepsFile, null, 2)}\n`)
+}
+
+export interface NewPersonStep {
+  command: string
+  why: string
+  changes: string
+  credential: string
+  delivery?: string | null
+  /** The read that proves it done, already checked (`checkProblem`). */
+  check?: StepCheck
+}
+
+/** Each problem with a step as given; empty when it can be recorded. */
+export function stepProblems(input: NewPersonStep): string[] {
+  const problems: string[] = []
+  const command = commandProblem(input.command)
+  if (command) problems.push(command)
+  if (!input.why?.trim()) problems.push('say why the step is needed (`why`)')
+  if (!input.changes?.trim()) problems.push('say what the step changes (`changes`)')
+  if (!(CREDENTIALS as readonly string[]).includes(input.credential)) problems.push(`the credential is one of: ${CREDENTIALS.join(', ')}`)
+  for (const [field, value] of [['why', input.why], ['changes', input.changes], ['delivery', input.delivery ?? '']] as const) {
+    if (value && looksSecret(value)) problems.push(`\`${field}\` carries what looks like a key, token or password`)
+    if (value && value.length > 1000) problems.push(`\`${field}\` is longer than 1000 characters`)
+  }
+  return problems
+}
+
+/**
+ * Record a step. The same command pending in the same delivery is the same
+ * step, updated rather than listed twice, so an agent restating its plan
+ * after a compaction doesn't double the card.
+ */
+export function addPersonStep(root: string, input: NewPersonStep, now = new Date()): { step: PersonStep; updated: boolean } {
+  const problems = stepProblems(input)
+  if (problems.length) throw new Error(problems.join('; '))
+  const steps = readPersonSteps(root)
+  const command = input.command.trim().replace(/\s+/g, ' ')
+  const delivery = input.delivery?.trim() || null
+  const same = steps.find((s) => s.status === 'pending' && s.command === command && s.delivery === delivery)
+  if (same) {
+    Object.assign(same, { why: input.why.trim(), changes: input.changes.trim(), credential: input.credential as Credential, ...(input.check ? { check: input.check } : {}) })
+    writeSteps(root, steps)
+    return { step: same, updated: true }
+  }
+  if (steps.filter((s) => s.status === 'pending').length >= MAX_STEPS) throw new Error(`${MAX_STEPS} steps are already pending; mark the done ones done first`)
+  const step: PersonStep = {
+    id: `ps_${crypto.randomUUID().replace(/-/g, '').slice(0, 10)}`,
+    command,
+    why: input.why.trim(),
+    changes: input.changes.trim(),
+    credential: input.credential as Credential,
+    delivery,
+    status: 'pending',
+    createdAt: now.toISOString(),
+    source: 'agent',
+    ...(input.check ? { check: input.check } : {}),
+  }
+  writeSteps(root, [...steps, step])
+  return { step, updated: false }
+}
+
+/** Mark a step done (the person ran it) or dismissed (not needed after all). */
+export function settlePersonStep(root: string, id: string, status: 'done' | 'dismissed' | 'pending', now = new Date()): PersonStep {
+  const steps = readPersonSteps(root)
+  const step = steps.find((s) => s.id === id)
+  if (!step) throw new Error(`no person-step ${id}; \`frontera local steps\` lists them`)
+  step.status = status
+  if (status === 'pending') {
+    delete step.doneAt
+    delete step.doneBy
+  } else {
+    step.doneAt = now.toISOString()
+    step.doneBy = 'person'
+  }
+  writeSteps(root, steps)
+  return step
+}
+
+/** Take settled steps off the list; pending ones stay. */
+export function clearSettledSteps(root: string): number {
+  const steps = readPersonSteps(root)
+  const kept = steps.filter((s) => s.status === 'pending')
+  if (kept.length !== steps.length) writeSteps(root, kept)
+  return steps.length - kept.length
+}
+
+/** The pending steps grouped as delivery cards, each in the order recorded; steps with no delivery come last as one group. */
+export function deliveryGroups(steps: PersonStep[]): Array<{ delivery: string | null; steps: PersonStep[] }> {
+  const pending = steps.filter((s) => s.status === 'pending')
+  const order: Array<string | null> = []
+  for (const s of pending) if (!order.includes(s.delivery)) order.push(s.delivery)
+  order.sort((a, b) => (a === null ? 1 : b === null ? -1 : 0))
+  return order.map((delivery) => ({ delivery, steps: pending.filter((s) => s.delivery === delivery) }))
+}
+
+// ── What a change request leaves after Apply (N6) ───────────────────────────
+
+/** One item of an applied request's after-apply list, as the platform returns it. */
+export interface AfterApplyItem {
+  key: string
+  label: string
+  why: string
+  command?: string
+  credential: string
+  check?: StepCheck
+}
+
+/** The after-apply list from an Apply's outcome; empty from a platform that sends none. */
+export function afterApplyOf(outcome: unknown): AfterApplyItem[] {
+  const list = (outcome as { afterApply?: unknown } | null)?.afterApply
+  if (!Array.isArray(list)) return []
+  return list.filter((i): i is AfterApplyItem => !!i && typeof i === 'object' && typeof (i as AfterApplyItem).key === 'string' && typeof (i as AfterApplyItem).label === 'string')
+}
+
+/** Why a check can't be run: it must be a read-only `frontera` command with `--json`. */
+export function checkProblem(check: StepCheck, readOnly: readonly string[]): string | null {
+  const problem = commandProblem(check.command)
+  if (problem) return problem
+  const words = check.command.trim().split(/\s+/).slice(1)
+  if (!words.includes('--json')) return 'a check reads JSON (`--json`)'
+  const path = words.filter((w) => !w.startsWith('-')).join(' ')
+  if (!readOnly.some((r) => path === r || path.startsWith(`${r} `))) return 'a check is a command that only reads'
+  return null
+}
+
+/**
+ * Record what a request left for a person, as person-steps of its delivery
+ * (the request's title). An item already listed (by its key) is updated, a
+ * settled one stays settled, so applying a request again doesn't bring back
+ * what was done.
+ */
+export function recordAfterApply(root: string, delivery: string, items: AfterApplyItem[], now = new Date()): PersonStep[] {
+  const steps = readPersonSteps(root)
+  const out: PersonStep[] = []
+  for (const item of items) {
+    const credential = ((CREDENTIALS as readonly string[]).includes(item.credential) ? item.credential : 'person') as Credential
+    const command = item.command && !commandProblem(item.command) ? item.command : null
+    const existing = steps.find((s) => s.key === item.key && s.delivery === delivery)
+    if (existing) {
+      Object.assign(existing, { command, why: item.why, changes: item.label, credential, ...(item.check ? { check: item.check } : {}) })
+      out.push(existing)
+      continue
+    }
+    const step: PersonStep = {
+      id: `ps_${crypto.randomUUID().replace(/-/g, '').slice(0, 10)}`,
+      command,
+      why: item.why,
+      changes: item.label,
+      credential,
+      delivery,
+      status: 'pending',
+      createdAt: now.toISOString(),
+      source: 'change-request',
+      key: item.key,
+      ...(item.check ? { check: item.check } : {}),
+    }
+    steps.push(step)
+    out.push(step)
+  }
+  if (out.length) writeSteps(root, steps)
+  return out
+}
+
+/** Whether a check's data says the step is done: the row `find` names, with every field of `expect`. */
+export function checkPasses(check: StepCheck, data: unknown): boolean {
+  const list = Array.isArray(data) ? data : check.in && data && typeof data === 'object' ? (data as Record<string, unknown>)[check.in] : null
+  if (!Array.isArray(list)) return false
+  const row = list.find((r) => r && typeof r === 'object' && Object.entries(check.find).every(([k, v]) => (r as Record<string, unknown>)[k] === v))
+  return !!row && Object.entries(check.expect).every(([k, v]) => (row as Record<string, unknown>)[k] === v)
+}
+
+/**
+ * Run each pending step's check, and mark the ones it proves done. `read`
+ * runs a check's command (the CLI itself, `--json`) and returns its data, or
+ * null when it could not run; such a step stays pending and says when it was
+ * last checked.
+ */
+export async function runStepChecks(
+  root: string,
+  read: (args: string[]) => Promise<unknown | null>,
+  readOnly: readonly string[],
+  now = new Date(),
+): Promise<{ checked: number; done: PersonStep[]; problems: Array<{ id: string; problem: string }> }> {
+  const steps = readPersonSteps(root)
+  const done: PersonStep[] = []
+  const problems: Array<{ id: string; problem: string }> = []
+  let checked = 0
+  for (const step of steps) {
+    if (step.status !== 'pending' || !step.check) continue
+    const problem = checkProblem(step.check, readOnly)
+    if (problem) {
+      problems.push({ id: step.id, problem })
+      continue
+    }
+    checked++
+    const args = step.check.command.trim().split(/\s+/).slice(1).filter((w) => w !== '--json')
+    const data = await read(args)
+    step.lastCheckedAt = now.toISOString()
+    if (data !== null && checkPasses(step.check, data)) {
+      step.status = 'done'
+      step.doneAt = now.toISOString()
+      step.doneBy = 'check'
+      done.push(step)
+    }
+  }
+  if (checked) writeSteps(root, steps)
+  return { checked, done, problems }
+}

package/src/local/local-personas.ts

@@ -19,7 +19,8 @@ import type { LocalCredentials } from './local-state'
  * 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
+ * <persona>` then runs as that persona, and so do `media list|upload|stage` (both roles hold
+ * Media content write, so a persona can stage the file an attachment Action takes). The session it uses is minted for the
  * one command, sent only to the local runtime, and never printed or logged.
  */
 
@@ -27,7 +28,11 @@ import type { LocalCredentials } from './local-state'
 export const SUBMITTER = 'submitter'
 
 /** The commands `--as` works on. */
-export const ACT_AS_COMMANDS = ['action available', 'action submit', 'action approve', 'action reject'] as const
+export const ACT_AS_COMMANDS = [
+  'action available', 'action submit', 'action approve', 'action reject',
+  // L6: a persona's files, into the runtime's stand-in Media Sets, and staged for an Action to attach.
+  'media list', 'media upload', 'media stage',
+] as const
 
 const KEY = /^[a-z][a-z0-9_-]{0,62}$/
 /** The most personas one seed takes (the route's limit). */
@@ -82,9 +87,11 @@ function actionDocs(root: string): Array<{ file: string; doc: Doc }> {
 
 /**
  * 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.
+ * stage key; `approver` for an Action approved in one step), and always a
+ * submitter, so `--as submitter` works for an Action that needs no approval
+ * too (Forge improvement plan X2; P1 #7, P4 2.3: PERSONA_NOT_FOUND when every
+ * Action had `approval: none`). 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>()
@@ -117,6 +124,10 @@ export function personaPlan(root: string): PersonaPlan {
     }
     add(SUBMITTER, `requests for ${apiName}`)
   }
+  if (!byKey.has(SUBMITTER)) {
+    const names = actionDocs(root).map(({ file, doc }) => (typeof doc.apiName === 'string' ? doc.apiName : file))
+    add(SUBMITTER, names.length ? `requests for ${names.join(', ')}` : 'requests, as the person who submits them')
+  }
   // 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`)

package/src/local/local-portability.ts

@@ -332,10 +332,31 @@ export function actionFit(doc: Doc, semantic?: SemanticFacts, opts: { changed?:
   if (!effect || !ONTOLOGY_EDITS.has(effect)) return { runsLocally: false, reason: 'it changes a system outside the local runtime', subject, ...inherited }
   const changes = (Array.isArray(doc.businessOutcomes) ? doc.businessOutcomes : []).flatMap((o: Doc) => (Array.isArray(o?.expectedChanges) ? o.expectedChanges : []))
   const sets = changes.some((c: Doc) => c?.kind === 'property_set' && c?.value?.kind === 'input')
-  if (effect !== 'delete' && !sets) return { runsLocally: false, reason: 'it sets no field from its inputs, so there is nothing to write locally', subject, ...inherited }
+  // An Action whose file says how its file is attached writes that (L6), even with no other field.
+  if (effect !== 'delete' && !sets && !actionAttachment(doc)) return { runsLocally: false, reason: 'it sets no field from its inputs, so there is nothing to write locally', subject, ...inherited }
   return { runsLocally: true, subject, ...inherited }
 }
 
+/**
+ * How a deployment of the Action attaches the file it takes (L6), from its
+ * file's `attachment`: the input the file arrives in (`fileInput`), and the
+ * media reference property (`property`), the text property that keeps the
+ * item's id (`itemIdProperty`), or both, with the Media Set by API name when
+ * it is not the property's own. Null when the file says none. A deployment
+ * choice, not the Action's contract: `local dev` deploys with it, and it
+ * stays in the project when the Action is proposed.
+ */
+export function actionAttachment(doc: Doc): { fileInput: string; property?: string; itemIdProperty?: string; mediaSet?: string } | null {
+  const a = doc.attachment
+  if (!a || typeof a !== 'object' || typeof a.fileInput !== 'string' || !a.fileInput) return null
+  return {
+    fileInput: a.fileInput,
+    ...(typeof a.property === 'string' && a.property ? { property: a.property } : {}),
+    ...(typeof a.itemIdProperty === 'string' && a.itemIdProperty ? { itemIdProperty: a.itemIdProperty } : {}),
+    ...(typeof a.mediaSet === 'string' && a.mediaSet ? { mediaSet: a.mediaSet } : {}),
+  }
+}
+
 /** What a pulled Action needs here: it is the workspace's as pulled, so a semantic-type conflict is inherited. */
 export function actionNeeds(doc: Doc, semantic?: SemanticFacts): Need[] {
   const conflicts = semantic ? actionSemanticConflicts(doc, semantic) : []

package/src/local/local-publish.ts

@@ -0,0 +1,26 @@
+import { PlatformApi } from '../api/platform-api'
+import { CliError } from '../errors'
+import type { LocalCredentials } from './local-state'
+
+/**
+ * Publish an Agent's draft on the local runtime (Forge improvement plan L2,
+ * T12; P3 F8). A public website key, a Chat App and a channel talk to an
+ * Agent's published version, and publishing one locally took a raw REST
+ * call. Local only: the workspace's Agent is published by a person, through
+ * a change request or on the platform.
+ */
+export async function publishLocalAgent(
+  link: { serviceUrl: string; creds: LocalCredentials },
+  slug: string,
+  notes: string | undefined,
+  deps: { api?: Pick<PlatformApi, 'allAgents' | 'publishAgent'> } = {},
+): Promise<{ agent: string; id: string; published: unknown }> {
+  const api = deps.api ?? new PlatformApi(link.serviceUrl, link.creds.workspaceKey ?? link.creds.orgKey, link.creds.workspaceId)
+  const listed = (await api.allAgents()) as Array<{ id?: string; agentId?: string }>
+  const row = listed.find((a) => a.agentId === slug)
+  if (!row?.id) {
+    throw new CliError(`the local runtime has no Agent ${slug}`, { code: 'NOT_FOUND', hint: `apply it first: \`frontera local dev --once\` (agents/${slug}/agent.json)` })
+  }
+  const published = await api.publishAgent(row.id, { notes: notes ?? 'Published on the local runtime.' })
+  return { agent: slug, id: row.id, published }
+}