@frontera-sdk/cli 1.52.39 → 1.52.41

package/src/commands/action/deploy.ts

@@ -3,6 +3,7 @@ import { randomUUID } from 'node:crypto'
 import { GovernedActionApi } from '../../api/governed-action-api'
 import { CliError, UsageError } from '../../errors'
 import { deriveOntologyEditPlan, PlanDerivationError } from '../../blueprint/ontology-edit-plan'
+import { validationFindings } from '../../local/local-actions'
 import { flagBool, flagString, type Command, type CommandContext } from '../types'
 
 /**
@@ -92,10 +93,18 @@ export const actionDeploy: Command = {
     const validation = await client.validateBindingRevision(binding.id, 1)
 
     if (validation.status !== 'valid') {
-      throw new CliError(`Deployment validation returned "${validation.status}".`, {
-        code: 'FAILURE',
-        hint: JSON.stringify(validation.findings ?? validation),
-      })
+      // Each failed check, by its code and the platform's message, one per line; the full report in `--json` details.
+      const failed = validationFindings(validation)
+      throw new CliError(
+        `the write path for "${apiName}" did not validate${failed.length ? `: ${failed.length} check${failed.length === 1 ? '' : 's'} failed` : ` (status "${validation.status}")`}`,
+        {
+          code: 'ACTION_DEPLOY_INVALID',
+          hint: failed.length
+            ? `${failed.map((f) => `✕ ${f}`).join('\n  ')}\n  fix the Action (blueprint/actions/${apiName}.yaml) or its object type's editable fields, publish, and deploy again`
+            : 'the service gave no findings for this report; read it with `--json`',
+          details: { action: apiName, bindingRevisionId: binding.id, validationReportId: validation.id, status: validation.status, findings: validation.findings ?? null, failed },
+        },
+      )
     }
 
     return {

package/src/commands/action/list.ts

@@ -1,49 +1,164 @@
-import { GovernedActionApi } from '../../api/governed-action-api'
+import { GovernedActionApi, type DeployableActionEntry } from '../../api/governed-action-api'
+import type { BuildEntry } from '../../local/local-applied'
+import { blueprintBuild } from '../../local/local-blueprint-outline'
+import { localRuntimeAt } from '../../local/local-runtime-target'
 import { table } from '../../table'
 import type { Command } from '../types'
 
 /**
- * Published Actions and whether anything can run them.
+ * Every Action and whether anything can run it.
  *
  * `deploymentStatus` is the question this answers: an Action can be published,
- * correct and completely inert, and nothing else in the CLI says so. `unbound`
- * here is the same state `blueprint publish` refuses to create and that an
- * agent silently cannot see.
+ * correct and completely inert, and nothing else in the CLI says so. The plain
+ * published list holds only Actions that can be invoked, so it never showed
+ * the ones that matter here: this reads the deployable view, which keeps
+ * every published Action with its readiness (one deployable read per Action
+ * on a service without the list), and the draft, for Actions authored but not
+ * published yet. WHY NOT is said for each one that cannot run, with the
+ * command that moves it.
  */
