@frontera-sdk/functions 1.52.39 → 1.52.41

package/README.md

@@ -114,8 +114,31 @@ 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.
+By default the handler runs once, straight through. In production it is
+re-entered after every step: code outside a step runs again, and each completed
+step hands back its stored result without running. Pass `replay: true` to run it
+that way in a test:
+
+```ts
+const replayed = createTestContext({ replay: true, grants: ['blueprint:read'] })
+await handler.handler(replayed.ctx)
+expect(replayed.steps).toEqual(['load', 'nothing-to-do']) // each step once
+expect(replayed.executions).toBeGreaterThan(1)            // the handler started again
+```
+
+With `replay`, the handler starts again after each step that completes for the
+first time, and after each `ctx.step.sleep`, each `ctx.agent(…).run` outside a
+step and each `ctx.person.confirm`. A completed step returns its stored result as
+JSON, as the platform stores it (a `Date` comes back as a string), and a failed
+step throws its error again. So a read outside a step that a later step changes
+takes the other branch here, as it does on the platform. `calls` records every
+pass's reads, `steps` lists each step once in the order it first ran, and
+`executions` counts how many times the handler started (`1` without `replay`).
+A `defineFunction` handler replays through `handler.handler(ctx)`; for a plain
+handler function, use the returned `run(handler)`. A handler that starts a new
+step on every pass, such as one whose step name includes the time, fails the
+test instead of running forever. `replay` is off by default, so a test that
+counts the calls made outside its steps keeps its numbers.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontera-sdk/functions",
-  "version": "1.52.39",
+  "version": "1.52.41",
   "description": "Author Frontera functions: manifest, triggers and the typed handler contract.",
   "keywords": [
     "frontera",
@@ -42,7 +42,7 @@
     "typescript": "^5.9.3"
   },
   "dependencies": {
-    "@frontera-sdk/blueprint": "1.52.39",
+    "@frontera-sdk/blueprint": "1.52.41",
     "cron-parser": "^5.0.6"
   }
 }

package/src/define.ts

@@ -5,6 +5,7 @@ import type {
   AutomationTrigger,
   InputsSchema,
 } from './types'
