@harborclient/sdk 1.5.3 → 1.6.0

package/dist/runtime/createBridgedPluginContext.js

@@ -15,12 +15,41 @@ const commandHandlers = new Map();
 /** @type {Map<string, import('../types').ImportHandler>} */
 const importHandlersByRegistrationId = new Map();
 
+/**
+ * Parse callbacks for custom chat pointers, keyed by registration id.
+ *
+ * @type {Map<string, NonNullable<import('../types').PluginChatPointerConfig['parse']>>}
+ */
+const chatPointerParseByRegistrationId = new Map();
+
 /** Monotonic id generator for import handler registrations within one webview. */
 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';
@@ -28,6 +57,15 @@ const HOST_COMMAND_OWNER = 'harborclient';
 /** Guards repeated import invoke listener installation per webview load. */
 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.
  *
@@ -123,6 +161,11 @@ export function installImportInvokeListener() {
 export function resetMcpServersForTests() {
   mcpRegistrationCounter = 0;
   aiChatPointerRegistrationCounter = 0;
+  aiInstructionsRegistrationCounter = 0;
+  chatPointerParseByRegistrationId.clear();
+  aiInstructionsByRegistrationId.clear();
+  aiBeforeTurnHandlers.clear();
+  aiAfterTurnHandlers.clear();
 }
 
 /**
@@ -132,9 +175,183 @@ export function resetImportHandlersForTests() {
   importHandlersByRegistrationId.clear();
   importRegistrationCounter = 0;
   importInvokeListenerInstalled = false;
+  aiParseChatPointerListenerInstalled = false;
+  aiBeforeTurnListenerInstalled = false;
+  aiAfterTurnListenerInstalled = false;
   resetMcpServersForTests();
 }
 
+/**
+ * Serializes a plugin chat-pointer match for the host bridge.
+ *
+ * @param {RegExp | string} match - Plugin-supplied match.
+ * @returns {{ source: string; flags: string }}
+ */
+function serializeChatPointerMatch(match) {
+  if (match instanceof RegExp) {
+    return { source: match.source, flags: match.flags.replace(/g/g, '') };
+  }
+  return { source: String(match ?? ''), flags: '' };
+}
+
+/**
+ * Subscribes to host-initiated chat-pointer parse invocations for the agent webview.
+ *
+ * Must run once before plugin activation so send/validate can reach registered parsers.
+ */
+export function installAiParseChatPointerListener() {
+  if (aiParseChatPointerListenerInstalled) {
+    return;
+  }
+  aiParseChatPointerListenerInstalled = true;
+
+  bridgeOn('ai.parseChatPointer', async (payload) => {
+    const { requestId, registrationId, matchGroups, fullToken, atIndex } = payload ?? {};
+    if (requestId == null || registrationId == null) {
+      return;
+    }
+
+    const parse = chatPointerParseByRegistrationId.get(String(registrationId));
+    if (!parse) {
+      await bridgeInvoke('ai.parseChatPointerComplete', {
+        requestId,
+        ok: false,
+        error: `Unknown chat pointer parse registration: ${registrationId}`
+      });
+      return;
+    }
+
+    try {
+      const groups = Array.isArray(matchGroups)
+        ? matchGroups.map((g) => (g == null ? undefined : String(g)))
+        : [];
+      const synthetic = /** @type {RegExpMatchArray} */ (groups);
+      synthetic.index = 0;
+      synthetic.input = String(fullToken ?? '').replace(/^@/, '');
+      const result = parse(synthetic, String(fullToken ?? ''), Number(atIndex) || 0);
+      await bridgeInvoke('ai.parseChatPointerComplete', {
+        requestId,
+        ok: true,
+        result: result ?? null
+      });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      await bridgeInvoke('ai.parseChatPointerComplete', {
+        requestId,
+        ok: false,
+        error: message
+      });
+    }
+  });
+}
+
+/**
+ * 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.
  *
@@ -338,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.
    */
@@ -1080,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();
@@ -1254,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();
@@ -1408,13 +1630,28 @@ export function createBridgedPluginContext({ pluginId, mode, contributionId, rea
         if (!/^[a-z][a-z0-9-]*$/.test(pointerId)) {
           throw new Error(`Invalid chat pointer id: ${pointerId}`);
         }
+        const hasMatch = config?.match != null && config.match !== '';
+        const hasParse = typeof config?.parse === 'function';
+        if (hasMatch !== hasParse) {
+          throw new Error('Chat pointer match and parse must be provided together.');
+        }
+
         const registrationId = String(++aiChatPointerRegistrationCounter);
+        /** @type {{ source: string; flags: string } | undefined} */
+        let matchPayload;
+        if (hasMatch) {
+          matchPayload = serializeChatPointerMatch(/** @type {RegExp | string} */ (config.match));
+          chatPointerParseByRegistrationId.set(registrationId, config.parse);
+        }
+
         void bridgeInvoke('ai.registerChatPointer', {
           registrationId,
           pointerId,
-          agentGuidance: config?.agentGuidance
+          agentGuidance: config?.agentGuidance,
+          ...(matchPayload != null ? { match: matchPayload } : {})
         });
         return track(() => {
+          chatPointerParseByRegistrationId.delete(registrationId);
           void bridgeInvoke('ai.unregisterChatPointer', { registrationId });
         });
       },
@@ -1422,11 +1659,62 @@ export function createBridgedPluginContext({ pluginId, mode, contributionId, rea
         assertAi();
         await bridgeInvoke('ai.copyToChat', {
           pointerId: String(input?.pointerId ?? '').trim(),
-          key: String(input?.key ?? '').trim(),
+          key: input?.key != null ? String(input.key).trim() : undefined,
+          token: input?.token != null ? String(input.token).trim() : undefined,
           label: String(input?.label ?? '').trim(),
           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,9 @@ import { clearContributionRegistry } from './contributionRegistry.js';
 import {
   createBridgedPluginContext,
   executeLocalPluginCommand,
+  installAiAfterTurnListener,
+  installAiBeforeTurnListener,
+  installAiParseChatPointerListener,
   installImportInvokeListener,
   mountContributionView,
   parseViewHostRole,
@@ -72,6 +75,9 @@ 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)