+
+export interface ActionRow {
+  apiName: string
+  published: boolean
+  /**
+   * `active`, `disabled`, `unbound`, `suspended`, `revoked`; `—` when not published;
+   * `left-off` on a local runtime that `local dev` did not give the Action to.
+   */
+  deployment: string
+  available: boolean
+  /** The service's readiness reason when it cannot run (`ACTION_UNBOUND`), or null. */
+  reason: string | null
+  /** In words, with the next command; empty when it runs. */
+  whyNot: string
+  /**
+   * What it runs with that its owner should fix (the service's deployment
+   * warnings): a value it offers that the semantic type it writes refuses.
+   * It still runs; a request with that value is refused when submitted.
+   */
+  warnings?: string[]
+}
+
+/** WHY NOT, in words, from the readiness the service reports. */
+export function whyNot(apiName: string, entry: { published: boolean; deploymentStatus?: string; reason?: string | null; available?: boolean }): string {
+  if (!entry.published) return `not published yet — \`frontera blueprint publish\``
+  if (entry.available && (!entry.reason || entry.reason === 'ACTION_AVAILABLE' || entry.reason === 'ACTION_READY')) return ''
+  const code = entry.reason && entry.reason !== 'ACTION_AVAILABLE' ? ` (${entry.reason})` : ''
+  switch (entry.deploymentStatus) {
+    case 'unbound':
+      return `no write path${code} — \`frontera action deploy ${apiName}\`, then \`action review\``
+    case 'disabled':
+      return `ships switched off${code} — \`frontera action deploy ${apiName}\`, then \`action review\``
+    case 'suspended':
+      return `its deployment is suspended${code} — review it again with \`frontera action review\``
+    case 'revoked':
+      return `its deployment was revoked${code} — \`frontera action deploy ${apiName}\` again`
+    case 'active':
+      return entry.reason === 'ACTION_FORBIDDEN' ? `deployed, but no role may run it${code} — \`frontera action grant\`` : `deployed, but not available${code}`
+    default:
+      return `not deployed${code} — \`frontera action deploy ${apiName}\``
+  }
+}
+
+function draftName(entry: Record<string, unknown>): string | null {
+  const nested = (entry.definition ?? entry.action) as { apiName?: unknown } | undefined
+  const name = nested?.apiName ?? entry.apiName
+  return typeof name === 'string' && name ? name : null
+}
+
+/** The rows: every published Action with its readiness, then each Action only the draft has. */
+export async function actionRows(client: Pick<GovernedActionApi, 'listDeployableActions' | 'listDraftActions' | 'listPublishedActions' | 'publishedAction'>): Promise<ActionRow[]> {
+  const drafts = await client.listDraftActions().then((list) => (Array.isArray(list) ? list.flatMap((e) => draftName(e) ?? []) : [])).catch(() => [] as string[])
+  let deployable = await client.listDeployableActions()
+  if (!deployable) {
+    // A service without the list view: each Action the draft or the published list names, read one at a time.
+    const published = await client.listPublishedActions().catch(() => [])
+    const names = [...new Set([...published.map((p) => p.definition.apiName), ...drafts])]
+    deployable = []
+    for (const name of names) {
+      const one = await client.publishedAction(name).catch(() => null)
+      if (one) deployable.push({ definition: one.definition as DeployableActionEntry['definition'], deploymentStatus: one.deploymentStatus, availability: one.availability, reason: one.reason })
+    }
+  }
+  const rows: ActionRow[] = deployable.map((e) => {
+    const available = e.availability === 'available' && e.executable !== false
+    const row = { published: true, deploymentStatus: e.deploymentStatus, reason: e.reason ?? null, available }
+    return {
+      apiName: e.definition.apiName,
+      published: true,
+      deployment: e.deploymentStatus ?? '—',
+      available,
+      reason: e.reason && e.reason !== 'ACTION_AVAILABLE' ? e.reason : null,
+      whyNot: whyNot(e.definition.apiName, row),
+      ...(e.warnings?.length ? { warnings: e.warnings.map((w) => w.message) } : {}),
+    }
+  })
+  const listed = new Set(rows.map((r) => r.apiName))
+  for (const name of drafts) {
+    if (listed.has(name)) continue
+    rows.push({ apiName: name, published: false, deployment: '—', available: false, reason: null, whyNot: whyNot(name, { published: false }) })
+  }
+  return rows.sort((a, b) => a.apiName.localeCompare(b.apiName))
+}
+
+/**
+ * On a project's own local runtime, each Action `local dev` left off it (the
+ * runtime refused its file, or it acts on a type left off here): the runtime
+ * never holds those, so the service's list cannot name them. From the last
+ * build's record, for the Blueprint files as they are now.
+ */
+export function leftOffActionRows(actions: BuildEntry['actions'] | null, listed: ReadonlySet<string>): ActionRow[] {
+  return Object.entries(actions ?? {}).flatMap(([apiName, a]) => {
+    if (a.status !== 'left-off' || listed.has(apiName)) return []
+    const why = (a.reason ?? 'local dev left it off').replace(/^the local runtime refused it: /, '')
+    return [{
+      apiName,
+      published: false,
+      deployment: 'left-off',
+      available: false,
+      reason: a.refused ? 'LOCAL_RUNTIME_REFUSED' : 'LOCAL_LEFT_OFF',
+      whyNot: a.refused
+        ? `the local runtime refused its file: ${why} — fix blueprint/actions/, then \`frontera local dev --once\``
+        : `left off this runtime: ${why}`,
+    }]
+  })
+}
+
 export const actionList: Command = {
   meta: {
     noun: 'action',
     verb: 'list',
     args: [],
     flags: {},
-    summary: 'List published Actions and their deployment state',
-    examples: ['frontera action list'],
+    summary: 'List every Action, its deployment state and why it cannot run',
+    examples: ['frontera action list', 'frontera action list --json'],
   },
 
   async run(ctx) {
     const client = new GovernedActionApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
-    const actions = await client.listPublishedActions()
+    const actions = await actionRows(client)
+    // The project's own local runtime: the Actions `local dev` left off it, which the runtime cannot list.
+    const local = localRuntimeAt(ctx.cwd, ctx.apiUrl)
+    if (local) {
+      actions.push(...leftOffActionRows(blueprintBuild(local.project.root).actions, new Set(actions.map((a) => a.apiName))))
+      actions.sort((a, b) => a.apiName.localeCompare(b.apiName))
+    }
 
     if (actions.length === 0) {
       return {
         data: { actions: [] },
-        text: 'No published Actions.\n  Author one, then `frontera blueprint publish`.',
+        text: 'No Actions.\n  Author one in blueprint/actions/, then `frontera blueprint apply` and `frontera blueprint publish`.',
       }
     }
 
-    const rows = actions.map((entry) => ({
-      apiName: entry.definition.apiName,
-      deployment: entry.deploymentStatus ?? '—',
-      // Present only when it is NOT invocable, which is when it matters.
-      reason: entry.reason && entry.reason !== 'ACTION_AVAILABLE' ? entry.reason : '',
-    }))
-
+    // Each Action that runs with something its owner should fix, said under the table.
+    const warned = actions.flatMap((r) => (r.warnings ?? []).map((w) => `  warning: ${r.apiName}: ${w} It runs; its owner fixes the Action's contract.`))
     return {
       data: { actions },
-      text: table(
+      text: [table(
         ['ACTION', 'DEPLOYMENT', 'WHY NOT'],
-        rows.map((r) => [r.apiName, r.deployment, r.reason]),
-      ),
+        actions.map((r) => [r.apiName, r.deployment, r.whyNot]),
+      ), ...warned].join('\n'),
     }
   },
 }

