@moxxy/sdk 0.41.3 → 0.42.1

package/src/tool-gating.test.ts

@@ -0,0 +1,81 @@
+import { describe, expect, it } from 'vitest';
+import { z } from 'zod';
+import { defineTool } from './define.js';
+import type { MoxxyEvent, MoxxyEventOfType, MoxxyEventType } from './events.js';
+import { asEventId, asSessionId, asToolCallId, asTurnId, type TurnId } from './ids.js';
+import type { EventLogReader } from './log.js';
+import type { ProviderMessage } from './provider.js';
+import { LAZY_TOOLS_AUTO_THRESHOLD, applyLazyTools, matchLoadableTools, shouldGateTools } from './tool-gating.js';
+
+const mk = (name: string) => defineTool({ name, description: `desc ${name}`, inputSchema: z.object({}), handler: () => '' });
+const messages: ProviderMessage[] = [{ role: 'system', content: [{ type: 'text', text: 'sys' }] }];
+const systemText = (out: ReadonlyArray<ProviderMessage>) => (out[0]?.content[0] as { text: string }).text;
+
+function logOfLoads(...names: string[]): EventLogReader {
+  const events = names.map((name, seq) => ({
+    id: asEventId(`e${seq}`), seq, ts: seq, sessionId: asSessionId('s'), turnId: asTurnId('t'), source: 'model',
+    type: 'tool_call_requested', callId: asToolCallId(`c${seq}`), name: 'load_tool', input: { name },
+  }) as MoxxyEvent);
+  return {
+    length: events.length,
+    at: (seq) => events[seq],
+    slice: (from = 0, to = events.length) => events.slice(from, to),
+    ofType: <T extends MoxxyEventType>(type: T): ReadonlyArray<MoxxyEventOfType<T>> => events.filter((e): e is MoxxyEventOfType<T> => e.type === type),
+    byTurn: (turnId: TurnId) => events.filter((e) => e.turnId === turnId),
+    toJSON: () => events,
+  };
+}
+
+const computer = ['computer_status', 'computer_click', 'computer_drag', 'computer_zoom'].map(mk);
+const zoho = ['mcp__zoho__list', 'mcp__zoho__get', 'mcp__zoho__add', 'mcp__zoho__drop'].map(mk);
+
+describe('tool families', () => {
+  it('lists a family of tools as one line that names how to load all of it', () => {
+    const { messages: out, tools } = applyLazyTools(messages, [mk('Read'), ...computer, mk('web_fetch')], logOfLoads());
+    expect(tools.map((t) => t.name)).toEqual(['Read']);
+    const text = systemText(out);
+    expect(text).toContain('- **computer_*** (4 tools: computer_status, computer_click, computer_drag, computer_zoom)');
+    expect(text).toContain('load_tool({ name: "computer_*" })');
+    expect(text).toContain('- **web_fetch** — desc web_fetch');
+    expect(text).not.toContain('desc computer_click');
+  });
+
+  it('groups tools of one MCP server by the server, not by "mcp"', () => {
+    const text = systemText(applyLazyTools(messages, [...zoho, mk('mcp__mail__send')], logOfLoads()).messages);
+    expect(text).toContain('- **mcp__zoho__*** (4 tools: ');
+    expect(text).toContain('- **mcp__mail__send** — ');
+  });
+
+  it('loads the whole family from one load_tool call, and leaves other families indexed', () => {
+    const { messages: out, tools } = applyLazyTools(messages, [mk('Read'), ...computer, ...zoho], logOfLoads('computer_*'));
+    expect(tools.map((t) => t.name)).toEqual(['Read', ...computer.map((t) => t.name)]);
+    expect(systemText(out)).not.toContain('computer_click');
+    expect(systemText(out)).toContain('mcp__zoho__*');
+  });
+
+  it('sends a tool marked always loaded in full, and indexes the rest of its family', () => {
+    const run = defineTool({ name: 'computer_run', description: 'desc computer_run', inputSchema: z.object({}), alwaysLoaded: true, handler: () => '' });
+    const { messages: out, tools } = applyLazyTools(messages, [mk('Read'), run, ...computer], logOfLoads());
+    expect(tools.map((t) => t.name)).toEqual(['Read', 'computer_run']);
+    expect(systemText(out)).toContain('- **computer_*** (4 tools: computer_status, computer_click, computer_drag, computer_zoom)');
+  });
+
+  it('resolves what a load_tool name stands for', () => {
+    const all = [...computer, ...zoho];
+    expect(matchLoadableTools('computer_*', all).map((t) => t.name)).toEqual(computer.map((t) => t.name));
+    expect(matchLoadableTools('computer_click', all).map((t) => t.name)).toEqual(['computer_click']);
+    expect(matchLoadableTools('nothing_*', all)).toEqual([]);
+  });
+});
+
+describe('shouldGateTools', () => {
+  it('follows an explicit setting', () => {
+    expect(shouldGateTools(true, 3)).toBe(true);
+    expect(shouldGateTools(false, 5000)).toBe(false);
+  });
+
+  it('turns itself on when nothing is set and the tool list is long', () => {
+    expect(shouldGateTools(undefined, LAZY_TOOLS_AUTO_THRESHOLD)).toBe(false);
+    expect(shouldGateTools(undefined, LAZY_TOOLS_AUTO_THRESHOLD + 1)).toBe(true);
+  });
+});

