@frontera-sdk/cli 1.50.18 → 1.50.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontera-sdk/cli",
-  "version": "1.50.18",
+  "version": "1.50.20",
   "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.18",
-    "@frontera-sdk/core": "1.50.18",
+    "@frontera-sdk/functions": "1.50.20",
+    "@frontera-sdk/core": "1.50.20",
     "ai": "^6.0.116",
     "gray-matter": "^4.0.3",
     "yaml": "^2.9.0"
   },
   "devDependencies": {
-    "@frontera-sdk/forge-contracts": "1.50.18",
+    "@frontera-sdk/forge-contracts": "1.50.20",
     "@types/bun": "^1.3.14",
     "typescript": "^5.9.3"
   }

package/src/api/platform-api.ts

@@ -689,12 +689,7 @@ export class PlatformApi {
    * chain from here is `agent apply` then `agent publish`, and both resolve a
    * slug through `GET /config/agents/:ref`, which does see it.
    */
-  createAgent(body: {
-    agentId: string
-    name?: string
-    description?: string
-    kind?: 'conversation' | 'work'
-  }) {
+  createAgent(body: { agentId: string; name?: string; description?: string }) {
     return this.client.request<unknown>('/v1/config/agents', { method: 'POST', body })
   }
 

package/src/api/workflow-api.ts

@@ -0,0 +1,272 @@
+import { CliError } from '../errors'
+import { credentialFailure } from './credential-failure'
+
+/**
+ * `/v1/workflows`.
+ *
+ * The routes were built for this client and shipped without it: the router's
+ * own header says "a workspace key can push from the CLI", and
+ * `pushWorkflowVersion` defaults `createdVia` to `'cli'` — a value nothing
+ * could produce. Everything here is workspace-grain; organization keys are
+ * closed at the service by decision, so there is no org lane to carry.
+ */
+
+interface Envelope<T> { error?: boolean; data?: T; message?: string }
+
+/** A row of `GET /v1/workflows`. */
+export interface WorkflowSummary {
+  id: string
+  slug: string
+  enabled: boolean
+  description: string | null
+  liveVersion: number | null
+  latestDraftNumber: number | null
+  versionCount: number
+  runCount: number
+  lastRunAt: string | null
+  lastRunStatus: string | null
+  triggerKinds: string[]
+  cron: string | null
+  subjectApiName: string | null
+  subjectLabel: string | null
+}
+
+/** A row of `GET /v1/workflows/:slug/versions`. */
+export interface VersionSummary {
+  id: string
+  number: number
+  status: string
+  createdAt: string
+  createdVia?: string | null
+}
+
+/**
+ * What a push answers with.
+ *
+ * `ok: false` is a RESULT, not a transport failure — but only on a dry run.
+ * A real push that fails validation comes back as a 400, so `push` and
+ * `validate` read the same errors from two different places. Modelling both
+ * here keeps that asymmetry in one file instead of in every caller.
+ */
+export interface PushResult {
+  ok: boolean
+  errors?: string[]
+  workflowId?: string
+  version?: { id: string; number: number; status: string }
+  grants?: string[]
+  lineage?: LineageEdge[]
+}
+
+export interface LineageEdge {
+  kind: string
+  resourceKind: string
+  resourceId: string
+  label?: string | null
+  property?: string | null
+  nodeId?: string | null
+}
+
+export interface VersionLineage {
+  version: number
+  status: string
+  grants: string[]
+  lineage: LineageEdge[]
+}
+
+/** A row of `GET /v1/workflows/:slug/runs`. */
+export interface RunSummary {
+  id: string
+  status: string
+  versionNumber: number
+  workflowSlug: string
+  triggerSource: string
+  triggeredByName: string | null
+  subjectPk: string | null
+  subjectLabel: string | null
+  nodeCalls: number
+  startedAt: string
+  endedAt: string | null
+  error: unknown
+}
+
+export interface RunTreeNode {
+  nodeId: string
+  nodePath: string
+  kind: string
+  status: string
+  attempt: number
+  output: unknown
+  error: unknown
+  startedAt: string
+  endedAt: string | null
+  childRun?: RunTree | null
+}
+
+export interface RunTree {
+  id: string
+  slug: string
+  status: string
+  versionNumber: number | null
+  triggerSource: string
+  subject: { pk: string; apiName: string | null; label: string | null } | null
+  input: Record<string, unknown>
+  output: unknown
+  error: unknown
+  nodeCalls: number
+  startedAt: string
+  endedAt: string | null
+  nodes: RunTreeNode[]
+}
+
+export interface RunRequest {
+  input?: Record<string, unknown>
+  subject?: { pk: string }
+  version?: number
+}
+
+export class WorkflowApi {
+  constructor(
+    private readonly apiUrl: string,
+    private readonly token: string,
+    private readonly workspaceId?: string,
+  ) {}
+
+  private headers(extra: Record<string, string> = {}): Record<string, string> {
+    return {
+      authorization: `Bearer ${this.token}`,
+      ...(this.workspaceId ? { 'x-workspace-id': this.workspaceId } : {}),
+      ...extra,
+    }
+  }
+
+  private async call<T>(path: string, init: { method?: string; body?: unknown } = {}): Promise<T> {
+    const response = await fetch(`${this.apiUrl}${path}`, {
+      method: init.method ?? 'GET',
+      headers: this.headers(init.body === undefined ? {} : { 'content-type': 'application/json' }),
+      ...(init.body === undefined ? {} : { body: JSON.stringify(init.body) }),
+    })
+    const text = await response.text()
+    let payload: unknown
+    try { payload = text ? JSON.parse(text) : null } catch { payload = null }
+
+    if (!response.ok) {
+      const body = payload as { message?: string; code?: string; details?: unknown; detail?: string } | null
+      // The lane refusal, worded before the generic credential one gets it.
+      // `/v1/workflows` is closed to organization keys by decision, and the
+      // shared `credentialFailure` renders that 403 as "check the key carries
+      // the capability … its workspace list" — advice that cannot work, since
+      // no grant reopens a closed lane. The service names the case in
+      // `detail`; nothing read it until now.
+      if (body?.detail === 'org-key-route-closed') {
+        throw new CliError('workflows are closed to organization keys', {
+          code: 'FORBIDDEN',
+          hint: 'use a workspace key (sk-ws-) — `frontera auth list` shows which kind each profile holds. '
+            + 'A manual run executes the workflow\'s derived grants, and which principal a machine '
+            + '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 })
+      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"
+      // has to re-push with `validate` to find out what was wrong.
+      const errors = readDefinitionErrors(body?.details)
+      if (errors) throw new CliError(body?.message ?? 'Invalid workflow definition', {
+        code: 'INVALID_DEFINITION',
+        hint: errors.join('\n  '),
+      })
+      throw new CliError(body?.message ?? `${response.status} from ${path}`, {
+        code: body?.code ?? 'FAILURE',
+        ...(body?.details ? { hint: JSON.stringify(body.details) } : {}),
+      })
+    }
+    const envelope = payload as Envelope<T>
+    return (envelope && envelope.error === false && 'data' in envelope
+      ? envelope.data
+      : payload) as T
+  }
+
+  list(): Promise<WorkflowSummary[]> {
+    return this.call<WorkflowSummary[]>('/v1/workflows')
+  }
+
+  get(slug: string): Promise<WorkflowSummary> {
+    return this.call<WorkflowSummary>(`/v1/workflows/${encodeURIComponent(slug)}`)
+  }
+
+  /**
+   * The version list, narrowed to the fields the CLI shows.
+   *
+   * The route answers with whole `workflow_versions` rows — `definition`,
+   * `grants`, `lineage` and `inputSchema` for EVERY version — so returning
+   * them unchanged would make `workflow get <slug> --json` dump every
+   * definition the workflow has ever had. Projected here rather than at the
+   * render site, so the `--json` contract is the same shape the table is.
+   * `workflow lineage <slug> <n>` is the verb for reading one version's body.
+   */
+  async versions(slug: string): Promise<VersionSummary[]> {
+    const rows = await this.call<VersionSummary[]>(`/v1/workflows/${encodeURIComponent(slug)}/versions`)
+    return rows.map((v) => ({
+      id: v.id,
+      number: v.number,
+      status: v.status,
+      createdAt: v.createdAt,
+      createdVia: v.createdVia ?? null,
+    }))
+  }
+
+  /**
+   * Push a definition as a new draft, or — with `dryRun` — validate it and
+   * write nothing.
+   *
+   * The definition goes up as the raw body. There is no `{ definition: … }`
+   * wrapper: the route passes `ctx.body` straight to the parser, so a wrapper
+   * would fail validation on every field at once.
+   */
+  push(slug: string, definition: unknown, opts: { dryRun?: boolean } = {}): Promise<PushResult> {
+    const query = opts.dryRun ? '?dryRun=true' : ''
+    return this.call<PushResult>(`/v1/workflows/${encodeURIComponent(slug)}/versions${query}`, {
+      method: 'PUT',
+      body: definition,
+    })
+  }
+
+  promote(slug: string, number: number): Promise<{ id: string; number: number; status: string }> {
+    return this.call(`/v1/workflows/${encodeURIComponent(slug)}/versions/${number}/promote`, { method: 'POST' })
+  }
+
+  lineage(slug: string, number: number): Promise<VersionLineage> {
+    return this.call<VersionLineage>(`/v1/workflows/${encodeURIComponent(slug)}/versions/${number}/lineage`)
+  }
+
+  run(slug: string, body: RunRequest): Promise<{ runId: string; versionNumber: number; reused?: boolean }> {
+    return this.call(`/v1/workflows/${encodeURIComponent(slug)}/run`, { method: 'POST', body })
+  }
+
+  /**
+   * The newest runs, at the service's default page size.
+   *
+   * The route also takes `limit` and a `before` keyset cursor; neither is
+   * carried here, because no verb pages yet and a parameter no caller passes
+   * reads as a capability the CLI has. `function runs` is capped the same way.
+   */
+  runs(slug: string): Promise<RunSummary[]> {
+    return this.call<RunSummary[]>(`/v1/workflows/${encodeURIComponent(slug)}/runs`)
+  }
+
+  /** One run and, with `depth: 'all'`, the child runs beneath it. */
+  runById(id: string, depth: 'run' | 'all' = 'all'): Promise<RunTree> {
+    return this.call<RunTree>(`/v1/workflows/runs/${encodeURIComponent(id)}?depth=${depth}`)
+  }
+
+  cancel(id: string): Promise<{ status: string }> {
+    return this.call(`/v1/workflows/runs/${encodeURIComponent(id)}/cancel`, { method: 'POST' })
+  }
+}
+
+/** `details.errors` from a 400, when the failure was the definition itself. */
+function readDefinitionErrors(details: unknown): string[] | null {
+  const errors = (details as { errors?: unknown } | null)?.errors
+  if (!Array.isArray(errors) || errors.length === 0) return null
+  return errors.map((e) => (typeof e === 'string' ? e : JSON.stringify(e)))
+}

package/src/commands/agent/compose.ts

@@ -18,7 +18,7 @@ export interface Lookups {
   /** workspace skill id → readable name. */
   skills: Map<string, string>
   /** Identity the snapshot's config does not carry. */
-  identity?: { id?: string; slug?: string; kind?: string; version?: number }
+  identity?: { id?: string; slug?: string; version?: number }
 }
 
 function arr(value: unknown): Row[] {
@@ -55,7 +55,6 @@ export function renderComposition(snapshot: Row, lookups: Lookups): string {
   for (const [k, v] of [
     ['slug', str(config, 'agentId') || (lookups.identity?.slug ?? '')],
     ['id', str(config, 'id') || (lookups.identity?.id ?? '')],
-    ['kind', str(config, 'kind') || (lookups.identity?.kind ?? '')],
     ['status', str(config, 'lifecycleStatus')],
     ['default mode', str(config, 'defaultMode')],
     ['live version', lookups.identity?.version ? String(lookups.identity.version) : ''],

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

@@ -31,7 +31,7 @@ async function target(ctx: CommandContext, verb: string): Promise<{ api: Platfor
  */
 async function buildLookups(
   client: PlatformApi,
-  identity?: { id?: string; slug?: string; kind?: string },
+  identity?: { id?: string; slug?: string },
 ): Promise<Lookups> {
   const [plugins, knowledge, skills] = await Promise.all([
     client.pluginInstalls().catch(() => [] as unknown[]),
@@ -107,12 +107,9 @@ const create: Command = {
         description: 'lowercase slug every other agent command takes, e.g. claims-triage',
       },
     ],
-    flags: { name: 'string', description: 'string', kind: 'string' },
+    flags: { name: 'string', description: 'string' },
     summary: 'Create an agent, ready for `agent apply` and `agent publish`',
-    examples: [
-      'frontera agent create claims-triage --name "Claims Triage"',
-      'frontera agent create nightly-extract --kind work',
-    ],
+    examples: ['frontera agent create claims-triage --name "Claims Triage"'],
   },
   async run(ctx) {
     const slug = ctx.positional[0]
@@ -126,11 +123,6 @@ const create: Command = {
       )
     }
 
-    const kind = flagString(ctx, 'kind')
-    if (kind && kind !== 'conversation' && kind !== 'work') {
-      throw new UsageError(`unknown --kind "${kind}"`, 'conversation (default) or work')
-    }
-
     const client = api(ctx)
 
     // Checked before the write: the service answers a duplicate slug from deep
@@ -153,7 +145,6 @@ const create: Command = {
       agentId: slug,
       ...(name ? { name } : {}),
       ...(description ? { description } : {}),
-      ...(kind ? { kind: kind as 'conversation' | 'work' } : {}),
     })) as { data?: AgentRow } | AgentRow
     const agent = ((row as { data?: AgentRow }).data ?? row) as AgentRow
 
@@ -188,8 +179,8 @@ const list: Command = {
           ? 'No agents in this workspace.'
           : // Either ID or SLUG works wherever an agent is named.
             table(
-              ['id', 'slug', 'kind', 'name'],
-              rows.map((a) => [a.id ?? '?', a.agentId ?? '', a.kind ?? '', a.name ?? '']),
+              ['id', 'slug', 'name'],
+              rows.map((a) => [a.id ?? '?', a.agentId ?? '', a.name ?? '']),
             ),
     }
   },
@@ -228,7 +219,7 @@ const get: Command = {
       // knowledge, plugins and channels are the reason to read an agent.
       // The lookups turn the snapshot's uuids into names — without them the
       // human output is a list of identifiers nobody can act on.
-      // The snapshot's config carries neither id, slug, kind nor the published
+      // The snapshot's config carries neither id, slug nor the published
       // version, so the config ROW is read alongside it. Two requests for a
       // complete picture beats one that silently omits what an agent is.
       const [snapshot, row, lookups] = await Promise.all([
@@ -239,7 +230,6 @@ const get: Command = {
       const identity = (row ?? {}) as {
         id?: string
         agentId?: string
-        kind?: string
         currentVersion?: { versionNumber?: number }
       }
       return {
@@ -249,7 +239,6 @@ const get: Command = {
           identity: {
             id: identity.id ?? t.id,
             slug: identity.agentId,
-            kind: identity.kind,
             version: identity.currentVersion?.versionNumber,
           },
         }),

package/src/commands/registry.ts

@@ -34,6 +34,7 @@ import { knowledgeCommands } from './knowledge/index-commands'
 import { packCommands } from './pack/index-commands'
 import { secretCommands } from './secret/index-commands'
 import { automationCommands } from './automation/index-commands'
+import { workflowCommands } from './workflow/index-commands'
 import { completionCommand } from './completion'
 import { initCommand } from './init'
 import { loginCommand } from './login'
@@ -98,6 +99,7 @@ export const COMMANDS: readonly Command[] = [
   ...packCommands,
   ...secretCommands,
   ...automationCommands,
+  ...workflowCommands,
 
   blueprintList,
   blueprintGet,
@@ -157,6 +159,7 @@ const NOUN_SUMMARY: Readonly<Record<string, string>> = {
   pack: 'Reusable skill bundles — author once, install per workspace',
   secret: 'Workspace secrets — named here, never printed back',
   function: 'Functions — TypeScript deployed here, run on a schedule',
+  workflow: 'Workflows — declared steps, versioned, promoted, then run',
   blueprint: 'The shared model of the organization — what an app can read',
   action: 'Governed Actions — arm the write path a published Action runs',
   capability: 'What an agent may DO — plugin operations granted to it',

package/src/commands/workflow/cancel.ts

@@ -0,0 +1,37 @@
+import { WorkflowApi } from '../../api/workflow-api'
+import type { Command } from '../types'
+import { requireRunId } from './run'
+
+/**
+ * Stop a run that is still going.
+ *
+ * Takes a run id and not a slug: cancelling "the workflow" is not a thing the
+ * engine can do — each run is cancelled on its own root id, and a slug would
+ * have to pick one silently.
+ *
+ * Cancellation propagates to child runs at the service, and a run that has
+ * already finished is a no-op rather than an error, so this is safe to call on
+ * an id read from a stale listing.
+ */
+export const workflowCancel: Command = {
+  meta: {
+    noun: 'workflow',
+    verb: 'cancel',
+    args: [{ name: 'runId', required: true, description: 'the run to stop' }],
+    flags: {},
+    summary: 'Stop a running workflow run, and the child runs beneath it',
+    examples: ['frontera workflow cancel 0f2c8b1e-7a41-4c96-9d3e-52b0c4a7e118'],
+  },
+
+  async run(ctx) {
+    const runId = requireRunId(ctx.positional[0])
+    const result = await new WorkflowApi(ctx.apiUrl, ctx.token, ctx.workspaceId).cancel(runId)
+    return {
+      data: result,
+      // The status is reported rather than assumed: a run that had already
+      // succeeded comes back `succeeded`, and printing "canceled" there would
+      // be a lie the caller acts on.
+      text: `${runId}: ${result.status}`,
+    }
+  },
+}

package/src/commands/workflow/get.ts

@@ -0,0 +1,57 @@
+import { WorkflowApi } from '../../api/workflow-api'
+import { table } from '../../table'
+import type { Command } from '../types'
+import { requireSlug } from './push'
+
+/**
+ * One workflow: what is live, what is drafted, and what it is bound to.
+ *
+ * The version table is here rather than under a separate `versions` verb
+ * because the two questions are never asked apart — "what is live" is only
+ * meaningful beside "what else exists", and `promote` needs a number from this
+ * list.
+ */
+export const workflowGet: Command = {
+  meta: {
+    noun: 'workflow',
+    verb: 'get',
+    args: [{ name: 'slug', required: true, description: 'workflow slug' }],
+    flags: {},
+    summary: 'Show one workflow, its versions and which is live',
+    examples: ['frontera workflow get invoice-intake'],
+  },
+
+  async run(ctx) {
+    const slug = requireSlug(ctx)
+    const client = new WorkflowApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
+    const [workflow, versions] = await Promise.all([client.get(slug), client.versions(slug)])
+
+    const facts = [
+      `${workflow.slug}${workflow.enabled ? '' : '  (disabled)'}`,
+      workflow.description ? `  ${workflow.description}` : '',
+      `  live       ${workflow.liveVersion === null ? 'nothing — no version has been promoted' : `v${workflow.liveVersion}`}`,
+      `  triggers   ${(workflow.triggerKinds ?? []).join(', ') || 'none'}`,
+      // Only when bound. An unbound workflow has no subject line to print, and
+      // an empty one reads as a missing value rather than an absent concept.
+      workflow.subjectApiName ? `  subject    ${workflow.subjectLabel ?? workflow.subjectApiName}` : '',
+      `  runs       ${workflow.runCount ?? 0}${workflow.lastRunStatus ? `, last ${workflow.lastRunStatus}` : ''}`,
+    ].filter(Boolean)
+
+    const versionTable = versions.length === 0
+      ? '  (none — `frontera workflow push` stores the first)'
+      : table(
+          ['VERSION', 'STATUS', 'PUSHED', 'VIA'],
+          versions.map((v) => [
+            `v${v.number}`,
+            v.status,
+            v.createdAt,
+            v.createdVia ?? '',
+          ]),
+        )
+
+    return {
+      data: { workflow, versions },
+      text: `${facts.join('\n')}\n\nVersions\n${versionTable}`,
+    }
+  },
+}

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

@@ -0,0 +1,41 @@
+import { workflowCancel } from './cancel'
+import { workflowGet } from './get'
+import { workflowLineage } from './lineage'
+import { workflowList } from './list'
+import { workflowPromote } from './promote'
+import { workflowPush, workflowValidate } from './push'
+import { workflowRun } from './run'
+import { workflowRuns } from './runs'
+import type { Command } from '../types'
+
+/**
+ * Workflows, which had no client at all.
+ *
+ * The routes were written for this: `/v1/workflows` authenticates through the
+ * same programmatic middleware Functions use so a workspace key can push, and
+ * `pushWorkflowVersion` stamps `createdVia: 'cli'` by default — an origin no
+ * caller could produce. Until now the only way to author a workflow was the
+ * Console, which means a definition could not be reviewed in a pull request or
+ * promoted from CI.
+ *
+ * Organization keys are deliberately absent, and that is the service's
+ * decision rather than an omission here: a manual run executes the workflow's
+ * derived grants, and which principal a machine credential runs as is the same
+ * open question that keeps `POST /v1/functions/:slug/run` undeclared. A key
+ * that pushed and promoted but could not run would be the more confusing half.
+ *
+ * Bindings are absent for a different reason: an agent binding is a standing
+ * permission for a model to start runs, it gates on `edit`, and it belongs
+ * beside the agent it grants — not beside the definition it points at.
+ */
+export const workflowCommands: readonly Command[] = [
+  workflowList,
+  workflowGet,
+  workflowValidate,
+  workflowPush,
+  workflowPromote,
+  workflowRun,
+  workflowRuns,
+  workflowCancel,
+  workflowLineage,
+]

package/src/commands/workflow/lineage.ts

@@ -0,0 +1,58 @@
+import { WorkflowApi } from '../../api/workflow-api'
+import { table } from '../../table'
+import type { Command } from '../types'
+import { requireSlug } from './push'
+import { requireVersionNumber } from './promote'
+
+/**
+ * What one version reads, writes and invokes.
+ *
+ * Derived from the definition at push time, never authored — which is exactly
+ * why it is worth printing. An author reads their own steps and sees intent;
+ * this reads the same steps and reports reach, and the two differ whenever a
+ * step touches something through a reference the author did not follow.
+ *
+ * The version is required rather than defaulting to live: "what does this
+ * touch" asked of a workflow with an unpromoted draft has two different
+ * answers, and guessing which one was meant is how a review misses a change.
+ */
+export const workflowLineage: Command = {
+  meta: {
+    noun: 'workflow',
+    verb: 'lineage',
+    args: [
+      { name: 'slug', required: true, description: 'workflow slug' },
+      { name: 'version', required: true, description: 'version number' },
+    ],
+    flags: {},
+    summary: 'What one version reads, writes and invokes — and the grants it runs with',
+    examples: ['frontera workflow lineage invoice-intake 3'],
+  },
+
+  async run(ctx) {
+    const slug = requireSlug(ctx)
+    const number = requireVersionNumber(ctx)
+    const lineage = await new WorkflowApi(ctx.apiUrl, ctx.token, ctx.workspaceId).lineage(slug, number)
+
+    const head = `${slug} v${lineage.version} (${lineage.status})\n`
+      + `  grants  ${lineage.grants.length > 0 ? lineage.grants.join(', ') : 'none'}`
+
+    if (lineage.lineage.length === 0) {
+      return { data: lineage, text: `${head}\n\n  This version touches nothing outside itself.` }
+    }
+
+    return {
+      data: lineage,
+      text: `${head}\n\n${table(
+        ['EDGE', 'KIND', 'RESOURCE', 'PROPERTY', 'STEP'],
+        lineage.lineage.map((e) => [
+          e.kind,
+          e.resourceKind,
+          e.label ?? e.resourceId,
+          e.property ?? '',
+          e.nodeId ?? '',
+        ]),
+      )}`,
+    }
+  },
+}