@lunnoa/client 2.1.0 → 2.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunnoa/client",
-  "version": "2.1.0",
+  "version": "2.2.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
@@ -364,7 +368,8 @@ export const ping = defineWorkflow({
 
 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' })],
 });
@@ -384,11 +389,20 @@ 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 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.
 
+`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):
 
 ```bash
@@ -442,6 +456,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 +554,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 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()`).
 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

@@ -106,18 +106,28 @@ 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 actions 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 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 +135,13 @@ 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`
 
 ---
 
@@ -150,6 +162,7 @@ can execute. Use this shape:
 
 ### Discovery (run first)
 - [ ] `npx @lunnoa/client tools list --json --for-agent` then `tools get <id>`
+- [ ] `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