@frontera-sdk/automation 1.45.8 → 1.45.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontera-sdk/automation",
-  "version": "1.45.8",
+  "version": "1.45.10",
   "description": "Author Frontera automations: manifest, triggers and the typed handler contract.",
   "keywords": [
     "frontera",
@@ -27,6 +27,10 @@
     "./runtime": {
       "types": "./src/runtime-context.ts",
       "import": "./src/runtime-context.ts"
+    },
+    "./inputs": {
+      "types": "./src/inputs.ts",
+      "import": "./src/inputs.ts"
     }
   },
   "scripts": {
@@ -38,7 +42,7 @@
     "typescript": "^5.9.3"
   },
   "dependencies": {
-    "@frontera-sdk/blueprint": "1.45.7",
+    "@frontera-sdk/blueprint": "1.45.9",
     "cron-parser": "^5.0.6"
   }
 }

package/src/define.ts

@@ -3,6 +3,7 @@ import type {
   AutomationHandler,
   AutomationManifest,
   AutomationTrigger,
+  InputsSchema,
 } from './types'
 
 export function automation(
@@ -18,11 +19,24 @@ export function automation(
   // runner registers.
   const trigger: AutomationTrigger = { ...manifest.trigger }
 
+  let inputs: Readonly<InputsSchema> | undefined
+  if (manifest.inputs) {
+    try {
+      inputs = Object.freeze(structuredClone(manifest.inputs))
+    } catch {
+      // `structuredClone` throws a raw `DataCloneError` DOMException on a
+      // function/symbol/etc default, which names neither the automation nor
+      // the field — useless in a deploy log. Rethrow with both.
+      throw new Error(`Automation "${manifest.name}": input defaults must be JSON-serializable values`)
+    }
+  }
+
   return Object.freeze({
     manifest: Object.freeze({
       ...manifest,
       trigger: Object.freeze(trigger),
       grants: Object.freeze([...(manifest.grants ?? [])]),
+      ...(inputs ? { inputs } : {}),
       concurrency: manifest.concurrency ?? 1,
       retries: manifest.retries ?? 0,
     }),

package/src/index.ts

@@ -11,4 +11,6 @@ export {
 } from './messages'
 export { createTestContext } from './testing'
 export type { TestCall, TestContext, TestContextOptions } from './testing'
+export { MAX_INPUT_BYTES, sanitizeInputsSchema, validateInputValue } from './inputs'
+export type { InputValidation } from './inputs'
 export type * from './types'

package/src/inputs.ts

@@ -0,0 +1,244 @@
+/**
+ * Run-input validation — the value-side twin of `validateManifest`.
+ *
+ * Three callers must agree on the verdict and the wording: the run route
+ * (fast 400 before anything queues), `startRun` (authoritative — the runner
+ * posts whatever rode the event), and the Console form (client courtesy).
+ * Living in the SDK is what keeps them one implementation.
+ */
+import type { InputFieldSpec, InputsSchema } from './types'
+
+export type InputValidation =
+  | { ok: true; value: Record<string, unknown> }
+  | { ok: false; errors: string[] }
+
+/**
+ * The five 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
+ * of re-deriving it, so a tightening here (the `Number.isFinite` guard that excludes
+ * `Infinity`/`NaN` from `number`) or a future widening can never drift between
+ * 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.
+ */
+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,
+}
+
+/** Lowercase kebab, matching `validateManifest`'s automation-`name` grammar. */
+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'])
+
+/** Keys `checkInputFieldSpec` understands on ONE input spec (`inputs.<name>`).
+ *  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'])
+
+/**
+ * Serialized cap on a run's input object — the same 64KB the service enforces
+ * when a run starts. Exported so `validateManifest` can refuse a manifest
+ * whose *defaults alone* exceed it at deploy time: past that point a cron
+ * fire would fail inside run-open with no run row, which is invisible.
+ */
+export const MAX_INPUT_BYTES = 64 * 1024
+
+/** Input names that smell like credentials — warned at deploy, never blocked.
+ *  Tails are anchored so `max_tokens` (a count) and `secretary` stay quiet
+ *  while `api_key`, `auth-token`, `client_secret`, `secret_key` still warn. */
+const CREDENTIAL_NAME_RE = /([_-]token$|[_-]key$|password|(^|[_-])secret([_-]|$))/i
+
+export interface InputFieldCheck {
+  errors: string[]
+  warnings: string[]
+}
+
+/**
+ * Structural rules for ONE `{ name: spec }` entry in an inputs schema — name
+ * shape, declared type, required/default shape, enum.
+ *
+ * The shared source for both `validateManifest` (deploy-time; also surfaces
+ * the non-fatal warnings) and `sanitizeInputsSchema` (runtime; pass/fail
+ * only) so the two can never quietly diverge on what "a well-formed input
+ * field" means — which is exactly how `manifest.ts`'s default-type check once
+ * drifted from `TYPE_CHECK` and admitted `default: Infinity`.
+ */
+export function checkInputFieldSpec(key: string, raw: unknown): InputFieldCheck {
+  const errors: string[] = []
+  const warnings: string[] = []
+
+  if (!INPUT_NAME_KEBAB_RE.test(key) && !INPUT_NAME_SNAKE_RE.test(key)) {
+    errors.push(`input "${key}" — names are lowercase snake or kebab`)
+    return { errors, warnings }
+  }
+
+  // Inputs land on the run row and in traces permanently; there is no way to
+  // detect a secret in a value, but a name that says "credential" is an honest
+  // mistake we can flag while the author is still looking at the file.
+  if (CREDENTIAL_NAME_RE.test(key)) {
+    warnings.push(
+      `input "${key}" looks like a credential — inputs are stored on the run row `
+        + 'and visible in traces. Use a `secret:` grant instead.',
+    )
+  }
+
+  if (raw && typeof raw === 'object' && !Array.isArray(raw)) {
+    for (const specKey of Object.keys(raw as Record<string, unknown>)) {
+      if (!INPUT_SPEC_KEYS.has(specKey)) {
+        warnings.push(`unknown key "${specKey}" on input "${key}" — ignored`)
+      }
+    }
+  }
+
+  const spec = (raw ?? {}) as {
+    type?: unknown
+    required?: unknown
+    default?: unknown
+    enum?: unknown
+    description?: unknown
+  }
+
+  if (spec.description !== undefined && typeof spec.description !== 'string') {
+    warnings.push(`input "${key}": description is not a string — ignored`)
+  }
+
+  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`)
+    return { errors, warnings }
+  }
+  const t = spec.type as InputFieldSpec['type']
+
+  // Deploy-side and runtime must share this exact predicate (`=== true`), not
+  // a truthy check — `inputs.ts`'s own `validateInputValue` only treats
+  // `required` as active when it is literally `true`. Without this, a plain
+  // `required: 1` would deploy clean and then never actually be enforced.
+  if (spec.required !== undefined && typeof spec.required !== 'boolean') {
+    errors.push(`input "${key}": required must be a boolean`)
+  }
+
+  if (spec.required === true && spec.default !== undefined) {
+    errors.push(`input "${key}": required and default are mutually exclusive — a default always satisfies required`)
+  }
+
+  let enumOk = true
+  if (spec.enum !== undefined) {
+    if (t !== 'string' && t !== 'number') {
+      errors.push(`input "${key}": enum is only valid for string and number types`)
+      enumOk = false
+    } else if (!Array.isArray(spec.enum) || spec.enum.length === 0) {
+      errors.push(`input "${key}": enum must not be empty`)
+      enumOk = false
+    } else if (spec.enum.some((e) => typeof e !== t)) {
+      errors.push(`input "${key}": enum values must match the declared type`)
+      enumOk = false
+    } else if (t === 'number' && spec.enum.some((e) => !Number.isFinite(e as number))) {
+      // TYPE_CHECK's own `number` check already excludes NaN/Infinity from
+      // values — a member of `enum` that no value could ever equal is
+      // unreachable and can only be an authoring mistake.
+      errors.push(`input "${key}": enum values must be finite numbers`)
+      enumOk = false
+    }
+  }
+
+  let defaultOk = true
+  if (spec.default !== undefined) {
+    if (!TYPE_CHECK[t](spec.default)) {
+      errors.push(`input "${key}": default must match the declared type`)
+      defaultOk = false
+    }
+  }
+
+  if (spec.enum !== undefined && spec.default !== undefined && enumOk && defaultOk) {
+    if (!(spec.enum as unknown[]).includes(spec.default)) {
+      errors.push(`input "${key}": default must be one of the enum values`)
+    }
+  }
+
+  return { errors, warnings }
+}
+
+export function validateInputValue(
+  schema: InputsSchema | undefined,
+  value: Record<string, unknown> | undefined | null,
+): InputValidation {
+  const given = value ?? {}
+  if (!schema || Object.keys(schema).length === 0) {
+    return Object.keys(given).length === 0
+      ? { ok: true, value: {} }
+      : { ok: false, errors: ['this automation declares no inputs — remove the input and run again'] }
+  }
+  const errors: string[] = []
+  const out: Record<string, unknown> = {}
+  for (const key of Object.keys(given)) {
+    // `Object.hasOwn`, not `key in schema`: the `in` operator also sees
+    // inherited members — every plain object "has" `toString` via
+    // `Object.prototype` — so a value keyed `toString` would slip past an
+    // undeclared-field check that used `in`.
+    if (!Object.hasOwn(schema, key)) errors.push(`"${key}" is not a declared input`)
+  }
+  for (const [key, spec] of Object.entries(schema)) {
+    // Same reasoning in reverse: plain `given[key]` for key `constructor`
+    // resolves to `Object.prototype.constructor` (a function) rather than
+    // `undefined` when the caller never supplied one, which would run type
+    // checks against Object's own constructor instead of treating the field
+    // as absent.
+    const v = Object.hasOwn(given, key) ? given[key] : undefined
+    if (v === undefined) {
+      if (spec.default !== undefined) out[key] = structuredClone(spec.default)
+      // `=== true`, not truthy: a legacy/malformed `required: 1` must not be
+      // silently enforced here when `validateManifest` already refuses it as
+      // "not a boolean" — the two sides share one predicate on purpose.
+      else if (spec.required === true) errors.push(`"${key}" is required`)
+      continue
+    }
+    // `Object.hasOwn`, not a plain lookup: `TYPE_CHECK` is an object literal,
+    // so `TYPE_CHECK['toString']` resolves to `Object.prototype.toString` —
+    // truthy, and callable — rather than `undefined`. A spec of `{ type:
+    // 'toString' }` would then pass `check(v)` for ANY `v` instead of being
+    // refused as the unknown type it is.
+    const check = Object.hasOwn(TYPE_CHECK, spec.type) ? TYPE_CHECK[spec.type as InputFieldSpec['type']] : undefined
+    if (!check) {
+      // A stored manifest can predate this SDK version and carry a `type`
+      // this build has never heard of (pre-input-validation, `inputs` was an
+      // unknown key with no shape checking at all). Fail the field, don't
+      // crash the run route.
+      errors.push(`"${key}" has an unknown declared type "${String(spec.type)}"`)
+      continue
+    }
+    if (!check(v)) {
+      errors.push(`"${key}" must be of type ${spec.type}`)
+      continue
+    }
+    if (spec.enum && !spec.enum.includes(v as string | number)) {
+      errors.push(`"${key}" must be one of ${spec.enum.join(', ')}`)
+      continue
+    }
+    out[key] = v
+  }
+  return errors.length > 0 ? { ok: false, errors } : { ok: true, value: out }
+}
+
+/**
+ * A stored manifest's `inputs` key, admitted only when structurally valid.
+ *
+ * Versions deployed before inputs existed could carry ANY value under this
+ * key (it was warn-and-store), and `startRun` must not let a stray legacy
+ * blob retroactively break a working schedule — an invalid schema is treated
+ * as "declares no inputs", never as a refusal.
+ */
+export function sanitizeInputsSchema(inputs: unknown): InputsSchema | undefined {
+  if (!inputs || typeof inputs !== 'object' || Array.isArray(inputs)) return undefined
+  for (const [key, raw] of Object.entries(inputs as Record<string, unknown>)) {
+    if (checkInputFieldSpec(key, raw).errors.length > 0) return undefined
+  }
+  return inputs as InputsSchema
+}

package/src/manifest.ts

@@ -1,4 +1,5 @@
 import { CronExpressionParser } from 'cron-parser'
+import { MAX_INPUT_BYTES, checkInputFieldSpec } from './inputs'
 
 const SEGMENT = '[a-z][a-z0-9]*(?:-[a-z0-9]+)*'
 const NAME_RE = new RegExp(`^${SEGMENT}$`)
@@ -41,6 +42,18 @@ const SECRET_NAME_RE = /^[A-Z][A-Z0-9_]*$/
 // deploy.
 const ACTION_API_NAME_RE = /^[a-z][A-Za-z0-9]{0,99}$/
 
+// `plugin:<install>:<capability>`. The service does NOT validate
+// `app_installs.install_name` — it is `t.String({ minLength: 1 })`, so an
+// admin can name an install "My CRM" and it works fine everywhere except
+// here. This grammar (lowercase, dot/dash/underscore, no spaces — the catalog
+// default is kebab) is what makes an install's name usable from a manifest;
+// one outside it has to be renamed before an automation can grant it. The
+// capability half is deliberately wider: MCP tool names and spec capability
+// names are `create_issue` / `listIssues`, neither of which is a SEGMENT. No
+// wildcard in either half — the manifest is the reviewable list of what the
+// automation can reach, same as `http:`.
+const PLUGIN_GRANT_RE = /^[a-z0-9][a-z0-9._-]{0,63}:[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/
+
 /** Namespaces whose value is not a SEGMENT. */
 const TYPED_NAMESPACES: Record<string, { re: RegExp; hint: string }> = {
   http: { re: HOST_RE, hint: 'a hostname, e.g. "http:api.stripe.com" (no scheme, no path, no wildcard)' },
@@ -49,10 +62,17 @@ const TYPED_NAMESPACES: Record<string, { re: RegExp; hint: string }> = {
     re: ACTION_API_NAME_RE,
     hint: 'one published Action apiName, e.g. "governed:approveInvoice" (camelCase, no wildcard)',
   },
+  plugin: {
+    re: PLUGIN_GRANT_RE,
+    hint:
+      '<install>:<capability>, e.g. "plugin:crm:create_ticket" — the install name from '
+      + '`frontera plugin list` (lowercase, no spaces) and one capability name (no wildcard)'
+      + ' — rename the install if its name has capitals or spaces',
+  },
 }
 
 const KNOWN_KEYS = new Set([
-  'name', 'trigger', 'grants', 'concurrency', 'retries', 'description',
+  'name', 'trigger', 'grants', 'inputs', 'concurrency', 'retries', 'description',
 ])
 
 export interface ValidationResult {
@@ -88,6 +108,7 @@ export function validateManifest(input: unknown): ValidationResult {
     name?: unknown
     trigger?: unknown
     grants?: unknown
+    inputs?: unknown
     concurrency?: unknown
     retries?: unknown
   }
@@ -176,6 +197,61 @@ export function validateManifest(input: unknown): ValidationResult {
     errors.push('retries must be an integer between 0 and 5')
   }
 
+  const inputs = m.inputs
+  if (inputs !== undefined) {
+    if (!inputs || typeof inputs !== 'object' || Array.isArray(inputs)) {
+      errors.push('inputs must be an object of { name: { type, … } }')
+    } else {
+      // Per-field rules (name shape, type, required/default shape, enum) live
+      // in `checkInputFieldSpec` — shared with `sanitizeInputsSchema` so the
+      // two can never drift on what "a well-formed input field" means.
+      for (const [key, raw] of Object.entries(inputs as Record<string, unknown>)) {
+        const field = checkInputFieldSpec(key, raw)
+        errors.push(...field.errors)
+        warnings.push(...field.warnings)
+      }
+      // A cron fire has no one to prompt: every required field must be
+      // satisfiable from defaults, or the schedule would fail on every tick.
+      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 }
+          if (spec?.required === true && spec.default === undefined) {
+            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.',
+            )
+          }
+        }
+      }
+      // A run's input is capped at MAX_INPUT_BYTES when it starts. If the
+      // declared defaults alone already exceed that, a cron fire (or a bare
+      // Run-now) fails inside run-open before any run row exists — a silent
+      // death only visible in runner logs. Catch it here, the one place the
+      // author is still looking at the file.
+      const defaultsOnly: Record<string, unknown> = {}
+      for (const [key, raw] of Object.entries(inputs as Record<string, unknown>)) {
+        const spec = raw as { default?: unknown }
+        if (spec && typeof spec === 'object' && spec.default !== undefined) {
+          defaultsOnly[key] = spec.default
+        }
+      }
+      try {
+        const bytes = new TextEncoder().encode(JSON.stringify(defaultsOnly)).length
+        if (bytes > MAX_INPUT_BYTES) {
+          errors.push(
+            `input defaults alone serialize to ${bytes} bytes — over the ${MAX_INPUT_BYTES}-byte `
+              + 'run-input cap, so every run would fail at start. Slim the defaults.',
+          )
+        }
+      } catch {
+        // A default that JSON.stringify chokes on (circular, throwing toJSON)
+        // is practically unreachable — the manifest itself must serialize to
+        // deploy at all — but the size check must never be the thing that throws.
+      }
+    }
+  }
+
   if (input && typeof input === 'object' && !Array.isArray(input)) {
     for (const key of Object.keys(input)) {
       if (!KNOWN_KEYS.has(key)) {

package/src/runtime-context.ts

@@ -33,6 +33,7 @@ import type {
   BlueprintQueryResult,
   HttpRequest,
   HttpResponse,
+  PluginCallResult,
 } from './types'
 
 const SERVICE_URL = process.env.SERVICE_URL ?? 'http://localhost:4000'
@@ -58,6 +59,8 @@ export interface StepTools {
    * reasoning `ctx.blueprint.query` narrows a warehouse row.
    */
   run<T>(id: string, fn: () => Promise<T>): Promise<unknown>
+  /** Absent on hosts that predate it — the runtime falls back to an inline wait. */
+  sleep?(id: string, ms: number): Promise<void>
 }
 
 interface Deps {
@@ -67,6 +70,8 @@ interface Deps {
   grants: string[]
   /** The platform's step tools for THIS execution. */
   step: StepTools
+  /** The run's frozen input row, or absent when the manifest declares none. */
+  input?: Record<string, unknown>
   /** Zero-indexed run attempt, stamped onto every row this context writes. */
   attempt?: number
   /**
@@ -350,11 +355,31 @@ export function buildContext(deps: Deps): AutomationContext {
     })) as T
   }
 
+  /**
+   * Durable pause. No step row is written: a row recorded after a memoized
+   * sleep would be re-recorded by every later execution (the code after an
+   * awaited memoized step re-runs per resumption), and unlike `runStep`
+   * there is no body to write it from exactly once.
+   */
+  const sleepStep = async (name: string, ms: number): Promise<void> => {
+    if (namesThisExecution.has(name)) throw new DuplicateStepNameError(name)
+    namesThisExecution.add(name)
+    if (deps.step.sleep) {
+      await deps.step.sleep(name, ms)
+      return
+    }
+    // Host without a sleep arm (an old dev worker): wait inline. Correct,
+    // just not durable — acceptable for the host that cannot resume anyway.
+    await new Promise((resolve) => setTimeout(resolve, ms))
+  }
+
   return {
     runId: deps.runId,
     workspaceId: deps.workspaceId,
+    // The host passes the run row's frozen copy; the SDK never re-validates — `startRun` is the authority.
+    input: deps.input ?? {},
 
-    step: { run: runStep },
+    step: { run: runStep, sleep: sleepStep },
 
     async log(message, data) {
       // Swallowed on purpose, inside `recordStep`. `ctx.log` is telemetry, and a
@@ -378,6 +403,29 @@ export function buildContext(deps: Deps): AutomationContext {
       }
     },
 
+    plugin(install: string) {
+      return {
+        call: <T = unknown>(capability: string, input?: Record<string, unknown>) =>
+          step('plugin', `plugin:${install}:${capability}`, async () => {
+            // Pre-flighted locally so an author reads the grant by name, in the
+            // same words the service uses. The service checks it again — this
+            // copy exists for the message, not for the authority.
+            requireGrant(`plugin:${install}:${capability}`)
+            const res = await scoped('/ctx/plugin-call', {
+              method: 'POST',
+              body: JSON.stringify({ install, capability, input: input ?? {} }),
+            })
+            if (!res.ok) {
+              throw new Error(
+                `ctx.plugin("${install}").call("${capability}") → ${res.status} ${await refusal(res)}`,
+              )
+            }
+            // 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>>,
+      }
+    },
+
     http: {
       fetch: (req: HttpRequest) =>
         step('http', `${req.method ?? 'GET'} ${req.url}`, async () => {

package/src/testing.ts

@@ -15,6 +15,7 @@ import type {
   Grant,
   HttpRequest,
   HttpResponse,
+  PluginCallResult,
 } from './types'
 
 /**
@@ -46,8 +47,8 @@ import type {
  * for a refusal, and on `calls` for what ran.
  */
 export interface TestCall {
-  kind: 'step' | 'log' | 'agent' | 'http' | 'blueprint' | 'action'
-  /** Step name, log message, agent slug, URL, object type, or Action apiName. */
+  kind: 'step' | 'log' | 'agent' | 'plugin' | 'http' | 'blueprint' | 'action'
+  /** Step name, log message, agent slug, `install:capability`, URL, object type, or Action apiName. */
   label: string
   /** Present on a step: how it ended. */
   status?: 'ok' | 'error'
@@ -57,6 +58,9 @@ export interface TestCall {
 export interface TestContextOptions {
   runId?: string
   workspaceId?: string
+  /** What the run was started with. Passed through verbatim — a unit test
+   *  states exactly what the handler sees; defaults are `startRun`'s job. */
+  input?: Record<string, unknown>
   /**
    * The grants the manifest declares.
    *
@@ -70,6 +74,15 @@ 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-install, per-capability plugin answers: `{ crm: { create_ticket: (input) => ({ data }) } }`.
+   * An unstubbed capability throws rather than answering — a fabricated
+   * `{ data: {} }` is a test that passes while asserting nothing.
+   */
+  plugins?: Record<
+    string,
+    Record<string, (input: Record<string, unknown>) => Promise<PluginCallResult> | PluginCallResult>
+  >
   /** Answers outbound requests. Unstubbed, `ctx.http.fetch` throws. */
   http?: (req: HttpRequest) => Promise<HttpResponse> | HttpResponse
   /** Rows per object type. An unstubbed type returns no rows, which is a real
@@ -130,6 +143,7 @@ export function createTestContext(options: TestContextOptions = {}): TestContext
   const ctx: AutomationContext = {
     runId: options.runId ?? 'test-run',
     workspaceId: options.workspaceId ?? 'test-workspace',
+    input: options.input ?? {},
 
     step: {
       async run<T>(name: string, fn: () => Promise<T>): Promise<T> {
@@ -147,6 +161,15 @@ export function createTestContext(options: TestContextOptions = {}): TestContext
           }
         })
       },
+
+      async sleep(name: string): Promise<void> {
+        if (seenNames.has(name)) throw new Error(duplicateStepMessage(name))
+        seenNames.add(name)
+        steps.push(name)
+        // Recorded, never waited: a test suite that really slept out its
+        // backoffs would take minutes to say nothing.
+        calls.push({ kind: 'step', label: name, status: 'ok' })
+      },
     },
 
     async log(message, data) {
@@ -174,6 +197,31 @@ export function createTestContext(options: TestContextOptions = {}): TestContext
       }
     },
 
+    plugin(install: string) {
+      return {
+        async call<T = unknown>(capability: string, input?: Record<string, unknown>) {
+          requireGrant(`plugin:${install}:${capability}`)
+          const stub = options.plugins?.[install]?.[capability]
+          // Before the record, matching the contract on `TestCall` and the
+          // `action` arm. (`agent` and `http` record first — a pre-existing
+          // divergence.)
+          if (!stub) {
+            throw new Error(
+              `No plugin stub for "${install}".${capability}. Pass ` +
+                // Quoted, unlike a bare identifier: an install name defaults to
+                // the catalog kind (kebab, e.g. "github-prod") and a capability
+                // can be dotted ("run.query") — neither survives as an object
+                // key without quotes, so the unquoted form the author would
+                // paste back in does not parse.
+                `plugins: { '${install}': { '${capability}': () => ({ data: … }) } } to createTestContext.`,
+            )
+          }
+          calls.push({ kind: 'plugin', label: `${install}:${capability}` })
+          return (await stub(input ?? {})) as PluginCallResult<T>
+        },
+      }
+    },
+
     http: {
       async fetch(req: HttpRequest) {
         let host: string

package/src/types.ts

@@ -34,6 +34,16 @@ export type AutomationTrigger =
 export type Grant =
   | 'blueprint:read'
   | `agent:${string}:run`
+  /**
+   * One capability of one Plugin install: `plugin:<install>:<capability>`.
+   *
+   * `<install>` is the install's name as `frontera plugin list` shows it
+   * (lowercase, no spaces); `<capability>` is the capability's name on that
+   * install. One grant per capability — there is no wildcard, for the same
+   * reason `http:` has none: the manifest is the reviewable list of what the
+   * automation can reach.
+   */
+  | `plugin:${string}:${string}`
   /** One EXACT host, no wildcards. `http:api.stripe.com` matches that host and
    *  nothing else — a wildcard would ask a reviewer to reason about
    *  subdomain-takeover risk, and the answer is usually wrong. */
@@ -49,10 +59,32 @@ export type Grant =
    *  answer changes with every release — to know what the automation may do. */
   | `governed:${string}`
 
+/** One declared run input. A deliberate subset of JSON Schema — the same
+ *  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'
+  /** 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. */
+  default?: unknown
+  description?: string
+  /** Allowed values — string and number types only. */
+  enum?: readonly (string | number)[]
+}
+
+export type InputsSchema = Record<string, InputFieldSpec>
+
 export interface AutomationManifest {
   name: string
   trigger: AutomationTrigger
   grants?: readonly Grant[]
+  /**
+   * Declared run inputs, validated and defaulted at run start. Absent means
+   * this automation takes no input — starting a run WITH input for such a
+   * version is refused. See `InputFieldSpec`.
+   */
+  inputs?: InputsSchema
   concurrency?: number
   /**
    * Times the platform may retry a run that FAILED. Default 0, and the opt-in
@@ -92,6 +124,7 @@ export interface ResolvedAutomationManifest extends AutomationManifest {
   readonly name: string
   readonly trigger: Readonly<AutomationTrigger>
   readonly grants: readonly Grant[]
+  readonly inputs?: Readonly<InputsSchema>
   readonly concurrency: number
   readonly retries: number
   readonly description?: string
@@ -101,6 +134,34 @@ export interface AgentHandle {
   run(prompt: string): Promise<{ text: string }>
 }
 
+/** What `ctx.plugin(install).call(...)` resolves to. */
+export interface PluginCallResult<T = unknown> {
+  /** Whatever the capability returned. Shape is the plugin's, not the platform's. */
+  data: T
+}
+
+export interface PluginHandle {
+  /**
+   * Invoke one capability of this install.
+   *
+   * Governed by the install's policy exactly as an agent's tool call is —
+   * a disabled install, a `read_only` Action policy, a parameter constraint
+   * or a missing workspace account all refuse here with the reason named.
+   * A capability that requires approval cannot be called from an automation
+   * at all (nobody to ask), and `deploy` refuses the grant up front.
+   *
+   * A failure reported by the plugin itself is thrown, carrying the plugin's
+   * message. A success resolves to `{ data }` — there is no `ok` flag to
+   * branch on, only the value.
+   *
+   * Dry in a dev run: returns `{ data: null }` and sends nothing.
+   */
+  call<T = unknown>(
+    capability: string,
+    input?: Record<string, unknown>,
+  ): Promise<PluginCallResult<T>>
+}
+
 /**
  * Durable steps.
  *
@@ -131,6 +192,18 @@ export interface StepApi {
    *    that used steps.
    */
   run<T>(name: string, fn: () => Promise<T>): Promise<T>
+
+  /**
+   * Park the run for `ms` milliseconds, durably, under a unique name.
+   *
+   * On the platform this is a real checkpoint: the run stops occupying a
+   * worker and resumes after the delay — pace provider polls with it (a
+   * measured 429 arrived after ~7 back-to-back polls). In `createTestContext`
+   * and in dev runs it records and returns immediately, so tests and dry runs
+   * never actually wait. Shares the name-uniqueness rule with `run`: the
+   * platform memoizes both by name.
+   */
+  sleep(name: string, ms: number): Promise<void>
 }
 
 /**
@@ -242,9 +315,19 @@ export interface ActionSubmitResult {
 export interface AutomationContext {
   runId: string
   workspaceId: string
+  /**
+   * The values this run was started with — validated against the manifest's
+   * `inputs` schema and fixed on the run row at start, so every resumption
+   * and retried attempt sees the same object. `{}` when the manifest declares
+   * no inputs. Visible in the run trace by design: never put a secret here —
+   * `secret:` grants are the credential path.
+   */
+  input: Record<string, unknown>
   /** Never rejects — telemetry must not be able to fail a run. */
   log(message: string, data?: Record<string, unknown>): Promise<void>
   agent(slug: string): AgentHandle
+  /** One Plugin install, by the name `frontera plugin list` shows. Needs `plugin:<install>:<capability>` per call. */
+  plugin(install: string): PluginHandle
   http: {
     /**
      * Call an allowlisted host, optionally with a workspace secret injected