@frontera-sdk/automation 1.45.14 → 1.46.0

package/package.json

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

package/src/inputs.ts

@@ -13,7 +13,7 @@ export type InputValidation =
   | { ok: false; errors: string[] }
 
 /**
- * The five input types' runtime validators, keyed by `InputFieldSpec['type']`.
+ * The input types' runtime validators, keyed by `InputFieldSpec['type']`.
  *
  * Single source of truth for "does this value have this type" — `validateInputValue`'s
  * value check and `checkInputFieldSpec`'s default/enum checks all call this instead
@@ -22,6 +22,12 @@ export type InputValidation =
  * deploy-time and run-time again. It drifting once — `manifest.ts`'s old `okDefault`
  * used `typeof spec.default === 'number'` and admitted `default: Infinity` — is why
  * this is exported rather than kept module-private.
+ *
+ * `file` is shape-only here: it confirms the value is a `FileRef` (a plain object
+ * 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.
  */
 export const TYPE_CHECK: Record<InputFieldSpec['type'], (v: unknown) => boolean> = {
   string: (v) => typeof v === 'string',
@@ -29,6 +35,12 @@ export const TYPE_CHECK: Record<InputFieldSpec['type'], (v: unknown) => boolean>
   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,
 }
 
 /** Lowercase kebab, matching `validateManifest`'s automation-`name` grammar. */
