@frontera-sdk/cli 1.45.11 → 1.45.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontera-sdk/cli",
-  "version": "1.45.11",
+  "version": "1.45.12",
   "description": "The frontera CLI — scaffold, pull, save and deploy Frontera apps and automations.",
   "keywords": [
     "frontera",
@@ -38,8 +38,8 @@
     "build:release": "bun run scripts/build-release.ts"
   },
   "dependencies": {
-    "@frontera-sdk/automation": "1.45.9",
-    "@frontera-sdk/core": "1.45.9",
+    "@frontera-sdk/automation": "1.45.12",
+    "@frontera-sdk/core": "1.45.12",
     "gray-matter": "^4.0.3",
     "yaml": "^2.9.0"
   },

package/src/api/automation-api.ts

@@ -26,6 +26,37 @@ export interface AutomationVersionSummary {
   createdAt: string
 }
 
+/** One agent↔automation binding, as the bindings routes return it. */
+export interface AgentAutomationBinding {
+  agentId: string
+  agentSlug: string
+  agentName: string
+  enabled: boolean
+  requiresApproval: boolean
+  waitSeconds: number
+  createdBy: string
+  createdAt: string
+}
+
+/**
+ * One binding seen from the agent's side.
+ *
+ * `projects` is the field worth reading: a binding can exist and grant nothing
+ * when the author has withdrawn `trigger: { agent: true }` from the live
+ * version, and a list without it reads as a working permission.
+ */
+export interface AgentBindingView {
+  automationSlug: string
+  automationId: string
+  enabled: boolean
+  requiresApproval: boolean
+  waitSeconds: number
+  projects: boolean
+  inertReason: 'no_live_version' | 'not_agent_callable' | 'version_retired' | 'disabled' | null
+  createdBy: string
+  createdAt: string
+}
+
 export interface AutomationDeployResult {
   automationId: string
   versionId: string
@@ -293,6 +324,44 @@ export class AutomationApi {
     )
   }
 
