Bump to v0.11.0, add code mode example and WorkerExecutor edge case tests

tylergibbs1 · claude · tylergibbs1 · commit 2a9eab817f6b · 2026-03-13T09:15:54.000-05:00
- Add real-world code mode example using public APIs (Open-Meteo, RestCountries)
- Add 15 new WorkerExecutor edge case tests (119 total codemode tests)

Co-Authored-By: Claude Opus 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/examples/05-code-mode.ts b/examples/05-code-mode.ts
@@ -0,0 +1,173 @@
+/**
+ * Code Mode example — the LLM writes code that orchestrates multiple API tools
+ * in a single execution, instead of making individual tool calls with round-trips.
+ *
+ * Uses free public APIs (no keys needed):
+ * - Open-Meteo for weather data
+ * - RestCountries for country info
+ * - IP-API for geolocation
+ *
+ * Run: bun examples/05-code-mode.ts
+ */
+
+import { z } from "zod";
+import { Agent, AzureChatCompletionsModel, stream, tool } from "../src";
+import { createCodeModeTool, WorkerExecutor } from "../src/core/codemode";
+
+// ── Model ──────────────────────────────────────────────────────────
+
+const model = new AzureChatCompletionsModel({
+	endpoint: process.env.AZURE_OPENAI_ENDPOINT!,
+	apiKey: process.env.AZURE_OPENAI_API_KEY!,
+	deployment: process.env.AZURE_OPENAI_DEPLOYMENT ?? "gpt-5-chat",
+	apiVersion: process.env.AZURE_OPENAI_API_VERSION,
+});
+
+// ── Tools (real APIs) ──────────────────────────────────────────────
+
+const getWeather = tool({
+	name: "get_weather",
+	description:
+		"Get current weather for a location by latitude and longitude. Returns temperature (°C), wind speed, and weather description.",
+	parameters: z.object({
+		latitude: z.number().describe("Latitude of the location"),
+		longitude: z.number().describe("Longitude of the location"),
+	}),
+	execute: async (_ctx, { latitude, longitude }) => {
+		const url = `https://api.open-meteo.com/v1/forecast?latitude=${latitude}&longitude=${longitude}&current=temperature_2m,wind_speed_10m,weather_code`;
+		const res = await fetch(url);
+		const data = await res.json();
+		return JSON.stringify(data.current);
+	},
+});
+
+const getCountryInfo = tool({
+	name: "get_country_info",
+	description:
+		"Get information about a country by name. Returns capital, population, region, languages, and currencies.",
+	parameters: z.object({
+		country: z.string().describe("Country name (e.g. 'France', 'Japan')"),
+	}),
+	execute: async (_ctx, { country }) => {
+		const url = `https://restcountries.com/v3.1/name/${encodeURIComponent(country)}?fields=name,capital,population,region,subregion,languages,currencies,latlng`;
+		const res = await fetch(url);
+		if (!res.ok) return JSON.stringify({ error: `Country "${country}" not found` });
+		const data = await res.json();
+		const c = data[0];
+		return JSON.stringify({
+			name: c.name.common,
+			capital: c.capital?.[0],
+			population: c.population,
+			region: c.region,
+			subregion: c.subregion,
+			languages: c.languages,
+			currencies: c.currencies,
+			latlng: c.latlng,
+		});
+	},
+});
+
+const geocode = tool({
+	name: "geocode",
+	description: "Convert a city/place name to latitude and longitude coordinates.",
+	parameters: z.object({
+		query: z.string().describe("City or place name to geocode (e.g. 'Paris', 'Tokyo')"),
+	}),
+	execute: async (_ctx, { query }) => {
+		const url = `https://geocoding-api.open-meteo.com/v1/search?name=${encodeURIComponent(query)}&count=1`;
+		const res = await fetch(url);
+		const data = await res.json();
+		if (!data.results?.length) return JSON.stringify({ error: `Location "${query}" not found` });
+		const r = data.results[0];
+		return JSON.stringify({
+			name: r.name,
+			country: r.country,
+			latitude: r.latitude,
+			longitude: r.longitude,
+		});
+	},
+});
+
+// ── Code Mode setup ────────────────────────────────────────────────
+
+const executor = new WorkerExecutor({ timeout: 30_000 });
+
+const codemode = createCodeModeTool({
+	tools: [getWeather, getCountryInfo, geocode],
+	executor,
+});
+
+// ── Agent ──────────────────────────────────────────────────────────
+
+const agent = new Agent({
+	name: "travel-researcher",
+	instructions: `You are a travel research assistant. When asked about destinations, use code mode to efficiently gather all the information in one go.
+
+You have access to geocoding, weather, and country info APIs through the execute_code tool. Write code that calls multiple APIs in parallel using Promise.all when possible.
+
+Always return structured, readable results.`,
+	model,
+	tools: [codemode],
+});
+
+// ── Run ────────────────────────────────────────────────────────────
+
+async function main() {
+	const prompt =
+		"Compare Paris, Tokyo, and New York City as travel destinations right now. For each city, get the current weather and country info. Tell me which one has the nicest weather today.";
+
+	console.log(`\n🔵 Prompt: ${prompt}\n`);
+	console.log("─".repeat(60));
+	console.log("Running with WorkerExecutor (isolated V8 context)...\n");
+
+	const { stream: s, result } = stream(agent, prompt, {
+		maxTurns: 5,
+		runHooks: {
+			onToolStart: ({ toolName }) => {
+				console.log(`\n🔧 Tool call: ${toolName}`);
+			},
+			onToolEnd: ({ toolName, result: toolResult }) => {
+				console.log(`✅ ${toolName} completed`);
+				try {
+					const parsed = JSON.parse(toolResult);
+					if (parsed.code) {
+						// Code mode result — show the generated code
+						console.log("\n📜 Generated code:");
+						console.log("┌" + "─".repeat(78) + "┐");
+						for (const line of parsed.code.split("\n")) {
+							console.log(`│ ${line.padEnd(77)}│`);
+						}
+						console.log("└" + "─".repeat(78) + "┘");
+						// Show execution result
+						console.log("\n📦 Execution result:");
+						const pretty = JSON.stringify(parsed.result, null, 2);
+						for (const line of pretty.split("\n")) {
+							console.log(`   ${line}`);
+						}
+						if (parsed.logs?.length) {
+							console.log("\n📋 Console logs:");
+							for (const log of parsed.logs) {
+								console.log(`   ${log}`);
+							}
+						}
+					}
+				} catch {
+					// not JSON
+				}
+				console.log();
+			},
+		},
+	});
+
+	for await (const event of s) {
+		if (event.type === "content_delta") {
+			process.stdout.write(event.content);
+		}
+	}
+
+	const final = await result;
+	console.log("\n\n" + "─".repeat(60));
+	console.log(`Turns: ${final.numTurns} | Tokens: ${final.usage.totalTokens}`);
+}
+
+main().catch(console.error);
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "stratus-sdk",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
diff --git a/tests/core/codemode.test.ts b/tests/core/codemode.test.ts
@@ -1623,4 +1623,179 @@ describe("WorkerExecutor", () => {
 		const result = JSON.parse(resultStr);
 		expect(result.result).toEqual({ temp: 72, city: "NYC" });
 	});