package/src/tool-gating.ts

@@ -50,16 +50,61 @@ function truncate(s: string, n: number): string {
   return s.length <= n ? s : `${s.slice(0, n - 1)}…`;
 }
 
-/** Compact index (name + 1-line description) of not-yet-loaded tools. */
+/** Above this many registered tools, lazy loading turns itself on unless the config says otherwise. */
+export const LAZY_TOOLS_AUTO_THRESHOLD = 200;
+
+/** Whether to gate tools: an explicit setting wins; unset means "only when the list is long". */
+export function shouldGateTools(setting: boolean | undefined, toolCount: number): boolean {
+  return setting ?? toolCount > LAZY_TOOLS_AUTO_THRESHOLD;
+}
+
+/** A family needs this many members before the index folds it into one line. */
+const FAMILY_MIN = 4;
+
+/** The prefix a tool shares with its siblings: its MCP server, or the word before the first underscore. */
+function familyPrefix(name: string): string | null {
+  const mcp = /^mcp__[^_]+(?:_[^_]+)*__/.exec(name);
+  if (mcp) return mcp[0];
+  const cut = name.indexOf('_');
+  return cut > 0 ? name.slice(0, cut + 1) : null;
+}
+
+/** The tools a `load_tool` name stands for: one tool, or a family written as `prefix*`. */
+export function matchLoadableTools<T extends { readonly name: string }>(name: string, tools: ReadonlyArray<T>): T[] {
+  if (!name.endsWith('*')) return tools.filter((t) => t.name === name);
+  const prefix = name.slice(0, -1);
+  return prefix.length === 0 ? [] : tools.filter((t) => t.name.startsWith(prefix));
+}
+
+/** Compact index of not-yet-loaded tools: one line per family, one per tool outside a family. */
 export function buildToolIndex(hidden: ReadonlyArray<ToolDef>): string {
-  const lines = hidden
-    .map((t) => `- **${t.name}** — ${truncate(oneLine(t.description ?? ''), 100)}`)
-    .join('\n');
+  const families = new Map<string, string[]>();
+  for (const t of hidden) {
+    const prefix = familyPrefix(t.name);
+    if (prefix === null) continue;
+    const members = families.get(prefix);
+    if (members) members.push(t.name);
+    else families.set(prefix, [t.name]);
+  }
+  const listed = new Set<string>();
+  const lines: string[] = [];
+  for (const t of hidden) {
+    const prefix = familyPrefix(t.name);
+    const members = prefix === null ? undefined : families.get(prefix);
+    if (prefix !== null && members && members.length >= FAMILY_MIN) {
+      if (listed.has(prefix)) continue;
+      listed.add(prefix);
+      lines.push(`- **${prefix}*** (${members.length} tools: ${members.join(', ')})`);
+    } else {
+      lines.push(`- **${t.name}** — ${truncate(oneLine(t.description ?? ''), 100)}`);
+    }
+  }
   return (
     `## Loadable tools\n\n` +
     `These tools exist but their full schemas are not loaded right now. When a ` +
     `task needs one, call \`load_tool({ name: "<tool-name>" })\` first, then call ` +
-    `the tool on the next turn.\n\n${lines}`
+    `the tool on the next turn. A line ending in \`*\` is a family: load all of it ` +
+    `at once with its name, e.g. \`load_tool({ name: "computer_*" })\`.\n\n${lines.join('\n')}`
   );
 }
 
