@schlenkr/ragents 0.1.0

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

@@ -0,0 +1,90 @@
+import type { AgentTool } from "@aicontainer/agent-core";
+import { mkdir as fsMkdir, writeFile as fsWriteFile } from "fs/promises";
+import { dirname } from "path";
+import { type Static, Type } from "typebox";
+import type { ToolDefinition } from "../extensions/types.ts";
+import { withFileMutationQueue } from "./file-mutation-queue.ts";
+import { resolveToCwd } from "./path-utils.ts";
+import { wrapToolDefinition } from "./tool-definition-wrapper.ts";
+
+const writeSchema = Type.Object({
+	path: Type.String({ description: "Path to the file to write (relative or absolute)" }),
+	content: Type.String({ description: "Content to write to the file" }),
+});
+
+export type WriteToolInput = Static<typeof writeSchema>;
+
+/**
+ * Pluggable operations for the write tool.
+ * Override these to delegate file writing to remote systems (for example SSH).
+ */
+export interface WriteOperations {
+	/** Write content to a file */
+	writeFile: (absolutePath: string, content: string) => Promise<void>;
+	/** Create directory recursively */
+	mkdir: (dir: string) => Promise<void>;
+}
+
+const defaultWriteOperations: WriteOperations = {
+	writeFile: (path, content) => fsWriteFile(path, content, "utf-8"),
+	mkdir: (dir) => fsMkdir(dir, { recursive: true }).then(() => {}),
+};
+
+export interface WriteToolOptions {
+	/** Custom operations for file writing. Default: local filesystem */
+	operations?: WriteOperations;
+}
+
+export function createWriteToolDefinition(
+	cwd: string,
+	options?: WriteToolOptions,
+): ToolDefinition<typeof writeSchema, undefined> {
+	const ops = options?.operations ?? defaultWriteOperations;
+	return {
+		name: "write",
+		label: "write",
+		description:
+			"Write content to a file. Creates the file if it doesn't exist, overwrites if it does. Automatically creates parent directories.",
+		promptSnippet: "Create or overwrite files",
+		promptGuidelines: ["Use write only for new files or complete rewrites."],
+		parameters: writeSchema,
+		async execute(
+			_toolCallId,
+			{ path, content }: { path: string; content: string },
+			signal?: AbortSignal,
+			_onUpdate?,
+			_ctx?,
+		) {
+			const absolutePath = resolveToCwd(path, cwd);
+			const dir = dirname(absolutePath);
+			return withFileMutationQueue(absolutePath, async () => {
+				// Do not reject from an abort event listener here: that would release the
+				// mutation queue while an in-flight filesystem operation may still finish.
+				// Checking signal.aborted after each await observes the same aborts while
+				// keeping the queue locked until the current operation has settled.
+				const throwIfAborted = (): void => {
+					if (signal?.aborted) throw new Error("Operation aborted");
+				};
+
+				throwIfAborted();
+				// Create parent directories if needed.
+				await ops.mkdir(dir);
+				throwIfAborted();
+
+				// Write the file contents.
+				await ops.writeFile(absolutePath, content);
+				throwIfAborted();
+
+				return {
+					content: [{ type: "text", text: `Successfully wrote ${content.length} bytes to ${path}` }],
+					details: undefined,
+				};
+			});
+		},
+
+	};
+}
+
+export function createWriteTool(cwd: string, options?: WriteToolOptions): AgentTool<typeof writeSchema> {
+	return wrapToolDefinition(createWriteToolDefinition(cwd, options));
+}

package/packages/agent/src/core/trust-manager.ts

