@harborclient/sdk 1.5.3 → 1.6.0

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).
  *
@@ -2674,20 +2686,61 @@ export interface PluginLivePages {
      */
     delete(id: number): Promise<void>;
 }
+/**
+ * Structured fields returned by a plugin {@link PluginChatPointerConfig.parse}.
+ *
+ * The host fills `kind`, `pluginId`, `pointerId`, and token offsets/text.
+ */
+export interface PluginChatPointerParseResult {
+    /**
+     * Opaque key identifying the referenced object for this pointer kind.
+     */
+    key: string;
+    /**
+     * Optional character-range selection within the captured context.
+     */
+    selection?: {
+        /**
+         * Inclusive start offset.
+         */
+        start: number;
+        /**
+         * Exclusive end offset.
+         */
+        end: number;
+    };
+}
 /**
  * Config for {@link PluginAi.registerChatPointer}.
  */
 export interface PluginChatPointerConfig {
     /**
-     * Pointer id segment in `@plugin.<pluginId>.<id>.<key>`.
+     * Pointer id segment. Must match `[a-z][a-z0-9-]*`.
      *
-     * Must match `[a-z][a-z0-9-]*`.
+     * With the default grammar this becomes `@plugin.<pluginId>.<id>.<key>`.
+     * With a custom {@link match}, it only identifies the registration.
      */
     id: string;
     /**
      * Static rules merged into the agent system prompt while the plugin is loaded.
      */
     agentGuidance?: string;
+    /**
+     * Regex for the token body after `@` (no leading `@`).
+     *
+     * Required together with {@link parse}. Omit both for the default
+     * `@plugin.<pluginId>.<id>.<key>` grammar. Must not collide with reserved
+     * builtin prefixes (`request`, `res`, `term`, `plugin`, …).
+     */
+    match?: RegExp | string;
+    /**
+     * Maps a successful {@link match} into key/selection (or null to reject).
+     *
+     * Required when {@link match} is set. Runs in the plugin webview; the host
+     * uses a sync fallback for composer highlighting and re-invokes this at
+     * send/validate over IPC.
+     */
+    parse?: (match: RegExpMatchArray, fullToken: string, atIndex: number) => PluginChatPointerParseResult | null;
 }
 /**
  * Input for {@link PluginAi.copyToChat}.
@@ -2698,9 +2751,15 @@ export interface PluginCopyToChatInput {
      */
     pointerId: string;
     /**
-     * Opaque key segment after the pointer id (no spaces). Host builds the full token.
+     * Opaque key for the default `@plugin…` grammar. Required when the pointer
+     * did not register a custom {@link PluginChatPointerConfig.match}.
      */
-    key: string;
+    key?: string;
+    /**
+     * Full composer token including leading `@`. Required when the pointer
+     * registered a custom {@link PluginChatPointerConfig.match}.
+     */
+    token?: string;
     /**
      * Badge label shown in the AI composer and message bubbles.
      */
@@ -2710,7 +2769,8 @@ export interface PluginCopyToChatInput {
      */
     context: string;
     /**
-     * Optional character-range selection appended as `#start.end` on the token.
+     * Optional character-range selection (default grammar appends `#start.end`;
+     * custom tokens may already include a selection suffix).
      */
     selection?: {
         /**
@@ -2846,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.
  */
@@ -2864,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}.
@@ -3338,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.
      */
@@ -3527,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. */
@@ -3788,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;
 }
@@ -3989,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. */
@@ -4012,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. */
@@ -4038,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.
  */
@@ -4151,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.
      *
@@ -4486,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.