@@ -36,7 +48,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'])
+const INPUT_TYPES = new Set<InputFieldSpec['type']>(['string', 'number', 'boolean', 'object', 'array', 'file'])
 
 /** Keys `checkInputFieldSpec` understands on ONE input spec (`inputs.<name>`).
  *  Anything else there is a warning, same philosophy as `manifest.ts`'s
@@ -49,6 +61,8 @@ const INPUT_SPEC_KEYS = new Set([
   'description',
   'enum',
   'redact',
+  'accept',
+  'maxBytes',
 ])
 
 /**
@@ -113,6 +127,8 @@ export function checkInputFieldSpec(key: string, raw: unknown): InputFieldCheck
     enum?: unknown
     description?: unknown
     redact?: unknown
+    accept?: unknown
+    maxBytes?: unknown
   }
 
   if (spec.description !== undefined && typeof spec.description !== 'string') {
@@ -120,7 +136,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`)
+    errors.push(`input "${key}": type must be one of string, number, boolean, object, array, file`)
     return { errors, warnings }
   }
   const t = spec.type as InputFieldSpec['type']
@@ -180,9 +196,37 @@ 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
+  // only a reference), so the server enforces them; here we check well-formedness.
+  if (spec.accept !== undefined) {
+    if (t !== 'file') {
+      errors.push(`input "${key}": accept is only valid for file inputs`)
+    } else if (
+      !Array.isArray(spec.accept)
+      || spec.accept.length === 0
+      || spec.accept.some((a) => typeof a !== 'string' || a.length === 0)
+    ) {
+      errors.push(`input "${key}": accept must be a non-empty array of MIME patterns`)
+    }
+  }
+  if (spec.maxBytes !== undefined) {
+    if (t !== 'file') {
+      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`)
+    }
+  }
+
   let defaultOk = true
   if (spec.default !== undefined) {
-    if (!TYPE_CHECK[t](spec.default)) {
+    // A `file` carries a reference to an uploaded item, so a fixed literal
+    // default is meaningless — refused rather than type-checked.
+    if (t === 'file') {
+      errors.push(`input "${key}": a file input cannot have a default`)
+      defaultOk = false
+    } else if (!TYPE_CHECK[t](spec.default)) {
       errors.push(`input "${key}": default must match the declared type`)
       defaultOk = false
     }

package/src/manifest.ts

@@ -244,11 +244,17 @@ export function validateManifest(input: unknown): ValidationResult {
       const trig = m.trigger as { cron?: unknown } | undefined
       if (typeof trig?.cron === 'string') {
         for (const [key, raw] of Object.entries(inputs as Record<string, unknown>)) {
-          const spec = raw as { required?: unknown; default?: 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 input cannot have a default — make the input optional or the trigger manual.'
+              : 'Add a default or make the trigger manual.'
             errors.push(
               `input "${key}" is required with no default, and the trigger is a cron — `
-                + 'cron has nobody to ask. Add a default or make the trigger manual.',
+                + `cron has nobody to ask. ${remedy}`,
             )
           }
         }

package/src/runtime-context.ts

@@ -38,6 +38,143 @@ import type {
 
 const SERVICE_URL = process.env.SERVICE_URL ?? 'http://localhost:4000'
 
+/**
+ * How much of a summary one step row may carry.
+ *
+ * A step row is telemetry, not storage: it is read by a human scanning a run,
+ * and it is written on every ctx call of every run. So what it records about a
+ * call is bounded rather than complete, and a value that does not fit is
+ * reported as a SIZE — which tells the reader the value existed and was large,
+ * instead of showing them the empty panel this cap exists to avoid.
+ */
+const DETAIL_MAX_CHARS = 4_000
+/** How much of an agent's answer a row keeps, so a trace can be read without
+ *  re-running the agent. */
+const PREVIEW_MAX_CHARS = 500
+
+/** JSON length of a value, or null when it does not serialize (a cycle, a BigInt). */
+function jsonSize(value: unknown): number | null {
+  try {
+    const json = JSON.stringify(value)
+    return json === undefined ? null : json.length
+  } catch {
+    return null
+  }
+}
+
+/**
+ * A NUL and an unpaired surrogate, which Postgres `jsonb` REFUSES rather than
+ * 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 UNPAIRED_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g
+
+/**
+ * Make a value storable, by removing the two byte classes `jsonb` rejects.
+ *
+ * Both are reachable from what a row now carries: `preview` cuts at a fixed
+ * offset and can split an emoji in half, and an author's step result may hold
+ * text pulled out of a PDF or a Postgres `text` column, where a NUL is routine.
+ *
+ * What a refusal costs is not the detail. A rejected insert loses the whole
+ * ROW — `recordStep` swallows a non-2xx by contract — and a rejected completion
+ * leaves an author's step reading `running` forever inside a run that finished,
+ * because the update is guarded on that status. Either is a worse trace than
+ * the empty panel this file set out to fix, so the scrub sits at the write
+ * rather than in each summarizer: one rule covering summaries, error messages
+ * and `ctx.log`'s author-supplied data alike.
+ */
+function jsonbSafeText(text: string): string {
+  return text.replace(NUL, '').replace(UNPAIRED_SURROGATE, '')
+}
+
+function jsonbSafe(value: unknown, seen: WeakSet<object> = new WeakSet()): unknown {
+  if (typeof value === 'string') return jsonbSafeText(value)
+  if (value === null || typeof value !== 'object') return value
+  // A cycle cannot be serialized at all: dropped here, named, rather than left
+  // 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
+  // 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.
+  seen.add(value)
+  const safe = Array.isArray(value)
+    ? value.map((item) => jsonbSafe(item, seen))
+    : Object.fromEntries(
+        Object.entries(value).map(([key, item]) => [jsonbSafeText(key), jsonbSafe(item, seen)]),
+      )
+  seen.delete(value)
+  return safe
+}
+
+/**
+ * `{ [key]: value }`, but only while the value stays small.
+ *
+ * Per key rather than over the whole detail so one enormous filter cannot cost
+ * the counts standing next to it — dropping everything would leave the row
+ * exactly as empty as it was before any of this existed.
+ */
+function ifSmall(key: string, value: unknown, max: number): Record<string, unknown> {
+  if (value === undefined) return {}
+  const size = jsonSize(value)
+  return size !== null && size <= max ? { [key]: value } : {}
+}
+
+/** The head of a text answer, marked when cut. */
+function preview(text: string): string {
+  return text.length <= PREVIEW_MAX_CHARS ? text : `${text.slice(0, PREVIEW_MAX_CHARS)}\u2026`
+}
+
+/**
+ * Run a summarizer for a row's `detail`, defending the run from it.
+ *
+ * Never throws and never grows without bound. A summary is a record OF the
+ * work by the same rule `recordStep` follows, so a summarizer that trips over
+ * a shape it did not expect — a dry dev run answering null, a service that
+ * grew a field — costs the detail, never the call it describes.
+ */
+function summarize<T>(
+  build: ((out: T) => Record<string, unknown>) | undefined,
+  out: T,
+): Record<string, unknown> | undefined {
+  if (!build) return undefined
+  let detail: Record<string, unknown>
+  try {
+    detail = build(out)
+  } catch {
+    // Named rather than omitted: an omitted detail renders as "This step
+    // recorded no detail", which is the sentence this whole path exists to
+    // stop — and it would hide a broken summarizer behind a fixed bug's
+    // symptom.
+    return { omitted: 'summary unavailable' }
+  }
+  const size = jsonSize(detail)
+  if (size === null) return { omitted: 'summary not serializable' }
+  return size <= DETAIL_MAX_CHARS ? detail : { omitted: 'summary too large', chars: size }
+}
+
+/**
+ * What an author-declared step records about its own return value.
+ *
+ * The value is already JSON — the platform stores and replays it — so keeping a
+ * copy asks nothing new of it, and it is what makes the row readable at all:
+ * without it a step shows a name and a duration for work whose result nobody
+ * can see. Bounded, and reported as a size when it does not fit, because a step
+ * that returns a thousand warehouse rows must not write them a second time into
+ * the audit trail.
+ */
+function stepResultDetail(out: unknown): Record<string, unknown> | undefined {
+  if (out === undefined) return undefined
+  const size = jsonSize(out)
+  if (size === null) return { omitted: 'result not serializable' }
+  return size <= DETAIL_MAX_CHARS
+    ? { result: out }
+    : { resultChars: size, omitted: 'result too large' }
+}
+
 /**
  * The step tools this module needs, declared structurally rather than imported
  * from `inngest`.
@@ -197,6 +334,19 @@ export function buildContext(deps: Deps): AutomationContext {
           ...(parentStepId ? { parentStepId } : {}),
           attempt: deps.attempt ?? 0,
           ...body,
+          // Last, so it applies to whatever `body` brought — see `jsonbSafe`.
+          ...(body.detail === undefined ? {} : { detail: jsonbSafe(body.detail) }),
+          // `label` and `step_name` are `text`, and a NUL is refused there too —
+          // `invalid byte sequence for encoding "UTF8": 0x00`. `ctx.log` writes
+          // the author's message as the label, so a NUL riding in from a PDF
+          // kills the row through the field NEXT to the one being scrubbed. A
+          // lone surrogate is not a hazard in a text column (the driver encodes
+          // it as U+FFFD), but it is scrubbed with it rather than reasoned about
+          // twice.
+          ...(typeof body.label === 'string' ? { label: jsonbSafeText(body.label) } : {}),
+          ...(typeof body.stepName === 'string'
+            ? { stepName: jsonbSafeText(body.stepName) }
+            : {}),
         }),
       })
       // `fetch` resolves on a 4xx/5xx, so the status is the only place a
@@ -215,10 +365,16 @@ export function buildContext(deps: Deps): AutomationContext {
   /** Close an author-declared step row. Never throws, for the same reason. */
   const completeStep = async (stepId: string, body: Record<string, unknown>): Promise<void> => {
     if (!stepId) return
+    // A row refused here is not closed at all — the service guards the update on
+    // `status = 'running'` — so the step would read `running` forever.
+    const payload = {
+      ...body,
+      ...(body.detail === undefined ? {} : { detail: jsonbSafe(body.detail) }),
+    }
     try {
       const res = await fetch(
         `${serviceUrl}/v1/automations/runner/runs/${deps.runId}/steps/${stepId}/complete`,
-        { method: 'POST', headers: runnerHeaders, body: JSON.stringify(body) },
+        { method: 'POST', headers: runnerHeaders, body: JSON.stringify(payload) },
       )
       if (!res.ok) console.warn(`[ctx] step complete failed (non-fatal): ${res.status}`)
     } catch (err) {
@@ -247,11 +403,36 @@ export function buildContext(deps: Deps): AutomationContext {
     return body
   }
 
-  const step = async (kind: string, label: string, fn: () => Promise<unknown>): Promise<unknown> => {
+  /**
+   * Record one ctx call as a row: timed, and with a bounded summary of what it
+   * did.
+   *
+   * The summary is per capability rather than generic. A reader opening
+   * `query:LoanApplication` wants the row count and the filter; a reader opening
+   * `agent:triage` wants what the agent said — a generic dump of the return
+   * value would be both larger and less useful than either. A capability whose
+   * result carries a credential (a file's signed URL) summarizes AROUND it:
+   * details are rendered verbatim in the Console.
+   */
+  const step = async <T>(
+    kind: string,
+    label: string,
+    fn: () => Promise<T>,
+    detailOf?: (out: T) => Record<string, unknown>,
+  ): Promise<T> => {
     const t0 = Date.now()
     try {
       const out = await fn()
-      await recordStep({ kind, label, status: 'ok', durationMs: Date.now() - t0 })
+      await recordStep({
+        kind,
+        label,
+        status: 'ok',
+        durationMs: Date.now() - t0,
+        // Omitted, not `{}`: an absent field leaves the service's own default in
+        // place rather than writing an empty object the panel would have to
+        // treat as detail.
+        detail: summarize(detailOf, out),
+      })
       return out
     } catch (err) {
       await recordStep({
@@ -342,7 +523,11 @@ export function buildContext(deps: Deps): AutomationContext {
           { stepId, stepName: name, submitted: new Set<string>() },
           fn,
         )
-        await completeStep(stepId, { status: 'ok', durationMs: Date.now() - t0 })
+        await completeStep(stepId, {
+          status: 'ok',
+          durationMs: Date.now() - t0,
+          detail: stepResultDetail(out),
+        })
         return out
       } catch (err) {
         await completeStep(stepId, {
@@ -390,19 +575,65 @@ export function buildContext(deps: Deps): AutomationContext {
 
     agent(slug: string) {
       return {
-        run: (prompt: string) =>
+        run: (prompt: string, options?: { files?: Array<{ fileId: string }> }) =>
           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 }),
+              body: JSON.stringify({
+                slug,
+                prompt,
+                ...(options?.files?.length ? { files: options.files.map((f) => ({ fileId: f.fileId })) } : {}),
+              }),
             })
             if (!res.ok) throw new Error(`agent ${slug} → ${res.status} ${await refusal(res)}`)
             return ((await res.json()) as { data: { text: string } }).data
-          }) as Promise<{ text: string }>,
+          },
+          // 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 }>,
       }
     },
 
+    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.
+        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 {
+          data: { file: { fileId: string; signedUrl: string; mimeType: string; sizeBytes: number; name: string | null } | null }
+        }).data.file
+      },
+      // 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.
+      (out) =>
+        out
+          ? { fileId: out.fileId, mimeType: out.mimeType, sizeBytes: out.sizeBytes, name: out.name }
+          : { resolved: false },
+    ) as Promise<import('./types').ResolvedFileHandle | null>,
+
     plugin(install: string) {
       return {
         call: <T = unknown>(capability: string, input?: Record<string, unknown>) =>
@@ -422,7 +653,19 @@ export function buildContext(deps: Deps): AutomationContext {
             }
             // Two levels: the service envelope's data, then PluginCallResult's own data.
             return ((await res.json()) as { data: PluginCallResult<T> }).data
-          }) as Promise<PluginCallResult<T>>,
+          },
+          (out) => {
+            const chars = jsonSize(out?.data)
+            return {
+              install,
+              capability,
+              ...(chars === null ? {} : { resultChars: chars }),
+              // The plugin's own shape, while it is small enough to read at a
+              // glance. The size above stands for it when it is not.
+              ...ifSmall('data', out?.data, 2_000),
+            }
+          },
+        ) as Promise<PluginCallResult<T>>,
       }
     },
 
