lumiverse-spindle-types 0.5.8 → 0.5.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lumiverse-spindle-types",
-  "version": "0.5.8",
+  "version": "0.5.10",
   "types": "./src/index.ts",
   "keywords": [
     "lumiverse",

package/src/api.ts

@@ -247,6 +247,25 @@ export interface GenerationRequestDTO {
   connection_id?: string;
   /** Optional tool/function definitions for inline function calling (raw/quiet only). */
   tools?: ToolSchemaDTO[];
+  /**
+   * Optional per-request override of the user's reasoning ("extended thinking")
+   * settings. When omitted (or `{ source: "inherit" }`) the backend resolves
+   * the effective settings the same way a normal chat generation does:
+   * the resolved connection's `reasoning_bindings` win, falling back to the
+   * user's global `reasoningSettings`.
+   *
+   * Use this to bypass that resolution for a single request — e.g. to force
+   * `"off"` for a quick, cheap call, or to dial the effort up/down with
+   * `source: "custom"`. The backend translates the high-level intent into
+   * the provider-specific knobs (`thinking`, `thinkingConfig`,
+   * `reasoning_effort`, `reasoning.effort`, etc.) so the extension doesn't
+   * need to know the per-provider quirks.
+   *
+   * Raw values supplied in `parameters` still take precedence at the field
+   * level — this override only fills in what hasn't already been set,
+   * except `source: "off"` which unconditionally strips reasoning fields.
+   */
+  reasoning?: GenerationReasoningOverrideDTO;
   /**
    * For operator-scoped extensions: the user ID whose connection profiles
    * and generation context should be used. For user-scoped extensions this
@@ -348,6 +367,112 @@ export interface RequestInitDTO {
   mediaType?: "image" | "audio";
 }
 
+/**
+ * Reasoning effort tier. Provider mapping:
+ * - Anthropic adaptive (Claude 4.6+): `low | medium | high | max` (+ `xhigh` on Opus 4.7) → `output_config.effort`.
+ * - Anthropic legacy: mapped to `thinking.budget_tokens` (low=2048, medium=8192, high=16384, max=32768).
+ * - Google (Gemini / Vertex): `minimal | low | medium | high` → `thinkingConfig.thinkingLevel`.
+ * - DeepSeek: `low | medium | high` → `"high"`, `max | xhigh` → `"max"` (`reasoning_effort`).
+ * - OpenRouter: `none | minimal | low | medium | high | xhigh` → `reasoning.effort`.
+ * - NanoGPT: `none | minimal | low | medium | high` → `reasoning.effort`.
+ * - Moonshot / Z.AI: toggle-only — effort ignored, just enables `thinking`.
+ * - Generic OpenAI-compatible: passed verbatim as `reasoning.effort`.
+ *
+ * `"auto"` defers to the user's preset/global setting or the provider's
+ * model-specific default and is the safest value to use when you don't
+ * have a specific tier in mind.
+ */
+export type ReasoningEffortDTO =
+  | "auto"
+  | "none"
+  | "minimal"
+  | "low"
+  | "medium"
+  | "high"
+  | "max"
+  | "xhigh";
+
+/**
+ * Anthropic-only display mode for thinking blocks. Maps to `thinking.display`
+ * in the Messages API. `"auto"` omits the field so Anthropic applies its
+ * model-specific default (`"omitted"` on Opus 4.7 / Mythos Preview,
+ * `"summarized"` elsewhere). Ignored by every other provider.
+ */
+export type ThinkingDisplayDTO = "auto" | "summarized" | "omitted";
+
+/**
+ * Full reasoning settings snapshot. Mirrors the user-level setting that
+ * Lumiverse stores under `reasoningSettings`. Surfaced on
+ * `ConnectionProfileDTO.reasoning_bindings.settings` when a connection has
+ * a binding attached.
+ *
+ * Only `apiReasoning` / `reasoningEffort` / `thinkingDisplay` influence the
+ * outgoing provider request — the remaining fields drive delimited-reasoning
+ * parsing (`prefix`, `suffix`, `autoParse`) and chat-history pruning
+ * (`keepInHistory`) and are included for inspection / round-tripping.
+ */
+export interface ReasoningSettingsDTO {
+  /** Master switch: whether the provider should produce thinking output. */
+  apiReasoning: boolean;
+  /** Effort tier — see {@link ReasoningEffortDTO}. */
+  reasoningEffort: ReasoningEffortDTO;
+  /** Anthropic-only. */
+  thinkingDisplay: ThinkingDisplayDTO;
+  /** Opening delimiter used by the delimited-reasoning parser (e.g. `"<think>\n"`). */
+  prefix: string;
+  /** Closing delimiter used by the delimited-reasoning parser (e.g. `"\n</think>"`). */
+  suffix: string;
+  /** Whether to auto-parse delimited reasoning out of the assistant content stream. */
+  autoParse: boolean;
+  /**
+   * How many recent reasoning blocks to retain in assembled prompt history.
+   * `0` strips all, `-1` keeps everything, `N` keeps the last N.
+   */
+  keepInHistory: number;
+}
+
+/**
+ * Reasoning settings bound to a specific connection profile. When present,
+ * these override the user's global `reasoningSettings` during normal chat
+ * generation on this connection.
+ */
+export interface ConnectionReasoningBindingsDTO {
+  /** Reasoning settings snapshot captured at bind time. */
+  settings: ReasoningSettingsDTO;
+  /**
+   * Optional "Start Reply With" assistant prefill captured alongside the
+   * reasoning snapshot. When present, overrides the user's global
+   * `promptBias` setting for this connection.
+   */
+  promptBias?: string;
+}
+
+/**
+ * Per-request reasoning override for `spindle.generate.*` calls. Use the
+ * `source` discriminator to pick how the backend resolves the effective
+ * reasoning settings:
+ *
+ *  - `"inherit"` (default if `source` is omitted): apply the connection's
+ *    `reasoning_bindings` if any, else the user's global setting. Same as
+ *    leaving the `reasoning` field off entirely. Useful when you want to
+ *    document intent without changing behaviour.
+ *  - `"off"`: short-circuit. The provider's no-reasoning off-switch is
+ *    applied unconditionally — even if `parameters` already carry an
+ *    explicit `thinking` / `reasoning` block from the caller.
+ *  - `"custom"`: use the explicit `apiReasoning` / `effort` / `thinkingDisplay`
+ *    fields below for this request only. Omitted fields use their defaults
+ *    (`apiReasoning: true`, `effort: "auto"`, `thinkingDisplay: "auto"`).
+ *    Raw values supplied via `parameters` still win at the field level —
+ *    the override only fills in unset fields, exactly like the inherited
+ *    settings would.
+ */
+export interface GenerationReasoningOverrideDTO {
+  source?: "inherit" | "off" | "custom";
+  apiReasoning?: boolean;
+  effort?: ReasoningEffortDTO;
+  thinkingDisplay?: ThinkingDisplayDTO;
+}
+
 /**
  * Safe representation of a user's connection profile exposed to extensions.
  * Never contains the actual API key — only `has_api_key` boolean.
@@ -361,7 +486,20 @@ export interface ConnectionProfileDTO {
   preset_id: string | null;
   is_default: boolean;
   has_api_key: boolean;
+  /**
+   * Raw provider-specific metadata bag stored on the connection. Includes
+   * provider-quirk flags (Anthropic prompt caching, Google thinking budget
+   * config, etc.) and the original `reasoningBindings` blob — `reasoning_bindings`
+   * below is the parsed, typed view of that same blob.
+   */
   metadata: Record<string, unknown>;
+  /**
+   * Typed view of the connection's bound reasoning settings, parsed from
+   * `metadata.reasoningBindings`. `null` when the connection has no binding
+   * (in which case generation falls back to the user's global
+   * `reasoningSettings`).
+   */
+  reasoning_bindings: ConnectionReasoningBindingsDTO | null;
   created_at: number;
   updated_at: number;
 }
@@ -1637,6 +1775,50 @@ export interface SpindleCommandContextDTO {
   isGroupChat?: boolean;
 }
 
+// ─── UI Automation DTOs ─────────────────────────────────────────────────
+
+/**
+ * Read-only snapshot of a drawer tab discoverable via
+ * {@link SpindleAPI.ui.getDrawerTabs}. Mirrors the metadata used by the
+ * built-in Command Palette to render the "Panels" group.
+ */
+export interface SpindleUIDrawerTabDTO {
+  /** Stable id used by `openDrawerTab(id)`. */
+  id: string;
+  /** Short label shown beneath the sidebar icon (max ~8 characters). */
+  shortName: string;
+  /** Full title shown in menus and the command palette. */
+  tabName: string;
+  /** One-line description shown in the command palette. */
+  tabDescription: string;
+  /** Keywords used for command-palette fuzzy search. */
+  keywords: string[];
+  /** Whether the tab is built into Lumiverse or contributed by another extension. */
+  source: "builtin" | "extension";
+  /** For extension-contributed tabs, the owning extension's identifier. */
+  extensionId?: string;
+}
+
+/**
+ * Read-only snapshot of a settings tab discoverable via
+ * {@link SpindleAPI.ui.getSettingsTabs}. Restricted entries (`role` set) are
+ * filtered out when the call resolves to a user that lacks the required role.
+ */
+export interface SpindleUISettingsTabDTO {
+  /** Stable id used by `openSettings(id)`. */
+  id: string;
+  /** Short label shown in the settings sidebar. */
+  shortName: string;
+  /** Full title shown in the settings header / command palette. */
+  tabName: string;
+  /** One-line description shown in the command palette. */
+  tabDescription: string;
+  /** Keywords used for command-palette fuzzy search. */
+  keywords: string[];
+  /** Set when the tab is only visible to certain roles. */
+  role?: "admin" | "owner";
+}
+
 // ─── Frontend Process Lifecycle DTOs ────────────────────────────────────
 
 /** High-level lifecycle state for a frontend process tracked by the backend host. */
@@ -2590,7 +2772,24 @@ export type WorkerToHost =
       scrape?: boolean;
       userId?: string;
     }
