@schlenkr/ragents 0.1.5 → 0.1.7

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

@@ -0,0 +1,5 @@
+export * from "./agent.ts";
+export * from "./agent-loop.ts";
+export * from "./types.ts";
+export { uuidv7 } from "./uuid.ts";
+//# sourceMappingURL=index.d.ts.map

package/packages/agent/dist/loop/types.d.ts

@@ -0,0 +1,333 @@
+import type { Api, AssistantMessage, AssistantMessageEvent, AssistantMessageEventStream, Context, ImageContent, Message, Model, SimpleStreamOptions, TextContent, Tool, ToolResultMessage } from "@ragents/ai";
+import type { Static, TSchema } from "typebox";
+/**
+ * Stream function used by the agent loop. `Models.streamSimple` satisfies
+ * this shape.
+ *
+ * Contract:
+ * - Must not throw or return a rejected promise for request/model/runtime failures.
+ * - Must return an AssistantMessageEventStream.
+ * - Failures must be encoded in the returned stream via protocol events and a
+ *   final AssistantMessage with stopReason "error" or "aborted" and errorMessage.
+ */
+export type StreamFn = (model: Model<Api>, context: Context, options?: SimpleStreamOptions) => AssistantMessageEventStream | Promise<AssistantMessageEventStream>;
+/**
+ * Configuration for how tool calls from a single assistant message are executed.
+ *
+ * - "sequential": each tool call is prepared, executed, and finalized before the next one starts.
+ * - "parallel": tool calls are prepared sequentially, then allowed tools execute concurrently.
+ *   `tool_execution_end` is emitted in tool completion order after each tool is finalized,
+ *   while tool-result message artifacts are emitted later in assistant source order.
+ */
+export type ToolExecutionMode = "sequential" | "parallel";
+/** A single tool call content block emitted by an assistant message. */
+export type AgentToolCall = Extract<AssistantMessage["content"][number], {
+    type: "toolCall";
+}>;
+/**
+ * Partial override returned from `afterToolCall`.
+ *
+ * Merge semantics are field-by-field:
+ * - `content`: if provided, replaces the tool result content array in full
+ * - `details`: if provided, replaces the tool result details value in full
+ * - `isError`: if provided, replaces the tool result error flag
+ * - `terminate`: if provided, replaces the early-termination hint
+ *
+ * Omitted fields keep the original executed tool result values.
+ * There is no deep merge for `content` or `details`.
+ */
+export interface AfterToolCallResult {
+    content?: (TextContent | ImageContent)[];
+    details?: unknown;
+    isError?: boolean;
+    /**
+     * Hint that the agent should stop after the current tool batch.
+     * Early termination only happens when every finalized tool result in the batch sets this to true.
+     */
+    terminate?: boolean;
+}
+/** Context passed to `afterToolCall`. */
+export interface AfterToolCallContext {
+    /** The assistant message that requested the tool call. */
+    assistantMessage: AssistantMessage;
+    /** The raw tool call block from `assistantMessage.content`. */
+    toolCall: AgentToolCall;
+    /** Validated tool arguments for the target tool schema. */
+    args: unknown;
+    /** The executed tool result before any `afterToolCall` overrides are applied. */
+    result: AgentToolResult<any>;
+    /** Whether the executed tool result is currently treated as an error. */
+    isError: boolean;
+    /** Current agent context at the time the tool call is finalized. */
+    context: AgentContext;
+}
+/** Context passed to `shouldStopAfterTurn`. */
+export interface ShouldStopAfterTurnContext {
+    /** The assistant message that completed the turn. */
+    message: AssistantMessage;
+    /** Tool result messages passed to the preceding `turn_end` event. */
+    toolResults: ToolResultMessage[];
+    /** Current agent context after the turn's assistant message and tool results have been appended. */
+    context: AgentContext;
+    /** Messages that this loop invocation will return if it exits at this point. Prompt runs include the initial prompt messages; continuation runs do not include pre-existing context messages. */
+    newMessages: AgentMessage[];
+}
+/** Replacement runtime state used by the agent loop before starting another provider request. */
+export interface AgentLoopTurnUpdate {
+    /** Context for the next provider request. */
+    context?: AgentContext;
+    /** Model for the next provider request. */
+    model?: Model<any>;
+    /** Thinking level for the next provider request. */
+    thinkingLevel?: ThinkingLevel;
+}
+export interface PrepareNextTurnContext extends ShouldStopAfterTurnContext {
+}
+export interface AgentLoopConfig extends SimpleStreamOptions {
+    model: Model<any>;
+    /**
+     * Converts AgentMessage[] to LLM-compatible Message[] before each LLM call.
+     *
+     * Each AgentMessage must be converted to a UserMessage, AssistantMessage, or ToolResultMessage
+     * that the LLM can understand. AgentMessages that cannot be converted (e.g., UI-only notifications,
+     * status messages) should be filtered out.
+     *
+     * Contract: must not throw or reject. Return a safe fallback value instead.
+     * Throwing interrupts the low-level agent loop without producing a normal event sequence.
+     *
+     * @example
+     * ```typescript
+     * convertToLlm: (messages) => messages.flatMap(m => {
+     *   if (m.role === "custom") {
+     *     // Convert custom message to user message
+     *     return [{ role: "user", content: m.content, timestamp: m.timestamp }];
+     *   }
+     *   if (m.role === "notification") {
+     *     // Filter out UI-only messages
+     *     return [];
+     *   }
+     *   // Pass through standard LLM messages
+     *   return [m];
+     * })
+     * ```
+     */
+    convertToLlm: (messages: AgentMessage[]) => Message[] | Promise<Message[]>;
+    /**
+     * Optional transform applied to the context before `convertToLlm`.
+     *
+     * Use this for operations that work at the AgentMessage level:
+     * - Context window management (pruning old messages)
+     * - Injecting context from external sources
+     *
+     * Contract: must not throw or reject. Return the original messages or another
+     * safe fallback value instead.
+     *
+     * @example
+     * ```typescript
+     * transformContext: async (messages) => {
+     *   if (estimateTokens(messages) > MAX_TOKENS) {
+     *     return pruneOldMessages(messages);
+     *   }
+     *   return messages;
+     * }
+     * ```
+     */
+    transformContext?: (messages: AgentMessage[], signal?: AbortSignal) => Promise<AgentMessage[]>;
+    /**
+     * Resolves an API key dynamically for each LLM call.
+     *
+     * Useful for short-lived OAuth tokens (e.g., GitHub Copilot) that may expire
+     * during long-running tool execution phases.
+     *
+     * Contract: must not throw or reject. Return undefined when no key is available.
+     */
+    getApiKey?: (provider: string) => Promise<string | undefined> | string | undefined;
+    /**
+     * Called after each turn fully completes and `turn_end` has been emitted.
+     *
+     * If it returns true, the loop emits `agent_end` and exits before polling steering messages,
+     * without starting another LLM call. The current assistant response and any tool executions finish normally.
+     *
+     * Use this to request a graceful stop after the current turn, e.g. before context gets too full.
+     *
+     * Contract: must not throw or reject. Throwing interrupts the low-level agent loop without producing a normal event sequence.
+     */
+    shouldStopAfterTurn?: (context: ShouldStopAfterTurnContext) => boolean | Promise<boolean>;
+    /**
+     * Called after `turn_end` and before the loop decides whether another provider request should start.
+     * Return replacement context/model/thinking state to affect the next turn in this run.
+     * Return undefined to keep using the current context/config.
+     */
+    prepareNextTurn?: (context: PrepareNextTurnContext) => AgentLoopTurnUpdate | undefined | Promise<AgentLoopTurnUpdate | undefined>;
+    /** Steering polled before the first model request and after each assistant turn; messages join the context, a rejection ends the run. */
+    getSteeringMessages?: () => Promise<AgentMessage[]>;
+    /**
+     * Tool execution mode.
+     * - "sequential": execute tool calls one by one
+     * - "parallel": preflight tool calls sequentially, then execute allowed tools concurrently;
+     *   emit `tool_execution_end` in tool completion order after each tool is finalized,
+     *   then emit tool-result message artifacts later in assistant source order
+     *
+     * Default: "parallel"
+     */
+    toolExecution?: ToolExecutionMode;
+    /** Customize an unavailable tool's error text; undefined keeps the default and execution stays blocked. */
+    formatUnknownToolError?: (toolName: string) => string | undefined;
+    /**
+     * Called after a tool finishes executing, before `tool_execution_end` and tool-result message events are emitted.
+     *
+     * Return an `AfterToolCallResult` to override parts of the executed tool result:
+     * - `content` replaces the full content array
+     * - `details` replaces the full details payload
+     * - `isError` replaces the error flag
+     * - `terminate` replaces the early-termination hint
+     *
+     * Any omitted fields keep their original values. No deep merge is performed.
+     * The hook receives the agent abort signal and is responsible for honoring it.
+     */
+    afterToolCall?: (context: AfterToolCallContext, signal?: AbortSignal) => Promise<AfterToolCallResult | undefined>;
+}
+/**
+ * Thinking/reasoning level for models that support it.
+ * Note: "xhigh" and "max" are only supported by selected model families. Use model
+ * thinking-level metadata from @ragents/ai to detect support for a concrete model.
+ */
+export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+/** Custom message types; `core/messages.ts` adds them through declaration merging. */
+export interface CustomAgentMessages {
+}
+/**
+ * AgentMessage: Union of LLM messages + custom messages.
+ * This abstraction allows apps to add custom message types while maintaining
+ * type safety and compatibility with the base LLM messages.
+ */
+export type AgentMessage = Message | CustomAgentMessages[keyof CustomAgentMessages];
+/**
+ * Public agent state.
+ *
+ * `tools` and `messages` use accessor properties so implementations can copy
+ * assigned arrays before storing them.
+ */
+export interface AgentState {
+    /** System prompt sent with each model request. */
+    systemPrompt: string;
+    /** Active model used for future turns. */
+    model: Model<any>;
+    /** Requested reasoning level for future turns. */
+    thinkingLevel: ThinkingLevel;
+    /** Available tools. Assigning a new array copies the top-level array. */
+    set tools(tools: AgentTool<any>[]);
+    get tools(): AgentTool<any>[];
+    /** Conversation transcript. Assigning a new array copies the top-level array. */
+    set messages(messages: AgentMessage[]);
+    get messages(): AgentMessage[];
+    /**
+     * True while the agent is processing a prompt or continuation.
+     *
+     * This remains true until awaited `agent_end` listeners settle.
+     */
+    readonly isStreaming: boolean;
+    /** Partial assistant message for the current streamed response, if any. */
+    readonly streamingMessage?: AgentMessage;
+    /** Tool call ids currently executing. */
+    readonly pendingToolCalls: ReadonlySet<string>;
+    /** Error message from the most recent failed or aborted assistant turn, if any. */
+    readonly errorMessage?: string;
+}
+/** Final or partial result produced by a tool. */
+export interface AgentToolResult<T> {
+    /** Text or image content returned to the model. */
+    content: (TextContent | ImageContent)[];
+    /** Arbitrary structured details for logs or UI rendering. */
+    details: T;
+    /** Names of tools introduced by this result and available from this transcript point onward. */
+    addedToolNames?: string[];
+    /**
+     * Hint that the agent should stop after the current tool batch.
+     * Early termination only happens when every finalized tool result in the batch sets this to true.
+     */
+    terminate?: boolean;
+}
+/**
+ * Callback used by tools to stream partial execution updates.
+ *
+ * The callback is scoped to the current `execute()` invocation. Calls made after
+ * the tool promise settles are ignored.
+ */
+export type AgentToolUpdateCallback<T = any> = (partialResult: AgentToolResult<T>) => void;
+/** Tool definition used by the agent runtime. */
+export interface AgentTool<TParameters extends TSchema = TSchema, TDetails = any> extends Tool<TParameters> {
+    /** Human-readable label for UI display. */
+    label: string;
+    /**
+     * Optional compatibility shim for raw tool-call arguments before schema validation.
+     * Must return an object that matches `TParameters`.
+     */
+    prepareArguments?: (args: unknown) => Static<TParameters>;
+    /** Execute the tool call. Throw on failure instead of encoding errors in `content`. */
+    execute: (toolCallId: string, params: Static<TParameters>, signal?: AbortSignal, onUpdate?: AgentToolUpdateCallback<TDetails>) => Promise<AgentToolResult<TDetails>>;
+    /**
+     * Per-tool execution mode override.
+     * - "sequential": this tool must execute one at a time with other tool calls.
+     * - "parallel": this tool can execute concurrently with other tool calls.
+     *
+     * If omitted, the default execution mode applies.
+     */
+    executionMode?: ToolExecutionMode;
+}
+/** Context snapshot passed into the low-level agent loop. */
+export interface AgentContext {
+    /** System prompt included with the request. */
+    systemPrompt: string;
+    /** Transcript visible to the model. */
+    messages: AgentMessage[];
+    /** Tools available for this run. */
+    tools?: AgentTool<any>[];
+}
+/**
+ * Events emitted by the Agent for UI updates.
+ *
+ * `agent_end` is the last event emitted for a run, but awaited `Agent.subscribe()`
+ * listeners for that event are still part of run settlement. The agent becomes
+ * idle only after those listeners finish.
+ */
+export type AgentEvent = {
+    type: "agent_start";
+} | {
+    type: "agent_end";
+    messages: AgentMessage[];
+} | {
+    type: "turn_start";
+} | {
+    type: "turn_end";
+    message: AgentMessage;
+    toolResults: ToolResultMessage[];
+} | {
+    type: "message_start";
+    message: AgentMessage;
+} | {
+    type: "message_update";
+    message: AgentMessage;
+    assistantMessageEvent: AssistantMessageEvent;
+} | {
+    type: "message_end";
+    message: AgentMessage;
+} | {
+    type: "tool_execution_start";
+    toolCallId: string;
+    toolName: string;
+    args: any;
+} | {
+    type: "tool_execution_update";
+    toolCallId: string;
+    toolName: string;
+    args: any;
+    partialResult: any;
+} | {
+    type: "tool_execution_end";
+    toolCallId: string;
+    toolName: string;
+    result: any;
+    isError: boolean;
+};
+//# sourceMappingURL=types.d.ts.map

