test(examples): execute the real example files

`tests/examples/` reimplemented each example's logic against `../../src` and
never imported `examples/*.ts`. An example could rot or break outright and CI
stayed green — and four of the eight had no test at all.

Examples do their work at import time via top-level await, so importing one runs
it. `tests/examples/run-example.ts` makes that safe under vitest:

- `STACKONE_BASE_URL` points the SDK at the MSW mock (toolsets.ts:630 reads it),
  so an example constructing `new StackOneToolSet()` with no explicit baseUrl
  still hits the mock rather than production. No example needed changing.
- `process.exit` becomes a throw that `runExample` catches and reports as
  `exitCode`, so an example bailing on missing config is an assertable outcome
  instead of a torn-down vitest worker.

Seven of the eight examples now execute for real. The eighth,
claude-agent-sdk-integration, still cannot: `query()` spawns a claude-code
subprocess that MSW cannot intercept. Its existing setup-level test is kept and
the exclusion is now stated in the file rather than implied.

Mock gaps that blocked execution, all of which made the examples exercise
nothing:

- The three `workday_*` actions every example filters on were absent from the
  MCP catalog, so the filters matched zero tools.
- No Anthropic handler existed at all (mocks/handlers.anthropic.ts).
- The OpenAI handlers keyed off prompts none of the examples send; the examples
  all prompt "List the first 5 employees".
- Semantic search (`/actions/search`) was unmocked, so search-tools hit the
  real network. Added scoped to that test via `server.use` — a global handler
  pre-empts src/semantic-search.test.ts, which asserts against an unmocked
  endpoint.

Tool-count assertions are exact rather than `> 0`. A `> 0` check cannot fail:
`fetchTools` appends tool_feedback *after* filtering, so a filter matching
nothing still returns one tool. Verified by mutation — pointing an example at a
nonexistent action now fails with `expected 1 to be 4`, where before it passed.

defender-config keeps all seven original wire-payload tests, which assert the
exact RPC body per defender mode; the four execution tests are added alongside.

fetch-tools and tanstack-ai-integration describe examples that do not exist.
Relabelled in place rather than moved — the `examples` vitest project globs only
`tests/examples/**` and `root` globs only `src/`+`scripts/`, so relocating them
would have dropped them from both projects silently.

348 passing, up from 329. The one failure is pre-existing and environmental
(`spawn tsc ENOENT`); it fails identically on origin/main.

Author: willleeney

mocks/handlers.anthropic.ts

@@ -0,0 +1,50 @@
+import { http, HttpResponse } from 'msw';
+
+/**
+ * Anthropic Messages API, for anthropic-integration.ts.
+ */
+export const anthropicHandlers = [
+	http.post('https://api.anthropic.com/v1/messages', async ({ request }) => {
+		const body = (await request.json()) as {
+			messages?: Array<{ content?: unknown; role?: string }>;
+			tools?: Array<{ name?: string }>;
+		};
+
+		const userMessage = body.messages
+			?.filter((message) => message.role === 'user')
+			.map((message) =>
+				typeof message.content === 'string' ? message.content : JSON.stringify(message.content),
+			)
+			.join(' ');
+		const hasTools = Boolean(body.tools?.length);
+
+		if (hasTools && userMessage?.includes('List the first 5 employees')) {
+			return HttpResponse.json({
+				id: 'msg_mock_list',
+				type: 'message',
+				role: 'assistant',
+				model: 'claude-haiku-4-5-20241022',
+				content: [
+					{
+						type: 'tool_use',
+						id: 'toolu_mock_list',
+						name: 'workday_list_workers',
+						input: { query: { limit: 5 } },
+					},
+				],
+				stop_reason: 'tool_use',
+				usage: { input_tokens: 100, output_tokens: 50 },
+			});
+		}
+
+		return HttpResponse.json({
+			id: 'msg_default',
+			type: 'message',
+			role: 'assistant',
+			model: 'claude-haiku-4-5-20241022',
+			content: [{ type: 'text', text: 'Mock response' }],
+			stop_reason: 'end_turn',
+			usage: { input_tokens: 10, output_tokens: 10 },
+		});
+	}),
+];

mocks/handlers.openai.ts

@@ -65,6 +65,29 @@ export const openaiHandlers = [
 			});
 		}
 