package/src/commands/action/requests.ts

@@ -1,5 +1,6 @@
 import { GovernedActionApi } from '../../api/governed-action-api'
 import { UsageError } from '../../errors'
+import { localRuntimeAt } from '../../local/local-runtime-target'
 import { table } from '../../table'
 import { flagBool, flagString, type Command } from '../types'
 
@@ -51,18 +52,19 @@ export const actionRequests: Command = {
       const request = await client.getRequest(requestId)
       return {
         data: request,
+        // Why it failed, first: the reason, the refusal it came from and its code, when the service says.
+        text: [failureLines((request as { failure?: unknown }).failure), table(
         // Flattened rather than curated: the surface records provenance,
         // attempts and failure detail under names that differ by adapter, and
         // naming a subset here would hide exactly the field that explains the
         // failure being investigated.
-        text: table(
           ['field', 'value'],
           Object.entries(request).map(([k, v]) => [
             k,
             v === null || v === undefined ? '' : typeof v === 'object' ? JSON.stringify(v) : String(v),
           ]),
           [undefined, 80],
-        ),
+        )].filter(Boolean).join('\n\n'),
       }
     }
 
@@ -100,6 +102,8 @@ export const actionRequests: Command = {
 
     if (page.requests.length === 0) {
       const filtered = flagString(ctx, 'lifecycle')
+      // On the project's own local runtime a person is a local persona (`--as`), never a session token to fetch.
+      const local = localRuntimeAt(ctx.cwd, ctx.apiUrl) !== null
       if (awaitingMe) {
         return {
           data: page,
@@ -108,8 +112,12 @@ export const actionRequests: Command = {
             : 'Nothing is waiting for your decision.\n')
             + '  This lists the requests you could approve or reject right now: not ones\n'
             + '  you raised, already decided, or that wait on a step for an App role.\n'
-            + '  It is a person\'s list: on a key it is always empty. Set FRONTERA_TOKEN\n'
-            + '  to your session token to read your own.'
+            + (local
+              ? '  It is a person\'s list: on a key it is always empty. On this local runtime,\n'
+                + '  `frontera action requests --lifecycle awaiting_approval` lists what waits,\n'
+                + '  and `frontera action approve <requestId> --as <approver>` decides it.'
+              : '  It is a person\'s list: on a key it is always empty. Set FRONTERA_TOKEN\n'
+                + '  to your session token to read your own.')
             + incomplete,
         }
       }
@@ -119,8 +127,11 @@ export const actionRequests: Command = {
           ? `No requests with lifecycle "${filtered}".`
           : 'No Action requests recorded.\n'
             + '  Nothing has invoked a deployed Action yet. Raise one with\n'
-            + '  `frontera action submit`, which acts as a person: set FRONTERA_TOKEN\n'
-            + '  to your session token and FRONTERA_API_URL.',
+            + (local
+              ? '  `frontera action submit <apiName> --as submitter`: on this local runtime a\n'
+                + '  local persona acts as the person (`frontera local status` lists them).'
+              : '  `frontera action submit`, which acts as a person: set FRONTERA_TOKEN\n'
+                + '  to your session token and FRONTERA_API_URL.'),
       }
     }
 
@@ -151,3 +162,20 @@ export const actionRequests: Command = {
     }
   },
 }
