@codeworksh/aikit 0.3.1 → 0.4.1-dev.20260530133305

package/README.md

@@ -1,6 +1,20 @@
 # @codeworksh/aikit
 
-Toolkit for building AI agents and streaming LLM workflows.
+@codeworksh/aikit is a **TypeScript SDK** for building AI agents and agentic harnesses. It provides a unified API for working with multiple LLM providers, built on top of the Vercel AI SDK, with full support for tool calling (function calling) required for agentic workflows.
+
+It gives you the basic primitives for streaming LLM responses without the extra bloat, letting you handle the orchestration yourself.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Supported Providers](#supported-providers)
+- [Quick Start](#quick-start)
+- [Tools](#tools)
+- [Providers and Models](#providers-and-models)
+- [CLI Tools](#cli-tools)
+  - [Model Generation](#model-generation)
+  - [OAuth Providers](#oauth-providers)
+- [Contribute](#contribute)
 
 ## Installation
 
@@ -10,196 +24,146 @@ npm install @codeworksh/aikit
 
 Node `>=24.14.1` is required.
 
-## What You Get
-
-- `llm(...)` to resolve a model from the built-in registry
-- `stream(...)` and `stream.complete(...)` for provider-normalized LLM streaming
-- `Agent.create(...)` for a stateful agent instance
-- `agent.loop(...)` and `agent.loopContinue(...)` for lower-level turn orchestration
-- `Message` helpers for typed messages and generated `messageId` values
+## Supported Providers
 
-## Root API
+Built on top of the Vercel AI SDK, `@codeworksh/aikit` supports a wide array of providers natively:
 
-```ts
-import { Agent, Message, agent, llm, stream } from "@codeworksh/aikit";
-```
+- **Anthropic** (`@ai-sdk/anthropic`)
+- **OpenAI** (`@ai-sdk/openai`)
+- **Google** (`@ai-sdk/google`)
+- **Google Vertex AI** (`@ai-sdk/google-vertex`)
+- **xAI** (`@ai-sdk/xai`)
+- **OpenRouter** (`@openrouter/ai-sdk-provider`)
+- **OpenAI Compatible APIs** (`@ai-sdk/openai-compatible`)
 
 ## Quick Start
 
 ```ts
-import { Agent } from "@codeworksh/aikit";
-
-const agent = await Agent.create({
-	provider: "anthropic",
-	model: "claude-haiku-4-5-20251001",
-	getApiKey: async () => process.env.ANTHROPIC_API_KEY,
-});
-
-agent.setSystemPrompt("Be concise.");
-
-await agent.prompt([{ type: "text", text: "Reply with exactly: hello" }]);
-
-const lastMessage = agent.state.messages.at(-1);
-console.log(lastMessage?.messageId);
-console.log(lastMessage?.role);
-```
-
-## Stream Events
-
-Use `stream(...)` when you want token and part-level events.
-
-```ts
-import { Message, llm, stream } from "@codeworksh/aikit";
+import { llm, stream, Message } from "@codeworksh/aikit";
 
+// Resolve a model from the built-in registry
 const model = await llm("anthropic", "claude-haiku-4-5-20251001");
 if (!model) throw new Error("Model not found");
 
-const s = stream(
-	model,
-	{
-		messages: [
-			Message.createUserMessage({
-				role: "user",
-				time: { created: Date.now() },
-				parts: [{ type: "text", text: "Count from 1 to 3" }],
-			}),
-		],
-	},
-	{ apiKey: process.env.ANTHROPIC_API_KEY },
-);
+// Setup conversation context
+const context: Message.Context = {
+  systemPrompt: "You are a helpful coding assistant.",
+  messages: [
+    Message.createUserMessage({
+      role: "user",
+      time: { created: Date.now() },
+      parts: [{ type: "text", text: "Write a simple loop in TypeScript." }],
+    }),
+  ],
+};
+
+// Option 1: Stream events
+const s = stream(model, context, { apiKey: process.env.ANTHROPIC_API_KEY });
 
 for await (const event of s) {
-	if (event.type === "text.delta") {
-		process.stdout.write(event.delta);
-	}
+  if (event.type === "text.delta") {
+    process.stdout.write(event.delta);
+  }
 }
 
 const finalMessage = await s.result();
-console.log(finalMessage.messageId);
+console.log(`\nMessage ID: ${finalMessage.messageId}`);
+
+// Option 2: Get complete response without streaming
+const message = await stream.complete(model, context, { apiKey: process.env.ANTHROPIC_API_KEY });
+console.log(message.parts);
 ```
 
-## Agent Instance
+## Tools
 
-`Agent.create(...)` is the simplest way to work with a stateful agent.
+Tools enable LLMs to interact with external systems. `@codeworksh/aikit` provides native support for function calling and schema validation using TypeBox.
 
 ```ts
-import { Agent } from "@codeworksh/aikit";
-
-const agent = await Agent.create({
-	provider: "anthropic",
-	model: "claude-haiku-4-5-20251001",
-	getApiKey: async () => process.env.ANTHROPIC_API_KEY,
-});
+import { Type, llm, stream, Message, validateToolArguments } from "@codeworksh/aikit";
+
+const calculatorTool = {
+  name: "calculator",
+  description: "Evaluate arithmetic expressions",
+  parameters: Type.Object({
+    expression: Type.String(),
+  }),
+};
+
+const context: Message.Context = {
+  messages: [
+    Message.createUserMessage({
+      role: "user",
+      time: { created: Date.now() },
+      parts: [{ type: "text", text: "What is 25 * 18?" }],
+    }),
+  ],
+  tools: [calculatorTool],
+};
+
+const response = await stream.complete(model, context, { apiKey: process.env.ANTHROPIC_API_KEY });
+
+// Check for tool calls in the response
+for (const part of response.parts) {
+  if (part.type === "toolCall") {
+    console.log(`Executing tool: ${part.name}`);
+    
+    // Validates arguments against TypeBox schema automatically
+    const args = validateToolArguments(calculatorTool.parameters, part.arguments);
+    // Execute your tool logic here...
+  }
+}
+```
 
-agent.setSystemPrompt("Be concise.");
+## Providers and Models
 
-agent.subscribe((event) => {
-	if (event.type === "message.end") {
-		console.log(event.message.role, event.message.messageId);
-	}
-});
+`@codeworksh/aikit` uses a registry to fetch model specifications and metadata. 
 
-await agent.prompt([{ type: "text", text: "Say hello in one line." }]);
+```ts
+import { llm } from "@codeworksh/aikit";
 
-console.log(agent.state.messages);
-```
+// Get all available providers
+const providers = await llm.providers();
+console.log(providers);
 
-## With Tools
+// Get all models for a specific provider
+const anthropicModels = await llm.models("anthropic");
 
-```ts
-import { Type } from "@sinclair/typebox";
-import { Agent } from "@codeworksh/aikit";
-
-const calculatorTool = Agent.defineTool({
-	name: "calculator",
-	label: "Calculator",
-	description: "Evaluate arithmetic expressions",
-	parameters: Type.Object({
-		expression: Type.String(),
-	}),
-	async execute(_callID, params) {
-		return {
-			status: "completed",
-			result: {
-				content: [{ type: "text", text: `result for ${params.expression}` }],
-				isError: false,
-			},
-		};
-	},
-});
-
-const instance = await Agent.create({
-	provider: "anthropic",
-	model: "claude-haiku-4-5-20251001",
-	getApiKey: async () => process.env.ANTHROPIC_API_KEY,
-	initialState: {
-		tools: [calculatorTool],
-	},
-});
-
-await instance.prompt([{ type: "text", text: "Use the calculator tool for 25 * 18." }]);
+// Get a specific model directly
+const gpt4 = await llm.model("openai", "gpt-4o");
 ```
 
-## Lower-Level Loop
+## CLI Tools
 
-Use `agent.loop(...)` when you want loop execution without creating a stateful instance.
+`@codeworksh/aikit` ships with a CLI tool for managing local metadata and authentication.
 
-```ts
-import { Message, agent, llm } from "@codeworksh/aikit";
+You can invoke it using `npx aikit` or `pnpm aikit`.
 
-const model = await llm("anthropic", "claude-haiku-4-5-20251001");
-if (!model) throw new Error("Model not found");
+### Model Generation
+
+Generate a `models.gen.json` file fetching the latest metadata about providers and their available models from `models.dev`.
 
-const run = agent.loop(
-	{
-		model,
-		apiKey: process.env.ANTHROPIC_API_KEY,
-		convertToLlm: async (messages) => messages,
-	},
-	{
-		systemPrompt: "Be concise.",
-		messages: [],
-		tools: [],
-	},
-	[
-		Message.createUserMessage({
-			role: "user",
-			time: { created: Date.now() },
-			parts: [{ type: "text", text: "Reply with exactly: ok" }],
-		}),
-	],
-);
-
-const messages = await run.result();
-console.log(messages.at(-1)?.role);
+```bash
+pnpm aikit modelgen [path]
 ```
 
-## Message IDs
+### OAuth Providers
 
-Every user and assistant message has a `messageId`.
+Manage OAuth credentials for providers that require it, such as OpenAI Codex.
 
-Use the helpers when constructing messages yourself:
+```bash
+# Start an OAuth login flow in your browser
+pnpm aikit auth --openai-codex
 
-```ts
-import { Message } from "@codeworksh/aikit";
+# Check the status of your stored credentials
+pnpm aikit auth --openai-codex --status
 
-const userMessage = Message.createUserMessage({
-	role: "user",
-	time: { created: Date.now() },
-	parts: [{ type: "text", text: "hello" }],
-});
+# Refresh your current credentials
+pnpm aikit auth --openai-codex --refresh
 
-console.log(userMessage.messageId);
+# Clear stored credentials
+pnpm aikit auth --openai-codex --logout
 ```
 
-This is useful for persistence layers like SQLite, event reconciliation, and updating stored messages by identity instead of array position.
-
-## Lower-Level APIs
-
-- `stream(...)`: raw provider-normalized stream
-- `stream.complete(...)`: final assistant message without manual iteration
-- `Agent.create(...)`: stateful agent instance
-- `agent.loop(...)`: lower-level agent loop
-- `agent.loopContinue(...)`: continue from an existing context
+## Contribute
 
-API docs can be added later. For now, the tests under `packages/aikit/test/` are the best reference for concrete usage.
+`@codeworksh/aikit` is open to community contribution. Please ensure you submit an issue before submitting a pull request. The project prefers open community discussion before accepting new features.

package/cli.d.mts

@@ -0,0 +1 @@
+export { };

package/cli.mjs

@@ -0,0 +1,308 @@
+#!/usr/bin/env node
+import { a as protocolForPackage, c as ModelCatalog, l as lazy, n as isAISDKPackage, s as Model, u as Filesystem } from "./registry-CYfzJ6lk.mjs";
+import { c as openAICodexHeaders, n as OpenAICodexOAuthClient, t as JsonOpenAICodexAuthStorage } from "./codex-DfYk740t.mjs";
+import { resolve } from "node:path";
+import yargs from "yargs";
+import { hideBin } from "yargs/helpers";
+import { mapValues, pickBy, pipe } from "remeda";
+//#region package.json
+var version = "0.4.0";
+//#endregion
+//#region src/cli/modelgen.ts
+const DEFAULT_PROVIDER_BASE_URLS = {
+	[Model.KnownProviderEnum.anthropic]: "https://api.anthropic.com/v1",
+	[Model.KnownProviderEnum.openai]: "https://api.openai.com/v1",
+	[Model.KnownProviderEnum.openrouter]: "https://openrouter.ai/api/v1",
+	[Model.KnownProviderEnum.xai]: "https://api.x.ai/v1"
+};
+function modelsDevURL() {
+	return process.env.OPENCODE_MODELS_URL || "https://models.dev";
+}
+function modelsDevPath() {
+	return process.env.CODEWORK_MODELS_DEV;
+}
+const modelsDevData = lazy(async () => {
+	const path = modelsDevPath();
+	if (path) {
+		const result = await Filesystem.readJson(path).catch(() => void 0);
+		if (result) return result;
+	}
+	const json = await fetch(`${modelsDevURL()}/api.json`).then((x) => x.text());
+	return JSON.parse(json);
+});
+async function pullModelsDevData() {
+	return modelsDevData();
+}
+function toModelValue(providerId, provider, model) {
+	return applyModification(providerId, provider, model);
+}
+async function loadBuiltInFromModelsDev() {
+	return pipe(await pullModelsDevData(), pickBy((provider) => Object.values(provider.models).some((model) => Boolean(model.tool_call) && isAISDKPackage(resolveModelNpm(provider, model)))), mapValues((provider, providerId) => pipe(provider.models, pickBy((model) => Boolean(model.tool_call) && isAISDKPackage(resolveModelNpm(provider, model))), mapValues((model) => toModelValue(providerId, provider, model)), pickBy((model) => model !== void 0))));
+}
+function resolveModelNpm(provider, model) {
+	return model.provider?.npm ?? provider.npm ?? "@ai-sdk/openai-compatible";
+}
+function resolveModelBaseUrl(provider, model) {
+	const protocol = protocolForPackage(resolveModelNpm(provider, model));
+	return model.baseUrl ?? model.provider?.api ?? provider.api ?? DEFAULT_PROVIDER_BASE_URLS[protocol] ?? "";
+}
+function resolveModelAPIMethod(npm) {
+	const protocol = protocolForPackage(npm);
+	if (protocol === Model.KnownProviderEnum.openai || protocol === Model.KnownProviderEnum.xai) return Model.APIMethodEnum.responses;
+	return Model.APIMethodEnum.languageModel;
+}
+function resolveProviderOptionsKey(protocol) {
+	if (protocol === Model.KnownProviderEnum.openaiCompatible) return "openai-compatible";
+	if (protocol === Model.KnownProviderEnum.googleVertex) return "google-vertex";
+	if (protocol === Model.KnownProviderEnum.googleVertexAnthropic) return "google-vertex-anthropic";
+	return protocol;
+}
+const OPENAI_RESPONSES_NONE_REASONING_MODELS = new Set([
+	"gpt-5.1",
+	"gpt-5.2",
+	"gpt-5.3-codex",
+	"gpt-5.4",
+	"gpt-5.4-mini",
+	"gpt-5.4-nano",
+	"gpt-5.5"
+]);
+function supportsOpenAiXhigh(modelId) {
+	return modelId.includes("gpt-5.2") || modelId.includes("gpt-5.3") || modelId.includes("gpt-5.4") || modelId.includes("gpt-5.5");
+}
+function mergeThinkingLevelMap(model, map) {
+	model.thinkingLevelMap = {
+		...model.thinkingLevelMap,
+		...map
+	};
+}
+function applyThinkingLevelMetadata(model) {
+	if (model.protocol === Model.KnownProviderEnum.openai && model.id.startsWith("gpt-5")) mergeThinkingLevelMap(model, { off: null });
+	if (model.protocol === Model.KnownProviderEnum.openai && model.provider.id === "openai" && OPENAI_RESPONSES_NONE_REASONING_MODELS.has(model.id)) mergeThinkingLevelMap(model, { off: "none" });
+	if (supportsOpenAiXhigh(model.id)) mergeThinkingLevelMap(model, { xhigh: "xhigh" });
+	if (model.id.includes("opus-4-6") || model.id.includes("opus-4.6")) mergeThinkingLevelMap(model, { xhigh: "max" });
+	if (model.id.includes("opus-4-7") || model.id.includes("opus-4.7")) mergeThinkingLevelMap(model, { xhigh: "xhigh" });
+}
+async function generateModels(args = {}) {
+	const path = resolve(args.path ?? ModelCatalog.path());
+	const models = await loadBuiltInFromModelsDev();
+	await Filesystem.writeJson(path, models);
+	return path;
+}
+const ModelgenCommand = {
+	command: "modelgen [path]",
+	describe: "generate models.gen.json",
+	builder: (yargs) => yargs.positional("path", {
+		type: "string",
+		describe: "output path (defaults to CODEWORK_MODELGEN_PATH or ./models.gen.json)"
+	}),
+	handler: async (args) => {
+		const path = await generateModels(args);
+		console.log(`Generated model catalog at ${path}`);
+	}
+};
+function applyModification(providerId, provider, model) {
+	const npm = resolveModelNpm(provider, model);
+	if (!isAISDKPackage(npm)) return;
+	const protocol = protocolForPackage(npm);
+	const baseUrl = resolveModelBaseUrl(provider, model);
+	const providerInfo = {
+		id: providerId,
+		name: provider.name,
+		source: "api",
+		env: provider.env
+	};
+	if (provider.key) providerInfo.key = provider.key;
+	const api = {
+		id: model.id,
+		method: resolveModelAPIMethod(npm)
+	};
+	if (baseUrl) api.url = baseUrl;
+	const info = {
+		id: model.id,
+		name: model.name,
+		provider: providerInfo,
+		baseUrl,
+		reasoning: Boolean(model.reasoning),
+		input: Model.normalizeInput(model.modalities.input),
+		cost: {
+			input: model.cost?.input ?? 0,
+			output: model.cost?.output ?? 0,
+			cacheRead: model.cost?.cache_read ?? 0,
+			cacheWrite: model.cost?.cache_write ?? 0
+		},
+		contextWindow: model.limit?.context ?? 4096,
+		maxTokens: model.limit?.output ?? 4096,
+		headers: {
+			...provider.headers,
+			...model.provider?.headers,
+			...model.headers
+		},
+		npm,
+		api,
+		providerOptionsKey: resolveProviderOptionsKey(protocol),
+		protocol
+	};
+	if (Object.keys(info.headers ?? {}).length === 0) delete info.headers;
+	applyThinkingLevelMetadata(info);
+	return info;
+}
+//#endregion
+//#region src/cli/oauth.ts
+async function promptLine(message) {
+	const rl = (await import("node:readline/promises")).createInterface({
+		input: process.stdin,
+		output: process.stdout
+	});
+	try {
+		return await rl.question(`${message} `);
+	} finally {
+		rl.close();
+	}
+}
+async function openBrowser(url) {
+	const { spawn } = await import("node:child_process");
+	const command = process.platform === "darwin" ? {
+		file: "open",
+		args: [url]
+	} : process.platform === "win32" ? {
+		file: "cmd",
+		args: [
+			"/c",
+			"start",
+			"",
+			url
+		]
+	} : {
+		file: "xdg-open",
+		args: [url]
+	};
+	spawn(command.file, command.args, {
+		detached: true,
+		stdio: "ignore"
+	}).unref();
+}
+function printCredentials(credentials, options) {
+	if (options.json) {
+		console.log(JSON.stringify({
+			accountId: credentials.accountId,
+			expires: credentials.expires,
+			expiresAt: new Date(credentials.expires).toISOString(),
+			headers: options.printHeaders ? openAICodexHeaders(credentials) : void 0
+		}, null, 2));
+		return;
+	}
+	console.log(`Account: ${credentials.accountId}`);
+	console.log(`Expires: ${new Date(credentials.expires).toLocaleString()}`);
+	if (options.printHeaders) {
+		console.log("Headers:");
+		for (const [name, value] of Object.entries(openAICodexHeaders(credentials))) console.log(`${name}: ${value}`);
+	}
+}
+async function runOpenAICodexAuth(args) {
+	const storage = new JsonOpenAICodexAuthStorage({ path: args.authFile });
+	const client = new OpenAICodexOAuthClient({ storage });
+	if (args.logout) {
+		await client.logout();
+		console.log(`Cleared OpenAI Codex credentials from ${storage.path}`);
+		return;
+	}
+	if (args.status) {
+		const credentials = await storage.get();
+		if (!credentials) {
+			console.log(`No OpenAI Codex credentials found at ${storage.path}`);
+			process.exitCode = 1;
+			return;
+		}
+		printCredentials(credentials, args);
+		return;
+	}
+	if (args.refresh) {
+		const credentials = await client.getCredentials();
+		if (!credentials) {
+			console.log(`No OpenAI Codex credentials found at ${storage.path}`);
+			process.exitCode = 1;
+			return;
+		}
+		console.log(`Refreshed OpenAI Codex credentials in ${storage.path}`);
+		printCredentials(credentials, args);
+		return;
+	}
+	const credentials = await client.login({
+		originator: args.originator,
+		onAuth: (info) => {
+			console.log(info.instructions ?? "Complete OpenAI Codex authentication in your browser.");
+			console.log(info.url);
+			if (args.browser !== false) openBrowser(info.url).catch((error) => {
+				console.warn(`Failed to open browser: ${error instanceof Error ? error.message : String(error)}`);
+			});
+		},
+		onPrompt: async (prompt) => promptLine(prompt.message),
+		onManualCodeInput: args.manual ? async () => promptLine("Paste the redirect URL or authorization code, or wait for browser callback:") : void 0
+	});
+	console.log(`Saved OpenAI Codex credentials to ${storage.path}`);
+	printCredentials(credentials, args);
+}
+//#endregion
+//#region src/cli.ts
+const cli = yargs(hideBin(process.argv)).scriptName("aikit").wrap(100).help("help", "show help").alias("help", "h").version("version", "show version number", version).alias("version", "v").command(ModelgenCommand).command({
+	command: "auth",
+	describe: "manage OAuth credentials",
+	builder: (yargs) => yargs.option("openai-codex", {
+		type: "boolean",
+		describe: "use OpenAI Codex OAuth"
+	}).option("auth-file", {
+		type: "string",
+		describe: "path to auth.json (defaults to CODEWORK_CREDENTIALS or ~/.codework/aikit/auth.json)"
+	}).option("browser", {
+		type: "boolean",
+		default: true,
+		describe: "open the authorization URL in the default browser"
+	}).option("manual", {
+		type: "boolean",
+		default: false,
+		describe: "also prompt for a pasted redirect URL or authorization code"
+	}).option("originator", {
+		type: "string",
+		default: "codework",
+		describe: "OAuth originator value"
+	}).option("status", {
+		type: "boolean",
+		describe: "show stored credential status without refreshing"
+	}).option("refresh", {
+		type: "boolean",
+		describe: "refresh stored credentials if expired"
+	}).option("logout", {
+		type: "boolean",
+		describe: "clear stored credentials"
+	}).option("json", {
+		type: "boolean",
+		describe: "print machine-readable output"
+	}).option("print-headers", {
+		type: "boolean",
+		describe: "print request headers for Codex API calls"
+	}).check((args) => {
+		if (!args.openaiCodex) throw new Error("Choose an auth provider, for example: auth --openai-codex");
+		if ([
+			args.status,
+			args.refresh,
+			args.logout
+		].filter(Boolean).length > 1) throw new Error("Choose only one of --status, --refresh, or --logout");
+		return true;
+	}),
+	handler: async (args) => {
+		await runOpenAICodexAuth(args);
+	}
+}).demandCommand(1, "Choose a command").strict().fail((message, error) => {
+	if (error) throw error;
+	if (message) throw new Error(message);
+});
+try {
+	await cli.parse();
+} catch (error) {
+	process.exitCode = 1;
+	console.error(error instanceof Error ? error.message : String(error));
+}
+//#endregion
+export {};
+
+//# sourceMappingURL=cli.mjs.map