lumiverse-spindle-types 0.4.21 → 0.4.25

package/package.json

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

package/src/api.ts

@@ -1,4 +1,5 @@
 import type { SpindleManifest } from "./manifest";
+import type { CouncilMemberContext } from "./council";
 
 // ─── DTO types for messages ──────────────────────────────────────────────
 
@@ -66,8 +67,67 @@ export interface GenerationRequestDTO {
    * is inferred from the extension owner and can be omitted.
    */
   userId?: string;
+  /**
+   * Optional `AbortSignal` to cancel an in-flight generation. When the
+   * signal fires, the upstream LLM HTTP request is torn down and the
+   * returned promise rejects with an `AbortError` (`err.name === "AbortError"`).
+   *
+   * The signal is consumed inside the extension worker and never crosses
+   * the host boundary — it is stripped before the RPC message is posted.
+   * The worker notifies the host via an internal `cancel_generation`
+   * message so the host can abort the in-flight request.
+   *
+   * @example
+   * ```ts
+   * const controller = new AbortController()
+   * const timer = setTimeout(() => controller.abort(), 10_000)
+   * try {
+   *   const result = await spindle.generate.raw({
+   *     provider: "openai",
+   *     model: "gpt-4o-mini",
+   *     messages: [{ role: "user", content: "hello" }],
+   *     signal: controller.signal,
+   *   })
+   * } catch (err) {
+   *   if (err instanceof Error && err.name === "AbortError") {
+   *     // user/timeout cancelled — not an error condition
+   *   }
+   * } finally {
+   *   clearTimeout(timer)
+   * }
+   * ```
+   */
+  signal?: AbortSignal;
 }
 
+/**
+ * Streamed chunk yielded by `spindle.generate.rawStream()` and
+ * `spindle.generate.quietStream()`.
+ *
+ * The stream emits one or more `token` / `reasoning` chunks and then
+ * exactly one terminal `done` chunk carrying the aggregated response.
+ * If the stream fails or is aborted, the async generator rejects instead
+ * of emitting `done`.
+ */
+export type StreamChunkDTO =
+  /** Incremental content token. */
+  | { type: "token"; token: string }
+  /** Incremental chain-of-thought / reasoning token. */
+  | { type: "reasoning"; token: string }
+  /** Terminal chunk — emitted exactly once, on successful completion. */
+  | {
+      type: "done";
+      content: string;
+      reasoning?: string;
+      finish_reason: string;
+      tool_calls?: ToolCallDTO[];
+      usage?: {
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+      };
+    };
+
 export interface RequestInitDTO {
   method?: string;
   headers?: Record<string, string>;
@@ -887,6 +947,29 @@ export interface MessageSwipedPayloadDTO {
   previousSwipeId?: number;
 }
 
+/**
+ * Payload delivered to `spindle.on("TOOL_INVOCATION", ...)` handlers.
+ *
+ * Fires whenever an extension-registered tool is invoked by Lumiverse. Handlers
+ * must return a string (or promise thereof) with the tool's result — the host
+ * coerces `undefined` / `null` to an empty string.
+ *
+ * `councilMember` is populated when the invocation originates from a council
+ * execution cycle, providing the assigned member's identity, role, chance,
+ * avatar URL, and Lumia personality fields. It is `undefined` for all other
+ * invocation paths.
+ */
+export interface ToolInvocationPayloadDTO {
+  /** The bare (unqualified) tool name, matching what was passed to `registerTool`. */
+  toolName: string;
+  /** Arguments delivered to the tool. Shape depends on the tool's JSON Schema. */
+  args: Record<string, unknown>;
+  /** Host-side correlation id for this invocation. */
+  requestId: string;
+  /** Council member snapshot when invoked via council — otherwise `undefined`. */
+  councilMember?: CouncilMemberContext;
+}
+
 /**
  * Observer handle returned by `spindle.generate.observe()`.
  * Provides a high-level API for watching an in-flight generation on a
@@ -924,6 +1007,18 @@ export type WorkerToHost =
   | { type: "register_tool"; tool: ToolRegistrationDTO }
   | { type: "unregister_tool"; name: string }
   | { type: "request_generation"; requestId: string; input: GenerationRequestDTO }
+  /**
+   * Start a streaming generation. The host responds asynchronously with
+   * one or more `generation_stream_chunk` messages, terminating with a
+   * `done` chunk on success or a `generation_stream_error` on failure.
+   */
+  | { type: "request_generation_stream"; requestId: string; input: GenerationRequestDTO }
+  /**
+   * Cancel an in-flight generation started via `request_generation` or
+   * `request_generation_stream`. `requestId` matches the original request.
+   * The host aborts the upstream LLM fetch and responds with an `AbortError`.
+   */
+  | { type: "cancel_generation"; requestId: string }
   | { type: "storage_read"; requestId: string; path: string }
   | { type: "storage_write"; requestId: string; path: string; data: string }
   | { type: "storage_read_binary"; requestId: string; path: string }
@@ -1230,6 +1325,15 @@ export type HostToWorker =
       requestId: string;
       toolName: string;
       args: Record<string, unknown>;
+      /**
+       * Populated when the invocation originates from a council execution
+       * cycle — carries the assigned council member's identity, role, chance,
+       * avatar URL, and Lumia personality fields so the extension can tailor
+       * its tool pipeline to the member on whose behalf it is running.
+       *
+       * Undefined for non-council invocation paths.
+       */
+      councilMember?: CouncilMemberContext;
     }
   | { type: "shutdown" }
   | { type: "frontend_message"; payload: unknown; userId: string }
