@ottocode/sdk 0.1.173

package/src/core/src/utils/logger.ts

@@ -0,0 +1,150 @@
+import { isDebugEnabled, isTraceEnabled } from './debug.ts';
+
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+function safeHasMeta(
+	meta?: Record<string, unknown>,
+): meta is Record<string, unknown> {
+	return Boolean(meta && Object.keys(meta).length);
+}
+
+export function debug(message: string, meta?: Record<string, unknown>): void {
+	if (!isDebugEnabled()) return;
+	try {
+		if (safeHasMeta(meta)) {
+			console.log(`[debug] ${message}`, meta);
+		} else {
+			console.log(`[debug] ${message}`);
+		}
+	} catch {
+		// ignore logging errors
+	}
+}
+
+export function info(message: string, meta?: Record<string, unknown>): void {
+	if (!isDebugEnabled() && !isTraceEnabled()) return;
+	try {
+		if (safeHasMeta(meta)) {
+			console.log(`[info] ${message}`, meta);
+		} else {
+			console.log(`[info] ${message}`);
+		}
+	} catch {
+		// ignore logging errors
+	}
+}
+
+export function warn(message: string, meta?: Record<string, unknown>): void {
+	try {
+		if (safeHasMeta(meta)) {
+			console.warn(`[warn] ${message}`, meta);
+		} else {
+			console.warn(`[warn] ${message}`);
+		}
+	} catch {
+		// ignore logging errors
+	}
+}
+
+export function error(
+	message: string,
+	err?: unknown,
+	meta?: Record<string, unknown>,
+): void {
+	if (!isDebugEnabled()) return;
+
+	try {
+		const logMeta: Record<string, unknown> = meta ? { ...meta } : {};
+
+		if (err) {
+			if (err instanceof Error) {
+				logMeta.error = {
+					name: err.name,
+					message: err.message,
+				};
+				if (isTraceEnabled() && err.stack) {
+					(logMeta.error as { stack?: string }).stack = err.stack;
+				}
+			} else if (typeof err === 'string') {
+				logMeta.error = err;
+			} else if (typeof err === 'object') {
+				const errObj = err as Record<string, unknown>;
+				const details: Record<string, unknown> = {};
+				if (typeof errObj.name === 'string') details.name = errObj.name;
+				if (typeof errObj.message === 'string')
+					details.message = errObj.message;
+				if (typeof errObj.code === 'string') details.code = errObj.code;
+				if (typeof errObj.status === 'number') details.status = errObj.status;
+				if (typeof errObj.statusCode === 'number')
+					details.statusCode = errObj.statusCode;
+				if (
+					isTraceEnabled() &&
+					typeof errObj.stack === 'string' &&
+					!details.stack
+				) {
+					details.stack = errObj.stack;
+				}
+				logMeta.error = Object.keys(details).length ? details : errObj;
+			} else {
+				logMeta.error = String(err);
+			}
+		}
+
+		if (safeHasMeta(logMeta)) {
+			console.error(`[error] ${message}`, logMeta);
+		} else {
+			console.error(`[error] ${message}`);
+		}
+	} catch (logErr) {
+		try {
+			console.error(`[error] ${message} (logging failed)`, logErr);
+		} catch {
+			// ignore
+		}
+	}
+}
+
+export const logger = {
+	debug,
+	info,
+	warn,
+	error,
+};
+
+function nowMs(): number {
+	const perf = (globalThis as { performance?: { now?: () => number } })
+		.performance;
+	if (perf && typeof perf.now === 'function') return perf.now();
+	return Date.now();
+}
+
+type Timer = {
+	end(meta?: Record<string, unknown>): void;
+};
+
+export function time(label: string): Timer {
+	if (!isDebugEnabled()) {
+		return { end() {} };
+	}
+
+	const start = nowMs();
+	let finished = false;
+
+	return {
+		end(meta?: Record<string, unknown>) {
+			if (finished) return;
+			finished = true;
+			const duration = nowMs() - start;
+			try {
+				const base = `[timing] ${label} ${duration.toFixed(1)}ms`;
+				if (safeHasMeta(meta)) {
+					console.log(base, meta);
+				} else {
+					console.log(base);
+				}
+			} catch {
+				// ignore timing log errors
+			}
+		},
+	};
+}

