@schlenkr/ragents 0.1.7 → 0.1.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@schlenkr/ragents",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "RAgents-Host: Server, Engine, Plugins und Werkzeuge ohne Quell-Checkout",
   "keywords": [
     "agents",
@@ -70,6 +70,6 @@
     "yaml": "2.9.0"
   },
   "ragents": {
-    "hostVersion": "765802e9cb0252b2a312b2b1b09a557ef8bf13cc"
+    "hostVersion": "f865fbf276b702ad64bbfa1af75e91d7effdcf41"
   }
 }

package/packages/agent/dist/core/agent-settings.d.ts

@@ -1,10 +1,5 @@
-/** The few knobs of an agent's runtime; everything else is fixed. */
+/** The few knobs of an agent's runtime; compaction belongs to the model, everything else is fixed. */
 export interface AgentSettings {
-    compaction: {
-        enabled: boolean;
-        reserveTokens: number;
-        keepRecentTokens: number;
-    };
     /** Retries after a retryable model error, with exponential backoff. */
     retry: {
         enabled: boolean;
@@ -19,7 +14,6 @@ export interface AgentSettings {
     };
 }
 export interface AgentSettingsInput {
-    compaction?: Partial<AgentSettings["compaction"]>;
     retry?: Partial<AgentSettings["retry"]>;
     providerRequest?: Partial<AgentSettings["providerRequest"]>;
 }

package/packages/agent/dist/core/compaction/compaction.d.ts

@@ -1,6 +1,6 @@
 /** Context compaction over the context log of one agent; pure functions, the caller persists the result. */
 import type { AgentMessage, StreamFn, ThinkingLevel } from "../../loop/index.ts";
-import type { Model, Usage } from "@ragents/ai";
+import type { Model, ModelCompaction, Usage } from "@ragents/ai";
 import { type ContextLogEntry } from "../context-log.ts";
 import { type FileOperations } from "./utils.ts";
 /** Result of compact(); the caller records it as a compaction entry. */
@@ -12,11 +12,17 @@ export interface CompactionResult {
     readFiles: string[];
     modifiedFiles: string[];
 }
-export interface CompactionSettings {
-    enabled: boolean;
-    reserveTokens: number;
-    keepRecentTokens: number;
-}
+/** The catalog standard of a model without own values: compact 16384 tokens below its context window. */
+export declare function catalogCompaction(model: Pick<Model<any>, "contextWindow">): ModelCompaction;
+/** Where the compaction values of a model come from. */
+export type CompactionSource = "model" | "catalog";
+/** The compaction values an agent applies on a model: its own, else the catalog standard. */
+export declare function compactionOf(model: Model<any>): {
+    values: ModelCompaction;
+    source: CompactionSource;
+};
+/** Why a value is no valid set of compaction values, or undefined; with a model also whether they fit its context window and output limit. */
+export declare function compactionProblem(value: unknown, model?: Pick<Model<any>, "contextWindow" | "maxTokens">): string | undefined;
 /**
  * Calculate total context tokens from usage.
  * Uses the native totalTokens field when available, falls back to computing from components.
@@ -33,10 +39,8 @@ export interface ContextUsageEstimate {
  * If there are messages after the last usage, estimate their tokens with estimateTokens.
  */
 export declare function estimateContextTokens(messages: AgentMessage[]): ContextUsageEstimate;
-/**
- * Check if compaction should trigger based on context usage.
- */
-export declare function shouldCompact(contextTokens: number, contextWindow: number, settings: CompactionSettings): boolean;
+/** Whether a context of this size lies above the compaction threshold. */
+export declare function shouldCompact(contextTokens: number, compaction: ModelCompaction): boolean;
 /**
  * Estimate token count for a message using chars/4 heuristic.
  * This is conservative (overestimates tokens).
@@ -58,7 +62,7 @@ export declare function findCutPoint(entries: ContextLogEntry[], startIndex: num
  * Generate a summary of the conversation using the LLM.
  * If previousSummary is provided, uses the update prompt to merge.
  */
-export declare function generateSummary(currentMessages: AgentMessage[], model: Model<any>, reserveTokens: number, apiKey: string | undefined, headers?: Record<string, string>, signal?: AbortSignal, customInstructions?: string, previousSummary?: string, thinkingLevel?: ThinkingLevel, streamFn?: StreamFn, env?: Record<string, string>): Promise<string>;
+export declare function generateSummary(currentMessages: AgentMessage[], model: Model<any>, summaryTokens: number, apiKey: string | undefined, headers?: Record<string, string>, signal?: AbortSignal, customInstructions?: string, previousSummary?: string, thinkingLevel?: ThinkingLevel, streamFn?: StreamFn, env?: Record<string, string>): Promise<string>;
 export interface CompactionPreparation {
     /** Id of the first entry to keep */
     firstKeptId: string;
@@ -73,10 +77,10 @@ export interface CompactionPreparation {
     previousSummary?: string;
     /** File operations extracted from messagesToSummarize */
     fileOps: FileOperations;
-    settings: CompactionSettings;
+    compaction: ModelCompaction;
 }
 /** Prepares a compaction of the whole context log; undefined when there is nothing to summarize. */
-export declare function prepareCompaction(entries: ContextLogEntry[], settings: CompactionSettings): CompactionPreparation | undefined;
+export declare function prepareCompaction(entries: ContextLogEntry[], compaction: ModelCompaction): CompactionPreparation | undefined;
 /** Summarizes a prepared compaction; the caller records the result. */
 export declare function compact(preparation: CompactionPreparation, model: Model<any>, apiKey: string | undefined, headers?: Record<string, string>, customInstructions?: string, signal?: AbortSignal, thinkingLevel?: ThinkingLevel, streamFn?: StreamFn, env?: Record<string, string>): Promise<CompactionResult>;
 //# sourceMappingURL=compaction.d.ts.map

package/packages/agent/dist/core/model-runtime.d.ts

@@ -1,13 +1,14 @@
-import { type Api, type AssistantMessage, type AssistantMessageEventStream, type AuthCheck, type AuthResult, type Context, type Model, type SimpleStreamOptions } from "@ragents/ai";
+import { type Api, type AssistantMessage, type AssistantMessageEventStream, type AuthCheck, type AuthResult, type Context, type Model, type ModelCompaction, type SimpleStreamOptions } from "@ragents/ai";
 import { type ProviderConfigInput } from "./provider-composer.ts";
-/** A name under which a model of another provider is offered; only the alias is visible to callers. */
+/** A name under which a model of another provider is offered, with its own compaction values; only the alias is visible to callers. */
 export interface ModelAlias {
     readonly alias: string;
     readonly upstream: string;
     readonly model: string;
+    readonly compaction: ModelCompaction;
 }
-/** The metadata of the target under the alias as id and name, with the alias provider as provider. */
-export declare function aliasedModel(providerId: string, alias: string, target: Model<Api>): Model<Api>;
+/** The metadata of the target under the alias as id and name, with the alias provider as provider and the alias's compaction values. */
+export declare function aliasedModel(providerId: string, entry: ModelAlias, target: Model<Api>): Model<Api>;
 /** The built-in providers plus the ones registered at runtime; a key comes from the registration or the environment. */
 export declare class ModelRuntime {
     private readonly models;

package/packages/agent/dist/core/provider-composer.d.ts

@@ -1,4 +1,4 @@
-import { type Api, type InputModality, type Model, type Provider } from "@ragents/ai";
+import { type Api, type InputModality, type Model, type ModelCompaction, type Provider } from "@ragents/ai";
 /** A provider registered at runtime: its models and a literal API key, over the built-in provider of the same id. */
 export interface ProviderConfigInput {
     name?: string;
@@ -17,6 +17,7 @@ export interface ProviderConfigInput {
         cost: Model<Api>["cost"];
         contextWindow: number;
         maxTokens: number;
+        compaction?: ModelCompaction;
         compat?: Model<Api>["compat"];
     }>;
 }

package/packages/agent/dist/core/tools/bash.d.ts

@@ -3,11 +3,14 @@ import type { ToolDefinition } from "../tool-definition.ts";
 import { type TruncationResult } from "./truncate.ts";
 export declare const BASH_MAX_BYTES: number;
 export declare const BASH_MAX_LINE_CHARS = 1000;
-declare const bashSchema: Type.TObject<{
+export declare const BASH_DEFAULT_TIMEOUT_SECONDS = 120;
+export declare const BASH_MAX_TIMEOUT_SECONDS = 600;
+declare const bashSchemaFor: (defaultTimeoutSeconds: number) => Type.TObject<{
     command: Type.TString;
     timeout: Type.TOptional<Type.TNumber>;
     cwd: Type.TOptional<Type.TString>;
 }>;
+type BashSchema = ReturnType<typeof bashSchemaFor>;
 export interface BashToolDetails {
     truncation?: TruncationResult;
     fullOutputPath?: string;
@@ -27,7 +30,8 @@ export interface BashOperations {
     exec: (command: string, cwd: string, options: {
         onData: (data: Buffer) => void;
         signal?: AbortSignal;
-        timeout?: number;
+        /** Seconds until the command is stopped. */
+        timeout: number;
         env?: NodeJS.ProcessEnv;
     }) => Promise<{
         exitCode: number | null;
@@ -52,7 +56,9 @@ export interface BashToolOptions {
     shellPath?: string;
     /** Hook to adjust command, cwd, or env before execution */
     spawnHook?: BashSpawnHook;
+    /** Timeout in seconds for a call without one, at most BASH_MAX_TIMEOUT_SECONDS. Default: BASH_DEFAULT_TIMEOUT_SECONDS */
+    defaultTimeoutSeconds?: number;
 }
-export declare function createBashToolDefinition(cwd: string, options?: BashToolOptions): ToolDefinition<typeof bashSchema, BashToolDetails | undefined>;
+export declare function createBashToolDefinition(cwd: string, options?: BashToolOptions): ToolDefinition<BashSchema, BashToolDetails | undefined>;
 export {};
 //# sourceMappingURL=bash.d.ts.map

package/packages/agent/dist/index.d.ts

@@ -1,7 +1,7 @@
 export { aliasedModel, type ModelAlias, ModelRuntime } from "./core/model-runtime.ts";
 export { type AgentSettings, type AgentSettingsInput, agentSettings } from "./core/agent-settings.ts";
 export { activeContextEntries, type ContextCompaction, type ContextLogEntry, contextMessages, latestCompaction, } from "./core/context-log.ts";
-export { calculateContextTokens, compact, estimateContextTokens, prepareCompaction, shouldCompact, } from "./core/compaction/index.ts";
+export { calculateContextTokens, compact, compactionOf, compactionProblem, type CompactionSource, estimateContextTokens, prepareCompaction, shouldCompact, } from "./core/compaction/index.ts";
 export { convertToLlm } from "./core/messages.ts";
 export { formatSkillsForPrompt, type Skill } from "./core/skills.ts";
 export { defineTool, type ToolDefinition } from "./core/tool-definition.ts";

package/packages/agent/src/core/agent-settings.ts

@@ -1,6 +1,5 @@
-/** The few knobs of an agent's runtime; everything else is fixed. */
+/** The few knobs of an agent's runtime; compaction belongs to the model, everything else is fixed. */
 export interface AgentSettings {
-	compaction: { enabled: boolean; reserveTokens: number; keepRecentTokens: number };
 	/** Retries after a retryable model error, with exponential backoff. */
 	retry: { enabled: boolean; maxRetries: number; baseDelayMs: number };
 	/** Timeout and retries of a single provider request; unset values leave the SDK defaults. */
@@ -8,13 +7,11 @@ export interface AgentSettings {
 }
 
 export interface AgentSettingsInput {
-	compaction?: Partial<AgentSettings["compaction"]>;
 	retry?: Partial<AgentSettings["retry"]>;
 	providerRequest?: Partial<AgentSettings["providerRequest"]>;
 }
 
 export const agentSettings = (input: AgentSettingsInput = {}): AgentSettings => ({
-	compaction: { enabled: true, reserveTokens: 16384, keepRecentTokens: 20000, ...input.compaction },
 	retry: { enabled: true, maxRetries: 3, baseDelayMs: 2000, ...input.retry },
 	providerRequest: { timeoutMs: 300_000, maxRetryDelayMs: 60_000, ...input.providerRequest },
 });

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

@@ -1,7 +1,7 @@
 /** Context compaction over the context log of one agent; pure functions, the caller persists the result. */
 
 import type { AgentMessage, StreamFn, ThinkingLevel } from "../../loop/index.ts";
-import type { AssistantMessage, Context, Model, SimpleStreamOptions, Usage } from "@ragents/ai";
+import type { AssistantMessage, Context, Model, ModelCompaction, SimpleStreamOptions, Usage } from "@ragents/ai";
 import { completeSimple } from "@ragents/ai";
 import { type ContextCompaction, type ContextLogEntry, contextEntryMessages, contextMessages } from "../context-log.ts";
 import { convertToLlm } from "../messages.ts";
@@ -42,15 +42,62 @@ export interface CompactionResult {
 }
 
 // ============================================================================
-// Types
+// Compaction values of a model
 // ============================================================================
 
-export interface CompactionSettings {
-	enabled: boolean;
-	reserveTokens: number;
-	keepRecentTokens: number;
+const CATALOG_RESERVE_TOKENS = 16384;
+
+/** The catalog standard of a model without own values: compact 16384 tokens below its context window. */
+export function catalogCompaction(model: Pick<Model<any>, "contextWindow">): ModelCompaction {
+	return {
+		threshold: model.contextWindow - CATALOG_RESERVE_TOKENS,
+		keepRecentTokens: 20000,
+		summaryTokens: Math.floor(0.8 * CATALOG_RESERVE_TOKENS),
+	};
+}
+
+/** Where the compaction values of a model come from. */
+export type CompactionSource = "model" | "catalog";
+
+/** The compaction values an agent applies on a model: its own, else the catalog standard. */
+export function compactionOf(model: Model<any>): { values: ModelCompaction; source: CompactionSource } {
+	return model.compaction
+		? { values: model.compaction, source: "model" }
+		: { values: catalogCompaction(model), source: "catalog" };
+}
+
+const COMPACTION_KEYS: readonly string[] = ["threshold", "keepRecentTokens", "summaryTokens"];
+
+/** Why a value is no valid set of compaction values, or undefined; with a model also whether they fit its context window and output limit. */
+export function compactionProblem(
+	value: unknown,
+	model?: Pick<Model<any>, "contextWindow" | "maxTokens">,
+): string | undefined {
+	if (!value || typeof value !== "object" || Array.isArray(value)) {
+		return "compaction needs threshold, keepRecentTokens and summaryTokens";
+	}
+	const fields = value as Record<string, unknown>;
+	const unknown = Object.keys(fields).find((key) => !COMPACTION_KEYS.includes(key));
+	if (unknown) return `compaction.${unknown} is not supported`;
+	const invalid = COMPACTION_KEYS.find((key) => !Number.isSafeInteger(fields[key]) || (fields[key] as number) < 1);
+	if (invalid) return `compaction.${invalid} must be a positive integer`;
+	const { threshold, keepRecentTokens, summaryTokens } = value as ModelCompaction;
+	if (keepRecentTokens + summaryTokens >= threshold) {
+		return `compaction: keepRecentTokens plus summaryTokens (${keepRecentTokens + summaryTokens}) must stay below threshold (${threshold})`;
+	}
+	if (!model) return undefined;
+	if (threshold + summaryTokens >= model.contextWindow) {
+		return `compaction: threshold plus summaryTokens (${threshold + summaryTokens}) must stay below the context window (${model.contextWindow})`;
+	}
+	if (model.maxTokens > 0 && summaryTokens > model.maxTokens) {
+		return `compaction.summaryTokens (${summaryTokens}) exceeds the output limit (${model.maxTokens})`;
+	}
+	return undefined;
 }
 
+/** The summary of a split turn's beginning gets five eighths of the summary budget, the ratio the forked runtime used. */
+const turnPrefixTokens = (summaryTokens: number): number => Math.round((summaryTokens * 5) / 8);
+
 // ============================================================================
 // Token calculation
 // ============================================================================
@@ -131,12 +178,9 @@ export function estimateContextTokens(messages: AgentMessage[]): ContextUsageEst
 	};
 }
 
-/**
- * Check if compaction should trigger based on context usage.
- */
-export function shouldCompact(contextTokens: number, contextWindow: number, settings: CompactionSettings): boolean {
-	if (!settings.enabled) return false;
-	return contextTokens > contextWindow - settings.reserveTokens;
+/** Whether a context of this size lies above the compaction threshold. */
+export function shouldCompact(contextTokens: number, compaction: ModelCompaction): boolean {
+	return contextTokens > compaction.threshold;
 }
 
 // ============================================================================
@@ -420,7 +464,7 @@ async function completeSummarization(
 export async function generateSummary(
 	currentMessages: AgentMessage[],
 	model: Model<any>,
-	reserveTokens: number,
+	summaryTokens: number,
 	apiKey: string | undefined,
 	headers?: Record<string, string>,
 	signal?: AbortSignal,
@@ -430,10 +474,7 @@ export async function generateSummary(
 	streamFn?: StreamFn,
 	env?: Record<string, string>,
 ): Promise<string> {
-	const maxTokens = Math.min(
-		Math.floor(0.8 * reserveTokens),
-		model.maxTokens > 0 ? model.maxTokens : Number.POSITIVE_INFINITY,
-	);
+	const maxTokens = Math.min(summaryTokens, model.maxTokens > 0 ? model.maxTokens : Number.POSITIVE_INFINITY);
 
 	// Use update prompt if we have a previous summary, otherwise initial prompt
 	let basePrompt = previousSummary ? UPDATE_SUMMARIZATION_PROMPT : SUMMARIZATION_PROMPT;
@@ -500,13 +541,13 @@ export interface CompactionPreparation {
 	previousSummary?: string;
 	/** File operations extracted from messagesToSummarize */
 	fileOps: FileOperations;
-	settings: CompactionSettings;
+	compaction: ModelCompaction;
 }
 
 /** Prepares a compaction of the whole context log; undefined when there is nothing to summarize. */
 export function prepareCompaction(
 	entries: ContextLogEntry[],
-	settings: CompactionSettings,
+	compaction: ModelCompaction,
 ): CompactionPreparation | undefined {
 	if (entries.length > 0 && entries[entries.length - 1].kind === "compaction") {
 		return undefined;
@@ -530,7 +571,7 @@ export function prepareCompaction(
 
 	const tokensBefore = estimateContextTokens(contextMessages(entries)).tokens;
 
-	const cutPoint = findCutPoint(entries, boundaryStart, boundaryEnd, settings.keepRecentTokens);
+	const cutPoint = findCutPoint(entries, boundaryStart, boundaryEnd, compaction.keepRecentTokens);
 	const firstKeptEntry = entries[cutPoint.firstKeptEntryIndex];
 	if (!firstKeptEntry) {
 		return undefined;
@@ -571,7 +612,7 @@ export function prepareCompaction(
 		tokensBefore,
 		previousSummary: previous?.summary,
 		fileOps,
-		settings,
+		compaction,
 	};
 }
 
@@ -614,7 +655,7 @@ export async function compact(
 		tokensBefore,
 		previousSummary,
 		fileOps,
-		settings,
+		compaction,
 	} = preparation;
 
 	// Generate summaries and merge into one
@@ -626,7 +667,7 @@ export async function compact(
 				? await generateSummary(
 						messagesToSummarize,
 						model,
-						settings.reserveTokens,
+						compaction.summaryTokens,
 						apiKey,
 						headers,
 						signal,
@@ -640,7 +681,7 @@ export async function compact(
 		const turnPrefixResult = await generateTurnPrefixSummary(
 			turnPrefixMessages,
 			model,
-			settings.reserveTokens,
+			turnPrefixTokens(compaction.summaryTokens),
 			apiKey,
 			headers,
 			env,
@@ -655,7 +696,7 @@ export async function compact(
 		summary = await generateSummary(
 			messagesToSummarize,
 			model,
-			settings.reserveTokens,
+			compaction.summaryTokens,
 			apiKey,
 			headers,
 			signal,
@@ -679,7 +720,7 @@ export async function compact(
 async function generateTurnPrefixSummary(
 	messages: AgentMessage[],
 	model: Model<any>,
-	reserveTokens: number,
+	budgetTokens: number,
 	apiKey: string | undefined,
 	headers?: Record<string, string>,
 	env?: Record<string, string>,
@@ -687,10 +728,7 @@ async function generateTurnPrefixSummary(
 	thinkingLevel?: ThinkingLevel,
 	streamFn?: StreamFn,
 ): Promise<string> {
-	const maxTokens = Math.min(
-		Math.floor(0.5 * reserveTokens),
-		model.maxTokens > 0 ? model.maxTokens : Number.POSITIVE_INFINITY,
-	); // Smaller budget for turn prefix
+	const maxTokens = Math.min(budgetTokens, model.maxTokens > 0 ? model.maxTokens : Number.POSITIVE_INFINITY);
 	const llmMessages = convertToLlm(messages);
 	const conversationText = serializeConversation(llmMessages);
 	const promptText = `<conversation>\n${conversationText}\n</conversation>\n\n${TURN_PREFIX_SUMMARIZATION_PROMPT}`;

package/packages/agent/src/core/model-runtime.ts

@@ -9,18 +9,21 @@ import {
 	createModels,
 	lazyStream,
 	type Model,
+	type ModelCompaction,
 	type MutableModels,
 	type Provider,
 	type SimpleStreamOptions,
 } from "@ragents/ai";
 import { builtinProviders } from "@ragents/ai/providers/all";
+import { compactionProblem } from "./compaction/compaction.ts";
 import { composeModelProvider, type ProviderConfigInput } from "./provider-composer.ts";
 
-/** A name under which a model of another provider is offered; only the alias is visible to callers. */
+/** A name under which a model of another provider is offered, with its own compaction values; only the alias is visible to callers. */
 export interface ModelAlias {
 	readonly alias: string;
 	readonly upstream: string;
 	readonly model: string;
+	readonly compaction: ModelCompaction;
 }
 
 interface AliasRegistration {
@@ -28,9 +31,9 @@ interface AliasRegistration {
 	readonly aliases: ReadonlyMap<string, ModelAlias>;
 }
 
-/** The metadata of the target under the alias as id and name, with the alias provider as provider. */
-export function aliasedModel(providerId: string, alias: string, target: Model<Api>): Model<Api> {
-	return { ...target, id: alias, name: alias, provider: providerId };
+/** The metadata of the target under the alias as id and name, with the alias provider as provider and the alias's compaction values. */
+export function aliasedModel(providerId: string, entry: ModelAlias, target: Model<Api>): Model<Api> {
+	return { ...target, id: entry.alias, name: entry.alias, provider: providerId, compaction: entry.compaction };
 }
 
 /** The built-in providers plus the ones registered at runtime; a key comes from the registration or the environment. */
@@ -102,6 +105,10 @@ export class ModelRuntime {
 		if (duplicate) throw new Error(`Alias ${duplicate.alias} is registered twice.`);
 		const missing = aliases.find((entry) => !this.models.getModel(entry.upstream, entry.model));
 		if (missing) throw new Error(`Alias ${missing.alias}: model ${missing.upstream}/${missing.model} is not configured.`);
+		for (const entry of aliases) {
+			const problem = compactionProblem(entry.compaction, this.models.getModel(entry.upstream, entry.model));
+			if (problem) throw new Error(`Alias ${entry.alias}: ${problem}.`);
+		}
 		this.aliasRegistration = { provider: providerId, aliases: new Map(aliases.map((entry) => [entry.alias, entry])) };
 	}
 
@@ -110,7 +117,7 @@ export class ModelRuntime {
 		if (!registration) return [];
 		return [...registration.aliases.values()].flatMap((entry) => {
 			const target = this.models.getModel(entry.upstream, entry.model);
-			return target ? [aliasedModel(registration.provider, entry.alias, target)] : [];
+			return target ? [aliasedModel(registration.provider, entry, target)] : [];
 		});
 	}
 

package/packages/agent/src/core/provider-composer.ts

@@ -7,10 +7,12 @@ import {
 	type InputModality,
 	lazyStream,
 	type Model,
+	type ModelCompaction,
 	type Provider,
 	type SimpleStreamOptions,
 	type StreamOptions,
 } from "@ragents/ai";
+import { compactionProblem } from "./compaction/compaction.ts";
 
 /** A provider registered at runtime: its models and a literal API key, over the built-in provider of the same id. */
 export interface ProviderConfigInput {
@@ -30,6 +32,7 @@ export interface ProviderConfigInput {
 		cost: Model<Api>["cost"];
 		contextWindow: number;
 		maxTokens: number;
+		compaction?: ModelCompaction;
 		compat?: Model<Api>["compat"];
 	}>;
 }
@@ -52,6 +55,8 @@ function registeredModels(
 		}
 		const baseUrl = definition.baseUrl ?? config.baseUrl ?? defaults?.baseUrl;
 		if (!baseUrl) throw new Error(`Provider ${providerId}: "baseUrl" is required when defining custom models.`);
+		const problem = definition.compaction === undefined ? undefined : compactionProblem(definition.compaction, definition);
+		if (problem) throw new Error(`Provider ${providerId}, model ${definition.id}: ${problem}.`);
 		return {
 			...definition,
 			api,

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

@@ -11,29 +11,36 @@ import { DEFAULT_MAX_LINES, formatSize, type TruncationResult } from "./truncate
 
 export const BASH_MAX_BYTES = 20 * 1024;
 export const BASH_MAX_LINE_CHARS = 1000;
+export const BASH_DEFAULT_TIMEOUT_SECONDS = 120;
+export const BASH_MAX_TIMEOUT_SECONDS = 600;
 
-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;
+function checkedTimeoutSeconds(timeout: number, label: string): number {
 	if (!Number.isFinite(timeout) || timeout <= 0) {
-		throw new Error("Invalid timeout: must be a finite number of seconds");
+		throw new Error(`Invalid ${label} ${timeout}: must be a positive number of seconds`);
 	}
-
-	const timeoutMs = timeout * 1000;
-	if (timeoutMs > MAX_TIMEOUT_MS) {
-		throw new Error(`Invalid timeout: maximum is ${MAX_TIMEOUT_SECONDS} seconds`);
+	if (timeout > BASH_MAX_TIMEOUT_SECONDS) {
+		throw new Error(`Invalid ${label} ${timeout}: the maximum is ${BASH_MAX_TIMEOUT_SECONDS} seconds`);
 	}
-	return timeoutMs;
+	return timeout;
 }
 
-const bashSchema = Type.Object({
+const bashSchemaFor = (defaultTimeoutSeconds: number) => Type.Object({
 	command: Type.String({ description: "Bash command to execute" }),
-	timeout: Type.Optional(Type.Number({ description: "Timeout in seconds (optional, no default timeout)" })),
+	timeout: Type.Optional(Type.Number({
+		exclusiveMinimum: 0,
+		maximum: BASH_MAX_TIMEOUT_SECONDS,
+		default: defaultTimeoutSeconds,
+		description: `Timeout in seconds (default ${defaultTimeoutSeconds}, maximum ${BASH_MAX_TIMEOUT_SECONDS})`,
+	})),
 	cwd: Type.Optional(Type.String({ description: "Folder to run the command in: relative to the working directory or starting with a workspace alias such as @name; defaults to the working directory" })),
 });
 
+type BashSchema = ReturnType<typeof bashSchemaFor>;
+
+const timeoutNotice = (seconds: number): string => seconds < BASH_MAX_TIMEOUT_SECONDS
+	? `Command stopped after ${seconds} seconds (timeout). Narrow the command, for example search with rg instead of grep -r, or pass a larger timeout, up to ${BASH_MAX_TIMEOUT_SECONDS} seconds.`
+	: `Command stopped after ${seconds} seconds, the maximum timeout. Narrow the command, for example search with rg instead of grep -r, or split it into shorter steps.`;
+
 
 export interface BashToolDetails {
 	truncation?: TruncationResult;
@@ -58,7 +65,8 @@ export interface BashOperations {
 		options: {
 			onData: (data: Buffer) => void;
 			signal?: AbortSignal;
-			timeout?: number;
+			/** Seconds until the command is stopped. */
+			timeout: number;
 			env?: NodeJS.ProcessEnv;
 		},
 	) => Promise<{ exitCode: number | null }>;
@@ -68,7 +76,6 @@ export interface BashOperations {
 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");
 			}
@@ -87,19 +94,15 @@ export function createLocalBashOperations(options?: { shellPath?: string }): Bas
 				windowsHide: true,
 			});
 			let timedOut = false;
-			let timeoutHandle: NodeJS.Timeout | undefined;
 			const onAbort = () => {
 				if (child.pid) killProcessTree(child.pid);
 			};
+			const timeoutHandle = setTimeout(() => {
+				timedOut = true;
+				if (child.pid) killProcessTree(child.pid);
+			}, timeout * 1000);
 
 			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);
@@ -119,7 +122,7 @@ export function createLocalBashOperations(options?: { shellPath?: string }): Bas
 				}
 				return { exitCode };
 			} finally {
-				if (timeoutHandle) clearTimeout(timeoutHandle);
+				clearTimeout(timeoutHandle);
 				if (signal) signal.removeEventListener("abort", onAbort);
 			}
 		},
@@ -148,6 +151,8 @@ export interface BashToolOptions {
 	shellPath?: string;
 	/** Hook to adjust command, cwd, or env before execution */
 	spawnHook?: BashSpawnHook;
+	/** Timeout in seconds for a call without one, at most BASH_MAX_TIMEOUT_SECONDS. Default: BASH_DEFAULT_TIMEOUT_SECONDS */
+	defaultTimeoutSeconds?: number;
 }
 
 const BASH_UPDATE_THROTTLE_MS = 100;
@@ -155,21 +160,23 @@ const BASH_UPDATE_THROTTLE_MS = 100;
 export function createBashToolDefinition(
 	cwd: string,
 	options?: BashToolOptions,
-): ToolDefinition<typeof bashSchema, BashToolDetails | undefined> {
+): ToolDefinition<BashSchema, BashToolDetails | undefined> {
 	const ops = options?.operations ?? createLocalBashOperations({ shellPath: options?.shellPath });
 	const commandPrefix = options?.commandPrefix;
 	const spawnHook = options?.spawnHook;
+	const defaultTimeoutSeconds = checkedTimeoutSeconds(options?.defaultTimeoutSeconds ?? BASH_DEFAULT_TIMEOUT_SECONDS, "default timeout");
 	return {
 		name: "bash",
 		label: "bash",
-		description: `Execute a bash command in the working directory, or in the folder given as cwd. 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 ${BASH_MAX_BYTES / 1024}KB (whichever is hit first), and lines longer than ${BASH_MAX_LINE_CHARS} characters are shortened. If anything was cut, the full output is saved to a temp file. Optionally provide a timeout in seconds.`,
-		parameters: bashSchema,
+		description: `Execute a bash command in the working directory, or in the folder given as cwd. 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 ${BASH_MAX_BYTES / 1024}KB (whichever is hit first), and lines longer than ${BASH_MAX_LINE_CHARS} characters are shortened. If anything was cut, the full output is saved to a temp file. A command is stopped after ${defaultTimeoutSeconds} seconds unless you pass a larger timeout (at most ${BASH_MAX_TIMEOUT_SECONDS} seconds); builds, test runs, installs and other long commands need one.`,
+		parameters: bashSchemaFor(defaultTimeoutSeconds),
 		async execute(
 			_toolCallId,
 			{ command, timeout, cwd: folder }: { command: string; timeout?: number; cwd?: string },
 			signal?: AbortSignal,
 			onUpdate?,
 		) {
+			const timeoutSeconds = timeout === undefined ? defaultTimeoutSeconds : checkedTimeoutSeconds(timeout, "timeout");
 			const resolvedCommand = commandPrefix ? `${commandPrefix}\n${command}` : command;
 			const spawnContext = resolveSpawnContext(resolvedCommand, folder === undefined ? cwd : resolvePath(folder, cwd), spawnHook);
 			const output = new OutputAccumulator({ maxBytes: BASH_MAX_BYTES, maxLineChars: BASH_MAX_LINE_CHARS, tempFilePrefix: "agent-bash" });
@@ -265,7 +272,7 @@ export function createBashToolDefinition(
 					const result = await ops.exec(spawnContext.command, spawnContext.cwd, {
 						onData: handleData,
 						signal,
-						timeout,
+						timeout: timeoutSeconds,
 						env: spawnContext.env,
 					});
 					exitCode = result.exitCode;
@@ -276,8 +283,7 @@ export function createBashToolDefinition(
 						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 new Error(appendStatus(text, timeoutNotice(timeoutSeconds)));
 					}
 					throw err;
 				}

package/packages/agent/src/index.ts

@@ -11,6 +11,9 @@ export {
 export {
 	calculateContextTokens,
 	compact,
+	compactionOf,
+	compactionProblem,
+	type CompactionSource,
 	estimateContextTokens,
 	prepareCompaction,
 	shouldCompact,