@controllerai/cli 0.2.17 → 0.2.20

package/skills/controllerai-agents/references/command-reference.md

@@ -0,0 +1,205 @@
+# Controller AI agents
+
+An agent has one mutable draft and immutable published versions. Build instructions, tools, permissions, and files on the draft; verify in Test; publish last. Draft edits never update Live by themselves.
+
+
+
+- Attach one ready action directly instead of wrapping it; see Choose the capability architecture.
+- Choose confirmation before attaching a consequential tool; see Create and assemble the draft.
+- Use one conversation on an explicit rail for each verification task; see Verify the draft as an agent.
+- Resolve pending requests in that same conversation; see Verify the draft as an agent.
+- Enablement is runtime state, not publication; see Create and assemble the draft.
+- Publish authorized workflow dependencies, preflight, then publish the agent; see Publish in dependency order.
+- Draft-only means stop before publish; draft evidence never proves Live. See Publish in dependency order.
+
+## 1. Choose the capability architecture
+
+- Use `controllerai-integration-actions` when one existing app operation completes it.
+- Use a workflow tool for multiple steps, transformations, branching, looping, durable state, triggers, a custom typed contract, or reusable business logic.
+- Put judgment, tool-selection rules, tone, and escalation in instructions; put stable sources in knowledge files.
+
+Do not create a one-node workflow merely to expose a ready action, or replace orchestration with several independent direct actions when ordering or data handling must be deterministic.
+
+## 2. Build and verify capabilities
+
+For a ready action, follow `controllerai-integration-actions`: discover exact identities, select a connection, decide confirmation, then attach.
+
+For every workflow tool, load the relevant workflow skills and test the development state before attaching:
+
+```bash
+cai use <workflowId>
+cai flow get <flowId> --json
+cai run flow <flowId> --inputs values.json --json
+```
+
+MCP: there is no pin; pass `workflowId` to `flow_get` and `run_flow`, pass parsed `inputs`, and set `waitSeconds`.
+
+Capture the successful execution ID. Inputs become tool parameters and outputs its result. Require a nonempty output contract and verify the run returns it.
+
+## 3. Create and assemble the draft
+
+
+Read [instructions-and-versioning.md](instructions-and-versioning.md) before publishing or explaining Test versus Live behavior.
+
+```bash
+cai agent create --name "<agent name>" --instructions-file instructions.md --json
+```
+
+MCP: `agent_create` takes complete Markdown in `instructions`; it cannot read `instructions.md`.
+
+```bash
+cai agent add-action <agentId> \
+  --integration <integrationSlug> \
+  --action <actionKey> \
+  --connection <connectionId> \
+  --description "Use when ..." \
+  --json
+
+cai agent add-workflow <agentId> \
+  --workflow-id <workflowId> \
+  --flow <flowId> \
+  --description "Use when ...; accepts ...; returns ..." \
+  --json
+```
+
+MCP: use `agent_tool_action_add` or `agent_tool_workflow_add`; `requireConfirmation` is optional and defaults to `false`.
+
+```bash
+cai agent add-file <agentId> --file <path> --space <knowledge|shared> --json
+cai agent files <agentId> --space <knowledge|shared> [--live] --json
+cai agent tools <agentId> --json
+cai agent get <agentId> --json
+```
+
+MCP: use `agent_knowledge_file_add` or `agent_workspace_file_add` with inline `content`; `agent_file_list` uses `environment: dev|live`. Shared runtime files update live immediately.
+
+The default is no approval: attached actions and workflow tools run without a human approval step unless `requireConfirmation` is `true`, and omitting `--require-confirmation` has the same behavior. When attaching an action that sends, posts, spends, or deletes, choose `true` or explicitly tell the user that it will run unattended. Mention the confirmation choice in the report to the user; `cai agent update-tool` can change it later.
+
+Keep the two modes straight:
+
+| Context | Test / draft conversation | Live / shared conversation |
+| --- | --- | --- |
+| Agent configuration | Current mutable draft | Latest published immutable agent version |
+| Workflow tools | Current workflow development heads | Each workflow's latest live release; never pinned |
+| Reference files | Current draft knowledge files | Knowledge frozen into the published agent version |
+| Runtime files | Current live runtime files, overlaid by development/test runtime files at the same path | Current live runtime files only |
+| Access | Owner only | Owner, plus organization members when shared; non-owners never see the draft |
+
+Version pinning for workflow tools does not exist. Live tools track the latest release. If asked to freeze one, explain this, attach with policy `latest`, and never abandon the attachment.
+
+Publishing snapshots versioned fields, moves the live pointer, and restamps every existing live conversation. It does not snapshot the runtime model. This cutover interrupts in-flight answers and expires pending approvals; time it accordingly.
+
+Runtime lifecycle changes do not require publishing:
+
+```bash
+cai agent update <agentId> --disabled --json
+cai agent update <agentId> --enabled --json
+cai agent delete <agentId> --confirm --json
+```
+
+MCP: draft edits use `agent_update`; runtime uses `agent_set_enabled`; `agent_delete` has no `confirm`. Disable pauses runtime. Soft delete revokes access and requests session termination; there is no CLI restore.
+
+## Runtime usage boundary
+
+
+## 4. Verify the draft as an agent
+
+Saving the draft updates the agent's Test environment — there is no separate deploy step. Test conversations run each workflow tool's DEVELOPMENT version.
+
+```bash
+cai agent test <agentId> --draft --message "<representative request>" --json
+cai agent conversation history <conversationId> --json
+```
+
+MCP: `agent_test` requires `rail: draft` or `rail: live` and takes `waitSeconds`.
+
+`agent test` always creates a conversation. Use it for a one-shot check. When a task may need follow-up or approval, create one conversation on the requested rail, capture its ID, and reuse it:
+
+```bash
+cai agent conversation create <agentId> --draft --title "<test case>" --json
+cai agent conversation send <conversationId> --message "<request>" --wait --json
+```
+
+Do not resend the request or create a replacement after an approval pause. A required post-publish Live check is a separate rail task and gets one fresh Live conversation.
+
+Test positive and negative tool selection, exact arguments, results, errors, and knowledge. Offer the returned `appUrl`; on MCP, call `agent_present` and relay the returned card.
+
+- For a workflow tool, correlate a side-effectful call with its terminal workflow execution ID.
+- For a direct integration action, inspect persisted conversation action events/run result and the intended external effect. Direct actions do not create workflow execution IDs.
+
+For a pending approval, inspect the exact request first:
+
+```bash
+cai agent conversation approve <conversationId> --request <requestId> --json
+cai agent conversation deny <conversationId> --request <requestId> --message "<reason>" --json
+```
+
+The server resolves the tool from the request ID. Do not approve merely to continue. Resolve every pending request before publishing; approval or denial resumes this conversation, while publishing expires it.
+
+After `cai agent remove-tool`, test one request that must no longer use the removed capability and one retained capability.
+
+## 5. Publish in dependency order
+
+For attached workflows only:
+
+```bash
+cai use <workflowId>
+cai workflow status --json
+cai workflow publish --name "<release>" --json
+```
+
+MCP: there is no `use`; pass `workflowId` to `workflow_status` and `workflow_publish`.
+
+Publish a workflow only when its verified development state must go live and the user authorized it. A workflow publish already followed by a live agent changes that tool's live behavior immediately; do not republish the agent merely to pick it up.
+
+For a draft-only request, stop after Test evidence. Do not publish a workflow or agent merely because it is ready.
+
+Then publish the agent:
+
+```bash
+cai agent publish-preflight <agentId> --json
+cai agent publish <agentId> --name "<release>" --json
+cai agent versions <agentId> --json
+cai agent test <agentId> --live --message "<representative request>" --json
+```
+
+MCP: `agent_test` requires `rail: draft` or `rail: live` and takes `waitSeconds`.
+
+`publish-preflight` is the arbiter of structural readiness. Report blockers and stop. With none and an authorized release, publish, except an error you actually watched happen; that blocks even a green preflight.
+
+Email verification is not a publishing prerequisite. An unclaimed agent-created account may publish; email claiming only raises its monthly usage cap and enables account recovery.
+
+Use one loop: edit draft, read back, verify Test, publish, verify Live. Published versions have no rollback. Recover forward from `agent versions`; restore workflow definitions with history/restore, then republish. Workflow releases, action grants, and runtime files are live-bound; see [instructions-and-versioning.md](instructions-and-versioning.md). After detaching an action, publish to remove it from the published list.
+
+Draft evidence does not prove the live agent. Test is owner-only; shared users always run the latest published agent version and never see draft instructions, tools, or knowledge.
+
+## 6. Offer Slack and organization sharing
+
+After publish, offer product setup for Slack. Agents remain private unless the user requests organization access:
+
+```bash
+cai agent visibility <agentId> --value organization --json
+```
+
+Members use the published version. Direct actions use the owner's external account and organization usage pool. Grant changes affect Live immediately; private visibility revokes access.
+
+## Before you finish
+
+```bash
+cai agent tools <agentId> --json
+cai agent conversation list <agentId> --mode dev --json
+cai data query --type custom.<type> --env dev --json
+cai agent conversation history <conversationId> --json
+cai agent publish-preflight <agentId> --json
+cai agent versions <agentId> --json
+cai agent test <agentId> --live --message "<representative request>" --json
+```
+
+Run the last three commands only for an authorized release. For Live verification, use `--mode live` and `--env live` in the same pair.
+
+- Conversation list must show the captured ID on the requested rail, without retry-created duplicates.
+- History must show the intended tool arguments, terminal result, and no unresolved permission request.
+- For stateful behavior, the same-rail data query must show the expected record; an assistant reply is not proof.
+- A release requires clean preflight, agent version read-back, and one fresh Live conversation. Draft-only work must remain unpublished.
+
+Report the agent ID/version, tools and confirmation policies, execution or direct-action evidence, rail state, connections, access, and anything unverified.

