@controllerai/cli 0.2.0

package/skills/controllerai-expressions/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: controllerai-expressions
+description: Author, validate, persist, and debug Controller AI expressions for node props and conditions. Use when a value comes from a flow input, upstream node, loop item, workflow data, constant, calculation, template, or boolean rule, or when an expression compiles but resolves to null or the wrong input.
+---
+
+# Controller AI expressions
+
+Controller AI uses a restricted JavaScript-like authoring language that is compiled into the workflow engine's expression AST. It is not general JavaScript. Discover the real scope and compile before every write.
+
+Data types are the TypeScript types of workflows: every expression is typed, and an expression can only be written against a known type. Integration types describe what integration actions output (resolved by a successful dev run); `custom.*` types describe shapes for data-store records and AI-node structured outputs. Two wrappers matter: `dataRecord.custom.x` means "an actual stored record of that shape" — the fields plus record identity (`id`, `createdAt`) — while bare `custom.x` is just data in that shape; `list.` prefixes a list of any type. When an expression cannot be authored, the cause is usually a missing type — resolve the upstream node's output type first, don't guess field paths.
+
+## How empty values evaluate
+
+An empty input is not "nothing" — it evaluates to the type's empty form: empty text `""` for TEXT, null/undefined for objects. Two platform semantics follow, and both fail silently rather than erroring:
+
+- **A filter comparing against an empty value still filters — and matches NO records.** This is deliberate (fail-closed; matching everything by accident would be worse). If "empty should mean skip this filter", opt that constraint into ignore-empty mode explicitly (`ignoreEmptyConstraints`, see [references/dsl-and-recipes.md](references/dsl-and-recipes.md)).
+- **An optional TEXT input left empty arrives as `""`**, so an `equals` constraint against it matches nothing — the classic symptom is "search finds zero results only when the optional filter is blank", which then cascades (e.g. a create-if-missing step makes duplicates).
+
+When a run unexpectedly returns zero results, check the resolved configs for empty comparison values first (`cai exec ports`).
+
+## Required write loop
+
+### 1. Wire first
+
+An upstream output is available only after it is connected to the target node. If context lists it under `unwiredUpstreamOutputs`, connect it, then fetch context again.
+
+```bash
+cai node connect --flow <flowId> --from <sourceNodeId> --to <targetNodeId> --json
+```
+
+Use `cai branch connect` for Router or If/Else outputs.
+
+### 2. Read the destination's exact scope
+
+```bash
+cai expr context <nodeId> --prop <propName> --json
+```
+
+Copy binding and field names exactly. Important sources include:
+
+- `flow.<name>`: flow input
+- `inputs.<name>`: wired node input; the payload is usually already unwrapped
+- `item`: injected current item, only where context exposes it
+- `workflowData("custom.type")`: records from an active workflow collection
+- `now`, `isLiveVersion`: constants shown by context
+
+Do not derive a binding from a display label. Context flags duplicate display names and supplies the de-duplicated JS name, input ID, and source node.
+
+### 3. Use only advertised syntax
+
+Get the current operation catalog when needed:
+
+```bash
+cai expr ops --type <text|number|date|list|boolean|file|custom> --json
+```
+
+Keep the program to optional `const` declarations followed by one final expression. Do not use loops, assignments, `new`, regular expressions, optional chaining, arbitrary library methods, or object construction unless the current compiler catalog explicitly supports them.
+
+Read [references/dsl-and-recipes.md](references/dsl-and-recipes.md) for canonical patterns.
+
+### 4. Compile, write, and read back atomically
+
+For a node prop, prefer:
+
+```bash
+cai expr set <nodeId> --prop <propName> --js '<expression>' --json
+```
+
+For multiline expressions or shell-sensitive templates, put the exact source in a UTF-8 file and use `--js-file <path>`. Use `--js-file -` to read stdin. It is mutually exclusive with inline `--js` and is available on `expr validate/set`, `node set/only-when`, and `branch add/update`.
+
+```bash
+cai expr set <nodeId> --prop <propName> --js-file expression.js --json
+```
+
+This fetches target metadata, compiles without writing on failure, chooses `valueJs` versus `expressionValueJs`, persists, and verifies read-back.
+
+For a side-effect-free check:
+
+```bash
+cai expr validate <nodeId> --prop <propName> --js '<expression>' --json
+```
+
+For conditions:
+
+```bash
+cai expr validate <nodeId> --mode onlyWhen --js '<boolean expression>' --json
+cai node only-when <nodeId> --js '<boolean expression>' --json
+```
+
+Router and If/Else conditions are written with `cai branch add` or `cai branch update` after the same context/validation discipline.
+
+### 5. Verify runtime resolution
+
+```bash
+cai expr decompile <nodeId> --prop <propName> --json
+cai run node <nodeId> --inputs <values.json> --json
+```
+
+Use `run node` to isolate the destination's own configuration. It never executes wired upstream nodes. If the expression consumes `inputs.<name>`, also run its containing flow:
+
+```bash
+cai run flow <flowId> --inputs <values.json> --json
+```
+
+Inspect `runScope` and `resolvedConfigs` in the run result. A null or missing dynamic config is an expression failure, not success; a partially empty value is equally suspect. Only the full flow run proves an upstream-derived value. Use `cai exec ports <nodeExecutionId> --json` to compare inputs, resolved configs, and outputs.
+
+## Hard rules
+
+- Never guess a binding, field, method, or target type.
+- Never author against an unwired output.
+- Never add `.data` automatically. Use the exact path shown by context.
+- Re-read context after rewiring, renaming inputs, changing schemas, changing dynamic selectors, or resolving an output type.
+- Preserve `0` and `false`; they are values, not missing data.
+- Optional filters need an explicit behavior decision. Do not silently change fail-closed filtering to match-all.
+- A compiler success proves syntax and types, not correct source selection. Verify the source node/input IDs when names are ambiguous and inspect runtime values.

