@frontera-sdk/automation 1.45.13 → 1.45.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontera-sdk/automation",
-  "version": "1.45.13",
+  "version": "1.45.14",
   "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.13",
+    "@frontera-sdk/blueprint": "1.45.14",
     "cron-parser": "^5.0.6"
   }
 }

package/src/index.ts

@@ -11,6 +11,17 @@ export {
 } from './messages'
 export { createTestContext } from './testing'
 export type { TestCall, TestContext, TestContextOptions } from './testing'
-export { MAX_INPUT_BYTES, sanitizeInputsSchema, validateInputValue } from './inputs'
+export {
+  MAX_INPUT_BYTES,
+  redactedInputKeys,
+  sanitizeInputsSchema,
+  validateInputValue,
+} from './inputs'
 export type { InputValidation } from './inputs'
+export {
+  EVENT_TRIGGER_SOURCES,
+  TICKETED_TRIGGER_SOURCES,
+  isEventTriggerSource,
+  isTicketedTriggerSource,
+} from './types'
 export type * from './types'

package/src/inputs.ts

@@ -42,7 +42,14 @@ const INPUT_TYPES = new Set<InputFieldSpec['type']>(['string', 'number', 'boolea
  *  Anything else there is a warning, same philosophy as `manifest.ts`'s
  *  top-level unknown-key warning: a typo like `requred` should be visible,
  *  but a field a newer SDK added must not fail an older validator's deploy. */
-const INPUT_SPEC_KEYS = new Set(['type', 'required', 'default', 'description', 'enum'])
+const INPUT_SPEC_KEYS = new Set([
+  'type',
+  'required',
+  'default',
+  'description',
+  'enum',
+  'redact',
+])
 
 /**
  * Serialized cap on a run's input object — the same 64KB the service enforces
@@ -105,6 +112,7 @@ export function checkInputFieldSpec(key: string, raw: unknown): InputFieldCheck
     default?: unknown
     enum?: unknown
     description?: unknown
+    redact?: unknown
   }
 
   if (spec.description !== undefined && typeof spec.description !== 'string') {
@@ -129,6 +137,29 @@ export function checkInputFieldSpec(key: string, raw: unknown): InputFieldCheck
     errors.push(`input "${key}": required and default are mutually exclusive — a default always satisfies required`)
   }
 
+  // Same `=== true` predicate as `required`, for the same reason: the runtime
+  // treats only a literal `true` as active, so a truthy check here would let
+  // `redact: 1` deploy clean and then mask nothing.
+  if (spec.redact !== undefined && typeof spec.redact !== 'boolean') {
+    errors.push(`input "${key}": redact must be a boolean`)
+  }
+
+  // Both of these publish the value the flag claims to hide, so they are
+  // refused rather than warned about: a manifest that declares them is a
+  // masking guarantee that was never going to hold.
+  if (spec.redact === true && spec.default !== undefined) {
+    errors.push(
+      `input "${key}": redact and default are mutually exclusive — a default is published in the `
+        + 'version manifest, so the value would be readable there',
+    )
+  }
+  if (spec.redact === true && spec.enum !== undefined) {
+    errors.push(
+      `input "${key}": redact and enum are mutually exclusive — an enum publishes every allowed `
+        + 'value in the version manifest',
+    )
+  }
+
   let enumOk = true
   if (spec.enum !== undefined) {
     if (t !== 'string' && t !== 'number') {
@@ -242,3 +273,24 @@ export function sanitizeInputsSchema(inputs: unknown): InputsSchema | undefined
   }
   return inputs as InputsSchema
 }
+
+
+/**
+ * The input names a version declared `redact: true` on.
+ *
+ * One implementation, so the service, the Console and anything else answer
+ * "which fields are masked" the same way — the same argument that keeps
+ * `checkInputFieldSpec` shared between deploy and runtime.
+ *
+ * FAIL CLOSED IS THE CALLER'S JOB, and it matters: `sanitizeInputsSchema`
+ * returns `undefined` for the WHOLE schema when any single field is malformed,
+ * which a caller deriving this list from its result would read as "nothing is
+ * redacted". A caller holding a non-empty raw `inputs` whose sanitized form is
+ * `undefined` must mask everything rather than nothing.
+ */
+export function redactedInputKeys(schema: InputsSchema | undefined): string[] {
+  if (!schema) return []
+  return Object.entries(schema)
+    .filter(([, spec]) => spec?.redact === true)
+    .map(([key]) => key)
+}

package/src/manifest.ts

@@ -300,13 +300,25 @@ export function validateManifest(input: unknown): ValidationResult {
     const agentInputs = m.inputs
     if (agentInputs && typeof agentInputs === 'object' && !Array.isArray(agentInputs)) {
       for (const [key, raw] of Object.entries(agentInputs as Record<string, unknown>)) {
-        const spec = raw as { description?: unknown } | null
+        const spec = raw as { description?: unknown; redact?: unknown } | null
         if (typeof spec?.description !== 'string' || spec.description.trim().length === 0) {
           errors.push(
             `input "${key}" needs a description: trigger { agent: true } publishes every input as `
               + 'a tool argument, and an agent cannot fill an argument it has no description for.',
           )
         }
+        // An error, not a warning, and refused here where the author still has
+        // the file open. On the agent path the MODEL produces this value as
+        // tool-call arguments: it is in the conversation and in that
+        // conversation's trace before a run row exists to mask. Masking the run
+        // row would advertise a guarantee this path cannot keep.
+        if (spec?.redact === true) {
+          errors.push(
+            `input "${key}": redact cannot be used with trigger { agent: true } — the agent `
+              + 'supplies this value as a tool argument, so it is already in the conversation and '
+              + 'its trace before the run exists.',
+          )
+        }
       }
     }
   }

package/src/types.ts

@@ -84,6 +84,45 @@ export interface InputFieldSpec {
   description?: string
   /** Allowed values — string and number types only. */
   enum?: readonly (string | number)[]
+  /**
+   * Mask this field's VALUE wherever a person reads the run.
+   *
+   * What it changes: the run list, the run page and `frontera automation runs`
+   * show a placeholder instead of the value. What it does NOT change: the
+   * handler, every resumption and every retried attempt receive the real value,
+   * because the run row still holds it — this is a display control, not
+   * storage encryption and not an access control.
+   *
+   * What it CANNOT cover, stated here so the flag never reads as a promise it
+   * does not keep:
+   *
+   *  - `ctx.log('…', { key: ctx.input.token })` — an author writing a value
+   *    into a step detail publishes it, and nothing here can intercept that.
+   *  - a redacted value the author TRANSFORMS before using it. The agent
+   *    transcript on the run page is masked by exact occurrence, so a value
+   *    interpolated into a prompt — or quoted back in the reply — is replaced.
+   *    A value upper-cased, truncated or reformatted first no longer matches
+   *    and is not found. Exact match is what can be done without guessing at
+   *    substrings; the alternative, withholding transcripts entirely for any
+   *    run with a redacted input, would take the review surface away from
+   *    exactly the runs that most need reviewing.
+   *  - `default` and `enum`, which are published in the version manifest and in
+   *    any tool schema built from it. Declaring either alongside `redact` is
+   *    refused at deploy for exactly that reason.
+   *  - the run's own `result` and error message. A handler that returns the
+   *    value — `return { note: ctx.input.customer_note }` — or throws an error
+   *    quoting it publishes it on the same run page, unmasked, next to the
+   *    masked input it came from. Only the INPUT is masked; what the handler
+   *    chooses to emit is the handler's decision.
+   *  - anything already recorded. Versions are append-only and the mask is
+   *    frozen onto each run when it starts, so adding `redact` masks future
+   *    runs and never rewrites history.
+   *
+   * A credential still belongs in a `secret:` grant, whose value never enters
+   * this process at all. `redact` is for the ordinary personal or commercial
+   * detail a run legitimately takes and a bystander has no reason to read.
+   */
+  redact?: boolean
 }
 
 export type InputsSchema = Record<string, InputFieldSpec>
@@ -461,3 +500,46 @@ export interface AutomationDescriptor {
   readonly manifest: ResolvedAutomationManifest
   readonly handler: AutomationHandler
 }
+
+/**
+ * How a run came to exist, named once so the two sides of the invoke event
+ * cannot drift.
+ *
+ * This is not decoration. The service publishes `source` on the invoke event,
+ * the RUNNER resolves it back and posts it to the open-run call, and the
+ * service then refuses an invocation ticket arriving under a source that does
+ * not expect one. So a source the service knows and the runner does not is not
+ * a mis-filed run — it is no run at all: the ticket rides along, the open-run
+ * call 400s, and the caller waits forever on a request that never became
+ * anything. That is precisely how the App lane shipped broken.
+ *
+ * Both packages depend on this one, so the list lives here rather than being
+ * spelled out in each. Adding a source means adding it here, and the two
+ * consumers pick it up by construction.
+ *
+ * `cron` is deliberately absent: it is what the runner INFERS when the event
+ * names no source at all, so it is never carried on an event.
+ */
+export const EVENT_TRIGGER_SOURCES = ['manual', 'rehearsal', 'agent', 'app'] as const
+export type EventTriggerSource = (typeof EVENT_TRIGGER_SOURCES)[number]
+
+/**
+ * The sources whose runs MUST arrive with an invocation ticket.
+ *
+ * A run under one of these has a caller whose identity exists only on the
+ * ticket, so a missing one is refused rather than opened unattributed. A ticket
+ * under any other source is refused too — it means the event was tampered with
+ * or two payloads got mixed.
+ */
+export const TICKETED_TRIGGER_SOURCES = ['agent', 'app'] as const
+export type TicketedTriggerSource = (typeof TICKETED_TRIGGER_SOURCES)[number]
+
+export function isEventTriggerSource(value: unknown): value is EventTriggerSource {
+  return typeof value === 'string'
+    && (EVENT_TRIGGER_SOURCES as readonly string[]).includes(value)
+}
+
+export function isTicketedTriggerSource(value: unknown): value is TicketedTriggerSource {
+  return typeof value === 'string'
+    && (TICKETED_TRIGGER_SOURCES as readonly string[]).includes(value)
+}