+
+	test("handles non-Error rejection (raw string throw)", async () => {
+		const executor = new WorkerExecutor();
+		const fns = {
+			bad: async () => {
+				throw "raw string rejection";
+			},
+		};
+		const result = await executor.execute(
+			"async () => { return await codemode.bad(); }",
+			fns,
+		);
+		expect(result.error).toBe("raw string rejection");
+	});
+
+	test("handles large return values across worker boundary", async () => {
+		const executor = new WorkerExecutor();
+		const result = await executor.execute(
+			"async () => { return Array.from({ length: 10000 }, (_, i) => i); }",
+			{},
+		);
+		expect(result.error).toBeUndefined();
+		expect((result.result as number[]).length).toBe(10000);
+	});
+
+	test("handles undefined return", async () => {
+		const executor = new WorkerExecutor();
+		const result = await executor.execute("async () => { /* no return */ }", {});
+		expect(result.error).toBeUndefined();
+		// undefined doesn't survive structured clone, becomes null or undefined
+		expect(result.result == null).toBe(true);
+	});
+
+	test("handles null return", async () => {
+		const executor = new WorkerExecutor();
+		const result = await executor.execute("async () => { return null; }", {});
+		expect(result.error).toBeUndefined();
+		expect(result.result).toBeNull();
+	});
+
+	test("handles syntax error in code", async () => {
+		const executor = new WorkerExecutor();
+		const result = await executor.execute("async () => { if ( }", {});
+		expect(result.error).toBeDefined();
+	});
+
+	test("times out on infinite loop", async () => {
+		const executor = new WorkerExecutor({ timeout: 300 });
+		const result = await executor.execute(
+			"async () => { while (true) {} }",
+			{},
+		);
+		expect(result.error).toBe("Execution timed out");
+	});
+
+	test("multiple sequential executions each get a fresh worker", async () => {
+		const executor = new WorkerExecutor();
+		const results: number[] = [];
+		for (let i = 0; i < 5; i++) {
+			const result = await executor.execute(`async () => { return ${i}; }`, {});
+			results.push(result.result as number);
+		}
+		expect(results).toEqual([0, 1, 2, 3, 4]);
+	});
+
+	test("handles tool that returns slowly (worker waits on host)", async () => {
+		const executor = new WorkerExecutor({ timeout: 10_000 });
+		const fns = {
+			slow: async () => {
+				await new Promise((r) => setTimeout(r, 200));
+				return "slow result";
+			},
+		};
+		const result = await executor.execute(
+			"async () => { return await codemode.slow(); }",
+			fns,
+		);
+		expect(result.result).toBe("slow result");
+	});
+
+	test("code without tool calls works with empty fns map", async () => {
+		const executor = new WorkerExecutor();
+		const result = await executor.execute(
+			"async () => { const x = [1,2,3]; return x.map(n => n * 2); }",
+			{},
+		);
+		expect(result.result).toEqual([2, 4, 6]);
+	});
+
+	test("returning nested objects survives structured clone", async () => {
+		const executor = new WorkerExecutor();
+		const result = await executor.execute(
+			`async () => {
+				return {
+					users: [
+						{ name: "Alice", scores: [10, 20] },
+						{ name: "Bob", scores: [30, 40] },
+					],
+					meta: { total: 2, nested: { deep: true } },
+				};
+			}`,
+			{},
+		);
+		expect(result.error).toBeUndefined();
+		const r = result.result as any;
+		expect(r.users).toHaveLength(2);
+		expect(r.users[0].scores).toEqual([10, 20]);
+		expect(r.meta.nested.deep).toBe(true);
+	});
+
+	test("tool call that returns undefined", async () => {
+		const executor = new WorkerExecutor();
+		const fns = {
+			noop: async () => undefined,
+		};
+		const result = await executor.execute(
+			"async () => { const r = await codemode.noop(); return { got: r }; }",
+			fns,
+		);
+		expect(result.error).toBeUndefined();
+		// undefined doesn't survive structured clone in postMessage
+		expect((result.result as any).got == null).toBe(true);
+	});
+
+	test("concurrent executions on same WorkerExecutor instance", async () => {
+		const executor = new WorkerExecutor();
+		const promises = Array.from({ length: 5 }, (_, i) =>
+			executor.execute(`async () => { return ${i} * 10; }`, {}),
+		);
+		const results = await Promise.all(promises);
+		expect(results.map((r) => r.result)).toEqual([0, 10, 20, 30, 40]);
+		expect(results.every((r) => !r.error)).toBe(true);
+	});
+
+	test("error in tool preserves logs captured before the error", async () => {
+		const executor = new WorkerExecutor();
+		const fns = {
+			explode: async () => {
+				throw new Error("kaboom");
+			},
+		};
+		const result = await executor.execute(
+			`async () => {
+				console.log("step 1");
+				console.log("step 2");
+				await codemode.explode();
+				console.log("step 3");
+			}`,
+			fns,
+		);
+		expect(result.error).toBe("kaboom");
+		expect(result.logs).toContain("step 1");
+		expect(result.logs).toContain("step 2");
+		expect(result.logs).not.toContain("step 3");
+	});
+
+	test("code that accesses globalThis still works in worker", async () => {
+		const executor = new WorkerExecutor();
+		const result = await executor.execute(
+			"async () => { return typeof globalThis === 'object'; }",
+			{},
+		);
+		expect(result.error).toBeUndefined();
+		expect(result.result).toBe(true);
+	});
+
+	test("handles boolean and string return types", async () => {
+		const executor = new WorkerExecutor();
+		const r1 = await executor.execute("async () => { return true; }", {});
+		expect(r1.result).toBe(true);
+		const r2 = await executor.execute("async () => { return 'hello'; }", {});
+		expect(r2.result).toBe("hello");
+		const r3 = await executor.execute("async () => { return 0; }", {});
+		expect(r3.result).toBe(0);
+	});
 });

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "stratus-sdk",`
`3`		`- "version": "0.10.0",`
	`3`	`+ "version": "0.11.0",`
`4`	`4`	`"type": "module",`
`5`	`5`	`"main": "./dist/index.js",`
`6`	`6`	`"types": "./dist/index.d.ts",`