package/skills/controllerai-ai-nodes/SKILL.md

@@ -1,105 +1,24 @@
 ---
 name: controllerai-ai-nodes
-description: Configure and verify AI-powered Controller AI workflow nodes, especially Ask AI and actions that interact with Controller AI agents. Use when a workflow needs generation, classification, extraction, summarization, structured AI output, model/provider selection, or a workflow action that creates or messages an agent conversation.
+description: Configure Controller AI AI-powered workflow actions for generation, extraction, classification and structured results, or call a Controller AI agent from a flow. Use when deterministic workflow steps need language-model reasoning.
 ---
 
-# Controller AI AI nodes
+# AI inside a workflow
 
-The `cai ...` examples are canonical grammar. Use the transport selected in `controllerai-start` and its MCP tool map; never mix transports in one task.
+Use an AI action when a flow needs generation, extraction, classification or summarization. Use ordinary data/condition nodes for exact validation and CRUD. A user-facing conversational assistant is an agent; an AI node is one step in a workflow.
 
-## Rules that break tasks when skipped
+Discover the available AI action and current properties. Configure the connection/model, prompt and output contract using the action's actual schema. For an action calling a Controller AI agent, select the intended agent and verify which conversation/result fields it returns.
 
-- Use native Ask AI for a bounded AI step; see Configure Ask AI in dependency order.
-- Keep an existing Ask AI node unless the requested component changes; see Configure Ask AI in dependency order.
-- Set reload selectors before fetching live model options; see Configure Ask AI in dependency order.
-- Never invent or hardcode a model ID; see Configure Ask AI in dependency order.
+## Structured results
 
