@schlenkr/ragents 0.1.0

package/packages/agent/src/core/extensions/wrapper.ts

@@ -0,0 +1,45 @@
+/**
+ * Tool wrappers for extension-registered tools.
+ *
+ * These wrappers only adapt tool execution so extension tools receive the runner context.
+ * Tool call and tool result interception is handled by AgentSession via agent-core hooks.
+ */
+
+import type { AgentTool } from "@aicontainer/agent-core";
+import { wrapToolDefinition } from "../tools/tool-definition-wrapper.ts";
+import type { ExtensionRunner } from "./runner.ts";
+import type { RegisteredTool } from "./types.ts";
+
+/**
+ * Wrap a RegisteredTool into an AgentTool.
+ * Uses the runner's createContext() for consistent context across tools and event handlers.
+ */
+export function wrapRegisteredTool(registeredTool: RegisteredTool, runner: ExtensionRunner): AgentTool {
+	const tool = wrapToolDefinition(registeredTool.definition, () => runner.createContext());
+	const execute = tool.execute;
+	return {
+		...tool,
+		execute: async (toolCallId, params, signal, onUpdate) => {
+			const activeBefore = runner.getActiveTools();
+			const result = await execute(toolCallId, params, signal, onUpdate);
+			const activeAfter = runner.getActiveTools();
+			if (!activeBefore.every((name) => activeAfter.includes(name))) return result;
+
+			const beforeNames = new Set(activeBefore);
+			const addedToolNames = activeAfter.filter((name) => !beforeNames.has(name));
+			if (addedToolNames.length === 0) return result;
+			return {
+				...result,
+				addedToolNames: [...new Set([...(result.addedToolNames ?? []), ...addedToolNames])],
+			};
+		},
+	};
+}
+
+/**
+ * Wrap all registered tools into AgentTools.
+ * Uses the runner's createContext() for consistent context across tools and event handlers.
+ */
+export function wrapRegisteredTools(registeredTools: RegisteredTool[], runner: ExtensionRunner): AgentTool[] {
+	return registeredTools.map((tool) => wrapRegisteredTool(tool, runner));
+}

package/packages/agent/src/core/footer-data-provider.ts

