@harborclient/sdk 1.5.4 → 1.6.1

package/dist/runtime/createBridgedPluginContext.js

@@ -28,6 +28,28 @@ let importRegistrationCounter = 0;
 /** Monotonic id generator for MCP server registrations within one webview. */
 let mcpRegistrationCounter = 0;
 let aiChatPointerRegistrationCounter = 0;
+let aiInstructionsRegistrationCounter = 0;
+
+/**
+ * Before-turn handlers registered via `hc.ai.onBeforeTurn`.
+ *
+ * @type {Set<(ctx: import('../types').PluginAiBeforeTurnContext) => void | Promise<void>>}
+ */
+const aiBeforeTurnHandlers = new Set();
+
+/**
+ * After-turn handlers registered via `hc.ai.onAfterTurn`.
+ *
+ * @type {Set<(ctx: import('../types').PluginAiAfterTurnContext) => void | Promise<void>>}
+ */
+const aiAfterTurnHandlers = new Set();
+
+/**
+ * Local instruction texts keyed by registration id (for `hc.ai.instructions.list`).
+ *
+ * @type {Map<string, string>}
+ */
+const aiInstructionsByRegistrationId = new Map();
 
 /** Plugin id prefix for built-in HarborClient host commands executed in the renderer. */
 const HOST_COMMAND_OWNER = 'harborclient';
@@ -38,6 +60,12 @@ let importInvokeListenerInstalled = false;
 /** Guards repeated chat-pointer parse listener installation per webview load. */
 let aiParseChatPointerListenerInstalled = false;
 
+/** Guards repeated before-turn listener installation per webview load. */
+let aiBeforeTurnListenerInstalled = false;
+
+/** Guards repeated after-turn listener installation per webview load. */
+let aiAfterTurnListenerInstalled = false;
+
 /**
  * Normalizes a file extension to lowercase with a leading dot.
  *
@@ -133,7 +161,11 @@ export function installImportInvokeListener() {
 export function resetMcpServersForTests() {
   mcpRegistrationCounter = 0;
   aiChatPointerRegistrationCounter = 0;
+  aiInstructionsRegistrationCounter = 0;
   chatPointerParseByRegistrationId.clear();
+  aiInstructionsByRegistrationId.clear();
+  aiBeforeTurnHandlers.clear();
+  aiAfterTurnHandlers.clear();
 }
 
 /**
@@ -144,6 +176,8 @@ export function resetImportHandlersForTests() {
   importRegistrationCounter = 0;
   importInvokeListenerInstalled = false;
   aiParseChatPointerListenerInstalled = false;
+  aiBeforeTurnListenerInstalled = false;
+  aiAfterTurnListenerInstalled = false;
   resetMcpServersForTests();
 }
 
@@ -211,6 +245,113 @@ export function installAiParseChatPointerListener() {
   });
 }
 
+/**
+ * Subscribes to host-initiated before-turn invocations for the agent webview.
+ *
+ * Must run once before plugin activation so chat sends can reach registered handlers.
+ */
+export function installAiBeforeTurnListener() {
+  if (aiBeforeTurnListenerInstalled) {
+    return;
+  }
+  aiBeforeTurnListenerInstalled = true;
+
+  bridgeOn('ai.beforeTurn', async (payload) => {
+    const { requestId, chatId, model, hubId, userMessage, messages } = payload ?? {};
+    if (requestId == null) {
+      return;
+    }
+
+    try {
+      const extraInstructions = [];
+      let cancelled = false;
+      let cancelReason;
+      const userMessageState = {
+        content: String(userMessage?.content ?? ''),
+        ...(userMessage?.referenceSnapshots != null
+          ? { referenceSnapshots: userMessage.referenceSnapshots }
+          : {})
+      };
+      /** @type {import('../types').PluginAiBeforeTurnContext} */
+      const ctx = {
+        chatId: Number(chatId) || 0,
+        model: String(model ?? ''),
+        ...(hubId != null && String(hubId).trim() !== '' ? { hubId: String(hubId) } : {}),
+        userMessage: userMessageState,
+        instructions: {
+          push: (text) => {
+            const trimmed = String(text ?? '').trim();
+            if (trimmed) {
+              extraInstructions.push(trimmed);
+            }
+          },
+          get list() {
+            return [...extraInstructions];
+          }
+        },
+        messages: Array.isArray(messages)
+          ? messages.map((row) => ({
+              role: row?.role ?? 'user',
+              content: row?.content ?? null
+            }))
+          : [],
+        cancel: (reason) => {
+          cancelled = true;
+          if (reason != null && String(reason).trim() !== '') {
+            cancelReason = String(reason).trim();
+          }
+        }
+      };
+
+      for (const handler of [...aiBeforeTurnHandlers]) {
+        await handler(ctx);
+        if (cancelled) {
+          break;
+        }
+      }
+
+      await bridgeInvoke('ai.beforeTurnComplete', {
+        requestId,
+        ok: true,
+        result: {
+          cancelled,
+          ...(cancelReason != null ? { cancelReason } : {}),
+          userContent: ctx.userMessage.content,
+          extraInstructions
+        }
+      });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      await bridgeInvoke('ai.beforeTurnComplete', {
+        requestId,
+        ok: false,
+        error: message
+      });
+    }
+  });
+}
+
+/**
+ * Subscribes to host-initiated after-turn push events for the agent webview.
+ *
+ * Must run once before plugin activation.
+ */
+export function installAiAfterTurnListener() {
+  if (aiAfterTurnListenerInstalled) {
+    return;
+  }
+  aiAfterTurnListenerInstalled = true;
+
+  bridgeOn('ai.afterTurn', (payload) => {
+    const ctx = /** @type {import('../types').PluginAiAfterTurnContext} */ (payload);
+    for (const handler of [...aiAfterTurnHandlers]) {
+      void Promise.resolve(handler(ctx)).catch((error) => {
+        console.error('Plugin ai.onAfterTurn handler failed:', error);
+      });
+    }
+  });
+}
+
 /**
  * Normalizes one MCP header row from plugin registration input.
  *
@@ -414,6 +555,11 @@ export function createBridgedPluginContext({ pluginId, mode, contributionId, rea
    */
   const assertUi = () => assertPermission('ui');
 