@@ -99,7 +144,8 @@ export function applyLazyTools(
   tools: ReadonlyArray<ToolDef>,
   log: EventLogReader,
 ): GatedTools {
-  const loaded = loadedToolNames(log);
+  const loaded = new Set<string>();
+  for (const name of loadedToolNames(log)) for (const t of matchLoadableTools(name, tools)) loaded.add(t.name);
   // Single partition pass: each tool is either visible (always-on or loaded) or
   // hidden, never both — so one loop yields the exact same two arrays (same
   // elements, same input order) the prior pair of complementary `filter`s did,
@@ -107,7 +153,7 @@ export function applyLazyTools(
   const visible: ToolDef[] = [];
   const hidden: ToolDef[] = [];
   for (const t of tools) {
-    (ALWAYS_ON_TOOLS.has(t.name) || loaded.has(t.name) ? visible : hidden).push(t);
+    (ALWAYS_ON_TOOLS.has(t.name) || t.alwaysLoaded === true || loaded.has(t.name) ? visible : hidden).push(t);
   }
   if (hidden.length === 0) return { messages, tools };
   return { messages: injectIntoSystem(messages, buildToolIndex(hidden)), tools: visible };

package/src/tool-modes.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it } from 'vitest';
+import { z } from 'zod';
+import { defineTool } from './define.js';
+import type { ToolRegistry } from './mode.js';
+import { toolsForMode } from './tool-modes.js';
+
+/**
+ * A tool that only means something in one mode — goal mode's goal_abandon, a
+ * collaboration's collab_inbox — was offered in every mode. In a plain browser
+ * task the model called collab_inbox ("Not in a collaboration") and then
+ * goal_abandon, and gave up on a task it could do. Such a tool names its modes,
+ * and the others do not see it.
+ */
+const tool = (name: string, modes?: string[]) =>
+  defineTool({ name, description: name, inputSchema: z.object({}), handler: async () => name, ...(modes ? { modes } : {}) });
+
+const registry: ToolRegistry = {
+  list: () => [tool('Read'), tool('goal_abandon', ['goal']), tool('collab_inbox', ['collab-architect', 'collab-peer'])],
+  get: (name) => registry.list().find((t) => t.name === name),
+  execute: async (name) => name,
+};
+const signal = new AbortController().signal;
+
+describe('defineTool', () => {
+  it('keeps the modes a tool is for', () => {
+    expect(tool('goal_abandon', ['goal']).modes).toEqual(['goal']);
+    expect(tool('Read')).not.toHaveProperty('modes');
+  });
+});
+
+describe('toolsForMode', () => {
+  it('leaves a tool meant for other modes out of the list and out of reach', async () => {
+    const tools = toolsForMode(registry, 'default');
+
+    expect(tools.list().map((t) => t.name)).toEqual(['Read']);
+    expect(tools.get('goal_abandon')).toBeUndefined();
+    await expect(tools.execute('Read', {}, signal)).resolves.toBe('Read');
+    await expect(tools.execute('goal_abandon', {}, signal)).rejects.toThrow(/goal_abandon is not available in default mode/);
+  });
+
+  it('offers it in a mode it names', () => {
+    expect(toolsForMode(registry, 'goal').list().map((t) => t.name)).toEqual(['Read', 'goal_abandon']);
+    expect(toolsForMode(registry, 'collab-peer').get('collab_inbox')?.name).toBe('collab_inbox');
+  });
+});

package/src/tool-modes.ts

@@ -0,0 +1,23 @@
+import type { ToolRegistry } from './mode.js';
+import type { ToolDef } from './tool.js';
+
+const offeredIn = (tool: ToolDef | undefined, mode: string): boolean => !tool?.modes || tool.modes.includes(mode);
+
+/**
+ * The registry as a mode sees it: a tool that names its modes is left out of
+ * the others — not offered to the model, and refused if called anyway. It stays
+ * registered, so its permission and isolation are looked up as before.
+ */
+export function toolsForMode(tools: ToolRegistry, mode: string): ToolRegistry {
+  return {
+    list: () => tools.list().filter((tool) => offeredIn(tool, mode)),
+    get: (name) => {
+      const tool = tools.get(name);
+      return offeredIn(tool, mode) ? tool : undefined;
+    },
+    execute: async (name, input, signal, opts) => {
+      if (!offeredIn(tools.get(name), mode)) throw new Error(`${name} is not available in ${mode} mode`);
+      return tools.execute(name, input, signal, opts);
+    },
+  };
+}

package/src/tool.ts

@@ -212,4 +212,22 @@ export interface ToolDef {
    * enforces these bounds at every call. See `ToolIsolationSpec`.
    */
   readonly isolation?: ToolIsolationSpec;
+  /**
+   * The tool reads state that changes outside the conversation (an app's
+   * window, a running job), so the same call between other calls is normal.
+   * The stuck-loop guard then counts only a back-to-back run of it.
+   */
+  readonly liveState?: boolean;
+  /**
+   * Sent in full even when the tool list is gated: a tool a task starts with,
+   * where loading it first would cost a model round. Each one is paid for on
+   * every request, so mark the entry point of a family, not the family.
+   */
+  readonly alwaysLoaded?: boolean;
+  /**
+   * The modes this tool is offered in; omitted = every mode. For a tool that
+   * means nothing elsewhere (goal mode's goal_abandon), so it is no way out of
+   * a task in a mode that never asked for it. See `toolsForMode`.
+   */
+  readonly modes?: ReadonlyArray<string>;
 }

package/src/wait-for.test.ts

@@ -0,0 +1,132 @@
+import { EventEmitter, getEventListeners } from 'node:events';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { waitFor, wakeAfter, type WakeSource } from './wait-for.js';
+
+afterEach(() => {
+  vi.useRealTimers();
+});
+
+/** A job that finishes when told to and wakes whoever listens. */
+function job() {
+  const emitter = new EventEmitter();
+  let result: string | undefined;
+  const changed: WakeSource = (wake) => {
+    emitter.on('change', wake);
+    return () => emitter.off('change', wake);
+  };
+  return {
+    changed,
+    result: () => result,
+    finish(value: string) {
+      result = value;
+      emitter.emit('change');
+    },
+    listeners: () => emitter.listenerCount('change'),
+  };
+}
+
+describe('waitFor', () => {
+  it('wakes the moment the job reports completion, without any timer tick', async () => {
+    vi.useFakeTimers();
+    const j = job();
+    const waiting = waitFor(j.result, { wakeOn: [j.changed], timeoutMs: 60_000 });
+
+    j.finish('built');
+
+    await expect(waiting).resolves.toEqual({ status: 'ready', value: 'built' });
+  });
+
+  it('returns at once when the job finished before the wait began', async () => {
+    const j = job();
+    j.finish('already done');
+
+    await expect(waitFor(j.result, { wakeOn: [j.changed] })).resolves.toEqual({
+      status: 'ready',
+      value: 'already done',
+    });
+  });
+
+  it('keeps waiting through wakes that do not settle the condition', async () => {
+    const emitter = new EventEmitter();
+    let lines = 0;
+    const waiting = waitFor(() => (lines >= 3 ? lines : undefined), {
+      wakeOn: [(wake) => (emitter.on('line', wake), () => emitter.off('line', wake))],
+    });
+
+    for (let i = 0; i < 3; i++) {
+      lines += 1;
+      emitter.emit('line');
+    }
+
+    await expect(waiting).resolves.toEqual({ status: 'ready', value: 3 });
+  });
+
+  it('reports a deadline as "still running", not as finished', async () => {
+    vi.useFakeTimers();
+    const j = job();
+    const waiting = waitFor(j.result, { wakeOn: [j.changed], timeoutMs: 5_000 });
+
+    await vi.advanceTimersByTimeAsync(5_000);
+
+    await expect(waiting).resolves.toEqual({ status: 'timeout' });
+  });
+
+  it('stops waiting when the turn is aborted', async () => {
+    const j = job();
+    const ac = new AbortController();
+    const waiting = waitFor(j.result, { wakeOn: [j.changed], signal: ac.signal });
+
+    ac.abort();
+
+    await expect(waiting).resolves.toEqual({ status: 'aborted' });
+  });
+
+  it('leaves no listener or timer behind after any outcome', async () => {
+    vi.useFakeTimers();
+    const ac = new AbortController();
+    const done = job();
+    await (done.finish('x'), waitFor(done.result, { wakeOn: [done.changed], timeoutMs: 1_000, signal: ac.signal }));
+    const late = job();
+    const timedOut = waitFor(late.result, { wakeOn: [late.changed], timeoutMs: 1_000, signal: ac.signal });
+    await vi.advanceTimersByTimeAsync(1_000);
+    await timedOut;
+
+    expect(done.listeners()).toBe(0);
+    expect(late.listeners()).toBe(0);
+    expect(getEventListeners(ac.signal, 'abort')).toHaveLength(0);
+    expect(vi.getTimerCount()).toBe(0);
+  });
+
+  it('rejects with the check’s error and cleans up', async () => {
+    const j = job();
+    let broken = false;
+    const waiting = waitFor(
+      () => {
+        if (broken) throw new Error('status read failed');
+        return undefined;
+      },
+      { wakeOn: [j.changed] },
+    );
+
+    broken = true;
+    j.finish('ignored');
+
+    await expect(waiting).rejects.toThrow('status read failed');
+    expect(j.listeners()).toBe(0);
+  });
+});
+
+describe('wakeAfter', () => {
+  it('re-checks a time-based condition once its moment passes', async () => {
+    vi.useFakeTimers();
+    const bootDeadline = Date.now() + 1_000;
+    const waiting = waitFor(() => (Date.now() >= bootDeadline ? 'gave up booting' : undefined), {
+      wakeOn: [wakeAfter(1_000)],
+    });
+
+    await vi.advanceTimersByTimeAsync(1_000);
+
+    await expect(waiting).resolves.toEqual({ status: 'ready', value: 'gave up booting' });
+    expect(vi.getTimerCount()).toBe(0);
+  });
+});

package/src/wait-for.ts

@@ -0,0 +1,79 @@
+/**
+ * Event-driven waiting: sleep until something says "look again", not on a
+ * fixed poll interval. A waiter resumes the moment its job reports progress,
+ * and a deadline only bounds the wait — it never means the job finished.
+ */
+
+/** Subscribes `wake` to a change signal; returns the unsubscribe. */
+export type WakeSource = (wake: () => void) => () => void;
+
+export type WaitOutcome<T> =
+  | { readonly status: 'ready'; readonly value: T }
+  /** The deadline passed while the job was still running. */
+  | { readonly status: 'timeout' }
+  | { readonly status: 'aborted' };
+
+export interface WaitForOptions {
+  /** Every signal after which `check` may give a different answer. */
+  readonly wakeOn: ReadonlyArray<WakeSource>;
+  readonly timeoutMs?: number;
+  readonly signal?: AbortSignal;
+}
+
+/**
+ * Resolve once `check` returns a value (anything but `undefined`), re-checking
+ * only when a wake source fires. Subscribes BEFORE the first check, so a job
+ * that finishes between "read the status" and "start listening" is never
+ * missed. Every listener and timer is released on any outcome.
+ */
+export function waitFor<T>(
+  check: () => T | undefined,
+  opts: WaitForOptions,
+): Promise<WaitOutcome<T>> {
+  return new Promise((resolve, reject) => {
+    const { signal, timeoutMs } = opts;
+    if (signal?.aborted) {
+      resolve({ status: 'aborted' });
+      return;
+    }
+    let settled = false;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const unsubscribes: Array<() => void> = [];
+
+    const finish = (outcome: WaitOutcome<T> | Error): void => {
+      if (settled) return;
+      settled = true;
+      if (timer !== undefined) clearTimeout(timer);
+      signal?.removeEventListener('abort', onAbort);
+      for (const unsubscribe of unsubscribes) unsubscribe();
+      if (outcome instanceof Error) reject(outcome);
+      else resolve(outcome);
+    };
+    const onAbort = (): void => finish({ status: 'aborted' });
+    const recheck = (): void => {
+      if (settled) return;
+      let value: T | undefined;
+      try {
+        value = check();
+      } catch (error) {
+        finish(error instanceof Error ? error : new Error(String(error)));
+        return;
+      }
+      if (value !== undefined) finish({ status: 'ready', value });
+    };
+
+    for (const source of opts.wakeOn) unsubscribes.push(source(recheck));
+    signal?.addEventListener('abort', onAbort, { once: true });
+    if (timeoutMs !== undefined) timer = setTimeout(() => finish({ status: 'timeout' }), timeoutMs);
+    recheck();
+  });
+}
+
+/** A wake source that fires once after `ms` — for conditions that turn on time
+ *  itself (a boot deadline), so they are re-checked exactly when they can flip. */
+export function wakeAfter(ms: number): WakeSource {
+  return (wake) => {
+    const timer = setTimeout(wake, ms);
+    return () => clearTimeout(timer);
+  };
+}