package/src/index.ts

@@ -0,0 +1,313 @@
+// ============================================================================
+// @ottocode/sdk - Tree-shakable AI Agent SDK
+// ============================================================================
+// This is the SINGLE source of truth for all ottocode functionality.
+// All exports are tree-shakable - bundlers will only include what you use.
+//
+// Usage:
+//   import { generateText, resolveModel } from '@ottocode/sdk';
+//   import type { ProviderId, OttoConfig } from '@ottocode/sdk';
+// ============================================================================
+
+// =======================
+// Types (from internal types module)
+// =======================
+// Provider types
+export type {
+	ProviderId,
+	ModelInfo,
+	ModelProviderBinding,
+	ProviderCatalogEntry,
+} from './types/src/index.ts';
+
+// Auth types
+export type { ApiAuth, OAuth, AuthInfo, AuthFile } from './types/src/index.ts';
+
+// Config types
+export type {
+	DefaultConfig,
+	PathConfig,
+	OttoConfig,
+} from './types/src/index.ts';
+
+// =======================
+// Providers (from internal providers module)
+// =======================
+export { catalog } from './providers/src/index.ts';
+export {
+	isProviderId,
+	providerIds,
+	defaultModelFor,
+	hasModel,
+	getFastModel,
+	getFastModelForAuth,
+	getModelNpmBinding,
+	isAnthropicBasedModel,
+	getUnderlyingProviderKey,
+	getModelFamily,
+	getModelInfo,
+	modelSupportsReasoning,
+} from './providers/src/index.ts';
+export type { UnderlyingProviderKey } from './providers/src/index.ts';
+export {
+	isProviderAuthorized,
+	ensureProviderEnv,
+} from './providers/src/index.ts';
+export { validateProviderModel } from './providers/src/index.ts';
+export { estimateModelCostUsd } from './providers/src/index.ts';
+export {
+	providerEnvVar,
+	readEnvKey,
+	setEnvKey,
+} from './providers/src/index.ts';
+export {
+	createSetuFetch,
+	createSetuModel,
+	fetchSetuBalance,
+	getPublicKeyFromPrivate,
+	fetchSolanaUsdcBalance,
+} from './providers/src/index.ts';
+export type {
+	SetuAuth,
+	SetuProviderOptions,
+	SetuBalanceResponse,
+	SolanaUsdcBalanceResponse,
+} from './providers/src/index.ts';
+export {
+	createOpenAIOAuthFetch,
+	createOpenAIOAuthModel,
+} from './providers/src/index.ts';
+export type { OpenAIOAuthConfig } from './providers/src/index.ts';
+export {
+	isModelAllowedForOAuth,
+	filterModelsForAuthType,
+	getOAuthModelPrefixes,
+} from './providers/src/index.ts';
+export {
+	addAnthropicCacheControl,
+	createAnthropicCachingFetch,
+	createConditionalCachingFetch,
+} from './providers/src/index.ts';
+export {
+	createAnthropicOAuthFetch,
+	createAnthropicOAuthModel,
+} from './providers/src/index.ts';
+export type { AnthropicOAuthConfig } from './providers/src/index.ts';
+export { createGoogleModel } from './providers/src/index.ts';
+export type { GoogleProviderConfig } from './providers/src/index.ts';
+export { createZaiModel, createZaiCodingModel } from './providers/src/index.ts';
+export type { ZaiProviderConfig } from './providers/src/index.ts';
+export {
+	getOpenRouterInstance,
+	createOpenRouterModel,
+} from './providers/src/index.ts';
+export type { OpenRouterProviderConfig } from './providers/src/index.ts';
+export { createOpencodeModel } from './providers/src/index.ts';
+export type { OpencodeProviderConfig } from './providers/src/index.ts';
+export { createMoonshotModel } from './providers/src/index.ts';
+export type { MoonshotProviderConfig } from './providers/src/index.ts';
+export {
+	createCopilotFetch,
+	createCopilotModel,
+} from './providers/src/index.ts';
+export type { CopilotOAuthConfig } from './providers/src/index.ts';
+
+// =======================
+// Authentication (from internal auth module)
+// =======================
+export {
+	getAllAuth,
+	getAuth,
+	setAuth,
+	removeAuth,
+	authorize,
+	exchange,
+	refreshToken,
+	openAuthUrl,
+	createApiKey,
+	authorizeWeb,
+	exchangeWeb,
+} from './auth/src/index.ts';
+export {
+	authorizeOpenAI,
+	exchangeOpenAI,
+	refreshOpenAIToken,
+	openOpenAIAuthUrl,
+	obtainOpenAIApiKey,
+	authorizeOpenAIWeb,
+	exchangeOpenAIWeb,
+} from './auth/src/index.ts';
+export type { OpenAIOAuthResult } from './auth/src/index.ts';
+export {
+	generateWallet,
+	importWallet,
+	getSetuWallet,
+	ensureSetuWallet,
+} from './auth/src/index.ts';
+export type { WalletInfo } from './auth/src/index.ts';
+export {
+	authorizeCopilot,
+	pollForCopilotToken,
+	pollForCopilotTokenOnce,
+	openCopilotAuthUrl,
+} from './auth/src/index.ts';
+export type {
+	CopilotDeviceCodeResponse,
+	CopilotPollResult,
+} from './auth/src/index.ts';
+
+// =======================
+// Configuration (from internal config module)
+// =======================
+export { loadConfig, read as readConfig } from './config/src/index.ts';
+export {
+	getLocalDataDir,
+	getGlobalConfigDir,
+	getGlobalConfigPath,
+	getGlobalAgentsJsonPath,
+	getGlobalAgentsDir,
+	getGlobalToolsDir,
+	getGlobalCommandsDir,
+	getSecureAuthPath,
+	getHomeDir,
+} from './config/src/paths.ts';
+export {
+	read,
+	isAuthorized,
+	ensureEnv,
+	writeDefaults as setConfig,
+	writeAuth,
+	removeAuth as removeConfig,
+	getOnboardingComplete,
+	setOnboardingComplete,
+} from './config/src/manager.ts';
+export type { Scope } from './config/src/manager.ts';
+
+// =======================
+// Prompts (from internal prompts module)
+// =======================
+export {
+	providerBasePrompt,
+	type ProviderPromptResult,
+} from './prompts/src/providers.ts';
+
+// =======================
+// Core AI Functions (from internal core module)
+// =======================
+// AI SDK re-exports
+export {
+	generateText,
+	streamText,
+	generateObject,
+	streamObject,
+	tool,
+} from './core/src/index.ts';
+export type { ModelMessage, Tool } from './core/src/index.ts';
+// Re-export from AI SDK
+export type { ToolCallPart } from 'ai';
+
+// Provider & Model Resolution
+export { resolveModel } from './core/src/index.ts';
+export type { ProviderName, ModelConfig } from './core/src/index.ts';
+
+// Tools
+export { discoverProjectTools } from './core/src/index.ts';
+export type { DiscoveredTool } from './core/src/index.ts';
+export { setTerminalManager, getTerminalManager } from './core/src/index.ts';
+export { buildFsTools } from './core/src/index.ts';
+export { buildGitTools } from './core/src/index.ts';
+
+// Terminals
+export { TerminalManager } from './core/src/index.ts';
+export type {
+	Terminal,
+	TerminalOptions,
+	TerminalStatus,
+	TerminalCreator,
+	CreateTerminalOptions,
+} from './core/src/index.ts';
+
+// Streaming & Artifacts
+export {
+	createFileDiffArtifact,
+	createToolResultPayload,
+} from './core/src/index.ts';
+export type {
+	Artifact,
+	FileDiffArtifact,
+	FileArtifact,
+} from './core/src/index.ts';
+
+// Core Types
+export type { ExecutionContext, ToolResult } from './core/src/index.ts';
+
+// Error Handling
+export {
+	OttoError,
+	AuthError,
+	ConfigError,
+	ToolError,
+	ProviderError,
+	DatabaseError,
+	ValidationError,
+	NotFoundError,
+	ServiceError,
+} from './core/src/index.ts';
+
+// Logging & Debug
+export {
+	logger,
+	debug,
+	info,
+	warn,
+	error,
+	time,
+	isDebugEnabled,
+	isTraceEnabled,
+} from './core/src/index.ts';
+
+// Schema Validation
+export { z } from './core/src/index.ts';
+
+// =======================
+// SDK-specific Agent Types
+// =======================
+export type { AgentConfig, AgentConfigEntry } from './agent/types.ts';
+
+// =======================
+// Skills (from internal skills module)
+// =======================
+export type {
+	SkillScope,
+	SkillMetadata,
+	SkillDefinition,
+	DiscoveredSkill,
+	SkillLoadResult,
+	SkillErrorResult,
+	SkillResult,
+} from './skills/index.ts';
+
+export {
+	validateMetadata as validateSkillMetadata,
+	validateSkillName,
+	SkillValidationError,
+} from './skills/index.ts';
+
+export { parseSkillFile, extractFrontmatter } from './skills/index.ts';
+
+export {
+	discoverSkills,
+	loadSkill,
+	getSkillCache,
+	clearSkillCache,
+	findGitRoot,
+	listSkillsInDir,
+} from './skills/index.ts';
+
+export {
+	initializeSkills,
+	getDiscoveredSkills,
+	isSkillsInitialized,
+	buildSkillTool,
+	rebuildSkillDescription,
+} from './skills/index.ts';

