@frontera-sdk/functions 1.50.84 → 1.51.0

package/package.json

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

package/src/messages.ts

@@ -143,3 +143,47 @@ export function agentReplayMismatchMessage(agentSlug: string, originalSlug: stri
     'they are recorded once and replayed.'
   )
 }
+
+/**
+ * A step that returned a `ctx.file` handle.
+ *
+ * A step's result is kept as JSON and replayed, and JSON cannot hold the
+ * handle's readers, so the run would fail one execution later with "text is
+ * not a function", far from the step that caused it. Both fixes are named,
+ * because which one fits depends on whether the bytes are needed later.
+ */
+export function fileHandleInStepMessage(stepName: string): string {
+  return (
+    `Step "${stepName}" returned a ctx.file handle. A step's result is saved as JSON, which keeps the ` +
+    "file's details but drops text(), bytes() and stream(). Read the file inside the step and return " +
+    'what you need from it, or call ctx.file outside the step.'
+  )
+}
+
+/**
+ * Code reading `ctx.file(...).signedUrl`, which a handle no longer has.
+ *
+ * A bundle deployed before the change still reads it. Without this it gets
+ * `undefined`, and fails later in `fetch(undefined)` with nothing pointing
+ * back here; the readers are named so the fix is plain.
+ */
+export function signedUrlRemovedMessage(): string {
+  return (
+    'ctx.file() no longer returns signedUrl: Function code cannot open network connections of its own. ' +
+    'Read the file with the handle instead: await file.text(), await file.bytes() or await file.stream().'
+  )
+}
+
+/**
+ * A `createTestContext` file stub written for the handle's old shape.
+ *
+ * An existing test passing `{ signedUrl, sizeBytes }` has no `content`, and
+ * would otherwise fail inside `ctx.file` as a bare TypeError on `undefined`.
+ */
+export function oldFileStubMessage(fileId: string): string {
+  return (
+    `The file stub for "${fileId}" has no content. ctx.file now returns the file's bytes rather than a signedUrl, ` +
+    `so stub it with its content: files: { '${fileId}': { content: '…', mimeType: '…', name: null } }. ` +
+    'sizeBytes is computed from the content.'
+  )
+}

package/src/runtime-context.ts

@@ -27,6 +27,8 @@ import {
   lostStepRowMessage as lostStepRowMessageText,
   duplicateSubmissionMessage as duplicateSubmissionMessageText,
   emptySubmissionKeyMessage as emptySubmissionKeyMessageText,
+  fileHandleInStepMessage,
+  signedUrlRemovedMessage,
 } from './messages'
 import type {
   ActionSubmission,
@@ -187,8 +189,9 @@ function brandTranscript(transcript: ConversationTranscript | null): Conversatio
   return transcript
 }
 
