gsd-pi 2.76.0 → 2.77.0-dev.538325aea

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

@@ -0,0 +1,550 @@
+import { createRequire } from "node:module";
+import { dirname, join, resolve } from "node:path";
+
+/**
+ * Structured error thrown when all credentials for a provider are in a
+ * backoff window.  Carries typed metadata so callers (e.g. the auto-loop)
+ * can make informed retry decisions instead of string-matching the message.
+ */
+export class CredentialCooldownError extends Error {
+	readonly code = "AUTH_COOLDOWN" as const;
+	/** Milliseconds until the earliest credential becomes available, or undefined if unknown. */
+	readonly retryAfterMs: number | undefined;
+
+	constructor(provider: string, retryAfterMs?: number) {
+		super(
+			`All credentials for "${provider}" are in a cooldown window. ` +
+				`Please wait a moment and try again, or switch to a different provider.`,
+		);
+		this.name = "CredentialCooldownError";
+		this.retryAfterMs = retryAfterMs;
+	}
+}
+import { Agent, type AgentMessage, type ThinkingLevel } from "@gsd/pi-agent-core";
+import type { Api, Message, Model } from "@gsd/pi-ai";
+import { getAgentDir } from "@gsd/pi-coding-agent";
+import { AgentSession } from "./agent-session.js";
+import { AuthStorage } from "@gsd/pi-coding-agent";
+import type { ExtensionRunner, LoadExtensionsResult, ToolDefinition } from "@gsd/agent-types";
+import { convertToLlm } from "@gsd/pi-coding-agent";
+import { ModelRegistry } from "@gsd/pi-coding-agent";
+import type { ResourceLoader } from "@gsd/agent-types";
+import { DefaultResourceLoader } from "@gsd/pi-coding-agent";
+import { SessionManager } from "@gsd/pi-coding-agent";
+import { SettingsManager } from "@gsd/pi-coding-agent";
+import {
+	bashTool,
+	codingTools,
+	createBashTool,
+	createCodingTools,
+	createEditTool,
+	createFindTool,
+	createGrepTool,
+	createLsTool,
+	createReadOnlyTools,
+	createReadTool,
+	createWriteTool,
+	editTool,
+	findTool,
+	grepTool,
+	hashlineEditTool,
+	hashlineReadTool,
+	lsTool,
+	readOnlyTools,
+	readTool,
+	writeTool,
+} from "@gsd/pi-coding-agent";
+import type { Tool, ToolName } from "@gsd/agent-types";
+
+const require = createRequire(import.meta.url);
+const DEFAULT_THINKING_LEVEL: ThinkingLevel = "medium";
+
+const allBuiltInTools = {
+	read: readTool,
+	bash: bashTool,
+	edit: editTool,
+	write: writeTool,
+	grep: grepTool,
+	find: findTool,
+	ls: lsTool,
+	hashline_edit: hashlineEditTool,
+	hashline_read: hashlineReadTool,
+} as const;
+
+function getDocsPath(): string {
+	const piEntryPath = require.resolve("@gsd/pi-coding-agent");
+	return resolve(dirname(piEntryPath), "..", "docs");
+}
+
+function time(_label: string): void {
+	if (process.env.PI_TIMING !== "1") return;
+}
+
+async function findInitialModel(options: {
+	scopedModels: Array<{ model: Model<Api>; thinkingLevel?: ThinkingLevel }>;
+	isContinuing: boolean;
+	defaultProvider?: string;
+	defaultModelId?: string;
+	defaultThinkingLevel?: ThinkingLevel;
+	modelRegistry: ModelRegistry;
+}): Promise<{ model: Model<Api> | undefined; thinkingLevel: ThinkingLevel; fallbackMessage: string | undefined }> {
+	const {
+		scopedModels,
+		isContinuing,
+		defaultProvider,
+		defaultModelId,
+		defaultThinkingLevel,
+		modelRegistry,
+	} = options;
+
+	if (scopedModels.length > 0 && !isContinuing) {
+		return {
+			model: scopedModels[0].model,
+			thinkingLevel: scopedModels[0].thinkingLevel ?? defaultThinkingLevel ?? DEFAULT_THINKING_LEVEL,
+			fallbackMessage: undefined,
+		};
+	}
+
+	if (defaultProvider && defaultModelId && modelRegistry.isProviderRequestReady(defaultProvider)) {
+		const found = modelRegistry.find(defaultProvider, defaultModelId);
+		if (found) {
+			return {
+				model: found,
+				thinkingLevel: defaultThinkingLevel ?? DEFAULT_THINKING_LEVEL,
+				fallbackMessage: undefined,
+			};
+		}
+	}
+
+	const availableModels = await modelRegistry.getAvailable();
+	if (availableModels.length > 0) {
+		if (defaultProvider) {
+			const sameProvider = availableModels.find((model) => model.provider === defaultProvider);
+			if (sameProvider) {
+				return { model: sameProvider, thinkingLevel: DEFAULT_THINKING_LEVEL, fallbackMessage: undefined };
+			}
+		}
+		return { model: availableModels[0], thinkingLevel: DEFAULT_THINKING_LEVEL, fallbackMessage: undefined };
+	}
+
+	return { model: undefined, thinkingLevel: DEFAULT_THINKING_LEVEL, fallbackMessage: undefined };
+}
+
+export interface CreateAgentSessionOptions {
+	/** Working directory for project-local discovery. Default: process.cwd() */
+	cwd?: string;
+	/** Global config directory. Default: ~/.pi/agent */
+	agentDir?: string;
+
+	/** Auth storage for credentials. Default: AuthStorage.create(agentDir/auth.json) */
+	authStorage?: AuthStorage;
+	/** Model registry. Default: new ModelRegistry(authStorage, agentDir/models.json) */
+	modelRegistry?: ModelRegistry;
+
+	/** Model to use. Default: from settings, else first available */
+	model?: Model<Api>;
+	/** 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<Api>; thinkingLevel?: ThinkingLevel }>;
+
+	/** Built-in tools to use. Default: codingTools [read, bash, edit, write] */
+	tools?: Tool[];
+	/** 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;
+
+	/** Optional: check if the claude-code CLI provider is ready (installed + authed).
+	 * Passed to RetryHandler for third-party block recovery (#3772). */
+	isClaudeCodeReady?: () => boolean;
+}
+
+/** 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 type {
+	ExtensionAPI,
+	ExtensionCommandContext,
+	ExtensionContext,
+	ExtensionFactory,
+	SlashCommandInfo,
+	SlashCommandSource,
+	ToolDefinition,
+} from "@gsd/agent-types";
+export type { PromptTemplate } from "@gsd/agent-types";
+export type { Skill } from "@gsd/agent-types";
+export type { Tool } from "@gsd/agent-types";
+
+export {
+	// Pre-built tools (use process.cwd())
+	readTool,
+	bashTool,
+	editTool,
+	writeTool,
+	grepTool,
+	findTool,
+	lsTool,
+	codingTools,
+	readOnlyTools,
+	allBuiltInTools,
+	// Tool factories (for custom cwd)
+	createCodingTools,
+	createReadOnlyTools,
+	createReadTool,
+	createBashTool,
+	createEditTool,
+	createWriteTool,
+	createGrepTool,
+	createFindTool,
+	createLsTool,
+};
+
+// 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 '@gsd/pi-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: [readTool, bashTool],
+ *   resourceLoader: loader,
+ *   sessionManager: SessionManager.inMemory(),
+ * });
+ * ```
+ */
+export async function createAgentSession(options: CreateAgentSessionOptions = {}): Promise<CreateAgentSessionResult> {
+	const cwd = options.cwd ?? process.cwd();
+	const agentDir = options.agentDir ?? getDefaultAgentDir();
+	let resourceLoader = options.resourceLoader;
+
+	// Use provided or create AuthStorage and ModelRegistry
+	const authPath = options.agentDir ? join(agentDir, "auth.json") : undefined;
+	const modelsPath = options.agentDir ? join(agentDir, "models.json") : undefined;
+	const authStorage = options.authStorage ?? AuthStorage.create(authPath);
+	const modelRegistry = options.modelRegistry ?? new ModelRegistry(authStorage, modelsPath);
+
+	const settingsManager = options.settingsManager ?? SettingsManager.create(cwd, agentDir);
+	const sessionManager = options.sessionManager ?? SessionManager.create(cwd);
+
+	if (!resourceLoader) {
+		resourceLoader = new DefaultResourceLoader({ cwd, agentDir, settingsManager });
+		await resourceLoader.reload();
+		time("resourceLoader.reload");
+	}
+
+	// Flush provider registrations queued during extension loading so that
+	// extension models (e.g. pi-claude-cli) are visible in the registry before
+	// findInitialModel() runs. bindCore() repeats this flush as a safety net
+	// for any late-arriving registrations.
+	const { runtime: extensionRuntime } = resourceLoader.getExtensions();
+	for (const { name, config } of extensionRuntime.pendingProviderRegistrations) {
+		modelRegistry.registerProvider(name, config);
+	}
+	extensionRuntime.pendingProviderRegistrations = [];
+
+	// 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 = modelRegistry.find(existingSession.model.provider, existingSession.model.modelId);
+		if (restoredModel) {
+			if (modelRegistry.isProviderRequestReady(restoredModel.provider)) {
+				model = restoredModel;
+			}
+		}
+		if (!model) {
+			modelFallbackMessage = `Could not restore model ${existingSession.model.provider}/${existingSession.model.modelId}`;
+		}
+	}
+
+	// Flush extension provider registrations so extension-provided models (e.g. claude-code/*)
+	// are available in the registry before model resolution. Without this, findInitialModel()
+	// cannot find extension models and falls back to built-in providers (#3534).
+	const extensionsForModelResolution = resourceLoader.getExtensions();
+	for (const { name, config } of extensionsForModelResolution.runtime.pendingProviderRegistrations) {
+		modelRegistry.registerProvider(name, config);
+	}
+	// Clear the queue so bindCore() doesn't re-register the same providers.
+	extensionsForModelResolution.runtime.pendingProviderRegistrations = [];
+
+	// 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(),
+			modelRegistry,
+		});
+		model = result.model;
+		if (!model) {
+			modelFallbackMessage = `No models available. Use /login or set an API key environment variable. See ${join(getDocsPath(), "providers.md")}. Then use /model to select a model.`;
+		} 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 || !model.reasoning) {
+		thinkingLevel = "off";
+	}
+
+	// getEditMode() was removed from SettingsManager in 0.67.2; use the standard tool set.
+	const defaultActiveToolNames: ToolName[] = ["read", "bash", "edit", "write"];
+	const initialActiveToolNames: ToolName[] = options.tools
+		? options.tools.map((t) => t.name).filter((n): n is ToolName => n in allBuiltInTools)
+		: defaultActiveToolNames;
+
+	// Create convertToLlm wrapper that filters images if blockImages is enabled (defense-in-depth)
+	const convertToLlmWithBlockImages = (messages: AgentMessage[]): Message[] => {
+		const converted = convertToLlm(messages);
+		// Check setting dynamically so mid-session changes take effect
+		if (!settingsManager.getBlockImages()) {
+			return converted;
+		}
+		// Filter out ImageContent from all messages, replacing with text placeholder
+		return converted.map((msg) => {
+			if (msg.role === "user" || msg.role === "toolResult") {
+				const content = msg.content;
+				if (Array.isArray(content)) {
+					const hasImages = content.some((c) => c.type === "image");
+					if (hasImages) {
+						const filteredContent = content
+							.map((c) =>
+								c.type === "image" ? { type: "text" as const, text: "Image reading is disabled." } : c,
+							)
+							.filter(
+								(c, i, arr) =>
+									// Dedupe consecutive "Image reading is disabled." texts
+									!(
+										c.type === "text" &&
+										c.text === "Image reading is disabled." &&
+										i > 0 &&
+										arr[i - 1].type === "text" &&
+										(arr[i - 1] as { type: "text"; text: string }).text === "Image reading is disabled."
+									),
+							);
+						return { ...msg, content: filteredContent };
+					}
+				}
+			}
+			return msg;
+		});
+	};
+
+	const extensionRunnerRef: { current?: ExtensionRunner } = {};
+
+	const agent = new Agent({
+		initialState: {
+			systemPrompt: "",
+			model,
+			thinkingLevel,
+			tools: [],
+		},
+		convertToLlm: convertToLlmWithBlockImages,
+		onPayload: async (payload, _currentModel) => {
+			const runner = extensionRunnerRef.current;
+			if (!runner?.hasHandlers("before_provider_request")) {
+				return payload;
+			}
+			return runner.emitBeforeProviderRequest(payload);
+		},
+		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.getRetrySettings().maxDelayMs,
+			getApiKey: async (provider): Promise<string> => {
+			// Use the provider argument from the in-flight request;
+			// agent.state.model may already be switched mid-turn.
+				const resolvedProvider: string | undefined = provider || agent.state.model?.provider;
+			if (!resolvedProvider) {
+				throw new Error("No model selected");
+			}
+
+			// GSD extension: cast to access GSD-added methods absent from 0.67.2 AuthStorage.
+			// These methods were present in 0.57.1 and provide cooldown-aware retry behavior.
+			// In 0.67.2 they are removed; optional chaining makes the call a no-op when absent.
+			const gsdAuthStorage = modelRegistry.authStorage as unknown as {
+				getEarliestBackoffExpiry?: (provider: string) => number | undefined;
+				hasLegacyOAuthCredential?: (provider: string) => boolean;
+				areAllCredentialsBackedOff?: (provider: string) => boolean;
+			};
+
+			// Retry key resolution with backoff to handle transient network failures.
+			const maxAttempts = 3;
+			const baseDelayMs = 2000;
+			const maxCooldownWaitMs = 60_000;
+			for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+					const key: string | undefined = await modelRegistry.getApiKeyForProvider(resolvedProvider);
+				if (key) return key;
+
+				if (attempt >= maxAttempts) break;
+
+				const hasAuth = modelRegistry.authStorage.hasAuth(resolvedProvider);
+				const model = agent.state.model;
+				const isOAuth = model && modelRegistry.isUsingOAuth(model);
+				if (!hasAuth && !isOAuth) break;
+
+				// If credentials are in a cooldown window, wait for the earliest to expire.
+				const backoffExpiry = gsdAuthStorage.getEarliestBackoffExpiry?.(resolvedProvider);
+				if (backoffExpiry !== undefined) {
+					const waitMs = backoffExpiry - Date.now() + 500;
+					if (waitMs > 0 && waitMs <= maxCooldownWaitMs) {
+						await new Promise(resolve => setTimeout(resolve, waitMs));
+						continue;
+					}
+					if (waitMs > maxCooldownWaitMs) {
+						break;
+					}
+				}
+
+				await new Promise(resolve => setTimeout(resolve, baseDelayMs * attempt));
+			}
+
+			// All retries exhausted — surface a descriptive error.
+			const hasAuth = modelRegistry.authStorage.hasAuth(resolvedProvider);
+			if (hasAuth) {
+				// Detect stale Anthropic OAuth credentials (removed in v2.74.0, #3952).
+				if (
+					resolvedProvider === "anthropic" &&
+					gsdAuthStorage.hasLegacyOAuthCredential?.(resolvedProvider)
+				) {
+					throw new Error(
+						`Your Anthropic credentials were set up via OAuth, which is no longer supported. ` +
+							`Please re-authenticate: run '/login', select 'Paste an API key' → Anthropic. ` +
+							`Alternatively, switch to the Claude Code CLI provider.`,
+					);
+				}
+				const expiry = gsdAuthStorage.getEarliestBackoffExpiry?.(resolvedProvider);
+				const retryAfterMs = expiry !== undefined ? Math.max(0, expiry - Date.now()) : undefined;
+				throw new CredentialCooldownError(resolvedProvider, retryAfterMs);
+			}
+			const model = agent.state.model;
+			const isOAuth = model && modelRegistry.isUsingOAuth(model);
+			if (isOAuth) {
+				if (gsdAuthStorage.areAllCredentialsBackedOff?.(resolvedProvider)) {
+					const expiry = gsdAuthStorage.getEarliestBackoffExpiry?.(resolvedProvider);
+					const retryAfterMs = expiry !== undefined ? Math.max(0, expiry - Date.now()) : undefined;
+					throw new CredentialCooldownError(resolvedProvider, retryAfterMs);
+				}
+				throw new Error(
+					`Authentication failed for "${resolvedProvider}". ` +
+						`Credentials may have expired or network is unavailable. ` +
+						`Run '/login ${resolvedProvider}' to re-authenticate.`,
+				);
+			}
+			throw new Error(
+				`No API key found for "${resolvedProvider}". ` +
+					`Set an API key environment variable or run '/login ${resolvedProvider}'.`,
+			);
+		},
+	});
+
+	// Restore messages if session has existing data
+	if (hasExistingSession) {
+		agent.state.messages = existingSession.messages;
+		if (!hasThinkingEntry) {
+			sessionManager.appendThinkingLevelChange(thinkingLevel ?? DEFAULT_THINKING_LEVEL);
+		}
+	} 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 ?? DEFAULT_THINKING_LEVEL);
+	}
+
+	const session = new AgentSession({
+		agent,
+		sessionManager,
+		settingsManager,
+		cwd,
+		scopedModels: options.scopedModels,
+		resourceLoader,
+		customTools: options.customTools,
+		modelRegistry,
+		initialActiveToolNames,
+		extensionRunnerRef,
+		isClaudeCodeReady: options.isClaudeCodeReady,
+	});
+	const extensionsResult = resourceLoader.getExtensions();
+
+	return {
+		session,
+		extensionsResult,
+		modelFallbackMessage,
+	};
+}