@lunnoa/client 2.4.0 → 3.0.0

package/dist/react.d.ts

@@ -206,6 +206,32 @@ declare class AgentChatClient {
 
 interface components {
     schemas: {
+        PublicAiModelResponseDto: {
+            /** @description Catalogue model id passed to agent deploy as `model`. Example: `deepseek-ai/DeepSeek-V4-Pro`. */
+            id: string;
+            /** @description Display name. */
+            name: string;
+            /** @description True when this is the model used if an agent deploy omits `model` on this connection. */
+            isDefault: boolean;
+            /** @description Whether the model can call tools. */
+            supportsTools: boolean;
+            /** @description Whether the model accepts image input. */
+            supportsVision: boolean;
+            /** @description Whether the model exposes a reasoning mode. */
+            supportsReasoning: boolean;
+        };
+        PublicAiConnectionResponseDto: {
+            /** @description AiProviderConnection UUID. Pass as `aiConnectionId` / `defineAiConnection({ id })` when this connection is not the default. */
+            id: string;
+            /** @description Connection display name. Example: `Lunnoa LLMs`. */
+            name: string;
+            /** @description Provider slug. Example: `featherless` or `openai`. */
+            provider: string;
+            /** @description True for the connection used when an agent deploy omits `aiConnectionId`. */
+            isDefault: boolean;
+            /** @description Models this connection accepts. Inactive models are omitted. */
+            models: components["schemas"]["PublicAiModelResponseDto"][];
+        };
         AuthMethodFlagsDto: {
             /** @description True when password-based login is disabled for this deployment (via AUTH_DISABLED_METHODS). */
             passwordDisabled: boolean;
@@ -809,26 +835,13 @@ interface components {
             /** @description Number of item IDs submitted for deletion. */
             requestedCount: number;
         };
-        UpsertWorkflowStepDto: {
-            /**
-             * @description Name later steps use in ={{step:<key>,path}}. Keyed steps keep their node id across deploys. "trigger" is reserved.
-             * @example loadCase
-             */
-            key?: string;
-            /** @description Workflow app id (catalogue slug). */
-            appId: string;
-            /** @description Catalogue action id. */
-            actionId: string;
-            /** @description Connection instance UUID for this step. */
-            connectionId?: string;
-            /** @description Action input / config fields. String values may use ={{step:trigger,field}} or ={{step:<key>,path,to,value}}. */
-            input?: {
-                [key: string]: unknown;
-            };
-            /** @description Display name for the step node. */
-            name?: string;
-            /** @description Step description. */
-            description?: string;
+        UpsertWorkflowPathConditionDto: {
+            /** @description One step reference, e.g. ={{step:load,amount}}. */
+            field: string;
+            /** @description contains, does_not_contain, equals, does_not_equal, exists, does_not_exist, starts_with, ends_with, is_empty, is_not_empty, comes_before, comes_after, is_in_the_past, is_in_the_future, is_true, is_false, is_truthy, is_falsey, is_greater_than, is_less_than, is_greater_than_or_equal_to, is_less_than_or_equal_to, matches_regex, does_not_match_regex. */
+            condition: string;
+            /** @description Value to compare with. */
+            value?: string;
         };
         UpsertWorkflowTriggerInputFieldDto: {
             /** @description Field id. Callers pass this key to workflows.execute. */
@@ -839,14 +852,10 @@ interface components {
             /** @description text, number, date, or select. Defaults to text. */
             inputType?: string;
             /** @description true, or { missingMessage, missingStatus }. */
-            required?: boolean | {
-                [key: string]: unknown;
-            };
+            required?: Record<string, never>;
             /** @description Used when the caller omits the field. */
-            defaultValue?: unknown;
-            selectOptions?: {
-                [key: string]: unknown;
-            }[];
+            defaultValue?: Record<string, never>;
+            selectOptions?: Record<string, never>[];
         };
         UpsertWorkflowTriggerDto: {
             /** @description Catalogue trigger id, for example flow-control_trigger_manual. */
@@ -865,6 +874,59 @@ interface components {
             name?: string;
             description?: string;
         };
+        UpsertWorkflowRetrySettingsDto: {
+            enabled: boolean;
+            /** @description How many times to attempt the step. */
+            maxAttempts: number;
+            /** @description Delay between attempts, in seconds. */
+            delaySeconds: number;
+        };
+        UpsertWorkflowContinueOnFailureDto: {
+            enabled: boolean;
+        };
+        UpsertWorkflowPathDto: {
+            /** @description Path label, unique on its step. */
+            label: string;
+            /** @description Conditional Paths only. Groups are OR-ed, conditions inside a group AND-ed. Omit to always take this path. */
+            when?: components["schemas"]["UpsertWorkflowPathConditionDto"][][];
+            /** @description Steps on this path. */
+            steps: components["schemas"]["UpsertWorkflowStepDto"][];
+        };
+        UpsertWorkflowStepDto: {
+            /**
+             * @description Name later steps use in ={{step:<key>,path}}. Keyed steps keep their node id across deploys. "trigger" is reserved.
+             * @example loadCase
+             */
+            key?: string;
+            /** @description Workflow app id (catalogue slug). */
+            appId: string;
+            /** @description Catalogue action id. */
+            actionId: string;
+            /** @description Connection instance UUID for this step. */
+            connectionId?: string;
+            /** @description Action input / config fields. String values may use ={{step:trigger,field}} or ={{step:<key>,path,to,value}}. */
+            input?: {
+                [key: string]: unknown;
+            };
+            /** @description Display name for the step node. */
+            name?: string;
+            /** @description Step description. */
+            description?: string;
+            retrySettings?: components["schemas"]["UpsertWorkflowRetrySettingsDto"];
+            continueOnFailure?: components["schemas"]["UpsertWorkflowContinueOnFailureDto"];
+            /** @description Branches after this step. Only on flow-control_action_conditional-paths, flow-control_action_manually-decide-paths, or flow-control_action_request-approval (approved path first, then rejected), and only on the last step of a list. */
+            paths?: components["schemas"]["UpsertWorkflowPathDto"][];
+        };
+        UpsertWorkflowGraphDto: {
+            /** @description Graph-file nodes. Each node has key, nodeType, appId, name, and value. The trigger key is "trigger". */
+            nodes: {
+                [key: string]: unknown;
+            }[];
+            /** @description Edges. source and target are node keys. */
+            edges: {
+                [key: string]: unknown;
+            }[];
+        };
         UpsertWorkflowBySlugDto: {
             /**
              * @description Stable workspace-scoped slug (lowercase, digits, hyphens). Used as the upsert key.
@@ -876,12 +938,107 @@ interface components {
             description?: string;
             /** @description Whether the workflow is active. */
             isActive?: boolean;
-            /** @description Catalogue trigger. Omit for a Manually Run trigger with no input fields. */
+            /** @description Catalogue trigger for a steps body. Omit for a Manually Run trigger with no input fields. Not valid with `graph`. */
             trigger?: components["schemas"]["UpsertWorkflowTriggerDto"];
-            /** @description Linear catalogue-action steps (v1; no branches). */
-            steps: components["schemas"]["UpsertWorkflowStepDto"][];
-            /** @description Marks the row as managed by code (CLI / SDK). Defaults to true on this endpoint. */
-            managedByCode?: boolean;
+            /** @description Catalogue-action steps in order. The last step may branch with `paths`. Send this or `graph`, not both. */
+            steps?: components["schemas"]["UpsertWorkflowStepDto"][];
+            /** @description Full graph in the graph-file shape. Send this or `steps`, not both. `trigger` is not valid with a graph. */
+            graph?: components["schemas"]["UpsertWorkflowGraphDto"];
+            /** @description Revision from the last pull. Required when updating a workflow that the UI can edit, unless `force` is true. */
+            baseRevision?: string;
+            /** @description Overwrite an existing workflow even when `baseRevision` is missing or stale. */
+            force?: boolean;
+            /**
+             * @description How code owns this workflow. Defaults to generated on this endpoint.
+             * @enum {string}
+             */
+            codeSource?: "synced" | "generated";
+        };
+        UpsertWorkflowResponseDto: {
+            /** @description Workflow ID */
+            id: string;
+            /** @description Workflow name */
+            name: string;
+            /** @description Stable workspace-scoped slug for CLI / code deploy upserts. Included when `expansion=slug` is requested. */
+            slug?: string | null;
+            /**
+             * @description Code source stored by this push. `generated` when the request omits it.
+             * @enum {string}
+             */
+            codeSource?: "none" | "synced" | "generated";
+            /**
+             * @description Sync state against the definitions folder. Included when `expansion=codeSyncStatus` is requested.
+             * @enum {string}
+             */
+            codeSyncStatus?: "none" | "in_sync" | "changed_in_ui" | "locked";
+            /** @description Workflow description. Included when `expansion=description` is requested. */
+            description?: string | null;
+            /** @description Declared output schema from the workflow's Output Workflow Data node. Shape is a map of field ID to `{ type, description? }`. Included when `expansion=output` is requested. Null when the workflow has no declared output schema. */
+            output?: {
+                [key: string]: unknown;
+            } | null;
+            /**
+             * Format: date-time
+             * @description Creation timestamp. Included when `expansion=createdAt` is requested.
+             */
+            createdAt?: string;
+            /**
+             * Format: date-time
+             * @description Last update timestamp. Included when `expansion=updatedAt` is requested.
+             */
+            updatedAt?: string;
+            /** @description Whether the workflow is active and can be triggered. Included when `expansion=isActive` is requested. */
+            isActive?: boolean;
+            /** @description Whether the workflow is internal (hidden from default listings). Included when `expansion=isInternal` is requested. */
+            isInternal?: boolean;
+            /** @description Object type whose records list this workflow's runs. Included when `expansion=objectLink` is requested. */
+            objectTypeId?: string | null;
+            /** @description Dot path on the trigger payload. A Lunnoa id when the type has no unique key, otherwise that key's value. Included when `expansion=objectLink` is requested. */
+            objectIdPath?: string | null;
+            /** @description Create a record when the unique key value is not found, then file the run on it. Included when `expansion=objectLink` is requested. */
+            createObjectIfMissing?: boolean;
+            /** @description Unique key on the linked object type (`name` or `attribute:<field>`). Included when `expansion=objectLink` is requested. */
+            uniqueKeyField?: string | null;
+            /** @description Workflow node definitions (JSON). Included when `expansion=nodes` is requested. */
+            nodes?: {
+                [key: string]: unknown;
+            }[];
+            /** @description Workflow edge definitions connecting nodes (JSON). Included when `expansion=edges` is requested. */
+            edges?: {
+                [key: string]: unknown;
+            }[];
+            /** @description The workflow trigger node definition (JSON). Included when `expansion=triggerNode` is requested. */
+            triggerNode?: {
+                [key: string]: unknown;
+            } | null;
+            /** @description IDs of the triggers and actions used by the workflow. Included when `expansion=triggerAndActionIds` is requested. */
+            triggerAndActionIds?: string[];
+            /** @description IDs of sub-workflows referenced by the workflow. Included when `expansion=subWorkflowIds` is requested. Only returned by GET /workflows/{workflowId}. */
+            subWorkflowIds?: string[];
+            /** @description IDs of agents referenced by the workflow. Included when `expansion=agentIds` is requested. Only returned by GET /workflows/{workflowId}. */
+            agentIds?: string[];
+            /** @description Internal polling trigger storage value. Included when `expansion=pollStorage` is requested. */
+            pollStorage?: string | null;
+            /**
+             * Format: date-time
+             * @description Timestamp of the next scheduled execution, if the workflow runs on a schedule. Included when `expansion=nextScheduledExecution` is requested.
+             */
+            nextScheduledExecution?: string | null;
+            /**
+             * @description Editor orientation of the workflow canvas. Included when `expansion=orientation` is requested.
+             * @enum {string}
+             */
+            workflowOrientation?: "HORIZONTAL" | "VERTICAL";
+            /** @description AI provider connection used by the workflow builder chat. Always returned on GET /workflows/{workflowId}. */
+            aiConnectionId?: string | null;
+            /** @description Selected model ID within the AI provider connection for workflow builder chat. Always returned on GET /workflows/{workflowId}. */
+            selectedModelId?: string | null;
+            /** @description sha256 hex of the canonical definition that was stored. */
+            revision: string;
+            /** @description Definition that was stored. Steps format when it round-trips, otherwise graph format. */
+            definition: {
+                [key: string]: unknown;
+            };
         };
         WorkflowResponseDto: {
             /** @description Workflow ID */
@@ -890,8 +1047,16 @@ interface components {
             name: string;
             /** @description Stable workspace-scoped slug for CLI / code deploy upserts. Included when `expansion=slug` is requested. */
             slug?: string | null;
-            /** @description True when last written by code (CLI / SDK). Included when `expansion=managedByCode` is requested. */
-            managedByCode?: boolean;
+            /**
+             * @description Where this workflow is defined. Included when `expansion=codeSource` is requested.
+             * @enum {string}
+             */
+            codeSource?: "none" | "synced" | "generated";
+            /**
+             * @description Sync state against the definitions folder. Included when `expansion=codeSyncStatus` is requested.
+             * @enum {string}
+             */
+            codeSyncStatus?: "none" | "in_sync" | "changed_in_ui" | "locked";
             /** @description Workflow description. Included when `expansion=description` is requested. */
             description?: string | null;
             /** @description Declared output schema from the workflow's Output Workflow Data node. Shape is a map of field ID to `{ type, description? }`. Included when `expansion=output` is requested. Null when the workflow has no declared output schema. */
@@ -924,77 +1089,505 @@ interface components {
             nodes?: {
                 [key: string]: unknown;
             }[];
-            /** @description Workflow edge definitions connecting nodes (JSON). Included when `expansion=edges` is requested. */
-            edges?: {
-                [key: string]: unknown;
+            /** @description Workflow edge definitions connecting nodes (JSON). Included when `expansion=edges` is requested. */
+            edges?: {
+                [key: string]: unknown;
+            }[];
+            /** @description The workflow trigger node definition (JSON). Included when `expansion=triggerNode` is requested. */
+            triggerNode?: {
+                [key: string]: unknown;
+            } | null;
+            /** @description IDs of the triggers and actions used by the workflow. Included when `expansion=triggerAndActionIds` is requested. */
+            triggerAndActionIds?: string[];
+            /** @description IDs of sub-workflows referenced by the workflow. Included when `expansion=subWorkflowIds` is requested. Only returned by GET /workflows/{workflowId}. */
+            subWorkflowIds?: string[];
+            /** @description IDs of agents referenced by the workflow. Included when `expansion=agentIds` is requested. Only returned by GET /workflows/{workflowId}. */
+            agentIds?: string[];
+            /** @description Internal polling trigger storage value. Included when `expansion=pollStorage` is requested. */
+            pollStorage?: string | null;
+            /**
+             * Format: date-time
+             * @description Timestamp of the next scheduled execution, if the workflow runs on a schedule. Included when `expansion=nextScheduledExecution` is requested.
+             */
+            nextScheduledExecution?: string | null;
+            /**
+             * @description Editor orientation of the workflow canvas. Included when `expansion=orientation` is requested.
+             * @enum {string}
+             */
+            workflowOrientation?: "HORIZONTAL" | "VERTICAL";
+            /** @description AI provider connection used by the workflow builder chat. Always returned on GET /workflows/{workflowId}. */
+            aiConnectionId?: string | null;
+            /** @description Selected model ID within the AI provider connection for workflow builder chat. Always returned on GET /workflows/{workflowId}. */
+            selectedModelId?: string | null;
+        };
+        WorkflowDefinitionResponseDto: {
+            /** @description Workflow ID. */
+            id: string;
+            /** @description Workspace-scoped slug. */
+            slug: string;
+            /** @description Workspace that owns the workflow. */
+            workspaceId: string;
+            /**
+             * @description Where this workflow is defined.
+             * @enum {string}
+             */
+            codeSource: "none" | "synced" | "generated";
+            /** @description sha256 hex of the canonical workflow definition. */
+            revision: string;
+            /** @description Steps format when the graph round-trips through it, otherwise the graph format. */
+            definition: {
+                [key: string]: unknown;
+            };
+        };
+        CodeSyncContextResponseDto: {
+            /** @description Active workspace id. */
+            workspaceId: string;
+            /** @description When true, synced agents and workflows can only be changed by a code push. */
+            lockCodeSyncedResources: boolean;
+        };
+        AgentSlugOrIdDto: {
+            /**
+             * @description Workspace slug. Send exactly one of slug or id.
+             * @example support-triage
+             */
+            slug?: string;
+            /**
+             * Format: uuid
+             * @description Resource UUID. Send exactly one of slug or id.
+             */
+            id?: string;
+        };
+        UpsertAgentMcpServerDto: {
+            /**
+             * Format: uuid
+             * @description MCP server UUID.
+             */
+            id: string;
+            /**
+             * Format: uuid
+             * @description User connection UUID for this server. Null clears a pinned connection.
+             */
+            connectionId?: string | null;
+        };
+        UpsertAgentToolDto: {
+            /** @description Stable tool key. Omitted keys are assigned from the tool name. Pattern: ^[A-Za-z][A-Za-z0-9_-]*$. */
+            key?: string;
+            /** @description Workflow app id (catalogue slug). */
+            appId: string;
+            /** @description Catalogue action id. */
+            actionId: string;
+            /** @description Connection instance UUID pre-bound on the tool. */
+            connectionId?: string;
+            /** @description Tool display name for the model. */
+            name?: string;
+            /** @description Tool description shown to the model. */
+            description?: string;
+            /** @description Pre-filled tool config (fields left empty are filled by the model). */
+            input?: {
+                [key: string]: unknown;
+            };
+        };
+        UpsertAgentSettingsDto: {
+            /** @description Model temperature. */
+            temperature?: number;
+            /** @description Top-p sampling. */
+            topP?: number;
+            /** @description Maximum output tokens per turn. Null clears the cap. */
+            maxOutputTokens?: number | null;
+            /** @description Frequency penalty. */
+            frequencyPenalty?: number;
+            /** @description Presence penalty. */
+            presencePenalty?: number;
+            /** @description Fixed sampling seed. Null clears it. */
+            seed?: number | null;
+            /** @description Maximum retries for a failed model call. */
+            maxRetries?: number;
+            /** @description Maximum tool roundtrips per turn. */
+            maxToolRoundtrips?: number;
+            /** @description How many previous messages are sent to the model. */
+            messageLookbackLimit?: number;
+            /** @description Instructions used when auto-naming new tasks. Null clears them. */
+            taskNamingInstructions?: string | null;
+            /** @description IDs of enabled provider built-in tools. */
+            enabledBuiltInTools?: string[];
+            /** @description IDs of enabled platform tools. */
+            enabledPlatformTools?: string[];
+            /** @description Enabled tool-policy ids. */
+            enabledToolPolicies?: string[];
+            /** @description Per-tool force overrides, stored as JSON. */
+            forcedTools?: {
+                [key: string]: unknown;
+            }[];
+            /** @description Suggested prompts, in stored order. */
+            suggestedPrompts?: string[];
+            /** @description Index the workflow-app catalogue for discovery. */
+            dynamicActionDiscoveryEnabled?: boolean;
+            /** @description Index MCP servers visible to the user for discovery. */
+            dynamicMcpDiscoveryEnabled?: boolean;
+            /** @description Let the agent propose updates to its own instructions. */
+            dynamicSelfInstructionsEnabled?: boolean;
+            /** @description Whether agent memory is enabled. */
+            memoryEnabled?: boolean;
+            /**
+             * @description Whose memories this agent reads and writes.
+             * @enum {string}
+             */
+            memoryScope?: "PER_USER" | "PER_AGENT" | "PER_USER_PER_AGENT";
+            /** @description How many days memories are kept. */
+            memoryRetentionDays?: number;
+            /** @description Opt in to runtime planning tools. */
+            enablePlanning?: boolean;
+            /** @description Gate heavy tools until the user approves a runtime plan. */
+            requirePlanApproval?: boolean;
+            /** @description Offload oversized tool results. */
+            enableToolResultOffload?: boolean;
+            /** @description Byte threshold for tool-result offload. */
+            toolResultOffloadThresholdBytes?: number;
+            /** @description Elevated step budget for long-running work. */
+            longHorizonMode?: boolean;
+            /** @description Step budget when long-horizon mode is on. Null clears it. */
+            longHorizonMaxSteps?: number | null;
+            /** @description Soft token budget for a long-horizon run. Null clears it. */
+            longHorizonMaxTokensPerRun?: number | null;
+            /**
+             * @description How this agent routes prompts that contain PII.
+             * @enum {string}
+             */
+            piiRoutingMode?: "INHERIT" | "AUTO_FALLBACK" | "ASK" | "BLOCK" | "ANONYMIZE";
+            /**
+             * Format: uuid
+             * @description AI connection used when PII routing falls back. Null clears it.
+             */
+            piiFallbackConnectionId?: string | null;
+            /** @description Model used when PII routing falls back. Null clears it. */
+            piiFallbackModelId?: string | null;
+            /** @description Web search access. Null removes the web-access row. */
+            webAccess?: boolean | null;
+            /** @description Outbound phone access. Null removes the phone-access row. */
+            phoneAccess?: boolean | null;
+        };
+        UpsertAgentBySlugDto: {
+            /**
+             * @description Stable workspace-scoped slug (lowercase, digits, hyphens). Used as the upsert key.
+             * @example support-triage
+             */
+            slug: string;
+            /** @description Display name. Defaults to the slug when omitted on create. */
+            name?: string;
+            /** @description Agent description. Null clears it. */
+            description?: string | null;
+            /** @description System instructions / prompt for the agent. */
+            instructions: string;
+            /** @description Catalogue model id enabled on the AI connection. Omit or null when the definition has no model. Example: `deepseek-ai/DeepSeek-V4-Pro`. */
+            model?: string | null;
+            /**
+             * Format: uuid
+             * @description AiProviderConnection UUID. When omitted on create, platform AI defaults apply. Null clears it.
+             */
+            aiConnectionId?: string | null;
+            /** @description App Connection UUIDs the agent may use for tools. */
+            connectionIds?: string[];
+            /** @description Workflow UUIDs the agent may run (AgentWorkflow links). */
+            workflowIds?: string[];
+            /** @description Workflows the agent may run, each by slug or id. Combined with workflowIds when both are sent. */
+            workflows?: components["schemas"]["AgentSlugOrIdDto"][];
+            /** @description Sub-agents, each by slug or id. */
+            agents?: components["schemas"]["AgentSlugOrIdDto"][];
+            /** @description Knowledge item UUIDs attached to the agent. */
+            knowledgeIds?: string[];
+            /** @description Variable UUIDs attached to the agent. */
+            variableIds?: string[];
+            /** @description Object UUIDs attached to the agent. */
+            objectIds?: string[];
+            /** @description Object type UUIDs attached to the agent. */
+            objectTypeIds?: string[];
+            /** @description A2A agent UUIDs attached to the agent. */
+            a2aAgentIds?: string[];
+            /** @description MCP servers pinned on the agent. */
+            mcpServers?: components["schemas"]["UpsertAgentMcpServerDto"][];
+            /** @description Catalogue action tools. A tool key is kept across pushes. */
+            tools?: components["schemas"]["UpsertAgentToolDto"][];
+            /** @description Agent settings. Omitted keys are left unchanged on update. */
+            settings?: components["schemas"]["UpsertAgentSettingsDto"];
+            /**
+             * @description How code owns this agent. Defaults to generated on this endpoint.
+             * @enum {string}
+             */
+            codeSource?: "synced" | "generated";
+            /** @description Revision from the last pull. Required when updating an agent that is not a generated redeploy, unless force is set. */
+            baseRevision?: string;
+            /** @description Overwrite even when baseRevision is missing or stale. */
+            force?: boolean;
+        };
+        AgentUpsertResponseDto: {
+            /**
+             * @description Agent ID (UUID)
+             * @example 4f7c9d2e-8a1b-4c3d-9e5f-6a7b8c9d0e1f
+             */
+            id: string;
+            /**
+             * @description Agent name
+             * @example Invoice Triage Agent
+             */
+            name: string;
+            /** @description Stable workspace-scoped slug for CLI / code deploy upserts. Included when `expansion=slug` is requested. */
+            slug?: string | null;
+            /**
+             * @description Where this agent is defined. Taken from the request, or generated when omitted.
+             * @enum {string}
+             */
+            codeSource?: "none" | "synced" | "generated";
+            /**
+             * @description Sync state against the definitions folder. Included when `expansion=codeSyncStatus` is requested.
+             * @enum {string}
+             */
+            codeSyncStatus?: "none" | "in_sync" | "changed_in_ui" | "locked";
+            /** @description ID of the AI provider connection assigned to the agent. Always included. Null when the agent falls back to the workspace default connection. */
+            FK_aiConnectionId: string | null;
+            /** @description Agent description. Included when `expansion=description` is requested. */
+            description?: string | null;
+            /** @description Public URL of the agent profile image. Included when `expansion=profileImageUrl` is requested. */
+            profileImageUrl?: string | null;
+            /**
+             * Format: date-time
+             * @description Creation timestamp. Included when `expansion=createdAt` is requested.
+             */
+            createdAt?: string;
+            /**
+             * Format: date-time
+             * @description Last update timestamp. Included when `expansion=updatedAt` is requested.
+             */
+            updatedAt?: string;
+            /** @description System instructions authored for the agent. Included when `expansion=instructions` is requested. */
+            instructions?: string | null;
+            /**
+             * @description Model temperature. Included when `expansion=temperature` is requested.
+             * @example 1
+             */
+            temperature?: number;
+            /** @description Maximum output tokens per turn. Included when `expansion=maxOutputTokens` is requested. */
+            maxOutputTokens?: number | null;
+            /**
+             * @description Top-p sampling. Included when `expansion=topP` is requested.
+             * @example 1
+             */
+            topP?: number;
+            /**
+             * @description Frequency penalty. Included when `expansion=frequencyPenalty` is requested.
+             * @example 0
+             */
+            frequencyPenalty?: number;
+            /**
+             * @description Presence penalty. Included when `expansion=presencePenalty` is requested.
+             * @example 0
+             */
+            presencePenalty?: number;
+            /**
+             * @description Maximum retries for a failed model call. Included when `expansion=maxRetries` is requested.
+             * @example 0
+             */
+            maxRetries?: number;
+            /** @description Fixed sampling seed. Included when `expansion=seed` is requested. */
+            seed?: number | null;
+            /**
+             * @description Maximum tool roundtrips per turn. Included when `expansion=maxToolRoundtrips` is requested.
+             * @example 5
+             */
+            maxToolRoundtrips?: number;
+            /**
+             * @description How many previous messages are sent to the model. Included when `expansion=messageLookbackLimit` is requested.
+             * @example 40
+             */
+            messageLookbackLimit?: number;
+            /** @description Configured tool nodes (app actions) for the agent. Included when `expansion=tools` is requested. */
+            tools?: {
+                [key: string]: unknown;
+            }[] | null;
+            /** @description Action IDs of the configured tools. Included when `expansion=toolIds` is requested. */
+            toolIds?: string[];
+            /** @description Instructions used when auto-naming new tasks. Included when `expansion=taskNamingInstructions` is requested. */
+            taskNamingInstructions?: string | null;
+            /** @description IDs of enabled provider built-in tools. Included when `expansion=enabledBuiltInTools` is requested. */
+            enabledBuiltInTools?: string[];
+            /** @description IDs of enabled platform tools. Included when `expansion=enabledPlatformTools` is requested. */
+            enabledPlatformTools?: string[];
+            /** @description Whether dynamic workflow-app action discovery is enabled. Included when `expansion=dynamicActionDiscoveryEnabled` is requested. */
+            dynamicActionDiscoveryEnabled?: boolean;
+            /** @description Whether dynamic MCP server discovery is enabled. Included when `expansion=dynamicMcpDiscoveryEnabled` is requested. */
+            dynamicMcpDiscoveryEnabled?: boolean;
+            /** @description Whether the agent maintains its own instructions. Included when `expansion=dynamicSelfInstructionsEnabled` is requested. */
+            dynamicSelfInstructionsEnabled?: boolean;
+            /** @description Whether long-term memory is enabled. Included when `expansion=memoryEnabled` is requested. */
+            memoryEnabled?: boolean;
+            /** @description Whether runtime planning tools are enabled. Included when `expansion=enablePlanning` is requested. */
+            enablePlanning?: boolean;
+            /** @description Whether oversized tool-result offload is enabled. Included when `expansion=enableToolResultOffload` is requested. */
+            enableToolResultOffload?: boolean;
+            /** @description Byte threshold for tool-result offload. Included when `expansion=toolResultOffloadThresholdBytes` is requested. */
+            toolResultOffloadThresholdBytes?: number;
+            /** @description Whether long-horizon mode is enabled. Included when `expansion=longHorizonMode` is requested. */
+            longHorizonMode?: boolean;
+            /** @description prepareStep safety-net policy ids. Included when `expansion=enabledToolPolicies` is requested. */
+            enabledToolPolicies?: string[];
+            /** @description Per-tool force overrides. Included when `expansion=forcedTools` is requested. */
+            forcedTools?: string[];
+            /** @description When true with planning, gate heavy tools until plan approval. Included when `expansion=requirePlanApproval` is requested. */
+            requirePlanApproval?: boolean;
+            /** @description Optional elevated max steps for long-horizon mode. Included when `expansion=longHorizonMaxSteps` is requested. */
+            longHorizonMaxSteps?: number | null;
+            /** @description Optional max tokens per run hint for long-horizon mode. Included when `expansion=longHorizonMaxTokensPerRun` is requested. */
+            longHorizonMaxTokensPerRun?: number | null;
+            /**
+             * @description Memory partitioning scope. Included when `expansion=memoryScope` is requested.
+             * @enum {string}
+             */
+            memoryScope?: "PER_USER" | "PER_AGENT" | "PER_USER_PER_AGENT";
+            /**
+             * @description Days memories are retained. Included when `expansion=memoryRetentionDays` is requested.
+             * @example 90
+             */
+            memoryRetentionDays?: number;
+            /** @description Suggested prompts shown to users starting a conversation. Included when `expansion=suggestedPrompts` is requested. */
+            suggestedPrompts?: string[];
+            /**
+             * Format: date-time
+             * @description When builder setup was completed (the first-time wizard, or a code deploy). Included when `expansion=builderSetupCompletedAt` is requested.
+             */
+            builderSetupCompletedAt?: string | null;
+            /** @description Saved canvas node positions for the agent builder. Included when `expansion=builderCanvasPositions` is requested. */
+            builderCanvasPositions?: {
+                [key: string]: unknown;
+            } | null;
+            /** @description Selected model ID within the AI provider connection. Included when `expansion=selectedModelId` is requested. */
+            selectedModelId?: string | null;
+            /** @description Assigned AI provider connection. Included when `expansion=aiConnection` is requested. */
+            aiConnection?: {
+                id?: string;
+                name?: string;
+                providerConfig?: {
+                    id?: string;
+                    providerSlug?: string;
+                };
+            } | null;
+            /** @description Knowledge notebooks attached to the agent. Included when `expansion=knowledge` is requested. */
+            agentKnowledge?: {
+                id?: string;
+                knowledge?: {
+                    id?: string;
+                    name?: string;
+                };
+            }[];
+            /** @description Object types attached to the agent. Included when `expansion=objectTypes` is requested. */
+            agentObjectTypes?: {
+                id?: string;
+                scope?: string;
+                objectType?: {
+                    id?: string;
+                    name?: string;
+                    slug?: string;
+                    icon?: string | null;
+                    color?: string | null;
+                };
+            }[];
+            /** @description Objects attached to the agent. Included when `expansion=objects` is requested. */
+            agentObjects?: {
+                id?: string;
+                scope?: string;
+                object?: {
+                    id?: string;
+                    name?: string;
+                    state?: string;
+                    objectType?: {
+                        id?: string;
+                        name?: string;
+                        slug?: string;
+                        icon?: string | null;
+                        color?: string | null;
+                    };
+                };
+            }[];
+            /** @description App connections available to the agent. Included when `expansion=connections` is requested. */
+            connections?: {
+                id?: string;
+                name?: string;
+            }[];
+            /** @description Variables attached to the agent. Included when `expansion=variables` is requested. */
+            agentVariables?: {
+                id?: string;
+                variable?: {
+                    id?: string;
+                    name?: string;
+                };
+            }[];
+            /** @description Workflows the agent can trigger. Included when `expansion=workflows` is requested. */
+            agentWorkflows?: {
+                id?: string;
+                workflow?: {
+                    id?: string;
+                    name?: string;
+                };
+            }[];
+            /** @description Sub-agent links for the agent. Included when `expansion=subAgents` is requested. */
+            agentSubAgents?: {
+                id?: string;
+                subagent?: {
+                    id?: string;
+                    name?: string;
+                };
+                parentAgent?: {
+                    id?: string;
+                    name?: string;
+                };
+            }[];
+            /** @description MCP servers attached to the agent, with per-tool overrides. Included when `expansion=mcpServers` is requested. */
+            agentMcpServers?: {
+                id?: string;
+                mcpServer?: {
+                    id?: string;
+                    slug?: string;
+                    name?: string;
+                    provider?: string;
+                    logoUrl?: string | null;
+                    description?: string | null;
+                };
+                toolOverrides?: {
+                    id?: string;
+                    toolName?: string;
+                    enabled?: boolean;
+                    requireApproval?: boolean;
+                }[];
             }[];
-            /** @description The workflow trigger node definition (JSON). Included when `expansion=triggerNode` is requested. */
-            triggerNode?: {
-                [key: string]: unknown;
+            /** @description A2A (agent-to-agent) endpoints attached to the agent. Included when `expansion=a2aAgents` is requested. */
+            agentA2aAgents?: {
+                id?: string;
+                a2aAgent?: {
+                    id?: string;
+                    slug?: string;
+                    name?: string;
+                    logoUrl?: string | null;
+                    description?: string | null;
+                    authType?: string;
+                };
+            }[];
+            /** @description Web access configuration. Included when `expansion=webAccess` is requested. */
+            agentWebAccess?: {
+                service?: string;
+                webSearchEnabled?: boolean;
+                websiteAccessEnabled?: boolean;
             } | null;
-            /** @description IDs of the triggers and actions used by the workflow. Included when `expansion=triggerAndActionIds` is requested. */
-            triggerAndActionIds?: string[];
-            /** @description IDs of sub-workflows referenced by the workflow. Included when `expansion=subWorkflowIds` is requested. Only returned by GET /workflows/{workflowId}. */
-            subWorkflowIds?: string[];
-            /** @description IDs of agents referenced by the workflow. Included when `expansion=agentIds` is requested. Only returned by GET /workflows/{workflowId}. */
-            agentIds?: string[];
-            /** @description Internal polling trigger storage value. Included when `expansion=pollStorage` is requested. */
-            pollStorage?: string | null;
-            /**
-             * Format: date-time
-             * @description Timestamp of the next scheduled execution, if the workflow runs on a schedule. Included when `expansion=nextScheduledExecution` is requested.
-             */
-            nextScheduledExecution?: string | null;
-            /**
-             * @description Editor orientation of the workflow canvas. Included when `expansion=orientation` is requested.
-             * @enum {string}
-             */
-            workflowOrientation?: "HORIZONTAL" | "VERTICAL";
-            /** @description AI provider connection used by the workflow builder chat. Always returned on GET /workflows/{workflowId}. */
-            aiConnectionId?: string | null;
-            /** @description Selected model ID within the AI provider connection for workflow builder chat. Always returned on GET /workflows/{workflowId}. */
-            selectedModelId?: string | null;
-        };
-        UpsertAgentToolDto: {
-            /** @description Workflow app id (catalogue slug). */
-            appId: string;
-            /** @description Catalogue action id. */
-            actionId: string;
-            /** @description Connection instance UUID pre-bound on the tool. */
-            connectionId?: string;
-            /** @description Tool display name for the model. */
-            name?: string;
-            /** @description Tool description shown to the model. */
-            description?: string;
-            /** @description Pre-filled tool config (fields left empty are filled by the model). */
-            input?: {
+            /** @description Phone access configuration. Included when `expansion=phoneAccess` is requested. */
+            agentPhoneAccess?: {
+                service?: string;
+                outboundCallsEnabled?: boolean;
+                inboundCallsEnabled?: boolean;
+            } | null;
+            /** @description sha256 hex of the stored agent definition. */
+            revision: string;
+            /** @description Stored agent definition in the file shape, including settings, tools, and linked resources. */
+            definition: {
                 [key: string]: unknown;
             };
         };
-        UpsertAgentBySlugDto: {
-            /**
-             * @description Stable workspace-scoped slug (lowercase, digits, hyphens). Used as the upsert key.
-             * @example support-triage
-             */
-            slug: string;
-            /** @description Display name. Defaults to the slug when omitted. */
-            name?: string;
-            description?: string;
-            /** @description System instructions / prompt for the agent. */
-            instructions: string;
-            /** @description Catalogue model id enabled on the AI connection. Example: `deepseek-ai/DeepSeek-V4-Pro`. Discover ids with GET /api/ai-connections. */
-            model: string;
-            /** @description AiProviderConnection UUID. When omitted, platform AI defaults apply. */
-            aiConnectionId?: string;
-            /** @description App Connection UUIDs the agent may use for tools. */
-            connectionIds?: string[];
-            /** @description Workflow UUIDs the agent may run (AgentWorkflow links). */
-            workflowIds?: string[];
-            /** @description Catalogue action tools (WorkflowNodeForRunner-shaped). */
-            tools?: components["schemas"]["UpsertAgentToolDto"][];
-            /** @description Marks the row as managed by code (CLI / SDK). Defaults to true on this endpoint. */
-            managedByCode?: boolean;
-        };
         AgentResponseDto: {
             /**
              * @description Agent ID (UUID)
@@ -1008,8 +1601,16 @@ interface components {
             name: string;
             /** @description Stable workspace-scoped slug for CLI / code deploy upserts. Included when `expansion=slug` is requested. */
             slug?: string | null;
-            /** @description True when last written by code (CLI / SDK). Included when `expansion=managedByCode` is requested. */
-            managedByCode?: boolean;
+            /**
+             * @description Where this agent is defined. Included when `expansion=codeSource` is requested.
+             * @enum {string}
+             */
+            codeSource?: "none" | "synced" | "generated";
+            /**
+             * @description Sync state against the definitions folder. Included when `expansion=codeSyncStatus` is requested.
+             * @enum {string}
+             */
+            codeSyncStatus?: "none" | "in_sync" | "changed_in_ui" | "locked";
             /** @description ID of the AI provider connection assigned to the agent. Always included. Null when the agent falls back to the workspace default connection. */
             FK_aiConnectionId: string | null;
             /** @description Agent description. Included when `expansion=description` is requested. */
@@ -1119,7 +1720,7 @@ interface components {
             suggestedPrompts?: string[];
             /**
              * Format: date-time
-             * @description When the first-time builder setup wizard was completed. Included when `expansion=builderSetupCompletedAt` is requested.
+             * @description When builder setup was completed (the first-time wizard, or a code deploy). Included when `expansion=builderSetupCompletedAt` is requested.
              */
             builderSetupCompletedAt?: string | null;
             /** @description Saved canvas node positions for the agent builder. Included when `expansion=builderCanvasPositions` is requested. */
@@ -1250,6 +1851,25 @@ interface components {
                 inboundCallsEnabled?: boolean;
             } | null;
         };
+        AgentDefinitionResponseDto: {
+            /** @description Agent ID (UUID). */
+            id: string;
+            /** @description Workspace-scoped slug. */
+            slug: string;
+            /** @description Workspace that owns the agent. */
+            workspaceId: string;
+            /**
+             * @description Where this agent is defined.
+             * @enum {string}
+             */
+            codeSource: "none" | "synced" | "generated";
+            /** @description sha256 hex of the canonical agent definition. */
+            revision: string;
+            /** @description Agent definition in the file shape (kind, slug, settings, tools, and linked resources). */
+            definition: {
+                [key: string]: unknown;
+            };
+        };
         WorkflowAppResponseDto: {
             /** @description App ID, e.g. `gmail`. Matches the appId used in workflow execution steps. */
             id: string;
@@ -2121,32 +2741,6 @@ interface components {
             /** Format: date-time */
             updatedAt: string;
         };
-        PublicAiModelResponseDto: {
-            /** @description Catalogue model id passed to agent deploy as `model`. Example: `deepseek-ai/DeepSeek-V4-Pro`. */
-            id: string;
-            /** @description Display name. */
-            name: string;
-            /** @description True when this is the model used if an agent deploy omits `model` on this connection. */
-            isDefault: boolean;
-            /** @description Whether the model can call tools. */
-            supportsTools: boolean;
-            /** @description Whether the model accepts image input. */
-            supportsVision: boolean;
-            /** @description Whether the model exposes a reasoning mode. */
-            supportsReasoning: boolean;
-        };
-        PublicAiConnectionResponseDto: {
-            /** @description AiProviderConnection UUID. Pass as `aiConnectionId` / `defineAiConnection({ id })` when this connection is not the default. */
-            id: string;
-            /** @description Connection display name. Example: `Lunnoa LLMs`. */
-            name: string;
-            /** @description Provider slug. Example: `featherless` or `openai`. */
-            provider: string;
-            /** @description True for the connection used when an agent deploy omits `aiConnectionId`. */
-            isDefault: boolean;
-            /** @description Models this connection accepts. Inactive models are omitted. */
-            models: components["schemas"]["PublicAiModelResponseDto"][];
-        };
         ConnectionWorkspaceDto: {
             /** @description Workspace ID. */
             id: string;
@@ -2268,6 +2862,20 @@ interface components {
             activeStreamId?: string;
             /** @description Durable outcome of the most recent agent-turn run. Omitted when the task has never run. */
             latestRun?: components["schemas"]["TaskLatestRunDto"];
+            /** @description Runtime todo/plan for this task when the agent has planning enabled (CTO-258). Always returned from the single-task endpoints. */
+            runtimePlan?: {
+                id?: string;
+                content?: string;
+                /** @enum {string} */
+                status?: "pending" | "in_progress" | "completed" | "cancelled";
+                /** Format: date-time */
+                updatedAt?: string;
+            }[] | null;
+            /**
+             * Format: date-time
+             * @description When the current runtime plan was approved (HITL). Null until approved or after the plan is rewritten.
+             */
+            planApprovedAt?: string | null;
             /** @description Task description. Included when `expansion=description` is requested. */
             description?: string | null;
             /**
@@ -2379,7 +2987,7 @@ interface components {
                 [key: string]: unknown;
             }[];
             /**
-             * @description Agent chat mode
+             * @description Loop to run. Omit or send `preview` for an app, public chat, or workflow turn (10 model rounds). `builder` is the agent-editor interview and stops after 4 rounds.
              * @example preview
              * @enum {string}
              */
@@ -2420,14 +3028,37 @@ interface components {
  */
 
 type Schemas = components['schemas'];
+/** Where an agent or workflow definition was last written from. */
+type CodeSource = 'none' | 'synced' | 'generated';
+/** Computed on read. `locked` means the UI cannot edit the definition. */
+type CodeSyncStatus = 'none' | 'in_sync' | 'changed_in_ui' | 'locked';
+interface CodeSyncContext {
+    workspaceId: string;
+    lockCodeSyncedResources: boolean;
+}
+/** `GET /api/{agents|workflows}/slug/:slug/definition`. */
+interface CodeDefinitionResponse<TDefinition> {
+    id: string;
+    slug: string;
+    workspaceId: string;
+    codeSource: CodeSource;
+    revision: string;
+    definition: TDefinition;
+}
 type EnabledFeatures = Schemas['EnabledFeaturesResponseDto'];
-type Agent = Schemas['AgentResponseDto'];
+type Agent = Omit<Schemas['AgentResponseDto'], 'managedByCode'> & {
+    codeSource?: CodeSource;
+    codeSyncStatus?: CodeSyncStatus;
+};
 type Task = Schemas['TaskResponseDto'];
 type TaskListItem = Schemas['TaskListItemResponseDto'];
 type CreateTaskInput = Schemas['CreateTaskDto'];
 type UpdateTaskInput = Schemas['UpdateTaskDto'];
 type DeletedTask = Schemas['DeletedTaskResponseDto'];
-type Workflow = Schemas['WorkflowResponseDto'];
+type Workflow = Omit<Schemas['WorkflowResponseDto'], 'managedByCode'> & {
+    codeSource?: CodeSource;
+    codeSyncStatus?: CodeSyncStatus;
+};
 type Execution = Schemas['ExecutionResponseDto'];
 type ExecutionPathStep = Schemas['ExecutionPathStepDto'];
 type ExecuteWorkflowResult = Schemas['ExecuteWorkflowResponseDto'];
@@ -2685,12 +3316,189 @@ declare class ActionsResource {
     get(appId: string, actionId: string): Promise<Record<string, unknown> | undefined>;
 }
 
+/**
+ * On-disk agent and workflow definitions (the pull/push file shape).
+ * `$schema` is allowed on input and stripped; the CLI adds it when writing.
+ */
+interface RetrySettings {
+    enabled: boolean;
+    maxAttempts: number;
+    delaySeconds: number;
+}
+interface ContinueOnFailureSettings {
+    enabled: boolean;
+}
+/** Every key is present on files the API returns. Hand-written files may omit unset keys. */
+interface AgentFileSettings {
+    temperature?: number;
+    topP?: number;
+    maxOutputTokens?: number | null;
+    frequencyPenalty?: number;
+    presencePenalty?: number;
+    seed?: number | null;
+    maxRetries?: number;
+    maxToolRoundtrips?: number;
+    messageLookbackLimit?: number;
+    taskNamingInstructions?: string | null;
+    enabledBuiltInTools?: string[];
+    enabledPlatformTools?: string[];
+    enabledToolPolicies?: string[];
+    forcedTools?: unknown;
+    suggestedPrompts?: string[];
+    dynamicActionDiscoveryEnabled?: boolean;
+    dynamicMcpDiscoveryEnabled?: boolean;
+    dynamicSelfInstructionsEnabled?: boolean;
+    memoryEnabled?: boolean;
+    memoryScope?: string;
+    memoryRetentionDays?: number;
+    enablePlanning?: boolean;
+    requirePlanApproval?: boolean;
+    enableToolResultOffload?: boolean;
+    toolResultOffloadThresholdBytes?: number;
+    longHorizonMode?: boolean;
+    longHorizonMaxSteps?: number | null;
+    longHorizonMaxTokensPerRun?: number | null;
+    piiRoutingMode?: string;
+    piiFallbackConnectionId?: string | null;
+    piiFallbackModelId?: string | null;
+    webAccess?: boolean | null;
+    phoneAccess?: boolean | null;
+}
+interface AgentFileTool {
+    key: string;
+    /** Catalogue action id. */
+    id: string;
+    appId?: string;
+    connection?: {
+        id: string;
+    };
+    name: string;
+    description?: string;
+    input: Record<string, unknown>;
+}
+interface AgentLinkBySlug {
+    slug: string;
+}
+interface AgentLinkById {
+    id: string;
+}
+type AgentSlugOrId = AgentLinkBySlug | AgentLinkById;
+interface AgentFileDefinition {
+    kind: 'agent';
+    slug: string;
+    name: string;
+    description?: string;
+    model?: string;
+    aiConnection?: {
+        id: string;
+    };
+    /**
+     * API and TypeScript use a string. Files on disk point at
+     * `<slug>.instructions.md`; only the CLI reads that file.
+     */
+    instructions: string | {
+        file: string;
+    };
+    settings: AgentFileSettings;
+    tools: AgentFileTool[];
+    workflows: AgentSlugOrId[];
+    agents: AgentSlugOrId[];
+    connections: AgentLinkById[];
+    knowledge: AgentLinkById[];
+    variables: AgentLinkById[];
+    objects: AgentLinkById[];
+    objectTypes: AgentLinkById[];
+    mcpServers: Array<{
+        id: string;
+        connectionId?: string;
+    }>;
+    a2aAgents: AgentLinkById[];
+}
+interface WorkflowUseFile {
+    id: string;
+    appId?: string;
+    connection?: {
+        id: string;
+    };
+}
+interface WorkflowTriggerFile {
+    id: string;
+    appId?: string;
+    connection?: {
+        id: string;
+    };
+    input?: Record<string, unknown>;
+    inputs?: Array<Record<string, unknown>>;
+    name: string;
+    description?: string;
+}
+interface WorkflowStepFile {
+    key: string;
+    name: string;
+    description?: string;
+    use: WorkflowUseFile;
+    input: Record<string, unknown>;
+    retrySettings?: RetrySettings;
+    continueOnFailure?: ContinueOnFailureSettings;
+    paths?: Array<{
+        label: string;
+        when?: Array<Array<{
+            field: string;
+            condition: string;
+            value?: string;
+        }>>;
+        steps: WorkflowStepFile[];
+    }>;
+}
+interface WorkflowStepsFileDefinition {
+    kind: 'workflow';
+    format: 'steps';
+    slug: string;
+    name: string;
+    description?: string;
+    trigger: WorkflowTriggerFile;
+    steps: WorkflowStepFile[];
+}
+interface WorkflowGraphNode {
+    id?: string;
+    key: string;
+    nodeType: 'trigger' | 'action';
+    appId: string;
+    actionId?: string;
+    triggerId?: string;
+    name: string;
+    description?: string;
+    value: Record<string, unknown>;
+    retrySettings?: Record<string, unknown>;
+    continueOnFailure?: Record<string, unknown>;
+    [other: string]: unknown;
+}
+interface WorkflowGraphEdge {
+    id?: string;
+    source: string;
+    target: string;
+    sourceHandle?: string;
+    targetHandle?: string;
+    type?: string;
+}
+interface WorkflowGraphFileDefinition {
+    kind: 'workflow';
+    format: 'graph';
+    slug: string;
+    name: string;
+    description?: string;
+    nodes: WorkflowGraphNode[];
+    edges: WorkflowGraphEdge[];
+}
+type WorkflowFileDefinition = WorkflowStepsFileDefinition | WorkflowGraphFileDefinition;
+
 /**
  * Pure typed definition factories for local workflow/agent authoring.
  * These do not call the network. Deploy with the CLI; run ad-hoc with `runs.start`.
  *
  * Not the same as `@lunnoa/toolkit` `createAction` / `createApp` (in-platform apps).
  */
+
 declare const DEFINE_KINDS: {
     readonly connection: "connection";
     readonly aiConnection: "aiConnection";
@@ -2778,6 +3586,41 @@ interface WorkflowStepDefinition {
     /** Per-step input overrides. Values may contain `ref.trigger` / `ref.step`. */
     input?: Record<string, unknown>;
     name?: string;
+    description?: string;
+    retrySettings?: {
+        enabled: boolean;
+        maxAttempts: number;
+        delaySeconds: number;
+    };
+    continueOnFailure?: {
+        enabled: boolean;
+    };
+    /**
+     * Branches after this step. Only on Conditional Paths, Manually Decide Path,
+     * or Request Approval (approved path first, then rejected), and only on the
+     * last step of a list. Put later steps inside each path.
+     */
+    paths?: WorkflowPathDefinition[];
+}
+/** Conditions Conditional Paths evaluates (same list as the builder). */
+declare const PATH_CONDITIONS: readonly ["contains", "does_not_contain", "equals", "does_not_equal", "exists", "does_not_exist", "starts_with", "ends_with", "is_empty", "is_not_empty", "comes_before", "comes_after", "is_in_the_past", "is_in_the_future", "is_true", "is_false", "is_truthy", "is_falsey", "is_greater_than", "is_less_than", "is_greater_than_or_equal_to", "is_less_than_or_equal_to", "matches_regex", "does_not_match_regex"];
+type PathConditionType = (typeof PATH_CONDITIONS)[number];
+interface PathCondition {
+    /** One reference: `ref.trigger(...)` or `ref.step(...)`. */
+    field: string;
+    condition: PathConditionType;
+    /** Compared as text. Omit for exists / is_empty / is_true and similar. */
+    value?: string;
+}
+interface WorkflowPathDefinition {
+    /** Unique on its step. On Request Approval use `Approved` / `Rejected`. */
+    label: string;
+    /**
+     * Conditional Paths only. Groups are OR-ed, conditions in a group AND-ed.
+     * Omit to always take this path.
+     */
+    when?: PathCondition[][];
+    steps: WorkflowStepDefinition[];
 }
 interface WorkflowDefinition {
     kind: typeof DEFINE_KINDS.workflow;
@@ -2791,7 +3634,7 @@ interface WorkflowDefinition {
      * `runs.start` ignores this and runs the steps only.
      */
     trigger?: TriggerDefinition;
-    /** Linear steps (v1; no branches). */
+    /** Steps in order. The last step may branch with `paths`. */
     steps: WorkflowStepDefinition[];
 }
 type AgentToolDefinition = ActionDefinition | WorkflowDefinition | {
@@ -2836,6 +3679,7 @@ interface EntityTypeDefinition {
 }
 
 interface UpsertAgentToolInput {
+    key?: string;
     appId: string;
     actionId: string;
     connectionId?: string;
@@ -2846,14 +3690,37 @@ interface UpsertAgentToolInput {
 interface UpsertAgentBySlugInput {
     slug: string;
     name?: string;
-    description?: string;
+    /** Null clears a description that was removed from the definition file. */
+    description?: string | null;
     instructions: string;
-    model: string;
+    /** Null clears a model that was removed from the definition file. */
+    model?: string | null;
     aiConnectionId?: string;
     connectionIds?: string[];
     workflowIds?: string[];
     tools?: UpsertAgentToolInput[];
-    managedByCode?: boolean;
+    settings?: Partial<AgentFileSettings>;
+    workflows?: AgentSlugOrId[];
+    agents?: AgentSlugOrId[];
+    knowledgeIds?: string[];
+    variableIds?: string[];
+    objectIds?: string[];
+    objectTypeIds?: string[];
+    mcpServers?: Array<{
+        id: string;
+        connectionId?: string;
+    }>;
+    a2aAgentIds?: string[];
+    /** `generated` for TypeScript deploys, `synced` for definition files. */
+    codeSource?: Extract<CodeSource, 'synced' | 'generated'>;
+    baseRevision?: string;
+    force?: boolean;
+}
+interface AgentUpsertOptions {
+    workflowIds?: string[];
+    codeSource?: Extract<CodeSource, 'synced' | 'generated'>;
+    baseRevision?: string;
+    force?: boolean;
 }
 declare class AgentsResource {
     private readonly http;
@@ -2862,13 +3729,13 @@ declare class AgentsResource {
     list(options?: ListQueryOptions): Promise<Agent[]>;
     /** Returns a single agent. */
     get(agentId: string, options?: Pick<ListQueryOptions, 'expansion'>): Promise<Agent>;
+    /** Exported definition for `lunnoa/agents/<slug>.json`. */
+    getDefinition(slug: string): Promise<CodeDefinitionResponse<AgentFileDefinition>>;
     /**
      * Upsert an agent by slug inside the workspace on the API key.
      * Prefer the CLI (`npx @lunnoa/client agents deploy`) for happy-path deploy.
      */
-    upsertBySlug(body: UpsertAgentBySlugInput | AgentDefinition, options?: {
-        workflowIds?: string[];
-    }): Promise<Agent>;
+    upsertBySlug(body: UpsertAgentBySlugInput | AgentDefinition | AgentFileDefinition, options?: AgentUpsertOptions): Promise<Agent & CodeDefinitionResponse<AgentFileDefinition>>;
 }
 
 /**
@@ -3555,6 +4422,13 @@ declare class VariablesResource {
     delete(variableId: string): Promise<boolean>;
 }
 
+declare class CodeSyncResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Workspace id and whether synced resources are locked in the UI. */
+    context(): Promise<CodeSyncContext>;
+}
+
 interface UpsertWorkflowStepInput {
     /** Name later steps use in `={{step:<key>,path}}`. Keeps the node id stable. */
     key?: string;
@@ -3564,6 +4438,21 @@ interface UpsertWorkflowStepInput {
     input?: Record<string, unknown>;
     name?: string;
     description?: string;
+    retrySettings?: {
+        enabled: boolean;
+        maxAttempts: number;
+        delaySeconds: number;
+    };
+    continueOnFailure?: {
+        enabled: boolean;
+    };
+    /** Branches after this step (last step of a list only). */
+    paths?: UpsertWorkflowPathInput[];
+}
+interface UpsertWorkflowPathInput {
+    label: string;
+    when?: WorkflowPathDefinition['when'];
+    steps: UpsertWorkflowStepInput[];
 }
 interface UpsertWorkflowTriggerInput {
     triggerId: string;
@@ -3576,15 +4465,30 @@ interface UpsertWorkflowTriggerInput {
     name?: string;
     description?: string;
 }
+interface UpsertWorkflowGraphInput {
+    nodes: WorkflowGraphFileDefinition['nodes'];
+    edges: WorkflowGraphFileDefinition['edges'];
+}
 interface UpsertWorkflowBySlugInput {
     slug: string;
     name?: string;
-    description?: string;
+    /** Null clears a description that was removed from the definition file. */
+    description?: string | null;
     isActive?: boolean;
     /** Omit for Manually Run with no input fields. */
     trigger?: UpsertWorkflowTriggerInput;
-    steps: UpsertWorkflowStepInput[];
-    managedByCode?: boolean;
+    steps?: UpsertWorkflowStepInput[];
+    /** Lossless graph. Not sent together with `trigger` / `steps`. */
+    graph?: UpsertWorkflowGraphInput;
+    /** `generated` for TypeScript deploys, `synced` for definition files. */
+    codeSource?: Extract<CodeSource, 'synced' | 'generated'>;
+    baseRevision?: string;
+    force?: boolean;
+}
+interface WorkflowUpsertOptions {
+    codeSource?: Extract<CodeSource, 'synced' | 'generated'>;
+    baseRevision?: string;
+    force?: boolean;
 }
 declare class WorkflowsResource {
     private readonly http;
@@ -3597,11 +4501,13 @@ declare class WorkflowsResource {
      * the manual trigger's custom input field definitions.
      */
     get(workflowId: string, options?: Pick<ListQueryOptions, 'expansion'>): Promise<Workflow>;
+    /** Exported definition for `lunnoa/workflows/<slug>.json`. */
+    getDefinition(slug: string): Promise<CodeDefinitionResponse<WorkflowFileDefinition>>;
     /**
      * Upsert a workflow by slug inside the workspace on the API key.
      * Prefer the CLI (`npx @lunnoa/client workflows deploy`) for happy-path deploy.
      */
-    upsertBySlug(body: UpsertWorkflowBySlugInput | WorkflowDefinition): Promise<Workflow>;
+    upsertBySlug(body: UpsertWorkflowBySlugInput | WorkflowDefinition | WorkflowFileDefinition, options?: WorkflowUpsertOptions): Promise<Workflow & CodeDefinitionResponse<WorkflowFileDefinition>>;
     /**
      * Starts a new execution of the workflow with the given trigger inputs.
      * Returns immediately with the execution ID.
@@ -3669,6 +4575,8 @@ declare class LunnoaClient {
     readonly aiConnections: AiConnectionsResource;
     readonly workflowApps: WorkflowAppsResource;
     readonly discovery: DiscoveryResource;
+    /** Workspace id for the definitions lock, and the code-sync lock flag. */
+    readonly codeSync: CodeSyncResource;
     constructor(options: LunnoaClientOptions);
 }