@@ -0,0 +1,388 @@
+import { type ExecFileException, execFile, spawnSync } from "child_process";
+import { existsSync, type FSWatcher, readFileSync, type Stats, statSync, unwatchFile, watchFile } from "fs";
+import { dirname, join, resolve } from "path";
+import { closeWatcher, FS_WATCH_RETRY_DELAY_MS, watchWithErrorHandler } from "../utils/fs-watch.ts";
+
+type GitPaths = {
+	repoDir: string;
+	commonGitDir: string;
+	headPath: string;
+};
+
+/**
+ * Find git metadata paths by walking up from cwd.
+ * Handles both regular git repos (.git is a directory) and worktrees (.git is a file).
+ */
+function findGitPaths(cwd: string): GitPaths | null {
+	let dir = cwd;
+	while (true) {
+		const gitPath = join(dir, ".git");
+		if (existsSync(gitPath)) {
+			try {
+				const stat = statSync(gitPath);
+				if (stat.isFile()) {
+					const content = readFileSync(gitPath, "utf8").trim();
+					if (content.startsWith("gitdir: ")) {
+						const gitDir = resolve(dir, content.slice(8).trim());
+						const headPath = join(gitDir, "HEAD");
+						if (!existsSync(headPath)) return null;
+						const commonDirPath = join(gitDir, "commondir");
+						const commonGitDir = existsSync(commonDirPath)
+							? resolve(gitDir, readFileSync(commonDirPath, "utf8").trim())
+							: gitDir;
+						return { repoDir: dir, commonGitDir, headPath };
+					}
+				} else if (stat.isDirectory()) {
+					const headPath = join(gitPath, "HEAD");
+					if (!existsSync(headPath)) return null;
+					return { repoDir: dir, commonGitDir: gitPath, headPath };
+				}
+			} catch {
+				return null;
+			}
+		}
+		const parent = dirname(dir);
+		if (parent === dir) return null;
+		dir = parent;
+	}
+}
+
+/** Ask git for the current branch. Returns null on detached HEAD or if git is unavailable. */
+function resolveBranchWithGitSync(repoDir: string): string | null {
+	const result = spawnSync("git", ["--no-optional-locks", "symbolic-ref", "--quiet", "--short", "HEAD"], {
+		cwd: repoDir,
+		encoding: "utf8",
+		stdio: ["ignore", "pipe", "ignore"],
+	});
+	const branch = result.status === 0 ? result.stdout.trim() : "";
+	return branch || null;
+}
+
+/** Ask git for the current branch asynchronously. Returns null on detached HEAD or if git is unavailable. */
+function resolveBranchWithGitAsync(repoDir: string): Promise<string | null> {
+	return new Promise((resolvePromise) => {
+		execFile(
+			"git",
+			["--no-optional-locks", "symbolic-ref", "--quiet", "--short", "HEAD"],
+			{
+				cwd: repoDir,
+				encoding: "utf8",
+			},
+			(error: ExecFileException | null, stdout: string) => {
+				if (error) {
+					resolvePromise(null);
+					return;
+				}
+				const branch = stdout.trim();
+				resolvePromise(branch || null);
+			},
+		);
+	});
+}
+
+function isWslEnvironment(): boolean {
+	return process.platform === "linux" && !!(process.env.WSL_DISTRO_NAME || process.env.WSL_INTEROP);
+}
+
+function isWindowsMountedRepoPath(repoDir: string): boolean {
+	return /^\/mnt\/[a-z](?:\/|$)/i.test(repoDir);
+}
+
+function shouldPollGitHead(repoDir: string): boolean {
+	return isWslEnvironment() && isWindowsMountedRepoPath(repoDir);
+}
+
+/**
+ * Provides git branch and extension statuses - data not otherwise accessible to extensions.
+ * Token stats, model info available via ctx.sessionManager and ctx.model.
+ */
+export class FooterDataProvider {
+	private cwd: string;
+	private static readonly WATCH_DEBOUNCE_MS = 500;
+
+	private extensionStatuses = new Map<string, string>();
+	private cachedBranch: string | null | undefined = undefined;
+	private gitPaths: GitPaths | null | undefined = undefined;
+	private headWatcher: FSWatcher | null = null;
+	private headWatchFilePath: string | null = null;
+	private headWatchFileListener: ((current: Stats, previous: Stats) => void) | null = null;
+	private reftableWatcher: FSWatcher | null = null;
+	private reftableTablesListWatcher: FSWatcher | null = null;
+	private reftableTablesListPath: string | null = null;
+	private branchChangeCallbacks = new Set<() => void>();
+	private availableProviderCount = 0;
+	private refreshTimer: ReturnType<typeof setTimeout> | null = null;
+	private gitWatcherRetryTimer: ReturnType<typeof setTimeout> | null = null;
+	private refreshInFlight = false;
+	private refreshPending = false;
+	private disposed = false;
+
+	constructor(cwd: string) {
+		this.cwd = cwd;
+		this.gitPaths = findGitPaths(cwd);
+		this.setupGitWatcher();
+	}
+
+	/** Current git branch, null if not in repo, "detached" if detached HEAD */
+	getGitBranch(): string | null {
+		if (this.cachedBranch === undefined) {
+			this.cachedBranch = this.resolveGitBranchSync();
+		}
+		return this.cachedBranch;
+	}
+
+	/** Extension status texts set via ctx.ui.setStatus() */
+	getExtensionStatuses(): ReadonlyMap<string, string> {
+		return this.extensionStatuses;
+	}
+
+	/** Subscribe to git branch changes. Returns unsubscribe function. */
+	onBranchChange(callback: () => void): () => void {
+		this.branchChangeCallbacks.add(callback);
+		return () => this.branchChangeCallbacks.delete(callback);
+	}
+
+	/** Internal: set extension status */
+	setExtensionStatus(key: string, text: string | undefined): void {
+		if (text === undefined) {
+			this.extensionStatuses.delete(key);
+		} else {
+			this.extensionStatuses.set(key, text);
+		}
+	}
+
+	/** Internal: clear extension statuses */
+	clearExtensionStatuses(): void {
+		this.extensionStatuses.clear();
+	}
+
+	/** Number of unique providers with available models (for footer display) */
+	getAvailableProviderCount(): number {
+		return this.availableProviderCount;
+	}
+
+	/** Internal: update available provider count */
+	setAvailableProviderCount(count: number): void {
+		this.availableProviderCount = count;
+	}
+
+	setCwd(cwd: string): void {
+		if (this.cwd === cwd) {
+			return;
+		}
+
+		this.cwd = cwd;
+		if (this.refreshTimer) {
+			clearTimeout(this.refreshTimer);
+			this.refreshTimer = null;
+		}
+		this.clearGitWatchers();
+		this.cachedBranch = undefined;
+		this.gitPaths = findGitPaths(cwd);
+		this.setupGitWatcher();
+		this.notifyBranchChange();
+	}
+
+	/** Internal: cleanup */
+	dispose(): void {
+		this.disposed = true;
+		if (this.refreshTimer) {
+			clearTimeout(this.refreshTimer);
+			this.refreshTimer = null;
+		}
+		this.clearGitWatchers();
+		this.branchChangeCallbacks.clear();
+	}
+
+	private notifyBranchChange(): void {
+		for (const cb of this.branchChangeCallbacks) cb();
+	}
+
+	private scheduleRefresh(): void {
+		if (this.disposed || this.refreshTimer) return;
+		if (this.refreshInFlight) {
+			this.refreshPending = true;
+			return;
+		}
+		this.refreshTimer = setTimeout(() => {
+			this.refreshTimer = null;
+			void this.refreshGitBranchAsync();
+		}, FooterDataProvider.WATCH_DEBOUNCE_MS);
+	}
+
+	private async refreshGitBranchAsync(): Promise<void> {
+		if (this.disposed) return;
+		if (this.refreshInFlight) {
+			this.refreshPending = true;
+			return;
+		}
+
+		this.refreshInFlight = true;
+		try {
+			const nextBranch = await this.resolveGitBranchAsync();
+			if (this.disposed) return;
+			if (this.cachedBranch !== undefined && this.cachedBranch !== nextBranch) {
+				this.cachedBranch = nextBranch;
+				this.notifyBranchChange();
+				return;
+			}
+			this.cachedBranch = nextBranch;
+		} finally {
+			this.refreshInFlight = false;
+			if (this.refreshPending && !this.disposed) {
+				this.refreshPending = false;
+				this.scheduleRefresh();
+			}
+		}
+	}
+
+	private resolveGitBranchSync(): string | null {
+		try {
+			if (!this.gitPaths) return null;
+			const content = readFileSync(this.gitPaths.headPath, "utf8").trim();
+			if (content.startsWith("ref: refs/heads/")) {
+				const branch = content.slice(16);
+				return branch === ".invalid" ? (resolveBranchWithGitSync(this.gitPaths.repoDir) ?? "detached") : branch;
+			}
+			return "detached";
+		} catch {
+			return null;
+		}
+	}
+
+	private async resolveGitBranchAsync(): Promise<string | null> {
+		try {
+			if (!this.gitPaths) return null;
+			const content = readFileSync(this.gitPaths.headPath, "utf8").trim();
+			if (content.startsWith("ref: refs/heads/")) {
+				const branch = content.slice(16);
+				return branch === ".invalid"
+					? ((await resolveBranchWithGitAsync(this.gitPaths.repoDir)) ?? "detached")
+					: branch;
+			}
+			return "detached";
+		} catch {
+			return null;
+		}
+	}
+
+	private clearGitWatchers(): void {
+		closeWatcher(this.headWatcher);
+		this.headWatcher = null;
+		if (this.headWatchFilePath && this.headWatchFileListener) {
+			unwatchFile(this.headWatchFilePath, this.headWatchFileListener);
+			this.headWatchFilePath = null;
+			this.headWatchFileListener = null;
+		}
+		closeWatcher(this.reftableWatcher);
+		this.reftableWatcher = null;
+		closeWatcher(this.reftableTablesListWatcher);
+		this.reftableTablesListWatcher = null;
+		if (this.reftableTablesListPath) {
+			unwatchFile(this.reftableTablesListPath);
+			this.reftableTablesListPath = null;
+		}
+		if (this.gitWatcherRetryTimer) {
+			clearTimeout(this.gitWatcherRetryTimer);
+			this.gitWatcherRetryTimer = null;
+		}
+	}
+
+	private scheduleGitWatcherRetry(): void {
+		if (this.disposed || this.gitWatcherRetryTimer) {
+			return;
+		}
+
+		this.gitWatcherRetryTimer = setTimeout(() => {
+			this.gitWatcherRetryTimer = null;
+			this.setupGitWatcher();
+		}, FS_WATCH_RETRY_DELAY_MS);
+	}
+
+	private handleGitWatcherError(): void {
+		this.clearGitWatchers();
+		this.scheduleGitWatcherRetry();
+	}
+
+	private setupGitWatcher(): void {
+		this.clearGitWatchers();
+		if (!this.gitPaths) return;
+
+		const pollGitHead = shouldPollGitHead(this.gitPaths.repoDir);
+
+		// Watch the directory containing HEAD, not HEAD itself.
+		// Git uses atomic writes (write temp, rename over HEAD), which changes the inode.
+		// fs.watch on a file stops working after the inode changes.
+		this.headWatcher = watchWithErrorHandler(
+			dirname(this.gitPaths.headPath),
+			(_eventType, filename) => {
+				if (!filename || filename === "HEAD") {
+					this.scheduleRefresh();
+				}
+			},
+			() => this.handleGitWatcherError(),
+		);
+		if (pollGitHead) {
+			this.headWatchFilePath = this.gitPaths.headPath;
+			this.headWatchFileListener = (current, previous) => {
+				if (
+					current.mtimeMs !== previous.mtimeMs ||
+					current.ctimeMs !== previous.ctimeMs ||
+					current.size !== previous.size
+				) {
+					this.scheduleRefresh();
+				}
+			};
+			watchFile(this.headWatchFilePath, { interval: 1000 }, this.headWatchFileListener);
+		}
+		if (!this.headWatcher && !pollGitHead) {
+			return;
+		}
+
+		// In reftable repos, branch switches update files in the reftable directory
+		// instead of HEAD. Watch it separately so the footer picks up those changes.
+		const reftableDir = join(this.gitPaths.commonGitDir, "reftable");
+		if (existsSync(reftableDir)) {
+			this.reftableWatcher = watchWithErrorHandler(
+				reftableDir,
+				() => {
+					this.scheduleRefresh();
+				},
+				() => this.handleGitWatcherError(),
+			);
+			if (!this.reftableWatcher) {
+				return;
+			}
+
+			const tablesListPath = join(reftableDir, "tables.list");
+			if (existsSync(tablesListPath)) {
+				this.reftableTablesListPath = tablesListPath;
+				this.reftableTablesListWatcher = watchWithErrorHandler(
+					tablesListPath,
+					() => {
+						this.scheduleRefresh();
+					},
+					() => this.handleGitWatcherError(),
+				);
+				if (!this.reftableTablesListWatcher) {
+					return;
+				}
+				watchFile(tablesListPath, { interval: 250 }, (current, previous) => {
+					if (
+						current.mtimeMs !== previous.mtimeMs ||
+						current.ctimeMs !== previous.ctimeMs ||
+						current.size !== previous.size
+					) {
+						this.scheduleRefresh();
+					}
+				});
+			}
+		}
+	}
+}
+
+/** Read-only view for extensions - excludes setExtensionStatus, setAvailableProviderCount and dispose */
+export type ReadonlyFooterDataProvider = Pick<
+	FooterDataProvider,
+	"getGitBranch" | "getExtensionStatuses" | "getAvailableProviderCount" | "onBranchChange"
+>;

