@agi-cli/sdk 0.1.54 → 0.1.56

package/src/core/src/errors.ts

@@ -0,0 +1,102 @@
+/**
+ * Base error class for all AGI errors
+ */
+export class AGIError extends Error {
+	constructor(
+		message: string,
+		public readonly code: string,
+		public readonly status: number = 500,
+		public readonly details?: Record<string, unknown>,
+	) {
+		super(message);
+		this.name = this.constructor.name;
+		Error.captureStackTrace(this, this.constructor);
+	}
+
+	toJSON() {
+		return {
+			name: this.name,
+			message: this.message,
+			code: this.code,
+			status: this.status,
+			details: this.details,
+		};
+	}
+}
+
+/**
+ * Authentication and authorization errors
+ */
+export class AuthError extends AGIError {
+	constructor(message: string, details?: Record<string, unknown>) {
+		super(message, 'AUTH_ERROR', 401, details);
+	}
+}
+
+/**
+ * Configuration errors
+ */
+export class ConfigError extends AGIError {
+	constructor(message: string, details?: Record<string, unknown>) {
+		super(message, 'CONFIG_ERROR', 500, details);
+	}
+}
+
+/**
+ * Tool execution errors
+ */
+export class ToolError extends AGIError {
+	constructor(message: string, details?: Record<string, unknown>) {
+		super(message, 'TOOL_ERROR', 500, details);
+	}
+}
+
+/**
+ * Provider errors (API, model not found, etc.)
+ */
+export class ProviderError extends AGIError {
+	constructor(message: string, details?: Record<string, unknown>) {
+		super(message, 'PROVIDER_ERROR', 500, details);
+	}
+}
+
+/**
+ * Database errors
+ */
+export class DatabaseError extends AGIError {
+	constructor(message: string, details?: Record<string, unknown>) {
+		super(message, 'DATABASE_ERROR', 500, details);
+	}
+}
+
+/**
+ * Validation errors (bad input, schema mismatch, etc.)
+ */
+export class ValidationError extends AGIError {
+	constructor(message: string, details?: Record<string, unknown>) {
+		super(message, 'VALIDATION_ERROR', 400, details);
+	}
+}
+
+/**
+ * Not found errors (session, agent, tool, etc.)
+ */
+export class NotFoundError extends AGIError {
+	constructor(message: string, details?: Record<string, unknown>) {
+		super(message, 'NOT_FOUND', 404, details);
+	}
+}
+
+/**
+ * Service errors from ask-service, session-manager, etc.
+ */
+export class ServiceError extends AGIError {
+	constructor(
+		message: string,
+		code = 'SERVICE_ERROR',
+		status = 500,
+		details?: Record<string, unknown>,
+	) {
+		super(message, code, status, details);
+	}
+}

package/src/core/src/index.ts

@@ -0,0 +1,75 @@
+// =======================
+// Core AI Functions (from AI SDK)
+// =======================
+export {
+	generateText,
+	streamText,
+	generateObject,
+	streamObject,
+	tool,
+} from 'ai';
+export type { CoreMessage, Tool } from 'ai';
+
+// =======================
+// Provider & Model Resolution
+// =======================
+export { resolveModel } from './providers/resolver';
+export type { ProviderName, ModelConfig } from './providers/resolver';
+
+// Re-export provider catalog and utilities for easy access
+export {
+	catalog,
+	providerIds,
+	isProviderId,
+	isProviderAuthorized,
+	validateProviderModel,
+} from '../../providers/src/index.ts';
+export type { ProviderId, ModelInfo } from '../../types/src/index.ts';
+
+// =======================
+// Tools
+// =======================
+export { discoverProjectTools } from './tools/loader';
+export type { DiscoveredTool } from './tools/loader';
+
+// Re-export builtin tools for direct access
+export { buildFsTools } from './tools/builtin/fs/index';
+export { buildGitTools } from './tools/builtin/git';
+
+// =======================
+// Streaming & Artifacts
+// =======================
+export {
+	createFileDiffArtifact,
+	createToolResultPayload,
+} from './streaming/artifacts';
+export type {
+	Artifact,
+	FileDiffArtifact,
+	FileArtifact,
+} from './streaming/artifacts';
+
+// =======================
+// Types
+// =======================
+export type { ExecutionContext, ToolResult } from './types/index';
+
+// =======================
+// Schema Validation
+// =======================
+export { z } from 'zod';
+
+// =======================
+// Error Handling
+// =======================
+export {
+	AGIError,
+	AuthError,
+	ConfigError,
+	ToolError,
+	ProviderError,
+	DatabaseError,
+	ValidationError,
+	NotFoundError,
+	ServiceError,
+} from './errors';

