@nxisai/agent-harness 0.4.1 → 0.6.0

package/src/harness/plan.ts

@@ -0,0 +1,91 @@
+/**
+ * Arranges missing values into the steps a renderer asks for them in.
+ *
+ * A single missing value is one question; several become a stepper.
+ *
+ * @module
+ */
+
+import type { Slot } from './slots.js';
+
+/** One screen of the plan. */
+export interface PlanStep {
+  /** Position in {@link ClarificationPlan.steps}, from zero. */
+  index: number;
+  /** Slots asked together. One by default; grouped when they belong together. */
+  slots: Slot[];
+  title: string;
+}
+
+/** The questions to ask before a tool call can proceed. */
+export interface ClarificationPlan {
+  steps: PlanStep[];
+  /** True when the renderer should draw stepper chrome (Back, Step n of m). */
+  stepped: boolean;
+}
+
+/**
+ * Field names conventionally asked together, so they share a step.
+ *
+ * Matched by exact field name. Kept short by design: the more fields are
+ * grouped, the less the step count communicates.
+ */
+const AFFINITY: string[][] = [
+  ['full_name', 'name', 'email', 'phone'],
+  ['city', 'state', 'zip', 'postal_code'],
+];
+
+/** Index of the {@link AFFINITY} group a field belongs to, or -1. */
+function affinityGroup(name: string): number {
+  return AFFINITY.findIndex(group => group.includes(name));
+}
+
+/**
+ * Arrange missing slots into steps.
+ *
+ * @param missing - The slots still needing values, in the order to ask for them.
+ * @param groupRelated - Whether to place related fields (see {@link AFFINITY})
+ * on one step. Pass `false` to ask for every field separately.
+ * @returns A plan whose `stepped` flag is true when it has more than one step.
+ */
+export function buildPlan(missing: Slot[], groupRelated = true): ClarificationPlan {
+  if (!missing.length) return { steps: [], stepped: false };
+
+  const steps: PlanStep[] = [];
+
+  if (groupRelated) {
+    const used = new Set<Slot>();
+    for (const slot of missing) {
+      if (used.has(slot)) continue;
+      const group = affinityGroup(slot.name);
+      const together = group === -1
+        ? [slot]
+        : missing.filter(s => !used.has(s) && affinityGroup(s.name) === group);
+      together.forEach(s => used.add(s));
+      steps.push({ index: steps.length, slots: together, title: stepTitle(together) });
+    }
+  } else {
+    for (const slot of missing) {
+      steps.push({ index: steps.length, slots: [slot], title: stepTitle([slot]) });
+    }
+  }
+
+  // Renumber after grouping so index always matches position.
+  steps.forEach((s, i) => (s.index = i));
+  return { steps, stepped: steps.length > 1 };
+}
+
+/** A human label for a slot: its description, or its name made readable. */
+function label(slot: Slot): string {
+  return (
+    slot.schema.description ||
+    slot.name.replace(/([a-z0-9])([A-Z])/g, '$1 $2').replace(/[_-]+/g, ' ')
+      .replace(/^\w/, c => c.toUpperCase())
+  );
+}
+
+/** The heading for a step, joining grouped slots with an ampersand. */
+function stepTitle(slots: Slot[]): string {
+  if (slots.length === 1) return label(slots[0]);
+  return slots.map(label).join(' & ');
+}

package/src/harness/policy.ts