-const TRANSCRIPT_SEARCH_DEPTH = 4
-const TRANSCRIPT_SEARCH_NODES = 200
+/** How far a step result is searched for something ctx handed out: a transcript, or a file handle. */
+const RESULT_SEARCH_DEPTH = 4
+const RESULT_SEARCH_NODES = 200
 
 /**
  * How many handed-out turns a step result carries, or null when it carries
@@ -223,7 +226,7 @@ function transcriptTurnsIn(
     // Any object is searched, not only plain ones: a class instance serializes
     // its own fields, and a turn could be one of them.
     for (const child of objectChildren(value)) {
-      if (depth >= TRANSCRIPT_SEARCH_DEPTH || queue.length >= TRANSCRIPT_SEARCH_NODES) {
+      if (depth >= RESULT_SEARCH_DEPTH || queue.length >= RESULT_SEARCH_NODES) {
         // Something here is left unsearched. The nodes already queued are
         // still visited, so a transcript among them is still counted.
         complete = false
@@ -236,6 +239,54 @@ function transcriptTurnsIn(
   return complete ? { kind: 'clean' } : { kind: 'not-inspected' }
 }
 
+/**
+ * Every handle `ctx.file` returned. Branded, like a transcript, so the check
+ * below is exact: the author's own `{ fileId, bytes }` is not a handle.
+ */
+const fileHandles = new WeakSet<object>()
+
+/**
+ * Finish a handle `ctx.file` returns: brand it, and make the `signedUrl` it no
+ * longer has say where it went. Exported for the test context, which builds
+ * its own handles and must behave the same.
+ *
+ * The getter is non-enumerable, so a step result, a trace summary or
+ * `JSON.stringify` never reads it; only code that asks for `signedUrl` does.
+ */
+export function asFileHandle<T extends object>(handle: T): T {
+  fileHandles.add(handle)
+  Object.defineProperty(handle, 'signedUrl', {
+    enumerable: false,
+    get: () => {
+      throw new Error(signedUrlRemovedMessage())
+    },
+  })
+  return handle
+}
+
+/**
+ * Whether a step result carries a `ctx.file` handle, within the same bounds as
+ * `transcriptTurnsIn`.
+ *
+ * A step's result is kept as JSON and replayed, and JSON cannot hold a
+ * function: the handle comes back with its details and without `text()`,
+ * `bytes()` or `stream()`, so the run fails one execution later with "text is
+ * not a function". Caught here, it fails at the step that caused it.
+ */
+export function carriesFileHandle(out: unknown): boolean {
+  if (typeof out !== 'object' || out === null) return false
+  const queue: Array<{ value: object; depth: number }> = [{ value: out, depth: 0 }]
+  for (let next = 0; next < queue.length; next++) {
+    const { value, depth } = queue[next]!
+    if (fileHandles.has(value)) return true
+    for (const child of objectChildren(value)) {
+      if (depth >= RESULT_SEARCH_DEPTH || queue.length >= RESULT_SEARCH_NODES) break
+      queue.push({ value: child, depth: depth + 1 })
+    }
+  }
+  return false
+}
+
 /** The object-valued children of an array or object, one at a time. */
 function* objectChildren(value: object): Generator<object> {
   if (Array.isArray(value)) {
@@ -349,6 +400,32 @@ const AGENT_TURN_FINISHED_EVENT = 'agent/turn.finished'
  */
 const KEEPALIVE_HEADER = 'x-ctx-keepalive'
 
+/**
+ * Every header this module sends to the service on a Function's own authority.
+ *
+ * The runner's forwarder passes on exactly these and drops the rest, so this
+ * list is the contract between the two, owned here. The request types below
+ * accept no other name: a header added to a call without adding it here fails
+ * to compile, instead of being dropped by the forwarder in deployed runs only.
+ */
+export const FUNCTION_SERVICE_HEADERS = [
+  'content-type',
+  'x-automation-run-token',
+  'x-workspace-id',
+  KEEPALIVE_HEADER,
+] as const
+
+/**
+ * Sent only by a process holding the runner's secret (the runner itself, on
+ * its own writes). A Function process never has it, so it is not a Function
+ * header and the forwarder never passes it on.
+ */
+const RUNNER_TOKEN_HEADER = 'x-automation-runner-token'
+
+type ServiceCallHeaders = Partial<Record<(typeof FUNCTION_SERVICE_HEADERS)[number] | typeof RUNNER_TOKEN_HEADER, string>>
+/** A request to the service: `RequestInit` with its headers held to the names above. */
+type ServiceCallInit = Omit<RequestInit, 'headers'> & { headers?: ServiceCallHeaders }
+
 type AgentRunOptions = { files?: ReadonlyArray<{ fileId: string }>; timeoutMs?: number }
 
 type AgentTurnStatus = 'queued' | 'running' | 'succeeded' | 'failed' | 'parked' | 'cancelled'
@@ -416,6 +493,31 @@ interface Deps {
    * because it has nothing to pass.
    */
   runnerToken?: string
+  /**
+   * The Unix socket the runner's forwarder listens on. Inside the deployed
+   * runner a Function process is denied internet sockets and reaches the
+   * forwarder only here, so every `ctx` call and `ctx.file` read goes over it.
+   * Absent (the CLI's dev worker, tests): calls go straight to `serviceUrl`.
+   */
+  socketPath?: string
+}
+
+/**
+ * The path under the forwarder that signed storage reads go to. Owned here and
+ * imported by the runner's forwarder, which routes on it, so the two cannot
+ * drift apart.
+ */
+export const FORWARDER_STORAGE_PATH = '/storage'
+
+/**
+ * A signed storage URL, pointed at the forwarder's storage path under
+ * `forwarderUrl`: same path and signature, forwarder host. The forwarder sends
+ * it on to real storage. In a Function process the service URL IS the
+ * forwarder, and its host is a placeholder; the Unix socket decides where it goes.
+ */
+function readdressToForwarder(forwarderUrl: string, signedUrl: string): string {
+  const signed = new URL(signedUrl)
+  return `${forwarderUrl}${FORWARDER_STORAGE_PATH}${signed.pathname}${signed.search}`
 }
 
 export {
@@ -443,6 +545,11 @@ class GrantError extends Error {
 
 export function buildContext(deps: Deps): AutomationContext {
   const serviceUrl = deps.serviceUrl ?? SERVICE_URL
+  // Every call to the service goes through here. In the runner it rides the
+  // forwarder's Unix socket (the one path left open); elsewhere it is a plain
+  // fetch. `unix` is a Bun extension to RequestInit, hence the cast.
+  const serviceFetch = (path: string, init?: ServiceCallInit): Promise<Response> =>
+    fetch(`${serviceUrl}${path}`, deps.socketPath ? { ...init, unix: deps.socketPath } as RequestInit : init)
   const requireGrant = (grant: string) => {
     if (!deps.grants.includes(grant)) throw new GrantError(grant)
   }
@@ -460,10 +567,10 @@ export function buildContext(deps: Deps): AutomationContext {
    * 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> = {
+  const runnerHeaders: ServiceCallHeaders = {
     'content-type': 'application/json',
     'x-automation-run-token': deps.runToken,
-    ...(deps.runnerToken ? { 'x-automation-runner-token': deps.runnerToken } : {}),
+    ...(deps.runnerToken ? { [RUNNER_TOKEN_HEADER]: deps.runnerToken } : {}),
   }
 
   /**
@@ -503,7 +610,7 @@ export function buildContext(deps: Deps): AutomationContext {
   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`, {
+      const res = await serviceFetch(`/v1/automations/runner/runs/${deps.runId}/steps`, {
         method: 'POST',
         headers: runnerHeaders,
         body: JSON.stringify({
@@ -553,8 +660,8 @@ export function buildContext(deps: Deps): AutomationContext {
       ...(body.detail === undefined ? {} : { detail: jsonbSafe(body.detail) }),
     }
     try {
-      const res = await fetch(
-        `${serviceUrl}/v1/automations/runner/runs/${deps.runId}/steps/${stepId}/complete`,
+      const res = await serviceFetch(
+        `/v1/automations/runner/runs/${deps.runId}/steps/${stepId}/complete`,
         { method: 'POST', headers: runnerHeaders, body: JSON.stringify(payload) },
       )
       if (!res.ok) console.warn(`[ctx] step complete failed (non-fatal): ${res.status}`)
@@ -634,13 +741,13 @@ export function buildContext(deps: Deps): AutomationContext {
    * 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) =>
+  const scoped = (path: string, init?: ServiceCallInit) =>
     // `/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}`, {
+    serviceFetch(`/v1/automations/runner${path}`, {
       ...init,
       headers: {
         ...(init?.headers ?? {}),
@@ -707,6 +814,7 @@ export function buildContext(deps: Deps): AutomationContext {
           { stepId, stepName: name, submitted: new Set<string>() },
           fn,
         )
+        if (carriesFileHandle(out)) throw new Error(fileHandleInStepMessage(name))
         await completeStep(stepId, {
           status: 'ok',
           durationMs: Date.now() - t0,
@@ -961,21 +1069,45 @@ export function buildContext(deps: Deps): AutomationContext {
     file: (ref: { fileId: string }) =>
       step('file', `file:${ref.fileId.slice(0, 8)}`, async () => {
         // No grant: this only reads a file the run was GIVEN — the route
-        // refuses any fileId that is not among this run's own inputs. Returns
-        // a short-lived signed URL plus the authoritative mime/size/name; in a
-        // dry dev run it returns null, like every other ctx call.
+        // refuses any fileId that is not among this run's own inputs. In a dry
+        // dev run it returns null, like every other ctx call.
         const res = await scoped('/ctx/file-resolve', {
           method: 'POST',
           body: JSON.stringify({ fileId: ref.fileId }),
         })
         if (!res.ok) throw new Error(`file ${ref.fileId} → ${res.status} ${await refusal(res)}`)
-        return ((await res.json()) as {
+        const file = ((await res.json()) as {
           data: { file: { fileId: string; signedUrl: string; mimeType: string; sizeBytes: number; name: string | null } | null }
         }).data.file
+        if (!file) return null
+
+        // The signed URL never leaves this closure. Function code cannot open a
+        // network socket in the runner, and a URL in a step row would be a live
+        // credential — so the SDK does the read, over the same forwarder socket,
+        // and hands back the bytes. `readFile` re-resolves each time it is
+        // called, so a large file need not sit in memory unless the author asks.
+        const readFile = async (): Promise<Response> => {
+          const target = deps.socketPath ? readdressToForwarder(serviceUrl, file.signedUrl) : file.signedUrl
+          const response = await fetch(target, deps.socketPath ? { unix: deps.socketPath } as RequestInit : undefined)
+          if (!response.ok) throw new Error(`file ${ref.fileId} download → ${response.status}`)
+          return response
+        }
+        const handle: import('./types').ResolvedFileHandle = {
+          fileId: file.fileId,
+          mimeType: file.mimeType,
+          sizeBytes: file.sizeBytes,
+          name: file.name,
+          bytes: async () => new Uint8Array(await (await readFile()).arrayBuffer()),
+          text: async () => (await readFile()).text(),
+          stream: async () => {
+            const body = (await readFile()).body
+            if (!body) throw new Error(`file ${ref.fileId} download had no body`)
+            return body
+          },
+        }
+        return asFileHandle(handle)
       },
-      // Everything the handle carries EXCEPT `signedUrl`. That URL is a
-      // short-lived credential, and a row is exactly the wrong place for one:
-      // details are rendered verbatim and kept for as long as the run is.
+      // The row records the file's identity, never its bytes or a way to read them.
       (out) =>
         out
           ? { fileId: out.fileId, mimeType: out.mimeType, sizeBytes: out.sizeBytes, name: out.name }

package/src/testing.ts

@@ -3,9 +3,12 @@ import {
   duplicateStepMessage,
   duplicateSubmissionMessage,
   emptySubmissionKeyMessage,
+  fileHandleInStepMessage,
   missingGrantMessage,
+  oldFileStubMessage,
   submitOutsideStepMessage,
 } from './messages'
+import { asFileHandle, carriesFileHandle } from './runtime-context'
 import type {
   ActionSubmission,
   ActionSubmitResult,
@@ -77,7 +80,7 @@ export interface TestContextOptions {
   agents?: Record<string, (prompt: string) => Promise<{ text: string }> | { text: string }>
   /** Per-fileId answers for `ctx.file`: what the resolved handle should carry.
    *  An unstubbed fileId throws — a fabricated handle is a false pass. */
-  files?: Record<string, { signedUrl: string; mimeType: string; sizeBytes: number; name: string | null }>
+  files?: Record<string, { content: string | Uint8Array; mimeType: string; name: string | null }>
   /**
    * Per-install, per-capability plugin answers: `{ crm: { create_ticket: (input) => ({ data }) } }`.
    * An unstubbed capability throws rather than answering — a fabricated
@@ -163,6 +166,9 @@ export function createTestContext(options: TestContextOptions = {}): TestContext
         return await stepScope.run({ stepName: name, submitted: new Set<string>() }, async () => {
           try {
             const out = await fn()
+            // Nothing here replays a step, so the handle would keep working in
+            // a test and break in a deployed run.
+            if (carriesFileHandle(out)) throw new Error(fileHandleInStepMessage(name))
             calls.push({ kind: 'step', label: name, status: 'ok' })
             return out
           } catch (err) {
@@ -194,11 +200,25 @@ export function createTestContext(options: TestContextOptions = {}): TestContext
       // stubbed would otherwise pass on made-up bytes.
       if (!stub) {
         throw new Error(
-          `No file stub for "${ref.fileId}". Pass files: { '${ref.fileId}': { signedUrl: '…', ` +
-            "mimeType: '…', sizeBytes: 0, name: null } } to createTestContext.",
+          `No file stub for "${ref.fileId}". Pass files: { '${ref.fileId}': { content: '…', ` +
+            "mimeType: '…', name: null } } to createTestContext.",
         )
       }
-      return { fileId: ref.fileId, ...stub }
+      // A stub written for the handle's old shape ({ signedUrl, sizeBytes })
+      // has no content; without this, reading it fails as a bare TypeError.
+      if (typeof stub.content !== 'string' && !(stub.content instanceof Uint8Array)) {
+        throw new Error(oldFileStubMessage(ref.fileId))
+      }
+      const bytes = typeof stub.content === 'string' ? new TextEncoder().encode(stub.content) : stub.content
+      return asFileHandle({
+        fileId: ref.fileId,
+        mimeType: stub.mimeType,
+        name: stub.name,
+        sizeBytes: bytes.byteLength,
+        bytes: async () => bytes,
+        text: async () => new TextDecoder().decode(bytes),
+        stream: async () => new ReadableStream<Uint8Array>({ start(controller) { controller.enqueue(bytes); controller.close() } }),
+      })
     },
 
     agent(slug: string) {

package/src/types.ts

@@ -233,15 +233,31 @@ export interface AgentHandle {
 }
 
 /**
- * What `ctx.file(ref)` resolves to: a short-lived signed URL plus the
- * authoritative mime/size resolved at upload. `null` only in a dry dev run.
+ * What `ctx.file(ref)` resolves to: the file's identity plus readers that fetch
+ * its bytes. `null` only in a dry dev run.
+ *
+ * There is no URL. In the deployed runner a Function cannot open a network
+ * socket, and a signed URL would be a live credential; the readers download
+ * over the runner's forwarder inside the SDK. Each reader fetches afresh, so a
+ * large file need not stay in memory.
  */
 export interface ResolvedFileHandle {
   fileId: string
-  signedUrl: string
   mimeType: string
   sizeBytes: number
   name: string | null
+  /**
+   * The whole file as bytes.
+   *
+   * Each reader downloads the file again, through a link that expires about an
+   * hour after `ctx.file` returned the handle. Read it soon after, or call
+   * `ctx.file` again rather than keeping a handle across a long wait.
+   */
+  bytes(): Promise<Uint8Array>
+  /** The whole file decoded as UTF-8 text. */
+  text(): Promise<string>
+  /** The file as a stream, for reading large files without holding them in memory. */
+  stream(): Promise<ReadableStream<Uint8Array>>
 }
 
 /**