-  | { type: "web_search_get_settings"; requestId: string; userId?: string };
+  | { type: "web_search_get_settings"; requestId: string; userId?: string }
+  // ─── UI Automation (free tier) ────────────────────────────────────────
+  | { type: "ui_get_drawer_tabs"; requestId: string; userId?: string }
+  | { type: "ui_get_settings_tabs"; requestId: string; userId?: string }
+  | {
+      type: "ui_navigate";
+      requestId: string;
+      action:
+        | "open_drawer_tab"
+        | "close_drawer"
+        | "open_settings"
+        | "close_settings"
+        | "open_command_palette"
+        | "close_command_palette";
+      tabId?: string;
+      viewId?: string;
+      userId?: string;
+    };
 
 // ─── Host → Worker messages ──────────────────────────────────────────────
 

package/src/index.ts

@@ -29,6 +29,11 @@ export type {
   ToolSchemaDTO,
   ToolCallDTO,
   GenerationRequestDTO,
+  GenerationReasoningOverrideDTO,
+  ReasoningEffortDTO,
+  ReasoningSettingsDTO,
+  ThinkingDisplayDTO,
+  ConnectionReasoningBindingsDTO,
   ChatAppendGenerationOptionsDTO,
   ChatAppendMessageOptionsDTO,
   StreamChunkDTO,
@@ -121,6 +126,8 @@ export type {
   SpindleModalItemDTO,
    SpindleCommandDTO,
    SpindleCommandContextDTO,
+   SpindleUIDrawerTabDTO,
+   SpindleUISettingsTabDTO,
    FrontendProcessStateDTO,
    FrontendProcessExitReasonDTO,
    FrontendProcessSpawnOptionsDTO,

package/src/spindle-api.ts

@@ -72,6 +72,8 @@ import type {
   SpindleModalItemDTO,
   SpindleCommandDTO,
   SpindleCommandContextDTO,
+  SpindleUIDrawerTabDTO,
+  SpindleUISettingsTabDTO,
   FrontendProcessSpawnOptionsDTO,
   FrontendProcessListOptionsDTO,
   FrontendProcessInfoDTO,
@@ -299,6 +301,21 @@ export interface SpindleAPI {
    * `fetch()` uses, so it composes with `AbortSignal.timeout()` and
    * `AbortSignal.any([...])`.
    *
+   * ## Reasoning / extended thinking
+   *
+   * By default every generation inherits the resolved user's reasoning
+   * settings — the connection's `reasoning_bindings` if any, else the
+   * user-global `reasoningSettings`. The host translates that into the
+   * correct provider-specific knob (`thinking.budget_tokens`,
+   * `thinkingConfig.thinkingLevel`, `reasoning.effort`, `reasoning_effort`,
+   * etc.) so extensions don't have to.
+   *
+   * Use `input.reasoning` to override that resolution per-request:
+   *  - `{ source: "off" }` — disable thinking for one cheap call.
+   *  - `{ source: "custom", effort: "high" }` — dial effort up just for this call.
+   *
+   * See {@link GenerationReasoningOverrideDTO} for the full shape.
+   *
    * @example
    * ```ts
    * const controller = new AbortController()
@@ -614,6 +631,25 @@ export interface SpindleAPI {
   /**
    * Connection profile access (permission: "generation").
    * Returns safe representations — API keys are never exposed.
+   *
+   * The returned DTO carries a typed `reasoning_bindings` view of the
+   * connection's bound reasoning settings (parsed from `metadata.reasoningBindings`).
+   * Pair this with `GenerationRequestDTO.reasoning` to inspect what the
+   * connection is configured for and optionally override it per-request:
+   *
+   * @example
+   * ```ts
+   * const conn = await spindle.connections.get(connId);
+   * const bound = conn?.reasoning_bindings?.settings;
+   * if (bound?.apiReasoning) {
+   *   await spindle.generate.raw({
+   *     messages,
+   *     connection_id: connId,
+   *     // Force the bound effort one tier higher, just for this request.
+   *     reasoning: { source: "custom", apiReasoning: true, effort: "max" },
+   *   });
+   * }
+   * ```
    */
   connections: {
     /**
@@ -1522,6 +1558,77 @@ export interface SpindleAPI {
     getRole(userId?: string): Promise<SpindleUserRoleDTO>;
   };
 
+  /**
+   * UI automation (free tier — no permission needed).
+   *
+   * Enumerate the built-in drawer / settings tabs and trigger navigation
+   * on the user's frontend. Same primitives the Command Palette uses, but
+   * exposed to extensions so agents and automations can guide the user to
+   * the right surface — for example, an onboarding flow that opens the
+   * Connections drawer, or a "fix it" prompt that jumps to the relevant
+   * settings tab.
+   *
+   * Listings include both built-in tabs (mirrored on the backend) and
+   * extension-contributed drawer tabs the user's frontend has registered.
+   * Navigation calls accept any tab id the frontend recognises — including
+   * extension-added ids — so an extension can deep-link into another
+   * extension's tab if it knows the id.
+   *
+   * @example
+   * ```ts
+   * // Enumerate every drawer tab the user can see and surface our own
+   * // command-palette-style picker.
+   * const tabs = await spindle.ui.getDrawerTabs({ userId })
+   * await spindle.modal.open({
+   *   title: "Jump to…",
+   *   items: tabs.map((t) => ({ type: "key_value", label: t.tabName, value: t.tabDescription })),
+   * })
+   *
+   * // Take the user straight to the Connections drawer.
+   * await spindle.ui.openDrawerTab("connections", { userId })
+   * ```
+   */
+  ui: {
+    /**
+     * Read the discoverable drawer tabs (built-in + extension-contributed)
+     * visible to the resolved user. Extension tabs are only included once
+     * the user's frontend has synced its registry over the WebSocket;
+     * during connection bootstrap the list may be limited to built-ins.
+     *
+     * For user-scoped extensions, `userId` defaults to the installer.
+     * Operator-scoped extensions should pass `userId` to scope the call.
+     */
+    getDrawerTabs(options?: { userId?: string }): Promise<SpindleUIDrawerTabDTO[]>;
+    /**
+     * Read the discoverable settings tabs visible to the resolved user.
+     * Restricted tabs (e.g. `role: "owner"`) are filtered out for users
+     * lacking the required role. When `userId` is omitted on operator-scoped
+     * extensions, role gating is skipped and every tab is returned.
+     */
+    getSettingsTabs(options?: { userId?: string }): Promise<SpindleUISettingsTabDTO[]>;
+    /**
+     * Open the drawer to a specific tab. The id is forwarded verbatim, so
+     * extension-contributed tabs are addressable too. The call resolves
+     * once the host has dispatched the navigation event — the frontend
+     * applies it asynchronously.
+     */
+    openDrawerTab(tabId: string, options?: { userId?: string }): Promise<void>;
+    /** Close the drawer if it is currently open. */
+    closeDrawer(options?: { userId?: string }): Promise<void>;
+    /**
+     * Open the settings modal. Pass a settings tab id (e.g. `"connections"`,
+     * `"display"`) to land on a specific view; omit to open the user's last
+     * settings view.
+     */
+    openSettings(viewId?: string, options?: { userId?: string }): Promise<void>;
+    /** Close the settings modal if it is currently open. */
+    closeSettings(options?: { userId?: string }): Promise<void>;
+    /** Open the command palette overlay. */
+    openCommandPalette(options?: { userId?: string }): Promise<void>;
+    /** Close the command palette overlay if it is currently open. */
+    closeCommandPalette(options?: { userId?: string }): Promise<void>;
+  };
+
   /** Show toast notifications in the frontend UI (free tier — no permission needed) */
   toast: {
     success(message: string, options?: { title?: string; duration?: number; /** For operator-scoped extensions only. */ userId?: string }): void;