@frontera-sdk/functions 1.49.0

package/src/runtime-context.ts

@@ -0,0 +1,836 @@
+/**
+ * The REAL `ctx` a handler receives — the one that talks to the service.
+ *
+ * It lives in the SDK rather than in the runner because it now has two
+ * consumers: the deployed runner executing a bundle, and the CLI's dev worker
+ * executing a file on a developer's machine. One implementation means a dev run
+ * and a production run cannot drift in what they enforce or how they word a
+ * refusal, which is the whole reason a dev loop is worth trusting.
+ *
+ * NOT re-exported from `index.ts`, and NOT in `AUTOMATION_SDK_FILES`: a
+ * scaffolded project vendors the authoring surface, and this file reaches the
+ * network. Authors get `createTestContext`; the two runtimes get this.
+ */
+import { AsyncLocalStorage } from 'node:async_hooks'
+// Wording lives in the SDK, not here: the runner refusing a call before it makes
+// it, the service's own 403, and `createTestContext` on the author's machine all
+// have to say the same sentence — a test that fails in different words than
+// production teaches the wrong lesson. Re-exported below because this module is
+// where the runner's code and tests have always reached for them.
+import {
+  duplicateStepMessage as duplicateStepMessageText,
+  missingGrantMessage as missingGrantMessageText,
+  submitOutsideStepMessage as submitOutsideStepMessageText,
+  lostStepRowMessage as lostStepRowMessageText,
+  duplicateSubmissionMessage as duplicateSubmissionMessageText,
+  emptySubmissionKeyMessage as emptySubmissionKeyMessageText,
+} from './messages'
+import type {
+  ActionSubmission,
+  ActionSubmitResult,
+  AutomationContext,
+  BlueprintQueryOptions,
+  BlueprintQueryResult,
+  HttpRequest,
+  HttpResponse,
+  PluginCallResult,
+} from './types'
+
+const SERVICE_URL = process.env.SERVICE_URL ?? 'http://localhost:4000'
+
+/**
+ * How much of a summary one step row may carry.
+ *
+ * A step row is telemetry, not storage: it is read by a human scanning a run,
+ * and it is written on every ctx call of every run. So what it records about a
+ * call is bounded rather than complete, and a value that does not fit is
+ * reported as a SIZE — which tells the reader the value existed and was large,
+ * instead of showing them the empty panel this cap exists to avoid.
+ */
+const DETAIL_MAX_CHARS = 4_000
+/** How much of an agent's answer a row keeps, so a trace can be read without
+ *  re-running the agent. */
+const PREVIEW_MAX_CHARS = 500
+
+/** JSON length of a value, or null when it does not serialize (a cycle, a BigInt). */
+function jsonSize(value: unknown): number | null {
+  try {
+    const json = JSON.stringify(value)
+    return json === undefined ? null : json.length
+  } catch {
+    return null
+  }
+}
+
+/**
+ * A NUL and an unpaired surrogate, which Postgres `jsonb` REFUSES rather than
+ * escapes: `\u0000 cannot be converted to text`, and `Unicode low surrogate
+ * must follow a high surrogate`. Both verified against the repo's own Postgres.
+ */
+const NUL = /\u0000/g
+const UNPAIRED_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g
+
+/**
+ * Make a value storable, by removing the two byte classes `jsonb` rejects.
+ *
+ * Both are reachable from what a row now carries: `preview` cuts at a fixed
+ * offset and can split an emoji in half, and an author's step result may hold
+ * text pulled out of a PDF or a Postgres `text` column, where a NUL is routine.
+ *
+ * What a refusal costs is not the detail. A rejected insert loses the whole
+ * ROW — `recordStep` swallows a non-2xx by contract — and a rejected completion
+ * leaves an author's step reading `running` forever inside a run that finished,
+ * because the update is guarded on that status. Either is a worse trace than
+ * the empty panel this file set out to fix, so the scrub sits at the write
+ * rather than in each summarizer: one rule covering summaries, error messages
+ * and `ctx.log`'s author-supplied data alike.
+ */
+function jsonbSafeText(text: string): string {
+  return text.replace(NUL, '').replace(UNPAIRED_SURROGATE, '')
+}
+
+function jsonbSafe(value: unknown, seen: WeakSet<object> = new WeakSet()): unknown {
+  if (typeof value === 'string') return jsonbSafeText(value)
+  if (value === null || typeof value !== 'object') return value
+  // A cycle cannot be serialized at all: dropped here, named, rather than left
+  // to throw inside the fetch that was carrying an otherwise-good row.
+  if (seen.has(value)) return undefined
+  // The ANCESTOR stack, not every node ever visited — unmarked on the way out.
+  // A node marked for good cannot tell a cycle from an ordinary shared
+  // reference, which `JSON.stringify` handles fine: `{ before: row, after: row }`
+  // lost `after`, and `[row, row]` became `[null, null]`. That is silent data
+  // loss in the very detail this file exists to make readable.
+  seen.add(value)
+  const safe = Array.isArray(value)
+    ? value.map((item) => jsonbSafe(item, seen))
+    : Object.fromEntries(
+        Object.entries(value).map(([key, item]) => [jsonbSafeText(key), jsonbSafe(item, seen)]),
+      )
+  seen.delete(value)
+  return safe
+}
+
+/**
+ * `{ [key]: value }`, but only while the value stays small.
+ *
+ * Per key rather than over the whole detail so one enormous filter cannot cost
+ * the counts standing next to it — dropping everything would leave the row
+ * exactly as empty as it was before any of this existed.
+ */
+function ifSmall(key: string, value: unknown, max: number): Record<string, unknown> {
+  if (value === undefined) return {}
+  const size = jsonSize(value)
+  return size !== null && size <= max ? { [key]: value } : {}
+}
+
+/** The head of a text answer, marked when cut. */
+function preview(text: string): string {
+  return text.length <= PREVIEW_MAX_CHARS ? text : `${text.slice(0, PREVIEW_MAX_CHARS)}\u2026`
+}
+
+/**
+ * Run a summarizer for a row's `detail`, defending the run from it.
+ *
+ * Never throws and never grows without bound. A summary is a record OF the
+ * work by the same rule `recordStep` follows, so a summarizer that trips over
+ * a shape it did not expect — a dry dev run answering null, a service that
+ * grew a field — costs the detail, never the call it describes.
+ */
+function summarize<T>(
+  build: ((out: T) => Record<string, unknown>) | undefined,
+  out: T,
+): Record<string, unknown> | undefined {
+  if (!build) return undefined
+  let detail: Record<string, unknown>
+  try {
+    detail = build(out)
+  } catch {
+    // Named rather than omitted: an omitted detail renders as "This step
+    // recorded no detail", which is the sentence this whole path exists to
+    // stop — and it would hide a broken summarizer behind a fixed bug's
+    // symptom.
+    return { omitted: 'summary unavailable' }
+  }
+  const size = jsonSize(detail)
+  if (size === null) return { omitted: 'summary not serializable' }
+  return size <= DETAIL_MAX_CHARS ? detail : { omitted: 'summary too large', chars: size }
+}
+
+/**
+ * What an author-declared step records about its own return value.
+ *
+ * The value is already JSON — the platform stores and replays it — so keeping a
+ * copy asks nothing new of it, and it is what makes the row readable at all:
+ * without it a step shows a name and a duration for work whose result nobody
+ * can see. Bounded, and reported as a size when it does not fit, because a step
+ * that returns a thousand warehouse rows must not write them a second time into
+ * the audit trail.
+ */
+function stepResultDetail(out: unknown): Record<string, unknown> | undefined {
+  if (out === undefined) return undefined
+  const size = jsonSize(out)
+  if (size === null) return { omitted: 'result not serializable' }
+  return size <= DETAIL_MAX_CHARS
+    ? { result: out }
+    : { resultChars: size, omitted: 'result too large' }
+}
+
+/**
+ * The step tools this module needs, declared structurally rather than imported
+ * from `inngest`.
+ *
+ * Structural because it keeps the whole file testable with a two-line stub, and
+ * because it states exactly what `ctx` depends on — one method — instead of the
+ * platform's entire step surface. `function-builder.ts` passes the real object
+ * straight in, so the compiler still checks the two agree.
+ */
+export interface StepTools {
+  /**
+   * Returns `unknown`, deliberately, and not the body's own type.
+   *
+   * What comes back is not the value the body returned but its JSON round trip:
+   * the platform stores a step's result and replays it on the next execution, so
+   * a `Date` returns as a string and a class instance as a plain object. Typing
+   * this as `Promise<T>` here would erase that at exactly the boundary where it
+   * happens. `ctx.step.run` narrows it once, at the seam, with the same
+   * reasoning `ctx.blueprint.query` narrows a warehouse row.
+   */
+  run<T>(id: string, fn: () => Promise<T>): Promise<unknown>
+  /** Absent on hosts that predate it — the runtime falls back to an inline wait. */
+  sleep?(id: string, ms: number): Promise<void>
+}
+
+interface Deps {
+  runId: string
+  workspaceId: string
+  runToken: string
+  grants: string[]
+  /** The platform's step tools for THIS execution. */
+  step: StepTools
+  /** The run's frozen input row, or absent when the manifest declares none. */
+  input?: Record<string, unknown>
+  /** Zero-indexed run attempt, stamped onto every row this context writes. */
+  attempt?: number
+  /**
+   * Where the service lives, when the caller knows better than the environment.
+   *
+   * The deployed runner reads `SERVICE_URL` from its own env; the CLI's dev
+   * worker knows it from the origin the developer logged into, and a
+   * module-level const read at import time cannot be told. Overriding here keeps
+   * this module usable in both processes rather than forked for one.
+   */
+  serviceUrl?: string
+  /**
+   * The deployment-wide runner secret, or absent.
+   *
+   * PASSED IN, never read from the environment here. This module now runs in two
+   * processes, and only one of them may hold this token: the runner does, a
+   * developer's laptop must not. Reading `process.env` inside shared code moves
+   * that decision into an environment nobody reviews — a developer who has the
+   * variable exported for any reason, a copied env file, a locally-run runner,
+   * would have `automation dev` sending a workspace-wide credential from their
+   * machine with nothing on screen to say so.
+   *
+   * As a parameter the rule is structural: the dev worker cannot send it,
+   * because it has nothing to pass.
+   */
+  runnerToken?: string
+}
+
+export {
+  duplicateStepMessage,
+  duplicateSubmissionMessage,
+  emptySubmissionKeyMessage,
+  lostStepRowMessage,
+  missingGrantMessage,
+  submitOutsideStepMessage,
+} from './messages'
+
+export class DuplicateStepNameError extends Error {
+  constructor(readonly stepName: string) {
+    super(duplicateStepMessageText(stepName))
+    this.name = 'DuplicateStepNameError'
+  }
+}
+
+class GrantError extends Error {
+  constructor(grant: string) {
+    super(missingGrantMessageText(grant))
+    this.name = 'GrantError'
+  }
+}
+
+export function buildContext(deps: Deps): AutomationContext {
+  const serviceUrl = deps.serviceUrl ?? SERVICE_URL
+  const requireGrant = (grant: string) => {
+    if (!deps.grants.includes(grant)) throw new GrantError(grant)
+  }
+
+  /**
+   * Step and finish writes carry BOTH credentials, and the service takes either.
+   *
+   * The deployed runner has the shared secret; a dev worker on a developer's
+   * laptop must never hold it, and has only the run's own token — which is the
+   * stronger claim for a row that belongs to one run. Sending both means this
+   * module works unchanged in either process, which is the whole reason it can
+   * be reused by the CLI rather than forked.
+   *
+   * An empty runner token is omitted rather than sent blank: the service treats
+   * a PRESENT runner header as an assertion to verify, so a blank one would be
+   * a 401 instead of a fall-through to the run token.
+   */
+  const runnerHeaders: Record<string, string> = {
+    'content-type': 'application/json',
+    'x-automation-run-token': deps.runToken,
+    ...(deps.runnerToken ? { 'x-automation-runner-token': deps.runnerToken } : {}),
+  }
+
+  /**
+   * Which author-declared step the code writing a row is running inside.
+   *
+   * Async-local rather than a plain variable because two steps can be in flight
+   * at once — `Promise.all([ctx.step.run('a', …), ctx.step.run('b', …)])` is
+   * legal, and a shared mutable "current step" would file `a`'s ctx calls under
+   * `b` depending on interleaving. This is per-run, not module-global: two runs
+   * in one process must never see each other's scope.
+   */
+  const stepScope = new AsyncLocalStorage<{
+    stepId: string
+    stepName: string
+    /**
+     * `action` + `submissionKey` for every submit this step body has made.
+     *
+     * The write plane CANNOT catch a repeat: two identical submissions derive
+     * one key and one semantic fingerprint, so it replays the first request and
+     * answers both calls with the same id — no error, one effect, a green run.
+     * The check has to be local, and per step EXECUTION so that a genuine
+     * resumption or retry (which re-enters the body from scratch) is unaffected.
+     */
+    submitted: Set<string>
+  }>()
+
+  /**
+   * Append a row to the run's audit trail, returning the id the service gave it.
+   *
+   * Never throws. A step row is a record OF the work, not part of it — so a
+   * service blip while recording must not turn a completed operation into a
+   * failed run, and must not replace an in-flight failure with a transport
+   * error on the way to reporting it. The same reasoning is why a failure
+   * returns an empty id rather than propagating: losing the parent link on one
+   * row is strictly better than losing the run.
+   */
+  const recordStep = async (body: Record<string, unknown>): Promise<string> => {
+    const parentStepId = stepScope.getStore()?.stepId
+    try {
+      const res = await fetch(`${serviceUrl}/v1/automations/runner/runs/${deps.runId}/steps`, {
+        method: 'POST',
+        headers: runnerHeaders,
+        body: JSON.stringify({
+          // Only when there IS a parent. A step whose own row failed to write
+          // leaves an empty id in scope, and sending that empty string reaches
+          // Postgres as `''::uuid`, which errors — so the child row would be
+          // dropped too, quietly, because this whole path is non-fatal. One
+          // lost step row must not cost the calls made inside it.
+          ...(parentStepId ? { parentStepId } : {}),
+          attempt: deps.attempt ?? 0,
+          ...body,
+          // Last, so it applies to whatever `body` brought — see `jsonbSafe`.
+          ...(body.detail === undefined ? {} : { detail: jsonbSafe(body.detail) }),
+          // `label` and `step_name` are `text`, and a NUL is refused there too —
+          // `invalid byte sequence for encoding "UTF8": 0x00`. `ctx.log` writes
+          // the author's message as the label, so a NUL riding in from a PDF
+          // kills the row through the field NEXT to the one being scrubbed. A
+          // lone surrogate is not a hazard in a text column (the driver encodes
+          // it as U+FFFD), but it is scrubbed with it rather than reasoned about
+          // twice.
+          ...(typeof body.label === 'string' ? { label: jsonbSafeText(body.label) } : {}),
+          ...(typeof body.stepName === 'string'
+            ? { stepName: jsonbSafeText(body.stepName) }
+            : {}),
+        }),
+      })
+      // `fetch` resolves on a 4xx/5xx, so the status is the only place a
+      // rejected step surfaces at all.
+      if (!res.ok) {
+        console.warn(`[ctx] step record failed (non-fatal): ${res.status}`)
+        return ''
+      }
+      return ((await res.json()) as { data?: { id?: string } }).data?.id ?? ''
+    } catch (err) {
+      console.warn('[ctx] step record failed (non-fatal):', (err as Error).message)
+      return ''
+    }
+  }
+
+  /** Close an author-declared step row. Never throws, for the same reason. */
+  const completeStep = async (stepId: string, body: Record<string, unknown>): Promise<void> => {
+    if (!stepId) return
+    // A row refused here is not closed at all — the service guards the update on
+    // `status = 'running'` — so the step would read `running` forever.
+    const payload = {
+      ...body,
+      ...(body.detail === undefined ? {} : { detail: jsonbSafe(body.detail) }),
+    }
+    try {
+      const res = await fetch(
+        `${serviceUrl}/v1/automations/runner/runs/${deps.runId}/steps/${stepId}/complete`,
+        { method: 'POST', headers: runnerHeaders, body: JSON.stringify(payload) },
+      )
+      if (!res.ok) console.warn(`[ctx] step complete failed (non-fatal): ${res.status}`)
+    } catch (err) {
+      console.warn('[ctx] step complete failed (non-fatal):', (err as Error).message)
+    }
+  }
+
+  /**
+   * The message an author should read when a ctx call is refused.
+   *
+   * The service answers with an envelope (`{error, message, code}`), so the raw
+   * body pasted into an error reads `ctx.http → 400 {"error":true,"message":...}`
+   * — the useful sentence is in there, wrapped in JSON the author did not ask
+   * for and cannot act on. This unwraps it and falls back to the raw body when
+   * the response is not one of ours (a proxy 502, say), because an empty message
+   * would be worse than a noisy one.
+   */
+  const refusal = async (res: Response): Promise<string> => {
+    const body = await res.text()
+    try {
+      const parsed = JSON.parse(body) as { message?: unknown }
+      if (typeof parsed.message === 'string' && parsed.message) return parsed.message
+    } catch {
+      // Not JSON. Fall through to the body.
+    }
+    return body
+  }
+
+  /**
+   * Record one ctx call as a row: timed, and with a bounded summary of what it
+   * did.
+   *
+   * The summary is per capability rather than generic. A reader opening
+   * `query:LoanApplication` wants the row count and the filter; a reader opening
+   * `agent:triage` wants what the agent said — a generic dump of the return
+   * value would be both larger and less useful than either. A capability whose
+   * result carries a credential (a file's signed URL) summarizes AROUND it:
+   * details are rendered verbatim in the Console.
+   */
+  const step = async <T>(
+    kind: string,
+    label: string,
+    fn: () => Promise<T>,
+    detailOf?: (out: T) => Record<string, unknown>,
+  ): Promise<T> => {
+    const t0 = Date.now()
+    try {
+      const out = await fn()
+      await recordStep({
+        kind,
+        label,
+        status: 'ok',
+        durationMs: Date.now() - t0,
+        // Omitted, not `{}`: an absent field leaves the service's own default in
+        // place rather than writing an empty object the panel would have to
+        // treat as detail.
+        detail: summarize(detailOf, out),
+      })
+      return out
+    } catch (err) {
+      await recordStep({
+        kind,
+        label,
+        status: 'error',
+        detail: { message: (err as Error).message },
+        durationMs: Date.now() - t0,
+      })
+      throw err
+    }
+  }
+
+  /**
+   * Every ctx call carries the per-run token, never a workspace credential.
+   *
+   * The fixed headers go LAST so `init.headers` cannot override them — the run
+   * token is the entire authority of this call, and a caller that could replace
+   * it could replace the run's scope.
+   */
+  const scoped = (path: string, init?: RequestInit) =>
+    // `/automations/runner` — the ctx endpoints live on `automationRunnerRouter`,
+    // which is prefixed, because they authenticate by run token rather than by
+    // session. Addressing them as `/automations/...` reaches the session-guarded
+    // router instead and 404s. This is only caught end to end: both sides pass
+    // their own tests, and the mismatch is between them.
+    fetch(`${serviceUrl}/v1/automations/runner${path}`, {
+      ...init,
+      headers: {
+        ...(init?.headers ?? {}),
+        'content-type': 'application/json',
+        'x-automation-run-token': deps.runToken,
+        'x-workspace-id': deps.workspaceId,
+      },
+    })
+
+  /**
+   * Names used by this EXECUTION, which is what the uniqueness rule is about.
+   *
+   * A run that uses steps is executed many times — once more after each step
+   * completes — and every execution walks the handler from the top, naming the
+   * same steps again. That is not a duplicate. A duplicate is the same name
+   * twice within one walk, which is what this set sees, because a fresh context
+   * is built per execution.
+   */
+  const namesThisExecution = new Set<string>()
+
+  /**
+   * Run `fn` as a durable step.
+   *
+   * The row is written from INSIDE the step body, and that placement is the
+   * whole design rather than an implementation detail. Code after
+   * `await step.run(...)` does not run in the same execution — the platform
+   * checkpoints the step and resumes the handler in a fresh execution — so a
+   * report written there would land one execution late, time the memoized
+   * return instead of the work, and repeat on every later resumption. A body
+   * runs exactly once per real execution of the step, so a report inside it is
+   * written exactly once and times what actually happened.
+   *
+   * Open-then-close rather than one write at the end: ctx calls made inside the
+   * body need the parent row to exist before they record, and opening first also
+   * puts the step ahead of its own children in `seq`.
+   */
+  const runStep = async <T>(name: string, fn: () => Promise<T>): Promise<T> => {
+    if (namesThisExecution.has(name)) throw new DuplicateStepNameError(name)
+    namesThisExecution.add(name)
+
+    // The cast is the honest boundary: the platform hands back the JSON round
+    // trip of what the body returned, and nothing here can verify the author's
+    // `T` survived it. Rule 2 on `StepApi` is that contract, stated where the
+    // author reads it.
+    return (await deps.step.run(name, async () => {
+      const stepId = await recordStep({
+        kind: 'step',
+        label: name,
+        stepName: name,
+        status: 'running',
+      })
+      const t0 = Date.now()
+      try {
+        // `stepName` rides alongside `stepId` because `ctx.action.submit` needs
+        // the NAME, not the row id: the id is fresh on every execution, and an
+        // idempotency key derived from it would differ on each resumption —
+        // which is the exact duplicate-submission this scope exists to prevent.
+        // The service reads the name off the row rather than trusting this
+        // copy; it travels here only so a refusal can name it.
+        const out = await stepScope.run(
+          { stepId, stepName: name, submitted: new Set<string>() },
+          fn,
+        )
+        await completeStep(stepId, {
+          status: 'ok',
+          durationMs: Date.now() - t0,
+          detail: stepResultDetail(out),
+        })
+        return out
+      } catch (err) {
+        await completeStep(stepId, {
+          status: 'error',
+          durationMs: Date.now() - t0,
+          detail: { message: (err as Error).message },
+        })
+        throw err
+      }
+    })) as T
+  }
+
+  /**
+   * Durable pause. No step row is written: a row recorded after a memoized
+   * sleep would be re-recorded by every later execution (the code after an
+   * awaited memoized step re-runs per resumption), and unlike `runStep`
+   * there is no body to write it from exactly once.
+   */
+  const sleepStep = async (name: string, ms: number): Promise<void> => {
+    if (namesThisExecution.has(name)) throw new DuplicateStepNameError(name)
+    namesThisExecution.add(name)
+    if (deps.step.sleep) {
+      await deps.step.sleep(name, ms)
+      return
+    }
+    // Host without a sleep arm (an old dev worker): wait inline. Correct,
+    // just not durable — acceptable for the host that cannot resume anyway.
+    await new Promise((resolve) => setTimeout(resolve, ms))
+  }
+
+  return {
+    runId: deps.runId,
+    workspaceId: deps.workspaceId,
+    // The host passes the run row's frozen copy; the SDK never re-validates — `startRun` is the authority.
+    input: deps.input ?? {},
+
+    step: { run: runStep, sleep: sleepStep },
+
+    async log(message, data) {
+      // Swallowed on purpose, inside `recordStep`. `ctx.log` is telemetry, and a
+      // blip reaching the service must not take down an otherwise-healthy run —
+      // the signature promises callers it never rejects.
+      await recordStep({ kind: 'log', label: message, detail: data ?? {} })
+    },
+
+    agent(slug: string) {
+      return {
+        run: (prompt: string, options?: { files?: Array<{ fileId: string }> }) =>
+          step('agent', `agent:${slug}`, async () => {
+            requireGrant(`agent:${slug}:run`)
+            // `files` hands the agent already-uploaded files by canonical id —
+            // the same `{ fileId }` a `file`-typed run input carries, so an
+            // input can be forwarded as `ctx.agent(s).run(p, { files:
+            // [ctx.input.doc] })`. The service authorizes each id against this
+            // run's workspace and stages the bytes onto the agent's computer;
+            // the agent is told the staged paths in its prompt.
+            const res = await scoped('/ctx/agent-run', {
+              method: 'POST',
+              body: JSON.stringify({
+                slug,
+                prompt,
+                ...(options?.files?.length ? { files: options.files.map((f) => ({ fileId: f.fileId })) } : {}),
+              }),
+            })
+            if (!res.ok) throw new Error(`agent ${slug} → ${res.status} ${await refusal(res)}`)
+            return ((await res.json()) as { data: { text: string } }).data
+          },
+          // The answer itself, capped. A run whose agent step is the expensive
+          // one is read to find out WHAT the agent said, and a length alone
+          // sends the reader back to re-run the automation to learn it.
+          (out) => ({
+            slug,
+            promptChars: prompt.length,
+            ...(options?.files?.length ? { files: options.files.length } : {}),
+            ...(typeof out?.text === 'string'
+              ? { textChars: out.text.length, preview: preview(out.text) }
+              : {}),
+          }),
+        ) as Promise<{ text: string }>,
+      }
+    },
+
+    file: (ref: { fileId: string }) =>
+      step('file', `file:${ref.fileId.slice(0, 8)}`, async () => {
+        // No grant: this only reads a file the run was GIVEN — the route
+        // refuses any fileId that is not among this run's own inputs. Returns
+        // a short-lived signed URL plus the authoritative mime/size/name; in a
+        // dry dev run it returns null, like every other ctx call.
+        const res = await scoped('/ctx/file-resolve', {
+          method: 'POST',
+          body: JSON.stringify({ fileId: ref.fileId }),
+        })
+        if (!res.ok) throw new Error(`file ${ref.fileId} → ${res.status} ${await refusal(res)}`)
+        return ((await res.json()) as {
+          data: { file: { fileId: string; signedUrl: string; mimeType: string; sizeBytes: number; name: string | null } | null }
+        }).data.file
+      },
+      // Everything the handle carries EXCEPT `signedUrl`. That URL is a
+      // short-lived credential, and a row is exactly the wrong place for one:
+      // details are rendered verbatim and kept for as long as the run is.
+      (out) =>
+        out
+          ? { fileId: out.fileId, mimeType: out.mimeType, sizeBytes: out.sizeBytes, name: out.name }
+          : { resolved: false },
+    ) as Promise<import('./types').ResolvedFileHandle | null>,
+
+    plugin(install: string) {
+      return {
+        call: <T = unknown>(capability: string, input?: Record<string, unknown>) =>
+          step('plugin', `plugin:${install}:${capability}`, async () => {
+            // Pre-flighted locally so an author reads the grant by name, in the
+            // same words the service uses. The service checks it again — this
+            // copy exists for the message, not for the authority.
+            requireGrant(`plugin:${install}:${capability}`)
+            const res = await scoped('/ctx/plugin-call', {
+              method: 'POST',
+              body: JSON.stringify({ install, capability, input: input ?? {} }),
+            })
+            if (!res.ok) {
+              throw new Error(
+                `ctx.plugin("${install}").call("${capability}") → ${res.status} ${await refusal(res)}`,
+              )
+            }
+            // Two levels: the service envelope's data, then PluginCallResult's own data.
+            return ((await res.json()) as { data: PluginCallResult<T> }).data
+          },
+          (out) => {
+            const chars = jsonSize(out?.data)
+            return {
+              install,
+              capability,
+              ...(chars === null ? {} : { resultChars: chars }),
+              // The plugin's own shape, while it is small enough to read at a
+              // glance. The size above stands for it when it is not.
+              ...ifSmall('data', out?.data, 2_000),
+            }
+          },
+        ) as Promise<PluginCallResult<T>>,
+      }
+    },
+
+    http: {
+      fetch: (req: HttpRequest) =>
+        step('http', `${req.method ?? 'GET'} ${req.url}`, async () => {
+          // Pre-flight the HOST grant so an author sees it named locally, in the
+          // same wording the service uses. The SECRET grant is deliberately not
+          // pre-flighted: the service derives it, and duplicating that derivation
+          // here would be a second place to get it wrong.
+          let host: string
+          try {
+            host = new URL(req.url).hostname.toLowerCase()
+          } catch {
+            throw new Error(`ctx.http: invalid URL ${req.url}`)
+          }
+          requireGrant(`http:${host}`)
+          const res = await scoped('/ctx/http', {
+            method: 'POST',
+            body: JSON.stringify(req),
+          })
+          if (!res.ok) throw new Error(`ctx.http → ${res.status} ${await refusal(res)}`)
+          return ((await res.json()) as { data: HttpResponse }).data
+        },
+        // The upstream status, which is the fact this call is read for — an API
+        // answering 404 is data here, not a throw, so the row is the only place
+        // that outcome appears at all. Not the body: it is capped at 1 MB and
+        // may carry whatever the host sent back.
+        (out) => ({
+          ...(out ? { status: out.status, bodyChars: out.body?.length ?? 0 } : {}),
+        }),
+      ) as Promise<HttpResponse>,
+    },
+
+    action: {
+      submit: (request: ActionSubmission) =>
+        step('action', `action:${request.action}`, async () => {
+          // Step scope BEFORE the grant. Both are the author's mistake, but this
+          // one is structural: a submit outside a step is wrong even with every
+          // grant in place, and the remedy is a code change rather than a
+          // manifest change. Naming the manifest first would send them to the
+          // wrong file.
+          const scope = stepScope.getStore()
+          if (!scope) throw new Error(submitOutsideStepMessageText(request.action))
+          // A step whose own row was lost cannot be submitted from. `recordStep`
+          // is contractually non-fatal and hands back an empty id, which is
+          // right for telemetry — one lost row must not cost the calls made
+          // inside it — but a submission has nothing to key on without it, and
+          // improvising a key is how an effect happens twice. Refused HERE so
+          // the cause is named; the service would otherwise see an empty string
+          // and answer with a generic invalid-submission.
+          if (!scope.stepId) throw new Error(lostStepRowMessageText(scope.stepName))
+          // NUL-joined because both halves are author strings; `a:b` with no
+          // key must not collide with `a` keyed `b`.
+          // Refused locally, matching the service's own field-named rejection
+          // — folding `''` into the no-key identity would make the two layers
+          // disagree about what the author asked for.
+          if (request.submissionKey !== undefined && request.submissionKey.length === 0) {
+            throw new Error(emptySubmissionKeyMessageText(request.action))
+          }
+          // Ahead of the reservation, and synchronous so check-and-reserve still
+          // land in one tick. Below it, a missing grant left the identity
+          // reserved and the author's next attempt was told they had duplicated
+          // a submission that never left the process — pointing at
+          // `submissionKey` when the fix is one line in the manifest. A call
+          // that is both ungranted and a duplicate now reports the grant, which
+          // is the more actionable of the two.
+          requireGrant(`governed:${request.action}`)
+          const submissionIdentity = `${request.action}\u0000${request.submissionKey ?? ''}`
+          // RESERVE, synchronously. The check and the record must land in one
+          // tick: with an await between them, `Promise.all([submit(x),
+          // submit(x)])` passes both checks before either records, both reach
+          // the plane, and — same key, same fingerprint — the plane replays the
+          // first for the second. Two calls, one effect, a green run, which is
+          // the exact failure this guard exists to prevent.
+          //
+          // Released again in the catch below, so a submission that never
+          // landed does not burn its identity and the author's retry loop still
+          // works. Reserve-then-release is what satisfies both at once.
+          if (scope.submitted.has(submissionIdentity)) {
+            throw new Error(duplicateSubmissionMessageText(request.action))
+          }
+          scope.submitted.add(submissionIdentity)
+          // The step ROW id, which the service issued. The service resolves the
+          // row, takes the step NAME off it, and derives the key from that — so
+          // what identifies the submission comes from the database rather than
+          // from this process. No ordinal: a positional one made an in-body
+          // retry mint a fresh key and duplicate the effect, and reordered
+          // concurrent submits bind each other's keys. `submissionKey` is how an
+          // author says two submissions are genuinely two.
+          let res: Response
+          try {
+            res = await scoped('/ctx/action-submit', {
+              method: 'POST',
+              body: JSON.stringify({ ...request, stepId: scope.stepId }),
+            })
+          } catch (err) {
+            // Never reached the service. Release, so a retry is a retry rather
+            // than a duplicate accusation for a step that submitted zero times.
+            scope.submitted.delete(submissionIdentity)
+            throw err
+          }
+          if (!res.ok) {
+            // Refused, so nothing was bound to this identity. A 5xx is the
+            // interesting case: the author catches it and submits again, and
+            // that second call must be allowed through to the plane, where the
+            // key — unchanged — makes it a replay rather than a second effect.
+            scope.submitted.delete(submissionIdentity)
+            throw new Error(`ctx.action.submit → ${res.status} ${await refusal(res)}`)
+          }
+          try {
+            return ((await res.json()) as { data: ActionSubmitResult }).data
+          } catch (err) {
+            // The submission LANDED, so keeping the reservation would be
+            // defensible — but the reasoning that releases a 503 applies here
+            // with more force: the key is unchanged, so a resubmit can only
+            // replay, and replaying is the only way the author recovers a
+            // request id they never received. Keeping it ends the run accusing
+            // them of two submissions when there was one and an unreadable
+            // answer.
+            scope.submitted.delete(submissionIdentity)
+            throw err
+          }
+        },
+        // `lifecycle` is the half of the answer a reader most often wants: a
+        // submission that stopped at `awaiting_approval` is a normal return, so
+        // the row's green status does not say whether anything happened yet.
+        (out) => ({
+          action: request.action,
+          ...(request.submissionKey ? { submissionKey: request.submissionKey } : {}),
+          ...(out ? { requestId: out.requestId, lifecycle: out.lifecycle } : {}),
+        }),
+      ) as Promise<ActionSubmitResult>,
+    },
+
+    blueprint: {
+      query: <T = Record<string, unknown>>(objectType: string, options?: BlueprintQueryOptions) =>
+        step('blueprint', `query:${objectType}`, async () => {
+          requireGrant('blueprint:read')
+          // Spread rather than forwarded field-by-field so adding an option to
+          // `BlueprintQueryOptions` does not silently drop it here — the
+          // service validates the body, so an unknown key is refused there
+          // rather than ignored in transit.
+          const res = await scoped('/ctx/blueprint-query', {
+            method: 'POST',
+            body: JSON.stringify({ objectType, ...(options ?? {}) }),
+          })
+          if (!res.ok) throw new Error(`blueprint query → ${res.status} ${await refusal(res)}`)
+          // `T` is an author-supplied shape for rows the warehouse returns
+          // untyped. The cast is the honest boundary: nothing here can verify
+          // it, and pretending otherwise would just move the lie deeper.
+          return ((await res.json()) as { data: BlueprintQueryResult<T> }).data
+        },
+        // Count AND filter, because the two questions a reader brings to a
+        // query step are "how many did it match" and "what did it ask for" —
+        // and `hasMore` is how they tell an empty result from a truncated one.
+        (out) => ({
+          objectType,
+          ...(out ? { rowCount: out.rows?.length ?? 0, hasMore: out.hasMore ?? false } : {}),
+          ...(options?.limit === undefined ? {} : { limit: options.limit }),
+          ...ifSmall('where', options?.where, 1_000),
+          ...ifSmall('select', options?.select, 500),
+          ...ifSmall('orderBy', options?.orderBy, 500),
+        }),
+      ) as Promise<BlueprintQueryResult<T>>,
+    },
+  }
+}