package/packages/agent/dist/loop/uuid.d.ts

@@ -0,0 +1,2 @@
+export declare function uuidv7(): string;
+//# sourceMappingURL=uuid.d.ts.map

package/packages/agent/dist/utils/child-process.d.ts

@@ -0,0 +1,17 @@
+import { type ChildProcess, type ChildProcessByStdio, type SpawnOptions, type SpawnOptionsWithStdioTuple, type StdioNull, type StdioPipe } from "node:child_process";
+import type { Readable } from "node:stream";
+export declare function spawnProcess(command: string, args: string[], options: SpawnOptionsWithStdioTuple<StdioNull, StdioPipe, StdioPipe>): ChildProcessByStdio<null, Readable, Readable>;
+export declare function spawnProcess(command: string, args: string[], options: SpawnOptions): ChildProcess;
+/**
+ * Wait for a child process to terminate without hanging on inherited stdio handles.
+ *
+ * A short-lived child can `exit` while a detached descendant keeps its stdout/stderr
+ * pipe open. We must not resolve and destroy the streams on a fixed deadline measured
+ * from `exit`, or output still being written past that deadline is silently lost
+ * (earendil-works/pi#5303). Instead, after `exit` we wait for the pipes to fall idle:
+ * the grace timer is re-armed on every chunk, so an actively writing descendant keeps
+ * us reading, while a quiet inherited handle (e.g. a Windows daemonized descendant
+ * that never lets `close` fire) still releases us after the grace elapses.
+ */
+export declare function waitForChildProcess(child: ChildProcess): Promise<number | null>;
+//# sourceMappingURL=child-process.d.ts.map

