@lunnoa/client 2.0.0 → 2.2.0

package/package.json

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

@@ -2,10 +2,10 @@
 name: lunnoa-client
 description: >-
   Builds custom frontends and backends on top of a Lunnoa Automate deployment
-  using the @lunnoa/client TypeScript SDK. Covers the two auth patterns
-  (server-side lna_ API keys via createServerClient, browser user JWTs via
-  createBrowserClient + lunnoa.auth.login / refresh / SSO — never lna_ keys in a
-  browser), discovery of the deployment's agents, workflows, and entity
+  using the @lunnoa/client TypeScript SDK. App login is always a Lunnoa user
+  (createBrowserClient + lunnoa.auth.login / refresh / SSO). lna_ API keys are
+  for the CLI only (discovery, codegen, deploy), never for the app session and
+  never in a browser. Covers discovery of the deployment's agents, workflows, and entity
   types, running the deployment codegen first for typed accessors, querying
   and creating entities, triggering workflows and polling executions,
   resuming NEEDS_INPUT executions from custom forms, streaming agent chat
@@ -49,19 +49,24 @@ Human docs (detail): Lunnoa Docs → Develop → TypeScript client SDK.
 
 Run these before inventing resources or shipping UI code:
 
-1. **Auth** — Pattern A (`createServerClient` + `lna_` on the server) or
-   Pattern B (`createBrowserClient` + JWT). **Never** put `lna_` in the
-   browser (SDK throws when `window` exists).
+1. **Auth** — Lunnoa user JWT via `createBrowserClient` + `lunnoa.auth.login`
+   (or SSO). **Never** call Lunnoa as the app's users with an `lna_` key, and
+   **never** put `lna_` in the browser (SDK throws when `window` exists).
+   `lna_` keys are for CLI discovery, codegen, and deploy only.
 2. **Codegen** — When building typed UIs, run
    `npx @lunnoa/client codegen` against the deployment first.
 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
@@ -70,36 +75,33 @@ Run these before inventing resources or shipping UI code:
 
 ---
 
-## 1. Auth: decide the pattern first
+## 1. Auth: Lunnoa users only
 
-| Pattern | Credential | Use when |
-|---|---|---|
-| **A. Backend holds the key** | `createServerClient({ apiKey: 'lna_...' })` | The app has its own users/login; Lunnoa never needs to know them. All Lunnoa calls go through the app's backend. |
-| **B. End users are Lunnoa users** | `createBrowserClient({ baseUrl })` + `lunnoa.auth.login` | Per-user permissions, agent shares, and task history must apply. The browser talks to Lunnoa directly. |
+Every person who uses the app is a Lunnoa user. If they are not in the
+workspace yet, they are provisioned there first (invite, SSO, or SCIM). The
+app does not keep its own user directory and does not call Lunnoa with an
+`lna_` key on their behalf.
+
+| Caller | Credential |
+|---|---|
+| **Person using the app** | `createBrowserClient({ baseUrl })` + `lunnoa.auth.login` (password, 2FA, or SSO). Permissions, agent shares, and task history are that user's. |
+| **CLI (codegen, discovery, deploy)** | `lna_` API key in `.env` / `--api-key`. Not the app session. |
 
 Hard rules:
 
 - **NEVER put an `lna_` key in browser code, env vars bundled into the client,
   or anything shipped to the browser.** The SDK throws if an `lna_` key is
   used while `window` exists. A leaked key exposes the whole workspace.
-- For browser apps with their own user base, use the **backend-for-frontend
-  pattern**: the browser calls your backend; your backend holds the key and
-  calls Lunnoa. Next.js route handlers / server actions count as backend.
-- Pattern B needs the deployment to allow the app's origin via
-  `CORS_ALLOWED_ORIGINS`.
-- Keys are minted by a SuperAdmin in **Adminspace → API keys** (workspace +
+- **NEVER build a backend-for-frontend that holds an `lna_` key so the app
+  can have its own users.** Next.js route handlers and server actions count
+  as the app: they must forward the signed-in user's JWT, not a service key.
+- The deployment must allow the app's origin via `CORS_ALLOWED_ORIGINS`.
+- CLI keys are minted by a SuperAdmin in **Adminspace → API keys** (workspace +
   RBAC role + optional expiry; secret shown once). Recommend a minimal custom
   role (e.g. `entities:read`, `entities:create`, `agents:use`), not Admin.
 
 ```typescript
-// Pattern A (server only)
-import { createServerClient } from '@lunnoa/client';
-const lunnoa = createServerClient({
-  baseUrl: process.env.LUNNOA_URL!,
-  apiKey: process.env.LUNNOA_API_KEY!,
-});
-
-// Pattern B (browser) — login + localStorage token store + auto-refresh on 401
+// App session — login + localStorage token store + auto-refresh on 401
 import { createBrowserClient, isLoginRequires2FA } from '@lunnoa/client';
 const lunnoa = createBrowserClient({ baseUrl });
 const result = await lunnoa.auth.login({ email, password });
@@ -150,7 +152,7 @@ const { data, setPage } = useEntityList({ objectTypeSlug: 'invoice' });
 
 Peer: `react` ≥ 18 for `/react`. `@ai-sdk/react` ships with the SDK (no extra install).
 Errors are `LunnoaApiError` with `.status`, `.body`, `.isUnauthorized`,
-`.isForbidden`, `.isRateLimited`. A 403 means the key's role or the
+`.isForbidden`, `.isRateLimited`. A 403 means the user's role or the
 deployment's licence edition does not cover the endpoint.
 
 ---
@@ -169,8 +171,9 @@ npx @lunnoa/client codegen --url <deployment-url> --api-key <lna_key> --out ./sr
 This emits `src/lunnoa/lunnoa.generated.ts` with `createDeploymentClient`:
 
 ```typescript
+import { createBrowserClient } from '@lunnoa/client';
 import { createDeploymentClient } from './lunnoa/lunnoa.generated';
-const lunnoa = createDeploymentClient(new LunnoaClient({ baseUrl, apiKey }));
+const lunnoa = createDeploymentClient(createBrowserClient({ baseUrl }));
 
 await lunnoa.entities.invoice.list({ state: 'pending' });      // typed attributes + states
 await lunnoa.workflows.processInvoice.execute({ invoiceId }); // typed trigger inputs
@@ -365,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' })],
 });
