@nxisai/agent-harness 0.4.1 → 0.6.0

package/src/providers/proxy.ts

@@ -0,0 +1,191 @@
+/**
+ * A {@link ModelProvider} that forwards completions to an endpoint you host.
+ *
+ * The browser never holds a vendor credential: the page posts to your own
+ * origin, and your endpoint calls the model with a key only it can see. This is
+ * the client half of that arrangement. The server half is yours to write, and
+ * `docs/remote-providers.md` documents the contract it has to satisfy.
+ *
+ * @example
+ * ```ts
+ * import { createProxyProvider } from '@nxisai/agent-harness';
+ *
+ * const agent = document.querySelector('nxis-agent-fullscreen');
+ * agent.modelProvider = createProxyProvider({ endpoint: '/api/agent' });
+ * ```
+ *
+ * @module
+ */
+import { toolSchema } from '../harness/tools/schema.js';
+import type { ModelContextToolInfo, ParsedToolCall } from '../types.js';
+import type { Completion, ModelProvider } from './types.js';
+
+/** Options for {@link createProxyProvider}. */
+export interface ProxyProviderOptions {
+  /**
+   * Where completions are requested from.
+   *
+   * A same-origin path such as `/api/agent` keeps the request under the page's
+   * own origin, which is what allows `credentials: 'same-origin'` to carry an
+   * existing session and lets the endpoint answer "who is allowed to ask".
+   */
+  endpoint: string;
+  /**
+   * Identifies the provider in logs and debug output, not to end users.
+   * Defaults to `'proxy'`.
+   */
+  name?: string;
+  /**
+   * The model's name as a visitor should read it — `'Claude'`. Shown beside
+   * the input. Worth setting: without it the visitor sees {@link name}.
+   */
+  label?: string;
+  /** Extra request headers, for an endpoint that expects its own auth. */
+  headers?: Record<string, string>;
+  /**
+   * `fetch` implementation to use. Defaults to the global.
+   *
+   * Present so the provider can be tested without a network, and so a host can
+   * wrap requests with its own retry or instrumentation.
+   */
+  fetchImpl?: typeof fetch;
+}
+
+/**
+ * What an endpoint may return.
+ *
+ * `calls` is not part of the contract, but mapping a vendor response tends to
+ * produce an array (Anthropic returns content blocks, and filtering them for
+ * tool uses yields one), so it is accepted and reduced rather than ignored.
+ */
+interface ProxyResponse {
+  text?: unknown;
+  call?: ParsedToolCall;
+  calls?: ParsedToolCall[];
+  usage?: { promptTokens?: number; outputTokens?: number };
+  model?: unknown;
+}
+
+/**
+ * Reduce the page's tools to plain, serialisable data.
+ *
+ * `discoverTools` returns whatever the WebMCP implementation holds, and a
+ * native registry returns live objects that reference the page: passing those
+ * to `JSON.stringify` throws "Converting circular structure to JSON, starting
+ * at object with constructor 'Window'". The local provider never hit this
+ * because it reads the same three fields out before building its prompt.
+ *
+ * Normalising the schema here also spares every endpoint the job: WebMCP
+ * carries it under four different keys and sometimes as a JSON string, and
+ * `inputSchema` is the one the contract documents.
+ */
+function wireTools(tools: ModelContextToolInfo[]) {
+  return tools.map((tool) => ({
+    name: tool.name,
+    description: tool.description ?? '',
+    inputSchema: toolSchema(tool),
+  }));
+}
+
+/**
+ * Reduce a response to the single call the harness can act on.
+ *
+ * The harness runs one tool per turn. An endpoint that returns several would
+ * otherwise have all but the first silently dropped, so the reduction happens
+ * here, once, with a warning naming what was discarded.
+ */
+function oneCall(body: ProxyResponse, name: string): ParsedToolCall | undefined {
+  const many = Array.isArray(body.calls) ? body.calls : [];
+  const all = body.call ? [body.call, ...many] : many;
+  if (all.length > 1) {
+    console.warn(
+      `[${name}] endpoint returned ${all.length} tool calls; using "${all[0]?.name}" and ` +
+        `discarding ${all.slice(1).map((c) => c?.name).join(', ')}. ` +
+        'The harness runs one tool per turn.',
+    );
+  }
+  return all[0];
+}
+
+/**
+ * Build a provider that posts completions to your own endpoint.
+ *
+ * The returned provider deliberately has no `load()`. Its absence is what tells
+ * the UI there is nothing to download, so the progress ring, byte counts and
+ * stage labels are skipped, and it is why a remote provider works on devices
+ * that cannot hold a local model. `countTokens` is likewise absent: token
+ * metrics hide themselves rather than reporting zeroes.
+ *
+ * @param opts - The endpoint, and optionally a name, extra headers, or a
+ * `fetch` implementation.
+ * @returns A provider ready to pass as `modelProvider` or {@link HarnessOptions.provider}.
+ * @throws From `complete()`, if the endpoint answers with a non-2xx status. An
+ * aborted request rejects with the `AbortError` from `fetch`, which the harness
+ * treats as a cancellation rather than a failure.
+ */
+export function createProxyProvider(opts: ProxyProviderOptions): ModelProvider {
+  const { endpoint, name = 'proxy', label, headers, fetchImpl } = opts;
+  /** The model the endpoint last said it used. Wins over the configured label. */
+  let served: string | undefined;
+
+  return {
+    name,
+    /**
+     * What the visitor sees beside the input: the model the endpoint last
+     * reported, or the label it was configured with until one has answered.
+     */
+    get label() {
+      return served ?? label;
+    },
+    /** Inference happens off-device, which the UI surfaces to the visitor. */
+    local: false,
+    ready: true,
+    loading: false,
+
+    async complete({ messages, tools, maxTokens, signal, cache }) {
+      const send = fetchImpl ?? fetch;
+      const res = await send(endpoint, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          // Declares which response shape this provider understands. A future
+          // streaming provider asks for text/event-stream instead, so an
+          // endpoint can offer both and this one keeps working unchanged.
+          Accept: 'application/json',
+          ...headers,
+        },
+        credentials: 'same-origin',
+        // Without this the stop control, Escape and edit-and-resend are all
+        // inert: they abort the turn through this signal and nothing else.
+        signal,
+        body: JSON.stringify({ messages, tools: wireTools(tools), maxTokens, cache }),
+      });
+
+      if (!res.ok) {
+        throw new Error(`Agent endpoint ${endpoint} returned ${res.status} ${res.statusText}`);
+      }
+
+      const body = (await res.json()) as ProxyResponse;
+      const completion: Completion = {
+        // Rendered verbatim, so an endpoint that strips its model's protocol
+        // markers is the only thing standing between them and the visitor.
+        text: typeof body.text === 'string' ? body.text : '',
+      };
+      const call = oneCall(body, name);
+      if (call) completion.call = call;
+      if (body.usage) {
+        completion.usage = {
+          promptTokens: body.usage.promptTokens ?? 0,
+          outputTokens: body.usage.outputTokens ?? 0,
+        };
+      }
+      // Which model answered, when the endpoint says. An endpoint may route
+      // between models, so this is the only place the true name comes from.
+      if (typeof body.model === 'string' && body.model.trim()) {
+        served = body.model.trim();
+        completion.model = served;
+      }
+      return completion;
+    },
+  };
+}

