@iloveagents/foundry-agent 0.1.0

package/AGENTS.md

@@ -0,0 +1,91 @@
+Pure-TS agent transport for the LastSpace open-core stack. Published as `@iloveagents/foundry-agent`. Zero DOM, zero React, zero `@assistant-ui/*`. Cross-runtime — consumed by `@iloveagents/foundry-web-ui` today, future Outlook / Teams / native shells tomorrow.
+
+# Architecture
+
+```
+src/
+  client/
+    agui-runner.ts    ← AG-UI protocol engine (SSE + multi-turn loop). Yields RunnerEvent.
+    runner-events.ts  ← RunnerEvent discriminated union.
+    service-fetch.ts  ← createServiceFetch({ acquireToken, baseUrl }) factory.
+  store/
+    streaming-status-store.ts  ← vanilla zustand store
+    citation-store.ts          ← vanilla zustand store
+  tools/
+    registry.ts       ← clientToolRegistry (vanilla zustand store).
+  msal/               ← subpath export: @iloveagents/foundry-agent/msal
+    auth-store.ts     ← authStore (vanilla zustand store)
+    auth-config.ts    ← MsalAuthConfig + initializeMsal singleton.
+    token-fetch.ts    ← Bearer-token-attaching fetch.
+    index.ts          ← barrel for the /msal subpath
+  index.ts            ← barrel for the root export.
+  __tests__/          ← vitest suite (runner, service-fetch, no-react smoke).
+```
+
+# Import boundary (enforced by guard test)
+
+Files under `packages/agent/src/` (excluding `msal/`) MUST NOT import:
+
+- `react`, `react-dom`
+- `@assistant-ui/*` (anywhere — including under `msal/`)
+- `@azure/msal-*` (anywhere — including under `msal/` for `msal-react`; only `@azure/msal-browser` is allowed under `msal/`)
+- bare `"zustand"` — use `"zustand/vanilla"` (`zustand/middleware` is allowed)
+
+Files under `packages/agent/src/msal/` MAY import `@azure/msal-browser` (dynamic import only — keeps the dep optional). They MUST NOT import `@azure/msal-react` (which is React-bound and lives in `@iloveagents/foundry-web-ui`).
+
+`packages/agent/` MUST NOT import from any other `@lastspace/*` package — agent is the leaf of the open-core graph.
+
+# Why `zustand/vanilla`
+
+`import { create } from "zustand"` resolves to the React build (`useSyncExternalStore`). Importing it in a "zero React" package would silently take a React dependency and defeat the cross-runtime goal. Every store in this package uses `import { createStore } from "zustand/vanilla"`. React consumers (in `@iloveagents/foundry-web-ui` / `apps/web/`) bind via `useStore(store, selector)` from the React entry of zustand.
+
+# What goes here
+
+- AG-UI protocol client (SSE, message conversion, multi-turn re-issue, tool dispatch).
+- Vanilla state stores that the protocol engine needs at runtime — streaming status, citation cache, client-tool registry.
+- MSAL bits under the `/msal` subpath only.
+- Generic per-service fetch factory (`createServiceFetch`).
+
+# What does NOT go here
+
+- Anything implementing `@assistant-ui/*` interfaces (`ChatModelAdapter`, `AttachmentAdapter`, etc.) — those are React UI surface and live in `@iloveagents/foundry-web-ui`.
+- React components, hooks, contexts, providers.
+- UI-layout state (panel widths, modal modes, theme).
+- The `MsalProvider` React component — that lives in `@iloveagents/foundry-web-ui`.
+
+# Public surface
+
+Root `@iloveagents/foundry-agent`:
+
+```ts
+import {
+  AGUIRunner,
+  type RunnerEvent,
+  createServiceFetch,
+  clientToolRegistry,
+  type ClientToolEntry,
+  streamingStatusStore,
+  type StreamingStatus,
+  citationStore,
+  type CitationResult,
+  type CitationHandler,
+} from "@iloveagents/foundry-agent";
+```
+
+Subpath `@iloveagents/foundry-agent/msal`:
+
+```ts
+import {
+  authStore,
+  type AuthUser,
+  type MsalAuthConfig,
+  initializeMsal,
+  getMsalInstance,
+  getMsalConfig,
+  tokenFetch,
+} from "@iloveagents/foundry-agent/msal";
+```
+
+# Bundle-size budget
+
+Target ≤25 KB gz on the root entry (`@iloveagents/foundry-agent`, excluding the `/msal` subpath). Measured manually pre-1.0 via `gzip -c dist/index.js | wc -c`; `size-limit` enforcement scaffolds in #92's follow-up.

