@schlenkr/ragents 0.1.5 → 0.1.7

package/packages/agent/src/core/compaction/branch-summarization.ts

@@ -1,372 +0,0 @@
-/**
- * Branch summarization for tree navigation.
- *
- * When navigating to a different point in the session tree, this generates
- * a summary of the branch being left so context isn't lost.
- */
-
-import type { AgentMessage, StreamFn } from "@aicontainer/agent-core";
-import type { Model, SimpleStreamOptions } from "@aicontainer/ai";
-import { completeSimple } from "@aicontainer/ai";
-import {
-	convertToLlm,
-	createBranchSummaryMessage,
-	createCompactionSummaryMessage,
-	createCustomMessage,
-} from "../messages.ts";
-import type { ReadonlySessionManager, SessionEntry } from "../session-manager.ts";
-import { estimateTokens } from "./compaction.ts";
-import {
-	computeFileLists,
-	createFileOps,
-	extractFileOpsFromMessage,
-	type FileOperations,
-	formatFileOperations,
-	SUMMARIZATION_SYSTEM_PROMPT,
-	serializeConversation,
-	collectUserAttachments,
-} from "./utils.ts";
-
-// ============================================================================
-// Types
-// ============================================================================
-
-export interface BranchSummaryResult {
-	summary?: string;
-	readFiles?: string[];
-	modifiedFiles?: string[];
-	aborted?: boolean;
-	error?: string;
-}
-
-/** Details stored in BranchSummaryEntry.details for file tracking */
-export interface BranchSummaryDetails {
-	readFiles: string[];
-	modifiedFiles: string[];
-}
-
-export type { FileOperations } from "./utils.ts";
-
-export interface BranchPreparation {
-	/** Messages extracted for summarization, in chronological order */
-	messages: AgentMessage[];
-	/** File operations extracted from tool calls */
-	fileOps: FileOperations;
-	/** Total estimated tokens in messages */
-	totalTokens: number;
-}
-
-export interface CollectEntriesResult {
-	/** Entries to summarize, in chronological order */
-	entries: SessionEntry[];
-	/** Common ancestor between old and new position, if any */
-	commonAncestorId: string | null;
-}
-
-export interface GenerateBranchSummaryOptions {
-	/** Model to use for summarization */
-	model: Model<any>;
-	/** API key for the model */
-	apiKey?: string;
-	/** Request headers for the model */
-	headers?: Record<string, string>;
-	/** Provider-scoped environment values for the model */
-	env?: Record<string, string>;
-	/** Abort signal for cancellation */
-	signal: AbortSignal;
-	/** Optional custom instructions for summarization */
-	customInstructions?: string;
-	/** If true, customInstructions replaces the default prompt instead of being appended */
-	replaceInstructions?: boolean;
-	/** Tokens reserved for prompt + LLM response (default 16384) */
-	reserveTokens?: number;
-	/** Optional session stream function. Used to preserve SDK request behavior without mutating agent state. */
-	streamFn?: StreamFn;
-}
-
-// ============================================================================
-// Entry Collection
-// ============================================================================
-
-/**
- * Collect entries that should be summarized when navigating from one position to another.
- *
- * Walks from oldLeafId back to the common ancestor with targetId, collecting entries
- * along the way. Does NOT stop at compaction boundaries - those are included and their
- * summaries become context.
- *
- * @param session - Session manager (read-only access)
- * @param oldLeafId - Current position (where we're navigating from)
- * @param targetId - Target position (where we're navigating to)
- * @returns Entries to summarize and the common ancestor
- */
-export function collectEntriesForBranchSummary(
-	session: ReadonlySessionManager,
-	oldLeafId: string | null,
-	targetId: string,
-): CollectEntriesResult {
-	// If no old position, nothing to summarize
-	if (!oldLeafId) {
-		return { entries: [], commonAncestorId: null };
-	}
-
-	// Find common ancestor (deepest node that's on both paths)
-	const oldPath = new Set(session.getBranch(oldLeafId).map((e) => e.id));
-	const targetPath = session.getBranch(targetId);
-
-	// targetPath is root-first, so iterate backwards to find deepest common ancestor
-	let commonAncestorId: string | null = null;
-	for (let i = targetPath.length - 1; i >= 0; i--) {
-		if (oldPath.has(targetPath[i].id)) {
-			commonAncestorId = targetPath[i].id;
-			break;
-		}
-	}
-
-	// Collect entries from old leaf back to common ancestor
-	const entries: SessionEntry[] = [];
-	let current: string | null = oldLeafId;
-
-	while (current && current !== commonAncestorId) {
-		const entry = session.getEntry(current);
-		if (!entry) break;
-		entries.push(entry);
-		current = entry.parentId;
-	}
-
-	// Reverse to get chronological order
-	entries.reverse();
-
-	return { entries, commonAncestorId };
-}
-
-// ============================================================================
-// Entry to Message Conversion
-// ============================================================================
-
-/**
- * Extract AgentMessage from a session entry.
- * Similar to getMessageFromEntry in compaction.ts but also handles compaction entries.
- */
-function getMessageFromEntry(entry: SessionEntry): AgentMessage | undefined {
-	switch (entry.type) {
-		case "message":
-			// Skip tool results - context is in assistant's tool call
-			if (entry.message.role === "toolResult") return undefined;
-			return entry.message;
-
-		case "custom_message":
-			return createCustomMessage(entry.customType, entry.content, entry.display, entry.details, entry.timestamp);
-
-		case "branch_summary":
-			return createBranchSummaryMessage(entry.summary, entry.fromId, entry.timestamp);
-
-		case "compaction":
-			return createCompactionSummaryMessage(entry.summary, entry.tokensBefore, entry.timestamp);
-
-		// These don't contribute to conversation content
-		case "thinking_level_change":
-		case "model_change":
-		case "custom":
-		case "label":
-		case "session_info":
-			return undefined;
-	}
-}
-
-/**
- * Prepare entries for summarization with token budget.
- *
- * Walks entries from NEWEST to OLDEST, adding messages until we hit the token budget.
- * This ensures we keep the most recent context when the branch is too long.
- *
- * Also collects file operations from:
- * - Tool calls in assistant messages
- * - Existing branch_summary entries' details (for cumulative tracking)
- *
- * @param entries - Entries in chronological order
- * @param tokenBudget - Maximum tokens to include (0 = no limit)
- */
-export function prepareBranchEntries(entries: SessionEntry[], tokenBudget: number = 0): BranchPreparation {
-	const messages: AgentMessage[] = [];
-	const fileOps = createFileOps();
-	let totalTokens = 0;
-
-	// First pass: collect file ops from ALL entries (even if they don't fit in token budget)
-	// This ensures we capture cumulative file tracking from nested branch summaries
-	// Only extract from agent-generated summaries (fromHook !== true), not extension-generated ones
-	for (const entry of entries) {
-		if (entry.type === "branch_summary" && !entry.fromHook && entry.details) {
-			const details = entry.details as BranchSummaryDetails;
-			if (Array.isArray(details.readFiles)) {
-				for (const f of details.readFiles) fileOps.read.add(f);
-			}
-			if (Array.isArray(details.modifiedFiles)) {
-				// Modified files go into both edited and written for proper deduplication
-				for (const f of details.modifiedFiles) {
-					fileOps.edited.add(f);
-				}
-			}
-		}
-	}
-
-	// Second pass: walk from newest to oldest, adding messages until token budget
-	for (let i = entries.length - 1; i >= 0; i--) {
-		const entry = entries[i];
-		const message = getMessageFromEntry(entry);
-		if (!message) continue;
-
-		// Extract file ops from assistant messages (tool calls)
-		extractFileOpsFromMessage(message, fileOps);
-
-		const tokens = estimateTokens(message);
-
-		// Check budget before adding
-		if (tokenBudget > 0 && totalTokens + tokens > tokenBudget) {
-			// If this is a summary entry, try to fit it anyway as it's important context
-			if (entry.type === "compaction" || entry.type === "branch_summary") {
-				if (totalTokens < tokenBudget * 0.9) {
-					messages.unshift(message);
-					totalTokens += tokens;
-				}
-			}
-			// Stop - we've hit the budget
-			break;
-		}
-
-		messages.unshift(message);
-		totalTokens += tokens;
-	}
-
-	return { messages, fileOps, totalTokens };
-}
-
-// ============================================================================
-// Summary Generation
-// ============================================================================
-
-const BRANCH_SUMMARY_PREAMBLE = `The user explored a different conversation branch before returning here.
-Summary of that exploration:
-
-`;
-
-const BRANCH_SUMMARY_PROMPT = `Create a structured summary of this conversation branch for context when returning later.
-
-Use this EXACT format:
-
-## Goal
-[What was the user trying to accomplish in this branch?]
-
-## Constraints & Preferences
-- [Any constraints, preferences, or requirements mentioned]
-- [Or "(none)" if none were mentioned]
-
-## Progress
-### Done
-- [x] [Completed tasks/changes]
-
-### In Progress
-- [ ] [Work that was started but not finished]
-
-### Blocked
-- [Issues preventing progress, if any]
-
-## Key Decisions
-- **[Decision]**: [Brief rationale]
-
-## Next Steps
-1. [What should happen next to continue this work]
-
-Keep each section concise. Preserve exact file paths, function names, and error messages.`;
-
-/**
- * Generate a summary of abandoned branch entries.
- *
- * @param entries - Session entries to summarize (chronological order)
- * @param options - Generation options
- */
-export async function generateBranchSummary(
-	entries: SessionEntry[],
-	options: GenerateBranchSummaryOptions,
-): Promise<BranchSummaryResult> {
-	const {
-		model,
-		apiKey,
-		headers,
-		env,
-		signal,
-		customInstructions,
-		replaceInstructions,
-		reserveTokens = 16384,
-		streamFn,
-	} = options;
-
-	// Token budget = context window minus reserved space for prompt + response
-	const contextWindow = model.contextWindow || 128000;
-	const tokenBudget = contextWindow - reserveTokens;
-
-	const { messages, fileOps } = prepareBranchEntries(entries, tokenBudget);
-
-	if (messages.length === 0) {
-		return { summary: "No content to summarize" };
-	}
-
-	// Transform to LLM-compatible messages, then serialize to text
-	// Serialization prevents the model from treating it as a conversation to continue
-	const llmMessages = convertToLlm(messages);
-	const conversationText = serializeConversation(llmMessages);
-
-	// Build prompt
-	let instructions: string;
-	if (replaceInstructions && customInstructions) {
-		instructions = customInstructions;
-	} else if (customInstructions) {
-		instructions = `${BRANCH_SUMMARY_PROMPT}\n\nAdditional focus: ${customInstructions}`;
-	} else {
-		instructions = BRANCH_SUMMARY_PROMPT;
-	}
-	const promptText = `<conversation>\n${conversationText}\n</conversation>\n\n${instructions}`;
-
-	const summarizationMessages = [
-		{
-			role: "user" as const,
-			content: [{ type: "text" as const, text: promptText }, ...collectUserAttachments(llmMessages)],
-			timestamp: Date.now(),
-		},
-	];
-
-	// Call LLM for summarization. Prefer the session stream function so SDK
-	// request behavior (timeouts, retries, attribution headers) stays consistent
-	// without running through agent state/events.
-	const context = { systemPrompt: SUMMARIZATION_SYSTEM_PROMPT, messages: summarizationMessages };
-	const requestOptions: SimpleStreamOptions = { apiKey, headers, env, signal, maxTokens: 2048 };
-	const response = streamFn
-		? await (await streamFn(model, context, requestOptions)).result()
-		: await completeSimple(model, context, requestOptions);
-
-	// Check if aborted or errored
-	if (response.stopReason === "aborted") {
-		return { aborted: true };
-	}
-	if (response.stopReason === "error") {
-		return { error: response.errorMessage || "Summarization failed" };
-	}
-
-	let summary = response.content
-		.filter((c): c is { type: "text"; text: string } => c.type === "text")
-		.map((c) => c.text)
-		.join("\n");
-
-	// Prepend preamble to provide context about the branch summary
-	summary = BRANCH_SUMMARY_PREAMBLE + summary;
-
-	// Compute file lists and append to summary
-	const { readFiles, modifiedFiles } = computeFileLists(fileOps);
-	summary += formatFileOperations(readFiles, modifiedFiles);
-
-	return {
-		summary: summary || "No summary generated",
-		readFiles,
-		modifiedFiles,
-	};
-}

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

