@frontera-sdk/cli 1.50.79 → 1.50.81

package/README.md

@@ -97,8 +97,14 @@ project) and `frontera app init` (scaffold a new app) are different commands.
 | `frontera app save` | package the working tree to storage |
 | `frontera app deploy` | build output → an immutable version |
 | `frontera app list` / `versions` | what exists, what is live |
+| `frontera chat-app list` / `get` | Chat Apps, and one's live version, roster, audience and endpoints |
+| `frontera chat-app draft` / `publish` | stage a configuration file, then publish it live |
+| `frontera chat-app access` / `endpoint` | who may open it, and where it is reachable |
 | `frontera blueprint list` / `get` | what data an app can read |
 | `frontera blueprint generate-types` | generate committed App-local types from that data contract |
+| `frontera marking list` / `grants` / `create` / `grant` / `revoke` | security markings — needs a person's session, never an API key; or the platform, in Blueprint → Access → Markings |
+| `frontera media create` / `grant` / `upload` | fill a Media Set from local files (session only) |
+| `frontera media process` / `status --watch` / `search` | switch processing on, wait for it, spot-check the passages |
 
 `frontera help --json` returns the whole table as data.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontera-sdk/cli",
-  "version": "1.50.79",
+  "version": "1.50.81",
   "description": "The frontera CLI — scaffold, pull, save and deploy Frontera apps and automations.",
   "keywords": [
     "frontera",
@@ -39,14 +39,14 @@
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.251",
-    "@frontera-sdk/functions": "1.50.79",
-    "@frontera-sdk/core": "1.50.79",
+    "@frontera-sdk/functions": "1.50.81",
+    "@frontera-sdk/core": "1.50.81",
     "ai": "^6.0.116",
     "gray-matter": "^4.0.3",
     "yaml": "^2.9.0"
   },
   "devDependencies": {
-    "@frontera-sdk/forge-contracts": "1.50.79",
+    "@frontera-sdk/forge-contracts": "1.50.81",
     "@types/bun": "^1.3.14",
     "typescript": "^5.9.3"
   }

package/src/api/blueprint-authoring-api.ts

@@ -4,6 +4,19 @@ import { credentialFailure } from './credential-failure'
 import { formatValidationDetails } from './validation-detail'
 import type { DefinitionBundle } from '../blueprint/model'
 
+/** A row of `GET /v1/blueprint/markings`. */
+export interface MarkingRow {
+  marking: string
+  displayName: string | null
+  description: string | null
+}
+
+/** Who a marking is granted to. A role is named; the other kinds are ids. */
+export interface MarkingPrincipal {
+  kind: 'workspace' | 'role' | 'user' | 'agent'
+  id: string
+}
+
 /**
  * Blueprint AUTHORING over HTTP.
  *
@@ -45,8 +58,18 @@ export class BlueprintAuthoringApi {
       // The credential failures worth telling apart, because each has a different
       // fix and a generic "request failed" sends the reader to the wrong one.
       // Shared with the other clients so the three of them cannot drift again.
+      // A lane refusal, worded before the generic credential one gets it — same
+      // reason as `workflow-api.ts`: "check the key's capability" cannot work on
+      // a route closed to organization keys, since no grant reopens it.
+      if (payload?.detail === 'org-key-route-closed') {
+        throw new CliError(`${path.split('?')[0]} is closed to organization keys by design`, {
+          code: (payload?.code as string) ?? 'FORBIDDEN',
+          hint: 'no grant on the key opens it — this needs a person’s session, or the platform',
+        })
+      }
       const credential = credentialFailure(res.status, payload?.message, {
         token: this.token,
+        code: payload?.code,
         whenSilent: "The key is not permitted to author this organization's Blueprint.",
       })
       if (credential) throw credential
@@ -514,6 +537,35 @@ export class BlueprintAuthoringApi {
     )
   }
 
+  // ── security markings: who may see which marked rows ─────────────────────
+
+  markings(): Promise<{ markings: MarkingRow[] }> {
+    return this.call('/v1/blueprint/markings')
+  }
+
+  createMarking(body: { marking: string; displayName?: string; description?: string }) {
+    return this.call<{ marking: string }>('/v1/blueprint/markings', { method: 'POST', body })
+  }
+
+  principalMarkings(principal: MarkingPrincipal): Promise<{ markings: string[] }> {
+    const query = new URLSearchParams({ principalKind: principal.kind, principalId: principal.id })
+    return this.call(`/v1/blueprint/markings/grants?${query}`)
+  }
+
+  grantMarking(marking: string, principal: MarkingPrincipal) {
+    return this.call('/v1/blueprint/markings/grants', {
+      method: 'POST',
+      body: { marking, principalKind: principal.kind, principalId: principal.id },
+    })
+  }
+
+  revokeMarking(marking: string, principal: MarkingPrincipal) {
+    return this.call('/v1/blueprint/markings/grants', {
+      method: 'DELETE',
+      body: { marking, principalKind: principal.kind, principalId: principal.id },
+    })
+  }
+
   // ── datasets: read-only, and reachable because the key holds `dataset:read` ─
 
   /**

package/src/api/credential-failure.ts

@@ -24,6 +24,10 @@ import { orgScopedServiceNouns } from '../scopes'
  * request leaves.
  */
 
