@schlenkr/ragents 0.1.0

package/packages/agent/src/core/system-prompt.ts

@@ -0,0 +1,147 @@
+/**
+ * System prompt construction and project context loading
+ */
+
+import { formatSkillsForPrompt, type Skill } from "./skills.ts";
+
+export interface BuildSystemPromptOptions {
+	/** Custom system prompt (replaces default). */
+	customPrompt?: string;
+	/** Tools to include in prompt. Default: [read, bash, edit, write] */
+	selectedTools?: string[];
+	/** Optional one-line tool snippets keyed by tool name. */
+	toolSnippets?: Record<string, string>;
+	/** Additional guideline bullets appended to the default system prompt guidelines. */
+	promptGuidelines?: string[];
+	/** Text to append to system prompt. */
+	appendSystemPrompt?: string;
+	/** Working directory. */
+	cwd: string;
+	/** Pre-loaded context files. */
+	contextFiles?: Array<{ path: string; content: string }>;
+	/** Pre-loaded skills. */
+	skills?: Skill[];
+}
+
+/** Build the system prompt with tools, guidelines, and context */
+export function buildSystemPrompt(options: BuildSystemPromptOptions): string {
+	const {
+		customPrompt,
+		selectedTools,
+		toolSnippets,
+		promptGuidelines,
+		appendSystemPrompt,
+		cwd,
+		contextFiles: providedContextFiles,
+		skills: providedSkills,
+	} = options;
+	const promptCwd = cwd.replace(/\\/g, "/");
+
+	const appendSection = appendSystemPrompt ? `\n\n${appendSystemPrompt}` : "";
+
+	const contextFiles = providedContextFiles ?? [];
+	const skills = providedSkills ?? [];
+
+	if (customPrompt) {
+		let prompt = customPrompt;
+
+		if (appendSection) {
+			prompt += appendSection;
+		}
+
+		// Append project context files
+		if (contextFiles.length > 0) {
+			prompt += "\n\n<project_context>\n\n";
+			prompt += "Project-specific instructions and guidelines:\n\n";
+			for (const { path: filePath, content } of contextFiles) {
+				prompt += `<project_instructions path="${filePath}">\n${content}\n</project_instructions>\n\n`;
+			}
+			prompt += "</project_context>\n";
+		}
+
+		// Append skills section (only if read tool is available)
+		const customPromptHasRead = !selectedTools || selectedTools.includes("read");
+		if (customPromptHasRead && skills.length > 0) {
+			prompt += formatSkillsForPrompt(skills);
+		}
+
+		prompt += `\nCurrent working directory: ${promptCwd}`;
+
+		return prompt;
+	}
+
+	// Get absolute paths to documentation and examples
+
+	// Build tools list based on selected tools.
+	// A tool appears in Available tools only when the caller provides a one-line snippet.
+	const tools = selectedTools || ["read", "bash", "edit", "write"];
+	const visibleTools = tools.filter((name) => !!toolSnippets?.[name]);
+	const toolsList =
+		visibleTools.length > 0 ? visibleTools.map((name) => `- ${name}: ${toolSnippets![name]}`).join("\n") : "(none)";
+
+	// Build guidelines based on which tools are actually available
+	const guidelinesList: string[] = [];
+	const guidelinesSet = new Set<string>();
+	const addGuideline = (guideline: string): void => {
+		if (guidelinesSet.has(guideline)) {
+			return;
+		}
+		guidelinesSet.add(guideline);
+		guidelinesList.push(guideline);
+	};
+
+	const hasBash = tools.includes("bash");
+	const hasRead = tools.includes("read");
+
+	// File exploration guidelines
+	if (hasBash) {
+		addGuideline("Use bash for file operations like ls, rg, find");
+	}
+
+	for (const guideline of promptGuidelines ?? []) {
+		const normalized = guideline.trim();
+		if (normalized.length > 0) {
+			addGuideline(normalized);
+		}
+	}
+
+	// Always include these
+	addGuideline("Be concise in your responses");
+	addGuideline("Show file paths clearly when working with files");
+
+	const guidelines = guidelinesList.map((g) => `- ${g}`).join("\n");
+
+	let prompt = `You are an expert coding assistant operating inside a coding agent harness. You help users by reading files, executing commands, editing code, and writing new files.
+
+Available tools:
+${toolsList}
+
+In addition to the tools above, you may have access to other custom tools depending on the project.
+
+Guidelines:
+${guidelines}
+`;
+
+	if (appendSection) {
+		prompt += appendSection;
+	}
+
+	// Append project context files
+	if (contextFiles.length > 0) {
+		prompt += "\n\n<project_context>\n\n";
+		prompt += "Project-specific instructions and guidelines:\n\n";
+		for (const { path: filePath, content } of contextFiles) {
+			prompt += `<project_instructions path="${filePath}">\n${content}\n</project_instructions>\n\n`;
+		}
+		prompt += "</project_context>\n";
+	}
+
+	// Append skills section (only if read tool is available)
+	if (hasRead && skills.length > 0) {
+		prompt += formatSkillsForPrompt(skills);
+	}
+
+	prompt += `\nCurrent working directory: ${promptCwd}`;
+
+	return prompt;
+}

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