package/packages/agent/dist/utils/exif-orientation.d.ts

@@ -0,0 +1,5 @@
+import type { PhotonImageType } from "./photon.ts";
+type Photon = typeof import("@silvia-odwyer/photon-node");
+export declare function applyExifOrientation(photon: Photon, image: PhotonImageType, originalBytes: Uint8Array): PhotonImageType;
+export {};
+//# sourceMappingURL=exif-orientation.d.ts.map

package/packages/agent/dist/utils/frontmatter.d.ts

@@ -0,0 +1,8 @@
+type ParsedFrontmatter<T extends Record<string, unknown>> = {
+    frontmatter: T;
+    body: string;
+};
+export declare const parseFrontmatter: <T extends Record<string, unknown> = Record<string, unknown>>(content: string) => ParsedFrontmatter<T>;
+export declare const stripFrontmatter: (content: string) => string;
+export {};
+//# sourceMappingURL=frontmatter.d.ts.map

package/packages/agent/dist/utils/image-convert.d.ts

@@ -0,0 +1,2 @@
+export declare function convertImageBytesToPng(bytes: Uint8Array): Promise<Uint8Array | null>;
+//# sourceMappingURL=image-convert.d.ts.map

package/packages/agent/dist/utils/image-process.d.ts

@@ -0,0 +1,18 @@
+import { type ImageResizeOptions } from "./image-resize.ts";
+export interface ProcessImageOptions {
+    /** Whether to resize images to inline provider limits. Default: true */
+    autoResizeImages?: boolean;
+    /** Optional resize overrides. Uses resizeImage defaults when omitted. */
+    resizeOptions?: ImageResizeOptions;
+}
+export type ProcessImageResult = {
+    ok: true;
+    data: string;
+    mimeType: string;
+    hints: string[];
+} | {
+    ok: false;
+    message: string;
+};
+export declare function processImage(bytes: Uint8Array, mimeType: string, options?: ProcessImageOptions): Promise<ProcessImageResult>;
+//# sourceMappingURL=image-process.d.ts.map