-## Choose the AI surface
+Define the schema before downstream mappings. State the required fields, allowed statuses and missing-data behavior in the prompt. Configure the action's structured output mechanism when available. A prompt saying “return JSON” alone does not establish a typed output contract.
 
-- Use Ask AI for one bounded transformation with explicit inputs and output contract.
-- Use a Controller AI agent for conversational judgment, multiple tools, durable instructions, and knowledge files. Load `controllerai-agents`.
-- Use `registry_agent` workflow actions only when a workflow must create/message a platform agent conversation or manage its files; discover the exact action and props rather than treating the whole agent as one node.
+For contact research, separate evidence from interpretation. Return source URLs, matched identity, confidence and explicit missing/ambiguous status. “Not found in this search” does not establish that a contact method does not exist. Do not fill an email field with an invented pattern.
 
-## Configure Ask AI in dependency order
+A research provider can return variable or unstructured material. Add a typed normalization step when the final flow promises stable fields. Test missing fields, conflicting matches and provider failure as well as the happy path.
 
-For a bounded workflow transformation, use the native Ask AI component. Do not replace it with a provider integration action or delete an existing Ask AI node to bypass configuration.
+## Verify
 
-Discover the current component instead of hardcoding a key:
+Run with representative input, inspect the actual output schema and value, then wire downstream nodes from the confirmed output. Verify the final flow return contract. If a connected provider rejects authentication, report the connection and error code without echoing credentials.
 