@@ -1,3 +0,0 @@
-import type { ThinkingLevel } from "@aicontainer/agent-core";
-
-export const DEFAULT_THINKING_LEVEL: ThinkingLevel = "medium";

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

@@ -1,15 +0,0 @@
-export interface ResourceCollision {
-	resourceType: "extension" | "skill" | "prompt" | "theme";
-	name: string; // skill name, command/tool/flag name, prompt name, theme name
-	winnerPath: string;
-	loserPath: string;
-	winnerSource?: string; // e.g., "npm:foo", "git:...", "local"
-	loserSource?: string;
-}
-
-export interface ResourceDiagnostic {
-	type: "warning" | "error" | "collision";
-	message: string;
-	path?: string;
-	collision?: ResourceCollision;
-}

package/packages/agent/src/core/event-bus.ts

@@ -1,33 +0,0 @@
-import { EventEmitter } from "node:events";
-
-export interface EventBus {
-	emit(channel: string, data: unknown): void;
-	on(channel: string, handler: (data: unknown) => void): () => void;
-}
-
-export interface EventBusController extends EventBus {
-	clear(): void;
-}
-
-export function createEventBus(): EventBusController {
-	const emitter = new EventEmitter();
-	return {
-		emit: (channel, data) => {
-			emitter.emit(channel, data);
-		},
-		on: (channel, handler) => {
-			const safeHandler = async (data: unknown) => {
-				try {
-					await handler(data);
-				} catch (err) {
-					console.error(`Event handler error (${channel}):`, err);
-				}
-			};
-			emitter.on(channel, safeHandler);
-			return () => emitter.off(channel, safeHandler);
-		},
-		clear: () => {
-			emitter.removeAllListeners();
-		},
-	};
-}

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