package/packages/agent/dist/utils/image-resize-core.d.ts

@@ -0,0 +1,30 @@
+export interface ImageResizeOptions {
+    maxWidth?: number;
+    maxHeight?: number;
+    maxBytes?: number;
+    jpegQuality?: number;
+}
+export interface ResizedImage {
+    data: string;
+    mimeType: string;
+    originalWidth: number;
+    originalHeight: number;
+    width: number;
+    height: number;
+    wasResized: boolean;
+}
+/**
+ * Resize an image to fit within the specified max dimensions and encoded file size.
+ * Returns null if the image cannot be resized below maxBytes.
+ *
+ * Uses Photon (Rust/WASM) for image processing. If Photon is not available,
+ * returns null.
+ *
+ * Strategy for staying under maxBytes:
+ * 1. First resize to maxWidth/maxHeight
+ * 2. Try both PNG and JPEG formats, pick the smaller one
+ * 3. If still too large, try JPEG with decreasing quality
+ * 4. If still too large, progressively reduce dimensions until 1x1
+ */
+export declare function resizeImageInProcess(inputBytes: Uint8Array, mimeType: string, options?: ImageResizeOptions): Promise<ResizedImage | null>;
+//# sourceMappingURL=image-resize-core.d.ts.map

package/packages/agent/dist/utils/image-resize-worker.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=image-resize-worker.d.ts.map