+/** A person's session refused for permission: no key would help, a role would. */
+export const PERSON_FORBIDDEN_HINT =
+  'the signed-in person lacks the permission this needs — ask an administrator for a role that grants it'
+
 /** The lane split, which is the first thing to check and the easiest to miss. */
 function laneNote(token: string): string {
   // A workspace key is refused organization scope BY DESIGN — it is not a
@@ -48,13 +52,39 @@ function laneNote(token: string): string {
 export function credentialFailure(
   status: number,
   message: string | undefined,
-  opts: { token: string; capability?: string; whenSilent?: string },
+  opts: { token: string; code?: string; capability?: string; whenSilent?: string },
 ): CliError | null {
+  // A person's session, not a key: "the key may not carry the capability"
+  // sends its holder hunting for a credential they were never meant to use.
+  const person = !opts.token.startsWith('sk-')
+
   if (status === 401) {
+    return person
+      ? new CliError('The session token was refused — it has expired or been signed out.', {
+        code: 'UNAUTHORIZED',
+        hint: 'sign in again, then set FRONTERA_TOKEN to the new session token',
+      })
+      : new CliError(
+        'The credential was refused. An organization key that has been revoked or has '
+        + 'expired reads exactly like this — mint or rotate one in Settings → API keys.',
+        { code: 'UNAUTHORIZED', hint: 'frontera auth verify — then `frontera login --api-url <url>`' },
+      )
+  }
+
+  if (status === 403 && person) {
+    // Only the generic RBAC refusal is a missing role. A 403 with its own code
+    // — `ACTION_FORBIDDEN` for separation of duties, say — is a rule no role
+    // lifts, so its code and message go back to the caller untouched.
+    if (opts.code !== undefined && opts.code !== 'FORBIDDEN') return null
     return new CliError(
-      'The credential was refused. An organization key that has been revoked or has '
-      + 'expired reads exactly like this — mint or rotate one in Settings → API keys.',
-      { code: 'UNAUTHORIZED', hint: 'frontera auth verify — then `frontera login --api-url <url>`' },
+      // The service's own words; the hint below says what they mean.
+      message ?? 'The signed-in person is not permitted to reach that resource.',
+      {
+        code: 'FORBIDDEN',
+        hint: opts.capability
+          ? `the signed-in person needs ${opts.capability} — ask an administrator for a role that grants it`
+          : PERSON_FORBIDDEN_HINT,
+      },
     )
   }
 

package/src/api/dataset-api.ts

@@ -106,7 +106,7 @@ export class DatasetApi {
       // Datasets and sources are organization-scoped, so a workspace key is
       // refused here by design — and this client used to answer that with a
       // bare "Insufficient permissions" and no route out.
-      const credential = credentialFailure(response.status, payload?.message, { token: this.token })
+      const credential = credentialFailure(response.status, payload?.message, { token: this.token, code: payload?.code })
       if (credential) throw credential
       // `details` is TypeBox's own error array. Stringified it was unreadable,
       // and this is the last gate before a Source exists.

package/src/api/governed-action-api.ts

@@ -38,6 +38,22 @@ export interface ActionRequestSummary {
   deadlineAt?: string | null
 }
 
+/** A row of `GET /v1/blueprint/governed-actions/discovery`. */
+export interface ActionDiscovery {
+  actionDefinitionId: string
+  apiName: string
+  displayName?: string
+  description?: string
+  /** `existing` Actions act on one object, named by `subjectRef`. */
+  subject?: { mode?: string; objectTypeId?: string }
+  approval?: { mode?: string; threshold?: number; separationOfDuties?: boolean }
+  /** JSON Schema of the invocation envelope: `input`, `subjectRef`, `reason`… */
+  inputSchema?: {
+    required?: string[]
+    properties?: { input?: { required?: string[]; properties?: Record<string, unknown> } }
+  }
+}
+
 export class GovernedActionApi {
   /**
    * `workspaceId` for the one verb on this plane that needs it: the deployment
@@ -60,10 +76,16 @@ export class GovernedActionApi {
     }
   }
 
-  private async call<T>(path: string, init: { method?: string; body?: unknown } = {}): Promise<T> {
+  private async call<T>(
+    path: string,
+    init: { method?: string; body?: unknown; headers?: Record<string, string> } = {},
+  ): Promise<T> {
     const response = await fetch(`${this.apiUrl}${path}`, {
       method: init.method ?? 'GET',
-      headers: this.headers(init.body === undefined ? {} : { 'content-type': 'application/json' }),
+      headers: this.headers({
+        ...(init.body === undefined ? {} : { 'content-type': 'application/json' }),
+        ...init.headers,
+      }),
       ...(init.body === undefined ? {} : { body: JSON.stringify(init.body) }),
     })
     const text = await response.text()
@@ -72,11 +94,14 @@ export class GovernedActionApi {
 
     if (!response.ok) {
       const body = payload as { message?: string; code?: string; details?: unknown } | null
-      const credential = credentialFailure(response.status, body?.message, { token: this.token })
+      const credential = credentialFailure(response.status, body?.message, { token: this.token, code: body?.code })
       if (credential) throw credential
       throw new CliError(body?.message ?? `${response.status} from ${path}`, {
         code: body?.code ?? 'FAILURE',
         ...(body?.details ? { hint: JSON.stringify(body.details) } : {}),
+        // The status is what separates "refused" from "unknown": `action
+        // submit` offers a retry only for the second.
+        cause: { status: response.status, details: body?.details },
       })
     }
     const envelope = payload as Envelope<T>
@@ -93,10 +118,9 @@ export class GovernedActionApi {
    * neither says whether anything has ever run through it, or what happened
    * when it did.
    *
-   * Reads only. Invoking stays absent for the reason this module's header
-   * gives — both CLI credential kinds present a non-member principal, and the
-   * invoke check joins organization membership. The LIST gate is different:
-   * `actionRequest: ['read']`, which a key can hold.
+   * The LIST gate is `actionRequest: ['read']`, which a workspace key can hold
+   * — unlike invoking, whose check joins organization membership and so needs
+   * a session (see `submit` below).
    *
    * `nextCursor` rides on the envelope beside `data`, so this cannot go
    * through `call` — that unwraps to `data` and would drop the cursor,
@@ -126,6 +150,7 @@ export class GovernedActionApi {
       // needs; the shared mapper adds the lane note the bare hint was missing.
       const credential = credentialFailure(response.status, body?.message, {
         token: this.token,
+        code: body?.code,
         capability: 'actionRequest:read',
       })
       if (credential) throw credential
@@ -147,6 +172,49 @@ export class GovernedActionApi {
     return this.call(`/v1/blueprint/governed-actions/requests/${encodeURIComponent(requestId)}`)
   }
 
+  /**
+   * The Actions THIS caller may invoke, with the input schema each one takes.
+   *
+   * Filtered by the same membership check submit runs, per Action, and a
+   * refused Action is skipped rather than reported: the service answers a
+   * workspace key with an empty list, not a refusal. The verbs on this half of
+   * the plane are session-lane, so the dispatcher refuses a key before it asks.
+   */
+  discover(): Promise<ActionDiscovery[]> {
+    return this.call('/v1/blueprint/governed-actions/discovery')
+  }
+
+  /**
+   * Raise a request against a deployed Action.
+   *
+   * The key is the caller's, not ours: the service answers a repeated key with
+   * the request it already made, which is what makes a retry after a timeout
+   * safe — and only if the retry sends the same key.
+   */
+  submit(apiName: string, invocation: Record<string, unknown>, idempotencyKey: string): Promise<ActionRequestSummary> {
+    return this.call(`/v1/blueprint/governed-actions/actions/${encodeURIComponent(apiName)}/requests`, {
+      method: 'POST',
+      body: { invocation },
+      headers: { 'idempotency-key': idempotencyKey },
+    })
+  }
+
+  decideApproval(requestId: string, decision: 'approve' | 'reject', reason: string): Promise<{
+    approval: Record<string, unknown>
+    request: ActionRequestSummary
+  }> {
+    return this.call(`/v1/blueprint/governed-actions/requests/${encodeURIComponent(requestId)}/approvals`, {
+      method: 'POST',
+      body: { decision, reason },
+    })
+  }
+
+  cancelRequest(requestId: string): Promise<ActionRequestSummary> {
+    return this.call(`/v1/blueprint/governed-actions/requests/${encodeURIComponent(requestId)}/cancel`, {
+      method: 'POST',
+    })
+  }
+
   /** The published Action: its definition and the digest a Binding pins. */
   publishedAction(apiName: string): Promise<{
     definition: PublishedActionDefinition

package/src/api/media-api.ts

@@ -0,0 +1,181 @@
+import { CliError } from '../errors'
+import { organizationHeaders } from '../organization'
+import { credentialFailure } from './credential-failure'
+import { formatValidationDetails } from './validation-detail'
+
+/**
+ * Media Sets, from the CLI: create a set, fill it from local files, switch its
+ * processing on, watch it finish, and grant it to a workspace.
+ *
+ * SESSION ONLY (`authLane: 'session'` on every verb). The router accepts
+ * programmatic auth, but its direct plane asks ORGANIZATION-scoped permissions
+ * a workspace key cannot satisfy, and it is closed to organization keys. The
+ * dispatcher words that refusal once for every session-lane noun.
+ */
+
+interface Options {
+  method?: string
+  body?: unknown
+  /** Multipart. Never set alongside `body` — the two choose different content types. */
+  form?: FormData
+}
+
+export interface MediaSet {
+  id: string
+  apiName: string
+  displayName: string
+  description?: string | null
+  createdAt?: string
+  itemCount?: number
+}
+
+export interface MediaItem {
+  mediaItemId: string
+  path: string
+  mimeType: string
+  sizeBytes: number
+  version: number
+  isLatest: boolean
+  supersedesMediaItemId?: string | null
+  createdAt?: string
+}
+
+export interface ExtractionStatus {
+  extraction: { extractEnabled: boolean; extractProfile: 'text' | 'ocr'; ocrModel?: string }
+  coverage: { ready: number; pending: number; failed: number; skipped: number; items: number }
+}
+
+export interface ChunkingStatus {
+  chunking: { chunkEnabled: boolean; embedEnabled: boolean; embedModel: string | null }
+  coverage: {
+    ready: number
+    pending: number
+    failed: number
+    skipped: number
+    extracts: number
+    chunks: number
+    embedded: number
+    truncated: number
+    embedFailed: number
+    embedPending: number
+  }
+}
+
+export interface ChunkMatch {
+  chunkId: string
+  mediaItemId: string
+  path: string
+  ordinal: number
+  text: string
+  distance: number
+}
+
+export class MediaApi {
+  constructor(
+    private readonly apiUrl: string,
+    private readonly token: string,
+    /** Sent as `x-workspace-id`: a non-administrator sees only the sets granted to it. */
+    private readonly workspaceId?: string,
+  ) {}
+
+  private async call<T>(path: string, options: Options = {}): Promise<T> {
+    const response = await fetch(`${this.apiUrl}/v1/media${path}`, {
+      method: options.form ? 'POST' : (options.method ?? 'GET'),
+      headers: {
+        Authorization: `Bearer ${this.token}`,
+        ...organizationHeaders(),
+        ...(this.workspaceId ? { 'x-workspace-id': this.workspaceId } : {}),
+        // Never set for multipart: `fetch` writes the boundary itself.
+        ...(options.body === undefined ? {} : { 'Content-Type': 'application/json' }),
+      },
+      ...(options.form ? { body: options.form } : {}),
+      ...(options.body === undefined ? {} : { body: JSON.stringify(options.body) }),
+    })
+    const text = await response.text()
+    let payload: { data?: unknown; message?: string; code?: string; details?: unknown } | null
+    try { payload = text ? JSON.parse(text) : null } catch { payload = null }
+
+    if (!response.ok) {
+      const credential = credentialFailure(response.status, payload?.message, { token: this.token, code: payload?.code })
+      if (credential) throw credential
+      const detail = formatValidationDetails(payload?.details)
+      throw new CliError(payload?.message ?? `Request failed (${response.status}).`, {
+        code: payload?.code ?? 'FAILURE',
+        ...(detail ? { hint: detail } : {}),
+      })
+    }
+    return (payload?.data ?? payload) as T
+  }
+
+  private set(mediaSetId: string): string {
+    return `/sets/${encodeURIComponent(mediaSetId)}`
+  }
+
+  async list(): Promise<MediaSet[]> {
+    return (await this.call<{ mediaSets: MediaSet[] }>('/sets')).mediaSets
+  }
+
+  /** Ready items, newest first, as the calling workspace may see them. */
+  async items(mediaSetId: string): Promise<MediaItem[]> {
+    return (await this.call<{ items: MediaItem[] }>(`${this.set(mediaSetId)}/items`)).items
+  }
+
+  async create(body: { apiName: string; displayName: string; description?: string }): Promise<MediaSet> {
+    return (await this.call<{ mediaSet: MediaSet }>('/sets', { method: 'POST', body })).mediaSet
+  }
+
+  /**
+   * One file into the set. `logicalPath` is the item's identity inside the
+   * set: uploading to a path that already holds a file makes a new VERSION of
+   * it, not a second item.
+   */
+  async upload(
+    mediaSetId: string,
+    file: { bytes: Uint8Array; filename: string; mime: string; logicalPath: string; markings?: string },
+  ): Promise<MediaItem> {
+    const form = new FormData()
+    form.set('file', new File([new Blob([file.bytes.buffer as ArrayBuffer])], file.filename, { type: file.mime }))
+    form.set('logicalPath', file.logicalPath)
+    if (file.markings) form.set('markings', file.markings)
+    return (await this.call<{ item: MediaItem }>(`${this.set(mediaSetId)}/items`, { form })).item
+  }
+
+  extraction(mediaSetId: string): Promise<ExtractionStatus> {
+    return this.call(`${this.set(mediaSetId)}/extraction`)
+  }
+
+  chunking(mediaSetId: string): Promise<ChunkingStatus> {
+    return this.call(`${this.set(mediaSetId)}/chunking`)
+  }
+
+  setExtraction(mediaSetId: string, body: { enabled: boolean; profile?: 'text' | 'ocr' }): Promise<unknown> {
+    return this.call(`${this.set(mediaSetId)}/extraction`, { method: 'PUT', body })
+  }
+
+  setChunking(mediaSetId: string, body: { enabled: boolean; embed?: { enabled: boolean } }): Promise<unknown> {
+    return this.call(`${this.set(mediaSetId)}/chunking`, { method: 'PUT', body })
+  }
+
+  retryExtraction(mediaSetId: string): Promise<{ retried: number }> {
+    return this.call(`${this.set(mediaSetId)}/extraction/retry`, { method: 'POST' })
+  }
+
+  retryChunking(mediaSetId: string): Promise<{ retried: { chunking: number; embedding: number } }> {
+    return this.call(`${this.set(mediaSetId)}/chunking/retry`, { method: 'POST' })
+  }
+
+  search(
+    mediaSetId: string,
+    body: { query: string; limit?: number; maxDistance?: number },
+  ): Promise<{ model: string; matches: ChunkMatch[] }> {
+    return this.call(`${this.set(mediaSetId)}/chunks/search`, { method: 'POST', body })
+  }
+
+  grant(mediaSetId: string, body: { workspaceId: string; permissions?: string[] }): Promise<{ permissions: string[] }> {
+    return this.call(`${this.set(mediaSetId)}/grants`, { method: 'POST', body })
+  }
+
+  revoke(mediaSetId: string, workspaceId: string): Promise<{ revoked: boolean }> {
+    return this.call(`${this.set(mediaSetId)}/grants/${encodeURIComponent(workspaceId)}`, { method: 'DELETE' })
+  }
+}

package/src/api/platform-api.ts

@@ -196,6 +196,65 @@ export class PlatformApi {
     return this.getList<unknown>('/v1/platform-apps/')
   }
 
+  // ── Chat Apps ─────────────────────────────────────────────────────────────
+
+  /**
+   * Create a Chat App, or return the one already holding this slug.
+   *
+   * The same upsert `app deploy` uses, with `kind: 'chat'`. The service refuses
+   * a slug held by a Custom App rather than converting it.
+   */
+  ensureChatApp(body: { slug: string; displayName: string; description?: string; accent?: string }) {
+    return this.client.request<{ id: string; slug: string; created: boolean }>('/v1/platform-apps/ensure', {
+      method: 'POST',
+      body: { ...body, kind: 'chat' },
+    })
+  }
+
+  /** Draft, live version, audience, endpoints and validation findings. */
+  chatAppEditor(appId: string) {
+    return this.get<unknown>(`/v1/chat-apps/${encodeURIComponent(appId)}/editor`)
+  }
+
+  /** Drafts are per principal: a key's draft is its own, not a person's. */
+  saveChatAppDraft(appId: string, configuration: unknown) {
+    return this.client.request<unknown>(`/v1/chat-apps/${encodeURIComponent(appId)}/draft`, {
+      method: 'PUT',
+      body: { configuration },
+    })
+  }
+
+  /** Without `configuration`, publishes the caller's saved draft. */
+  publishChatApp(appId: string, body: { configuration?: unknown; dryRun?: boolean }) {
+    return this.client.request<unknown>(`/v1/chat-apps/${encodeURIComponent(appId)}/publish`, {
+      method: 'POST',
+      body,
+    })
+  }
+
+  /** Replaces the whole audience. No grants closes the App to everyone. */
+  setChatAppAccess(
+    appId: string,
+    grants: Array<{ principalKind: 'workspace' | 'user' | 'group'; principalId?: string }>,
+  ) {
+    return this.client.request<unknown>(`/v1/chat-apps/${encodeURIComponent(appId)}/access`, {
+      method: 'PUT',
+      body: { grants },
+    })
+  }
+
+  setChatAppEndpoint(appId: string, kind: 'platform' | 'standalone' | 'widget', enabled: boolean) {
+    return this.client.request<unknown>(
+      `/v1/chat-apps/${encodeURIComponent(appId)}/endpoints/${kind}`,
+      { method: 'PUT', body: { enabled } },
+    )
+  }
+
+  /** Workspace members — the user ids an access grant names. */
+  chatAppMembers(appId: string) {
+    return this.getList<unknown>(`/v1/chat-apps/${encodeURIComponent(appId)}/members`)
+  }
+
   /** `{ agentId, revision, snapshot }`, or null when nothing is staged. */
   async agentDraft(id: string): Promise<AgentDraft | null> {
     // Wrapped twice: `ok({ data: … })` around the SDK's own envelope.

package/src/api/workflow-api.ts

@@ -178,7 +178,7 @@ export class WorkflowApi {
             + 'credential runs as is still open, so no capability on an organization key opens this.',
         })
       }
-      const credential = credentialFailure(response.status, body?.message, { token: this.token })
+      const credential = credentialFailure(response.status, body?.message, { token: this.token, code: body?.code })
       if (credential) throw credential
       // A rejected definition carries its reasons in `details.errors`, and they
       // are the whole answer — a caller told only "Invalid workflow definition"

package/src/auth-verify.ts

@@ -25,7 +25,7 @@ export function classifyKey(token: string): CredentialKind {
   throw new UsageError(
     'that does not look like a Frontera key',
     'workspace keys start with sk-ws- (Workspace settings → API Keys); '
-    + 'organization keys start with sk-org- (Settings → API keys)',
+    + 'organization keys start with sk-org- (Organization settings → API Keys)',
   )
 }
 

package/src/commands/action/available.ts

@@ -0,0 +1,59 @@
+import { GovernedActionApi } from '../../api/governed-action-api'
+import { table } from '../../table'
+import type { Command } from '../types'
+
+/**
+ * The Actions this caller may submit, and what each one takes.
+ *
+ * Not `action list`: that is the organization's catalog and its deployment
+ * state, whoever is asking. This is one person's view in one workspace —
+ * every Action whose capability, subject grant and deployment all line up for
+ * them. An Action in `list` and missing here is the gap to chase.
+ */
+export const actionAvailable: Command = {
+  meta: {
+    noun: 'action',
+    verb: 'available',
+    // Invoking needs a person: the check joins organization and workspace
+    // membership. The service would answer a key with an empty list, so the
+    // dispatcher refuses a key before the request.
+    authLane: 'session',
+    scope: 'workspace' as const,
+    args: [],
+    flags: {},
+    summary: 'List the Actions you can submit in this workspace, and their inputs',
+    examples: ['frontera action available', 'frontera action available --json'],
+  },
+
+  async run(ctx) {
+    const actions = await new GovernedActionApi(ctx.apiUrl, ctx.token, ctx.workspaceId).discover()
+
+    if (actions.length === 0) {
+      return {
+        data: { actions: [] },
+        text: 'No Actions you can submit here.\n'
+          + '  `frontera action list` shows what is published and deployed; an Action there\n'
+          + '  and not here is missing a capability grant or a subject grant for you.',
+      }
+    }
+
+    return {
+      data: { actions },
+      text: table(
+        ['ACTION', 'SUBJECT', 'APPROVAL', 'INPUTS'],
+        actions.map((a) => [
+          a.apiName,
+          a.subject?.mode ?? '',
+          a.approval?.mode === 'none' || !a.approval?.mode
+            ? 'none'
+            : `${a.approval.mode} ×${a.approval.threshold ?? 1}`,
+          // Required ones marked: the envelope refuses a missing one without
+          // naming it, so this is the only place the name is visible.
+          Object.keys(a.inputSchema?.properties?.input?.properties ?? {})
+            .map((name) => (a.inputSchema?.properties?.input?.required ?? []).includes(name) ? `${name}*` : name)
+            .join(' '),
+        ]),
+      ),
+    }
+  },
+}

package/src/commands/action/cancel.ts

@@ -0,0 +1,34 @@
+import { GovernedActionApi } from '../../api/governed-action-api'
+import { UsageError } from '../../errors'
+import type { Command } from '../types'
+import { requestSummary } from './request-summary'
+
+/**
+ * Withdraw a request before it runs.
+ *
+ * Only while nothing has been attempted: `awaiting_approval` or `ready`, never
+ * dispatched. Anything later answers 409 "can no longer be cancelled", because
+ * an effect may already be on the far side. Cancelling twice is a no-op.
+ * Session-lane: the cancel gate locks the caller's workspace membership.
+ */
+export const actionCancel: Command = {
+  meta: {
+    noun: 'action',
+    verb: 'cancel',
+    authLane: 'session',
+    scope: 'workspace' as const,
+    args: [{ name: 'requestId', required: true, description: 'The request to cancel' }],
+    flags: {},
+    summary: 'Cancel an Action request that has not run yet',
+    examples: ['frontera action cancel <requestId>'],
+  },
+
+  async run(ctx) {
+    const requestId = ctx.positional[0]
+    if (!requestId) {
+      throw new UsageError('missing <requestId>', 'frontera action requests — to find it')
+    }
+    const request = await new GovernedActionApi(ctx.apiUrl, ctx.token, ctx.workspaceId).cancelRequest(requestId)
+    return { data: request, text: requestSummary(request) }
+  },
+}