+
+/**
+ * A failed request's `failure` in words: its reason, the refusal it came from
+ * and its code, each on a line. Empty when the request has no failure.
+ */
+export function failureLines(failure: unknown): string {
+  if (!failure || typeof failure !== 'object') return ''
+  const f = failure as { reason?: unknown; refusal?: unknown; reasonCode?: unknown; businessOutcomeCode?: unknown }
+  const text = (v: unknown) => (typeof v === 'string' && v ? v : typeof v === 'object' && v ? JSON.stringify(v) : '')
+  const lines = [
+    text(f.reason) ? `Failed: ${text(f.reason)}` : 'Failed',
+    text(f.refusal) ? `  refusal: ${text(f.refusal)}` : '',
+    text(f.reasonCode) ? `  code: ${text(f.reasonCode)}` : '',
+    text(f.businessOutcomeCode) ? `  outcome: ${text(f.businessOutcomeCode)}` : '',
+  ].filter(Boolean)
+  return lines.length > 1 || text(f.reason) ? lines.join('\n') : ''
+}

package/src/commands/action/submit.ts

@@ -3,6 +3,7 @@ import { CliError, UsageError } from '../../errors'
 import { toEnvelope } from '../../exit'
 import { parseInputFlag } from '../automation/run'
 import { flagString, type Command } from '../types'
