@frontera-sdk/automation 0.1.0 → 1.43.5

package/README.md

@@ -29,6 +29,54 @@ A trigger is `{ cron }` or `{ manual: true }`, never both — the type refuses
 the ambiguous shape rather than leaving the runner to decide what it means.
 `ctx.log` never rejects: telemetry must not be able to fail a run.
 
+## Steps
+
+`ctx.step.run(name, fn)` makes a piece of work durable. The platform stores the
+result, and if the run is retried the step is not run again — it returns what it
+returned the first time.
+
+```ts
+async (ctx) => {
+  const overdue = await ctx.step.run('load-overdue', () =>
+    ctx.blueprint.query('Invoice', {
+      where: { property: 'status', op: 'eq', value: 'overdue' },
+    }),
+  )
+
+  for (const [i, row] of overdue.rows.entries()) {
+    await ctx.step.run(`notify:${i}`, () =>
+      ctx.http.fetch({ url: 'https://hooks.example.com/notify', method: 'POST',
+        body: JSON.stringify({ invoiceId: row.id }) }),
+    )
+  }
+
+  return { notified: overdue.rows.length }
+}
+```
+
+Three rules, and each one is a real failure mode rather than a style note:
+
+- **Names are unique within a run.** The platform memoizes by name, so reusing
+  one would hand back the first step's result. It is refused instead, naming the
+  collision — inside a loop, put the index in the name.
+- **Results are JSON.** A step's result is stored and replayed, so a `Date`
+  comes back as a string. Return data, not objects with behaviour.
+- **Code outside a step re-runs.** After each step the handler restarts from the
+  top, with completed steps returning their stored results. A `ctx.http` call
+  that is not inside a step therefore fires once per step and spends its call
+  budget every time.
+
+Each step is recorded on the run, and every `ctx` call made inside one records
+the step it belongs to — so a run's trail is a tree of named work rather than a
+flat list.
+
+The Console reads your deployed code and draws the whole shape: every step, both
+arms of every `if` with the condition on the edge, and a loop as a single node.
+A step named with a template shows as its pattern (`items:${i}`), because one
+loop in the code is one step in the picture however many times it runs. Each
+card names what the step reaches — Blueprint, Agent, HTTP — read from the `ctx`
+calls in its body, and clicking one shows that step's source.
+
 `automation()` freezes the manifest it returns, including a copy of the
 trigger — a later mutation of the object you passed in cannot silently change
 the schedule the runner registers.
@@ -37,6 +85,38 @@ the schedule the runner registers.
 you can run it in your own tests: names are kebab-case segments, and a cron
 expression is parsed rather than pattern-matched.
 
+## Testing a handler
+
+`createTestContext` gives you a `ctx` to call your handler with, so a branch can
+be exercised without deploying and waiting for a day with the right data.
+
+```ts
+import { createTestContext } from '@frontera-sdk/automation'
+import handler from './index'
+
+const empty = createTestContext({ grants: ['blueprint:read'] })
+expect(await handler.handler(empty.ctx)).toEqual({ handled: 0 })
+expect(empty.steps).toEqual(['load', 'nothing-to-do'])
+
+const busy = createTestContext({
+  grants: ['blueprint:read', 'agent:ava:run'],
+  blueprint: { Invoice: { rows: [{ id: 'INV-1' }], hasMore: false } },
+  agents: { ava: () => ({ text: 'looks fine' }) },
+})
+await handler.handler(busy.ctx)
+expect(busy.calls.map((c) => c.kind)).toContain('agent')
+```
+
+It refuses what the platform refuses, in the same words: a grant your manifest
+does not declare, and a step name used twice. An agent or an HTTP call you did
+not stub throws rather than answering — a fabricated `200` or an empty agent
+reply is a test that passes while asserting nothing. An object type you did not
+stub returns no rows, because that is a real answer and usually the branch worth
+testing.
+
+What it does not simulate is resumption: in production your handler is re-entered
+after every step, and here it runs once, straight through.
+
 ## License
 
 Apache-2.0. See [LICENSE](./LICENSE).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontera-sdk/automation",
-  "version": "0.1.0",
+  "version": "1.43.5",
   "description": "Author Frontera automations: manifest, triggers and the typed handler contract.",
   "keywords": [
     "frontera",

package/src/define.ts

@@ -24,6 +24,7 @@ export function automation(
       trigger: Object.freeze(trigger),
       grants: Object.freeze([...(manifest.grants ?? [])]),
       concurrency: manifest.concurrency ?? 1,
+      retries: manifest.retries ?? 0,
     }),
     handler,
   })