package/skills/controllerai-expressions/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Controller AI Expressions"
+  short_description: "Author and verify dynamic workflow expressions"
+  default_prompt: "Write and validate the Controller AI expressions needed for this workflow using exact runtime bindings."

package/skills/controllerai-expressions/references/dsl-and-recipes.md

@@ -0,0 +1,120 @@
+# Expression DSL and recipes
+
+The live compiler and `cai expr context`/`cai expr ops` are authoritative. These examples show structure, not names to copy blindly.
+
+## Text template
+
+```js
+`Hello ${flow.firstName.trim()}, order ${inputs.order.id} is ready`
+```
+
+Use the exact bindings and fields returned for the destination node.
+
+## HTTP JSON body
+
+An HTTP node's JSON/body prop is stored as JSON text. The expression language does not support object literals or `JSON.stringify`. Build the document as a template and insert complete JSON tokens:
+
+```js
+`{"message":${flow.name.jsonEncode()},"payload":${flow.user.stringify()}}`
+```
+
+- Use `.jsonEncode()` for text or boolean values. It returns a JSON-safe token, including the quotes around text, so do not add another pair of quotes around `${...}`.
+- Use `.stringify()` for a custom object or list.
+- Keep JSON punctuation outside the interpolation and validate against the destination's exact prop before writing.
+
+```bash
+cai expr validate <httpNodeId> --prop <jsonBodyProp> --js-file body-expression.js --json
+cai expr set <httpNodeId> --prop <jsonBodyProp> --js-file body-expression.js --json
+```
+
+## Same-type fallback
+
+```js
+flow.count ?? 0
+flow.label ?? "unknown"
+flow.enabled ?? false
+```
+
+Fallbacks must be same-type literals. `0` and `false` remain real values.
+
+## Boolean condition
+
+```js
+flow.email.isNotEmpty()
+inputs.score >= 80
+```
+
+Validate conditions with `--mode onlyWhen` and without a prop name.
+
+## Dates
+
+```js
+inputs.createdAt.toDate() > now.plusDays(-7)
+inputs.createdAt.toDate().format("YYYY-MM-DD")
+```
+
+Convert text to a date before date math. Use negative amounts to move backward.
+
+## Workflow records
+
+Filter immediately after `workflowData` so the engine can push supported predicates into storage:
+
+```js
+workflowData("custom.lead")
+  .filter(row => row.status === "active")
+  .sortBy("created_at", "desc")
+```
+
+The collection must exist on the current dev/live rail. A schema declaration alone does not guarantee active records.
+
+## Optional filter inputs
+
+Filters are fail-closed by default: a missing right-hand value matches no records. Use optional matching only when the user's requirement explicitly allows an omitted constraint:
+
+```js
+workflowData("custom.lead").filter(
+  row => row.ownerId === flow.ownerId,
+  { ignoreEmptyConstraints: true }
+)
+```
+
+Test both the supplied and omitted cases. Empty text may behave as a real value rather than a missing value; do not assume the opt-in drops it.
+
+## Loop item
+
+Where context exposes `item`, primitive lists use the item directly:
+
+```js
+item
+```
+
+Object lists use an advertised field:
+
+```js
+item.email
+```
+
+Inside the child flow, the item arrives through a flow input and is referenced as `flow.<name>`, not `item`.
+
+## Loop output
+
+Run-on-list output is a list of iteration records. Child flow outputs live under `outputs`:
+
+```js
+inputs.enrichEach[0].outputs.score
+```
+
+Confirm the exact binding and field path in context.
+
+## Troubleshooting sequence
+
+1. `cai expr context <node> --prop <prop> --json`
+2. Confirm the intended source is wired and its `sourceNodeId` is correct.
+3. `cai expr validate ...`
+4. `cai expr set ...`
+5. `cai expr decompile ...`
+6. `cai run node ... --json` for isolated destination configuration
+7. `cai run flow <flowId> ... --json` when the expression consumes a wired upstream input
+8. `cai exec ports <nodeExecutionId> --json`
+
+If compilation succeeds but runtime is null or partially empty, inspect `runScope`, the actual input value, and `resolvedConfigs`; do not keep rewriting syntax blindly. A node-only run cannot prove an `inputs.<name>` binding because it does not execute upstream nodes.

