@frontera-sdk/functions 1.50.79 → 1.50.81

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontera-sdk/functions",
-  "version": "1.50.79",
+  "version": "1.50.81",
   "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.50.79",
+    "@frontera-sdk/blueprint": "1.50.81",
     "cron-parser": "^5.0.6"
   }
 }

package/src/messages.ts

@@ -106,3 +106,40 @@ export function submitOutsideStepMessage(apiName: string): string {
     `Wrap it: ctx.step.run('submit-${apiName}', () => ctx.action.submit({ ... }))`
   )
 }
+
+/**
+ * A `ctx.agent` turn that outlived the wait the author asked for.
+ *
+ * The same sentence the service writes when it gives up on the turn, so the
+ * synchronous wait, the durable wait and the durable loop's own last-resort
+ * deadline all read identically. The turn is NOT cancelled; its output still
+ * lands in the conversation linked from the run.
+ */
+export function agentTimeoutMessage(agentSlug: string, timeoutMs: number): string {
+  return (
+    `Agent "${agentSlug}" did not finish within ${Math.round(timeoutMs / 1000)}s. ` +
+    'The run is still executing server-side; shorten the prompt or split the work ' +
+    'across steps.'
+  )
+}
+
+/**
+ * A top-level `ctx.agent` call that does not match the one this run made at
+ * the same point before it last waited.
+ *
+ * Top-level code re-runs every time a durable wait resumes, and a call is
+ * matched to its earlier self by ORDER. When a read above it returned
+ * something different on the re-run (a query, an HTTP call, the clock), the
+ * n-th call is now a different call — and silently reusing the turn started
+ * for the old one would attribute its answer to the wrong record.
+ */
+export function agentReplayMismatchMessage(agentSlug: string, originalSlug: string, callNumber: number): string {
+  return (
+    `ctx.agent("${agentSlug}") is not the call this run made at this point before it resumed ` +
+    `(call #${callNumber} was ctx.agent("${originalSlug}") with a different prompt, files or timeoutMs). ` +
+    'Code outside ctx.step.run runs again every time the run resumes, so it must make the same ' +
+    'ctx.agent calls in the same order each time. Move reads whose results can change ' +
+    '(ctx.blueprint.query, ctx.http, the current time, random values) into ctx.step.run so ' +
+    'they are recorded once and replayed.'
+  )
+}

package/src/runtime-context.ts

@@ -12,12 +12,15 @@
  * network. Authors get `createTestContext`; the two runtimes get this.
  */
 import { AsyncLocalStorage } from 'node:async_hooks'
+import { createHash } from 'node:crypto'
 // 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 {
+  agentReplayMismatchMessage,
+  agentTimeoutMessage,
   duplicateStepMessage as duplicateStepMessageText,
   missingGrantMessage as missingGrantMessageText,
   submitOutsideStepMessage as submitOutsideStepMessageText,
@@ -198,8 +201,85 @@ export interface StepTools {
   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>
+  /**
+   * Park the run until a matching event arrives or `timeout` passes, holding no
+   * connection. Resolves to the event, or null on timeout.
+   *
+   * Absent on hosts that cannot resume a run (the CLI's dev worker): `ctx.agent`
+   * then waits on one request, exactly as it did before durable waits existed.
+   */
+  waitForEvent?(id: string, opts: { event: string; timeout: string; if: string }): Promise<unknown>
+}
+
+/** What `ctx.agent` waits when the author names no `timeoutMs`; the service's default. */
+const AGENT_DEFAULT_TIMEOUT_MS = 120_000
+
+/**
+ * One durable wait's length before the loop reads the turn again.
+ *
+ * A wait only matches events sent AFTER it is registered, and a turn can
+ * settle between two reads — so the loop never parks for the whole deadline on
+ * one wait. A missed wake costs at most one slice, not the call.
+ */
+const AGENT_WAIT_SLICE_MS = 60_000
+
+/**
+ * How long past the author's wait the loop keeps reading before it gives up
+ * on its own.
+ *
+ * The service settles the turn AT the deadline, with the same timeout message,
+ * and that is the answer the loop normally reads. This margin only matters when
+ * the process watching the turn died: the service's minute-by-minute sweep then
+ * settles it within about ninety seconds. Past that, the loop reports the
+ * timeout itself rather than wait for an answer that is not coming.
+ */
+const AGENT_SETTLE_GRACE_MS = 120_000
+
+/** The event the service sends once when a durable agent turn settles. */
+const AGENT_TURN_FINISHED_EVENT = 'agent/turn.finished'
+
+/**
+ * Asks `/ctx/agent-run` to keep the held request alive: a 200 at once, a space
+ * every few seconds while the turn runs, then one JSON envelope —
+ * `{ ok: true, data }` or `{ ok: false, status, message }`. Without it the
+ * request is silent, and an idle limit on the way (the server's 255 s, a
+ * proxy's) drops it however long `timeoutMs` is. A service that predates the header ignores it and
+ * answers plainly; both shapes are read below.
+ */
+const KEEPALIVE_HEADER = 'x-ctx-keepalive'
+
+type AgentRunOptions = { files?: ReadonlyArray<{ fileId: string }>; timeoutMs?: number }
+
+type AgentTurnStatus = 'queued' | 'running' | 'succeeded' | 'failed' | 'parked' | 'cancelled'
+
+/** The start step's memoized answer. `startedAt` anchors every later deadline
+ *  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 }) & {
+  fingerprint?: string
+  slug?: string
+}
+
+/**
+ * What makes two `ctx.agent` calls the same call: agent, prompt, files and
+ * wait. A replay recomputes it and compares with the one its start step
+ * memoized.
+ */
+function agentFingerprint(slug: string, prompt: string, options: AgentRunOptions | undefined): string {
+  const files = (options?.files ?? []).map((f) => f.fileId)
+  return createHash('sha256')
+    .update(JSON.stringify([slug, prompt, files, options?.timeoutMs ?? null]))
+    .digest('hex')
 }
 
