@lunnoa/client 2.0.0 → 2.2.0

package/dist/index.d.cts

@@ -2,7 +2,7 @@ import { UIMessage, UIMessageChunk } from 'ai';
 export { UIMessage, UIMessageChunk } from 'ai';
 
 /**
- * Pluggable storage for Pattern B JWTs.
+ * Pluggable storage for Lunnoa user JWTs.
  * The SDK never uses httpOnly cookies: Automate auth is bearer JWT based.
  */
 interface TokenStore {
@@ -46,20 +46,20 @@ interface LunnoaClientOptions {
      */
     baseUrl: string;
     /**
-     * Server-side machine credential (`lna_...`). Never usable in browsers —
-     * the constructor throws if one is supplied while `window` exists.
+     * Machine credential (`lna_...`) for the CLI and operator scripts, not for app login.
+     * Never usable in browsers: the constructor throws if one is supplied while `window` exists.
      */
     apiKey?: string;
     /**
      * User JWT obtained from login / SSO. The supported credential for browser
      * applications. May be a function so refreshed tokens are picked up per request.
      *
-     * Prefer {@link tokenStore} for Pattern B so login/refresh can persist tokens
+     * Prefer {@link tokenStore} so login/refresh can persist tokens
      * and optionally auto-refresh on 401.
      */
     accessToken?: string | (() => string | Promise<string>);
     /**
-     * Optional JWT store for Pattern B. When set, authenticated requests read
+     * Optional JWT store for a signed-in Lunnoa user. When set, authenticated requests read
      * the access token from the store. Login / refresh helpers write back into it.
      */
     tokenStore?: TokenStore;
@@ -129,7 +129,10 @@ declare class HttpClient {
 
 type ChatMode = 'builder' | 'preview';
 interface StreamMessageOptions {
-    /** Agent chat mode; defaults to the server default (`builder`). */
+    /**
+     * Agent chat mode. Defaults to `preview` (10 model rounds, a normal agent run).
+     * `builder` is the agent-editor interview and stops after 4 rounds.
+     */
     chatMode?: ChatMode;
     /** Optional image attachment forwarded with this turn. */
     data?: {
@@ -1449,6 +1452,26 @@ interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/ai-connections": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * List AI connections available to the caller
+         * @description Returns AI provider connections the caller may assign to an agent, each with the catalogue model ids that connection accepts. Use `models[].id` as the agent `model`. `isDefault` marks the connection and model applied when a deploy omits them. App connections (Gmail, HTTP, and similar) are listed separately at `GET /api/connections`. Credentials are never returned. Requires `agents:create`.
+         */
+        get: operations["AiConnectionsController_list"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/connections": {
         parameters: {
             query?: never;
@@ -2406,7 +2429,7 @@ interface components {
             description?: string;
             /** @description System instructions / prompt for the agent. */
             instructions: string;
-            /** @description Selected model id on the AI provider connection (e.g. `gpt-4o`). */
+            /** @description Catalogue model id enabled on the AI connection. Example: `deepseek-ai/DeepSeek-V4-Pro`. Discover ids with GET /api/ai-connections. */
             model: string;
             /** @description AiProviderConnection UUID. When omitted, platform AI defaults apply. */
             aiConnectionId?: string;
@@ -3543,6 +3566,32 @@ interface components {
             /** Format: date-time */
             updatedAt: string;
         };
+        PublicAiModelResponseDto: {
+            /** @description Catalogue model id passed to agent deploy as `model`. Example: `deepseek-ai/DeepSeek-V4-Pro`. */
+            id: string;
+            /** @description Display name. */
+            name: string;
+            /** @description True when this is the model used if an agent deploy omits `model` on this connection. */
+            isDefault: boolean;
+            /** @description Whether the model can call tools. */
+            supportsTools: boolean;
+            /** @description Whether the model accepts image input. */
+            supportsVision: boolean;
+            /** @description Whether the model exposes a reasoning mode. */
+            supportsReasoning: boolean;
+        };
+        PublicAiConnectionResponseDto: {
+            /** @description AiProviderConnection UUID. Pass as `aiConnectionId` / `defineAiConnection({ id })` when this connection is not the default. */
+            id: string;
+            /** @description Connection display name. Example: `Lunnoa LLMs`. */
+            name: string;
+            /** @description Provider slug. Example: `featherless` or `openai`. */
+            provider: string;
+            /** @description True for the connection used when an agent deploy omits `aiConnectionId`. */
+            isDefault: boolean;
+            /** @description Models this connection accepts. Inactive models are omitted. */
+            models: components["schemas"]["PublicAiModelResponseDto"][];
+        };
         ConnectionWorkspaceDto: {
             /** @description Workspace ID. */
             id: string;
@@ -5477,7 +5526,7 @@ interface operations {
             query?: {
                 /** @description Comma-separated inclusion flags. Available: all, internal. Pass internal to include executions of internal workflows, which are excluded by default. */
                 includeType?: string;
-                /** @description Comma-separated key:value filters. Available: projectId, workflowId, source (WORKFLOW|SDK), objectId. Example: filterBy=workflowId:wf_123 or filterBy=objectId:<uuid> */
+                /** @description Comma-separated key:value filters. Available: workflowId, source (WORKFLOW|SDK), objectId. Example: filterBy=workflowId:wf_123 or filterBy=objectId:<uuid> */
                 filterBy?: string;
                 /** @description Comma-separated fields to expand. Available: createdAt, updatedAt, startedAt, stoppedAt, executionNumber, nodes, edges, status, statusMessage, continueExecutionAt, workflow, project, workspace, output, orientation, executionVariables, source, name. The executionPath expansion is only honoured on GET /executions/{executionId}. Example: expansion=status,startedAt,workflow,source */
                 expansion?: string;
@@ -5812,6 +5861,26 @@ interface operations {
             };
         };
     };
+    AiConnectionsController_list: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description AI connections and the models each one accepts. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["PublicAiConnectionResponseDto"][];
+                };
+            };
+        };
+    };
     ConnectionsController_findAllForWorkspace: {
         parameters: {
             query?: {
@@ -6597,7 +6666,10 @@ interface AgentDefinition {
     slug: string;
     name?: string;
     description?: string;
-    /** Selected model id on the AI provider connection. */
+    /**
+     * Catalogue model id from `ai-connections list` (`models[].id`).
+     * Example on Lunnoa LLMs: `deepseek-ai/DeepSeek-V4-Pro`.
+     */
     model: string;
     instructions: string;
     aiConnection?: AiConnectionDefinition;
@@ -6721,7 +6793,7 @@ interface CurrentUser {
 }
 
 /**
- * Login, refresh, SSO discovery, and session helpers for Pattern B.
+ * Login, refresh, SSO discovery, and session helpers for Lunnoa users.
  *
  * Password login, token exchange, refresh, and SSO provider listing are
  * **public** endpoints (no Bearer). `me()` requires a user JWT.
@@ -6810,6 +6882,36 @@ declare class SsoAuthResource {
     getLoginUrl(providerId: string): string;
 }
 
+interface AiConnectionModel {
+    /** Catalogue id for `defineAgent({ model })`. */
+    id: string;
+    name: string;
+    isDefault: boolean;
+    supportsTools: boolean;
+    supportsVision: boolean;
+    supportsReasoning: boolean;
+}
+interface AiConnection {
+    /** AiProviderConnection UUID for `defineAiConnection({ id })`. */
+    id: string;
+    name: string;
+    /** Provider slug, for example `featherless` or `openai`. */
+    provider: string;
+    /** True when agent deploy uses this connection if `aiConnection` is omitted. */
+    isDefault: boolean;
+    models: AiConnectionModel[];
+}
+declare class AiConnectionsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Lists AI connections the caller can assign to an agent, with the model
+     * ids each connection accepts. Credentials are never included.
+     * Requires `agents:create` (the same permission as agent deploy).
+     */
+    list(): Promise<AiConnection[]>;
+}
+
 declare class ConnectionsResource {
     private readonly http;
     constructor(http: HttpClient);
@@ -7379,28 +7481,21 @@ declare class WorkflowsResource {
 /**
  * Typed client for the Lunnoa Automate Public API.
  *
- * Server-side (Pattern A — the backend holds the key):
- * ```ts
- * const lunnoa = new LunnoaClient({
- *   baseUrl: 'https://lunnoa.acme.example',
- *   apiKey: process.env.LUNNOA_API_KEY, // lna_...
- * });
- * ```
- *
- * Browser (Pattern B — the end user is a Lunnoa user):
+ * Apps sign people in as Lunnoa users:
  * ```ts
  * import { createBrowserClient } from '@lunnoa/client';
  * const lunnoa = createBrowserClient({ baseUrl: 'https://lunnoa.acme.example' });
  * await lunnoa.auth.login({ email, password });
  * ```
  *
- * Passing an `lna_` API key in a browser throws immediately: API keys are
- * workspace-wide server credentials and must never ship to browsers.
+ * `apiKey` (`lna_...`) is for the CLI and operator scripts (codegen, discovery,
+ * deploy). It is not an app login. Passing one while `window` exists throws:
+ * a leaked key acts as that service account across its whole workspace.
  */
 declare class LunnoaClient {
     /** The underlying HTTP layer, exposed for advanced/escape-hatch requests. */
     readonly http: HttpClient;
-    /** Login, refresh, SSO discovery, and session helpers (Pattern B). */
+    /** Login, refresh, SSO discovery, and session helpers for Lunnoa users. */
     readonly auth: AuthResource;
     readonly agents: AgentsResource;
     readonly tasks: TasksResource;
@@ -7427,6 +7522,8 @@ declare class LunnoaClient {
     readonly variables: VariablesResource;
     readonly scorecards: ScorecardsResource;
     readonly connections: ConnectionsResource;
+    /** AI provider connections and the model ids each one accepts. */
+    readonly aiConnections: AiConnectionsResource;
     readonly workflowApps: WorkflowAppsResource;
     readonly discovery: DiscoveryResource;
     constructor(options: LunnoaClientOptions);
@@ -7463,11 +7560,10 @@ declare const API_KEY_PREFIX = "lna_";
 /** Returns true when running inside a browser (or browser-like) environment. */
 declare function isBrowserEnvironment(): boolean;
 /**
- * API keys are server-to-server credentials. Shipping one to a browser exposes
- * the whole workspace the key is scoped to, so the SDK refuses outright.
+ * API keys are operator credentials (CLI, codegen, deploy). Shipping one to a
+ * browser exposes the whole workspace the key is scoped to, so the SDK refuses.
  *
- * Browser apps must authenticate end users with a Lunnoa user JWT (Pattern B)
- * or proxy through their own backend which holds the key (Pattern A / BFF).
+ * Apps authenticate end users with a Lunnoa user JWT.
  */
 declare function assertApiKeyAllowedInEnvironment(apiKey: string): void;
 
@@ -7540,7 +7636,7 @@ interface CreateBrowserClientOptions {
     headers?: Record<string, string>;
 }
 /**
- * Pattern B helper: browser (or isomorphic) client with JWT storage,
+ * Browser (or isomorphic) client with JWT storage,
  * `lunnoa.auth.login` / refresh, and optional auto-refresh on 401.
  *
  * Never pass an `lna_` API key here.
@@ -7550,13 +7646,13 @@ interface CreateServerClientOptions {
     /** Base URL of the Lunnoa Automate deployment. */
     baseUrl: string;
     /**
-     * Workspace API key (`lna_...`). Preferred for Pattern A backends / BFFs.
+     * Workspace API key (`lna_...`) for operator scripts and the CLI.
+     * Not an app login: people using an app authenticate as Lunnoa users.
      * Mutually exclusive with `accessToken` / `tokenStore`.
      */
     apiKey?: string;
     /**
-     * User JWT (or getter) when the server acts on behalf of a logged-in user.
-     * Prefer this over embedding tokens in the browser when you own the session.
+     * User JWT (or getter) when the server already holds a signed-in Lunnoa user's token.
      */
     accessToken?: string | (() => string | Promise<string>);
     /** Optional store when the server holds both access and refresh tokens. */
@@ -7566,11 +7662,10 @@ interface CreateServerClientOptions {
     headers?: Record<string, string>;
 }
 /**
- * Pattern A (or server-side Pattern B) helper for Node / BFF / route handlers.
- *
- * Provide `apiKey` for a service account, or `accessToken` / `tokenStore` for a
- * user JWT held on the server. Throws if used with an API key in a browser.
+ * Node helper for a Lunnoa user JWT held on the server, or an `lna_` key for
+ * operator scripts. App login uses {@link createBrowserClient}. Throws if
+ * used with an API key in a browser.
  */
 declare function createServerClient(options: CreateServerClientOptions): LunnoaClient;
 
-export { API_KEY_PREFIX, type ActionDefinition, ActionsResource, type AddQueueItemErrorInput, type Agent, AgentChatClient, AgentChatStream, type AgentDefinition, type AgentToolDefinition, AgentsResource, type AiConnectionDefinition, type ApprovalInboxItem, ApprovalsResource, AuthResource, type AuthTokens, type BulkCreateQueueItemsInput, type BulkCreateQueueItemsResult, type ChangeEntityStateInput, type ChangeEntityStateResult, type ChatMode, type Connection, type ConnectionDefinition, ConnectionsResource, type CreateBrowserClientOptions, type CreateEntityInput, type CreateKnowledgeInput, type CreateQueueInput, type CreateQueueItemInput, type CreateServerClientOptions, type CreateTaskInput, type CreateVariableInput, type CurrentUser, DEFINE_KINDS, type DefineKind, type DeletedTask, DiscoveryResource, type EligibleApprover, type EnabledFeatures, EntitiesResource, type Entity, type EntityStateHistoryEntry, type EntityStateTransitions, type EntityType, type EntityTypeDefinition, type EntityTypeReadOptions, EntityTypesResource, type ExecuteWorkflowResult, type Execution, type ExecutionPathStep, type ExecutionProgress, type ExecutionProgressPayload, type ExecutionProgressStep, ExecutionProgressStream, type ExecutionStatus, type ExecutionStreamEvent, type ExecutionStreamEventType, ExecutionTimeoutError, ExecutionsResource, type ExportEntitiesInput, type FetchLike, HttpClient, type ImportEntitiesInput, type ImportEntitiesResult, type ImportTemplate, type Knowledge, type KnowledgeDocument, type KnowledgeDocumentGroup, KnowledgeResource, type ListEntitiesOptions, type ListQueryOptions, type ListQueueItemsByObjectOptions, type ListQueueItemsOptions, type LocalStorageTokenStoreOptions, type LoginRequires2FA, type LoginResult, type LoginSuccess, LunnoaApiError, LunnoaClient, type LunnoaClientOptions, type MessageTaskInput, type OffsetPagination, type PagePagination, type PaginatedEntities, type PendingInput, type PendingInputField, type QueryValue, type Queue, type QueueAllowedObjectType, type QueueItem, type QueueItemCreated, type QueueItemErrorEntry, type QueueItemFull, type QueueItemList, type QueueItemObjectSummary, type QueueItemStats, type QueueItemStatus, QueueItemsResource, type QueueStats, QueuesResource, type RecordMeasureValueInput, type RequestOptions, type RunActionInput, type RunActionOptions, type RunActionResult, RunsResource, type SaveUploadedTextInput, type Scorecard, type ScorecardMeasure, type ScorecardMeasureStatus, type ScorecardMeasureValue, type ScorecardObjective, type ScorecardSummary, ScorecardsResource, type SseEvent, SsoAuthResource, type SsoProviderSummary, type SsoProvidersResponse, type StartRunInput, type StartRunInputDto, type StartRunOptions, type StartRunStep, type StopStreamOptions, type StreamMessageOptions, type Table, TablesResource, type Task, type TaskListItem, TasksResource, type TokenStore, type UpdateEntityInput, type UpdateKnowledgeInput, type UpdateQueueInput, type UpdateQueueItemInput, type UpdateTaskInput, type UpdateVariableInput, type UpsertAgentBySlugInput, type UpsertAgentBySlugInputDto, type UpsertAgentToolInput, type UpsertEntityTypeBySlugInput, type UpsertTableBySlugInput, type UpsertWorkflowBySlugInput, type UpsertWorkflowBySlugInputDto, type UpsertWorkflowStepInput, type Variable, VariablesResource, type WaitUntilFinishedOptions, type WatchProgressOptions, type Workflow, type WorkflowApp, WorkflowAppsResource, type WorkflowDefinition, type WorkflowStepDefinition, WorkflowsResource, assertApiKeyAllowedInEnvironment, type components, createBrowserClient, createLocalStorageTokenStore, createMemoryTokenStore, createServerClient, defineAction, defineAgent, defineAiConnection, defineConnection, defineEntityType, defineWorkflow, entityTypeDefinitionToUpsert, isBrowserEnvironment, isLoginRequires2FA, iterateOffset, iteratePages, type operations, parseSseEvents, parseSseStream, type paths, resolveActionAppId, resolveActionId };
+export { API_KEY_PREFIX, type ActionDefinition, ActionsResource, type AddQueueItemErrorInput, type Agent, AgentChatClient, AgentChatStream, type AgentDefinition, type AgentToolDefinition, AgentsResource, type AiConnection, type AiConnectionDefinition, type AiConnectionModel, AiConnectionsResource, type ApprovalInboxItem, ApprovalsResource, AuthResource, type AuthTokens, type BulkCreateQueueItemsInput, type BulkCreateQueueItemsResult, type ChangeEntityStateInput, type ChangeEntityStateResult, type ChatMode, type Connection, type ConnectionDefinition, ConnectionsResource, type CreateBrowserClientOptions, type CreateEntityInput, type CreateKnowledgeInput, type CreateQueueInput, type CreateQueueItemInput, type CreateServerClientOptions, type CreateTaskInput, type CreateVariableInput, type CurrentUser, DEFINE_KINDS, type DefineKind, type DeletedTask, DiscoveryResource, type EligibleApprover, type EnabledFeatures, EntitiesResource, type Entity, type EntityStateHistoryEntry, type EntityStateTransitions, type EntityType, type EntityTypeDefinition, type EntityTypeReadOptions, EntityTypesResource, type ExecuteWorkflowResult, type Execution, type ExecutionPathStep, type ExecutionProgress, type ExecutionProgressPayload, type ExecutionProgressStep, ExecutionProgressStream, type ExecutionStatus, type ExecutionStreamEvent, type ExecutionStreamEventType, ExecutionTimeoutError, ExecutionsResource, type ExportEntitiesInput, type FetchLike, HttpClient, type ImportEntitiesInput, type ImportEntitiesResult, type ImportTemplate, type Knowledge, type KnowledgeDocument, type KnowledgeDocumentGroup, KnowledgeResource, type ListEntitiesOptions, type ListQueryOptions, type ListQueueItemsByObjectOptions, type ListQueueItemsOptions, type LocalStorageTokenStoreOptions, type LoginRequires2FA, type LoginResult, type LoginSuccess, LunnoaApiError, LunnoaClient, type LunnoaClientOptions, type MessageTaskInput, type OffsetPagination, type PagePagination, type PaginatedEntities, type PendingInput, type PendingInputField, type QueryValue, type Queue, type QueueAllowedObjectType, type QueueItem, type QueueItemCreated, type QueueItemErrorEntry, type QueueItemFull, type QueueItemList, type QueueItemObjectSummary, type QueueItemStats, type QueueItemStatus, QueueItemsResource, type QueueStats, QueuesResource, type RecordMeasureValueInput, type RequestOptions, type RunActionInput, type RunActionOptions, type RunActionResult, RunsResource, type SaveUploadedTextInput, type Scorecard, type ScorecardMeasure, type ScorecardMeasureStatus, type ScorecardMeasureValue, type ScorecardObjective, type ScorecardSummary, ScorecardsResource, type SseEvent, SsoAuthResource, type SsoProviderSummary, type SsoProvidersResponse, type StartRunInput, type StartRunInputDto, type StartRunOptions, type StartRunStep, type StopStreamOptions, type StreamMessageOptions, type Table, TablesResource, type Task, type TaskListItem, TasksResource, type TokenStore, type UpdateEntityInput, type UpdateKnowledgeInput, type UpdateQueueInput, type UpdateQueueItemInput, type UpdateTaskInput, type UpdateVariableInput, type UpsertAgentBySlugInput, type UpsertAgentBySlugInputDto, type UpsertAgentToolInput, type UpsertEntityTypeBySlugInput, type UpsertTableBySlugInput, type UpsertWorkflowBySlugInput, type UpsertWorkflowBySlugInputDto, type UpsertWorkflowStepInput, type Variable, VariablesResource, type WaitUntilFinishedOptions, type WatchProgressOptions, type Workflow, type WorkflowApp, WorkflowAppsResource, type WorkflowDefinition, type WorkflowStepDefinition, WorkflowsResource, assertApiKeyAllowedInEnvironment, type components, createBrowserClient, createLocalStorageTokenStore, createMemoryTokenStore, createServerClient, defineAction, defineAgent, defineAiConnection, defineConnection, defineEntityType, defineWorkflow, entityTypeDefinitionToUpsert, isBrowserEnvironment, isLoginRequires2FA, iterateOffset, iteratePages, type operations, parseSseEvents, parseSseStream, type paths, resolveActionAppId, resolveActionId };

package/dist/index.d.ts

@@ -2,7 +2,7 @@ import { UIMessage, UIMessageChunk } from 'ai';
 export { UIMessage, UIMessageChunk } from 'ai';
 
 /**
- * Pluggable storage for Pattern B JWTs.
+ * Pluggable storage for Lunnoa user JWTs.
  * The SDK never uses httpOnly cookies: Automate auth is bearer JWT based.
  */
 interface TokenStore {
@@ -46,20 +46,20 @@ interface LunnoaClientOptions {
      */
     baseUrl: string;
     /**
-     * Server-side machine credential (`lna_...`). Never usable in browsers —
-     * the constructor throws if one is supplied while `window` exists.
+     * Machine credential (`lna_...`) for the CLI and operator scripts, not for app login.
+     * Never usable in browsers: the constructor throws if one is supplied while `window` exists.
      */
     apiKey?: string;
     /**
      * User JWT obtained from login / SSO. The supported credential for browser
      * applications. May be a function so refreshed tokens are picked up per request.
      *
-     * Prefer {@link tokenStore} for Pattern B so login/refresh can persist tokens
+     * Prefer {@link tokenStore} so login/refresh can persist tokens
      * and optionally auto-refresh on 401.
      */
     accessToken?: string | (() => string | Promise<string>);
     /**
-     * Optional JWT store for Pattern B. When set, authenticated requests read
+     * Optional JWT store for a signed-in Lunnoa user. When set, authenticated requests read
      * the access token from the store. Login / refresh helpers write back into it.
      */
     tokenStore?: TokenStore;
@@ -129,7 +129,10 @@ declare class HttpClient {
 
 type ChatMode = 'builder' | 'preview';
 interface StreamMessageOptions {
-    /** Agent chat mode; defaults to the server default (`builder`). */
+    /**
+     * Agent chat mode. Defaults to `preview` (10 model rounds, a normal agent run).
+     * `builder` is the agent-editor interview and stops after 4 rounds.
+     */
     chatMode?: ChatMode;
     /** Optional image attachment forwarded with this turn. */
     data?: {
@@ -1449,6 +1452,26 @@ interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/ai-connections": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * List AI connections available to the caller
+         * @description Returns AI provider connections the caller may assign to an agent, each with the catalogue model ids that connection accepts. Use `models[].id` as the agent `model`. `isDefault` marks the connection and model applied when a deploy omits them. App connections (Gmail, HTTP, and similar) are listed separately at `GET /api/connections`. Credentials are never returned. Requires `agents:create`.
+         */
+        get: operations["AiConnectionsController_list"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/connections": {
         parameters: {
             query?: never;
@@ -2406,7 +2429,7 @@ interface components {
             description?: string;
             /** @description System instructions / prompt for the agent. */
             instructions: string;
-            /** @description Selected model id on the AI provider connection (e.g. `gpt-4o`). */
+            /** @description Catalogue model id enabled on the AI connection. Example: `deepseek-ai/DeepSeek-V4-Pro`. Discover ids with GET /api/ai-connections. */
             model: string;
             /** @description AiProviderConnection UUID. When omitted, platform AI defaults apply. */
             aiConnectionId?: string;
@@ -3543,6 +3566,32 @@ interface components {
             /** Format: date-time */
             updatedAt: string;
         };
+        PublicAiModelResponseDto: {
+            /** @description Catalogue model id passed to agent deploy as `model`. Example: `deepseek-ai/DeepSeek-V4-Pro`. */
+            id: string;
+            /** @description Display name. */
+            name: string;
+            /** @description True when this is the model used if an agent deploy omits `model` on this connection. */
+            isDefault: boolean;
+            /** @description Whether the model can call tools. */
+            supportsTools: boolean;
+            /** @description Whether the model accepts image input. */
+            supportsVision: boolean;
+            /** @description Whether the model exposes a reasoning mode. */
+            supportsReasoning: boolean;
+        };
+        PublicAiConnectionResponseDto: {
+            /** @description AiProviderConnection UUID. Pass as `aiConnectionId` / `defineAiConnection({ id })` when this connection is not the default. */
+            id: string;
+            /** @description Connection display name. Example: `Lunnoa LLMs`. */
+            name: string;
+            /** @description Provider slug. Example: `featherless` or `openai`. */
+            provider: string;
+            /** @description True for the connection used when an agent deploy omits `aiConnectionId`. */
+            isDefault: boolean;
+            /** @description Models this connection accepts. Inactive models are omitted. */
+            models: components["schemas"]["PublicAiModelResponseDto"][];
+        };
         ConnectionWorkspaceDto: {
             /** @description Workspace ID. */
             id: string;
@@ -5477,7 +5526,7 @@ interface operations {
             query?: {
                 /** @description Comma-separated inclusion flags. Available: all, internal. Pass internal to include executions of internal workflows, which are excluded by default. */
                 includeType?: string;
-                /** @description Comma-separated key:value filters. Available: projectId, workflowId, source (WORKFLOW|SDK), objectId. Example: filterBy=workflowId:wf_123 or filterBy=objectId:<uuid> */
+                /** @description Comma-separated key:value filters. Available: workflowId, source (WORKFLOW|SDK), objectId. Example: filterBy=workflowId:wf_123 or filterBy=objectId:<uuid> */
                 filterBy?: string;
                 /** @description Comma-separated fields to expand. Available: createdAt, updatedAt, startedAt, stoppedAt, executionNumber, nodes, edges, status, statusMessage, continueExecutionAt, workflow, project, workspace, output, orientation, executionVariables, source, name. The executionPath expansion is only honoured on GET /executions/{executionId}. Example: expansion=status,startedAt,workflow,source */
                 expansion?: string;
@@ -5812,6 +5861,26 @@ interface operations {
             };
         };
     };
+    AiConnectionsController_list: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description AI connections and the models each one accepts. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["PublicAiConnectionResponseDto"][];
+                };
+            };
+        };
+    };
     ConnectionsController_findAllForWorkspace: {
         parameters: {
             query?: {
@@ -6597,7 +6666,10 @@ interface AgentDefinition {
     slug: string;
     name?: string;
     description?: string;
-    /** Selected model id on the AI provider connection. */
+    /**
+     * Catalogue model id from `ai-connections list` (`models[].id`).
+     * Example on Lunnoa LLMs: `deepseek-ai/DeepSeek-V4-Pro`.
+     */
     model: string;
     instructions: string;
     aiConnection?: AiConnectionDefinition;
@@ -6721,7 +6793,7 @@ interface CurrentUser {
 }
 
 /**
- * Login, refresh, SSO discovery, and session helpers for Pattern B.
+ * Login, refresh, SSO discovery, and session helpers for Lunnoa users.
  *
  * Password login, token exchange, refresh, and SSO provider listing are
  * **public** endpoints (no Bearer). `me()` requires a user JWT.
@@ -6810,6 +6882,36 @@ declare class SsoAuthResource {
     getLoginUrl(providerId: string): string;
 }
 
+interface AiConnectionModel {
+    /** Catalogue id for `defineAgent({ model })`. */
+    id: string;
+    name: string;
+    isDefault: boolean;
+    supportsTools: boolean;
+    supportsVision: boolean;
+    supportsReasoning: boolean;
+}
+interface AiConnection {
+    /** AiProviderConnection UUID for `defineAiConnection({ id })`. */
+    id: string;
+    name: string;
+    /** Provider slug, for example `featherless` or `openai`. */
+    provider: string;
+    /** True when agent deploy uses this connection if `aiConnection` is omitted. */
+    isDefault: boolean;
+    models: AiConnectionModel[];
+}
+declare class AiConnectionsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Lists AI connections the caller can assign to an agent, with the model
+     * ids each connection accepts. Credentials are never included.
+     * Requires `agents:create` (the same permission as agent deploy).
+     */
+    list(): Promise<AiConnection[]>;
+}
+
 declare class ConnectionsResource {
     private readonly http;
     constructor(http: HttpClient);
@@ -7379,28 +7481,21 @@ declare class WorkflowsResource {
 /**
  * Typed client for the Lunnoa Automate Public API.
  *
- * Server-side (Pattern A — the backend holds the key):
- * ```ts
- * const lunnoa = new LunnoaClient({
- *   baseUrl: 'https://lunnoa.acme.example',
- *   apiKey: process.env.LUNNOA_API_KEY, // lna_...
- * });
- * ```
- *
- * Browser (Pattern B — the end user is a Lunnoa user):
+ * Apps sign people in as Lunnoa users:
  * ```ts
  * import { createBrowserClient } from '@lunnoa/client';
  * const lunnoa = createBrowserClient({ baseUrl: 'https://lunnoa.acme.example' });
  * await lunnoa.auth.login({ email, password });
  * ```
  *
- * Passing an `lna_` API key in a browser throws immediately: API keys are
- * workspace-wide server credentials and must never ship to browsers.
+ * `apiKey` (`lna_...`) is for the CLI and operator scripts (codegen, discovery,
+ * deploy). It is not an app login. Passing one while `window` exists throws:
+ * a leaked key acts as that service account across its whole workspace.
  */
 declare class LunnoaClient {
     /** The underlying HTTP layer, exposed for advanced/escape-hatch requests. */
     readonly http: HttpClient;
-    /** Login, refresh, SSO discovery, and session helpers (Pattern B). */
+    /** Login, refresh, SSO discovery, and session helpers for Lunnoa users. */
     readonly auth: AuthResource;
     readonly agents: AgentsResource;
     readonly tasks: TasksResource;
@@ -7427,6 +7522,8 @@ declare class LunnoaClient {
     readonly variables: VariablesResource;
     readonly scorecards: ScorecardsResource;
     readonly connections: ConnectionsResource;
+    /** AI provider connections and the model ids each one accepts. */
+    readonly aiConnections: AiConnectionsResource;
     readonly workflowApps: WorkflowAppsResource;
     readonly discovery: DiscoveryResource;
     constructor(options: LunnoaClientOptions);
@@ -7463,11 +7560,10 @@ declare const API_KEY_PREFIX = "lna_";
 /** Returns true when running inside a browser (or browser-like) environment. */
 declare function isBrowserEnvironment(): boolean;
 /**
- * API keys are server-to-server credentials. Shipping one to a browser exposes
- * the whole workspace the key is scoped to, so the SDK refuses outright.
+ * API keys are operator credentials (CLI, codegen, deploy). Shipping one to a
+ * browser exposes the whole workspace the key is scoped to, so the SDK refuses.
  *
- * Browser apps must authenticate end users with a Lunnoa user JWT (Pattern B)
- * or proxy through their own backend which holds the key (Pattern A / BFF).
+ * Apps authenticate end users with a Lunnoa user JWT.
  */
 declare function assertApiKeyAllowedInEnvironment(apiKey: string): void;
 
@@ -7540,7 +7636,7 @@ interface CreateBrowserClientOptions {
     headers?: Record<string, string>;
 }
 /**
- * Pattern B helper: browser (or isomorphic) client with JWT storage,
+ * Browser (or isomorphic) client with JWT storage,
  * `lunnoa.auth.login` / refresh, and optional auto-refresh on 401.
  *
  * Never pass an `lna_` API key here.
@@ -7550,13 +7646,13 @@ interface CreateServerClientOptions {
     /** Base URL of the Lunnoa Automate deployment. */
     baseUrl: string;
     /**
-     * Workspace API key (`lna_...`). Preferred for Pattern A backends / BFFs.
+     * Workspace API key (`lna_...`) for operator scripts and the CLI.
+     * Not an app login: people using an app authenticate as Lunnoa users.
      * Mutually exclusive with `accessToken` / `tokenStore`.
      */
     apiKey?: string;
     /**
-     * User JWT (or getter) when the server acts on behalf of a logged-in user.
-     * Prefer this over embedding tokens in the browser when you own the session.
+     * User JWT (or getter) when the server already holds a signed-in Lunnoa user's token.
      */
     accessToken?: string | (() => string | Promise<string>);
     /** Optional store when the server holds both access and refresh tokens. */
@@ -7566,11 +7662,10 @@ interface CreateServerClientOptions {
     headers?: Record<string, string>;
 }
 /**
- * Pattern A (or server-side Pattern B) helper for Node / BFF / route handlers.
- *
- * Provide `apiKey` for a service account, or `accessToken` / `tokenStore` for a
- * user JWT held on the server. Throws if used with an API key in a browser.
+ * Node helper for a Lunnoa user JWT held on the server, or an `lna_` key for
+ * operator scripts. App login uses {@link createBrowserClient}. Throws if
+ * used with an API key in a browser.
  */
 declare function createServerClient(options: CreateServerClientOptions): LunnoaClient;
 
-export { API_KEY_PREFIX, type ActionDefinition, ActionsResource, type AddQueueItemErrorInput, type Agent, AgentChatClient, AgentChatStream, type AgentDefinition, type AgentToolDefinition, AgentsResource, type AiConnectionDefinition, type ApprovalInboxItem, ApprovalsResource, AuthResource, type AuthTokens, type BulkCreateQueueItemsInput, type BulkCreateQueueItemsResult, type ChangeEntityStateInput, type ChangeEntityStateResult, type ChatMode, type Connection, type ConnectionDefinition, ConnectionsResource, type CreateBrowserClientOptions, type CreateEntityInput, type CreateKnowledgeInput, type CreateQueueInput, type CreateQueueItemInput, type CreateServerClientOptions, type CreateTaskInput, type CreateVariableInput, type CurrentUser, DEFINE_KINDS, type DefineKind, type DeletedTask, DiscoveryResource, type EligibleApprover, type EnabledFeatures, EntitiesResource, type Entity, type EntityStateHistoryEntry, type EntityStateTransitions, type EntityType, type EntityTypeDefinition, type EntityTypeReadOptions, EntityTypesResource, type ExecuteWorkflowResult, type Execution, type ExecutionPathStep, type ExecutionProgress, type ExecutionProgressPayload, type ExecutionProgressStep, ExecutionProgressStream, type ExecutionStatus, type ExecutionStreamEvent, type ExecutionStreamEventType, ExecutionTimeoutError, ExecutionsResource, type ExportEntitiesInput, type FetchLike, HttpClient, type ImportEntitiesInput, type ImportEntitiesResult, type ImportTemplate, type Knowledge, type KnowledgeDocument, type KnowledgeDocumentGroup, KnowledgeResource, type ListEntitiesOptions, type ListQueryOptions, type ListQueueItemsByObjectOptions, type ListQueueItemsOptions, type LocalStorageTokenStoreOptions, type LoginRequires2FA, type LoginResult, type LoginSuccess, LunnoaApiError, LunnoaClient, type LunnoaClientOptions, type MessageTaskInput, type OffsetPagination, type PagePagination, type PaginatedEntities, type PendingInput, type PendingInputField, type QueryValue, type Queue, type QueueAllowedObjectType, type QueueItem, type QueueItemCreated, type QueueItemErrorEntry, type QueueItemFull, type QueueItemList, type QueueItemObjectSummary, type QueueItemStats, type QueueItemStatus, QueueItemsResource, type QueueStats, QueuesResource, type RecordMeasureValueInput, type RequestOptions, type RunActionInput, type RunActionOptions, type RunActionResult, RunsResource, type SaveUploadedTextInput, type Scorecard, type ScorecardMeasure, type ScorecardMeasureStatus, type ScorecardMeasureValue, type ScorecardObjective, type ScorecardSummary, ScorecardsResource, type SseEvent, SsoAuthResource, type SsoProviderSummary, type SsoProvidersResponse, type StartRunInput, type StartRunInputDto, type StartRunOptions, type StartRunStep, type StopStreamOptions, type StreamMessageOptions, type Table, TablesResource, type Task, type TaskListItem, TasksResource, type TokenStore, type UpdateEntityInput, type UpdateKnowledgeInput, type UpdateQueueInput, type UpdateQueueItemInput, type UpdateTaskInput, type UpdateVariableInput, type UpsertAgentBySlugInput, type UpsertAgentBySlugInputDto, type UpsertAgentToolInput, type UpsertEntityTypeBySlugInput, type UpsertTableBySlugInput, type UpsertWorkflowBySlugInput, type UpsertWorkflowBySlugInputDto, type UpsertWorkflowStepInput, type Variable, VariablesResource, type WaitUntilFinishedOptions, type WatchProgressOptions, type Workflow, type WorkflowApp, WorkflowAppsResource, type WorkflowDefinition, type WorkflowStepDefinition, WorkflowsResource, assertApiKeyAllowedInEnvironment, type components, createBrowserClient, createLocalStorageTokenStore, createMemoryTokenStore, createServerClient, defineAction, defineAgent, defineAiConnection, defineConnection, defineEntityType, defineWorkflow, entityTypeDefinitionToUpsert, isBrowserEnvironment, isLoginRequires2FA, iterateOffset, iteratePages, type operations, parseSseEvents, parseSseStream, type paths, resolveActionAppId, resolveActionId };
+export { API_KEY_PREFIX, type ActionDefinition, ActionsResource, type AddQueueItemErrorInput, type Agent, AgentChatClient, AgentChatStream, type AgentDefinition, type AgentToolDefinition, AgentsResource, type AiConnection, type AiConnectionDefinition, type AiConnectionModel, AiConnectionsResource, type ApprovalInboxItem, ApprovalsResource, AuthResource, type AuthTokens, type BulkCreateQueueItemsInput, type BulkCreateQueueItemsResult, type ChangeEntityStateInput, type ChangeEntityStateResult, type ChatMode, type Connection, type ConnectionDefinition, ConnectionsResource, type CreateBrowserClientOptions, type CreateEntityInput, type CreateKnowledgeInput, type CreateQueueInput, type CreateQueueItemInput, type CreateServerClientOptions, type CreateTaskInput, type CreateVariableInput, type CurrentUser, DEFINE_KINDS, type DefineKind, type DeletedTask, DiscoveryResource, type EligibleApprover, type EnabledFeatures, EntitiesResource, type Entity, type EntityStateHistoryEntry, type EntityStateTransitions, type EntityType, type EntityTypeDefinition, type EntityTypeReadOptions, EntityTypesResource, type ExecuteWorkflowResult, type Execution, type ExecutionPathStep, type ExecutionProgress, type ExecutionProgressPayload, type ExecutionProgressStep, ExecutionProgressStream, type ExecutionStatus, type ExecutionStreamEvent, type ExecutionStreamEventType, ExecutionTimeoutError, ExecutionsResource, type ExportEntitiesInput, type FetchLike, HttpClient, type ImportEntitiesInput, type ImportEntitiesResult, type ImportTemplate, type Knowledge, type KnowledgeDocument, type KnowledgeDocumentGroup, KnowledgeResource, type ListEntitiesOptions, type ListQueryOptions, type ListQueueItemsByObjectOptions, type ListQueueItemsOptions, type LocalStorageTokenStoreOptions, type LoginRequires2FA, type LoginResult, type LoginSuccess, LunnoaApiError, LunnoaClient, type LunnoaClientOptions, type MessageTaskInput, type OffsetPagination, type PagePagination, type PaginatedEntities, type PendingInput, type PendingInputField, type QueryValue, type Queue, type QueueAllowedObjectType, type QueueItem, type QueueItemCreated, type QueueItemErrorEntry, type QueueItemFull, type QueueItemList, type QueueItemObjectSummary, type QueueItemStats, type QueueItemStatus, QueueItemsResource, type QueueStats, QueuesResource, type RecordMeasureValueInput, type RequestOptions, type RunActionInput, type RunActionOptions, type RunActionResult, RunsResource, type SaveUploadedTextInput, type Scorecard, type ScorecardMeasure, type ScorecardMeasureStatus, type ScorecardMeasureValue, type ScorecardObjective, type ScorecardSummary, ScorecardsResource, type SseEvent, SsoAuthResource, type SsoProviderSummary, type SsoProvidersResponse, type StartRunInput, type StartRunInputDto, type StartRunOptions, type StartRunStep, type StopStreamOptions, type StreamMessageOptions, type Table, TablesResource, type Task, type TaskListItem, TasksResource, type TokenStore, type UpdateEntityInput, type UpdateKnowledgeInput, type UpdateQueueInput, type UpdateQueueItemInput, type UpdateTaskInput, type UpdateVariableInput, type UpsertAgentBySlugInput, type UpsertAgentBySlugInputDto, type UpsertAgentToolInput, type UpsertEntityTypeBySlugInput, type UpsertTableBySlugInput, type UpsertWorkflowBySlugInput, type UpsertWorkflowBySlugInputDto, type UpsertWorkflowStepInput, type Variable, VariablesResource, type WaitUntilFinishedOptions, type WatchProgressOptions, type Workflow, type WorkflowApp, WorkflowAppsResource, type WorkflowDefinition, type WorkflowStepDefinition, WorkflowsResource, assertApiKeyAllowedInEnvironment, type components, createBrowserClient, createLocalStorageTokenStore, createMemoryTokenStore, createServerClient, defineAction, defineAgent, defineAiConnection, defineConnection, defineEntityType, defineWorkflow, entityTypeDefinitionToUpsert, isBrowserEnvironment, isLoginRequires2FA, iterateOffset, iteratePages, type operations, parseSseEvents, parseSseStream, type paths, resolveActionAppId, resolveActionId };