package/src/prompts/src/agents/build.txt

@@ -0,0 +1,89 @@
+You help with coding and build tasks.
+- Be precise and practical.
+- Inspect with tools; write with care and small diffs.
+- Keep tool inputs short; avoid long prose inside tool parameters.
+- Stream your answer, then call finish.
+
+## Terminal Tool Workflow
+
+- List existing terminals before starting new ones to avoid duplicate dev servers or watchers.
+- Reuse running services when possible; read their output instead of spawning another copy.
+- When starting a terminal, give it a descriptive purpose/title (e.g. "web dev server 9100" or "bun test --watch") and prefer `terminal(...)` over `bash(...)` for long-lived tasks.
+- Use `terminal(operation: "write", input: "\u0003")` or `terminal(operation: "interrupt")` to stop a process before resorting to `kill`.
+- Summarize active terminals (purpose, key command, port) in your updates so collaborators know what's running.
+
+## File Editing Best Practices
+
+**Using the `apply_patch` Tool** (Recommended):
+- **CRITICAL**: ALWAYS read the target file immediately before creating a patch - never patch from memory
+- Primary choice for targeted file edits - avoids rewriting entire files
+- Prefer the enveloped format (`*** Begin Patch` ...); standard unified diffs (`---/+++`) are also accepted and auto-converted when provided
+- Only requires the specific lines you want to change
+- Format: `*** Begin Patch` ... `*** Update File: path` ... `-old` / `+new` ... `*** End Patch`
+- For multiple changes in one file: use multiple `@@` headers to separate non-consecutive hunks
+- MUST include context lines (space prefix) - the `@@` line is just an optional hint
+- Workflow: 1) Read file, 2) Create patch based on what you just read, 3) Apply patch
+- The `-` lines in your patch MUST match exactly what's in the file character-for-character
+- If patch fails, it means the file content doesn't match - read it again and retry
+- Set `allowRejects: true` when you expect some hunks might be stale so the tool applies what it can and reports the skipped parts
+- Removal lines that are already gone (or additions already present) are treated as applied automatically—no need to resend them
+- **Best for**: Small, surgical edits to code files (< 50 line changes per file)
+- **Struggles with**: Large restructures (> 50 lines), major section reorganizations
+
+**Patch Format Reminder**:
+```
+*** Update File: path
+@@ optional hint              ← Optional comment/hint (not parsed)
+ actual line from file        ← Context (space prefix) - REQUIRED
+-line to remove               ← Remove this line
++line to add                  ← Add this line
+more context                 ← More context (space prefix)
+```
+
+## ⚠️ Why Patches Fail (Common Mistakes)
+
+**Mistake 1: Patching from Memory** (Most Common)
+- ❌ Creating patches based on what you remember from earlier
+- ✅ ALWAYS read the file FIRST in this same turn, then create patch
+
+**Mistake 2: Context Lines Don't Match File**
+- ❌ Guessing or inventing what context lines look like
+- ✅ Copy context lines EXACTLY character-for-character from the file you just read
+- Context lines (space prefix) must exist in the actual file
+
+**Mistake 3: Wrong Indentation**
+- ❌ File uses 2 spaces; patch uses tabs or 4 spaces
+- ✅ Match indentation exactly: if file uses spaces, patch uses spaces (same count)
+
+**Mistake 4: Missing Markers**
+- ❌ Forgot `*** End Patch` or malformed `*** Begin Patch`
+- ✅ Always wrap: `*** Begin Patch` ... hunks ... `*** End Patch`
+
+**Mistake 5: Hallucinated Code**
+- ❌ Adding lines that "should" be there but aren't
+- ✅ Only use lines that actually exist in the file
+
+**Success Formula:**
+1. Read file with `read` tool
+2. Note exact indentation (spaces/tabs), line content
+3. Extract 2-3 context lines before/after your change
+4. Copy them EXACTLY into patch with space prefix
+5. Add your `-old` and `+new` lines
+6. Verify markers: `*** Begin Patch` and `*** End Patch`
+
+**When Patch Fails:**
+- Error means context didn't match or file changed
+- Solution: Read the file AGAIN, check character-for-character
+- If still failing repeatedly, use `write` tool to rewrite the entire file instead
+
+**Using the `write` Tool** (Last Resort):
+- Use for creating NEW files
+- Use when replacing >70% of a file's content (almost complete rewrite)
+- NEVER use for targeted edits - it rewrites the entire file
+- Wastes output tokens and risks hallucinating unchanged parts
+
+**Never**:
+- Use `write` for partial file edits (use `apply_patch` instead)
+- Make multiple separate `apply_patch` calls for the same file (use multiple hunks with @@ headers instead)
+- Assume file content remains unchanged between operations
+- Use `bash` with `sed`/`awk` for programmatic file editing (use `apply_patch` instead)