@@ -0,0 +1,50 @@
+/**
+ * Central timing instrumentation for startup profiling.
+ * Enable with AGENT_TIMING=1 environment variable.
+ */
+
+const ENABLED = process.env.AGENT_TIMING === "1";
+interface TimingNamespace {
+	timings: Array<{ label: string; ms: number }>;
+	lastTime: number;
+}
+
+type TimingLabel = "main" | "extensions";
+
+const timingNamespaces = new Map<TimingLabel, TimingNamespace>();
+
+export function resetTimings(namespace: TimingLabel = "main"): void {
+	if (!ENABLED) return;
+	timingNamespaces.set(namespace, { timings: [], lastTime: Date.now() });
+}
+
+export function time(label: string, namespace: TimingLabel = "main"): void {
+	if (!ENABLED) return;
+	const now = Date.now();
+
+	if (!timingNamespaces.has(namespace)) {
+		resetTimings(namespace);
+	}
+
+	const timingNamespace = timingNamespaces.get(namespace)!;
+	timingNamespace.timings.push({ label, ms: now - timingNamespace.lastTime });
+	timingNamespace.lastTime = now;
+}
+
+function printTimingGroup(title: string, timings: TimingNamespace["timings"]): void {
+	const printableTimings = timings.filter((timing) => timing.ms >= 0);
+	if (printableTimings.length === 0) return;
+	console.error(`\n--- ${title} ---`);
+	for (const t of printableTimings) {
+		console.error(`  ${t.label}: ${t.ms}ms`);
+	}
+	console.error(`  TOTAL: ${printableTimings.reduce((a, b) => a + b.ms, 0)}ms`);
+	console.error(`${"-".repeat(title.length + 8)}\n`);
+}
+
+export function printTimings(): void {
+	if (!ENABLED) return;
+	for (const [namespace, timingNamespace] of timingNamespaces) {
+		printTimingGroup(`Startup Timings: ${namespace}`, timingNamespace.timings);
+	}
+}

package/packages/agent/src/core/tools/bash.ts