package/src/core/src/providers/resolver.ts

@@ -0,0 +1,84 @@
+import { openai, createOpenAI } from '@ai-sdk/openai';
+import { anthropic, createAnthropic } from '@ai-sdk/anthropic';
+import { google } from '@ai-sdk/google';
+import { createOpenRouter } from '@openrouter/ai-sdk-provider';
+import { createOpenAICompatible } from '@ai-sdk/openai-compatible';
+
+export type ProviderName =
+	| 'openai'
+	| 'anthropic'
+	| 'google'
+	| 'openrouter'
+	| 'opencode';
+
+export type ModelConfig = {
+	apiKey?: string;
+	customFetch?: typeof fetch;
+	baseURL?: string;
+};
+
+export async function resolveModel(
+	provider: ProviderName,
+	model: string,
+	config: ModelConfig = {},
+) {
+	if (provider === 'openai') {
+		if (config.apiKey) {
+			const instance = createOpenAI({ apiKey: config.apiKey });
+			return instance(model);
+		}
+		return openai(model);
+	}
+
+	if (provider === 'anthropic') {
+		if (config.customFetch) {
+			return createAnthropic({
+				apiKey: config.apiKey || '',
+				fetch: config.customFetch as typeof fetch,
+			});
+		}
+		if (config.apiKey) {
+			const instance = createAnthropic({ apiKey: config.apiKey });
+			return instance(model);
+		}
+		return anthropic(model);
+	}
+
+	if (provider === 'google') {
+		if (config.apiKey) {
+			throw new Error('Google provider config not yet supported in SDK');
+		}
+		return google(model);
+	}
+
+	if (provider === 'openrouter') {
+		const apiKey = config.apiKey || process.env.OPENROUTER_API_KEY || '';
+		const openrouter = createOpenRouter({ apiKey });
+		return openrouter.chat(model);
+	}
+
+	if (provider === 'opencode') {
+		const baseURL = config.baseURL || 'https://opencode.ai/zen/v1';
+		const apiKey = config.apiKey || process.env.OPENCODE_API_KEY || '';
+
+		const ocOpenAI = createOpenAI({ apiKey, baseURL });
+		const ocAnthropic = createAnthropic({ apiKey, baseURL });
+		const ocCompat = createOpenAICompatible({
+			name: 'opencode',
+			baseURL,
+			headers: apiKey ? { Authorization: `Bearer ${apiKey}` } : undefined,
+		});
+
+		const id = model.toLowerCase();
+		if (id.includes('claude')) return ocAnthropic(model);
+		if (
+			id.includes('qwen3-coder') ||
+			id.includes('grok-code') ||
+			id.includes('kimi-k2')
+		)
+			return ocCompat(model);
+		return ocOpenAI(model);
+	}
+
+	throw new Error(`Unsupported provider: ${provider}`);
+}

package/src/core/src/streaming/artifacts.ts

@@ -0,0 +1,41 @@
+// Shared types and helpers for tool artifacts persisted in message parts.
+
+export type FileDiffArtifact = {
+	kind: 'file_diff';
+	patchFormat: 'unified';
+	patch: string; // full unified patch text
+	summary?: { files?: number; additions?: number; deletions?: number };
+};
+
+export type FileArtifact = {
+	kind: 'file';
+	path: string; // repository-relative path
+	mime?: string;
+	size?: number;
+	sha256?: string;
+};
+
+export type Artifact =
+	| FileDiffArtifact
+	| FileArtifact
+	| { kind: string; [k: string]: unknown };
+
+export function createFileDiffArtifact(
+	patch: string,
+	summary?: { files?: number; additions?: number; deletions?: number },
+): FileDiffArtifact {
+	return { kind: 'file_diff', patchFormat: 'unified', patch, summary };
+}
+
+export function createToolResultPayload(
+	name: string,
+	result?: unknown,
+	artifact?: Artifact,
+) {
+	const payload: { name: string; result?: unknown; artifact?: Artifact } = {
+		name,
+	};
+	if (result !== undefined) payload.result = result;
+	if (artifact) payload.artifact = artifact;
+	return payload;
+}