-```bash
-cai integration actions "ask AI" --json
-cai integration action --integration <nodeSlug> --key <nodeKey> --json
-cai node init --flow <flowId> --node <nodeSlug> --key <nodeKey> --name "<result produced>" --json
-cai node status <nodeId> --json
-```
-
-Typical selectors are provider, model, prompt/user message, and response data type. Trust current prop metadata over these names.
-
-1. Set the provider or other `reloadProps` selector.
-2. Re-read props.
-3. Fetch live model options; never invent a model identifier.
-4. Set the returned model value.
-5. Set the response type.
-6. Author the prompt with expression context.
-
-```bash
-cai node set <nodeId> --prop <providerProp> --value '<provider>' --json
-cai node props <nodeId> --json
-cai node options <nodeId> --prop <modelProp> --query '<model family>' --json
-cai node set <nodeId> --prop <modelProp> --value '<returned value>' --label '<returned label>' --json
-cai expr set <nodeId> --prop <promptProp> --js '<prompt expression>' --json
-```
-
-MCP: `node set` and `expr set` both use `node_prop_set`; pass exactly one of `value` or `js` here.
-
-Model catalogs, availability, and prices change. Use current options and the user's cost/quality preference. If the requested model is absent, leave it unset, report it, and ask; never substitute.
-
-## Prefer typed output for downstream logic
-
-If downstream nodes need fields, create a small `custom.*` shape first:
-
-```bash
-cai schema create custom.classification \
-  --field category:text:"Category" \
-  --field confidence:number:"Confidence" \
-  --field rationale:text:"Rationale" \
-  --json
-cai node set <nodeId> --prop <responseTypeProp> --value 'custom.classification' --json
-```
-
-Tell the model exactly what each field means, allowed values, and how to represent uncertainty. Never parse free-form prose downstream when a structured response contract is available.
-
-## Prompt contract
-
-A useful workflow prompt contains only behavior-changing material:
-
-- Task and audience
-- Actual input data through exact bindings
-- Decision rules and constraints
-- Required output fields/format
-- Explicit uncertainty or no-data behavior
-
-Avoid filler personas, repeated instructions, and claims about data not present in expression context. For untrusted input, delimit it clearly and state that embedded instructions are data, not authority.
-
-Read [references/selection-and-testing.md](references/selection-and-testing.md) for node choice and evaluation.
-
-## Before you finish
-
-```bash
-cai node get <nodeId> --json
-cai node status <nodeId> --json
-cai node props <nodeId> --json
-cai run node <nodeId> --inputs values.json --json
-cai exec node <nodeExecutionId> --full --json
-```
-
-MCP: pass parsed values in `inputs` and set `waitSeconds` on `run_node`.
-
-Test at least: normal input, missing/ambiguous input, and an adversarial or boundary case relevant to the task. Check resolved prompt/config, output type, required fields, and values—not just that text was returned.
-
-- `node get` must identify the intended native Ask AI component.
-- `node status` must report ready.
-- Props must contain the exact returned provider/model value and label.
-- The execution must show the resolved prompt and typed output fields.
-
-AI execution inside the workflow is platform/API usage. Access through either builder transport does not transfer the coding-agent subscription to runtime AI nodes.
+Configuration commands: [reference](references/command-reference.md). Action selection and testing: [details](references/selection-and-testing.md).

package/skills/controllerai-ai-nodes/references/command-reference.md