@@ -0,0 +1,314 @@
+import { constants } from "node:fs";
+import { access as fsAccess } from "node:fs/promises";
+import type { AgentTool } from "@aicontainer/agent-core";
+import { spawn } from "child_process";
+import { type Static, Type } from "typebox";
+import { waitForChildProcess } from "../../utils/child-process.ts";
+import {
+	getShellConfig,
+	getShellEnv,
+	killProcessTree,
+	trackDetachedChildPid,
+	untrackDetachedChildPid,
+} from "../../utils/shell.ts";
+import type { ToolDefinition } from "../extensions/types.ts";
+import { OutputAccumulator } from "./output-accumulator.ts";
+import { wrapToolDefinition } from "./tool-definition-wrapper.ts";
+import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, formatSize, type TruncationResult } from "./truncate.ts";
+
+const MAX_TIMEOUT_MS = 2_147_483_647;
+const MAX_TIMEOUT_SECONDS = MAX_TIMEOUT_MS / 1000;
+
+function resolveTimeoutMs(timeout: number | undefined): number | undefined {
+	if (timeout === undefined) return undefined;
+	if (!Number.isFinite(timeout) || timeout <= 0) {
+		throw new Error("Invalid timeout: must be a finite number of seconds");
+	}
+
+	const timeoutMs = timeout * 1000;
+	if (timeoutMs > MAX_TIMEOUT_MS) {
+		throw new Error(`Invalid timeout: maximum is ${MAX_TIMEOUT_SECONDS} seconds`);
+	}
+	return timeoutMs;
+}
+
+const bashSchema = Type.Object({
+	command: Type.String({ description: "Bash command to execute" }),
+	timeout: Type.Optional(Type.Number({ description: "Timeout in seconds (optional, no default timeout)" })),
+});
+
+export type BashToolInput = Static<typeof bashSchema>;
+
+export interface BashToolDetails {
+	truncation?: TruncationResult;
+	fullOutputPath?: string;
+}
+
+/**
+ * Pluggable operations for the bash tool.
+ * Override these to delegate command execution to remote systems (for example SSH).
+ */
+export interface BashOperations {
+	/**
+	 * Execute a command and stream output.
+	 * @param command The command to execute
+	 * @param cwd Working directory
+	 * @param options Execution options
+	 * @returns Promise resolving to exit code (null if killed)
+	 */
+	exec: (
+		command: string,
+		cwd: string,
+		options: {
+			onData: (data: Buffer) => void;
+			signal?: AbortSignal;
+			timeout?: number;
+			env?: NodeJS.ProcessEnv;
+		},
+	) => Promise<{ exitCode: number | null }>;
+}
+
+/**
+ * Create bash operations using the built-in local shell execution backend.
+ *
+ * This is useful for extensions that intercept user_bash and still want the
+ * standard local shell behavior while wrapping or rewriting commands.
+ */
+export function createLocalBashOperations(options?: { shellPath?: string }): BashOperations {
+	return {
+		exec: async (command, cwd, { onData, signal, timeout, env }) => {
+			const timeoutMs = resolveTimeoutMs(timeout);
+			if (signal?.aborted) {
+				throw new Error("aborted");
+			}
+			const shellConfig = getShellConfig(options?.shellPath);
+			try {
+				await fsAccess(cwd, constants.F_OK);
+			} catch {
+				throw new Error(`Working directory does not exist: ${cwd}\nCannot execute bash commands.`);
+			}
+
+			const commandFromStdin = shellConfig.commandTransport === "stdin";
+			const child = spawn(shellConfig.shell, commandFromStdin ? shellConfig.args : [...shellConfig.args, command], {
+				cwd,
+				detached: process.platform !== "win32",
+				env: env ?? getShellEnv(),
+				stdio: [commandFromStdin ? "pipe" : "ignore", "pipe", "pipe"],
+				windowsHide: true,
+			});
+			if (commandFromStdin) {
+				child.stdin?.on("error", () => {});
+				child.stdin?.end(command);
+			}
+			if (child.pid) trackDetachedChildPid(child.pid);
+			let timedOut = false;
+			let timeoutHandle: NodeJS.Timeout | undefined;
+			const onAbort = () => {
+				if (child.pid) killProcessTree(child.pid);
+			};
+
+			try {
+				// Set timeout if provided.
+				if (timeoutMs !== undefined) {
+					timeoutHandle = setTimeout(() => {
+						timedOut = true;
+						if (child.pid) killProcessTree(child.pid);
+					}, timeoutMs);
+				}
+				// Stream stdout and stderr.
+				child.stdout?.on("data", onData);
+				child.stderr?.on("data", onData);
+				// Handle abort signal by killing the entire process tree.
+				if (signal) {
+					if (signal.aborted) onAbort();
+					else signal.addEventListener("abort", onAbort, { once: true });
+				}
+				// Handle shell spawn errors and wait for the process to terminate without hanging
+				// on inherited stdio handles held by detached descendants.
+				const exitCode = await waitForChildProcess(child);
+				if (signal?.aborted) {
+					throw new Error("aborted");
+				}
+				if (timedOut) {
+					throw new Error(`timeout:${timeout}`);
+				}
+				return { exitCode };
+			} finally {
+				if (child.pid) untrackDetachedChildPid(child.pid);
+				if (timeoutHandle) clearTimeout(timeoutHandle);
+				if (signal) signal.removeEventListener("abort", onAbort);
+			}
+		},
+	};
+}
+
+export interface BashSpawnContext {
+	command: string;
+	cwd: string;
+	env: NodeJS.ProcessEnv;
+}
+
+export type BashSpawnHook = (context: BashSpawnContext) => BashSpawnContext;
+
+function resolveSpawnContext(command: string, cwd: string, spawnHook?: BashSpawnHook): BashSpawnContext {
+	const baseContext: BashSpawnContext = { command, cwd, env: { ...getShellEnv() } };
+	return spawnHook ? spawnHook(baseContext) : baseContext;
+}
+
+export interface BashToolOptions {
+	/** Custom operations for command execution. Default: local shell */
+	operations?: BashOperations;
+	/** Command prefix prepended to every command (for example shell setup commands) */
+	commandPrefix?: string;
+	/** Optional explicit shell path from settings */
+	shellPath?: string;
+	/** Hook to adjust command, cwd, or env before execution */
+	spawnHook?: BashSpawnHook;
+}
+
+const BASH_UPDATE_THROTTLE_MS = 100;
+
+export function createBashToolDefinition(
+	cwd: string,
+	options?: BashToolOptions,
+): ToolDefinition<typeof bashSchema, BashToolDetails | undefined> {
+	const ops = options?.operations ?? createLocalBashOperations({ shellPath: options?.shellPath });
+	const commandPrefix = options?.commandPrefix;
+	const spawnHook = options?.spawnHook;
+	return {
+		name: "bash",
+		label: "bash",
+		description: `Execute a bash command in the current working directory. Returns stdout and stderr; a nonzero exit code is reported at the end of the result (for example grep without a match), not as a tool error. Output is truncated to last ${DEFAULT_MAX_LINES} lines or ${DEFAULT_MAX_BYTES / 1024}KB (whichever is hit first). If truncated, full output is saved to a temp file. Optionally provide a timeout in seconds.`,
+		promptSnippet: "Execute bash commands (ls, grep, find, etc.)",
+		parameters: bashSchema,
+		async execute(
+			_toolCallId,
+			{ command, timeout }: { command: string; timeout?: number },
+			signal?: AbortSignal,
+			onUpdate?,
+			_ctx?,
+		) {
+			const resolvedCommand = commandPrefix ? `${commandPrefix}\n${command}` : command;
+			const spawnContext = resolveSpawnContext(resolvedCommand, cwd, spawnHook);
+			const output = new OutputAccumulator({ tempFilePrefix: "agent-bash" });
+			let acceptingOutput = true;
+			let updateTimer: NodeJS.Timeout | undefined;
+			let updateDirty = false;
+			let lastUpdateAt = 0;
+
+			const emitOutputUpdate = () => {
+				if (!onUpdate || !updateDirty) return;
+				updateDirty = false;
+				lastUpdateAt = Date.now();
+				const snapshot = output.snapshot({ persistIfTruncated: true });
+				onUpdate({
+					content: [{ type: "text", text: snapshot.content || "" }],
+					details: {
+						truncation: snapshot.truncation.truncated ? snapshot.truncation : undefined,
+						fullOutputPath: snapshot.fullOutputPath,
+					},
+				});
+			};
+
+			const clearUpdateTimer = () => {
+				if (updateTimer) {
+					clearTimeout(updateTimer);
+					updateTimer = undefined;
+				}
+			};
+
+			const scheduleOutputUpdate = () => {
+				if (!onUpdate) return;
+				updateDirty = true;
+				const delay = BASH_UPDATE_THROTTLE_MS - (Date.now() - lastUpdateAt);
+				if (delay <= 0) {
+					clearUpdateTimer();
+					emitOutputUpdate();
+					return;
+				}
+				updateTimer ??= setTimeout(() => {
+					updateTimer = undefined;
+					emitOutputUpdate();
+				}, delay);
+			};
+
+			if (onUpdate) {
+				onUpdate({ content: [], details: undefined });
+			}
+
+			const handleData = (data: Buffer) => {
+				if (!acceptingOutput) return;
+				output.append(data);
+				scheduleOutputUpdate();
+			};
+
+			const finishOutput = async () => {
+				acceptingOutput = false;
+				output.finish();
+				clearUpdateTimer();
+				emitOutputUpdate();
+				const snapshot = output.snapshot({ persistIfTruncated: true });
+				await output.closeTempFile();
+				return snapshot;
+			};
+
+			const formatOutput = (snapshot: Awaited<ReturnType<typeof finishOutput>>, emptyText = "(no output)") => {
+				const truncation = snapshot.truncation;
+				let text = snapshot.content || emptyText;
+				let details: BashToolDetails | undefined;
+				if (truncation.truncated) {
+					details = { truncation, fullOutputPath: snapshot.fullOutputPath };
+					const startLine = truncation.totalLines - truncation.outputLines + 1;
+					const endLine = truncation.totalLines;
+					if (truncation.lastLinePartial) {
+						const lastLineSize = formatSize(output.getLastLineBytes());
+						text += `\n\n[Showing last ${formatSize(truncation.outputBytes)} of line ${endLine} (line is ${lastLineSize}). Full output: ${snapshot.fullOutputPath}]`;
+					} else if (truncation.truncatedBy === "lines") {
+						text += `\n\n[Showing lines ${startLine}-${endLine} of ${truncation.totalLines}. Full output: ${snapshot.fullOutputPath}]`;
+					} else {
+						text += `\n\n[Showing lines ${startLine}-${endLine} of ${truncation.totalLines} (${formatSize(DEFAULT_MAX_BYTES)} limit). Full output: ${snapshot.fullOutputPath}]`;
+					}
+				}
+				return { text, details };
+			};
+
+			const appendStatus = (text: string, status: string) => `${text ? `${text}\n\n` : ""}${status}`;
+
+			try {
+				let exitCode: number | null;
+				try {
+					const result = await ops.exec(spawnContext.command, spawnContext.cwd, {
+						onData: handleData,
+						signal,
+						timeout,
+						env: spawnContext.env,
+					});
+					exitCode = result.exitCode;
+				} catch (err) {
+					const snapshot = await finishOutput();
+					const { text } = formatOutput(snapshot, "");
+					if (err instanceof Error && err.message === "aborted") {
+						throw new Error(appendStatus(text, "Command aborted"));
+					}
+					if (err instanceof Error && err.message.startsWith("timeout:")) {
+						const timeoutSecs = err.message.split(":")[1];
+						throw new Error(appendStatus(text, `Command timed out after ${timeoutSecs} seconds`));
+					}
+					throw err;
+				}
+
+				const snapshot = await finishOutput();
+				const { text: outputText, details } = formatOutput(snapshot);
+				const text = exitCode !== 0 && exitCode !== null ? appendStatus(outputText, `Command exited with code ${exitCode}`) : outputText;
+				return { content: [{ type: "text", text }], details };
+			} finally {
+				clearUpdateTimer();
+			}
+		},
+
+	};
+}
+
+export function createBashTool(cwd: string, options?: BashToolOptions): AgentTool<typeof bashSchema> {
+	return wrapToolDefinition(createBashToolDefinition(cwd, options));
+}