package/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 iLoveAgents, a brand of Leitwolf GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@iloveagents/foundry-agent",
+  "version": "0.1.0",
+  "license": "SEE LICENSE IN LICENSE",
+  "type": "module",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./msal": "./src/msal/index.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "zustand": "^5.0.0",
+    "@ag-ui/client": "^0.0.52",
+    "@ag-ui/core": "^0.0.52",
+    "@azure/msal-browser": "^5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@azure/msal-browser": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "typescript": "~5.9.3",
+    "vitest": "^4.1.4",
+    "jsdom": "^28.1.0",
+    "zustand": "^5.0.0",
+    "@ag-ui/client": "^0.0.52",
+    "@ag-ui/core": "^0.0.52"
+  },
+  "scripts": {
+    "test:unit": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/__tests__/agui-runner.test.ts

@@ -0,0 +1,329 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { AgentSubscriber } from "@ag-ui/client";
+
+// Scripted event playback for the mocked HttpAgent. Each test sets `script`
+// to an array of (subscriber) => Promise<void> functions. The mock's
+// runAgent fires them in order, synchronously yielding the loop between
+// each one so the runner's queue can drain.
+
+type ScriptedRun = (subscriber: AgentSubscriber) => Promise<void>;
+
+let nextScript: ScriptedRun[] = [];
+let runCount = 0;
+let lastMessages: unknown[] = [];
+
+vi.mock("@ag-ui/client", () => {
+  class MockHttpAgent {
+    threadId: string;
+    state: Record<string, unknown> = {};
+    messages: unknown[] = [];
+
+    constructor(opts: { url?: string; threadId?: string }) {
+      this.threadId = opts.threadId ?? "thread-1";
+    }
+
+    setMessages(messages: unknown[]) {
+      this.messages = [...messages];
+      lastMessages = this.messages;
+    }
+    setState(state: Record<string, unknown>) {
+      this.state = state;
+    }
+    addMessage(message: unknown) {
+      this.messages.push(message);
+      lastMessages = this.messages;
+    }
+
+    async runAgent(_params: unknown, subscriber: AgentSubscriber): Promise<void> {
+      const turnIdx = runCount;
+      runCount++;
+      const script = nextScript[turnIdx];
+      if (script) await script(subscriber);
+    }
+
+    abortRun() {
+      // no-op for tests
+    }
+  }
+  return { HttpAgent: MockHttpAgent };
+});
+
+import { AGUIRunner } from "../client/agui-runner.ts";
+import { clientToolRegistry } from "../tools/registry.ts";
+import type { RunnerEvent } from "../client/runner-events.ts";
+
+function makeRegistry(client: { isRegistered: (name: string) => boolean; executeTool?: (name: string, args: string) => Promise<string> }) {
+  return {
+    isRegistered: client.isRegistered,
+    executeTool: client.executeTool ?? (async () => JSON.stringify({})),
+    getActiveSchemas: () => [],
+  };
+}
+
+async function collect(runner: AGUIRunner, registry: ReturnType<typeof makeRegistry>): Promise<RunnerEvent[]> {
+  const out: RunnerEvent[] = [];
+  for await (const evt of runner.run({ messages: [], registry })) {
+    out.push(evt);
+  }
+  return out;
+}
+
+describe("AGUIRunner", () => {
+  beforeEach(() => {
+    nextScript = [];
+    runCount = 0;
+    lastMessages = [];
+    clientToolRegistry.setState({ globalTools: new Map(), pageTools: new Map() });
+  });
+
+  it("emits the canonical event sequence for a text-only run", async () => {
+    nextScript = [
+      async (s) => {
+        await s.onRunStartedEvent?.({ event: { type: "RUN_STARTED" } } as never);
+        await s.onTextMessageStartEvent?.({ event: { type: "TEXT_MESSAGE_START" } } as never);
+        await s.onTextMessageContentEvent?.({
+          event: { type: "TEXT_MESSAGE_CONTENT", delta: "Hello" } as never,
+        } as never);
+        await s.onTextMessageContentEvent?.({
+          event: { type: "TEXT_MESSAGE_CONTENT", delta: " world" } as never,
+        } as never);
+        await s.onTextMessageEndEvent?.({ event: { type: "TEXT_MESSAGE_END" } } as never);
+        await s.onRunFinishedEvent?.({ event: { type: "RUN_FINISHED" } } as never);
+      },
+    ];
+
+    const runner = new AGUIRunner();
+    const events = await collect(runner, makeRegistry({ isRegistered: () => false }));
+
+    const types = events.map((e) => e.type);
+    expect(types).toContain("turn-started");
+    expect(types).toContain("request-sent");
+    expect(types).toContain("run-started");
+    expect(types).toContain("text-delta");
+    expect(types).toContain("text-message-end");
+    expect(types).toContain("run-finished");
+
+    const deltas = events.filter((e): e is Extract<RunnerEvent, { type: "text-delta" }> =>
+      e.type === "text-delta",
+    );
+    expect(deltas.map((d) => d.delta).join("")).toBe("Hello world");
+  });
+
+  it("emits tool-call events with isClientSide flag", async () => {
+    nextScript = [
+      async (s) => {
+        await s.onRunStartedEvent?.({ event: { type: "RUN_STARTED" } } as never);
+        await s.onToolCallStartEvent?.({
+          event: {
+            type: "TOOL_CALL_START",
+            toolCallId: "tc-1",
+            toolCallName: "server_tool",
+          } as never,
+        } as never);
+        await s.onToolCallArgsEvent?.({
+          event: { type: "TOOL_CALL_ARGS", toolCallId: "tc-1", delta: "{\"q\":\"x\"}" } as never,
+        } as never);
+        await s.onToolCallEndEvent?.({
+          event: { type: "TOOL_CALL_END", toolCallId: "tc-1" } as never,
+        } as never);
+        await s.onToolCallResultEvent?.({
+          event: {
+            type: "TOOL_CALL_RESULT",
+            toolCallId: "tc-1",
+            content: '{"ok":true}',
+          } as never,
+        } as never);
+        await s.onRunFinishedEvent?.({ event: { type: "RUN_FINISHED" } } as never);
+      },
+    ];
+
+    const runner = new AGUIRunner();
+    const events = await collect(runner, makeRegistry({ isRegistered: () => false }));
+
+    const start = events.find((e): e is Extract<RunnerEvent, { type: "tool-call-start" }> =>
+      e.type === "tool-call-start",
+    );
+    expect(start).toBeDefined();
+    expect(start!.isClientSide).toBe(false);
+    expect(start!.name).toBe("server_tool");
+
+    const result = events.find(
+      (e): e is Extract<RunnerEvent, { type: "tool-call-result" }> => e.type === "tool-call-result",
+    );
+    expect(result).toBeDefined();
+    expect(result!.result).toEqual({ ok: true });
+    expect(result!.isError).toBe(false);
+  });
+
+  it("intercepts client-side tools and re-issues the run with the result", async () => {
+    const executeTool = vi.fn().mockResolvedValue('{"navigated":true}');
+
+    nextScript = [
+      async (s) => {
+        await s.onRunStartedEvent?.({ event: { type: "RUN_STARTED" } } as never);
+        await s.onToolCallStartEvent?.({
+          event: {
+            type: "TOOL_CALL_START",
+            toolCallId: "tc-1",
+            toolCallName: "ui_navigate",
+          } as never,
+        } as never);
+        await s.onToolCallArgsEvent?.({
+          event: {
+            type: "TOOL_CALL_ARGS",
+            toolCallId: "tc-1",
+            delta: '{"path":"/foo"}',
+          } as never,
+        } as never);
+        await s.onToolCallEndEvent?.({
+          event: { type: "TOOL_CALL_END", toolCallId: "tc-1" } as never,
+        } as never);
+        await s.onRunFinishedEvent?.({ event: { type: "RUN_FINISHED" } } as never);
+      },
+      async (s) => {
+        // Second turn after follow-up: agent acknowledges with text + finishes.
+        await s.onRunStartedEvent?.({ event: { type: "RUN_STARTED" } } as never);
+        await s.onTextMessageStartEvent?.({ event: { type: "TEXT_MESSAGE_START" } } as never);
+        await s.onTextMessageContentEvent?.({
+          event: { type: "TEXT_MESSAGE_CONTENT", delta: "Done" } as never,
+        } as never);
+        await s.onTextMessageEndEvent?.({ event: { type: "TEXT_MESSAGE_END" } } as never);
+        await s.onRunFinishedEvent?.({ event: { type: "RUN_FINISHED" } } as never);
+      },
+    ];
+
+    const runner = new AGUIRunner();
+    const events = await collect(
+      runner,
+      makeRegistry({
+        isRegistered: (name) => name === "ui_navigate",
+        executeTool,
+      }),
+    );
+
+    expect(executeTool).toHaveBeenCalledWith("ui_navigate", '{"path":"/foo"}');
+    expect(runCount).toBe(2); // Initial + follow-up
+
+    // Second turn was issued with the same toolCallId in the assistant message
+    const lastAssistantMsg = lastMessages.find(
+      (m): m is { role: string; toolCalls?: Array<{ id: string }> } =>
+        typeof m === "object" && m !== null && (m as { role?: string }).role === "assistant",
+    );
+    expect(lastAssistantMsg?.toolCalls?.[0]?.id).toBe("tc-1");
+
+    // tool-call-start should have isClientSide=true
+    const start = events.find((e): e is Extract<RunnerEvent, { type: "tool-call-start" }> =>
+      e.type === "tool-call-start",
+    );
+    expect(start!.isClientSide).toBe(true);
+  });
+
+  it("preserves pre-tool assistant text in the follow-up replay", async () => {
+    // Regression: if the model emits text before the tool call in the
+    // same turn ("Looking up..." then ui_navigate), the follow-up
+    // assistant message must include that text. Otherwise the next-turn
+    // context drifts (no server-side thread state — full history rides
+    // each request).
+    const executeTool = vi.fn().mockResolvedValue('{"ok":true}');
+
+    nextScript = [
+      async (s) => {
+        await s.onRunStartedEvent?.({ event: { type: "RUN_STARTED" } } as never);
+        await s.onTextMessageStartEvent?.({ event: { type: "TEXT_MESSAGE_START" } } as never);
+        await s.onTextMessageContentEvent?.({
+          event: { type: "TEXT_MESSAGE_CONTENT", delta: "Navigating..." } as never,
+        } as never);
+        await s.onTextMessageEndEvent?.({ event: { type: "TEXT_MESSAGE_END" } } as never);
+        await s.onToolCallStartEvent?.({
+          event: {
+            type: "TOOL_CALL_START",
+            toolCallId: "tc-pre",
+            toolCallName: "ui_navigate",
+          } as never,
+        } as never);
+        await s.onToolCallArgsEvent?.({
+          event: {
+            type: "TOOL_CALL_ARGS",
+            toolCallId: "tc-pre",
+            delta: '{"path":"/x"}',
+          } as never,
+        } as never);
+        await s.onToolCallEndEvent?.({
+          event: { type: "TOOL_CALL_END", toolCallId: "tc-pre" } as never,
+        } as never);
+        await s.onRunFinishedEvent?.({ event: { type: "RUN_FINISHED" } } as never);
+      },
+      async (s) => {
+        await s.onRunStartedEvent?.({ event: { type: "RUN_STARTED" } } as never);
+        await s.onRunFinishedEvent?.({ event: { type: "RUN_FINISHED" } } as never);
+      },
+    ];
+
+    const runner = new AGUIRunner();
+    await collect(
+      runner,
+      makeRegistry({
+        isRegistered: (name) => name === "ui_navigate",
+        executeTool,
+      }),
+    );
+
+    expect(runCount).toBe(2);
+    const lastAssistant = lastMessages.find(
+      (m): m is { role: string; content: string; toolCalls?: Array<{ id: string }> } =>
+        typeof m === "object" && m !== null && (m as { role?: string }).role === "assistant",
+    );
+    expect(lastAssistant?.content).toBe("Navigating...");
+  });
+
+  it("yields turn-started exactly once per run iteration", async () => {
+    nextScript = [
+      async (s) => {
+        await s.onRunStartedEvent?.({ event: { type: "RUN_STARTED" } } as never);
+        await s.onRunFinishedEvent?.({ event: { type: "RUN_FINISHED" } } as never);
+      },
+    ];
+
+    const runner = new AGUIRunner();
+    const events = await collect(runner, makeRegistry({ isRegistered: () => false }));
+
+    const turnStarts = events.filter((e) => e.type === "turn-started");
+    expect(turnStarts.length).toBe(1);
+  });
+
+  it("emits request-sent before any subscriber events", async () => {
+    nextScript = [
+      async (s) => {
+        await s.onRunFinishedEvent?.({ event: { type: "RUN_FINISHED" } } as never);
+      },
+    ];
+
+    const runner = new AGUIRunner();
+    const events = await collect(runner, makeRegistry({ isRegistered: () => false }));
+
+    const requestIdx = events.findIndex((e) => e.type === "request-sent");
+    const finishedIdx = events.findIndex((e) => e.type === "run-finished");
+    expect(requestIdx).toBeGreaterThanOrEqual(0);
+    expect(requestIdx).toBeLessThan(finishedIdx);
+  });
+
+  it("translates RUN_ERROR into run-error with the message", async () => {
+    nextScript = [
+      async (s) => {
+        await s.onRunStartedEvent?.({ event: { type: "RUN_STARTED" } } as never);
+        await s.onRunErrorEvent?.({
+          event: { type: "RUN_ERROR", message: "boom" } as never,
+        } as never);
+      },
+    ];
+
+    const runner = new AGUIRunner();
+    const events = await collect(runner, makeRegistry({ isRegistered: () => false }));
+
+    const err = events.find((e): e is Extract<RunnerEvent, { type: "run-error" }> =>
+      e.type === "run-error",
+    );
+    expect(err).toBeDefined();
+    expect(err!.message).toBe("boom");
+  });
+});

package/src/__tests__/auth-store.test.ts

@@ -0,0 +1,37 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import { authStore } from "../msal/auth-store.ts";
+
+const store = () => authStore.getState();
+
+describe("authStore", () => {
+  beforeEach(() => {
+    authStore.setState({ user: null, isAuthenticated: false });
+  });
+
+  it("starts unauthenticated", () => {
+    expect(store().isAuthenticated).toBe(false);
+    expect(store().user).toBeNull();
+  });
+
+  it("signs in with a user", () => {
+    store().signIn({ name: "Alice", email: "alice@example.com" });
+    expect(store().isAuthenticated).toBe(true);
+    expect(store().user?.name).toBe("Alice");
+  });
+
+  it("signs out and clears user", () => {
+    store().signIn({ name: "Alice", email: "alice@example.com" });
+    store().signOut();
+    expect(store().isAuthenticated).toBe(false);
+    expect(store().user).toBeNull();
+  });
+
+  it("signs in with avatar", () => {
+    store().signIn({
+      name: "Bob",
+      email: "bob@example.com",
+      avatar: "https://example.com/bob.png",
+    });
+    expect(store().user?.avatar).toBe("https://example.com/bob.png");
+  });
+});

package/src/__tests__/citation-store.test.ts

@@ -0,0 +1,46 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { citationStore } from "../store/citation-store.ts";
+import type { CitationResult, CitationHandler } from "../store/citation-store.ts";
+
+const mockResult: CitationResult = {
+  chunk_id: "chunk-1",
+  entity_id: "e-1",
+  entity_name: "Test Doc",
+  content: "Some content",
+  page_number: 1,
+  bounding_regions: "0,0,100,100",
+  score: 0.95,
+};
+
+describe("citationStore", () => {
+  beforeEach(() => {
+    citationStore.setState({ results: [], handler: null });
+  });
+
+  describe("setResults", () => {
+    it("stores citation results", () => {
+      citationStore.getState().setResults([mockResult]);
+      expect(citationStore.getState().results).toEqual([mockResult]);
+    });
+  });
+
+  describe("setHandler", () => {
+    it("registers a citation handler", () => {
+      const handler: CitationHandler = { openCitation: () => {} };
+      citationStore.getState().setHandler(handler);
+      expect(citationStore.getState().handler).toBe(handler);
+    });
+  });
+
+  describe("clear", () => {
+    it("resets results and handler", () => {
+      citationStore.getState().setResults([mockResult]);
+      citationStore.getState().setHandler({ openCitation: () => {} });
+
+      citationStore.getState().clear();
+
+      expect(citationStore.getState().results).toEqual([]);
+      expect(citationStore.getState().handler).toBeNull();
+    });
+  });
+});

package/src/__tests__/client-tool-registry.test.ts

@@ -0,0 +1,84 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { clientToolRegistry } from "../tools/registry.ts";
+import type { ClientToolEntry } from "../tools/registry.ts";
+
+function makeTool(name: string): ClientToolEntry {
+  return {
+    name,
+    description: `${name} tool`,
+    parameters: { type: "object", properties: {} },
+    execute: async () => JSON.stringify({ ok: true }),
+  };
+}
+
+describe("clientToolRegistry", () => {
+  beforeEach(() => {
+    clientToolRegistry.setState({ globalTools: new Map(), pageTools: new Map() });
+  });
+
+  describe("registerGlobal", () => {
+    it("adds a global tool", () => {
+      clientToolRegistry.getState().registerGlobal(makeTool("ui_navigate"));
+      expect(clientToolRegistry.getState().isRegistered("ui_navigate")).toBe(true);
+    });
+  });
+
+  describe("registerPageTools / clearPageTools", () => {
+    it("registers page-scoped tools", () => {
+      clientToolRegistry.getState().registerPageTools([makeTool("page_search")]);
+      expect(clientToolRegistry.getState().isRegistered("page_search")).toBe(true);
+    });
+
+    it("clears page tools", () => {
+      clientToolRegistry.getState().registerPageTools([makeTool("page_search")]);
+      clientToolRegistry.getState().clearPageTools();
+      expect(clientToolRegistry.getState().isRegistered("page_search")).toBe(false);
+    });
+  });
+
+  describe("getActiveSchemas", () => {
+    it("merges global and page tools", () => {
+      clientToolRegistry.getState().registerGlobal(makeTool("ui_navigate"));
+      clientToolRegistry.getState().registerPageTools([makeTool("page_search")]);
+      const schemas = clientToolRegistry.getState().getActiveSchemas();
+      expect(schemas.map((s) => s.name).sort()).toEqual(["page_search", "ui_navigate"]);
+    });
+
+    it("page tools override global tools with same name", () => {
+      clientToolRegistry.getState().registerGlobal(makeTool("shared_tool"));
+      const pageTool = makeTool("shared_tool");
+      pageTool.description = "page version";
+      clientToolRegistry.getState().registerPageTools([pageTool]);
+
+      const schemas = clientToolRegistry.getState().getActiveSchemas();
+      const match = schemas.find((s) => s.name === "shared_tool");
+      expect(match?.description).toBe("page version");
+    });
+  });
+
+  describe("executeTool", () => {
+    it("executes a registered tool", async () => {
+      clientToolRegistry.getState().registerGlobal(makeTool("ui_navigate"));
+      const result = await clientToolRegistry.getState().executeTool("ui_navigate", "{}");
+      expect(JSON.parse(result)).toEqual({ ok: true });
+    });
+
+    it("returns error for unknown tool", async () => {
+      const result = await clientToolRegistry.getState().executeTool("unknown_tool", "{}");
+      expect(JSON.parse(result).error).toContain("Unknown client tool");
+    });
+
+    it("page tool takes precedence over global", async () => {
+      const globalTool = makeTool("shared");
+      globalTool.execute = async () => "global";
+      const pageTool = makeTool("shared");
+      pageTool.execute = async () => "page";
+
+      clientToolRegistry.getState().registerGlobal(globalTool);
+      clientToolRegistry.getState().registerPageTools([pageTool]);
+
+      const result = await clientToolRegistry.getState().executeTool("shared", "{}");
+      expect(result).toBe("page");
+    });
+  });
+});