modulex-js 0.1.0 → 1.0.0

package/dist/index.d.ts

@@ -6,7 +6,12 @@ interface ModulexConfig {
     apiKey: string;
     /** Default organization ID for all requests. Can be overridden per-request. */
     organizationId?: string;
-    /** Base URL for the ModuleX API. */
+    /**
+     * Base URL for the ModuleX REST API (the root; routers are mounted at the root
+     * with NO version prefix, so do not append `/api` or `/v1`). Defaults to the
+     * production host. For local development point this at your dev server,
+     * e.g. `http://localhost:8000`.
+     */
     baseUrl?: string;
     /** Request timeout in milliseconds. */
     timeout?: number;
@@ -27,8 +32,19 @@ interface ResolvedConfig {
 
 /** A parsed SSE event. */
 interface SSEEvent {
-    /** Event type (e.g., "node_update", "done", "error"). */
+    /**
+     * The raw SSE `event:` field, or "message" when the frame has no `event:` line.
+     * NOTE: most ModuleX streams (workflows, composer, assistant, credentials) emit
+     * data-only frames, so `event` is "message" for them — prefer {@link SSEEvent.type}
+     * for discriminating. The chats stream is the exception and uses real `event:` lines.
+     */
     event: string;
+    /**
+     * The semantic event type to discriminate on. Resolves to `data.type` when the
+     * JSON payload carries a `type` field (data-only streams), otherwise falls back to
+     * the `event:` field (chats stream). This is the value to switch on in consumers.
+     */
+    type: string;
     /** Parsed JSON data payload. */
     data: Record<string, unknown>;
     /** Optional event ID. */
@@ -64,13 +80,17 @@ interface SuccessResponse {
 }
 /**
  * Generic paginated list envelope.
- * The API uses different pagination styles across resources; all optional
- * fields that a particular endpoint may or may not include are represented here.
+ * The API uses different pagination styles across resources (page+limit,
+ * offset, cursor/has_next); every field a particular endpoint may or may not
+ * include is optional here. `total` is optional because cursor/has_next style
+ * endpoints do not return a total count.
  *
  * @template T - The type of each item in the collection.
  */
 interface PaginatedList<T> {
-    total: number;
+    /** The page of items. Some endpoints nest items under a resource-specific key instead. */
+    items?: T[];
+    total?: number;
     page?: number;
     page_size?: number;
     total_pages?: number;
@@ -165,14 +185,23 @@ interface UserResponse {
 }
 /**
  * Lightweight organization membership record returned inside user-centric responses.
+ *
+ * Wire shape matches the backend `get_user_organizations` projection
+ * (`{id, slug, name, domain, role, joined_at, is_default}`). Fields are
+ * snake_case to mirror the API response exactly.
  */
 interface OrganizationInfo {
     id: string;
     name: string;
     slug: string;
+    /** The organization's email domain, or `null` when unset. */
+    domain: string | null;
     /** The calling user's role inside this organization. */
     role: string;
-    created_at: string;
+    /** ISO-8601 timestamp of when the user joined this organization. */
+    joined_at: string;
+    /** Whether this organization is the user's default organization. */
+    is_default: boolean;
 }
 /**
  * Response from listing the organizations a user belongs to.
@@ -183,19 +212,47 @@ interface OrganizationsResponse {
     organizations: OrganizationInfo[];
     total: number;
 }
+/**
+ * The organization an invitation grants membership to.
+ */
+interface InvitationOrganization {
+    id: string;
+    name: string;
+    slug: string | null;
+    /** The organization's email domain, or `null` when unset. */
+    domain: string | null;
+}
+/**
+ * The user who issued an invitation.
+ */
+interface InvitationInviter {
+    id: string;
+    email: string;
+    username: string | null;
+}
 /**
  * A single organization invitation object.
+ *
+ * Wire shape matches the backend `get_user_all_pending_invitations_optimized`
+ * projection. The organization and inviter are nested objects (not flat
+ * `organization_id` / `invited_email` fields).
  */
 interface InvitationObject {
     id: string;
-    organization_id: string;
-    organization_name?: string;
-    invited_email: string;
+    /** The organization the invitation grants access to. */
+    organization: InvitationOrganization;
+    /** The user who sent the invitation. */
+    invited_by: InvitationInviter;
     role: string;
     status: string;
-    invitation_message?: string;
+    invitation_message?: string | null;
     created_at: string;
-    expires_at?: string;
+    expires_at?: string | null;
+    /**
+     * Whole days remaining until the invitation expires. Can be `0` for
+     * invitations expiring in under 24 hours (derived from `timedelta.days`).
+     */
+    days_until_expiry: number;
 }
 /**
  * Response from listing pending invitations for the authenticated user.
@@ -203,15 +260,30 @@ interface InvitationObject {
 interface InvitationsResponse {
     success: boolean;
     invitations: InvitationObject[];
-    total: number;
+    /** Total number of pending invitations returned. */
+    total_count: number;
+}
+/**
+ * The organization details returned when an invitation is accepted.
+ */
+interface AcceptedInvitationOrganization {
+    id: string;
+    name: string;
+    slug: string;
 }
 /**
- * Response from accepting or rejecting a single invitation.
+ * Response from accepting an invitation.
+ *
+ * On success the backend returns the joined organization and the granted
+ * role in addition to `success` / `message`.
  */
 interface InvitationResponse {
     success: boolean;
     message?: string;
-    invitation: InvitationObject;
+    /** The organization the user joined. */
+    organization?: AcceptedInvitationOrganization;
+    /** The role the user was granted in the organization. */
+    role?: string;
 }
 /**
  * Response returned when a user leaves an organization.
@@ -223,12 +295,12 @@ interface LeaveResponse {
     left_organization: {
         id: string;
         name: string;
+        slug: string;
     };
-    /** The organizations the user still belongs to. */
-    remaining_organizations: {
-        id: string;
-        name: string;
-    }[];
+    /**
+     * The organizations the user still belongs to, as full membership records.
+     */
+    remaining_organizations: OrganizationInfo[];
     total_remaining: number;
 }
 
@@ -241,13 +313,19 @@ interface LeaveResponse {
  * Field names are camelCase; the SDK converts them to snake_case before sending.
  */
 interface CreateApiKeyParams {
-    /** Human-readable label for the key. */
+    /** Human-readable label for the key. Must be 1-255 characters. */
     name: string;
-    /** Scope the key to a specific organization. Defaults to the client-level org. */
+    /**
+     * Scope the key to a specific organization.
+     * If omitted, the key works for all of the user's organizations.
+     */
     organizationId?: string;
     /** ISO-8601 datetime after which the key becomes invalid. */
     expiresAt?: string;
-    /** Maximum number of API calls allowed per minute for this key. */
+    /**
+     * Maximum number of API calls allowed per minute for this key.
+     * Must be between 1 and 1000 (backend default: 60).
+     */
     rateLimitPerMinute?: number;
 }
 /**
@@ -262,13 +340,21 @@ interface ApiKeyResponse {
      * Only returned once, immediately after creation — store it securely.
      */
     key?: string;
-    /** Masked hint showing the first / last characters of the key. */
+    /** Identifier hint: the first 8 characters of the key. */
     key_hint: string;
+    /** Masked key for display, e.g. `mx_live_XXXX****`. */
+    masked_key: string;
     organization_id: string | null;
     expires_at: string | null;
-    rate_limit_per_minute: number | null;
+    /** Whether the key has passed its expiration datetime. */
+    is_expired: boolean;
+    /** Whether the key is active (i.e. not revoked). */
+    is_active: boolean;
+    rate_limit_per_minute: number;
+    /** ISO-8601 datetime the key was last used, or null if never used. */
+    last_used_at: string | null;
     created_at: string;
-    is_revoked?: boolean;
+    /** ISO-8601 datetime the key was revoked, or null if still active. */
     revoked_at?: string | null;
 }
 /**
@@ -284,7 +370,10 @@ interface CreateApiKeyResponse extends ApiKeyResponse {
  */
 interface ApiKeyListResponse {
     keys: ApiKeyResponse[];
-    total?: number;
+    /** Total number of keys returned. Always present. */
+    total: number;
+    /** Maximum number of keys allowed per user. */
+    max_keys: number;
 }
 /**
  * Response returned after revoking an API key.
@@ -308,12 +397,20 @@ interface CreateOrganizationParams {
     slug?: string;
 }
 /**
- * Minimal organization object embedded in creation responses.
+ * Organization object embedded in creation responses.
+ *
+ * Wire fields are snake_case to match the backend `org_payload`.
  */
 interface OrganizationCreatedObject {
     id: string;
     name: string;
     slug: string;
+    /** Email domain associated with the organization, if any. */
+    domain: string | null;
+    /** Whether the organization is active. */
+    is_active: boolean;
+    /** ISO-8601 creation timestamp, or `null` if unavailable. */
+    created_at: string | null;
 }
 /**
  * Response from the create-organization endpoint.
@@ -348,8 +445,13 @@ interface LLMsResponse {
 interface InviteParams {
     /** Email address of the person being invited. */
     invitedEmail: string;
-    /** Role to assign upon acceptance. Defaults to `'member'`. */
-    role?: string;
+    /**
+     * Role to assign upon acceptance. Only `'admin'` is accepted — the org
+     * `member` role was retired (organizations are owner/admin only). Omit to use
+     * the server-side default (`admin`). The backend rejects `role: 'member'` with
+     * HTTP 422.
+     */
+    role?: 'admin';
     /** Optional personal message included in the invitation email. */
     invitationMessage?: string;
 }
@@ -364,8 +466,12 @@ interface CancelInvitationResponse {
  * Parameters for updating a member's role within an organization.
  */
 interface RoleUpdateParams {
-    /** New role to assign. */
-    role: 'member' | 'admin';
+    /**
+     * New role to assign. Only `'admin'` is accepted — the org `member` role was
+     * retired (organizations are owner/admin only); the backend rejects
+     * `role: 'member'` with HTTP 422.
+     */
+    role: 'admin';
 }
 /**
  * Response returned after a successful role update.
@@ -377,6 +483,120 @@ interface RoleUpdateResponse {
     organization_id: string;
     new_role: string;
 }
+/**
+ * Response from previewing the prorated cost of adding one seat
+ * (`POST /organizations/invite/preview`).
+ *
+ * A discriminated union on `preview_available`:
+ * - `false` — preview is not available (e.g. no active subscription); includes a `reason`.
+ * - `true` — a prorated cost preview is available with full pricing detail.
+ *
+ * Wire fields are snake_case to match the backend response.
+ */
+type InvitePreviewResponse = {
+    preview_available: false;
+    /** Machine-readable reason the preview is unavailable, e.g. `'no_active_subscription'`. */
+    reason: string;
+} | {
+    preview_available: true;
+    /** Billing interval of the active subscription, e.g. `'month'` or `'year'`. */
+    interval: string;
+    /** The seat count that would result after adding one seat. */
+    new_quantity: number;
+    /** Total amount due, in major currency units (e.g. dollars). */
+    amount_due: number;
+    /** ISO-4217 currency code, e.g. `'usd'`. */
+    currency: string;
+    /** Prorated line amount for the added seat, in major currency units. */
+    proration_line_amount: number;
+    /** `true` if the charge is immediate (annual plans); `false` if billed on the next invoice (monthly). */
+    immediate: boolean;
+};
+/**
+ * A single visible model in an integration's model-visibility dropdown.
+ *
+ * Wire fields are snake_case to match the backend `LLMModelEntry`.
+ */
+interface LLMModelEntry {
+    /** Model id / slug used at runtime. */
+    id: string;
+    /** Optional label shown in the dropdown. */
+    display_name?: string;
+}
+/**
+ * The org's persisted default composer LLM selection.
+ *
+ * Wire fields are snake_case to match the backend `composer_llm` object.
+ */
+interface ComposerLLMSelection {
+    integration_name: string;
+    provider_id: string;
+    model_id: string;
+    credential_id?: string;
+}
+/**
+ * Response from reading per-organization settings (`GET /organizations/settings`).
+ *
+ * Wire fields are snake_case to match the backend response.
+ */
+interface SettingsResponse {
+    /**
+     * Per-integration map of visible models. Keys are integration names
+     * (e.g. `'openrouter'`), values are the visible model entries.
+     */
+    llm_model_visibility: Record<string, LLMModelEntry[]>;
+    /** The org's default composer LLM, or `null` if not configured. */
+    composer_llm: ComposerLLMSelection | null;
+}
+/**
+ * Parameters for setting which models are visible for one integration
+ * (`PUT /organizations/settings/llm-model-visibility`).
+ *
+ * Send the FULL desired visible list. An empty `models` array resets the
+ * integration's visibility to the catalog default.
+ *
+ * Field names are camelCase and converted to snake_case on the wire by the
+ * base client.
+ */
+interface SetModelVisibilityParams {
+    /** Integration name, e.g. `'openrouter'` or `'openai'`. */
+    integrationName: string;
+    /** Full desired set of visible models. Empty resets to default. */
+    models: LLMModelEntry[];
+}
+/**
+ * Response from setting model visibility
+ * (`PUT /organizations/settings/llm-model-visibility`).
+ */
+interface SetModelVisibilityResponse {
+    /** Updated per-integration map of visible models. */
+    llm_model_visibility: Record<string, LLMModelEntry[]>;
+}
+/**
+ * Parameters for setting the org's default composer LLM
+ * (`PUT /organizations/settings/composer-llm`).
+ *
+ * Field names are camelCase and converted to snake_case on the wire by the
+ * base client.
+ */
+interface ComposerLLMParams {
+    /** Integration name, e.g. `'openrouter'`. */
+    integrationName: string;
+    /** Provider id for the selected model. */
+    providerId: string;
+    /** Model id to use as the default composer LLM. */
+    modelId: string;
+    /** Optional credential id to associate with the selection. */
+    credentialId?: string;
+}
+/**
+ * Response from setting the org's default composer LLM
+ * (`PUT /organizations/settings/composer-llm`).
+ */
+interface ComposerLLMResponse {
+    /** The org's updated default composer LLM, or `null` if cleared. */
+    composer_llm: ComposerLLMSelection | null;
+}
 
 /**
  * Types for workflow definitions, nodes, edges, and builder metadata.
@@ -479,8 +699,12 @@ interface LLMNodeConfig {
     system_prompt?: string;
     /** User prompt template. */
     user_prompt?: string;
+    /** @deprecated Use `user_prompt`. Kept as a backward-compatible alias; the backend copies it into `user_prompt`. */
+    prompt_template?: string;
     /** JSON Schema describing the expected structured output format. */
     structured_output_schema?: Record<string, unknown>;
+    /** When `true`, enforce strict structured-output schema validation. */
+    structured_output_strict?: boolean;
 }
 /**
  * Configuration for a `tool` node — executes a single tool action.
@@ -497,17 +721,25 @@ interface AgentNodeConfig {
     llm: LLMConfig;
     /** Tools available to this agent. */
     tools?: ToolDefinition[];
-    system_prompt?: string;
+    /** Required by the backend — an agent node without a system prompt is rejected (422). */
+    system_prompt: string;
     user_prompt?: string;
     /** Maximum tool-call iterations before the agent yields. */
     max_iterations?: number;
     input_mapping?: Record<string, string>;
 }
 /**
- * Configuration for a `function` node — executes arbitrary registered code.
- * Shape is integration-specific and passed through without transformation.
+ * Configuration for a `function` node — executes a registered function.
+ * The backend requires `function_name`; `input_mapping` and `parameters` are
+ * optional. Additional integration-specific keys pass through untransformed.
  */
 interface FunctionNodeConfig {
+    /** Name of the registered function to invoke (required by the backend). */
+    function_name?: string;
+    /** Maps state fields to function input parameters. */
+    input_mapping?: Record<string, string>;
+    /** Static parameters passed to the function. */
+    parameters?: Record<string, unknown>;
     [key: string]: unknown;
 }
 /**
@@ -529,6 +761,8 @@ interface LoopConfig {
     mode: string;
     /** Fixed iteration count for `"for"` mode. */
     iterations?: number;
+    /** State field holding a dynamic iteration count for `"for"` mode. */
+    iterations_ref?: string;
     /** State field containing the collection to iterate over for `"foreach"` mode. */
     collection?: string;
     /** Boolean expression used for `"while"` mode. */
@@ -541,6 +775,12 @@ interface LoopConfig {
     exit_target?: string;
     /** Hard upper bound on iterations to prevent infinite loops. */
     max_iterations?: number;
+    /** Run `"foreach"` iterations in parallel rather than sequentially. */
+    parallel?: boolean;
+    /** Accumulate iteration results instead of overwriting. */
+    accumulate?: boolean;
+    /** State field to accumulate iteration results from/into. */
+    accumulate_from?: string;
 }
 /**
  * Configuration for a `conditional` node — branches or loops based on state.
@@ -624,10 +864,10 @@ interface NodeDefinition {
     description?: string;
     /** Whether the node participates in execution. Defaults to `true`. */
     enabled?: boolean;
-    /** Canvas X position (used by the visual editor). */
-    x?: number;
-    /** Canvas Y position (used by the visual editor). */
-    y?: number;
+    /** Canvas X position. Required by the backend (create/update return 422 without it). */
+    x: number;
+    /** Canvas Y position. Required by the backend (create/update return 422 without it). */
+    y: number;
     retry_config?: RetryConfig;
     llm_config?: LLMNodeConfig;
     tool_config?: ToolNodeConfig;