package/skills/controllerai-flow-control/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: controllerai-flow-control
+description: Design and configure Controller AI execution paths using only-when rules, Router routes, If/Else branches, for-each loops, and subflows. Use when work must branch, fan out, skip, iterate over a list, call another flow, converge paths, or handle errors without changing the user's intended semantics.
+---
+
+# Controller AI flow control
+
+Choose the primitive from the intended execution semantics before adding nodes.
+
+## Pick the correct primitive
+
+| Intent | Primitive | Semantics |
+| --- | --- | --- |
+| Skip one action when a condition is false | Node `only-when` | No alternate path |
+| Choose exactly one path | If/Else | First matching branch runs; Else is last |
+| Run every matching path | Router | Conditions are independent; multiple routes may run |
+| Apply work to every list item | `flow for-each` | Atomic loop scaffold with typed item flow |
+| Reuse a typed unit of work once | Run flow/subflow node | Explicit input and output contract |
+| Continue after an action error | Error output or continue-on-error | Error behavior is explicit and testable |
+
+Do not substitute one primitive merely because its component is easier to find.
+
+## Conditions
+
+Before writing any condition:
+
+```bash
+cai expr context <controlNodeId> --json
+cai expr validate <controlNodeId> --mode onlyWhen --js '<boolean expression>' --json
+```
+
+For one guarded action:
+
+```bash
+cai node only-when <nodeId> --js '<boolean expression>' --json
+```
+
+Use `--clear` only when the user's intent is to remove the guard.
+
+## If/Else and Router
+
+Discover and initialize the appropriate control component using `controllerai-node-config`, then inspect its exact branch IDs:
+
+```bash
+cai branch list <controlNodeId> --json
+```
+
+A fresh If/Else already contains one blank `If` branch and an Else branch. The blank condition is a publish/runtime blocker: copy that default branch ID from `branch list` and update it before adding another condition branch. Do not leave the default blank and create a replacement beside it.
+
+```bash
+cai branch update <ifElseNodeId> \
+  --route <defaultIfBranchId> \
+  --name "<meaning>" \
+  --js '<boolean expression>' \
+  --json
+```
+
+Add another condition only when the decision needs another non-Else case. Router routes are independent, so update an existing blank route or add each intended route explicitly:
+
+```bash
+cai branch add <controlNodeId> --name "<meaning>" --js '<boolean expression>' --json
+cai branch update <controlNodeId> --route <routeOrBranchId> --js '<boolean expression>' --json
+cai branch connect <controlNodeId> --route <routeOrBranchId> --to <targetNodeId> --flow <flowId> --json
+```
+
+For If/Else, order is behavior:
+
+```bash
+cai branch reorder <ifElseNodeId> --order <conditionId1,conditionId2> --json
+```
+
+List every condition branch exactly once and omit Else; the CLI keeps Else last. Router routes cannot be reordered because every match runs.
+
+After edits, run `cai branch list` again. Treat its warnings about missing conditions or unwired paths as blockers: an unwired selected path can end with an apparently green execution.
+
+## Loops
+
+Never assemble the standard per-item subflow pattern by hand:
+
+```bash
+cai node get <listProducingNodeId> --json
+cai flow for-each \
+  --flow <parentFlowId> \
+  --from <listProducingNodeId> \
+  --source-output <exactOutputId> \
+  --name "<item flow name>" \
+  --item-type <text|number|date|boolean|custom.type> \
+  --json
+```
+
+Use repeatable `--item-field <id:type[:display]>` only when creating a new `custom.*` item type.
+
+Copy `--source-output` from the selected node's exact `outputs[].id`. It is an opaque ID, not `displayName`, and there is no first-output default. This matters for Router, If/Else, and error outputs as well as ordinary action nodes.
+
+- If the source's whole output is the list, omit both `--list-field` and `--list-js`.
+- If the list is nested in the source payload, use `--list-field` with the dot-delimited path below `.data`; the CLI derives the not-yet-created loop input binding deterministically.
+- Use `--list-js` only for an advanced exact expression. For multiline or shell-sensitive source, use `--js-file <path|->` instead. Both are mutually exclusive with `--list-field` and with each other; copy the wrapper/binding shape from expression context rather than guessing it.
+- The runtime cap defaults to 500 items and accepts 1 through 10000. Set `--max-items` explicitly when the product requirement differs. The CLI creates the core scaffold first, then materializes and verifies this optional prop. The cap is all-or-nothing at runtime: a list larger than the cap throws and NOTHING iterates — there is no partial truncation.
+
+Read every returned warning. A list/item type mismatch means the scaffold is not verified even though it was created. Follow the returned `nextSteps` in order.
+
+Inside loop mappings, `item` exists only where context exposes it. Inside the body flow, use its `flow.<itemInput>` binding. Downstream loop results are iteration records whose declared child outputs are under `.outputs`.
+
+Loops run sequentially. `--continue-on-error` applies to a failed child iteration; a list expression or mapping/config expression that fails before the child starts still aborts the loop. Test empty, one-item, several-item, over-limit, and intended iteration-error behavior.
+
+## Subflows and convergence
+
+Define the called flow's inputs and outputs first. Then initialize a Run flow component and bind it:
+
+```bash
+cai node set-flow <runFlowNodeId> --flow <calledFlowId> --json
+cai node props <runFlowNodeId> --json
+```
+
+Setting the target flow creates mapping props from the target's current inputs. If those inputs later change, run `set-flow` again and reconfigure mappings.
+
+When paths converge, inspect the concrete graph and execution behavior. Do not assume wiring two paths to one action creates a barrier or waits for both. If the requirement is a true join, discover a join-capable component and verify it with representative branch timing.
+
+Return semantics: a flow that should return data needs a Return response node — without one it returns nothing, and callers (including agents invoking it as a tool) see silent success with empty output. If several Return response nodes complete in one execution, their result objects merge in execution order and a later node silently overwrites an earlier value for the same field. Design for exactly one Return per path unless merging is the intent.
+
+Deleting a flow is a normal, undoable edit: it removes the flow's nodes, edges, inputs/outputs, and attached triggers, and unlinks run-subflow callers in other flows — the same way deleting a function breaks its call sites. No confirmation ceremony is needed; run `cai workflow validate` afterwards to see every break, fix or remove the callers it lists, and `cai workflow restore` if the deletion was a mistake. Turning `continueOnError` off is the same class: it deletes the node's Error output and every edge from it — validate after, restore if regretted.
+
+Read [references/patterns.md](references/patterns.md) for concise canonical patterns.
+
+## Completion gate
+
+- Every branch has the intended condition and a wired target.
+- If/Else ordering matches priority and Else remains last.
+- Router fan-out is intentional when more than one condition can be true.
+- Loop item type and list expression compile against actual source data.
+- Expected true, false/Else, empty-list, one-item, several-item, over-limit, and error paths are tested.
+- `cai exec tree <workflowExecutionId>` contains no unexplained skipped or missing nodes.