@@ -1,107 +0,0 @@
-/**
- * Shared command execution utilities for extensions and custom tools.
- */
-
-import { spawn } from "node:child_process";
-import { waitForChildProcess } from "../utils/child-process.ts";
-
-/**
- * Options for executing shell commands.
- */
-export interface ExecOptions {
-	/** AbortSignal to cancel the command */
-	signal?: AbortSignal;
-	/** Timeout in milliseconds */
-	timeout?: number;
-	/** Working directory */
-	cwd?: string;
-}
-
-/**
- * Result of executing a shell command.
- */
-export interface ExecResult {
-	stdout: string;
-	stderr: string;
-	code: number;
-	killed: boolean;
-}
-
-/**
- * Execute a shell command and return stdout/stderr/code.
- * Supports timeout and abort signal.
- */
-export async function execCommand(
-	command: string,
-	args: string[],
-	cwd: string,
-	options?: ExecOptions,
-): Promise<ExecResult> {
-	return new Promise((resolve) => {
-		const proc = spawn(command, args, {
-			cwd,
-			shell: false,
-			stdio: ["ignore", "pipe", "pipe"],
-		});
-
-		let stdout = "";
-		let stderr = "";
-		let killed = false;
-		let timeoutId: NodeJS.Timeout | undefined;
-
-		const killProcess = () => {
-			if (!killed) {
-				killed = true;
-				proc.kill("SIGTERM");
-				// Force kill after 5 seconds if SIGTERM doesn't work
-				setTimeout(() => {
-					if (!proc.killed) {
-						proc.kill("SIGKILL");
-					}
-				}, 5000);
-			}
-		};
-
-		// Handle abort signal
-		if (options?.signal) {
-			if (options.signal.aborted) {
-				killProcess();
-			} else {
-				options.signal.addEventListener("abort", killProcess, { once: true });
-			}
-		}
-
-		// Handle timeout
-		if (options?.timeout && options.timeout > 0) {
-			timeoutId = setTimeout(() => {
-				killProcess();
-			}, options.timeout);
-		}
-
-		proc.stdout?.on("data", (data) => {
-			stdout += data.toString();
-		});
-
-		proc.stderr?.on("data", (data) => {
-			stderr += data.toString();
-		});
-
-		// Wait for process termination without hanging on inherited stdio handles
-		// held open by detached descendants.
-		waitForChildProcess(proc)
-			.then((code) => {
-				if (timeoutId) clearTimeout(timeoutId);
-				if (options?.signal) {
-					options.signal.removeEventListener("abort", killProcess);
-				}
-				resolve({ stdout, stderr, code: code ?? 0, killed });
-			})
-			.catch((_err) => {
-				if (timeoutId) clearTimeout(timeoutId);
-				if (options?.signal) {
-					options.signal.removeEventListener("abort", killProcess);
-				}
-				resolve({ stdout, stderr, code: 1, killed });
-			});
-	});
-}

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