+import { criteriaRefusal } from './criteria-refusal'
 import { requestSummary } from './request-summary'
 
 /**
@@ -55,11 +56,16 @@ export const actionSubmit: Command = {
       'subject-version': 'string',
       reason: 'string',
       'idempotency-key': 'string',
+      as: 'string',
     },
     summary: 'Submit a request to a deployed Action',
+    details: [
+      'On the local runtime, `--as <persona>` submits as a local persona (`--as submitter`), so a later step can be decided by another one. Refused anywhere else.',
+    ],
     examples: [
       'frontera action submit createTicket title=Broken priority=2',
       'frontera action submit escalateTicket --subject TKT-1 --subject-version 0',
+      'frontera action submit escalateTicket id=TKT-1 expectedVersion=0',
       'frontera action submit createTicket --input @params.json',
       'frontera action submit createTicket --idempotency-key retry-2026-09-26-01',
     ],
@@ -72,11 +78,8 @@ export const actionSubmit: Command = {
     }
     const subject = flagString(ctx, 'subject')
     const version = flagString(ctx, 'subject-version')
-    if ((subject === undefined) !== (version === undefined)) {
-      throw new UsageError(
-        '--subject and --subject-version go together',
-        `pass both: frontera action submit ${apiName} --subject <objectId> --subject-version <version>`,
-      )
+    if (version !== undefined && subject === undefined) {
+      throw new UsageError('--subject-version names the version of a --subject', `pass the record too: frontera action submit ${apiName} --subject <objectId> --subject-version <version>`)
     }
 
     const client = new GovernedActionApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
@@ -94,7 +97,13 @@ export const actionSubmit: Command = {
       ...(await parseInputFlag(ctx)),
       ...Object.fromEntries(pairs.map((raw) => pair(raw, stringInputs(action)))),
     }
-    const missing = (action.inputSchema?.properties?.input?.required ?? []).filter((name) => !(name in input))
+    const existing = action.subject?.mode === 'existing' && action.subject.objectTypeId
+    // An edit names its record either way: `--subject` (and `--subject-version`), or the key
+    // and `expectedVersion` inputs. The platform fills whichever half is left out from the
+    // other, so with `--subject` the key and version inputs are not missing; the service
+    // names any input that still is.
+    const filled = (name: string) => existing && subject !== undefined && (name === 'expectedVersion' || /^(id|.+(Id|Key|Pk))$/.test(name))
+    const missing = (action.inputSchema?.properties?.input?.required ?? []).filter((name) => !(name in input) && !filled(name))
     if (missing.length > 0) {
       throw new UsageError(
         `"${apiName}" needs ${missing.join(', ')}`,
@@ -103,11 +112,16 @@ export const actionSubmit: Command = {
     }
 
     const invocation: Record<string, unknown> = { input }
-    const existing = action.subject?.mode === 'existing' && action.subject.objectTypeId
-    if (existing && subject === undefined) {
+    if (existing && subject !== undefined && version === undefined && !('expectedVersion' in input)) {
+      throw new UsageError(
+        `"${apiName}" edits a record, so it says the version the change was decided on`,
+        `frontera action submit ${apiName} --subject ${subject} --subject-version <version> (\`blueprint instance\` shows it as _meta.recordVersion)`,
+      )
+    }
+    if (existing && subject === undefined && !('expectedVersion' in input)) {
       throw new UsageError(
         `"${apiName}" acts on an existing object`,
-        `name it: frontera action submit ${apiName} --subject <objectId> --subject-version <version>`,
+        `name it and its version: frontera action submit ${apiName} --subject <objectId> --subject-version <version>, or pass its key input and expectedVersion=<version>`,
       )
     }
     if (!existing && subject !== undefined) {
@@ -116,10 +130,10 @@ export const actionSubmit: Command = {
         `drop --subject and --subject-version: frontera action submit ${apiName} key=value…`,
       )
     }
-    if (existing) {
+    if (existing && subject !== undefined) {
       // The object type is the Action's, not the caller's to choose.
       invocation.subjectRef = { objectTypeId: action.subject!.objectTypeId, objectId: subject }
-      invocation.expectedSubjectVersion = version
+      if (version !== undefined) invocation.expectedSubjectVersion = version
     }
     const reason = flagString(ctx, 'reason')
     if (reason !== undefined) invocation.reason = reason
@@ -146,8 +160,9 @@ export const actionSubmit: Command = {
     } catch (err) {
       // Only where the outcome is unknown. A refusal the service answered
       // (400, 403, 404, 409) is replayed identically under the same key, so
-      // naming the retry there would invite a loop; it is rethrown as is.
-      if (!transient(err)) throw err
+      // naming the retry there would invite a loop; it is rethrown as is —
+      // a submission-criteria refusal with each criterion's message, not only its code.
+      if (!transient(err)) throw criteriaRefusal(err, apiName, ctx.cwd) ?? err
       const envelope = toEnvelope(err)
       throw new CliError(envelope.message, {
         code: err instanceof CliError ? envelope.code : 'FAILURE',

package/src/commands/agent/draft-changes.ts

@@ -79,7 +79,7 @@ export async function agentDraftChanges(api: PlatformApi, id: string): Promise<A
           (k) => stableStringify(draftSections[k]) !== stableStringify(liveSnapshot[k]),
         )
       : []),
-  ].sort()
+  ].sort((a, b) => (String(a) < String(b) ? -1 : String(a) > String(b) ? 1 : 0))
 
   return { hasDraft: true, published, revision: draft.revision, changed }
 }

package/src/commands/agent/index-commands.ts

@@ -152,9 +152,9 @@ const create: Command = {
       data: agent,
       text: [
         `created ${slug}${agent.id ? `  ${agent.id}` : ''}`,
-        // Said plainly because the next thing a caller does is run `agent list`,
-        // see nothing, and conclude the create failed.
-        `  it is in \`configuring\` and will NOT appear in \`frontera agent list\` until published`,
+        // Said plainly: a caller who runs `agent list` next sees it as a draft, not
+        // among the published ones, and should not conclude the create failed.
+        `  it is in \`configuring\` until published: \`frontera agent list\` shows it as \`draft only\``,
         `  next: frontera agent apply ${slug} -f <file>  then  frontera agent publish ${slug}`,
       ].join('\n'),
     }
@@ -171,7 +171,20 @@ const list: Command = {
     examples: ['frontera agent list', 'frontera agent list --json'],
   },
   async run(ctx) {
-    const rows = (await api(ctx).agents()) as AgentRow[]
+    const client = api(ctx)
+    const published = (await client.agents()) as AgentRow[]
+    // An Agent never published (one created and only applied, as every Agent on a local runtime is)
+    // is not in that list; the workspace's full listing adds it, marked as a draft. A platform
+    // without that listing lists the published ones, as before.
+    const all = ((await client.allAgents().catch(() => [])) ?? []) as AgentRow[]
+    const known = new Set(published.map((a) => a.id))
+    const drafts = all.filter((a) => a.lifecycleStatus === 'configuring' && !known.has(a.id) && !String(a.agentId ?? '').startsWith('preview_'))
+    const rows = [...published, ...drafts]
+    // An archived Agent is in the published listing: said as archived, not as live. One with no published
+    // version is a draft, not published, even when it reads active: restore now brings a draft-only Agent
+    // back `configuring`, but one restored before that fix still reads active.
+    const state = (a: AgentRow) => (a.lifecycleStatus === 'archived' ? 'archived' : a.lifecycleStatus === 'configuring' || (a.currentVersionId === null && a.lifecycleStatus === 'active') ? 'draft only' : 'published')
+    const withState = drafts.length > 0 || rows.some((a) => state(a) !== 'published')
     return {
       data: rows,
       text:
@@ -179,8 +192,8 @@ const list: Command = {
           ? 'No agents in this workspace.'
           : // Either ID or SLUG works wherever an agent is named.
             table(
-              ['id', 'slug', 'name'],
-              rows.map((a) => [a.id ?? '?', a.agentId ?? '', a.name ?? '']),
+              withState ? ['id', 'slug', 'name', 'state'] : ['id', 'slug', 'name'],
+              rows.map((a) => [a.id ?? '?', a.agentId ?? '', a.name ?? '', ...(withState ? [state(a)] : [])]),
             ),
     }
   },
@@ -230,7 +243,16 @@ const get: Command = {
       const identity = (row ?? {}) as {
         id?: string
         agentId?: string
-        currentVersion?: { versionNumber?: number }
+        currentVersionId?: string | null
+        currentVersion?: { versionNumber?: number } | null
+        draft?: unknown
+      }
+      // Never published: the composition is the empty published side, which reads as an Agent with nothing.
+      if (row && !identity.currentVersionId && !identity.currentVersion) {
+        throw new CliError(`${identity.agentId ?? t.ref} has no published version yet: only its draft exists`, {
+          code: 'NOT_FOUND',
+          hint: `read the draft: \`frontera agent get ${identity.agentId ?? t.ref} --draft\`${identity.draft ? '' : ' (`frontera agent list` shows its state)'}`,
+        })
       }
       return {
         data: snapshot,
@@ -388,6 +410,44 @@ const discard: Command = {
   },
 }
 
+const archive: Command = {
+  meta: {
+    noun: 'agent',
+    verb: 'archive',
+    args: [{ name: 'agent', required: true, description: 'agent id or slug' }],
+    flags: {},
+    summary: 'Archive an agent: it leaves service with its versions and conversations kept (`agent restore` puts it back)',
+    examples: ['frontera agent archive assistant'],
+  },
+  async run(ctx) {
+    const t = await target(ctx, 'archive')
+    const row = (await t.api.agent(t.id).catch(() => null)) as AgentRow | null
+    if (row?.lifecycleStatus === 'archived') return { data: { archived: true, agent: t.ref, already: true }, text: `${t.ref} is already archived.` }
+    await t.api.archiveAgent(t.id)
+    return {
+      data: { archived: true, agent: t.ref },
+      text: [`Archived ${t.ref}: no chat, channel or workflow reaches it now; its versions and conversations are kept.`, `  its slug stays taken; \`frontera agent restore ${t.ref}\` puts it back`].join('\n'),
+    }
+  },
+}
+
+const restore: Command = {
+  meta: {
+    noun: 'agent',
+    verb: 'restore',
+    args: [{ name: 'agent', required: true, description: 'agent id or slug' }],
+    flags: {},
+    summary: 'Put an archived agent back into service, as it was',
+    examples: ['frontera agent restore assistant'],
+  },
+  async run(ctx) {
+    const t = await target(ctx, 'restore')
+    const result = (await t.api.restoreAgent(t.id)) as { restored?: boolean; lifecycleStatus?: string } | null
+    if (result && result.restored === false) return { data: { restored: false, agent: t.ref }, text: `${t.ref} isn't archived${result.lifecycleStatus ? ` (it is ${result.lifecycleStatus === 'configuring' ? 'a draft' : result.lifecycleStatus})` : ''}: nothing to restore.` }
+    return { data: { restored: true, agent: t.ref }, text: `Restored ${t.ref}.` }
+  },
+}
+
 const versions: Command = {
   meta: {
     noun: 'agent',
@@ -555,6 +615,8 @@ export const agentCommands: Command[] = [
   publish,
   diff,
   discard,
+  archive,
+  restore,
   versions,
   revert,
   skillAttach,

package/src/commands/agent/resolve.ts

@@ -8,6 +8,8 @@ export interface AgentRow {
   name?: string
   kind?: string
   lifecycleStatus?: string
+  /** The published version; null for an Agent never published. */
+  currentVersionId?: string | null
 }
 
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i