package/packages/agent/src/core/http-dispatcher.ts

@@ -0,0 +1,106 @@
+import { EventEmitter } from "node:events";
+import * as undici from "undici";
+
+export const DEFAULT_HTTP_IDLE_TIMEOUT_MS = 300_000;
+
+export const HTTP_IDLE_TIMEOUT_CHOICES = [
+	{ label: "30 sec", timeoutMs: 30_000 },
+	{ label: "1 min", timeoutMs: 60_000 },
+	{ label: "2 min", timeoutMs: 120_000 },
+	{ label: "5 min", timeoutMs: 300_000 },
+	{ label: "disabled", timeoutMs: 0 },
+] as const;
+
+const originalGlobalFetch = globalThis.fetch;
+let installedGlobalFetch: typeof globalThis.fetch | undefined;
+
+export function parseHttpIdleTimeoutMs(value: unknown): number | undefined {
+	if (typeof value === "string") {
+		const trimmed = value.trim();
+		if (trimmed.toLowerCase() === "disabled") {
+			return 0;
+		}
+		if (trimmed.length === 0) {
+			return undefined;
+		}
+		return parseHttpIdleTimeoutMs(Number(trimmed));
+	}
+
+	if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+		return undefined;
+	}
+	return Math.floor(value);
+}
+
+export function formatHttpIdleTimeoutMs(timeoutMs: number): string {
+	const choice = HTTP_IDLE_TIMEOUT_CHOICES.find((item) => item.timeoutMs === timeoutMs);
+	if (choice) {
+		return choice.label;
+	}
+	return `${timeoutMs / 1000} sec`;
+}
+
+export function applyHttpProxySettings(httpProxy: string | undefined): void {
+	const proxy = httpProxy?.trim();
+	if (!proxy) return;
+	process.env.HTTP_PROXY ??= proxy;
+	process.env.HTTPS_PROXY ??= proxy;
+}
+
+const ignoreUndiciDispatcherError = (_error: unknown): void => {};
+
+// Undici can emit an internal Client "error" while terminating a mid-stream
+// fetch body. The body stream still rejects through reader.read(); this listener
+// only prevents EventEmitter's unhandled "error" special case from crashing the process.
+function withUndiciErrorListener<T extends undici.Dispatcher>(dispatcher: T): T {
+	if (dispatcher instanceof EventEmitter) {
+		EventEmitter.prototype.on.call(dispatcher, "error", ignoreUndiciDispatcherError);
+	}
+	return dispatcher;
+}
+
+function createUndiciClient(origin: string | URL, options: object): undici.Dispatcher {
+	return withUndiciErrorListener(new undici.Client(origin, options as undici.Client.Options));
+}
+
+function createUndiciOriginDispatcher(origin: string | URL, options: object): undici.Dispatcher {
+	const dispatcherOptions = options as undici.Pool.Options;
+	if (dispatcherOptions.connections === 1) {
+		return createUndiciClient(origin, dispatcherOptions);
+	}
+	return withUndiciErrorListener(
+		new undici.Pool(origin, {
+			...dispatcherOptions,
+			factory: createUndiciClient,
+		}),
+	);
+}
+
+export function configureHttpDispatcher(timeoutMs: number = DEFAULT_HTTP_IDLE_TIMEOUT_MS): void {
+	const normalizedTimeoutMs = parseHttpIdleTimeoutMs(timeoutMs);
+	if (normalizedTimeoutMs === undefined) {
+		throw new Error(`Invalid HTTP idle timeout: ${String(timeoutMs)}`);
+	}
+	const dispatcher = withUndiciErrorListener(
+		new undici.EnvHttpProxyAgent({
+			allowH2: false,
+			bodyTimeout: normalizedTimeoutMs,
+			headersTimeout: normalizedTimeoutMs,
+			clientFactory: createUndiciClient,
+			factory: createUndiciOriginDispatcher,
+		}),
+	);
+	undici.setGlobalDispatcher(dispatcher);
+	// Keep fetch and the dispatcher on the same undici implementation. Node 26.0's
+	// bundled fetch can otherwise consume compressed responses through npm undici's
+	// dispatcher without decompressing them, causing response.json() failures.
+	// If a caller replaced fetch after module load, preserve that deliberate override.
+	const shouldInstallGlobals =
+		installedGlobalFetch === undefined
+			? globalThis.fetch === originalGlobalFetch
+			: globalThis.fetch === installedGlobalFetch;
+	if (shouldInstallGlobals) {
+		undici.install?.();
+		installedGlobalFetch = globalThis.fetch;
+	}
+}

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

