@lunnoa/client 0.0.0-development

package/dist/react.d.cts

@@ -0,0 +1,3533 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { UIMessage, UIMessageChunk } from 'ai';
+
+/**
+ * Pluggable storage for Pattern B JWTs.
+ * The SDK never uses httpOnly cookies: Automate auth is bearer JWT based.
+ */
+interface TokenStore {
+    getAccessToken(): string | null | Promise<string | null>;
+    getRefreshToken(): string | null | Promise<string | null>;
+    setTokens(tokens: {
+        accessToken: string;
+        refreshToken?: string;
+    }): void | Promise<void>;
+    clear(): void | Promise<void>;
+}
+
+type FetchLike = (input: string | URL, init?: RequestInit) => Promise<Response>;
+interface LunnoaClientOptions {
+    /**
+     * Base URL of the Lunnoa Automate deployment, e.g. `https://lunnoa.acme.example`.
+     * Paths are appended under `/api/*`.
+     */
+    baseUrl: string;
+    /**
+     * Server-side machine credential (`lna_...`). 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
+     * and optionally auto-refresh on 401.
+     */
+    accessToken?: string | (() => string | Promise<string>);
+    /**
+     * Optional JWT store for Pattern B. When set, authenticated requests read
+     * the access token from the store. Login / refresh helpers write back into it.
+     */
+    tokenStore?: TokenStore;
+    /**
+     * When true (default if `tokenStore` is set), a 401 triggers one
+     * `POST /api/auth/refresh-token` attempt using the stored refresh token,
+     * then retries the original request.
+     */
+    autoRefresh?: boolean;
+    /** Custom fetch implementation (testing, polyfills, interceptors). */
+    fetch?: FetchLike;
+    /** Extra headers sent with every request. */
+    headers?: Record<string, string>;
+}
+type QueryValue = string | number | boolean | undefined | null;
+interface RequestOptions {
+    query?: Record<string, QueryValue>;
+    body?: unknown;
+    signal?: AbortSignal;
+    headers?: Record<string, string>;
+    /**
+     * Return the raw Response instead of parsing JSON. Used by the streaming
+     * module and endpoints that may legitimately return 204.
+     */
+    raw?: boolean;
+    /**
+     * Skip the Authorization header. Used for public auth endpoints
+     * (login, refresh, SSO providers).
+     */
+    skipAuth?: boolean;
+    /** Internal: set after an auto-refresh retry so we do not loop. */
+    _retriedAfterRefresh?: boolean;
+}
+/**
+ * Minimal typed HTTP layer shared by every resource namespace. Handles auth
+ * header resolution, query serialisation, JSON parsing, and error mapping.
+ */
+declare class HttpClient {
+    readonly baseUrl: string;
+    readonly tokenStore?: TokenStore;
+    /** Underlying fetch (shared with AI SDK transports when needed). */
+    readonly fetch: FetchLike;
+    private readonly apiKey?;
+    private readonly accessToken?;
+    private readonly autoRefresh;
+    private readonly defaultHeaders;
+    private refreshInFlight;
+    constructor(options: LunnoaClientOptions);
+    resolveAuthHeader(): Promise<string>;
+    buildUrl(path: string, query?: Record<string, QueryValue>): string;
+    request<T>(method: string, path: string, options: RequestOptions & {
+        raw: true;
+    }): Promise<Response>;
+    request<T>(method: string, path: string, options?: RequestOptions): Promise<T>;
+    get<T>(path: string, options?: RequestOptions): Promise<T>;
+    post<T>(path: string, options?: RequestOptions): Promise<T>;
+    patch<T>(path: string, options?: RequestOptions): Promise<T>;
+    put<T>(path: string, options?: RequestOptions): Promise<T>;
+    delete<T>(path: string, options?: RequestOptions): Promise<T>;
+    /**
+     * Single-flight refresh using the token store. Returns false when refresh
+     * is impossible or fails (store is cleared on failure).
+     */
+    tryRefreshAccessToken(): Promise<boolean>;
+    private performRefresh;
+}
+
+type ChatMode = 'builder' | 'preview';
+interface StreamMessageOptions {
+    /** Agent chat mode; defaults to the server default (`builder`). */
+    chatMode?: ChatMode;
+    /** Abort the stream (closes the HTTP connection; the run keeps going server-side — call `stop` to cancel it). */
+    signal?: AbortSignal;
+}
+interface StopStreamOptions {
+    /**
+     * Partial assistant message (AI SDK UIMessage) received so far; the server
+     * persists it so the partial turn is not lost.
+     */
+    assistantMessage?: UIMessage;
+}
+/**
+ * An in-flight agent chat turn, exposed as an async iterable of AI SDK
+ * `UIMessageChunk`s (`text-delta`, `tool-*`, `finish`, ...).
+ *
+ * ```ts
+ * const stream = await client.agentChat.streamMessage(agentId, taskId, message);
+ * for await (const chunk of stream) {
+ *   if (chunk.type === 'text-delta') process.stdout.write(chunk.delta);
+ * }
+ * ```
+ *
+ * Use {@link AgentChatStream.toUIMessageStream} with the AI SDK's
+ * `readUIMessageStream` to consume assembled `UIMessage` snapshots instead of
+ * raw chunks.
+ */
+declare class AgentChatStream implements AsyncIterable<UIMessageChunk> {
+    private readonly response;
+    private readonly options?;
+    /**
+     * Server run id of this turn (`X-Task-Run-Id` response header), when
+     * provided. Useful for diagnostics.
+     */
+    readonly runId: string | null;
+    private consumed;
+    constructor(response: Response, options?: {
+        signal?: AbortSignal;
+    } | undefined);
+    [Symbol.asyncIterator](): AsyncGenerator<UIMessageChunk, void, undefined>;
+    chunks(): AsyncGenerator<UIMessageChunk, void, undefined>;
+    /**
+     * The same chunks as a web `ReadableStream`, ready for the AI SDK's
+     * `readUIMessageStream({ stream })` to assemble into `UIMessage` snapshots.
+     */
+    toUIMessageStream(): ReadableStream<UIMessageChunk>;
+    /** Collects the full text of the turn (concatenated `text-delta` chunks). */
+    text(): Promise<string>;
+}
+/**
+ * Hand-written client for the Agent Runtime SSE endpoints
+ * (`POST/GET /api/agents/:agentId/tasks/:taskId/stream-message` and `/stop`).
+ * Code generators handle SSE poorly, so this module wraps the wire protocol
+ * the bundled UI uses (AI SDK UIMessage chunks, SSE-framed, resumable).
+ */
+declare class AgentChatClient {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Sends a user message to an agent task and streams the assistant turn.
+     * Creates the task row when `taskId` does not exist yet (client-generated
+     * UUIDs are supported, mirroring the bundled UI).
+     *
+     * `message` may be a plain string (wrapped into a UIMessage) or a full AI
+     * SDK `UIMessage`.
+     */
+    streamMessage(agentId: string, taskId: string, message: string | UIMessage, options?: StreamMessageOptions): Promise<AgentChatStream>;
+    /**
+     * Reattaches to an in-flight agent turn after a disconnect (the resumable
+     * stream replays from the beginning of the turn). Returns `null` when
+     * there is no active stream to resume (server responds 204).
+     */
+    resumeStream(agentId: string, taskId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<AgentChatStream | null>;
+    /**
+     * Requests cancellation of the active agent turn for a task. Idempotent:
+     * succeeds even when no stream is active. Optionally persists the partial
+     * assistant message received so far.
+     */
+    stop(agentId: string, taskId: string, options?: StopStreamOptions): Promise<{
+        ok: boolean;
+    }>;
+}
+
+interface components {
+    schemas: {
+        AuthMethodFlagsDto: {
+            /** @description True when password-based login is disabled for this deployment (via AUTH_DISABLED_METHODS). */
+            passwordDisabled: boolean;
+            /** @description True when Google sign-in is disabled for this deployment (via AUTH_DISABLED_METHODS). */
+            googleDisabled: boolean;
+        };
+        EnabledFeaturesResponseDto: {
+            /** @description Whether the Workflows feature is enabled. Always enabled. */
+            WORKFLOWS: boolean;
+            /** @description Whether the Agents feature is enabled. */
+            AGENTS: boolean;
+            /** @description Whether the Connections feature is enabled. Always enabled. */
+            CONNECTIONS: boolean;
+            /** @description Whether the Variables feature is enabled. Always enabled. */
+            VARIABLES: boolean;
+            /** @description Whether the Knowledge feature is enabled. Requires storage (S3 or database-configured storage) and a vector database. */
+            KNOWLEDGE: boolean;
+            /** @description Whether email sending is enabled. Requires an active email configuration. */
+            EMAILS: boolean;
+            /** @description Whether web search is enabled. Requires a Serper API key. */
+            WEB_SEARCH: boolean;
+            /** @description Whether dynamic web content extraction is enabled. Requires an Apify configuration. */
+            WEB_EXTRACTION_DYNAMIC: boolean;
+            /** @description Whether static web content extraction is enabled. Requires an Apify configuration. */
+            WEB_EXTRACTION_STATIC: boolean;
+            /** @description Whether the phone calling feature is enabled. Requires a VAPI API key. */
+            CALLING: boolean;
+            /** @description Whether the Teams feature is enabled. Always enabled. */
+            TEAMS: boolean;
+            /** @description Whether the Skills feature is enabled. */
+            SKILLS: boolean;
+            /** @description Whether the hexagonal agent builder canvas UI is enabled. */
+            AGENT_BUILDER_CANVAS: boolean;
+            /** @description Whether isolated code execution for agents is enabled. */
+            CODE_EXECUTION: boolean;
+            /** @description Whether SSO (OIDC) login is enabled. Requires at least one enabled SSO provider. */
+            SSO: boolean;
+            /** @description Whether SCIM provisioning is configured. True when at least one active (non-revoked) SCIM bearer token exists. */
+            SCIM: boolean;
+            /** @description Availability of authentication methods for this deployment. */
+            AUTH_METHODS: components["schemas"]["AuthMethodFlagsDto"];
+        };
+        CreateProjectDto: {
+            /** @description Name of the project. */
+            name: string;
+            /** @description Description of the project. */
+            description?: string;
+        };
+        ProjectCountDto: {
+            /** @description Number of agents in the project. */
+            agents?: number;
+            /** @description Number of variables in the project. */
+            variables?: number;
+            /** @description Number of workflows in the project. */
+            workflows?: number;
+        };
+        ProjectCreatedByUserDto: {
+            /** @description User ID. */
+            id: string;
+            /** @description User email address. */
+            email: string;
+            /** @description User display name. */
+            name: string;
+        };
+        ProjectCreatedByWorkspaceUserDto: {
+            /** @description Workspace user ID. */
+            id: string;
+            /** @description The underlying user. */
+            user: components["schemas"]["ProjectCreatedByUserDto"];
+        };
+        ProjectWorkflowSummaryDto: {
+            /** @description Workflow ID. */
+            id: string;
+            /** @description Workflow name. */
+            name: string;
+        };
+        ProjectResponseDto: {
+            /** @description Project ID. */
+            id: string;
+            /** @description Project name. */
+            name: string;
+            /** @description Project description. Included when `expansion=description` is requested. */
+            description?: string;
+            /**
+             * Format: date-time
+             * @description Creation timestamp. Included when `expansion=createdAt` is requested.
+             */
+            createdAt?: string;
+            /**
+             * Format: date-time
+             * @description Last update timestamp. Included when `expansion=updatedAt` is requested.
+             */
+            updatedAt?: string;
+            /** @description Aggregate counts. Included when `expansion=countAgents` is requested; countVariables and countWorkflows add their respective counts. */
+            _count?: components["schemas"]["ProjectCountDto"];
+            /** @description Workspace user who created the project. Included when `expansion=createdByWorkspaceUser` is requested. */
+            createdByWorkspaceUser?: components["schemas"]["ProjectCreatedByWorkspaceUserDto"];
+            /** @description Workflows in the project. Included when `expansion=workflows` is requested. */
+            workflows?: components["schemas"]["ProjectWorkflowSummaryDto"][];
+        };
+        CreateQueueDto: {
+            /** @description Human-readable name for the queue. */
+            name: string;
+            /** @description Description of what the queue is used for. */
+            description?: string;
+            /** @description Maximum number of retry attempts per item. Defaults to 3. */
+            maxRetries?: number;
+            /** @description Delay in minutes before a failed item becomes eligible for retry. Defaults to 60. */
+            retryDelayMinutes?: number;
+            /** @description Number of items fetched per processing batch. Defaults to 10. */
+            batchSize?: number;
+            /** @description Default priority for items in this queue. Higher values are processed first. Defaults to 0. */
+            priority?: number;
+        };
+        QueueProjectSummaryDto: {
+            /** @description Project ID. */
+            id: string;
+            /** @description Project name. */
+            name: string;
+        };
+        QueueWorkspaceSummaryDto: {
+            /** @description Workspace ID. */
+            id: string;
+            /** @description Workspace name. */
+            name: string;
+        };
+        QueueCreatedByUserSummaryDto: {
+            /** @description User ID. */
+            id: string;
+            /** @description User email address. */
+            email: string;
+            /** @description User display name. */
+            name: string;
+        };
+        QueueCreatedByWorkspaceUserDto: {
+            /** @description Workspace user ID. */
+            id: string;
+            /** @description User account behind the workspace user. */
+            user: components["schemas"]["QueueCreatedByUserSummaryDto"];
+        };
+        QueueItemCountsDto: {
+            /** @description Number of items in the queue. */
+            items: number;
+        };
+        QueueResponseDto: {
+            /** @description Queue ID. */
+            id: string;
+            /** @description Queue name. */
+            name: string;
+            /** @description Whether the queue is active. Inactive queues do not accept processing. */
+            isActive: boolean;
+            /** @description Default priority for items in this queue. */
+            priority: number;
+            /** @description Maximum number of retry attempts per item. Not included in list responses. */
+            maxRetries?: number;
+            /** @description Delay in minutes before a failed item becomes eligible for retry. Not included in list responses. */
+            retryDelayMinutes?: number;
+            /** @description Number of items fetched per processing batch. Not included in list responses. */
+            batchSize?: number;
+            /** @description Queue description. Included when `expansion=description` is requested. */
+            description?: string | null;
+            /**
+             * Format: date-time
+             * @description Creation timestamp. Included when `expansion=createdAt` is requested.
+             */
+            createdAt?: string;
+            /**
+             * Format: date-time
+             * @description Last update timestamp. Included when `expansion=updatedAt` is requested.
+             */
+            updatedAt?: string;
+            /** @description Total number of items. Included when `expansion=statistics` is requested. */
+            totalItems?: number;
+            /** @description Number of pending items. Included when `expansion=statistics` is requested. */
+            pendingItems?: number;
+            /** @description Number of items being processed. Included when `expansion=statistics` is requested. */
+            processingItems?: number;
+            /** @description Number of successfully processed items. Included when `expansion=statistics` is requested. */
+            successItems?: number;
+            /** @description Number of failed items. Included when `expansion=statistics` is requested. */
+            failedItems?: number;
+            /** @description Owning project. Included when `expansion=project` is requested. */
+            project?: components["schemas"]["QueueProjectSummaryDto"];
+            /** @description Owning workspace. Included when `expansion=workspace` is requested. */
+            workspace?: components["schemas"]["QueueWorkspaceSummaryDto"];
+            /** @description Workspace user who created the queue. Included when `expansion=createdByWorkspaceUser` is requested. */
+            createdByWorkspaceUser?: components["schemas"]["QueueCreatedByWorkspaceUserDto"];
+            /** @description Relation counts. Included when `expansion=itemCounts` is requested. */
+            _count?: components["schemas"]["QueueItemCountsDto"];
+        };
+        QueueStatsResponseDto: {
+            /** @description Total number of items in the queue. */
+            totalItems: number;
+            /** @description Number of items awaiting processing. */
+            pendingItems: number;
+            /** @description Number of items currently being processed. */
+            processingItems: number;
+            /** @description Number of successfully processed items. */
+            successItems: number;
+            /** @description Number of items that failed permanently. */
+            failedItems: number;
+            /** @description Number of items awaiting a retry attempt. */
+            retryingItems: number;
+        };
+        UpdateQueueDto: {
+            /** @description Human-readable name for the queue. */
+            name?: string;
+            /** @description Description of what the queue is used for. */
+            description?: string;
+            /** @description Maximum number of retry attempts per item. Defaults to 3. */
+            maxRetries?: number;
+            /** @description Delay in minutes before a failed item becomes eligible for retry. Defaults to 60. */
+            retryDelayMinutes?: number;
+            /** @description Number of items fetched per processing batch. Defaults to 10. */
+            batchSize?: number;
+            /** @description Default priority for items in this queue. Higher values are processed first. Defaults to 0. */
+            priority?: number;
+            /** @description Whether the queue is active. Inactive queues do not accept processing. */
+            isActive?: boolean;
+        };
+        SuccessResponseDto: {
+            /** @description True when the operation succeeded. */
+            success: boolean;
+        };
+        CreateQueueItemDto: {
+            /** @description External identifier used to deduplicate items within the queue. */
+            externalId?: string;
+            /** @description Arbitrary JSON payload for the item. Maximum size 64KB. */
+            data?: {
+                [key: string]: unknown;
+            };
+            /** @description Item priority. Higher values are processed first. Defaults to the queue priority. */
+            priority?: number;
+            /** @description Maximum number of retry attempts for this item. Defaults to the queue setting. */
+            maxRetries?: number;
+            /** @description ISO 8601 date-time to defer processing until. Omit to make the item ready immediately. */
+            scheduledFor?: string;
+            /** @description Arbitrary JSON metadata attached to the item. Maximum size 64KB. */
+            metadata?: {
+                [key: string]: unknown;
+            };
+        };
+        QueueItemErrorEntryResponseDto: {
+            /** @description Error message. */
+            error: string;
+            /** @description Additional structured error details, if provided. */
+            errorDetails?: {
+                [key: string]: unknown;
+            };
+            /**
+             * Format: date-time
+             * @description ISO 8601 timestamp when the error was recorded.
+             */
+            timestamp: string;
+        };
+        QueueItemQueueSummaryDto: {
+            /** @description Queue ID. */
+            id: string;
+            /** @description Queue name. */
+            name: string;
+        };
+        QueueItemExecutionWorkflowDto: {
+            /** @description Workflow ID. */
+            id: string;
+        };
+        QueueItemLastExecutionDto: {
+            /** @description Execution ID. */
+            id: string;
+            /** @description Execution status. */
+            status: string;
+            /** @description Workflow the execution belongs to. */
+            workflow: components["schemas"]["QueueItemExecutionWorkflowDto"];
+        };
+        QueueItemCreateResponseDto: {
+            /** @description Queue item ID. */
+            id: string;
+            /** @description External identifier used for deduplication. */
+            externalId: string | null;
+            /** @description JSON payload for the item. */
+            data: {
+                [key: string]: unknown;
+            } | null;
+            /**
+             * @description Processing status of the item.
+             * @enum {string}
+             */
+            status: "PENDING" | "PROCESSING" | "SUCCESS" | "FAILED" | "RETRYING";
+            /** @description Number of retry attempts made so far. */
+            retryCount: number;
+            /** @description Maximum number of retry attempts allowed. */
+            maxRetries: number;
+            /** @description Most recent error message. */
+            lastError: string | null;
+            /** @description Item priority. Higher values are processed first. */
+            priority: number;
+            /** @description JSON metadata attached to the item. */
+            metadata: {
+                [key: string]: unknown;
+            } | null;
+            /**
+             * Format: date-time
+             * @description When the item becomes eligible for retry. Included when `expansion=createdAt` is requested.
+             */
+            nextRetryAt?: string | null;
+            /**
+             * Format: date-time
+             * @description When processing started. Included when `expansion=createdAt` is requested.
+             */
+            processingStartedAt?: string | null;
+            /**
+             * Format: date-time
+             * @description When processing finished. Included when `expansion=createdAt` is requested.
+             */
+            processingCompletedAt?: string | null;
+            /**
+             * Format: date-time
+             * @description When the most recent error occurred. Included when `expansion=createdAt` is requested.
+             */
+            lastErrorAt?: string | null;
+            /**
+             * Format: date-time
+             * @description When the item is scheduled for processing. Included when `expansion=createdAt` is requested.
+             */
+            scheduledFor?: string | null;
+            /**
+             * Format: date-time
+             * @description Creation timestamp. Included when `expansion=createdAt` is requested.
+             */
+            createdAt?: string;
+            /**
+             * Format: date-time
+             * @description Last update timestamp. Included when `expansion=updatedAt` is requested.
+             */
+            updatedAt?: string;
+            /** @description History of errors recorded against the item. Included when `expansion=errorHistory` is requested. */
+            errorHistory?: components["schemas"]["QueueItemErrorEntryResponseDto"][] | null;
+            /** @description Owning queue. Included when `expansion=queue` is requested. */
+            queue?: components["schemas"]["QueueItemQueueSummaryDto"];
+            /** @description Most recently linked workflow execution. Included when `expansion=lastExecution` is requested. */
+            lastExecution?: components["schemas"]["QueueItemLastExecutionDto"] | null;
+            /** @description True when an existing item with the same externalId was returned instead of creating a new one. */
+            isDuplicate: boolean;
+        };
+        BulkCreateQueueItemsOptionsDto: {
+            /** @description If true, items whose externalId already exists are skipped silently. If false, existing items are returned. */
+            skipDuplicates?: boolean;
+            /** @description If true, existing items matched by externalId are updated with the submitted data. */
+            updateExisting?: boolean;
+        };
+        BulkCreateQueueItemsDto: {
+            /** @description Items to create in the queue. */
+            items: components["schemas"]["CreateQueueItemDto"][];
+            /** @description Options controlling duplicate handling. */
+            options?: components["schemas"]["BulkCreateQueueItemsOptionsDto"];
+        };
+        QueueItemResponseDto: {
+            /** @description Queue item ID. */
+            id: string;
+            /** @description External identifier used for deduplication. */
+            externalId: string | null;
+            /** @description JSON payload for the item. */
+            data: {
+                [key: string]: unknown;
+            } | null;
+            /**
+             * @description Processing status of the item.
+             * @enum {string}
+             */
+            status: "PENDING" | "PROCESSING" | "SUCCESS" | "FAILED" | "RETRYING";
+            /** @description Number of retry attempts made so far. */
+            retryCount: number;
+            /** @description Maximum number of retry attempts allowed. */
+            maxRetries: number;
+            /** @description Most recent error message. */
+            lastError: string | null;
+            /** @description Item priority. Higher values are processed first. */
+            priority: number;
+            /** @description JSON metadata attached to the item. */
+            metadata: {
+                [key: string]: unknown;
+            } | null;
+            /**
+             * Format: date-time
+             * @description When the item becomes eligible for retry. Included when `expansion=createdAt` is requested.
+             */
+            nextRetryAt?: string | null;
+            /**
+             * Format: date-time
+             * @description When processing started. Included when `expansion=createdAt` is requested.
+             */
+            processingStartedAt?: string | null;
+            /**
+             * Format: date-time
+             * @description When processing finished. Included when `expansion=createdAt` is requested.
+             */
+            processingCompletedAt?: string | null;
+            /**
+             * Format: date-time
+             * @description When the most recent error occurred. Included when `expansion=createdAt` is requested.
+             */
+            lastErrorAt?: string | null;
+            /**
+             * Format: date-time
+             * @description When the item is scheduled for processing. Included when `expansion=createdAt` is requested.
+             */
+            scheduledFor?: string | null;
+            /**
+             * Format: date-time
+             * @description Creation timestamp. Included when `expansion=createdAt` is requested.
+             */
+            createdAt?: string;
+            /**
+             * Format: date-time
+             * @description Last update timestamp. Included when `expansion=updatedAt` is requested.
+             */
+            updatedAt?: string;
+            /** @description History of errors recorded against the item. Included when `expansion=errorHistory` is requested. */
+            errorHistory?: components["schemas"]["QueueItemErrorEntryResponseDto"][] | null;
+            /** @description Owning queue. Included when `expansion=queue` is requested. */
+            queue?: components["schemas"]["QueueItemQueueSummaryDto"];
+            /** @description Most recently linked workflow execution. Included when `expansion=lastExecution` is requested. */
+            lastExecution?: components["schemas"]["QueueItemLastExecutionDto"] | null;
+        };
+        BulkCreateQueueItemsSummaryDto: {
+            /** @description Number of items created. */
+            created: number;
+            /** @description Number of existing items returned or updated. */
+            existing: number;
+            /** @description Number of duplicate items skipped. */
+            skipped: number;
+            /** @description Total number of items submitted. */
+            total: number;
+        };
+        BulkCreateQueueItemsResponseDto: {
+            /** @description Newly created queue items. */
+            created: components["schemas"]["QueueItemResponseDto"][];
+            /** @description Existing items matched by externalId, updated when the updateExisting option is set. */
+            existing: components["schemas"]["QueueItemResponseDto"][];
+            /** @description Summary counts for the bulk operation. */
+            summary: components["schemas"]["BulkCreateQueueItemsSummaryDto"];
+        };
+        QueueItemListPaginationDto: {
+            /** @description Total number of items matching the filters. */
+            total: number;
+            /** @description Page size applied to the request. */
+            limit: number;
+            /** @description Offset applied to the request. */
+            offset: number;
+            /** @description Whether more items exist beyond the current page. */
+            hasMore: boolean;
+        };
+        QueueItemListResponseDto: {
+            /** @description Queue items for the current page. */
+            items: components["schemas"]["QueueItemResponseDto"][];
+            /** @description Pagination details. */
+            pagination: components["schemas"]["QueueItemListPaginationDto"];
+        };
+        QueueItemFullResponseDto: {
+            /** @description Queue item ID. */
+            id: string;
+            /**
+             * Format: date-time
+             * @description Creation timestamp.
+             */
+            createdAt: string;
+            /**
+             * Format: date-time
+             * @description Last update timestamp.
+             */
+            updatedAt: string;
+            /** @description External identifier used for deduplication. */
+            externalId: string | null;
+            /** @description JSON payload for the item. */
+            data: {
+                [key: string]: unknown;
+            } | null;
+            /**
+             * @description Processing status of the item.
+             * @enum {string}
+             */
+            status: "PENDING" | "PROCESSING" | "SUCCESS" | "FAILED" | "RETRYING";
+            /** @description Number of retry attempts made so far. */
+            retryCount: number;
+            /** @description Maximum number of retry attempts allowed. */
+            maxRetries: number;
+            /**
+             * Format: date-time
+             * @description When the item becomes eligible for retry.
+             */
+            nextRetryAt: string | null;
+            /**
+             * Format: date-time
+             * @description When processing started.
+             */
+            processingStartedAt: string | null;
+            /**
+             * Format: date-time
+             * @description When processing finished.
+             */
+            processingCompletedAt: string | null;
+            /** @description Most recent error message. */
+            lastError: string | null;
+            /**
+             * Format: date-time
+             * @description When the most recent error occurred.
+             */
+            lastErrorAt: string | null;
+            /** @description History of errors recorded against the item. */
+            errorHistory: {
+                [key: string]: unknown;
+            }[] | null;
+            /** @description ID of the most recently linked workflow execution. */
+            FK_lastExecutionId: string | null;
+            /** @description Item priority. Higher values are processed first. */
+            priority: number;
+            /**
+             * Format: date-time
+             * @description When the item is scheduled for processing.
+             */
+            scheduledFor: string | null;
+            /** @description JSON metadata attached to the item. */
+            metadata: {
+                [key: string]: unknown;
+            } | null;
+            /** @description ID of the owning queue. */
+            FK_queueId: string;
+        };
+        QueueItemStatusCountsDto: {
+            /** @description Number of items awaiting processing. */
+            PENDING: number;
+            /** @description Number of items currently being processed. */
+            PROCESSING: number;
+            /** @description Number of successfully processed items. */
+            SUCCESS: number;
+            /** @description Number of items that failed permanently. */
+            FAILED: number;
+            /** @description Number of items awaiting a retry attempt. */
+            RETRYING: number;
+        };
+        QueueItemPriorityCountsDto: {
+            /** @description Items with priority 10 or above. */
+            high: number;
+            /** @description Items with priority 5 to 9. */
+            medium: number;
+            /** @description Items with priority below 5. */
+            low: number;
+        };
+        QueueItemStatsResponseDto: {
+            /** @description Total number of items in the queue. */
+            total: number;
+            /** @description Item counts grouped by status. */
+            byStatus: components["schemas"]["QueueItemStatusCountsDto"];
+            /** @description Item counts grouped by priority band. */
+            byPriority: components["schemas"]["QueueItemPriorityCountsDto"];
+            /** @description Average processing time in milliseconds for successful items. */
+            averageProcessingTime: number;
+            /** @description Fraction of items that required at least one retry, between 0 and 1. */
+            retryRate: number;
+        };
+        UpdateQueueItemDto: {
+            /** @description External identifier used to deduplicate items within the queue. */
+            externalId?: string;
+            /** @description Arbitrary JSON payload for the item. Maximum size 64KB. */
+            data?: {
+                [key: string]: unknown;
+            };
+            /** @description Item priority. Higher values are processed first. Defaults to the queue priority. */
+            priority?: number;
+            /** @description Maximum number of retry attempts for this item. Defaults to the queue setting. */
+            maxRetries?: number;
+            /** @description ISO 8601 date-time to defer processing until. Omit to make the item ready immediately. */
+            scheduledFor?: string;
+            /** @description Arbitrary JSON metadata attached to the item. Maximum size 64KB. */
+            metadata?: {
+                [key: string]: unknown;
+            };
+            /**
+             * @description New processing status for the item.
+             * @enum {string}
+             */
+            status?: "PENDING" | "PROCESSING" | "SUCCESS" | "FAILED" | "RETRYING";
+            /** @description ISO 8601 date-time when the item becomes eligible for retry. Set to null to clear. */
+            nextRetryAt?: string;
+        };
+        UpdateStatusDto: {
+            /**
+             * @description Target status. Must be a valid transition from the current status.
+             * @enum {string}
+             */
+            status: "PENDING" | "PROCESSING" | "SUCCESS" | "FAILED" | "RETRYING";
+            /** @description Error message recorded with the transition. Recommended when moving to FAILED or RETRYING. */
+            error?: string;
+        };
+        LinkExecutionDto: {
+            /** @description ID of the workflow execution to link to the queue item. */
+            executionId: string;
+        };
+        BulkUpdateItemsDto: {
+            /** @description IDs of the queue items to update. */
+            itemIds: string[];
+            /** @description Fields to apply to every listed item. */
+            updates: components["schemas"]["UpdateQueueItemDto"];
+        };
+        AddErrorDto: {
+            /** @description Error message to record against the queue item. */
+            error: string;
+            /** @description Additional structured error details, supplied as a JSON string. */
+            errorDetails?: {
+                [key: string]: unknown;
+            };
+        };
+        BulkDeleteItemsDto: {
+            /** @description IDs of the queue items to delete. */
+            itemIds: string[];
+        };
+        BulkDeleteItemsResponseDto: {
+            /** @description Whether the bulk delete ran to completion. */
+            success: boolean;
+            /** @description Number of items actually deleted. */
+            deletedCount: number;
+            /** @description Number of item IDs submitted for deletion. */
+            requestedCount: number;
+        };
+        WorkflowProjectSummaryDto: {
+            /** @description Project ID */
+            id: string;
+            /** @description Project name */
+            name: string;
+        };
+        WorkflowResponseDto: {
+            /** @description Workflow ID */
+            id: string;
+            /** @description Workflow name */
+            name: string;
+            /** @description Stable project-scoped slug for CLI / code deploy upserts. Included when `expansion=slug` is requested. */
+            slug?: string | null;
+            /** @description True when last written by code (CLI / SDK). Included when `expansion=managedByCode` is requested. */
+            managedByCode?: boolean;
+            /** @description Workflow description. Included when `expansion=description` is requested. */
+            description?: string | null;
+            /** @description Declared output schema from the workflow's Output Workflow Data node. Shape is a map of field ID to `{ type, description? }`. Included when `expansion=output` is requested. Null when the workflow has no declared output schema. */
+            output?: {
+                [key: string]: unknown;
+            } | null;
+            /**
+             * Format: date-time
+             * @description Creation timestamp. Included when `expansion=createdAt` is requested.
+             */
+            createdAt?: string;
+            /**
+             * Format: date-time
+             * @description Last update timestamp. Included when `expansion=updatedAt` is requested.
+             */
+            updatedAt?: string;
+            /** @description Whether the workflow is active and can be triggered. Included when `expansion=isActive` is requested. */
+            isActive?: boolean;
+            /** @description Whether the workflow is internal (hidden from default listings). Included when `expansion=isInternal` is requested. */
+            isInternal?: boolean;
+            /** @description Workflow node definitions (JSON). Included when `expansion=nodes` is requested. */
+            nodes?: {
+                [key: string]: unknown;
+            }[];
+            /** @description Workflow edge definitions connecting nodes (JSON). Included when `expansion=edges` is requested. */
+            edges?: {
+                [key: string]: unknown;
+            }[];
+            /** @description The workflow trigger node definition (JSON). Included when `expansion=triggerNode` is requested. */
+            triggerNode?: {
+                [key: string]: unknown;
+            } | null;
+            /** @description IDs of the triggers and actions used by the workflow. Included when `expansion=triggerAndActionIds` is requested. */
+            triggerAndActionIds?: string[];
+            /** @description IDs of sub-workflows referenced by the workflow. Included when `expansion=subWorkflowIds` is requested. Only returned by GET /workflows/{workflowId}. */
+            subWorkflowIds?: string[];
+            /** @description IDs of agents referenced by the workflow. Included when `expansion=agentIds` is requested. Only returned by GET /workflows/{workflowId}. */
+            agentIds?: string[];
+            /** @description Internal polling trigger storage value. Included when `expansion=pollStorage` is requested. */
+            pollStorage?: string | null;
+            /**
+             * Format: date-time
+             * @description Timestamp of the next scheduled execution, if the workflow runs on a schedule. Included when `expansion=nextScheduledExecution` is requested.
+             */
+            nextScheduledExecution?: string | null;
+            /**
+             * @description Editor orientation of the workflow canvas. Included when `expansion=orientation` is requested.
+             * @enum {string}
+             */
+            workflowOrientation?: "HORIZONTAL" | "VERTICAL";
+            /** @description The project the workflow belongs to. Included when `expansion=project` is requested. */
+            project?: components["schemas"]["WorkflowProjectSummaryDto"];
+            /** @description AI provider connection used by the workflow builder chat. Always returned on GET /workflows/{workflowId}. */
+            aiConnectionId?: string | null;
+            /** @description Selected model ID within the AI provider connection for workflow builder chat. Always returned on GET /workflows/{workflowId}. */
+            selectedModelId?: string | null;
+        };
+        UpsertWorkflowStepDto: {
+            /** @description Workflow app id (catalogue slug). */
+            appId: string;
+            /** @description Catalogue action id. */
+            actionId: string;
+            /** @description Connection instance UUID for this step. */
+            connectionId?: string;
+            /** @description Action input / config fields. */
+            input?: {
+                [key: string]: unknown;
+            };
+            /** @description Display name for the step node. */
+            name?: string;
+            /** @description Step description. */
+            description?: string;
+        };
+        UpsertWorkflowBySlugDto: {
+            /**
+             * @description Stable project-scoped slug (lowercase, digits, hyphens). Used as the upsert key.
+             * @example sync-orders
+             */
+            slug: string;
+            /** @description Display name. Defaults to the slug when omitted. */
+            name?: string;
+            description?: string;
+            /** @description Whether the workflow is active. */
+            isActive?: boolean;
+            /** @description Linear catalogue-action steps (v1; no branches). */
+            steps: components["schemas"]["UpsertWorkflowStepDto"][];
+            /** @description Marks the row as managed by code (CLI / SDK). Defaults to true on this endpoint. */
+            managedByCode?: boolean;
+        };
+        WorkflowAppResponseDto: {
+            /** @description App ID, e.g. `gmail`. Matches the appId used in workflow execution steps. */
+            id: string;
+            /** @description Human-readable app name. */
+            name: string;
+            /** @description App description. */
+            description: string;
+            /** @description URL of the app logo. */
+            logoUrl: string;
+            /** @description Whether the app is published and available for use. */
+            isPublished: boolean;
+            /** @description Whether the app requires a connection before its actions and triggers can run. */
+            needsConnection: boolean;
+            /** @description Whether the app can be used by agents. */
+            availableForAgent: boolean;
+            /** @description Action definitions, each with id, name, description, iconUrl, needsConnection, availableForAgent, viewOptions and the declarative inputConfig field metadata used to render action UIs. */
+            actions: {
+                [key: string]: unknown;
+            }[];
+            /** @description Trigger definitions, each with id, name, description, iconUrl, needsConnection and the declarative inputConfig field metadata used to render trigger UIs. */
+            triggers: {
+                [key: string]: unknown;
+            }[];
+            /** @description Connection type definitions supported by the app (e.g. oauth2, apiKey, basic), each with id, name, description, connectionType and any declarative inputConfig fields. */
+            connections: {
+                [key: string]: unknown;
+            }[];
+        };
+        ObjectTypeUserSummaryDto: {
+            /** @description User ID. */
+            id: string;
+            /** @description Email address of the user. */
+            email: string;
+            /** @description Display name of the user. */
+            name: string;
+        };
+        ObjectTypeCreatedByDto: {
+            /** @description Workspace user ID. */
+            id: string;
+            user: components["schemas"]["ObjectTypeUserSummaryDto"];
+        };
+        ObjectTypeCountDto: {
+            /** @description Number of non-deleted entities of this type. */
+            objects: number;
+        };
+        ObjectTypeResponseDto: {
+            /** @description Entity type ID. */
+            id: string;
+            /** @description Singular display name of the entity type. */
+            name: string;
+            /** @description Plural display name of the entity type. */
+            namePlural: string;
+            /** @description URL-safe slug, unique within the workspace. */
+            slug: string;
+            /** @description Icon identifier for the entity type. */
+            icon: string;
+            /** @description Hex colour of the entity type. */
+            color: string;
+            /** @description Whether the entity type is enabled. */
+            isEnabled: boolean;
+            /** @description Description of the entity type. Included when `expansion=description` is requested. */
+            description?: string | null;
+            /** @description Field definitions grouped into sections. Included when `expansion=attributeSchema` is requested. */
+            attributeSchema?: {
+                [key: string]: unknown;
+            };
+            /** @description State machine definition. Included when `expansion=stateSchema` is requested. */
+            stateSchema?: {
+                [key: string]: unknown;
+            } | null;
+            /**
+             * Format: date-time
+             * @description Included when `expansion=createdAt` is requested.
+             */
+            createdAt?: string;
+            /**
+             * Format: date-time
+             * @description Included when `expansion=updatedAt` is requested.
+             */
+            updatedAt?: string;
+            /** @description Workspace member who created the entity type. Included when `expansion=createdBy` is requested. */
+            createdBy?: components["schemas"]["ObjectTypeCreatedByDto"];
+            /** @description Included when `expansion=countObjects` is requested. */
+            _count?: components["schemas"]["ObjectTypeCountDto"];
+        };
+        CreateObjectDto: {
+            /** @description Display name of the entity. */
+            name: string;
+            /**
+             * Format: uuid
+             * @description ID of the entity type to create the entity under.
+             */
+            objectTypeId: string;
+            /** @description Initial state ID. Must exist in the entity type state schema. Defaults to the schema initial state when omitted. */
+            state?: string;
+            /** @description Dynamic attribute values keyed by field ID. */
+            attributes?: {
+                [key: string]: unknown;
+            };
+            /**
+             * Format: uuid
+             * @description Workspace user ID of the entity owner.
+             */
+            ownerId?: string;
+        };
+        ObjectTypeSummaryDto: {
+            /** @description Entity type ID. */
+            id: string;
+            /** @description Singular display name of the entity type. */
+            name: string;
+            /** @description URL-safe slug of the entity type. */
+            slug: string;
+            /** @description Icon identifier for the entity type. */
+            icon: string;
+            /** @description Hex colour of the entity type. */
+            color: string;
+            /** @description Plural display name. Included when `expansion=objectType` is requested. */
+            namePlural?: string;
+            /** @description Field definitions grouped into sections. Included when `expansion=objectType` is requested on single-entity reads. */
+            attributeSchema?: {
+                [key: string]: unknown;
+            };
+            /** @description State machine definition. Included when `expansion=objectType` is requested. */
+            stateSchema?: {
+                [key: string]: unknown;
+            } | null;
+        };
+        ObjectUserSummaryDto: {
+            /** @description User ID. */
+            id: string;
+            /** @description Email address of the user. */
+            email: string;
+            /** @description Display name of the user. */
+            name: string;
+        };
+        ObjectWorkspaceUserSummaryDto: {
+            /** @description Workspace user ID. */
+            id: string;
+            user: components["schemas"]["ObjectUserSummaryDto"];
+        };
+        ObjectStateHistoryUserSummaryDto: {
+            /** @description User ID. */
+            id: string;
+            /** @description Display name of the user. */
+            name: string;
+        };
+        ObjectStateHistoryChangedByDto: {
+            /** @description Workspace user ID. */
+            id: string;
+            user: components["schemas"]["ObjectStateHistoryUserSummaryDto"];
+        };
+        ObjectStateHistoryItemDto: {
+            /** @description State history entry ID. */
+            id: string;
+            /** @description State the entity moved from. Null for the initial state. */
+            fromState: string | null;
+            /** @description State the entity moved to. */
+            toState: string;
+            /** @description Reason recorded for the state change, if any. */
+            reason: string | null;
+            /**
+             * Format: date-time
+             * @description When the state change occurred.
+             */
+            createdAt: string;
+            /** @description Workspace member who made the change, if recorded. */
+            changedBy: components["schemas"]["ObjectStateHistoryChangedByDto"] | null;
+        };
+        ObjectResponseDto: {
+            /** @description Entity ID. */
+            id: string;
+            /** @description Display name of the entity. */
+            name: string;
+            /** @description Current state of the entity, if the type defines states. */
+            state: string | null;
+            /** @description Dynamic attribute values keyed by field ID. */
+            attributes: {
+                [key: string]: unknown;
+            };
+            /**
+             * Format: date-time
+             * @description Included when `expansion=createdAt` is requested.
+             */
+            createdAt?: string;
+            /**
+             * Format: date-time
+             * @description Included by default on list responses, otherwise when `expansion=updatedAt` is requested.
+             */
+            updatedAt?: string;
+            /** @description Included by default on list responses with a minimal shape, otherwise when `expansion=objectType` is requested. */
+            objectType?: components["schemas"]["ObjectTypeSummaryDto"];
+            /** @description Included when `expansion=owner` is requested. */
+            owner?: components["schemas"]["ObjectWorkspaceUserSummaryDto"] | null;
+            /** @description Included when `expansion=createdBy` is requested. */
+            createdBy?: components["schemas"]["ObjectWorkspaceUserSummaryDto"] | null;
+            /** @description Most recent state changes (up to 50, newest first). Included when `expansion=stateHistory` is requested. */
+            stateHistory?: components["schemas"]["ObjectStateHistoryItemDto"][];
+        };
+        ObjectPaginationDto: {
+            /** @description Current page number (1-based). */
+            page: number;
+            /** @description Number of items per page (maximum 100). */
+            pageSize: number;
+            /** @description Total number of matching entities. */
+            totalCount: number;
+            /** @description Total number of pages. */
+            totalPages: number;
+        };
+        PaginatedObjectsResponseDto: {
+            data: components["schemas"]["ObjectResponseDto"][];
+            pagination: components["schemas"]["ObjectPaginationDto"];
+        };
+        UpdateObjectDto: {
+            /** @description New display name of the entity. */
+            name?: string;
+            /** @description Attribute values keyed by field ID. Merged into the existing attributes; fields not supplied are left unchanged. */
+            attributes?: {
+                [key: string]: unknown;
+            };
+            /** @description Workspace user ID of the new entity owner. */
+            ownerId?: string;
+        };
+        ChangeObjectStateDto: {
+            /** @description ID of the target state. Must be a valid transition from the current state when the entity type defines transitions. */
+            newState: string;
+            /** @description Reason for the state change. Required when the transition is configured with requiresReason. */
+            reason?: string;
+        };
+        ChangeObjectStateResponseDto: {
+            /** @description Entity ID. */
+            id: string;
+            /** @description Display name of the entity. */
+            name: string;
+            /** @description State of the entity after the change. */
+            state: string | null;
+            /**
+             * Format: date-time
+             * @description When the entity was last updated.
+             */
+            updatedAt: string;
+        };
+        StateHistoryUserSummaryDto: {
+            /** @description User ID. */
+            id: string;
+            /** @description Display name of the user. */
+            name: string;
+            /** @description Email address of the user. */
+            email: string;
+        };
+        StateHistoryChangedByDto: {
+            /** @description Workspace user ID. */
+            id: string;
+            user: components["schemas"]["StateHistoryUserSummaryDto"];
+        };
+        ObjectStateHistoryEntryResponseDto: {
+            /** @description State history entry ID. */
+            id: string;
+            /** @description State the entity moved from. Null for the initial state. */
+            fromState: string | null;
+            /** @description State the entity moved to. */
+            toState: string;
+            /** @description Reason recorded for the state change, if any. */
+            reason: string | null;
+            /**
+             * Format: date-time
+             * @description When the state change occurred.
+             */
+            createdAt: string;
+            /** @description Workspace member who made the change, if recorded. */
+            changedBy: components["schemas"]["StateHistoryChangedByDto"] | null;
+        };
+        ObjectStateInfoDto: {
+            /** @description State ID. */
+            id: string;
+            /** @description Display name of the state. */
+            name: string;
+            /** @description Colour associated with the state. */
+            color?: string;
+            /** @description Icon associated with the state. */
+            icon?: string;
+            /** @description Whether the state is a final state. */
+            isFinal: boolean;
+        };
+        ObjectStateTransitionDto: {
+            /** @description Transition ID from the state schema. */
+            transitionId: string;
+            /** @description ID of the target state. */
+            toStateId: string;
+            /** @description Display name of the target state. */
+            toStateName: string;
+            /** @description Colour of the target state. */
+            toStateColor?: string;
+            /** @description Icon of the target state. */
+            toStateIcon?: string;
+            /** @description Whether a reason must be supplied for this transition. */
+            requiresReason: boolean;
+            /** @description Confirmation message to show before applying the transition. */
+            confirmationMessage?: string;
+        };
+        ObjectStateTransitionsResponseDto: {
+            /** @description Current state of the entity. Null when the entity has no state or the type defines no state schema. */
+            currentState: components["schemas"]["ObjectStateInfoDto"] | null;
+            /** @description Transitions allowed from the current state. */
+            validTransitions: components["schemas"]["ObjectStateTransitionDto"][];
+            /** @description All states defined by the entity type, for cases where no transitions are defined. */
+            allStates: components["schemas"]["ObjectStateInfoDto"][];
+        };
+        ImportRowErrorDto: {
+            /** @description Row number the error relates to (1-based). */
+            row: number;
+            /** @description Field ID the error relates to, when applicable. */
+            field?: string;
+            /** @description Human-readable error message. */
+            message: string;
+        };
+        ImportEntitiesResponseDto: {
+            /** @description Total number of rows processed. */
+            totalRows: number;
+            /** @description Number of rows imported successfully. */
+            successCount: number;
+            /** @description Number of rows that failed to import. */
+            errorCount: number;
+            /** @description Per-row errors encountered during the import. */
+            errors: components["schemas"]["ImportRowErrorDto"][];
+            /** @description IDs of entities created by the import. */
+            createdIds: string[];
+            /** @description IDs of existing entities updated by the import. */
+            updatedIds: string[];
+        };
+        ImportTemplateResponseDto: {
+            /** @description Column headers for the import file. Always starts with "name". */
+            columns: string[];
+            /** @description Sample row with an example value for each column. */
+            sampleRow: {
+                [key: string]: string;
+            };
+        };
+        CreateKnowledgeDto: {
+            /** @description Name of the knowledge base. */
+            name: string;
+            /** @description Description of the knowledge base. */
+            description?: string;
+            /** @description Default chunk overlap in words. Must be provided together with chunkSize and cannot exceed 50% of it. */
+            chunkOverlap?: number;
+            /** @description Default chunk size in words (50 to 2000). Must be provided together with chunkOverlap. */
+            chunkSize?: number;
+            /** @description Embedding model to use. Defaults to the platform-configured embedding model. */
+            embeddingModel?: string;
+            /** @description Embedding provider to use. Defaults to the platform-configured embedding provider. */
+            embeddingProvider?: string;
+            /** @description Embedding vector dimensions. Defaults to the platform-configured dimensions. */
+            dimensions?: number;
+        };
+        KnowledgeCountDto: {
+            /** @description Number of vector references stored in this knowledge base. */
+            vectorRefs: number;
+        };
+        KnowledgeVectorRefSummaryDto: {
+            /** @description Vector reference ID. */
+            id: string;
+            /** @description ID of the knowledge base the vector reference belongs to. */
+            FK_knowledgeId: string;
+        };
+        KnowledgeUsageDto: {
+            /** @description Total prompt tokens consumed when embedding content into this knowledge base. */
+            promptTokens: number;
+        };
+        KnowledgeWorkspaceDto: {
+            /** @description Workspace ID. */
+            id: string;
+            /** @description Workspace name. */
+            name: string;
+        };
+        KnowledgeResponseDto: {
+            /** @description Knowledge base ID. */
+            id: string;
+            /** @description Knowledge base name. */
+            name: string;
+            /** @description Knowledge base description. Included when `expansion=description` is requested. */
+            description?: string;
+            /**
+             * Format: date-time
+             * @description Creation timestamp. Included when `expansion=createdAt` is requested.
+             */
+            createdAt?: string;
+            /**
+             * Format: date-time
+             * @description Last update timestamp. Included when `expansion=updatedAt` is requested.
+             */
+            updatedAt?: string;
+            /** @description Name of the underlying vector index collection. Included when `expansion=indexName` is requested. */
+            indexName?: string;
+            /** @description Default chunk size in words used when uploading text. Included when `expansion=chunkSize` is requested. */
+            chunkSize?: number;
+            /** @description Default chunk overlap in words used when uploading text. Included when `expansion=chunkOverlap` is requested. */
+            chunkOverlap?: number;
+            /** @description Embedding model used for this knowledge base. Included when `expansion=embeddingModel` is requested. */
+            embeddingModel?: string;
+            /** @description Embedding provider used for this knowledge base. Included when `expansion=embeddingProvider` is requested. */
+            embeddingProvider?: string;
+            /** @description Embedding vector dimensions. Included when `expansion=dimensions` is requested. */
+            dimensions?: number;
+            /** @description Aggregate counts. Included when `expansion=countVectorRefs` is requested. */
+            _count?: components["schemas"]["KnowledgeCountDto"];
+            /** @description Vector references stored in this knowledge base. Included when `expansion=vectorRefs` is requested. */
+            vectorRefs?: components["schemas"]["KnowledgeVectorRefSummaryDto"][];
+            /** @description Embedding token usage. Included when `expansion=usage` is requested. */
+            usage?: components["schemas"]["KnowledgeUsageDto"];
+            /** @description Owning workspace. Included when `expansion=workspace` is requested. */
+            workspace?: components["schemas"]["KnowledgeWorkspaceDto"];
+        };
+        UpdateKnowledgeDto: {
+            /** @description Name of the knowledge base. */
+            name?: string;
+            /** @description Description of the knowledge base. */
+            description?: string;
+            /** @description Default chunk overlap in words. Must be provided together with chunkSize and cannot exceed 50% of it. */
+            chunkOverlap?: number;
+            /** @description Default chunk size in words (50 to 2000). Must be provided together with chunkOverlap. */
+            chunkSize?: number;
+            /** @description Embedding model to use. Defaults to the platform-configured embedding model. */
+            embeddingModel?: string;
+            /** @description Embedding provider to use. Defaults to the platform-configured embedding provider. */
+            embeddingProvider?: string;
+            /** @description Embedding vector dimensions. Defaults to the platform-configured dimensions. */
+            dimensions?: number;
+        };
+        SaveUploadedTextToKnowledgeDto: {
+            /** @description Name of the document. Multi-part uploads are suffixed with the part number. */
+            name: string;
+            /** @description Raw text content to embed into the knowledge base. */
+            text: string;
+            /** @description Chunk overlap in words. Roughly 10% of chunkSize is recommended. */
+            chunkOverlap: number;
+            /** @description Chunk size in words used to split the text before embedding. */
+            chunkSize: number;
+        };
+        KnowledgeDocumentResponseDto: {
+            /** @description Document ID. For `group` documents this is the vector reference group ID; for `standalone` documents it is the vector reference ID. */
+            id: string;
+            /** @description Document name. */
+            name: string;
+            /**
+             * Format: date-time
+             * @description Creation timestamp.
+             */
+            createdAt: string;
+            /** @description Number of parts (chunks) the document was split into. */
+            partCount: number;
+            /**
+             * @description Whether the document is a multi-part group or a standalone single-part upload.
+             * @enum {string}
+             */
+            type: "group" | "standalone";
+        };
+        KnowledgeDocumentGroupVectorRefDto: {
+            /** @description Vector reference ID. */
+            id: string;
+            /** @description Vector reference name, including the part suffix for multi-part uploads. */
+            name: string;
+            /**
+             * Format: date-time
+             * @description Creation timestamp.
+             */
+            createdAt: string;
+            /** @description Part number within the group, or null for single-part uploads. */
+            part: number | null;
+            /** @description Storage path of the raw text for this part. */
+            s3Link: string | null;
+        };
+        KnowledgeDocumentGroupResponseDto: {
+            /** @description Document group ID. */
+            id: string;
+            /** @description Document group name, or null for legacy groups without a stored name. */
+            name: string | null;
+            /**
+             * Format: date-time
+             * @description Creation timestamp.
+             */
+            createdAt: string;
+            /** @description ID of the knowledge base the group belongs to, or null for legacy groups. */
+            FK_knowledgeId: string | null;
+            /** @description Vector references (parts) in the group, ordered by part number. */
+            vectorRefs: components["schemas"]["KnowledgeDocumentGroupVectorRefDto"][];
+        };
+        ManuallyRunWorkflowInputDataDto: {
+            /**
+             * @description Values for the custom input fields configured on the workflow "Manually Run" trigger, keyed by field ID. Pass an empty object when the trigger defines no custom input fields.
+             * @example {
+             *       "customerEmail": "jane@example.com",
+             *       "priority": "high"
+             *     }
+             */
+            inputData: {
+                [key: string]: unknown;
+            };
+        };
+        ExecuteWorkflowResponseDto: {
+            /** @description ID of the newly created execution. Poll GET /executions/{executionId} to track progress. */
+            id: string;
+        };
+        ExecutionWorkspaceSummaryDto: {
+            /** @description Workspace ID */
+            id: string;
+            /** @description Workspace name */
+            name: string;
+        };
+        ExecutionProjectSummaryDto: {
+            /** @description Project ID */
+            id: string;
+            /** @description Project name */
+            name: string;
+            /** @description The workspace the project belongs to. Included when `expansion=workspace` is requested alongside `workflow` and `project`. */
+            workspace?: components["schemas"]["ExecutionWorkspaceSummaryDto"];
+        };
+        ExecutionWorkflowSummaryDto: {
+            /** @description Workflow ID */
+            id: string;
+            /** @description Workflow name */
+            name: string;
+            /** @description The project the workflow belongs to. Included when `expansion=project` is requested alongside `workflow`. */
+            project?: components["schemas"]["ExecutionProjectSummaryDto"];
+        };
+        ExecutionPathStepDto: {
+            /** @description ID of the workflow node this step represents */
+            nodeId: string;
+            /** @description Human-friendly node name */
+            label: string;
+            /** @description ID of the app the node belongs to */
+            appId: string;
+            /** @description Action ID, present when the step is an action node */
+            actionId?: string;
+            /** @description Trigger ID, present when the step is the trigger node */
+            triggerId?: string;
+            /**
+             * @description Step status. NEEDS_INPUT indicates the step is paused waiting for user input.
+             * @enum {string}
+             */
+            status: "RUNNING" | "SUCCESS" | "FAILED" | "NEEDS_INPUT" | "SCHEDULED" | "RETRYING" | "WAITING";
+            /** @description Status detail message for the step */
+            statusMessage?: string;
+            /** @description Timestamp when the step started */
+            startTime?: string;
+            /** @description Timestamp when the step finished */
+            endTime?: string;
+            /** @description nodeId this step is an iteration of (set on loop child entries) */
+            iterationOf?: string;
+            /** @description Index of the loop iteration this step belongs to */
+            iterationIndex?: number;
+            /** @description On the collapsed loop parent entry: how many times the loop ran (or is planned to run) */
+            iterationCount?: number;
+            /**
+             * @description Approval status when this step is a Request Approval node awaiting or past a decision
+             * @enum {string}
+             */
+            approvalStatus?: "pending" | "partially_approved" | "approved" | "rejected" | "expired";
+            /** @description Number of approve decisions received so far */
+            approvalsReceived?: number;
+            /** @description Number of approvals required for quorum / current stage */
+            approvalsRequired?: number;
+        };
+        PendingInputFieldDto: {
+            /** @description Field ID used as the key when submitting input */
+            id: string;
+            /** @description Human-readable field label */
+            label: string;
+            /** @description Field input type from the workflow builder (e.g. text, number, select) */
+            inputType: string;
+            /** @description Whether the field must be provided to resume */
+            required: boolean;
+            /** @description Optional helper text for the field */
+            description?: string;
+            /** @description Selectable options when the field is a select-like input */
+            options?: {
+                label?: string;
+                value?: string;
+            }[];
+        };
+        PendingInputDto: {
+            /** @description ID of the waiting workflow node */
+            nodeId: string;
+            /** @description Human-friendly node name */
+            label: string;
+            /** @description Action ID of the waiting node, when it is an action step */
+            actionId?: string;
+            /** @description Optional instructions configured on the waiting node */
+            instructions?: string;
+            /** @description Fields the custom UI should collect. Submit values keyed by field `id` to POST /api/webhooks/executions/{executionId}/nodes/{nodeId}/input. */
+            fields: components["schemas"]["PendingInputFieldDto"][];
+        };
+        ExecutionResponseDto: {
+            /** @description Execution ID */
+            id: string;
+            /**
+             * Format: date-time
+             * @description Timestamp when the execution started. Always returned by GET /executions/{executionId}; included in list responses when `expansion=startedAt` is requested.
+             */
+            startedAt?: string;
+            /**
+             * Format: date-time
+             * @description Timestamp when the execution stopped. Included when `expansion=stoppedAt` is requested.
+             */
+            stoppedAt?: string | null;
+            /**
+             * Format: date-time
+             * @description Creation timestamp. Included when `expansion=createdAt` is requested.
+             */
+            createdAt?: string;
+            /**
+             * Format: date-time
+             * @description Last update timestamp. Included when `expansion=updatedAt` is requested.
+             */
+            updatedAt?: string | null;
+            /** @description Sequential execution number within the workflow. Included when `expansion=executionNumber` is requested. */
+            executionNumber?: number;
+            /** @description Raw execution node state (JSON). Included when `expansion=nodes` is requested. Most integrations should prefer the `executionPath` expansion instead. */
+            nodes?: {
+                [key: string]: unknown;
+            }[];
+            /** @description Raw execution edge state (JSON). Included when `expansion=edges` is requested. */
+            edges?: {
+                [key: string]: unknown;
+            }[];
+            /**
+             * @description Overall execution status. Included when `expansion=status` is requested.
+             * @enum {string}
+             */
+            status?: "RUNNING" | "SUCCESS" | "FAILED" | "NEEDS_INPUT" | "SCHEDULED" | "CANCELLED" | "WAITING";
+            /** @description Human-readable status detail. Included when `expansion=statusMessage` is requested. */
+            statusMessage?: string | null;
+            /** @description Final output of the execution (JSON). Included when `expansion=output` is requested. */
+            output?: {
+                [key: string]: unknown;
+            } | null;
+            /**
+             * Format: date-time
+             * @description Timestamp when a waiting execution is scheduled to continue. Included when `expansion=continueExecutionAt` is requested.
+             */
+            continueExecutionAt?: string | null;
+            /**
+             * @description Editor orientation of the workflow canvas at execution time. Included when `expansion=orientation` is requested.
+             * @enum {string}
+             */
+            workflowOrientation?: "HORIZONTAL" | "VERTICAL";
+            /** @description Variables captured during the execution (JSON). Included when `expansion=executionVariables` is requested. */
+            executionVariables?: {
+                [key: string]: unknown;
+            } | null;
+            /** @description The workflow the execution belongs to. Included when `expansion=workflow` is requested. */
+            workflow?: components["schemas"]["ExecutionWorkflowSummaryDto"];
+            /** @description Business-readable, ordered representation of the executed (or queued) steps, derived from the raw node and edge state: step labels, per-step status (including NEEDS_INPUT for steps paused awaiting user input), start and end timings, and loop iteration metadata. Custom UIs render execution progress from this field. Included when `expansion=executionPath` is requested. Only returned by GET /executions/{executionId}. */
+            executionPath?: components["schemas"]["ExecutionPathStepDto"][];
+            /** @description Field schemas for steps currently paused in NEEDS_INPUT. Each entry includes the waiting nodeId, label, optional instructions, and the fields to collect. Submit values keyed by field id to POST /api/webhooks/executions/{executionId}/nodes/{nodeId}/input. Included when `expansion=pendingInput` is requested. Only returned by GET /executions/{executionId}. Null when no step is waiting for input. */
+            pendingInput?: components["schemas"]["PendingInputDto"][] | null;
+            /**
+             * @description How the execution was started. `WORKFLOW` for graph runs; `SDK` for ad-hoc single-action runs from the Public API / client SDK. Included when `expansion=source` is requested.
+             * @enum {string}
+             */
+            source?: "WORKFLOW" | "SDK";
+            /** @description Optional display name (set for ad-hoc SDK runs). Included when `expansion=name` is requested. */
+            name?: string | null;
+        };
+        RunActionDto: {
+            /** @description Workflow app id (catalogue slug), e.g. `http`, `gmail`. */
+            appId: string;
+            /** @description Action id within the app, e.g. `http_action_send-request`. Discover via GET /workflow-apps (`actions[].id` / `inputConfig`). */
+            actionId: string;
+            /** @description Connection instance UUID (`Connection.id`). Required when the action needs a connection and the workspace has more than one connection for the app with no single workspace default. When omitted: sole usable connection for the app is used; else the workspace default (`isDefault`); else 400 with candidates. Never silently picks among multiple non-default connections. */
+            connectionId?: string;
+            /** @description Project UUID used for variable/project scoping. When omitted and the workspace has exactly one project, that project is used; otherwise the request fails with 400. */
+            projectId?: string;
+            /** @description Action input fields (mirrors the action `inputConfig` keys). Combined with `connectionId` into the action configValue. */
+            input?: {
+                [key: string]: unknown;
+            };
+            /** @description Optional display name for the ad-hoc Execution. */
+            name?: string;
+        };
+        RunActionResponseDto: {
+            /** @description ID of the ad-hoc Execution. Use GET /executions/{executionId} (with expansion=executionPath) to re-read progress. */
+            id: string;
+            /**
+             * @description Final execution status after the single action step.
+             * @enum {string}
+             */
+            status: "RUNNING" | "SUCCESS" | "FAILED" | "NEEDS_INPUT" | "SCHEDULED" | "CANCELLED" | "WAITING";
+            /** @description Human-readable status detail. */
+            statusMessage?: string | null;
+            /** @description Action output on success (same shape as a workflow step output). Null on failure or when the run paused. */
+            output?: {
+                [key: string]: unknown;
+            } | null;
+            /** @description Single-step executionPath for the ad-hoc run (label, status, timings). */
+            executionPath?: components["schemas"]["ExecutionPathStepDto"][];
+        };
+        RunStepDto: {
+            /** @description Workflow app id (catalogue slug), e.g. `http`, `gmail`. */
+            appId: string;
+            /** @description Action id within the app, e.g. `http_action_send-request`. Discover via GET /workflow-apps. */
+            actionId: string;
+            /** @description Connection instance UUID. When omitted, the platform resolves: sole usable connection for the app, else the workspace default (`isDefault`), else 400 with candidates. */
+            connectionId?: string;
+            /** @description Action input fields (mirrors the action `inputConfig` keys). */
+            input?: {
+                [key: string]: unknown;
+            };
+            /** @description Optional display name for this step. */
+            name?: string;
+        };
+        StartRunDto: {
+            /** @description Linear catalogue-action steps. Executed as one multi-step Execution with `source: SDK` (not a soft batch / correlation id). */
+            steps: components["schemas"]["RunStepDto"][];
+            /** @description Project UUID for variable/project scoping. When omitted and the workspace has exactly one project, that project is used. */
+            projectId?: string;
+            /** @description Optional display name for the ad-hoc Execution. */
+            name?: string;
+        };
+        CreateVariableDto: {
+            /** @description Name of the variable. */
+            name: string;
+            /** @description Description of the variable. */
+            description?: string;
+            /**
+             * @description Scope of the variable (system, workspace or project).
+             * @enum {string}
+             */
+            type: "system" | "workspace" | "project";
+            /**
+             * @description Data type of the variable value.
+             * @enum {string}
+             */
+            dataType: "string" | "number" | "boolean" | "date" | "json";
+            /** @description Project ID to scope the variable to. Must belong to the current workspace. */
+            projectId?: string;
+            /** @description Variable value, submitted as a string. Values with dataType `number` are converted to numbers on save. */
+            value: string;
+        };
+        VariableWorkspaceDto: {
+            /** @description Workspace ID. */
+            id: string;
+            /** @description Workspace name. */
+            name: string;
+        };
+        VariableProjectDto: {
+            /** @description Project ID. */
+            id: string;
+            /** @description Project name. */
+            name: string;
+        };
+        VariableResponseDto: {
+            /** @description Variable ID. */
+            id: string;
+            /** @description Variable name. */
+            name: string;
+            /**
+             * @description Data type of the variable value.
+             * @enum {string}
+             */
+            dataType: "string" | "number" | "boolean" | "date" | "json";
+            /**
+             * @description Scope of the variable (system, workspace or project).
+             * @enum {string}
+             */
+            type: "system" | "workspace" | "project";
+            /** @description Variable value. Included when `expansion=value` is requested. */
+            value?: Record<string, never>;
+            /** @description Variable description. Included when `expansion=description` is requested. */
+            description?: string;
+            /**
+             * Format: date-time
+             * @description Creation timestamp. Included when `expansion=createdAt` is requested.
+             */
+            createdAt?: string;
+            /**
+             * Format: date-time
+             * @description Last update timestamp. Included when `expansion=updatedAt` is requested.
+             */
+            updatedAt?: string;
+            /** @description Owning workspace. Included when `expansion=workspace` is requested. */
+            workspace?: components["schemas"]["VariableWorkspaceDto"];
+            /** @description Owning project for project-scoped variables. Included when `expansion=project` is requested. */
+            project?: components["schemas"]["VariableProjectDto"];
+        };
+        UpdateVariableDto: {
+            /** @description Name of the variable. */
+            name?: string;
+            /** @description Description of the variable. */
+            description?: string;
+            /**
+             * @description Scope of the variable (system, workspace or project).
+             * @enum {string}
+             */
+            type?: "system" | "workspace" | "project";
+            /**
+             * @description Data type of the variable value.
+             * @enum {string}
+             */
+            dataType?: "string" | "number" | "boolean" | "date" | "json";
+            /** @description Project ID to scope the variable to. Must belong to the current workspace. */
+            projectId?: string;
+            /** @description Variable value, submitted as a string. Values with dataType `number` are converted to numbers on save. */
+            value?: string;
+        };
+        ConnectionWorkspaceDto: {
+            /** @description Workspace ID. */
+            id: string;
+            /** @description Workspace name. */
+            name: string;
+        };
+        ConnectionResponseDto: {
+            /** @description Connection ID. */
+            id: string;
+            /** @description Connection name. */
+            name: string;
+            /**
+             * Format: date-time
+             * @description Creation timestamp. Included when `expansion=createdAt` is requested.
+             */
+            createdAt?: string;
+            /**
+             * Format: date-time
+             * @description Last update timestamp. Included when `expansion=updatedAt` is requested.
+             */
+            updatedAt?: string;
+            /** @description App connection type ID (e.g. the OAuth2 or API key connection definition of the app). Included when `expansion=connectionId` is requested. */
+            connectionId?: string;
+            /** @description ID of the workflow app this connection belongs to. Included when `expansion=workflowAppId` or `expansion=workflowApp` is requested. */
+            workflowAppId?: string;
+            /** @description Full workflow app definition for this connection. Included when `expansion=workflowApp` is requested on the list endpoint. */
+            workflowApp?: {
+                [key: string]: unknown;
+            };
+            /** @description Owning workspace. Included when `expansion=workspace` is requested. */
+            workspace?: components["schemas"]["ConnectionWorkspaceDto"];
+        };
+        AgentResponseDto: {
+            /**
+             * @description Agent ID (UUID)
+             * @example 4f7c9d2e-8a1b-4c3d-9e5f-6a7b8c9d0e1f
+             */
+            id: string;
+            /**
+             * @description Agent name
+             * @example Invoice Triage Agent
+             */
+            name: string;
+            /** @description Stable project-scoped slug for CLI / code deploy upserts. Included when `expansion=slug` is requested. */
+            slug?: string | null;
+            /** @description True when last written by code (CLI / SDK). Included when `expansion=managedByCode` is requested. */
+            managedByCode?: boolean;
+            /** @description ID of the AI provider connection assigned to the agent. Always included. Null when the agent falls back to the workspace default connection. */
+            FK_aiConnectionId: string | null;
+            /** @description Agent description. Included when `expansion=description` is requested. */
+            description?: string | null;
+            /** @description Public URL of the agent profile image. Included when `expansion=profileImageUrl` is requested. */
+            profileImageUrl?: string | null;
+            /**
+             * Format: date-time
+             * @description Creation timestamp. Included when `expansion=createdAt` is requested.
+             */
+            createdAt?: string;
+            /**
+             * Format: date-time
+             * @description Last update timestamp. Included when `expansion=updatedAt` is requested.
+             */
+            updatedAt?: string;
+            /** @description System instructions authored for the agent. Included when `expansion=instructions` is requested. */
+            instructions?: string | null;
+            /**
+             * @description Model temperature. Included when `expansion=temperature` is requested.
+             * @example 1
+             */
+            temperature?: number;
+            /** @description Maximum output tokens per turn. Included when `expansion=maxOutputTokens` is requested. */
+            maxOutputTokens?: number | null;
+            /**
+             * @description Top-p sampling. Included when `expansion=topP` is requested.
+             * @example 1
+             */
+            topP?: number;
+            /**
+             * @description Frequency penalty. Included when `expansion=frequencyPenalty` is requested.
+             * @example 0
+             */
+            frequencyPenalty?: number;
+            /**
+             * @description Presence penalty. Included when `expansion=presencePenalty` is requested.
+             * @example 0
+             */
+            presencePenalty?: number;
+            /**
+             * @description Maximum retries for a failed model call. Included when `expansion=maxRetries` is requested.
+             * @example 0
+             */
+            maxRetries?: number;
+            /** @description Fixed sampling seed. Included when `expansion=seed` is requested. */
+            seed?: number | null;
+            /**
+             * @description Maximum tool roundtrips per turn. Included when `expansion=maxToolRoundtrips` is requested.
+             * @example 5
+             */
+            maxToolRoundtrips?: number;
+            /**
+             * @description How many previous messages are sent to the model. Included when `expansion=messageLookbackLimit` is requested.
+             * @example 40
+             */
+            messageLookbackLimit?: number;
+            /** @description Configured tool nodes (app actions) for the agent. Included when `expansion=tools` is requested. */
+            tools?: {
+                [key: string]: unknown;
+            }[] | null;
+            /** @description Action IDs of the configured tools. Included when `expansion=toolIds` is requested. */
+            toolIds?: string[];
+            /** @description Instructions used when auto-naming new tasks. Included when `expansion=taskNamingInstructions` is requested. */
+            taskNamingInstructions?: string | null;
+            /** @description IDs of enabled provider built-in tools. Included when `expansion=enabledBuiltInTools` is requested. */
+            enabledBuiltInTools?: string[];
+            /** @description IDs of enabled platform tools. Included when `expansion=enabledPlatformTools` is requested. */
+            enabledPlatformTools?: string[];
+            /** @description Whether dynamic workflow-app action discovery is enabled. Included when `expansion=dynamicActionDiscoveryEnabled` is requested. */
+            dynamicActionDiscoveryEnabled?: boolean;
+            /** @description Whether dynamic MCP server discovery is enabled. Included when `expansion=dynamicMcpDiscoveryEnabled` is requested. */
+            dynamicMcpDiscoveryEnabled?: boolean;
+            /** @description Whether the agent maintains its own instructions. Included when `expansion=dynamicSelfInstructionsEnabled` is requested. */
+            dynamicSelfInstructionsEnabled?: boolean;
+            /** @description Whether long-term memory is enabled. Included when `expansion=memoryEnabled` is requested. */
+            memoryEnabled?: boolean;
+            /**
+             * @description Memory partitioning scope. Included when `expansion=memoryScope` is requested.
+             * @enum {string}
+             */
+            memoryScope?: "PER_USER" | "PER_AGENT" | "PER_USER_PER_AGENT";
+            /**
+             * @description Days memories are retained. Included when `expansion=memoryRetentionDays` is requested.
+             * @example 90
+             */
+            memoryRetentionDays?: number;
+            /** @description Suggested prompts shown to users starting a conversation. Included when `expansion=suggestedPrompts` is requested. */
+            suggestedPrompts?: string[];
+            /**
+             * Format: date-time
+             * @description When the first-time builder setup wizard was completed. Included when `expansion=builderSetupCompletedAt` is requested.
+             */
+            builderSetupCompletedAt?: string | null;
+            /** @description Saved canvas node positions for the agent builder. Included when `expansion=builderCanvasPositions` is requested. */
+            builderCanvasPositions?: {
+                [key: string]: unknown;
+            } | null;
+            /** @description Selected model ID within the AI provider connection. Included when `expansion=selectedModelId` is requested. */
+            selectedModelId?: string | null;
+            /** @description Assigned AI provider connection. Included when `expansion=aiConnection` is requested. */
+            aiConnection?: {
+                id?: string;
+                name?: string;
+                providerConfig?: {
+                    id?: string;
+                    providerSlug?: string;
+                };
+            } | null;
+            /** @description Knowledge notebooks attached to the agent. Included when `expansion=knowledge` is requested. */
+            agentKnowledge?: {
+                id?: string;
+                knowledge?: {
+                    id?: string;
+                    name?: string;
+                };
+            }[];
+            /** @description Object types attached to the agent. Included when `expansion=objectTypes` is requested. */
+            agentObjectTypes?: {
+                id?: string;
+                scope?: string;
+                objectType?: {
+                    id?: string;
+                    name?: string;
+                    slug?: string;
+                    icon?: string | null;
+                    color?: string | null;
+                };
+            }[];
+            /** @description Objects attached to the agent. Included when `expansion=objects` is requested. */
+            agentObjects?: {
+                id?: string;
+                scope?: string;
+                object?: {
+                    id?: string;
+                    name?: string;
+                    state?: string;
+                    objectType?: {
+                        id?: string;
+                        name?: string;
+                        slug?: string;
+                        icon?: string | null;
+                        color?: string | null;
+                    };
+                };
+            }[];
+            /** @description App connections available to the agent. Included when `expansion=connections` is requested. */
+            connections?: {
+                id?: string;
+                name?: string;
+            }[];
+            /** @description Variables attached to the agent. Included when `expansion=variables` is requested. */
+            agentVariables?: {
+                id?: string;
+                variable?: {
+                    id?: string;
+                    name?: string;
+                };
+            }[];
+            /** @description Workflows the agent can trigger. Included when `expansion=workflows` is requested. */
+            agentWorkflows?: {
+                id?: string;
+                workflow?: {
+                    id?: string;
+                    name?: string;
+                };
+            }[];
+            /** @description Sub-agent links for the agent. Included when `expansion=subAgents` is requested. */
+            agentSubAgents?: {
+                id?: string;
+                subagent?: {
+                    id?: string;
+                    name?: string;
+                };
+                parentAgent?: {
+                    id?: string;
+                    name?: string;
+                };
+            }[];
+            /** @description MCP servers attached to the agent, with per-tool overrides. Included when `expansion=mcpServers` is requested. */
+            agentMcpServers?: {
+                id?: string;
+                mcpServer?: {
+                    id?: string;
+                    slug?: string;
+                    name?: string;
+                    provider?: string;
+                    logoUrl?: string | null;
+                    description?: string | null;
+                };
+                toolOverrides?: {
+                    id?: string;
+                    toolName?: string;
+                    enabled?: boolean;
+                    requireApproval?: boolean;
+                }[];
+            }[];
+            /** @description A2A (agent-to-agent) endpoints attached to the agent. Included when `expansion=a2aAgents` is requested. */
+            agentA2aAgents?: {
+                id?: string;
+                a2aAgent?: {
+                    id?: string;
+                    slug?: string;
+                    name?: string;
+                    logoUrl?: string | null;
+                    description?: string | null;
+                    authType?: string;
+                };
+            }[];
+            /** @description Web access configuration. Included when `expansion=webAccess` is requested. */
+            agentWebAccess?: {
+                service?: string;
+                webSearchEnabled?: boolean;
+                websiteAccessEnabled?: boolean;
+            } | null;
+            /** @description Phone access configuration. Included when `expansion=phoneAccess` is requested. */
+            agentPhoneAccess?: {
+                service?: string;
+                outboundCallsEnabled?: boolean;
+                inboundCallsEnabled?: boolean;
+            } | null;
+            /** @description Project the agent belongs to. Included when `expansion=project` is requested. */
+            project?: {
+                id?: string;
+                name?: string;
+            };
+        };
+        UpsertAgentToolDto: {
+            /** @description Workflow app id (catalogue slug). */
+            appId: string;
+            /** @description Catalogue action id. */
+            actionId: string;
+            /** @description Connection instance UUID pre-bound on the tool. */
+            connectionId?: string;
+            /** @description Tool display name for the model. */
+            name?: string;
+            /** @description Tool description shown to the model. */
+            description?: string;
+            /** @description Pre-filled tool config (fields left empty are filled by the model). */
+            input?: {
+                [key: string]: unknown;
+            };
+        };
+        UpsertAgentBySlugDto: {
+            /**
+             * @description Stable project-scoped slug (lowercase, digits, hyphens). Used as the upsert key.
+             * @example support-triage
+             */
+            slug: string;
+            /** @description Display name. Defaults to the slug when omitted. */
+            name?: string;
+            description?: string;
+            /** @description System instructions / prompt for the agent. */
+            instructions: string;
+            /** @description Selected model id on the AI provider connection (e.g. `gpt-4o`). */
+            model: string;
+            /** @description AiProviderConnection UUID. When omitted, platform AI defaults apply. */
+            aiConnectionId?: string;
+            /** @description App Connection UUIDs the agent may use for tools. */
+            connectionIds?: string[];
+            /** @description Workflow UUIDs the agent may run (AgentWorkflow links). */
+            workflowIds?: string[];
+            /** @description Catalogue action tools (WorkflowNodeForRunner-shaped). */
+            tools?: components["schemas"]["UpsertAgentToolDto"][];
+            /** @description Marks the row as managed by code (CLI / SDK). Defaults to true on this endpoint. */
+            managedByCode?: boolean;
+        };
+        TaskListItemResponseDto: {
+            /**
+             * @description Task ID (UUID)
+             * @example 2c8e0f1a-3b4d-4e5f-8a9b-0c1d2e3f4a5b
+             */
+            id: string;
+            /**
+             * @description Task name
+             * @example Summarise the Q3 sales figures
+             */
+            name: string;
+            /** @description True when a UI stream is currently in progress for this task */
+            isStreaming: boolean;
+            /** @description Task description. Included when `expansion=description` is requested. */
+            description?: string | null;
+            /**
+             * Format: date-time
+             * @description Creation timestamp. Included when `expansion=createdAt` is requested.
+             */
+            createdAt?: string;
+            /**
+             * Format: date-time
+             * @description Last update timestamp. Included when `expansion=updatedAt` is requested.
+             */
+            updatedAt?: string;
+            /** @description Conversation messages ordered oldest first. Included when `expansion=messages` is requested. */
+            messages?: {
+                id?: string;
+                /** @description Message content in AI SDK UIMessage part format */
+                content?: {
+                    [key: string]: unknown;
+                } | {
+                    [key: string]: unknown;
+                }[] | string;
+                /** @enum {string} */
+                role?: "system" | "user" | "assistant" | "function" | "data" | "tool";
+                /** Format: date-time */
+                createdAt?: string;
+                data?: {
+                    [key: string]: unknown;
+                } | null;
+            }[];
+            /** @description Agent the task belongs to. Included when `expansion=agent` is requested. The nested `project` is included when `expansion=project` is also requested. */
+            agent?: {
+                id?: string;
+                name?: string;
+                project?: {
+                    id?: string;
+                    name?: string;
+                };
+            };
+        };
+        TaskLatestRunDto: {
+            /**
+             * @description Run ID (also the resumable stream ID)
+             * @example 9b2f4c6d-1e3a-4b5c-8d7e-0f1a2b3c4d5e
+             */
+            id: string;
+            /**
+             * @description Run status
+             * @enum {string}
+             */
+            status: "QUEUED" | "RUNNING" | "COMPLETED" | "FAILED" | "CANCELLED";
+            /** @description Error message when the run failed */
+            errorMessage: string | null;
+            /**
+             * Format: date-time
+             * @description When the run finished
+             */
+            finishedAt: string | null;
+        };
+        TaskResponseDto: {
+            /**
+             * @description Task ID (UUID)
+             * @example 2c8e0f1a-3b4d-4e5f-8a9b-0c1d2e3f4a5b
+             */
+            id: string;
+            /**
+             * @description Task name
+             * @example Summarise the Q3 sales figures
+             */
+            name: string;
+            /** @description True when a UI stream is currently in progress for this task */
+            isStreaming: boolean;
+            /**
+             * Format: date-time
+             * @description Timestamp of the last activity on the task
+             */
+            lastActivityAt: string | null;
+            /** @description Present when a resumable UI stream may still be running. Pass to `GET /agents/:agentId/tasks/:taskId/stream-message` to resume. */
+            activeStreamId?: string;
+            /** @description Durable outcome of the most recent agent-turn run. Omitted when the task has never run. */
+            latestRun?: components["schemas"]["TaskLatestRunDto"];
+            /** @description Task description. Included when `expansion=description` is requested. */
+            description?: string | null;
+            /**
+             * Format: date-time
+             * @description Creation timestamp. Included when `expansion=createdAt` is requested.
+             */
+            createdAt?: string;
+            /**
+             * Format: date-time
+             * @description Last update timestamp. Included when `expansion=updatedAt` is requested.
+             */
+            updatedAt?: string;
+            /** @description Client-supplied deduplication identifier. Included when `expansion=customIdentifier` is requested. */
+            customIdentifier?: string | null;
+            /** @description Conversation messages ordered oldest first. Included when `expansion=messages` is requested. */
+            messages?: {
+                id?: string;
+                /** @description Message content in AI SDK UIMessage part format */
+                content?: {
+                    [key: string]: unknown;
+                } | {
+                    [key: string]: unknown;
+                }[] | string;
+                /** @enum {string} */
+                role?: "system" | "user" | "assistant" | "function" | "data" | "tool";
+                /** Format: date-time */
+                createdAt?: string;
+                data?: {
+                    [key: string]: unknown;
+                } | null;
+            }[];
+            /** @description Agent the task belongs to. Included when `expansion=agent` is requested. The nested `project` is included when `expansion=project` is also requested. */
+            agent?: {
+                id?: string;
+                name?: string;
+                project?: {
+                    id?: string;
+                    name?: string;
+                };
+            };
+        };
+        UpdateTaskDto: {
+            /**
+             * @description New task name
+             * @example Summarise the Q3 sales figures
+             */
+            name?: string;
+            /**
+             * @description New task description
+             * @example Conversation covering the Q3 regional sales report
+             */
+            description?: string;
+        };
+        DeletedTaskResponseDto: {
+            /**
+             * @description Task ID (UUID)
+             * @example 2c8e0f1a-3b4d-4e5f-8a9b-0c1d2e3f4a5b
+             */
+            id: string;
+            /**
+             * Format: date-time
+             * @description Creation timestamp
+             */
+            createdAt: string;
+            /**
+             * Format: date-time
+             * @description Last update timestamp
+             */
+            updatedAt: string;
+            /**
+             * @description Task name
+             * @example Summarise the Q3 sales figures
+             */
+            name: string;
+            /** @description Task description */
+            description: string | null;
+            /** @description ID of the agent the task belonged to */
+            FK_agentId: string;
+            /** @description Client-supplied deduplication identifier */
+            customIdentifier: string | null;
+            /** @description Resumable stream ID that was active when the task was deleted, if any */
+            activeStreamId: string | null;
+            /**
+             * Format: date-time
+             * @description Timestamp of the last activity on the task
+             */
+            lastActivityAt: string | null;
+            /** @description Workspace user who owned the conversation. Null for legacy or builder-created tasks without owner attribution. */
+            FK_ownerWorkspaceUserId: string | null;
+        };
+        CreateTaskDto: {
+            /**
+             * @description Task name shown in the task list
+             * @example Summarise the Q3 sales figures
+             */
+            name: string;
+            /**
+             * @description Optional task description
+             * @example Conversation covering the Q3 regional sales report
+             */
+            description?: string;
+            /**
+             * @description Client-supplied identifier used to deduplicate tasks for an agent. When a task with this identifier already exists, that task is returned instead of creating a new one.
+             * @example crm-ticket-1042
+             */
+            customIdentifier?: string;
+        };
+        MessageTaskDto: {
+            /** @description Conversation messages in AI SDK UI format */
+            messages: {
+                [key: string]: unknown;
+            }[];
+            /**
+             * @description Agent chat mode
+             * @example preview
+             * @enum {string}
+             */
+            chatMode?: "builder" | "preview";
+            /**
+             * @description Optional attachment data for the message
+             * @example {
+             *       "imageUrl": "https://example.com/image.png"
+             *     }
+             */
+            data?: Record<string, never>;
+        };
+        StreamMessageStopDto: {
+            /** @description Partial assistant message to persist when stopping a stream */
+            assistantMessage?: {
+                [key: string]: unknown;
+            };
+        };
+    };
+    responses: never;
+    parameters: never;
+    requestBodies: never;
+    headers: never;
+    pathItems: never;
+}
+
+/**
+ * Friendly aliases over the OpenAPI-generated component schemas
+ * (`src/generated/schema.d.ts`, produced by `npm run codegen:spec`).
+ *
+ * Regenerate the underlying types whenever the deployment's
+ * `openapi.public.json` changes.
+ */
+
+type Schemas = components['schemas'];
+type EnabledFeatures = Schemas['EnabledFeaturesResponseDto'];
+type Project = Schemas['ProjectResponseDto'];
+type CreateProjectInput = Schemas['CreateProjectDto'];
+type Agent = Schemas['AgentResponseDto'];
+type Task = Schemas['TaskResponseDto'];
+type TaskListItem = Schemas['TaskListItemResponseDto'];
+type CreateTaskInput = Schemas['CreateTaskDto'];
+type UpdateTaskInput = Schemas['UpdateTaskDto'];
+type DeletedTask = Schemas['DeletedTaskResponseDto'];
+type Workflow = Schemas['WorkflowResponseDto'];
+type Execution = Schemas['ExecutionResponseDto'];
+type ExecutionPathStep = Schemas['ExecutionPathStepDto'];
+type ExecuteWorkflowResult = Schemas['ExecuteWorkflowResponseDto'];
+type ExecutionStatus = NonNullable<Execution['status']>;
+type PendingInput = Schemas['PendingInputDto'];
+type RunActionResult = Schemas['RunActionResponseDto'];
+type Entity = Schemas['ObjectResponseDto'];
+type PaginatedEntities = Schemas['PaginatedObjectsResponseDto'];
+type CreateEntityInput = Schemas['CreateObjectDto'];
+type UpdateEntityInput = Schemas['UpdateObjectDto'];
+type ChangeEntityStateInput = Schemas['ChangeObjectStateDto'];
+type ChangeEntityStateResult = Schemas['ChangeObjectStateResponseDto'];
+type EntityStateHistoryEntry = Schemas['ObjectStateHistoryEntryResponseDto'];
+type EntityStateTransitions = Schemas['ObjectStateTransitionsResponseDto'];
+type ImportEntitiesResult = Schemas['ImportEntitiesResponseDto'];
+type ImportTemplate = Schemas['ImportTemplateResponseDto'];
+type EntityType = Schemas['ObjectTypeResponseDto'];
+type Knowledge = Schemas['KnowledgeResponseDto'];
+type CreateKnowledgeInput = Schemas['CreateKnowledgeDto'];
+type UpdateKnowledgeInput = Schemas['UpdateKnowledgeDto'];
+type SaveUploadedTextInput = Schemas['SaveUploadedTextToKnowledgeDto'];
+type KnowledgeDocument = Schemas['KnowledgeDocumentResponseDto'];
+type KnowledgeDocumentGroup = Schemas['KnowledgeDocumentGroupResponseDto'];
+type Queue = Schemas['QueueResponseDto'];
+type CreateQueueInput = Schemas['CreateQueueDto'];
+type UpdateQueueInput = Schemas['UpdateQueueDto'];
+type QueueStats = Schemas['QueueStatsResponseDto'];
+type QueueItem = Schemas['QueueItemResponseDto'];
+type QueueItemFull = Schemas['QueueItemFullResponseDto'];
+type CreateQueueItemInput = Schemas['CreateQueueItemDto'];
+type UpdateQueueItemInput = Schemas['UpdateQueueItemDto'];
+type QueueItemList = Schemas['QueueItemListResponseDto'];
+type QueueItemStats = Schemas['QueueItemStatsResponseDto'];
+type BulkCreateQueueItemsInput = Schemas['BulkCreateQueueItemsDto'];
+type BulkCreateQueueItemsResult = Schemas['BulkCreateQueueItemsResponseDto'];
+type QueueItemErrorEntry = Schemas['QueueItemErrorEntryResponseDto'];
+type Variable = Schemas['VariableResponseDto'];
+type CreateVariableInput = Schemas['CreateVariableDto'];
+type UpdateVariableInput = Schemas['UpdateVariableDto'];
+type Connection = Schemas['ConnectionResponseDto'];
+type WorkflowApp = Schemas['WorkflowAppResponseDto'];
+
+type ExecutionStreamEventType = 'connected' | 'heartbeat' | 'execution.progress' | 'execution.finished' | 'execution.error' | 'loop.progress' | string;
+interface ExecutionStreamEvent {
+    event: ExecutionStreamEventType;
+    data: Record<string, unknown>;
+}
+interface WatchProgressOptions {
+    signal?: AbortSignal;
+}
+/**
+ * Opens `GET /api/executions/:id/stream` and yields typed SSE events.
+ * Prefer {@link ExecutionsResource.watchProgress} for timeline UIs.
+ */
+declare class ExecutionProgressStream implements AsyncIterable<ExecutionStreamEvent> {
+    private readonly response;
+    private readonly options?;
+    private consumed;
+    constructor(response: Response, options?: WatchProgressOptions | undefined);
+    [Symbol.asyncIterator](): AsyncGenerator<ExecutionStreamEvent, void, undefined>;
+    events(): AsyncGenerator<ExecutionStreamEvent, void, undefined>;
+}
+
+/**
+ * Standard list-query conventions shared by most Lunnoa list endpoints:
+ *
+ * - `expansion` — comma-separated field names to include beyond the defaults
+ * - `filterBy` — comma-separated `key:value` pairs
+ * - `includeType` — comma-separated inclusion flags (e.g. `all`, `internal`)
+ */
+interface ListQueryOptions {
+    expansion?: string | string[];
+    filterBy?: string | Record<string, string>;
+    includeType?: string | string[];
+}
+
+/**
+ * Read-only catalog of workflow apps and their actions/triggers. Custom UIs
+ * use it to resolve `executionPath` step `appId`/`actionId` pairs to
+ * human-readable names and icons, and to read the declarative
+ * `ActionUIDefinition` metadata for rendering rich action outputs.
+ */
+declare class WorkflowAppsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Lists all workflow apps installed on the deployment. */
+    list(): Promise<WorkflowApp[]>;
+    /**
+     * Creates a connection for an app where the connection type is
+     * non-interactive (API key, basic auth). OAuth connections require the
+     * browser flow inside the bundled UI and cannot be created here.
+     */
+    connect(appId: string, connectionId: string, value: Record<string, unknown>): Promise<unknown>;
+}
+
+interface WaitUntilFinishedOptions {
+    /** Give up after this long. Default: 10 minutes. */
+    timeoutMs?: number;
+    /** First delay between polls. Default: 500ms. */
+    initialDelayMs?: number;
+    /** Cap on the delay between polls. Default: 5s. */
+    maxDelayMs?: number;
+    /** Multiplier applied to the delay after each poll. Default: 1.5. */
+    backoffFactor?: number;
+    /**
+     * Also stop waiting when the execution pauses in `NEEDS_INPUT` (so a form
+     * can be shown). Default: true.
+     */
+    stopOnNeedsInput?: boolean;
+    /** Extra expansion fields to request with each poll (always includes `status,statusMessage,output`). */
+    expansion?: string[];
+    signal?: AbortSignal;
+    /** Injectable sleep, for tests. */
+    sleep?: (ms: number) => Promise<void>;
+}
+/** One step in a timeline-ready progress snapshot. */
+interface ExecutionProgressStep extends ExecutionPathStep {
+    /** App logo URL from the workflow-apps catalogue, when resolvable. */
+    appLogoUrl?: string | null;
+    /** Action/trigger icon URL from the catalogue, when resolvable. */
+    iconUrl?: string | null;
+    /** Duration in ms when both startTime and endTime are present. */
+    durationMs?: number | null;
+}
+/** Timeline-ready progress for a custom UI (status bar / step list). */
+interface ExecutionProgress {
+    executionId: string;
+    status?: ExecutionStatus | string;
+    statusMessage?: string | null;
+    name?: string | null;
+    source?: string | null;
+    startedAt?: string;
+    stoppedAt?: string | null;
+    steps: ExecutionProgressStep[];
+    pendingInput?: unknown;
+    output?: unknown;
+    /** Index of the first non-terminal step, or -1 when all done / unknown. */
+    activeStepIndex: number;
+}
+declare class ExecutionsResource {
+    #private;
+    private readonly http;
+    private readonly workflowApps?;
+    private catalogCache;
+    constructor(http: HttpClient, workflowApps?: WorkflowAppsResource | undefined);
+    /**
+     * Starts a new execution of a workflow. Only the execution ID is returned;
+     * use {@link waitUntilFinished} or `get` to track progress.
+     */
+    execute(workflowId: string, inputData?: Record<string, unknown>): Promise<ExecuteWorkflowResult>;
+    /** Lists executions in the current workspace, most recently started first. */
+    list(options?: ListQueryOptions): Promise<Execution[]>;
+    /**
+     * Returns a single execution. Request `expansion: ['status', 'executionPath']`
+     * for the business-readable step list custom UIs render progress from.
+     */
+    get(executionId: string, options?: Pick<ListQueryOptions, 'expansion'>): Promise<Execution>;
+    /**
+     * Timeline-ready progress: `executionPath` plus catalogue icons/logos.
+     * Use this for a custom status bar / step list (not raw nodes/edges).
+     */
+    getProgress(executionId: string): Promise<ExecutionProgress>;
+    /**
+     * Opens the Public API SSE stream (`GET /executions/:id/stream`).
+     * Yields `execution.progress`, `loop.progress`, `execution.finished`, etc.
+     * For a simple timeline, prefer {@link watchProgress}.
+     */
+    stream(executionId: string, options?: WatchProgressOptions): Promise<ExecutionProgressStream>;
+    /**
+     * Live progress snapshots for a custom timeline UI.
+     * Subscribes to SSE `execution.progress` events (and enriches steps with icons).
+     * Completes when the execution reaches a terminal status or the signal aborts.
+     */
+    watchProgress(executionId: string, options?: WatchProgressOptions): AsyncGenerator<ExecutionProgress, void, undefined>;
+    /**
+     * Polls an execution with exponential backoff until it reaches a terminal
+     * status (`SUCCESS`, `FAILED`, `CANCELLED`) — or pauses in `NEEDS_INPUT`
+     * (unless `stopOnNeedsInput: false`). Resolves with the final execution
+     * including `status`, `statusMessage`, and `output`.
+     */
+    waitUntilFinished(executionId: string, options?: WaitUntilFinishedOptions): Promise<Execution>;
+    /**
+     * Resumes an execution paused in `NEEDS_INPUT` by submitting values for the
+     * waiting node. Identify the waiting node and its field schema via
+     * `expansion: ['pendingInput', 'executionPath']` (prefer `pendingInput` for
+     * the form contract; `executionPath` steps with status `NEEDS_INPUT` also
+     * carry the `nodeId`). Required fields from the schema must be present.
+     * The server acknowledges immediately and resumes asynchronously — follow
+     * up with {@link waitUntilFinished}.
+     */
+    submitInput(executionId: string, nodeId: string, values: Record<string, unknown>): Promise<void>;
+    /**
+     * Submit an approve/reject decision for a Request Approval node.
+     * Uses the authenticated Approvals API (not the public input webhook).
+     * Partial approvals keep the execution paused; terminal decisions resume it.
+     */
+    submitApproval(executionId: string, nodeId: string, body: {
+        decision: 'approved' | 'rejected';
+        comment?: string;
+    }): Promise<{
+        executionId: string;
+        nodeId: string;
+        approvalId?: string;
+        terminal: boolean;
+        canDecide: boolean;
+        approval: Record<string, unknown>;
+    }>;
+}
+
+interface RunActionOptions {
+    /** Workflow app id (catalogue slug), e.g. `http`, `gmail`. */
+    appId: string;
+    /** Action id within the app, e.g. `http_action_send-request`. */
+    actionId: string;
+    /**
+     * Connection instance UUID (`Connection.id`). Required when the action needs
+     * a connection and the workspace has more than one for the app. When omitted
+     * and exactly one connection exists, the platform uses that connection.
+     */
+    connectionId?: string;
+    /**
+     * Project UUID for variable/project scoping. Required when the workspace has
+     * more than one project.
+     */
+    projectId?: string;
+    /** Action input fields (keys from the action `inputConfig`). */
+    input?: Record<string, unknown>;
+    /** Optional display name for the ad-hoc Execution. */
+    name?: string;
+}
+declare class ActionsResource {
+    private readonly http;
+    private readonly executions;
+    constructor(http: HttpClient, executions: ExecutionsResource);
+    /**
+     * Run a single catalogue action as a one-step ad-hoc Execution (`source: SDK`).
+     *
+     * The platform runs the action synchronously and returns the execution id
+     * plus status/output/executionPath. You can also poll
+     * {@link ExecutionsResource.get} / {@link ExecutionsResource.waitUntilFinished}
+     * with the returned id.
+     *
+     * Discover `appId` / `actionId` / `inputConfig` via `workflowApps.list()`.
+     */
+    run(options: RunActionOptions): Promise<RunActionResult>;
+    /**
+     * Convenience: run the action and wait until the Execution reaches a
+     * terminal status (or pauses in `NEEDS_INPUT`). Prefer {@link run} when the
+     * synchronous response is enough.
+     */
+    runAndWait(options: RunActionOptions, waitOptions?: WaitUntilFinishedOptions): Promise<Execution>;
+    /**
+     * Thin discovery helper: find one action definition from `workflowApps.list()`.
+     * Prefer calling `workflowApps.list()` once and caching when looking up many
+     * actions.
+     */
+    get(appId: string, actionId: string): Promise<Record<string, unknown> | undefined>;
+}
+
+/**
+ * Pure typed definition factories for local workflow/agent authoring.
+ * These do not call the network. Deploy with the CLI; run ad-hoc with `runs.start`.
+ *
+ * Not the same as `@lunnoa/toolkit` `createAction` / `createApp` (in-platform apps).
+ */
+declare const DEFINE_KINDS: {
+    readonly connection: "connection";
+    readonly aiConnection: "aiConnection";
+    readonly action: "action";
+    readonly workflow: "workflow";
+    readonly agent: "agent";
+};
+/** Ref to an existing app Connection (credentials stay on Lunnoa). */
+interface ConnectionDefinition {
+    kind: typeof DEFINE_KINDS.connection;
+    /** Connection instance UUID. Optional when the platform can resolve sole/default. */
+    id?: string;
+}
+/** Ref to an existing AiProviderConnection. */
+interface AiConnectionDefinition {
+    kind: typeof DEFINE_KINDS.aiConnection;
+    /** AiProviderConnection UUID. Optional when platform AI defaults apply. */
+    id?: string;
+}
+interface ActionDefinition {
+    kind: typeof DEFINE_KINDS.action;
+    /**
+     * Catalogue action id, e.g. `http_action_send-request`.
+     * Optionally `appId.actionId` (first segment before `.` used as appId when
+     * `appId` is omitted and the id contains a dot that is not part of the
+     * usual `_action_` pattern).
+     */
+    id: string;
+    /** Workflow app id. Inferred from `id` when it matches `{app}_action_…`. */
+    appId?: string;
+    /** Optional Connection ref. Omit to let the platform resolve. */
+    connection?: ConnectionDefinition;
+    /** Default input merged at run/deploy time. */
+    input?: Record<string, unknown>;
+    name?: string;
+    description?: string;
+}
+interface WorkflowStepDefinition {
+    /** Action definition (or inline action-shaped object). */
+    use: ActionDefinition;
+    /** Per-step input overrides. */
+    input?: Record<string, unknown>;
+    name?: string;
+}
+interface WorkflowDefinition {
+    kind: typeof DEFINE_KINDS.workflow;
+    /** Stable project-scoped slug (upsert key). */
+    slug: string;
+    name?: string;
+    description?: string;
+    isActive?: boolean;
+    /** Linear steps (v1; no branches). */
+    steps: WorkflowStepDefinition[];
+}
+type AgentToolDefinition = ActionDefinition | WorkflowDefinition | {
+    use: ActionDefinition | WorkflowDefinition;
+};
+interface AgentDefinition {
+    kind: typeof DEFINE_KINDS.agent;
+    /** Stable project-scoped slug (upsert key). */
+    slug: string;
+    name?: string;
+    description?: string;
+    /** Selected model id on the AI provider connection. */
+    model: string;
+    instructions: string;
+    aiConnection?: AiConnectionDefinition;
+    /** App Connection refs the agent may use for tools. */
+    connections?: ConnectionDefinition[];
+    /** Action and/or workflow tool refs. */
+    tools?: AgentToolDefinition[];
+}
+
+interface UpsertAgentToolInput {
+    appId: string;
+    actionId: string;
+    connectionId?: string;
+    name?: string;
+    description?: string;
+    input?: Record<string, unknown>;
+}
+interface UpsertAgentBySlugInput {
+    slug: string;
+    name?: string;
+    description?: string;
+    instructions: string;
+    model: string;
+    aiConnectionId?: string;
+    connectionIds?: string[];
+    workflowIds?: string[];
+    tools?: UpsertAgentToolInput[];
+    managedByCode?: boolean;
+}
+declare class AgentsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Lists agents visible to the caller in the current workspace. */
+    list(options?: ListQueryOptions): Promise<Agent[]>;
+    /** Returns a single agent. */
+    get(agentId: string, options?: Pick<ListQueryOptions, 'expansion'>): Promise<Agent>;
+    /**
+     * Upsert an agent by project-scoped slug.
+     * Prefer the CLI (`npx @lunnoa/client agents deploy`) for happy-path deploy.
+     */
+    upsertBySlug(projectId: string, body: UpsertAgentBySlugInput | AgentDefinition, options?: {
+        workflowIds?: string[];
+    }): Promise<Agent>;
+}
+
+/**
+ * Tokens returned by login / 2FA / login-with-token.
+ * Mapped from the wire format (`access_token` / `refresh_token`).
+ */
+interface AuthTokens {
+    accessToken: string;
+    refreshToken: string;
+}
+/** Successful password login without 2FA, or after 2FA / token exchange. */
+type LoginSuccess = AuthTokens;
+/**
+ * Password login when the user has 2FA enabled.
+ * Call {@link AuthResource.verify2faLogin} with the session token and TOTP/backup code.
+ */
+interface LoginRequires2FA {
+    requires2FA: true;
+    sessionToken: string;
+}
+type LoginResult = LoginSuccess | LoginRequires2FA;
+/** Public SSO discovery from `GET /api/auth/sso/providers`. */
+interface SsoProvidersResponse {
+    providers: SsoProviderSummary[];
+    passwordAuthDisabled: boolean;
+    googleAuthDisabled: boolean;
+    ssoEnforced: boolean;
+}
+interface SsoProviderSummary {
+    id: string;
+    name: string;
+    buttonLabel: string | null;
+}
+/**
+ * Current user from `GET /api/users/me`.
+ * Password is never returned.
+ */
+interface CurrentUser {
+    id: string;
+    email: string;
+    name: string | null;
+    createdAt?: string;
+    updatedAt?: string;
+    rootProfileImageUrl?: string | null;
+    emailVerifiedAt?: string | null;
+    toursCompleted?: unknown;
+    hasPassword?: boolean;
+    ssoProviders?: string[];
+}
+
+/**
+ * Login, refresh, SSO discovery, and session helpers for Pattern B.
+ *
+ * Password login, token exchange, refresh, and SSO provider listing are
+ * **public** endpoints (no Bearer). `me()` requires a user JWT.
+ *
+ * There is no server logout endpoint: {@link AuthResource.logout} only clears
+ * the configured {@link TokenStore}.
+ */
+declare class AuthResource {
+    private readonly http;
+    private readonly tokenStore?;
+    readonly sso: SsoAuthResource;
+    constructor(http: HttpClient, tokenStore?: TokenStore | undefined);
+    /**
+     * `POST /api/auth/login`
+     *
+     * On success without 2FA, tokens are written to the token store (when set).
+     * When 2FA is required, returns `{ requires2FA, sessionToken }` and does not
+     * store tokens until {@link verify2faLogin} succeeds.
+     */
+    login(input: {
+        email: string;
+        password: string;
+    }): Promise<LoginResult>;
+    /**
+     * `POST /api/auth/2fa/verify-login`
+     *
+     * Completes password login after TOTP or backup-code verification.
+     */
+    verify2faLogin(input: {
+        sessionToken: string;
+        token: string;
+    }): Promise<AuthTokens>;
+    /**
+     * `POST /api/auth/login-with-token`
+     *
+     * Exchanges a short-lived hidden JWT (SSO callback or email verification)
+     * for access and refresh tokens.
+     */
+    loginWithToken(input: {
+        token: string;
+    }): Promise<AuthTokens>;
+    /**
+     * `POST /api/auth/refresh-token`
+     *
+     * Returns a new access token. The refresh token itself is not rotated.
+     * When a token store is configured and `refreshToken` is omitted, the
+     * stored refresh token is used.
+     */
+    refresh(input?: {
+        refreshToken?: string;
+    }): Promise<{
+        accessToken: string;
+    }>;
+    /**
+     * `GET /api/users/me` — current user profile for the active JWT.
+     */
+    me(): Promise<CurrentUser>;
+    /**
+     * Clears tokens from the token store.
+     * There is no server-side logout endpoint; access tokens remain valid until expiry
+     * (or until the user's `tokensValidFrom` watermark invalidates them).
+     */
+    logout(): Promise<void>;
+    /** True when the token store has an access token (sync stores only wait on Promise). */
+    hasSession(): Promise<boolean>;
+    private persistTokens;
+}
+/**
+ * SSO discovery and login URL helpers.
+ *
+ * Browser SSO callbacks redirect to the deployment's `CLIENT_URL/verify-token`,
+ * not to an arbitrary custom origin. Custom portals typically complete the
+ * exchange with {@link AuthResource.loginWithToken} after receiving the hidden
+ * token (for example via a BFF that can see the verify-token page, or by
+ * setting `CLIENT_URL` to the custom app).
+ */
+declare class SsoAuthResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** `GET /api/auth/sso/providers` (public). */
+    listProviders(): Promise<SsoProvidersResponse>;
+    /**
+     * Absolute URL for `GET /api/auth/sso/:providerId/login`.
+     * Navigate the browser here to start the OIDC redirect.
+     */
+    getLoginUrl(providerId: string): string;
+}
+
+declare class ConnectionsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Lists connections in the workspace. */
+    list(options?: ListQueryOptions): Promise<Connection[]>;
+    /** Returns a single connection (secrets are never included). */
+    get(connectionId: string, options?: Pick<ListQueryOptions, 'expansion'>): Promise<Connection>;
+}
+
+declare class DiscoveryResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Returns the deployment's feature flags (storage, vector database, email,
+     * SSO, edition gating), letting a custom UI adapt to what is enabled.
+     */
+    enabledFeatures(): Promise<EnabledFeatures>;
+}
+
+interface ListEntitiesOptions {
+    /** Filter by entity type ID. */
+    objectTypeId?: string;
+    /** Filter by entity type slug (alternative to objectTypeId). */
+    objectTypeSlug?: string;
+    /** Filter by a single state. */
+    state?: string;
+    /** Filter by several states (comma-separated server-side). */
+    states?: string[];
+    /** Filter by owner workspace-user ID. */
+    ownerId?: string;
+    /** Free-text search over entity names. */
+    search?: string;
+    sortBy?: string;
+    sortOrder?: 'asc' | 'desc';
+    /** 1-based page number. */
+    page?: number;
+    /** Items per page (max 100). */
+    pageSize?: number;
+    /** Fields to expand, e.g. `['attributes', 'objectType']`. */
+    expansion?: string | string[];
+}
+interface ImportEntitiesInput {
+    entityTypeId: string;
+    columnMappings: Array<{
+        sourceColumn: string;
+        targetFieldId: string;
+        transform?: 'none' | 'date' | 'number' | 'boolean';
+    }>;
+    rows: Array<Record<string, string>>;
+    updateExisting?: boolean;
+    matchField?: string;
+}
+interface ExportEntitiesInput {
+    entityTypeId: string;
+    fieldIds: string[];
+    filters?: Array<{
+        fieldId: string;
+        operator: string;
+        value: unknown;
+    }>;
+    format?: 'csv' | 'xlsx';
+    includeRelatedEntityNames?: boolean;
+}
+/**
+ * Entities (the platform calls them Objects internally): the structured data
+ * layer custom UIs query heavily. Attribute values are keyed by field ID as
+ * defined on the entity type's `attributeSchema` — run
+ * `npx @lunnoa/client codegen` against your deployment for fully typed,
+ * per-entity-type accessors.
+ */
+declare class EntitiesResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Returns one page of entities matching the filter. */
+    list(options?: ListEntitiesOptions): Promise<PaginatedEntities>;
+    /**
+     * Async-iterates every entity matching the filter, fetching pages lazily.
+     *
+     * ```ts
+     * for await (const invoice of client.entities.iterate({ objectTypeSlug: 'invoice' })) { ... }
+     * ```
+     */
+    iterate(options?: Omit<ListEntitiesOptions, 'page'>): AsyncGenerator<Entity, void, undefined>;
+    /** Returns a single entity. Request `expansion: ['attributes']` for field values. */
+    get(entityId: string, options?: {
+        expansion?: string | string[];
+    }): Promise<Entity>;
+    /** Creates an entity. `attributes` are keyed by field ID. */
+    create(data: CreateEntityInput, options?: {
+        expansion?: string | string[];
+    }): Promise<Entity>;
+    /** Partially updates an entity; supplied attributes are merged. */
+    update(entityId: string, data: UpdateEntityInput, options?: {
+        expansion?: string | string[];
+    }): Promise<Entity>;
+    /** Soft-deletes an entity. */
+    delete(entityId: string): Promise<boolean>;
+    /** Moves an entity to a new state (validated against the type's state machine). */
+    changeState(entityId: string, data: ChangeEntityStateInput): Promise<ChangeEntityStateResult>;
+    /** Returns the entity's state changes, newest first. */
+    getStateHistory(entityId: string, options?: {
+        limit?: number;
+    }): Promise<EntityStateHistoryEntry[]>;
+    /** Returns the current state and the transitions allowed from it. */
+    getStateTransitions(entityId: string): Promise<EntityStateTransitions>;
+    /** Imports pre-parsed rows into an entity type (SuperAdmin only). */
+    import(data: ImportEntitiesInput): Promise<ImportEntitiesResult>;
+    /** Exports entities of a type as flat JSON rows. */
+    export(data: ExportEntitiesInput): Promise<Array<Record<string, unknown>>>;
+    /** Returns the column headers and a sample row for importing (SuperAdmin only). */
+    getImportTemplate(entityTypeId: string): Promise<ImportTemplate>;
+    private serializeListOptions;
+}
+
+interface EntityTypeReadOptions {
+    /** Fields to expand, e.g. `['attributeSchema', 'stateSchema', 'description']`. */
+    expansion?: string | string[];
+}
+declare class EntityTypesResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Lists entity types in the workspace. Request
+     * `expansion: ['attributeSchema', 'stateSchema']` for the field and state
+     * machine definitions the codegen CLI builds types from.
+     */
+    list(options?: EntityTypeReadOptions & {
+        includeDisabled?: boolean;
+    }): Promise<EntityType[]>;
+    /** Returns a single entity type by ID. */
+    get(id: string, options?: EntityTypeReadOptions): Promise<EntityType>;
+    /** Returns a single entity type by its URL-safe slug. */
+    getBySlug(slug: string, options?: EntityTypeReadOptions): Promise<EntityType>;
+}
+
+type EligibleApprover = {
+    workspaceUserId: string;
+    email: string;
+    name?: string;
+};
+type ApprovalInboxItem = {
+    approvalId: string;
+    executionId: string;
+    nodeId: string;
+    title: string;
+    status: string;
+    requiredCount: number;
+    receivedApprovals: number;
+    currentStageIndex?: number;
+    expiresAt?: string;
+    createdAt?: string;
+    updatedAt?: string;
+    canDecide?: boolean;
+    executionNumber?: number;
+    workflow?: {
+        id: string;
+        name: string;
+    };
+    project?: {
+        id: string;
+        name: string;
+    };
+    myDecision?: {
+        decision: string;
+        comment?: string;
+        decidedAt?: string;
+    };
+    /** People who can still decide (current stage; emails resolved). */
+    eligibleApprovers?: EligibleApprover[];
+    approval?: Record<string, unknown>;
+};
+/**
+ * Authenticated Approvals inbox helpers (workspace API; not Public API v1).
+ */
+declare class ApprovalsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * @param options.status `pending` (default) for actionable items, or `done` for history.
+     */
+    inbox(options?: {
+        status?: 'pending' | 'done' | string;
+    }): Promise<{
+        items: ApprovalInboxItem[];
+    }>;
+    decide(approvalId: string, body: {
+        decision: 'approved' | 'rejected';
+        comment?: string;
+    }): Promise<{
+        executionId: string;
+        nodeId: string;
+        approvalId?: string;
+        terminal: boolean;
+        canDecide: boolean;
+        approval: Record<string, unknown>;
+    }>;
+}
+
+declare class KnowledgeResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Lists knowledge notebooks in the workspace. */
+    list(options?: {
+        expansion?: string | string[];
+    }): Promise<Knowledge[]>;
+    /** Returns a single knowledge notebook. */
+    get(knowledgeId: string, options?: {
+        expansion?: string | string[];
+    }): Promise<Knowledge>;
+    /** Creates a knowledge notebook. Subject to the deployment's storage/vector infrastructure. */
+    create(data: CreateKnowledgeInput): Promise<Knowledge>;
+    /** Updates a knowledge notebook. */
+    update(knowledgeId: string, data: UpdateKnowledgeInput): Promise<Knowledge>;
+    /** Deletes a knowledge notebook. */
+    delete(knowledgeId: string): Promise<boolean>;
+    /** Saves raw text into the notebook (chunked, embedded, and indexed server-side). */
+    saveUploadedText(knowledgeId: string, data: SaveUploadedTextInput): Promise<unknown>;
+    /** Lists the documents stored in a notebook. */
+    listDocuments(knowledgeId: string): Promise<KnowledgeDocument[]>;
+    /** Returns one document group (an uploaded document and its chunks). */
+    getDocumentGroup(knowledgeId: string, groupId: string): Promise<KnowledgeDocumentGroup>;
+    /** Deletes one document group from the notebook. */
+    deleteDocumentGroup(knowledgeId: string, groupId: string): Promise<boolean>;
+}
+
+declare class ProjectsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Lists projects in the workspace, most recently updated first. */
+    list(options?: ListQueryOptions): Promise<Project[]>;
+    /** Returns a single project. */
+    get(projectId: string, options?: Pick<ListQueryOptions, 'expansion'>): Promise<Project>;
+    /** Creates a project. */
+    create(data: CreateProjectInput): Promise<Project>;
+}
+
+interface ListQueueItemsOptions {
+    limit?: number;
+    offset?: number;
+    expansion?: string | string[];
+    filterBy?: string | Record<string, string>;
+}
+declare class QueueItemsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Returns one page of items in a queue (offset-based pagination). */
+    list(queueId: string, options?: ListQueueItemsOptions): Promise<QueueItemList>;
+    /** Async-iterates every item in a queue, fetching batches lazily. */
+    iterate(queueId: string, options?: Omit<ListQueueItemsOptions, 'offset'>): AsyncGenerator<QueueItem, void, undefined>;
+    /** Returns a single queue item. */
+    get(queueId: string, itemId: string): Promise<QueueItemFull>;
+    /** Adds an item to a queue. */
+    create(queueId: string, data: CreateQueueItemInput): Promise<QueueItem>;
+    /** Adds many items to a queue in one call. */
+    bulkCreate(queueId: string, data: BulkCreateQueueItemsInput): Promise<BulkCreateQueueItemsResult>;
+    /** Updates a queue item. */
+    update(queueId: string, itemId: string, data: UpdateQueueItemInput): Promise<QueueItem>;
+    /** Deletes a queue item. */
+    delete(queueId: string, itemId: string): Promise<{
+        success: boolean;
+    }>;
+    /** Returns items that are ready to be processed. */
+    listReady(queueId: string, options?: {
+        limit?: number;
+    }): Promise<QueueItem[]>;
+    /** Returns items eligible for retry. */
+    listRetryable(queueId: string): Promise<QueueItem[]>;
+    /** Returns items with the given status. */
+    listByStatus(queueId: string, status: string): Promise<QueueItem[]>;
+    /** Looks an item up by the external ID your system supplied. */
+    getByExternalId(queueId: string, externalId: string): Promise<QueueItemFull>;
+    /** Searches items in the queue. */
+    search(queueId: string, query: string): Promise<QueueItem[]>;
+    /** Returns per-status and per-priority counts for the queue. */
+    stats(queueId: string): Promise<QueueItemStats>;
+    /** Returns the recorded processing errors of an item. */
+    listErrors(queueId: string, itemId: string): Promise<QueueItemErrorEntry[]>;
+    /** Updates the processing status of an item. */
+    updateStatus(queueId: string, itemId: string, status: string): Promise<QueueItem>;
+    /** Links an item to the workflow execution that processed it. */
+    linkExecution(queueId: string, itemId: string, executionId: string): Promise<QueueItem>;
+    /** Queues the item for another processing attempt. */
+    retry(queueId: string, itemId: string): Promise<QueueItem>;
+    /** Records a processing error on the item. */
+    addError(queueId: string, itemId: string, error: {
+        message: string;
+        [key: string]: unknown;
+    }): Promise<QueueItem>;
+}
+
+declare class QueuesResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Lists queues in the workspace, ordered by priority then creation date. */
+    list(options?: ListQueryOptions): Promise<Queue[]>;
+    /** Returns a single queue. */
+    get(queueId: string, options?: Pick<ListQueryOptions, 'expansion'>): Promise<Queue>;
+    /** Creates a queue. */
+    create(data: CreateQueueInput): Promise<Queue>;
+    /** Updates a queue. */
+    update(queueId: string, data: UpdateQueueInput): Promise<Queue>;
+    /** Deletes a queue. */
+    delete(queueId: string): Promise<{
+        success: boolean;
+    }>;
+    /** Returns aggregate statistics for a queue. */
+    stats(queueId: string): Promise<QueueStats>;
+    /** Activates a queue. */
+    activate(queueId: string): Promise<Queue>;
+    /** Deactivates a queue. */
+    deactivate(queueId: string): Promise<Queue>;
+}
+
+interface StartRunStep {
+    appId: string;
+    actionId: string;
+    connectionId?: string;
+    input?: Record<string, unknown>;
+    name?: string;
+}
+interface StartRunOptions {
+    steps: StartRunStep[];
+    projectId?: string;
+    name?: string;
+}
+type StartRunInput = StartRunOptions | WorkflowDefinition | WorkflowStepDefinition[] | StartRunStep[];
+/**
+ * Multi-step ad-hoc runs (`POST /api/runs`) → one Execution with `source: SDK`.
+ */
+declare class RunsResource {
+    private readonly http;
+    private readonly executions;
+    constructor(http: HttpClient, executions: ExecutionsResource);
+    /**
+     * Start a linear multi-step ad-hoc Execution.
+     *
+     * Accepts a `defineWorkflow` result, a step array, or an explicit
+     * `{ steps, projectId?, name? }` payload.
+     */
+    start(input: StartRunInput): Promise<RunActionResult>;
+    /** Convenience: start and wait until terminal / NEEDS_INPUT. */
+    startAndWait(input: StartRunInput, waitOptions?: WaitUntilFinishedOptions): Promise<Execution>;
+}
+
+declare class TasksResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Lists tasks (conversation threads) visible to the caller, most recently updated first. */
+    list(options?: ListQueryOptions): Promise<TaskListItem[]>;
+    /** Returns a single task. Request `expansion: ['messages']` for the conversation history. */
+    get(taskId: string, options?: Pick<ListQueryOptions, 'expansion'>): Promise<Task>;
+    /** Creates a task (conversation thread) for an agent. */
+    create(agentId: string, data: CreateTaskInput, options?: Pick<ListQueryOptions, 'expansion'>): Promise<Task>;
+    /** Updates the task name or description. */
+    update(taskId: string, data: UpdateTaskInput, options?: Pick<ListQueryOptions, 'expansion'>): Promise<Task>;
+    /** Permanently deletes a task and its messages. */
+    delete(taskId: string): Promise<DeletedTask>;
+    /**
+     * Sends a message to an agent task and waits for the full agent turn to
+     * finish (non-streaming). Returns either a plain string or the assistant
+     * messages in AI SDK UIMessage format. For token-by-token output use
+     * `client.agentChat.streamMessage` instead.
+     */
+    message(agentId: string, taskId: string, message: string | UIMessage, options?: {
+        chatMode?: ChatMode;
+    }): Promise<string | UIMessage[]>;
+}
+
+declare class VariablesResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Lists variables in the workspace. */
+    list(options?: ListQueryOptions): Promise<Variable[]>;
+    /** Returns a single variable. */
+    get(variableId: string, options?: Pick<ListQueryOptions, 'expansion'>): Promise<Variable>;
+    /** Creates a variable. */
+    create(data: CreateVariableInput): Promise<Variable>;
+    /** Updates a variable. */
+    update(variableId: string, data: UpdateVariableInput): Promise<Variable>;
+    /** Deletes a variable. */
+    delete(variableId: string): Promise<boolean>;
+}
+
+interface UpsertWorkflowStepInput {
+    appId: string;
+    actionId: string;
+    connectionId?: string;
+    input?: Record<string, unknown>;
+    name?: string;
+    description?: string;
+}
+interface UpsertWorkflowBySlugInput {
+    slug: string;
+    name?: string;
+    description?: string;
+    isActive?: boolean;
+    steps: UpsertWorkflowStepInput[];
+    managedByCode?: boolean;
+}
+declare class WorkflowsResource {
+    private readonly http;
+    private readonly executions;
+    constructor(http: HttpClient, executions: ExecutionsResource);
+    /** Lists workflows in the current workspace. */
+    list(options?: ListQueryOptions): Promise<Workflow[]>;
+    /**
+     * Returns a single workflow. Request `expansion: ['triggerNode']` to read
+     * the manual trigger's custom input field definitions.
+     */
+    get(workflowId: string, options?: Pick<ListQueryOptions, 'expansion'>): Promise<Workflow>;
+    /**
+     * Upsert a workflow by project-scoped slug from a linear step list.
+     * Prefer the CLI (`npx @lunnoa/client workflows deploy`) for happy-path deploy.
+     */
+    upsertBySlug(projectId: string, body: UpsertWorkflowBySlugInput | WorkflowDefinition): Promise<Workflow>;
+    /**
+     * Starts a new execution of the workflow with the given trigger inputs.
+     * Returns immediately with the execution ID.
+     */
+    execute(workflowId: string, inputs?: Record<string, unknown>): Promise<ExecuteWorkflowResult>;
+    /**
+     * Convenience: execute the workflow and wait (poll with backoff) until it
+     * reaches a terminal status or pauses in `NEEDS_INPUT`.
+     */
+    executeAndWait(workflowId: string, inputs?: Record<string, unknown>, waitOptions?: WaitUntilFinishedOptions): Promise<Execution>;
+    /**
+     * Triggers a workflow through its unauthenticated custom webhook endpoint
+     * (`POST /api/webhooks/workflows/:workflowId`). Only works for workflows
+     * with a webhook trigger. Returns the synchronous trigger output when the
+     * workflow responds synchronously.
+     */
+    triggerWebhook(workflowId: string, payload?: Record<string, unknown>): Promise<Record<string, unknown> | undefined>;
+}
+
+/**
+ * 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):
+ * ```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.
+ */
+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). */
+    readonly auth: AuthResource;
+    readonly agents: AgentsResource;
+    readonly tasks: TasksResource;
+    /** Hand-written SSE streaming client for agent chat (AI SDK UIMessage chunks). */
+    readonly agentChat: AgentChatClient;
+    readonly workflows: WorkflowsResource;
+    readonly executions: ExecutionsResource;
+    /** Run catalogue actions as one-step ad-hoc Executions (`source: SDK`). */
+    readonly actions: ActionsResource;
+    /**
+     * Multi-step ad-hoc Executions (`source: SDK`) via `POST /api/runs`.
+     * Prefer `defineWorkflow` + `runs.start` for local linear chains.
+     */
+    readonly runs: RunsResource;
+    /** Authenticated Approvals inbox (workspace API). */
+    readonly approvals: ApprovalsResource;
+    readonly entities: EntitiesResource;
+    readonly entityTypes: EntityTypesResource;
+    readonly knowledge: KnowledgeResource;
+    readonly queues: QueuesResource;
+    readonly queueItems: QueueItemsResource;
+    readonly variables: VariablesResource;
+    readonly connections: ConnectionsResource;
+    readonly projects: ProjectsResource;
+    readonly workflowApps: WorkflowAppsResource;
+    readonly discovery: DiscoveryResource;
+    constructor(options: LunnoaClientOptions);
+}
+
+interface CreateBrowserClientOptions {
+    /** Base URL of the Lunnoa Automate deployment. */
+    baseUrl: string;
+    /**
+     * JWT store. Defaults to `localStorage` keys `accessToken` / `refreshToken`
+     * (same as the built-in Automate UI).
+     */
+    tokenStore?: TokenStore;
+    /**
+     * Retry once after `POST /api/auth/refresh-token` on 401.
+     * Defaults to true.
+     */
+    autoRefresh?: boolean;
+    fetch?: FetchLike;
+    headers?: Record<string, string>;
+}
+
+type AuthStatus = 'loading' | 'authenticated' | 'unauthenticated';
+interface LunnoaAuthContextValue {
+    /** Shared Lunnoa client (Pattern B token store). */
+    client: LunnoaClient;
+    /** Current user from `GET /api/users/me`, or null when signed out. */
+    user: CurrentUser | null;
+    /** Session bootstrap / mutation status. */
+    status: AuthStatus;
+    /** Last auth error message, if any. */
+    error: string | null;
+    /**
+     * Password login. May return `{ requires2FA, sessionToken }` — then call
+     * {@link verify2faLogin}. On success, refreshes `user`.
+     */
+    login: (input: {
+        email: string;
+        password: string;
+    }) => Promise<LoginResult>;
+    /** Completes password login when 2FA is required. */
+    verify2faLogin: (input: {
+        sessionToken: string;
+        token: string;
+    }) => Promise<CurrentUser>;
+    /**
+     * Exchanges an SSO / email-verification hidden JWT (from verify-token URL).
+     */
+    loginWithToken: (input: {
+        token: string;
+    }) => Promise<CurrentUser>;
+    /**
+     * Returns the OIDC start URL for a provider. Navigate the browser there
+     * (e.g. `window.location.assign(url)`).
+     */
+    getSsoLoginUrl: (providerId: string) => string;
+    /** Lists public SSO providers for the login screen. */
+    listSsoProviders: () => Promise<SsoProvidersResponse>;
+    /** Clears the token store and local user state. */
+    logout: () => Promise<void>;
+    /** Re-fetches `auth.me()` when a session exists. */
+    refreshUser: () => Promise<CurrentUser | null>;
+    /** Current access token from the token store (for AI SDK headers, etc.). */
+    getAccessToken: () => Promise<string | null>;
+}
+type LunnoaAuthProviderProps = {
+    /** Existing Pattern B client (from `createBrowserClient`). */
+    client: LunnoaClient;
+    children: ReactNode;
+} | (CreateBrowserClientOptions & {
+    client?: undefined;
+    children: ReactNode;
+});
+/**
+ * Provides a Pattern B Lunnoa client and session helpers to React trees.
+ *
+ * ```tsx
+ * <LunnoaAuthProvider baseUrl={import.meta.env.VITE_LUNNOA_URL}>
+ *   <App />
+ * </LunnoaAuthProvider>
+ * ```
+ */
+declare function LunnoaAuthProvider(props: LunnoaAuthProviderProps): react.FunctionComponentElement<react.ProviderProps<LunnoaAuthContextValue | null>>;
+/** Full auth session API for Pattern B React apps. */
+declare function useLunnoaAuth(): LunnoaAuthContextValue;
+/** The Lunnoa client from the nearest {@link LunnoaAuthProvider}. */
+declare function useLunnoaClient(): LunnoaClient;
+/**
+ * Current access token from the provider's token store.
+ * Useful for AI SDK `useChat` / `DefaultChatTransport` Authorization headers.
+ */
+declare function useAccessToken(): {
+    getAccessToken: () => Promise<string | null>;
+    status: AuthStatus;
+};
+
+type ExecutionProgressStatus = 'idle' | 'loading' | 'live' | 'error' | 'finished';
+interface UseExecutionProgressResult {
+    /** Latest progress snapshot, or null before the first update. */
+    progress: ExecutionProgress | null;
+    status: ExecutionProgressStatus;
+    error: Error | null;
+    /** Fetches a one-shot snapshot via `executions.getProgress`. */
+    refresh: () => Promise<ExecutionProgress | null>;
+}
+/**
+ * Live execution timeline for a custom UI.
+ *
+ * When `executionId` is set, subscribes via `executions.watchProgress` and
+ * keeps the latest snapshot. Aborts the stream on unmount or id change.
+ *
+ * ```tsx
+ * const { progress, status, error, refresh } = useExecutionProgress(executionId);
+ * ```
+ */
+declare function useExecutionProgress(executionId: string | null): UseExecutionProgressResult;
+
+type NeedsInputSource = ExecutionProgress | Pick<Execution, 'id' | 'executionPath' | 'pendingInput' | 'status'> | null | undefined;
+interface UseNeedsInputOptions {
+    /** Called after a successful `submitInput`. */
+    onSubmitted?: () => void | Promise<void>;
+}
+interface UseNeedsInputResult {
+    /** True when a step is currently waiting for input. */
+    waiting: boolean;
+    /** The `NEEDS_INPUT` step, when present. */
+    waitingStep: ExecutionPathStep | ExecutionProgressStep | null;
+    /**
+     * Field schema for the waiting step (from `pendingInput` expansion), when
+     * available.
+     */
+    pendingInput: PendingInput | null;
+    executionId: string | null;
+    nodeId: string | null;
+    /**
+     * Submits values keyed by field id, then optionally runs `onSubmitted`.
+     * Throws when nothing is waiting.
+     */
+    submitInput: (values: Record<string, unknown>) => Promise<void>;
+}
+/**
+ * Derives the waiting `NEEDS_INPUT` step from an execution or progress
+ * snapshot and exposes `submitInput` for custom forms.
+ *
+ * ```tsx
+ * const { waiting, pendingInput, submitInput } = useNeedsInput(progress);
+ * ```
+ */
+declare function useNeedsInput(source: NeedsInputSource, options?: UseNeedsInputOptions): UseNeedsInputResult;
+
+interface UseAgentChatOptions {
+    /** Agent chat mode forwarded in the request body. */
+    chatMode?: 'builder' | 'preview';
+}
+interface UseAgentChatResult {
+    /** Stable task id for this hook lifetime (generated if omitted). */
+    taskId: string;
+    messages: UIMessage[];
+    /** AI SDK chat status (`ready` | `submitted` | `streaming` | `error`). */
+    status: string;
+    error: Error | undefined;
+    /** Sends a plain-text user message. */
+    send: (text: string) => Promise<void>;
+    /**
+     * Aborts the in-flight HTTP stream and asks the server to cancel the turn.
+     */
+    stop: () => Promise<void>;
+}
+/**
+ * Thin AI SDK wrapper for Lunnoa agent chat.
+ *
+ * Requires optional peer `@ai-sdk/react` (and the `ai` package already shipped
+ * with `@lunnoa/client`). Points `DefaultChatTransport` at the Automate
+ * stream-message endpoint with a Bearer token from the auth provider.
+ *
+ * ```tsx
+ * const { messages, send, stop, status, taskId } = useAgentChat(agentId);
+ * ```
+ */
+declare function useAgentChat(agentId: string, taskId?: string, options?: UseAgentChatOptions): UseAgentChatResult;
+
+type ApprovalsInboxStatus = 'idle' | 'loading' | 'ready' | 'error';
+interface UseApprovalsInboxOptions {
+    /** Inbox filter; defaults to `pending`. */
+    status?: 'pending' | 'done' | string;
+    /**
+     * Poll interval in ms. Off by default (`0` / `undefined`).
+     * A common value for live inboxes is `15_000`.
+     */
+    pollIntervalMs?: number;
+}
+interface UseApprovalsInboxResult {
+    items: ApprovalInboxItem[];
+    status: ApprovalsInboxStatus;
+    error: Error | null;
+    refresh: () => Promise<ApprovalInboxItem[]>;
+    decide: (approvalId: string, body: {
+        decision: 'approved' | 'rejected';
+        comment?: string;
+    }) => Promise<void>;
+}
+/**
+ * Approvals inbox for the current user (workspace API).
+ *
+ * ```tsx
+ * const { items, decide, refresh } = useApprovalsInbox({ pollIntervalMs: 15_000 });
+ * ```
+ */
+declare function useApprovalsInbox(options?: UseApprovalsInboxOptions): UseApprovalsInboxResult;
+
+type EntityListStatus = 'idle' | 'loading' | 'ready' | 'error';
+type UseEntityListOptions = ListEntitiesOptions & {
+    /**
+     * When false, skips fetching until set true. Defaults to true.
+     */
+    enabled?: boolean;
+};
+interface UseEntityListResult {
+    data: Entity[];
+    pagination: PaginatedEntities['pagination'] | null;
+    page: number;
+    setPage: (page: number) => void;
+    status: EntityListStatus;
+    error: Error | null;
+    refresh: () => Promise<PaginatedEntities | null>;
+    /** Merges into list filters and resets to page 1. */
+    setSearch: (search: string | undefined) => void;
+    /** Merges into list filters and resets to page 1. */
+    setState: (state: string | undefined) => void;
+    /** Current effective list options (including page). */
+    options: ListEntitiesOptions;
+}
+/**
+ * Paginated entity list for tables and pickers.
+ *
+ * ```tsx
+ * const { data, page, setPage, setSearch, status } = useEntityList({
+ *   objectTypeSlug: 'invoice',
+ *   expansion: ['attributes'],
+ *   pageSize: 25,
+ * });
+ * ```
+ */
+declare function useEntityList(initialOptions: UseEntityListOptions): UseEntityListResult;
+
+export { type ApprovalsInboxStatus, type AuthStatus, type EntityListStatus, type ExecutionProgressStatus, type LunnoaAuthContextValue, LunnoaAuthProvider, type LunnoaAuthProviderProps, type NeedsInputSource, type UseAgentChatOptions, type UseAgentChatResult, type UseApprovalsInboxOptions, type UseApprovalsInboxResult, type UseEntityListOptions, type UseEntityListResult, type UseExecutionProgressResult, type UseNeedsInputOptions, type UseNeedsInputResult, useAccessToken, useAgentChat, useApprovalsInbox, useEntityList, useExecutionProgress, useLunnoaAuth, useLunnoaClient, useNeedsInput };