@lunnoa/client 2.3.0 → 2.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunnoa/client",
-  "version": "2.3.0",
+  "version": "2.5.0",
   "description": "TypeScript SDK for building applications on top of Lunnoa Automate — typed client for the Public API (agents, workflows, executions, entities, knowledge, queues), SSE agent chat streaming, and deployment-specific codegen",
   "type": "module",
   "main": "./dist/index.cjs",

package/skills/lunnoa-client/SKILL.md

@@ -354,6 +354,7 @@ import {
   defineAgent,
   defineTrigger,
   defineWorkflow,
+  ref,
 } from '@lunnoa/client';
 
 export const ping = defineWorkflow({
@@ -379,9 +380,22 @@ export const syncOrders = defineWorkflow({
   }),
   steps: [
     {
+      key: 'order',
       use: defineAction({
         id: 'http_action_send-request',
-        input: { method: 'GET', url: 'https://example.com/orders' },
+        input: {
+          method: 'GET',
+          url: `https://example.com/orders/${ref.trigger('invoiceId')}`,
+        },
+      }),
+    },
+    {
+      use: defineAction({
+        id: 'http_action_send-request',
+        input: {
+          method: 'GET',
+          url: `https://example.com/status/${ref.step('order', 'response', 'status')}`,
+        },
       }),
     },
   ],
@@ -417,6 +431,66 @@ One catalogue trigger per deployed workflow:
 - **Any other trigger:** `id` from `apps get`, optional `connection`, and
   `input` copied from that trigger's `inputConfig`. Do not invent ids.
 
+### Passing data between steps
+
+Wire step settings in code with `ref`. Do not leave them for the builder.
+
+- `ref.trigger('caseId')`: a trigger output field. On Manually Run that is
+  one of the `inputs` ids. On a webhook it is the request shape
+  (`ref.trigger('body', 'caseId')`).
+- `ref.step('load', 'rows', 0, 'status')`: an earlier step's output. Give
+  that step a `key: 'load'`. Array indexes are numbers.
+- A `ref` is a plain string. Use it as a whole value, inside a template
+  string, or inside nested settings (`args: { case_id: ref.trigger('caseId') }`).
+- On deploy the server swaps each `ref` for the real node id. The builder
+  shows it as a mapped field from that earlier node (top-level text fields
+  and lists; nested settings show the reference text). `runs.start` resolves
+  `ref.step` too, but it has no trigger, so `ref.trigger` fails there.
+- `defineWorkflow` throws, and deploy returns 400, for an unknown key, a
+  reference to the same or a later step, a duplicate key, or a Manually Run
+  field missing from `inputs`.
+- To find a step's output path, run it once (`actions.run` or
+  `runs.startAndWait`) and read that step's output in the execution.
+- Give every step another step reads from a `key`. Keyed steps keep their
+  node id across deploys, so run history and builder mappings stay attached.
+  The trigger keeps its id while its type and settings stay the same.
+
+### Branches (paths)
+
+Put `paths` on the **last** step of a list. Steps after the branch go inside
+each path. Paths do not merge back together.
+
+```ts
+const approval = defineAction({ id: 'flow-control_action_request-approval', input: { /* from tools get */ } });
+const split = defineAction({ id: 'flow-control_action_conditional-paths' });
+
+steps: [
+  { key: 'review', use: approval, paths: [
+    { label: 'Approved', steps: [{ key: 'apply', use: applyChange }] },
+    { label: 'Rejected', steps: [{ use: notify, input: { text: ref.step('review', 'comment') } }] },
+  ] },
+]
+
+// Conditional Paths: groups in `when` are OR-ed, conditions in a group AND-ed.
+{ key: 'route', use: split, paths: [
+  { label: 'Large', when: [[{ field: ref.step('load', 'amount'), condition: 'is_greater_than', value: '1000' }]], steps: [...] },
+  { label: 'Other', steps: [...] }, // no `when`: always taken
+] }
+```
+
+- `paths` works on Request Approval (at most two: approved first, then
+  rejected; labels `Approved` / `Rejected`), Conditional Paths (with `when`),
+  and Manually Decide Path (no `when`).
+- `when` conditions: `field` is exactly one `ref.trigger` / `ref.step`.
+  `condition` is one of `PATH_CONDITIONS` (equals, contains, is_empty,
+  is_true, is_greater_than, is_less_than, matches_regex, is_in_the_past, ...).
+  `value` is text; omit it for exists / is_empty / is_true style conditions.
+- Conditional Paths takes every path whose `when` matches. A path without
+  `when` always runs. For if/else, give the else path the opposite condition.
+- Steps on a path can `ref.step` the branching step and earlier steps on
+  the same path, not steps on another path.
+- `runs.start` rejects `paths`. Deploy, then execute the workflow.
+
 Discover the catalogue **before** writing `defineAction` (do not guess ids):
 
 ```bash
@@ -592,7 +666,7 @@ with emails (capped; not Azure object IDs).
 3. Call `discovery.enabledFeatures()` and hide unsupported areas.
 4. Build forms/tables from `attributeSchema` / `customInputConfig` (or the generated types).
 5. Render workflow progress from `executionPath`; handle `NEEDS_INPUT` with `submitInput`.
-6. For single-action calls, use `actions.run`; for linear multi-step, use `runs.start` / `defineWorkflow`. Deploy with `npx @lunnoa/client workflows|agents deploy`. Discover actions via `npx @lunnoa/client tools list|get|search` (or `workflowApps.list()`). Discover triggers via `apps get <appId> --json` and pass `defineTrigger` on `defineWorkflow` (omit it for Manually Run with no fields). `runs.start` does not save the trigger. Discover agent models via `npx @lunnoa/client ai-connections list --json` (or `aiConnections.list()`).
+6. For single-action calls, use `actions.run`; for linear multi-step, use `runs.start` / `defineWorkflow`. Deploy with `npx @lunnoa/client workflows|agents deploy`. Discover actions via `npx @lunnoa/client tools list|get|search` (or `workflowApps.list()`). Discover triggers via `apps get <appId> --json` and pass `defineTrigger` on `defineWorkflow` (omit it for Manually Run with no fields). `runs.start` does not save the trigger. Pass trigger inputs and earlier step outputs into step settings with `ref.trigger` / `ref.step` (key the source step). Branch with `paths` on Request Approval or Conditional Paths (last step only). Discover agent models via `npx @lunnoa/client ai-connections list --json` (or `aiConnections.list()`).
 7. For Request Approval nodes, use `approvals.inbox` / `approvals.decide` (or `executions.submitApproval`).
 8. Chat: stream via SSE, handle resume (reconnects) and stop, load history from the task.
 9. Handle `LunnoaApiError`: 401 → re-auth; 403 → hide the capability; 429 → back off.

package/skills/lunnoa-solution-design/SKILL.md

@@ -85,7 +85,8 @@ interrogation.
 |---|---|---|
 | One catalogue call | `actions.run` | One-step Execution (`source: SDK`) |
 | Linear multi-step, experiment | `runs.start` / `defineWorkflow` then run | One Execution; optional later deploy |
-| Reusable automation + triggers | Saved **Workflow** (`defineWorkflow` + `defineTrigger`, or the UI) | Discover trigger ids with `apps get <appId> --json`. Omit `trigger` for Manually Run with no fields. `runs.start` ignores the trigger. |
+| Reusable automation + triggers | Saved **Workflow** (`defineWorkflow` + `defineTrigger`, or the UI) | Discover trigger ids with `apps get <appId> --json`. Omit `trigger` for Manually Run with no fields. `runs.start` ignores the trigger. Wire step settings to trigger fields and earlier steps with `ref.trigger` / `ref.step`. |
+| Branches (approve / reject, if/else) | `defineWorkflow` with `paths` on Request Approval or Conditional Paths | Paths do not merge back. For steps shared after a branch, repeat them in each path or use the builder. A later code deploy replaces builder edits. |
 | Reasoning + tools + conversation | **Agent** | Tools = workflows, actions, knowledge |
 | Structured CRUD / portals | **Entities** + schemas | Codegen for typed accessors |
 | Reference / lookup data | **Tables** | `tables.upsertBySlug`; workflows use the Tables Lookup action |
@@ -126,6 +127,10 @@ interrogation.
    `deepseek-ai/DeepSeek-V4-Pro`). Client `defineAction` binds existing
    catalogue actions; toolkit `createAction` is a different product
    (in-platform apps).
+4b. **Every step input has a source.** In the brief, list each step's settings
+   as a fixed value, "from trigger `caseId`", or "from step `load` →
+   `rows.0.status`". The build uses `ref.trigger` / `ref.step` for these, so
+   "connect it in the builder" is not a fallback for data wiring.
 5. **Durable vs ephemeral:** experiments → `runs.start`; shared production
    automation → CLI `workflows deploy` / `agents deploy` by slug.
 6. **UI is headless.** `@lunnoa/client` has no design system. Optional React
@@ -146,6 +151,7 @@ interrogation.
 - Designing a local LangChain loop instead of Lunnoa-hosted agents
 - Hardcoding `model: 'gpt-4o'` without reading `ai-connections list`
 - Inventing a trigger id, or expecting `runs.start` to save a webhook or schedule
+- Leaving step inputs as "map it in the builder" when `ref.trigger` / `ref.step` covers it
 
 ---
 
@@ -174,7 +180,7 @@ can execute. Use this shape:
 ### Resources (every row says REUSED or CREATED)
 | Kind | Slug / id | Reused / created | Notes |
 |---|---|---|---|
-| Workflow | … | … | steps / trigger |
+| Workflow | … | … | steps (with keys) / trigger / each input's source |
 | Agent | … | … | model, tools |
 | Entity type | … | … | if portal CRUD |
 | Table | … | … | reference / lookup data |