@sayknow-cli/agent-core 0.3.16 → 0.4.0

package/src/compaction/pruning.ts

@@ -9,8 +9,9 @@
  */
 
 import type { ToolCall, ToolResultMessage } from "@sayknow-cli/ai";
+import { sanitizeText } from "@sayknow-cli/utils";
 import type { AgentMessage } from "../types";
-import { estimateEntryTokens } from "./compaction";
+import { estimateEntryTokens, estimateTextTokensHeuristic } from "./compaction";
 import type { SessionEntry, SessionMessageEntry } from "./entries";
 
 export interface PruneConfig {
@@ -48,6 +49,7 @@ export interface PruneResult {
 }
 
 const DIGEST_NOTICE_TOKEN_CAP_MULTIPLIER = 1.25;
+const ERROR_DIGEST_NOTICE_MIN_CHARS = 240;
 
 function createGenericPrunedNotice(tokens: number): string {
 	return `[Output truncated - ${tokens} tokens]`;
@@ -66,6 +68,17 @@ function firstErrorLine(text: string): string | undefined {
 		?.trim();
 }
 
+function firstNonEmptyLine(text: string): string | undefined {
+	return text
+		.split(/\r?\n/)
+		.find(line => line.trim().length > 0)
+		?.trim();
+}
+
+function lastNonEmptyLine(text: string): string | undefined {
+	return text.trim().split(/\r?\n/).filter(Boolean).at(-1)?.trim();
+}
+
 function truncateField(value: string, maxLength: number): string {
 	if (value.length <= maxLength) return value;
 	if (maxLength <= 1) return "…";
@@ -74,7 +87,7 @@ function truncateField(value: string, maxLength: number): string {
 
 function resultDigest(message: ToolResultMessage): string | undefined {
 	const toolName = message.toolName.toLowerCase();
-	const text = firstTextContent(message);
+	const text = sanitizeText(firstTextContent(message));
 	if (toolName === "bash") {
 		const details = message as { details?: { exitCode?: unknown } };
 		const exitCode =
@@ -99,7 +112,12 @@ function resultDigest(message: ToolResultMessage): string | undefined {
 				.join("; ") || "search digest unavailable"
 		);
 	}
-	return undefined;
+	if (message.isError !== true) return undefined;
+	if (text.trim().length === 0) return "error=tool result failed without text";
+	const error = firstErrorLine(text);
+	if (error) return `error=${error}`;
+	const summary = firstNonEmptyLine(text) ?? lastNonEmptyLine(text);
+	return summary ? `summary=${summary}` : undefined;
 }
 
 function createPrunedNotice(tokens: number, message?: ToolResultMessage): string {
@@ -110,7 +128,9 @@ function createPrunedNotice(tokens: number, message?: ToolResultMessage): string
 	const maxTokens = Math.max(genericTokens, Math.floor(genericTokens * DIGEST_NOTICE_TOKEN_CAP_MULTIPLIER));
 	const prefix = `[Output truncated - ${tokens} tokens; `;
 	const suffix = "]";
-	const maxChars = Math.max(0, maxTokens * 4 - prefix.length - suffix.length);
+	const digestChars = maxTokens * 4 - prefix.length - suffix.length;
+	const maxChars =
+		message?.isError === true ? Math.max(ERROR_DIGEST_NOTICE_MIN_CHARS, digestChars) : Math.max(0, digestChars);
 	return `${prefix}${truncateField(digest, maxChars)}${suffix}`;
 }
 
@@ -122,8 +142,7 @@ function getToolResultMessage(entry: SessionEntry): ToolResultMessage | undefine
 }
 
 function estimatePrunedSavings(tokens: number, notice: string): number {
-	const noticeTokens = Math.ceil(notice.length / 4);
-	return Math.max(0, tokens - noticeTokens);
+	return tokens - estimateTextTokensHeuristic(notice);
 }
 
 export interface AssistantArgumentPruneResult {
@@ -267,6 +286,56 @@ function readBasePath(path: string): string {
 	return base;
 }
 
+type ReadLineRange = { start: number; end: number };
+
+const DEFAULT_READ_LINE_LIMIT = 500;
+
+/** Parse trailing read selectors using the read tool's actual bounded default. */
+function readLineRanges(path: string): ReadLineRange[] {
+	let target = path;
+	let raw = false;
+	while (/:(?:raw|conflicts)$/.test(target)) {
+		raw ||= target.endsWith(":raw");
+		target = target.replace(/:(?:raw|conflicts)$/, "");
+	}
+	const match = target.match(/:(\d+(?:[-+]\d+)?(?:,\d+(?:[-+]\d+)?)*)$/);
+	if (!match) return raw ? [{ start: 1, end: Number.POSITIVE_INFINITY }] : [];
+	return match[1].split(",").flatMap(part => {
+		const range = part.match(/^(\d+)(?:([-+])(\d+))?$/);
+		if (!range) return [];
+		const start = Number(range[1]);
+		const end =
+			range[2] === "+"
+				? start + Number(range[3]) - 1
+				: range[2] === "-"
+					? Number(range[3])
+					: start + DEFAULT_READ_LINE_LIMIT - 1;
+		return start > 0 && end >= start ? [{ start, end }] : [];
+	});
+}
+
+function strictlyContainsReadRange(container: ReadLineRange, contained: ReadLineRange): boolean {
+	return (
+		container.start <= contained.start &&
+		container.end >= contained.end &&
+		(container.start < contained.start || container.end > contained.end)
+	);
+}
+
+function readSupersedesRead(
+	later: ToolCall,
+	earlier: ToolCall,
+	lineRangesByCall: ReadonlyMap<ToolCall, ReadLineRange[]>,
+): boolean {
+	const laterRanges = lineRangesByCall.get(later);
+	const earlierRanges = lineRangesByCall.get(earlier);
+	return (
+		laterRanges?.length === 1 &&
+		earlierRanges?.length === 1 &&
+		strictlyContainsReadRange(laterRanges[0], earlierRanges[0])
+	);
+}
+
 /**
  * Stable identity for "the same logical lookup": same tool re-targeting the
  * same subject. A later result with the same key supersedes earlier ones.
@@ -275,9 +344,23 @@ function readBasePath(path: string): string {
  * (`skip`) and result-shaping flags (`i`, `gitignore`): a later page or a
  * differently-shaped search complements earlier output, it does not replace it.
  */
+const IDEMPOTENT_BASH_COMMAND =
+	/^(?:(?:bun|npm|pnpm|yarn)\s+(?:run\s+)?(?:test|build)\b|git\s+status\b|cargo\s+build\b|(?:make|just)\s+build\b)/;
+
+function normalizedIdempotentBashCommand(call: ToolCall): string | undefined {
+	if (call.name !== "bash") return undefined;
+	const command = call.arguments.command;
+	if (typeof command !== "string") return undefined;
+	const normalized = command.trim().replace(/\s+/g, " ");
+	if (/[;&|]/.test(normalized) || !IDEMPOTENT_BASH_COMMAND.test(normalized)) return undefined;
+	return JSON.stringify([normalized, typeof call.arguments.cwd === "string" ? call.arguments.cwd : undefined]);
+}
+
 function toolTargetKey(call: ToolCall): string | undefined {
 	const path = toolCallPath(call);
 	if (path !== undefined) return JSON.stringify([call.name, "path", path]);
+	const command = normalizedIdempotentBashCommand(call);
+	if (command !== undefined) return JSON.stringify([call.name, "command", command]);
 	const pattern = call.arguments.pattern;
 	if (typeof pattern === "string" && pattern.length > 0) {
 		const paths = call.arguments.paths;
@@ -372,8 +455,9 @@ function buildStalenessIndex(entries: SessionEntry[]): StalenessIndex {
 		}
 	}
 
+	type ResultMeta = { key?: string; call: ToolCall; message: ToolResultMessage };
 	const lastResultIndexByKey = new Map<string, number>();
-	const resultMeta = new Map<number, { key?: string; call: ToolCall; message: ToolResultMessage }>();
+	const resultMeta = new Map<number, ResultMeta>();
 	const lastEditIndexByPath = new Map<string, number>();
 
 	for (let i = 0; i < entries.length; i++) {
@@ -439,6 +523,31 @@ function buildStalenessIndex(entries: SessionEntry[]): StalenessIndex {
 		}
 	}
 
+	const readsByBasePath = new Map<string, Array<[number, ResultMeta]>>();
+	const lineRangesByCall = new Map<ToolCall, ReadLineRange[]>();
+	for (const [index, meta] of resultMeta) {
+		if (meta.call.name !== "read") continue;
+		const path = toolCallPath(meta.call);
+		if (!path) continue;
+		lineRangesByCall.set(meta.call, readLineRanges(path));
+		const basePath = readBasePath(path);
+		const group = readsByBasePath.get(basePath);
+		if (group) group.push([index, meta]);
+		else readsByBasePath.set(basePath, [[index, meta]]);
+	}
+	for (const reads of readsByBasePath.values()) {
+		if (reads.length < 2) continue;
+		for (let earlier = 0; earlier < reads.length - 1; earlier++) {
+			const [index, meta] = reads[earlier];
+			for (let later = earlier + 1; later < reads.length; later++) {
+				if (readSupersedesRead(reads[later][1].call, meta.call, lineRangesByCall)) {
+					staleResultIndices.add(index);
+					break;
+				}
+			}
+		}
+	}
+
 	return { staleResultIndices };
 }
 export function pruneAssistantToolArguments(
@@ -580,11 +689,17 @@ function collectToolOutputPruneCandidates(
 		}
 
 		const notice = createPrunedNotice(tokens, message);
+		const savings = estimatePrunedSavings(tokens, notice);
+		const errorNoticeGrows = message.isError === true && notice.length > firstTextContent(message).length;
+		if (savings <= 0 || errorNoticeGrows) {
+			accumulatedTokens += tokens;
+			continue;
+		}
 		candidates.push({
 			entry: entry as SessionMessageEntry,
 			tokens,
 			notice,
-			savings: estimatePrunedSavings(tokens, notice),
+			savings,
 		});
 		accumulatedTokens += tokens;
 	}
@@ -596,6 +711,13 @@ function collectToolOutputPruneCandidates(
 	return { candidates, tokensSaved };
 }
 
+function minimumSavings(config: PruneConfig, options: PruneToolOutputsOptions = {}): number {
+	const relaxedMinimum = options.relaxedMinimum;
+	return typeof relaxedMinimum === "number" && Number.isFinite(relaxedMinimum)
+		? Math.min(config.minimumSavings, Math.max(0, relaxedMinimum))
+		: config.minimumSavings;
+}
+
 /**
  * Estimate the token savings {@link pruneToolOutputs} would achieve, without
  * mutating any entry. Returns 0 savings when below the configured minimum so the
@@ -604,9 +726,10 @@ function collectToolOutputPruneCandidates(
 export function estimateToolOutputPruneSavings(
 	entries: SessionEntry[],
 	config: PruneConfig = DEFAULT_PRUNE_CONFIG,
+	options: PruneToolOutputsOptions = {},
 ): { prunableCount: number; tokensSaved: number } {
 	const { candidates, tokensSaved } = collectToolOutputPruneCandidates(entries, config);
-	if (tokensSaved < config.minimumSavings || candidates.length === 0) {
+	if (tokensSaved < minimumSavings(config, options) || candidates.length === 0) {
 		return { prunableCount: 0, tokensSaved: 0 };
 	}
 	return { prunableCount: candidates.length, tokensSaved };
@@ -630,10 +753,20 @@ export function shouldRunMaintenancePrune(args: {
 	return args.estimatedSavings > args.cacheEpochResetCost;
 }
 
-export function pruneToolOutputs(entries: SessionEntry[], config: PruneConfig = DEFAULT_PRUNE_CONFIG): PruneResult {
+export interface PruneToolOutputsOptions {
+	/** Lower the usual minimum only when the caller is already over its compaction threshold. */
+	relaxedMinimum?: number;
+}
+
+export function pruneToolOutputs(
+	entries: SessionEntry[],
+	config: PruneConfig = DEFAULT_PRUNE_CONFIG,
+	options: PruneToolOutputsOptions = {},
+): PruneResult {
 	const { candidates, tokensSaved } = collectToolOutputPruneCandidates(entries, config);
+	const minimum = minimumSavings(config, options);
 
-	if (tokensSaved < config.minimumSavings || candidates.length === 0) {
+	if (tokensSaved < minimum || candidates.length === 0) {
 		return { prunedCount: 0, tokensSaved: 0, prunedEntries: [] };
 	}
 

package/src/proxy.ts

@@ -30,6 +30,33 @@ class ProxyMessageEventStream extends EventStream<AssistantMessageEvent, Assista
 	}
 }
 
+interface ReasoningBuffers {
+	summary: string;
+	raw: string;
+}
+
+const reasoningBuffers = new WeakMap<object, ReasoningBuffers>();
+
+function materializeReasoningProvenance(
+	content: Extract<AssistantMessage["content"][number], { type: "thinking" }>,
+): void {
+	const buffers = reasoningBuffers.get(content);
+	if (!buffers) return;
+	const mutable = content as { provenance?: "summary" | "raw" | "mixed"; summaryText?: string; rawText?: string };
+	if (mutable.provenance === undefined) {
+		if (mutable.summaryText === undefined && buffers.summary) mutable.summaryText = buffers.summary;
+		if (mutable.rawText === undefined && buffers.raw) mutable.rawText = buffers.raw;
+		mutable.provenance =
+			buffers.summary && buffers.raw ? "mixed" : buffers.summary ? "summary" : buffers.raw ? "raw" : undefined;
+	}
+	// Finalized display string must exclude raw CoT when a summary exists (parity with
+	// the Responses/Codex decoders): summary/mixed -> summary only; raw-only -> raw. The
+	// raw text stays available separately via rawText for explicit consumers.
+	const effSummary = mutable.summaryText ?? buffers.summary;
+	const effRaw = mutable.rawText ?? buffers.raw;
+	content.thinking = mutable.provenance === "raw" ? effRaw : effSummary || effRaw;
+}
+
 /**
  * Proxy event types - server sends these with partial field stripped to reduce bandwidth.
  */
@@ -41,6 +68,9 @@ export type ProxyAssistantMessageEvent =
 	| { type: "thinking_start"; contentIndex: number }
 	| { type: "thinking_delta"; contentIndex: number; delta: string }
 	| { type: "thinking_end"; contentIndex: number; contentSignature?: string }
+	| { type: "reasoning_summary_start"; contentIndex: number }
+	| { type: "reasoning_summary_delta"; contentIndex: number; delta: string }
+	| { type: "reasoning_summary_end"; contentIndex: number; content?: string }
 	| { type: "toolcall_start"; contentIndex: number; id: string; toolName: string }
 	| { type: "toolcall_delta"; contentIndex: number; delta: string }
 	| { type: "toolcall_end"; contentIndex: number }
@@ -238,14 +268,22 @@ function processProxyEvent(
 			throw new Error("Received text_end for non-text content");
 		}
 
-		case "thinking_start":
-			partial.content[proxyEvent.contentIndex] = { type: "thinking", thinking: "" };
+		case "thinking_start": {
+			const content = { type: "thinking", thinking: "" } as Extract<
+				AssistantMessage["content"][number],
+				{ type: "thinking" }
+			>;
+			partial.content[proxyEvent.contentIndex] = content;
+			reasoningBuffers.set(content, { summary: "", raw: "" });
 			return { type: "thinking_start", contentIndex: proxyEvent.contentIndex, partial };
+		}
 
 		case "thinking_delta": {
 			const content = partial.content[proxyEvent.contentIndex];
 			if (content?.type === "thinking") {
 				content.thinking += proxyEvent.delta;
+				const buffers = reasoningBuffers.get(content);
+				if (buffers) buffers.raw += proxyEvent.delta;
 				return {
 					type: "thinking_delta",
 					contentIndex: proxyEvent.contentIndex,
@@ -256,10 +294,52 @@ function processProxyEvent(
 			throw new Error("Received thinking_delta for non-thinking content");
 		}
 
+		case "reasoning_summary_start":
+			return { type: "reasoning_summary_start", contentIndex: proxyEvent.contentIndex, partial };
+
+		case "reasoning_summary_delta": {
+			const content = partial.content[proxyEvent.contentIndex];
+			if (content?.type === "thinking") {
+				content.thinking += proxyEvent.delta;
+				const buffers = reasoningBuffers.get(content);
+				if (buffers) buffers.summary += proxyEvent.delta;
+				return {
+					type: "reasoning_summary_delta",
+					contentIndex: proxyEvent.contentIndex,
+					delta: proxyEvent.delta,
+					partial,
+				};
+			}
+			throw new Error("Received reasoning_summary_delta for non-thinking content");
+		}
+
+		case "reasoning_summary_end": {
+			const content = partial.content[proxyEvent.contentIndex];
+			if (content?.type === "thinking") {
+				const buffers = reasoningBuffers.get(content);
+				// Final-only summaries arrive with the text on the end event and no summary
+				// deltas, so the accumulated buffer is empty. Prefer the end event's content
+				// so the summary survives the proxy and materializes as provenance "summary".
+				if (buffers && !buffers.summary.trim() && proxyEvent.content) {
+					buffers.summary = proxyEvent.content;
+					if (!content.thinking.trim()) content.thinking = proxyEvent.content;
+				}
+				materializeReasoningProvenance(content);
+				return {
+					type: "reasoning_summary_end",
+					contentIndex: proxyEvent.contentIndex,
+					content: buffers?.summary || proxyEvent.content || "",
+					partial,
+				};
+			}
+			throw new Error("Received reasoning_summary_end for non-thinking content");
+		}
+
 		case "thinking_end": {
 			const content = partial.content[proxyEvent.contentIndex];
 			if (content?.type === "thinking") {
 				content.thinkingSignature = proxyEvent.contentSignature;
+				materializeReasoningProvenance(content);
 				return {
 					type: "thinking_end",
 					contentIndex: proxyEvent.contentIndex,

package/src/types.ts

@@ -13,6 +13,7 @@ import type {
 	Tool,
 	ToolChoice,
 	ToolResultMessage,
+	TransportFailureFacts,
 	TSchema,
 } from "@sayknow-cli/ai";
 import type { AppendOnlyContextManager } from "./append-only-context";
@@ -25,11 +26,84 @@ export type StreamFn = (
 	...args: Parameters<typeof streamSimple>
 ) => AssistantMessageEventStream | Promise<AssistantMessageEventStream>;
 
+/** Stable identifier for a managed logical run, shared by all of its retry attempts. */
+export type ManagedLogicalRunId = number;
+
+/** Terminal completion requested for a logical run. */
+export interface RunTerminalRequest {
+	stopReason: "cancelled" | "error" | "exhausted";
+	messages?: AgentMessage[];
+}
+
+/**
+ * Ownership token supplied when Agent invokes a retry continuation.
+ *
+ * A continuation MUST verify `isCurrent()` immediately before starting a
+ * follow-up invocation and abandon the retry when it returns false. The token
+ * becomes invalid when its originating run is force-aborted or superseded.
+ * Coding-agent retry continuations must accept this argument and must not call
+ * `agent.continue()` after ownership has been lost.
+ */
+export interface ManagedAttemptContinuationOwnership {
+	/** Per-attempt run-loop id; use only for attempt-local ownership checks. */
+	readonly runId: number;
+	/** Stable managed logical-run id; use for all terminal completion requests. */
+	readonly logicalRunId: ManagedLogicalRunId;
+	readonly generation: number;
+	isCurrent(): boolean;
+}
+
+/** Runs after a discarded attempt is idle, only while its ownership token remains current. */
+export type ManagedAttemptContinuation = (ownership: ManagedAttemptContinuationOwnership) => void | Promise<void>;
+
+/** Decision returned by managed fallback policy for one provisional attempt. */
+export type ManagedAttemptDecision =
+	| { type: "retry"; continuation: ManagedAttemptContinuation }
+	| { type: "maintenance"; continuation: ManagedAttemptContinuation }
+	| { type: "terminal"; terminal: RunTerminalRequest };
+
+/** Structured result for one managed upstream invocation. */
+export type ManagedAttemptOutcome =
+	| {
+			type: "retryable_discarded";
+			failure: {
+				message: AssistantMessage;
+				/** Exact provider transport facts, including retry headers, for fallback policy. */
+				transportFailure?: TransportFailureFacts;
+			};
+	  }
+	| { type: "context_overflow_discarded"; message: AssistantMessage }
+	| { type: "run_terminal"; reason: "cancelled" | "error" | "exhausted" };
+
+export type ManagedAttemptOutcomeHandler = (
+	outcome: ManagedAttemptOutcome,
+) => ManagedAttemptDecision | Promise<ManagedAttemptDecision>;
+
+/**
+ * Outcome of a cooperative mid-run context-maintenance checkpoint (see
+ * {@link AgentLoopConfig.maintainContext}). Any value other than "not-needed"
+ * means the checkpoint mutated (or attempted to mutate) durable context, so the
+ * loop ends the current run without the lossy `agent_end` finalization and the
+ * maintenance owner resumes the run on the rewritten context.
+ */
+export type MidRunMaintenanceOutcome = "not-needed" | "pruned" | "compacted" | "promoted" | "failed" | "aborted";
+
 /**
  * Configuration for the agent loop.
  */
 export interface AgentLoopConfig extends SimpleStreamOptions {
 	model: Model;
+	/**
+	 * Supplies a fresh opaque token at each concrete managed transport invocation.
+	 * The callback runs at the stream boundary so controller accounting matches
+	 * upstream request count, including multi-step tool turns.
+	 */
+	nextFallbackAttempt?: (model: Model) => SimpleStreamOptions["fallbackAttempt"];
+	/** Called after a managed upstream request is accepted and committed. */
+	onManagedAttemptAccepted?: () => void | Promise<void>;
+
+	/** Receives a managed invocation outcome without publishing provisional lifecycle events. */
+	onManagedAttemptOutcome?: ManagedAttemptOutcomeHandler;
 
 	/**
 	 * When to interrupt tool execution for steering messages.
@@ -161,6 +235,33 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
 	 */
 	syncContextBeforeModelCall?: (context: AgentContext) => void | Promise<void>;
 
+	/**
+	 * Cooperative mid-run context-maintenance checkpoint.
+	 *
+	 * Invoked at the top of every loop iteration AFTER pending tool-result /
+	 * steering messages have been materialized into durable context and BEFORE
+	 * {@link syncContextBeforeModelCall} and the model call. This is the only
+	 * boundary where the full unsent context (tool results + dequeued steering)
+	 * is already durable, so a long uninterrupted tool loop can be bounded here
+	 * before it grows past the provider window.
+	 *
+	 * The callback owns the maintenance decision (prune / compact / promote) and
+	 * receives the minimal cancellation-aware lifecycle: `signal` is the
+	 * non-optional loop signal, and `awaitEventDrain(invocationSignal)` waits for
+	 * prior event consumer bodies with loop and invocation cancellation composed.
+	 * Any outcome other than "not-needed" ends the current run with
+	 * `agent_end.stopReason === "maintenance"` (NOT the lossy pause / completed
+	 * finalization); the callback's continuation owner resumes the run on the
+	 * rewritten context.
+	 */
+	maintainContext?: (
+		context: AgentContext,
+		lifecycle: {
+			signal: AbortSignal;
+			awaitEventDrain: (invocationSignal: AbortSignal) => Promise<void>;
+		},
+	) => Promise<MidRunMaintenanceOutcome> | MidRunMaintenanceOutcome;
+
 	/**
 	 * Optional transform applied to tool call arguments before execution.
 	 * Use for deobfuscating secrets or rewriting arguments.
@@ -357,7 +458,7 @@ export type AgentMessage = Message | CustomAgentMessages[keyof CustomAgentMessag
  */
 export interface AgentState {
 	systemPrompt: string[];
-	model: Model;
+	model: Model | undefined;
 	thinkingLevel?: Effort;
 	tools: AgentTool<any>[];
 	messages: AgentMessage[]; // Can include attachments + custom message types
@@ -470,8 +571,10 @@ export type AgentEvent =
 	| {
 			type: "agent_end";
 			messages: AgentMessage[];
-			/** Indicates whether the loop ended normally or suspended at a pause checkpoint. */
-			stopReason?: "completed" | "paused";
+			/** Indicates whether the loop ended normally, suspended, cancelled, or entered maintenance. */
+			stopReason?: "completed" | "paused" | "cancelled" | "maintenance";
+			/** Present iff `stopReason === "maintenance"`; the maintenance outcome. */
+			maintenanceOutcome?: MidRunMaintenanceOutcome;
 			/** Present iff `AgentTelemetryConfig` was supplied on this run. */
 			telemetry?: AgentRunSummary;
 			coverage?: AgentRunCoverage;

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

@@ -1,56 +0,0 @@
-/**
- * Agent loop that works with AgentMessage throughout.
- * Transforms to Message[] only at the LLM call boundary.
- */
-import { type Context, EventStream } from "@sayknow-cli/ai";
-import { type AgentRunCoverage, type AgentRunSummary } from "./run-collector";
-import type { AgentContext, AgentEvent, AgentLoopConfig, AgentMessage, StreamFn } from "./types";
-/**
- * Start an agent loop with a new prompt message.
- * The prompt is added to the context and events are emitted for it.
- */
-export declare function agentLoop(prompts: AgentMessage[], context: AgentContext, config: AgentLoopConfig, signal?: AbortSignal, streamFn?: StreamFn): EventStream<AgentEvent, AgentMessage[]>;
-/**
- * Continue an agent loop from the current context without adding a new message.
- * Used for retries - context already has user message or tool results.
- *
- * **Important:** The last message in context must convert to a `user` or `toolResult` message
- * via `convertToLlm`. If it doesn't, the LLM provider will reject the request.
- * This cannot be validated here since `convertToLlm` is only called once per turn.
- */
-export declare function agentLoopContinue(context: AgentContext, config: AgentLoopConfig, signal?: AbortSignal, streamFn?: StreamFn): EventStream<AgentEvent, AgentMessage[]>;
-/**
- * Detailed-result handle returned by {@link agentLoopDetailed}. Adds the
- * run-level telemetry/coverage rollup to the existing `AgentMessage[]`
- * payload without changing the resolved type of `stream.result()`.
- */
-export interface AgentLoopDetailedResult {
-    readonly messages: AgentMessage[];
-    readonly telemetry: AgentRunSummary | undefined;
-    readonly coverage: AgentRunCoverage | undefined;
-}
-/**
- * Convenience wrapper over {@link agentLoop} that exposes the run-level
- * summary + coverage alongside the messages. The returned `stream` is the
- * same `EventStream` callers already consume; `detailed()` awaits the
- * stream's `agent_end` event and returns the additive fields.
- *
- * Existing `stream.result()` semantics are preserved — it still resolves to
- * `AgentMessage[]`. Use {@link agentLoopDetailed} when you need the rollup;
- * use {@link agentLoop} when you do not.
- */
-export declare function agentLoopDetailed(prompts: AgentMessage[], context: AgentContext, config: AgentLoopConfig, signal?: AbortSignal, streamFn?: StreamFn): {
-    readonly stream: EventStream<AgentEvent, AgentMessage[]>;
-    readonly detailed: () => Promise<AgentLoopDetailedResult>;
-};
-/**
- * Like {@link agentLoopDetailed} but built on top of
- * {@link agentLoopContinue}.
- */
-export declare function agentLoopContinueDetailed(context: AgentContext, config: AgentLoopConfig, signal?: AbortSignal, streamFn?: StreamFn): {
-    readonly stream: EventStream<AgentEvent, AgentMessage[]>;
-    readonly detailed: () => Promise<AgentLoopDetailedResult>;
-};
-export declare function normalizeMessagesForProvider(messages: Context["messages"], model: AgentLoopConfig["model"]): Context["messages"];
-export declare const INTENT_FIELD = "_i";
-export declare function normalizeTools(tools: AgentContext["tools"], injectIntent: boolean): Context["tools"];