@@ -0,0 +1,244 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import lockfile from "proper-lockfile";
+import { CONFIG_DIR_NAME } from "../config.ts";
+import { canonicalizePath, resolvePath } from "../utils/paths.ts";
+
+export type ProjectTrustDecision = boolean | null;
+
+export interface ProjectTrustStoreEntry {
+	path: string;
+	decision: boolean;
+}
+
+export interface ProjectTrustUpdate {
+	path: string;
+	decision: ProjectTrustDecision;
+}
+
+export interface ProjectTrustOption {
+	label: string;
+	trusted: boolean;
+	updates: ProjectTrustUpdate[];
+	savedPath?: string;
+}
+
+type TrustFile = Record<string, boolean | null | undefined>;
+
+const TRUST_REQUIRING_PROJECT_CONFIG_RESOURCES = [
+	"settings.json",
+	"extensions",
+	"skills",
+	"prompts",
+	"themes",
+	"SYSTEM.md",
+	"APPEND_SYSTEM.md",
+] as const;
+
+function normalizeCwd(cwd: string): string {
+	return canonicalizePath(resolvePath(cwd));
+}
+
+function findNearestTrustEntry(data: TrustFile, cwd: string): ProjectTrustStoreEntry | null {
+	let currentDir = normalizeCwd(cwd);
+	while (true) {
+		const value = data[currentDir];
+		if (value === true || value === false) {
+			return { path: currentDir, decision: value };
+		}
+
+		const parentDir = dirname(currentDir);
+		if (parentDir === currentDir) {
+			return null;
+		}
+		currentDir = parentDir;
+	}
+}
+
+export function getProjectTrustParentPath(cwd: string): string | undefined {
+	const trustPath = normalizeCwd(cwd);
+	const parentDir = dirname(trustPath);
+	return parentDir === trustPath ? undefined : parentDir;
+}
+
+export function getProjectTrustOptions(cwd: string, options?: { includeSessionOnly?: boolean }): ProjectTrustOption[] {
+	const trustPath = normalizeCwd(cwd);
+	const trustOptions: ProjectTrustOption[] = [
+		{ label: "Trust", trusted: true, updates: [{ path: trustPath, decision: true }], savedPath: trustPath },
+	];
+	const parentPath = getProjectTrustParentPath(cwd);
+	if (parentPath !== undefined) {
+		trustOptions.push({
+			label: `Trust parent folder (${parentPath})`,
+			trusted: true,
+			updates: [
+				{ path: parentPath, decision: true },
+				{ path: trustPath, decision: null },
+			],
+			savedPath: parentPath,
+		});
+	}
+	if (options?.includeSessionOnly) {
+		trustOptions.push({ label: "Trust (this session only)", trusted: true, updates: [] });
+	}
+	trustOptions.push({
+		label: "Do not trust",
+		trusted: false,
+		updates: [{ path: trustPath, decision: false }],
+		savedPath: trustPath,
+	});
+	if (options?.includeSessionOnly) {
+		trustOptions.push({ label: "Do not trust (this session only)", trusted: false, updates: [] });
+	}
+	return trustOptions;
+}
+
+function readTrustFile(path: string): TrustFile {
+	if (!existsSync(path)) {
+		return {};
+	}
+
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(readFileSync(path, "utf-8"));
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		throw new Error(`Failed to read trust store ${path}: ${message}`);
+	}
+
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+		throw new Error(`Invalid trust store ${path}: expected an object`);
+	}
+
+	const data: TrustFile = {};
+	for (const [key, value] of Object.entries(parsed)) {
+		if (value !== true && value !== false && value !== null) {
+			throw new Error(`Invalid trust store ${path}: value for ${JSON.stringify(key)} must be true, false, or null`);
+		}
+		data[key] = value;
+	}
+	return data;
+}
+
+function writeTrustFile(path: string, data: TrustFile): void {
+	const sorted: TrustFile = {};
+	for (const key of Object.keys(data).sort()) {
+		const value = data[key];
+		if (value === true || value === false || value === null) {
+			sorted[key] = value;
+		}
+	}
+	mkdirSync(dirname(path), { recursive: true });
+	writeFileSync(path, `${JSON.stringify(sorted, null, 2)}\n`, "utf-8");
+}
+
+function acquireTrustLockSync(path: string): () => void {
+	const trustDir = dirname(path);
+	mkdirSync(trustDir, { recursive: true });
+	const maxAttempts = 10;
+	const delayMs = 20;
+	let lastError: unknown;
+
+	for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+		try {
+			return lockfile.lockSync(trustDir, { realpath: false, lockfilePath: `${path}.lock` });
+		} catch (error) {
+			const code =
+				typeof error === "object" && error !== null && "code" in error
+					? String((error as { code?: unknown }).code)
+					: undefined;
+			if (code !== "ELOCKED" || attempt === maxAttempts) {
+				throw error;
+			}
+			lastError = error;
+			const start = Date.now();
+			while (Date.now() - start < delayMs) {
+				// Sleep synchronously to avoid changing trust store callers to async.
+			}
+		}
+	}
+
+	if (lastError instanceof Error) {
+		throw lastError;
+	}
+	throw new Error("Failed to acquire trust store lock");
+}
+
+function withTrustFileLock<T>(path: string, fn: () => T): T {
+	const release = acquireTrustLockSync(path);
+	try {
+		return fn();
+	} finally {
+		release();
+	}
+}
+
+/**
+ * Returns true when cwd has project-local resources that must be gated by
+ * project trust: trust-requiring entries under the project config dir, or .agents/skills in
+ * cwd or one of its ancestors. Returns false when no such project resources
+ * exist. The user/global ~/.agents/skills directory is always treated as a
+ * trusted user resource and is ignored here, even when cwd is $HOME.
+ */
+export function hasTrustRequiringProjectResources(cwd: string): boolean {
+	const homeDir = canonicalizePath(resolvePath(process.env.HOME || homedir()));
+	const userAgentsSkillsDir = join(homeDir, ".agents", "skills");
+	let currentDir = canonicalizePath(resolvePath(cwd));
+
+	const configDir = join(currentDir, CONFIG_DIR_NAME);
+	if (TRUST_REQUIRING_PROJECT_CONFIG_RESOURCES.some((entry) => existsSync(join(configDir, entry)))) {
+		return true;
+	}
+
+	while (true) {
+		const agentsSkillsDir = join(currentDir, ".agents", "skills");
+		if (agentsSkillsDir !== userAgentsSkillsDir && existsSync(agentsSkillsDir)) {
+			return true;
+		}
+
+		const parentDir = dirname(currentDir);
+		if (parentDir === currentDir) {
+			return false;
+		}
+		currentDir = parentDir;
+	}
+}
+
+export class ProjectTrustStore {
+	private trustPath: string;
+
+	constructor(agentDir: string) {
+		this.trustPath = join(resolvePath(agentDir), "trust.json");
+	}
+
+	get(cwd: string): ProjectTrustDecision {
+		return this.getEntry(cwd)?.decision ?? null;
+	}
+
+	getEntry(cwd: string): ProjectTrustStoreEntry | null {
+		return withTrustFileLock(this.trustPath, () => {
+			const data = readTrustFile(this.trustPath);
+			return findNearestTrustEntry(data, cwd);
+		});
+	}
+
+	set(cwd: string, decision: ProjectTrustDecision): void {
+		this.setMany([{ path: cwd, decision }]);
+	}
+
+	setMany(decisions: ProjectTrustUpdate[]): void {
+		withTrustFileLock(this.trustPath, () => {
+			const data = readTrustFile(this.trustPath);
+			for (const { path, decision } of decisions) {
+				const key = normalizeCwd(path);
+				if (decision === null) {
+					delete data[key];
+				} else {
+					data[key] = decision;
+				}
+			}
+			writeTrustFile(this.trustPath, data);
+		});
+	}
+}

