@frontera-sdk/cli 1.52.39 → 1.52.40

package/src/mcp/tools/workflow-tools.ts

@@ -0,0 +1,611 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { parse } from 'yaml'
+
+import type { RunTree, VersionSummary, WebhookListen } from '../../api/workflow-api'
+import { METRIC_GRAINS, metricQueryBody, metricRows, resolveRangeWindow, timeseriesOf, type MetricQueryResult } from '../../blueprint/metric-query'
+import type { LocalProject } from '../../local/local-project'
+import { errorResult, intArg, jsonResult, stringArg, type McpTool } from '../mcp-protocol'
+import { requireRuntime, serviceCall, studioLink, type RuntimeLink } from '../mcp-runtime'
+
+/**
+ * Run a workflow and read the Blueprint's records on the local runtime.
+ * Records are read only: writes go through the governed Actions an App or an
+ * Agent calls, never through MCP, so what the agent tests is the same path a
+ * person's request takes.
+ */
+
+const TERMINAL = new Set(['succeeded', 'failed', 'canceled', 'cancelled'])
+
+const OUTPUT_CLIP = 2_000
+
+const fits = (value: unknown) => (JSON.stringify(value) ?? 'null').length <= OUTPUT_CLIP
+
+/** A list cut to the items that fit, then how many were left out. */
+function cutList(list: unknown[], keep?: number): unknown[] {
+  let n = keep ?? list.length
+  while (n > 1 && !fits(list.slice(0, n))) n = Math.max(1, Math.floor(n / 2))
+  return n < list.length ? [...list.slice(0, n), `… ${list.length - n} more`] : list
+}
+
+/**
+ * A step's output as the answer carries it: whole when small; else its lists
+ * cut to their first items (so its shape and keys still show), else its JSON
+ * clipped; and said so.
+ */
+function shown(value: unknown): { output?: unknown; outputClipped?: true } {
+  if (value === undefined) return {}
+  if (fits(value)) return { output: value }
+  if (Array.isArray(value)) {
+    const cut = cutList(value)
+    if (fits(cut)) return { output: cut, outputClipped: true }
+  } else if (value && typeof value === 'object') {
+    const cut: Record<string, unknown> = { ...(value as Record<string, unknown>) }
+    const lists = Object.entries(cut).filter(([, v]) => Array.isArray(v)).sort(([, a], [, b]) => (JSON.stringify(b) ?? '').length - (JSON.stringify(a) ?? '').length)
+    for (const [key, list] of lists) {
+      if (fits(cut)) break
+      cut[key] = cutList(list as unknown[], 3)
+    }
+    if (fits(cut)) return { output: cut, outputClipped: true }
+  }
+  const text = JSON.stringify(value) ?? 'null'
+  return { output: `${text.slice(0, OUTPUT_CLIP)}… (${text.length - OUTPUT_CLIP} more characters; the run's link shows it whole)`, outputClipped: true }
+}
+
+/** A top-level step is one of the definition's own nodes ("/4:escalate"), not a node inside a branch, loop or parallel. */
+const isTopLevel = (path: string) => /^\/?\d+:[^/]+$/.test(path)
+
+/**
+ * One step as the agent reads it, with `output` as `$steps.<id>` reads it in
+ * an expression. A run records a `forEach` as `{ mode, count, results }`,
+ * while `$steps.<forEach>` is the bare `results` list: one entry per item,
+ * each that iteration's `$steps` keyed by the loop body's node ids (a
+ * failed iteration skipped with skipFailure is `{ error }`). So the loop's
+ * output is that list, and what the run view shows is beside it, labelled.
+ */
+export function describeStep(n: RunTree['nodes'][number]) {
+  const path = n.nodePath || n.nodeId
+  const base = { step: path, kind: n.kind, status: n.status, ...(n.error ? { error: n.error } : {}), ...(n.attempt > 1 ? { attempts: n.attempt } : {}) }
+  if (n.status === 'skipped') return { ...base, note: `skipped: $steps.${n.nodeId} has no entry` }
+  const recorded = n.output
+  if (n.kind === 'forEach' && recorded && typeof recorded === 'object' && !Array.isArray(recorded) && 'count' in recorded) {
+    const { results, ...rest } = recorded as { results?: unknown[]; count?: number; mode?: string }
+    const body = Array.isArray(results) ? results.find((r) => r && typeof r === 'object' && !('error' in r)) : undefined
+    const first = body ? Object.keys(body as object)[0] : undefined
+    return {
+      ...base,
+      ...(Array.isArray(results) ? shown(results) : {}),
+      recorded: rest,
+      reads: Array.isArray(results)
+        ? `$steps.${n.nodeId} is this list, not the run view's { mode, count, results }: one entry per item, each that iteration's $steps by body node id${first ? `, e.g. $steps.${n.nodeId}.${first} for every item's ${first} output, $steps.${n.nodeId}[0].${first} for the first` : ''}; a failed iteration skipped with skipFailure is { error }. $count($steps.${n.nodeId}) is the number of items.`
+        : `The loop failed before it finished, so it has no results: with continueOnError, $steps.${n.nodeId} is { error }.`,
+    }
+  }
+  return { ...base, ...(isTopLevel(path) ? {} : { inside: path.split('/').slice(0, -1).join('/') }), ...shown(recorded) }
+}
+
+function describe(run: RunTree) {
+  return {
+    runId: run.id,
+    workflow: run.slug,
+    status: run.status,
+    version: run.versionNumber,
+    output: run.output,
+    error: run.error ?? undefined,
+    // Each step's output is what `$steps.<id>` reads in an expression.
+    steps: run.nodes.map(describeStep),
+    startedAt: run.startedAt,
+    endedAt: run.endedAt,
+  }
+}
+
+/**
+ * The version a run asks for: a number as given, `draft` (or its synonym
+ * `latest`) for the newest version that is not retired — what `apply` last
+ * pushed, which is the live one when a person promoted it (promoting retires
+ * the older drafts) — or undefined for the live one.
+ */
+export function pickVersion(requested: unknown, versions: () => Promise<VersionSummary[]>, slug: string): Promise<number | undefined> | number | undefined {
+  if (requested === undefined || requested === null || requested === '') return undefined
+  const n = typeof requested === 'number' ? requested : /^\d+$/.test(String(requested).trim()) ? Number(String(requested).trim()) : NaN
+  if (Number.isFinite(n)) {
+    if (!Number.isInteger(n) || n < 1) throw new Error(`version must be a whole number from 1, "draft" or "latest"; got ${String(requested)}`)
+    return n
+  }
+  const word = String(requested).trim().toLowerCase()
+  if (word !== 'draft' && word !== 'latest') throw new Error(`version must be a whole number from 1, "draft" or "latest"; got "${String(requested)}"`)
+  return versions().then((rows) => {
+    const sorted = [...rows].sort((a, b) => b.number - a.number)
+    // Not "the newest with status draft": after a promotion the newest is live and its older drafts are retired.
+    const found = sorted.find((v) => v.status !== 'retired')
+    if (!found) {
+      throw new Error(
+        sorted.length
+          ? `Workflow "${slug}" has only retired versions on the local runtime (${sorted.map((v) => `${v.number} ${v.status}`).join(', ')}). Apply its file (\`frontera local dev --once\`), then run it with version "${word}".`
+          : `Workflow "${slug}" has no version on the local runtime yet. Apply its file first (\`frontera local dev --once\`).`,
+      )
+    }
+    return found.number
+  })
+}
+
+async function startRun(link: RuntimeLink, slug: string, body: Record<string, unknown>): Promise<{ runId: string; versionNumber: number }> {
+  try {
+    return await serviceCall<{ runId: string; versionNumber: number }>(link, `/v1/workflows/${encodeURIComponent(slug)}/run`, { body })
+  } catch (err) {
+    const message = (err as Error).message
+    // The runtime's words are about its API; the agent needs the argument to pass.
+    if (/answered 409/.test(message) && /no live version/i.test(message) && body.version === undefined) {
+      throw new Error(`Workflow "${slug}" has no live version on the local runtime. Pass version: "draft" to run the draft you applied (or a version number); promoting stays with a person.`)
+    }
+    throw err
+  }
+}
+
+/** Wait for a run to finish, at most until `deadline`: the run as it is then. */
+async function followRun(link: RuntimeLink, runId: string, deadline: number): Promise<{ run: RunTree; finished: boolean }> {
+  for (;;) {
+    const run = await serviceCall<RunTree>(link, `/v1/workflows/runs/${encodeURIComponent(runId)}?depth=run`)
+    if (TERMINAL.has(run.status)) return { run, finished: true }
+    if (Date.now() >= deadline) return { run, finished: false }
+    await new Promise((r) => setTimeout(r, 1_500))
+  }
+}
+
+/** The webhook door a delivery goes to: the one named by path, or the only one. */
+export function pickDoor(doors: WebhookListen['doors'], path: string | undefined): WebhookListen['doors'][number] | string {
+  if (!doors.length) return 'has no webhook trigger, so there is no door to deliver to. workflow_run runs it with an input instead.'
+  const wanted = path?.replace(/^\/+/, '')
+  if (wanted !== undefined) {
+    const door = doors.find((d) => d.path.replace(/^\/+/, '') === wanted)
+    return door ?? `has no webhook door at path "${path}"; its doors: ${doors.map((d) => `"${d.path}" (${d.methods.join(', ')})`).join('; ')}.`
+  }
+  if (doors.length > 1) return `has ${doors.length} webhook doors: pass path, one of ${doors.map((d) => `"${d.path}"`).join(', ')}.`
+  return doors[0]!
+}
+
+/** The test door's address on the local runtime, whatever base the runtime wrote it with. */
+export function localDoorUrl(test: string, serviceUrl: string): string {
+  const u = new URL(test, serviceUrl)
+  return new URL(`${u.pathname}${u.search}`, serviceUrl).toString()
+}
+
+/** Headers as the answer shows them: names kept, values of anything that may be a credential blanked. */
+export function shownHeaders(headers: Record<string, string>): Record<string, string> {
+  return Object.fromEntries(Object.entries(headers).map(([name, value]) => [name, /auth|token|secret|signature|key|cookie|session/i.test(name) ? '[given]' : value]))
+}
+
+/** A webhook trigger's own auth, as its workflow file declares it (the platform's `auth` on a `kind: webhook` trigger). */
+export type TriggerAuth =
+  | { type: 'none' }
+  | { type: 'header'; name: string; secret: string }
+  | { type: 'basic'; username: string; secret: string }
+  | { type: 'hmac'; header: string; secret: string; algorithm?: string; encoding?: string; prefix?: string }
+
+/** The auth of the webhook trigger at `doorPath` in workflows/<slug>.yaml (or .yml, .json), or null when the file or trigger isn't there. */
+export function triggerAuthOf(root: string, slug: string, doorPath: string): TriggerAuth | null {
+  const file = ['yaml', 'yml', 'json'].map((ext) => join(root, 'workflows', `${slug}.${ext}`)).find((f) => existsSync(f))
+  if (!file) return null
+  let doc: unknown
+  try {
+    doc = parse(readFileSync(file, 'utf8'))
+  } catch {
+    return null
+  }
+  const raw = (doc as { trigger?: unknown; triggers?: unknown } | null)?.trigger ?? (doc as { triggers?: unknown } | null)?.triggers
+  const triggers = (Array.isArray(raw) ? raw : raw ? [raw] : []) as Array<{ kind?: unknown; path?: unknown; auth?: unknown }>
+  const bare = (p: unknown) => (typeof p === 'string' ? p.replace(/^\/+|\/+$/g, '') : '')
+  const hooks = triggers.filter((t) => t?.kind === 'webhook')
+  const trigger = hooks.find((t) => bare(t.path) === bare(doorPath)) ?? (hooks.length === 1 ? hooks[0] : undefined)
+  const auth = trigger?.auth as TriggerAuth | undefined
+  return auth && typeof auth === 'object' && typeof auth.type === 'string' ? auth : trigger ? { type: 'none' } : null
+}
+
+/** The header a trigger's auth reads its credential from: the secret header, Authorization for basic, the signature header for HMAC. */
+export function authHeaderOf(auth: TriggerAuth): string | null {
+  if (auth.type === 'header') return auth.name
+  if (auth.type === 'basic') return 'authorization'
+  if (auth.type === 'hmac') return auth.header
+  return null
+}
+
+/** What the runtime's own delivery to a test door answers (`POST /v1/workflows/:slug/test-delivery`): the door's answer and the run, never the secret. */
+interface TestDelivery {
+  version: number
+  path: string
+  method: string
+  status: number
+  headers?: Record<string, string>
+  body?: unknown
+  runId?: string | null
+  /** How the runtime authenticated the delivery: the trigger's auth type and the secret's name. */
+  auth?: { type: string; secret?: string }
+}
+
+/** The test run a delivery started: the id the door answered with, else the newest test run of that version since it was sent. */
+async function deliveredRun(link: RuntimeLink, slug: string, version: number, sentAt: string, answered: unknown): Promise<string | null> {
+  const fromBody = answered && typeof answered === 'object' && typeof (answered as { runId?: unknown }).runId === 'string' ? (answered as { runId: string }).runId : null
+  if (fromBody) return fromBody
+  for (let attempt = 0; attempt < 6; attempt++) {
+    const page = await serviceCall<unknown>(link, `/v1/workflows/${encodeURIComponent(slug)}/runs?source=test&from=${encodeURIComponent(sentAt)}&limit=10`).catch(() => null)
+    const rows = (Array.isArray(page) ? page : ((page as { items?: unknown[]; runs?: unknown[]; data?: unknown[] } | null)?.items ?? (page as { runs?: unknown[] } | null)?.runs ?? (page as { data?: unknown[] } | null)?.data ?? [])) as Array<{
+      id: string
+      versionNumber?: number | null
+      startedAt?: string
+    }>
+    const mine = rows.filter((r) => r.versionNumber === undefined || r.versionNumber === null || r.versionNumber === version).sort((a, b) => Date.parse(b.startedAt ?? '') - Date.parse(a.startedAt ?? ''))
+    if (mine[0]) return mine[0].id
+    await new Promise((r) => setTimeout(r, 500))
+  }
+  return null
+}
+
+export interface SavedObjectSet {
+  id: string
+  name: string
+  description?: string | null
+  kind?: string
+  /** The file that defines it, `blueprint/object-sets/<file>.yaml`, when the project has one by that name. */
+  file?: string
+  objectType?: string
+}
+
+/** The project's object set files by the set's name: `blueprint/object-sets/<file>.yaml` and the object type it names. */
+function objectSetFiles(root: string): Map<string, { file: string; objectType?: string }> {
+  const dir = join(root, 'blueprint', 'object-sets')
+  const out = new Map<string, { file: string; objectType?: string }>()
+  if (!existsSync(dir)) return out
+  for (const entry of readdirSync(dir)) {
+    if (!/\.ya?ml$/.test(entry)) continue
+    try {
+      const doc = parse(readFileSync(join(dir, entry), 'utf8')) as { name?: unknown; objectType?: unknown } | null
+      if (typeof doc?.name === 'string') out.set(doc.name.toLowerCase(), { file: entry.replace(/\.ya?ml$/, ''), ...(typeof doc.objectType === 'string' ? { objectType: doc.objectType } : {}) })
+    } catch {
+      // A file that does not parse is apply's to report.
+    }
+  }
+  return out
+}
+
+/** The saved object sets on the local runtime, with the file each comes from: what a query, a workflow or an App addresses by id. */
+export async function savedObjectSets(link: RuntimeLink, root: string): Promise<SavedObjectSet[]> {
+  const rows = await serviceCall<Array<{ id: string; name: string; description?: string | null; kind?: string; deletedAt?: string | null; objectTypeApiName?: string | null }> | { items?: unknown[] }>(link, '/v1/blueprint/object-sets', { timeoutMs: 15_000 })
+  const list = (Array.isArray(rows) ? rows : ((rows?.items ?? []) as never[])) as Array<{ id: string; name: string; description?: string | null; kind?: string; deletedAt?: string | null; objectTypeApiName?: string | null }>
+  const files = objectSetFiles(root)
+  return list
+    .filter((r) => r && typeof r.id === 'string' && !r.deletedAt)
+    .map((r) => {
+      const file = files.get(String(r.name).toLowerCase())
+      // The type its records are: as the runtime lists it, else as the file names it.
+      const objectType = r.objectTypeApiName ?? file?.objectType
+      return { id: r.id, name: r.name, ...(r.description ? { description: r.description } : {}), ...(r.kind ? { kind: r.kind } : {}), ...(file ? { file: file.file } : {}), ...(objectType ? { objectType } : {}) }
+    })
+}
+
+/**
+ * A saved object set by what the agent knows it as: its id, its name (any
+ * case), its file name (`open-work-orders`), or a project reference
+ * (`objectSet/open-work-orders`, `objectSet/Open work orders`).
+ */
+export function findObjectSet(sets: SavedObjectSet[], wanted: string): SavedObjectSet | string {
+  const ref = wanted.trim().replace(/^objectSet\//, '').replace(/^blueprint\/object-sets\//, '').replace(/\.ya?ml$/, '')
+  const lower = ref.toLowerCase()
+  const slug = (name: string) => name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '')
+  const found = sets.find((s) => s.id === ref) ?? sets.find((s) => s.name.toLowerCase() === lower) ?? sets.find((s) => s.file === ref) ?? sets.find((s) => slug(s.name) === slug(ref))
+  if (found) return found
+  return sets.length
+    ? `No saved object set "${wanted}" on the local runtime. Its sets: ${sets.map((s) => `"${s.name}"${s.file ? ` (${s.file})` : ''}`).join(', ')}.`
+    : `No saved object set "${wanted}": the local runtime has none. Sets are files under blueprint/object-sets/; apply puts them on the runtime.`
+}
+
+export function workflowTools(project: LocalProject): McpTool[] {
+  return [
+    {
+      name: 'workflow_run',
+      description:
+        'Run a workflow on the local runtime with an input, wait for it to finish (up to waitSeconds), and return each step\'s status, output and any error, and the run\'s output. A step\'s output is what $steps.<id> reads in an expression: for a forEach that is the list of per-item $steps (the run view\'s { mode, count } is beside it as recorded). Runs the live version unless version says otherwise: pass version "draft" to run what you last applied (the live one, once a person promoted it). A run is real, on the local runtime only: its steps read and write the runtime’s own records (the project’s datasets, never the workspace’s), and a governed Action it submits, from an action step or from a Function step’s code, is applied and changes those records when the Action runs here (it creates, updates or deletes Blueprint records). An Action whose effect would reach another system (a transition or a command) is switched off here and does not run. The writes stay: frontera local snapshot restore (or frontera local reset) takes them back; frontera local check rolls back its own tests’ writes, this tool does not.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          workflow: { type: 'string', description: 'The workflow\'s slug (its file name under workflows/).' },
+          input: { type: 'object', description: 'The run\'s input, as its trigger declares it.' },
+          subject: { type: 'string', description: 'The primary key of the record it runs on, for a record-triggered workflow.' },
+          version: {
+            type: ['integer', 'string'],
+            description: 'Which version to run: a version number, or "draft" (the newest version that is not retired: what apply last pushed, which is the live one once a person promoted it; "latest" means the same). Default: the live version.',
+          },
+          waitSeconds: { type: 'integer', minimum: 0, maximum: 300, description: 'Wait at most this long for it to finish (default 120; 0 returns at once).' },
+        },
+        required: ['workflow'],
+        additionalProperties: false,
+      },
+      annotations: { title: 'Run a workflow', readOnlyHint: false, openWorldHint: false },
+      async run(input) {
+        const link = requireRuntime(project)
+        const slug = stringArg(input, 'workflow', { required: true })
+        const subject = stringArg(input, 'subject')
+        const version = await pickVersion(input.version, () => serviceCall<VersionSummary[]>(link, `/v1/workflows/${encodeURIComponent(slug)}/versions`), slug)
+        const started = await startRun(link, slug, {
+          ...(input.input && typeof input.input === 'object' ? { input: input.input } : {}),
+          ...(subject ? { subject: { pk: subject } } : {}),
+          ...(version !== undefined ? { version } : {}),
+        })
+        const runLink = studioLink(link, `/workflows/runs/${encodeURIComponent(started.runId)}`)
+        const deadline = Date.now() + intArg(input, 'waitSeconds', 120, 0, 300) * 1000
+        for (;;) {
+          const run = await serviceCall<RunTree>(link, `/v1/workflows/runs/${encodeURIComponent(started.runId)}?depth=run`)
+          if (TERMINAL.has(run.status)) return jsonResult({ ...describe(run), link: runLink })
+          if (Date.now() >= deadline) return jsonResult({ ...describe(run), link: runLink, note: 'Still running. Call workflow_run again later or open the link.' })
+          await new Promise((r) => setTimeout(r, 1_500))
+        }
+      },
+    },
+    {
+      name: 'workflow_webhook_test',
+      description:
+        "Test a workflow's webhook trigger on its draft, as Studio's Listen does: arms the draft's test door for one delivery, sends your request to it (body, headers, method, query), and returns what the door answered (status, headers, body), then the run it started with each step's status, output and error. Tests the mapping from $request and the trigger's respond settings before anything is live. By default the newest version that is not retired (what apply last pushed, the live one once a person promoted it); version names another. The trigger's auth (a secret header, basic auth or an HMAC signature, naming a workspace secret) is applied by the local runtime from its own secret store when you leave its header out, so you never handle the secret: set its value once with `frontera secret set NAME`. Pass the header in headers only to test what a wrong or missing credential does; header values that look like credentials are not repeated in the answer.",
+      inputSchema: {
+        type: 'object',
+        properties: {
+          workflow: { type: 'string', description: 'The workflow\'s slug (its file name under workflows/).' },
+          body: { description: 'The request body: an object or array is sent as JSON, a string as it is.' },
+          headers: { type: 'object', additionalProperties: { type: 'string' }, description: 'Request headers, e.g. the trigger\'s auth header. content-type defaults to application/json for an object body.' },
+          method: { type: 'string', enum: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'], description: 'Default: POST when the door takes it, else its first method.' },
+          path: { type: 'string', description: 'Which webhook door, by its trigger path, when the workflow has more than one.' },
+          query: { type: 'object', additionalProperties: { type: 'string' }, description: 'Query parameters to add to the door\'s address.' },
+          version: { type: ['integer', 'string'], description: 'Which version to test: "draft" (default: the newest version that is not retired, what apply last pushed, which is the live one once a person promoted it) or a version number. The local runtime\'s test door takes the live version too.' },
+          waitSeconds: { type: 'integer', minimum: 0, maximum: 300, description: 'Wait at most this long for the run to finish (default 120; 0 returns after the delivery).' },
+        },
+        required: ['workflow'],
+        additionalProperties: false,
+      },
+      annotations: { title: "Test a workflow's webhook", readOnlyHint: false, openWorldHint: false },
+      async run(input) {
+        const link = requireRuntime(project)
+        const slug = stringArg(input, 'workflow', { required: true })
+        const version = await pickVersion(input.version ?? 'draft', () => serviceCall<VersionSummary[]>(link, `/v1/workflows/${encodeURIComponent(slug)}/versions`), slug)
+        let listen: WebhookListen
+        try {
+          listen = await serviceCall<WebhookListen>(link, `/v1/workflows/${encodeURIComponent(slug)}/listen`, { body: version === undefined ? {} : { version } })
+        } catch (err) {
+          const message = (err as Error).message
+          if (/answered 404/.test(message)) return errorResult(`The local runtime cannot listen on a workflow's test door (${message.slice(0, 200)}). Update the runtime, or test the mapping with workflow_run and an input shaped like $request.`)
+          throw err
+        }
+        const door = pickDoor(listen.doors, stringArg(input, 'path'))
+        if (typeof door === 'string') return errorResult(`Workflow "${slug}" v${listen.version} ${door}`)
+        const given = input.method === undefined ? undefined : String(input.method).toUpperCase()
+        const method = given ?? (door.methods.includes('POST') ? 'POST' : door.methods[0] ?? 'POST')
+        if (!door.methods.includes(method)) return errorResult(`The door at "${door.path}" takes ${door.methods.join(', ')}, not ${method}.`)
+        const url = new URL(localDoorUrl(door.test, link.serviceUrl))
+        for (const [k, v] of Object.entries((input.query && typeof input.query === 'object' ? input.query : {}) as Record<string, unknown>)) url.searchParams.set(k, String(v))
+        const headers: Record<string, string> = Object.fromEntries(Object.entries((input.headers && typeof input.headers === 'object' ? input.headers : {}) as Record<string, unknown>).map(([k, v]) => [k, String(v)]))
+        const raw = input.body
+        const hasBody = raw !== undefined && method !== 'GET'
+        const payload = !hasBody ? undefined : typeof raw === 'string' ? raw : JSON.stringify(raw)
+        if (hasBody && typeof raw !== 'string' && !Object.keys(headers).some((h) => h.toLowerCase() === 'content-type')) headers['content-type'] = 'application/json'
+        const sentAt = new Date(Date.now() - 1_000).toISOString()
+        const waitSeconds = intArg(input, 'waitSeconds', 120, 0, 300)
+        // The trigger checks a credential and none was given: the runtime sends the delivery with the secret it names, read from its own store.
+        const auth = triggerAuthOf(project.root, slug, door.path)
+        const authHeader = auth ? authHeaderOf(auth) : null
+        if (auth && authHeader && auth.type !== 'none' && !Object.keys(headers).some((h) => h.toLowerCase() === authHeader.toLowerCase())) {
+          let delivered: TestDelivery
+          try {
+            delivered = await serviceCall<TestDelivery>(link, `/v1/workflows/${encodeURIComponent(slug)}/test-delivery`, {
+              body: { version: listen.version, path: door.path, method, headers, query: Object.fromEntries(url.searchParams), ...(payload !== undefined ? { body: payload } : {}), auth: 'trigger' },
+              timeoutMs: (waitSeconds + 30) * 1000,
+            })
+          } catch (err) {
+            const message = (err as Error).message
+            const secret = 'secret' in auth ? auth.secret : ''
+            if (/answered 404/.test(message) && /test-delivery|not found/i.test(message)) {
+              return errorResult(`The trigger at "${door.path}" checks ${auth.type === 'hmac' ? `an HMAC signature in ${auth.header}` : auth.type === 'basic' ? 'basic auth' : `the ${auth.name} header`} against the secret ${secret}, and this local runtime can't send a delivery with its own secret yet. Update the runtime; until then pass the credential in headers as the caller would (never in a file you commit).`)
+            }
+            if (/WEBHOOK_SECRET_MISSING|secret/i.test(message) && /answered 409|answered 400/.test(message)) {
+              return errorResult(`The trigger at "${door.path}" needs the secret ${secret}, which has no value on this runtime: set it with \`frontera secret set ${secret}\` in the project folder, then test again.`)
+            }
+            throw err
+          }
+          const answeredBody = delivered.body
+          const doorAnswer = {
+            url: `${url.pathname}${url.search}`,
+            method: delivered.method ?? method,
+            sent: { headers: { ...shownHeaders(headers), [authHeader]: `[from secret ${'secret' in auth ? auth.secret : ''}]` }, ...(hasBody ? { body: typeof raw === 'string' ? raw.slice(0, 2_000) : raw } : {}) },
+            status: delivered.status,
+            headers: delivered.headers ?? {},
+            body: typeof answeredBody === 'string' ? answeredBody.slice(0, 4_000) : answeredBody,
+          }
+          if (delivered.status === 401 || delivered.status === 403 || delivered.status === 404) {
+            return { ...jsonResult({ workflow: slug, version: delivered.version ?? listen.version, door: doorAnswer, why: delivered.status === 404 ? 'The test door refused the delivery: the method or path does not match the trigger. Check its methods and path.' : `The trigger refused the runtime's own credential: check that ${'secret' in auth ? auth.secret : 'its secret'} holds the value the trigger expects.` }), isError: true }
+          }
+          const runId = delivered.runId ?? (await deliveredRun(link, slug, delivered.version ?? listen.version, sentAt, answeredBody))
+          if (!runId) return jsonResult({ workflow: slug, version: delivered.version ?? listen.version, door: doorAnswer, note: 'The door answered, but no test run of this version showed up: trace_list or Studio\'s workflow runs show what happened.', link: studioLink(link, `/workflows/${encodeURIComponent(slug)}`) })
+          const { run, finished } = await followRun(link, runId, Date.now() + waitSeconds * 1000)
+          return jsonResult({
+            workflow: slug,
+            version: delivered.version ?? listen.version,
+            door: doorAnswer,
+            run: describe(run),
+            ...(finished ? {} : { note: 'The run is still going: its link shows it as it goes. Calling workflow_webhook_test again sends another delivery.' }),
+            link: studioLink(link, `/workflows/runs/${encodeURIComponent(run.id)}`),
+          })
+        }
+        // The door can hold the delivery until the run answers (respond onFinish), so it gets the run's time too.
+        const res = await fetch(url, { method, headers, body: payload, signal: AbortSignal.timeout((waitSeconds + 30) * 1000) })
+        const text = await res.text()
+        let answered: unknown = text
+        try {
+          answered = text ? JSON.parse(text) : null
+        } catch {
+          // Not JSON: the door answered text, kept as it is.
+        }
+        const delivery = {
+          url: `${url.pathname}${url.search}`,
+          method,
+          sent: { headers: shownHeaders(headers), ...(hasBody ? { body: typeof raw === 'string' ? raw.slice(0, 2_000) : raw } : {}) },
+          status: res.status,
+          headers: Object.fromEntries([...res.headers].filter(([k]) => !/^(date|connection|keep-alive|transfer-encoding|access-control-)/i.test(k))),
+          body: typeof answered === 'string' ? answered.slice(0, 4_000) : answered,
+        }
+        if (res.status === 404 || res.status === 401 || res.status === 403) {
+          return {
+            ...jsonResult({
+              workflow: slug,
+              version: listen.version,
+              door: delivery,
+              why:
+                res.status === 404
+                  ? "The test door refused the delivery: its one delivery was already used, the Listen ended, or the method or path does not match the trigger. Call workflow_webhook_test again to listen for another; check the trigger's methods and path."
+                  : "The trigger's own auth refused the credential in headers: leave its header out and the runtime sends the delivery with the secret the trigger names.",
+            }),
+            isError: true,
+          }
+        }
+        const runId = await deliveredRun(link, slug, listen.version, sentAt, answered)
+        if (!runId) return jsonResult({ workflow: slug, version: listen.version, door: delivery, note: 'The door answered, but no test run of this version showed up: trace_list or Studio\'s workflow runs show what happened.', link: studioLink(link, `/workflows/${encodeURIComponent(slug)}`) })
+        const { run, finished } = await followRun(link, runId, Date.now() + waitSeconds * 1000)
+        return jsonResult({
+          workflow: slug,
+          version: listen.version,
+          door: delivery,
+          run: describe(run),
+          ...(finished ? {} : { note: 'The run is still going: its link shows it as it goes. Calling workflow_webhook_test again sends another delivery.' }),
+          link: studioLink(link, `/workflows/runs/${encodeURIComponent(run.id)}`),
+        })
+      },
+    },
+    {
+      name: 'blueprint_query',
+      description:
+        "Read records of a Blueprint object type, or of a saved object set, on the local runtime: optional equality filters, the properties to return, an order and a limit. A set is named by its name, its file name under blueprint/object-sets/ or its id; the answer gives its id, which an App's or a query's { type: 'reference', objectSetId } needs. Without objectType or objectSet it lists the saved object sets. A metric's numbers are blueprint_query_metric's. Read only.",
+      inputSchema: {
+        type: 'object',
+        properties: {
+          objectType: { type: 'string', description: 'The object type\'s API name, e.g. Ticket.' },
+          objectSet: { type: 'string', description: 'A saved object set instead of a whole type: its name ("Open work orders"), its file name (open-work-orders) or its id.' },
+          where: { type: 'object', additionalProperties: { type: ['string', 'number', 'boolean'] }, description: 'Property equals value, every one must hold, e.g. {"status":"open"}. On a date or time property the value can be the time the query runs: "$now", or "$now" plus or minus m (min), h, d or w ("$now-7d"); a range (before, after) is `frontera blueprint query --where \'dueAt:lt:$now\'`.' },
+          select: { type: 'array', items: { type: 'string' }, description: 'Only these properties.' },
+          orderBy: { type: 'string', description: 'A property, optionally with :desc, e.g. "createdAt:desc".' },
+          limit: { type: 'integer', minimum: 1, maximum: 100, description: 'At most this many records (default 20).' },
+        },
+        additionalProperties: false,
+      },
+      annotations: { title: 'Read Blueprint records', readOnlyHint: true, openWorldHint: false },
+      async run(input) {
+        const link = requireRuntime(project)
+        const objectTypeArg = stringArg(input, 'objectType')
+        const setArg = stringArg(input, 'objectSet')
+        if (!objectTypeArg && !setArg) {
+          const sets = await savedObjectSets(link, project.root)
+          return jsonResult({ objectSets: sets, ...(sets.length ? {} : { note: 'No saved object sets on the local runtime. Sets are files under blueprint/object-sets/; apply puts them on the runtime.' }), next: 'Pass objectType, or objectSet with a set\'s name, file or id, to read records.' })
+        }
+        let set: SavedObjectSet | null = null
+        if (setArg) {
+          const found = findObjectSet(await savedObjectSets(link, project.root), setArg)
+          if (typeof found === 'string') return errorResult(found)
+          set = found
+          if (objectTypeArg && set.objectType && set.objectType !== objectTypeArg) return errorResult(`The set "${set.name}" is over ${set.objectType}, not ${objectTypeArg}. Leave objectType out, or name a set over ${objectTypeArg}.`)
+        }
+        const where = input.where && typeof input.where === 'object' ? Object.entries(input.where as Record<string, unknown>) : []
+        const base = set ? { type: 'reference', objectSetId: set.id } : { type: 'base', objectType: objectTypeArg }
+        const objectSet =
+          where.length === 0
+            ? base
+            : {
+                type: 'filter',
+                objectSet: base,
+                where: where.length === 1 ? { property: where[0]![0], op: 'eq', value: where[0]![1] } : { and: where.map(([property, value]) => ({ property, op: 'eq', value })) },
+              }
+        const order = stringArg(input, 'orderBy')
+        const [property, dir] = order ? order.split(':') : []
+        const res = await serviceCall<{ rows?: unknown[]; data?: unknown[]; nextPageToken?: string; objectType?: string }>(link, '/v1/blueprint/query', {
+          body: {
+            objectSet,
+            ...(Array.isArray(input.select) && input.select.length ? { select: input.select } : {}),
+            ...(property ? { orderBy: [{ property, dir: dir === 'desc' ? 'desc' : 'asc' }] } : {}),
+            pageSize: intArg(input, 'limit', 20, 1, 100),
+          },
+        })
+        const rows = res.rows ?? res.data ?? []
+        const objectType = objectTypeArg ?? res.objectType ?? set?.objectType ?? null
+        return jsonResult({
+          objectType,
+          ...(set ? { objectSet: { id: set.id, name: set.name, ...(set.file ? { file: `blueprint/object-sets/${set.file}.yaml` } : {}), reference: { type: 'reference', objectSetId: set.id } } } : {}),
+          count: rows.length,
+          more: Boolean(res.nextPageToken),
+          rows,
+          ...(objectType ? { link: studioLink(link, `/blueprint/object-types/${encodeURIComponent(objectType)}`) } : {}),
+        })
+      },
+    },
+    {
+      name: 'blueprint_query_metric',
+      description:
+        "Query a Blueprint metric's numbers on the local runtime, through the route an App's useMetric and an Agent's blueprint_query_metric use: every measure (or `measures`), grouped by `dimensions`, over `timeRange` (an ISO duration, or a start and an end), as a series by `grain` (the metric's timeseries dimension is added for it), with `compare` adding the window before (<measure>_prev, _delta, _pct). An isoDuration window is counted back from the newest value of the metric's timeseries in the data, not from now: P7D is after newest − 7 days, through newest. The answer's `window` gives those bounds; compare rows against them, not against now. Use it to check a metric you just authored. Read only.",
+      inputSchema: {
+        type: 'object',
+        properties: {
+          metric: { type: 'string', description: 'The metric\'s API name (blueprint/metrics/<apiName>.yaml).' },
+          measures: { type: 'array', items: { type: 'string' }, description: 'Only these measures; all when absent.' },
+          dimensions: { type: 'array', items: { type: 'string' }, description: 'The metric\'s dimensions to group by.' },
+          grain: { enum: [...METRIC_GRAINS], description: 'A series by this bucket over the metric\'s timeseries dimension.' },
+          timeRange: {
+            type: 'object',
+            properties: { isoDuration: { type: 'string', description: 'An ISO-8601 duration, e.g. P7D, counted back from the newest value of the metric\'s timeseries in the data (not from now).' }, start: { type: 'string', description: 'ISO date or timestamp, inclusive.' }, end: { type: 'string', description: 'ISO date or timestamp, exclusive.' } },
+            additionalProperties: false,
+          },
+          compare: { description: 'true: the window before timeRange; or { start, end }: that window.', anyOf: [{ type: 'boolean' }, { type: 'object', properties: { start: { type: 'string' }, end: { type: 'string' } }, required: ['start', 'end'], additionalProperties: false }] },
+        },
+        required: ['metric'],
+        additionalProperties: false,
+      },
+      annotations: { title: 'Query a Blueprint metric', readOnlyHint: true, openWorldHint: false },
+      async run(input) {
+        const link = requireRuntime(project)
+        const metric = stringArg(input, 'metric')
+        if (!metric) return errorResult('Name the metric: { "metric": "<apiName>" }.')
+        const grain = stringArg(input, 'grain')
+        const range = (input.timeRange && typeof input.timeRange === 'object' ? input.timeRange : {}) as { isoDuration?: string; start?: string; end?: string }
+        const strings = (v: unknown) => (Array.isArray(v) ? v.filter((x): x is string => typeof x === 'string') : undefined)
+        let timeseries: string | null | undefined
+        if (grain) timeseries = await serviceCall<unknown>(link, `/v1/blueprint/metrics/${encodeURIComponent(metric)}`).then(timeseriesOf, () => undefined)
+        let body
+        try {
+          body = metricQueryBody({
+            measures: strings(input.measures),
+            dimensions: strings(input.dimensions),
+            grain,
+            range: range.isoDuration,
+            from: range.start,
+            to: range.end,
+            compare: input.compare === true ? true : input.compare && typeof input.compare === 'object' ? (input.compare as { start: string; end: string }) : undefined,
+          }, timeseries)
+        } catch (err) {
+          return errorResult(`${(err as Error).message}.`)
+        }
+        const result = await serviceCall<MetricQueryResult>(link, `/v1/blueprint/metrics/${encodeURIComponent(metric)}/query`, { body })
+        const rows = metricRows(result)
+        // The window ends at the newest record, not at now: the bounds a check against rows needs.
+        const window = body.timeRange?.isoDuration
+          ? await resolveRangeWindow(body.timeRange.isoDuration, {
+              metric: () => serviceCall<unknown>(link, `/v1/blueprint/metrics/${encodeURIComponent(metric)}`),
+              objectTypes: () => serviceCall<unknown>(link, '/v1/blueprint/object-types'),
+              aggregate: (aggregate) => serviceCall<unknown>(link, '/v1/blueprint/aggregate', { body: aggregate }),
+            })
+          : undefined
+        return jsonResult({
+          metric,
+          query: body,
+          ...(window ? { window } : {}),
+          count: rows.length,
+          rows,
+          ...(result && !Array.isArray(result) && result.truncated ? { truncated: true } : {}),
+          ...(result && !Array.isArray(result) && result.compareWindow ? { compareWindow: result.compareWindow } : {}),
+          ...(rows.length ? {} : { note: 'No rows: the metric\'s object type may have no records in that window. blueprint_query shows its records.' }),
+        })
+      },
+    },
+  ]
+}

package/src/output.ts

@@ -146,7 +146,7 @@ export function createOutput(
         streams.err(`error [${envelope.code}]: ${envelope.message}\n`)
         if (envelope.hint) streams.err(`  ${envelope.hint}\n`)
       }
-      return exitCodeFor(envelope.code)
+      return exitCodeFor(envelope.code, envelope.details)
     },
   }
 }