package/src/core/src/tools/builtin/bash.ts

@@ -0,0 +1,90 @@
+import { tool, type Tool } from 'ai';
+import { z } from 'zod';
+import { exec } from 'node:child_process';
+import DESCRIPTION from './bash.txt' with { type: 'text' };
+
+function normalizePath(p: string) {
+	const parts = p.replace(/\\/g, '/').split('/');
+	const stack: string[] = [];
+	for (const part of parts) {
+		if (!part || part === '.') continue;
+		if (part === '..') stack.pop();
+		else stack.push(part);
+	}
+	return `/${stack.join('/')}`;
+}
+
+function resolveSafePath(projectRoot: string, p: string) {
+	const root = normalizePath(projectRoot);
+	const abs = normalizePath(`${root}/${p || '.'}`);
+	if (!(abs === root || abs.startsWith(`${root}/`))) {
+		throw new Error(`cwd escapes project root: ${p}`);
+	}
+	return abs;
+}
+
+export function buildBashTool(projectRoot: string): {
+	name: string;
+	tool: Tool;
+} {
+	const bash = tool({
+		description: DESCRIPTION,
+		inputSchema: z
+			.object({
+				cmd: z.string().describe('Shell command to run (bash -lc <cmd>)'),
+				cwd: z
+					.string()
+					.default('.')
+					.describe('Working directory relative to project root'),
+				allowNonZeroExit: z
+					.boolean()
+					.optional()
+					.default(false)
+					.describe('If true, do not throw on non-zero exit'),
+			})
+			.strict(),
+		async execute({
+			cmd,
+			cwd,
+			allowNonZeroExit,
+		}: {
+			cmd: string;
+			cwd?: string;
+			allowNonZeroExit?: boolean;
+		}) {
+			const absCwd = resolveSafePath(projectRoot, cwd || '.');
+
+			return new Promise((resolve, reject) => {
+				const proc = exec(`bash -lc '${cmd.replace(/'/g, "'\\''")}'`, {
+					cwd: absCwd,
+					maxBuffer: 10 * 1024 * 1024,
+				});
+
+				let stdout = '';
+				let stderr = '';
+
+				proc.stdout?.on('data', (chunk) => {
+					stdout += chunk.toString();
+				});
+
+				proc.stderr?.on('data', (chunk) => {
+					stderr += chunk.toString();
+				});
+
+				proc.on('close', (exitCode) => {
+					if (exitCode !== 0 && !allowNonZeroExit) {
+						const msg = (stderr || stdout || `Command failed: ${cmd}`).trim();
+						reject(new Error(msg));
+					} else {
+						resolve({ exitCode: exitCode ?? 0, stdout, stderr });
+					}
+				});
+
+				proc.on('error', (err) => {
+					reject(err);
+				});
+			});
+		},
+	});
+	return { name: 'bash', tool: bash };
+}

package/src/core/src/tools/builtin/bash.txt

@@ -0,0 +1,7 @@
+- Execute a shell command using `bash -lc`
+- Returns `stdout`, `stderr`, and `exitCode`
+- `cwd` is relative to the project root and sandboxed within it
+
+Usage tips:
+- Chain multiple commands with `&&` to fail-fast
+- For long outputs, consider redirecting to a file and reading it

package/src/core/src/tools/builtin/edit.ts