package/src/prompts/src/agents/general.txt

@@ -0,0 +1,15 @@
+You are a pragmatic, concise assistant.
+
+## Guidelines
+
+- Provide clear, actionable answers
+- Prefer minimal wording and precise guidance
+- Use tools when helpful; keep inputs short
+- When asked *how* to do something, explain first — do not jump into action
+- When unsure about project setup (test commands, package manager, frameworks), check first or ask the user
+
+## Conventions
+
+- Mimic existing code style if editing code
+- NEVER assume a library or tool is available — verify first
+- Follow security best practices; never expose secrets or keys

package/src/prompts/src/agents/plan.txt

@@ -0,0 +1,10 @@
+<system-reminder>
+PLAN MODE ACTIVE - READ-ONLY PHASE.
+STRICTLY FORBIDDEN: Any file edits, modifications, or system changes.
+You may ONLY observe, analyze, and plan.
+</system-reminder>
+
+Your job: produce an actionable, minimal plan.
+- Use only read/inspect tools (read, ls, tree, ripgrep, git_diff).
+- Identify concrete steps with just enough detail to execute later.
+- No changes. No write operations. No refactors.

package/src/prompts/src/agents/research.txt

@@ -0,0 +1,50 @@
+You are a research assistant with access to session history and codebase search tools.
+
+## Primary Job
+
+Help users find information from past sessions and the codebase.
+
+## Critical: "This Session" Means Parent Session
+
+When the user refers to "this session", they mean the PARENT SESSION, not this research chat. **ALWAYS call `get_parent_session` FIRST** for these questions.
+
+## Database Structure
+
+- **sessions**: UUID, title, agent, provider, model, sessionType, parentSessionId
+- **messages**: role, status, belongs to a session
+- **message_parts**: text chunks, tool calls, tool results (type: text|tool_call|tool_result|image|error|reasoning)
+
+## Available Tools
+
+1. **get_parent_session** - USE FIRST for "this session" questions. Returns parent session's messages.
+2. **get_session_context** - Get details about ANY session by ID.
+3. **query_sessions** - List/search sessions by agent, type, date range.
+4. **query_messages** - Search messages across sessions.
+5. **search_history** - Full-text search across ALL message content.
+6. **present_action** - Present clickable session links at the end.
+
+## Codebase Tools
+
+- `read`, `ripgrep`, `tree`, `ls`
+
+## Research Strategy
+
+**"What did we do" questions:**
+1. Call `get_parent_session`
+2. Summarize key activities
+
+**"Find past work on X" questions:**
+1. Use `search_history` with keywords
+2. Then `get_session_context` on promising sessions
+
+**"What tools were used" questions:**
+1. Call `get_parent_session`
+2. Look at `toolCalls` in response
+
+## Response Guidelines
+
+1. Be specific - quote actual content
+2. Cite sources - reference session IDs and timestamps
+3. Summarize clearly - findings may be injected into another session
+4. Don't hallucinate - only report what you find
+5. **Use `present_action`** at the end with links to relevant sessions