+/** One read step's memoized answer. `now` is the read's own clock, memoized with
+ *  it, so the loop's decisions replay identically. */
+type AgentRead =
+  | { done: true; text: string }
+  | { done: true; error: string }
+  | { done: false; now: number }
+
 interface Deps {
   runId: string
   workspaceId: string
@@ -558,6 +638,192 @@ export function buildContext(deps: Deps): AutomationContext {
     await new Promise((resolve) => setTimeout(resolve, ms))
   }
 
+  /** What an agent call's row says about it — shared by both transports so a
+   *  durable call and a synchronous one read the same in the run's trace. */
+  const agentDetail = (slug: string, prompt: string, options: AgentRunOptions | undefined) =>
+    (out: { text?: unknown } | undefined): Record<string, unknown> => ({
+      slug,
+      promptChars: prompt.length,
+      ...(options?.files?.length ? { files: options.files.length } : {}),
+      // 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.
+      ...(typeof out?.text === 'string' ? { textChars: out.text.length, preview: preview(out.text) } : {}),
+    })
+
+  /** The body both agent routes accept. */
+  const agentBody = (slug: string, prompt: string, options: AgentRunOptions | undefined) => ({
+    slug,
+    prompt,
+    // `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.
+    ...(options?.files?.length ? { files: options.files.map((f) => ({ fileId: f.fileId })) } : {}),
+    ...(options?.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
+  })
+
+  /**
+   * `ctx.agent` on one held request — the only shape available inside an
+   * author's step body (steps do not nest) and on a host that cannot park a
+   * run. Unchanged from before durable waits existed.
+   */
+  const agentSync = (slug: string, prompt: string, options: AgentRunOptions | undefined) =>
+    step(
+      'agent',
+      `agent:${slug}`,
+      async () => {
+        requireGrant(`agent:${slug}:run`)
+        const res = await scoped('/ctx/agent-run', {
+          method: 'POST',
+          headers: { [KEEPALIVE_HEADER]: '1' },
+          body: JSON.stringify(agentBody(slug, prompt, options)),
+        })
+        // 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)}`)
+        // 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?: 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}`)
+        return body.data
+      },
+      agentDetail(slug, prompt, options),
+    ) as Promise<{ text: string }>
+
+  /**
+   * Durable `ctx.agent` calls made by THIS execution, in call order.
+   *
+   * The counter names the call's steps, so it must come out the same on every
+   * replay — which it does, because a fresh context is built per execution and
+   * a deterministic handler makes its calls in the same order each time. The
+   * agent's slug is deliberately NOT in the id: two calls to one agent are two
+   * turns, and a name built from the slug would memoize the second as the first.
+   *
+   * "A deterministic handler" is the author's side of the bargain, and it is
+   * CHECKED rather than assumed: the start step memoizes a fingerprint of the
+   * call (agent, prompt, files, timeoutMs), and a replay whose n-th call has a
+   * different fingerprint fails with `agentReplayMismatchMessage` instead of
+   * reusing the other call's turn.
+   */
+  let agentCalls = 0
+
+  /**
+   * `ctx.agent` without a held connection.
+   *
+   *   agent:<n>:start      start the turn; the service answers at once
+   *   agent:<n>:result:<i> read the turn; terminal → done
+   *   agent:<n>:wait:<i>   park until the turn's finished event, or one slice
+   *
+   * The read is the answer and the event only a wake-up: a wait matches only
+   * events sent after it registers, so a turn that settles between a read and
+   * the next wait is caught by the read after that slice rather than lost.
+   *
+   * Every decision is taken from memoized values (`startedAt`, each read's
+   * `now`), so a replay walks the same loop and reaches the same step ids. The
+   * call's row is written from INSIDE the step that reached the verdict — the
+   * one place a body runs exactly once — and times the whole wait.
+   *
+   * Charged once: the start is the only billable request and it is memoized;
+   * reads are free. The idempotency key is the step id, so a start step retried
+   * after the service already began the turn gets that same turn back.
+   */
+  const agentDurable = async (
+    slug: string,
+    prompt: string,
+    options: AgentRunOptions | undefined,
+  ): Promise<{ text: string }> => {
+    const callNumber = ++agentCalls
+    const base = `agent:${callNumber - 1}`
+    const label = `agent:${slug}`
+    const waitMs = options?.timeoutMs ?? AGENT_DEFAULT_TIMEOUT_MS
+    const detailOf = agentDetail(slug, prompt, options)
+    const fingerprint = agentFingerprint(slug, prompt, options)
+
+    const start = (await deps.step.run(`${base}:start`, async (): Promise<AgentStart> => {
+      const startedAt = Date.now()
+      const res = await scoped('/ctx/agent-start', {
+        method: 'POST',
+        body: JSON.stringify({ ...agentBody(slug, prompt, options), idempotencyKey: `${base}:start` }),
+      })
+      if (!res.ok) {
+        // 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)}`
+        await recordStep({ kind: 'agent', label, status: 'error', detail: { message }, durationMs: Date.now() - startedAt })
+        return { ok: false, message, fingerprint, slug }
+      }
+      const { invocationId } = ((await res.json()) as { data: { invocationId: string } }).data
+      return { ok: true, invocationId, startedAt, fingerprint, slug }
+    })) as AgentStart
+    // Replayed from an earlier execution: is this still the call that started
+    // it? Steps are matched by ORDER, so if top-level code before this call
+    // read different data this time, the n-th call can be another call — and
+    // reusing its turn would hand this call someone else's answer.
+    if (start.fingerprint !== undefined && start.fingerprint !== fingerprint) {
+      throw new Error(agentReplayMismatchMessage(slug, start.slug ?? slug, callNumber))
+    }
+    if (!start.ok) throw 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> => {
+          await recordStep(
+            'text' in verdict
+              ? { kind: 'agent', label, status: 'ok', durationMs: now - start.startedAt, detail: summarize(detailOf, verdict) }
+              : { kind: 'agent', label, status: 'error', durationMs: now - start.startedAt, detail: { message: verdict.error } },
+          )
+          return { done: true, ...verdict }
+        }
+
+        let res: Response | null
+        try {
+          res = await scoped(`/ctx/agent-result/${start.invocationId}`, { method: 'GET' })
+        } catch {
+          // The service is unreachable for a moment. The turn does not depend
+          // on this request, so try again after the next wait.
+          res = null
+        }
+        if (res?.ok) {
+          const turn = ((await res.json()) as {
+            data: { status: AgentTurnStatus; text: string | null; error: string | null }
+          }).data
+          if (turn.status === 'succeeded') return settle({ text: turn.text ?? '' })
+          if (turn.status !== 'queued' && turn.status !== 'running') {
+            // The service stores the message the synchronous route would have
+            // thrown; the prefix is the one that route's refusal carries.
+            return settle({ error: `agent ${slug} → 400 ${turn.error ?? `the agent turn ended ${turn.status}`}` })
+          }
+        } 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)}` })
+        }
+        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)
+        return { text: read.text }
+      }
+      const sliceMs = Math.max(1_000, Math.min(AGENT_WAIT_SLICE_MS, giveUpAt - read.now))
+      await deps.step.waitForEvent!(`${base}:wait:${i}`, {
+        event: AGENT_TURN_FINISHED_EVENT,
+        timeout: `${Math.ceil(sliceMs / 1000)}s`,
+        if: `async.data.invocationId == "${start.invocationId}"`,
+      })
+    }
+  }
+
   return {
     runId: deps.runId,
     workspaceId: deps.workspaceId,
@@ -575,39 +841,16 @@ export function buildContext(deps: Deps): AutomationContext {
 
     agent(slug: string) {
       return {
-        run: (prompt: string, options?: { files?: Array<{ fileId: string }>; timeoutMs?: number }) =>
-          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 })) } : {}),
-                ...(options?.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
-              }),
-            })
-            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 }>,
+        run: (prompt: string, options?: AgentRunOptions) => {
+          // Durable only where it can be: at the top level of the handler (a
+          // step cannot contain steps), on a host that can park a run, and
+          // with the grant in place — a missing grant is refused by the
+          // synchronous path in the same words and with the same row it has
+          // always written.
+          const durable =
+            !stepScope.getStore() && !!deps.step.waitForEvent && deps.grants.includes(`agent:${slug}:run`)
+          return durable ? agentDurable(slug, prompt, options) : agentSync(slug, prompt, options)
+        },
       }
     },
 

package/src/types.ts

@@ -220,6 +220,12 @@ export interface AgentHandle {
    * `options.timeoutMs` waits longer than the default 120 s for work known to
    * be long (a long scanned document); the service caps it at 480 s, under
    * the run's own 10-minute ceiling.
+   *
+   * Call it at the TOP LEVEL of the handler, not inside `ctx.step.run`. There
+   * the wait is durable: the turn is started once, the run is parked until it
+   * finishes, and a resumption replays the answer instead of asking again.
+   * Inside a step body (steps cannot nest) the call waits on one request, and
+   * a step that is re-run asks the agent again.
    */
   run(prompt: string, options?: { files?: readonly FileRef[]; timeoutMs?: number }): Promise<{ text: string }>
 }