@frontera-sdk/automation 1.45.11 → 1.45.12

package/package.json

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

package/src/manifest.ts

@@ -71,6 +71,17 @@ const TYPED_NAMESPACES: Record<string, { re: RegExp; hint: string }> = {
   },
 }
 
+/**
+ * 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',
 ])
@@ -111,6 +122,7 @@ export function validateManifest(input: unknown): ValidationResult {
     inputs?: unknown
     concurrency?: unknown
     retries?: unknown
+    description?: unknown
   }
 
   if (typeof m.name !== 'string' || !NAME_RE.test(m.name)) {
@@ -119,10 +131,27 @@ export function validateManifest(input: unknown): ValidationResult {
     errors.push('name must be 64 characters or fewer')
   }
 
-  const trigger = m.trigger as { cron?: string; manual?: boolean } | undefined
-  if (!trigger || (trigger.cron === undefined && trigger.manual !== true)) {
-    errors.push('trigger must be { cron } or { manual: true }')
-  } else if (trigger.cron !== undefined) {
+  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 {
@@ -252,6 +281,36 @@ export function validateManifest(input: unknown): ValidationResult {
     }
   }
 
+  // `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 } | 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.',
+          )
+        }
+      }
+    }
+  }
+
   if (input && typeof input === 'object' && !Array.isArray(input)) {
     for (const key of Object.keys(input)) {
       if (!KNOWN_KEYS.has(key)) {

package/src/types.ts

@@ -7,16 +7,29 @@
 import type { WhereNode } from '@frontera-sdk/blueprint/types'
 
 /**
- * Cron and manual only for now; event and webhook land with Event Triggers.
+ * Cron, manual, and agent for now; event and webhook land with Event Triggers.
  *
  * The `?: never` members are load-bearing. Without them `{ cron, manual }`
  * typechecks — TypeScript's excess-property check admits any key present on
  * *some* member of a union — and the runner would have to decide at runtime
  * what a both-shaped trigger means.
+ *
+ * `agent` is deliberately NOT part of that exclusion. Cron and manual answer
+ * "what fires this on its own"; `agent: true` answers "may a bound agent call
+ * this", which is an orthogonal question — a nightly reconciliation that an
+ * analyst can also ask an agent to run on demand is one automation, not two.
+ * So `agent` rides alongside either, and the third arm exists for the
+ * agent-only automation, which has no self-starting trigger at all.
+ *
+ * Declaring it is only the AUTHOR's half of the permission. A workspace
+ * operator must still bind the automation to one named agent before any tool
+ * is projected; see the design in
+ * docs/superpowers/specs/2026-08-27-agent-callable-automations-design.md.
  */
 export type AutomationTrigger =
-  | { cron: string; manual?: never }
-  | { cron?: never; manual: true }
+  | { cron: string; manual?: never; agent?: true }
+  | { cron?: never; manual: true; agent?: true }
+  | { cron?: never; manual?: never; agent: true }
 
 /**
  * An author-time affordance, not a validation gate.