package/skills/controllerai-flow-control/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Controller AI Flow Control"
+  short_description: "Build branches, loops, joins, and subflows"
+  default_prompt: "Build the Controller AI control flow, wire every path, and verify each branch or loop."

package/skills/controllerai-flow-control/references/patterns.md

@@ -0,0 +1,61 @@
+# Flow-control patterns
+
+## Guard a side effect
+
+Use `only-when` when false should mean "skip this action" and nothing else:
+
+```text
+Read record -> Send notification [only when status changed]
+```
+
+Test both true and false. A false run should show an intentional skip reason.
+
+## Exclusive decision
+
+Use If/Else when only one outcome must occur:
+
+```text
+Score -> If/Else
+           high priority -> Escalate
+           normal        -> Queue
+           Else          -> Record unknown
+```
+
+Put the most specific/highest-priority conditions first. Never write a complement condition for Else.
+
+## Independent fan-out
+
+Use Router when every applicable action should run:
+
+```text
+New order -> Router
+              international -> Customs review
+              high value    -> Fraud review
+              gift          -> Gift note
+```
+
+One order may take all three routes. If that is not acceptable, use If/Else.
+
+## Per-item subflow
+
+Use `cai flow for-each` to create the item flow, typed item input, loop node, and list wiring atomically. First run `cai node get <sourceNodeId> --json`, choose the intended `outputs[]` entry, and pass its exact opaque `id` as `--source-output`; never pass its label or assume the first output. Omit list-selection flags when the whole selected output payload is a list; use `--list-field <nested.path>` for a list below `.data`; reserve `--list-js` for an exact advanced expression or `--js-file <path|->` for that expression in a UTF-8 file/stdin. The three selection forms are mutually exclusive.
+
+The runtime limit defaults to 500 items and supports 1 through 10000. Use `--max-items` when the intended bound differs, then verify the returned read-back. Put meaningful work inside the generated body flow and declare body outputs before consuming aggregate results.
+
+Decide explicitly whether one child-flow failure should stop the sequential loop. Use `--continue-on-error` only when partial completion is acceptable and downstream logic handles failed iteration records. It does not recover a list or mapping expression that fails before an iteration starts.
+
+## Error path
+
+Continue-on-error is for steps whose failure must not block the main path — notifications, logging, optional enrichment. Enabling it captures the node's error, downstream nodes still execute (receiving null for the failed node's output), and the run ends `completed_with_error`:
+
+```bash
+cai node continue-on-error <nodeId> --enable --json
+```
+
+Wiring the Error output is OPTIONAL — add it when a failure needs explicit handling, not as a precondition:
+
+```bash
+cai node connect --flow <flowId> --from <nodeId> --to <handlerNodeId> --output error --json
+```
+
+Never enable continue-on-error on critical-path steps (validate → charge → confirm must fail fast), and never merely to make the parent execution green. Read back the setting after changing it.