@@ -446,7 +689,15 @@ export function buildContext(deps: Deps): AutomationContext {
           })
           if (!res.ok) throw new Error(`ctx.http → ${res.status} ${await refusal(res)}`)
           return ((await res.json()) as { data: HttpResponse }).data
-        }) as Promise<HttpResponse>,
+        },
+        // The upstream status, which is the fact this call is read for — an API
+        // answering 404 is data here, not a throw, so the row is the only place
+        // that outcome appears at all. Not the body: it is capped at 1 MB and
+        // may carry whatever the host sent back.
+        (out) => ({
+          ...(out ? { status: out.status, bodyChars: out.body?.length ?? 0 } : {}),
+        }),
+      ) as Promise<HttpResponse>,
     },
 
     action: {
@@ -538,7 +789,16 @@ export function buildContext(deps: Deps): AutomationContext {
             scope.submitted.delete(submissionIdentity)
             throw err
           }
-        }) as Promise<ActionSubmitResult>,
+        },
+        // `lifecycle` is the half of the answer a reader most often wants: a
+        // submission that stopped at `awaiting_approval` is a normal return, so
+        // the row's green status does not say whether anything happened yet.
+        (out) => ({
+          action: request.action,
+          ...(request.submissionKey ? { submissionKey: request.submissionKey } : {}),
+          ...(out ? { requestId: out.requestId, lifecycle: out.lifecycle } : {}),
+        }),
+      ) as Promise<ActionSubmitResult>,
     },
 
     blueprint: {
@@ -558,7 +818,19 @@ export function buildContext(deps: Deps): AutomationContext {
           // untyped. The cast is the honest boundary: nothing here can verify
           // it, and pretending otherwise would just move the lie deeper.
           return ((await res.json()) as { data: BlueprintQueryResult<T> }).data
-        }) as Promise<BlueprintQueryResult<T>>,
+        },
+        // Count AND filter, because the two questions a reader brings to a
+        // query step are "how many did it match" and "what did it ask for" —
+        // and `hasMore` is how they tell an empty result from a truncated one.
+        (out) => ({
+          objectType,
+          ...(out ? { rowCount: out.rows?.length ?? 0, hasMore: out.hasMore ?? false } : {}),
+          ...(options?.limit === undefined ? {} : { limit: options.limit }),
+          ...ifSmall('where', options?.where, 1_000),
+          ...ifSmall('select', options?.select, 500),
+          ...ifSmall('orderBy', options?.orderBy, 500),
+        }),
+      ) as Promise<BlueprintQueryResult<T>>,
     },
   }
 }

