@lunnoa/client 2.1.0 → 2.3.0

package/package.json

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

@@ -58,11 +58,15 @@ Run these before inventing resources or shipping UI code:
 3. **Discover before inventing** — prefer the CLI (JSON for agents), then
    the SDK: `npx @lunnoa/client tools list --json --for-agent`,
    `tools get <actionId> --json`, `apps list`, `connections list`,
+   `ai-connections list --json`,
    `agents|workflows|entity-types|tables list`, `tables get <slugOrId>`,
    `features`.
    SDK equivalents: `workflowApps.list()`, `agents.list`, `workflows.list`,
-   `entityTypes.list`, `tables.list`, `discovery.enabledFeatures()`.
-   Do not invent catalogue action ids.
+   `entityTypes.list`, `tables.list`, `aiConnections.list()`,
+   `discovery.enabledFeatures()`.
+   Do not invent catalogue action ids or model ids. `connections list` is
+   app connections (Gmail, HTTP). `ai-connections list` is the model
+   provider connection and the `models[].id` values `defineAgent` accepts.
 4. **Run vs deploy** — Ad-hoc: `actions.run` / `runs.start` /
    `workflows.execute`. Durable shared automation: CLI
    `npx @lunnoa/client workflows|agents deploy`. Upsert is by slug
@@ -218,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.
 
@@ -347,11 +352,13 @@ Pure typed config (no network):
 import {
   defineAction,
   defineAgent,
+  defineTrigger,
   defineWorkflow,
 } from '@lunnoa/client';
 
 export const ping = defineWorkflow({
   slug: 'ping',
+  // Omit trigger for Manually Run with no input fields.
   steps: [
     {
       use: defineAction({
@@ -362,32 +369,77 @@ 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: [
+    {
+      use: defineAction({
+        id: 'http_action_send-request',
+        input: { method: 'GET', url: 'https://example.com/orders' },
+      }),
+    },
+  ],
+});
+
 export const triage = defineAgent({
   slug: 'support-triage',
-  model: 'gpt-4o',
+  // models[].id from `npx @lunnoa/client ai-connections list --json`
+  model: 'deepseek-ai/DeepSeek-V4-Pro',
   instructions: 'Triage mail. Be concise.',
   tools: [defineAction({ id: 'http_action_send-request' })],
 });
 ```
 
-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.
+
 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
+(on Lunnoa LLMs that is a catalogue id such as
+`deepseek-ai/DeepSeek-V4-Pro`). Omit `aiConnection` to
+use the connection with `isDefault: true`. Pass
+`defineAiConnection({ id })` only for a different connection. SDK:
+`lunnoa.aiConnections.list()`.
 
 Deploy to Automate UI (upsert by slug inside the workspace on the API key; prefer CLI):
 
@@ -442,6 +494,8 @@ for await (const chunk of stream) {
 }
 ```
 
+A turn from an app runs in **preview**: 10 model rounds, so the agent can call tools a few times and still send a final reply. The SDK sends `chatMode: 'preview'` for you. Do not pass `chatMode: 'builder'` from an app. That is the agent-editor interview: 4 rounds, and it stops a tool-using agent halfway. The workflow then fails with "Agent did not generate a response" even when a tool already saved the data. A workflow Message Agent step uses the same preview budget. For a job that chains many tool calls (read every record, then write a result), turn on **Long-horizon mode** on that agent in Lunnoa. That raises the budget to 50 rounds. `defineAgent` cannot set the switch, and a later deploy leaves it as you set it.
+
 - **React apps:** prefer `useAgentChat` from `@lunnoa/client/react`, which wraps AI SDK `useChat` + `DefaultChatTransport`
   pointed at
   `${baseUrl}/api/agents/${agentId}/tasks/${taskId}/stream-message` with an
@@ -538,7 +592,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()`).
+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()`).
 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,7 @@ 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. |
 | 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 |
@@ -106,18 +106,31 @@ interrogation.
 1. **Agents have no schedules or event triggers.** If something must run on a
    cron or webhook, use a **Workflow** that messages the agent (or runs
    actions). Do not invent an agent trigger.
-2. **Connections stay on Lunnoa.** Definitions only reference connection ids
+2. **A tool-using agent gets 10 model rounds per turn** from an app or a
+   Message Agent step. That covers a handful of tool calls plus a final reply.
+   If the job chains many calls (read every record, then write), the brief must
+   say to turn on **Long-horizon mode** for that agent in Lunnoa (50 rounds).
+   Do not plan around `chatMode: 'builder'`; that is the editor interview and
+   stops after 4 rounds.
+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.
-3. **Do not invent catalogue actions.** Discover 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). Client `defineAction` binds existing catalogue actions; toolkit
-   `createAction` is a different product (in-platform apps).
-4. **Durable vs ephemeral:** experiments → `runs.start`; shared production
+   / 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).
+5. **Durable vs ephemeral:** experiments → `runs.start`; shared production
    automation → CLI `workflows deploy` / `agents deploy` by slug.
-5. **UI is headless.** `@lunnoa/client` has no design system. Optional React
+6. **UI is headless.** `@lunnoa/client` has no design system. Optional React
    hooks in `@lunnoa/client/react`. Partners bring their own UI.
-6. **Reuse before create.** Before proposing any new entity type, table,
+7. **Reuse before create.** Before proposing any new entity type, table,
    workflow, or agent, run `npx @lunnoa/client entity-types list --json`,
    `tables list --json`, `workflows list --json`, and `agents list --json`.
    The build brief must state explicitly what is **reused** vs **created**.
@@ -125,11 +138,14 @@ interrogation.
 ### Common anti-patterns to reject
 
 - Putting an agent on a schedule without a workflow wrapper
+- Expecting an agent to loop tools indefinitely, or sending `chatMode: 'builder'` from an app (4 rounds, editor only)
 - Building a fake multi-step “batch” as many unrelated `actions.run` calls
   when the user wanted one Execution (use `runs.start` / workflow)
 - Shipping `lna_` to the browser “just for the demo”
 - 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
 
 ---
 
@@ -150,6 +166,8 @@ 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