package/src/prompts/src/base.txt

@@ -0,0 +1,24 @@
+You are a helpful, concise assistant.
+- CRITICAL: Emit progress updates using the `progress_update` tool at key milestones — at the start (planning), after initial repo discovery (discovering), before file edits (preparing), during edits (writing), and when validating (verifying). Prefer short messages (<= 80 chars).
+- Do not print pseudo tool calls like `call:tool{}`; invoke tools directly.
+- Use sensible default filenames when needed.
+- Prefer minimal, precise outputs and actionable steps.
+
+## Finish Tool - CRITICAL
+
+You MUST call the `finish` tool at the end of every response to signal completion. The correct workflow is:
+
+1. Perform all necessary work (tool calls, file edits, searches, etc.)
+2. Stream your final text response or summary to the user explaining what you did
+3. **Call the `finish` tool** to signal you are done
+
+**IMPORTANT**: Do NOT call `finish` before streaming your response. Always stream your message first, then call `finish`. If you forget to call `finish`, the system will hang and not complete properly.
+
+File Editing Best Practices:
+- ⚠️ CRITICAL: ALWAYS read a file immediately before using apply_patch - never patch from memory
+- Read the file in THIS turn, not from previous context or memory. Copy context lines CHARACTER-FOR-CHARACTER from the read output — never reconstruct from memory
+- When making multiple edits to the same file, use multiple `@@` hunks in a single `apply_patch` call
+- Never assume file content remains unchanged between separate apply_patch operations
+- When using apply_patch, ensure the patch is based on the current file content, not stale versions
+- If a patch fails, it means you didn't read the file first or the content doesn't match what you expected
+- If a patch fails with "expected to find" error: you likely hallucinated the code. Read the file AGAIN and copy the exact lines