@@ -1,3 +0,0 @@
-export function areExperimentalFeaturesEnabled(): boolean {
-	return process.env.AGENT_EXPERIMENTAL === "1";
-}

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

@@ -1,149 +0,0 @@
-/**
- * Extension system for lifecycle events and custom tools.
- */
-
-export type { SlashCommandInfo, SlashCommandSource } from "../slash-commands.ts";
-export type { SourceInfo } from "../source-info.ts";
-export {
-	createExtensionRuntime,
-	discoverAndLoadExtensions,
-	loadExtensionFromFactory,
-	loadExtensions,
-} from "./loader.ts";
-export type {
-	ExtensionErrorListener,
-	ForkHandler,
-	NavigateTreeHandler,
-	NewSessionHandler,
-	ShutdownHandler,
-	SwitchSessionHandler,
-} from "./runner.ts";
-export { ExtensionRunner } from "./runner.ts";
-export type {
-	AfterProviderResponseEvent,
-	AgentEndEvent,
-	AgentSettledEvent,
-	AgentStartEvent,
-	AgentToolResult,
-	AgentToolUpdateCallback,
-	AppendEntryHandler,
-	BashToolCallEvent,
-	BashToolResultEvent,
-	BeforeAgentStartEvent,
-	BeforeAgentStartEventResult,
-	BeforeProviderHeadersEvent,
-	BeforeProviderRequestEvent,
-	BeforeProviderRequestEventResult,
-	BuildSystemPromptOptions,
-	CompactOptions,
-	ContextEvent,
-	ContextEventResult,
-	ContextUsage,
-	CustomToolCallEvent,
-	CustomToolResultEvent,
-	EditToolCallEvent,
-	EditToolResultEvent,
-	EntryRenderOptions,
-	ExecOptions,
-	ExecResult,
-	Extension,
-	ExtensionActions,
-	ExtensionAPI,
-	ExtensionCommandContext,
-	ExtensionCommandContextActions,
-	ExtensionContext,
-	ExtensionContextActions,
-	ExtensionError,
-	ExtensionEvent,
-	ExtensionFactory,
-	ExtensionFactoryContext,
-	ExtensionFactorySettlementObserver,
-	ExtensionFlag,
-	ExtensionHandler,
-	ExtensionMode,
-	ExtensionRuntime,
-	ExtensionUIContext,
-	ExtensionUIDialogOptions,
-	ExtensionWidgetOptions,
-	GetActiveToolsHandler,
-	GetAllToolsHandler,
-	GetCommandsHandler,
-	GetThinkingLevelHandler,
-	InlineExtension,
-	InputEvent,
-	InputEventResult,
-	InputSource,
-	LoadExtensionsResult,
-	MessageEndEvent,
-	MessageRenderOptions,
-	MessageStartEvent,
-	MessageUpdateEvent,
-	ModelSelectEvent,
-	ModelSelectSource,
-	ProjectTrustContext,
-	ProjectTrustEvent,
-	ProjectTrustEventDecision,
-	ProjectTrustEventResult,
-	ProjectTrustHandler,
-	ProviderConfig,
-	ProviderModelConfig,
-	ReadToolCallEvent,
-	ReadToolResultEvent,
-	RegisteredCommand,
-	RegisteredTool,
-	ReplacedSessionContext,
-	ResolvedCommand,
-	ResourcesDiscoverEvent,
-	ResourcesDiscoverResult,
-	SendMessageHandler,
-	SendUserMessageHandler,
-	SessionBeforeCompactEvent,
-	SessionBeforeCompactResult,
-	SessionBeforeForkEvent,
-	SessionBeforeForkResult,
-	SessionBeforeSwitchEvent,
-	SessionBeforeSwitchResult,
-	SessionBeforeTreeEvent,
-	SessionBeforeTreeResult,
-	SessionCompactEvent,
-	SessionEvent,
-	SessionInfoChangedEvent,
-	SessionShutdownEvent,
-	SessionStartEvent,
-	SessionTreeEvent,
-	SetActiveToolsHandler,
-	SetLabelHandler,
-	SetModelHandler,
-	SetThinkingLevelHandler,
-	TerminalInputHandler,
-	ToolCallEvent,
-	ToolCallEventResult,
-	ToolDefinition,
-	ToolExecutionEndEvent,
-	ToolExecutionMode,
-	ToolExecutionStartEvent,
-	ToolExecutionUpdateEvent,
-	ToolInfo,
-	ToolRenderResultOptions,
-	ToolResultEvent,
-	ToolResultEventResult,
-	TreePreparation,
-	TurnEndEvent,
-	TurnStartEvent,
-	UserBashEvent,
-	UserBashEventResult,
-	WidgetPlacement,
-	WorkingIndicatorOptions,
-	WriteToolCallEvent,
-	WriteToolResultEvent,
-} from "./types.ts";
-// Type guards
-export {
-	defineTool,
-	isBashToolResult,
-	isEditToolResult,
-	isReadToolResult,
-	isToolCallEventType,
-	isWriteToolResult,
-} from "./types.ts";
-export { wrapRegisteredTool, wrapRegisteredTools } from "./wrapper.ts";