@frontera-sdk/functions 1.49.0

package/src/inputs.ts

@@ -0,0 +1,340 @@
+/**
+ * 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 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.
+ *
+ * `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',
+  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,
+}
+
+/** 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', 'file'])
+
+/** 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',
+  'redact',
+  'accept',
+  'maxBytes',
+])
+
+/**
+ * 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
+    redact?: unknown
+    accept?: unknown
+    maxBytes?: 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, file`)
+    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`)
+  }
+
+  // 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') {
+      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
+    }
+  }
+
+  // `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) {
+    // 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
+    }
+  }
+
+  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
+}
+
+
+/**
+ * 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

@@ -0,0 +1,341 @@
+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}$`)
+
+/**
+ * Runtime gate for a grant: `<namespace>:<name>[:<action>]`, every segment
+ * sharing NAME_RE's grammar so the whole vocabulary is consistent.
+ *
+ * WIDER than the `Grant` union on namespaces — a server must not reject
+ * `notify:email` merely because this build predates it. NARROWER than the
+ * union's `agent:${string}:run` arm on the slug, which admits `agent::run` and
+ * `agent:AGENT:run`; both are rejected here. No legitimate slug is affected —
+ * this repo's agent slugs are already lowercase-kebab.
+ */
+const GRANT_RE = new RegExp(`^${SEGMENT}:${SEGMENT}(?::${SEGMENT})?$`)
+
+/**
+ * `http:<host>` and `secret:<NAME>` need their own grammars, because SEGMENT is
+ * lowercase-kebab and neither value is.
+ *
+ * A host contains DOTS (`api.stripe.com`); a secret name is conventionally
+ * SCREAMING_SNAKE_CASE (`STRIPE_KEY`). Validating them with SEGMENT rejected both
+ * realistic forms — found by deploying an automation that used them.
+ *
+ * Deliberately not solved by widening SEGMENT: that governs agent slugs too, and
+ * loosening it there would admit `agent:AGENT:run`, which the comment above says
+ * is rejected on purpose.
+ */
+const HOST_RE = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)*$/
+// Matches SECRET_NAME_PATTERN in workspace-secrets-router exactly. Being MORE
+// permissive here would let a manifest declare `secret:myKey`, validate cleanly,
+// and then never be satisfiable — no such secret can be created. A validator that
+// accepts the unsatisfiable is worse than one that is strict.
+const SECRET_NAME_RE = /^[A-Z][A-Z0-9_]*$/
+// Matches `apiNameSchema` in the Blueprint Action definition schema exactly.
+// Same reasoning as SECRET_NAME_RE: a looser grammar here would accept
+// `governed:Approve_Invoice`, validate cleanly, and name an Action that can
+// never exist — no published Action carries that apiName, so the grant is
+// unsatisfiable and the automation fails at its first submit instead of at
+// 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)' },
+  secret: { re: SECRET_NAME_RE, hint: 'a workspace secret name, e.g. "secret:STRIPE_KEY"' },
+  governed: {
+    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',
+  },
+}
+
+/**
+ * Shortest description an agent-callable automation may carry.
+ *
+ * Not a round number picked for looks: it is about the length of one honest
+ * clause ("Reconcile open invoices against the settlement file"), and it is
+ * chosen to be long enough that the slug restated as a sentence — "reconcile
+ * invoices" — does not clear it. A description that only repeats the name
+ * tells a model nothing it did not already have from the tool name.
+ */
+export const AGENT_DESCRIPTION_MIN_CHARS = 24
+
+const KNOWN_KEYS = new Set([
+  'name', 'trigger', 'grants', 'inputs', 'concurrency', 'retries', 'description',
+])
+
+export interface ValidationResult {
+  valid: boolean
+  errors: string[]
+  /**
+   * Non-fatal. An unknown manifest key lands here rather than in `errors`:
+   * a newer SDK must be able to add a field without an older service refusing
+   * the deploy. The CLI prints these, so a typo like `concurrancy: 100` — which
+   * would otherwise deploy "successfully" with the default of 1 — is caught at
+   * author time, where the SDK and the manifest are the same version.
+   */
+  warnings: string[]
+}
+
+/**
+ * Takes `unknown`, on purpose.
+ *
+ * The authoritative call site is the service, validating a manifest that
+ * arrived over HTTP — untrusted, and not yet known to have any shape. Typing
+ * the parameter as `AutomationManifest` would force every honest caller to
+ * launder untrusted input through a cast, which is how a validator ends up
+ * trusting the thing it exists to check.
+ *
+ * The regexes here are deliberately wider than the `Grant` union in `types.ts`:
+ * that union is an author-time affordance, this is a runtime gate, and a server
+ * must not reject a grant merely because this build predates it.
+ */
+export function validateManifest(input: unknown): ValidationResult {
+  const errors: string[] = []
+  const warnings: string[] = []
+  const m = (input ?? {}) as {
+    name?: unknown
+    trigger?: unknown
+    grants?: unknown
+    inputs?: unknown
+    concurrency?: unknown
+    retries?: unknown
+    description?: unknown
+  }
+
+  if (typeof m.name !== 'string' || !NAME_RE.test(m.name)) {
+    errors.push('name must be lowercase kebab-case')
+  } else if (m.name.length > 64) {
+    errors.push('name must be 64 characters or fewer')
+  }
+
+  const trigger = m.trigger as
+    | { cron?: string; manual?: boolean; agent?: boolean }
+    | undefined
+  if (
+    !trigger
+    || (trigger.cron === undefined && trigger.manual !== true && trigger.agent !== true)
+  ) {
+    errors.push('trigger must be { cron }, { manual: true }, or { agent: true }')
+  } else if (trigger.agent !== undefined && trigger.agent !== true) {
+    // Not folded into the arm above: `{ manual: true, agent: false }` is a
+    // legal-looking manifest that means nothing. `agent` is a permission, and
+    // the way to withhold a permission is to omit it, not to write it false —
+    // the same rule the grant list follows.
+    errors.push(
+      'trigger.agent must be true when present — omit the key to mean "not agent-callable"',
+    )
+  }
+  // Separate `if`, not the old `else if`: with three arms the cron check has to
+  // run whenever a cron is present, including on `{ cron, agent: true }`, and
+  // an `else if` chained off the acceptance test above would skip it there.
+  if (trigger?.cron !== undefined) {
+    if (typeof trigger.cron !== 'string') {
+      errors.push('invalid cron expression: must be a string')
+    } else {
+      // Both field-count branches exist because `cron-parser` accepts an
+      // off-count expression rather than throwing, so neither case would ever
+      // reach the `catch` below:
+      //   `* * * * * *` -> reads field 1 as SECONDS and fires sub-minute.
+      //   `0 7 * *`     -> left-pads, scheduling something the author never wrote.
+      // Only an exactly-5-field expression means what it looks like it means.
+      const fields = trigger.cron.trim().split(/\s+/).length
+      if (fields !== 5) {
+        // One message shape for one class of fault. Splitting it meant a
+        // 7-field expression was told it was "sub-minute" — a diagnosis
+        // asserted rather than derived — while a 4-field one got no diagnosis
+        // at all.
+        errors.push(
+          `invalid cron expression: expected 5 fields, got ${fields}` +
+            (fields > 5 ? '; sub-minute schedules are not supported' : ''),
+        )
+      } else {
+        try {
+          CronExpressionParser.parse(trigger.cron, { tz: 'UTC' })
+        } catch (err) {
+          errors.push(`invalid cron expression: ${(err as Error).message}`)
+        }
+      }
+    }
+  }
+
+  if (m.grants !== undefined && !Array.isArray(m.grants)) {
+    errors.push('grants must be an array')
+  } else {
+    for (const g of (m.grants as unknown[]) ?? []) {
+      // String(g), not `${g}` — a template literal THROWS on a symbol, and a
+      // validator that exists to absorb hostile input must not have a throwing
+      // path. The message names the fix, not just the verdict.
+      if (typeof g !== 'string') {
+        errors.push(
+          `malformed grant "${String(g)}" — expected "<namespace>:<action>", ` +
+            'e.g. "blueprint:read" or "agent:risk-analyst:run"',
+        )
+        continue
+      }
+      const colon = g.indexOf(':')
+      const typed = colon > 0 ? TYPED_NAMESPACES[g.slice(0, colon)] : undefined
+      if (typed) {
+        // A typed namespace validates its OWN value grammar. `http:` and
+        // `secret:` carry hosts and secret names, neither of which is a SEGMENT.
+        if (!typed.re.test(g.slice(colon + 1))) {
+          errors.push(`malformed grant "${g}" — the part after the colon must be ${typed.hint}`)
+        }
+        continue
+      }
+      if (!GRANT_RE.test(g)) {
+        errors.push(
+          `malformed grant "${String(g)}" — expected "<namespace>:<action>", ` +
+            'e.g. "blueprint:read" or "agent:risk-analyst:run"',
+        )
+      }
+    }
+  }
+
+  const c = m.concurrency
+  if (c !== undefined && (!Number.isInteger(c) || (c as number) < 1 || (c as number) > 50)) {
+    errors.push('concurrency must be an integer between 1 and 50')
+  }
+
+  // Capped at 5. Above that it is not a retry policy, it is a loop — and every
+  // attempt re-runs whatever side effects the previous one already performed.
+  const r = m.retries
+  if (r !== undefined && (!Number.isInteger(r) || (r as number) < 0 || (r as number) > 5)) {
+    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 { 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. ${remedy}`,
+            )
+          }
+        }
+      }
+      // 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.
+      }
+    }
+  }
+
+  // `trigger: { agent: true }` turns this manifest into the source of a tool
+  // definition a language model reads and decides from. Two fields that are
+  // courtesies everywhere else become load-bearing here, so they are errors
+  // rather than warnings: a model handed an undescribed tool, or an undescribed
+  // argument, does not fail loudly — it guesses, and the guess starts a real
+  // run against real systems. Checked at deploy, where the author still has the
+  // file open, rather than at bind time in a Console someone else is using.
+  if (trigger?.agent === true) {
+    const description = m.description
+    if (typeof description !== 'string' || description.trim().length < AGENT_DESCRIPTION_MIN_CHARS) {
+      errors.push(
+        `trigger { agent: true } requires a description of at least ${AGENT_DESCRIPTION_MIN_CHARS} `
+          + 'characters — it becomes the tool description an agent reads before calling this '
+          + 'automation.',
+      )
+    }
+    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; 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.',
+          )
+        }
+      }
+    }
+  }
+
+  if (input && typeof input === 'object' && !Array.isArray(input)) {
+    for (const key of Object.keys(input)) {
+      if (!KNOWN_KEYS.has(key)) {
+        warnings.push(`unknown manifest key "${key}" — ignored`)
+      }
+    }
+  }
+
+  return { valid: errors.length === 0, errors, warnings }
+}