@frontera-sdk/functions 1.52.19 → 1.52.21

package/package.json

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

package/src/index.ts

@@ -25,6 +25,8 @@ export {
 export type { InputFieldCheck, InputValidation } from './inputs'
 export {
   EVENT_TRIGGER_SOURCES,
+  PERSON_CONFIRM_DEFAULT_MINUTES,
+  PERSON_CONFIRM_MAX_MINUTES,
   TICKETED_TRIGGER_SOURCES,
   isEventTriggerSource,
   isTicketedTriggerSource,

package/src/messages.ts

@@ -8,6 +8,8 @@
  * different words than production is a test that teaches the wrong lesson.
  */
 
+import { PERSON_CONFIRM_MAX_MINUTES } from './types'
+
 /**
  * A `ctx` call the manifest does not permit.
  *
@@ -187,3 +189,19 @@ export function oldFileStubMessage(fileId: string): string {
     'sizeBytes is computed from the content.'
   )
 }
+
+/**
+ * A `ctx.person.confirm` asking to wait longer than a Function run can.
+ *
+ * Refused before anyone is asked: the run ends at ten minutes, waits included,
+ * so a longer question would still be open after its Function stopped. `null`
+ * when the wait is one the run can hold.
+ */
+export function personConfirmTimeoutRefusal(timeoutMinutes: number | undefined): string | null {
+  if (timeoutMinutes === undefined) return null
+  if (Number.isInteger(timeoutMinutes) && timeoutMinutes >= 1 && timeoutMinutes <= PERSON_CONFIRM_MAX_MINUTES) return null
+  return (
+    `ctx.person.confirm: timeoutMinutes must be a whole number from 1 to ${PERSON_CONFIRM_MAX_MINUTES}, got ${String(timeoutMinutes)}. ` +
+    'A Function run ends at ten minutes, waits included. To wait longer for the person, ask in a workflow\'s "Confirm with the person" node.'
+  )
+}

package/src/runtime-context.ts

@@ -28,12 +28,16 @@ import {
   duplicateSubmissionMessage as duplicateSubmissionMessageText,
   emptySubmissionKeyMessage as emptySubmissionKeyMessageText,
   fileHandleInStepMessage,
+  personConfirmTimeoutRefusal,
   signedUrlRemovedMessage,
 } from './messages'
 import type {
   ActionSubmission,
   ActionSubmitResult,
   AutomationContext,
+  FunctionCaller,
+  PersonConfirmRequest,
+  PersonConfirmResult,
   BlueprintQueryOptions,
   BlueprintQueryResult,
   ConversationTranscript,
@@ -102,7 +106,7 @@ function jsonbSafe(value: unknown, seen: WeakSet<object> = new WeakSet()): unkno
   // 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
+  // A node that stays marked 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.
@@ -375,6 +379,14 @@ const AGENT_DEFAULT_TIMEOUT_MS = 120_000
  */
 const AGENT_WAIT_SLICE_MS = 60_000
 
+/**
+ * The `i`-th wait of `ctx.person.confirm`: 10 s, doubling, up to a minute. An
+ * answer wakes the wait at once; the slice only bounds a missed wake-up.
+ */
+function confirmSliceMs(i: number): number {
+  return Math.min(10_000 * 2 ** i, AGENT_WAIT_SLICE_MS)
+}
+
 /**
  * How long past the author's wait the loop keeps reading before it gives up
  * on its own.
@@ -461,6 +473,8 @@ type AgentRead =
 interface Deps {
   runId: string
   workspaceId: string
+  /** An Agent-started run's trusted context, from `startRun`. */
+  context?: { caller: Record<string, unknown>; agentId: string; conversationId: string; variables: Record<string, unknown> } | null
   runToken: string
   grants: string[]
   /** The platform's step tools for THIS execution. */
@@ -925,6 +939,61 @@ export function buildContext(deps: Deps): AutomationContext {
    */
   let agentCalls = 0
 
+  /**
+   * `ctx.person.confirm` without a held connection, the way `agentDurable`
+   * waits for a turn:
+   *
+   *   person.confirm:<n>:open      ask (the service finds the conversation)
+   *   person.confirm:<n>:read:<i>  read the answer; answered or expired → done
+   *   person.confirm:<n>:wait:<i>  park until the answer's wake-up, or a slice
+   *
+   * The read is the answer and the event only a wake-up (the service sends
+   * `agent/turn.finished` keyed by the confirmation's id when it is answered).
+   */
+  let confirmCalls = 0
+  const personConfirm = async (request: PersonConfirmRequest): Promise<PersonConfirmResult> => {
+    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 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)}`)
+      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
+    for (let i = 0; ; i++) {
+      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)}`)
+        // 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() }
+      })) as { status: string; now: number }
+      if (read.status !== 'pending') return read.status as PersonConfirmResult
+      const slice = confirmSliceMs(i)
+      const remaining = Date.parse(opened.expiresAt ?? '') - read.now
+      // Past its expiry by this run's clock but not the service's: a whole slice, then read again.
+      const sliceMs = Math.max(1_000, remaining > 0 ? Math.min(slice, remaining) : slice)
+      if (deps.step.waitForEvent) {
+        await deps.step.waitForEvent(`${base}:wait:${i}`, {
+          event: AGENT_TURN_FINISHED_EVENT,
+          timeout: `${Math.ceil(sliceMs / 1000)}s`,
+          if: `async.data.invocationId == "${opened.id}"`,
+        })
+      } else {
+        // No durable wait on this platform: poll within this execution.
+        await new Promise((resolve) => setTimeout(resolve, Math.min(sliceMs, 2_000)))
+      }
+    }
+  }
+
   /**
    * `ctx.agent` without a held connection.
    *
@@ -1039,6 +1108,10 @@ export function buildContext(deps: Deps): AutomationContext {
   return {
     runId: deps.runId,
     workspaceId: deps.workspaceId,
+    caller: deps.context
+      ? ({ ...deps.context.caller, agentId: deps.context.agentId, conversationId: deps.context.conversationId } as FunctionCaller)
+      : null,
+    variables: deps.context?.variables ?? {},
     // The host passes the run row's frozen copy; the SDK never re-validates — `startRun` is the authority.
     input: deps.input ?? {},
 
@@ -1314,6 +1387,8 @@ export function buildContext(deps: Deps): AutomationContext {
       ) as Promise<BlueprintQueryResult<T>>,
     },
 
+    person: { confirm: personConfirm },
+
     conversation: {
       transcript: () =>
         step('conversation', 'transcript', async () => {

package/src/testing.ts

@@ -6,6 +6,7 @@ import {
   fileHandleInStepMessage,
   missingGrantMessage,
   oldFileStubMessage,
+  personConfirmTimeoutRefusal,
   submitOutsideStepMessage,
 } from './messages'
 import { asFileHandle, carriesFileHandle } from './runtime-context'
@@ -13,6 +14,9 @@ import type {
   ActionSubmission,
   ActionSubmitResult,
   AutomationContext,
+  FunctionCaller,
+  PersonConfirmRequest,
+  PersonConfirmResult,
   BlueprintQueryOptions,
   BlueprintQueryResult,
   ConversationTranscript,
@@ -51,8 +55,8 @@ import type {
  * for a refusal, and on `calls` for what ran.
  */
 export interface TestCall {
-  kind: 'step' | 'log' | 'agent' | 'plugin' | 'http' | 'blueprint' | 'action' | 'file' | 'conversation'
-  /** Step name, log message, agent slug, `install:capability`, URL, object type, Action apiName, or `transcript`. */
+  kind: 'step' | 'log' | 'agent' | 'plugin' | 'http' | 'blueprint' | 'action' | 'file' | 'conversation' | 'person'
+  /** Step name, log message, agent slug, `install:capability`, URL, object type, Action apiName, `transcript`, or the person's answer. */
   label: string
   /** Present on a step: how it ended. */
   status?: 'ok' | 'error'
@@ -62,6 +66,12 @@ export interface TestCall {
 export interface TestContextOptions {
   runId?: string
   workspaceId?: string
+  /** Who asked for the run through an Agent; `null` (no Agent) by default. */
+  caller?: FunctionCaller | null
+  /** The conversation's variables; `{}` by default. */
+  variables?: Record<string, unknown>
+  /** How the person answers `ctx.person.confirm`: a fixed answer or a function of the request; `unavailable` by default. */
+  confirm?: PersonConfirmResult | ((request: PersonConfirmRequest) => PersonConfirmResult)
   /** What the run was started with. Passed through verbatim — a unit test
    *  states exactly what the handler sees; defaults are `startRun`'s job. */
   input?: Record<string, unknown>
@@ -156,6 +166,8 @@ export function createTestContext(options: TestContextOptions = {}): TestContext
   const ctx: AutomationContext = {
     runId: options.runId ?? 'test-run',
     workspaceId: options.workspaceId ?? 'test-workspace',
+    caller: options.caller ?? null,
+    variables: options.variables ?? {},
     input: options.input ?? {},
 
     step: {
@@ -345,6 +357,16 @@ export function createTestContext(options: TestContextOptions = {}): TestContext
       },
     },
 
+    person: {
+      async confirm(request) {
+        const refused = personConfirmTimeoutRefusal(request.timeoutMinutes)
+        if (refused) throw new Error(refused)
+        const answer = typeof options.confirm === 'function' ? options.confirm(request) : (options.confirm ?? 'unavailable')
+        calls.push({ kind: 'person', label: answer })
+        return answer
+      },
+    },
+
     conversation: {
       async transcript(): Promise<ConversationTranscript | null> {
         requireGrant('conversation:read')

package/src/types.ts

@@ -479,12 +479,89 @@ export interface ActionSubmitResult {
   lifecycle: ActionRequestLifecycle
 }
 
+/**
+ * Who asked an Agent for this run, as the platform knows them. Set by the
+ * platform beside the run's input, never by the model, so a Function can
+ * trust it for identity and authorization.
+ */
+export type FunctionCaller = (
+  /** A signed-in member of the workspace. */
+  | { kind: 'person'; userId: string }
+  /** A system calling with one of the Agent's API keys. */
+  | { kind: 'api-key'; apiKeyId: string }
+  /** An end user signed in with a chat token your backend minted (`externalUserId` is your id for them). */
+  | { kind: 'external-user'; externalUserId: string }
+  /**
+   * A customer on a messaging channel. `application` is the channel
+   * application's name, or the workspace channel's slug; `customerId` is the
+   * channel's id for the customer, such as a phone number.
+   */
+  | { kind: 'channel'; application: string; customerId: string }
+) & {
+  /** The Agent whose tool call started this run. */
+  agentId: string
+  /** The conversation it was in. */
+  conversationId: string
+}
+
+/**
+ * The longest `ctx.person.confirm` waits, in minutes. A Function run ends at
+ * ten minutes, waits included, so a question holds at most eight and leaves
+ * two for the Function's own work, the same ceiling as `ctx.agent`'s
+ * `timeoutMs`. A longer wait for a person belongs in a workflow's confirm node.
+ */
+export const PERSON_CONFIRM_MAX_MINUTES = 8
+/** How long `ctx.person.confirm` waits when the Function names no `timeoutMinutes`. */
+export const PERSON_CONFIRM_DEFAULT_MINUTES = 5
+
+/** What `ctx.person.confirm` asks the person. */
+export interface PersonConfirmRequest {
+  /** What will be done, in one sentence the person can say yes to ("Refund 49.00 to the card ending 4242"). */
+  summary: string
+  /** Anything else they should see first, as plain text. */
+  details?: string
+  /** The confirm button's label; "Confirm" by default. */
+  confirmLabel?: string
+  /** The cancel button's label; "Cancel" by default. */
+  cancelLabel?: string
+  /**
+   * How long the question stays open, in whole minutes from 1 to 8; 5 by
+   * default. The run still ends at ten minutes, waits included.
+   */
+  timeoutMinutes?: number
+}
+
+/**
+ * The person's answer. `unavailable`: no Agent started this run from a
+ * conversation (a schedule, a manual run, a workflow, a dry run), or the Agent
+ * was talking to nobody the platform can name, so there is nobody to ask; or
+ * the conversation is on a messaging channel, which cannot show the question.
+ */
+export type PersonConfirmResult = 'confirmed' | 'cancelled' | 'expired' | 'unavailable'
+
 /**
  * `notify` still arrives with a later slice; `governed` is here.
  */
 export interface AutomationContext {
   runId: string
   workspaceId: string
+  /**
+   * Who asked for this run, when an Agent's tool call started it: the person,
+   * API key, chat-token user or channel customer in that conversation. Set by
+   * the platform, not the model, and the same on every resumption. `null`
+   * when no Agent started the run (a schedule, a manual run, an App, a
+   * workflow), when the Agent was talking to nobody the platform can name
+   * (an Agent another Function ran with no person behind it), and in dry
+   * (dev) runs.
+   */
+  caller: FunctionCaller | null
+  /**
+   * The conversation's variables, by name: the values its entry point
+   * supplied when it started (the SDK or API, a channel). Set by the
+   * platform, not the model. `{}` when there are none or no Agent started
+   * the run.
+   */
+  variables: Record<string, unknown>
   /**
    * The values this run was started with — validated against the manifest's
    * `inputs` schema and fixed on the run row at start, so every resumption
@@ -527,6 +604,22 @@ export interface AutomationContext {
       options?: BlueprintQueryOptions,
     ): Promise<BlueprintQueryResult<T>>
   }
+  person: {
+    /**
+     * Ask the person in the conversation that started this run to confirm
+     * before the run acts. They answer on a card in web chat; in an API
+     * conversation, the system holding the Agent's key answers. The Agent
+     * waits for the answer, and so does this run, durably, without holding a
+     * connection. A conversation on a messaging channel (WhatsApp, Telegram)
+     * cannot show the question yet and answers `unavailable` at once.
+     *
+     * Call it at the top level of the handler, not inside `ctx.step.run`, and
+     * act on the answer after it: do the work in a step only when it is
+     * `confirmed`. The question is yours, not the Agent's model's: write
+     * everything the person needs to decide in `summary` and `details`.
+     */
+    confirm(request: PersonConfirmRequest): Promise<PersonConfirmResult>
+  }
   conversation: {
     /**
      * The conversation that started THIS run, as the person saw it.