package/packages/agent/src/index.ts

@@ -0,0 +1,287 @@
+
+// Config paths
+export {
+	CONFIG_DIR_NAME,
+	getAgentDir,
+	getPackageDir,
+	VERSION,
+} from "./config.ts";
+export {
+	AgentSession,
+	type AgentSessionConfig,
+	type AgentSessionEvent,
+	type AgentSessionEventListener,
+	type ModelCycleResult,
+	type ParsedSkillBlock,
+	type PromptOptions,
+	parseSkillBlock,
+	type SessionStats,
+} from "./core/agent-session.ts";
+export { readStoredCredential } from "./core/auth-storage.ts";
+// Compaction
+export {
+	type BranchPreparation,
+	type BranchSummaryResult,
+	type CollectEntriesResult,
+	type CompactionResult,
+	type CutPointResult,
+	calculateContextTokens,
+	collectEntriesForBranchSummary,
+	compact,
+	DEFAULT_COMPACTION_SETTINGS,
+	estimateTokens,
+	type FileOperations,
+	findCutPoint,
+	findTurnStartIndex,
+	type GenerateBranchSummaryOptions,
+	generateBranchSummary,
+	generateSummary,
+	getLastAssistantUsage,
+	prepareBranchEntries,
+	serializeConversation,
+	shouldCompact,
+} from "./core/compaction/index.ts";
+export { createEventBus, type EventBus, type EventBusController } from "./core/event-bus.ts";
+// Extension system
+export type {
+	AgentEndEvent,
+	AgentSettledEvent,
+	AgentStartEvent,
+	AgentToolResult,
+	AgentToolUpdateCallback,
+	BashToolCallEvent,
+	BeforeAgentStartEvent,
+	BeforeAgentStartEventResult,
+	BeforeProviderHeadersEvent,
+	BeforeProviderRequestEvent,
+	BeforeProviderRequestEventResult,
+	BuildSystemPromptOptions,
+	CompactOptions,
+	ContextEvent,
+	ContextUsage,
+	CustomToolCallEvent,
+	EditToolCallEvent,
+	EntryRenderOptions,
+	ExecOptions,
+	ExecResult,
+	Extension,
+	ExtensionActions,
+	ExtensionAPI,
+	ExtensionCommandContext,
+	ExtensionCommandContextActions,
+	ExtensionContext,
+	ExtensionContextActions,
+	ExtensionError,
+	ExtensionEvent,
+	ExtensionFactory,
+	ExtensionFactoryContext,
+	ExtensionFactorySettlementObserver,
+	ExtensionFlag,
+	ExtensionHandler,
+	ExtensionRuntime,
+	ExtensionUIContext,
+	ExtensionUIDialogOptions,
+	ExtensionWidgetOptions,
+	InlineExtension,
+	InputEvent,
+	InputEventResult,
+	InputSource,
+	LoadExtensionsResult,
+	MessageRenderOptions,
+	ProjectTrustContext,
+	ProjectTrustEvent,
+	ProjectTrustEventDecision,
+	ProjectTrustEventResult,
+	ProjectTrustHandler,
+	ProviderConfig,
+	ProviderModelConfig,
+	ReadToolCallEvent,
+	RegisteredCommand,
+	RegisteredTool,
+	ResolvedCommand,
+	SessionBeforeCompactEvent,
+	SessionBeforeForkEvent,
+	SessionBeforeSwitchEvent,
+	SessionBeforeTreeEvent,
+	SessionCompactEvent,
+	SessionInfoChangedEvent,
+	SessionShutdownEvent,
+	SessionStartEvent,
+	SessionTreeEvent,
+	SlashCommandInfo,
+	SlashCommandSource,
+	SourceInfo,
+	TerminalInputHandler,
+	ToolCallEvent,
+	ToolCallEventResult,
+	ToolDefinition,
+	ToolExecutionMode,
+	ToolInfo,
+	ToolRenderResultOptions,
+	ToolResultEvent,
+	TurnEndEvent,
+	TurnStartEvent,
+	UserBashEvent,
+	UserBashEventResult,
+	WidgetPlacement,
+	WorkingIndicatorOptions,
+	WriteToolCallEvent,
+} from "./core/extensions/index.ts";
+export {
+	createExtensionRuntime,
+	defineTool,
+	discoverAndLoadExtensions,
+	ExtensionRunner,
+	isBashToolResult,
+	isEditToolResult,
+	isReadToolResult,
+	isToolCallEventType,
+	isWriteToolResult,
+	wrapRegisteredTool,
+	wrapRegisteredTools,
+} from "./core/extensions/index.ts";
+// Footer data provider (git branch + extension statuses - data not otherwise available to extensions)
+export type { ReadonlyFooterDataProvider } from "./core/footer-data-provider.ts";
+export { convertToLlm } from "./core/messages.ts";
+export { ModelRegistry } from "./core/model-registry.ts";
+export {
+	type ModelScopeDiagnostic,
+	type ResolveCliModelResult,
+	type ResolveModelScopeResult,
+	resolveCliModel,
+	resolveModelScopeWithDiagnostics,
+	type ScopedModel,
+} from "./core/model-resolver.ts";
+export {
+	type CreateModelRuntimeOptions,
+	ModelRuntime,
+	type ModelRuntimeAuthOverrides,
+} from "./core/model-runtime.ts";
+export type {
+	PackageManager,
+	PathMetadata,
+	ProgressCallback,
+	ProgressEvent,
+	ResolvedPaths,
+	ResolvedResource,
+} from "./core/package-manager.ts";
+export { DefaultPackageManager } from "./core/package-manager.ts";
+export type { ResourceCollision, ResourceDiagnostic, ResourceLoader } from "./core/resource-loader.ts";
+export { DefaultResourceLoader, loadProjectContextFiles } from "./core/resource-loader.ts";
+// SDK for programmatic usage
+export {
+	AgentSessionRuntime,
+	DEFAULT_SESSION_SHUTDOWN_TIMEOUT_MS,
+	type AgentSessionRuntimeDiagnostic,
+	type AgentSessionServices,
+	type CreateAgentSessionFromServicesOptions,
+	type CreateAgentSessionOptions,
+	type CreateAgentSessionResult,
+	type CreateAgentSessionRuntimeFactory,
+	type CreateAgentSessionRuntimeResult,
+	type CreateAgentSessionServicesOptions,
+	// Factory
+	createAgentSession,
+	createAgentSessionFromServices,
+	createAgentSessionRuntime,
+	createAgentSessionServices,
+	createBashTool,
+	// Tool factories (for custom cwd)
+	createCodingTools,
+	createEditTool,
+	createReadTool,
+	createWriteTool,
+	type PromptTemplate,
+} from "./core/sdk.ts";
+export {
+	type BranchSummaryEntry,
+	buildContextEntries,
+	buildSessionContext,
+	type CompactionEntry,
+	CURRENT_SESSION_VERSION,
+	type CustomEntry,
+	type CustomMessageEntry,
+	type FileEntry,
+	getLatestCompactionEntry,
+	type ModelChangeEntry,
+	migrateSessionEntries,
+	type NewSessionOptions,
+	parseSessionEntries,
+	type SessionContext,
+	type SessionEntry,
+	type SessionEntryBase,
+	type SessionHeader,
+	type SessionInfo,
+	type SessionInfoEntry,
+	SessionManager,
+	type SessionMessageEntry,
+	type SessionTreeNode,
+	sessionEntryToContextMessages,
+	type ThinkingLevelChangeEntry,
+} from "./core/session-manager.ts";
+export {
+	type CompactionSettings,
+	type DefaultProjectTrust,
+	type ImageSettings,
+	type PackageSource,
+	type RetrySettings,
+	SettingsManager,
+	type SettingsManagerCreateOptions,
+} from "./core/settings-manager.ts";
+// Skills
+export {
+	formatSkillsForPrompt,
+	type LoadSkillsFromDirOptions,
+	type LoadSkillsResult,
+	loadSkills,
+	loadSkillsFromDir,
+	type Skill,
+	type SkillFrontmatter,
+} from "./core/skills.ts";
+export { createSyntheticSourceInfo } from "./core/source-info.ts";
+export { type EditDiffResult, generateDiffString, generateUnifiedPatch } from "./core/tools/edit-diff.ts";
+// Tools
+export {
+	type BashOperations,
+	type BashSpawnContext,
+	type BashSpawnHook,
+	type BashToolDetails,
+	type BashToolInput,
+	type BashToolOptions,
+	createBashToolDefinition,
+	createEditToolDefinition,
+	createLocalBashOperations,
+	createReadToolDefinition,
+	createWriteToolDefinition,
+	DEFAULT_MAX_BYTES,
+	DEFAULT_MAX_LINES,
+	type EditOperations,
+	type EditToolDetails,
+	type EditToolInput,
+	type EditToolOptions,
+	formatSize,
+	type ReadOperations,
+	type ReadToolDetails,
+	type ReadToolInput,
+	type ReadToolOptions,
+	type ToolsOptions,
+	type TruncationOptions,
+	type TruncationResult,
+	truncateHead,
+	truncateLine,
+	truncateTail,
+	type WriteOperations,
+	type WriteToolInput,
+	type WriteToolOptions,
+	withFileMutationQueue,
+} from "./core/tools/index.ts";
+export {
+	hasTrustRequiringProjectResources,
+	type ProjectTrustDecision,
+	ProjectTrustStore,
+	type ProjectTrustStoreEntry,
+	type ProjectTrustUpdate,
+} from "./core/trust-manager.ts";
+export { parseFrontmatter, stripFrontmatter } from "./utils/frontmatter.ts";
+// Shell utilities
+export { getShellConfig, killProcessTree, type ShellConfig } from "./utils/shell.ts";