package/packages/agent/dist/utils/image-resize.d.ts

@@ -0,0 +1,16 @@
+import { type ImageResizeOptions, type ResizedImage } from "./image-resize-core.ts";
+export type { ImageResizeOptions, ResizedImage } from "./image-resize-core.ts";
+/**
+ * Resize an image to fit within the specified max dimensions and encoded file size.
+ * Runs Photon in a worker thread so WASM decoding, resizing, and encoding do not
+ * block the TUI event loop. If the worker cannot be loaded (for example in some
+ * Bun compiled executable layouts), fall back to in-process resizing so image
+ * reads still work.
+ */
+export declare function resizeImage(inputBytes: Uint8Array, mimeType: string, options?: ImageResizeOptions): Promise<ResizedImage | null>;
+/**
+ * Format a dimension note for resized images.
+ * This helps the model understand the coordinate mapping.
+ */
+export declare function formatDimensionNote(result: ResizedImage): string | undefined;
+//# sourceMappingURL=image-resize.d.ts.map

package/packages/agent/dist/utils/mime.d.ts

@@ -0,0 +1,3 @@
+export declare function detectSupportedImageMimeType(buffer: Uint8Array): string | null;
+export declare function detectSupportedImageMimeTypeFromFile(filePath: string): Promise<string | null>;
+//# sourceMappingURL=mime.d.ts.map

package/packages/agent/dist/utils/paths.d.ts

@@ -0,0 +1,15 @@
+export interface PathInputOptions {
+    /** Trim leading/trailing whitespace before normalization. */
+    trim?: boolean;
+    /** Expand leading `~` to a home directory. Defaults to true. */
+    expandTilde?: boolean;
+    /** Home directory used for `~` expansion. Defaults to `os.homedir()`. */
+    homeDir?: string;
+    /** Strip a leading `@`, used for CLI @file paths. */
+    stripAtPrefix?: boolean;
+    /** Normalize unicode space variants to regular spaces. */
+    normalizeUnicodeSpaces?: boolean;
+}
+export declare function normalizePath(input: string, options?: PathInputOptions): string;
+export declare function resolvePath(input: string, baseDir?: string, options?: PathInputOptions): string;
+//# sourceMappingURL=paths.d.ts.map

