@nxisai/agent-harness 0.4.1 → 0.5.0

package/src/harness/tools/webmcp.ts

@@ -0,0 +1,200 @@
+/**
+ * Tool discovery and execution over WebMCP.
+ *
+ * Discovery and execution work the same way whichever model is answering, so
+ * they sit with the harness rather than behind {@link ModelProvider}.
+ *
+ * @module
+ */
+import { TOOLS_TIMEOUT_MS } from '../../engine.js';
+import type {
+  ModelContext,
+  ModelContextToolInfo,
+  ModelContextToolResponse,
+} from '../../types.js';
+
+/**
+ * The default tool source, backed by the page's `document.modelContext`.
+ *
+ * Supply an instance as {@link HarnessOptions.toolSource}, or substitute any
+ * object with the same shape to draw tools from somewhere else.
+ */
+export class WebMcpTools {
+  /**
+   * The page's model context.
+   *
+   * @returns The context, or null on a page where WebMCP is not present.
+   */
+  modelContext(): ModelContext | null {
+    return document.modelContext || navigator.modelContext || null;
+  }
+
+  /**
+   * Wait for tools to appear on a model context.
+   *
+   * Tools register asynchronously, so a context can be present but empty for a
+   * short time after page load. Polls, and also listens for `toolchange`.
+   *
+   * @param mc - The context to watch.
+   * @param signal - Abort to stop waiting early. Resolves empty when aborted.
+   * @returns The registered tools, or an empty array if none appear within
+   * {@link TOOLS_TIMEOUT_MS}.
+   */
+  waitForTools(mc: ModelContext, signal?: AbortSignal): Promise<ModelContextToolInfo[]> {
+    return new Promise((resolve) => {
+      let done = false;
+      const finish = async (tools?: ModelContextToolInfo[]) => {
+        if (done) return;
+        done = true;
+        clearInterval(iv);
+        clearTimeout(to);
+        mc.removeEventListener('toolchange', onChange);
+        signal?.removeEventListener('abort', onAbort);
+        resolve(tools || (await mc.getTools()));
+      };
+      const onAbort = () => finish([]);
+      if (signal?.aborted) return finish([]);
+      signal?.addEventListener('abort', onAbort, { once: true });
+      const check = async () => {
+        const tools = await mc.getTools();
+        if (tools && tools.length) finish(tools);
+      };
+      const onChange = () => check();
+      mc.addEventListener('toolchange', onChange);
+      const iv = setInterval(check, 800);
+      const to = setTimeout(() => finish(), TOOLS_TIMEOUT_MS);
+      check();
+    });
+  }
+
+  /**
+   * Every tool registered on the page.
+   *
+   * @param signal - Abort to stop waiting for tools to appear.
+   * @returns The registered tools, or an empty array when WebMCP is absent,
+   * discovery fails, or the wait is aborted.
+   */
+  async discoverTools(signal?: AbortSignal): Promise<ModelContextToolInfo[]> {
+    const mc = this.modelContext();
+    if (!mc) return [];
+    try {
+      return await this.waitForTools(mc, signal);
+    } catch {
+      return [];
+    }
+  }
+
+  /**
+   * Call a tool.
+   *
+   * Handles each runtime's calling convention — see {@link executeRegistered} —
+   * trying the spec's form first and falling back when the context rejects it.
+   *
+   * @param toolObj - The tool as reported by discovery, or null to call by name.
+   * @param name - The tool's name, used for the fallback call.
+   * @param args - The arguments to send.
+   * @returns The tool's response.
+   * @throws If WebMCP is not available, or the tool itself throws.
+   */
+  async execTool(
+    toolObj: ModelContextToolInfo | null,
+    name: string,
+    args: Record<string, unknown>,
+  ): Promise<ModelContextToolResponse> {
+    const mc = this.modelContext();
+    if (!mc) throw new Error('WebMCP is not available on this page.');
+    return executeRegistered(mc, toolObj, name, args);
+  }
+}
+
+/**
+ * A registry refusing the SHAPE of a call, as opposed to the tool failing.
+ *
+ * Every message here was measured to come back before the tool's own code ran,
+ * which is what makes trying another form safe. Chrome 153 refuses an object
+ * input with "Failed to parse input arguments" having run nothing; a tool that
+ * ran and threw says "Tool was executed but the invocation failed", which is
+ * deliberately not here — it may already have done something.
+ */
+const REFUSED_SHAPE =
+  /RegisteredTool|not of type|not an object|invalid input|Failed to parse input arguments|arguments required|No tool registered|NotFound/i;
+
+/**
+ * Call a registered tool the way the runtime in front of us accepts.
+ *
+ * Runtimes disagree, and each refuses the others' forms. Measured:
+ *
+ * - Chrome 155 (Beta), and the WebMCP spec: the registered tool object and an
+ *   arguments *object*. A JSON string is refused ("invalid input object: value
+ *   is not an object"), and so is a name ("not of type 'RegisteredTool'").
+ * - Chrome 153 (stable): the tool object and a JSON *string*, required. An
+ *   object is refused, before the tool runs, with "Failed to parse input
+ *   arguments".
+ * - Older polyfills (`@nxisai/webmcp` 0.1) took a name. Today's, and the
+ *   harness's own registry, follow the spec.
+ *
+ * So: object, then string, then name — each tried only when the one before was
+ * refused for its shape. A tool that ran and failed is reported as it failed,
+ * never retried in another form, since it may already have done something.
+ *
+ * @returns The tool's response as an object, whichever runtime answered — see
+ * {@link asResponse}.
+ */
+export async function executeRegistered(
+  mc: ModelContext,
+  toolObj: ModelContextToolInfo | null,
+  name: string,
+  args: Record<string, unknown>,
+): Promise<ModelContextToolResponse> {
+  const input = args ?? {};
+  const attempts: (() => Promise<ModelContextToolResponse>)[] = [
+    ...(toolObj
+      ? [
+          () => mc.executeTool(toolObj as unknown as object, input),
+          () => mc.executeTool(toolObj as unknown as object, JSON.stringify(input)),
+        ]
+      : []),
+    () => mc.executeTool(name, input),
+  ];
+  let refused: unknown;
+  for (const attempt of attempts) {
+    try {
+      return asResponse(await attempt());
+    } catch (err) {
+      if (!REFUSED_SHAPE.test(String((err as Error)?.message || err))) throw err;
+      refused = err;
+    }
+  }
+  throw refused;
+}
+
+/**
+ * Whatever a registry returned, as the response object the tool produced.
+ *
+ * The spec's `executeTool` resolves with a string — the tool's result
+ * serialized — and native Chrome does exactly that. Read as text, a tool that
+ * reported `isError` looks like a success and its `structuredContent` is gone:
+ * a form that refused the input would be shown as sent. Parsing it back here,
+ * once, gives every caller the same object whichever runtime answered.
+ *
+ * A tool that returned text comes back as that text. Under the spec every
+ * result is JSON, so text arrives quoted (`"\"Done\""`); Chrome 155 passes it
+ * unquoted, and `"undefined"` for a tool that returned nothing. Both read the
+ * same here.
+ */
+export function asResponse(raw: unknown): ModelContextToolResponse {
+  if (raw && typeof raw === 'object' && !Array.isArray(raw)) return raw as ModelContextToolResponse;
+  if (typeof raw !== 'string') return { content: raw === undefined ? [] : [{ type: 'text', text: String(raw) }] };
+  const trimmed = raw.trim();
+  if (trimmed === 'undefined' || trimmed === '') return { content: [] };
+  if (trimmed.startsWith('{') || trimmed.startsWith('"')) {
+    try {
+      const parsed = JSON.parse(trimmed) as unknown;
+      if (typeof parsed === 'string') return { content: parsed ? [{ type: 'text', text: parsed }] : [] };
+      if (parsed && Array.isArray((parsed as ModelContextToolResponse).content)) return parsed as ModelContextToolResponse;
+    } catch {
+      // Not JSON; the tool's own text.
+    }
+  }
+  return { content: [{ type: 'text', text: raw }] };
+}

