@harborclient/sdk 1.5.4 → 1.6.1

package/dist/types.d.ts

@@ -3,6 +3,12 @@ import type * as React from 'react';
  * HTTP method supported in the request editor.
  */
 export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
+/**
+ * Transport protocol for a saved request or editor draft.
+ *
+ * HTTP uses the buffered send path. SSE opens a long-lived event stream.
+ */
+export type RequestProtocol = 'http' | 'sse';
 /**
  * A collection-scoped variable for use in request URLs via {{key}} syntax.
  */
@@ -306,6 +312,12 @@ export interface RequestDraft {
      * HTTP method (for example `GET`, `POST`).
      */
     method: string;
+    /**
+     * Transport protocol for the active request (`http` or `sse`).
+     *
+     * When `sse`, the editor uses the SSE session path instead of a buffered send.
+     */
+    protocol?: RequestProtocol;
     /**
      * Request URL including scheme, host, path, and query string.
      */
@@ -956,12 +968,12 @@ export interface StatusBarItemContribution {
  * - `resize-handle` — resizable panel grip (and high-contrast chrome accents)
  * - `variable-token` — `{{variable}}` syntax highlight in editors
  * - `danger`, `danger-light`, `warning`, `success`, `info` — status colors
- * - `method-get`, `method-post`, `method-put`, `method-patch`, `method-delete`, `method-head`, `method-options` — HTTP method badge colors
+ * - `method-get`, `method-post`, `method-put`, `method-patch`, `method-delete`, `method-head`, `method-options`, `method-sse` — HTTP method / SSE badge colors
  * - `scrollbar-track`, `scrollbar-thumb`, `scrollbar-thumb-hover`, `scrollbar-thumb-active` — scrollbar track and thumb colors
  * - `script-stage-before-all`, `script-stage-before-each`, `script-stage-main`, `script-stage-after-each`, `script-stage-after-all` — script row stage accent colors
  * - `terminal` — footer terminal background
  */
-export type ThemeColorToken = 'surface' | 'header' | 'page-header' | 'page-header-text' | 'page-header-muted' | 'sidebar' | 'sidebar-toolbar' | 'sidebar-rail' | 'sidebar-rail-active' | 'sidebar-rail-text' | 'sidebar-rail-separator' | 'sidebar-section' | 'sidebar-section-text' | 'footer' | 'footer-text' | 'footer-muted' | 'footer-icon-active' | 'toolbar-action-active' | 'breadcrumb-background' | 'breadcrumb-segment' | 'breadcrumb-current' | 'git-staged' | 'git-uncommitted' | 'git-unstaged' | 'git-untracked' | 'control' | 'field' | 'separator' | 'text' | 'text-secondary' | 'muted' | 'accent' | 'selection' | 'doc-markdown' | 'tab-unsaved' | 'tab-underline' | 'resize-separator' | 'resize-handle' | 'variable-token' | 'danger' | 'danger-light' | 'warning' | 'success' | 'info' | 'method-get' | 'method-post' | 'method-put' | 'method-patch' | 'method-delete' | 'method-head' | 'method-options' | 'scrollbar-track' | 'scrollbar-thumb' | 'scrollbar-thumb-hover' | 'scrollbar-thumb-active' | 'script-stage-before-all' | 'script-stage-before-each' | 'script-stage-main' | 'script-stage-after-each' | 'script-stage-after-all' | 'terminal';
+export type ThemeColorToken = 'surface' | 'header' | 'page-header' | 'page-header-text' | 'page-header-muted' | 'sidebar' | 'sidebar-toolbar' | 'sidebar-rail' | 'sidebar-rail-active' | 'sidebar-rail-text' | 'sidebar-rail-separator' | 'sidebar-section' | 'sidebar-section-text' | 'footer' | 'footer-text' | 'footer-muted' | 'footer-icon-active' | 'toolbar-action-active' | 'breadcrumb-background' | 'breadcrumb-segment' | 'breadcrumb-current' | 'git-staged' | 'git-uncommitted' | 'git-unstaged' | 'git-untracked' | 'control' | 'field' | 'separator' | 'text' | 'text-secondary' | 'muted' | 'accent' | 'selection' | 'doc-markdown' | 'tab-unsaved' | 'tab-underline' | 'resize-separator' | 'resize-handle' | 'variable-token' | 'danger' | 'danger-light' | 'warning' | 'success' | 'info' | 'method-get' | 'method-post' | 'method-put' | 'method-patch' | 'method-delete' | 'method-head' | 'method-options' | 'method-sse' | 'scrollbar-track' | 'scrollbar-thumb' | 'scrollbar-thumb-hover' | 'scrollbar-thumb-active' | 'script-stage-before-all' | 'script-stage-before-each' | 'script-stage-main' | 'script-stage-after-each' | 'script-stage-after-all' | 'terminal';
 /**
  * HarborClient UI metric token ids (typography and geometry).
  *
@@ -2894,7 +2906,166 @@ export interface PluginLivePageHandle {
     }>;
 }
 /**
- * AI chat pointer APIs available on {@link PluginContext.ai}.
+ * Append-only static instruction bag on {@link PluginAi.instructions}.
+ *
+ * Fragments are merged into the agent system prompt while registered. Plugins
+ * cannot rewrite Harbor's base system prompt.
+ */
+export interface PluginAiInstructions {
+    /**
+     * Appends a fragment merged into the agent system prompt while registered.
+     *
+     * @param text - Instruction text (whitespace-only strings are ignored).
+     * @returns A {@link Disposable} that removes the fragment when disposed.
+     */
+    add(text: string): Disposable;
+    /**
+     * This plugin's currently registered instruction fragments (read-only).
+     */
+    readonly list: readonly string[];
+}
+/**
+ * One conversation message visible to {@link PluginAiBeforeTurnContext} handlers.
+ */
+export interface PluginAiTurnMessage {
+    /**
+     * OpenAI-compatible message role.
+     */
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    /**
+     * Message text content.
+     */
+    content?: string | null;
+}
+/**
+ * Turn-scoped ephemeral instruction bag on {@link PluginAiBeforeTurnContext}.
+ */
+export interface PluginAiTurnInstructions {
+    /**
+     * Appends a fragment for this turn only (ephemeral system message).
+     *
+     * @param text - Instruction text.
+     */
+    push(text: string): void;
+    /**
+     * Fragments pushed for this turn so far.
+     */
+    readonly list: readonly string[];
+}
+/**
+ * Mutable context passed to {@link PluginAi.onBeforeTurn} once per user chat turn.
+ *
+ * Fires before the first LLM completion step. Mutating {@link userMessage.content}
+ * changes model-facing text for this turn only (not the persisted DB row).
+ */
+export interface PluginAiBeforeTurnContext {
+    /**
+     * Chat row id.
+     */
+    chatId: number;
+    /**
+     * Model id selected in the composer.
+     */
+    model: string;
+    /**
+     * Team Hub id when the selected model is hub-proxied.
+     */
+    hubId?: string;
+    /**
+     * The user message driving this turn.
+     */
+    userMessage: {
+        /**
+         * Model-facing user text (mutable).
+         */
+        content: string;
+        /**
+         * Read-only `@` reference snapshots already collected for this send.
+         */
+        readonly referenceSnapshots?: Record<string, unknown>;
+    };
+    /**
+     * Turn-only instruction fragments (appended after static plugin instructions).
+     */
+    instructions: PluginAiTurnInstructions;
+    /**
+     * Conversation history that will be sent (excluding Harbor's base system prompt).
+     */
+    messages: PluginAiTurnMessage[];
+    /**
+     * Aborts the turn before any LLM call.
+     *
+     * @param reason - Optional user-facing cancel reason.
+     */
+    cancel(reason?: string): void;
+}
+/**
+ * Read-only result passed to {@link PluginAi.onAfterTurn} when a user turn ends.
+ */
+export interface PluginAiAfterTurnContext {
+    /**
+     * Chat row id.
+     */
+    chatId: number;
+    /**
+     * Model id used for the turn.
+     */
+    model: string;
+    /**
+     * Team Hub id when hub-proxied.
+     */
+    hubId?: string;
+    /**
+     * User text that drove this turn (after before-turn rewrites).
+     */
+    userMessage: {
+        /**
+         * User message content.
+         */
+        content: string;
+    };
+    /**
+     * Final assistant text persisted for the turn, if any.
+     */
+    assistantMessage: {
+        /**
+         * Assistant message content.
+         */
+        content: string;
+    } | null;
+    /**
+     * How the turn ended.
+     */
+    status: 'completed' | 'cancelled' | 'error';
+    /**
+     * Error details when {@link status} is `error`.
+     */
+    error?: {
+        /**
+         * User-facing error message.
+         */
+        message: string;
+    };
+    /**
+     * Cheap telemetry from the tool loop.
+     */
+    stats: {
+        /**
+         * Number of `completeChatStep` calls in this turn.
+         */
+        stepCount: number;
+        /**
+         * Number of tool calls executed in this turn.
+         */
+        toolCallCount: number;
+        /**
+         * Wall-clock duration of the turn in milliseconds.
+         */
+        durationMs: number;
+    };
+}
+/**
+ * AI chat pointer, instruction, and turn-hook APIs available on {@link PluginContext.ai}.
  *
  * Requires the `ai` permission. Registrations are activation-scoped.
  */
@@ -2912,6 +3083,24 @@ export interface PluginAi {
      * @param input - Pointer id, key, label, and context text captured by the plugin.
      */
     copyToChat(input: PluginCopyToChatInput): Promise<void>;
+    /**
+     * Append-only static instruction fragments merged into the agent system prompt.
+     */
+    instructions: PluginAiInstructions;
+    /**
+     * Registers a callback that runs once per user chat turn before the first LLM step.
+     *
+     * @param handler - Called with a mutable turn context.
+     * @returns A {@link Disposable} that unregisters the handler when disposed.
+     */
+    onBeforeTurn(handler: (ctx: PluginAiBeforeTurnContext) => void | Promise<void>): Disposable;
+    /**
+     * Registers a callback that runs once when a user chat turn finishes.
+     *
+     * @param handler - Called with a read-only turn result.
+     * @returns A {@link Disposable} that unregisters the handler when disposed.
+     */
+    onAfterTurn(handler: (ctx: PluginAiAfterTurnContext) => void | Promise<void>): Disposable;
 }
 /**
  * **File → Import** handler registration available on {@link PluginContext.imports}.
@@ -3386,6 +3575,10 @@ export interface CreateCollectionRequest {
      * HTTP method (for example `GET`, `POST`). Defaults to `GET` when omitted or invalid.
      */
     method?: string;
+    /**
+     * Transport protocol (`http` or `sse`). Defaults to `http` when omitted.
+     */
+    protocol?: 'http' | 'sse';
     /**
      * Request URL including scheme, host, path, and query string.
      */
@@ -3575,6 +3768,10 @@ export interface SavedRequestSummary {
     name: string;
     /** HTTP method. */
     method: HttpMethod;
+    /**
+     * Transport protocol (`http` or `sse`). Defaults to `http` when omitted by older hosts.
+     */
+    protocol?: RequestProtocol;
     /** Sibling sort order. */
     sort_order: number;
     /** Optional sidebar marker color. */
@@ -3836,6 +4033,10 @@ export interface CreateRequestInput {
     name?: string;
     /** HTTP method; defaults to `GET`. */
     method?: HttpMethod;
+    /**
+     * Transport protocol; defaults to `http`. Use `sse` for Server-Sent Events.
+     */
+    protocol?: RequestProtocol;
     /** Request URL; defaults to empty. */
     url?: string;
 }
@@ -4037,7 +4238,10 @@ export interface HostSavedRequest extends SavedRequestSummary {
     updated_at: string;
 }
 /**
- * Input for {@link PluginHost.sendHttpRequest}.
+ * Input for plugin outbound HTTP before conversion to the native fetch API.
+ * Prefer {@link PluginHost.fetch} with `(input, init?)` in new code.
+ *
+ * @deprecated Use fetch(url, init?) instead.
  */
 export interface PluginSendRequestInput {
     /** HTTP method to use. */
@@ -4060,7 +4264,72 @@ export interface PluginSendRequestInput {
     sourceRequestName?: string;
 }
 /**
- * Result of {@link PluginHost.sendHttpRequest}.
+ * Headers-like facade returned by {@link PluginHost.fetch}.
+ */
+export interface PluginFetchHeaders {
+    /**
+     * Returns the first header value for the given name (case-insensitive), or null.
+     *
+     * @param name - Header name.
+     */
+    get(name: string): string | null;
+    /**
+     * Returns true when a header with the given name is present.
+     *
+     * @param name - Header name.
+     */
+    has(name: string): boolean;
+    /**
+     * Iterates header entries as [name, value] pairs.
+     */
+    entries(): IterableIterator<[string, string]>;
+    /**
+     * Iterates header names.
+     */
+    keys(): IterableIterator<string>;
+    /**
+     * Iterates header values.
+     */
+    values(): IterableIterator<string>;
+    /**
+     * Invokes callback for each header entry.
+     *
+     * @param callback - Called with (value, key).
+     */
+    forEach(callback: (value: string, key: string) => void): void;
+}
+/**
+ * Response-compatible result of {@link PluginHost.fetch}.
+ */
+export interface PluginFetchResponse {
+    /** True when status is in the 200–299 range. */
+    readonly ok: boolean;
+    /** HTTP status code. */
+    readonly status: number;
+    /** HTTP status text. */
+    readonly statusText: string;
+    /** Response headers. */
+    readonly headers: PluginFetchHeaders;
+    /** Returns the response body as text. */
+    text(): Promise<string>;
+    /** Parses the response body as JSON. */
+    json(): Promise<unknown>;
+    /** Returns the response body as an ArrayBuffer (UTF-8 bytes of the text body). */
+    arrayBuffer(): Promise<ArrayBuffer>;
+}
+/**
+ * RequestInit-compatible options for {@link PluginHost.fetch}.
+ */
+export interface PluginFetchInit {
+    /** HTTP method (default GET). */
+    method?: string;
+    /** Request headers as a record, header list, or Headers-like object. */
+    headers?: Record<string, string> | Array<[string, string]> | PluginFetchHeaders;
+    /** Request body. Only strings and URLSearchParams are supported. */
+    body?: string | URLSearchParams | null;
+}
+/**
+ * Result of a plugin-initiated HTTP send used by console logging and history.
  */
 export interface PluginSendResult {
     /** HTTP status code, or 0 when the request failed before a response. */
@@ -4086,7 +4355,7 @@ export interface PluginSendResult {
 /**
  * Typed wrappers for built-in HarborClient request editor commands.
  *
- * Requires the `ui` permission (except {@link PluginHost.sendHttpRequest}, which
+ * Requires the `ui` permission (except {@link PluginHost.fetch}, which
  * requires `network`). Prefer these over stringly-typed
  * {@link PluginCommands.execute} for opening request tabs.
  */
@@ -4199,7 +4468,7 @@ export interface PluginHost {
      *
      * No-op when a send is already in flight for the active tab.
      */
-    sendRequest(): Promise<void>;
+    send(): Promise<void>;
     /**
      * Creates a new environment, populates it with variables, and selects it as active.
      *
@@ -4534,14 +4803,18 @@ export interface PluginHost {
         result: PluginSendResult;
     }): Promise<void>;
     /**
-     * Sends one HTTP request through the main-process pipeline, bypassing the
-     * renderer's CORS restrictions. Failures resolve to an error result.
+     * Sends one HTTP request through the main-process pipeline using the native
+     * fetch(input, init?) signature. Failures resolve to a Response-like object
+     * with status 0 rather than throwing.
      *
      * Requires the `network` permission.
      *
-     * @param input - Request configuration to execute.
+     * @param input - URL string, URL, or Request-like `{ url }` object.
+     * @param init - Optional RequestInit-compatible options.
      */
-    sendHttpRequest(input: PluginSendRequestInput): Promise<PluginSendResult>;
+    fetch(input: string | URL | {
+        url: string;
+    }, init?: PluginFetchInit): Promise<PluginFetchResponse>;
     /**
      * Clears the active request tab's last HTTP response so plugin-only response
      * views can take over the panel.