@frontera-sdk/automation 1.43.6 → 1.43.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontera-sdk/automation",
-  "version": "1.43.6",
+  "version": "1.43.8",
   "description": "Author Frontera automations: manifest, triggers and the typed handler contract.",
   "keywords": [
     "frontera",
@@ -23,6 +23,10 @@
     ".": {
       "types": "./src/index.ts",
       "import": "./src/index.ts"
+    },
+    "./runtime": {
+      "types": "./src/runtime-context.ts",
+      "import": "./src/runtime-context.ts"
     }
   },
   "scripts": {
@@ -34,7 +38,7 @@
     "typescript": "^5.9.3"
   },
   "dependencies": {
-    "@frontera-sdk/blueprint": "0.1.0",
+    "@frontera-sdk/blueprint": "1.43.6",
     "cron-parser": "^5.0.6"
   }
 }

package/src/runtime-context.ts

@@ -0,0 +1,389 @@
+/**
+ * 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,
+} from './messages'
+import type {
+  AutomationContext,
+  BlueprintQueryOptions,
+  BlueprintQueryResult,
+  HttpRequest,
+  HttpResponse,
+} from './types'
+
+const SERVICE_URL = process.env.SERVICE_URL ?? 'http://localhost:4000'
+
+/**
+ * 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>
+}
+
+interface Deps {
+  runId: string
+  workspaceId: string
+  runToken: string
+  grants: string[]
+  /** The platform's step tools for THIS execution. */
+  step: StepTools
+  /** 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, missingGrantMessage } 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 }>()
+
+  /**
+   * 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,
+        }),
+      })
+      // `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
+    try {
+      const res = await fetch(
+        `${serviceUrl}/v1/automations/runner/runs/${deps.runId}/steps/${stepId}/complete`,
+        { method: 'POST', headers: runnerHeaders, body: JSON.stringify(body) },
+      )
+      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
+  }
+
+  const step = async (kind: string, label: string, fn: () => Promise<unknown>): Promise<unknown> => {
+    const t0 = Date.now()
+    try {
+      const out = await fn()
+      await recordStep({ kind, label, status: 'ok', durationMs: Date.now() - t0 })
+      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 {
+        const out = await stepScope.run({ stepId }, fn)
+        await completeStep(stepId, { status: 'ok', durationMs: Date.now() - t0 })
+        return out
+      } catch (err) {
+        await completeStep(stepId, {
+          status: 'error',
+          durationMs: Date.now() - t0,
+          detail: { message: (err as Error).message },
+        })
+        throw err
+      }
+    })) as T
+  }
+
+  return {
+    runId: deps.runId,
+    workspaceId: deps.workspaceId,
+
+    step: { run: runStep },
+
+    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) =>
+          step('agent', `agent:${slug}`, async () => {
+            requireGrant(`agent:${slug}:run`)
+            const res = await scoped('/ctx/agent-run', {
+              method: 'POST',
+              body: JSON.stringify({ slug, prompt }),
+            })
+            if (!res.ok) throw new Error(`agent ${slug} → ${res.status} ${await refusal(res)}`)
+            return ((await res.json()) as { data: { text: string } }).data
+          }) as Promise<{ text: string }>,
+      }
+    },
+
+    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
+        }) as Promise<HttpResponse>,
+    },
+
+    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
+        }) as Promise<BlueprintQueryResult<T>>,
+    },
+  }
+}