@@ -0,0 +1,152 @@
+import { tool, type Tool } from 'ai';
+import { z } from 'zod';
+import { readFile, writeFile, access } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import DESCRIPTION from './edit.txt' with { type: 'text' };
+
+const replaceOp = z.object({
+	type: z.literal('replace'),
+	find: z.string().describe('String or regex (when regex=true)'),
+	replace: z.string().default(''),
+	regex: z.boolean().optional().default(false),
+	flags: z.string().optional().default('g'),
+	count: z
+		.number()
+		.int()
+		.min(1)
+		.optional()
+		.describe('Limit number of replacements'),
+});
+
+const insertOp = z.object({
+	type: z.literal('insert'),
+	position: z.enum(['before', 'after', 'start', 'end']).default('after'),
+	pattern: z.string().optional().describe('Anchor pattern for before/after'),
+	content: z.string(),
+	once: z.boolean().optional().default(true),
+});
+
+const deleteRangeOp = z.object({
+	type: z.literal('delete_range'),
+	start: z.string().describe('Start marker (first occurrence)'),
+	end: z.string().describe('End marker (first occurrence after start)'),
+	includeBoundaries: z.boolean().optional().default(false),
+});
+
+const opSchema = z.discriminatedUnion('type', [
+	replaceOp,
+	insertOp,
+	deleteRangeOp,
+]);
+
+export const editTool: Tool = tool({
+	description: DESCRIPTION,
+	inputSchema: z.object({
+		path: z.string().min(1),
+		ops: z.array(opSchema).min(1),
+		create: z.boolean().optional().default(false),
+	}),
+	async execute({
+		path,
+		ops,
+		create,
+	}: {
+		path: string;
+		ops: z.infer<typeof opSchema>[];
+		create?: boolean;
+	}) {
+		let exists = false;
+		try {
+			await access(path, constants.F_OK);
+			exists = true;
+		} catch {}
+
+		if (!exists) {
+			if (!create) throw new Error(`File not found: ${path}`);
+			await writeFile(path, '');
+		}
+		let text = await readFile(path, 'utf-8');
+		let applied = 0;
+
+		for (const op of ops) {
+			if (op.type === 'replace') {
+				const originalText = text;
+				if (op.regex) {
+					const re = new RegExp(op.find, op.flags || 'g');
+					if (op.count && op.count > 0) {
+						let n = 0;
+						text = text.replace(re, (m) => {
+							if (n < (op.count as number)) {
+								n += 1;
+								return op.replace;
+							}
+							return m;
+						});
+					} else text = text.replace(re, op.replace);
+				} else {
+					// Check if the text to find exists
+					if (!text.includes(op.find)) {
+						console.warn(
+							`Warning: Text not found for replace operation: "${op.find.substring(0, 50)}${op.find.length > 50 ? '...' : ''}"`,
+						);
+					}
+					if (op.count && op.count > 0) {
+						let remaining = op.count as number;
+						let idx = text.indexOf(op.find);
+						while (idx !== -1 && remaining > 0) {
+							text =
+								text.slice(0, idx) +
+								op.replace +
+								text.slice(idx + op.find.length);
+							remaining -= 1;
+							idx = text.indexOf(op.find, idx + op.replace.length);
+						}
+					} else {
+						text = text.split(op.find).join(op.replace);
+					}
+				}
+				// Only count as applied if text actually changed
+				if (text !== originalText) {
+					applied += 1;
+				}
+			} else if (op.type === 'insert') {
+				if (op.position === 'start') {
+					text = `${op.content}${text}`;
+					applied += 1;
+					continue;
+				}
+				if (op.position === 'end') {
+					text = `${text}${op.content}`;
+					applied += 1;
+					continue;
+				}
+				if (!op.pattern)
+					throw new Error('insert requires pattern for before/after');
+				const idx = text.indexOf(op.pattern);
+				if (idx === -1) continue;
+				if (op.position === 'before')
+					text = text.slice(0, idx) + op.content + text.slice(idx);
+				else
+					text =
+						text.slice(0, idx + op.pattern.length) +
+						op.content +
+						text.slice(idx + op.pattern.length);
+				applied += 1;
+				if (op.once) continue;
+			} else if (op.type === 'delete_range') {
+				const startIdx = text.indexOf(op.start);
+				if (startIdx === -1) continue;
+				const after = startIdx + op.start.length;
+				const endIdx = text.indexOf(op.end, after);
+				if (endIdx === -1) continue;
+				const from = op.includeBoundaries ? startIdx : after;
+				const to = op.includeBoundaries ? endIdx + op.end.length : endIdx;
+				text = text.slice(0, from) + text.slice(to);
+				applied += 1;
+			}
+		}
+
+		await writeFile(path, text);
+		return { path, opsApplied: applied, bytes: text.length };
+	},
+});