@@ -385,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
@@ -443,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
@@ -500,7 +515,7 @@ const { items: work } = await lunnoa.queueItems.listByObject(ticket.id);
 `lunnoa.approvals` mirrors Automate **Approvals** (`/approvals`). It uses the
 workspace API (`/api/approvals/...`), not Public API v1. The inbox is filtered
 to requests where the **current user** is eligible and has not decided yet.
-Prefer pattern B (user JWT). Role needs `approvals:read` / `approvals:decide`.
+The caller is the signed-in Lunnoa user. Role needs `approvals:read` / `approvals:decide`.
 
 ```typescript
 const { items } = await lunnoa.approvals.inbox(); // pending + partially_approved
@@ -531,14 +546,15 @@ with emails (capped; not Azure object IDs).
 
 ## 10. Ship checklist (after the mandatory checklist)
 
-1. Confirm base URL + credential pattern (A or B); wire the key server-side only.
-   For Pattern B prefer `createBrowserClient` and `lunnoa.auth.login` (not raw
-   localStorage getters unless you already hold a JWT).
+1. Confirm the base URL. Sign people in with `createBrowserClient` and
+   `lunnoa.auth.login` (not an `lna_` key, and not raw localStorage getters
+   unless you already hold that user's JWT). Allow the origin in
+   `CORS_ALLOWED_ORIGINS`.
 2. Run `npx @lunnoa/client codegen` against the deployment; commit the output.
 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

@@ -42,10 +42,11 @@ interrogation.
 
 ### Actors
 
-- Who uses the custom UI: Lunnoa employees (workspace users), external
-  customers (not Lunnoa users), or a backend system only?
-- That choice drives auth: JWT (Pattern B) vs API key BFF (Pattern A). Never
-  put `lna_` keys in a browser.
+- Who uses the custom UI? They sign in as Lunnoa users. If they are not in
+  the workspace yet, they are provisioned there first (invite, SSO, or SCIM).
+- The app does not keep its own login and does not call Lunnoa with an `lna_`
+  key on their behalf. `lna_` keys are for the CLI only. Never put one in a
+  browser.
 
 ### Data and knowledge
 
@@ -70,10 +71,10 @@ interrogation.
 
 ### Auth for any custom UI
 
-| End users | Prefer |
+| End users | Auth |
 |---|---|
-| App has its own login; Lunnoa is a backend | Pattern A: server holds `lna_` |
-| End users are Lunnoa users; per-user history/permissions | Pattern B: browser JWT |
+| People using the app | Lunnoa user JWT: `createBrowserClient` + `lunnoa.auth.login` (or SSO). Provision missing people with invite, SSO, or SCIM first. |
+| Coding agent / CLI | `LUNNOA_API_KEY` for discovery, codegen, and deploy. Not the app session. |
 | Anonymous embed chat (no full login) | Out of scope for v1 client path; scoped embed tokens are a later platform bet |
 
 ---
@@ -105,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**.
@@ -124,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`
 
 ---
 
@@ -149,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
 
@@ -192,7 +206,7 @@ continue in a coding turn with that skill loaded.
 **You ask:** Who chats (customers or staff)? Data source (entities vs ERP
 action)? Need approvals? Existing HTTP/CRM connections?
 
-**You conclude (example):** Pattern A BFF; Agent `order-status` with tools
+**You conclude (example):** Customers are Lunnoa users (SCIM or invite) and sign in with a browser JWT; Agent `order-status` with tools
 `defineAction` for ERP lookup (after `tools list` / `tools get`) + optional
 workflow for staff notifications; UI = chat only; no agent schedule.