@nxisai/agent-harness 0.2.0

package/dist/harness/harness.d.ts

@@ -0,0 +1,284 @@
+/**
+ * The turn loop: discover tools, generate, parse the tool call, resolve what is
+ * still unknown, decide whether to ask or act, run the tool, report the result.
+ *
+ * The harness decides; a {@link HarnessRenderer} draws. What a turn does
+ * depends on the tool's own annotations and on how much the model supplied:
+ *
+ * | Tool | Missing values | Outcome |
+ * |---|---|---|
+ * | read | none | runs immediately, no UI |
+ * | read | some | asks for those, then runs |
+ * | write | none | read-only summary and one Submit |
+ * | write | several | a stepper, then a confirmation |
+ *
+ * @module
+ */
+import { parseToolCall, type ChatMessage } from '../engine.js';
+import type { ModelContextToolInfo, ModelContextToolResponse } from '../types.js';
+import type { ModelProvider } from '../providers/types.js';
+import { WebMcpTools } from './tools/webmcp.js';
+import { type Decision } from './policy.js';
+import type { HarnessRenderer } from './renderer.js';
+/** Configuration for an {@link AgentHarness}. */
+export interface HarnessOptions {
+    /**
+     * Where completions come from. Defaults to a {@link LocalGemmaProvider}.
+     *
+     * Several agents may share one provider, so a coordinator and its specialists
+     * need only one model between them.
+     */
+    provider?: ModelProvider;
+    /** Where tools come from. Defaults to the page's WebMCP registry. */
+    toolSource?: WebMcpTools;
+    /** The UI to drive. The only required option. */
+    renderer: HarnessRenderer;
+    /**
+     * This agent's instructions, asserted at the start of each of its turns.
+     *
+     * Agents sharing a provider can each hold a different prompt, since the
+     * prompt travels with the agent rather than with the model.
+     */
+    systemPrompt?: string;
+    /**
+     * Filter deciding which of the page's tools this agent may use.
+     *
+     * Tool definitions dominate what the model reads each turn, so narrowing them
+     * shortens the prompt and reduces the number of wrong tools available to be
+     * chosen. Defaults to every tool on the page.
+     *
+     * @param tool - A tool reported by the tool source.
+     * @returns True to expose it to this agent.
+     */
+    tools?(tool: ModelContextToolInfo): boolean;
+    /** This agent's name, used in warnings and the default unavailable message. */
+    name?: string;
+    /**
+     * What to say when none of this agent's tools are on the page.
+     *
+     * Worth setting per agent, so the message can name what cannot be done here
+     * and where it can be done instead.
+     */
+    unavailable?: string;
+    /**
+     * Standing values for a tool's schema, such as a saved name or email.
+     *
+     * @param schema - The tool's input schema.
+     * @returns Values keyed by schema property name.
+     */
+    profile?(schema: unknown): Record<string, unknown>;
+    /**
+     * Values the host page knows, such as the record currently being viewed.
+     *
+     * @param tool - The tool about to be called.
+     * @returns Values keyed by schema property name.
+     */
+    context?(tool: ModelContextToolInfo): Record<string, unknown>;
+    /**
+     * Whether related fields share a step when asking for missing values.
+     * Defaults to true. Pass false to ask one question at a time.
+     */
+    groupRelated?: boolean;
+    /** Called whenever the conversation changes, for hosts that persist it. */
+    onMessages?(messages: ChatMessage[]): void;
+}
+/** How a turn ended. */
+export interface TurnResult {
+    /**
+     * The outcome:
+     *
+     * - a {@link Decision}, when a tool call was resolved;
+     * - `'none'`, when the model answered in prose;
+     * - `'handback'`, when the model named a tool this agent does not hold, with
+     *   the name in {@link TurnResult.wanted};
+     * - `'unavailable'`, when none of this agent's tools are on the page;
+     * - `'stopped'`, when the user cancelled the turn.
+     */
+    decision: Decision | 'none' | 'handback' | 'unavailable' | 'stopped';
+    /** The tool that was called, when one was. */
+    tool?: ModelContextToolInfo;
+    /** The arguments it was called with. */
+    values?: Record<string, unknown>;
+    /**
+     * The tool the model asked for and this agent does not hold.
+     *
+     * Set only with `decision: 'handback'`, and used by
+     * {@link AgentCoordinator} to move the turn to the agent that holds it.
+     */
+    wanted?: string;
+}
+/**
+ * Whether an error represents a cancelled operation rather than a failure.
+ *
+ * @param err - The caught value.
+ * @returns True for a DOM `AbortError`, as thrown by an aborted `fetch`.
+ */
+export declare function isAbort(err: unknown): boolean;
+/**
+ * A sentence to show for a turn whose model output was only a tool call.
+ *
+ * Claims no more than the harness knows at that point: which tool was chosen,
+ * and whether it reads or writes.
+ *
+ * @param call - The parsed tool call, or null if there was none.
+ * @param tools - The tools available this turn, used to read the annotations.
+ * @returns A short line to display in place of the model's own words.
+ */
+export declare function narrateCall(call: ReturnType<typeof parseToolCall>, tools: ModelContextToolInfo[]): string;
+/**
+ * How many records a tool response contained.
+ *
+ * Best-effort: it feeds a summary line, so an unrecognised shape reports
+ * nothing rather than guessing.
+ *
+ * @param res - The tool response, whose `structuredContent` is preferred.
+ * @param text - The same response flattened to text, parsed as JSON if needed.
+ * @returns The record count, or undefined when the shape is not recognised.
+ */
+export declare function countRecords(res: ModelContextToolResponse, text: string): number | undefined;
+/**
+ * One agent: a provider, a set of tools, and the loop that runs a turn.
+ *
+ * Use it directly for a single-agent page, or several behind an
+ * {@link AgentCoordinator} to route between specialists.
+ *
+ * @example
+ * ```ts
+ * const harness = new AgentHarness({ renderer });
+ * const messages: ChatMessage[] = [];
+ * await harness.turn('what are your opening hours?', messages);
+ * ```
+ */
+export declare class AgentHarness {
+    /** Where completions come from. May be shared between agents. */
+    readonly provider: ModelProvider;
+    /** Where tools come from. */
+    readonly toolSource: WebMcpTools;
+    private renderer;
+    private opts;
+    /** Values typed into a prompt that is still open, kept across turns. */
+    private entered;
+    private liveTool;
+    /** The in-flight turn's controller, so it can be cancelled. */
+    private abort;
+    /** The previous request's system prompt and tool names, for the cache hint. */
+    private lastPrompt;
+    private lastTools;
+    constructor(opts: HarnessOptions);
+    /**
+     * End a turn that the user stopped.
+     *
+     * Discards any partial answer and keeps the question, recording it if the
+     * stop arrived before the turn had done so, so the transcript matches what is
+     * on screen.
+     */
+    private stopTurn;
+    /** Report a finished turn and clear the stoppable state. */
+    private finished;
+    /** Whether the current turn has been stopped. */
+    private get stopped();
+    /**
+     * Abandon the turn in flight.
+     *
+     * Aborts tool discovery or generation, whichever is running. The turn
+     * resolves as `'stopped'` rather than rejecting, so a cancellation is not
+     * reported as a failure. Safe to call when nothing is running.
+     *
+     * A tool call already in progress is not interrupted, since it may have
+     * reached a server already.
+     */
+    stop(): void;
+    /**
+     * Render a completion for the transcript.
+     *
+     * The transcript must record the tool call, or the model repeats it on the
+     * next turn. Providers returning structured calls have no text form for one,
+     * so this writes it. Never displayed: the UI shows `completion.text`.
+     */
+    private transcribe;
+    /**
+     * Compare this request with the previous one to build a {@link CacheHint}.
+     *
+     * Must be called after `applySystemPrompt`, since a handoff between agents
+     * replaces both the system message and the tool slice.
+     */
+    private cacheHint;
+    /**
+     * Run one turn.
+     *
+     * The turn moves through phases the renderer is told about as they happen
+     * (loading the model, finding tools, generating, running the tool), each on a
+     * {@link HarnessRenderer.streaming} bubble with its own label. A renderer
+     * should expect the first bubble before any token exists.
+     *
+     * Starting a turn supersedes any turn still running.
+     *
+     * @param goal - The user's message.
+     * @param messages - The live conversation, appended to in place. The caller
+     * keeps ownership of persistence; see {@link HarnessOptions.onMessages}.
+     * @returns How the turn ended. A page with no tools, a tool that errors, and
+     * a cancellation all resolve normally; see {@link TurnResult.decision}.
+     * @throws If the model cannot be loaded (no WebGPU, unreachable weights) or a
+     * generation fails for a reason other than being aborted.
+     */
+    turn(goal: string, messages: ChatMessage[]): Promise<TurnResult>;
+    /**
+     * Narrow the page's tools to this agent's slice.
+     *
+     * @param registered - Every tool the tool source reported.
+     * @returns The tools matching {@link HarnessOptions.tools}, or all of them
+     * when no filter is set.
+     */
+    private visibleTools;
+    /**
+     * Whether this agent's filter accepts a tool, by name.
+     *
+     * Called by {@link AgentCoordinator} when another agent hands a turn back.
+     * The filter receives a tool with only its name set, so a filter that
+     * inspects annotations should reject a bare name and let the fallback take
+     * the turn.
+     *
+     * @param name - The tool name to test.
+     * @returns True when this agent would use that tool.
+     */
+    owns(name: string): boolean;
+    /**
+     * Place this agent's instructions at the head of the shared transcript,
+     * replacing another agent's if one is there.
+     */
+    private applySystemPrompt;
+    /**
+     * Generate once more, instructing the model to call a tool.
+     *
+     * The instruction is added as a user turn, which carries the most weight in a
+     * chat template mid-conversation, and is removed again afterwards so it never
+     * remains in the transcript as something the user said.
+     *
+     * @returns The tool call, or null if the model still did not produce one.
+     */
+    private retryForToolCall;
+    /**
+     * Resolve a proposed call's arguments, then run it, confirm it, or ask.
+     *
+     * @param tool - The tool the model chose.
+     * @param rawArgs - Its arguments, before reconciliation against the schema.
+     * @param messages - The live conversation.
+     * @returns The decision taken and the values it was taken with.
+     */
+    private act;
+    /**
+     * Reopen a confirmation as an editable form covering every field, not only
+     * the gaps. Reached through {@link ConfirmRequest.onEdit}.
+     */
+    private askAll;
+    /** Discard a live prompt and the values typed into it. */
+    private cancel;
+    /**
+     * Execute a fully resolved call and render its result.
+     *
+     * Read tools render as records, writes as a detail card. Either way the
+     * outcome is written into the transcript so the model can refer back to it.
+     */
+    private run;
+}
+//# sourceMappingURL=harness.d.ts.map

package/dist/harness/harness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"harness.d.ts","sourceRoot":"","sources":["../../src/harness/harness.ts"],"names":[],"mappings":"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"}