package/src/providers/types.ts

@@ -0,0 +1,150 @@
+/**
+ * The model provider interface.
+ *
+ * A provider supplies one completion at a time. Everything else the harness
+ * does (discovering tools, reading their schemas, deciding whether to ask,
+ * confirm or run) is the same whichever model answers.
+ *
+ * Completions are structured rather than plain text: a provider reports a tool
+ * call as {@link Completion.call}, whether its model expresses that as a native
+ * tool-use block or as markers in the text it generates.
+ *
+ * @see The bundled {@link LocalGemmaProvider}, and `docs/remote-providers.md`
+ * for a worked remote implementation.
+ *
+ * @module
+ */
+import type {
+  ChatMessage,
+  GenerationUsage,
+  ModelContextToolInfo,
+  ParsedToolCall,
+  PreloadMode,
+} from '../types.js';
+
+/**
+ * What the harness knows about which parts of a request will repeat.
+ *
+ * Advisory. The harness caches nothing itself; acting on the hint is a
+ * provider's decision, and only worthwhile where the backend supports prompt
+ * caching. Both fields go false when a handoff between agents changes the
+ * system prompt and the tool set.
+ */
+export interface CacheHint {
+  /** How many leading messages will be identical on the next request. */
+  stableMessages: number;
+  /** Whether the tool definitions are unchanged since the previous request. */
+  toolsStable: boolean;
+}
+
+/** One request for a completion. */
+export interface CompletionRequest {
+  /** The conversation so far, including the system prompt. */
+  messages: ChatMessage[];
+  /**
+   * The tools available for this turn, as raw WebMCP entries.
+   *
+   * Providers translate these into whatever their model expects.
+   */
+  tools: ModelContextToolInfo[];
+  /** Ceiling on generated tokens. Providers may apply their own default. */
+  maxTokens?: number;
+  /**
+   * Aborts when the user stops the turn, closes the panel, or starts another.
+   *
+   * Honour it: pass it to `fetch`, or interrupt local generation. Rejecting
+   * with an `AbortError` is correct, and the harness treats it as a
+   * cancellation rather than a failure.
+   */
+  signal?: AbortSignal;
+  /**
+   * Called as text arrives, with the whole answer so far rather than the newest
+   * fragment. Optional: a provider that does not stream simply omits it.
+   */
+  onToken?(textSoFar: string): void;
+  /** What the harness knows about reuse. Advisory; see {@link CacheHint}. */
+  cache?: CacheHint;
+}
+
+/** What a provider returns for one request. */
+export interface Completion {
+  /**
+   * Text to show the user, rendered verbatim. Strip any protocol markers in the
+   * provider: the harness does no parsing of its own.
+   */
+  text: string;
+  /**
+   * The tool the model asked for, if any. At most one per completion; a model
+   * that returns several calls should report the first and drop the rest.
+   */
+  call?: ParsedToolCall;
+  /** Token counts, when the provider can report them. */
+  usage?: GenerationUsage;
+  /**
+   * The model that produced this completion, as a visitor should read it.
+   *
+   * For a provider that cannot know in advance — an endpoint that routes
+   * between models, or falls back to a cheaper one under load — this is how
+   * the name shown beside the input stays true.
+   */
+  model?: string;
+}
+
+/**
+ * A source of model completions.
+ *
+ * Implement `complete` and the four readonly fields; everything else is
+ * optional. See `docs/remote-providers.md` for a worked example.
+ */
+export interface ModelProvider {
+  /** Identifies the provider in logs and debug output, not to end users. */
+  readonly name: string;
+  /**
+   * The model's name as a visitor should read it — `'Gemma 4 E2B'`.
+   *
+   * Shown beside the input, so someone can see what is answering them.
+   * Falls back to {@link name} when absent.
+   */
+  readonly label?: string;
+  /**
+   * Whether inference happens on the user's device.
+   *
+   * Surfaced in the UI, so that a page sending conversations to a remote
+   * service says so.
+   */
+  readonly local: boolean;
+
+  /** Whether the provider can answer a request right now. */
+  readonly ready: boolean;
+  /** Whether a load is in flight. Always false when there is nothing to load. */
+  readonly loading: boolean;
+
+  /**
+   * Prepare the model, resolving once it is ready.
+   *
+   * Omit it entirely when there is nothing to prepare: its absence is what
+   * tells the UI to skip the download progress treatment.
+   */
+  load?(): Promise<void>;
+  /**
+   * Begin loading ahead of the first turn.
+   *
+   * @param mode - How eagerly to load, from the element's `preload` attribute.
+   */
+  preload?(mode: Exclude<PreloadMode, 'none'>): void;
+
+  /**
+   * Produce one completion.
+   *
+   * @param req - The conversation, the available tools, and the abort signal.
+   * @returns The generated text and the tool call it implies, if any.
+   */
+  complete(req: CompletionRequest): Promise<Completion>;
+  /**
+   * Count tokens in a string.
+   *
+   * Optional. A provider that cannot count causes token metrics to be hidden
+   * rather than estimated.
+   */
+  countTokens?(text: string): Promise<number>;
+}