+		// For openai-responses-integration.ts and search-tools.ts, which prompt with
+		// the same sentence and expect a tool call back.
+		if (hasTools && userMessage.includes('List the first 5 employees')) {
+			return HttpResponse.json({
+				id: 'resp_mock_list',
+				object: 'response',
+				created_at: Date.now(),
+				model: 'gpt-5',
+				status: 'completed',
+				output: [
+					{
+						type: 'function_call',
+						id: 'call_mock_list',
+						call_id: 'call_mock_list',
+						name: 'workday_list_workers',
+						arguments: JSON.stringify({ query: { limit: 5 } }),
+						status: 'completed',
+					},
+				],
+				usage: { input_tokens: 100, output_tokens: 50, total_tokens: 150 },
+			});
+		}
+
 		// For human-in-the-loop.ts
 		if (hasTools && userMessage.includes('Create a new employee')) {
 			return HttpResponse.json({
@@ -158,6 +181,38 @@ export const openaiHandlers = [
 			});
 		}
 
+		// For openai-integration.ts, which filters to workday actions and prompts
+		// with this sentence.
+		if (hasTools && userMessage.includes('List the first 5 employees')) {
+			return HttpResponse.json({
+				id: 'chatcmpl-mock-list',
+				object: 'chat.completion',
+				created: Date.now(),
+				model: 'gpt-5',
+				choices: [
+					{
+						index: 0,
+						message: {
+							role: 'assistant',
+							content: null,
+							tool_calls: [
+								{
+									id: 'call_mock_list',
+									type: 'function',
+									function: {
+										name: 'workday_list_workers',
+										arguments: JSON.stringify({ query: { limit: 5 } }),
+									},
+								},
+							],
+						},
+						finish_reason: 'tool_calls',
+					},
+				],
+				usage: { prompt_tokens: 100, completion_tokens: 50, total_tokens: 150 },
+			});
+		}
+
 		// For human-in-the-loop.ts - returns tool call for bamboohr_create_employee
 		if (hasTools && userMessage.includes('Create a new employee')) {
 			return HttpResponse.json({

mocks/handlers.ts

@@ -1,10 +1,12 @@
+import { anthropicHandlers } from './handlers.anthropic';
 import { exampleApiHandlers } from './handlers.example-api';
 import { mcpHandlers } from './handlers.mcp';
 import { openaiHandlers } from './handlers.openai';
 import { stackoneAiHandlers } from './handlers.stackone-ai';
 import { stackoneRpcHandlers } from './handlers.stackone-rpc';
 
 export const handlers = [
+	...anthropicHandlers,
 	...openaiHandlers,
 	...stackoneRpcHandlers,
 	...stackoneAiHandlers,

mocks/mcp-server.ts

@@ -227,6 +227,42 @@ export const exampleBamboohrTools = [
 			required: ['name'],
 		},
 	},
+	// The examples filter on these three action names. Without them the examples
+	// execute against an empty toolset and assert nothing.
+	{
+		name: 'workday_list_workers',
+		description: 'List workers from Workday',
+		inputSchema: {
+			type: 'object',
+			properties: {
+				query: {
+					type: 'object',
+					properties: {
+						limit: { type: 'number', description: 'Limit the number of results' },
+					},
+				},
+			},
+		},
+	},
+	{
+		name: 'workday_get_worker',
+		description: 'Get a single worker by ID from Workday',
+		inputSchema: {
+			type: 'object',
+			properties: {
+				id: { type: 'string', description: 'The worker ID' },
+			},
+			required: ['id'],
+		},
+	},
+	{
+		name: 'workday_get_current_user',
+		description: 'Get the currently authenticated Workday user',
+		inputSchema: {
+			type: 'object',
+			properties: {},
+		},
+	},
 ] as const satisfies McpToolDefinition[];
 
 export const mixedProviderTools = [

tests/examples/ai-sdk-integration.test.ts

@@ -0,0 +1,36 @@
+/**
+ * Executes examples/ai-sdk-integration.ts.
+ */
+
+import { runExample, stubExampleEnv } from './run-example';
+
+describe('ai-sdk-integration example', () => {
+	beforeEach(() => {
+		stubExampleEnv({ OPENAI_API_KEY: 'test-openai-key' });
+	});
+
+	afterEach(() => {
+		vi.unstubAllEnvs();
+	});
+
+	it('loads tools and drives a Vercel AI SDK generation', async () => {
+		const { stdout, exitCode } = await runExample('../../examples/ai-sdk-integration.ts');
+
+		expect(exitCode).toBeUndefined();
+
+		// 4: 3 workday actions the example filters to, plus the auto-appended tool_feedback.
+		// A bare > 0 check cannot fail here — tool_feedback is appended after
+		// filtering, so even a filter matching nothing still yields one tool.
+		const loaded = stdout.match(/Loaded (\d+) tools/);
+		expect(loaded).not.toBeNull();
+		expect(Number(loaded?.[1])).toBe(4);
+	});
+
+	it('skips cleanly when OPENAI_API_KEY is absent', async () => {
+		vi.stubEnv('OPENAI_API_KEY', '');
+
+		const { stdout, exitCode } = await runExample('../../examples/ai-sdk-integration.ts');
+
+		expect(exitCode).toBe(0);
+	});
+});

tests/examples/anthropic-integration.test.ts

@@ -0,0 +1,38 @@
+/**
+ * Executes examples/anthropic-integration.ts.
+ */
+
+import { runExample, stubExampleEnv } from './run-example';
+
+describe('anthropic-integration example', () => {
+	beforeEach(() => {
+		stubExampleEnv({ ANTHROPIC_API_KEY: 'test-anthropic-key' });
+	});
+
+	afterEach(() => {
+		vi.unstubAllEnvs();
+	});
+
+	it('loads tools, calls Anthropic, and reports the tool use', async () => {
+		const { stdout, exitCode } = await runExample('../../examples/anthropic-integration.ts');
+
+		expect(exitCode).toBeUndefined();
+
+		// 3: 2 tools matching the example's filters, plus the auto-appended tool_feedback.
+		// A bare > 0 check cannot fail here — tool_feedback is appended after
+		// filtering, so even a filter matching nothing still yields one tool.
+		const loaded = stdout.match(/Loaded (\d+) tools/);
+		expect(loaded).not.toBeNull();
+		expect(Number(loaded?.[1])).toBe(3);
+
+		expect(stdout).toContain('workday_list_workers');
+	});
+
+	it('skips cleanly when ANTHROPIC_API_KEY is absent', async () => {
+		vi.stubEnv('ANTHROPIC_API_KEY', '');
+
+		const { stdout, exitCode } = await runExample('../../examples/anthropic-integration.ts');
+
+		expect(exitCode).toBe(0);
+	});
+});

tests/examples/auth-management.test.ts

@@ -0,0 +1,51 @@
+/**
+ * Executes examples/auth-management.ts.
+ */
+
+import { runExample, stubExampleEnv } from './run-example';
+
+describe('auth-management example', () => {
+	beforeEach(() => {
+		stubExampleEnv();
+	});
+
+	afterEach(() => {
+		vi.unstubAllEnvs();
+	});
+
+	it('runs every auth pattern to completion', async () => {
+		const { stdout, exitCode } = await runExample('../../examples/auth-management.ts');
+
+		expect(exitCode).toBeUndefined();
+		expect(stdout).toContain('Done — all auth patterns demonstrated.');
+	});
+
+	it('loads tools through each configuration path', async () => {
+		const { stdout } = await runExample('../../examples/auth-management.ts');
+
+		for (const section of [
+			'1a. API Key from environment',
+			'1b. Explicit API key',
+			'2. Account ID from environment',
+			'3. Account ID in constructor',
+			'4. setAccounts() — global account list',
+			'5. Per-tool account override',
+		]) {
+			expect(stdout).toContain(section);
+		}
+
+		// Every fetchTools() call must return a non-empty toolset; "Loaded 0 tools"
+		// would mean the example ran but silently exercised nothing.
+		const loaded = [...stdout.matchAll(/Loaded (\d+) tools/g)].map((match) => Number(match[1]));
+		expect(loaded.length).toBeGreaterThan(0);
+		expect(loaded.every((count) => count > 0)).toBe(true);
+	});
+
+	it('exits non-zero when STACKONE_API_KEY is absent', async () => {
+		vi.stubEnv('STACKONE_API_KEY', '');
+
+		const { exitCode } = await runExample('../../examples/auth-management.ts');
+
+		expect(exitCode).toBe(1);
+	});
+});

tests/examples/claude-agent-sdk-integration.test.ts

@@ -3,10 +3,11 @@
  *
  * Tests the setup of StackOne tools with Claude Agent SDK.
  *
- * Note: The Claude Agent SDK spawns a subprocess to run claude-code, which
- * requires the ANTHROPIC_API_KEY environment variable and a running claude-code
- * installation. This test validates the tool setup and MCP server creation,
- * but does not test the actual query execution.
+ * This is the one example NOT executed directly (see tests/examples/run-example.ts
+ * for how the others are). `query()` spawns a claude-code subprocess, which MSW
+ * cannot intercept and which needs a real ANTHROPIC_API_KEY and installation.
+ * So this reimplements the example's setup — tool fetch, tool wrapper, MCP server
+ * creation and handler execution — and stops short of the query call.
  */
 
 import { tool, createSdkMcpServer } from '@anthropic-ai/claude-agent-sdk';

tests/examples/defender-config.test.ts

@@ -8,9 +8,10 @@
  */
 
 import { TEST_BASE_URL } from '../../mocks/constants';
+import { runExample, stubExampleEnv } from './run-example';
 import { DEFAULT_DEFENDER_CONFIG, StackOneToolSet, ToolSetConfigError } from '../../src';
 
-describe('defender-config example e2e', () => {
+describe('defender-config wire payloads', () => {
 	beforeEach(() => {
 		vi.stubEnv('STACKONE_API_KEY', 'test-key');
 		// Silence override warnings so they don't pollute test output.
@@ -153,3 +154,45 @@ describe('defender-config example e2e', () => {
 		});
 	});
 });
+
+describe('defender-config example', () => {
+	beforeEach(() => {
+		// The example defaults section 8 to gmail_list_messages, which the MCP mock
+		// does not serve; TOOL_NAME is the example's own knob for pointing it elsewhere.
+		stubExampleEnv({ TOOL_NAME: 'workday_list_workers' });
+	});
+
+	afterEach(() => {
+		vi.unstubAllEnvs();
+	});
+
+	it('demonstrates every defender pattern to completion', async () => {
+		const { stdout, exitCode } = await runExample('../../examples/defender-config.ts');
+
+		expect(exitCode).toBeUndefined();
+		expect(stdout).toContain('Done — defender patterns demonstrated.');
+	});
+
+	it('shows both the omitted and the all-false payload shapes', async () => {
+		const { stdout } = await runExample('../../examples/defender-config.ts');
+
+		expect(stdout).toContain('SDK adds no defender_config to the RPC payload.');
+		expect(stdout).toContain('SDK sends defender_config with all fields false.');
+	});
+
+	it('reaches the live section and gets defender metadata back', async () => {
+		const { stdout } = await runExample('../../examples/defender-config.ts');
+
+		// With STACKONE_API_KEY stubbed the example runs section 8 rather than
+		// printing its skip notice.
+		expect(stdout).not.toContain('Skipping — set STACKONE_API_KEY to run this section.');
+		expect(stdout).toContain('defenderMetadata:');
+	});
+
+	it('still rejects an invalid defender combination', async () => {
+		const { stdout } = await runExample('../../examples/defender-config.ts');
+
+		// The example prints this only if the invalid combo failed to throw.
+		expect(stdout).not.toContain('(no throw — unexpected!)');
+	});
+});

tests/examples/fetch-tools.test.ts

@@ -1,15 +1,16 @@
 /**
- * E2E test for fetch-tools.ts example
+ * E2E coverage for fetching and filtering tools via MCP.
  *
- * Tests the complete flow of fetching and filtering tools via MCP.
+ * There is no `examples/fetch-tools.ts`; this exercises the discovery flow the
+ * other examples build on, against the MCP mock.
  */
 
 import { http, HttpResponse } from 'msw';
 import { server } from '../../mocks/node';
 import { TEST_BASE_URL } from '../../mocks/constants';
 import { StackOneToolSet } from '../../src';
 
-describe('fetch-tools example e2e', () => {
+describe('fetch-tools e2e', () => {
 	beforeEach(() => {
 		vi.stubEnv('STACKONE_API_KEY', 'test-key');
 	});