package/src/index.ts

@@ -0,0 +1,193 @@
+/**
+ * Headless entry point for `@nxisai/agent-harness`.
+ *
+ * Everything exported here runs without a UI. For the packaged chat element,
+ * import `@nxisai/agent-harness/ui`; to keep this decision logic behind an
+ * interface of your own, implement {@link HarnessRenderer}.
+ *
+ * @example
+ * ```ts
+ * import { AgentHarness } from '@nxisai/agent-harness';
+ *
+ * const harness = new AgentHarness({ renderer });
+ * await harness.turn('book me in for Thursday', messages);
+ * ```
+ *
+ * @module
+ */
+
+export { AgentHarness } from './harness/harness.js';
+
+// ── Model providers ──────────────────────────────────────────────────────────
+export { LocalGemmaProvider, AgentEngine, shouldUseCache } from './engine.js';
+export { createProxyProvider } from './providers/proxy.js';
+export type { ProxyProviderOptions } from './providers/proxy.js';
+export { assessLocalCapability, requestPersistentStorage } from './providers/capability.js';
+export type { LocalCapability } from './providers/capability.js';
+export type {
+  ModelProvider,
+  CompletionRequest,
+  Completion,
+  CacheHint,
+} from './providers/types.js';
+
+// ── Tools, as the harness sees them ──────────────────────────────────────────
+export { WebMcpTools } from './harness/tools/webmcp.js';
+export {
+  toolSchema,
+  missingRequired,
+  reconcileArgs,
+  extractResult,
+  proseAnswer,
+} from './harness/tools/schema.js';
+export type { HarnessOptions, TurnResult } from './harness/harness.js';
+
+export { policyFor, decide } from './harness/policy.js';
+export type { ToolPolicy, Decision } from './harness/policy.js';
+
+export { resolveSlots, summarySlots } from './harness/slots.js';
+export type { Slot, Resolution, ResolveSources } from './harness/slots.js';
+
+export { buildPlan } from './harness/plan.js';
+
+export { AgentCoordinator } from './harness/router/coordinator.js';
+export type { CoordinatorOptions, RoutedTurn, RouteSource } from './harness/router/coordinator.js';
+export { matchRoute } from './harness/router/rules.js';
+export type { RouteRule, RouteDecision } from './harness/router/rules.js';
+export type { ClarificationPlan, PlanStep } from './harness/plan.js';
+
+export type {
+  HarnessRenderer,
+  AskRequest,
+  ConfirmRequest,
+  StreamingBubble,
+} from './harness/renderer.js';
+
+export {
+  parseToolCall,
+  stripMarkers,
+  humanize,
+  lcFirst,
+  escapeHtml,
+  MODEL_ID,
+  MODEL_HOST,
+  MODEL_PATH_TEMPLATE,
+  SYSTEM_PROMPT,
+  MAX_STEPS,
+  MAX_NEW_TOKENS,
+  TOOLS_TIMEOUT_MS,
+} from './engine.js';
+
+/**
+ * Brand marks and icons used by the packaged UI.
+ *
+ * Exported for custom renderers. Inline SVG using `currentColor`, so each icon
+ * takes the surrounding text colour.
+ */
+export {
+  NXIS_LOGO_SVG,
+  ICON_CHECK,
+  ICON_WARN,
+  ICON_ARROW,
+  ICON_PLUS,
+  ICON_MENU,
+  ICON_TRASH,
+  ICON_STOP,
+  ICON_COPY,
+  ICON_PENCIL,
+  ICON_REDO,
+  ICON_CHECK_MARK,
+} from './engine.js';
+export type {
+  AgentEngineOptions,
+  ChatMessage,
+  ToolDef,
+  GenerationUsage,
+  ParsedToolCall,
+  ProgressDetail,
+  PreloadMode,
+} from './engine.js';
+
+export { connectTools, waitForModelContext } from './harness/tools/source.js';
+export {
+  buildSiteActionTools,
+  registerSiteActionTools,
+  withoutShadowedTools,
+  handoffFor,
+  findPageTool,
+  awaitPageTool,
+  pageToolRef,
+  siteToolName,
+  sanitizeToolName,
+  selectSiteTools,
+  DEFAULT_SITE_TOOL_LIMIT,
+} from './harness/tools/action-tools.js';
+export {
+  beginJourney,
+  currentJourney,
+  journeySteps,
+  onJourneyChange,
+  recordStep,
+  restoreJourney,
+} from './harness/steps.js';
+export type { AgentStep, AgentStepId, AgentStepStatus } from './harness/steps.js';
+export { resumePendingAction } from './harness/tools/resume.js';
+export type { ResumeOutcome, ResumeOptions } from './harness/tools/resume.js';
+export {
+  loadSitePages,
+  parsePage,
+  pagesFromActions,
+  mergePages,
+  pageForEntity,
+  findPage,
+} from './harness/tools/site-pages.js';
+export type { SitePage, SitePagesOptions } from './harness/tools/site-pages.js';
+export { buildOpenPageTool, registerOpenPageTool, resolveDestination, visitFor, OPEN_PAGE_TOOL } from './harness/tools/open-page.js';
+export { isRateLimited, retryAfterMs, withRetry } from './harness/tools/retry.js';
+export type { RetryOptions } from './harness/tools/retry.js';
+export {
+  applyTrails,
+  buildNav,
+  buildPageLinksTool,
+  describeNav,
+  loadSiteTrails,
+  nameOf,
+  navFor,
+  parentOf,
+  parseTrail,
+  registerPageLinksTool,
+  PAGE_LINKS_TOOL,
+} from './harness/tools/site-nav.js';
+export type { NavLink, PageNav, SiteNav, SiteTrail, SiteTrailsOptions, TrailLevel } from './harness/tools/site-nav.js';
+export type { OpenPageOptions, Destination } from './harness/tools/open-page.js';
+export type { SiteActionTool, Handoff, PageToolRef } from './harness/tools/action-tools.js';
+export {
+  savePendingAction,
+  takePendingAction,
+  clearPendingAction,
+  PENDING_TTL_MS,
+  savePendingVisit,
+  takePendingVisit,
+  setConversationSource,
+} from './harness/tools/pending-action.js';
+export type { PendingAction, PendingVisit } from './harness/tools/pending-action.js';
+export { loadSiteActions, parseAction } from './harness/tools/site-actions.js';
+export type { ConnectResult, ConnectOptions, SiteActionsOptions } from './harness/tools/source.js';
+export type { BridgeOptions } from './harness/tools/bridge.js';
+
+export type {
+  JsonSchema,
+  ModelContext,
+  ModelContextTool,
+  ModelContextToolInfo,
+  ModelContextToolResponse,
+  McpServerInfo,
+  NxisConfig,
+} from './types.js';
+
+export type {
+  NxisAction,
+  NxisEntryPoint,
+  NxisPropertyValueSpecification,
+  NxisValueOption,
+} from './webmcp-contract.js';