package/skills/controllerai-integration-actions/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: controllerai-integration-actions
+description: Discover, connect, attach, update, and verify ready integration actions used directly by Controller AI agents. Use when an agent needs one existing app operation without a workflow, when choosing between a direct action and a workflow tool, or when changing an action's connection or per-run approval policy.
+---
+
+# Controller AI integration actions
+
+Ready integration actions give a hosted agent one app operation without first building a workflow. Use only the `cai` commands below; do not call Controller AI REST or MCP routes directly.
+
+## Choose direct action or workflow
+
+Use a direct action for one existing operation such as sending one message, creating one record, or adding one row.
+
+Use a workflow tool instead when the capability needs multiple operations, transformations, branches, loops, durable state, triggers, a custom typed contract, or reuse outside the agent. Do not build a one-node workflow when the same ready action already fits.
+
+## Discover exact identities
+
+```bash
+cai integration search "<app or capability>" --json
+cai integration actions <integrationSlug> --search "<operation>" --json
+```
+
+Preserve the returned integration `slug` and action `key` exactly. Never derive either from a display label. Continue with `--after <nextCursor>` when pagination reports more results.
+
+## Select a connection
+
+```bash
+cai connection list --integration <integrationSlug> --json
+```
+
+Use an active connection whose `nodeSlug` exactly matches the integration. If none exists:
+
+```bash
+cai connection connect <integrationSlug>
+```
+
+The browser handoff keeps provider credentials out of the agent context. Re-list connections after the user finishes.
+
+## Decide approval before attaching
+
+The product default is to run without per-call approval. Do not accept that default mechanically. Inspect the action name, description, pricing, and intended use, then decide:
+
+- Require confirmation for deletion, purchases or spend, external communications, permission changes, irreversible writes, or an ambiguous destination.
+- Usually omit confirmation for read-only retrieval and low-risk, reversible operations the user clearly asked the agent to perform autonomously.
+
+Tell the user which policy was selected and why when it has a meaningful consequence.
+
+```bash
+cai agent add-action <agentId> \
+  --integration <integrationSlug> \
+  --action <actionKey> \
+  --connection <connectionId> \
+  --description "Use when ..." \
+  --require-confirmation \
+  --json
+```
+
+Omit `--require-confirmation` only after making the decision; the CLI still sends an explicit `false`. Do not attach the same action twice.
+
+Read the saved grant back:
+
+```bash
+cai agent tools <agentId> --json
+```
+
+Verify `toolType`, integration, action key, connection, schema tier, description, and confirmation policy. The hosted runtime configures dynamic action properties when it invokes the action; the builder does not preconfigure runtime-only action arguments here.
+
+To rebind the live authorization grant or change a versioned policy:
+
+```bash
+cai agent update-tool <agentId> --tool <toolId> --connection <connectionId> --json
+cai agent update-tool <agentId> --tool <toolId> --require-confirmation --json
+cai agent update-tool <agentId> --tool <toolId> --no-confirmation --json
+```
+
+`--connection` can redirect the published action immediately because authorization is live-bound. Description and confirmation-policy edits remain draft changes until the agent is published.
+
+## Verify through the hosted agent
+
+Use a representative draft conversation:
+
+```bash
+cai agent test <agentId> --draft --message "<request>" --json
+cai agent conversation history <conversationId> --json
+```
+
+A direct action runs inline and does not create a workflow execution ID. Evidence is the persisted conversation, its direct-action tool/run events, the returned result, and any observed external side effect. Never invent a workflow execution ID for it.
+
+If confirmation is required, inspect the pending action and exact arguments before approving or denying its request. A successful assistant reply alone does not prove the intended action ran.
+
+## Publishing and sharing semantics
+
+Publishing snapshots the action identity, description, and approval policy into the agent version. The connection and authorization grant remain live security bindings: rebinding can redirect the published action, while breakage, revocation, or detachment can stop it immediately without another agent publish. Detachment also removes the draft tool; publish afterward to remove the unavailable tool from the published list.
+
+Organization members use the published agent, never its mutable draft. Direct actions run through the agent owner's connected external account. Controller AI usage draws from the organization's shared usage pool, regardless of which member calls the agent. State that credential boundary before organization sharing.

package/skills/controllerai-integration-actions/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Controller AI Integration Actions"
+  short_description: "Attach ready integration actions to agents"
+  default_prompt: "Use $controllerai-integration-actions to find and attach the right integration action to my Controller AI agent."