+import { TEST_CONTEXT_CHECK, TEST_CONTEXT_RUN } from './test-check'
 
 /**
  * Declare a Function: a manifest and the handler the runner executes.
@@ -38,16 +39,30 @@ export function defineFunction(
     }
   }
 
+  const frozen = Object.freeze({
+    ...manifest,
+    trigger: Object.freeze(trigger),
+    grants: Object.freeze([...(manifest.grants ?? [])]),
+    ...(inputs ? { inputs } : {}),
+    concurrency: manifest.concurrency ?? 1,
+    retries: manifest.retries ?? 0,
+  })
+
   return Object.freeze({
-    manifest: Object.freeze({
-      ...manifest,
-      trigger: Object.freeze(trigger),
-      grants: Object.freeze([...(manifest.grants ?? [])]),
-      ...(inputs ? { inputs } : {}),
-      concurrency: manifest.concurrency ?? 1,
-      retries: manifest.retries ?? 0,
-    }),
-    handler,
+    manifest: frozen,
+    // A unit test's ctx (`createTestContext`) checks the manifest and the
+    // input the way the platform does before the handler runs, so a test
+    // refuses what a deploy or a run would. Any other ctx passes straight
+    // through: production never carries the check.
+    // With `replay`, it also runs the handler as the platform does: again from
+    // the top after each step, until it returns.
+    handler: (async (ctx) => {
+      const check = (ctx as unknown as Record<symbol, unknown> | null)?.[TEST_CONTEXT_CHECK]
+      if (typeof check === 'function') (check as (m: AutomationManifest) => void)(frozen)
+      const run = (ctx as unknown as Record<symbol, unknown> | null)?.[TEST_CONTEXT_RUN]
+      if (typeof run === 'function') return (run as (h: AutomationHandler) => ReturnType<AutomationHandler>)(handler)
+      return handler(ctx)
+    }) as AutomationHandler,
   })
 }
 

package/src/errors.ts

@@ -0,0 +1,82 @@
+/**
+ * A `ctx` call the platform refused.
+ *
+ * The message is the one a refused call has always thrown
+ * (`ctx.action.submit → 409 Record "SRV-1" already has an open … request`), so
+ * a log line or a trace reads the same. What it adds is what a handler branches
+ * on: the platform's error `code` (`ACTION_REQUEST_ALREADY_OPEN`), the HTTP
+ * `status` and the refusal's `details`, the same code a workflow step reads as
+ * `$steps.<id>.error.code`. Matching on the wording breaks the day it changes;
+ * the code does not.
+ *
+ * Codes are not enumerated: the platform adds new ones, and an SDK that refused
+ * unknown codes would need a release each time.
+ */
+export class FronteraCallError extends Error {
+  /** The platform's error code, e.g. `ACTION_REQUEST_ALREADY_OPEN`. */
+  readonly code: string
+  /** The HTTP status the platform answered with. */
+  readonly status: number
+  /** What the platform said beside the message, e.g. `{ openRequest: { requestId, lifecycle } }`; absent when it said nothing more. */
+  readonly details?: unknown
+  /** The call that was refused, e.g. `ctx.action.submit`. */
+  readonly call: string
+
+  constructor(call: string, status: number, message: string, options: { code?: string; details?: unknown } = {}) {
+    super(`${call} → ${status} ${message}`)
+    this.name = 'FronteraCallError'
+    this.call = call
+    this.status = status
+    this.code = options.code ?? codeForStatus(status)
+    if (options.details !== undefined) this.details = options.details
+  }
+}
+
+/** The code of a refusal whose body names none: a proxy's 502, say. */
+function codeForStatus(status: number): string {
+  switch (status) {
+    case 400: return 'BAD_REQUEST'
+    case 401: return 'UNAUTHORIZED'
+    case 403: return 'FORBIDDEN'
+    case 404: return 'NOT_FOUND'
+    case 409: return 'CONFLICT'
+    case 410: return 'GONE'
+    case 429: return 'RATE_LIMITED'
+    case 503: return 'SERVICE_UNAVAILABLE'
+    default: return status >= 500 ? 'INTERNAL_ERROR' : 'REQUEST_FAILED'
+  }
+}
+
+/**
+ * Whether `err` is a refused `ctx` call, optionally with this code.
+ *
+ * Reads the fields rather than `instanceof`, so a refusal thrown by another
+ * copy of the SDK (a test helper's, a bundled one) still matches.
+ */
+export function isFronteraCallError(err: unknown, code?: string): err is FronteraCallError {
+  if (!err || typeof err !== 'object') return false
+  const e = err as { name?: unknown; code?: unknown; status?: unknown }
+  if (e.name !== 'FronteraCallError' || typeof e.code !== 'string' || typeof e.status !== 'number') return false
+  return code === undefined || e.code === code
+}
+
+/**
+ * The refusal in a response body: the platform answers `{ error, message, code, details }`.
+ * A body that is not one of ours gives its text as the message, because an
+ * empty message would be worse than a noisy one.
+ */
+export function refusalOf(body: string): { message: string; code?: string; details?: unknown } {
+  try {
+    const parsed = JSON.parse(body) as { message?: unknown; code?: unknown; details?: unknown }
+    if (parsed && typeof parsed === 'object' && typeof parsed.message === 'string' && parsed.message) {
+      return {
+        message: parsed.message,
+        ...(typeof parsed.code === 'string' && parsed.code ? { code: parsed.code } : {}),
+        ...(parsed.details !== undefined ? { details: parsed.details } : {}),
+      }
+    }
+  } catch {
+    // Not JSON. Fall through to the body.
+  }
+  return { message: body }
+}

package/src/index.ts

@@ -9,7 +9,9 @@ export {
   missingGrantMessage,
   submitOutsideStepMessage,
 } from './messages'
