@lunnoa/client 2.2.0 → 2.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunnoa/client",
-  "version": "2.2.0",
+  "version": "2.4.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

@@ -222,7 +222,8 @@ await lunnoa.tables.upsertBySlug({
 - A workflow's manual-trigger input fields live on
   `workflows.get(id, { expansion: ['triggerNode'] })` →
   `triggerNode.value.customInputConfig` (each field: `id`, `label`,
-  `inputType`, `required`, `selectOptions`).
+  `inputType`, `required`, `selectOptions`). Declare them at deploy time
+  with `defineTrigger({ id: 'flow-control_trigger_manual', inputs })`.
 - `workflowApps.list()` resolves `executionPath` step `appId`/`actionId`
   pairs to human-readable names and icons.
 
@@ -351,11 +352,14 @@ Pure typed config (no network):
 import {
   defineAction,
   defineAgent,
+  defineTrigger,
   defineWorkflow,
+  ref,
 } from '@lunnoa/client';
 
 export const ping = defineWorkflow({
   slug: 'ping',
+  // Omit trigger for Manually Run with no input fields.
   steps: [
     {
       use: defineAction({
@@ -366,6 +370,37 @@ export const ping = defineWorkflow({
   ],
 });
 
+export const syncOrders = defineWorkflow({
+  slug: 'sync-orders',
+  trigger: defineTrigger({
+    id: 'flow-control_trigger_manual',
+    inputs: [
+      { id: 'invoiceId', label: 'Invoice', inputType: 'text', required: true },
+    ],
+  }),
+  steps: [
+    {
+      key: 'order',
+      use: defineAction({
+        id: 'http_action_send-request',
+        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')}`,
+        },
+      }),
+    },
+  ],
+});
+
 export const triage = defineAgent({
   slug: 'support-triage',
   // models[].id from `npx @lunnoa/client ai-connections list --json`
@@ -375,25 +410,66 @@ export const triage = defineAgent({
 });
 ```
 
-Ad-hoc multi-step run (one Execution, `source: SDK`):
+Ad-hoc multi-step run (one Execution, `source: SDK`). `runs.start` sends
+steps only. A `trigger` on the definition is ignored. Deploy to persist it.
 
 ```typescript
 const result = await lunnoa.runs.start(ping);
 // or lunnoa.runs.startAndWait(ping)
 ```
 
+One catalogue trigger per deployed workflow:
+
+- **Manually Run** (`flow-control_trigger_manual`): `inputs` is the caller
+  form. It is stored as `customInputConfig`. `workflows.execute(id, { invoiceId })`
+  passes those keys.
+- **Listen for Webhook** (`flow-control_trigger_listen-for-webhook`):
+  `input: { method: 'POST' }` (`PUT` or `GET` too).
+- **Recurring Schedule** (`flow-control_trigger_recurring-schedule`): `input`
+  from the catalogue (`start`, `rrule`). A schedule that cannot compute its
+  next run fails the deploy.
+- **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.
+
 Discover the catalogue **before** writing `defineAction` (do not guess ids):
 
 ```bash
 npx @lunnoa/client tools list --json --for-agent
 npx @lunnoa/client tools search email --json --for-agent
 npx @lunnoa/client tools get http_action_send-request --json
+npx @lunnoa/client apps get flow-control --json
 npx @lunnoa/client connections list --app gmail --json
 npx @lunnoa/client ai-connections list --json
 ```
 
 `tools get` returns `inputConfig` / `inputFields` and a `defineAction` sketch.
-`tools list` is compact; use `get` for the schema. `--json` is for coding agents.
+`tools list` is compact; use `get` for the schema. `apps get --json` returns
+`triggers[]` with `triggerId`, `inputFields`, and a `defineTrigger` sketch.
+`--json` is for coding agents. Do not invent trigger ids.
 
 `ai-connections list` returns the AI connections this key can assign to an
 agent. Set `defineAgent({ model })` to a `models[].id` from that JSON
@@ -554,7 +630,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 catalogue via `npx @lunnoa/client tools list|get|search` (or `workflowApps.list()`). 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). 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** (UI or CLI deploy) | Schedules/webhooks live on workflows |
+| 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) | Builder in Lunnoa | Code deploys build straight lines only. 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 |
@@ -115,14 +116,21 @@ interrogation.
 3. **Connections stay on Lunnoa.** Definitions only reference connection ids
    (or omit for sole/default resolution). Never ask the partner to put OAuth
    secrets in their app.
-4. **Do not invent catalogue actions or model ids.** Discover actions with
+4. **Do not invent catalogue action, trigger, or model ids.** Discover actions with
    `npx @lunnoa/client tools list|get|search --json` (or `workflowApps.list()`
-   / codegen). Discover models with
+   / codegen). Discover triggers with `npx @lunnoa/client apps get <appId> --json`
+   and use `triggers[].triggerId` in `defineTrigger`. `input` is that trigger's
+   catalogue config. On Manually Run, `inputs` is the caller form
+   (`customInputConfig`). Discover models with
    `npx @lunnoa/client ai-connections list --json` and use a returned
    `models[].id` (Lunnoa LLMs uses catalogue ids such as
    `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
@@ -142,6 +150,8 @@ interrogation.
 - Using `@lunnoa/toolkit` to build a customer portal
 - 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
 
 ---
 
@@ -162,6 +172,7 @@ can execute. Use this shape:
 
 ### Discovery (run first)
 - [ ] `npx @lunnoa/client tools list --json --for-agent` then `tools get <id>`
+- [ ] `npx @lunnoa/client apps get <appId> --json` before `defineTrigger`
 - [ ] `npx @lunnoa/client ai-connections list --json` before choosing an agent model
 - [ ] agents / workflows / entity-types / tables list — reuse before create
 - [ ] codegen — if building typed entity/workflow accessors
@@ -169,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 |