package/src/index.ts

@@ -1,4 +1,7 @@
 export { automation } from './define'
 export { validateManifest } from './manifest'
 export type { ValidationResult } from './manifest'
+export { duplicateStepMessage, missingGrantMessage } from './messages'
+export { createTestContext } from './testing'
+export type { TestCall, TestContext, TestContextOptions } from './testing'
 export type * from './types'

package/src/manifest.ts

@@ -15,7 +15,34 @@ const NAME_RE = new RegExp(`^${SEGMENT}$`)
  */
 const GRANT_RE = new RegExp(`^${SEGMENT}:${SEGMENT}(?::${SEGMENT})?$`)
 
-const KNOWN_KEYS = new Set(['name', 'trigger', 'grants', 'concurrency', 'description'])
+/**
+ * `http:<host>` and `secret:<NAME>` need their own grammars, because SEGMENT is
+ * lowercase-kebab and neither value is.
+ *
+ * A host contains DOTS (`api.stripe.com`); a secret name is conventionally
+ * SCREAMING_SNAKE_CASE (`STRIPE_KEY`). Validating them with SEGMENT rejected both
+ * realistic forms — found by deploying an automation that used them.
+ *
+ * Deliberately not solved by widening SEGMENT: that governs agent slugs too, and
+ * loosening it there would admit `agent:AGENT:run`, which the comment above says
+ * is rejected on purpose.
+ */
+const HOST_RE = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)*$/
+// Matches SECRET_NAME_PATTERN in workspace-secrets-router exactly. Being MORE
+// permissive here would let a manifest declare `secret:myKey`, validate cleanly,
+// and then never be satisfiable — no such secret can be created. A validator that
+// accepts the unsatisfiable is worse than one that is strict.
+const SECRET_NAME_RE = /^[A-Z][A-Z0-9_]*$/
+
+/** Namespaces whose value is not a SEGMENT. */
+const TYPED_NAMESPACES: Record<string, { re: RegExp; hint: string }> = {
+  http: { re: HOST_RE, hint: 'a hostname, e.g. "http:api.stripe.com" (no scheme, no path, no wildcard)' },
+  secret: { re: SECRET_NAME_RE, hint: 'a workspace secret name, e.g. "secret:STRIPE_KEY"' },
+}
+
+const KNOWN_KEYS = new Set([
+  'name', 'trigger', 'grants', 'concurrency', 'retries', 'description',
+])
 
 export interface ValidationResult {
   valid: boolean
@@ -51,6 +78,7 @@ export function validateManifest(input: unknown): ValidationResult {
     trigger?: unknown
     grants?: unknown
     concurrency?: unknown
+    retries?: unknown
   }
 
   if (typeof m.name !== 'string' || !NAME_RE.test(m.name)) {
@@ -99,7 +127,24 @@ export function validateManifest(input: unknown): ValidationResult {
       // String(g), not `${g}` — a template literal THROWS on a symbol, and a
       // validator that exists to absorb hostile input must not have a throwing
       // path. The message names the fix, not just the verdict.
-      if (typeof g !== 'string' || !GRANT_RE.test(g)) {
+      if (typeof g !== 'string') {
+        errors.push(
+          `malformed grant "${String(g)}" — expected "<namespace>:<action>", ` +
+            'e.g. "blueprint:read" or "agent:risk-analyst:run"',
+        )
+        continue
+      }
+      const colon = g.indexOf(':')
+      const typed = colon > 0 ? TYPED_NAMESPACES[g.slice(0, colon)] : undefined
+      if (typed) {
+        // A typed namespace validates its OWN value grammar. `http:` and
+        // `secret:` carry hosts and secret names, neither of which is a SEGMENT.
+        if (!typed.re.test(g.slice(colon + 1))) {
+          errors.push(`malformed grant "${g}" — the part after the colon must be ${typed.hint}`)
+        }
+        continue
+      }
+      if (!GRANT_RE.test(g)) {
         errors.push(
           `malformed grant "${String(g)}" — expected "<namespace>:<action>", ` +
             'e.g. "blueprint:read" or "agent:risk-analyst:run"',
@@ -113,6 +158,13 @@ export function validateManifest(input: unknown): ValidationResult {
     errors.push('concurrency must be an integer between 1 and 50')
   }
 
+  // Capped at 5. Above that it is not a retry policy, it is a loop — and every
+  // attempt re-runs whatever side effects the previous one already performed.
+  const r = m.retries
+  if (r !== undefined && (!Number.isInteger(r) || (r as number) < 0 || (r as number) > 5)) {
+    errors.push('retries must be an integer between 0 and 5')
+  }
+
   if (input && typeof input === 'object' && !Array.isArray(input)) {
     for (const key of Object.keys(input)) {
       if (!KNOWN_KEYS.has(key)) {

package/src/messages.ts

@@ -0,0 +1,36 @@
+/**
+ * The two things an author reads when the platform turns their code away.
+ *
+ * They live in the SDK, not in the runner, because three surfaces have to say
+ * exactly the same sentence: the runner refusing a call before it makes it, the
+ * service refusing it after, and `createTestContext` refusing it on the author's
+ * own machine. Three copies of a message drift, and a test that fails with
+ * different words than production is a test that teaches the wrong lesson.
+ */
+
+/**
+ * A `ctx` call the manifest does not permit.
+ *
+ * Names the fix, not the verdict: the author is looking at CLI output, and
+ * "missing grant" without the remedy costs them a round trip through the docs.
+ */
+export function missingGrantMessage(grant: string): string {
+  return `Automation is missing the "${grant}" grant. Add it to the manifest and redeploy.`
+}
+
+/**
+ * One step name used twice in a run.
+ *
+ * The platform memoizes by name, so the second call would return the FIRST
+ * step's result — no error, no warning, a wrong value flowing on. The remedy
+ * names THIS step rather than a placeholder, because a hint that reads as code
+ * to paste gets pasted.
+ */
+export function duplicateStepMessage(name: string): string {
+  return (
+    `Duplicate automation step name "${name}". Step names must be unique within a run — ` +
+    "the platform memoizes by name, so this call would return the first step's result " +
+    'instead of running again. If this is a loop, add the index: ' +
+    `ctx.step.run(\`${name}:\${i}\`, ...)`
+  )
+}

package/src/testing.ts

@@ -0,0 +1,164 @@
+import { duplicateStepMessage, missingGrantMessage } from './messages'
+import type {
+  AutomationContext,
+  BlueprintQueryOptions,
+  BlueprintQueryResult,
+  Grant,
+  HttpRequest,
+  HttpResponse,
+} from './types'
+
+/**
+ * A `ctx` you can hand your handler in a unit test.
+ *
+ * Until this existed the only way to find out whether an automation worked was
+ * to deploy it and run it — a loop measured in tens of seconds, against real
+ * data, for a question as small as "does the empty branch return the right
+ * shape".
+ *
+ * It enforces what the platform enforces, in the platform's own words: a
+ * missing grant and a repeated step name fail here exactly as they fail in
+ * production, so a green test means something.
+ *
+ * What it does NOT simulate is resumption. In production a handler is re-entered
+ * after every step, so code outside a step runs many times; here the handler is
+ * called once, straight through. Steps still memoize by name within the run, and
+ * everything the handler did is recorded on `calls`.
+ */
+
+export interface TestCall {
+  kind: 'step' | 'log' | 'agent' | 'http' | 'blueprint'
+  /** Step name, log message, agent slug, URL, or object type. */
+  label: string
+  /** Present on a step: how it ended. */
+  status?: 'ok' | 'error'
+}
+
+export interface TestContextOptions {
+  runId?: string
+  workspaceId?: string
+  /**
+   * The grants the manifest declares.
+   *
+   * Given, they are enforced — which is the point: a missing grant is one of
+   * the few automation bugs that only shows up in a deployed run, and it is
+   * exactly the kind a unit test should catch.
+   *
+   * Omitted, nothing is refused, so an existing test does not have to enumerate
+   * grants to keep passing.
+   */
+  grants?: readonly Grant[]
+  /** Per-slug agent answers. An unstubbed agent throws rather than answering. */
+  agents?: Record<string, (prompt: string) => Promise<{ text: string }> | { text: string }>
+  /** Answers outbound requests. Unstubbed, `ctx.http.fetch` throws. */
+  http?: (req: HttpRequest) => Promise<HttpResponse> | HttpResponse
+  /** Rows per object type. An unstubbed type returns no rows, which is a real
+   *  answer and usually the branch worth testing. */
+  blueprint?: Record<string, BlueprintQueryResult<never> | BlueprintQueryResult<Record<string, unknown>>>
+}
+
+export interface TestContext {
+  ctx: AutomationContext
+  /** Everything the handler did, in order. */
+  calls: TestCall[]
+  /** Step names, in the order they ran. */
+  steps: string[]
+  logs: Array<{ message: string; data?: Record<string, unknown> }>
+}
+
+export function createTestContext(options: TestContextOptions = {}): TestContext {
+  const calls: TestCall[] = []
+  const steps: string[] = []
+  const logs: TestContext['logs'] = []
+  const seenNames = new Set<string>()
+
+  const requireGrant = (grant: string): void => {
+    // No grant list means the test is not about grants. Enforcing an empty list
+    // would fail every existing test for a reason its author never chose.
+    if (!options.grants) return
+    if (!options.grants.includes(grant as Grant)) throw new Error(missingGrantMessage(grant))
+  }
+
+  const ctx: AutomationContext = {
+    runId: options.runId ?? 'test-run',
+    workspaceId: options.workspaceId ?? 'test-workspace',
+
+    step: {
+      async run<T>(name: string, fn: () => Promise<T>): Promise<T> {
+        if (seenNames.has(name)) throw new Error(duplicateStepMessage(name))
+        seenNames.add(name)
+        steps.push(name)
+        try {
+          const out = await fn()
+          calls.push({ kind: 'step', label: name, status: 'ok' })
+          return out
+        } catch (err) {
+          calls.push({ kind: 'step', label: name, status: 'error' })
+          throw err
+        }
+      },
+    },
+
+    async log(message, data) {
+      logs.push({ message, ...(data ? { data } : {}) })
+      calls.push({ kind: 'log', label: message })
+    },
+
+    agent(slug: string) {
+      return {
+        async run(prompt: string) {
+          requireGrant(`agent:${slug}:run`)
+          calls.push({ kind: 'agent', label: slug })
+          const stub = options.agents?.[slug]
+          // Throwing beats answering with an empty string: a test whose agent
+          // silently returns '' passes while asserting nothing about the step
+          // that matters most.
+          if (!stub) {
+            throw new Error(
+              `No agent stub for "${slug}". Pass agents: { '${slug}': () => ({ text: '…' }) } ` +
+                'to createTestContext.',
+            )
+          }
+          return await stub(prompt)
+        },
+      }
+    },
+
+    http: {
+      async fetch(req: HttpRequest) {
+        let host: string
+        try {
+          host = new URL(req.url).hostname.toLowerCase()
+        } catch {
+          throw new Error(`ctx.http: invalid URL ${req.url}`)
+        }
+        requireGrant(`http:${host}`)
+        calls.push({ kind: 'http', label: req.url })
+        // Same reasoning as the agent: a fabricated 200 is a false pass.
+        if (!options.http) {
+          throw new Error(
+            `No http stub. Pass http: (req) => ({ status: 200, headers: {}, body: '' }) ` +
+              'to createTestContext.',
+          )
+        }
+        return await options.http(req)
+      },
+    },
+
+    blueprint: {
+      async query<T = Record<string, unknown>>(
+        objectType: string,
+        _options?: BlueprintQueryOptions,
+      ): Promise<BlueprintQueryResult<T>> {
+        requireGrant('blueprint:read')
+        calls.push({ kind: 'blueprint', label: objectType })
+        const stub = options.blueprint?.[objectType]
+        // Empty is a real answer, and the branch an author most often forgets
+        // to test — so this one defaults rather than throwing.
+        return (stub ?? { rows: [], hasMore: false }) as BlueprintQueryResult<T>
+      },
+    },
+  }
+
+  return { ctx, calls, steps, logs }
+}

package/src/types.ts

@@ -34,12 +34,40 @@ export type AutomationTrigger =
 export type Grant =
   | 'blueprint:read'
   | `agent:${string}:run`
+  /** One EXACT host, no wildcards. `http:api.stripe.com` matches that host and
+   *  nothing else — a wildcard would ask a reviewer to reason about
+   *  subdomain-takeover risk, and the answer is usually wrong. */
+  | `http:${string}`
+  /** The NAME of a workspace secret. Its VALUE never enters this process: you
+   *  name it, the platform injects it server-side. */
+  | `secret:${string}`
 
 export interface AutomationManifest {
   name: string
   trigger: AutomationTrigger
   grants?: readonly Grant[]
   concurrency?: number
+  /**
+   * Times the platform may retry a run that FAILED. Default 0, and the opt-in
+   * is the contract.
+   *
+   * Setting this asserts your handler is safe to run twice. With `ctx.http` that
+   * is a real claim rather than a formality — a retried run that charged a card
+   * charges it again, and the platform cannot check idempotency on your behalf.
+   * Per-automation, not global, because you are the only one who knows.
+   *
+   * Retries do NOT extend the ctx call budget: each attempt is a separate run
+   * with its own meter.
+   *
+   * With steps, this is a bound on RUN attempts, and a step that fails is what
+   * consumes one. Completed steps are not re-executed on the next attempt —
+   * they return their stored results — so a retry resumes from the failure
+   * rather than starting the work again. That is the point of putting a call
+   * that costs something inside a step: `retries: 2` on a handler whose work is
+   * all in steps re-runs only the step that failed, while the same setting on a
+   * handler with no steps re-runs everything.
+   */
+  retries?: number
   description?: string
 }
 
@@ -58,6 +86,7 @@ export interface ResolvedAutomationManifest extends AutomationManifest {
   readonly trigger: Readonly<AutomationTrigger>
   readonly grants: readonly Grant[]
   readonly concurrency: number
+  readonly retries: number
   readonly description?: string
 }
 
@@ -65,6 +94,38 @@ export interface AgentHandle {
   run(prompt: string): Promise<{ text: string }>
 }
 
+/**
+ * Durable steps.
+ *
+ * A step is the unit the platform can memoize, retry and draw. Work inside one
+ * runs at most once per run; work outside one runs again every time the
+ * platform resumes the handler, which it does after every step completes.
+ *
+ * That resumption is the whole model and it is what the three rules below are
+ * about — none of them is a style preference.
+ */
+export interface StepApi {
+  /**
+   * Run `fn` as a durable step and return its result.
+   *
+   * Three rules, all enforced or observable rather than advisory:
+   *
+   * 1. **`name` must be unique within a run.** The platform memoizes by it, so a
+   *    repeated name would silently hand back the FIRST call's result. Inside a
+   *    loop, put the index in the name — `` `submit:${i}` ``. A repeat fails the
+   *    run naming the collision rather than returning the wrong value.
+   * 2. **The result must be JSON-serializable.** It is stored and replayed, so a
+   *    `Date` comes back as a string and a class instance comes back as a plain
+   *    object. Return data, not objects with behaviour.
+   * 3. **Code outside a step re-executes.** After each step the handler restarts
+   *    from the top with completed steps returning their stored results. A
+   *    `ctx.http` call sitting outside a step therefore fires once per step, and
+   *    spends its call budget every time. The Console flags such calls on a run
+   *    that used steps.
+   */
+  run<T>(name: string, fn: () => Promise<T>): Promise<T>
+}
+
 /** Read-only for now. `governed`/`notify` arrive with Governed Writes. */
 export interface AutomationContext {
   runId: string
@@ -72,12 +133,54 @@ export interface AutomationContext {
   /** Never rejects — telemetry must not be able to fail a run. */
   log(message: string, data?: Record<string, unknown>): Promise<void>
   agent(slug: string): AgentHandle
+  http: {
+    /**
+     * Call an allowlisted host, optionally with a workspace secret injected
+     * server-side.
+     *
+     * Requires an `http:<host>` grant, and an `secret:<name>` grant when `auth`
+     * is used. The secret's VALUE never enters this process — that is deliberate:
+     * a credential this process never held cannot be leaked by a stray
+     * `ctx.log`, an exception serialiser, or a dependency, and step details are
+     * rendered verbatim in the Console.
+     *
+     * An upstream 4xx/5xx comes back as `status`, not as a throw. An API
+     * answering 404 is data; only failures of the mechanism reject.
+     */
+    fetch(req: HttpRequest): Promise<HttpResponse>
+  }
   blueprint: {
     query<T = Record<string, unknown>>(
       objectType: string,
       options?: BlueprintQueryOptions,
     ): Promise<BlueprintQueryResult<T>>
   }
+  /**
+   * Durable steps. See `StepApi`.
+   *
+   * Present on every automation — a handler that uses no steps behaves exactly
+   * as it did before this existed, because a run with no steps is never
+   * resumed.
+   */
+  step: StepApi
+}
+
+export interface HttpRequest {
+  url: string
+  method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'
+  headers?: Record<string, string>
+  /** String only — no streaming, no binary. */
+  body?: string
+  /** Inject a workspace secret into one header. Needs a `secret:<name>` grant. */
+  auth?: { header: string; secret: string; prefix?: string }
+}
+
+export interface HttpResponse {
+  status: number
+  headers: Record<string, string>
+  /** Capped at 1 MB. Exceeding the cap is an error, never a truncation — a
+   *  silently shortened response is a wrong answer that looks right. */
+  body: string
 }
 
 export interface BlueprintQueryOptions {