@@ -0,0 +1,59 @@
+/**
+ * Tool policy: whether a resolved tool call runs immediately or waits for a
+ * human confirmation.
+ *
+ * The decision comes from the tool's own `readOnlyHint` annotation, so a tool
+ * source that annotates its tools correctly gets the right behaviour with no
+ * further configuration.
+ *
+ * @module
+ */
+
+import type { ModelContextToolInfo } from '../types.js';
+
+/** What the harness should do once arguments are resolved. */
+export type Decision =
+  /** Run it now, with no interstitial UI. */
+  | 'execute'
+  /** Ask for the missing values, then run without a further confirmation. */
+  | 'ask'
+  /** Nothing is missing, but a human still presses Submit. */
+  | 'confirm';
+
+/** How a single tool should be treated once its arguments are known. */
+export interface ToolPolicy {
+  /** Taken from `annotations.readOnlyHint`. Read-only tools never write. */
+  readOnly: boolean;
+  /**
+   * Whether a call with no missing values still needs a human press.
+   *
+   * True for writes, whose effects reach a real system and cannot be undone by
+   * the harness. The confirmation displays the values read-only: nothing is
+   * missing, so there is nothing to edit.
+   */
+  confirmWhenSatisfied: boolean;
+}
+
+/**
+ * Derive a tool's policy from its annotations.
+ *
+ * @param tool - The tool as reported by the tool source.
+ * @returns The policy the harness applies to calls of this tool.
+ */
+export function policyFor(tool: ModelContextToolInfo): ToolPolicy {
+  const readOnly = !!tool.annotations?.readOnlyHint;
+  return { readOnly, confirmWhenSatisfied: !readOnly };
+}
+
+/**
+ * Resolve the decision from a tool's policy and what is still unknown.
+ *
+ * @param policy - The policy for the tool being called.
+ * @param gapCount - How many required values are still missing.
+ * @returns `'ask'` when anything is missing, otherwise `'confirm'` for writes
+ * and `'execute'` for reads.
+ */
+export function decide(policy: ToolPolicy, gapCount: number): Decision {
+  if (gapCount > 0) return 'ask';
+  return policy.confirmWhenSatisfied ? 'confirm' : 'execute';
+}

package/src/harness/renderer.ts