package/src/commands/app/checks.ts

@@ -0,0 +1,44 @@
+import { AppsApi, type DeploymentCheck } from '../../api/apps-api'
+import { UsageError } from '../../errors'
+import { table } from '../../table'
+import { projectApp, requireProjectFrom } from './shared'
+import type { Command } from '../types'
+
+/** The checks a deployment passes in the App's workspace, with which ones the workspace requires. */
+export function renderChecks(deployment: string, checks: DeploymentCheck[]): string {
+  if (!checks.length) return `${deployment}: no checks recorded`
+  return table(
+    ['CHECK', 'STATUS', 'REQUIRED', 'DETAIL'],
+    checks.map((c) => [c.label, c.status, c.required ? 'yes' : '-', c.detail]),
+    [undefined, undefined, undefined, 72],
+  )
+}
+
+export const appChecks: Command = {
+  meta: {
+    noun: 'app',
+    verb: 'checks',
+    args: [
+      {
+        name: 'deployment',
+        required: true,
+        description: 'the deployment id or release label, from `frontera app deployments`',
+        producer: 'frontera app deployments — then `frontera app checks <deployment>`',
+      },
+    ],
+    flags: {},
+    summary: 'Show the build, render, contract and accessibility checks for a deployment',
+    examples: ['frontera app checks dpl_01JABCDEF', 'frontera app checks 1.4.0 --json'],
+    needsProject: true,
+  },
+
+  async run(ctx) {
+    const deployment = ctx.positional[0]
+    if (!deployment) throw new UsageError('say which deployment', 'frontera app checks <deployment id or label>')
+    const project = requireProjectFrom(ctx)
+    const client = new AppsApi(ctx.apiUrl, ctx.token)
+    const app = await projectApp(client, project)
+    const res = await client.checks(app.id, deployment)
+    return { data: res, text: renderChecks(res.deployment, res.checks) }
+  },
+}