package/packages/agent/dist/utils/photon.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Photon image processing wrapper.
+ *
+ * This module provides a unified interface to @silvia-odwyer/photon-node that works in:
+ * 1. Node.js (development, npm run build)
+ * 2. Bun compiled binaries (standalone distribution)
+ *
+ * The challenge: photon-node's CJS entry uses fs.readFileSync(__dirname + '/photon_rs_bg.wasm')
+ * which bakes the build machine's absolute path into Bun compiled binaries.
+ *
+ * Solution:
+ * 1. Patch fs.readFileSync to redirect missing photon_rs_bg.wasm reads
+ * 2. Copy photon_rs_bg.wasm next to the executable in build:binary
+ */
+export type { PhotonImage as PhotonImageType } from "@silvia-odwyer/photon-node";
+/**
+ * Load the photon module asynchronously.
+ * Returns cached module on subsequent calls.
+ */
+export declare function loadPhoton(): Promise<typeof import("@silvia-odwyer/photon-node") | null>;
+//# sourceMappingURL=photon.d.ts.map

package/packages/agent/dist/utils/shell.d.ts

@@ -0,0 +1,17 @@
+export interface ShellConfig {
+    shell: string;
+    args: string[];
+}
+/**
+ * Resolve the bash to run commands with.
+ * Resolution order:
+ * 1. The explicit shell path
+ * 2. On Windows: nothing, the caller brings its own bash and names it
+ * 3. On Unix: /bin/bash, then bash on PATH
+ */
+export declare function getShellConfig(customShellPath?: string, platform?: NodeJS.Platform): ShellConfig;
+/**
+ * Kill a process and all its children (cross-platform)
+ */
+export declare function killProcessTree(pid: number): void;
+//# sourceMappingURL=shell.d.ts.map

package/packages/agent/dist/utils/sleep.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Sleep helper that respects abort signal.
+ */
+export declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
+//# sourceMappingURL=sleep.d.ts.map

package/packages/agent/package.json

@@ -1,7 +1,7 @@
 {
-	"name": "@aicontainer/agent",
+	"name": "@ragents/agent",
 	"version": "0.80.10",
-	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
+	"description": "The agent runtime of RAgents: agent loop, compaction, model runtime and the read, write, edit and bash tools",
 	"type": "module",
 	"main": "./src/index.ts",
 	"types": "./dist/index.d.ts",
@@ -16,49 +16,20 @@
 		"test": "node --test tests/*.test.ts"
 	},
 	"dependencies": {
-		"@aicontainer/agent-core": "^0.80.10",
-		"@aicontainer/ai": "^0.80.10",
+		"@ragents/ai": "^0.80.10",
 		"@silvia-odwyer/photon-node": "0.3.4",
-		"chalk": "5.6.2",
 		"cross-spawn": "7.0.6",
 		"diff": "8.0.4",
-		"glob": "13.0.6",
-		"hosted-git-info": "9.0.3",
-		"ignore": "7.0.5",
-		"jiti": "2.7.0",
-		"minimatch": "10.2.5",
-		"proper-lockfile": "4.1.2",
-		"semver": "7.8.0",
 		"typebox": "1.1.38",
-		"undici": "8.5.0",
 		"yaml": "2.9.0"
 	},
-	"overrides": {
-		"rimraf": "6.1.2",
-		"gaxios": {
-			"rimraf": "6.1.2"
-		}
-	},
 	"devDependencies": {
 		"@types/cross-spawn": "6.0.6",
 		"@types/diff": "7.0.2",
-		"@types/hosted-git-info": "3.0.5",
-		"@types/ms": "2.1.0",
 		"@types/node": "24.12.4",
-		"@types/proper-lockfile": "4.1.4",
-		"@types/semver": "7.7.1",
-		"shx": "0.4.0",
 		"typescript": "5.9.3"
 	},
 	"engines": {
 		"node": ">=22.19.0"
-	},
-	"appConfig": {
-		"name": "agent",
-		"configDir": ".agent"
-	},
-	"agentConfig": {
-		"name": "agent",
-		"configDir": ".agent"
 	}
 }

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

@@ -0,0 +1,20 @@
+/** The few knobs of an agent's runtime; 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. */
+	providerRequest: { timeoutMs: number; maxRetries?: number; maxRetryDelayMs: number };
+}
+
+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 },
+});