@frontera-sdk/cli 1.52.28 → 1.52.30

package/src/commands/skill/bundle-commands.ts

@@ -25,7 +25,7 @@ import { resolveSkillRef } from './resolve'
  * sidecar metadata file.
  */
 
-interface SkillDoc {
+export interface SkillDoc {
   id?: string
   name?: string
   displayName?: string
@@ -67,17 +67,17 @@ const MIME_BY_EXT: Record<string, string> = {
   pptx: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
 }
 
-function mimeFromPath(path: string): string {
+export function mimeFromPath(path: string): string {
   return MIME_BY_EXT[path.split('.').pop()?.toLowerCase() ?? ''] ?? 'application/octet-stream'
 }
 
 /** `workspace/{ws}/skill-assets/{sha}.{ext}` → `{sha}.{ext}`, or null. */
-function assetFilename(storageKey: string): string | null {
+export function assetFilename(storageKey: string): string | null {
   const m = /^workspace\/[^/]+\/skill-assets\/([0-9a-f]{6,64}\.[A-Za-z0-9]+)$/.exec(storageKey)
   return m ? m[1]! : null
 }
 
-function toSkillMd(doc: SkillDoc): string {
+export function toSkillMd(doc: SkillDoc): string {
   const data: Record<string, unknown> = { name: doc.name }
   if (doc.displayName != null) data.displayName = doc.displayName
   if (doc.trigger != null) data.trigger = doc.trigger
@@ -87,7 +87,9 @@ function toSkillMd(doc: SkillDoc): string {
   if (typeof doc.sortOrder === 'number') data.sortOrder = doc.sortOrder
   const visible = (doc.assets ?? []).filter((a) => a.visible).map((a) => a.path)
   if (visible.length) data.visibleAssets = visible
-  return matter.stringify(doc.body ?? '', data)
+  // As content, not a string: gray-matter parses a string's own front matter
+  // first, so a body opening with a `---` block was merged in, or threw.
+  return matter.stringify({ content: doc.body ?? '' }, data)
 }
 
 /**
@@ -202,7 +204,8 @@ export function readBundle(dir: string): {
       const full = join(current, entry)
       const rel = relative(dir, full).split(sep).join('/')
       const base = entry
-      if (base === '.DS_Store' || base.startsWith('._') || base === 'Thumbs.db' || base === '.git') continue
+      // `<file>.workspace` is a sync conflict's copy of the workspace's version, never part of the bundle.
+      if (base === '.DS_Store' || base.startsWith('._') || base === 'Thumbs.db' || base === '.git' || base.endsWith('.workspace')) continue
       if (statSync(full).isDirectory()) {
         walk(full)
         continue

package/src/errors.ts

@@ -12,13 +12,16 @@
 export class CliError extends Error {
   readonly code: string
   readonly hint?: string
+  /** What a caller reading `--json` needs beyond the message: the checks a refusal names, per item. */
+  readonly details?: unknown
 
   /** `cause` keeps the original error — and its `details` — when one is reworded. */
-  constructor(message: string, opts: { code: string; hint?: string; cause?: unknown }) {
+  constructor(message: string, opts: { code: string; hint?: string; cause?: unknown; details?: unknown }) {
     super(message, opts.cause === undefined ? undefined : { cause: opts.cause })
     this.name = 'CliError'
     this.code = opts.code
     if (opts.hint) this.hint = opts.hint
+    if (opts.details !== undefined) this.details = opts.details
   }
 }
 

package/src/exit.ts

@@ -29,6 +29,8 @@ export interface ErrorEnvelope {
   code: string
   message: string
   hint?: string
+  /** A CliError's `details`, when it has them (a refused push's checks). */
+  details?: unknown
 }
 
 const USAGE_CODES = new Set([
@@ -207,6 +209,7 @@ export function toEnvelope(err: unknown): ErrorEnvelope {
       code: err.code,
       message: err.message,
       ...(err.hint ? { hint: err.hint } : {}),
+      ...(err.details !== undefined ? { details: err.details } : {}),
     }
   }
 

package/src/flag-help.ts

@@ -85,6 +85,7 @@ export const FLAG_HELP: Readonly<Record<string, string>> = {
   lines: 'how many of the latest log lines to print (default 100)',
   stdin: 'read the value from standard input instead of a hidden prompt',
   live: 'test the published Agent instead of its draft',
+  regression: 'run only the files marked `regression: true`: each Agent’s regression dataset in the workspace',
   once: 'apply the solution once and exit instead of watching for changes',
   'no-publish': 'keep Blueprint changes as a draft instead of publishing them to the local workspace',
   registry: 'the registry host and namespace image mode pulls the platform images from, such as registry.example.com/frontera',
@@ -206,6 +207,37 @@ export const FLAG_HELP: Readonly<Record<string, string>> = {
   'token-stdin': 'read the key from stdin instead of prompting — sk-ws- or sk-org-',
   'no-input': 'never prompt; fail instead, for use in scripts and CI',
   config: 'print the resolved configuration and where each value came from',
+
+  // A local project's link to a platform workspace (`local sync`, `local init --from-workspace`).
+  platform: 'the platform\'s API origin, e.g. https://api.acme.frontera.example',
+  'workspace-key': '`-` to read the workspace key (sk-ws-…) from stdin; never pass the key itself',
+  'org-key': '`-` to read an organization key (sk-org-…) from stdin, after the workspace key; widens the Blueprint to the whole model',
+  blueprint: 'workspace (the slice granted to the workspace, default) or organization (the whole model; needs an organization key)',
+  relink: 'point a project already linked to another workspace at this one',
+  preview: 'list what a pull would bring, or a push would propose, file by file, and change nothing',
+  kinds: 'comma-separated: blueprint, skills, functions, plugins, knowledge, workflows, agents, evaluations',
+  drafts: 'comma-separated items (agent/<slug>, workflow/<slug>, function/<slug>, blueprint) to read as their draft instead of the live version; the Blueprint’s draft takes an organization key',
+  'all-changed': 'pull every item the workspace changed since the last pull, and every clean merge; never one that conflicts or replaces local edits',
+  offline: 'do not ask the platform; use only what the project and the last fetch record',
+  fetch: 'fetch from the workspace first, then answer from the new snapshot',
+  full: 'read the whole sync index, deletions included, instead of what changed since the last fetch',
+  'forget-link': 'also remove the link from frontera.yaml',
+  snapshot: 'the snapshot a preview showed; if the workspace moved since, plan again and write nothing',
+  'delete-here': 'comma-separated items the workspace deleted: delete their files here too',
+  'keep-local': 'comma-separated items the workspace deleted: keep them here as the project’s own',
+  keep: 'workspace or mine: the side every conflict takes, unless --picks says otherwise',
+  picks: 'a side per conflict, numbered as `diff` shows them: 1=workspace,2=mine; =both keeps mine then the workspace’s where `diff` says both can be kept',
+  edited: 'take the files as you edited them; the workspace’s copies beside them go',
+  title: 'the change request’s title; a push that opens a new one needs it',
+  migration: 'for a Blueprint change that is not additive: what happens to existing records',
+  documents: 'comma-separated knowledge bases whose documents a pull brings, or a push proposes (`*` for every one); without it they stay as they are',
+  lessons: 'bring each Agent’s reviewed rules from customer feedback into agents/<slug>/lessons.yaml (never the feedback itself); off by default',
+  conflicts: 'the conflicts the picks were chosen against, as `diff --json` names them; refused if they moved',
+  'from-workspace': 'start the project from a platform workspace instead of the examples',
+  'no-sample-data': 'do not generate sample rows for the pulled Blueprint',
+  synthetic: 'generate sample rows for the Blueprint: values fit each property, links stay consistent',
+  rows: 'rows per object type (default 200; types others link to get half)',
+  seed: 'the same seed writes the same rows (default 7)',
 }
 
 /**
@@ -234,6 +266,8 @@ const PLACEHOLDER: Readonly<Record<string, string>> = {
   'expect-revision': 'hash',
   notes: 'text',
   description: 'text',
+  title: 'text',
+  migration: 'text',
   'display-name': 'text',
   strategy: 'auto|text|ocr',
   from: '-|path',
@@ -255,6 +289,20 @@ const PLACEHOLDER: Readonly<Record<string, string>> = {
   'max-distance': '0-2',
   permissions: 'read,write',
   template: 'non-negative|percentage|status-enum|code-length',
+  platform: 'url',
+  'workspace-key': '-',
+  'org-key': '-',
+  blueprint: 'workspace|organization',
+  kinds: 'a,b',
+  drafts: 'kind/name,…',
+  snapshot: 'id',
+  'delete-here': 'kind/name,…',
+  'keep-local': 'kind/name,…',
+  documents: 'name,…',
+  keep: 'workspace|mine',
+  picks: 'n=side,…',
+  rows: 'n',
+  seed: 'n',
 }
 
 /**

package/src/local/local-actions.ts

@@ -0,0 +1,306 @@
+import { randomUUID } from 'node:crypto'
+
+import { deriveOntologyEditPlan, PlanDerivationError, type ObjectTypeShape, type PublishedActionDefinition } from '../blueprint/ontology-edit-plan'
+import type { ActionFit } from './local-portability'
+import type { LocalCredentials } from './local-state'
+
+/**
+ * Governed Actions on the local runtime (design §15.1, D3): pulled with the
+ * Blueprint and deployed here automatically, so a workflow naming
+ * `action/<apiName>` applies and runs. The platform's own deployment decision
+ * is never touched: every call below goes to the local runtime, and
+ * `localActionCalls` refuses any other address.
+ *
+ * It is the platform's deployment lane, run by the local owner, the same steps
+ * `frontera action prepare`, `action deploy` and `action review` take:
+ *
+ *   before the publish   the draft moves to schema 2 if it is older (Actions need it), and
+ *                        each Action gets its first decision, "ships switched off", which
+ *                        publishing requires
+ *   after the publish    an Action that writes only the Blueprint's records gets its write
+ *                        path (an ontology edit derived from the Action), built and validated
+ *                        by the organization key, then reviewed and activated by the owner's
+ *                        session (the service refuses a reviewer who built it); the owner role
+ *                        may then invoke it
+ *
+ * An Action whose effect would reach another system (a transition, a command)
+ * keeps its switched-off decision: it is published, workflows that name it
+ * apply, and the build says it is switched off here.
+ */
+
+export interface Answer {
+  status: number
+  body: unknown
+}
+
+/** One call to the local runtime, as the organization key or as the owner's session. */
+export type Call = (as: 'org' | 'session', method: string, path: string, body?: unknown) => Promise<Answer>
+
+const LOOPBACK = /^https?:\/\/(127\.0\.0\.1|localhost|\[::1\])(:\d+)?(\/|$)/
+
+/** Calls to the local runtime with the project's own keys. Never a platform: a non-loopback address is refused. */
+export function localActionCalls(serviceUrl: string, creds: LocalCredentials, fetcher: typeof fetch = fetch): Call {
+  if (!LOOPBACK.test(serviceUrl)) throw new Error(`governed Actions are deployed on the local runtime only, not on ${new URL(serviceUrl).host}`)
+  return async (as, method, path, body) => {
+    const token = as === 'org' ? creds.orgKey : creds.session
+    if (!token) return { status: 401, body: { message: as === 'session' ? 'the runtime has no owner session; restart it' : 'the runtime has no organization key' } }
+    const res = await fetcher(new URL(path, serviceUrl), {
+      method,
+      headers: {
+        authorization: `Bearer ${token}`,
+        'x-org-id': creds.organizationId,
+        ...(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 }
+  }
+}
+
+/** `{data}` or `{error:false,data}` envelopes, unwrapped. */
+function data<T>(answer: Answer): T {
+  const b = answer.body as { data?: unknown } | null
+  return (b && typeof b === 'object' && 'data' in b ? b.data : b) as T
+}
+
+function message(answer: Answer): string {
+  const b = answer.body as { message?: unknown; error?: unknown } | null
+  const text = typeof b?.message === 'string' ? b.message : typeof b === 'string' ? b : JSON.stringify(b)
+  return `${answer.status} ${String(text).replace(/\s+/g, ' ').slice(0, 240)}`
+}
+
+const ADMIN = '/v1/blueprint/governed-actions/admin'
+
+/** The checks a validation report failed, by name: its findings with `passed: false`, anywhere in it. */
+function failedChecks(report: unknown): string {
+  const names: string[] = []
+  const visit = (v: unknown) => {
+    if (Array.isArray(v)) return v.forEach(visit)
+    if (!v || typeof v !== 'object') return
+    const o = v as Record<string, unknown>
+    if (o.passed === false) names.push(String(o.code ?? o.check ?? o.kind ?? o.name ?? 'a check'))
+    for (const x of Object.values(o)) visit(x)
+  }
+  visit(report)
+  return names.length ? `failed ${[...new Set(names)].join(', ')}` : `status ${String((report as { status?: unknown } | null)?.status ?? 'unknown')}`
+}
+
+/**
+ * Before `blueprint apply` writes Actions: a draft still on schema 1 cannot
+ * hold them, so it moves to schema 2 (a steward's call: the owner's session).
+ * Returns a note when it moved, null when nothing needed doing.
+ */
+export async function ensureActionDraft(call: Call): Promise<{ ok: boolean; note: string | null }> {
+  const lifecycle = await call('org', 'GET', '/v1/blueprint/lifecycle')
+  if (lifecycle.status === 404) return { ok: true, note: null }
+  if (lifecycle.status >= 300) return { ok: false, note: `the Blueprint draft could not be read: ${message(lifecycle)}` }
+  const draft = data<{ draft?: { revision?: number; definition?: { schemaVersion?: number } } }>(lifecycle)?.draft
+  if (draft?.definition?.schemaVersion !== 1 || !draft.revision) return { ok: true, note: null }
+  const migrated = await call('session', 'POST', '/v1/blueprint/lifecycle/draft/migrate-v2', { expectedRevision: draft.revision })
+  if (migrated.status >= 300) return { ok: false, note: `the Blueprint draft could not move to schema 2, which governed Actions need: ${message(migrated)}` }
+  return { ok: true, note: 'moved the Blueprint draft to schema 2 for its governed Actions' }
+}
+
+/**
+ * Each Action's first decision, before the publish: it ships switched off. An
+ * Action that already has one (published before) needs nothing. Returns the
+ * Actions that could not get one, with why.
+ */
+export async function prepareActions(call: Call, apiNames: string[], authoredAgain: ReadonlySet<string> = new Set()): Promise<Map<string, string>> {
+  const failed = new Map<string, string>()
+  for (const apiName of apiNames) {
+    // Published already: it has its decision, and a deploy follows the release, not the draft.
+    // One authored again under a new id has none yet, whatever the release still holds.
+    if (!authoredAgain.has(apiName)) {
+      const published = await call('org', 'GET', `/v1/blueprint/actions/${encodeURIComponent(apiName)}?view=deployable`)
+      if (published.status < 300) continue
+    }
+    const res = await call('org', 'POST', `${ADMIN}/deployments`, { actionApiName: apiName, reason: 'Pulled into a local project: ships switched off until the local runtime deploys it.' })
+    if (res.status < 300) continue
+    const details = (res.body as { details?: { contractChanged?: boolean } } | null)?.details
+    if (res.status === 409 && !details?.contractChanged) continue
+    failed.set(apiName, details?.contractChanged ? 'it changed after it was first deployed here; the local runtime needs a reset to deploy it again' : message(res))
+  }
+  return failed
+}
+
+/** Of these Actions, the ones still waiting for their first decision: not published here yet. */
+export async function unpublishedActions(call: Call, apiNames: string[]): Promise<string[]> {
+  const out: string[] = []
+  for (const apiName of apiNames) {
+    const published = await call('org', 'GET', `/v1/blueprint/actions/${encodeURIComponent(apiName)}?view=deployable`)
+    if (published.status >= 300) out.push(apiName)
+  }
+  return out
+}
+
+/**
+ * Actions whose contract moved after their decision was taken here (an edit
+ * to the Action, or to a field of its object type), which blocks the publish:
+ * a decision cannot follow a new contract. The draft's validation names them.
+ * On the platform the cure is authoring the Action again under a new id; on
+ * the local runtime `local dev` does that itself (see `dev.ts`).
+ */
+export async function staleActions(call: Call, apiNames: string[]): Promise<{ stale: string[]; consumed: string[] }> {
+  const validated = await call('org', 'POST', '/v1/blueprint/lifecycle/validate', {})
+  const report = data<{ report?: { blockers?: Blocker[] }; blockers?: Blocker[] }>(validated)
+  const blockers = report?.report?.blockers ?? report?.blockers ?? []
+  const stale = [...new Set(blockers.flatMap((b) => (b.code === 'ACTION_BINDING_DIGEST_MISMATCH' ? [/Action "([^"]+)"/.exec(b.message ?? '')?.[1]].filter((n): n is string => !!n) : [])))]
+  // An Action taken out of the draft while its old deployment still runs: named by the released id.
+  const ids = new Set(blockers.flatMap((b) => (b.code === 'ACTION_BINDING_CONSUMER_INVALID' ? [/^actions\.([^.]+)\./.exec(b.path ?? '')?.[1]].filter((n): n is string => !!n) : [])))
+  const consumed: string[] = []
+  if (ids.size) {
+    for (const apiName of apiNames) {
+      const read = await call('org', 'GET', `/v1/blueprint/actions/${encodeURIComponent(apiName)}?view=deployable`)
+      if (read.status < 300 && ids.has(data<Deployable>(read).definition?.id)) consumed.push(apiName)
+    }
+  }
+  return { stale, consumed }
+}
+
+interface Blocker {
+  code?: string
+  message?: string
+  path?: string
+}
+
+/**
+ * Before an Action is authored again: its deployment here, if one is live,
+ * is retired, since a release may not drop a contract a live deployment
+ * still runs. Returns the Actions whose deployment could not be retired.
+ */
+export async function retireActions(call: Call, apiNames: string[]): Promise<Map<string, string>> {
+  const failed = new Map<string, string>()
+  for (const apiName of apiNames) {
+    const read = await call('org', 'GET', `/v1/blueprint/actions/${encodeURIComponent(apiName)}?view=deployable`)
+    if (read.status >= 300) continue
+    const id = data<Deployable>(read).definition?.id
+    if (!id) continue
+    const listed = data<{ entries?: Array<{ actionDefinitionId: string; deployment?: { stateId?: string; generation?: number; state?: string } | null }> }>(
+      await call('session', 'GET', `${ADMIN}/bindings?actionDefinitionId=${encodeURIComponent(id)}`),
+    )
+    const current = listed?.entries?.find((e) => e.actionDefinitionId === id)?.deployment
+    if (!current?.stateId || typeof current.generation !== 'number' || (current.state !== 'active' && current.state !== 'suspended')) continue
+    const retired = await call('session', 'POST', `${ADMIN}/deployments/${current.stateId}/revoke`, { expectedGeneration: current.generation, reason: 'Authored again on the local runtime after its contract changed.' })
+    if (retired.status >= 300) failed.set(apiName, `its deployment here could not be revoked: ${message(retired)}`)
+  }
+  return failed
+}
+
+export type ActionBuildStatus = 'runs' | 'switched-off' | 'failed' | 'left-off'
+
+export interface ActionBuild {
+  status: ActionBuildStatus
+  /** Why it is not running, in words. */
+  reason?: string
+}
+
+interface Deployable {
+  definition: PublishedActionDefinition
+  contractDigest: string
+  deploymentStatus?: string
+}
+
+/** The write path for one Action that writes the Blueprint's records: built, validated, reviewed, activated. */
+async function deployOne(call: Call, published: Deployable): Promise<string | null> {
+  const { definition, contractDigest } = published
+  const types = data<Array<{ id?: string; apiName?: string }>>(await call('org', 'GET', '/v1/blueprint/object-types')) ?? []
+  const subject = (Array.isArray(types) ? types : []).find((t) => t.id === definition.subject.objectTypeId)?.apiName
+  if (!subject) return 'the object type it acts on is not published here'
+  const shape = data<{ objectType?: { id?: string; apiName?: string; primaryKeyPropertyId?: string | null }; properties?: ObjectTypeShape['properties'] }>(
+    await call('org', 'GET', `/v1/blueprint/object-types/${encodeURIComponent(subject)}`),
+  )
+  if (!shape?.objectType?.id) return `${subject} is not published here`
+  let plan
+  try {
+    plan = deriveOntologyEditPlan(definition, { id: shape.objectType.id, apiName: shape.objectType.apiName ?? subject, primaryKeyPropertyId: shape.objectType.primaryKeyPropertyId ?? null, properties: shape.properties ?? [] })
+  } catch (err) {
+    if (err instanceof PlanDerivationError) return err.message
+    throw err
+  }
+  const planRevision = await call('org', 'POST', `${ADMIN}/mutation-plans/${randomUUID()}/revisions`, { expectedRevision: 0, parentRevisionId: null, plan })
+  if (planRevision.status >= 300) return `its write plan was refused: ${message(planRevision)}`
+  const binding = await call('org', 'POST', `${ADMIN}/bindings/${randomUUID()}/revisions`, {
+    expectedRevision: 0,
+    parentRevisionId: null,
+    actionDefinitionId: definition.id,
+    actionContractDigest: contractDigest,
+    mutationPlanRevisionId: data<{ id: string }>(planRevision).id,
+  })
+  if (binding.status >= 300) return `its write path was refused: ${message(binding)}`
+  const bindingRevisionId = data<{ id: string }>(binding).id
+  const validation = await call('org', 'POST', `${ADMIN}/binding-revisions/${bindingRevisionId}/validate`, { expectedStateGeneration: 1 })
+  const report = data<{ id?: string; status?: string; findings?: unknown }>(validation)
+  if (validation.status >= 300 || report?.status !== 'valid') return `its write path did not validate: ${validation.status >= 300 ? message(validation) : failedChecks(report)}`
+  // A different principal from the key that built it: the service insists.
+  const reviewed = await call('session', 'POST', `${ADMIN}/binding-revisions/${bindingRevisionId}/review`, { validationReportId: report.id, expectedStateGeneration: 2 })
+  if (reviewed.status >= 300) return `its review was refused: ${message(reviewed)}`
+  const revision = data<{ stateId?: string; stateGeneration?: number; actionDefinitionId?: string }>(await call('session', 'GET', `${ADMIN}/binding-revisions/${bindingRevisionId}`))
+  if (!revision?.stateId || typeof revision.stateGeneration !== 'number') return 'it was reviewed, but its deployment state could not be read'
+  const listed = data<{ entries?: Array<{ actionDefinitionId: string; deployment?: { stateId?: string; generation?: number } | null }> }>(
+    await call('session', 'GET', `${ADMIN}/bindings?actionDefinitionId=${encodeURIComponent(definition.id)}`),
+  )
+  const current = listed?.entries?.find((e) => e.actionDefinitionId === definition.id)?.deployment
+  const activated = await call('session', 'POST', `${ADMIN}/deployments/${revision.stateId}/activate`, {
+    expectedGeneration: revision.stateGeneration,
+    expectedCurrentStateId: current?.stateId ?? null,
+    expectedCurrentGeneration: typeof current?.generation === 'number' ? current.generation : null,
+    reason: 'Activated on the local runtime by frontera local dev.',
+  })
+  if (activated.status >= 300) return `its activation was refused: ${message(activated)}`
+  return null
+}
+
+export interface LocalAction {
+  apiName: string
+  fit: ActionFit
+  /** The capability that lets a role invoke it (`governance.invokeCapability`). */
+  invokeCapability?: string
+}
+
+/**
+ * After the publish: deploy what runs here and let the owner role invoke it;
+ * leave the rest switched off. Already active Actions are left as they are.
+ * Each is read in its deployable view: the plain list holds only Actions that
+ * can be invoked, which a switched-off one cannot.
+ */
+export async function deployActions(call: Call, actions: LocalAction[]): Promise<Record<string, ActionBuild>> {
+  const out: Record<string, ActionBuild> = {}
+  for (const action of actions) {
+    if (!action.fit.runsLocally) {
+      out[action.apiName] = { status: 'switched-off', reason: action.fit.reason }
+      continue
+    }
+    const read = await call('org', 'GET', `/v1/blueprint/actions/${encodeURIComponent(action.apiName)}?view=deployable`)
+    if (read.status === 404) {
+      out[action.apiName] = { status: 'failed', reason: 'it is not published on the local runtime' }
+      continue
+    }
+    if (read.status >= 300) {
+      out[action.apiName] = { status: 'failed', reason: `its published contract could not be read: ${message(read)}` }
+      continue
+    }
+    const published = data<Deployable>(read)
+    let failure: string | null = null
+    if (published.deploymentStatus !== 'active') {
+      try {
+        failure = await deployOne(call, published)
+      } catch (err) {
+        failure = (err as Error).message
+      }
+    }
+    if (!failure && action.invokeCapability) {
+      const granted = await call('session', 'POST', `${ADMIN}/capability-grants`, { capability: action.invokeCapability, role: 'owner', revoke: false })
+      if (granted.status >= 300) failure = `it is deployed, but the owner role could not be allowed to run it: ${message(granted)}`
+    }
+    out[action.apiName] = failure ? { status: 'failed', reason: failure } : { status: 'runs' }
+  }
+  return out
+}