+  /**
+   * Which agents may run this automation from a conversation.
+   *
+   * Two locks have to be open before any of this matters: the automation's own
+   * manifest must declare `trigger: { agent: true }` (the author's half), and a
+   * binding must name the agent (the operator's half, these three calls).
+   */
+  bindings(slug: string): Promise<AgentAutomationBinding[]> {
+    return this.client.request<AgentAutomationBinding[]>(
+      `/v1/automations/${encodeURIComponent(slug)}/bindings`,
+    )
+  }
+
+  bind(
+    slug: string,
+    agentSlug: string,
+    options: { enabled?: boolean; requiresApproval?: boolean; waitSeconds?: number } = {},
+  ): Promise<AgentAutomationBinding> {
+    return this.client.request<AgentAutomationBinding>(
+      `/v1/automations/${encodeURIComponent(slug)}/bindings/${encodeURIComponent(agentSlug)}`,
+      { method: 'PUT', body: options },
+    )
+  }
+
+  /** The same question from the agent's side: what may this agent start? */
+  agentBindings(agentSlug: string): Promise<AgentBindingView[]> {
+    return this.client.request<AgentBindingView[]>(
+      `/v1/automations/agent-bindings/${encodeURIComponent(agentSlug)}`,
+    )
+  }
+
+  unbind(slug: string, agentSlug: string): Promise<{ unbound: boolean }> {
+    return this.client.request<{ unbound: boolean }>(
+      `/v1/automations/${encodeURIComponent(slug)}/bindings/${encodeURIComponent(agentSlug)}`,
+      { method: 'DELETE' },
+    )
+  }
+
   setEnabled(slug: string, enabled: boolean): Promise<{ slug: string; enabled: boolean }> {
     return this.client.request<{ slug: string; enabled: boolean }>(
       `/v1/automations/${encodeURIComponent(slug)}/enabled`,

package/src/commands/automation/bindings.ts

@@ -0,0 +1,193 @@
+/**
+ * `frontera automation bind|unbind|bindings` — the operator's half of making an
+ * automation callable from a conversation.
+ *
+ * The author's half is in the manifest (`trigger: { agent: true }`, plus a
+ * description of the automation and of every input) and is checked at deploy.
+ * These verbs cannot substitute for it: the service refuses a binding whose
+ * automation does not declare the flag, and the message says so.
+ *
+ * `bind` and `unbind` are separate verbs rather than `bind --off`, for the same
+ * reason `disable` is not `enable --false`: taking a permission away is done
+ * under pressure, and a flag is one more thing to get wrong.
+ */
+import { AutomationApi } from '../../api/automation-api'
+import { UsageError } from '../../errors'
+import { table } from '../../table'
+import { flagString, type Command, type CommandContext } from '../types'
+
+function requireSlug(ctx: CommandContext): string {
+  const slug = ctx.positional[0]
+  if (!slug) {
+    throw new UsageError(
+      'missing <slug>',
+      'run `frontera automation list` — then pass the slug of the one you mean',
+    )
+  }
+  return slug
+}
+
+function requireAgent(ctx: CommandContext): string {
+  const agent = flagString(ctx, 'agent')
+  if (!agent) {
+    throw new UsageError(
+      'missing --agent <agent-slug>',
+      'a binding names exactly one agent — there is no "all agents" form on purpose',
+    )
+  }
+  return agent
+}
+
+const bind: Command = {
+  meta: {
+    noun: 'automation',
+    verb: 'bind',
+    args: [{ name: 'slug', required: true, description: 'automation slug' }],
+    flags: { agent: 'string', approval: 'string', wait: 'string' },
+    summary: 'Let one agent run this automation from a conversation',
+    examples: [
+      'frontera automation bind reconcile-invoices --agent finance-analyst',
+      'frontera automation bind reconcile-invoices --agent analyst --approval auto',
+      'frontera automation bind reconcile-invoices --agent analyst --wait 120',
+    ],
+  },
+
+  async run(ctx) {
+    const slug = requireSlug(ctx)
+    const agent = requireAgent(ctx)
+
+    // `required` is the default at every layer, and it is spelled out here
+    // rather than left to the server's default so that `--approval` reads as a
+    // choice an operator made either way.
+    const approval = flagString(ctx, 'approval') ?? 'required'
+    if (approval !== 'required' && approval !== 'auto') {
+      throw new UsageError(
+        `--approval must be "required" or "auto", got "${approval}"`,
+        '`required` asks a human before each call; `auto` does not',
+      )
+    }
+
+    const rawWait = flagString(ctx, 'wait')
+    const waitSeconds = rawWait === undefined ? undefined : Number(rawWait)
+    if (waitSeconds !== undefined && !Number.isInteger(waitSeconds)) {
+      throw new UsageError(
+        `--wait must be a whole number of seconds, got "${rawWait}"`,
+        'how long the agent waits for the run before it is told it is still going (5–300)',
+      )
+    }
+
+    const result = await new AutomationApi(ctx.apiUrl, ctx.token, ctx.workspaceId).bind(
+      slug,
+      agent,
+      { requiresApproval: approval === 'required', waitSeconds },
+    )
+
+    return {
+      data: result,
+      text:
+        `Bound ${slug} to ${result.agentSlug} — approval ${result.requiresApproval ? 'required' : 'not required'}, `
+        + `waits ${result.waitSeconds}s.`,
+    }
+  },
+}
+
+const unbind: Command = {
+  meta: {
+    noun: 'automation',
+    verb: 'unbind',
+    args: [{ name: 'slug', required: true, description: 'automation slug' }],
+    flags: { agent: 'string' },
+    summary: 'Stop one agent being able to run this automation',
+    examples: ['frontera automation unbind reconcile-invoices --agent finance-analyst'],
+  },
+
+  async run(ctx) {
+    const slug = requireSlug(ctx)
+    const agent = requireAgent(ctx)
+    await new AutomationApi(ctx.apiUrl, ctx.token, ctx.workspaceId).unbind(slug, agent)
+    return { data: { unbound: true }, text: `${agent} can no longer run ${slug}.` }
+  },
+}
+
+/**
+ * Both directions of the same question, because an operator asks it from both
+ * ends: the function owner asks who can run their code, and a security review
+ * asks what one agent can reach. Answering the second by walking every
+ * automation's bindings is the kind of fan-out that gets skipped.
+ */
+const bindings: Command = {
+  meta: {
+    noun: 'automation',
+    verb: 'bindings',
+    args: [
+      {
+        name: 'slug',
+        required: false,
+        description: 'automation slug — omit it and pass --agent to ask from the agent side',
+      },
+    ],
+    flags: { agent: 'string' },
+    summary: 'List the agents that may run an automation, or what one agent may run',
+    examples: [
+      'frontera automation bindings reconcile-invoices',
+      'frontera automation bindings --agent finance-analyst',
+    ],
+  },
+
+  async run(ctx) {
+    const client = new AutomationApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
+    const agent = flagString(ctx, 'agent')
+    const slug = ctx.positional[0]
+
+    if (!slug && !agent) {
+      throw new UsageError(
+        'pass an automation slug, or --agent <agent-slug>',
+        'the first lists who may run one automation; the second lists what one agent may run',
+      )
+    }
+
+    if (agent) {
+      const rows = await client.agentBindings(agent)
+      return {
+        data: rows,
+        text:
+          rows.length === 0
+            ? `${agent} cannot run any automation from a conversation.`
+            : table(
+                ['automation', 'grants a tool', 'approval', 'wait', 'why not'],
+                rows.map((b) => [
+                  b.automationSlug,
+                  // The load-bearing column. A binding that grants nothing
+                  // still has a row, and a list that showed only the row would
+                  // read as a working permission.
+                  b.projects ? 'yes' : 'no',
+                  b.requiresApproval ? 'required' : 'auto',
+                  `${b.waitSeconds}s`,
+                  b.inertReason ?? '',
+                ]),
+              ),
+      }
+    }
+
+    const rows = await client.bindings(slug!)
+    return {
+      data: rows,
+      text:
+        rows.length === 0
+          ? `No agent can run ${slug} from a conversation.`
+          : table(
+              ['agent', 'name', 'enabled', 'approval', 'wait', 'bound by'],
+              rows.map((b) => [
+                b.agentSlug,
+                b.agentName,
+                String(b.enabled),
+                b.requiresApproval ? 'required' : 'auto',
+                `${b.waitSeconds}s`,
+                b.createdBy,
+              ]),
+            ),
+    }
+  },
+}
+
+export const automationBindingCommands: Command[] = [bind, unbind, bindings]

package/src/commands/automation/index-commands.ts

@@ -11,6 +11,7 @@ import { automationInit } from './init'
 import { automationPull } from './pull'
 import { automationRun, automationRuns } from './run'
 import { automationDev } from './dev'
+import { automationBindingCommands } from './bindings'
 import { buildAndExtract } from './build-entry'
 
 export { buildAndExtract } from './build-entry'
@@ -313,4 +314,5 @@ export const automationCommands: Command[] = [
   automationPull,
   automationInit,
   automationDev,
+  ...automationBindingCommands,
 ]

package/src/flag-help.ts

@@ -13,6 +13,11 @@
  * fails if a command declares a flag this file does not describe.
  */
 export const FLAG_HELP: Readonly<Record<string, string>> = {
+  // Agent↔automation bindings. `agent` is deliberately singular: a binding
+  // names one agent, and there is no wildcard form.
+  agent: 'agent slug this binding is for — one agent, no wildcard',
+  approval: '"required" (default) asks a human before each call; "auto" does not',
+  wait: 'seconds the agent waits for the run before it is told the run is still going (5–300)',
   // Declarative Blueprint authoring — the file tree, and what applying it may do.
   prune: 'also remove artifacts that are on the draft but absent from the file tree',
   dataset: 'dataset name the object type reads through; the revision is resolved at apply time',