@@ -0,0 +1,208 @@
+/**
+ * The interface between the harness and a user interface.
+ *
+ * The harness makes every decision about what to do; a renderer is asked only
+ * to draw and to report what a person did. Keeping this interface narrow is
+ * what allows the same harness to drive the bundled web component, an A2UI
+ * surface, or a UI of your own.
+ *
+ * @module
+ */
+
+import type { ModelContextToolInfo, ModelContextToolResponse } from '../types.js';
+import type { ClarificationPlan } from './plan.js';
+import type { Resolution, Slot } from './slots.js';
+import type { AgentStep } from './steps.js';
+
+/** One tool call and its response, for renderers that show their work. */
+export interface TraceEntry {
+  /** The tool that was called. */
+  tool: ModelContextToolInfo;
+  /** Arguments as sent, after the harness reconciled and filled them. */
+  args: Record<string, unknown>;
+  /** The response, flattened to text. */
+  text: string;
+  /** Whether the tool reported a failure. */
+  isError: boolean;
+  /** How many records came back, when the response was a record set. */
+  count?: number;
+}
+
+/**
+ * The assistant's bubble for one phase of a turn.
+ *
+ * A turn is not one continuous stream. The harness opens a bubble, moves it
+ * through its phases and finalizes it, then opens another when the next silence
+ * begins, so {@link HarnessRenderer.streaming} is called more than once per turn
+ * and each bubble should be treated as independent.
+ *
+ * The usual order:
+ *
+ * ```ts
+ * bubble.thinking('Loading model…');        // no output yet
+ * bubble.update('The nearest plumb');       // text has started arriving
+ * bubble.finalize('The nearest plumber is…'); // the phase is over
+ * ```
+ */
+export interface StreamingBubble {
+  /**
+   * Show that work is happening, before there is anything to show.
+   *
+   * A turn can be silent for a long time: loading model weights takes tens of
+   * seconds on a first visit. Safe to call repeatedly, since each call replaces
+   * the label in place rather than adding a bubble.
+   *
+   * @param label - The current phase, such as `'Loading model…'`. Omit it to
+   * indicate work with nothing worth naming.
+   */
+  thinking(label?: string): void;
+
+  /**
+   * Stream the answer as it is produced.
+   *
+   * @param text - The whole visible answer so far, not the newest fragment.
+   * Replace the bubble's contents with it; appending accumulates the answer on
+   * itself. Tool-call markers are already stripped.
+   */
+  update(text: string): void;
+
+  /**
+   * Close the bubble with its final text.
+   *
+   * Usually the last call a bubble receives, but not guaranteed to be: when the
+   * model answers with a question instead of calling a tool, the harness runs a
+   * second generation into the same bubble, so `update` can follow a non-empty
+   * `finalize`. Implementations should stay usable rather than throwing.
+   *
+   * @param text - The text to keep. Empty means the phase produced nothing
+   * worth keeping (a failed load, a finished tool call, a generation that was
+   * only a tool call), and the bubble should be removed rather than left blank.
+   */
+  finalize(text: string): void;
+}
+
+/** A write tool with every value resolved, awaiting a human press. */
+export interface ConfirmRequest {
+  /** The tool about to be called. */
+  tool: ModelContextToolInfo;
+  /** Rows to display read-only. Nothing is missing, so nothing is editable. */
+  slots: Slot[];
+  /** The values that will be sent. */
+  values: Record<string, unknown>;
+  /**
+   * What the submit button should say, when "Submit" would understate it.
+   *
+   * Set for a form on another page of the site, where pressing submit also
+   * takes the visitor there: `'Open & submit'`. Short on purpose, since a
+   * card in a window or a rail has little room; {@link destination} carries
+   * the rest. A renderer that ignores both still works, but the page change
+   * arrives unannounced.
+   */
+  submitLabel?: string;
+  /**
+   * The page pressing submit will open, named for the visitor:
+   * `'Royal Oak Remodeling'`. Set with {@link submitLabel}, for a renderer
+   * to say in a sentence what the button no longer has room to.
+   */
+  destination?: string;
+  /** Call to proceed, optionally with values the user amended. */
+  onSubmit(values: Record<string, unknown>): void;
+  /** Call if the user declines. */
+  onCancel(): void;
+  /** Call to open the full editable form instead of confirming. */
+  onEdit(): void;
+}
+
+/** A tool call missing required values, and the plan for asking about them. */
+export interface AskRequest {
+  /** The tool waiting on the answers. */
+  tool: ModelContextToolInfo;
+  /** The questions to ask, as one step or several. */
+  plan: ClarificationPlan;
+  /** What is already known, and from where. */
+  resolution: Resolution;
+  /** Call with the merged values once the last step is answered. */
+  onComplete(values: Record<string, unknown>): void;
+  /** Call if the user abandons the questions. */
+  onCancel(): void;
+}
+
+/**
+ * Everything the harness needs from a user interface.
+ *
+ * Required members are called during an ordinary turn. Optional ones may be
+ * omitted by a renderer that has nothing to show for them.
+ */
+export interface HarnessRenderer {
+  /** Add a complete message, already known in full. */
+  message(role: 'user' | 'assistant', text: string): void;
+
+  /**
+   * Open a bubble for the phase about to start.
+   *
+   * Called several times per turn: once before the model is touched, so the
+   * thread is never silent while weights download, and again around each tool
+   * call. Each bubble is finalized before the next is requested.
+   *
+   * @returns The bubble the harness will drive through that phase.
+   */
+  streaming(): StreamingBubble;
+
+  /**
+   * Show a one-line status outside the thread, such as a header strip.
+   *
+   * @param text - The status. Empty clears it.
+   * @param isError - Whether to present the status as a failure.
+   */
+  status(text: string, isError?: boolean): void;
+
+  /** Ask for missing values, as one question or a stepper. */
+  ask(req: AskRequest): void;
+  /** Present a write for confirmation. Nothing is missing. */
+  confirm(req: ConfirmRequest): void;
+
+  /** A read tool returned records. */
+  results(tool: ModelContextToolInfo, res: ModelContextToolResponse): void;
+  /** A write tool succeeded. */
+  detail(tool: ModelContextToolInfo, values: Record<string, unknown>, text: string): void;
+  /** A tool failed, or returned something that cannot be rendered. */
+  toolError(tool: ModelContextToolInfo, message: string): void;
+
+  /**
+   * Record the exchange behind a rendered card.
+   *
+   * Distinct from {@link HarnessRenderer.results} and
+   * {@link HarnessRenderer.detail}, which draw the outcome the user asked for.
+   * A trace is the underlying call and raw response, suited to a collapsed
+   * panel. Omit it to record nothing.
+   */
+  trace?(entry: TraceEntry): void;
+
+  /**
+   * Report what the agent is doing, for a surface that shows progress.
+   *
+   * The thread says what was said; this says that the page is about to
+   * change, or that a form is being filled right now. A chat panel can ignore
+   * it — the status line and the cards already cover the same ground — and a
+   * copilot surface beside the page is built on it.
+   *
+   * @param step - The step that changed.
+   * @param all - Every step of this journey, oldest first, including the ones
+   * taken before a page change.
+   */
+  step?(step: AgentStep, all: AgentStep[]): void;
+
+  /** Tear down any live ask or confirm UI. */
+  dismissPrompt?(): void;
+
+  /**
+   * Report whether the turn can still be stopped.
+   *
+   * Called with `true` when a turn starts and `false` when it ends, and also
+   * `false` as soon as a tool is invoked: past that point the call may already
+   * have reached a server, so it can no longer be cancelled.
+   *
+   * @param canStop - Whether {@link AgentHarness.stop} would still take effect.
+   */
+  stoppable?(canStop: boolean): void;
+}