package/src/types.ts

@@ -0,0 +1,258 @@
+/**
+ * Shared types: the WebMCP surface (`document.modelContext`), MCP discovery
+ * (catalogs and server cards), and the model and tool-call shapes.
+ *
+ * @module
+ */
+
+// ── WebMCP (W3C draft ModelContext API) ──────────────────────────────────────
+
+/** A JSON Schema fragment, as carried by a tool's input schema. */
+export interface JsonSchema {
+  type?: string;
+  properties?: Record<string, JsonSchema>;
+  required?: string[];
+  enum?: unknown[];
+  items?: JsonSchema;
+  format?: string;
+  description?: string;
+  default?: unknown;
+  [key: string]: unknown;
+}
+
+/** Behavioural hints a tool declares about itself. */
+export interface ModelContextToolAnnotations {
+  /** True when calling the tool has no side effects. Drives {@link policyFor}. */
+  readOnlyHint?: boolean;
+  [key: string]: unknown;
+}
+
+/** One block of a tool response. */
+export interface ModelContextContent {
+  /** The block's kind, commonly `'text'`. */
+  type: string;
+  /** The block's text, when it has one. */
+  text?: string;
+  [key: string]: unknown;
+}
+
+/** What a tool returns. */
+export interface ModelContextToolResponse {
+  /** The response blocks, in order. */
+  content: ModelContextContent[];
+  /** True when the tool reports a failure. */
+  isError?: boolean;
+  /** A parsed form of the response, preferred over the text when present. */
+  structuredContent?: Record<string, unknown>;
+}
+
+/**
+ * A tool as reported by `getTools()`.
+ *
+ * Implementations differ over where the schema lives and whether it arrives
+ * parsed or as a JSON string, so several keys are accepted. Use
+ * {@link toolSchema} to read it rather than these fields directly.
+ */
+export interface ModelContextToolInfo {
+  /** The tool's unique name, as used to call it. */
+  name: string;
+  /** What the tool does, shown to the model. */
+  description?: string;
+  /** The input schema. See also the aliases below. */
+  inputSchema?: JsonSchema | string;
+  /** Alias for {@link ModelContextToolInfo.inputSchema}. */
+  input_schema?: JsonSchema | string;
+  /** Alias for {@link ModelContextToolInfo.inputSchema}. */
+  parameters?: JsonSchema | string;
+  /** Alias for {@link ModelContextToolInfo.inputSchema}. */
+  schema?: JsonSchema | string;
+  /** Behavioural hints, notably `readOnlyHint`. */
+  annotations?: ModelContextToolAnnotations;
+  /** Where the tool came from, when the registry records it. */
+  origin?: string;
+}
+
+/** A tool as passed to `registerTool()`. */
+export interface ModelContextTool {
+  /** The tool's unique name. */
+  name: string;
+  /** A human-readable name. `getTools` reports `""` when absent. */
+  title?: string;
+  /** What the tool does, shown to the model. */
+  description?: string;
+  /** The parsed input schema. */
+  inputSchema?: JsonSchema;
+  /** Behavioural hints, notably `readOnlyHint`. */
+  annotations?: ModelContextToolAnnotations;
+  /** Called to run the tool. */
+  execute(
+    input: Record<string, unknown>,
+    context?: unknown,
+  ): ModelContextToolResponse | Promise<ModelContextToolResponse>;
+}
+
+/**
+ * The page's model context, per the W3C draft ModelContext API.
+ *
+ * Emits `toolchange` when the set of registered tools changes.
+ */
+export interface ModelContext extends EventTarget {
+  /**
+   * Add a tool to the page's registry.
+   *
+   * Native implementations may return a promise, which rejects on a duplicate
+   * name; the polyfill returns nothing and replaces the existing tool.
+   */
+  registerTool(tool: ModelContextTool, options?: unknown): void | Promise<void>;
+  /** Supply page context to the registry, where the implementation supports it. */
+  provideContext?(context?: unknown): void;
+  /** Call a tool, by registered object or by name. */
+  executeTool(
+    nameOrTool: string | object,
+    input?: string | Record<string, unknown> | null,
+    options?: unknown,
+  ): Promise<ModelContextToolResponse>;
+  /** Every tool currently registered on the page. */
+  getTools(options?: unknown): Promise<ModelContextToolInfo[]>;
+}
+
+// ── MCP discovery (.well-known catalogs, then a server card) ─────────────────
+
+/** One entry in a discovery catalog. */
+export interface CatalogEntry {
+  identifier?: string;
+  displayName?: string;
+  mediaType?: string;
+  type?: string;
+  url?: string;
+}
+
+/** A `.well-known` discovery catalog. */
+export interface CatalogFile {
+  /** The catalog spec version the file claims. */
+  specVersion?: string;
+  /** The catalog's entries. */
+  entries?: CatalogEntry[];
+}
+
+/** A header a remote expects on each request, such as an API key. */
+export interface ServerCardRemoteHeader {
+  name: string;
+  description?: string;
+  isSecret?: boolean;
+  isRequired?: boolean;
+  format?: string;
+}
+
+/** One way of reaching an MCP server. */
+export interface ServerCardRemote {
+  type?: string;
+  url?: string;
+  headers?: ServerCardRemoteHeader[];
+  supportedProtocolVersions?: string[];
+}
+
+/** An MCP server's published description. */
+export interface ServerCard {
+  name?: string;
+  title?: string;
+  description?: string;
+  websiteUrl?: string;
+  remotes?: ServerCardRemote[];
+  _meta?: Record<string, unknown>;
+}
+
+/** The connection details an MCP client needs, distilled from a server card. */
+export interface McpServerInfo {
+  /** The server's Streamable HTTP endpoint. */
+  endpoint: string;
+  /** Header carrying the API key, when one is required. */
+  authHeaderName?: string;
+  /** Whether calls need an API key. */
+  authRequired: boolean;
+  /** Tools callable without authentication. */
+  publicTools: string[];
+  /** Protocol versions the server accepts. */
+  protocolVersions: string[];
+  /** Where the card was fetched from. */
+  cardUrl: string;
+  /** The server's display title. */
+  title?: string;
+}
+
+// ── Page config ──────────────────────────────────────────────────────────────
+
+/** The `window.__NXIS_CONFIG__` global, when the host page defines one. */
+export interface NxisConfig {
+  /** Organisation identifier. */
+  org_id?: string;
+  /** Site identifier. */
+  site_id?: string;
+  /** Subscription identifier. */
+  sub_id?: string;
+  /** WebMCP settings for the page. */
+  webmcp?: { mode?: string };
+}
+
+declare global {
+  interface Document {
+    modelContext?: ModelContext;
+  }
+  interface Navigator {
+    modelContext?: ModelContext;
+  }
+  interface Window {
+    __NXIS_CONFIG__?: NxisConfig;
+  }
+}
+
+// ── Model and tool-call shapes ───────────────────────────────────────────────
+
+
+/** One message in a conversation. */
+export interface ChatMessage {
+  /** Who produced the message. */
+  role: 'system' | 'user' | 'assistant';
+  /** The message text. */
+  content: string;
+}
+
+/** A tool definition in the form a chat template expects. */
+export interface ToolDef {
+  /** Always `'function'`. */
+  type: 'function';
+  /** The callable's name, description and parameter schema. */
+  function: { name: string; description?: string; parameters: JsonSchema };
+}
+
+/** A tool call the model asked for. */
+export interface ParsedToolCall {
+  /** The tool's name. */
+  name: string;
+  /** The arguments, as supplied by the model. */
+  args: Record<string, unknown>;
+}
+
+/** Token counts for one generation. */
+export interface GenerationUsage {
+  /** Tokens in the prompt, including tools and history. */
+  promptTokens: number;
+  /** Tokens generated. */
+  outputTokens: number;
+}
+
+/**
+ * Byte counts behind a load percentage.
+ *
+ * `total` covers only the files announced so far and grows as further shards
+ * register, which is why progress is reported per stage and left unclamped.
+ */
+export interface ProgressDetail {
+  /** Bytes received so far in this stage. */
+  loaded: number;
+  /** Bytes expected, across the files announced so far. */
+  total: number;
+}
+
+/** How eagerly to fetch model weights. */
+export type PreloadMode = 'eager' | 'idle' | 'none';