@frontera-sdk/functions 1.50.84 → 1.51.1

package/package.json

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

package/src/index.ts

@@ -12,8 +12,12 @@ export {
 export { createTestContext } from './testing'
 export type { TestCall, TestContext, TestContextOptions } from './testing'
 export {
+  DEFAULT_MAX_FILES,
+  MAX_FILES_CAP,
   MAX_INPUT_BYTES,
   checkInputFieldSpec,
+  isFileInputType,
+  maxFilesOf,
   redactedInputKeys,
   sanitizeInputsSchema,
   validateInputValue,

package/src/inputs.ts

@@ -27,20 +27,39 @@ export type InputValidation =
  * naming a non-empty string `fileId`). It deliberately does NOT authorize the id
  * or check mime/size — those need the DB and the caller's workspace scope, so the
  * SERVER (`run-service` via `resolveFile`) authorizes and resolves the reference
- * after this passes.
+ * after this passes. `files` is a list of the same reference; its count is
+ * checked in `validateInputValue`, which knows the field's `maxFiles`.
  */
+const isFileRef = (v: unknown): boolean =>
+  typeof v === 'object' &&
+  v !== null &&
+  !Array.isArray(v) &&
+  typeof (v as { fileId?: unknown }).fileId === 'string' &&
+  (v as { fileId: string }).fileId.length > 0
+
 export const TYPE_CHECK: Record<InputFieldSpec['type'], (v: unknown) => boolean> = {
   string: (v) => typeof v === 'string',
   number: (v) => typeof v === 'number' && Number.isFinite(v),
   boolean: (v) => typeof v === 'boolean',
   object: (v) => typeof v === 'object' && v !== null && !Array.isArray(v),
   array: Array.isArray,
-  file: (v) =>
-    typeof v === 'object' &&
-    v !== null &&
-    !Array.isArray(v) &&
-    typeof (v as { fileId?: unknown }).fileId === 'string' &&
-    (v as { fileId: string }).fileId.length > 0,
+  file: isFileRef,
+  files: (v) => Array.isArray(v) && v.every(isFileRef),
+}
+
+/** The most files a `files` input holds when its spec names no `maxFiles`. */
+export const DEFAULT_MAX_FILES = 20
+/** The highest `maxFiles` a `files` input may declare. */
+export const MAX_FILES_CAP = 50
+
+/** Whether an input of this type holds file references: one, or a list. */
+export function isFileInputType(type: unknown): type is 'file' | 'files' {
+  return type === 'file' || type === 'files'
+}
+
+/** The most files a `files` input holds. */
+export function maxFilesOf(spec: Pick<InputFieldSpec, 'maxFiles'>): number {
+  return spec.maxFiles ?? DEFAULT_MAX_FILES
 }
 
 /** Lowercase kebab, matching `validateManifest`'s automation-`name` grammar. */
@@ -48,7 +67,7 @@ const INPUT_NAME_KEBAB_RE = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/
 /** Lowercase snake — the one allowance kebab doesn't cover. */
 const INPUT_NAME_SNAKE_RE = /^[a-z][a-z0-9_]*$/
 
-const INPUT_TYPES = new Set<InputFieldSpec['type']>(['string', 'number', 'boolean', 'object', 'array', 'file'])
+const INPUT_TYPES = new Set<InputFieldSpec['type']>(['string', 'number', 'boolean', 'object', 'array', 'file', 'files'])
 
 /** Keys `checkInputFieldSpec` understands on ONE input spec (`inputs.<name>`).
  *  Anything else there is a warning, same philosophy as `manifest.ts`'s
@@ -63,6 +82,7 @@ const INPUT_SPEC_KEYS = new Set([
   'redact',
   'accept',
   'maxBytes',
+  'maxFiles',
 ])
 
 /**
@@ -129,6 +149,7 @@ export function checkInputFieldSpec(key: string, raw: unknown): InputFieldCheck
     redact?: unknown
     accept?: unknown
     maxBytes?: unknown
+    maxFiles?: unknown
   }
 
   if (spec.description !== undefined && typeof spec.description !== 'string') {
@@ -136,7 +157,7 @@ export function checkInputFieldSpec(key: string, raw: unknown): InputFieldCheck
   }
 
   if (typeof spec.type !== 'string' || !INPUT_TYPES.has(spec.type as InputFieldSpec['type'])) {
-    errors.push(`input "${key}": type must be one of string, number, boolean, object, array, file`)
+    errors.push(`input "${key}": type must be one of string, number, boolean, object, array, file, files`)
     return { errors, warnings }
   }
   const t = spec.type as InputFieldSpec['type']
@@ -196,12 +217,12 @@ export function checkInputFieldSpec(key: string, raw: unknown): InputFieldCheck
     }
   }
 
-  // `accept`/`maxBytes` are the file-only constraints — refused on any other
-  // type so a typo like `accept` on a string field is loud, not silently
-  // ignored. They constrain the UPLOAD, not the value on the run row (which is
+  // `accept`/`maxBytes` are the file-only constraints, for one file or a list
+  // of them — refused on any other type so a typo like `accept` on a string
+  // field is loud, not silently ignored. They constrain the UPLOAD, not the value on the run row (which is
   // only a reference), so the server enforces them; here we check well-formedness.
   if (spec.accept !== undefined) {
-    if (t !== 'file') {
+    if (!isFileInputType(t)) {
       errors.push(`input "${key}": accept is only valid for file inputs`)
     } else if (
       !Array.isArray(spec.accept)
@@ -212,18 +233,30 @@ export function checkInputFieldSpec(key: string, raw: unknown): InputFieldCheck
     }
   }
   if (spec.maxBytes !== undefined) {
-    if (t !== 'file') {
+    if (!isFileInputType(t)) {
       errors.push(`input "${key}": maxBytes is only valid for file inputs`)
     } else if (typeof spec.maxBytes !== 'number' || !Number.isFinite(spec.maxBytes) || spec.maxBytes <= 0) {
       errors.push(`input "${key}": maxBytes must be a positive number`)
     }
   }
+  if (spec.maxFiles !== undefined) {
+    if (t !== 'files') {
+      errors.push(`input "${key}": maxFiles is only valid for files inputs`)
+    } else if (
+      typeof spec.maxFiles !== 'number'
+      || !Number.isInteger(spec.maxFiles)
+      || spec.maxFiles < 1
+      || spec.maxFiles > MAX_FILES_CAP
+    ) {
+      errors.push(`input "${key}": maxFiles must be a whole number from 1 to ${MAX_FILES_CAP}`)
+    }
+  }
 
   let defaultOk = true
   if (spec.default !== undefined) {
-    // A `file` carries a reference to an uploaded item, so a fixed literal
-    // default is meaningless — refused rather than type-checked.
-    if (t === 'file') {
+    // A `file` or `files` input carries references to uploaded items, so a
+    // fixed literal default is meaningless — refused rather than type-checked.
+    if (isFileInputType(t)) {
       errors.push(`input "${key}": a file input cannot have a default`)
       defaultOk = false
     } else if (!TYPE_CHECK[t](spec.default)) {
@@ -290,9 +323,23 @@ export function validateInputValue(
       continue
     }
     if (!check(v)) {
-      errors.push(`"${key}" must be of type ${spec.type}`)
+      errors.push(
+        spec.type === 'files' ? `"${key}" must be a list of files` : `"${key}" must be of type ${spec.type}`,
+      )
       continue
     }
+    if (spec.type === 'files') {
+      const count = (v as unknown[]).length
+      // An empty list says "no files", which a required input does not accept.
+      if (count === 0 && spec.required === true) {
+        errors.push(`"${key}" is required — add at least one file`)
+        continue
+      }
+      if (count > maxFilesOf(spec)) {
+        errors.push(`"${key}" holds ${count} files — the most it takes is ${maxFilesOf(spec)}`)
+        continue
+      }
+    }
     if (spec.enum && !spec.enum.includes(v as string | number)) {
       errors.push(`"${key}" must be one of ${spec.enum.join(', ')}`)
       continue

package/src/manifest.ts

@@ -1,5 +1,5 @@
 import { CronExpressionParser } from 'cron-parser'
-import { MAX_INPUT_BYTES, checkInputFieldSpec } from './inputs'
+import { MAX_INPUT_BYTES, checkInputFieldSpec, isFileInputType } from './inputs'
 
 const SEGMENT = '[a-z][a-z0-9]*(?:-[a-z0-9]+)*'
 const NAME_RE = new RegExp(`^${SEGMENT}$`)
@@ -246,10 +246,11 @@ export function validateManifest(input: unknown): ValidationResult {
         for (const [key, raw] of Object.entries(inputs as Record<string, unknown>)) {
           const spec = raw as { type?: unknown; required?: unknown; default?: unknown }
           if (spec?.required === true && spec.default === undefined) {
-            // A `file` input can never carry a default (refused above), so the
-            // "add a default" remedy would send the author straight into the
-            // next validation error — name the two remedies that actually work.
-            const remedy = spec.type === 'file'
+            // A `file` or `files` input can never carry a default (refused
+            // above), so the "add a default" remedy would send the author
+            // straight into the next validation error — name the two remedies
+            // that actually work.
+            const remedy = isFileInputType(spec.type)
               ? 'A file input cannot have a default — make the input optional or the trigger manual.'
               : 'Add a default or make the trigger manual.'
             errors.push(

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,46 @@ 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 (a `file`
+        // input, or one item of a `files` input). 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

@@ -78,21 +78,26 @@ export type Grant =
  *  philosophy as the grant grammar: small enough that a wrong shape is
  *  refusable with a sentence, wide enough for real parameters. */
 export interface InputFieldSpec {
-  type: 'string' | 'number' | 'boolean' | 'object' | 'array' | 'file'
+  type: 'string' | 'number' | 'boolean' | 'object' | 'array' | 'file' | 'files'
   /** Refused at run start when absent. Mutually exclusive with `default`. */
   required?: boolean
   /** Applied at run start when the field is absent. Cron runs rely on these.
-   *  Not permitted on a `file` field — a file has no meaningful literal default. */
+   *  Not permitted on a `file` or `files` field — a file has no meaningful literal default. */
   default?: unknown
   description?: string
   /** Allowed values — string and number types only. */
   enum?: readonly (string | number)[]
-  /** `file` type only. Allowed MIME patterns, e.g. `['image/*', 'application/pdf']`.
+  /** `file` and `files` types only. Allowed MIME patterns, e.g. `['image/*', 'application/pdf']`.
+   *  On a `files` field it applies to each file.
    *  A declaration aid: the value on the run row is only a reference, so this is
    *  enforced server-side at upload and at run start, never against the value here. */
   accept?: readonly string[]
-  /** `file` type only. Maximum upload size in bytes, enforced server-side. */
+  /** `file` and `files` types only. Maximum upload size in bytes, enforced server-side.
+   *  On a `files` field it applies to each file. */
   maxBytes?: number
+  /** `files` type only. The most files the field holds: a whole number from 1
+   *  to 50, 20 when absent. */
+  maxFiles?: number
   /**
    * Mask this field's VALUE wherever a person reads the run.
    *
@@ -233,15 +238,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>>
 }
 
 /**
@@ -472,9 +493,10 @@ export interface AutomationContext {
   log(message: string, data?: Record<string, unknown>): Promise<void>
   agent(slug: string): AgentHandle
   /**
-   * Resolve one of THIS run's `file` inputs to a readable form (signed URL +
-   * authoritative mime/size). No grant — it only reads files the run was given;
-   * any other fileId is refused. `null` in a dry dev run.
+   * Resolve one of THIS run's files to a readable form (signed URL +
+   * authoritative mime/size): the value of a `file` input, or one item of a
+   * `files` input. No grant — it only reads files the run was given; any other
+   * fileId is refused. `null` in a dry dev run.
    */
   file(ref: FileRef): Promise<ResolvedFileHandle | null>
   /** One Plugin install, by the name `frontera plugin list` shows. Needs `plugin:<install>:<capability>` per call. */