lumiverse-spindle-types 0.4.21 → 0.4.24

package/package.json

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

package/src/api.ts

@@ -66,8 +66,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>;
@@ -924,6 +983,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 }
@@ -1243,4 +1314,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/index.ts

@@ -20,6 +20,7 @@ export type {
   ToolSchemaDTO,
   ToolCallDTO,
   GenerationRequestDTO,
+  StreamChunkDTO,
   RequestInitDTO,
   ConnectionProfileDTO,
   PermissionDeniedDetail,

package/src/spindle-api.ts

@@ -45,6 +45,7 @@ import type {
   GenerationStoppedPayloadDTO,
   GenerationObserver,
   MessageSwipedPayloadDTO,
+  StreamChunkDTO,
 } from "./api";
 
 /** The global `spindle` object available in backend extension workers */
@@ -102,11 +103,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>;
     /**