@@ -1243,4 +1347,16 @@ export type HostToWorker =
       commandId: string;
       context: SpindleCommandContextDTO;
       userId: string;
-    };
+    }
+  /**
+   * One streamed chunk for a generation started via
+   * `request_generation_stream`. Multiple `token` / `reasoning` chunks
+   * may arrive, terminating with exactly one `done` chunk on success.
+   */
+  | { type: "generation_stream_chunk"; requestId: string; chunk: StreamChunkDTO }
+  /**
+   * Terminal failure for a generation started via
+   * `request_generation_stream`. Mutually exclusive with the `done`
+   * chunk in `generation_stream_chunk`. Aborts surface here too.
+   */
+  | { type: "generation_stream_error"; requestId: string; error: string };

package/src/council.ts

@@ -77,6 +77,47 @@ export interface CouncilSettings {
   toolsSettings: CouncilToolsSettings;
 }
 
+// ---- Tool Invocation Context ----
+
+/**
+ * Personality snapshot of the council member that triggered a tool invocation.
+ *
+ * Delivered to extension `TOOL_INVOCATION` handlers when an extension-provided
+ * council tool is executed as part of a council cycle. Allows extensions to
+ * personalise their tool pipeline with the assigned member's identity, role,
+ * and Lumia personality fields.
+ *
+ * This field is optional — it is only populated when the tool is invoked via
+ * the council execution path. Tools invoked outside council (e.g. future
+ * inline function calling) will not see this context.
+ */
+export interface CouncilMemberContext {
+  /** Unique council member id (council settings row id). */
+  memberId: string;
+  /** Source Lumia item id this member is backed by. */
+  itemId: string;
+  /** Pack id the Lumia item lives in. */
+  packId: string;
+  /** Pack name the Lumia item lives in. */
+  packName: string;
+  /** Display name of the Lumia item (also used as the member name). */
+  name: string;
+  /** Freeform role description assigned by the user (e.g. "Plot Enforcer"). */
+  role: string;
+  /** Probability (0–100) that this member participates each generation. */
+  chance: number;
+  /** Relative URL to the member's avatar (e.g. `/api/v1/images/{id}`), or null. */
+  avatarUrl: string | null;
+  /** Lumia item "definition" field — physical/identity description. */
+  definition: string;
+  /** Lumia item "personality" field. */
+  personality: string;
+  /** Lumia item "behavior" field — behavioural patterns. */
+  behavior: string;
+  /** Gender identity marker (0=unspecified, 1=feminine, 2=masculine). */
+  genderIdentity: 0 | 1 | 2;
+}
+
 // ---- Execution Results ----
 
 /** Result of a single tool invocation for a single member. */

package/src/index.ts