package/src/testing.ts

@@ -47,7 +47,7 @@ import type {
  * for a refusal, and on `calls` for what ran.
  */
 export interface TestCall {
-  kind: 'step' | 'log' | 'agent' | 'plugin' | 'http' | 'blueprint' | 'action'
+  kind: 'step' | 'log' | 'agent' | 'plugin' | 'http' | 'blueprint' | 'action' | 'file'
   /** Step name, log message, agent slug, `install:capability`, URL, object type, or Action apiName. */
   label: string
   /** Present on a step: how it ended. */
@@ -74,6 +74,9 @@ export interface TestContextOptions {
   grants?: readonly Grant[]
   /** Per-slug agent answers. An unstubbed agent throws rather than answering. */
   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 }>
   /**
    * Per-install, per-capability plugin answers: `{ crm: { create_ticket: (input) => ({ data }) } }`.
    * An unstubbed capability throws rather than answering — a fabricated
@@ -177,6 +180,20 @@ export function createTestContext(options: TestContextOptions = {}): TestContext
       calls.push({ kind: 'log', label: message })
     },
 
+    async file(ref: { fileId: string }) {
+      calls.push({ kind: 'file', label: ref.fileId })
+      const stub = options.files?.[ref.fileId]
+      // Throwing beats a fabricated handle: a test that reads a file it never
+      // 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.",
+        )
+      }
+      return { fileId: ref.fileId, ...stub }
+    },
+
     agent(slug: string) {
       return {
         async run(prompt: string) {

package/src/types.ts

@@ -76,14 +76,21 @@ 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'
+  type: 'string' | 'number' | 'boolean' | 'object' | 'array' | 'file'
   /** 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. */
+  /** 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. */
   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']`.
+   *  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. */
+  maxBytes?: number
   /**
    * Mask this field's VALUE wherever a person reads the run.
    *
@@ -125,6 +132,26 @@ export interface InputFieldSpec {
   redact?: boolean
 }
 
+
+/**
+ * The value of a `file`-typed input.
+ *
+ * A REFERENCE to an already-uploaded file, never its bytes: `fileId` is the
+ * canonical handle from the platform's unified file registry (see
+ * docs/superpowers/plans/2026-08-27-unified-file-layer.md). Bytes live in
+ * storage; only this small id rides on the run row, so the 64KB input cap is
+ * untouched.
+ *
+ * One reference, two entry points: the run-form uploader gets a `fileId` for a
+ * file a person drops in, and an agent passes the `fileId` of a chat attachment
+ * it is already holding — both resolve identically downstream. The client never
+ * supplies a trusted path or URL; the SERVER authorizes the `fileId` against the
+ * caller's workspace (`resolveFile`) and resolves it to bytes/URL when read.
+ */
+export interface FileRef {
+  fileId: string
+}
+
 export type InputsSchema = Record<string, InputFieldSpec>
 
 export interface AutomationManifest {
@@ -183,7 +210,26 @@ export interface ResolvedAutomationManifest extends AutomationManifest {
 }
 
 export interface AgentHandle {
-  run(prompt: string): Promise<{ text: string }>
+  /**
+   * One headless agent turn. `options.files` hands the agent already-uploaded
+   * files by canonical id — the same `{ fileId }` a `file`-typed run input
+   * carries, so an input forwards directly: `run(p, { files: [ctx.input.doc] })`.
+   * Each id is authorized against this run's workspace and the bytes are staged
+   * onto the agent's computer; the agent is told the staged paths.
+   */
+  run(prompt: string, options?: { files?: readonly FileRef[] }): Promise<{ text: string }>
+}
+
+/**
+ * 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.
+ */
+export interface ResolvedFileHandle {
+  fileId: string
+  signedUrl: string
+  mimeType: string
+  sizeBytes: number
+  name: string | null
 }
 
 /** What `ctx.plugin(install).call(...)` resolves to. */
@@ -236,7 +282,10 @@ export interface StepApi {
    *    run naming the collision rather than returning the wrong value.
    * 2. **The result must be JSON-serializable.** It is stored and replayed, so a
    *    `Date` comes back as a string and a class instance comes back as a plain
-   *    object. Return data, not objects with behaviour.
+   *    object. Return data, not objects with behaviour. It is also recorded on
+   *    the step's row — capped, and replaced by its size when it is too large —
+   *    so the run trace can show what the step produced. Never return a secret
+   *    from a step: details are rendered verbatim in the Console.
    * 3. **Code outside a step re-executes.** After each step the handler restarts
    *    from the top with completed steps returning their stored results. A
    *    `ctx.http` call sitting outside a step therefore fires once per step, and
@@ -378,6 +427,12 @@ export interface AutomationContext {
   /** Never rejects — telemetry must not be able to fail a run. */
   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.
+   */
+  file(ref: FileRef): Promise<ResolvedFileHandle | null>
   /** One Plugin install, by the name `frontera plugin list` shows. Needs `plugin:<install>:<capability>` per call. */
   plugin(install: string): PluginHandle
   http: {