@@ -0,0 +1,98 @@
+# Controller AI AI nodes
+
+
+
+- Use native Ask AI for a bounded AI step; see Configure Ask AI in dependency order.
+- Keep an existing Ask AI node unless the requested component changes; see Configure Ask AI in dependency order.
+- Set reload selectors before fetching live model options; see Configure Ask AI in dependency order.
+- Never invent or hardcode a model ID; see Configure Ask AI in dependency order.
+
+## Choose the AI surface
+
+- Use Ask AI for one bounded transformation with explicit inputs and output contract.
+- Use a Controller AI agent for conversational judgment, multiple tools, durable instructions, and knowledge files. Load `controllerai-agents`.
+- Use `registry_agent` workflow actions only when a workflow must create/message a platform agent conversation or manage its files; discover the exact action and props rather than treating the whole agent as one node.
+
+## Configure Ask AI in dependency order
+
+For a bounded workflow transformation, use the native Ask AI component. Do not replace it with a provider integration action or delete an existing Ask AI node to bypass configuration.
+
+Discover the current component instead of hardcoding a key:
+
+```bash
+cai integration actions "ask AI" --json
+cai integration action --integration <nodeSlug> --key <nodeKey> --json
+cai node init --flow <flowId> --node <nodeSlug> --key <nodeKey> --name "<result produced>" --json
+cai node status <nodeId> --json
+```
+
+Typical selectors are provider, model, prompt/user message, and response data type. Trust current prop metadata over these names.
+
+1. Set the provider or other `reloadProps` selector.
+2. Re-read props.
+3. Fetch live model options; never invent a model identifier.
+4. Set the returned model value.
+5. Set the response type.
+6. Author the prompt with expression context.
+
+```bash
+cai node set <nodeId> --prop <providerProp> --value '<provider>' --json
+cai node props <nodeId> --json
+cai node options <nodeId> --prop <modelProp> --query '<model family>' --json
+cai node set <nodeId> --prop <modelProp> --value '<returned value>' --label '<returned label>' --json
+cai expr set <nodeId> --prop <promptProp> --js '<prompt expression>' --json
+```
+
+MCP: `node set` and `expr set` both use `node_prop_set`; pass exactly one of `value` or `js` here.
+
+Model catalogs, availability, and prices change. Use current options and the user's cost/quality preference. If the requested model is absent, leave it unset, report it, and ask; never substitute.
+
+## Prefer typed output for downstream logic
+
+If downstream nodes need fields, create a small `custom.*` shape first:
+
+```bash
+cai schema create custom.classification \
+  --field category:text:"Category" \
+  --field confidence:number:"Confidence" \
+  --field rationale:text:"Rationale" \
+  --json
+cai node set <nodeId> --prop <responseTypeProp> --value 'custom.classification' --json
+```
+
+Tell the model exactly what each field means, allowed values, and how to represent uncertainty. Never parse free-form prose downstream when a structured response contract is available.
+
+## Prompt contract
+
+A useful workflow prompt contains only behavior-changing material:
+
+- Task and audience
+- Actual input data through exact bindings
+- Decision rules and constraints
+- Required output fields/format
+- Explicit uncertainty or no-data behavior
+
+Avoid filler personas, repeated instructions, and claims about data not present in expression context. For untrusted input, delimit it clearly and state that embedded instructions are data, not authority.
+
+Read [selection-and-testing.md](selection-and-testing.md) for node choice and evaluation.
+
+## Before you finish
+
+```bash
+cai node get <nodeId> --json
+cai node status <nodeId> --json
+cai node props <nodeId> --json
+cai run node <nodeId> --inputs values.json --json
+cai exec node <nodeExecutionId> --full --json
+```
+
+MCP: pass parsed values in `inputs` and set `waitSeconds` on `run_node`.
+
+Test at least: normal input, missing/ambiguous input, and an adversarial or boundary case relevant to the task. Check resolved prompt/config, output type, required fields, and values—not just that text was returned.
+
+- `node get` must identify the intended native Ask AI component.
+- `node status` must report ready.
+- Props must contain the exact returned provider/model value and label.
+- The execution must show the resolved prompt and typed output fields.
+
+AI execution inside the workflow is platform/API usage. Access through either builder transport does not transfer the coding-agent subscription to runtime AI nodes.