+  /**
+   * Asserts network permission for outbound HTTP via hc.host.fetch.
+   */
+  const assertNetwork = () => assertPermission('network');
+
   /**
    * Returns whether UI registration should run in this webview role.
    */
@@ -1156,9 +1302,9 @@ export function createBridgedPluginContext({ pluginId, mode, contributionId, rea
           }
         });
       },
-      sendRequest: async () => {
+      send: async () => {
         assertUi();
-        await bridgeInvoke('host.sendRequest');
+        await bridgeInvoke('host.send');
       },
       createEnvironmentWithVariables: async (name, variables) => {
         assertUi();
@@ -1330,9 +1476,9 @@ export function createBridgedPluginContext({ pluginId, mode, contributionId, rea
         assertUi();
         await bridgeInvoke('host.logRequestToConsole', { payload });
       },
-      sendHttpRequest: async (input) => {
-        assertUi();
-        return bridgeInvoke('host.sendHttpRequest', { input });
+      fetch: async (input, init) => {
+        assertNetwork();
+        return bridgeInvoke('host.fetch', { input, init });
       },
       clearResponse: async () => {
         assertUi();
@@ -1519,6 +1665,56 @@ export function createBridgedPluginContext({ pluginId, mode, contributionId, rea
           context: String(input?.context ?? ''),
           selection: input?.selection
         });
+      },
+      instructions: {
+        add: (text) => {
+          assertAi();
+          if (!isAgent) {
+            return noopDisposable();
+          }
+          const trimmed = String(text ?? '').trim();
+          const registrationId = String(++aiInstructionsRegistrationCounter);
+          if (trimmed) {
+            aiInstructionsByRegistrationId.set(registrationId, trimmed);
+          }
+          void bridgeInvoke('ai.registerInstructions', {
+            registrationId,
+            text: trimmed
+          });
+          return track(() => {
+            aiInstructionsByRegistrationId.delete(registrationId);
+            void bridgeInvoke('ai.unregisterInstructions', { registrationId });
+          });
+        },
+        get list() {
+          return [...aiInstructionsByRegistrationId.values()];
+        }
+      },
+      onBeforeTurn: (handler) => {
+        assertAi();
+        if (!isAgent) {
+          return noopDisposable();
+        }
+        if (typeof handler !== 'function') {
+          throw new Error('onBeforeTurn handler must be a function.');
+        }
+        aiBeforeTurnHandlers.add(handler);
+        return track(() => {
+          aiBeforeTurnHandlers.delete(handler);
+        });
+      },
+      onAfterTurn: (handler) => {
+        assertAi();
+        if (!isAgent) {
+          return noopDisposable();
+        }
+        if (typeof handler !== 'function') {
+          throw new Error('onAfterTurn handler must be a function.');
+        }
+        aiAfterTurnHandlers.add(handler);
+        return track(() => {
+          aiAfterTurnHandlers.delete(handler);
+        });
       }
     },
     /**

package/dist/runtime/viewHost.js

@@ -2,6 +2,8 @@ import { clearContributionRegistry } from './contributionRegistry.js';
 import {
   createBridgedPluginContext,
   executeLocalPluginCommand,
+  installAiAfterTurnListener,
+  installAiBeforeTurnListener,
   installAiParseChatPointerListener,
   installImportInvokeListener,
   mountContributionView,
@@ -74,6 +76,8 @@ export async function bootstrapViewHost(options = {}) {
   if (parsedRole.mode === 'agent') {
     installImportInvokeListener();
     installAiParseChatPointerListener();
+    installAiBeforeTurnListener();
+    installAiAfterTurnListener();
   }
 
   await module.activate(hc);

package/dist/snippets.d.ts

@@ -246,28 +246,37 @@ interface HcInfoApi {
 }
 
 /**
- * Outbound request payload accepted by hc.sendRequest.
+ * RequestInit-compatible options accepted by hc.fetch.
  */
-interface HcSendRequestInput {
+interface HcFetchInit {
   method?: string;
-  url: string;
-  headers?: Array<{ key: string; value: string; enabled?: boolean }> | Record<string, string>;
-  params?: Array<{ key: string; value: string; enabled?: boolean }>;
-  body?: string;
-  bodyType?: 'none' | 'json' | 'text' | 'multipart' | 'urlencoded';
-  body_type?: 'none' | 'json' | 'text' | 'multipart' | 'urlencoded';
+  headers?: Record<string, string> | Array<[string, string]>;
+  body?: string | URLSearchParams | null;
 }
 
 /**
- * Response snapshot returned by hc.sendRequest.
+ * Headers-like facade returned by hc.fetch.
  */
-interface HcSendRequestResponse {
-  readonly code: number;
-  readonly status: string;
-  readonly headers: Record<string, string>;
-  readonly responseTime: number;
-  text(): string;
-  json(): unknown;
+interface HcFetchHeaders {
+  get(name: string): string | null;
+  has(name: string): boolean;
+  entries(): IterableIterator<[string, string]>;
+  keys(): IterableIterator<string>;
+  values(): IterableIterator<string>;
+  forEach(callback: (value: string, key: string) => void): void;
+}
+
+/**
+ * Response-compatible object returned by hc.fetch.
+ */
+interface HcFetchResponse {
+  readonly ok: boolean;
+  readonly status: number;
+  readonly statusText: string;
+  readonly headers: HcFetchHeaders;
+  text(): Promise<string>;
+  json(): Promise<unknown>;
+  arrayBuffer(): Promise<ArrayBuffer>;
 }
 
 /**
@@ -468,12 +477,14 @@ interface HcScriptApi {
   /** Read-only metadata about the current script run (Postman pm.info equivalent). */
   info: HcInfoApi;
   /**
-   * Sends an outbound HTTP request from the script sandbox.
+   * Sends an outbound HTTP request using the native fetch(input, init?) signature.
    * Requires Settings → General → Allow script network requests.
    *
-   * @throws When the setting is disabled or sendRequest is unavailable in this context.
+   * @param input - URL string, URL, or Request-like `{ url }` object.
+   * @param init - Optional RequestInit-compatible options.
+   * @throws When the setting is disabled or fetch is unavailable in this context.
    */
-  sendRequest(req: HcSendRequestInput): Promise<HcSendRequestResponse>;
+  fetch(input: string | URL | { url: string }, init?: HcFetchInit): Promise<HcFetchResponse>;
   /**
    * Sends a one-shot prompt to a configured AI model.
    * Includes the current send's request (and response in post-request scripts)