package/src/harness/router/coordinator.ts

@@ -0,0 +1,241 @@
+/**
+ * Routes each turn to one of several {@link AgentHarness} instances.
+ *
+ * The coordinator holds no tools and produces no answers of its own. Its only
+ * job is choosing which agent handles a turn, so that agent sends the model its
+ * own few tool definitions rather than every tool on the page.
+ *
+ * It decides in four stages, cheapest first:
+ *
+ * | Stage | Cost | When it applies |
+ * |---|---|---|
+ * | `rules` | microseconds | A rule table matches the goal unambiguously. |
+ * | `sticky` | none | The rules abstained, and this conversation is already with an agent. |
+ * | `model` | one generation | The rules abstained and there is no history. Requires `provider`. |
+ * | `fallback` | none | Nothing else decided. |
+ *
+ * After the fact it applies one correction: if the chosen agent reports that
+ * the model asked for a tool it does not hold, the turn moves once to the agent
+ * that does.
+ *
+ * @module
+ */
+import type { ChatMessage } from '../../types.js';
+import type { ModelProvider } from '../../providers/types.js';
+import type { AgentHarness, TurnResult } from '../harness.js';
+import type { HandoffController } from '../../handoff/controller.js';
+import { matchRoute, type RouteDecision, type RouteRule } from './rules.js';
+
+/** How a turn's agent was chosen. */
+/** Which stage of {@link AgentCoordinator} chose the agent for a turn. */
+export type RouteSource = 'rules' | 'sticky' | 'model' | 'fallback' | 'handback';
+
+/** Configuration for an {@link AgentCoordinator}. */
+export interface CoordinatorOptions {
+  /** The agents to route between, keyed by the name the rules refer to. */
+  agents: Record<string, AgentHarness>;
+  /** The rule table scored against each goal. May be empty. */
+  rules: RouteRule[];
+  /**
+   * The agent an otherwise unroutable turn goes to.
+   *
+   * Must name a key of {@link CoordinatorOptions.agents}; the constructor
+   * throws if it does not.
+   */
+  fallback: string;
+  /**
+   * Enables the model classification stage, which is otherwise skipped.
+   *
+   * This is the only part of routing that costs a generation, so it runs only
+   * when the rules abstain and no stickiness applies.
+   */
+  provider?: ModelProvider;
+  /** One line per agent describing what it handles, shown to the classifier. */
+  descriptions?: Record<string, string>;
+  /** Called with every routing decision, including corrections. */
+  onRoute?(decision: RoutedTurn): void;
+  /**
+   * Handoffs to remote agents and people.
+   *
+   * While a conversation is handed off, its turns go to the target rather than
+   * to any agent here, and resolve with `decision: 'handoff'`. Routing returns
+   * to the agents when the target finishes or the visitor ends the handoff.
+   */
+  handoff?: {
+    controller: HandoffController;
+    /** The id the controller knows this conversation by. */
+    conversationId(messages: ChatMessage[]): string | undefined;
+  };
+}
+
+/** A routing decision, reported through {@link CoordinatorOptions.onRoute}. */
+export interface RoutedTurn extends RouteDecision {
+  /** The agent that ran, which may differ from {@link RouteDecision.route}. */
+  agent: string;
+  /** Which stage chose the agent. */
+  via: RouteSource;
+  /** True when no stage decided and the fallback was used. */
+  fellBack: boolean;
+  /** The user message that was routed. */
+  goal: string;
+}
+
+/** Token ceiling for the classification pass, whose answer is one agent name. */
+const CLASSIFY_MAX_TOKENS = 12;
+
+/**
+ * Routes turns between several agents. See the module description for the
+ * stages it decides in.
+ */
+export class AgentCoordinator {
+  /**
+   * The agent each conversation is currently with.
+   *
+   * Keyed by the transcript array itself, so several conversations can be open
+   * at once and a discarded one takes its routing state with it.
+   */
+  private readonly sticky = new WeakMap<ChatMessage[], string>();
+  /** The classification pass in flight, if any. */
+  private classifying: AbortController | null = null;
+  /** The agent handling the current turn, so {@link stop} can reach it. */
+  private working: AgentHarness | null = null;
+
+  constructor(private readonly opts: CoordinatorOptions) {
+    if (!opts.agents[opts.fallback]) {
+      throw new Error(`Coordinator fallback "${opts.fallback}" is not one of its agents.`);
+    }
+  }
+
+  /**
+   * Abandon the turn in flight, whichever stage it has reached.
+   *
+   * Aborts the classification pass and delegates to the agent handling the
+   * turn, which resolves as `'stopped'`. Safe to call when nothing is running.
+   */
+  stop(): void {
+    this.classifying?.abort();
+    this.classifying = null;
+    this.working?.stop();
+  }
+
+  /**
+   * Decide which agent should take a turn, without running it.
+   *
+   * Covers the rules, sticky and fallback stages. The model stage is skipped,
+   * since it is asynchronous and costs a generation.
+   *
+   * @param goal - The user's message.
+   * @param messages - The conversation, consulted for stickiness. Optional.
+   * @returns The chosen agent and the stage that chose it.
+   */
+  route(goal: string, messages?: ChatMessage[]): RoutedTurn {
+    const decision = matchRoute(goal, this.opts.rules);
+    const named = decision.route && this.opts.agents[decision.route] ? decision.route : null;
+    if (named) return { ...decision, agent: named, via: 'rules', fellBack: false, goal };
+
+    const held = messages && this.sticky.get(messages);
+    if (held && this.opts.agents[held]) {
+      return { ...decision, agent: held, via: 'sticky', fellBack: false, goal };
+    }
+    return { ...decision, agent: this.opts.fallback, via: 'fallback', fellBack: true, goal };
+  }
+
+  /**
+   * Route a turn, run it, and re-route it once if it reached the wrong agent.
+   *
+   * @param goal - The user's message.
+   * @param messages - The live conversation, appended to in place.
+   * @returns The chosen agent's {@link TurnResult}.
+   */
+  async turn(goal: string, messages: ChatMessage[]): Promise<TurnResult> {
+    // A handed-off conversation belongs to its target until it hands back.
+    const handoff = this.opts.handoff;
+    const conversationId = handoff?.conversationId(messages);
+    if (handoff && handoff.controller.active(conversationId)) {
+      await handoff.controller.send(conversationId!, goal);
+      return { decision: 'handoff' };
+    }
+
+    let routed = this.route(goal, messages);
+
+    // The model is only asked when nothing cheaper had an opinion.
+    if (routed.via === 'fallback' && this.opts.provider) {
+      const guessed = await this.classify(goal);
+      if (guessed) routed = { ...routed, agent: guessed, via: 'model', fellBack: false };
+    }
+
+    this.opts.onRoute?.(routed);
+    this.sticky.set(messages, routed.agent);
+
+    this.working = this.opts.agents[routed.agent];
+    const result = await this.working.turn(goal, messages);
+
+    // Release stickiness after a refusal, so the next unclear follow-up is not
+    // routed back to the one agent known to lack the tools for it.
+    if (result.decision === 'unavailable') this.sticky.delete(messages);
+
+    if (result.decision !== 'handback' || !result.wanted) return result;
+
+    // Exactly one correction: the owner's answer stands whatever it is. Without
+    // the cap, two agents that disagree could pass a turn back and forth.
+    const owner = this.ownerOf(result.wanted, routed.agent);
+    if (!owner) return result;
+
+    const moved: RoutedTurn = { ...routed, agent: owner, via: 'handback', fellBack: false };
+    this.opts.onRoute?.(moved);
+    this.sticky.set(messages, owner);
+    this.working = this.opts.agents[owner];
+    return this.working.turn(goal, messages);
+  }
+
+  /** The agent holding a tool, ignoring the one that handed the turn back. */
+  private ownerOf(tool: string, except: string): string | null {
+    for (const [name, agent] of Object.entries(this.opts.agents)) {
+      if (name !== except && agent.owns(tool)) return name;
+    }
+    return null;
+  }
+
+  /**
+   * Ask the model which agent should take the turn.
+   *
+   * One short generation with no tools. Any reply that does not name a known
+   * agent returns null, leaving the fallback in place.
+   */
+  private async classify(goal: string): Promise<string | null> {
+    const provider = this.opts.provider;
+    if (!provider) return null;
+    const names = Object.keys(this.opts.agents);
+    const menu = names
+      .map((n) => `- ${n}: ${this.opts.descriptions?.[n] ?? 'handles ' + n + ' requests'}`)
+      .join('\n');
+
+    this.classifying = new AbortController();
+    try {
+      const reply = await provider.complete({
+        messages: [
+          {
+            role: 'system',
+            content:
+              'Choose which assistant should handle the message. ' +
+              `Answer with exactly one of these names and nothing else:\n${menu}`,
+          },
+          { role: 'user', content: goal },
+        ],
+        tools: [],
+        maxTokens: CLASSIFY_MAX_TOKENS,
+        signal: this.classifying.signal,
+      });
+      const said = reply.text.toLowerCase();
+      // Longest name first, so a shorter name that is a substring of another
+      // does not match in its place.
+      const found = [...names]
+        .sort((a, b) => b.length - a.length)
+        .find((n) => said.includes(n.toLowerCase()));
+      return found ?? null;
+    } catch {
+      // Routing must not fail a turn: the fallback covers a failed pass.
+      return null;
+    }
+  }
+}