@@ -674,7 +914,12 @@ interface CreateWorkflowParams {
     category?: string;
     /** Lifecycle status (e.g. `"draft"`, `"published"`). */
     status?: string;
-    /** Sharing visibility (e.g. `"private"`, `"organization"`, `"public"`). */
+    /**
+     * Sharing visibility — one of `"private"`, `"organization"`, `"public"`, or
+     * `"system"`. Omit to let the backend default to `"organization"` (there is no
+     * client-side default). Note: `"private"` is no longer creator-only — it now
+     * behaves like `"organization"` (any org admin/owner can view/run/resume).
+     */
     visibility?: string;
     /** Default input values shown in the run panel. */
     input?: Record<string, unknown>;
@@ -692,6 +937,11 @@ interface UpdateWorkflowParams {
     tags?: string[];
     category?: string;
     status?: string;
+    /**
+     * Sharing visibility — `"private"`, `"organization"`, `"public"`, or
+     * `"system"`. `"private"` is no longer creator-only; it behaves like
+     * `"organization"`.
+     */
     visibility?: string;
     workflowSchema?: WorkflowDefinition;
     input?: Record<string, unknown>;
@@ -706,18 +956,28 @@ interface WorkflowSummary {
     description: string | null;
     version: string;
     status: string;
+    /**
+     * Sharing visibility — one of `"private"`, `"organization"`, `"public"`, or
+     * `"system"`. New workflows default to `"organization"`; `"private"` is no
+     * longer creator-only and behaves like `"organization"`.
+     */
     visibility: string;
     category: string | null;
     tags: string[];
     created_at: string;
     updated_at: string;
-    creator_id: string;
+    /** Null for workflows with no recorded creator (e.g. system/seed workflows). */
+    creator_id: string | null;
+    /** Default state input payload returned on each list row. */
+    input?: Record<string, unknown>;
 }
 /**
  * Full workflow record including the stored schema.
  */
 interface WorkflowResponse extends WorkflowSummary {
     workflow_schema: WorkflowDefinition;
+    /** Execution config defaults returned by create/get/update. */
+    config?: Partial<WorkflowConfig>;
     edit_version?: number;
     last_edited_by?: string | null;
     last_edited_at?: string | null;
@@ -729,11 +989,14 @@ interface WorkflowResponse extends WorkflowSummary {
 interface WorkflowListParams {
     status?: string;
     category?: string;
+    /**
+     * Filter by sharing visibility — `"private"`, `"organization"`, `"public"`, or
+     * `"system"`.
+     */
     visibility?: string;
     search?: string;
     page?: number;
     pageSize?: number;
-    organizationId?: string;
 }
 /**
  * Paginated list of workflow summaries.
@@ -764,22 +1027,62 @@ interface BuilderDetailsParams {
     category?: string;
     /** Filter to a specific integration name. */
     integrationName?: string;
-    organizationId?: string;
+}
+/**
+ * A rich descriptor for a single builder node type.
+ */
+interface BuilderNodeTypeDescriptor {
+    label?: string;
+    description?: string;
+    default_schema?: Record<string, unknown>;
+    output_schema?: Record<string, unknown>;
+    providers?: unknown[];
+    integrations?: unknown[];
+    [key: string]: unknown;
 }
 /**
  * Response from the builder details endpoint, providing the palette of
  * available node types, integration categories, and their counts.
  */
 interface BuilderDetailsResponse {
-    /** Map of node type identifier to its descriptor. */
-    node_types: Record<string, unknown>;
-    /** Available integration categories. */
-    categories: string[];
-    /** Count breakdown by category or type. */
-    counts: Record<string, number>;
+    /** Map of node type identifier to its rich descriptor. */
+    node_types: Record<string, BuilderNodeTypeDescriptor>;
+    /** Available integration items grouped by category. */
+    categories: {
+        tools: string[];
+        functions: string[];
+        transformers: string[];
+    };
+    /** Count breakdown. Known keys: integrations, functions, transformers, providers. */
+    counts: {
+        integrations?: number;
+        functions?: number;
+        transformers?: number;
+        providers?: number;
+        [key: string]: number | undefined;
+    };
+    /** Builder feature flags (e.g. array-spread support). */
+    features?: {
+        array_spread: boolean;
+    };
     /** Whether the response was served from cache. */
     cached: boolean;
 }
+/**
+ * A real-time collaboration event from the `GET /workflows/{id}/changes`
+ * SSE stream. This is a data-only stream; discriminate on `type`.
+ */
+type WorkflowChangeEvent = {
+    type: 'connected';
+    workflow_id: string;
+    edit_version: number;
+} | ({
+    type: 'workflow_updated';
+} & Record<string, unknown>) | ({
+    type: 'user_joined';
+} & Record<string, unknown>) | ({
+    type: 'user_left';
+} & Record<string, unknown>);
 
 /**
  * Types for workflow execution — running, resuming, cancelling, and streaming.
@@ -788,19 +1091,29 @@ interface BuilderDetailsResponse {
 
 /**
  * Parameters for triggering a workflow run.
+ *
+ * Two run modes are supported:
+ * - `workflowId` — run a previously saved workflow (requires an active deployment;
+ *   the backend returns 400 if the workflow has not been deployed).
+ * - `workflow` — run an inline, ad-hoc definition without saving it.
+ *
+ * The legacy `llm`-only and `systemWorkflow` modes were removed from the backend
+ * (the run endpoint now returns HTTP 410 for an `llm_config`-only request — use
+ * `client.assistant.chat()` instead).
  */
 interface WorkflowRunParams {
-    /** ID of a previously saved workflow to run. Mutually exclusive with `workflow`. */
+    /** ID of a previously saved workflow to run. Mutually exclusive with `workflow`. Requires an active deployment. */
     workflowId?: string;
-    /** An inline workflow definition to run without saving. */
+    /** An inline workflow definition to run without saving. Mutually exclusive with `workflowId`. */
     workflow?: WorkflowDefinition;
-    /** Override the LLM used by the run. */
-    llm?: LLMConfig;
-    /** Name of a system-level workflow to run (e.g. `"workflow_name"`). */
-    systemWorkflow?: string;
+    /** For ad-hoc (inline) runs, the saved workflow to attribute this run to in run history. */
+    attributionWorkflowId?: string;
     /** State input values passed to the workflow's entry node. */
     input?: Record<string, unknown>;
-    /** Runtime config overrides for this execution. */
+    /**
+     * Runtime config overrides for this execution. Recognised keys include
+     * `thread_id`, `recursion_limit`, and `batch_interval_ms`.
+     */
     config?: Record<string, unknown>;
     /** Whether to open an SSE stream for real-time events. */
     stream?: boolean;
@@ -808,15 +1121,32 @@ interface WorkflowRunParams {
     ephemeral?: boolean;
     /** If `true`, the run and its messages are only visible to the creator. */
     isPrivate?: boolean;
-    /** Knowledge base retrieval config for this run. */
-    knowledgeConfig?: Record<string, unknown>;
-    organizationId?: string;
+}
+/**
+ * A persisted workflow message envelope (human or AI message) returned inline
+ * by a synchronous run.
+ */
+interface WorkflowMessageEnvelope {
+    id: string;
+    chat_id: string | null;
+    role: string;
+    content: unknown;
+    workflow: Record<string, unknown> | null;
+    run_id: string;
+    running_status: string;
+    created_at: string;
+    updated_at: string;
+    deleted_at: string | null;
 }
 /**
  * Response from initiating a workflow run.
  */
 interface WorkflowRunResponse {
-    /** Terminal or intermediate status (e.g. `"completed"`, `"running"`, `"interrupted"`). */
+    /**
+     * The status of the synchronous portion. For a streaming/async run this is
+     * always `"running"`; terminal statuses are observed via `listen()` or the
+     * run-history endpoints, not here.
+     */
     status: string;
     run_id: string;
     thread_id: string;
@@ -825,12 +1155,12 @@ interface WorkflowRunResponse {
     stream: boolean;
     workflow_name: string;
     workflow_version: string;
-    /** `"saved"` | `"inline"` | `"deployment"` */
-    workflow_source: string;
+    /** Origin of the executed definition: `"database"`, `"request"`, or `"system:<name>"`. */
+    workflow_source: 'database' | 'request' | `system:${string}`;
     /** Wall-clock duration of the synchronous portion in milliseconds. */
     elapsed_ms: number;
-    human_message?: Record<string, unknown> | null;
-    ai_message?: Record<string, unknown> | null;
+    human_message?: WorkflowMessageEnvelope | null;
+    ai_message?: WorkflowMessageEnvelope | null;
     message: string;
 }
 /**
@@ -838,7 +1168,8 @@ interface WorkflowRunResponse {
  */
 interface WorkflowStateResponse {
     thread_id: string;
-    run_id: string;
+    /** The originating run ID, read from checkpoint metadata — may be null. */
+    run_id: string | null;
     checkpoint_id: string;
     /** The full LangGraph state object. */
     state: Record<string, unknown>;
@@ -846,7 +1177,7 @@ interface WorkflowStateResponse {
     next: string[];
     /** LangGraph metadata blob. */
     metadata: Record<string, unknown>;
-    /** Number of writes pending flush to the checkpoint store. */
+    /** Count of pending writes not yet flushed to the checkpoint store. */
     pending_writes: number;
 }
 /**
@@ -865,7 +1196,6 @@ interface WorkflowResumeParams {
     runId: string;
     /** Whether to open an SSE stream for the resumed execution. */
     stream?: boolean;
-    organizationId?: string;
 }
 /**
  * Response from resuming an interrupted workflow run.
@@ -875,112 +1205,194 @@ interface WorkflowResumeResponse {
     run_id: string;
     thread_id: string;
     stream: boolean;
-    workflow_source: string;
+    workflow_source: 'database' | 'request' | `system:${string}`;
     message: string;
 }
 /**
  * Response from cancelling an in-progress workflow run.
  */
 interface CancelResponse {
-    status: string;
+    /** The backend returns the literal `"cancellation_requested"` on success. */
+    status: 'cancellation_requested' | string;
     run_id: string;
     reason: string;
     message: string;
 }
-/**
- * Data payload for the `metadata` SSE event — emitted at the start of a run.
- */
+/** Payload of a `metadata` event (wrapped under `data`). */
 interface MetadataEventData {
     run_id: string;
     thread_id: string;
     workflow_name: string;
     workflow_version: string;
-    /** Ordered list of node IDs in the execution plan. */
-    nodes: string[];
+    /** `"llm"` (token-streaming) or `"workflow"`. */
+    workflow_type: string;
+    timestamp: string;
+}
+/** Payload of a `node_started` event (flat — fields sit alongside `type`). */
+interface NodeStartedEventData {
+    /** The node ID. */
+    node: string;
+    /** The node display name. */
+    name: string;
+    timestamp: string;
+    /** Node-specific start metadata (shape varies by node type). */
+    metadata?: Record<string, unknown>;
 }
-/**
- * Data payload for a `node_update` SSE event — emitted as each node changes state.
- */
+/** Payload of a `node_update` event (flat — fields sit alongside `type`). */
 interface NodeUpdateEventData {
-    node_id: string;
-    node_type: string;
-    status: 'started' | 'completed' | 'error';
-    /** Node output value (present when `status` is `"completed"`). */
-    output?: unknown;
-    /** Error message (present when `status` is `"error"`). */
-    error?: string;
-    /** How long the node took to execute, in milliseconds. */
-    execution_time_ms?: number;
+    /** The node ID. */
+    node: string;
+    /** The node display name. */
+    name: string;
+    timestamp: string;
+    /** Node output (shape varies by node type). */
+    output?: Record<string, unknown>;
 }
-/**
- * Data payload for an `interrupt` SSE event — execution is paused for human input.
- */
+/** Payload of an `interrupt` event (wrapped under `data`). */
 interface InterruptEventData {
     message: string;
-    /** Current workflow state at the point of interruption. */
-    state: Record<string, unknown>;
-    /** Instructions describing what the human should supply as a resume value. */
-    resume_instructions?: string;
-    /** ID of the node that triggered the interrupt. */
-    node_id: string;
+    /** Structured interrupt payload, if any. */
+    data: Record<string, unknown>;
+    /** JSON Schema describing the expected resume value, when provided. */
+    resume_schema?: Record<string, unknown>;
+    /** Example resume values, when provided. */
+    examples?: unknown;
 }
-/**
- * Data payload for a `resumed` SSE event — a previously interrupted run has continued.
- */
+/** Payload of a `resumed` event (wrapped under `data`). */
 interface ResumedEventData {
     run_id: string;
     thread_id: string;
+    resume_value: unknown;
+    timestamp: string;
 }
-/**
- * Data payload for the `done` SSE event — the workflow has finished executing.
- */
+/** Payload of a `done` event (wrapped under `data`). */
 interface DoneEventData {
-    final_state: Record<string, unknown>;
-    steps_executed: number;
-    total_execution_time_ms: number;
+    message: string;
 }
-/**
- * Data payload for an `error` SSE event — an unrecoverable error occurred.
- */
+/** Payload of an `error` event (flat — fields sit alongside `type`). */
 interface ErrorEventData {
-    error_message: string;
+    message: string;
     error_type?: string;
-    /** ID of the node where the error originated, if applicable. */
-    node_id?: string;
-    stack_trace?: string;
 }
 /**
- * A type-safe discriminated union of all possible SSE events emitted during
- * a workflow run or resume stream.
+ * A type-safe discriminated union of every SSE frame emitted during a workflow
+ * run or resume stream. Discriminate on the `type` field (NOT `event`, which is
+ * always `"message"` for these data-only streams):
  *
- * Discriminate on the `event` field to narrow the `data` type:
  * ```ts
- * for await (const evt of stream) {
- *   if (evt.event === 'done') {
- *     console.log(evt.data.final_state);
+ * for await (const evt of client.executions.listen(runId)) {
+ *   switch (evt.type) {
+ *     case 'node_update': console.log(evt.node, evt.output); break; // flat
+ *     case 'done':        console.log(evt.data.message);           break; // wrapped
+ *     case 'error':       console.error(evt.message);              break; // flat
  *   }
  * }
  * ```
  */
-type WorkflowSSEEvent = {
-    event: 'metadata';
+type WorkflowSSEEvent = ({
+    type: 'metadata';
+} & {
     data: MetadataEventData;
-} | {
-    event: 'node_update';
-    data: NodeUpdateEventData;
-} | {
-    event: 'interrupt';
+}) | ({
+    type: 'node_started';
+} & NodeStartedEventData) | ({
+    type: 'node_update';
+} & NodeUpdateEventData) | ({
+    type: 'interrupt';
+} & {
     data: InterruptEventData;
-} | {
-    event: 'resumed';
+}) | ({
+    type: 'resumed';
+} & {
     data: ResumedEventData;
-} | {
-    event: 'done';
+}) | ({
+    type: 'done';
+} & {
     data: DoneEventData;
-} | {
-    event: 'error';
-    data: ErrorEventData;
-};
+}) | ({
+    type: 'cancelled';
+} & {
+    data: Record<string, unknown> | null;
+}) | ({
+    type: 'error';
+} & ErrorEventData);
+
+/**
+ * Types for the durable workflow run-history read endpoints (`/workflow-runs`).
+ * @module types/workflow-runs
+ */
+/**
+ * Query parameters for listing workflow runs.
+ */
+interface WorkflowRunListParams {
+    /** Filter to a single workflow's run history. */
+    workflowId?: string;
+    /** Filter by run status. */
+    status?: string;
+    /** Filter by trigger type. */
+    triggerType?: string;
+    /** Page size, 1–100 (default 50). */
+    limit?: number;
+    /** Number of rows to skip (default 0). */
+    offset?: number;
+}
+/**
+ * A preview-optimized run-history list row (no heavy snapshot columns).
+ */
+interface WorkflowRunListItem {
+    /** The run table primary key (UUID) — pass this to `get()`, NOT `run_id`. */
+    id: string;
+    /** The execution run ID (string) used by listen/cancel. */
+    run_id: string;
+    workflow_id: string | null;
+    trigger_type: string;
+    is_ad_hoc: boolean;
+    status: string;
+    started_at: string | null;
+    completed_at: string | null;
+    duration_seconds: number | null;
+    error_message: string | null;
+    created_at: string;
+    has_output: boolean;
+}
+/**
+ * Response from `GET /workflow-runs`. Pagination uses `has_more` (there is no
+ * total count).
+ */
+interface WorkflowRunListResponse {
+    runs: WorkflowRunListItem[];
+    has_more: boolean;
+    limit: number;
+    offset: number;
+}
+/**
+ * A full durable run record, including input/output snapshots and attribution.
+ */
+interface WorkflowRunDetail {
+    /** The run table primary key (UUID). */
+    id: string;
+    run_id: string;
+    organization_id: string;
+    workflow_id: string | null;
+    trigger_type: string;
+    is_ad_hoc: boolean;
+    status: string;
+    user_id: string | null;
+    api_key_id: string | null;
+    schedule_id: string | null;
+    composer_chat_id: string | null;
+    thread_id: string | null;
+    chat_id: string | null;
+    deployment_id: string | null;
+    started_at: string | null;
+    completed_at: string | null;
+    duration_seconds: number | null;
+    error_message: string | null;
+    input_snapshot: unknown | null;
+    output_summary: unknown | null;
+    created_at: string;
+    updated_at: string;
+}
 
 /**
  * Types for workflow deployment management.
@@ -1001,12 +1413,14 @@ interface CreateDeploymentParams {
  */
 interface DeploymentResponse {
     id: string;
-    workflow_id: string;
+    /** Omitted from list rows by the backend; present on detail. */
+    workflow_id?: string;
     name: string;
     version: string;
     deployment_note: string | null;
     schema_image_url: string | null;
-    deployed_by: string;
+    /** Null when the deploying user is unknown/unrecorded. */
+    deployed_by: string | null;
     created_at: string;
     /** Whether this deployment is currently the live (active) version. */
     is_live: boolean;
@@ -1032,6 +1446,8 @@ interface DeploymentListResponse {
  * Returned by the get-single-deployment endpoint.
  */
 interface DeploymentDetailResponse extends DeploymentResponse {
+    /** Free-form description, present only on the detail response. */
+    description?: string | null;
     /** The full workflow graph definition at the time of this deployment. */
     workflow_schema: WorkflowDefinition;
     /** Default input values stored with the deployment. */
@@ -1046,8 +1462,8 @@ interface ActivateDeploymentResponse {
     success: boolean;
     message: string;
     deployment_id: string;
-    /** The deployment that was previously live, if any. */
-    previous_live_deployment_id: string | null;
+    /** The deployment that was previously live. Omitted in early-return branches. */
+    previous_live_deployment_id?: string | null;
 }
 /**
  * Response from deactivating the current live deployment.
@@ -1055,8 +1471,8 @@ interface ActivateDeploymentResponse {
 interface DeactivateDeploymentResponse {
     success: boolean;
     message: string;
-    /** The deployment that was deactivated. */
-    previous_live_deployment_id: string;
+    /** The deployment that was deactivated. Omitted in early-return branches. */
+    previous_live_deployment_id?: string | null;
 }
 /**
  * Response from deleting a deployment.
@@ -1083,22 +1499,29 @@ interface DeleteDeploymentResponse {
  */
 interface ChatResponse {
     id: string;
-    title: string | null;
-    creator_id: string;
+    /** Chat title — always present (backend `str`, non-nullable). */
+    title: string;
+    /** Creator user ID — nullable for system/org-owned chats. */
+    creator_id: string | null;
     is_private: boolean;
     /** ID of the currently in-progress run attached to this chat, if any. */
     running_id: string | null;
     created_at: string;
     updated_at: string;
-    organization_id?: string | null;
+    /** Owning organization ID — always present. */
+    organization_id: string;
     /** Messages are included when fetching a single chat with messages embedded. */
     messages?: ChatMessageResponse[];
     deleted_at?: string | null;
 }
 /**
  * The role of a participant in a chat message.
+ *
+ * Common values are `'human'`, `'ai'`, and `'system'`, but the backend stores
+ * the role as a free-form string (e.g. `'assistant'` may also appear), so any
+ * string is accepted while preserving autocomplete for the common values.
  */
-type ChatMessageRole = 'human' | 'ai' | 'system';
+type ChatMessageRole = 'human' | 'ai' | 'system' | (string & {});
 /**
  * A single message within a chat session.
  */
@@ -1115,6 +1538,8 @@ interface ChatMessageResponse {
     running_status?: string | null;
     created_at: string;
     updated_at: string;
+    /** Soft-deletion timestamp, if the message has been deleted. */
+    deleted_at?: string | null;
 }
 /**
  * Query parameters for paginating messages within a chat.
@@ -1125,25 +1550,40 @@ interface ChatMessagesParams {
 }
 /**
  * Paginated list of messages within a chat.
+ *
+ * Mirrors the backend `MessageListResponse`, which returns only the page of
+ * messages plus the echoed `limit`/`offset`. The `limit` is nullable because
+ * the backend leaves it unset when no limit was applied.
  */
 interface ChatMessagesResponse {
     messages: ChatMessageResponse[];
-    total: number;
-    limit: number;
+    limit: number | null;
     offset: number;
-    has_next: boolean;
-    /** The number of messages actually returned (may differ from `limit` on the last page). */
-    actual_count: number;
 }
 /**
  * Parameters for updating a chat's metadata.
  */
 interface UpdateChatParams {
     title?: string;
-    isPrivate?: boolean;
+    is_private?: boolean;
     /** Move the chat to a named folder (e.g. `"pinned"`, `"archived"`, or a custom name). */
     folder?: string;
 }
+/**
+ * A lightweight chat row as returned by the grouped list endpoint. Unlike
+ * {@link ChatResponse}, list rows do NOT include `organization_id`, `messages`,
+ * or `deleted_at`.
+ */
+interface ChatListItem {
+    id: string;
+    title: string;
+    /** Creator user ID — nullable for system/org-owned chats. */
+    creator_id: string | null;
+    is_private: boolean;
+    running_id: string | null;
+    created_at: string;
+    updated_at: string;
+}
 /**
  * Grouped chat list response.
  *
@@ -1156,7 +1596,29 @@ interface UpdateChatParams {
  * const pinned = list['pinned'] ?? [];
  * ```
  */
-type ChatListResponse = Record<string, ChatResponse[]>;
+type ChatListResponse = Record<string, ChatListItem[]>;
+/**
+ * Payload of the initial `connected` SSE event sent when the stream opens.
+ */
+interface ChatConnectedEvent {
+    status: 'connected';
+    /** ISO-8601 timestamp of when the connection was established. */
+    timestamp: string;
+}
+/**
+ * Payload of a `chat_list_updated` SSE event, emitted when the user's chat list
+ * changes and should be re-fetched via `GET /chats`.
+ */
+interface ChatListUpdatedEvent {
+    event: 'chat_list_updated';
+    /**
+     * Scope of the change: `"public"` affects all org users, `"private"` affects
+     * only the current user.
+     */
+    type: 'public' | 'private';
+    /** ISO-8601 timestamp of when the change occurred. */
+    timestamp: string;
+}
 
 /**
  * Types for credential management and MCP server connections.
@@ -1168,18 +1630,38 @@ type ChatListResponse = Record<string, ChatResponse[]>;
 interface CredentialResponse {
     credential_id: string;
     integration_name: string;
-    /** Integration category (e.g. `"tool"`, `"llm"`, `"knowledge"`). */
-    integration_type: string;
+    /** Integration category (e.g. `"tool"`, `"llm"`, `"knowledge"`). May be `null`. */
+    integration_type: string | null;
     /** Human-readable label for the credential. */
     display_name: string;
     /** Auth mechanism used (e.g. `"api_key"`, `"oauth2"`, `"basic"`). */
     auth_type: string;
     /** Whether this is the default credential for its integration. */
     is_default: boolean;
-    created_at: string;
-    updated_at: string;
+    created_at: string | null;
+    updated_at: string | null;
     last_used_at?: string | null;
     expires_at?: string | null;
+    /** Arbitrary metadata associated with the credential. */
+    credentials_metadata?: Record<string, unknown> | null;
+}
+/**
+ * Detailed credential record returned by `GET /credentials/{id}`.
+ * Extends {@link CredentialResponse} with ownership and masked-auth fields
+ * that are only present on the single-credential detail endpoint.
+ */
+interface CredentialDetailResponse extends CredentialResponse {
+    /** Organization that owns the credential. */
+    organization_id: string;
+    /** User ID that created the credential, if known. */
+    created_by: string | null;
+    /** Email of the user that created the credential, if known. */
+    created_by_email?: string | null;
+    /**
+     * Masked representation of the auth data when `include_masked=true`
+     * (e.g. `"OAuth2"`, `"sk-proj12...xyz"`). `null` when not requested.
+     */
+    auth_data_masked?: string | null;
 }
 /**
  * Parameters for creating a new credential.
@@ -1301,8 +1783,8 @@ interface CredentialUsageResponse {
     success_rate: number;
     /** Call counts broken down by action / operation name. */
     action_breakdown: Record<string, number>;
-    start_date: string;
-    end_date: string;
+    start_date: string | null;
+    end_date: string | null;
 }
 /**
  * Query parameters for paginating a credential's audit log.
@@ -1311,6 +1793,27 @@ interface CredentialAuditParams {
     limit?: number;
     offset?: number;
 }
+/**
+ * A single audit log entry for a credential, as returned by
+ * `GET /credentials/{id}/audit`.
+ */
+interface AuditLogResponse {
+    id: string;
+    /** ID of the credential this entry belongs to. */
+    credential_id: string;
+    /** Type of event recorded (e.g. `"created"`, `"updated"`, `"used"`). */
+    event_type: string;
+    /** User ID that triggered the event, if known. */
+    user_id: string | null;
+    /** Structured details of what changed during the event. */
+    changes: Record<string, unknown>;
+    /** Source IP address of the request, if recorded. */
+    ip_address: string | null;
+    /** User-agent of the request, if recorded. */
+    user_agent: string | null;
+    /** ISO-8601 timestamp of when the event occurred. */
+    timestamp: string;
+}
 /**
  * Parameters for connecting a Model Context Protocol (MCP) server as a credential.
  */
@@ -1325,11 +1828,29 @@ interface McpServerParams {
     makeDefault?: boolean;
 }
 /**
- * Response listing tools discovered from an MCP server credential.
+ * Response from creating a Model Context Protocol (MCP) server credential
+ * via `POST /credentials/mcp-server`.
+ *
+ * Note: this is a narrower shape than {@link CredentialResponse} — the
+ * backend `MCPServerCredentialResponse` omits `updated_at`, `integration_type`,
+ * `last_used_at`, and `expires_at`.
  */
-interface McpToolsResponse {
+interface MCPServerCredentialResponse {
     credential_id: string;
-    /** Array of tool descriptors in MCP schema format. */
+    integration_name: string;
+    display_name: string;
+    auth_type: string;
+    is_default: boolean;
+    created_at: string | null;
+    /** Arbitrary metadata associated with the credential. */
+    credentials_metadata?: Record<string, unknown> | null;
+}
+/**
+ * Response listing tools discovered from an MCP server credential.
+ */
+interface McpToolsResponse {
+    credential_id: string;
+    /** Array of tool descriptors in MCP schema format. */
     tools: Record<string, unknown>[];
     total_count: number;
 }
@@ -1344,6 +1865,92 @@ interface RefreshDiscoveryResponse {
     total_tools: number;
     success: boolean;
 }
+/**
+ * Parameters for initiating an OAuth2 authorization flow via
+ * `POST /credentials/oauth2/initiate`.
+ *
+ * Requires admin/owner role on the target organization.
+ */
+interface InitiateOAuth2Params {
+    /** Integration name to start the OAuth2 flow for (e.g. `"github"`). */
+    integrationName: string;
+    /** Whether to use ModuleX's managed OAuth app. Defaults to `true` server-side. */
+    useModulexOauth?: boolean;
+    /** Custom OAuth app config; required when `useModulexOauth` is `false`. */
+    customOauthConfig?: Record<string, unknown>;
+    /** Callback URL the provider should redirect back to after authorization. */
+    redirectUri: string;
+    /** Space-separated OAuth scopes to request. Defaults to the integration's scopes. */
+    scope?: string;
+    /** Human-readable label for the credential that will be created. */
+    displayName?: string;
+    /** Whether to set the resulting credential as the default for its integration. */
+    makeDefault?: boolean;
+    /**
+     * Per-user setup environment variables to inject into the persisted
+     * `auth_data`, keyed by raw env-var name.
+     */
+    envVarValues?: Record<string, string>;
+    /** Composer chat ID to atomically resume after the callback completes. */
+    composerChatId?: string;
+    /** Composer interrupt request ID, validated on callback. */
+    composerRequestId?: string;
+    /** LLM provider config used to rebuild the chat model on composer resume. */
+    composerLlmConfig?: Record<string, unknown>;
+}
+/**
+ * Response from initiating an OAuth2 flow. The caller should redirect the
+ * user's browser to `authorization_url` to complete authorization.
+ */
+interface OAuth2InitiateResponse {
+    /** Provider authorization URL the user must visit to grant access. */
+    authorization_url: string;
+    /** Opaque CSRF/state token correlated with this flow. */
+    state: string;
+}
+/**
+ * Per-integration status entry emitted in bulk ModuleX-key SSE events.
+ */
+interface ModulexKeyIntegrationStatus {
+    integration_name: string;
+    integration_type: string;
+    display_name: string;
+    /** Whether a ModuleX-managed key credential already exists for this integration. */
+    has_modulex_key_credential: boolean;
+}
+/**
+ * Summary counts emitted in the terminal (`completed`) bulk ModuleX-key event.
+ */
+interface ModulexKeyBulkSummary {
+    total: number;
+    created: number;
+    already_existed: number;
+}
+/**
+ * Typed `data` payload of a bulk ModuleX-key provisioning SSE event.
+ *
+ * Emitted by `POST /credentials/bulk-modulex-keys/stream`. The `phase`
+ * field discriminates the lifecycle stage; phase-specific extras are
+ * optional and only present on the relevant phases.
+ */
+interface ModulexKeyBulkEventData {
+    /** Lifecycle phase of the bulk provisioning stream. */
+    phase: 'initial_status' | 'creating' | 'retrying' | 'completed';
+    /** Current per-integration statuses. */
+    integrations?: ModulexKeyIntegrationStatus[];
+    /** Whether the overall operation has completed. */
+    completed?: boolean;
+    /** Integrations created during this phase. */
+    just_created?: string[];
+    /** Number of integrations being retried. */
+    retrying_count?: number;
+    /** Final summary counts, present on the `completed` phase. */
+    summary?: ModulexKeyBulkSummary;
+    /** Human-readable status message. */
+    message?: string;
+    /** Error message when a phase fails. */
+    error?: string;
+}
 
 /**
  * Types for browsing the integration catalog and fetching provider details.
@@ -1369,63 +1976,147 @@ interface BrowseParams {
     pageSize?: number;
 }
 /**
- * Response from the catalog browse endpoint.
- */
-interface BrowseResponse {
-    integrations: IntegrationResponse[];
-    total: number;
-    page?: number;
-    page_size?: number;
-    total_pages?: number;
-}
-/**
- * Generic integration object as returned by catalog and detail endpoints.
- * Fields beyond the listed ones are provider-specific and accessed via the index signature.
+ * Integration metadata as returned by list/browse endpoints
+ * (`/integrations/browse`, `/integrations/tools`, `/integrations/llm-providers`,
+ * `/integrations/knowledge-providers`).
+ *
+ * Mirrors the backend `IntegrationMetadata` model. Wire field names are
+ * snake_case and are returned as-is by the client (no camelCase conversion).
+ *
+ * Note: when `include_details=false` on browse, the backend strips
+ * `actions`, `models`, and `auth_schemas` from each element, hence those
+ * fields are optional.
  */
-interface IntegrationResponse {
+interface IntegrationMetadata {
+    /** Canonical integration name / identifier. */
     name: string;
-    /** Integration category (e.g. `"tool"`, `"llm_provider"`, `"knowledge_provider"`). */
-    type: string;
-    display_name?: string;
-    description?: string;
-    /** Available action/service names. */
-    actions?: string[];
-    /** Authentication schema descriptors. */
-    auth_schemas?: Record<string, unknown>[];
-    icon_url?: string;
+    /** Human-readable display name (always present). */
+    display_name: string;
+    /** Human-readable description (always present). */
+    description: string;
+    /** Logo URL, if any. */
+    logo?: string | null;
+    /** Marketing / app URL, if any. */
+    app_url?: string | null;
+    /** Documentation URL, if any. */
+    docs_url?: string | null;
+    /** Categories this integration belongs to. */
+    categories?: string[];
+    /** Integration type (e.g. `"tool"`, `"llm_provider"`, `"knowledge_provider"`). */
+    integration_type: string;
+    /** Integration version, if any. */
+    version?: string | null;
+    /** Lifecycle status (e.g. `"active"`). */
+    status?: string;
+    /** Whether this integration is recommended. */
+    recommended?: boolean;
+    /** Tool action descriptors (present only when details are included). */
+    actions?: Record<string, unknown>[];
+    /** LLM provider model descriptors (present only when details are included). */
+    models?: Record<string, unknown>[];
+    /** Auth requirement descriptors (present only when details are included). */
+    auth_schemas?: AuthSchema[];
     [key: string]: unknown;
 }
 /**
- * Detailed tool integration response including action definitions.
- */
-interface ToolIntegrationResponse {
-    integration_name: string;
-    display_name?: string;
-    description?: string;
-    /** Map of action name to action descriptor. */
-    actions?: Record<string, unknown>;
-    auth_types?: string[];
+ * Authentication schema descriptor as returned by detail endpoints.
+ *
+ * For `oauth2` schemas the backend enriches the descriptor with the
+ * `supports_modulex_oauth` / `supports_custom_oauth` boolean flags.
+ */
+interface AuthSchema {
+    /** Auth type discriminator (e.g. `"api_key"`, `"oauth2"`). */
+    auth_type?: string;
+    /** Whether ModuleX-managed OAuth is available for this provider (oauth2 only). */
+    supports_modulex_oauth?: boolean;
+    /** Whether custom OAuth credentials are supported (oauth2 only). */
+    supports_custom_oauth?: boolean;
     [key: string]: unknown;
 }
 /**
- * Detailed LLM provider response including available models.
+ * Detailed integration information as returned by the detail endpoints
+ * (`/integrations/{integration_name}`, `/integrations/tools/{name}`,
+ * `/integrations/llm-providers/{name}`, `/integrations/knowledge-providers/{name}`).
+ *
+ * Mirrors the backend `IntegrationDetail` model. Wire field names are
+ * snake_case and are returned as-is by the client (no camelCase conversion).
  */
-interface LLMProviderResponse {
-    provider_name: string;
-    display_name?: string;
+interface IntegrationDetail {
+    /** Canonical integration name / identifier. */
+    name: string;
+    /** Human-readable display name (always present). */
+    display_name: string;
+    /** Human-readable description (always present). */
+    description: string;
+    /** Logo URL, if any. */
+    logo?: string | null;
+    /** Marketing / app URL, if any. */
+    app_url?: string | null;
+    /** Documentation URL, if any. */
+    docs_url?: string | null;
+    /** Categories this integration belongs to. */
+    categories?: string[];
+    /** Integration type (e.g. `"tool"`, `"llm_provider"`, `"knowledge_provider"`). */
+    integration_type: string;
+    /** Integration version, if any. */
+    version?: string | null;
+    /** Auth requirement descriptors (OAuth-enriched where applicable). */
+    auth_schemas?: AuthSchema[];
+    /** Tool action descriptors (for tools). */
+    actions?: Record<string, unknown>[];
+    /** LLM provider model descriptors (for LLM providers). */
     models?: Record<string, unknown>[];
-    auth_types?: string[];
+    /** Supported feature flags, if any. */
+    features?: string[] | null;
+    /** Arbitrary provider-specific metadata, if any. */
+    metadata?: Record<string, unknown> | null;
     [key: string]: unknown;
 }
 /**
- * Detailed knowledge provider response including supported collection features.
+ * Response from the catalog browse endpoint (`/integrations/browse`).
+ *
+ * Mirrors the backend `BrowseResponse` model. The `integrations` array
+ * carries `IntegrationMetadata` elements (not full details).
  */
-interface KnowledgeProviderResponse {
-    provider_name: string;
-    display_name?: string;
-    auth_types?: string[];
-    [key: string]: unknown;
+interface BrowseResponse {
+    /** Catalog entries for the current page. */
+    integrations: IntegrationMetadata[];
+    /** Total number of matching integrations across all pages. */
+    total: number;
+    /** Current page number (always present). */
+    page: number;
+    /** Page size (always present). */
+    page_size: number;
+    /** Whether more pages are available after the current one. */
+    has_more: boolean;
 }
+/**
+ * Generic integration detail as returned by `/integrations/{integration_name}`.
+ *
+ * Backend `response_model=IntegrationDetail`.
+ */
+type IntegrationResponse = IntegrationDetail;
+/**
+ * Detailed tool integration response, including action definitions, as
+ * returned by `/integrations/tools/{integration_name}`.
+ *
+ * Backend `response_model=IntegrationDetail` (`actions` populated).
+ */
+type ToolIntegrationResponse = IntegrationDetail;
+/**
+ * Detailed LLM provider response, including available models, as returned by
+ * `/integrations/llm-providers/{provider_name}`.
+ *
+ * Backend `response_model=IntegrationDetail` (`models` populated).
+ */
+type LLMProviderResponse = IntegrationDetail;
+/**
+ * Detailed knowledge provider response as returned by
+ * `/integrations/knowledge-providers/{provider_name}`.
+ *
+ * Backend `response_model=IntegrationDetail`.
+ */
+type KnowledgeProviderResponse = IntegrationDetail;
 
 /**
  * Types for knowledge base management, document ingestion, and semantic search.
@@ -1433,16 +2124,26 @@ interface KnowledgeProviderResponse {
  */
 /**
  * Configuration for the embedding model used to vectorize documents and queries.
+ *
+ * The backend stores `embedding_config` as a free-form object, but the keys it
+ * actually reads are `credential_id` and `model_id`. Field names here are kept
+ * in snake_case to match the wire shape the embedding pipeline consumes.
  */
 interface EmbeddingConfig {
-    /** Credential ID for the embedding provider. */
-    provider_credential_id?: string;
+    /**
+     * Credential ID for the embedding provider. This is the key the backend
+     * reads (`embedding_config.credential_id`); the embedding pipeline uses it
+     * to resolve provider authentication.
+     */
+    credential_id?: string;
     /** Provider name (e.g. `"openai"`, `"cohere"`). */
     provider?: string;
     /** Model identifier (e.g. `"text-embedding-3-small"`). */
-    model?: string;
+    model_id?: string;
     /** Expected vector dimension for the model. */
     dimension?: number;
+    /** Allow additional provider-specific configuration keys. */
+    [key: string]: unknown;
 }
 /**
  * Configuration for how documents are split into chunks before indexing.
@@ -1452,8 +2153,13 @@ interface ChunkingConfig {
     strategy?: string;
     /** Target token/character count per chunk. */
     chunk_size?: number;
-    /** Overlap in tokens/characters between consecutive chunks. */
-    overlap?: number;
+    /**
+     * Overlap in tokens/characters between consecutive chunks.
+     *
+     * Wire field name is `chunk_overlap` — the embedding pipeline reads this key.
+     * (Previously named `overlap`, which the backend silently dropped.)
+     */
+    chunk_overlap?: number;
     /** Custom separator strings used by recursive/sentence strategies. */
     separators?: string[];
 }
@@ -1488,14 +2194,24 @@ interface KnowledgeBaseResponse {
     name: string;
     description: string | null;
     organization_id: string;
+    /** User ID of the member who created the knowledge base. */
+    created_by_user_id: string;
+    /** Credential ID associated with the knowledge base, if any. */
+    credential_id: string | null;
     embedding_config: EmbeddingConfig;
     chunking_config: ChunkingConfig;
+    /** Number of documents in the knowledge base. Always present. */
+    document_count: number;
+    /** Total number of indexed chunks. Always present. */
+    total_chunks: number;
+    /** Total number of tokens across all chunks. Always present. */
+    total_tokens: number;
     /** Lifecycle status (e.g. `"active"`, `"building"`, `"error"`). */
     status: string;
-    document_count?: number;
-    total_chunks?: number;
-    created_at: string;
-    updated_at: string;
+    created_at: string | null;
+    updated_at: string | null;
+    /** Optional aggregated statistics for the knowledge base. */
+    stats?: Record<string, unknown> | null;
 }
 /**
  * Query parameters for listing knowledge bases.
@@ -1505,21 +2221,22 @@ interface KnowledgeBaseListParams {
     limit?: number;
     offset?: number;
 }
-/**
- * Paginated list of knowledge bases.
- */
-interface KnowledgeBaseListResponse {
-    knowledge_bases: KnowledgeBaseResponse[];
-    total: number;
-    limit: number;
-    offset: number;
-}
 /**
  * Aggregated statistics across all knowledge bases in an organization.
- * The shape is extensible; provider-specific fields may be present.
+ *
+ * Mirrors the backend `OrganizationStatsResponse` shape.
  */
 interface KnowledgeBaseStatsResponse {
-    [key: string]: unknown;
+    /** Number of knowledge bases in the organization. */
+    knowledge_base_count: number;
+    /** Total number of documents across all knowledge bases. */
+    total_documents: number;
+    /** Total number of indexed chunks across all knowledge bases. */
+    total_chunks: number;
+    /** Total number of tokens across all knowledge bases. */
+    total_tokens: number;
+    /** Combined byte size of all stored files. */
+    total_file_size_bytes: number;
 }
 /**
  * A document record as returned by the API.
@@ -1529,13 +2246,17 @@ interface DocumentResponse {
     knowledge_base_id: string;
     filename: string;
     file_type: string;
-    file_size: number;
-    /** Processing status (e.g. `"pending"`, `"processing"`, `"ready"`, `"error"`). */
+    /** Size of the source file in bytes. */
+    file_size_bytes: number | null;
+    /** Processing status: `"pending"`, `"processing"`, `"completed"`, or `"failed"`. */
     status: string;
-    metadata?: Record<string, unknown>;
-    chunk_count?: number;
-    created_at: string;
-    updated_at: string;
+    /** Number of chunks produced from this document. */
+    chunk_count: number;
+    /** Number of tokens across this document's chunks. */
+    token_count: number;
+    /** Error message if processing failed; `null` otherwise. */
+    error_message: string | null;
+    created_at: string | null;
 }
 /**
  * Query parameters for listing documents within a knowledge base.
@@ -1557,20 +2278,43 @@ interface UploadDocumentParams {
     metadata?: Record<string, unknown>;
 }
 /**
- * Status and progress of a document being processed.
+ * Processing status of a document.
+ *
+ * This endpoint has no `response_model`; it returns the raw service dict.
+ * `document_id`, `status`, `filename`, and `file_type` are always present.
+ * The remaining fields are conditional on `status`.
  */
 interface DocumentStatusResponse {
+    document_id: string;
+    /** Processing status: `"pending"`, `"processing"`, `"completed"`, or `"failed"`. */
     status: string;
-    /** Processing progress as a fraction (0–1). */
-    progress?: number;
-    error?: string;
+    filename: string;
+    file_type: string;
+    /** Human-readable status message. */
+    message?: string;
+    /** Present only when `status` is `"processing"`. */
+    processing_started_at?: string | null;
+    /** Present only when `status` is `"completed"`. */
+    processing_completed_at?: string | null;
+    /** Present only when `status` is `"completed"`. */
+    chunk_count?: number;
+    /** Present only when `status` is `"completed"`. */
+    token_count?: number;
+    /** Present only when `status` is `"failed"`. */
+    error?: string | null;
 }
 /**
  * A single document chunk as returned by the chunks endpoint or a search result.
  */
 interface ChunkResponse {
     id: string;
+    /** ID of the document this chunk belongs to. */
+    document_id?: string;
+    /** Position of this chunk within its document. */
+    chunk_index?: number;
     content: string;
+    /** Number of tokens in this chunk. */
+    token_count?: number;
     metadata?: Record<string, unknown>;
     /** Similarity score (0–1). Present only in search results. */
     score?: number;
@@ -1601,22 +2345,35 @@ interface SearchParams {
     includeMetadata?: boolean;
 }
 /**
- * A single search result entry.
+ * A single search match entry.
+ *
+ * `content` and `metadata` are present only when the request enabled
+ * `includeContent` / `includeMetadata` (both default to `true`).
  */
-interface SearchResult {
+interface SearchMatch {
     chunk_id: string;
-    content: string;
-    score: number;
-    metadata: Record<string, unknown>;
     document_id: string;
+    /** Filename of the document the matching chunk belongs to. */
+    document_filename: string;
+    /** Position of the matching chunk within its document. */
+    chunk_index: number;
+    score: number;
+    /** Chunk content; omitted when `includeContent` is `false`. */
+    content?: string;
+    /** Chunk metadata; omitted when `includeMetadata` is `false`. */
+    metadata?: Record<string, unknown>;
 }
 /**
  * Response from a knowledge base search.
+ *
+ * Returned by `search`, `searchMultiple`, and `hybridSearch`.
  */
 interface SearchResponse {
-    results: SearchResult[];
     query: string;
-    total: number;
+    knowledge_base_id: string;
+    top_k: number;
+    total_matches: number;
+    matches: SearchMatch[];
 }
 /**
  * Parameters for searching across multiple knowledge bases simultaneously.
@@ -1697,14 +2454,12 @@ interface CreateScheduleParams {
  * All fields are optional; only provided fields are updated.
  */
 interface UpdateScheduleParams {
-    workflowId?: string;
     name?: string;
     description?: string;
     scheduleType?: 'interval' | 'cron';
     intervalSeconds?: number;
     cronExpression?: string;
     timezone?: string;
-    isActive?: boolean;
     input?: Record<string, unknown>;
     config?: Record<string, unknown>;
 }
@@ -1714,6 +2469,8 @@ interface UpdateScheduleParams {
 interface ScheduleResponse {
     id: string;
     workflow_id: string;
+    /** Organization that owns this schedule. */
+    organization_id: string;
     name: string;
     description: string | null;
     schedule_type: 'interval' | 'cron';
@@ -1721,14 +2478,23 @@ interface ScheduleResponse {
     cron_expression?: string | null;
     /** IANA timezone name. */
     timezone: string;
+    /** State input passed to the workflow on each scheduled run. Always present (defaults to `{}`). */
+    input: Record<string, unknown>;
+    /** Runtime config overrides applied to each scheduled run. Always present (defaults to `{}`). */
+    config: Record<string, unknown>;
     is_active: boolean;
-    input?: Record<string, unknown> | null;
-    config?: Record<string, unknown> | null;
     next_run_at?: string | null;
     last_run_at?: string | null;
+    /** Status of the most recent run, or `null` if the schedule has never run. */
+    last_run_status?: string | null;
+    /** Total number of runs recorded for this schedule. */
+    total_runs: number;
+    /** Number of runs that completed successfully. */
+    successful_runs: number;
+    /** Number of runs that failed. */
+    failed_runs: number;
     created_at: string;
     updated_at: string;
-    created_by: string;
 }
 /**
  * Query parameters for listing schedules.
@@ -1754,12 +2520,28 @@ interface ScheduleListResponse {
 interface ScheduleRunResponse {
     id: string;
     schedule_id: string;
+    /** Workflow executed by this run, or `null` if not associated. */
+    workflow_id?: string | null;
+    /** Underlying execution run identifier, or `null`. */
+    run_id?: string | null;
+    /** Thread identifier for the run, or `null`. */
+    thread_id?: string | null;
+    /** Time the run was scheduled to execute. */
+    scheduled_at: string;
+    /** Time the run actually started, or `null` if it has not started. */
+    started_at?: string | null;
+    completed_at?: string | null;
+    /** Run duration in seconds, or `null` if unavailable. */
+    duration_seconds?: number | null;
     /** Run status (e.g. `"completed"`, `"failed"`, `"running"`). */
     status: string;
-    started_at: string;
-    completed_at?: string | null;
-    error?: string | null;
-    duration_ms?: number | null;
+    /** Failure message when the run failed, or `null`. */
+    error_message?: string | null;
+    /** How the run was triggered (e.g. `"scheduler"`, `"manual"`). */
+    triggered_by: string;
+    /** Deployment used for the run, or `null`. */
+    deployment_id?: string | null;
+    created_at: string;
 }
 /**
  * Query parameters for listing runs belonging to a schedule.
@@ -1769,6 +2551,15 @@ interface ScheduleRunListParams {
     limit?: number;
     offset?: number;
 }
+/**
+ * Paginated list of scheduled runs.
+ */
+interface ScheduleRunListResponse {
+    runs: ScheduleRunResponse[];
+    total: number;
+    limit: number;
+    offset: number;
+}
 /**
  * Query parameters for fetching aggregate run statistics.
  */
@@ -1780,120 +2571,145 @@ interface ScheduleRunStatsParams {
  * Aggregate run statistics for a schedule.
  */
 interface ScheduleRunStatsResponse {
+    /** Number of past days covered by this stats window. */
+    period_days: number;
     total_runs: number;
     successful_runs: number;
     failed_runs: number;
-    average_duration_ms: number;
-}
-
-/**
- * Types for workflow templates and creator profiles.
- * @module types/templates
- */
-
-/**
- * Public profile information for a template creator.
- */
-interface CreatorInfo {
-    name: string;
-    display_photo?: string | null;
-    about?: string | null;
-    /** Map of social platform name to profile URL. */
-    socials?: Record<string, string>;
-}
-/**
- * A template record as returned by the API.
- */
-interface TemplateResponse {
-    id: string;
-    creator_id: string;
-    creator?: CreatorInfo | null;
-    name: string;
-    description: string | null;
-    tags: string[];
-    workflow_schema: WorkflowDefinition;
-    input?: Record<string, unknown> | null;
-    config?: Record<string, unknown> | null;
-    schema_image_url?: string | null;
-    /** Sharing visibility (e.g. `"private"`, `"public"`). */
-    visibility: string;
-    /** Lifecycle status (e.g. `"draft"`, `"published"`). */
-    status: string;
-    like_count: number;
-    used_count: number;
-    /** Whether the authenticated user has liked this template. */
-    is_liked?: boolean;
-    edit_version?: number | null;
-    created_at: string;
-    updated_at: string;
+    /** Fraction of runs that succeeded (0.0–1.0). */
+    success_rate: number;
+    /** Average run duration in seconds, or `null` if no runs. */
+    avg_duration_seconds?: number | null;
+    /** Minimum run duration in seconds, or `null` if no runs. */
+    min_duration_seconds?: number | null;
+    /** Maximum run duration in seconds, or `null` if no runs. */
+    max_duration_seconds?: number | null;
 }
 /**
- * Response from the public template browse endpoint.
+ * Response returned when retrying a scheduled run.
  */
-interface TemplateListResponse {
-    templates: TemplateResponse[];
-    /** Whether the response was served from cache. */
-    cached?: boolean;
+interface RetryRunResponse {
+    message: string;
+    /** Identifier of the original run that was retried. */
+    original_run_id: string;
 }
 /**
- * Response from listing templates created by the authenticated user.
+ * Response returned when deleting a schedule.
  */
-interface MyTemplatesResponse {
-    templates: TemplateResponse[];
-    total: number;
+interface DeleteScheduleResponse {
+    message: string;
 }
+
 /**
- * Parameters for publishing a workflow as a template.
- */
-interface CreateTemplateParams {
-    /** ID of the saved workflow to publish as a template. */
-    workflowId: string;
-    name?: string;
+ * Human-in-the-Loop (HITL) wire contract — discriminated unions for structured
+ * questions the agent asks (`UserInputRequest`) and the answers the client sends
+ * back on resume (`UserInputResponse`).
+ *
+ * Shared by the Composer and Assistant resources. Mirrors the backend
+ * `app/models/composer_events.py`. Discriminate on the `kind` field.
+ * @module types/hitl
+ */
+/** A selectable option in a single/multi choice question. */
+interface ChoiceOption {
+    value: string;
+    label: string;
     description?: string;
-    tags?: string[];
-    /** URL to a preview image of the workflow canvas. */
-    schemaImageUrl?: string;
+    icon?: string;
+    badge?: string;
 }
-/**
- * Response from using (importing) a template into the user's workspace.
- */
-interface TemplateUseResponse {
-    success: boolean;
+/** One way to authenticate when answering a credential request. */
+interface CredentialAuthOption {
+    auth_type: 'oauth2' | 'api_key' | 'bearer_token' | 'modulex_key' | 'custom';
+    display_name: string;
+    fields?: Record<string, unknown>[];
+    oauth_initiate_endpoint?: string;
+    setup_instructions?: string[];
+    test_supported: boolean;
+}
+/** Fields common to every user-input request. */
+interface UserInputRequestBase {
+    request_id: string;
+    /** Markdown-supported prompt shown to the user. */
     message: string;
-    /** The newly created workflow in the user's workspace. */
-    workflow: WorkflowResponse;
-    used_count: number;
+    /** Whether the user is allowed to skip. */
+    required: boolean;
+    /** Escape hatch: allow a "write your own" answer. */
+    allow_free_text: boolean;
+    context?: Record<string, unknown> | null;
+    timeout_hint_seconds?: number | null;
+}
+interface SingleChoiceRequest extends UserInputRequestBase {
+    kind: 'single_choice';
+    options: ChoiceOption[];
+}
+interface MultiChoiceRequest extends UserInputRequestBase {
+    kind: 'multi_choice';
+    options: ChoiceOption[];
+    min_selections: number;
+    max_selections?: number | null;
+}
+interface YesNoRequest extends UserInputRequestBase {
+    kind: 'yes_no';
+    yes_label: string;
+    no_label: string;
+}
+interface FreeTextRequest extends UserInputRequestBase {
+    kind: 'free_text';
+    placeholder?: string | null;
+    multiline: boolean;
+    min_length: number;
+    max_length?: number | null;
+}
+interface CredentialRequest extends UserInputRequestBase {
+    kind: 'credential_request';
+    integration_name: string;
+    integration_display_name: string;
+    integration_logo?: string | null;
+    auth_options: CredentialAuthOption[];
+    pending_node_name?: string | null;
+}
+/** A structured question the agent asks while paused. Discriminate on `kind`. */
+type UserInputRequest = SingleChoiceRequest | MultiChoiceRequest | YesNoRequest | FreeTextRequest | CredentialRequest;
+interface SingleChoiceResponse {
+    kind: 'single_choice';
+    selected_value?: string;
+    free_text?: string;
+}
+interface MultiChoiceResponse {
+    kind: 'multi_choice';
+    selected_values: string[];
+}
+interface YesNoResponse {
+    kind: 'yes_no';
+    answer: boolean;
+}
+interface FreeTextResponse {
+    kind: 'free_text';
+    text: string;
+}
+interface CredentialAddedResponse {
+    kind: 'credential_added';
+    credential_id: string;
+    integration_name: string;
+    auth_type: string;
 }
-/**
- * Response from liking or un-liking a template.
- */
-interface TemplateLikeResponse {
-    success: boolean;
-    /** `true` if the template is now liked, `false` if the like was removed. */
-    liked: boolean;
-    like_count: number;
+/** Reason codes for a failed credential attempt. */
+type CredentialFailureCode = 'oauth_denied' | 'oauth_provider_error' | 'invalid_credentials' | 'network_error' | 'popup_closed' | 'timeout' | 'unknown';
+interface CredentialFailedResponse {
+    kind: 'credential_failed';
+    integration_name: string;
+    auth_type: string;
+    error_code: CredentialFailureCode;
+    error_message: string;
+    retryable?: boolean;
+    provider_details?: Record<string, unknown> | null;
 }
-/**
- * Parameters for requesting an update to a published template.
- */
-interface UpdateTemplateRequestParams {
-    /** ID of the updated workflow to sync into the template. */
-    workflowId: string;
-    name?: string;
-    description?: string;
-    tags?: string[];
-    schemaImageUrl?: string;
-}
-/**
- * Parameters for creating or updating a template creator profile.
- */
-interface CreateCreatorParams {
-    name: string;
-    about?: string;
-    displayPhoto?: string;
-    /** Map of social platform name to profile URL. */
-    socials?: Record<string, string>;
+interface SkippedResponse {
+    kind: 'skipped';
+    reason?: string;
 }
+/** The answer the client sends back to resume a paused run. Discriminate on `kind`. */
+type UserInputResponse = SingleChoiceResponse | MultiChoiceResponse | YesNoResponse | FreeTextResponse | CredentialAddedResponse | CredentialFailedResponse | SkippedResponse;
 
 /**
  * Types for the AI Composer — a chat-driven workflow builder.
@@ -1908,13 +2724,16 @@ interface ComposerChatParams {
     workflowId?: string;
     /** ID of an existing Composer chat to continue. Omit to start a new session. */
     composerChatId?: string;
-    /** The user's message to the Composer AI. */
+    /** The user's message to the Composer AI (required). */
     message: string;
-    /** Override the LLM used by the Composer AI. */
+    /** Override the LLM. Defaults to the organization's configured composer LLM. */
     llm?: LLMConfig;
 }
 /**
  * Response from starting or continuing a Composer chat session.
+ *
+ * Note: `POST /composer/chat` returns 409 if the chat has a pending HITL
+ * question — answer it via `resume()` before sending a new message.
  */
 interface ComposerChatResponse {
     status: string;
@@ -1930,19 +2749,33 @@ interface ComposerChatResponse {
  */
 interface ComposerMessageResponse {
     id: string;
+    /** Persisted roles are `human`/`ai`; `system` may appear for system entries. */
     role: 'human' | 'ai' | 'system';
     content: string;
+    /** The agent's reasoning trace, when present. */
+    thinking?: string | null;
+    /** Workflow changes produced by this message, when present. */
+    workflow_changes?: Record<string, unknown> | null;
+    /** The run that produced this message, when applicable. */
+    run_id?: string | null;
+    /** Running status of this message, when applicable. */
+    running_status?: string | null;
     created_at: string;
 }
 /**
- * Full Composer chat detail including messages and workflow snapshot status.
+ * Full Composer chat detail including messages and live HITL state.
  */
 interface ComposerChatDetailResponse {
     id: string;
     workflow_id: string | null;
+    title: string;
     messages: ComposerMessageResponse[];
-    /** Whether there is a saved workflow snapshot associated with this chat. */
-    snapshot_status: string | null;
+    /** The currently-running run ID, or null when idle. */
+    running_id: string | null;
+    /** IDs of every workflow this chat has touched. */
+    touched_workflow_ids: string[];
+    /** The open HITL question awaiting an answer, rehydrated, or null. */
+    pending_user_input_request: UserInputRequest | null;
     /** Whether the AI has produced changes not yet saved to the workflow. */
     has_pending_changes: boolean;
     created_at: string;
@@ -1957,14 +2790,100 @@ interface ComposerStatusResponse {
     is_running: boolean;
     running_id: string | null;
     has_pending_changes: boolean;
-    /** Status of the most recent run attached to this Composer session. */
-    run_status: string | null;
+    /** True when the run is paused on a HITL question (do NOT re-attach SSE). */
+    awaiting_input: boolean;
+    /** The pending HITL request id when `awaiting_input`, else null. */
+    pending_request_id: string | null;
+    /** The Redis status payload for the latest run, or null. */
+    run_status: Record<string, unknown> | null;
+}
+/** Canvas-sync payload returned by save/revert so the client can refresh state. */
+interface ComposerWorkflowSync {
+    workflow_id: string;
+    edit_version: number;
+    workflow: {
+        nodes: unknown[];
+        edges: unknown[];
+        metadata: Record<string, unknown>;
+        state_schema: Record<string, unknown>;
+    };
+    input: Record<string, unknown> | null;
+}
+/** Optional targeting body for save/revert (defaults to the chat's focused workflow). */
+interface ComposerSaveParams {
+    /** Target a specific touched workflow instead of the focused one. */
+    workflowId?: string;
+}
+/** Response from saving Composer changes. */
+interface ComposerSaveResponse {
+    status: 'saved';
+    workflow_id: string;
+    workflow_name: string;
+    message: string;
+    workflow_sync: ComposerWorkflowSync | null;
+}
+/** Response from reverting Composer changes. */
+interface ComposerRevertResponse {
+    status: 'reverted';
+    workflow_id: string;
+    workflow_name: string;
+    message: string;
+    workflow_sync: ComposerWorkflowSync | null;
 }
 /**
- * Query parameters for listing Composer chat history.
+ * Body for `POST /composer/chat/{id}/resume` — answers an open HITL question.
  */
-interface ComposerHistoryParams {
+interface ComposerResumeParams {
+    /** The `request_id` of the open question (from the `user_input_request` event). */
+    requestId: string;
+    /** The structured answer (discriminated on `kind`). */
+    response: UserInputResponse;
+    /**
+     * LLM config used to rebuild the chat model on resume. Optional in the wire
+     * schema, but required in production — the backend returns 400 if omitted.
+     */
+    llm?: LLMConfig;
+}
+/** Response from resuming a paused Composer run. */
+interface ComposerResumeResponse {
+    status: 'resuming';
+    composer_chat_id: string;
+    /** A NEW run_id for the resumed execution. */
+    run_id: string;
+    thread_id: string;
+    stream_url: string;
+}
+/** Body for `PATCH /composer/chat/{id}/focus`. `null` clears the focus. */
+interface ComposerFocusParams {
+    /** The workflow to focus, or `null` to clear. The key must be present. */
+    workflowId: string | null;
+}
+/** Response from changing a chat's focused workflow. */
+interface ComposerFocusResponse {
+    composer_chat_id: string;
+    workflow_id: string | null;
+    updated_at: string;
+}
+/** Query parameters for listing the user's Composer chats. */
+interface ComposerListParams {
+    /** Page size, 1–100 (default 20). */
     limit?: number;
+    /** ISO `updated_at` timestamp cursor for the next page. */
+    cursor?: string;
+}
+/** A row in the user's Composer chat list. */
+interface ComposerChatListItem {
+    id: string;
+    workflow_id: string | null;
+    title: string;
+    created_at: string;
+    updated_at: string;
+    is_running: boolean;
+}
+/** Cursor-paginated list of the user's Composer chats. */
+interface ComposerChatListResponse {
+    items: ComposerChatListItem[];
+    next_cursor: string | null;
 }
 /**
  * Parameters for deleting a Composer chat session.
@@ -1973,11 +2892,236 @@ interface ComposerDeleteParams {
     /** If `true`, also permanently delete the associated workflow. */
     permanent?: boolean;
 }
+/** Response from deleting a Composer chat session. */
+interface ComposerDeleteResponse {
+    status: 'deleted';
+    composer_chat_id: string;
+    permanent: boolean;
+}
+/** Response from cancelling a Composer chat's in-progress run. */
+interface ComposerCancelResponse {
+    status: 'cancelled';
+    composer_chat_id: string;
+    run_id: string;
+}
+/**
+ * A Composer SSE frame. This is a data-only stream; discriminate on `type`.
+ * The `user_input_request` frame carries the open HITL question — answer it
+ * with `composer.resume()`.
+ */
+type ComposerSSEEvent = ({
+    type: 'metadata';
+} & Record<string, unknown>) | ({
+    type: 'tool_call';
+} & Record<string, unknown>) | ({
+    type: 'tool_result';
+} & Record<string, unknown>) | ({
+    type: 'workflow_change';
+} & Record<string, unknown>) | ({
+    type: 'response_chunk';
+} & Record<string, unknown>) | ({
+    type: 'subagent_start';
+} & Record<string, unknown>) | {
+    type: 'user_input_request';
+    data: UserInputRequest;
+} | ({
+    type: 'workflow_sync';
+} & Record<string, unknown>) | ({
+    type: 'cancelled';
+} & Record<string, unknown>) | ({
+    type: 'done';
+} & Record<string, unknown>) | ({
+    type: 'error';
+} & Record<string, unknown>);
+
+/**
+ * Types for the Assistant — a chat agent with HITL, NOT bound to any workflow.
+ *
+ * Mirrors `/assistant` (app/api/assistant.py). Structurally similar to Composer
+ * but with NO workflow fields (`workflow_id`/`snapshot_status`/`has_pending_changes`).
+ * @module types/assistant
+ */
+
+/**
+ * Parameters for starting a new Assistant chat or sending a message.
+ */
+interface AssistantChatParams {
+    /** The user's message (required; v1 is text-only). */
+    message: string;
+    /** ID of an existing Assistant chat to continue. Omit to start a new session. */
+    chatId?: string;
+    /** Override the LLM. Defaults to the organization's configured composer LLM. */
+    llm?: LLMConfig;
+}
+/**
+ * Response from starting or continuing an Assistant chat.
+ *
+ * Errors: 409 if the chat has a pending HITL question or a run is already in
+ * progress; 402/403/429 at the billing gate.
+ */
+interface AssistantChatResponse {
+    status: string;
+    chat_id: string;
+    run_id: string;
+    thread_id: string;
+    /** `/assistant/chat/{chat_id}/listen/{run_id}` */
+    stream_url: string;
+}
+/**
+ * A single message within an Assistant chat.
+ */
+interface AssistantMessageResponse {
+    id: string;
+    role: 'human' | 'ai' | 'system';
+    content: string;
+    /** The agent's reasoning trace, when present. */
+    thinking?: string | null;
+    run_id?: string | null;
+    running_status?: string | null;
+    created_at: string;
+}
+/**
+ * Full Assistant chat detail including messages and any open HITL question.
+ */
+interface AssistantChatDetailResponse {
+    id: string;
+    title: string | null;
+    running_id: string | null;
+    /** The open HITL question awaiting an answer, or null. */
+    pending_user_input_request: UserInputRequest | null;
+    messages: AssistantMessageResponse[];
+    created_at: string;
+    updated_at: string;
+}
+/**
+ * Real-time status of an Assistant chat.
+ */
+interface AssistantStatusResponse {
+    chat_id: string;
+    is_running: boolean;
+    /** True when paused on a HITL question (do NOT re-attach SSE). */
+    awaiting_input: boolean;
+    pending_request_id: string | null;
+    running_id: string | null;
+    /** The Redis status payload for the latest run, or null. */
+    run_status: Record<string, unknown> | null;
+}
+/**
+ * Body for `POST /assistant/chat/{id}/resume` — answers an open HITL question.
+ */
+interface AssistantResumeParams {
+    /** The `request_id` of the open question (from the `user_input_request` event). */
+    requestId: string;
+    /** The structured answer (discriminated on `kind`). */
+    response: UserInputResponse;
+    /** LLM config to rebuild the chat model. Required by this endpoint (400 if omitted). */
+    llm: LLMConfig;
+}
+/** Response from resuming a paused Assistant run. */
+interface AssistantResumeResponse {
+    status: 'resuming';
+    chat_id: string;
+    /** A NEW run_id for the resumed execution. */
+    run_id: string;
+    thread_id: string;
+    stream_url: string;
+}
+/** Query parameters for listing the user's Assistant chats. */
+interface AssistantListParams {
+    /** Page size, 1–100 (default 20). */
+    limit?: number;
+    /** ISO `updated_at` timestamp cursor for the next page. */
+    cursor?: string;
+}
+/** A row in the user's Assistant chat list. */
+interface AssistantChatSummary {
+    id: string;
+    title: string;
+    created_at: string;
+    updated_at: string;
+    is_running: boolean;
+}
+/** Cursor-paginated list of the user's Assistant chats. */
+interface AssistantChatListResponse {
+    items: AssistantChatSummary[];
+    next_cursor: string | null;
+}
+/** Parameters for deleting an Assistant chat. */
+interface AssistantDeleteParams {
+    /** `false` (default) soft-deletes; `true` hard-deletes the chat. */
+    permanent?: boolean;
+}
+/** Response from deleting an Assistant chat. */
+interface AssistantDeleteResponse {
+    status: 'deleted';
+    chat_id: string;
+    permanent: boolean;
+}
+/** Response from cancelling an Assistant run. `run_id` is the cancelled run. */
+interface AssistantCancelResponse {
+    status: 'cancelled';
+    chat_id: string;
+    run_id: string;
+}
+/**
+ * An Assistant SSE frame. Data-only stream; discriminate on `type`. The
+ * `user_input_request` frame carries the open HITL question — answer it with
+ * `assistant.resume()`. (No `workflow_change`/`workflow_sync` — Assistant has
+ * no workflow.)
+ */
+type AssistantSSEEvent = ({
+    type: 'metadata';
+} & Record<string, unknown>) | ({
+    type: 'response_chunk';
+} & Record<string, unknown>) | ({
+    type: 'tool_call';
+} & Record<string, unknown>) | ({
+    type: 'tool_result';
+} & Record<string, unknown>) | {
+    type: 'user_input_request';
+    data: UserInputRequest;
+} | ({
+    type: 'run_resumed';
+} & Record<string, unknown>) | ({
+    type: 'guidance';
+} & Record<string, unknown>) | ({
+    type: 'done';
+} & Record<string, unknown>) | ({
+    type: 'error';
+} & Record<string, unknown>) | ({
+    type: 'cancelled';
+} & Record<string, unknown>) | ({
+    type: 'heartbeat';
+} & Record<string, unknown>);
 
 /**
  * Types for the organization dashboard — activity logs, analytics, and user management.
  * @module types/dashboard
  */
+/**
+ * Error envelope returned by dashboard endpoints. All five dashboard routes
+ * return HTTP 200 even on failure, with `success: false` and this `error`
+ * object (instead of the success-shaped `data`/`users`/`filters` keys).
+ */
+interface DashboardErrorEnvelope {
+    success: false;
+    /** Machine-readable error code (e.g. `"AUDIT_LOGS_ERROR"`, `"ANALYTICS_ERROR"`, `"USER_ERROR"`). */
+    error: {
+        code: string;
+        message: string;
+        /** Stringified underlying exception detail. */
+        details: string;
+    };
+}
+/**
+ * Per-organization monthly credit usage, embedded in several analytics payloads.
+ */
+interface CurrentMonthCreditUsage {
+    used_credit: number;
+    max_credit: number;
+    /** ISO-8601 timestamp of the next credit reset, or `null`. */
+    next_reset_date: string | null;
+}
 /**
  * Query parameters for fetching organization activity logs.
  */
@@ -1994,20 +3138,22 @@ interface DashboardLogsParams {
     endDate?: string;
 }
 /**
- * A single activity log entry.
+ * A single activity (audit) log entry, as emitted by `GET /dashboard/logs`.
  */
 interface ActivityLogEntry {
     id: string;
+    /** ISO-8601 timestamp of the audited event; `null` when unset. */
+    audit_time?: string | null;
     category: string;
     operation: string;
-    user_id: string;
-    resource_id?: string | null;
-    resource_type?: string | null;
+    /** Email of the acting user; `null` when the actor row is missing (outer join). */
+    actor_email?: string | null;
+    /** Human-readable description of the audited event. */
+    message: string;
     metadata?: Record<string, unknown>;
-    created_at: string;
 }
 /**
- * Pagination metadata embedded in log responses.
+ * Pagination payload embedded in the logs response (offset-based).
  */
 interface LogsPaginationData {
     logs: ActivityLogEntry[];
@@ -2018,33 +3164,90 @@ interface LogsPaginationData {
     has_previous: boolean;
 }
 /**
- * Response from the dashboard logs endpoint.
+ * Concrete shape of the `filters` echo returned by the logs endpoint.
  */
-interface DashboardLogsResponse {
-    success: boolean;
+interface DashboardLogsFilters {
+    category: string | null;
+    operation: string | null;
+    /** ISO-8601 start date echoed back, or `null`. */
+    start_date: string | null;
+    /** ISO-8601 end date echoed back, or `null`. */
+    end_date: string | null;
+}
+/**
+ * Success response from the dashboard logs endpoint.
+ */
+interface DashboardLogsSuccess {
+    success: true;
     organization_id: string;
     data: LogsPaginationData;
-    filters: Record<string, unknown>;
+    filters: DashboardLogsFilters;
     meta: Record<string, unknown>;
 }
+/**
+ * Response from the dashboard logs endpoint — success or error envelope.
+ */
+type DashboardLogsResponse = DashboardLogsSuccess | DashboardErrorEnvelope;
 /**
  * Query parameters for the analytics overview endpoint.
  */
-interface AnalyticsOverviewParams {
-    limit?: number;
-    offset?: number;
+interface AnalyticsOverviewParams {
+    limit?: number;
+    offset?: number;
+}
+/**
+ * Billing subscription window for the organization.
+ */
+interface AnalyticsSubscription {
+    /** ISO-8601 start of the current billing period (always present). */
+    current_period_start: string;
+    /** ISO-8601 end of the current billing period (always present). */
+    current_period_end: string;
+}
+/**
+ * A single credential-usage log row in the overview payload.
+ *
+ * Unlike the tools/LLM usage rows, overview rows include `auth_type`.
+ */
+interface OverviewCredentialUsageLog {
+    integration_name: string;
+    service_name: string;
+    /** Raw auth type of the credential (e.g. `"modulex_key"`, `"oauth2"`). */
+    auth_type: string;
+    credential_display_name: string | null;
+    success: boolean;
+    /** ISO-8601 execution timestamp; `null` when unset. */
+    executed_at: string | null;
+    /** Email of the executing user; `null` when the user row is missing (outer join). */
+    user_email: string | null;
+}
+/**
+ * Structured analytics overview payload.
+ */
+interface AnalyticsOverview {
+    active_member_count: number;
+    configured_integrations_count: number;
+    total_integrations_count: number;
+    total_credentials_count: number;
+    current_month_credit_usage: CurrentMonthCreditUsage;
+    subscription: AnalyticsSubscription;
+    credential_usage_logs: OverviewCredentialUsageLog[];
 }
 /**
- * Response from the analytics overview endpoint.
+ * Success response from the analytics overview endpoint.
  */
-interface AnalyticsOverviewResponse {
-    success: boolean;
+interface AnalyticsOverviewSuccess {
+    success: true;
     organization_id: string;
     data: {
-        overview: Record<string, unknown>;
+        overview: AnalyticsOverview;
     };
     meta: Record<string, unknown>;
 }
+/**
+ * Response from the analytics overview endpoint — success or error envelope.
+ */
+type AnalyticsOverviewResponse = AnalyticsOverviewSuccess | DashboardErrorEnvelope;
 /**
  * Query parameters for the tools analytics endpoint.
  */
@@ -2055,30 +3258,120 @@ interface AnalyticsToolsParams {
     offset?: number;
 }
 /**
- * Response from the tools analytics endpoint.
+ * Most-used action within the requested period.
  */
-interface AnalyticsToolsResponse {
-    success: boolean;
+interface MostUsedAction {
+    action_name: string;
+    integration_name: string;
+}
+/**
+ * A single tool-usage log row.
+ */
+interface ToolUsage {
+    /** Email of the executing user; `null` when the user row is missing (outer join). */
+    user_email: string | null;
+    integration_name: string;
+    action_name: string;
+    /** ISO-8601 execution timestamp; `null` when unset. */
+    executed_at: string | null;
+    execution_duration_ms: number | null;
+    /** Derived status from the underlying `success` boolean. */
+    status: 'success' | 'error';
+    /** Display name (`"Modulex Key"` for managed-key credentials), or `null`. */
+    credential_display_name: string | null;
+}
+/**
+ * Structured tools analytics payload.
+ */
+interface AnalyticsToolsData {
+    total_tool_executions: number;
+    current_month_total_tool_executions: number;
+    current_month_credit_usage: CurrentMonthCreditUsage;
+    success_rate: number;
+    /** Most used action in the period, or `null` when there is none. */
+    most_used_action: MostUsedAction | null;
+    configured_integrations_count: number;
+    total_integrations_count: number;
+    tool_usages: ToolUsage[];
+}
+/**
+ * Success response from the tools analytics endpoint.
+ */
+interface AnalyticsToolsSuccess {
+    success: true;
     organization_id: string;
-    data: Record<string, unknown>;
+    data: AnalyticsToolsData;
     meta: Record<string, unknown>;
 }
 /**
- * Response from the LLM usage analytics endpoint.
+ * Response from the tools analytics endpoint — success or error envelope.
  */
-interface AnalyticsLLMUsageResponse {
-    success: boolean;
+type AnalyticsToolsResponse = AnalyticsToolsSuccess | DashboardErrorEnvelope;
+/**
+ * Query parameters for the LLM usage analytics endpoint.
+ *
+ * Mirrors {@link AnalyticsToolsParams}; declared separately for clarity.
+ */
+interface AnalyticsLLMUsageParams {
+    /** Aggregation period (e.g. `"24h"`, `"7d"`, `"30d"`, `"90d"`). */
+    period?: string;
+    limit?: number;
+    offset?: number;
+}
+/**
+ * A single LLM-usage log row.
+ *
+ * Note the renamed keys relative to tool usage: `provider` (integration),
+ * `model` (service), `request_time` (executed_at), `request_duration`
+ * (execution_duration_ms).
+ */
+interface LLMUsage {
+    /** Email of the requesting user; `null` when the user row is missing (outer join). */
+    user_email: string | null;
+    provider: string;
+    model: string;
+    prompt_tokens: number;
+    completion_tokens: number;
+    /** ISO-8601 request timestamp; `null` when unset. */
+    request_time: string | null;
+    request_duration: number | null;
+    /** Derived status from the underlying `success` boolean. */
+    status: 'success' | 'error';
+    /** Display name (`"Modulex Key"` for managed-key credentials), or `null`. */
+    credential_display_name: string | null;
+}
+/**
+ * Structured LLM usage analytics payload.
+ */
+interface AnalyticsLLMUsageData {
+    total_llm_call: number;
+    current_month_total_llm_call: number;
+    current_month_credit_usage: CurrentMonthCreditUsage;
+    request_success_rate: number;
+    total_completion_tokens: number;
+    total_prompt_tokens: number;
+    llm_usages: LLMUsage[];
+}
+/**
+ * Success response from the LLM usage analytics endpoint.
+ */
+interface AnalyticsLLMUsageSuccess {
+    success: true;
     organization_id: string;
-    data: Record<string, unknown>;
+    data: AnalyticsLLMUsageData;
     meta: Record<string, unknown>;
 }
+/**
+ * Response from the LLM usage analytics endpoint — success or error envelope.
+ */
+type AnalyticsLLMUsageResponse = AnalyticsLLMUsageSuccess | DashboardErrorEnvelope;
 /**
  * Query parameters for listing organization members from the dashboard.
  */
 interface DashboardUsersParams {
     search?: string;
-    /** Filter by member status (e.g. `"active"`, `"invited"`, `"suspended"`). */
-    status?: string;
+    /** Filter by member status. Only `"active"` and `"inactive"` are honored by the backend. */
+    status?: 'active' | 'inactive';
     /** Field to sort by (e.g. `"created_at"`, `"email"`). */
     sortBy?: string;
     /** Sort direction — `"asc"` or `"desc"`. */
@@ -2087,12 +3380,61 @@ interface DashboardUsersParams {
     limit?: number;
 }
 /**
- * Response from the dashboard users endpoint.
+ * A dashboard user row representing an active organization member.
  */
-interface DashboardUsersResponse {
-    success: boolean;
+interface DashboardMemberUser {
+    id: string;
+    email: string;
+    username: string | null;
+    avatar: string | null;
+    role: string;
+    is_active: boolean;
+    /** ISO-8601 creation timestamp; `null` when unset. */
+    created_at: string | null;
+    /** ISO-8601 last-update timestamp; `null` when unset. */
+    updated_at: string | null;
+    /** ISO-8601 last-active timestamp; `null` when unset. */
+    last_active_at: string | null;
+    current_month_credit_usage: number;
+}
+/**
+ * A dashboard user row representing a pending invitation (prepended to the list).
+ */
+interface DashboardInvitationUser {
+    id: string;
+    email: string;
+    username: null;
+    avatar: null;
+    role: string;
+    is_active: false;
+    /** ISO-8601 creation timestamp; `null` when unset. */
+    created_at: string | null;
+    updated_at: null;
+    last_active_at: null;
+    current_month_credit_usage: number;
+    /** Discriminant flag marking this row as an invitation. */
+    is_invitation: true;
+    /** Invitation status (e.g. `"pending"`, `"rejected"`, `"expired"`, `"canceled"`). */
+    invitation_status: string;
+    /** ISO-8601 expiry timestamp; `null` when unset. */
+    invitation_expires_at: string | null;
+    /** ID of the invited user if already registered, else `null`. */
+    invited_user_id: string | null;
+    /** ISO-8601 invitation timestamp; `null` when unset. */
+    invited_at: string | null;
+}
+/**
+ * A dashboard user row — either an active member or a pending invitation.
+ * Discriminate on the optional `is_invitation` flag.
+ */
+type DashboardUser = DashboardMemberUser | DashboardInvitationUser;
+/**
+ * Success response from the dashboard users endpoint (page-based pagination).
+ */
+interface DashboardUsersSuccess {
+    success: true;
     organization_id: string;
-    users: Record<string, unknown>[];
+    users: DashboardUser[];
     invitation_count: number;
     max_seats: number;
     total: number;
@@ -2102,131 +3444,185 @@ interface DashboardUsersResponse {
     has_next: boolean;
     has_previous: boolean;
 }
-
 /**
- * Types for subscription plans, billing, and payment portal management.
- * @module types/subscriptions
+ * Response from the dashboard users endpoint — success or error envelope.
  */
+type DashboardUsersResponse = DashboardUsersSuccess | DashboardErrorEnvelope;
+
 /**
- * A single price option for a plan (monthly or yearly).
- */
-interface PlanPrice {
-    price: number;
-    /** Billing interval (e.g. `"month"`, `"year"`). */
-    interval: string;
-    /** ISO-4217 currency code (e.g. `"usd"`). */
-    currency: string;
-}
-/**
- * A subscription plan available to organizations.
+ * Types for organization notifications.
+ * @module types/notifications
  */
-interface Plan {
-    id: string;
-    name: string;
-    /** Display sort order on the pricing page. */
-    sort_order: number;
-    is_enterprise: boolean;
-    /** Discount percentage (0–100). */
-    discount: number;
-    prices: PlanPrice[];
-    /** List of feature descriptions included in this plan. */
-    features: string[];
-    /** Whether the plan can be self-selected (vs. sales-only). */
-    is_selectable?: boolean;
-}
-/**
- * Response from listing available organization plans.
- */
-interface OrganizationPlansResponse {
-    plans: Plan[];
-    total: number;
-}
 /**
- * An active subscription record.
+ * Topic of an organization notification.
+ *
+ * Mirrors the backend `notification_topic` enum for organization
+ * notifications (`integration` | `attention`).
  */
-interface Subscription {
-    id: string;
-    /** Stripe/payment-provider subscription status (e.g. `"active"`, `"past_due"`). */
-    status: string;
-    current_period_start: string;
-    current_period_end: string;
-    /** Current billing interval (`"month"` or `"year"`). */
-    billing_interval: string;
-    current_price: number;
-    created_at: string;
-}
+type OrganizationNotificationTopic = 'integration' | 'attention';
 /**
- * Billing information for an organization.
+ * Topic of a system notification.
+ *
+ * Mirrors the backend `notification_topic` enum for system
+ * notifications (`notice` | `incident` | `changelog`).
  */
-interface BillingResponse {
-    has_subscription: boolean;
-    subscription?: Subscription;
-    plan?: Plan;
-}
+type SystemNotificationTopic = 'notice' | 'incident' | 'changelog';
 /**
- * Parameters for creating a Stripe Checkout session.
+ * Fields shared by every notification variant returned from
+ * `GET /notifications`.
  */
-interface CheckoutParams {
-    planId: string;
-    interval: 'month' | 'year';
+interface NotificationBase {
+    /** Unique identifier of the notification (or invitation) record. */
+    id: string;
+    /** Human-readable notification message. */
+    message: string;
+    /** ISO-8601 creation timestamp. May be null for some system/organization rows. */
+    created_at: string | null;
+    /** ISO-8601 expiration timestamp, or `null` when it never expires. */
+    expires_at?: string | null;
 }
 /**
- * Response from creating a Checkout session.
- */
-interface CheckoutResponse {
-    /** Stripe Checkout URL — redirect the user here to complete payment. */
-    url: string;
+ * An invitation surfaced through the notifications feed.
+ *
+ * Produced by the invitation branch of the backend notification service.
+ * Note: invitation rows do **not** carry `notification_topic`,
+ * `notification_url` or `notified_at`. `organization_id` may be `null`
+ * because it is derived from the invitation's organization payload.
+ */
+interface InvitationNotification extends NotificationBase {
+    notification_type: 'invitation';
+    /** Inviting organization id; may be `null` if unavailable. */
+    organization_id?: string | null;
+    /** Display name of the inviting organization. */
+    organization_name: string;
+    /** Role the user is invited to assume. */
+    role: string;
+    /** Email of the user who issued the invitation, when known. */
+    invited_by_email?: string | null;
+    /** Optional custom message attached to the invitation. */
+    invitation_message?: string | null;
 }
 /**
- * Response from creating a Stripe Customer Portal session.
- */
-interface PortalResponse {
-    /** Stripe Portal URL — redirect the user here to manage billing. */
-    url: string;
+ * A system-wide notification.
+ *
+ * System notifications are not scoped to an organization, so they carry
+ * **no** `organization_id` field.
+ */
+interface SystemNotification extends NotificationBase {
+    notification_type: 'system';
+    /** System notification topic. */
+    notification_topic: SystemNotificationTopic;
+    /** Optional deep-link URL associated with the notification. */
+    notification_url?: string | null;
+    /** ISO-8601 timestamp of when the notification was emitted. */
+    notified_at?: string | null;
 }
-
-/**
- * Types for organization notifications.
- * @module types/notifications
- */
 /**
- * A notification record as returned by the API.
+ * An organization-scoped notification.
  */
-interface NotificationResponse {
-    id: string;
+interface OrganizationNotification extends NotificationBase {
+    notification_type: 'organization';
+    /** Owning organization id (always present for this variant). */
     organization_id: string;
-    user_id: string | null;
-    notification_topic: string;
-    message: string;
+    /** Organization notification topic. */
+    notification_topic: OrganizationNotificationTopic;
+    /** Optional deep-link URL associated with the notification. */
     notification_url?: string | null;
-    is_read: boolean;
-    expires_at?: string | null;
-    created_at: string;
-    updated_at: string;
+    /** ISO-8601 timestamp of when the notification was emitted. */
+    notified_at?: string | null;
+    /**
+     * `true` when the notification was broadcast to all org members
+     * (i.e. `notified_to` was null), `false` when targeted at a user.
+     */
+    is_broadcast: boolean;
 }
 /**
- * Response from listing notifications for an organization.
+ * A notification record as returned by `GET /notifications`.
+ *
+ * This is a discriminated union keyed on `notification_type`. The backend
+ * merges invitations, system notifications and organization notifications
+ * into a single feed, so consumers should switch on `notification_type`
+ * before accessing variant-specific fields.
+ */
+type NotificationResponse = InvitationNotification | SystemNotification | OrganizationNotification;
+/**
+ * Response from listing notifications for the current user / organization.
+ *
+ * `organization_id` reflects the resolved `X-Organization-ID` header and is
+ * `null` when no (valid) organization context was supplied.
  */
 interface NotificationListResponse {
     success: boolean;
     notifications: NotificationResponse[];
     total: number;
-    organization_id: string;
+    organization_id: string | null;
 }
 /**
  * Parameters for creating an organization notification.
+ *
+ * Backend validation constraints (not enforced client-side):
+ * - `message`: 1-5000 characters.
+ * - `notificationUrl`: at most 500 characters.
+ * - `expiresAt`: must be a valid ISO-8601 datetime.
  */
 interface CreateNotificationParams {
     /** The category / channel for the notification. */
-    notificationTopic: 'integration' | 'attention';
+    notificationTopic: OrganizationNotificationTopic;
+    /** Notification message (1-5000 characters). */
     message: string;
     /** User ID to direct the notification to. Omit to send to all org members. */
     notifiedTo?: string;
-    /** Deep-link URL associated with the notification. */
+    /** Deep-link URL associated with the notification (max 500 characters). */
     notificationUrl?: string;
     /** ISO-8601 datetime after which the notification should be hidden. */
     expiresAt?: string;
 }
+/**
+ * The notification object echoed back by
+ * `POST /notifications/organization` after creation.
+ */
+interface CreatedNotification {
+    id: string;
+    organization_id: string;
+    notification_topic: OrganizationNotificationTopic;
+    message: string;
+    notification_url?: string | null;
+    created_at: string;
+    notified_at: string;
+    expires_at?: string | null;
+    /** `true` when broadcast to all members, `false` when targeted. */
+    is_broadcast: boolean;
+    /** Target user id, or `null` for a broadcast notification. */
+    notified_to?: string | null;
+}
+/**
+ * Response envelope from `POST /notifications/organization`.
+ */
+interface CreateNotificationResponse {
+    success: boolean;
+    notification: CreatedNotification;
+}
+
+/**
+ * Types for the System timezone endpoints.
+ * @module types/system
+ */
+/** A single selectable timezone option. */
+interface TimezoneOption {
+    value: string;
+    label: string;
+    offset: string;
+}
+/** A group of timezones under a region heading. */
+interface TimezoneGroup {
+    region: string;
+    timezones: TimezoneOption[];
+}
+/** Response from `GET /system/timezones`. */
+interface TimezoneListResponse {
+    popular: TimezoneGroup[];
+    all_timezones: string[];
+}
 
 /**
  * Auth resource — identity and organization membership endpoints.
@@ -2260,9 +3656,10 @@ declare class Auth extends BaseResource {
     /**
      * POST /auth/invitations/{id}/accept
      *
-     * Accepts a pending organization invitation.
+     * Accepts a pending organization invitation. On success the response
+     * includes the joined organization and the granted role.
      */
-    acceptInvitation(invitationId: string, options?: RequestOptions): Promise<SuccessResponse>;
+    acceptInvitation(invitationId: string, options?: RequestOptions): Promise<InvitationResponse>;
     /**
      * POST /auth/invitations/{id}/reject
      *
@@ -2338,7 +3735,9 @@ declare class Organizations extends BaseResource {
     /**
      * POST /organizations/invite
      *
-     * Sends an invitation email to add a user to the current organization.
+     * Sends an invitation email to add a user to the current organization. The
+     * invited user joins as `admin`; the org `member` role was retired, so the
+     * backend rejects `role: 'member'` with HTTP 422.
      */
     invite(params: InviteParams, options?: RequestOptions): Promise<SuccessResponse>;
     /**
@@ -2356,7 +3755,9 @@ declare class Organizations extends BaseResource {
     /**
      * PUT /organizations/{orgId}/users/{userId}/role
      *
-     * Updates a member's role within an organization.
+     * Updates a member's role within an organization. Only `'admin'` is accepted —
+     * the org `member` role was retired, so the backend rejects `role: 'member'`
+     * with HTTP 422.
      */
     updateRole(organizationId: string, userId: string, params: RoleUpdateParams, options?: RequestOptions): Promise<RoleUpdateResponse>;
     /**
@@ -2365,6 +3766,51 @@ declare class Organizations extends BaseResource {
      * Removes a user from an organization. Requires owner permission.
      */
     removeUser(organizationId: string, userId: string, options?: RequestOptions): Promise<SuccessResponse>;
+    /**
+     * POST /organizations/invite/preview
+     *
+     * Previews the prorated cost of adding one seat to the current organization,
+     * for displaying to the user before confirming an invite. The organization is
+     * resolved from the `X-Organization-ID` header, so no request body is sent.
+     *
+     * Returns a discriminated union on `preview_available`: when `false`, the
+     * organization has no active paid subscription (a `reason` is provided); when
+     * `true`, full prorated pricing detail is returned.
+     *
+     * @remarks Admin-only: requires organization admin (or owner) permission.
+     */
+    invitePreview(options?: RequestOptions): Promise<InvitePreviewResponse>;
+    /**
+     * GET /organizations/settings
+     *
+     * Returns the per-organization preference settings (model visibility and the
+     * default composer LLM) for the current organization. The organization is
+     * resolved from the `X-Organization-ID` header.
+     *
+     * @remarks Available to any organization member.
+     */
+    getSettings(options?: RequestOptions): Promise<SettingsResponse>;
+    /**
+     * PUT /organizations/settings/llm-model-visibility
+     *
+     * Sets which models are visible in the dropdown for a single integration.
+     * Send the FULL desired visible list; an empty `models` array resets that
+     * integration's visibility to the catalog default. The organization is
+     * resolved from the `X-Organization-ID` header.
+     *
+     * @remarks Admin-only: requires organization admin (or owner) permission.
+     */
+    setModelVisibility(params: SetModelVisibilityParams, options?: RequestOptions): Promise<SetModelVisibilityResponse>;
+    /**
+     * PUT /organizations/settings/composer-llm
+     *
+     * Persists the organization's default composer LLM. Composer requests that
+     * omit an explicit LLM fall back to this value. The organization is resolved
+     * from the `X-Organization-ID` header.
+     *
+     * @remarks Admin-only: requires organization admin (or owner) permission.
+     */
+    setComposerLlm(params: ComposerLLMParams, options?: RequestOptions): Promise<ComposerLLMResponse>;
 }
 
 /**
@@ -2379,7 +3825,13 @@ declare class Workflows extends BaseResource {
     /**
      * POST /workflows
      *
-     * Creates a new workflow with the given schema.
+     * Creates a new workflow with the given schema. Returns HTTP 201.
+     * Requires organization admin/owner role.
+     *
+     * `params.visibility` is passed through unchanged with no client-side default;
+     * omit it to let the backend default to `"organization"`. `"private"` is no
+     * longer creator-only — it behaves like `"organization"` (any org admin/owner
+     * can view/run/resume).
      */
     create(params: CreateWorkflowParams, options?: RequestOptions): Promise<WorkflowResponse>;
     /**
@@ -2405,12 +3857,15 @@ declare class Workflows extends BaseResource {
      * PUT /workflows/{workflowId}
      *
      * Updates an existing workflow. Only provided fields are changed.
+     * Requires organization admin/owner role.
      */
     update(workflowId: string, params: UpdateWorkflowParams, options?: RequestOptions): Promise<WorkflowResponse>;
     /**
      * DELETE /workflows/{workflowId}
      *
-     * Soft-deletes a workflow.
+     * Permanently (hard) deletes a workflow. This is IRREVERSIBLE — the workflow
+     * row and its schema are removed from the database, not soft-deleted.
+     * Requires organization admin/owner role.
      */
     delete(workflowId: string, options?: RequestOptions): Promise<DeleteWorkflowResponse>;
     /**
@@ -2420,23 +3875,41 @@ declare class Workflows extends BaseResource {
      * the visual workflow builder. Results are cached for 60 minutes.
      */
     builderDetails(params?: BuilderDetailsParams, options?: RequestOptions): Promise<BuilderDetailsResponse>;
+    /**
+     * GET /workflows/{workflowId}/changes — SSE stream
+     *
+     * Opens a Server-Sent Events stream of real-time collaboration changes for a
+     * workflow (canvas/composer sync). This is a data-only stream: each yielded
+     * value is a {@link WorkflowChangeEvent} discriminated on its `type` field
+     * (`connected`, `workflow_updated`, `user_joined`, `user_left`).
+     */
+    listenChanges(workflowId: string, options?: RequestOptions): AsyncGenerator<WorkflowChangeEvent>;
 }
 
 /**
- * Executions resource — workflow run, resume, cancel, listen, and state endpoints.
+ * Executions resource — ephemeral workflow execution control under `/workflows`
+ * (run, state, resume, cancel, listen).
+ *
+ * For durable run history (list/get persisted runs) see the {@link WorkflowRuns}
+ * resource (`client.workflowRuns`).
  * @module resources/executions
  */
 
 /**
- * Provides methods for workflow execution endpoints under `/workflows`.
+ * Provides methods for workflow execution-control endpoints under `/workflows`.
  */
 declare class Executions extends BaseResource {
     /**
      * POST /workflows/run
      *
-     * Initiates a workflow run. Supports four modes: existing workflow, ad-hoc
-     * workflow, direct LLM call, and system workflow. Returns immediately with
-     * run metadata; stream events via `listen()`.
+     * Initiates a workflow run. Supports two modes: a saved workflow (`workflowId`,
+     * which requires an active deployment — the backend returns 400 otherwise) or
+     * an inline ad-hoc definition (`workflow`). Returns immediately with run
+     * metadata (`status` is `"running"` for streaming runs); stream events via
+     * `listen()`.
+     *
+     * The legacy direct-LLM mode was removed; an `llm_config`-only request now
+     * returns HTTP 410 — use `client.assistant.chat()` instead.
      */
     run(params: WorkflowRunParams, options?: RequestOptions): Promise<WorkflowRunResponse>;
     /**
@@ -2444,18 +3917,33 @@ declare class Executions extends BaseResource {
      *
      * Returns the persisted state snapshot of a workflow thread at its latest
      * checkpoint.
+     *
+     * Throws `NotFoundError` on HTTP 404 — the thread does not exist OR is not
+     * owned by your organization. Ownership failures return an identical 404 (not
+     * 403) by design, so there is no existence leak.
      */
     getState(threadId: string, options?: RequestOptions): Promise<WorkflowStateResponse>;
     /**
      * POST /workflows/resume/{threadId}
      *
      * Resumes a workflow that is waiting at an interrupt node.
+     *
+     * Guard responses: 400 (missing `resumeValue` or `runId`); 404 — a
+     * `NotFoundError` — when there is no checkpoint for the thread OR the
+     * run/thread is not owned by your organization. Ownership failures return an
+     * identical 404 (not 403) by design, so there is no existence leak.
      */
     resume(params: WorkflowResumeParams, options?: RequestOptions): Promise<WorkflowResumeResponse>;
     /**
      * POST /workflows/cancel/{runId}
      *
-     * Requests cancellation of an in-progress workflow run.
+     * Requests cancellation of an in-progress workflow run. On success the
+     * response `status` is `"cancellation_requested"`.
+     *
+     * Guard responses: 404 — a `NotFoundError` — when the run is unknown OR is not
+     * owned by your organization (ownership failures return an identical 404, not
+     * 403, by design, so there is no existence leak); 400 (the run is not in a
+     * `running`/`interrupted` state).
      */
     cancel(runId: string, params?: {
         reason?: string;
@@ -2463,12 +3951,53 @@ declare class Executions extends BaseResource {
     /**
      * GET /workflows/listen/{runId} — SSE stream
      *
-     * Opens a Server-Sent Events stream for real-time execution events of
-     * an in-progress workflow run. Yields typed `WorkflowSSEEvent` values.
+     * Opens a Server-Sent Events stream for real-time execution events of an
+     * in-progress workflow run. This is a data-only stream: each yielded value is
+     * a {@link WorkflowSSEEvent} discriminated on its `type` field (`metadata`,
+     * `node_started`, `node_update`, `interrupt`, `resumed`, `done`, `cancelled`,
+     * `error`). The stream ends after a `done` or `error` event.
+     *
+     * A 404 on connect throws `NotFoundError` before any event is yielded — the
+     * run does not exist OR is not owned by your organization (ownership failures
+     * return an identical 404, not 403). The stream does NOT auto-reconnect on a
+     * 404.
      */
     listen(runId: string, options?: RequestOptions): AsyncGenerator<WorkflowSSEEvent>;
 }
 
+/**
+ * WorkflowRuns resource — durable run-history read endpoints under `/workflow-runs`.
+ *
+ * These are distinct from the ephemeral execution-control endpoints in the
+ * {@link Executions} resource: this resource reads the persisted `workflow_runs`
+ * table (history, input/output snapshots, attribution).
+ * @module resources/workflow-runs
+ */
+
+/**
+ * Provides read access to durable workflow run history under `/workflow-runs`.
+ */
+declare class WorkflowRuns extends BaseResource {
+    /**
+     * GET /workflow-runs
+     *
+     * Lists workflow runs for the organization, newest first. Pass `workflowId`
+     * for per-workflow history. Pagination is via `has_more` (no total count).
+     */
+    list(params?: WorkflowRunListParams, options?: RequestOptions): Promise<WorkflowRunListResponse>;
+    /**
+     * GET /workflow-runs/{runPk}
+     *
+     * Returns the full durable run record (including input/output snapshots).
+     *
+     * NOTE: `runPk` is the run table primary key (the `id` field of a
+     * {@link WorkflowRunListItem} / {@link WorkflowRunDetail}), NOT the string
+     * `run_id` used by `executions.listen()` / `executions.cancel()`. Passing a
+     * `run_id` here returns 404.
+     */
+    get(runPk: string, options?: RequestOptions): Promise<WorkflowRunDetail>;
+}
+
 /**
  * Deployments resource — workflow deployment management endpoints.
  * @module resources/deployments
@@ -2585,15 +4114,18 @@ declare class Credentials extends BaseResource {
     /**
      * GET /credentials/{credentialId}
      *
-     * Returns a single credential record.
+     * Returns a single credential record, including ownership and (optionally
+     * masked) auth detail fields not present on the list endpoint.
      */
     get(credentialId: string, params?: {
         includeMasked?: boolean;
-    }, options?: RequestOptions): Promise<CredentialResponse>;
+    }, options?: RequestOptions): Promise<CredentialDetailResponse>;
     /**
      * POST /credentials
      *
      * Creates a new credential. The auth data is encrypted at rest.
+     *
+     * @remarks Requires admin/owner role on the organization.
      */
     create(params: CreateCredentialParams, options?: RequestOptions): Promise<CredentialResponse>;
     /**
@@ -2631,18 +4163,25 @@ declare class Credentials extends BaseResource {
      * GET /credentials/{credentialId}/usage
      *
      * Returns usage statistics for a credential.
+     *
+     * @remarks Requires admin/owner role on the organization.
      */
     usage(credentialId: string, params?: CredentialUsageParams, options?: RequestOptions): Promise<CredentialUsageResponse>;
     /**
      * GET /credentials/{credentialId}/audit
      *
-     * Returns the audit log for a credential.
+     * Returns the audit log for a credential as an array of entries.
+     *
+     * @remarks Requires admin/owner role on the organization.
      */
-    audit(credentialId: string, params?: CredentialAuditParams, options?: RequestOptions): Promise<Record<string, unknown>>;
+    audit(credentialId: string, params?: CredentialAuditParams, options?: RequestOptions): Promise<AuditLogResponse[]>;
     /**
      * POST /credentials/bulk-modulex-keys/stream — SSE
      *
-     * Streams bulk ModuleX managed key provisioning events.
+     * Streams bulk ModuleX managed key provisioning events. Each event's
+     * `data` field can be parsed as a {@link ModulexKeyBulkEventData}.
+     *
+     * @remarks Requires admin/owner role on the organization.
      */
     bulkModulexKeys(options?: RequestOptions): AsyncGenerator<SSEEvent>;
     /**
@@ -2650,7 +4189,7 @@ declare class Credentials extends BaseResource {
      *
      * Creates a credential for a Model Context Protocol (MCP) server.
      */
-    mcpServer(params: McpServerParams, options?: RequestOptions): Promise<CredentialResponse>;
+    mcpServer(params: McpServerParams, options?: RequestOptions): Promise<MCPServerCredentialResponse>;
     /**
      * POST /credentials/{credentialId}/refresh-discovery
      *
@@ -2663,6 +4202,25 @@ declare class Credentials extends BaseResource {
      * Returns the tools discovered from an MCP server credential.
      */
     mcpTools(credentialId: string, options?: RequestOptions): Promise<McpToolsResponse>;
+    /**
+     * POST /credentials/oauth2/initiate
+     *
+     * Initiates an OAuth2 authorization flow for an integration and returns the
+     * authorization URL the user should be redirected to, along with a `state`
+     * token correlating the flow.
+     *
+     * @remarks Requires admin/owner role on the organization.
+     */
+    initiateOAuth2(params: InitiateOAuth2Params, options?: RequestOptions): Promise<OAuth2InitiateResponse>;
+    /**
+     * POST /credentials/{credentialId}/oauth2/refresh
+     *
+     * Manually refreshes the access token of an existing OAuth2 credential and
+     * returns the updated credential record.
+     *
+     * @remarks Requires admin/owner role on the organization.
+     */
+    refreshOAuth2(credentialId: string, options?: RequestOptions): Promise<CredentialResponse>;
 }
 
 /**
@@ -2687,7 +4245,7 @@ declare class Integrations extends BaseResource {
      */
     tools(params?: {
         category?: string;
-    }, options?: RequestOptions): Promise<Record<string, unknown>>;
+    }, options?: RequestOptions): Promise<IntegrationMetadata[]>;
     /**
      * GET /integrations/tools/{integrationName}
      *
@@ -2701,7 +4259,7 @@ declare class Integrations extends BaseResource {
      */
     llmProviders(params?: {
         category?: string;
-    }, options?: RequestOptions): Promise<Record<string, unknown>>;
+    }, options?: RequestOptions): Promise<IntegrationMetadata[]>;
     /**
      * GET /integrations/llm-providers/{providerName}
      *
@@ -2715,7 +4273,7 @@ declare class Integrations extends BaseResource {
      */
     knowledgeProviders(params?: {
         category?: string;
-    }, options?: RequestOptions): Promise<Record<string, unknown>>;
+    }, options?: RequestOptions): Promise<IntegrationMetadata[]>;
     /**
      * GET /integrations/knowledge-providers/{providerName}
      *
@@ -2743,12 +4301,17 @@ declare class Knowledge extends BaseResource {
      * GET /knowledge-bases
      *
      * Lists knowledge bases for the current organization.
+     *
+     * The backend returns a bare JSON array (no pagination envelope); the
+     * `limit`/`offset`/`status` query params control which records are returned.
      */
-    list(params?: KnowledgeBaseListParams, options?: RequestOptions): Promise<KnowledgeBaseListResponse>;
+    list(params?: KnowledgeBaseListParams, options?: RequestOptions): Promise<KnowledgeBaseResponse[]>;
     /**
      * POST /knowledge-bases
      *
      * Creates a new knowledge base.
+     *
+     * Requires an organization admin or owner role; non-admin keys receive 403.
      */
     create(params: CreateKnowledgeBaseParams, options?: RequestOptions): Promise<KnowledgeBaseResponse>;
     /**
@@ -2767,6 +4330,8 @@ declare class Knowledge extends BaseResource {
      * PUT /knowledge-bases/{kbId}
      *
      * Updates a knowledge base's name, description, or configuration.
+     *
+     * Requires an organization admin or owner role; non-admin keys receive 403.
      */
     update(knowledgeBaseId: string, params: UpdateKnowledgeBaseParams, options?: RequestOptions): Promise<KnowledgeBaseResponse>;
     /**
@@ -2774,6 +4339,8 @@ declare class Knowledge extends BaseResource {
      *
      * Deletes a knowledge base. Pass `deleteFiles: true` to also remove
      * the underlying stored files.
+     *
+     * Requires an organization admin or owner role; non-admin keys receive 403.
      */
     delete(knowledgeBaseId: string, params?: {
         deleteFiles?: boolean;
@@ -2782,19 +4349,27 @@ declare class Knowledge extends BaseResource {
      * POST /knowledge-bases/{kbId}/archive
      *
      * Archives a knowledge base, pausing ingestion without deleting data.
+     * Returns the updated knowledge base record.
+     *
+     * Requires an organization admin or owner role; non-admin keys receive 403.
      */
-    archive(knowledgeBaseId: string, options?: RequestOptions): Promise<SuccessResponse>;
+    archive(knowledgeBaseId: string, options?: RequestOptions): Promise<KnowledgeBaseResponse>;
     /**
      * GET /knowledge-bases/{kbId}/documents
      *
      * Returns documents within a knowledge base.
+     *
+     * The backend returns a bare JSON array; the `limit`/`offset`/`status`
+     * query params control which records are returned.
      */
-    documents(knowledgeBaseId: string, params?: DocumentListParams, options?: RequestOptions): Promise<Record<string, unknown>>;
+    documents(knowledgeBaseId: string, params?: DocumentListParams, options?: RequestOptions): Promise<DocumentResponse[]>;
     /**
      * POST /knowledge-bases/{kbId}/documents — multipart upload
      *
      * Uploads a document file to a knowledge base for ingestion.
      * Builds a `FormData` with the file and optional metadata JSON.
+     *
+     * Requires an organization admin or owner role; non-admin keys receive 403.
      */
     uploadDocument(knowledgeBaseId: string, params: UploadDocumentParams, options?: RequestOptions): Promise<DocumentResponse>;
     /**
@@ -2806,7 +4381,8 @@ declare class Knowledge extends BaseResource {
     /**
      * GET /knowledge-bases/{kbId}/documents/{docId}/status
      *
-     * Returns the processing status and progress of a document.
+     * Returns the processing status of a document. Some fields are conditional
+     * on the document's `status` value.
      */
     documentStatus(knowledgeBaseId: string, documentId: string, options?: RequestOptions): Promise<DocumentStatusResponse>;
     /**
@@ -2814,6 +4390,8 @@ declare class Knowledge extends BaseResource {
      *
      * Deletes a document and its chunks from the knowledge base.
      * Pass `deleteFile: true` to also remove the source file from storage.
+     *
+     * Requires an organization admin or owner role; non-admin keys receive 403.
      */
     deleteDocument(knowledgeBaseId: string, documentId: string, params?: {
         deleteFile?: boolean;
@@ -2821,9 +4399,11 @@ declare class Knowledge extends BaseResource {
     /**
      * POST /knowledge-bases/{kbId}/documents/{docId}/retry
      *
-     * Retries ingestion of a failed document.
+     * Retries ingestion of a failed document. Returns the updated document record.
+     *
+     * Requires an organization admin or owner role; non-admin keys receive 403.
      */
-    retryDocument(knowledgeBaseId: string, documentId: string, options?: RequestOptions): Promise<Record<string, unknown>>;
+    retryDocument(knowledgeBaseId: string, documentId: string, options?: RequestOptions): Promise<DocumentResponse>;
     /**
      * GET /knowledge-bases/{kbId}/documents/{docId}/chunks
      *
@@ -2901,25 +4481,26 @@ declare class Schedules extends BaseResource {
      *
      * Deletes a schedule and cancels all pending executions.
      */
-    delete(scheduleId: string, options?: RequestOptions): Promise<SuccessResponse>;
+    delete(scheduleId: string, options?: RequestOptions): Promise<DeleteScheduleResponse>;
     /**
      * POST /schedules/{scheduleId}/pause
      *
      * Pauses a schedule, preventing future runs until resumed.
+     * Returns the updated schedule.
      */
-    pause(scheduleId: string, options?: RequestOptions): Promise<SuccessResponse>;
+    pause(scheduleId: string, options?: RequestOptions): Promise<ScheduleResponse>;
     /**
      * POST /schedules/{scheduleId}/resume
      *
-     * Resumes a paused schedule.
+     * Resumes a paused schedule. Returns the updated schedule.
      */
-    resume(scheduleId: string, options?: RequestOptions): Promise<SuccessResponse>;
+    resume(scheduleId: string, options?: RequestOptions): Promise<ScheduleResponse>;
     /**
      * GET /schedules/{scheduleId}/runs
      *
      * Returns the run history for a schedule.
      */
-    runs(scheduleId: string, params?: ScheduleRunListParams, options?: RequestOptions): Promise<Record<string, unknown>>;
+    runs(scheduleId: string, params?: ScheduleRunListParams, options?: RequestOptions): Promise<ScheduleRunListResponse>;
     /**
      * GET /schedules/{scheduleId}/runs/stats
      *
@@ -2937,139 +4518,204 @@ declare class Schedules extends BaseResource {
      *
      * Retries a failed scheduled run.
      */
-    retryRun(scheduleId: string, runId: string, options?: RequestOptions): Promise<Record<string, unknown>>;
+    retryRun(scheduleId: string, runId: string, options?: RequestOptions): Promise<RetryRunResponse>;
 }
 
 /**
- * Templates resource — workflow template and creator profile endpoints.
- * @module resources/templates
+ * Composer resource — AI-driven workflow builder chat endpoints.
+ * @module resources/composer
  */
 
 /**
- * Provides methods for the `/templates` API endpoints.
+ * Provides methods for the `/composer` API endpoints.
  */
-declare class Templates extends BaseResource {
+declare class Composer extends BaseResource {
+    /**
+     * POST /composer/chat
+     *
+     * Starts a new Composer chat or sends a message to an existing session.
+     * Returns a run ID that can be used to listen to the SSE stream.
+     *
+     * Errors: 409 if the chat has a pending HITL question (answer it via
+     * `resume()` first); 402/403/429 for billing/limit gates.
+     */
+    chat(params: ComposerChatParams, options?: RequestOptions): Promise<ComposerChatResponse>;
+    /**
+     * GET /composer/chats
+     *
+     * Lists the current user's Composer chats, newest first, with cursor
+     * pagination (`next_cursor` is an ISO `updated_at` timestamp).
+     */
+    list(params?: ComposerListParams, options?: RequestOptions): Promise<ComposerChatListResponse>;
     /**
-     * GET /templates
+     * GET /composer/chat/{composerChatId}
      *
-     * Returns the public template library.
+     * Returns a Composer chat session with its messages, touched workflows, and
+     * any open HITL question (`pending_user_input_request`).
      */
-    list(options?: RequestOptions): Promise<TemplateListResponse>;
+    get(composerChatId: string, options?: RequestOptions): Promise<ComposerChatDetailResponse>;
     /**
-     * GET /templates/{templateId}
+     * GET /composer/chat/{composerChatId}/listen/{runId} — SSE
+     *
+     * Opens a Server-Sent Events stream for real-time Composer output. This is a
+     * data-only stream: each yielded value is a {@link ComposerSSEEvent}
+     * discriminated on `type`. A `user_input_request` frame signals a HITL pause —
+     * answer it with `resume()`.
      *
-     * Returns a single template including its full workflow schema.
+     * A 404 on connect throws `NotFoundError` before any event is yielded — the
+     * chat/run does not exist OR is not owned by your organization (ownership
+     * failures return an identical 404, not 403). The stream does NOT
+     * auto-reconnect on a 404.
      */
-    get(templateId: string, options?: RequestOptions): Promise<TemplateResponse>;
+    listen(composerChatId: string, runId: string, options?: RequestOptions): AsyncGenerator<ComposerSSEEvent>;
     /**
-     * GET /templates/me
+     * POST /composer/chat/{composerChatId}/resume
      *
-     * Returns templates created by the authenticated user.
+     * Answers an open HITL question and resumes the paused run. Returns a NEW
+     * `run_id` to listen on.
+     *
+     * Errors: 404 (a `NotFoundError`) when the chat does not exist OR is not owned
+     * by your organization (ownership failures return an identical 404, not 403);
+     * 410 if the `requestId` is not pending or already consumed; 403 if the caller
+     * is not the user who triggered the question. The `llm` config is required in
+     * production (the backend returns 400 if omitted).
      */
-    mine(options?: RequestOptions): Promise<MyTemplatesResponse>;
+    resume(composerChatId: string, params: ComposerResumeParams, options?: RequestOptions): Promise<ComposerResumeResponse>;
     /**
-     * POST /templates
+     * PATCH /composer/chat/{composerChatId}/focus
      *
-     * Publishes a workflow as a new template.
+     * Sets (or clears, with `workflowId: null`) the chat's focused workflow.
      */
-    create(params: CreateTemplateParams, options?: RequestOptions): Promise<TemplateResponse>;
+    focus(composerChatId: string, params: ComposerFocusParams, options?: RequestOptions): Promise<ComposerFocusResponse>;
     /**
-     * POST /templates/{templateId}/like
+     * POST /composer/chat/{composerChatId}/save
      *
-     * Toggles the authenticated user's like on a template.
+     * Saves the Composer's pending workflow changes. Without `workflowId` it
+     * targets the chat's focused workflow (400 if there is none). Returns a
+     * `workflow_sync` payload for refreshing the canvas.
      */
-    like(templateId: string, options?: RequestOptions): Promise<TemplateLikeResponse>;
+    save(composerChatId: string, params?: ComposerSaveParams, options?: RequestOptions): Promise<ComposerSaveResponse>;
     /**
-     * POST /templates/{templateId}/use
+     * POST /composer/chat/{composerChatId}/revert
      *
-     * Imports a template as a new workflow in the current organization.
+     * Reverts pending changes to the last snapshot. Without `workflowId` it
+     * targets the focused workflow (400 if there is none, or if no snapshot
+     * exists). Returns a `workflow_sync` payload.
      */
-    use(templateId: string, options?: RequestOptions): Promise<TemplateUseResponse>;
+    revert(composerChatId: string, params?: ComposerSaveParams, options?: RequestOptions): Promise<ComposerRevertResponse>;
     /**
-     * POST /templates/{templateId}/update-request
+     * DELETE /composer/chat/{composerChatId}
      *
-     * Submits an update request for a published template.
+     * Deletes a Composer chat session. Pass `permanent: true` for a hard delete
+     * (default is a soft delete). `permanent` is sent as a query parameter.
      */
-    updateRequest(templateId: string, params: UpdateTemplateRequestParams, options?: RequestOptions): Promise<SuccessResponse>;
+    delete(composerChatId: string, params?: ComposerDeleteParams, options?: RequestOptions): Promise<ComposerDeleteResponse>;
     /**
-     * POST /templates/creators
+     * GET /composer/chat/{composerChatId}/status
      *
-     * Creates or updates the authenticated user's template creator profile.
+     * Returns the real-time status of a Composer chat session, including HITL
+     * pause state (`awaiting_input` / `pending_request_id`).
      */
-    createCreator(params: CreateCreatorParams, options?: RequestOptions): Promise<Record<string, unknown>>;
+    status(composerChatId: string, options?: RequestOptions): Promise<ComposerStatusResponse>;
     /**
-     * GET /templates/creators/me
+     * POST /composer/chat/{composerChatId}/cancel
+     *
+     * Cancels the in-progress run for a Composer chat session.
      *
-     * Returns the authenticated user's template creator profile.
+     * Throws `NotFoundError` on HTTP 404 — the chat does not exist OR is not owned
+     * by your organization (ownership failures return an identical 404, not 403,
+     * so there is no existence leak).
      */
-    getCreator(options?: RequestOptions): Promise<Record<string, unknown>>;
+    cancel(composerChatId: string, options?: RequestOptions): Promise<ComposerCancelResponse>;
 }
 
 /**
- * Composer resource — AI-driven workflow builder chat endpoints.
- * @module resources/composer
+ * Assistant resource — a chat agent with HITL support under `/assistant`.
+ *
+ * Structurally similar to {@link Composer} but NOT bound to any workflow
+ * (no save/revert/focus). Shares the HITL union types in `types/hitl`.
+ * @module resources/assistant
  */
 
 /**
- * Provides methods for the `/composer` API endpoints.
+ * Provides methods for the `/assistant` API endpoints.
  */
-declare class Composer extends BaseResource {
+declare class Assistant extends BaseResource {
     /**
-     * POST /composer/chat
+     * POST /assistant/chat
      *
-     * Starts a new Composer chat or sends a message to an existing session.
-     * Returns a run ID that can be used to listen to the SSE stream.
-     */
-    chat(params: ComposerChatParams, options?: RequestOptions): Promise<ComposerChatResponse>;
-    /**
-     * GET /composer/chat/{composerChatId}
+     * Starts a new Assistant chat or sends a message to an existing one. Returns
+     * a run ID to listen on.
      *
-     * Returns a Composer chat session with its messages and workflow snapshot status.
+     * Errors: 409 if the chat has a pending HITL question or a run is already in
+     * progress (answer via `resume()` / `cancel()` first); 402/403/429 at the
+     * billing gate.
      */
-    get(composerChatId: string, options?: RequestOptions): Promise<ComposerChatDetailResponse>;
+    chat(params: AssistantChatParams, options?: RequestOptions): Promise<AssistantChatResponse>;
     /**
-     * GET /composer/chat/{composerChatId}/listen/{runId} — SSE
+     * GET /assistant/chats
      *
-     * Opens a Server-Sent Events stream for real-time Composer output during a run.
+     * Lists the current user's Assistant chats, newest first, with cursor
+     * pagination (`next_cursor` is an ISO `updated_at` timestamp).
      */
-    listen(composerChatId: string, runId: string, options?: RequestOptions): AsyncGenerator<SSEEvent>;
+    list(params?: AssistantListParams, options?: RequestOptions): Promise<AssistantChatListResponse>;
     /**
-     * POST /composer/chat/{composerChatId}/save
+     * GET /assistant/chat/{chatId}
      *
-     * Saves the Composer's current workflow changes to the associated workflow.
+     * Returns an Assistant chat with its messages and any open HITL question
+     * (`pending_user_input_request`).
      */
-    save(composerChatId: string, options?: RequestOptions): Promise<SuccessResponse>;
+    get(chatId: string, options?: RequestOptions): Promise<AssistantChatDetailResponse>;
     /**
-     * POST /composer/chat/{composerChatId}/revert
+     * GET /assistant/chat/{chatId}/listen/{runId} — SSE
+     *
+     * Opens a Server-Sent Events stream for real-time Assistant output. This is a
+     * data-only stream: each yielded value is an {@link AssistantSSEEvent}
+     * discriminated on `type`. A `user_input_request` frame signals a HITL pause —
+     * answer it with `resume()`.
      *
-     * Reverts the Composer's pending changes, restoring the last saved state.
+     * A 404 on connect throws `NotFoundError` before any event is yielded — the
+     * chat/run does not exist OR is not owned by your organization (ownership
+     * failures return an identical 404, not 403). The stream does NOT
+     * auto-reconnect on a 404.
      */
-    revert(composerChatId: string, options?: RequestOptions): Promise<SuccessResponse>;
+    listen(chatId: string, runId: string, options?: RequestOptions): AsyncGenerator<AssistantSSEEvent>;
     /**
-     * GET /composer/chat/workflow/{workflowId}/history
+     * POST /assistant/chat/{chatId}/resume
      *
-     * Returns the Composer chat history associated with a workflow.
+     * Answers an open HITL question and resumes the paused run. Returns a NEW
+     * `run_id` to listen on.
+     *
+     * Errors: 404 (a `NotFoundError`) when the chat is not found OR is not owned by
+     * your organization (ownership failures return an identical 404, not 403); 410
+     * if the question was already answered or cancelled; 403 if the caller is not
+     * the user who triggered it. `llm` is required (400 if omitted).
      */
-    history(workflowId: string, params?: ComposerHistoryParams, options?: RequestOptions): Promise<Record<string, unknown>>;
+    resume(chatId: string, params: AssistantResumeParams, options?: RequestOptions): Promise<AssistantResumeResponse>;
     /**
-     * DELETE /composer/chat/{composerChatId}
+     * GET /assistant/chat/{chatId}/status
      *
-     * Deletes a Composer chat session. Pass `permanent: true` to also delete
-     * the associated workflow.
+     * Returns real-time status including HITL pause state (`awaiting_input` /
+     * `pending_request_id`).
      */
-    delete(composerChatId: string, params?: ComposerDeleteParams, options?: RequestOptions): Promise<SuccessResponse>;
+    status(chatId: string, options?: RequestOptions): Promise<AssistantStatusResponse>;
     /**
-     * GET /composer/chat/{composerChatId}/status
+     * POST /assistant/chat/{chatId}/cancel
      *
-     * Returns the real-time status of a Composer chat session.
+     * Cancels the in-progress run and clears any pending HITL question. The
+     * returned `run_id` is the run that was cancelled. Errors: 404 (a
+     * `NotFoundError`) when the chat is not found OR is not owned by your
+     * organization (ownership failures return an identical 404, not 403); 400 if
+     * there is no active execution.
      */
-    status(composerChatId: string, options?: RequestOptions): Promise<ComposerStatusResponse>;
+    cancel(chatId: string, options?: RequestOptions): Promise<AssistantCancelResponse>;
     /**
-     * POST /composer/chat/{composerChatId}/cancel
+     * DELETE /assistant/chat/{chatId}
      *
-     * Cancels the in-progress run for a Composer chat session.
+     * Deletes an Assistant chat. Pass `permanent: true` for a hard delete
+     * (default is a soft delete).
      */
-    cancel(composerChatId: string, options?: RequestOptions): Promise<SuccessResponse>;
+    delete(chatId: string, params?: AssistantDeleteParams, options?: RequestOptions): Promise<AssistantDeleteResponse>;
 }
 
 /**
@@ -3104,7 +4750,7 @@ declare class Dashboard extends BaseResource {
      *
      * Returns LLM token-usage analytics broken down by model and provider.
      */
-    analyticsLlmUsage(params?: AnalyticsToolsParams, options?: RequestOptions): Promise<AnalyticsLLMUsageResponse>;
+    analyticsLlmUsage(params?: AnalyticsLLMUsageParams, options?: RequestOptions): Promise<AnalyticsLLMUsageResponse>;
     /**
      * GET /dashboard/users
      *
@@ -3113,42 +4759,6 @@ declare class Dashboard extends BaseResource {
     users(params?: DashboardUsersParams, options?: RequestOptions): Promise<DashboardUsersResponse>;
 }
 
-/**
- * Subscriptions resource — billing and subscription plan management endpoints.
- * @module resources/subscriptions
- */
-
-/**
- * Provides methods for the `/subscriptions` API endpoints.
- */
-declare class Subscriptions extends BaseResource {
-    /**
-     * GET /subscriptions/organization-plans
-     *
-     * Returns the list of available organization subscription plans.
-     */
-    organizationPlans(options?: RequestOptions): Promise<OrganizationPlansResponse>;
-    /**
-     * GET /subscriptions/organization-billing
-     *
-     * Returns the current organization's billing status and active subscription.
-     */
-    billing(options?: RequestOptions): Promise<BillingResponse>;
-    /**
-     * POST /subscriptions/checkout-link
-     *
-     * Creates a Stripe Checkout session and returns the redirect URL.
-     */
-    checkoutLink(params: CheckoutParams, options?: RequestOptions): Promise<CheckoutResponse>;
-    /**
-     * POST /subscriptions/customer-portal
-     *
-     * Creates a Stripe Customer Portal session and returns the redirect URL
-     * for the user to manage their billing.
-     */
-    customerPortal(options?: RequestOptions): Promise<PortalResponse>;
-}
-
 /**
  * Notifications resource — organization notification management endpoints.
  * @module resources/notifications
@@ -3168,49 +4778,40 @@ declare class Notifications extends BaseResource {
      * POST /notifications/organization
      *
      * Creates a new notification for the organization or a specific user.
+     *
+     * Requires an organization context: an `X-Organization-ID` header is sent
+     * automatically from the client's configured `organizationId` or from
+     * `options.organizationId`. If neither is set, no header is sent and the
+     * backend responds with HTTP 400 ("X-Organization-ID header is required").
+     *
+     * @returns The created notification wrapped in a `{ success, notification }`
+     *   envelope.
      */
-    create(params: CreateNotificationParams, options?: RequestOptions): Promise<Record<string, unknown>>;
+    create(params: CreateNotificationParams, options?: RequestOptions): Promise<CreateNotificationResponse>;
 }
 
 /**
- * System resource — health, metrics, and timezone endpoints.
+ * System resource — timezone utilities.
  * @module resources/system
  */
 
 /**
- * Provides methods for the `/system` API endpoints.
+ * Provides methods for the `/system` timezone endpoints.
  */
 declare class System extends BaseResource {
-    /**
-     * GET /system/health
-     *
-     * Returns the service health status, name, and version.
-     */
-    health(options?: RequestOptions): Promise<{
-        status: string;
-        service: string;
-        version: string;
-    }>;
-    /**
-     * GET /system/metrics
-     *
-     * Returns Prometheus-format metrics as plain text.
-     * This endpoint bypasses the JSON-parsing logic of `BaseResource.get()` and
-     * reads the raw response body as a string.
-     */
-    metrics(options?: RequestOptions): Promise<string>;
     /**
      * GET /system/timezones
      *
-     * Returns the list of supported IANA timezone identifiers.
+     * Returns popular timezone groups plus the full list of IANA identifiers.
      */
-    timezones(options?: RequestOptions): Promise<Record<string, unknown>>;
+    timezones(options?: RequestOptions): Promise<TimezoneListResponse>;
     /**
      * GET /system/timezones/search
      *
-     * Searches supported IANA timezone identifiers by query string.
+     * Searches supported IANA timezones by query string. `query` must be at least
+     * 2 characters (the backend returns 422 otherwise). Returns at most 20 results.
      */
-    searchTimezones(query: string, options?: RequestOptions): Promise<Record<string, unknown>>;
+    searchTimezones(query: string, options?: RequestOptions): Promise<TimezoneOption[]>;
 }
 
 /**
@@ -3237,16 +4838,16 @@ declare class Modulex {
     private _organizations?;
     private _workflows?;
     private _executions?;
+    private _workflowRuns?;
     private _deployments?;
     private _chats?;
     private _credentials?;
     private _integrations?;
     private _knowledge?;
     private _schedules?;
-    private _templates?;
     private _composer?;
+    private _assistant?;
     private _dashboard?;
-    private _subscriptions?;
     private _notifications?;
     private _system?;
     constructor(config: ModulexConfig);
@@ -3258,8 +4859,10 @@ declare class Modulex {
     get organizations(): Organizations;
     /** Workflow CRUD endpoints. */
     get workflows(): Workflows;
-    /** Workflow execution endpoints (run, resume, cancel, listen). */
+    /** Workflow execution-control endpoints (run, resume, cancel, listen). */
     get executions(): Executions;
+    /** Durable workflow run-history endpoints (list, get persisted runs). */
+    get workflowRuns(): WorkflowRuns;
     /** Workflow deployment endpoints. */
     get deployments(): Deployments;
     /** Chat endpoints. */
@@ -3272,14 +4875,12 @@ declare class Modulex {
     get knowledge(): Knowledge;
     /** Schedule management endpoints. */
     get schedules(): Schedules;
-    /** Template endpoints. */
-    get templates(): Templates;
     /** Composer (AI workflow builder) endpoints. */
     get composer(): Composer;
+    /** Assistant (HITL chat agent) endpoints. */
+    get assistant(): Assistant;
     /** Dashboard and analytics endpoints. */
     get dashboard(): Dashboard;
-    /** Subscription and billing endpoints. */
-    get subscriptions(): Subscriptions;
     /** Notification endpoints. */
     get notifications(): Notifications;
     /** System health and utility endpoints. */
@@ -3288,11 +4889,22 @@ declare class Modulex {
 
 /**
  * Base error class for all ModuleX SDK errors.
+ *
+ * When the API returns a structured error envelope — either a dict-shaped
+ * `detail` (e.g. rate-limit) or a flat top-level `{code, reason, ...}` body
+ * (e.g. BillingDenied, which has no `detail` wrapper) — the `code`, `reason`
+ * and `layer` fields are surfaced here for programmatic handling.
  */
 declare class ModulexError extends Error {
     readonly status: number | undefined;
     readonly body: unknown;
     readonly headers: Headers | undefined;
+    /** Machine-readable error code from the API envelope, if present. */
+    readonly code?: string;
+    /** Human-readable reason from the API envelope, if present. */
+    readonly reason?: string;
+    /** The layer/subsystem that produced the error (e.g. "billing", "auth"), if present. */
+    readonly layer?: string;
     constructor(message: string, status: number | undefined, body: unknown, headers: Headers | undefined);
 }
 /** Thrown when the API returns 400 Bad Request. */
@@ -3321,8 +4933,14 @@ declare class ValidationError extends ModulexError {
 }
 /** Thrown when the API returns 429 Too Many Requests. */
 declare class RateLimitError extends ModulexError {
-    /** Seconds to wait before retrying (from Retry-After header). */
+    /** Seconds to wait before retrying (from the Retry-After header). */
     readonly retryAfter: number | undefined;
+    /** The rate limit ceiling, from the X-RateLimit-Limit header. */
+    readonly limit: number | undefined;
+    /** Remaining requests in the window, from the X-RateLimit-Remaining header. */
+    readonly remaining: number | undefined;
+    /** Unix epoch (seconds) when the window resets, from the X-RateLimit-Reset header. */
+    readonly reset: number | undefined;
     constructor(message: string, body: unknown, headers: Headers | undefined);
 }
 /** Thrown when the API returns 500 Internal Server Error. */
@@ -3346,4 +4964,4 @@ declare class TimeoutError extends ModulexError {
     constructor(message?: string);
 }
 
-export { type ActivateDeploymentResponse, type AgentNodeConfig, type AnalyticsLLMUsageResponse, type AnalyticsOverviewParams, type AnalyticsOverviewResponse, type AnalyticsToolsParams, type AnalyticsToolsResponse, type ApiKeyListResponse, type ApiKeyResponse, AuthenticationError, BadRequestError, type BillingResponse, type BrowseParams, type BrowseResponse, type BuilderDetailsParams, type BuilderDetailsResponse, type CancelInvitationResponse, type CancelResponse, type ChatListResponse, type ChatMessageResponse, type ChatMessagesParams, type ChatMessagesResponse, type ChatResponse, type CheckoutParams, type CheckoutResponse, type ChunkResponse, type ChunkingConfig, type ComposerChatDetailResponse, type ComposerChatParams, type ComposerChatResponse, type ComposerDeleteParams, type ComposerHistoryParams, type ComposerStatusResponse, type ConditionalBranch, type ConditionalNodeConfig, ConflictError, type CreateApiKeyParams, type CreateApiKeyResponse, type CreateCreatorParams, type CreateCredentialParams, type CreateDeploymentParams, type CreateKnowledgeBaseParams, type CreateNotificationParams, type CreateOrganizationParams, type CreateOrganizationResponse, type CreateScheduleParams, type CreateTemplateParams, type CreateWorkflowParams, type CreatorInfo, type CredentialAuditParams, type CredentialListFlat, type CredentialListGrouped, type CredentialListParams, type CredentialResponse, type CredentialUsageParams, type CredentialUsageResponse, type DashboardLogsParams, type DashboardLogsResponse, type DashboardUsersParams, type DashboardUsersResponse, type DeactivateDeploymentResponse, type DeleteDeploymentResponse, type DeleteWorkflowResponse, type DeploymentDetailResponse, type DeploymentListParams, type DeploymentListResponse, type DeploymentResponse, type DocumentChunksParams, type DocumentChunksResponse, type DocumentListParams, type DocumentResponse, type DocumentStatusResponse, type DoneEventData, type EdgeDefinition, type EmbeddingConfig, type ErrorEventData, ExternalServiceError, type FunctionNodeConfig, type GuardrailsNodeConfig, type HybridSearchParams, type IntegrationResponse, InternalError, type InterruptEventData, type InterruptNodeConfig, type InvitationResponse, type InvitationsResponse, type InviteParams, type KnowledgeBaseListParams, type KnowledgeBaseListResponse, type KnowledgeBaseResponse, type KnowledgeBaseStatsResponse, type KnowledgeNodeConfig, type KnowledgeProviderResponse, type LLMConfig, type LLMNodeConfig, type LLMProviderResponse, type LLMsResponse, type LeaveResponse, type LoopConfig, type McpServerParams, type McpToolsResponse, type MetadataEventData, Modulex, type ModulexConfig, ModulexError, type MultiSearchParams, type MyTemplatesResponse, type NodeDefinition, type NodeType, type NodeUpdateEventData, NotFoundError, type NotificationListResponse, type NotificationResponse, type OrganizationInfo, type OrganizationPlansResponse, type OrganizationsResponse, type PaginatedList, PermissionError, type Plan, type PlanPrice, type PortalResponse, RateLimitError, type RefreshDiscoveryResponse, type RequestOptions, type ResumedEventData, type RetrieveContextParams, type RetrieveContextResponse, type RetryConfig, type RevokeApiKeyResponse, type RoleUpdateParams, type RoleUpdateResponse, type SSEEvent, type ScheduleListParams, type ScheduleListResponse, type ScheduleResponse, type ScheduleRunListParams, type ScheduleRunResponse, type ScheduleRunStatsParams, type ScheduleRunStatsResponse, type SearchParams, type SearchResponse, type SearchResult, ServiceUnavailableError, type StateSchema, type StateSchemaField, StreamError, type Subscription, type SuccessResponse, type SupportedFileTypesResponse, type TemplateLikeResponse, type TemplateListResponse, type TemplateResponse, type TemplateUseResponse, type TestCredentialResponse, type TestTemporaryParams, type TestTemporaryResponse, TimeoutError, type ToolDefinition, type ToolIntegrationResponse, type ToolNodeConfig, type TransformerNodeConfig, type TransformerOperation, type UpdateChatParams, type UpdateCredentialParams, type UpdateKnowledgeBaseParams, type UpdateScheduleParams, type UpdateTemplateRequestParams, type UpdateWorkflowParams, type UploadDocumentParams, type UserResponse, ValidationError, type WorkflowConfig, type WorkflowDefinition, type WorkflowListParams, type WorkflowListResponse, type WorkflowMetadata, type WorkflowResponse, type WorkflowResumeParams, type WorkflowResumeResponse, type WorkflowRunParams, type WorkflowRunResponse, type WorkflowSSEEvent, type WorkflowStateResponse, type WorkflowSummary };
+export { type AcceptedInvitationOrganization, type ActivateDeploymentResponse, type AgentNodeConfig, type AnalyticsLLMUsageData, type AnalyticsLLMUsageParams, type AnalyticsLLMUsageResponse, type AnalyticsLLMUsageSuccess, type AnalyticsOverview, type AnalyticsOverviewParams, type AnalyticsOverviewResponse, type AnalyticsOverviewSuccess, type AnalyticsSubscription, type AnalyticsToolsData, type AnalyticsToolsParams, type AnalyticsToolsResponse, type AnalyticsToolsSuccess, type ApiKeyListResponse, type ApiKeyResponse, type AssistantCancelResponse, type AssistantChatDetailResponse, type AssistantChatListResponse, type AssistantChatParams, type AssistantChatResponse, type AssistantChatSummary, type AssistantDeleteParams, type AssistantDeleteResponse, type AssistantListParams, type AssistantMessageResponse, type AssistantResumeParams, type AssistantResumeResponse, type AssistantSSEEvent, type AssistantStatusResponse, type AuditLogResponse, type AuthSchema, AuthenticationError, BadRequestError, type BrowseParams, type BrowseResponse, type BuilderDetailsParams, type BuilderDetailsResponse, type BuilderNodeTypeDescriptor, type CancelInvitationResponse, type CancelResponse, type ChatConnectedEvent, type ChatListItem, type ChatListResponse, type ChatListUpdatedEvent, type ChatMessageResponse, type ChatMessagesParams, type ChatMessagesResponse, type ChatResponse, type ChoiceOption, type ChunkResponse, type ChunkingConfig, type ComposerCancelResponse, type ComposerChatDetailResponse, type ComposerChatListItem, type ComposerChatListResponse, type ComposerChatParams, type ComposerChatResponse, type ComposerDeleteParams, type ComposerDeleteResponse, type ComposerFocusParams, type ComposerFocusResponse, type ComposerLLMParams, type ComposerLLMResponse, type ComposerLLMSelection, type ComposerListParams, type ComposerMessageResponse, type ComposerResumeParams, type ComposerResumeResponse, type ComposerRevertResponse, type ComposerSSEEvent, type ComposerSaveParams, type ComposerSaveResponse, type ComposerStatusResponse, type ComposerWorkflowSync, type ConditionalBranch, type ConditionalNodeConfig, ConflictError, type CreateApiKeyParams, type CreateApiKeyResponse, type CreateCredentialParams, type CreateDeploymentParams, type CreateKnowledgeBaseParams, type CreateNotificationParams, type CreateNotificationResponse, type CreateOrganizationParams, type CreateOrganizationResponse, type CreateScheduleParams, type CreateWorkflowParams, type CreatedNotification, type CredentialAddedResponse, type CredentialAuditParams, type CredentialAuthOption, type CredentialDetailResponse, type CredentialFailedResponse, type CredentialFailureCode, type CredentialListFlat, type CredentialListGrouped, type CredentialListParams, type CredentialRequest, type CredentialResponse, type CredentialUsageParams, type CredentialUsageResponse, type CurrentMonthCreditUsage, type DashboardErrorEnvelope, type DashboardInvitationUser, type DashboardLogsFilters, type DashboardLogsParams, type DashboardLogsResponse, type DashboardLogsSuccess, type DashboardMemberUser, type DashboardUser, type DashboardUsersParams, type DashboardUsersResponse, type DashboardUsersSuccess, type DeactivateDeploymentResponse, type DeleteDeploymentResponse, type DeleteScheduleResponse, type DeleteWorkflowResponse, type DeploymentDetailResponse, type DeploymentListParams, type DeploymentListResponse, type DeploymentResponse, type DocumentChunksParams, type DocumentChunksResponse, type DocumentListParams, type DocumentResponse, type DocumentStatusResponse, type DoneEventData, type EdgeDefinition, type EmbeddingConfig, type ErrorEventData, ExternalServiceError, type FreeTextRequest, type FreeTextResponse, type FunctionNodeConfig, type GuardrailsNodeConfig, type HybridSearchParams, type InitiateOAuth2Params, type IntegrationDetail, type IntegrationMetadata, type IntegrationResponse, InternalError, type InterruptEventData, type InterruptNodeConfig, type InvitationInviter, type InvitationNotification, type InvitationObject, type InvitationOrganization, type InvitationResponse, type InvitationsResponse, type InviteParams, type InvitePreviewResponse, type KnowledgeBaseListParams, type KnowledgeBaseResponse, type KnowledgeBaseStatsResponse, type KnowledgeNodeConfig, type KnowledgeProviderResponse, type LLMConfig, type LLMModelEntry, type LLMNodeConfig, type LLMProviderResponse, type LLMUsage, type LLMsResponse, type LeaveResponse, type LoopConfig, type MCPServerCredentialResponse, type McpServerParams, type McpToolsResponse, type MetadataEventData, Modulex, type ModulexConfig, ModulexError, type ModulexKeyBulkEventData, type ModulexKeyBulkSummary, type ModulexKeyIntegrationStatus, type MostUsedAction, type MultiChoiceRequest, type MultiChoiceResponse, type MultiSearchParams, type NodeDefinition, type NodeStartedEventData, type NodeType, type NodeUpdateEventData, NotFoundError, type NotificationBase, type NotificationListResponse, type NotificationResponse, type OAuth2InitiateResponse, type OrganizationInfo, type OrganizationNotification, type OrganizationNotificationTopic, type OrganizationsResponse, type OverviewCredentialUsageLog, type PaginatedList, PermissionError, RateLimitError, type RefreshDiscoveryResponse, type RequestOptions, type ResumedEventData, type RetrieveContextParams, type RetrieveContextResponse, type RetryConfig, type RetryRunResponse, type RevokeApiKeyResponse, type RoleUpdateParams, type RoleUpdateResponse, type SSEEvent, type ScheduleListParams, type ScheduleListResponse, type ScheduleResponse, type ScheduleRunListParams, type ScheduleRunListResponse, type ScheduleRunResponse, type ScheduleRunStatsParams, type ScheduleRunStatsResponse, type SearchMatch, type SearchParams, type SearchResponse, ServiceUnavailableError, type SetModelVisibilityParams, type SetModelVisibilityResponse, type SettingsResponse, type SingleChoiceRequest, type SingleChoiceResponse, type SkippedResponse, type StateSchema, type StateSchemaField, StreamError, type SuccessResponse, type SupportedFileTypesResponse, type SystemNotification, type SystemNotificationTopic, type TestCredentialResponse, type TestTemporaryParams, type TestTemporaryResponse, TimeoutError, type TimezoneGroup, type TimezoneListResponse, type TimezoneOption, type ToolDefinition, type ToolIntegrationResponse, type ToolNodeConfig, type ToolUsage, type TransformerNodeConfig, type TransformerOperation, type UpdateChatParams, type UpdateCredentialParams, type UpdateKnowledgeBaseParams, type UpdateScheduleParams, type UpdateWorkflowParams, type UploadDocumentParams, type UserInputRequest, type UserInputRequestBase, type UserInputResponse, type UserResponse, ValidationError, type WorkflowChangeEvent, type WorkflowConfig, type WorkflowDefinition, type WorkflowListParams, type WorkflowListResponse, type WorkflowMessageEnvelope, type WorkflowMetadata, type WorkflowResponse, type WorkflowResumeParams, type WorkflowResumeResponse, type WorkflowRunDetail, type WorkflowRunListItem, type WorkflowRunListParams, type WorkflowRunListResponse, type WorkflowRunParams, type WorkflowRunResponse, type WorkflowSSEEvent, type WorkflowStateResponse, type WorkflowSummary, type YesNoRequest, type YesNoResponse };