package/packages/agent/src/utils/ansi.ts

@@ -0,0 +1,60 @@
+/*
+ * Portions of this file are derived from:
+ * - ansi-regex (https://github.com/chalk/ansi-regex)
+ * - strip-ansi (https://github.com/chalk/strip-ansi)
+ *
+ * MIT License
+ *
+ * Copyright (c) Sindre Sorhus <sindresorhus@gmail.com> (https://sindresorhus.com)
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+function ansiRegex({ onlyFirst = false }: { onlyFirst?: boolean } = {}): RegExp {
+	// Valid string terminator sequences are BEL, ESC\, and 0x9c
+	const ST = "(?:\\u0007|\\u001B\\u005C|\\u009C)";
+
+	// OSC sequences only: ESC ] ... ST (non-greedy until the first ST)
+	const osc = `(?:\\u001B\\][\\s\\S]*?${ST})`;
+
+	// CSI and related: ESC/C1, optional intermediates, optional params (supports ; and :) then final byte
+	const csi = "[\\u001B\\u009B][[\\]()#;?]*(?:\\d{1,4}(?:[;:]\\d{0,4})*)?[\\dA-PR-TZcf-nq-uy=><~]";
+
+	const pattern = `${osc}|${csi}`;
+
+	return new RegExp(pattern, onlyFirst ? undefined : "g");
+}
+
+const regex = ansiRegex();
+
+export function stripAnsi(value: string): string {
+	if (typeof value !== "string") {
+		throw new TypeError(`Expected a \`string\`, got \`${typeof value}\``);
+	}
+
+	// Fast path: ANSI codes require ESC (7-bit) or CSI (8-bit) introducer
+	if (!value.includes("\u001B") && !value.includes("\u009B")) {
+		return value;
+	}
+
+	// Even though the regex is global, we don't need to reset the `.lastIndex`
+	// because unlike `.exec()` and `.test()`, `.replace()` does it automatically
+	// and doing it manually has a performance penalty.
+	return value.replace(regex, "");
+}