@schlenkr/ragents 0.1.0

package/packages/agent/src/core/runtime-credentials.ts

@@ -0,0 +1,48 @@
+import type { Credential, CredentialInfo, CredentialStore } from "@aicontainer/ai";
+
+/** Async credential store overlay for non-persistent runtime API keys. */
+export class RuntimeCredentials implements CredentialStore {
+	private readonly store: CredentialStore;
+	private readonly overrides = new Map<string, string>();
+
+	constructor(store: CredentialStore) {
+		this.store = store;
+	}
+
+	setRuntimeApiKey(providerId: string, apiKey: string): void {
+		this.overrides.set(providerId, apiKey);
+	}
+
+	removeRuntimeApiKey(providerId: string): void {
+		this.overrides.delete(providerId);
+	}
+
+	hasRuntimeApiKey(providerId: string): boolean {
+		return this.overrides.has(providerId);
+	}
+
+	async read(providerId: string): Promise<Credential | undefined> {
+		const override = this.overrides.get(providerId);
+		return override ? { type: "api_key", key: override } : this.store.read(providerId);
+	}
+
+	async list(): Promise<readonly CredentialInfo[]> {
+		const entries = new Map((await this.store.list()).map((entry) => [entry.providerId, entry]));
+		for (const providerId of this.overrides.keys()) {
+			entries.set(providerId, { providerId, type: "api_key" });
+		}
+		return [...entries.values()];
+	}
+
+	modify(
+		providerId: string,
+		fn: (current: Credential | undefined) => Promise<Credential | undefined>,
+	): Promise<Credential | undefined> {
+		return this.store.modify(providerId, fn);
+	}
+
+	async delete(providerId: string): Promise<void> {
+		this.overrides.delete(providerId);
+		await this.store.delete(providerId);
+	}
+}

package/packages/agent/src/core/sdk.ts