package/src/providers/capability.ts

@@ -0,0 +1,167 @@
+/**
+ * Whether this device can load the local model without harming the visitor.
+ *
+ * {@link LocalGemmaProvider} downloads and holds roughly 3.4 GB of weights in
+ * the tab. A mobile renderer cannot take that: it is killed, and the visitor
+ * loses the whole host page rather than just the agent.
+ *
+ * That failure cannot be caught. An out-of-memory kill runs no `catch`, no
+ * `onerror` and no `unload` handler, so there is no recovery path and nothing
+ * to report afterwards. The only defence is deciding before the load starts,
+ * which is what this module is for.
+ *
+ * @module
+ */
+
+/** Fields the standard DOM types do not declare. */
+type CapabilityNavigator = Navigator & {
+  deviceMemory?: number;
+  userAgentData?: { mobile?: boolean };
+  gpu?: {
+    requestAdapter(): Promise<{
+      features: { has(feature: string): boolean };
+      limits: Record<string, number>;
+    } | null>;
+  };
+};
+
+/** Approximate footprint of the q4f16 weights, in bytes. */
+export const MODEL_BYTES = 3.4e9;
+
+/** Weights plus room for the browser's own use, for the storage estimate. */
+const REQUIRED_QUOTA = MODEL_BYTES * 1.8;
+
+/** Reported memory, in GB, below which the load is not attempted. */
+const MIN_DEVICE_MEMORY_GB = 8;
+
+/** What {@link assessLocalCapability} found. */
+export interface LocalCapability {
+  /** Whether the local model should be loaded on this device. */
+  ok: boolean;
+  /** Why not, when `ok` is false. Suitable for a log, not for a visitor. */
+  reason?: string;
+  /** The individual findings, for a host that wants to decide for itself. */
+  checks: {
+    /** True for a phone or tablet, by client hints or user-agent string. */
+    mobile: boolean;
+    /** Whether `navigator.gpu` exists. The API, not a usable adapter. */
+    webgpuApi: boolean;
+    /** Whether an adapter was actually returned. */
+    adapter: boolean;
+    /** Whether the adapter supports fp16 compute, which `q4f16` requires. */
+    shaderF16: boolean;
+    /** `navigator.deviceMemory` in GB, where the browser reports it. */
+    deviceMemoryGb?: number;
+    /** Storage quota in bytes, where the browser estimates it. */
+    storageQuota?: number;
+  };
+}
+
+/** Is this a phone or tablet? Client hints where available, UA string if not. */
+function isMobile(nav: CapabilityNavigator): boolean {
+  if (typeof nav.userAgentData?.mobile === 'boolean') return nav.userAgentData.mobile;
+  return /Android|iPhone|iPad|iPod|Mobile|Silk|Kindle/i.test(nav.userAgent);
+}
+
+/**
+ * Decide whether the local model can be loaded here, without loading it.
+ *
+ * Safe and cheap to call: it acquires a WebGPU adapter and reads storage
+ * estimates, and downloads nothing. Hosts can call it directly to decide
+ * whether to offer the agent at all, rather than rendering a control that
+ * cannot work.
+ *
+ * Deliberately conservative, because the two ways of being wrong are not
+ * equal. A false negative costs a capable visitor the local model, and a
+ * remote provider still works. A false positive costs a visitor their browser
+ * tab, and takes the host's page with it.
+ *
+ * There is no smaller quantisation to fall back to: `q4f16` is already the
+ * smallest build of this model, and `q4` is larger. So a device without fp16
+ * compute is declined rather than degraded.
+ *
+ * @returns The verdict, and the individual findings behind it.
+ */
+export async function assessLocalCapability(): Promise<LocalCapability> {
+  const checks: LocalCapability['checks'] = {
+    mobile: false,
+    webgpuApi: false,
+    adapter: false,
+    shaderF16: false,
+  };
+
+  if (typeof navigator === 'undefined') {
+    return { ok: false, reason: 'no navigator', checks };
+  }
+  const nav = navigator as CapabilityNavigator;
+
+  checks.mobile = isMobile(nav);
+  checks.webgpuApi = !!nav.gpu;
+  if (typeof nav.deviceMemory === 'number') checks.deviceMemoryGb = nav.deviceMemory;
+
+  // Mobile is the case this exists for. Even a phone reporting ample memory is
+  // subject to a renderer cap far below what these weights need.
+  if (checks.mobile) return { ok: false, reason: 'mobile device', checks };
+  if (!nav.gpu) return { ok: false, reason: 'no WebGPU', checks };
+
+  if (checks.deviceMemoryGb !== undefined && checks.deviceMemoryGb < MIN_DEVICE_MEMORY_GB) {
+    return { ok: false, reason: `deviceMemory ${checks.deviceMemoryGb}GB`, checks };
+  }
+
+  let adapter;
+  try {
+    adapter = await nav.gpu.requestAdapter();
+  } catch (error) {
+    return { ok: false, reason: `adapter request failed: ${String(error)}`, checks };
+  }
+  // The API can exist with no adapter behind it, which is a load that fails
+  // after the download rather than before it.
+  if (!adapter) return { ok: false, reason: 'no WebGPU adapter', checks };
+  checks.adapter = true;
+
+  checks.shaderF16 = adapter.features.has('shader-f16');
+  if (!checks.shaderF16) return { ok: false, reason: 'no shader-f16', checks };
+
+  // Storage is checked last because it is advisory: browsers report a quota
+  // they do not promise to honour, and a missing estimate is not a refusal.
+  try {
+    const estimate = await nav.storage?.estimate?.();
+    if (typeof estimate?.quota === 'number') {
+      checks.storageQuota = estimate.quota;
+      if (estimate.quota < REQUIRED_QUOTA) {
+        return {
+          ok: false,
+          reason: `storage quota ${(estimate.quota / 1e9).toFixed(1)}GB`,
+          checks,
+        };
+      }
+    }
+  } catch {
+    // An unavailable estimate says nothing either way.
+  }
+
+  return { ok: true, checks };
+}
+
+/**
+ * Ask the browser to keep this origin's storage rather than evicting it.
+ *
+ * Cache Storage is best-effort by default, and a browser under pressure evicts
+ * best-effort data without warning. A multi-gigabyte model is the first thing
+ * to go, which looks exactly like caching never having worked.
+ *
+ * Browsers grant this on their own heuristics, so it is a request rather than
+ * a guarantee. Not asking guarantees best-effort; asking sometimes gets more.
+ *
+ * @returns Whether the origin's storage is persistent afterwards.
+ */
+export async function requestPersistentStorage(): Promise<boolean> {
+  try {
+    const storage = navigator?.storage;
+    if (!storage?.persist) return false;
+    if (await storage.persisted?.()) return true;
+    return await storage.persist();
+  } catch {
+    return false;
+  }
+}