package/src/harness/router/rules.ts

@@ -0,0 +1,65 @@
+/**
+ * Pattern-based routing, used before falling back to a model classification.
+ *
+ * Matching a table of regular expressions costs microseconds, where a
+ * classification pass costs a generation. Rules run first and may abstain by
+ * returning a null route, which is what tells {@link AgentCoordinator} that a
+ * model pass is worth its cost.
+ *
+ * @module
+ */
+
+/** One pattern, and the agent it votes for. */
+export interface RouteRule {
+  /** The agent this rule votes for. */
+  route: string;
+  /** Tested against the goal, lower-cased. */
+  match: RegExp;
+/**
+   * How much this rule's vote counts. Defaults to 1.
+   *
+   * Raise it so a specific phrase outscores a general one when both match.
+   */
+  weight?: number;
+  /** A note on the rule's purpose, carried through to {@link RouteDecision}. */
+  because?: string;
+}
+
+/** The result of scoring a goal against a rule table. */
+export interface RouteDecision {
+  /** The winning agent, or null when no rule matched or two rules tied. */
+  route: string | null;
+  /** Total score per route, highest first. Empty when nothing matched. */
+  scores: [string, number][];
+  /** Every rule that matched, in table order. */
+  matched: RouteRule[];
+}
+
+/**
+ * Score a goal against a rule table and return the highest-scoring agent.
+ *
+ * Ties abstain rather than picking arbitrarily, since routing to an agent that
+ * lacks the required tool is more costly than the model pass that resolves the
+ * ambiguity.
+ *
+ * @param goal - The user's message. Matched lower-cased.
+ * @param rules - The table to score against.
+ * @returns The winning route, or a null route when nothing matched or the top
+ * two scores are equal.
+ */
+export function matchRoute(goal: string, rules: RouteRule[]): RouteDecision {
+  const text = goal.toLowerCase();
+  const matched = rules.filter((r) => r.match.test(text));
+
+  const totals = new Map<string, number>();
+  for (const rule of matched) {
+    totals.set(rule.route, (totals.get(rule.route) ?? 0) + (rule.weight ?? 1));
+  }
+
+  const scores = [...totals.entries()].sort((a, b) => b[1] - a[1]);
+  if (!scores.length) return { route: null, scores, matched };
+  if (scores.length > 1 && scores[0][1] === scores[1][1]) {
+    return { route: null, scores, matched };
+  }
+  return { route: scores[0][0], scores, matched };
+}