@@ -0,0 +1,78 @@
+/**
+ * Core modules shared between all run modes.
+ */
+
+export {
+	AgentSession,
+	type AgentSessionConfig,
+	type AgentSessionEvent,
+	type AgentSessionEventListener,
+	type ModelCycleResult,
+	type PromptOptions,
+	type SessionStats,
+} from "./agent-session.ts";
+export {
+	AgentSessionRuntime,
+	type CreateAgentSessionRuntimeFactory,
+	type CreateAgentSessionRuntimeResult,
+	createAgentSessionRuntime,
+} from "./agent-session-runtime.ts";
+export {
+	type AgentSessionRuntimeDiagnostic,
+	type AgentSessionServices,
+	type CreateAgentSessionFromServicesOptions,
+	type CreateAgentSessionServicesOptions,
+	createAgentSessionFromServices,
+	createAgentSessionServices,
+} from "./agent-session-services.ts";
+export { type BashExecutorOptions, type BashResult, executeBashWithOperations } from "./bash-executor.ts";
+export type { CompactionResult } from "./compaction/index.ts";
+export { createEventBus, type EventBus, type EventBusController } from "./event-bus.ts";
+export { areExperimentalFeaturesEnabled } from "./experimental.ts";
+// Extensions system
+export {
+	type AgentEndEvent,
+	type AgentSettledEvent,
+	type AgentStartEvent,
+	type AgentToolResult,
+	type AgentToolUpdateCallback,
+	type BeforeAgentStartEvent,
+	type BeforeAgentStartEventResult,
+	type BuildSystemPromptOptions,
+	type ContextEvent,
+	defineTool,
+	discoverAndLoadExtensions,
+	type ExecOptions,
+	type ExecResult,
+	type Extension,
+	type ExtensionAPI,
+	type ExtensionCommandContext,
+	type ExtensionContext,
+	type ExtensionError,
+	type ExtensionEvent,
+	type ExtensionFactory,
+	type ExtensionFlag,
+	type ExtensionHandler,
+	ExtensionRunner,
+	type ExtensionUIContext,
+	type InlineExtension,
+	type LoadExtensionsResult,
+	type RegisteredCommand,
+	type SessionBeforeCompactEvent,
+	type SessionBeforeForkEvent,
+	type SessionBeforeSwitchEvent,
+	type SessionBeforeTreeEvent,
+	type SessionCompactEvent,
+	type SessionShutdownEvent,
+	type SessionStartEvent,
+	type SessionTreeEvent,
+	type ToolCallEvent,
+	type ToolCallEventResult,
+	type ToolDefinition,
+	type ToolRenderResultOptions,
+	type ToolResultEvent,
+	type TurnEndEvent,
+	type TurnStartEvent,
+	type WorkingIndicatorOptions,
+} from "./extensions/index.ts";
+export { createSyntheticSourceInfo } from "./source-info.ts";