@@ -20,6 +20,7 @@ export type {
   ToolSchemaDTO,
   ToolCallDTO,
   GenerationRequestDTO,
+  StreamChunkDTO,
   RequestInitDTO,
   ConnectionProfileDTO,
   PermissionDeniedDetail,
@@ -70,6 +71,7 @@ export type {
   ChatMessageDTO,
   MessageSwipeAction,
   MessageSwipedPayloadDTO,
+  ToolInvocationPayloadDTO,
   WorkerToHost,
   HostToWorker,
 } from "./api";
@@ -113,6 +115,7 @@ export type { SpindleAPI } from "./spindle-api";
 
 export type {
   CouncilMember,
+  CouncilMemberContext,
   SidecarConfig,
   CouncilSidecarConfig,
   CouncilToolsSettings,

package/src/spindle-api.ts

@@ -45,6 +45,8 @@ import type {
   GenerationStoppedPayloadDTO,
   GenerationObserver,
   MessageSwipedPayloadDTO,
+  ToolInvocationPayloadDTO,
+  StreamChunkDTO,
 } from "./api";
 
 /** The global `spindle` object available in backend extension workers */
@@ -63,6 +65,21 @@ export interface SpindleAPI {
    * `swipeId` identifies which slot the event concerns.
    */
   on(event: "MESSAGE_SWIPED", handler: (payload: MessageSwipedPayloadDTO, userId?: string) => void): () => void;
+  /**
+   * Receive invocations for tools registered via {@link SpindleAPI.registerTool}.
+   *
+   * The handler must return the tool's textual result (or a promise thereof).
+   * Undefined / null returns are coerced to an empty string by the host.
+   *
+   * When the invocation originates from a council execution cycle, the payload
+   * includes a `councilMember` snapshot describing the assigned member
+   * (identity, role, chance, avatar URL, and Lumia personality fields) so the
+   * extension can tailor its tool output to that member's voice.
+   */
+  on(
+    event: "TOOL_INVOCATION",
+    handler: (payload: ToolInvocationPayloadDTO) => string | Promise<string> | void | Promise<void>
+  ): () => void;
   /** Subscribe to a Lumiverse event. */
   on(event: string, handler: (payload: unknown, userId?: string) => void): () => void;
 
@@ -102,11 +119,76 @@ export interface SpindleAPI {
   /** Unregister an LLM tool */
   unregisterTool(name: string): void;
 
-  /** Generation helpers */
+  /**
+   * Generation helpers.
+   *
+   * All three entry points (`raw`, `quiet`, `batch`) accept a standard
+   * `AbortSignal` via `input.signal`. Aborting the signal tears down the
+   * upstream LLM HTTP request and rejects the returned promise with an
+   * `AbortError` (`err.name === "AbortError"`). This is the same pattern
+   * `fetch()` uses, so it composes with `AbortSignal.timeout()` and
+   * `AbortSignal.any([...])`.
+   *
+   * @example
+   * ```ts
+   * const controller = new AbortController()
+   * const result = spindle.generate.raw({
+   *   provider: "openai",
+   *   model: "gpt-4o-mini",
+   *   messages,
+   *   signal: controller.signal,
+   * })
+   * // Cancel from elsewhere — e.g. user closed the panel
+   * controller.abort()
+   * ```
+   */
   generate: {
     raw(input: GenerationRequestDTO): Promise<unknown>;
     quiet(input: GenerationRequestDTO): Promise<unknown>;
     batch(input: GenerationRequestDTO): Promise<unknown>;
+    /**
+     * Streaming variant of {@link raw}. Returns an async generator that
+     * yields incremental {@link StreamChunkDTO} values:
+     *
+     *  - `{ type: 'token', token }`     — content chunk
+     *  - `{ type: 'reasoning', token }` — chain-of-thought chunk
+     *  - `{ type: 'done', ... }`        — final aggregated response (emitted exactly once)
+     *
+     * Tool-call deltas, finish reason, and token usage live on the terminal
+     * `done` chunk. If the upstream call fails or the request is aborted
+     * via `input.signal`, the generator rejects with the underlying error
+     * (`AbortError` for cancellations).
+     *
+     * @example
+     * ```ts
+     * const ctrl = new AbortController()
+     * setTimeout(() => ctrl.abort(), 30_000)
+     * try {
+     *   for await (const chunk of spindle.generate.rawStream({
+     *     provider: 'openai',
+     *     model: 'gpt-4o-mini',
+     *     messages,
+     *     signal: ctrl.signal,
+     *   })) {
+     *     if (chunk.type === 'token') process.stdout.write(chunk.token)
+     *     else if (chunk.type === 'done') usage = chunk.usage
+     *   }
+     * } catch (err) {
+     *   if (err instanceof Error && err.name === 'AbortError') return
+     *   throw err
+     * }
+     * ```
+     */
+    rawStream(input: GenerationRequestDTO): AsyncGenerator<StreamChunkDTO, void, void>;
+    /**
+     * Streaming variant of {@link quiet}. Same chunk schema and abort
+     * semantics as {@link rawStream}.
+     *
+     * Note: streaming is not exposed for `batch` — compose multiple
+     * `rawStream` / `quietStream` calls yourself if you need parallel
+     * streamed responses.
+     */
+    quietStream(input: GenerationRequestDTO): AsyncGenerator<StreamChunkDTO, void, void>;
     /** Run a dry-run prompt assembly without calling the LLM. */
     dryRun(input: DryRunRequestDTO, userId?: string): Promise<DryRunResultDTO>;
     /**