@@ -0,0 +1,358 @@
+import { join } from "node:path";
+import { Agent, type AgentMessage, type ThinkingLevel } from "@aicontainer/agent-core";
+import { clampThinkingLevel, type Message, type Model } from "@aicontainer/ai";
+import { getAgentDir } from "../config.ts";
+import { resolvePath } from "../utils/paths.ts";
+import { AgentSession } from "./agent-session.ts";
+import { formatNoModelsAvailableMessage } from "./auth-guidance.ts";
+import { DEFAULT_THINKING_LEVEL } from "./defaults.ts";
+import type { ExtensionRunner, LoadExtensionsResult, SessionStartEvent, ToolDefinition } from "./extensions/index.ts";
+import { convertToLlm } from "./messages.ts";
+import { findInitialModel } from "./model-resolver.ts";
+import { ModelRuntime } from "./model-runtime.ts";
+import type { ResourceLoader } from "./resource-loader.ts";
+import { DefaultResourceLoader } from "./resource-loader.ts";
+import { getDefaultSessionDir, SessionManager } from "./session-manager.ts";
+import { SettingsManager } from "./settings-manager.ts";
+import { time } from "./timings.ts";
+import {
+	createBashTool,
+	createCodingTools,
+	createEditTool,
+	createReadTool,
+	createWriteTool,
+	type ToolName,
+	withFileMutationQueue,
+} from "./tools/index.ts";
+
+export interface CreateAgentSessionOptions {
+	/** Working directory for project-local discovery. Default: process.cwd() */
+	cwd?: string;
+	/** Global config directory. Default: ~/.agent */
+	agentDir?: string;
+
+	/** Canonical model/auth runtime. Defaults to a runtime using agentDir/auth.json and models.json. */
+	modelRuntime?: ModelRuntime;
+
+	/** Model to use. Default: from settings, else first available */
+	model?: Model<any>;
+	/** Thinking level. Default: from settings, else 'medium' (clamped to model capabilities) */
+	thinkingLevel?: ThinkingLevel;
+	/** Models available for cycling (Ctrl+P in interactive mode) */
+	scopedModels?: Array<{ model: Model<any>; thinkingLevel?: ThinkingLevel }>;
+
+	/**
+	 * Optional default tool suppression mode when no explicit allowlist is provided.
+	 *
+	 * - "all": start with no tools enabled
+	 * - "builtin": disable the default built-in tools (read, bash, edit, write)
+	 *   but keep extension/custom tools enabled
+	 */
+	noTools?: "all" | "builtin";
+	/**
+	 * Optional allowlist of tool names.
+	 *
+	 * When omitted, the agent enables the default built-in tools (read, bash, edit, write)
+	 * and leaves extension/custom tools enabled unless `noTools` changes that default.
+	 * When provided, only the listed tool names are enabled.
+	 */
+	tools?: string[];
+	/** Optional denylist of tool names to disable. Applies after `tools` when both are provided. */
+	excludeTools?: string[];
+	/** Custom tools to register (in addition to built-in tools). */
+	customTools?: ToolDefinition[];
+
+	/** Resource loader. When omitted, DefaultResourceLoader is used. */
+	resourceLoader?: ResourceLoader;
+
+	/** Session manager. Default: SessionManager.create(cwd) */
+	sessionManager?: SessionManager;
+
+	/** Settings manager. Default: SettingsManager.create(cwd, agentDir) */
+	settingsManager?: SettingsManager;
+	/** Session start event metadata for extension runtime startup. */
+	sessionStartEvent?: SessionStartEvent;
+}
+
+/** Result from createAgentSession */
+export interface CreateAgentSessionResult {
+	/** The created session */
+	session: AgentSession;
+	/** Extensions result (for UI context setup in interactive mode) */
+	extensionsResult: LoadExtensionsResult;
+	/** Warning if session was restored with a different model than saved */
+	modelFallbackMessage?: string;
+}
+
+// Re-exports
+
+export * from "./agent-session-runtime.ts";
+export type {
+	ExtensionAPI,
+	ExtensionCommandContext,
+	ExtensionContext,
+	ExtensionFactory,
+	InlineExtension,
+	SlashCommandInfo,
+	SlashCommandSource,
+	ToolDefinition,
+} from "./extensions/index.ts";
+export type { PromptTemplate } from "./prompt-templates.ts";
+export type { Skill } from "./skills.ts";
+export type { Tool } from "./tools/index.ts";
+
+export {
+	withFileMutationQueue,
+	// Tool factories (for custom cwd)
+	createCodingTools,
+	createReadTool,
+	createBashTool,
+	createEditTool,
+	createWriteTool,
+};
+
+// Helper Functions
+
+function getDefaultAgentDir(): string {
+	return getAgentDir();
+}
+
+/**
+ * Create an AgentSession with the specified options.
+ *
+ * @example
+ * ```typescript
+ * // Minimal - uses defaults
+ * const { session } = await createAgentSession();
+ *
+ * // With explicit model
+ * import { getModel } from '@aicontainer/ai';
+ * const { session } = await createAgentSession({
+ *   model: getModel('anthropic', 'claude-opus-4-5'),
+ *   thinkingLevel: 'high',
+ * });
+ *
+ * // Continue previous session
+ * const { session, modelFallbackMessage } = await createAgentSession({
+ *   continueSession: true,
+ * });
+ *
+ * // Full control
+ * const loader = new DefaultResourceLoader({
+ *   cwd: process.cwd(),
+ *   agentDir: getAgentDir(),
+ *   settingsManager: SettingsManager.create(),
+ * });
+ * await loader.reload();
+ * const { session } = await createAgentSession({
+ *   model: myModel,
+ *   tools: ["read", "bash"],
+ *   resourceLoader: loader,
+ *   sessionManager: SessionManager.inMemory(),
+ * });
+ * ```
+ */
+export async function createAgentSession(options: CreateAgentSessionOptions = {}): Promise<CreateAgentSessionResult> {
+	const cwd = resolvePath(options.cwd ?? options.sessionManager?.getCwd() ?? process.cwd());
+	const agentDir = options.agentDir ? resolvePath(options.agentDir) : getDefaultAgentDir();
+	let resourceLoader = options.resourceLoader;
+
+	const authPath = options.agentDir ? join(agentDir, "auth.json") : undefined;
+	const modelsPath = options.agentDir ? join(agentDir, "models.json") : undefined;
+	const modelRuntime = options.modelRuntime ?? (await ModelRuntime.create({ authPath, modelsPath }));
+
+	const settingsManager = options.settingsManager ?? SettingsManager.create(cwd, agentDir);
+	const sessionManager = options.sessionManager ?? SessionManager.create(cwd, getDefaultSessionDir(cwd, agentDir));
+
+	if (!resourceLoader) {
+		resourceLoader = new DefaultResourceLoader({ cwd, agentDir, settingsManager });
+		await resourceLoader.reload();
+		time("resourceLoader.reload");
+	}
+
+	// Check if session has existing data to restore
+	const existingSession = sessionManager.buildSessionContext();
+	const hasExistingSession = existingSession.messages.length > 0;
+	const hasThinkingEntry = sessionManager.getBranch().some((entry) => entry.type === "thinking_level_change");
+
+	let model = options.model;
+	let modelFallbackMessage: string | undefined;
+
+	// If session has data, try to restore model from it
+	if (!model && hasExistingSession && existingSession.model) {
+		const restoredModel = modelRuntime.getModel(existingSession.model.provider, existingSession.model.modelId);
+		if (restoredModel && modelRuntime.hasConfiguredAuth(restoredModel.provider)) {
+			model = restoredModel;
+		}
+		if (!model) {
+			modelFallbackMessage = `Could not restore model ${existingSession.model.provider}/${existingSession.model.modelId}`;
+		}
+	}
+
+	// If still no model, use findInitialModel (checks settings default, then provider defaults)
+	if (!model) {
+		const result = await findInitialModel({
+			scopedModels: [],
+			isContinuing: hasExistingSession,
+			defaultProvider: settingsManager.getDefaultProvider(),
+			defaultModelId: settingsManager.getDefaultModel(),
+			defaultThinkingLevel: settingsManager.getDefaultThinkingLevel(),
+			modelRuntime,
+		});
+		model = result.model;
+		if (!model) {
+			modelFallbackMessage = formatNoModelsAvailableMessage();
+		} else if (modelFallbackMessage) {
+			modelFallbackMessage += `. Using ${model.provider}/${model.id}`;
+		}
+	}
+
+	let thinkingLevel = options.thinkingLevel;
+
+	// If session has data, restore thinking level from it
+	if (thinkingLevel === undefined && hasExistingSession) {
+		thinkingLevel = hasThinkingEntry
+			? (existingSession.thinkingLevel as ThinkingLevel)
+			: (settingsManager.getDefaultThinkingLevel() ?? DEFAULT_THINKING_LEVEL);
+	}
+
+	// Fall back to settings default
+	if (thinkingLevel === undefined) {
+		thinkingLevel = settingsManager.getDefaultThinkingLevel() ?? DEFAULT_THINKING_LEVEL;
+	}
+
+	// Clamp to model capabilities
+	if (!model) {
+		thinkingLevel = "off";
+	} else {
+		thinkingLevel = clampThinkingLevel(model, thinkingLevel) as ThinkingLevel;
+	}
+
+	const defaultActiveToolNames: ToolName[] = ["read", "bash", "edit", "write"];
+	const allowedToolNames = options.tools ?? (options.noTools === "all" ? [] : undefined);
+	const excludedToolNames = options.excludeTools;
+	const excludedToolNameSet = excludedToolNames ? new Set(excludedToolNames) : undefined;
+	const initialActiveToolNames: string[] = (
+		options.tools ? [...options.tools] : options.noTools ? [] : defaultActiveToolNames
+	).filter((name) => !excludedToolNameSet?.has(name));
+
+	let agent: Agent;
+
+	// Reject image-bearing messages when image reading is disabled.
+	const convertToLlmWithBlockImages = (messages: AgentMessage[]): Message[] => {
+		const converted = convertToLlm(messages);
+		// Check setting dynamically so mid-session changes take effect
+		if (!settingsManager.getBlockImages()) {
+			return converted;
+		}
+		for (const message of converted) {
+			if ((message.role === "user" || message.role === "toolResult") && Array.isArray(message.content)
+				&& message.content.some((part) => part.type === "image")) {
+				throw new Error("Image reading is disabled.");
+			}
+		}
+		return converted;
+	};
+
+	const extensionRunnerRef: { current?: ExtensionRunner } = {};
+
+	agent = new Agent({
+		initialState: {
+			systemPrompt: "",
+			model,
+			thinkingLevel,
+			tools: [],
+		},
+		convertToLlm: convertToLlmWithBlockImages,
+		streamFn: async (model, context, options) => {
+			const providerRetrySettings = settingsManager.getProviderRetrySettings();
+			const httpIdleTimeoutMs = settingsManager.getHttpIdleTimeoutMs();
+			// SDKs treat timeout=0 as 0ms (immediate timeout), not "no timeout".
+			// Use max int32 to effectively disable the timeout.
+			const effectiveTimeoutMs = httpIdleTimeoutMs === 0 ? 2147483647 : httpIdleTimeoutMs;
+			const timeoutMs = options?.timeoutMs ?? providerRetrySettings.timeoutMs ?? effectiveTimeoutMs;
+			const websocketConnectTimeoutMs =
+				options?.websocketConnectTimeoutMs ?? settingsManager.getWebSocketConnectTimeoutMs();
+			const headerRunner = extensionRunnerRef.current;
+			return modelRuntime.streamSimple(model, context, {
+				...options,
+				timeoutMs,
+				websocketConnectTimeoutMs,
+				maxRetries: options?.maxRetries ?? providerRetrySettings.maxRetries,
+				maxRetryDelayMs: options?.maxRetryDelayMs ?? providerRetrySettings.maxRetryDelayMs,
+				transformHeaders: async (requestHeaders) => {
+					const headers = requestHeaders ?? {};
+					return headerRunner?.hasHandlers("before_provider_headers")
+						? headerRunner.emitBeforeProviderHeaders(headers)
+						: headers;
+				},
+			});
+		},
+		onPayload: async (payload, _model) => {
+			const runner = extensionRunnerRef.current;
+			if (!runner?.hasHandlers("before_provider_request")) {
+				return payload;
+			}
+			return runner.emitBeforeProviderRequest(payload);
+		},
+		onResponse: async (response, _model) => {
+			const runner = extensionRunnerRef.current;
+			if (!runner?.hasHandlers("after_provider_response")) {
+				return;
+			}
+			await runner.emit({
+				type: "after_provider_response",
+				status: response.status,
+				headers: response.headers,
+			});
+		},
+		sessionId: sessionManager.getSessionId(),
+		transformContext: async (messages) => {
+			const runner = extensionRunnerRef.current;
+			if (!runner) return messages;
+			return runner.emitContext(messages);
+		},
+		steeringMode: settingsManager.getSteeringMode(),
+		followUpMode: settingsManager.getFollowUpMode(),
+		transport: settingsManager.getTransport(),
+		thinkingBudgets: settingsManager.getThinkingBudgets(),
+		maxRetryDelayMs: settingsManager.getProviderRetrySettings().maxRetryDelayMs,
+	});
+
+	// Restore messages if session has existing data
+	if (hasExistingSession) {
+		agent.state.messages = existingSession.messages;
+		if (!hasThinkingEntry) {
+			sessionManager.appendThinkingLevelChange(thinkingLevel);
+		}
+	} else {
+		// Save initial model and thinking level for new sessions so they can be restored on resume
+		if (model) {
+			sessionManager.appendModelChange(model.provider, model.id);
+		}
+		sessionManager.appendThinkingLevelChange(thinkingLevel);
+	}
+
+	const session = new AgentSession({
+		agent,
+		sessionManager,
+		settingsManager,
+		cwd,
+		scopedModels: options.scopedModels,
+		resourceLoader,
+		customTools: options.customTools,
+		modelRuntime,
+		initialActiveToolNames,
+		allowedToolNames,
+		excludedToolNames,
+		extensionRunnerRef,
+		sessionStartEvent: options.sessionStartEvent,
+	});
+	const extensionsResult = resourceLoader.getExtensions();
+
+	return {
+		session,
+		extensionsResult,
+		modelFallbackMessage,
+	};
+}