package/src/core/src/tools/builtin/edit.txt

@@ -0,0 +1,7 @@
+- Edit a file using structured operations
+- Supported ops: `replace`, `insert`, `delete_range`
+- Paths are relative to the project root; can create files if flagged
+
+Usage tips:
+- Prefer minimal, targeted changes for clarity
+- For sweeping refactors, consider Write or Patch to replace full content

package/src/core/src/tools/builtin/file-cache.ts

@@ -0,0 +1,39 @@
+/**
+ * File content cache to track modifications during a session/step
+ * This helps ensure tools always work with the latest file content
+ */
+
+const fileContentCache = new Map<string, Map<string, string>>();
+
+export function getFileCache(sessionId: string): Map<string, string> {
+	if (!fileContentCache.has(sessionId)) {
+		fileContentCache.set(sessionId, new Map());
+	}
+	return fileContentCache.get(sessionId) as Map<string, string>;
+}
+
+export function updateFileCache(
+	sessionId: string,
+	filePath: string,
+	content: string,
+): void {
+	const cache = getFileCache(sessionId);
+	cache.set(filePath, content);
+}
+
+export function getCachedContent(
+	sessionId: string,
+	filePath: string,
+): string | undefined {
+	const cache = getFileCache(sessionId);
+	return cache.get(filePath);
+}
+
+export function clearFileCache(sessionId: string): void {
+	fileContentCache.delete(sessionId);
+}
+
+export function clearFileCacheEntry(sessionId: string, filePath: string): void {
+	const cache = getFileCache(sessionId);
+	cache.delete(filePath);
+}

package/src/core/src/tools/builtin/finish.ts

@@ -0,0 +1,11 @@
+import { z } from 'zod';
+import { tool } from 'ai';
+import DESCRIPTION from './finish.txt' with { type: 'text' };
+
+export const finishTool = tool({
+	description: DESCRIPTION,
+	inputSchema: z.object({}),
+	async execute() {
+		return { done: true } as const;
+	},
+});

package/src/core/src/tools/builtin/finish.txt

@@ -0,0 +1,5 @@
+- Signal that the task is complete
+- Agent should stream the summary directly as assistant message not using the finish tool
+
+Usage tips:
+- Ensure all necessary outputs are already saved/emitted before finishing

package/src/core/src/tools/builtin/fs/cd.ts

@@ -0,0 +1,19 @@
+import { tool, type Tool } from 'ai';
+import { z } from 'zod';
+import DESCRIPTION from './cd.txt' with { type: 'text' };
+
+// description imported above
+
+export function buildCdTool(): { name: string; tool: Tool } {
+	const cd = tool({
+		description: DESCRIPTION,
+		inputSchema: z.object({
+			path: z.string().describe('Relative directory path'),
+		}),
+		async execute({ path }: { path: string }) {
+			// Actual cwd update is handled in the adapter; this is a placeholder schema
+			return { cwd: path };
+		},
+	});
+	return { name: 'cd', tool: cd };
+}

package/src/core/src/tools/builtin/fs/cd.txt

@@ -0,0 +1,5 @@
+- Change the current working directory (relative to the project root)
+- The runner enforces boundaries; this tool only requests a new cwd
+
+Usage tip:
+- Use PWD to verify the current directory

package/src/core/src/tools/builtin/fs/index.ts

@@ -0,0 +1,20 @@
+import type { Tool } from 'ai';
+import { buildReadTool } from './read.ts';
+import { buildWriteTool } from './write.ts';
+import { buildLsTool } from './ls.ts';
+import { buildTreeTool } from './tree.ts';
+import { buildPwdTool } from './pwd.ts';
+import { buildCdTool } from './cd.ts';
+
+export function buildFsTools(
+	projectRoot: string,
+): Array<{ name: string; tool: Tool }> {
+	const out: Array<{ name: string; tool: Tool }> = [];
+	out.push(buildReadTool(projectRoot));
+	out.push(buildWriteTool(projectRoot));
+	out.push(buildLsTool(projectRoot));
+	out.push(buildTreeTool(projectRoot));
+	out.push(buildPwdTool());
+	out.push(buildCdTool());
+	return out;
+}