@ai-matrx/chat 0.1.77 → 0.2.0

package/dist/agents/types/instance.types.d.ts

@@ -0,0 +1,1227 @@
+/**
+ * Execution Instance Types
+ *
+ * Each execution context is keyed by a conversationId — a plain UUID that
+ * doubles as the server-side conversation thread identifier. The client
+ * generates the ID upfront and sends it to the server on the first request.
+ *
+ * Key principle: instances NEVER write back to agent source slices.
+ * They read from them (for defaults) and maintain their own override layers.
+ * Multiple conversations for the same agent coexist with zero shared mutable state.
+ */
+import type { AgentType, VariableResourceContextConfig } from "./agent-definition.types.js";
+import type { ContextObjectType, LLMParams, SystemInstruction } from "./agent-api-types.js";
+import type { ValueMappingMap } from "../../surfaces/types.js";
+import type { AnyMandateKey } from "@ai-matrx/agents/mandates";
+import type { UserInputPart } from "./request.types.js";
+import type { MessagePart } from "@ai-matrx/agents/generated/stream-events";
+import type { components } from "@ai-matrx/agents/generated/api-types";
+import type { ResultDisplayMode } from "../utils/run-ui-utils.js";
+import type { VariablesPanelStyle } from "../components/inputs/variable-input-variations/variable-input-options.js";
+import type { ServerOperationState } from "../runtime-reconnect/types.js";
+import { SOURCE_APPS, SOURCE_FEATURES, SOURCE_FEATURE_PATTERNS, isSourceApp, isSourceFeature, type SourceApp, type SourceFeature } from "@ai-matrx/agents/generated/source-attribution";
+export type { UserRequestResult as CompletionStats } from "@ai-matrx/agents/generated/stream-events";
+export type { AggregatedUsageResult, ModelUsageSummary, UsageTotals, TimingStatsResult, ToolCallStatsResult, ToolCallByTool, } from "@ai-matrx/agents/generated/stream-events";
+/**
+ * Durable resource identity carried on a run — the generated API contract's
+ * shape, never a hand-mirrored copy. The server reloads the named row and
+ * derives authoritative org/project/task from it.
+ */
+export type ContextAnchor = components["schemas"]["ContextAnchor"];
+export type InstanceStatus = "draft" | "ready" | "running" | "streaming" | "paused" | "complete" | "error" | "cancelled";
+export type InstanceOrigin = "manual" | "shortcut" | "test" | "sub-agent";
+/**
+ * Conversation provenance — `cx_conversation.source_app` / `source_feature`.
+ *
+ * **Single source of truth:** `@ai-matrx/agents/generated/source-attribution`,
+ * generated from aidream `source_attribution.py` via `pnpm sync-types`.
+ * Do not hand-add feature slugs here. Stamp the product feature that hosts the
+ * run (not chrome like context menus / ProTextarea). FE always stamps
+ * `SOURCE_APP` (`matrx-frontend`).
+ *
+ * UI labels/icons/filters: `features/agents/redux/conversation-history/source-registry.ts`
+ */
+export { SOURCE_APPS, SOURCE_FEATURES, SOURCE_FEATURE_PATTERNS, isSourceApp, isSourceFeature, type SourceApp, type SourceFeature, };
+/** Every matrx-frontend producer stamps this — never invent another app slug. */
+export declare const SOURCE_APP: "matrx-frontend";
+declare const UNREGISTERED_SOURCE_FEATURE: unique symbol;
+export type UnregisteredSourceFeature = string & {
+    readonly [UNREGISTERED_SOURCE_FEATURE]: true;
+};
+export type SourceFeatureValue = SourceFeature | UnregisteredSourceFeature;
+/** Preserve DB fidelity while preventing new producer call sites from inventing strings. */
+export declare function sourceFeatureFromStorage(value: string): SourceFeatureValue;
+declare const UNREGISTERED_SOURCE_APP: unique symbol;
+export type UnregisteredSourceApp = string & {
+    readonly [UNREGISTERED_SOURCE_APP]: true;
+};
+export type SourceAppValue = SourceApp | UnregisteredSourceApp;
+/** Preserve DB fidelity while preventing new producer call sites from inventing strings. */
+export declare function sourceAppFromStorage(value: string): SourceAppValue;
+export type ApiEndpointMode = "agent" | "manual";
+/**
+ * Client attestation of HOW an AI request was triggered — the only provenance
+ * input the client may send. The server DERIVES `origin_class` from witnessed
+ * facts; a body can never carry `origin_class` itself.
+ *
+ *   "user" — a person directly triggered this request (clicked send, submitted
+ *            a form, pressed a button). Server classes it `human`.
+ *   "auto" — client code triggered it automatically (page-load effect, timer,
+ *            auto-refresh, background prefetch, an agent tool driving sends).
+ *            Server classes it `client_auto`.
+ *
+ * Omitting the field makes the server class the request `api` (unattested) —
+ * NOT what we want for real UI traffic, so every execution path stamps one.
+ * Be honest: only paths that genuinely start from a user gesture send "user".
+ */
+export type RequestInitiation = "user" | "auto";
+/**
+ * Conversation lifecycle intent — declared ONCE at creation, never mutated.
+ *
+ *   "continuous" — a durable thread the user keeps adding turns to (chat,
+ *                  scribe, runner, agent-apps, notes…). Must NEVER be split /
+ *                  orphaned. This is the safe default (undefined ⇒ continuous).
+ *   "iterate"    — a disposable "run the same prompt again against a fresh
+ *                  call" surface (builder/tester, Conductor generator,
+ *                  programmatic extraction). Here the auto-clear SPLIT is the
+ *                  whole point: each send mints a fresh historyless id.
+ *
+ * The split gate in `smartExecute` fires only for `"iterate"`; an `autoClear +
+ * surfaceKey` submit on any non-iterate conversation is refused loudly (it
+ * would orphan a durable thread). Derived at creation from
+ * `deriveConversationLifecycle(autoClearConversation, showAutoClearToggle)` —
+ * a surface that enables auto-clear OR merely SHOWS the auto-clear toggle
+ * (letting the user flip it on at runtime) is iterate-capable.
+ */
+export type ConversationLifecycle = "continuous" | "iterate";
+/**
+ * The ONE place the iterate/continuous decision is made. A conversation is
+ * `"iterate"` iff it was created with auto-clear on OR it exposes the auto-clear
+ * toggle (the only runtime path that can turn auto-clear on — see
+ * `InputActionButtons` → `setAutoClearMode`, gated on `showAutoClearToggle`).
+ * Everything else is `"continuous"` — the safe, un-splittable default.
+ */
+export declare function deriveConversationLifecycle(autoClearConversation?: boolean, showAutoClearToggle?: boolean): ConversationLifecycle;
+/**
+ * Conversation record shape.
+ *
+ * Fields above the first block break mirror the existing legacy surface.
+ * Fields below mirror the DB `cx_conversation.Row` + ConversationInvocation
+ * semantics and are populated by Phase 2 of the unification (rehydration +
+ * `launchConversation`). They are typed optional so existing call sites that
+ * only set the original field set continue to compile and behave identically.
+ *
+ * `ConversationRecord` is the forward name for this shape, re-exported by
+ * `features/agents/redux/execution-system/conversations/conversations.slice.ts`.
+ */
+export interface ExecutionInstance {
+    conversationId: string;
+    agentId: string;
+    agentType: AgentType;
+    origin: InstanceOrigin;
+    shortcutId: string | null;
+    /**
+     * The launch declared its inputs (a shortcut, binding or per-launch value
+     * mapping): every turn sends only what it mapped plus always-on values,
+     * never the page (`mapScopeToInstanceWithSurface`, W-31). Stamped by
+     * `launchAgentExecution`; absent = an unmapped run that follows the page.
+     */
+    engineeredInputs?: boolean;
+    status: InstanceStatus;
+    sourceApp: SourceAppValue;
+    sourceFeature: SourceFeatureValue;
+    /**
+     * How this conversation's runs get triggered by default — stamped at
+     * creation (launch option / creation args). Per-send overrides win (a user
+     * typing into an auto-launched conversation is a "user" send). Absent ⇒
+     * the assemblers default to "user" for the interactive send paths.
+     */
+    initiation?: RequestInitiation;
+    /**
+     * The launching SURFACE writes this conversation's result itself (a deck, a
+     * mind map, one merged artifact of a segmented run), so the stream's commit
+     * step and the on-load reconcile must never materialize its assistant turns
+     * into canvas items / feature records — doing so minted one twin deck per
+     * section (live 2026-09-28). Stamped at launch (`surfaceOwnsOutput` launch
+     * option), persisted as `chat.conversation.metadata.surface_owns_output`,
+     * and restored by `loadConversation`, so a reload or resume keeps it. Read
+     * only through `selectConversationSurfaceOwnsOutput`.
+     */
+    surfaceOwnsOutput?: boolean;
+    /** True until the server confirms this conversation ID via X-Conversation-ID header */
+    cacheOnly: boolean;
+    createdAt: string;
+    updatedAt: string;
+    /**
+     * Canonical owner — `cx_conversation.created_by` (trigger-stamped). This is
+     * the field ownership/edit decisions must read. (The old `user_id` column was
+     * dropped from `cx_conversation` in favor of `created_by`.)
+     */
+    createdBy?: string | null;
+    /**
+     * May the signed-in viewer ADD a turn here? The access kernel's answer
+     * (`iam.has_access('conversation', id, 'editor')`), asked by
+     * `loadConversation` when the viewer is not the owner. `undefined` means
+     * the conversation is the viewer's own (or brand new) — a reply is allowed.
+     * `false` = a view-level share: the composer is replaced by an honest
+     * view-only bar (W-65). Read only through `selectViewerCanReply`.
+     */
+    viewerCanReply?: boolean;
+    /** Canonical DB column name for the agent that started this conversation. */
+    initialAgentId?: string | null;
+    /** Agent version that started this conversation (pinned for shortcuts/apps). */
+    initialAgentVersionId?: string | null;
+    /**
+     * THE MANDATE DOOR. When set, this conversation's FIRST turn is POSTed to
+     * `/ai/mandates/{mandateKey}` instead of `/ai/agents/{agentId}` — the server
+     * resolves the principal's binding and decides which agent actually answers.
+     *
+     * `agentId` on a mandate-driven conversation is DISPLAY IDENTITY ONLY (the
+     * name/avatar the surface paints before the stream starts). It is never the
+     * run target, which is why an org/user rebind changes who answers with no
+     * client deploy. Turn 2+ continues on `/ai/conversations/{id}` exactly as
+     * before — the conversation is already bound to the agent the server chose.
+     */
+    mandateKey?: AnyMandateKey | null;
+    /** Model id used on the most recent assistant turn. */
+    lastModelId?: string | null;
+    parentConversationId?: string | null;
+    forkedFromId?: string | null;
+    forkedAtPosition?: number | null;
+    organizationId?: string | null;
+    projectId?: string | null;
+    taskId?: string | null;
+    /**
+     * Durable-entity identity this conversation belongs to. When present it goes
+     * out as `context_anchor` on every turn and the SERVER reloads that row to
+     * derive authoritative organization/project/task — ambient picker values are
+     * recorded as drift, never allowed to redefine an established entity
+     * (aidream `services/conversation_context/scope.py#bind_request_scope`).
+     */
+    contextAnchor?: ContextAnchor | null;
+    /** Stable UI-surface key (e.g. "agent-runner:<agentId>", "code-editor"). */
+    surfaceKey?: string;
+    /**
+     * The DB-registered `ui_surface.name` this conversation was LAUNCHED from
+     * (e.g. `matrx-user/quick-note-save`). Distinct from `surfaceKey`, which is
+     * a UI rendering-context string, not a surface the server knows.
+     *
+     * Stamped by `launchAgentExecution` whenever the launch resolved a surface.
+     * `buildToolInjection` prefers it over the route-derived guess so the
+     * server resolves against the surface the run actually belongs to.
+     *
+     * This is the ONLY way an OVERLAY surface can be attributed correctly: its
+     * window renders on top of a mapped route, so `detectActiveSurface()` (which
+     * reads `window.location.pathname`) always reports the ROUTE — on
+     * `/chat/[id]` that is `matrx-user/chat`, never the open window's surface.
+     *
+     * Absent on conversations that never launched from a surface (a plain chat
+     * send), which is what keeps those runs on the route-derived behavior.
+     */
+    surfaceName?: string | null;
+    /**
+     * The mapping a person chose for this run (Custom Agent's "Map Inputs"),
+     * and the page it was captured on. Lets an answer offer "Save as shortcut"
+     * and "Bind to this page" with that exact mapping. Tab lifetime only.
+     */
+    launchMapping?: {
+        valueMappings: ValueMappingMap;
+        surfaceName: string | null;
+    } | null;
+    /**
+     * When true, the server persists NOTHING for this conversation. Redux
+     * (specifically the messages slice) is the sole source of truth.
+     *
+     * Routing implication handled by `launchConversation`:
+     *   Turn 1  — POST /ai/agents/{id} with the client's id, is_new:true,
+     *             store:false. `store` is what makes it ephemeral.
+     *   Turn 2+ — POST /ai/chat (NOT /conversations/{id}; it 404s with no row).
+     *             Client sends the full accumulated history from `messages/`.
+     */
+    isEphemeral?: boolean;
+    /**
+     * Whether this conversation may be split (auto-clear "iterate") or must stay
+     * a single durable thread. Stamped once at creation from
+     * `deriveConversationLifecycle`; the `smartExecute` split gate reads it so a
+     * durable ("continuous"/undefined) conversation can never be orphaned. See
+     * `ConversationLifecycle`.
+     */
+    conversationLifecycle?: ConversationLifecycle;
+    title?: string | null;
+    description?: string | null;
+    keywords?: string[] | null;
+    /** System instruction snapshot — persisted on cx_conversation. */
+    systemInstruction?: string | null;
+    /** Lifecycle status on the cx_conversation row — "active" | "archived". */
+    persistedStatus?: "active" | "archived";
+    messageCount?: number;
+    /**
+     * Selects the API path family when dispatching through `launchConversation`.
+     *   "agent"  — full harness API (`agents/{id}` → `conversations/{id}`).
+     *   "manual" — raw prompt-style API (`prompts`). Builder only.
+     *
+     * NOTE: Legacy surface uses "chat" as the second value. "manual" is the
+     * canonical name from the invocation reference. Until Phase 3 retires the
+     * legacy callers the field is typed as the union of both.
+     */
+    apiEndpointMode?: ApiEndpointMode;
+    /** Only meaningful when `apiEndpointMode === "manual"`. Builder mechanism. */
+    reuseConversationId?: boolean;
+    builderAdvancedSettings?: BuilderAdvancedSettings | null;
+    metadata?: Record<string, unknown>;
+    /**
+     * A known non-terminal server-side operation for this conversation, stamped
+     * from aidream's `/runtime` reconnect surface (SERVER truth — survives page
+     * refresh). Drives the "still working on the server" banner; `null`/absent
+     * means no such operation. Written only by `reconnectServerOperation`.
+     */
+    serverOperation?: ServerOperationState | null;
+    /**
+     * THE sandbox this conversation is bound to — the single source of truth,
+     * identical in shape whether the conversation was just created locally or
+     * fetched from the DB. The agent's fs/shell/git tools route into this box.
+     *
+     * Persisted on `cx_conversation.sandbox_instance_id` (+ proxyUrl / tier /
+     * kind / name mirrored into `cx_conversation.metadata`) and rehydrated by the
+     * conversation bundle — so the SERVER, which checks the same column, can
+     * never disagree with us about which box is bound. Ephemeral conversations
+     * (no cx_* row) keep it in memory only, by design.
+     *
+     * `null`/absent means genuinely NOT BOUND — and the pre-send hard-gate reads
+     * exactly this. The per-surface `activeAgentSandboxBySurface` preference is a
+     * SEED for new conversations, not a binding: it arms an unbound conversation
+     * at turn time and is then promoted here (see `active-binding.ts`).
+     */
+    sandboxBinding?: {
+        rowId: string;
+        proxyUrl: string;
+        tier?: "ec2" | "hosted";
+        /**
+         * Compute-target kind. Absent / "ec2" / "hosted" → orchestrator sandbox.
+         * "local-pc" → user's matrx-local PC over Cloudflare tunnel; the
+         * binding payload is resolved server-side at chat-send time and
+         * `proxyUrl` is empty (the URL is built by `/api/compute-targets/resolve`).
+         */
+        kind?: "ec2" | "hosted" | "local-pc";
+        /** Display label latched at selection — rendered without re-fetching. */
+        name?: string;
+    } | null;
+    /**
+     * True once `sandboxBinding` has been written to `cx_conversation`. A binding
+     * set on a conversation that has no DB row yet (`cacheOnly` — the row is
+     * created server-side by the first turn) can't be persisted at that moment;
+     * this flag is what makes the write get retried on the next send, so the
+     * column the SERVER reads never silently drifts from what the client thinks
+     * is bound. Always true for a binding rehydrated from the DB.
+     */
+    sandboxBindingPersisted?: boolean;
+}
+/**
+ * The override layer for an instance's model config.
+ *
+ * CRITICAL: baseSettings is a snapshot copied from the agent at creation time.
+ * No component or selector should ever look up agentId for model settings.
+ *
+ * Three states for any setting key:
+ *   - NOT in overrides AND NOT in removals → untouched, falls through to baseSettings
+ *   - IN overrides → changed to a new value
+ *   - IN removals → explicitly removed (do not send, even if default exists)
+ */
+export interface InstanceModelOverrideState {
+    conversationId: string;
+    /** Snapshot of agent's LLM settings at instance creation. Never look up agentId again. */
+    baseSettings: Partial<LLMParams>;
+    overrides: Partial<LLMParams>;
+    removals: string[];
+    /**
+     * Override keys a LAUNCH wrote (the caller's config, a shortcut, the
+     * person's default-chat-model preference on the basic-chat door), not the
+     * person's own picker. They belong to THIS conversation's agent only: an
+     * agent switch never carries them (W-81). Absent = none.
+     */
+    seededKeys?: string[];
+}
+export type ResourceStatus = "pending" | "resolving" | "ready" | "error";
+/**
+ * All possible resource/content block types.
+ *
+ * The first group maps to the ContentBlock union from the AI API types —
+ * those resources serialize to structured `MessagePart`s in `user_input`.
+ *
+ * The `editor_*` group is different: those resources serialize to **XML in
+ * the user message text**, not to structured blocks. They're for pills the
+ * code editor surfaces (errors, code snippets) where the persisted user
+ * message must round-trip through the DB and re-render as chips on load.
+ */
+export type ResourceBlockType = "text" | "image" | "audio" | "video" | "youtube_video" | "document" | "input_webpage" | "input_notes" | "input_task" | "input_table" | "input_list" | "input_data" | "input_agent" | "input_project" | "input_agent_app" | "input_transcript" | "input_transcript_session" | "input_workbook" | "input_document" | "processed_document" | "source_ref" | "editor_error" | "editor_code_snippet" | "input_remarks";
+/**
+ * Which representation of a processed document is the PRIMARY one placed in the
+ * agent's context. The agent reaches the other formats (raw text, per-page,
+ * knowledge assets, PDF page images) on demand via the `document_content` tool.
+ */
+export type DocumentRepresentation = "clean" | "raw" | "pdf";
+export interface ResourceOptions {
+    keepFresh: boolean;
+    editable: boolean;
+    convertToText: boolean;
+    optionalContext: boolean;
+    template?: "full" | "compact" | "minimal";
+    /** For `processed_document` resources: the chosen primary representation. */
+    representation?: DocumentRepresentation;
+    /** Per-reference file-family promotion/suppression policy. */
+    resourcePolicy?: VariableResourceContextConfig;
+}
+export interface ManagedResource {
+    resourceId: string;
+    blockType: ResourceBlockType;
+    /** Raw input: URL string, file data, note IDs, bookmark objects, etc. */
+    source: unknown;
+    /** Client-resolved preview for the UI (scraped text, image thumbnail, etc.) */
+    preview: unknown | null;
+    /** Current lifecycle status */
+    status: ResourceStatus;
+    /** Error message if status is 'error' */
+    errorMessage: string | null;
+    /** Did the user modify the resolved content? */
+    userEdited: boolean;
+    /** The user's modified version (only when userEdited is true) */
+    editedContent: unknown | null;
+    /** Behavioral flags */
+    options: ResourceOptions;
+    /** The assembled ContentBlock payload ready for the API call */
+    finalPayload: UserInputPart | null;
+    /** Sort order for display and payload assembly */
+    sortOrder: number;
+}
+export interface InstanceContextEntry {
+    key: string;
+    value: unknown;
+    /** Whether this key matched an agent-defined context policy */
+    slotMatched: boolean;
+    /** If mandate-matched, the mandate's type. Otherwise inferred. */
+    type: ContextObjectType;
+    /** Display label (from mandate or auto-generated) */
+    label: string;
+    /**
+     * The surface whose live runtime PUBLISHED this value (a transcript open on
+     * the Knowledge page publishes `transcript_title` as `matrx-user/transcripts`).
+     * A value sits under the page that produced it — its row, its page layer and
+     * the person's rule for it are that surface's (`collectContextRowSources`).
+     * Absent for values no page published (attachments, host-written context).
+     */
+    surfaceName?: string;
+}
+export type InputSubmissionPhase = "idle" | "pending" | "persisted";
+/**
+ * THE PRE-SEND WINDOW, made visible. Between the person pressing Send and the
+ * request being admitted (`markInputSubmitted`), a surface may do real work —
+ * the tutor searches the learner's material for 10–25 s. That window used to
+ * show NOTHING, and a failure in it only reached the console (2026-09-28).
+ * `preparing` renders the outgoing message with what is happening to it;
+ * `failed` renders an honest in-place error with Retry. The composer `text`
+ * is never touched by either — the draft stays exactly as typed.
+ */
+export interface PreSendState {
+    status: "preparing" | "failed";
+    /** The text being sent, captured at press time (display only). */
+    text: string;
+    /** What is happening, e.g. "Searching your study material". */
+    label: string;
+    /** Present only when `status === "failed"`: what failed, in plain words. */
+    error?: string;
+    startedAt: number;
+}
+export interface InstanceUserInputState {
+    conversationId: string;
+    /** Plain text input from the user */
+    text: string;
+    /**
+     * If the user is composing mixed content (text + inline images, etc.),
+     * this holds the structured parts. When null, `text` is the only input.
+     */
+    messageParts: MessagePart[] | null;
+    /**
+     * Phase of the most recent submission lifecycle.
+     *   idle      — not submitting (also: the user has typed a NEW draft — the
+     *               instant they hit a key, setUserInputText resets phase to idle)
+     *   pending   — submit dispatched, server has not yet confirmed persistence
+     *   persisted — server confirmed cx_user_request record reserved; text visually cleared
+     *
+     * SACRED: clearing `text` (markInputPersisted / clearUserInput) is gated on
+     * `isInputDraftProtected` — see instance-user-input/input-draft-protection.ts.
+     * The composer holds the user's NEXT message after a submit and must never be
+     * wiped by stream/conversation events. Phase=idle + text≠lastSubmittedText
+     * means a live draft is present and is untouchable.
+     */
+    submissionPhase: InputSubmissionPhase;
+    /**
+     * Snapshot of the text/userValues captured at submit time. Preserved through
+     * the "persisted" phase so we can re-apply after a conversation reset.
+     * Cleared on full completion.
+     */
+    lastSubmittedText: string;
+    lastSubmittedUserValues: Record<string, unknown>;
+    /**
+     * Snapshot of the text/userValues from the FIRST submit on this instance
+     * lineage — the state the engineer had when they first clicked submit (no
+     * history yet). Captured once, never overwritten, and carried forward across
+     * autoclear splits / resets. The builder's auto-clear toggle re-applies this
+     * so the engineer can return to the exact original test inputs at any time.
+     * `undefined` until the first submit.
+     */
+    originalSubmittedText?: string;
+    originalSubmittedUserValues?: Record<string, unknown>;
+    /**
+     * The ATTACHMENTS of that same first submit — its structured message parts
+     * and its resource chips, exactly as they were — so the auto-clear restore
+     * brings back the identical request, files included. Captured and carried
+     * with `originalSubmittedText`; `undefined` until the first submit.
+     */
+    originalSubmittedAttachments?: SubmittedAttachments;
+    /** The visible pre-send window — see `PreSendState`. Null/absent when idle. */
+    preSend?: PreSendState | null;
+}
+/** The attachments of one submitted message, as the composer held them. */
+export interface SubmittedAttachments {
+    messageParts: MessagePart[] | null;
+    resources: ManagedResource[];
+}
+/**
+ * Transient builder/test settings sent to the chat endpoint on each call.
+ * NOT persisted with the agent definition — destroyed with the instance.
+ */
+export interface BuilderAdvancedSettings {
+    debug: boolean;
+    store: boolean;
+    maxIterations: number;
+    maxRetriesPerIteration: number;
+    /**
+     * When true, the system message from the agent's priming messages is extracted
+     * and sent as a structured `system_instruction` object instead of being included
+     * inline in the `messages` array.
+     *
+     * The structured form unlocks the server's SystemInstruction builder — intro,
+     * outro, content_blocks, tools_list, date injection, guidelines sections, etc.
+     *
+     * Default: false — the simple path (system message stays in messages[]).
+     */
+    useStructuredSystemInstruction: boolean;
+    /**
+     * User-provided overrides for structured system instruction fields.
+     * Only applied when `useStructuredSystemInstruction` is true.
+     * The `content` / `base_instruction` field is auto-populated from the
+     * agent's system message — the rest are additive fields the user configures
+     * via the structured instruction modal.
+     */
+    structuredInstruction: Partial<SystemInstruction>;
+    /**
+     * THE PERSON'S per-chat auto-tools switch (TOOL-SOURCES rule A), sent as
+     * `user.auto_tools` on every turn and saved with the conversation
+     * (`metadata.run_configuration.auto_tools`). `null`/absent = follow the
+     * agent's own `auto_tools_disabled`; `true`/`false` overrides it both ways.
+     * OFF ⇒ the server adds no transient tools and the client offers no page
+     * tools; the agent's own tools, picks (`addedTools`) and self-healing tools
+     * still ride.
+     */
+    autoTools?: boolean | null;
+    /**
+     * Creator-only "Surface Simulator": when set, `buildToolInjection` sends
+     * this exact `ui_surface.name` as `client.surface` instead of the
+     * route-detected one — letting a creator mimic ANY surface (matrx-user/*,
+     * matrx-admin/*, chrome-extension/*, …). The server resolves it normally
+     * and cannot tell it is simulated. null/empty → use the detected surface.
+     */
+    surfaceOverride?: string | null;
+    /**
+     * Tools the user added to THIS conversation from the Smart Input tools menu
+     * — registry tool UUIDs. Sent as `user.add` (TOOL-SOURCES P2): explicit
+     * picks survive the auto-tools switch and beat the agent's forbidden list.
+     * Never mixed into the anonymous request `tools[]`.
+     */
+    addedTools?: string[];
+    /**
+     * Tools the person REMOVED from THIS conversation (registry tool names, or a
+     * custom tool's name). Sent as `user.remove` — absolute on the server.
+     */
+    removedTools?: string[];
+    /**
+     * Connected MCP servers explicitly enabled for THIS conversation. These are
+     * server slugs (not registry-tool IDs) and are sent as `client.mcp`, so the
+     * server resolves the user's existing connection and its current tools.
+     */
+    addedMcpServers?: string[];
+    /**
+     * Skills the user added to THIS conversation from the Smart Input skills menu
+     * — registry skill UUIDs, additive on top of the agent's saved `skill_config`.
+     * `buildSkillConfigForRequest` folds them into `included` for the request's
+     * `skill_config` field so aidream's `apply_unified_skills` bakes the bodies
+     * into the system preamble for this run.
+     */
+    addedSkills?: string[];
+    /**
+     * The composer's Output → types the person asked for in THIS conversation
+     * (`text`, `image`, `audio`, `video`, `voice`, `music`, `document`, …; ids
+     * from `composer/output-selection.ts` OUTPUT_TYPES). Multi-select, Text on
+     * by default. NOT SENT: no request field carries requested output types
+     * today, so this is saved for the chat and shown — the panel says so.
+     */
+    outputTypes?: string[];
+    /**
+     * The composer's Output → Shapes: every content_ir kind slug picked for
+     * THIS conversation. A kind whose render_block skill exists ALSO has that
+     * skill in `addedSkills` (that is what reaches the run, via
+     * `skill_config.included`); a kind without one is recorded here only and
+     * labelled as not sent.
+     */
+    outputKinds?: string[];
+    /**
+     * Creator/admin-only, THIS conversation only: override the backend route the
+     * Builder's manual execution POSTs to. Normally the Builder always hits
+     * `/ai/manual` (the live-definition execution path). Set this to test the
+     * SAME request body against a different route — e.g. "/v2/ai/manual" — without
+     * editing code. The base URL / server selection (incl. localhost) is
+     * untouched; only the path changes. null/empty → use `ENDPOINTS.ai.manual`.
+     *
+     * Takes precedence over the global apiConfig version/path overrides for this
+     * one conversation. Value may be given with or without a leading slash.
+     */
+    manualEndpointOverride?: string | null;
+    /**
+     * MANUAL, default-OFF, THIS conversation only: arm the `agent-fs` client
+     * capability. When true, `buildToolInjection` adds `"agent-fs"` to
+     * `client.capabilities` (stateless — no `state` entry), which tells the
+     * backend to bring `fs_*` + `shell_execute` online against the user's
+     * durable `code.code_files`-backed VFS even with NO sandbox attached. Files
+     * persist to the user's Code Snippets under `/home/agent/...`.
+     *
+     * Not rolled out — kept behind an explicit toggle in "Chat Options →
+     * Settings" until deliberately shipped. Default: false. NEVER auto-enable.
+     */
+    agentFs?: boolean;
+    /**
+     * Creator/admin-only, THIS conversation only: a raw JSON object shallow-
+     * merged onto the outbound request body just before POST — the "add anything
+     * I want to the request for testing" escape hatch. Top-level keys override
+     * the assembled payload (e.g. `{"debug":true,"client":{...},"foo":1}`). The
+     * backend allows extra keys (`extra="allow"`) and warns on unrecognized ones.
+     *
+     * Stored as the raw text the user typed so an in-progress edit round-trips;
+     * parsed at send time. Invalid JSON is skipped loudly (toast) — the request
+     * still goes without the override. null/empty → no override.
+     */
+    requestOverrides?: string | null;
+}
+export declare const DEFAULT_BUILDER_ADVANCED_SETTINGS: BuilderAdvancedSettings;
+export interface JsonExtractionConfig {
+    enabled: boolean;
+    fuzzyOnFinalize?: boolean;
+    maxResults?: number;
+}
+export interface InstanceUIState {
+    conversationId: string;
+    displayMode: ResultDisplayMode;
+    /**
+     * When true, execution starts automatically as soon as the instance has
+     * sufficient input (variables filled, user input set, etc.).
+     * When false, the user must explicitly trigger execution.
+     */
+    autoRun: boolean;
+    /** Whether the user can continue chatting after the first response. */
+    allowChat: boolean;
+    /**
+     * When true, an intermediate input overlay is shown before the main display.
+     * The user enters text, clicks "Continue", and then the main component renders.
+     * Primarily for inline/toast/compact modes where the main display has no input.
+     */
+    showPreExecutionGate: boolean;
+    /**
+     * Flips to true after the user completes the pre-execution input step.
+     * Components check: if showPreExecutionGate && !preExecutionSatisfied → show gate.
+     */
+    preExecutionSatisfied: boolean;
+    /** Whether the variable input panel is visible. Independent of message display. */
+    showVariablePanel: boolean;
+    /**
+     * Whether definition-sourced conversation turns (fabricated user messages from
+     * the agent's priming definition) are visible at all. When false, the first N
+     * turns (where N = hiddenMessageCount) are completely hidden.
+     */
+    showDefinitionMessages: boolean;
+    /**
+     * When definition messages ARE shown, whether the "secret" template portion
+     * (system prompt instructions, variable placeholders in the raw form) is visible.
+     * When false, only user-entered values (variables, resources, attachments) render.
+     */
+    showDefinitionMessageContent: boolean;
+    /**
+     * Whether sub-agent turns appear in the transcript. When false, consumer
+     * components filter them out when projecting the messages slice into the
+     * display list (data is still stored on the record — no loss). Default true.
+     */
+    showSubAgents?: boolean;
+    /**
+     * Number of agent-definition messages to hide from the conversation display.
+     * Fetched from `agx_get_defined_data` RPC at instance creation time.
+     *
+     * ⚠️ TEMPORARY: This is a stopgap until the backend streams per-message
+     * shown-to flags (is_visible_to_user / is_visible_to_model).
+     */
+    hiddenMessageCount: number;
+    /**
+     * CallbackManager id for this instance's WidgetHandle — a single object
+     * carrying capability methods (onTextReplace, onAttachMedia, ...) and
+     * lifecycle methods (onComplete, onCancel, onError). The submit-body
+     * assembler reads the handle per-turn via `callbackManager.get(id)` to
+     * derive `client_tools`; the tool_delegated dispatcher routes widget_*
+     * calls to the corresponding method.
+     *
+     * Stored as a string so Redux stays serializable. See
+     * `features/agents/types/widget-handle.types.ts` for the contract.
+     */
+    widgetHandleId: string | null;
+    isExpanded: boolean;
+    /**
+     * The variable row currently expanded into an edit popover.
+     * null = no variable is expanded.
+     */
+    expandedVariableId: string | null;
+    /**
+     * Is the current user the creator/owner of the source agent?
+     * Copied at instance creation — never look up agentId for this.
+     */
+    isCreator: boolean;
+    /** Show creator-only debug panels (request preview, variable provenance, etc.) */
+    showCreatorDebug: boolean;
+    /**
+     * Submit on Enter (vs Shift+Enter for newline).
+     * Defaults to true; users can toggle per-instance.
+     */
+    submitOnEnter: boolean;
+    /**
+     * When true, the conversation history is cleared after each submission so
+     * every send starts a fresh agent call with no prior turns. The server never
+     * receives a conversationId from a previous turn.
+     *
+     * DEFAULT: true in builder/test Mode (AgentBuilderRightPanel).
+     * DEFAULT: false in run Mode (AgentRunPage) where multi-turn is desired.
+     */
+    autoClearConversation: boolean;
+    /**
+     * When true, the auto-clear toggle is shown in the input area.
+     * When false, the auto-clear toggle is not shown.
+     */
+    showAutoClearToggle: boolean;
+    /**
+     * When true, subsequent chat calls reuse the conversation_id from the first
+     * response. When false (default), each call gets a fresh conversation.
+     * Only applies to chat-Mode instances (builder test runs).
+     */
+    reuseConversationId: boolean;
+    /**
+     * Builder-only control knobs sent to the chat endpoint.
+     * Ephemeral — not saved with the agent definition.
+     */
+    builderAdvancedSettings: BuilderAdvancedSettings;
+    /** When true, reasoning/thinking blocks are not shown in the message list. */
+    hideReasoning: boolean;
+    /** When true, tool-call result blocks are not shown in the message list. */
+    hideToolResults: boolean;
+    /**
+     * Density of the assistant transcript chrome (tool call cards, thinking
+     * blocks, action bar).
+     *   - "comfortable" (default): full chrome, persistent action bar.
+     *   - "compact": one-line tool/thinking strips, hover-revealed controls,
+     *     action bar appears only on hover unless this message is the latest.
+     *
+     * Designed for highly agentic / coding-style runs where dozens of tool
+     * calls + reasoning blocks would otherwise drown the actual model output.
+     * Per-conversation so a single surface (e.g. the code-editor agent runner)
+     * can opt in without affecting other chat surfaces.
+     */
+    responseDensity: "comfortable" | "compact";
+    /**
+     * Optional app-level identity overrides for the AgentEmptyMessageDisplay
+     * (the centered hero shown before the first message). When null, the
+     * empty display falls back to the agent's name/description. Surfaces
+     * that want their own identity (agent-apps' Live Builder, the public
+     * /p/<slug> runner, embedded iframes) set these to surface the app
+     * identity rather than the underlying agent's.
+     */
+    displayNameOverride: string | null;
+    displayDescriptionOverride: string | null;
+    /**
+     * Lucide icon name (or Matrx svg path) for the centered hero. Falls
+     * back to a default Webhook icon when null.
+     */
+    displayIconNameOverride: string | null;
+    /**
+     * Settings group: input chrome — read by SmartAgentInput / AgentTextarea
+     * and friends. Surfaces (e.g. agent-apps) tune these at instance-create
+     * time so the input renders with the right affordances WITHOUT passing
+     * props through six render levels.
+     *
+     *   - inputPlaceholder           : null → use built-in default. Any
+     *                                  string overrides the textarea
+     *                                  placeholder.
+     *   - showFreeformInput          : false → render variables panel only,
+     *                                  no free-text input. Apps with only
+     *                                  structured inputs use this.
+     *   - showAttachments            : false → hide the file/image
+     *                                  attach button + resource chips.
+     *   - showMicrophone             : false → hide the mic button in
+     *                                  the input toolbar.
+     *   - showUserMessageOptions     : false → hide the ⋯ menu on user
+     *                                  messages in the transcript.
+     *   - showAssistantMessageOptions: false → same, for assistant
+     *                                  messages.
+     *   - bufferStream               : true  → wait for the stream to
+     *                                  finish before painting, so the
+     *                                  user sees one full response
+     *                                  instead of a live-typing effect.
+     */
+    inputPlaceholder: string | null;
+    showFreeformInput: boolean;
+    showAttachments: boolean;
+    showMicrophone: boolean;
+    showUserMessageOptions: boolean;
+    showAssistantMessageOptions: boolean;
+    bufferStream: boolean;
+    /**
+     * Optional message shown in the pre-execution input gate.
+     * Used to give the user context about what the agent expects.
+     */
+    preExecutionMessage: string | null;
+    /**
+     * Seconds before the pre-execution gate auto-submits (falls through).
+     * 0 = wait indefinitely for the user. Any positive number starts a visible
+     * countdown in AgentGateBody that auto-advances once it reaches zero.
+     */
+    bypassGateSeconds: number;
+    /**
+     * Controls which variable input UI style is rendered.
+     * - "inline"  — compact rows above the textarea (default)
+     * - "wizard"  — one variable at a time, fixed-height card with Back/Skip/Skip All
+     */
+    variablesPanelStyle: VariablesPanelStyle;
+    /**
+     * Arbitrary UI state specific to the display Mode.
+     * E.g., scroll position, active tab, selected card, etc.
+     */
+    modeState: Record<string, unknown>;
+    /**
+     * When set, processStream will run a StreamingJsonTracker during execution
+     * and dispatch extractedJson updates into the active request slice.
+     * Read by executeInstance at stream time.
+     */
+    jsonExtraction?: JsonExtractionConfig | null;
+    /**
+     * The text that was selected in the editor/notes surface when the launch
+     * was triggered. Passed through to onTextReplace / onTextInsertBefore /
+     * onTextInsertAfter callbacks once the AI response is ready.
+     */
+    originalText: string | null;
+    /**
+     * Editor-context bridge (matrx /code workspace).
+     *
+     * Tab ids that the user has explicitly excluded from the editor → agent
+     * context bridge for this instance. The bridge mirrors every open tab into
+     * `editor.tab.<id>` context entries; ids in this set are skipped (and the
+     * matching context entry, if any, is removed). Persisted per-conversation
+     * so the user's preference rides along the conversation.
+     *
+     * Empty/undefined = include all tabs (default).
+     */
+    editorContextDisabledTabs?: string[];
+    /**
+     * Per-conversation backend URL override.
+     *
+     * When set, the agent execute thunks (`executeInstance`, tool-result
+     * POSTs) prefer this URL over the global `selectResolvedBaseUrl(state)`.
+     * This is how Sandbox-mode
+     * conversations talk to the in-container Python server without
+     * disturbing every other backend call in the page.
+     *
+     * Set by `useBindAgentToSandbox(conversationId, instanceId)` when the
+     * editor surface mounts a sandbox adapter, cleared on unmount.
+     *
+     * Format: a fully-qualified base URL with no trailing slash, e.g.
+     * `https://orchestrator.dev.codematrx.com/sandboxes/<instanceId>/proxy`.
+     * The thunks will append `/ai/...` paths exactly as they do for the
+     * global base URL — the override is a drop-in replacement.
+     *
+     * Null/undefined = no override; thunks fall back to `selectResolvedBaseUrl`.
+     */
+    serverOverrideUrl?: string | null;
+    /**
+     * Bearer token paired with `serverOverrideUrl` for direct sandbox-proxy
+     * calls. Minted by `POST /api/sandbox/[id]/access-tokens` (which
+     * forwards to the orchestrator), short-lived (orchestrator decides
+     * the TTL — typically 15 min), and refreshed lazily by
+     * `useSandboxAccessToken` before expiry.
+     *
+     * When set together with `serverOverrideUrl`, the agent execute thunks
+     * send `Authorization: Bearer <this token>` and DO NOT send the user's
+     * Supabase JWT (the orchestrator authenticates via this token alone).
+     *
+     * Null/undefined while the URL is set is technically valid — the
+     * proxy will then return 401 for the AI call. The hook is responsible
+     * for keeping URL + token in lockstep.
+     */
+    serverOverrideAuthToken?: string | null;
+    /**
+     * Last error from the bearer-token mint flow for this conversation, if
+     * any. Surfaced by `useBindAgentToSandbox` so admin debug panels can
+     * show *why* a sandbox-mode call is unauthenticated instead of just
+     * "(none)".
+     *
+     * Cleared automatically when a token is successfully minted, when the
+     * URL override is cleared, or when the conversation entry is removed.
+     */
+    serverOverrideAuthTokenError?: string | null;
+}
+/**
+ * ManagedAgentOptions — the full invocation envelope for launching an agent.
+ *
+ * Organized in four sections:
+ *   1. IDENTITY   — who is being launched, from where
+ *   2. CONFIG     — the AgentExecutionConfig bundle (customization knobs)
+ *   3. RUNTIME    — per-call values (user input, scope, handles)
+ *   4. INVOCATION — flags that don't belong in any of the above
+ *
+ * All customization knobs live in the nested `config` bundle and all
+ * per-call values in `runtime`; there are no flat config fields on this
+ * type. The launchAgentExecution thunk reads both at entry.
+ */
+export interface ManagedAgentOptions {
+    /** Stable surface key for the focus registry (e.g. "agent-builder", "agent-runner:<id>") */
+    surfaceKey: string;
+    agentId?: string;
+    /**
+     * Agent-mandate key (`<domain>.<step>`, e.g. `plan_client.shape_planner`) —
+     * THE MANDATE DOOR. Turn 1 POSTs `/ai/mandates/{mandateKey}` and aidream
+     * resolves principal → system default → org binding → user binding, applies
+     * the binding's `config_overrides` and the provision/variable contract, then
+     * runs the identical downstream pipeline. A rebind therefore changes which
+     * agent answers with NO client deploy.
+     *
+     * `agentId` may be passed ALONGSIDE this key: it is then DISPLAY IDENTITY
+     * only (the agent row the surface paints before the stream starts, e.g.
+     * `/chat/new`'s SSR-resolved default) and this launch resolves nothing
+     * client-side. Omit `agentId` and the thunk reads one through
+     * `resolveMandate` purely to snapshot the instance — still a display read,
+     * never the run decision.
+     *
+     * Mutually exclusive with `shortcutId`.
+     *
+     * 🚨 TYPED, NEVER `string` (V-L6a, 2026-09-17). A wrong key here is a 404 at
+     * the mandate door that the user sees only as an agent that never answers,
+     * so it must fail `pnpm type-check` instead. `AnyMandateKey` because a
+     * user-built app's DB-authored `app.*` key launches through this same door.
+     */
+    mandateKey?: AnyMandateKey;
+    shortcutId?: string;
+    manual?: {
+        label?: string;
+        baseSettings?: Partial<LLMParams>;
+    };
+    /**
+     * Client-assigned conversation id to use for this launch instead of minting a
+     * fresh one. `useAgentLauncher` resolves a STABLE id per surface (reuse the
+     * focused id, else mint once) and threads it here so the conversation exists
+     * under a known id from the first render — never null, never re-minted on
+     * remount. The server honors this id end-to-end (turn-1 body + X-Conversation-ID).
+     */
+    conversationId?: string;
+    /** UI surface that triggered the launch. Required for telemetry and attribution. */
+    sourceFeature: SourceFeature;
+    /**
+     * Provenance attestation for this launch's requests — see
+     * {@link RequestInitiation}. Defaults to "user" (the interactive launch
+     * path). Programmatic schedulers / auto-triggers (mount effects, timers,
+     * agent-tool-driven sends) MUST pass "auto".
+     */
+    initiation?: RequestInitiation;
+    /**
+     * The launching surface saves this run's result itself — never materialize
+     * its assistant turns (see `ExecutionInstance.surfaceOwnsOutput`). Stamped
+     * on the conversation record before the first stream commits.
+     */
+    surfaceOwnsOutput?: boolean;
+    /**
+     * Canonical agent-customization bundle. When launching via a shortcut,
+     * the shortcut's persisted config is loaded here; callers can layer
+     * additional partial overrides on top.
+     *
+     * Preferred over the deprecated flat fields below — the launch thunk
+     * merges both but new code should only set `config`.
+     */
+    config?: Partial<import("./agent-execution-config.types.js").AgentExecutionConfig>;
+    /**
+     * Per-call runtime data: applicationScope (UI-captured), live userInput,
+     * widget handle id, original text for widget handoff.
+     */
+    runtime?: import("./agent-execution-config.types.js").AgentExecutionRuntime;
+    /** Delay conversation creation until the caller signals readiness. Default: true */
+    ready?: boolean;
+    /**
+     * "I will dispatch `executeInstance` myself." The ONLY legitimate reason to
+     * pair a HEADLESS display mode (one that paints no interface —
+     * `HEADLESS_DISPLAY_MODES`) with `autoRun: false`.
+     *
+     * WHY THIS EXISTS. `autoRun` is a user-interface control: it decides whether
+     * the interface pauses and lets the person act before the request goes out.
+     * A headless mode has no interface, so there is nothing to pause — which
+     * means `autoRun: false` there does not defer the send to a human, it just
+     * never sends. The launch therefore IGNORES autoRun on headless modes and
+     * runs anyway (loudly), because the overwhelmingly common cause is a call
+     * site that simply forgot the flag.
+     *
+     * But a caller can legitimately need the deferral: when it must seed
+     * something the launch itself cannot carry — multi-part message content, for
+     * example (`runtime.userInput` and `runtime.variables` ARE seeded before
+     * execution, so anything expressible there needs no deferral at all). Those
+     * callers set this, and it reads as the deliberate claim it is instead of
+     * looking identical to the bug.
+     *
+     * Setting this and then NOT executing produces a conversation that never
+     * runs and that nothing can ever start. That is on you.
+     */
+    callerExecutes?: boolean;
+    /**
+     * When true, the server writes nothing to the DB and Redux becomes the sole
+     * source of truth for the transcript.
+     *   Turn 1:  POST /ai/agents/{id} with the client's id, `is_new:true`,
+     *            `store:false`.
+     *   Turn 2+: POST /ai/conversations/{id} with `store:false`. The server
+     *            still streams the next iteration; nothing is persisted.
+     * Stamped onto the conversation record via `createInstance`; the execute
+     * thunk reads `instance.isEphemeral` to branch.
+     */
+    isEphemeral?: boolean;
+    /**
+     * Explicit organization for this run — the org of the ROW the launch is
+     * generating from. Pass it whenever the caller knows it: without it the
+     * request falls back to the user's ambient active org, which can file the
+     * output under a different organization entirely.
+     */
+    organizationId?: string | null;
+    /**
+     * The durable entity this run is FOR (e.g. `{resource_type:"research_topic",
+     * resource_id}`). Sent as `context_anchor`; the server reloads that row and
+     * derives authoritative organization/project/task from it, recording any
+     * conflicting ambient value as drift rather than obeying it. This is the
+     * execution-system equivalent of `useRunAgent`'s `contextAnchor`, so a
+     * surface migrating to the live posture keeps its scope instead of silently
+     * dropping it.
+     */
+    contextAnchor?: ContextAnchor | null;
+    showAutoClearToggle?: boolean;
+    /** When true, conversation history is wiped after each submit (builder/test). */
+    autoClearConversation?: boolean;
+    /**
+     * Controls which execution path and history strategy is used.
+     * Set once at invocation; never mutated.
+     *
+     * "agent"  — Default. Turn 1 → POST /ai/agents/{id}. Turn 2+ → POST /ai/conversations/{id}.
+     *            Server owns history and the agent definition. Client only stores for display.
+     *
+     * "manual" — Always POST /ai/manual. Client owns history and sends full messages[]
+     *            on every turn. Used by Builder (LIVE unsaved agent definition) and
+     *            by ephemeral conversations (turn 2+, where no DB row exists).
+     *
+     */
+    apiEndpointMode?: ApiEndpointMode;
+    /**
+     * Opt-in JSON extraction during streaming. When provided with `enabled: true`,
+     * processStream runs a StreamingJsonTracker and dispatches results into
+     * the active request slice. Read via selectExtractedJson / selectFirstExtractedObject.
+     */
+    jsonExtraction?: JsonExtractionConfig;
+    /**
+     * Fires as soon as the instance has been created but BEFORE the stream
+     * starts. Lets streaming UIs mount their Redux selectors keyed to this
+     * conversationId immediately instead of waiting for the awaited Promise
+     * to resolve (which, for direct-mode runs, can be 30+ seconds).
+     *
+     * Purely a side-channel for the caller — the launch thunk still owns the
+     * conversation lifecycle.
+     */
+    onConversationCreated?: (conversationId: string) => void;
+    /**
+     * Fires the moment the request row exists — right after `executeInstance`
+     * resolves, BEFORE the run is polled to completion.
+     *
+     * `onConversationCreated` is not enough for a streaming UI: every live
+     * selector (`selectAccumulatedText`, `selectRequestStatus`, …) is keyed by
+     * `requestId`, not `conversationId`. Without this hook a caller can only
+     * learn the requestId from the awaited `LaunchResult`, which for
+     * direct/background runs arrives AFTER `pollForCompletion` — so the panel
+     * mounts already-finished and the whole response appears at once behind a
+     * spinner. That was the auto-create "nothing, then everything" bug.
+     *
+     * Purely a side-channel for the caller — the launch thunk still owns the
+     * request lifecycle.
+     */
+    onRequestId?: (requestId: string) => void;
+    /**
+     * CLIENT-ONLY (read by `useAgentLauncher`, never forwarded to the thunk).
+     *
+     * Controls the managed-mode unmount cleanup:
+     *   - false (default): always destroy the launcher-created instance on
+     *     unmount. Right for surfaces whose URL is stable for a conversation's
+     *     whole life (agent runner, builder).
+     *   - true: on unmount, only destroy the instance if it's ABANDONED (no
+     *     messages). A conversation the user actually started is RETAINED.
+     *     Required by surfaces that change route mid-conversation — the chat
+     *     route promotes `/chat/new` → `/chat/[conversationId]` right after the
+     *     first submit, which unmounts the launcher; destroying the instance
+     *     there would wipe the in-flight stream. The destination route
+     *     re-attaches to the retained instance instead of re-fetching.
+     */
+    retainOnUnmount?: boolean;
+    /**
+     * CLIENT-ONLY (read by `useAgentLauncher`, never forwarded to the thunk).
+     *
+     * When true, the hook mints a new conversation id instead of reusing the
+     * surface's cached focus. Required on fresh chat routes (`/chat/new`,
+     * `/chat/a/[agentId]`) so navigating from an existing conversation does
+     * not revive its transcript on the first render (before `clearFocus` runs).
+     */
+    preferFresh?: boolean;
+    /**
+     * CLIENT-ONLY. Bumped when the user explicitly starts a new chat (+). Forces
+     * the managed launcher to remint even when the URL stays on `/chat/new`.
+     */
+    freshSessionKey?: number;
+    /**
+     * CLIENT-ONLY. With `preferFresh`: the conversation id this fresh room must
+     * use instead of a random one (a UUID reserved before the room opened — the
+     * `?c=` of "New chat about this"). Content staged for that id (its chip) is
+     * keyed to it, so it survives a reload and can never land in another chat.
+     */
+    reservedConversationId?: string | null;
+}
+export declare const AGENT_EXECUTION_DEFAULTS: {
+    /**
+     * How the result is presented. "direct" means the caller manages the UI
+     * (AgentRunPage, builder panel, etc.). All other modes open an overlay.
+     */
+    readonly displayMode: ResultDisplayMode;
+    /**
+     * Which execution path and history strategy to use.
+     * "agent" is the standard path for all non-builder surfaces.
+     * Set once at invocation time; never mutated.
+     */
+    readonly apiEndpointMode: ApiEndpointMode;
+    /**
+     * Delay conversation creation until the caller signals readiness.
+     * When true, the instance is created but does not fetch/execute until
+     * the caller flips it to ready. Default true for safety.
+     */
+    readonly ready: true;
+    /**
+     * Should the instance execute immediately after creation without the user
+     * clicking submit? false = wait for explicit user action.
+     *
+     * Set to true only for programmatic triggers where the full context is
+     * already assembled (e.g. flashcard "I'm confused" button).
+     */
+    readonly autoRun: false;
+    /**
+     * Can the user send follow-up messages after the first response?
+     * true = multi-turn conversation; false = single-shot only.
+     */
+    readonly allowChat: true;
+    /**
+     * Show a gate UI before executing where the user provides initial text.
+     * Used for inline/toast/compact modes that have no built-in input.
+     */
+    readonly showPreExecutionGate: false;
+    /**
+     * When true, submitting creates a fresh instance (no history) instead of
+     * continuing the current conversation. Only meaningful in builder/test system.
+     */
+    readonly autoClearConversation: false;
+    /**
+     * Whether to show the auto-clear toggle control in the UI. Independent of
+     * autoClearConversation itself — this governs display of the toggle.
+     */
+    readonly showAutoClearToggle: false;
+    /**
+     * Coarse toggle: when true → showVariablePanel + showDefinitionMessages on.
+     * Overridden by the fine-grained fields below.
+     * undefined = fine-grained fields take effect individually.
+     */
+    readonly showVariables: boolean | undefined;
+    /** Show the variable input panel above the input area. */
+    readonly showVariablePanel: false;
+    /**
+     * Show agent-definition messages (fabricated priming turns) in the thread.
+     * When false, the first N turns (hiddenMessageCount) are hidden from the user.
+     */
+    readonly showDefinitionMessages: true;
+    /**
+     * When definition messages are shown, also show the raw template content
+     * (system prompt, variable placeholders). When false, only filled values render.
+     */
+    readonly showDefinitionMessageContent: false;
+    /**
+     * How variables are collected from the user before execution.
+     * "inline" = compact rows above the textarea.
+     * "wizard" = one-at-a-time card with Back/Skip/Skip All.
+     */
+    readonly variablesPanelStyle: VariablesPanelStyle;
+    /** Submit on Enter key; Shift+Enter = newline. */
+    readonly submitOnEnter: true;
+    /**
+     * For chat-system instances: reuse the server's conversationId across calls
+     * so the server can maintain its own history. When false, each call starts
+     * fresh. Relevant only when apiEndpointMode is "manual".
+     */
+    readonly reuseConversationId: false;
+    /** Expose creator-only debug panels (request preview, variable provenance). */
+    readonly showCreatorDebug: false;
+    /** Hide reasoning/thinking blocks from the message list. */
+    readonly hideReasoning: false;
+    /** Hide tool-call result blocks from the message list. */
+    readonly hideToolResults: false;
+    /** Optional message shown in the pre-execution input gate. */
+    readonly preExecutionMessage: null;
+    /** How many definition messages to hide (fetched from agx_get_defined_data). */
+    readonly hiddenMessageCount: 0;
+    /**
+     * CallbackManager id for a WidgetHandle. See widget-handle.types.ts.
+     * Null by default; set by callers that use `useWidgetHandle`.
+     */
+    readonly widgetHandleId: null;
+    /**
+     * The text that was selected in the editor when the launch was triggered.
+     * Stored in instanceUIState.originalText. Forwarded to the widget handle's
+     * text-manipulation methods alongside the agent's response.
+     */
+    readonly originalText: null;
+    /**
+     * Opt-in JSON extraction during streaming. When provided with `enabled: true`,
+     * processStream runs a StreamingJsonTracker and dispatches results into
+     * the active request slice. Stored in instanceUIState.jsonExtraction.
+     */
+    readonly jsonExtraction: null;
+    /** Pre-filled user message text. Stored in instanceUserInput. */
+    readonly userInput: null;
+    /** Pre-filled variable values. Stored in instanceVariableValues. */
+    readonly variables: null;
+    /**
+     * LLM parameter overrides (delta from agent base settings).
+     * Stored in instanceModelOverrides. Applied in execute-instance thunk.
+     * Not used in chat Mode (builder reads full live agent definition instead).
+     */
+    readonly overrides: null;
+    /**
+     * UI surface that triggered the launch. Stored on ExecutionInstance.
+     * Required on ManagedAgentOptions — this fallback is only used by internal
+     * code paths that construct instances without a caller-facing options object.
+     */
+    readonly sourceFeature: SourceFeature;
+};
+export type { VariablesPanelStyle } from "../components/inputs/variable-input-variations/variable-input-options.js";
+export type { ResultDisplayMode } from "../utils/run-ui-utils.js";