package/packages/agent/src/core/session-cwd.ts

@@ -0,0 +1,59 @@
+import { existsSync } from "node:fs";
+
+export interface SessionCwdIssue {
+	sessionFile?: string;
+	sessionCwd: string;
+	fallbackCwd: string;
+}
+
+interface SessionCwdSource {
+	getCwd(): string;
+	getSessionFile(): string | undefined;
+}
+
+export function getMissingSessionCwdIssue(
+	sessionManager: SessionCwdSource,
+	fallbackCwd: string,
+): SessionCwdIssue | undefined {
+	const sessionFile = sessionManager.getSessionFile();
+	if (!sessionFile) {
+		return undefined;
+	}
+
+	const sessionCwd = sessionManager.getCwd();
+	if (!sessionCwd || existsSync(sessionCwd)) {
+		return undefined;
+	}
+
+	return {
+		sessionFile,
+		sessionCwd,
+		fallbackCwd,
+	};
+}
+
+export function formatMissingSessionCwdError(issue: SessionCwdIssue): string {
+	const sessionFile = issue.sessionFile ? `\nSession file: ${issue.sessionFile}` : "";
+	return `Stored session working directory does not exist: ${issue.sessionCwd}${sessionFile}\nCurrent working directory: ${issue.fallbackCwd}`;
+}
+
+export function formatMissingSessionCwdPrompt(issue: SessionCwdIssue): string {
+	return `cwd from session file does not exist\n${issue.sessionCwd}\n\ncontinue in current cwd\n${issue.fallbackCwd}`;
+}
+
+export class MissingSessionCwdError extends Error {
+	readonly issue: SessionCwdIssue;
+
+	constructor(issue: SessionCwdIssue) {
+		super(formatMissingSessionCwdError(issue));
+		this.name = "MissingSessionCwdError";
+		this.issue = issue;
+	}
+}
+
+export function assertSessionCwdExists(sessionManager: SessionCwdSource, fallbackCwd: string): void {
+	const issue = getMissingSessionCwdIssue(sessionManager, fallbackCwd);
+	if (issue) {
+		throw new MissingSessionCwdError(issue);
+	}
+}