-export { createTestContext } from './testing'
+export { FronteraCallError, isFronteraCallError } from './errors'
+export { actionRefused, createTestContext } from './testing'
+export { subjectOf } from './subject'
 export type { TestCall, TestContext, TestContextOptions } from './testing'
 export {
   DEFAULT_MAX_FILES,

package/src/runtime-context.ts

@@ -31,6 +31,7 @@ import {
   personConfirmTimeoutRefusal,
   signedUrlRemovedMessage,
 } from './messages'
+import { FronteraCallError, refusalOf } from './errors'
 import type {
   ActionSubmission,
   ActionSubmitResult,
@@ -77,7 +78,7 @@ function jsonSize(value: unknown): number | null {
  * 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 NUL = new RegExp(String.fromCharCode(0), 'g')
 const UNPAIRED_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g
 
 /**
@@ -446,7 +447,17 @@ type AgentTurnStatus = 'queued' | 'running' | 'succeeded' | 'failed' | 'parked'
  *  check, so it must come from inside the step, never from a replay's clock.
  *  `fingerprint` and `slug` identify the call it was made for — see
  *  `agentFingerprint`. Absent on a start memoized before they existed. */
-type AgentStart = ({ ok: true; invocationId: string; startedAt: number } | { ok: false; message: string }) & {
+/** A refusal as a step memoizes it: the error's fields, since a step's value must be plain data. */
+type Refusal = { call: string; status: number; message: string; code: string; details?: unknown }
+const memoizedRefusal = (err: FronteraCallError): Refusal => ({
+  call: err.call,
+  status: err.status,
+  message: err.message.slice(`${err.call} → ${err.status} `.length),
+  code: err.code,
+  ...(err.details !== undefined ? { details: err.details } : {}),
+})
+
+type AgentStart = ({ ok: true; invocationId: string; startedAt: number } | { ok: false; message: string; refusal?: Refusal }) & {
   fingerprint?: string
   slug?: string
 }
@@ -467,7 +478,7 @@ function agentFingerprint(slug: string, prompt: string, options: AgentRunOptions
  *  it, so the loop's decisions replay identically. */
 type AgentRead =
   | { done: true; text: string }
-  | { done: true; error: string }
+  | { done: true; error: string; refusal?: Refusal }
   | { done: false; now: number }
 
 interface Deps {
@@ -693,17 +704,17 @@ export function buildContext(deps: Deps): AutomationContext {
    * 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.
+   *
+   * Thrown as a `FronteraCallError`, which carries the platform's `code`,
+   * `status` and `details`, so a handler branches on
+   * `err.code === 'ACTION_REQUEST_ALREADY_OPEN'` instead of the wording.
    */
-  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 refused = async (call: string, res: Response): Promise<FronteraCallError> => {
+    const r = refusalOf(await res.text())
+    return new FronteraCallError(call, res.status, r.message, r)
   }
+  /** A memoized refusal thrown again on a replay, as the error it was. */
+  const rebuilt = (r: Refusal) => new FronteraCallError(r.call, r.status, r.message, r)
 
   /**
    * Record one ctx call as a row: timed, and with a bounded summary of what it
@@ -908,15 +919,15 @@ export function buildContext(deps: Deps): AutomationContext {
         })
         // A refusal before the turn starts (token, grant, budget, files) is
         // still a plain non-2xx, on either shape.
-        if (!res.ok) throw new Error(`agent ${slug} → ${res.status} ${await refusal(res)}`)
+        if (!res.ok) throw await refused(`agent ${slug}`, res)
         // The kept-alive body is leading spaces and one JSON value; `JSON.parse`
         // skips the whitespace. The plain body is `{ data }`.
         const body = JSON.parse(await res.text()) as
           | { ok: true; data: { text: string } }
-          | { ok: false; status: number; message: string }
+          | { ok: false; status: number; message: string; code?: string; details?: unknown }
           | { ok?: undefined; data: { text: string } }
         // The same words the plain route's non-2xx would have produced.
-        if (body.ok === false) throw new Error(`agent ${slug} → ${body.status} ${body.message}`)
+        if (body.ok === false) throw new FronteraCallError(`agent ${slug}`, body.status, body.message, body)
         return body.data
       },
       agentDetail(slug, prompt, options),
@@ -955,15 +966,15 @@ export function buildContext(deps: Deps): AutomationContext {
     if (stepScope.getStore()) {
       throw new Error('ctx.person.confirm must be called at the top level of the handler, not inside ctx.step.run')
     }
-    const refused = personConfirmTimeoutRefusal(request.timeoutMinutes)
-    if (refused) throw new Error(refused)
+    const badTimeout = personConfirmTimeoutRefusal(request.timeoutMinutes)
+    if (badTimeout) throw new Error(badTimeout)
     const base = `person.confirm:${confirmCalls++}`
     const opened = (await deps.step.run(`${base}:open`, async () => {
       const res = await scoped('/ctx/person-confirmation', {
         method: 'POST',
         body: JSON.stringify({ key: base, ...request }),
       })
-      if (!res.ok) throw new Error(`person.confirm → ${res.status} ${await refusal(res)}`)
+      if (!res.ok) throw await refused('person.confirm', res)
       return ((await res.json()) as { data: { id?: string; status: string; expiresAt?: string } }).data
     })) as { id?: string; status: string; expiresAt?: string }
     if (opened.status !== 'pending' || !opened.id) return opened.status as PersonConfirmResult
@@ -971,7 +982,7 @@ export function buildContext(deps: Deps): AutomationContext {
       const read = (await deps.step.run(`${base}:read:${i}`, async () => {
         const res = await scoped(`/ctx/person-confirmation/${opened.id}`, { method: 'GET' }).catch(() => null)
         // Refused permanently: waiting on it would only spend the run's steps.
-        if (res && res.status >= 400 && res.status < 500) throw new Error(`person.confirm → ${res.status} ${await refusal(res)}`)
+        if (res && res.status >= 400 && res.status < 500) throw await refused('person.confirm', res)
         // Unreachable or failing for now: read again after the next wait.
         const status = res?.ok ? ((await res.json()) as { data: { status: string } }).data.status : 'pending'
         return { status, now: Date.now() }
@@ -1036,9 +1047,10 @@ export function buildContext(deps: Deps): AutomationContext {
         // A refusal is an answer, not a transient fault: returned, so the
         // platform does not retry a call the service has already turned down,
         // and thrown below in the words the synchronous path uses.
-        const message = `agent ${slug} → ${res.status} ${await refusal(res)}`
+        const err = await refused(`agent ${slug}`, res)
+        const message = err.message
         await recordStep({ kind: 'agent', label, status: 'error', detail: { message }, durationMs: Date.now() - startedAt })
-        return { ok: false, message, fingerprint, slug }
+        return { ok: false, message, refusal: memoizedRefusal(err), fingerprint, slug }
       }
       const { invocationId } = ((await res.json()) as { data: { invocationId: string } }).data
       return { ok: true, invocationId, startedAt, fingerprint, slug }
@@ -1050,13 +1062,13 @@ export function buildContext(deps: Deps): AutomationContext {
     if (start.fingerprint !== undefined && start.fingerprint !== fingerprint) {
       throw new Error(agentReplayMismatchMessage(slug, start.slug ?? slug, callNumber))
     }
-    if (!start.ok) throw new Error(start.message)
+    if (!start.ok) throw start.refusal ? rebuilt(start.refusal) : new Error(start.message)
 
     const giveUpAt = start.startedAt + waitMs + AGENT_SETTLE_GRACE_MS
     for (let i = 0; ; i++) {
       const read = (await deps.step.run(`${base}:result:${i}`, async (): Promise<AgentRead> => {
         const now = Date.now()
-        const settle = async (verdict: { text: string } | { error: string }): Promise<AgentRead> => {
+        const settle = async (verdict: { text: string } | { error: string; refusal?: Refusal }): Promise<AgentRead> => {
           await recordStep(
             'text' in verdict
               ? { kind: 'agent', label, status: 'ok', durationMs: now - start.startedAt, detail: summarize(detailOf, verdict) }
@@ -1086,14 +1098,15 @@ export function buildContext(deps: Deps): AutomationContext {
         } else if (res && res.status < 500) {
           // Not transient: the run's token is gone, or the turn is not this
           // run's. Waiting longer cannot change the answer.
-          return settle({ error: `agent ${slug} → ${res.status} ${await refusal(res)}` })
+          const err = await refused(`agent ${slug}`, res)
+          return settle({ error: err.message, refusal: memoizedRefusal(err) })
         }
         if (now >= giveUpAt) return settle({ error: `agent ${slug} → 400 ${agentTimeoutMessage(slug, waitMs)}` })
         return { done: false, now }
       })) as AgentRead
 
       if (read.done) {
-        if ('error' in read) throw new Error(read.error)
+        if ('error' in read) throw read.refusal ? rebuilt(read.refusal) : new Error(read.error)
         return { text: read.text }
       }
       const sliceMs = Math.max(1_000, Math.min(AGENT_WAIT_SLICE_MS, giveUpAt - read.now))
@@ -1149,7 +1162,7 @@ export function buildContext(deps: Deps): AutomationContext {
           method: 'POST',
           body: JSON.stringify({ fileId: ref.fileId }),
         })
-        if (!res.ok) throw new Error(`file ${ref.fileId} → ${res.status} ${await refusal(res)}`)
+        if (!res.ok) throw await refused(`file ${ref.fileId}`, res)
         const file = ((await res.json()) as {
           data: { file: { fileId: string; signedUrl: string; mimeType: string; sizeBytes: number; name: string | null } | null }
         }).data.file
@@ -1200,11 +1213,7 @@ export function buildContext(deps: Deps): AutomationContext {
               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)}`,
-              )
-            }
+            if (!res.ok) throw await refused(`ctx.plugin("${install}").call("${capability}")`, res)
             // Two levels: the service envelope's data, then PluginCallResult's own data.
             return ((await res.json()) as { data: PluginCallResult<T> }).data
           },
@@ -1241,7 +1250,7 @@ export function buildContext(deps: Deps): AutomationContext {
             method: 'POST',
             body: JSON.stringify(req),
           })
-          if (!res.ok) throw new Error(`ctx.http → ${res.status} ${await refusal(res)}`)
+          if (!res.ok) throw await refused('ctx.http', res)
           return ((await res.json()) as { data: HttpResponse }).data
         },
         // The upstream status, which is the fact this call is read for — an API
@@ -1328,7 +1337,7 @@ export function buildContext(deps: Deps): AutomationContext {
             // 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)}`)
+            throw await refused('ctx.action.submit', res)
           }
           try {
             return ((await res.json()) as { data: ActionSubmitResult }).data
@@ -1367,7 +1376,7 @@ export function buildContext(deps: Deps): AutomationContext {
             method: 'POST',
             body: JSON.stringify({ objectType, ...(options ?? {}) }),
           })
-          if (!res.ok) throw new Error(`blueprint query → ${res.status} ${await refusal(res)}`)
+          if (!res.ok) throw await refused('blueprint query', 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.
@@ -1397,7 +1406,7 @@ export function buildContext(deps: Deps): AutomationContext {
           // PLATFORM recorded as this run's trigger, so there is nothing an
           // author could name to read someone else's.
           const res = await scoped('/ctx/conversation-transcript', { method: 'POST', body: '{}' })
-          if (!res.ok) throw new Error(`ctx.conversation.transcript → ${res.status} ${await refusal(res)}`)
+          if (!res.ok) throw await refused('ctx.conversation.transcript', res)
           const transcript = brandTranscript(
             ((await res.json()) as { data: { transcript: ConversationTranscript | null } }).data.transcript,
           )

package/src/subject.ts

@@ -0,0 +1,50 @@
+import type { BlueprintQueryResult } from './types'
+
+/**
+ * The subject half of an Action submission, for one row of a query.
+ *
+ * An Action that changes an existing record needs `subjectRef` (which record)
+ * and `expectedSubjectVersion` (the version you read it at). Both come from the
+ * same read, so build them from it:
+ *
+ * ```ts
+ * const found = await ctx.blueprint.query('WorkOrder', {
+ *   where: { property: 'id', op: 'eq', value: ctx.input.work_order_id },
+ *   limit: 1,
+ * })
+ * const order = found.rows[0]
+ * if (!order) return { submitted: false }
+ * await ctx.step.run('assign', () => ctx.action.submit({
+ *   action: 'assignTechnician',
+ *   ...subjectOf(found, order, order.id),
+ *   input: { technician: ctx.input.technician_id },
+ * }))
+ * ```
+ *
+ * `objectId` is the row's primary key value. Throws, naming the reason, when
+ * the row carries no version: its type has no editable properties (so no
+ * Action can change it), or the row changed while it was read (read again).
+ */
+export function subjectOf(
+  result: Pick<BlueprintQueryResult<unknown>, 'objectTypeId'>,
+  row: unknown,
+  objectId: string | number,
+): { subjectRef: { objectTypeId: string; objectId: string }; expectedSubjectVersion: string } {
+  if (!result.objectTypeId) {
+    throw new Error('subjectOf: pass the query result the row came from — it carries the object type id.')
+  }
+  const meta = row && typeof row === 'object' ? (row as { _meta?: unknown })._meta : undefined
+  const version = meta && typeof meta === 'object'
+    ? (meta as { recordVersion?: unknown }).recordVersion
+    : undefined
+  if (typeof version !== 'number') {
+    throw new Error(
+      'subjectOf: this row has no record version. Either its object type has no editable properties, '
+        + 'so no Action can change it, or the record changed while it was read — query it again.',
+    )
+  }
+  return {
+    subjectRef: { objectTypeId: result.objectTypeId, objectId: String(objectId) },
+    expectedSubjectVersion: String(version),
+  }
+}

package/src/test-check.ts

@@ -0,0 +1,16 @@
+/**
+ * Where a unit test's ctx keeps the check `defineFunction`'s handler runs
+ * before the author's code: the manifest's deploy rules and the run's input
+ * rules, as the platform applies them. A registered symbol, so a vendored
+ * copy of the SDK and the package find the same one; never enumerable, so it
+ * is not part of what the handler sees.
+ */
+export const TEST_CONTEXT_CHECK: unique symbol = Symbol.for('frontera.functions.test-context-check') as never
+
+/**
+ * Where a unit test's ctx keeps how to run a handler (`createTestContext`'s
+ * `run`): once, or with `replay`, again from the top after each step as the
+ * platform does. `defineFunction`'s handler hands its code to it, so
+ * `fn.handler(ctx)` replays without the test changing how it calls it.
+ */
+export const TEST_CONTEXT_RUN: unique symbol = Symbol.for('frontera.functions.test-context-run') as never