@aigne/afs-agent 1.11.0-beta.13

package/dist/index.mjs

@@ -0,0 +1,3667 @@
+import { ASH_EVENT_TYPES, makeNsLog } from "@aigne/afs";
+import { validateToolCall } from "@aigne/afs-ash";
+import { parseSkillFrontmatter } from "@aigne/afs-skills/format";
+import { joinURL } from "ufo";
+import { randomUUID } from "node:crypto";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { AFSBaseProvider, Actions, Stat } from "@aigne/afs/provider";
+import { z } from "zod";
+import { join } from "node:path";
+import { load } from "js-yaml";
+
+//#region src/ash-generator.ts
+/**
+* Format a value as an ASH inline literal.
+* Strings get quoted, numbers/booleans are bare.
+*/
+function formatValue(v) {
+	if (typeof v === "string") return JSON.stringify(v);
+	if (typeof v === "number" || typeof v === "boolean") return String(v);
+	return JSON.stringify(v);
+}
+/**
+* Format args as ASH inline object: { key: "val", num: 42 }
+*/
+function formatInlineArgs(args) {
+	const entries = Object.entries(args);
+	if (entries.length === 0) return "";
+	return ` { ${entries.map(([k, v]) => `${k}: ${formatValue(v)}`).join(", ")} }`;
+}
+/**
+* Generate a single pipeline statement for a tool call.
+*/
+function generateStatement(call) {
+	const resultPath = `/.results/${call.id}`;
+	if (call.op === "read" || call.op === "list") return `find ${call.path} | save ${resultPath}`;
+	const inlineArgs = formatInlineArgs(call.args);
+	return `action ${call.path}${inlineArgs} | save ${resultPath}`;
+}
+/**
+* Derive @caps declaration from the calls in this round.
+*
+* Capabilities:
+* - read: for read/list ops (exact path)
+* - exec: for exec ops (exact path)
+* - write: always /.results/* (where save goes)
+*/
+function deriveCaps(calls) {
+	const parts = [];
+	for (const call of calls) if (call.op === "read" || call.op === "list") parts.push(`read ${call.path}`);
+	else if (call.op === "exec") parts.push(`exec ${call.path}`);
+	parts.push("write /.results/*");
+	return `@caps(${parts.join(" ")})`;
+}
+/**
+* Generate a complete ASH program from validated tool calls.
+*
+* Each call becomes a separate pipeline within a single job.
+* The program is scoped with @caps derived from actual paths.
+*/
+function generateAsh(calls, round) {
+	const caps = deriveCaps(calls);
+	const statements = calls.map(generateStatement);
+	return `${caps}\njob round_${round} {\n  ${statements.length > 0 ? statements.join("\n  ") : "output \"no-op\""}\n}`;
+}
+
+//#endregion
+//#region src/token-estimator.ts
+/**
+* Lightweight token estimation based on character types.
+*
+* Uses empirical heuristics for CJK characters, English words, and other characters
+* to approximate token counts without requiring an external tokenizer.
+*/
+/** CJK Unified Ideographs + Extension A + Compatibility + Hiragana + Katakana */
+const CJK_PATTERN = /[\u4e00-\u9fff\u3400-\u4dbf\uf900-\ufaff\u3040-\u309f\u30a0-\u30ff]/g;
+/** Consecutive ASCII letter sequences (English words) */
+const WORD_PATTERN = /[a-zA-Z]+/g;
+/** CJK: ~1.5 characters per token */
+const CJK_CHARS_PER_TOKEN = 1.5;
+/** English: ~1 token per word (conservative estimate) */
+const TOKENS_PER_WORD = 1;
+/**
+* Estimate token count for a text string.
+*
+* Uses character-type-aware heuristics:
+* - CJK characters: ~1.5 chars per token
+* - English words: ~1 token per word
+* - Other characters (punctuation, digits, whitespace): ~1 char per token
+*/
+function estimateTokens(text) {
+	if (!text) return 0;
+	let tokens = 0;
+	let accountedChars = 0;
+	const cjkMatches = text.match(CJK_PATTERN);
+	if (cjkMatches) {
+		tokens += cjkMatches.length / CJK_CHARS_PER_TOKEN;
+		accountedChars += cjkMatches.length;
+	}
+	const wordMatches = text.match(WORD_PATTERN);
+	if (wordMatches) {
+		tokens += wordMatches.length * TOKENS_PER_WORD;
+		for (const w of wordMatches) accountedChars += w.length;
+	}
+	const remaining = text.length - accountedChars;
+	if (remaining > 0) tokens += remaining;
+	return Math.ceil(tokens);
+}
+/**
+* Estimate total tokens for an array of messages (OpenAI format).
+*
+* Handles:
+* - `content` (string) — text tokens, capped per message
+* - `toolCalls` / `tool_calls` — function name + arguments + structure overhead
+*
+* @param singleMessageLimit - Max tokens counted per individual message content
+*   (prevents a single huge tool result from dominating the estimate)
+*/
+function estimateMessagesTokens(messages, singleMessageLimit = Number.POSITIVE_INFINITY) {
+	let total = 0;
+	for (const msg of messages) {
+		let msgTokens = 0;
+		const content = msg.content;
+		if (typeof content === "string") msgTokens += Math.min(estimateTokens(content), singleMessageLimit);
+		const toolCalls = msg.toolCalls ?? msg.tool_calls;
+		if (Array.isArray(toolCalls)) for (const tc of toolCalls) {
+			const fn = tc.function;
+			if (fn) {
+				msgTokens += estimateTokens(String(fn.name ?? ""));
+				const args = fn.arguments;
+				msgTokens += estimateTokens(typeof args === "string" ? args : JSON.stringify(args ?? {}));
+				msgTokens += 10;
+			}
+		}
+		total += msgTokens;
+	}
+	return total;
+}
+
+//#endregion
+//#region src/context.ts
+const DEFAULT_MEMORY_MAX_TOKENS = 2e3;
+/**
+* Convert JSONL content (from archived sessions) into a readable conversation format.
+* Non-JSONL content is returned as-is.
+*/
+function formatRecallContent(content) {
+	const lines = content.split("\n");
+	if (lines.length === 0) return content;
+	const formatted = [];
+	let hasJson = false;
+	for (const line of lines) {
+		const trimmed = line.trim();
+		if (!trimmed) continue;
+		try {
+			const msg = JSON.parse(trimmed);
+			if (msg.role && msg.content) {
+				formatted.push(`[${msg.role}]: ${msg.content}`);
+				hasJson = true;
+			} else formatted.push(trimmed);
+		} catch {
+			formatted.push(trimmed);
+		}
+	}
+	return hasJson && formatted.length > 0 ? formatted.join("\n") : content;
+}
+async function buildMemoryContext(afs, opts, task) {
+	let recallResult;
+	try {
+		recallResult = await afs.exec(opts.recallPath, {
+			text: task,
+			scope: opts.domain,
+			limit: 30
+		}, {});
+	} catch {
+		return null;
+	}
+	if (!recallResult.success) return null;
+	const data = recallResult.data;
+	const layers = data?.layers;
+	if (!Array.isArray(layers) || layers.length === 0) return null;
+	const maxTokens = opts.maxTokens ?? DEFAULT_MEMORY_MAX_TOKENS;
+	const l3 = layers.find((l) => l.level === "L3");
+	const l2 = layers.find((l) => l.level === "L2");
+	const parts = [];
+	const sources = [];
+	let tokens = 0;
+	for (const layer of [l3, l2]) {
+		if (!layer?.entries) continue;
+		for (const entry of layer.entries) {
+			if (!entry.content) continue;
+			const readable = formatRecallContent(entry.content);
+			const t = estimateTokens(readable);
+			if (tokens + t > maxTokens) continue;
+			parts.push(readable);
+			sources.push(entry.path);
+			tokens += t;
+		}
+	}
+	if (parts.length === 0) return null;
+	return {
+		text: parts.join("\n\n---\n\n"),
+		trace: {
+			tokens,
+			entries: parts.length,
+			sources
+		},
+		query: task,
+		available: data?.totalAvailable
+	};
+}
+/**
+* Assemble a messages array for LLM calls.
+*
+* Output order: [system, ...history, user]
+*
+* System message = system prompt + memory recall + directives.
+* Without memory, output is identical to agent-run's current hand-assembled messages.
+* Memory failures silently fall back to the no-memory path.
+*/
+async function buildContext(afs, opts) {
+	let memoryResult = null;
+	if (opts.memory) memoryResult = await buildMemoryContext(afs, opts.memory, opts.task);
+	const systemParts = [];
+	if (opts.system) systemParts.push(opts.system);
+	if (memoryResult) systemParts.push(`\n## Relevant memories\n${memoryResult.text}`);
+	if (opts.directives) {
+		for (const d of opts.directives) if (d) systemParts.push(d);
+	}
+	const systemContent = systemParts.join("\n\n");
+	const messages = [];
+	messages.push({
+		role: "system",
+		content: systemContent
+	});
+	if (opts.history) for (const msg of opts.history) messages.push(msg);
+	messages.push({
+		role: "user",
+		content: opts.task
+	});
+	const systemTokens = estimateTokens(systemContent);
+	const userTokens = estimateTokens(opts.task);
+	const historyTokens = opts.history ? estimateMessagesTokens(opts.history) : 0;
+	const historyCount = opts.history?.length ?? 0;
+	const manifest = {
+		memory: {
+			selected: memoryResult?.trace.sources ?? [],
+			query: opts.memory ? opts.task : void 0,
+			available: memoryResult?.available
+		},
+		history: {
+			keptTurns: historyCount,
+			truncatedTurns: 0,
+			compressed: false
+		},
+		tools: { included: [] }
+	};
+	return {
+		messages,
+		trace: {
+			system: { tokens: systemTokens },
+			memory: memoryResult?.trace ?? null,
+			history: {
+				tokens: historyTokens,
+				messages: historyCount
+			},
+			user: { tokens: userTokens },
+			total: systemTokens + historyTokens + userTokens,
+			manifest
+		}
+	};
+}
+
+//#endregion
+//#region src/context-compress.ts
+const DEFAULT_CONTEXT_WINDOW$1 = 8e4;
+/** Trigger compression when messages exceed this ratio of context window */
+const TRIGGER_RATIO = .7;
+/** Keep recent messages up to this ratio of context window */
+const KEEP_RECENT_RATIO = .35;
+/** Timeout for the compression LLM call (ms) */
+const COMPRESS_TIMEOUT_MS = 6e4;
+/** Max characters for the formatted summary input sent to LLM */
+const MAX_SUMMARY_INPUT_CHARS = 3e4;
+/** Per-tool-result truncation limit for summary formatting */
+const TOOL_RESULT_TRUNCATE = 500;
+/** System prompt for the summarizer LLM call */
+const COMPRESS_SYSTEM_PROMPT = `You are a conversation compressor. Your task is to losslessly compress the provided conversation into a structured summary that preserves ALL important context for future conversation continuity.
+
+You are NOT the assistant — do not respond to the user or continue the conversation. You are an external summarizer.
+
+Output format — use this exact structure:
+
+## User Profile
+<Who the user is: name, role, expertise, preferences — if mentioned>
+
+## Conversation Summary
+<Chronological summary of what happened: topics discussed, questions asked, actions taken, tools called and their outcomes>
+
+## Key Decisions & Facts
+<Bullet list of specific decisions made, facts established, paths/URLs/IDs mentioned, configurations set>
+
+## Current State
+<Where things stand: what was accomplished, what is in progress, any errors or blockers encountered>
+
+## Open Items
+<Pending tasks, unanswered questions, follow-up items — if any>
+
+Rules:
+- Preserve specific details: names, file paths, IDs, error messages, config values
+- Include tool call outcomes (what was called, what it returned in brief)
+- Write in the same language the user used in the conversation
+- Be thorough — it is better to include too much than to lose critical context
+- If a section has no content, write "None" and move on`;
+async function maybeCompress(messages, opts) {
+	const contextWindow = opts.contextWindow ?? DEFAULT_CONTEXT_WINDOW$1;
+	const triggerThreshold = Math.floor(contextWindow * TRIGGER_RATIO);
+	const keepRecentTokens = Math.floor(contextWindow * KEEP_RECENT_RATIO);
+	const totalTokens = estimateMessagesTokens(messages);
+	if (totalTokens <= triggerThreshold) {
+		opts.onProgress?.({
+			phase: "skipped",
+			beforeTokens: totalTokens,
+			contextWindow
+		});
+		return messages;
+	}
+	let systemMessage;
+	let contentStart = 0;
+	if (messages.length > 0 && messages[0].role === "system") {
+		systemMessage = messages[0];
+		contentStart = 1;
+	}
+	const singleMessageLimit = Math.floor(keepRecentTokens * .5);
+	let splitIndex = messages.length;
+	let recentTokens = 0;
+	for (let i = messages.length - 1; i >= contentStart; i--) {
+		const msgTokens = estimateMessagesTokens([messages[i]], singleMessageLimit);
+		if (recentTokens + msgTokens > keepRecentTokens) {
+			splitIndex = i + 1;
+			break;
+		}
+		recentTokens += msgTokens;
+		splitIndex = i;
+	}
+	if (splitIndex <= contentStart) {
+		splitIndex = messages.length;
+		recentTokens = 0;
+		for (let i = messages.length - 1; i >= contentStart; i--) {
+			const msgTokens = estimateMessagesTokens([messages[i]]);
+			if (recentTokens + msgTokens > keepRecentTokens) {
+				splitIndex = i + 1;
+				break;
+			}
+			recentTokens += msgTokens;
+			splitIndex = i;
+		}
+	}
+	splitIndex = adjustSplitForMessageBoundary(messages, splitIndex, contentStart);
+	const pinIdx = opts.pinMessage && contentStart > 0 ? messages.indexOf(opts.pinMessage, contentStart) : opts.pinMessage ? messages.indexOf(opts.pinMessage) : -1;
+	const pinValid = pinIdx >= contentStart;
+	const pinInCompressZone = pinValid && !(pinValid && pinIdx >= splitIndex);
+	const pinnedMessage = pinValid ? messages[pinIdx] : void 0;
+	const toCompress = [];
+	for (let i = contentStart; i < splitIndex; i++) {
+		if (i === pinIdx) continue;
+		toCompress.push(messages[i]);
+	}
+	const toKeep = messages.slice(splitIndex);
+	if (toCompress.length === 0) return messages;
+	const baseProgress = {
+		beforeTokens: totalTokens,
+		contextWindow,
+		compressedMessages: toCompress.length,
+		keptMessages: toKeep.length
+	};
+	opts.onProgress?.({
+		phase: "triggered",
+		...baseProgress
+	});
+	try {
+		const formatted = formatMessagesForSummary(toCompress);
+		opts.onProgress?.({
+			phase: "summarizing",
+			...baseProgress
+		});
+		const compressResult = await Promise.race([opts.callLLM({ messages: [{
+			role: "system",
+			content: COMPRESS_SYSTEM_PROMPT
+		}, {
+			role: "user",
+			content: formatted
+		}] }), new Promise((_, reject) => setTimeout(() => reject(/* @__PURE__ */ new Error("Compression LLM call timed out")), COMPRESS_TIMEOUT_MS))]);
+		if (!compressResult.success) return compressFallback(systemMessage, toKeep, toCompress, baseProgress, opts, "LLM call failed", pinInCompressZone ? pinnedMessage : void 0);
+		const summary = compressResult.data?.text;
+		if (typeof summary !== "string" || !summary.trim()) return compressFallback(systemMessage, toKeep, toCompress, baseProgress, opts, "Empty summary", pinInCompressZone ? pinnedMessage : void 0);
+		const result = [];
+		if (systemMessage) result.push(systemMessage);
+		if (pinInCompressZone && pinnedMessage) result.push(pinnedMessage);
+		result.push({
+			role: "user",
+			content: `[Previous conversation summary]\n${summary.trim()}`
+		});
+		result.push(...toKeep);
+		const afterTokens = estimateMessagesTokens(result);
+		opts.onProgress?.({
+			phase: "done",
+			...baseProgress,
+			afterTokens
+		});
+		if (opts.onCompressed) try {
+			await opts.onCompressed(result, toCompress);
+		} catch {}
+		return result;
+	} catch (err) {
+		return compressFallback(systemMessage, toKeep, toCompress, baseProgress, opts, err instanceof Error ? err.message : String(err), pinInCompressZone ? pinnedMessage : void 0);
+	}
+}
+/**
+* Fallback when LLM-based compression fails (timeout, error, empty summary).
+* Drops compressed messages and inserts a "[conversation history truncated]"
+* placeholder so the agent can continue instead of looping.
+*/
+function compressFallback(systemMessage, toKeep, toCompress, baseProgress, opts, error, pinnedMessage) {
+	const result = [];
+	if (systemMessage) result.push(systemMessage);
+	if (pinnedMessage) result.push(pinnedMessage);
+	result.push({
+		role: "user",
+		content: `[Previous conversation history was truncated due to context limits. ${toCompress.length} older messages were removed.]`
+	});
+	result.push(...toKeep);
+	const afterTokens = estimateMessagesTokens(result);
+	opts.onProgress?.({
+		phase: "done",
+		...baseProgress,
+		afterTokens,
+		error: `Fallback truncation: ${error}`
+	});
+	if (opts.onCompressed) try {
+		opts.onCompressed(result, toCompress);
+	} catch {}
+	return result;
+}
+/**
+* Adjust splitIndex so it doesn't break tool_call/tool_result groups.
+*
+* Rules:
+* 1. Keep zone must not start with a tool message (orphaned result without parent assistant).
+*    → Walk backward to include the parent assistant+tool_calls.
+* 2. Compress zone must not end with assistant+tool_calls whose results are in keep zone.
+*    → Move that assistant into keep zone.
+*/
+function adjustSplitForMessageBoundary(messages, splitIndex, contentStart) {
+	if (splitIndex <= contentStart || splitIndex >= messages.length) return splitIndex;
+	while (splitIndex > contentStart && messages[splitIndex]?.role === "tool") splitIndex--;
+	if (splitIndex > contentStart) {
+		const lastCompress = messages[splitIndex - 1];
+		const toolCalls = lastCompress?.toolCalls ?? lastCompress?.tool_calls;
+		if (Array.isArray(toolCalls) && toolCalls.length > 0) splitIndex--;
+	}
+	return splitIndex;
+}
+/**
+* Format a single message into a readable line for the summarizer.
+*/
+function formatSingleMessage(msg) {
+	const role = String(msg.role ?? "unknown");
+	const content = String(msg.content ?? "");
+	const toolCalls = msg.toolCalls ?? msg.tool_calls;
+	if (Array.isArray(toolCalls) && toolCalls.length > 0) {
+		const callSummary = toolCalls.map((tc) => `${tc.function?.name ?? "unknown"}(...)`).join(", ");
+		return `[${role}] ${content.slice(0, 500)}\n  Tool calls: ${callSummary}`;
+	}
+	if (role === "tool") return `[tool result] ${content.slice(0, TOOL_RESULT_TRUNCATE)}`;
+	return `[${role}] ${content.slice(0, 1e3)}`;
+}
+/**
+* Format messages into a readable text block for the summarizer.
+*
+* Uses a two-end strategy: prioritize the earliest messages (conversation start,
+* often contains user identity and goals) and the most recent messages (current
+* context and latest actions). Middle messages are omitted if budget is exceeded.
+*/
+function formatMessagesForSummary(messages) {
+	const headBudget = Math.floor(MAX_SUMMARY_INPUT_CHARS * .4);
+	const tailBudget = Math.floor(MAX_SUMMARY_INPUT_CHARS * .6);
+	const headParts = [];
+	let headLen = 0;
+	let headEnd = 0;
+	for (let i = 0; i < messages.length; i++) {
+		const line = formatSingleMessage(messages[i]);
+		if (headLen + line.length + 2 > headBudget) break;
+		headParts.push(line);
+		headLen += line.length + 2;
+		headEnd = i + 1;
+	}
+	const tailParts = [];
+	let tailLen = 0;
+	let tailStart = messages.length;
+	for (let i = messages.length - 1; i >= headEnd; i--) {
+		const line = formatSingleMessage(messages[i]);
+		if (tailLen + line.length + 2 > tailBudget) break;
+		tailParts.unshift(line);
+		tailLen += line.length + 2;
+		tailStart = i;
+	}
+	const omitted = tailStart - headEnd;
+	if (omitted > 0) return [
+		...headParts,
+		`\n[... ${omitted} messages omitted ...]\n`,
+		...tailParts
+	].join("\n\n");
+	return [...headParts, ...tailParts].join("\n\n");
+}
+
+//#endregion
+//#region src/observability.ts
+/**
+* Agent-run observability helpers (Phase 0.5 jsonl).
+*
+* One run = one .jsonl file under `/instance/logs/agent-runs/{date}/`. Each line
+* is one event with `type` discriminator + monotonic `seq` + ms `ts`. Writes go
+* through the standard `callAFS("write", path, { content, mode: "append" })`
+* interface so a future AFSLog provider can be mounted at `/instance/logs/`
+* without touching application code.
+*
+* - `safeStringifyLine`: JSON.stringify with no indent, circular/BigInt/Date/
+*   Symbol/Function handling, plus per-line size cap via largest-field-first
+*   truncation.
+* - `truncateField`: per-field truncation marker for over-budget strings + nested objects.
+* - `stripInternalFields`: drops `_*` prefixed keys from recorded toolCall args
+*   (prevents `_scope_afs` / `_abort_signal` etc. from leaking into the log).
+*/
+const FIELD_LIMIT = 64 * 1024;
+const EVENT_LIMIT = 256 * 1024;
+function buildReplacer() {
+	const seen = /* @__PURE__ */ new WeakSet();
+	return (_key, val) => {
+		if (typeof val === "bigint") return `${val.toString()}n`;
+		if (val instanceof Date) return val.toISOString();
+		if (typeof val === "function") return "[Function]";
+		if (typeof val === "symbol") return val.toString();
+		if (val && typeof val === "object") {
+			if (seen.has(val)) return "[Circular]";
+			seen.add(val);
+		}
+		return val;
+	};
+}
+/**
+* Stringify a single jsonl event into one line (no indent). Returns valid JSON
+* even for `undefined` (which `JSON.stringify` would otherwise yield as
+* `undefined` and break a `JSON.parse` round-trip).
+*
+* If the line exceeds `EVENT_LIMIT`, the largest fields are truncated until the
+* line fits; truncated fields gain `_truncated: true` + `_originalSize` markers.
+*/
+function safeStringifyLine(value, maxEventSize = EVENT_LIMIT) {
+	if (value === void 0) return JSON.stringify({
+		_serialization_failed: true,
+		error: "input is undefined"
+	});
+	let json;
+	try {
+		json = JSON.stringify(value, buildReplacer());
+	} catch (err) {
+		return JSON.stringify({
+			_serialization_failed: true,
+			error: err instanceof Error ? err.message : String(err)
+		});
+	}
+	if (json.length > maxEventSize && value !== null && typeof value === "object" && !Array.isArray(value)) return truncateOversizedLine(value, maxEventSize);
+	return json;
+}
+function truncateOversizedLine(obj, maxEventSize) {
+	const truncated = { ...obj };
+	const fieldSizes = [];
+	for (const k of Object.keys(truncated)) {
+		let size;
+		try {
+			size = JSON.stringify(truncated[k], buildReplacer()).length;
+		} catch {
+			size = 0;
+		}
+		fieldSizes.push([k, size]);
+	}
+	fieldSizes.sort((a, b) => b[1] - a[1]);
+	for (const [k] of fieldSizes) {
+		truncated[k] = truncateField(truncated[k], FIELD_LIMIT);
+		let sized;
+		try {
+			sized = JSON.stringify(truncated, buildReplacer()).length;
+		} catch {
+			sized = maxEventSize + 1;
+		}
+		if (sized <= maxEventSize) break;
+	}
+	try {
+		return JSON.stringify(truncated, buildReplacer());
+	} catch (err) {
+		return JSON.stringify({
+			_serialization_failed: true,
+			error: err instanceof Error ? err.message : String(err)
+		});
+	}
+}
+function truncateField(value, limit) {
+	if (value === null || value === void 0) return value;
+	if (typeof value === "string") {
+		if (value.length > limit) return {
+			_truncated: true,
+			_originalSize: value.length,
+			content: value.slice(0, limit)
+		};
+		return value;
+	}
+	let json;
+	try {
+		json = JSON.stringify(value, buildReplacer());
+	} catch {
+		return {
+			_truncated: true,
+			_serialization_failed: true
+		};
+	}
+	if (json.length > limit) return {
+		_truncated: true,
+		_originalSize: json.length,
+		content: json.slice(0, limit)
+	};
+	return value;
+}
+function stripInternalFields(args) {
+	const cleaned = {};
+	for (const [k, v] of Object.entries(args)) if (!k.startsWith("_")) cleaned[k] = v;
+	return cleaned;
+}
+
+//#endregion
+//#region src/tool-schema.ts
+const OP_DEFINITIONS = {
+	read: {
+		name: "afs_read",
+		description: "Read RAW content at an AFS path. Use this ONLY when you already know the path is a data file and you want its bytes (e.g. /data/persona.md, a log). DO NOT use `afs_read` to learn how something works or discover capabilities — use `afs_explain` for that; `afs_explain` returns a curated guide (markdown with usage, warnings, required next steps) that raw reads omit, and skipping it causes agents to miss mandatory post-mount setup and write broken workarounds.\nTo read SEVERAL files (e.g. every child a list just returned), pass `entries` in ONE call and OMIT `path` — never loop single reads. Batch results are per-entry: check each results[i].success, partial success is normal (a missing file fails alone).",
+		extraProps: { entries: {
+			type: "array",
+			description: "Batch mode: array of {path} entries, up to 16 per call. When provided, top-level `path` is ignored. Chunk larger sets into multiple calls.",
+			items: {
+				type: "object",
+				properties: { path: {
+					type: "string",
+					description: "AFS path to read"
+				} },
+				required: ["path"]
+			}
+		} },
+		extraRequired: [],
+		pathOptional: true
+	},
+	list: {
+		name: "afs_list",
+		description: "List directory contents at an AFS path",
+		extraProps: {
+			depth: {
+				type: "number",
+				description: "Recursion depth (default 1)"
+			},
+			pattern: {
+				type: "string",
+				description: "Filter pattern, e.g. *.md"
+			}
+		},
+		extraRequired: []
+	},
+	exec: {
+		name: "afs_exec",
+		description: "Execute an action at an AFS path. IMPORTANT: Before calling, use afs_list on the parent path's .actions/ to discover available actions and their inputSchema, then pass the required fields in args.",
+		extraProps: { args: {
+			type: "object",
+			description: "Action arguments matching the action's inputSchema"
+		} },
+		extraRequired: []
+	},
+	search: {
+		name: "afs_search",
+		description: "Search for content within an AFS path",
+		extraProps: { query: {
+			type: "string",
+			description: "Search query"
+		} },
+		extraRequired: ["query"]
+	},
+	write: {
+		name: "afs_write",
+		description: "Write content to an AFS path. Eight modes cover most cases without read-modify-write loops:\n  - replace (default) — overwrite path with `content`.\n  - append / prepend — add `content` at end / start of existing.\n  - patch — str_replace inside existing content (legacy).\n  - create / update — fail if path exists / doesn't exist.\n  - tree-merge — JSON-aware: merge `content` (a JSON-stringified object) into existing JSON, preserving sibling fields. Use this to flip a single field without re-writing the rest of the object.\n  - tree-toggle — flip a boolean field named by `field`. No `content` needed.\n  - tree-increment — add `by` (default 1) to a number field named by `field`. No `content` needed.\nProvide `path` for a single write. For multiple files, use batch mode: pass `entries` and OMIT the top-level `path` (it is ignored when `entries` is present) — never loop single writes. Batch is NOT a transaction: results are per-entry, check each results[i], partial success is normal.",
+		extraProps: {
+			content: {
+				type: "string",
+				description: "Content to write. For JSON files use a JSON-stringified object string. Ignored when `entries` is provided, and unused by tree-toggle / tree-increment."
+			},
+			mode: {
+				type: "string",
+				description: "Write mode. One of: replace (default), append, prepend, patch, create, update, tree-merge, tree-toggle, tree-increment."
+			},
+			field: {
+				type: "string",
+				description: "Field name on the JSON object — required for tree-toggle and tree-increment."
+			},
+			by: {
+				type: "number",
+				description: "Increment delta for tree-increment (default 1). Negative values decrement."
+			},
+			ifMatch: {
+				type: "string",
+				description: "Optimistic concurrency. Pass the opaque `version` returned by an earlier stat/read to fail the write (AFS_CONFLICT) if another writer changed the file in between."
+			},
+			entries: {
+				type: "array",
+				description: "Batch mode: array of {path, content, mode?} entries. When provided, top-level path/content/mode are ignored.",
+				items: {
+					type: "object",
+					properties: {
+						path: {
+							type: "string",
+							description: "AFS path to write to"
+						},
+						content: {
+							type: "string",
+							description: "Content to write"
+						},
+						mode: {
+							type: "string",
+							description: "Write mode (default: replace)"
+						}
+					},
+					required: ["path"]
+				}
+			}
+		},
+		extraRequired: [],
+		pathOptional: true
+	},
+	delete: {
+		name: "afs_delete",
+		description: "Delete an AFS path. Two modes: (1) Single-file delete: just `path`. (2) Batch delete on a directory: `path` is the directory + `where` is a predicate (a JSON-stringified object) matched against each child's content. Only matching children are deleted; the directory itself is kept. Use this for 'sweep' operations like clearing completed items in one call instead of list-then-loop.",
+		extraProps: {
+			where: {
+				type: "string",
+				description: "Optional. JSON-stringified predicate object. Each top-level key/value pair must match an entry's content for that entry to be deleted. Example: `\"{\\\"completed\\\":true}\"` deletes only entries whose JSON content has completed:true. Omit for single-file delete."
+			},
+			maxItems: {
+				type: "number",
+				description: "Optional cap on batch delete size (server enforces an upper bound). Use to limit blast radius when unsure."
+			}
+		},
+		extraRequired: []
+	},
+	stat: {
+		name: "afs_stat",
+		description: "Get metadata for an AFS path",
+		extraProps: {},
+		extraRequired: []
+	},
+	explain: {
+		name: "afs_explain",
+		description: "Get the curated guide for an AFS path. This is the DEFAULT first tool for discovery — always try this before `afs_read` or `afs_list` when investigating anything you don't already know how to use. Returns markdown: what the node is, how to invoke it, required fields, warnings, next steps. For providers in /registry/providers/*, the explain IS the mount guide — includes required post-mount setup (e.g. running a skill) that you MUST follow in full.",
+		extraProps: {},
+		extraRequired: []
+	}
+};
+/**
+* Build OpenAI function-calling tools from ToolEntry declarations.
+*
+* Deduplicates operations across entries — one tool per unique op.
+* Each tool's path description lists all allowed patterns for that op.
+*
+* When actionSchemas are provided (from startup discovery), generates
+* per-action tools (afs_action_{name}) with explicit typed parameters
+* so LLMs know exactly what fields each action requires.
+*/
+function buildToolSchema(tools, actionSchemas) {
+	const pathsByOp = /* @__PURE__ */ new Map();
+	const excludedActionsByOp = /* @__PURE__ */ new Map();
+	const maxDepthByOp = /* @__PURE__ */ new Map();
+	for (const entry of tools) for (const op of entry.ops) {
+		if (!pathsByOp.has(op)) pathsByOp.set(op, []);
+		const paths = pathsByOp.get(op);
+		if (!paths.includes(entry.path)) paths.push(entry.path);
+		if (entry.path.includes("**") && entry.maxDepth != null) {
+			if (!maxDepthByOp.has(op)) maxDepthByOp.set(op, /* @__PURE__ */ new Map());
+			maxDepthByOp.get(op).set(entry.path, entry.maxDepth);
+		}
+		if (op === "exec" && entry.exclude_actions?.length) {
+			if (!excludedActionsByOp.has(op)) excludedActionsByOp.set(op, []);
+			const excluded = excludedActionsByOp.get(op);
+			for (const a of entry.exclude_actions) if (!excluded.includes(a)) excluded.push(a);
+		}
+	}
+	const result = [];
+	for (const [op, paths] of pathsByOp) {
+		const def = OP_DEFINITIONS[op];
+		if (!def) continue;
+		const depthMap = maxDepthByOp.get(op);
+		const hasDstar = paths.some((p) => p.includes("**"));
+		let pathDesc = `AFS path. Allowed: ${paths.join(", ")}.`;
+		if (hasDstar && depthMap) {
+			const depthNotes = [...depthMap.entries()].map(([p, d]) => `${p} (maxDepth ${d})`).join(", ");
+			pathDesc += ` ** matches multiple levels: ${depthNotes}.`;
+		}
+		pathDesc += " Note: * matches one level only (e.g. /a/* matches /a/b but NOT /a/b/c).";
+		const excluded = excludedActionsByOp.get(op);
+		if (excluded?.length) pathDesc += ` Excluded actions: ${excluded.join(", ")}.`;
+		let description = def.description;
+		let extraProps = def.extraProps;
+		let extraRequired = def.extraRequired;
+		if (op === "exec" && actionSchemas?.length) {
+			description = `Execute an action. Pass the action's parameters in args.
+Available actions:\n${actionSchemas.map((a) => {
+				const fields = Object.entries(a.inputSchema?.properties ?? {}).map(([k, v]) => {
+					const req = a.inputSchema?.required?.includes(k) ? " (required)" : "";
+					let typeStr = v.type ?? "string";
+					if (typeStr === "object" && v.additionalProperties) typeStr = "object (map)";
+					if (typeStr === "array" && v.items) typeStr = "array";
+					return `${k}: ${typeStr}${req}`;
+				}).join(", ");
+				return `- ${a.pathPattern}: {${fields || "none"}} — ${a.description}`;
+			}).join("\n")}`;
+			extraRequired = ["args"];
+			const mergedProps = {};
+			for (const a of actionSchemas) if (a.inputSchema?.properties) for (const [k, v] of Object.entries(a.inputSchema.properties)) mergedProps[k] = {
+				...v,
+				type: v.type ?? "string"
+			};
+			extraProps = { args: {
+				type: ["object", "null"],
+				description: "Action arguments matching the action's inputSchema",
+				...Object.keys(mergedProps).length > 0 ? { properties: mergedProps } : {}
+			} };
+		}
+		result.push({
+			type: "function",
+			function: {
+				name: def.name,
+				description,
+				parameters: {
+					type: "object",
+					properties: {
+						path: {
+							type: "string",
+							description: pathDesc
+						},
+						...extraProps
+					},
+					required: def.pathOptional ? [...extraRequired] : ["path", ...extraRequired]
+				}
+			}
+		});
+	}
+	return result;
+}
+
+//#endregion
+//#region src/agent-run.ts
+const log$1 = makeNsLog("provider:agent");
+const DEFAULT_MAX_ROUNDS = 20;
+const DEFAULT_ACTIONS_PER_ROUND = 10;
+const RESULTS_PREFIX = "/.results/";
+/** Circuit breaker: trip after N consecutive identical tool calls. */
+const CIRCUIT_BREAKER_THRESHOLD = 3;
+/**
+* Default max output tokens per LLM call. Without this the gateway applies a
+* conservative per-model default (~8k) — observed truncating a full article's
+* `content` arg mid-sentence inside a cms-write tool call, after which the model
+* re-emitted the same truncated call until the circuit breaker blocked recovery.
+* We ask high so long content (article body + reasoning, or a whole doc page)
+* has ample headroom; AI Device clamps this down to each routed model's real
+* `maxOutputTokens` (see applyMaxOutputBudget in execution/forward.ts), so a
+* model that supports less never receives an over-limit request. Only a default
+* — a caller-supplied max_tokens always wins.
+*/
+const DEFAULT_MAX_OUTPUT_TOKENS = 32768;
+/** LLM call retry defaults. Non-rate-limit retries keep the historical linear delay. */
+const DEFAULT_MAX_RETRIES = 3;
+const LLM_RETRY_DELAY_MS = 1e3;
+const LLM_RETRY_MAX_MS = 5e3;
+const LLM_RATE_LIMIT_RETRY_BASE_MS = 5e3;
+const LLM_RATE_LIMIT_RETRY_MAX_MS = 3e4;
+/** Timeout for a single LLM call (5 minutes). Prevents session lock from hanging forever. */
+const LLM_CALL_TIMEOUT_MS = 300 * 1e3;
+/** Default context window size when not provided by model metadata. */
+const DEFAULT_CONTEXT_WINDOW = 8e4;
+/** Maximum serialized size for chain array in progress events (bytes). */
+const MAX_CHAIN_JSON_SIZE = 1024;
+/**
+* Compute sanitized depth and chain for progress event stamping.
+*
+* - Filters non-string entries from the chain
+* - Strips path traversal characters
+* - If no chain provided, builds [session] (or [] if no session)
+* - Truncates chain if serialized JSON exceeds MAX_CHAIN_JSON_SIZE
+* - depth = max(0, chain.length - 1)
+*/
+function computeProgressNesting(params) {
+	let chain;
+	if (params.chain && params.chain.length > 0) {
+		const filtered = params.chain.filter((s) => typeof s === "string");
+		if (filtered.length !== params.chain.length) log$1.warn("[agent-run] chain contains non-string elements, filtered out");
+		chain = filtered.map((s) => s.replace(/\.\.\//g, "").replace(/\.\.\\/g, ""));
+	} else if (params.session) {
+		if (params.parentSession && !params.chain) log$1.warn("[agent-run] parentSession set but chain missing, defaulting depth to 0");
+		chain = [params.session];
+	} else chain = [];
+	while (chain.length > 1 && JSON.stringify(chain).length > MAX_CHAIN_JSON_SIZE) chain = [chain[0], ...chain.slice(2)];
+	if (chain.length === 1 && JSON.stringify(chain).length > MAX_CHAIN_JSON_SIZE) chain = [chain[0].slice(0, MAX_CHAIN_JSON_SIZE - 10)];
+	return {
+		depth: Math.max(0, chain.length - 1),
+		chain
+	};
+}
+function isSubAgentRunPath(path) {
+	return path.endsWith("/.actions/run") || path.endsWith("/.actions/agent-run");
+}
+/**
+* Operations routed through ASH (deterministic sandbox).
+*
+* Currently empty: all ops go through direct AFS calls.
+* agent-run's security comes from path-validator (tools declaration whitelist),
+* not from ASH @caps. The ASH sandbox is valuable for user-written scripts
+* (/.actions/run) but redundant for agent-run's auto-generated single-step execs.
+*/
+const ASH_OPS = /* @__PURE__ */ new Set([]);
+const RATE_LIMIT_ERROR_RE = /\b429\b|RESOURCE_EXHAUSTED|Too Many Requests|rate[-\s]?limit|quota exceeded|quota has been exceeded/i;
+function clampDelayMs(ms, maxMs) {
+	if (!Number.isFinite(ms) || ms <= 0) return 0;
+	return Math.min(Math.ceil(ms), maxMs);
+}
+function parseRetryAfterMs(error) {
+	const retryAfter = error.match(/retry[-_\s]?after["']?\s*[:=]?\s*["']?(\d+(?:\.\d+)?)\s*(ms|milliseconds?|s|sec|seconds?|m|minutes?)?/i);
+	const tryAgainIn = error.match(/try again (?:later,?\s*)?in\s+(\d+(?:\.\d+)?)\s*(ms|milliseconds?|s|sec|seconds?|m|minutes?)/i);
+	const match = retryAfter ?? tryAgainIn;
+	if (!match) return void 0;
+	const value = Number(match[1]);
+	if (!Number.isFinite(value) || value <= 0) return void 0;
+	const unit = match[2]?.toLowerCase();
+	if (unit?.startsWith("m") && unit !== "ms" && !unit.startsWith("millisecond")) return value * 6e4;
+	if (!unit || unit.startsWith("s")) return value * 1e3;
+	return value;
+}
+function computeLLMRetryDelayMs(error, failedAttempt) {
+	const attempt = Math.max(1, failedAttempt);
+	const retryAfterMs = parseRetryAfterMs(error);
+	if (retryAfterMs !== void 0) return clampDelayMs(retryAfterMs, LLM_RATE_LIMIT_RETRY_MAX_MS);
+	if (RATE_LIMIT_ERROR_RE.test(error)) return clampDelayMs(LLM_RATE_LIMIT_RETRY_BASE_MS * 2 ** (attempt - 1), LLM_RATE_LIMIT_RETRY_MAX_MS);
+	return clampDelayMs(LLM_RETRY_DELAY_MS * attempt, LLM_RETRY_MAX_MS);
+}
+function sleep(ms, signal) {
+	if (ms <= 0) return Promise.resolve();
+	if (signal?.aborted) return Promise.reject(/* @__PURE__ */ new Error("Cancelled"));
+	return new Promise((resolve, reject) => {
+		let timer;
+		const cleanup = () => {
+			clearTimeout(timer);
+			signal?.removeEventListener("abort", onAbort);
+		};
+		const onResolve = () => {
+			cleanup();
+			resolve();
+		};
+		const onAbort = () => {
+			cleanup();
+			reject(/* @__PURE__ */ new Error("Cancelled"));
+		};
+		timer = setTimeout(onResolve, ms);
+		signal?.addEventListener("abort", onAbort, { once: true });
+	});
+}
+/** Required arguments per operation (beyond path) */
+const REQUIRED_ARGS = { search: ["query"] };
+/** Map tool function name → AFS operation name */
+function toolNameToOp(name) {
+	if (name.startsWith("afs_action_")) return "exec";
+	return {
+		afs_read: "read",
+		afs_list: "list",
+		afs_exec: "exec",
+		afs_search: "search",
+		afs_write: "write",
+		afs_delete: "delete",
+		afs_stat: "stat",
+		afs_explain: "explain"
+	}[name];
+}
+/** JSON.stringify with sorted keys for deterministic comparison of tool call args. */
+function stableStringify(obj) {
+	return JSON.stringify(obj, Object.keys(obj).sort());
+}
+/** Truncate a result string for progress events. */
+function truncateResult(s, max) {
+	if (!s) return void 0;
+	return s.length > max ? `${s.slice(0, max)}...` : s;
+}
+/**
+* Normalize a tool call from any format to our internal ToolCallInput.
+*
+* AigneHub returns OpenAI format:
+*   { id, type: "function", function: { name, arguments } }
+* Some SDKs return Vercel AI SDK format:
+*   { toolCallId, toolName, args }
+*/
+function normalizeToolCall(tc) {
+	if (tc.toolCallId && tc.toolName) return {
+		toolCallId: tc.toolCallId,
+		toolName: tc.toolName,
+		args: tc.args ?? {}
+	};
+	const fn = tc.function;
+	const rawArgs = fn?.arguments;
+	let args = {};
+	if (typeof rawArgs === "string") try {
+		args = JSON.parse(rawArgs);
+	} catch {
+		args = { _parseError: `Invalid JSON in function arguments: ${rawArgs.slice(0, 200)}` };
+	}
+	else if (rawArgs && typeof rawArgs === "object") args = rawArgs;
+	return {
+		toolCallId: tc.toolCallId ?? tc.id ?? "",
+		toolName: tc.toolName ?? fn?.name ?? "",
+		args
+	};
+}
+/**
+* Map AFS operation to a glyph a human scans faster than a word.
+* `afs_action_<name>` (per-action sugar) and any other non-standard tool
+* name collapse to the generic exec ⚡.
+*/
+const OP_EMOJI = {
+	read: "📖",
+	write: "✍️",
+	edit: "✏️",
+	list: "📋",
+	stat: "ℹ️",
+	explain: "💡",
+	search: "🔎",
+	exec: "⚡",
+	delete: "🗑"
+};
+function toolNameToEmoji(toolName) {
+	if (toolName.startsWith("afs_action_")) return OP_EMOJI.exec;
+	return OP_EMOJI[toolName.replace(/^afs_/, "")] ?? "🔧";
+}
+/**
+* Render a round's tool calls + outcomes as a user-facing one-line-per-call
+* summary. Used by the onProgress payload so the progress surface (Telegram
+* live-progress, web UI tail, etc.) shows each AFS operation the agent ran
+* and whether it succeeded.
+*
+* Output per call: `<emoji> <path> <status>`, e.g.
+*   📖 /x/me ✓
+*   📋 /x/me/tweets ✓
+*   ⚡ /x/.actions/search ✗
+*
+* Status glyphs:
+*   ✓ — tool executed successfully
+*   ✗ — tool errored (validation, runtime, permission)
+*   ⊘ — circuit breaker tripped (same call repeated too many times)
+*
+* Falls back to `🔧` for tools outside the standard AFS op set.
+*/
+function summarizeToolCalls(roundCalls, traceEntries, errorResults) {
+	const traceById = new Map(traceEntries.map((t) => [t.id, t]));
+	const errorIds = new Set(errorResults.map((e) => e.id));
+	return roundCalls.map((call) => {
+		const emoji = toolNameToEmoji(call.toolName);
+		const path = String(call.args.path ?? "");
+		const trace = traceById.get(call.toolCallId);
+		let status;
+		if (errorIds.has(call.toolCallId)) status = "✗";
+		else if (trace?.status === "circuit_breaker") status = "⊘";
+		else if (trace?.status === "error") status = "✗";
+		else status = "✓";
+		return path ? `${emoji} ${path} ${status}` : `${emoji} ${status}`;
+	}).join("\n");
+}
+/**
+* Fix path for per-action tool calls.
+*
+* LLMs often make mistakes with per-action tools:
+* 1. Put tool name in path: /.actions/afs_action_send → /.actions/send
+* 2. Drop mount prefix: /default/conversations/123 → /telegram/default/conversations/123
+*
+* Uses discovered pathPattern to auto-correct missing mount prefixes.
+* Mutates call.args.path in place.
+*/
+function fixPerActionPath(call, schemasByAction) {
+	const path = call.args.path;
+	if (!path) return;
+	const realName = call.toolName.slice(11).replace(/_/g, "-");
+	const marker = "/.actions/";
+	const idx = path.lastIndexOf(marker);
+	if (idx !== -1) {
+		const currentAction = path.slice(idx + 10).split("/")[0];
+		if (currentAction && currentAction !== realName) call.args.path = path.slice(0, idx) + marker + realName;
+	}
+	const schema = schemasByAction.get(realName);
+	if (!schema?.pathPattern) return;
+	const fixedPath = call.args.path;
+	const starIdx = schema.pathPattern.indexOf("*");
+	if (starIdx === -1) return;
+	const expectedPrefix = schema.pathPattern.slice(0, starIdx);
+	if (fixedPath.startsWith(expectedPrefix)) return;
+	for (let i = 1; i < expectedPrefix.length; i++) if (expectedPrefix[i] === "/" && fixedPath.startsWith(expectedPrefix.slice(i))) {
+		call.args.path = expectedPrefix.slice(0, i) + fixedPath;
+		return;
+	}
+}
+/** Extract exec args from tool call: try nested `args` field first, fall back to all fields except `path`. */
+function extractExecArgs(callArgs) {
+	if (callArgs.args && typeof callArgs.args === "object" && !Array.isArray(callArgs.args)) return callArgs.args;
+	const { path: _, ...rest } = callArgs;
+	return rest;
+}
+/**
+* Discover available actions and their inputSchemas at startup.
+*
+* Strategy (per exec-capable tool entry):
+* 1. Instance-probe: list basePath to find a child, then list its .actions/
+* 2. Capabilities fallback: walk up path hierarchy to find /.meta/.capabilities,
+*    extract action schemas from the manifest's catalog entries
+*
+* Results are used to generate per-action tools with explicit typed parameters.
+* Best-effort: failures are silently ignored and the generic afs_exec fallback remains.
+*/
+async function discoverActionSchemas(tools, deps) {
+	const schemas = [];
+	const discoveredPaths = /* @__PURE__ */ new Set();
+	const candidates = [];
+	for (const tool of tools) {
+		if (!tool.ops.includes("exec")) continue;
+		const basePath = tool.path.replace(/\/?\*+$/, "");
+		if (!basePath || discoveredPaths.has(basePath)) continue;
+		discoveredPaths.add(basePath);
+		candidates.push({
+			tool,
+			basePath
+		});
+	}
+	const discovered = await Promise.all(candidates.map(async ({ tool, basePath }) => {
+		const toolSchemas = [];
+		const toolActions = /* @__PURE__ */ new Set();
+		try {
+			if (basePath.endsWith("/.actions")) {
+				await discoverFromActionsDir(tool, basePath, toolActions, toolSchemas, deps);
+				return toolSchemas;
+			}
+			if (!await discoverViaInstanceProbe(tool, basePath, toolActions, toolSchemas, deps)) await discoverViaCapabilities(tool, basePath, toolActions, toolSchemas, deps);
+		} catch {}
+		return toolSchemas;
+	}));
+	const discoveredActions = /* @__PURE__ */ new Set();
+	for (const toolSchemas of discovered) for (const schema of toolSchemas) {
+		if (discoveredActions.has(schema.actionName)) continue;
+		discoveredActions.add(schema.actionName);
+		schemas.push(schema);
+	}
+	return schemas;
+}
+/** Fast path: tool path already ends with /.actions/* — list the directory directly. */
+async function discoverFromActionsDir(tool, actionsPath, discoveredActions, schemas, deps) {
+	const result = await deps.callAFS("list", actionsPath);
+	if (!result.success) return;
+	const actions = extractEntries(result.data);
+	for (const action of actions) {
+		const name = extractActionNameFromEntry(action);
+		if (!name || discoveredActions.has(name)) continue;
+		discoveredActions.add(name);
+		schemas.push({
+			actionName: name,
+			description: action.meta?.description || `Execute ${name}`,
+			pathPattern: `${tool.path.replace(/\*+$/, name)}`,
+			inputSchema: action.meta?.inputSchema
+		});
+	}
+}
+/** Strategy 1: list basePath, pick first child, list its .actions/ */
+async function discoverViaInstanceProbe(tool, basePath, discoveredActions, schemas, deps) {
+	const listResult = await deps.callAFS("list", basePath);
+	if (!listResult.success) return false;
+	const entries = extractEntries(listResult.data);
+	if (entries.length === 0) return false;
+	const mcpTools = entries.filter((e) => e.meta?.kind === "mcp:tool" || e.meta?.kinds?.includes?.("mcp:tool"));
+	if (mcpTools.length > 0) {
+		let found$1 = false;
+		for (const mcpTool of mcpTools) {
+			const name = mcpTool.meta?.mcp?.name || extractActionNameFromEntry(mcpTool);
+			if (!name || discoveredActions.has(name)) continue;
+			discoveredActions.add(name);
+			found$1 = true;
+			const toolPath = mcpTool.path || `${basePath}/${name}`;
+			schemas.push({
+				actionName: name,
+				description: mcpTool.meta?.description || `Execute ${name}`,
+				pathPattern: toolPath,
+				inputSchema: mcpTool.meta?.inputSchema
+			});
+		}
+		return found$1;
+	}
+	const firstChild = entries[0];
+	const childPath = firstChild.path || firstChild.id;
+	if (!childPath) return false;
+	const actionsPath = `${childPath}/.actions`;
+	const actionsResult = await deps.callAFS("list", actionsPath);
+	if (!actionsResult.success) return false;
+	const actions = extractEntries(actionsResult.data);
+	let found = false;
+	for (const action of actions) {
+		const name = extractActionNameFromEntry(action);
+		if (!name || discoveredActions.has(name)) continue;
+		discoveredActions.add(name);
+		found = true;
+		schemas.push({
+			actionName: name,
+			description: action.meta?.description || `Execute ${name}`,
+			pathPattern: `${tool.path}/.actions/${name}`,
+			inputSchema: action.meta?.inputSchema
+		});
+	}
+	return found;
+}
+/**
+* Strategy 2: walk up path hierarchy to find a provider's /.meta/.capabilities,
+* then extract action schemas from the manifest's catalog + inputSchema.
+*
+* For a tool path like /telegram/default/conversations/*, tries:
+*   /telegram/default/conversations/.meta/.capabilities
+*   /telegram/default/.meta/.capabilities
+*   /telegram/.meta/.capabilities
+*/
+async function discoverViaCapabilities(tool, basePath, discoveredActions, schemas, deps) {
+	const segments = basePath.split("/").filter(Boolean);
+	for (let depth = segments.length; depth >= 1; depth--) {
+		const capsPath = `${`/${segments.slice(0, depth).join("/")}`}/.meta/.capabilities`;
+		try {
+			const result = await deps.callAFS("read", capsPath);
+			if (!result.success) continue;
+			const content = extractCapabilitiesContent(result.data);
+			if (!content?.actions) continue;
+			let found = false;
+			for (const actionGroup of content.actions) {
+				const catalog = actionGroup.catalog;
+				if (!Array.isArray(catalog)) continue;
+				for (const entry of catalog) {
+					const name = entry.name;
+					if (!name || discoveredActions.has(name)) continue;
+					discoveredActions.add(name);
+					found = true;
+					schemas.push({
+						actionName: name,
+						description: entry.description || `Execute ${name}`,
+						pathPattern: `${tool.path}/.actions/${name}`,
+						inputSchema: entry.inputSchema
+					});
+				}
+			}
+			if (found) return true;
+		} catch {}
+	}
+	return false;
+}
+/** Extract capabilities content from a read result (may be nested in data.content or data directly). */
+function extractCapabilitiesContent(data) {
+	if (!data || typeof data !== "object") return null;
+	const d = data;
+	if (d.actions) return d;
+	if (d.content && typeof d.content === "object" && d.content.actions) return d.content;
+	return null;
+}
+/** Extract entries array from callAFS response data (may be raw array or wrapped). */
+function extractEntries(data) {
+	if (Array.isArray(data)) return data;
+	if (data && typeof data === "object" && Array.isArray(data.data)) return data.data;
+	return [];
+}
+/** Tolerant extraction of text content from a callAFS("read") result's data. */
+function extractReadContent(data) {
+	if (typeof data === "string") return data;
+	if (data && typeof data === "object") {
+		const d = data;
+		if (typeof d.content === "string") return d.content;
+		if (typeof d.data === "string") return d.data;
+		if (d.data && typeof d.data === "object" && typeof d.data.content === "string") return d.data.content;
+	}
+}
+/** Parse `name` + `description` from a SKILL.md frontmatter block. Delegates to
+*  the canonical parser in `@aigne/afs-skills/format` (single source of truth)
+*  and preserves this module's `null`-when-empty contract for its callers. */
+function parseSkillFrontmatter$1(md) {
+	const fm = parseSkillFrontmatter(md);
+	if (Object.keys(fm).length === 0) return null;
+	return {
+		name: fm.name,
+		description: fm.description
+	};
+}
+/**
+* Build a compact skill catalog from the agent's skill roots, read at startup
+* (server-side) so the LLM does NOT spend discovery rounds listing roots and
+* reading every SKILL.md just to learn what exists. Each skill's `name` +
+* `description` come from its SKILL.md frontmatter; the agent then reads the
+* full SKILL.md only for the one skill it decides to use.
+*
+* Bounded: scans at most 2 levels deep and caps the catalog size, so the
+* injected prompt stays small no matter how many skills are mounted. All AFS
+* access is best-effort — a failing root/skill is skipped, never fatal.
+*/
+async function buildSkillCatalog(skillPaths, deps) {
+	if (!skillPaths || skillPaths.length === 0) return void 0;
+	const MAX_SKILLS = 40;
+	const DESC_MAX = 220;
+	const entries = [];
+	const seen = /* @__PURE__ */ new Set();
+	/** Try `<dir>/SKILL.md`; on success record the skill. Returns true if a
+	*  SKILL.md was found (so the caller does not descend into a leaf dir). */
+	const tryLeaf = async (dirPath) => {
+		const skillFile = `${dirPath}/SKILL.md`;
+		let res;
+		try {
+			res = await deps.callAFS("read", skillFile);
+		} catch {
+			return false;
+		}
+		if (!res.success) return false;
+		const md = extractReadContent(res.data);
+		if (!md) return false;
+		const fm = parseSkillFrontmatter$1(md);
+		if (!fm?.name || seen.has(fm.name)) return !!fm?.name;
+		seen.add(fm.name);
+		let desc = (fm.description ?? "").replace(/\s+/g, " ").trim();
+		if (desc.length > DESC_MAX) desc = `${desc.slice(0, DESC_MAX - 1)}…`;
+		entries.push({
+			name: fm.name,
+			description: desc,
+			path: skillFile
+		});
+		return true;
+	};
+	for (const root of skillPaths) {
+		if (entries.length >= MAX_SKILLS) break;
+		let listRes;
+		try {
+			listRes = await deps.callAFS("list", root);
+		} catch {
+			continue;
+		}
+		if (!listRes.success) continue;
+		for (const child of extractEntries(listRes.data)) {
+			if (entries.length >= MAX_SKILLS) break;
+			const childPath = child.path || child.id;
+			if (!childPath) continue;
+			if (await tryLeaf(childPath)) continue;
+			let groupRes;
+			try {
+				groupRes = await deps.callAFS("list", childPath);
+			} catch {
+				continue;
+			}
+			if (!groupRes.success) continue;
+			for (const gc of extractEntries(groupRes.data)) {
+				if (entries.length >= MAX_SKILLS) break;
+				const gcPath = gc.path || gc.id;
+				if (gcPath) await tryLeaf(gcPath);
+			}
+		}
+	}
+	if (entries.length === 0) return void 0;
+	return [
+		"## Available Skills",
+		"These skills are ready to use. When a user request matches a skill's purpose, `read` its SKILL.md for the full procedure and follow it exactly — do not improvise the workflow. If none fit, work directly with the AFS tools.",
+		"",
+		...entries.map((e) => `- **${e.name}** — ${e.description || "(no description)"} → read \`${e.path}\``)
+	].join("\n");
+}
+/** Extract action name from an action entry (from path or id). */
+function extractActionNameFromEntry(entry) {
+	if (entry.meta?.name) return entry.meta.name;
+	const path = entry.path || entry.id || "";
+	const idx = path.lastIndexOf("/.actions/");
+	if (idx !== -1) return path.slice(idx + 10).split("/")[0];
+	if (entry.id && !entry.id.includes("/")) return entry.id;
+}
+/**
+* Compute the per-tool-result character limit based on context window size.
+* Each tool result should occupy at most ~2% of the context window.
+*/
+function computeToolResultLimit(contextWindow) {
+	const cw = contextWindow ?? DEFAULT_CONTEXT_WINDOW;
+	return Math.max(16e3, Math.floor(cw * .05 * 3));
+}
+/**
+* Truncate a tool result string if it exceeds the given character limit.
+* Returns the original string unchanged if within limit.
+*/
+function truncateToolResult(content, limit) {
+	if (content.length <= limit) return content;
+	return `${content.slice(0, limit)}\n[... truncated ${content.length - limit} chars]`;
+}
+/**
+* Enrich tool result content with multimodal images when `_images` is present.
+* Returns the original string for normal results, or a multimodal content array
+* containing both text and image parts when images are detected.
+*/
+function enrichToolContent(resultStr) {
+	try {
+		const parsed = JSON.parse(resultStr);
+		if (Array.isArray(parsed?._images) && parsed._images.length > 0) {
+			const images = parsed._images.filter((img) => img && typeof img === "object" && img.type && (img.url || img.data || img.path));
+			if (images.length > 0) return [{
+				type: "text",
+				text: resultStr
+			}, ...images];
+		}
+	} catch {}
+	return resultStr;
+}
+/** Normalize an in-memory message (AigneHub camelCase) to canonical JSONL format (OpenAI snake_case). */
+function normalizeForHistory(msg) {
+	const role = msg.role;
+	if (role === "system") return null;
+	const createdAt = (/* @__PURE__ */ new Date()).toISOString();
+	if (role === "user") return {
+		role: "user",
+		content: String(msg.content ?? ""),
+		createdAt
+	};
+	if (role === "assistant") {
+		const result = {
+			role: "assistant",
+			content: String(msg.content ?? ""),
+			createdAt,
+			...typeof msg.durationMs === "number" ? { durationMs: msg.durationMs } : {}
+		};
+		const rawToolCalls = msg.toolCalls ?? msg.tool_calls;
+		if (rawToolCalls?.length) result.tool_calls = rawToolCalls.map((tc) => {
+			const fn = tc.function;
+			const rawArgs = fn?.arguments ?? tc.args;
+			return {
+				id: tc.id ?? tc.toolCallId ?? "",
+				type: "function",
+				function: {
+					name: fn?.name ?? tc.toolName ?? "",
+					arguments: typeof rawArgs === "string" ? rawArgs : JSON.stringify(rawArgs ?? {})
+				}
+			};
+		});
+		return result;
+	}
+	if (role === "tool") {
+		const content = Array.isArray(msg.content) ? msg.content : String(msg.content ?? "");
+		return {
+			role: "tool",
+			tool_call_id: msg.tool_call_id ?? msg.toolCallId ?? "",
+			content,
+			createdAt,
+			...typeof msg.durationMs === "number" ? { durationMs: msg.durationMs } : {}
+		};
+	}
+	return null;
+}
+async function runAgentLoop(params, deps) {
+	const maxRounds = params.budget?.max_rounds ?? DEFAULT_MAX_ROUNDS;
+	const actionsPerRound = params.budget?.actions_per_round ?? DEFAULT_ACTIONS_PER_ROUND;
+	const tokenBudget = params.budget?.total_tokens ?? Number.POSITIVE_INFINITY;
+	const nesting = computeProgressNesting(params);
+	const emitProgress = (event) => {
+		if (!params.onToolProgress) return;
+		try {
+			params.onToolProgress({
+				...event,
+				depth: nesting.depth,
+				chain: [...nesting.chain]
+			});
+		} catch {}
+	};
+	/** Stamp seq + ts and forward to deps.emit. No-op when observability isn't
+	*  wired up (CLI direct call). Failures are swallowed — trace is best-effort.
+	*  `LogEventInput` (= LogEvent minus seq/ts, distributed) preserves each
+	*  variant's required keys at the call site. */
+	const emitObs = async (event) => {
+		if (!deps.emit || !deps.nextSeq) return;
+		try {
+			await deps.emit({
+				...event,
+				seq: deps.nextSeq(),
+				ts: Date.now()
+			});
+		} catch {}
+	};
+	const afs = { exec: async (path, args, opts) => {
+		return deps.callAFS("exec", path, {
+			...args,
+			...opts
+		});
+	} };
+	const sessionTag = params.session ? params.session.split("/").filter(Boolean).pop() ?? params.session : Math.random().toString(16).slice(2, 10);
+	const procId = await deps.callAFS("exec", "/proc/.actions/register", {
+		type: "agent-run",
+		did: `did:afs:ash-run:${sessionTag}`,
+		parentId: params.execContext?.procId ?? params.parentProcId,
+		budget: {
+			tokens: params.budget?.total_tokens,
+			calls: params.budget?.max_rounds
+		}
+	}).then((r) => (r?.data)?.procId).catch(() => void 0);
+	const completeProc = (status) => {
+		if (procId) deps.callAFS("exec", "/proc/.actions/complete", {
+			id: procId,
+			status
+		}).catch(() => {});
+	};
+	if (params.memory?.toolsPath) params.tools.push({
+		path: params.memory.toolsPath,
+		ops: ["exec"]
+	});
+	if (params.memory?.domain && params.memory?.recallPath) {
+		const mountRoot = params.memory.recallPath.replace(/\/\.actions\/recall\/?$/, "");
+		if (mountRoot && mountRoot !== params.memory.recallPath) params.tools.push({
+			path: joinURL(mountRoot, params.memory.domain),
+			ops: ["list", "read"],
+			maxDepth: 3
+		});
+	}
+	if (params.index?.scope && params.index?.queryPath) {
+		const mountRoot = params.index.queryPath.replace(/\/\.actions\/query\/?$/, "");
+		if (mountRoot && mountRoot !== params.index.queryPath) params.tools.push({
+			path: joinURL(mountRoot, "domains", params.index.scope),
+			ops: ["list", "read"],
+			maxDepth: 2
+		});
+	}
+	const ASK_USER_PATH = "/dev/ui/.actions/ask";
+	if (!params.tools.some((t) => t.path === ASK_USER_PATH)) params.tools.push({
+		path: ASK_USER_PATH,
+		ops: ["exec"]
+	});
+	const actionSchemas = await discoverActionSchemas(params.tools, deps);
+	const schemasByAction = /* @__PURE__ */ new Map();
+	for (const s of actionSchemas) schemasByAction.set(s.actionName, s);
+	const toolSchema = buildToolSchema(params.tools, actionSchemas);
+	let responseSchema;
+	if (params.responseSchema) {
+		if (params.responseSchema.startsWith("/")) try {
+			const content = (await deps.callAFS("read", params.responseSchema))?.data?.content;
+			if (typeof content === "string") responseSchema = JSON.parse(content);
+			else if (content && typeof content === "object") responseSchema = content;
+		} catch {}
+		if (!responseSchema) try {
+			const parsed = JSON.parse(params.responseSchema);
+			if (parsed && typeof parsed === "object") responseSchema = parsed;
+		} catch {}
+	}
+	let history = [];
+	if (params.session && deps.loadHistory) try {
+		history = await deps.loadHistory(params.session);
+	} catch {}
+	const AFS_HINT = [
+		"## AFS Discovery Protocol",
+		"Start with `read /.knowledge` — it returns a complete capability index of all providers, actions, and paths in ONE call.",
+		"For deeper detail on a specific provider: `read /.knowledge/{provider-name}`.",
+		"Only use `explain {path}` when you need the deepest detail about a specific path or action.",
+		"Do NOT read source code from /modules/project/ to learn about providers — use `/.knowledge` or `explain` instead.",
+		"",
+		"## Skills",
+		"Skills are regular AFS files, not a special tool. Two roots:",
+		"  - /blocklet/skills         — this app's own skills (from the blocklet)",
+		"  - /.mounted-skills         — each mounted provider's bundled skills",
+		"",
+		"When you need a capability:",
+		"  1. `list` one of the skill roots to see what's available",
+		"  2. `read <dir>/SKILL.md` (or `README.md`) for usage + params",
+		"  3. `read <path>.ash` if you need exact `param` declarations",
+		"  4. `exec <path>.ash { ...params, caps: [\"*\"] }` to run the skill",
+		"",
+		"A SKILL.md-bearing directory = one leaf skill. A DESCRIPTION.md-bearing directory = a group; descend into its children to find leaves."
+	].join("\n");
+	const STOP_DIRECTIVE = responseSchema ? `When you have completed the user's task, respond with your final answer as a JSON object. Do not make additional tool calls after you have gathered all needed information.\n\nResponse JSON Schema:\n${JSON.stringify(responseSchema, null, 2)}` : params.skipAfsHint ? "When you have completed the user's task, respond with a concise text summary. Do not make additional tool calls after the task is done." : `When you have completed the user's task, respond with a concise text summary. Do not make additional tool calls after the task is done.\n\n${AFS_HINT}`;
+	const TIME_DIRECTIVE = `Current time: ${(/* @__PURE__ */ new Date()).toISOString()} (UTC). When writing timestamps in tool args (createdAt, updatedAt, etc.) use this — do not invent dates.`;
+	const memoryConfig = params.memory ? {
+		recallPath: params.memory.recallPath,
+		maxTokens: params.memory.maxTokens,
+		domain: params.memory.domain
+	} : void 0;
+	const skillCatalog = await buildSkillCatalog(params.skillPaths, deps);
+	const messages = (await buildContext(afs, {
+		task: params.task,
+		system: params.system,
+		history,
+		memory: memoryConfig,
+		directives: skillCatalog ? [
+			TIME_DIRECTIVE,
+			STOP_DIRECTIVE,
+			skillCatalog
+		] : [TIME_DIRECTIVE, STOP_DIRECTIVE]
+	})).messages;
+	const currentTaskMessage = messages[messages.length - 1];
+	const contextWindow = params.budget?.context_window;
+	const toolResultLimit = computeToolResultLimit(contextWindow);
+	/** Normalize new messages, persist to working history (if session), and emit
+	*  one observability `message` event per normalized entry. emit fires
+	*  regardless of session — observability is independent from history.jsonl. */
+	const appendNewMessages = async (newMsgs) => {
+		const normalized = [];
+		for (const msg of newMsgs) {
+			const n = normalizeForHistory(msg);
+			if (n) normalized.push(n);
+		}
+		if (normalized.length === 0) return;
+		if (params.session) try {
+			await deps.appendHistory?.(params.session, normalized);
+		} catch {}
+		for (const m of normalized) {
+			const tc = m.tool_calls;
+			const cid = m.tool_call_id;
+			await emitObs({
+				type: "message",
+				role: m.role,
+				content: m.content,
+				...tc ? { toolCalls: tc } : {},
+				...cid ? { callId: cid } : {}
+			});
+		}
+	};
+	/** Latest compress progress, captured by `onProgress` and read by
+	*  `rewriteCompressed` (whose signature is fixed by maybeCompress's
+	*  `onCompressed` contract — only `compressed` + `archived` are passed). */
+	let latestCompressInfo = {
+		beforeTokens: 0,
+		afterTokens: 0,
+		round: 0
+	};
+	/** Archive original messages + rewrite working history + emit `compress` event. */
+	const rewriteCompressed = async (compressed, archived) => {
+		if (params.session) {
+			if (deps.archiveHistory && archived.length > 0) {
+				const archivedNorm = [];
+				for (const msg of archived) {
+					const n = normalizeForHistory(msg);
+					if (n) archivedNorm.push(n);
+				}
+				try {
+					await deps.archiveHistory(params.session, archivedNorm);
+				} catch {}
+			}
+			if (deps.rewriteHistory) {
+				const compressedNorm = [];
+				for (const msg of compressed) {
+					const n = normalizeForHistory(msg);
+					if (n) compressedNorm.push(n);
+				}
+				await deps.rewriteHistory(params.session, compressedNorm);
+			}
+		}
+		await emitObs({
+			type: "compress",
+			round: latestCompressInfo.round,
+			compressed_messages: compressed,
+			archived_count: archived.length,
+			before_tokens: latestCompressInfo.beforeTokens,
+			after_tokens: latestCompressInfo.afterTokens
+		});
+	};
+	/** Archive conversation to memory provider (best-effort, called on completion). */
+	const archiveToMemory = async (status) => {
+		if (!params.memory?.archivePath || !params.session) return;
+		if (status !== "completed") return;
+		try {
+			const archiveMessages = messages.filter((m) => {
+				const role = m.role;
+				if (role !== "user" && role !== "assistant") return false;
+				const content = m.content;
+				return content != null && String(content).trim().length > 0;
+			}).map((m) => ({
+				role: String(m.role),
+				content: String(m.content)
+			}));
+			if (archiveMessages.length > 0) {
+				const safeSessionId = params.session.replace(/^\/+/, "").replace(/\//g, "-");
+				await deps.callAFS("exec", params.memory.archivePath, {
+					sessionId: safeSessionId,
+					messages: archiveMessages,
+					domain: params.memory.domain
+				});
+			}
+		} catch (e) {
+			log$1.error(`[agent-run] archiveToMemory error: ${e instanceof Error ? e.message : String(e)}`);
+		}
+	};
+	await appendNewMessages([messages[messages.length - 1]]);
+	const trace = [];
+	let totalTokens = 0;
+	let totalActions = 0;
+	let subRuns = 0;
+	let totalInputTokens = 0;
+	let totalOutputTokens = 0;
+	let totalCachedTokens = 0;
+	let totalCost = 0;
+	let resolvedModelName = "";
+	const callHistory = /* @__PURE__ */ new Map();
+	const totalsAccumulator = {
+		rounds: 0,
+		totalTokensIn: 0,
+		totalTokensOut: 0,
+		totalCachedTokens: 0,
+		totalCost: 0,
+		modelsUsed: /* @__PURE__ */ new Set(),
+		hubsUsed: /* @__PURE__ */ new Set(),
+		toolsUsed: /* @__PURE__ */ new Set()
+	};
+	/** Update totals + emit `turn` event after each LLM call. Hub is pulled from
+	*  `data.reason.topPick.hub` when AI Device returns a routing reason. */
+	const emitTurn = async (turnRound, turnStartedAtMs, data, inputTokens, outputTokens, cost, cachedTokens, status = "ok", errorMessage = null) => {
+		const hub = ((data?.reason)?.topPick)?.hub ?? null;
+		const turnModel = data?.model ?? resolvedModelName ?? null;
+		totalsAccumulator.rounds += 1;
+		totalsAccumulator.totalTokensIn += inputTokens;
+		totalsAccumulator.totalTokensOut += outputTokens;
+		totalsAccumulator.totalCost += cost;
+		totalsAccumulator.totalCachedTokens += cachedTokens;
+		if (turnModel) totalsAccumulator.modelsUsed.add(turnModel);
+		if (hub) totalsAccumulator.hubsUsed.add(hub);
+		await emitObs({
+			type: "turn",
+			round: turnRound,
+			model: turnModel,
+			hub,
+			tokensIn: inputTokens,
+			tokensOut: outputTokens,
+			tokensCached: cachedTokens,
+			cost,
+			durationMs: Date.now() - turnStartedAtMs,
+			status,
+			errorMessage
+		});
+	};
+	/** Snapshot the totals accumulator for the AgentRunResult.totals field. */
+	const totalsSnapshot = () => ({
+		rounds: totalsAccumulator.rounds,
+		totalTokensIn: totalsAccumulator.totalTokensIn,
+		totalTokensOut: totalsAccumulator.totalTokensOut,
+		totalCachedTokens: totalsAccumulator.totalCachedTokens,
+		totalCost: totalsAccumulator.totalCost,
+		modelsUsed: [...totalsAccumulator.modelsUsed],
+		hubsUsed: [...totalsAccumulator.hubsUsed],
+		toolsUsed: [...totalsAccumulator.toolsUsed]
+	});
+	for (let round = 1; round <= maxRounds; round++) {
+		const roundStartedAtMs = Date.now();
+		if (params.abortSignal?.aborted) {
+			emitProgress({
+				type: "summary",
+				round: round - 1,
+				model: resolvedModelName,
+				tokens: {
+					input: totalInputTokens,
+					output: totalOutputTokens,
+					cached: totalCachedTokens,
+					cost: totalCost
+				}
+			});
+			completeProc("done");
+			return {
+				status: "budget_exhausted",
+				result: void 0,
+				rounds: round - 1,
+				total_actions: totalActions,
+				total_tokens: totalTokens,
+				sub_runs: subRuns,
+				trace,
+				totals: totalsSnapshot()
+			};
+		}
+		const compressed = await maybeCompress(messages, {
+			contextWindow,
+			pinMessage: currentTaskMessage,
+			callLLM: deps.callLLM,
+			onCompressed: rewriteCompressed,
+			onProgress: (info) => {
+				if (info.phase === "skipped") return;
+				latestCompressInfo = {
+					round,
+					beforeTokens: info.beforeTokens,
+					afterTokens: info.afterTokens ?? latestCompressInfo.afterTokens
+				};
+				if (params.onToolProgress) emitProgress({
+					type: info.phase === "done" || info.phase === "failed" ? "compress_result" : "compress_start",
+					round,
+					compress: {
+						phase: info.phase,
+						beforeTokens: info.beforeTokens,
+						contextWindow: info.contextWindow,
+						compressedMessages: info.compressedMessages ?? 0,
+						keptMessages: info.keptMessages ?? 0,
+						afterTokens: info.afterTokens,
+						error: info.error
+					}
+				});
+			}
+		});
+		if (compressed !== messages) {
+			messages.length = 0;
+			messages.push(...compressed);
+		}
+		const llmArgs = { ...params.modelArgs ?? {} };
+		llmArgs.messages = [...messages];
+		if (llmArgs.max_tokens == null && llmArgs.maxTokens == null) llmArgs.max_tokens = DEFAULT_MAX_OUTPUT_TOKENS;
+		if (toolSchema.length > 0) {
+			llmArgs.tools = toolSchema;
+			llmArgs.toolChoice = params.toolChoice ?? "auto";
+		}
+		if (responseSchema) llmArgs.responseFormat = {
+			type: "json_schema",
+			jsonSchema: {
+				name: "response",
+				schema: responseSchema
+			}
+		};
+		llmArgs.includeReason = true;
+		const maxRetries = params.budget?.max_retries ?? DEFAULT_MAX_RETRIES;
+		let llmResult;
+		let lastLLMError = "";
+		let hadStreamingDeltas = false;
+		if (params.onToolProgress) llmArgs._onChunk = (chunk) => {
+			if (chunk.thoughts) {
+				hadStreamingDeltas = true;
+				emitProgress({
+					type: "thinking_delta",
+					round,
+					text: chunk.thoughts
+				});
+			}
+			if (chunk.text) {
+				hadStreamingDeltas = true;
+				emitProgress({
+					type: "llm_delta",
+					round,
+					text: chunk.text
+				});
+			}
+		};
+		emitProgress({
+			type: "llm_start",
+			round,
+			model: resolvedModelName
+		});
+		const llmStartTime = Date.now();
+		for (let attempt = 0; attempt < maxRetries; attempt++) {
+			try {
+				llmResult = await Promise.race([deps.callLLM(llmArgs), new Promise((_, reject) => setTimeout(() => reject(/* @__PURE__ */ new Error("LLM call timed out")), LLM_CALL_TIMEOUT_MS))]);
+				if (llmResult.success) break;
+				lastLLMError = llmResult.data?.error ?? llmResult.error?.message ?? "unknown error";
+			} catch (err) {
+				lastLLMError = err instanceof Error ? err.message : String(err);
+				llmResult = void 0;
+			}
+			const hasNextAttempt = attempt < maxRetries - 1;
+			const retryDelayMs = hasNextAttempt ? computeLLMRetryDelayMs(lastLLMError, attempt + 1) : void 0;
+			emitProgress({
+				type: "llm_result",
+				round,
+				model: resolvedModelName,
+				attempt: attempt + 1,
+				maxAttempts: maxRetries,
+				llmError: lastLLMError,
+				retryDelayMs
+			});
+			if (hasNextAttempt && retryDelayMs && retryDelayMs > 0) await (deps.sleep ?? sleep)(retryDelayMs, params.abortSignal);
+		}
+		if (!llmResult?.success) {
+			trace.push({
+				round,
+				tool_calls: [],
+				tokens: {
+					input: 0,
+					output: 0
+				}
+			});
+			const diagMessages = llmArgs.messages || [];
+			const requestSummary = {
+				model: params.model,
+				messageCount: diagMessages.length,
+				hasTools: !!llmArgs.tools,
+				toolCount: Array.isArray(llmArgs.tools) ? llmArgs.tools.length : 0
+			};
+			await emitTurn(round, roundStartedAtMs, void 0, 0, 0, 0, 0, "error", lastLLMError);
+			completeProc("failed");
+			return {
+				status: "error",
+				error: `LLM call failed after ${maxRetries} attempts: ${lastLLMError}`,
+				detail: {
+					request: requestSummary,
+					lastResponse: llmResult ?? null
+				},
+				rounds: round,
+				total_actions: totalActions,
+				total_tokens: totalTokens,
+				sub_runs: subRuns,
+				trace,
+				totals: totalsSnapshot()
+			};
+		}
+		const data = llmResult.data;
+		const inputTokens = data.inputTokens ?? 0;
+		const outputTokens = data.outputTokens ?? 0;
+		totalTokens += inputTokens + outputTokens;
+		if (procId) deps.callAFS("exec", "/proc/.actions/record-usage", {
+			id: procId,
+			tokens: inputTokens + outputTokens,
+			calls: 1
+		}).catch(() => {});
+		if (data.model) resolvedModelName = data.model;
+		const llmUsage = data.usage;
+		totalInputTokens += inputTokens;
+		totalOutputTokens += outputTokens;
+		if (llmUsage?.cacheReadInputTokens) totalCachedTokens += llmUsage.cacheReadInputTokens;
+		if (llmUsage?.aigneHubCredits) totalCost += llmUsage.aigneHubCredits;
+		const text = data.text;
+		const json = data.json;
+		const thoughtsText = data.thoughts;
+		const rawToolCalls = data.toolCalls;
+		const finishReason = data.finishReason?.toLowerCase();
+		if (finishReason === "length" || finishReason === "max_tokens") emitProgress({
+			type: "warning",
+			round,
+			model: resolvedModelName,
+			text: "Model output hit the token limit and was truncated — any content written this round may be incomplete. Write more concise content, or split a large file (one cms-write, then mode:append for the rest)."
+		});
+		if (thoughtsText && !hadStreamingDeltas) emitProgress({
+			type: "thinking",
+			round,
+			text: thoughtsText,
+			model: resolvedModelName
+		});
+		if (!rawToolCalls || rawToolCalls.length === 0) {
+			trace.push({
+				round,
+				tool_calls: [],
+				tokens: {
+					input: inputTokens,
+					output: outputTokens
+				}
+			});
+			emitProgress({
+				type: "summary",
+				round,
+				model: resolvedModelName,
+				tokens: {
+					input: totalInputTokens,
+					output: totalOutputTokens,
+					cached: totalCachedTokens,
+					cost: totalCost
+				}
+			});
+			await emitTurn(round, roundStartedAtMs, data, inputTokens, outputTokens, llmUsage?.aigneHubCredits ?? 0, llmUsage?.cacheReadInputTokens ?? 0);
+			const assistantContent = json ? JSON.stringify(json) : text ?? "";
+			const llmDurationMs$1 = Date.now() - llmStartTime;
+			messages.push({
+				role: "assistant",
+				content: assistantContent,
+				durationMs: llmDurationMs$1
+			});
+			await appendNewMessages([messages[messages.length - 1]]);
+			let result = text ?? "";
+			if (responseSchema) {
+				if (json) result = json;
+				else if (text) try {
+					result = JSON.parse(text);
+				} catch {
+					const jsonMatch = text.match(/\{[\s\S]*\}/);
+					if (jsonMatch) try {
+						result = JSON.parse(jsonMatch[0]);
+					} catch {}
+				}
+			}
+			if (params.onProgress) {
+				const prog = params.onProgress;
+				const progressPath = typeof prog === "string" ? prog : prog.path;
+				const progressArgs = typeof prog === "string" ? {} : Object.fromEntries(Object.entries(prog).filter(([k]) => k !== "path"));
+				const trimmed = text?.trim() ?? "";
+				const prefixedText = trimmed ? `🤖 ${trimmed}` : "";
+				try {
+					await deps.callAFS("exec", progressPath, {
+						...progressArgs,
+						text: prefixedText,
+						message_text: prefixedText,
+						tool_summary: ""
+					});
+				} catch {}
+			}
+			await archiveToMemory("completed");
+			completeProc("done");
+			return {
+				status: "completed",
+				result,
+				rounds: round,
+				total_actions: totalActions,
+				total_tokens: totalTokens,
+				sub_runs: subRuns,
+				trace,
+				totals: totalsSnapshot()
+			};
+		}
+		if (totalTokens > tokenBudget) {
+			trace.push({
+				round,
+				tool_calls: [],
+				tokens: {
+					input: inputTokens,
+					output: outputTokens
+				}
+			});
+			emitProgress({
+				type: "summary",
+				round,
+				model: resolvedModelName,
+				tokens: {
+					input: totalInputTokens,
+					output: totalOutputTokens,
+					cached: totalCachedTokens,
+					cost: totalCost
+				}
+			});
+			await emitTurn(round, roundStartedAtMs, data, inputTokens, outputTokens, llmUsage?.aigneHubCredits ?? 0, llmUsage?.cacheReadInputTokens ?? 0);
+			completeProc("done");
+			return {
+				status: "budget_exhausted",
+				result: text,
+				rounds: round,
+				total_actions: totalActions,
+				total_tokens: totalTokens,
+				sub_runs: subRuns,
+				trace,
+				totals: totalsSnapshot()
+			};
+		}
+		const toolCalls = rawToolCalls.map(normalizeToolCall);
+		await emitTurn(round, roundStartedAtMs, data, inputTokens, outputTokens, llmUsage?.aigneHubCredits ?? 0, llmUsage?.cacheReadInputTokens ?? 0);
+		const roundMsgStart = messages.length;
+		const llmDurationMs = Date.now() - llmStartTime;
+		messages.push({
+			role: "assistant",
+			content: text ?? "",
+			toolCalls: rawToolCalls,
+			durationMs: llmDurationMs
+		});
+		await appendNewMessages([messages[messages.length - 1]]);
+		const roundCalls = toolCalls.slice(0, actionsPerRound);
+		const droppedCalls = toolCalls.slice(actionsPerRound);
+		const traceEntries = [];
+		if (text?.trim()) emitProgress({
+			type: "thinking",
+			round,
+			text,
+			model: resolvedModelName
+		});
+		emitProgress({
+			type: "tool_start",
+			round,
+			calls: roundCalls.map((c) => ({
+				id: c.toolCallId,
+				tool: c.toolName,
+				path: String(c.args.path ?? ""),
+				status: "pending",
+				args: c.args
+			}))
+		});
+		const toolsStartTime = Date.now();
+		const skillResults = /* @__PURE__ */ new Map();
+		const breakerResults = /* @__PURE__ */ new Map();
+		const thisRoundKeys = /* @__PURE__ */ new Set();
+		for (const call of roundCalls) {
+			const key = `${call.toolName}:${stableStringify(call.args)}`;
+			thisRoundKeys.add(key);
+			if (String(call.args?.path ?? "") === ASK_USER_PATH) continue;
+			const entry = callHistory.get(key);
+			if (entry && entry.count >= CIRCUIT_BREAKER_THRESHOLD - 1) {
+				breakerResults.set(call.toolCallId, entry.lastResult);
+				traceEntries.push({
+					id: call.toolCallId,
+					name: call.toolName,
+					path: String(call.args.path ?? ""),
+					status: "circuit_breaker"
+				});
+			}
+		}
+		const validatedCalls = [];
+		for (const call of roundCalls) {
+			if (skillResults.has(call.toolCallId)) continue;
+			if (breakerResults.has(call.toolCallId)) continue;
+			const op = toolNameToOp(call.toolName);
+			if (!op) {
+				validatedCalls.push({
+					call,
+					op: "unknown",
+					valid: false,
+					reason: `Unknown tool: ${call.toolName}`
+				});
+				continue;
+			}
+			if (call.toolName.startsWith("afs_action_")) fixPerActionPath(call, schemasByAction);
+			const path = call.args.path;
+			const isBatchWrite = op === "write" && Array.isArray(call.args.entries) && call.args.entries.length > 0;
+			const batchReadPaths = op === "read" && Array.isArray(call.args.entries) && call.args.entries.length > 0 ? call.args.entries.map((e) => e?.path).filter((p) => typeof p === "string") : null;
+			if (!path && !isBatchWrite && !batchReadPaths) {
+				validatedCalls.push({
+					call,
+					op,
+					valid: false,
+					reason: "Missing path argument"
+				});
+				continue;
+			}
+			if (path) {
+				const validation = validateToolCall(path, op, params.tools);
+				if (!validation.allowed) {
+					validatedCalls.push({
+						call,
+						op,
+						valid: false,
+						reason: validation.reason
+					});
+					continue;
+				}
+			}
+			if (batchReadPaths) {
+				const denied = batchReadPaths.map((p) => ({
+					p,
+					v: validateToolCall(p, op, params.tools)
+				})).find(({ v }) => !v.allowed);
+				if (denied) {
+					validatedCalls.push({
+						call,
+						op,
+						valid: false,
+						reason: denied.v.reason
+					});
+					continue;
+				}
+			}
+			const missingArg = REQUIRED_ARGS[op]?.find((arg) => !(arg in call.args));
+			if (missingArg) {
+				validatedCalls.push({
+					call,
+					op,
+					valid: false,
+					reason: `Missing required argument '${missingArg}' for ${op}`
+				});
+				continue;
+			}
+			validatedCalls.push({
+				call,
+				op,
+				valid: true
+			});
+		}
+		const ashCalls = [];
+		const directCalls = [];
+		const errorResults = [];
+		for (const { call, op, valid, reason } of validatedCalls) {
+			if (!valid) {
+				errorResults.push({
+					id: call.toolCallId,
+					error: reason ?? "Validation failed"
+				});
+				traceEntries.push({
+					id: call.toolCallId,
+					name: call.toolName,
+					path: String(call.args.path ?? ""),
+					status: "error",
+					error: reason
+				});
+				emitProgress({
+					type: "tool_result",
+					round,
+					calls: [{
+						id: call.toolCallId,
+						tool: call.toolName,
+						path: String(call.args.path ?? ""),
+						status: "error",
+						error: reason
+					}]
+				});
+				continue;
+			}
+			const path = call.args.path;
+			if (ASH_OPS.has(op)) ashCalls.push({
+				id: call.toolCallId,
+				op,
+				path,
+				args: extractExecArgs(call.args)
+			});
+			else directCalls.push({
+				call,
+				op
+			});
+			traceEntries.push({
+				id: call.toolCallId,
+				name: call.toolName,
+				path,
+				status: "ok"
+			});
+		}
+		const ashResults = {};
+		if (ashCalls.length > 0) {
+			const source = generateAsh(ashCalls, round);
+			const ashResult = await deps.runAsh(source, {
+				returnWrittenData: true,
+				skipWritePrefix: RESULTS_PREFIX
+			});
+			if (ashResult.success && ashResult.data?.writtenData) {
+				const writtenData = ashResult.data.writtenData;
+				for (const call of ashCalls) {
+					const data$1 = writtenData[`${RESULTS_PREFIX}${call.id}`];
+					ashResults[call.id] = data$1 ? JSON.stringify(data$1) : "No result";
+				}
+			} else for (const call of ashCalls) ashResults[call.id] = `ASH execution error: ${ashResult.data?.error ?? "unknown"}`;
+			emitProgress({
+				type: "tool_result",
+				round,
+				calls: ashCalls.map((c) => ({
+					id: c.id,
+					tool: `afs_${c.op}`,
+					path: c.path,
+					status: ashResults[c.id]?.startsWith("ASH execution error") ? "error" : "ok",
+					result: truncateResult(ashResults[c.id], 2e3)
+				}))
+			});
+		}
+		const directResults = {};
+		const executeDirectCall = async ({ call, op }) => {
+			const path = call.args.path || "/";
+			const directArgs = { ...call.args };
+			delete directArgs.path;
+			if (op === "exec" && directArgs.args && typeof directArgs.args === "object" && !Array.isArray(directArgs.args)) {
+				if (!("task" in directArgs || "proc" in directArgs || "session" in directArgs || "system" in directArgs)) {
+					const inner = directArgs.args;
+					delete directArgs.args;
+					for (const [k, v] of Object.entries(inner)) if (!(k in directArgs)) directArgs[k] = v;
+				}
+			}
+			if (op === "exec" && params.execContext) {
+				const nested = directArgs.args;
+				if (nested && typeof nested === "object" && !Array.isArray(nested)) {
+					const nestedObj = nested;
+					const innerArgs = nestedObj.args;
+					if (innerArgs && typeof innerArgs === "object" && !Array.isArray(innerArgs)) nestedObj.args = {
+						...params.execContext,
+						...innerArgs
+					};
+					else directArgs.args = {
+						...params.execContext,
+						...nestedObj
+					};
+				} else if (path.startsWith("/proc/messaging/tools/")) {
+					for (const [k, v] of Object.entries(params.execContext)) if (!(k in directArgs)) directArgs[k] = v;
+				}
+			}
+			if (op === "exec" && procId && !directArgs.parentProcId) directArgs.parentProcId = procId;
+			if (op === "exec" && isSubAgentRunPath(path)) {
+				const parentRemaining = tokenBudget - totalTokens;
+				if (parentRemaining < Number.POSITIVE_INFINITY) directArgs._parent_budget_remaining = Math.max(0, parentRemaining);
+				if (params.abortSignal) directArgs._abort_signal = params.abortSignal;
+				const parentSession = params.session ?? nesting.chain[nesting.chain.length - 1] ?? void 0;
+				if (parentSession) directArgs._parent_session = parentSession;
+				const childSession = typeof directArgs.session === "string" && directArgs.session ? directArgs.session : `${path}#${call.toolCallId}`;
+				directArgs._chain = [...nesting.chain, childSession];
+			}
+			const toolStartedAt = Date.now();
+			let recordResult = null;
+			let recordStatus = "ok";
+			let recordError = null;
+			try {
+				const result = await deps.callAFS(op, path, directArgs);
+				const isOk = result.success;
+				if (isOk && op === "exec" && path.endsWith("/.actions/run")) subRuns += 1;
+				let dataForLLM = result.data;
+				if (isOk && dataForLLM && typeof dataForLLM === "object" && "_meta" in dataForLLM) {
+					const shaped = dataForLLM;
+					if (shaped._meta) {
+						emitProgress({
+							type: "subAgentMetadata",
+							round,
+							calls: [{
+								id: call.toolCallId,
+								tool: call.toolName,
+								path,
+								status: "ok"
+							}],
+							subAgentMeta: shaped._meta
+						});
+						const childTokens = shaped._meta.tokens_used;
+						if (typeof childTokens === "number" && childTokens > 0) totalTokens += childTokens;
+					}
+					dataForLLM = shaped.result;
+				}
+				if (isOk) {
+					recordResult = dataForLLM;
+					recordStatus = "ok";
+				} else {
+					recordStatus = "error";
+					recordError = result.error?.message ?? result.data?.error ?? "failed";
+				}
+				let stringifiedResult;
+				if (isOk) try {
+					stringifiedResult = JSON.stringify(dataForLLM);
+				} catch (stringErr) {
+					const msg = stringErr instanceof Error ? stringErr.message : String(stringErr);
+					stringifiedResult = `Error: ${msg}`;
+					recordStatus = "error";
+					recordError = msg;
+				}
+				else stringifiedResult = `Error: ${recordError ?? "failed"}`;
+				directResults[call.toolCallId] = stringifiedResult;
+				emitProgress({
+					type: "tool_result",
+					round,
+					calls: [{
+						id: call.toolCallId,
+						tool: call.toolName,
+						path,
+						status: isOk ? "ok" : "error",
+						...!isOk && { error: directResults[call.toolCallId] },
+						result: truncateResult(directResults[call.toolCallId], 2e3)
+					}]
+				});
+			} catch (err) {
+				const msg = err instanceof Error ? err.message : String(err);
+				directResults[call.toolCallId] = `Error: ${msg}`;
+				recordStatus = "error";
+				recordError = msg;
+				emitProgress({
+					type: "tool_result",
+					round,
+					calls: [{
+						id: call.toolCallId,
+						tool: call.toolName,
+						path,
+						status: "error",
+						error: msg,
+						result: `Error: ${msg}`
+					}]
+				});
+			}
+			totalsAccumulator.toolsUsed.add(call.toolName);
+			await emitObs({
+				type: "tool",
+				round,
+				callId: call.toolCallId,
+				name: call.toolName,
+				path,
+				op,
+				args: stripInternalFields(directArgs),
+				result: truncateField(recordResult, FIELD_LIMIT),
+				status: recordStatus,
+				errorMessage: recordError,
+				durationMs: Date.now() - toolStartedAt
+			});
+		};
+		const isMutatingOp = (op) => op === "write" || op === "exec";
+		let readBatch = [];
+		const flushReadBatch = async () => {
+			if (readBatch.length === 0) return;
+			await Promise.all(readBatch.map((entry) => executeDirectCall(entry)));
+			readBatch = [];
+		};
+		for (const entry of directCalls) {
+			if (isMutatingOp(entry.op)) {
+				await flushReadBatch();
+				await executeDirectCall(entry);
+				continue;
+			}
+			readBatch.push(entry);
+		}
+		await flushReadBatch();
+		if (params.onProgress) {
+			const prog = params.onProgress;
+			const progressPath = typeof prog === "string" ? prog : prog.path;
+			const progressArgs = typeof prog === "string" ? {} : Object.fromEntries(Object.entries(prog).filter(([k]) => k !== "path"));
+			const toolSummary = summarizeToolCalls(roundCalls, traceEntries, errorResults);
+			const trimmed = text?.trim() ?? "";
+			const prefixedText = trimmed ? `🤖 ${trimmed}` : "";
+			const enrichedText = prefixedText && toolSummary ? `${prefixedText}\n${toolSummary}` : prefixedText || toolSummary;
+			await deps.callAFS("exec", progressPath, {
+				...progressArgs,
+				text: enrichedText,
+				message_text: prefixedText,
+				tool_summary: toolSummary
+			});
+		}
+		const updatedKeys = /* @__PURE__ */ new Set();
+		for (const call of roundCalls) {
+			if (breakerResults.has(call.toolCallId) || errorResults.find((e) => e.id === call.toolCallId)) continue;
+			if (String(call.args?.path ?? "") === ASK_USER_PATH) continue;
+			const key = `${call.toolName}:${stableStringify(call.args)}`;
+			if (updatedKeys.has(key)) continue;
+			updatedKeys.add(key);
+			const result = ashResults[call.toolCallId] ?? directResults[call.toolCallId] ?? "";
+			const prev = callHistory.get(key);
+			callHistory.set(key, {
+				count: (prev?.count ?? 0) + 1,
+				lastResult: result
+			});
+		}
+		for (const key of callHistory.keys()) if (!thisRoundKeys.has(key)) callHistory.delete(key);
+		for (const call of roundCalls) {
+			let content;
+			if (skillResults.has(call.toolCallId)) content = skillResults.get(call.toolCallId);
+			else if (breakerResults.has(call.toolCallId)) content = `[Circuit breaker: this exact call was repeated ${CIRCUIT_BREAKER_THRESHOLD} consecutive times. Cached result returned. Change your approach — do NOT re-send the identical call. If you are writing a large file and the content looks cut off, your output was likely truncated at the token limit: write more concise content, or split it (one cms-write for the first part, then mode:append for the rest).]\n${breakerResults.get(call.toolCallId)}`;
+			else {
+				const errorEntry = errorResults.find((e) => e.id === call.toolCallId);
+				if (errorEntry) content = `Error: ${errorEntry.error}`;
+				else {
+					const resultStr = ashResults[call.toolCallId] ?? directResults[call.toolCallId] ?? void 0;
+					content = resultStr !== void 0 ? enrichToolContent(truncateToolResult(resultStr, toolResultLimit)) : "Error: No result returned for this tool call";
+				}
+			}
+			if (typeof content === "string") content = truncateToolResult(content, toolResultLimit);
+			messages.push({
+				role: "tool",
+				tool_call_id: call.toolCallId,
+				content
+			});
+		}
+		for (const call of droppedCalls) messages.push({
+			role: "tool",
+			tool_call_id: call.toolCallId,
+			content: `Error: Tool call dropped — exceeded actions_per_round limit (${actionsPerRound}). Retry in next round.`
+		});
+		const toolsDurationMs = Date.now() - toolsStartTime;
+		for (let i = roundMsgStart + 1; i < messages.length; i++) {
+			const m = messages[i];
+			if (m.role === "tool") m.durationMs = toolsDurationMs;
+		}
+		totalActions += roundCalls.length - errorResults.length - skillResults.size - breakerResults.size;
+		trace.push({
+			round,
+			tool_calls: traceEntries,
+			tokens: {
+				input: inputTokens,
+				output: outputTokens
+			}
+		});
+		await appendNewMessages(messages.slice(roundMsgStart + 1));
+	}
+	emitProgress({
+		type: "summary",
+		round: maxRounds,
+		model: resolvedModelName,
+		tokens: {
+			input: totalInputTokens,
+			output: totalOutputTokens,
+			cached: totalCachedTokens,
+			cost: totalCost
+		}
+	});
+	completeProc("done");
+	return {
+		status: "budget_exhausted",
+		rounds: maxRounds,
+		total_actions: totalActions,
+		total_tokens: totalTokens,
+		sub_runs: subRuns,
+		trace,
+		totals: totalsSnapshot()
+	};
+}
+
+//#endregion
+//#region src/messages-log.ts
+/**
+* Append-only JSONL message log for inter-agent communication (L3).
+*
+* Provider internal: direct fs calls are allowed here (see CLAUDE.md).
+*/
+const MAX_BODY_BYTES = 64 * 1024;
+let globalSeq = 0;
+function appendMessage(filePath, from, to, body, kind = "message") {
+	if (JSON.stringify(body).length > MAX_BODY_BYTES) throw new Error("PAYLOAD_TOO_LARGE: message body exceeds 64KB limit");
+	if (!from || typeof from !== "string") throw new TypeError("from must be a non-empty string");
+	if (!to || typeof to !== "string") throw new TypeError("to must be a non-empty string");
+	const entry = {
+		message_id: randomUUID(),
+		from,
+		to,
+		kind,
+		ts: (/* @__PURE__ */ new Date()).toISOString(),
+		seq: ++globalSeq,
+		body
+	};
+	const line = `${JSON.stringify(entry)}\n`;
+	if (!existsSync(filePath)) writeFileSync(filePath, line);
+	else appendFileSync(filePath, line);
+	return entry;
+}
+function readMessages(filePath, options) {
+	if (!existsSync(filePath)) return [];
+	const raw = readFileSync(filePath, "utf8");
+	if (!raw.trim()) return [];
+	const entries = [];
+	const lines = raw.split("\n");
+	for (const line of lines) {
+		const trimmed = line.trim();
+		if (!trimmed) continue;
+		try {
+			const entry = JSON.parse(trimmed);
+			entries.push(entry);
+		} catch {}
+	}
+	let filtered = entries;
+	if (options?.since) {
+		const sinceDate = new Date(options.since);
+		filtered = filtered.filter((e) => new Date(e.ts) > sinceDate);
+	}
+	filtered.sort((a, b) => {
+		const tsDiff = new Date(a.ts).getTime() - new Date(b.ts).getTime();
+		if (tsDiff !== 0) return tsDiff;
+		return a.seq - b.seq;
+	});
+	if (options?.limit && options.limit > 0) filtered = filtered.slice(0, options.limit);
+	return filtered;
+}
+function resetSeqCounter() {
+	globalSeq = 0;
+}
+
+//#endregion
+//#region src/observability-routing.ts
+/**
+* Derive the owning persistence class from the trusted write context.
+* `agentRunOrigin` defaults to `interactive` when undefined.
+*
+* **An authenticated** caller (`callerAuthenticated: true`) ALWAYS routes to
+* `"user"` — their runs are owned by their persisted identity. An
+* unauthenticated caller — including an anonymous WS connection that the
+* Node daemon stamped with a synthetic guest DID — is treated as anonymous
+* and falls through to the `anonymousInteractivePersistence` policy so the
+* trace lands somewhere the observability explorer can actually scan
+* (`/blocklets/<id>/instance/logs/agent-runs/` or the host-inbox), rather
+* than the guest's per-DID user space which is by design private.
+*
+* `callerAuthenticated` defaults to `false` when `callerDid` is set but the
+* caller comes from a legacy path that doesn't carry an auth marker — that
+* was the pre-Phase 3c behavior, so legacy callers stay routed the same
+* way.
+*/
+function derivePersistenceClass(input) {
+	if (input.callerDid && input.callerAuthenticated !== false) return "user";
+	if (input.agentRunOrigin === "system") return "instance";
+	if (input.anonymousInteractivePersistence === "instance") return "instance";
+	return "ephemeral";
+}
+/** Build the relative-within-fragment jsonl path (`logs/agent-runs/<date>/<file>`). */
+function userFragmentRunPath(date, fileName) {
+	return joinURL("/logs/agent-runs", date, fileName);
+}
+/**
+* Resolve the `TraceSink` for a run. Pure except for the injected
+* `spaceResolver` / `legacyProbe` async calls. Called once per run (the
+* resolved sink is reused for every emit).
+*/
+async function resolveTraceSink(input) {
+	const pc = input.persistenceClass;
+	if (pc === "ephemeral") return {
+		kind: "none",
+		persistenceClass: pc,
+		reason: "ephemeral",
+		dropped: false
+	};
+	if (pc === "user") {
+		const missing = [];
+		if (!input.callerDid) missing.push("callerDid");
+		if (!input.instanceDid) missing.push("instanceDid");
+		if (!input.spaceResolver) missing.push("spaceResolver");
+		if (missing.length === 0) return {
+			kind: "afs",
+			persistenceClass: pc,
+			afs: await (await input.spaceResolver.resolveUserSpace(input.callerDid)).getInstanceSpace({
+				instanceDid: input.instanceDid,
+				role: "user",
+				accessMode: "readwrite"
+			}),
+			path: input.fragmentRunPath,
+			reason: "user-direct-write"
+		};
+		const reason = `user-missing:${missing.join(",")} mode=${input.ownershipRoutingMode}`;
+		if (input.ownershipRoutingMode === "strict-user" || input.ownershipRoutingMode === "strict-all") return {
+			kind: "none",
+			persistenceClass: pc,
+			reason,
+			dropped: true
+		};
+		return {
+			kind: "legacy-current-afs",
+			persistenceClass: pc,
+			path: await input.legacyProbe(),
+			reason
+		};
+	}
+	if (input.ownershipRoutingMode === "strict-all" && !input.instanceDid) return {
+		kind: "none",
+		persistenceClass: pc,
+		reason: `instance-missing:instanceDid mode=strict-all`,
+		dropped: true
+	};
+	return {
+		kind: "legacy-current-afs",
+		persistenceClass: pc,
+		path: await input.legacyProbe(),
+		reason: "instance-legacy-probing"
+	};
+}
+
+//#endregion
+//#region src/spawn-depth.ts
+const DEFAULT_MAX = 3;
+const HARD_CAP = 10;
+function checkSpawnDepth(chain, manifestMax) {
+	if (!Array.isArray(chain)) throw new TypeError("chain must be an array");
+	let max = DEFAULT_MAX;
+	if (typeof manifestMax === "number" && manifestMax > 0) max = Math.min(Math.floor(manifestMax), HARD_CAP);
+	const depth = chain.length;
+	if (depth >= max) throw new Error(`MAX_SPAWN_DEPTH_EXCEEDED: depth ${depth} >= max ${max}`);
+}
+
+//#endregion
+//#region src/orchestration.ts
+/**
+* agent-run orchestration — the args→params→deps→runAgentLoop pipeline.
+*
+* Owns the execution flow that used to live as `executeAgentRunImpl` on
+* the AFSAsh class. Now exposed as a standalone function so AFSAgent
+* can call it directly without delegating to ash.
+*
+* What this layer does (between AFS exec args and `runAgentLoop`):
+*
+*   1. Strip the in-process `_*` args (scope_afs, on_tool_progress,
+*      abort_signal, parent_session, chain) so cleanArgs is
+*      serialization-safe.
+*   2. Validate task / model / tools shape.
+*   3. Resolve the model path (short name → /dev/ai/hubs/aignehub mount;
+*      absolute path → normalized verbatim; chat-action leaf → kept as-is).
+*   4. Stat the model node to discover its context window (best-effort,
+*      non-fatal).
+*   5. Append caller-provided structured `context` JSON to the task.
+*   6. Build the `AgentRunParams` + `AgentRunDeps` (callLLM, runAsh,
+*      callAFS, history persistence) and invoke `runAgentLoop`.
+*
+* The `runAsh` dep delegates back to ash via AFS exec on the configured
+* mount path (default `/ash/.actions/run`) — agent-run does not own the
+* ash DSL execution. ash's run handler accepts `_return_written_data`
+* and `_skip_write_prefix` flags forwarded here so the orchestration
+* doesn't need to import AFSAsh internals.
+*/
+const log = makeNsLog("provider:agent");
+function normalizeAbsoluteAfsPath(path) {
+	if (!path.startsWith("/")) return path;
+	const segments = [];
+	for (const segment of path.split("/")) {
+		if (!segment || segment === ".") continue;
+		if (segment === "..") segments.pop();
+		else segments.push(segment);
+	}
+	return `/${segments.join("/")}`;
+}
+function hasUnsafePathSegments(path) {
+	return path.split("/").some((segment) => segment === "." || segment === "..");
+}
+/**
+* Resolve a user-provided model identifier into an absolute AFS path.
+*
+* - `/foo/bar` → verbatim (after `..` / `.` normalization, rejected if
+*   any path segment is `.` or `..`).
+* - `gpt-4o` → `/dev/ai/hubs/aignehub/models/gpt-4o`.
+*
+* The returned path may either point at a model NODE (e.g.
+* `/dev/ai/hubs/aignehub/models/gpt-4o`) or directly at a chat-action
+* leaf (e.g. `/dev/ai/.actions/chat`). The caller distinguishes via
+* regex on `/.actions/(chat|embed|image|video)$`.
+*/
+function resolveAgentModelPath(model) {
+	if (!model) throw new Error("agent-run requires 'model' parameter as string");
+	if (model.startsWith("/")) {
+		if (hasUnsafePathSegments(model)) throw new Error("agent-run model path contains unsafe path segments");
+		return normalizeAbsoluteAfsPath(model);
+	}
+	if (model.includes("//") || hasUnsafePathSegments(model)) throw new Error("agent-run model path contains unsafe path segments");
+	return `/dev/ai/hubs/aignehub/models/${model}`;
+}
+/**
+* Normalize tool calls to AIGNE format: { id, type: "function", function: { name, arguments } }.
+*
+* Accepts Vercel AI SDK ({ toolCallId, toolName, args }),
+* OpenAI ({ id, type, function: { name, arguments: string } }),
+* or already-normalized AIGNE format.
+*/
+function normalizeToolCallsToAIGNE(toolCalls) {
+	return toolCalls.map((tc) => {
+		if (tc.toolName && !tc.function) return {
+			id: tc.toolCallId ?? tc.id,
+			type: "function",
+			function: {
+				name: tc.toolName,
+				arguments: tc.args ?? {}
+			}
+		};
+		const fn = tc.function;
+		if (fn && typeof fn.arguments === "string") try {
+			return {
+				...tc,
+				function: {
+					...fn,
+					arguments: JSON.parse(fn.arguments)
+				}
+			};
+		} catch {
+			return tc;
+		}
+		return tc;
+	});
+}
+/**
+* The full args → result pipeline. Same contract as the legacy
+* `executeAgentRunImpl` method that used to live on AFSAsh, but as a
+* standalone function with explicit deps.
+*
+* Does NOT enqueue on a session queue — that's the caller's job (see
+* AFSAgent). Throws on validation failures (bad task / bad model)
+* and returns an `AFSExecResult` envelope on runtime failures.
+*/
+async function executeAgentRun(args, options = {}) {
+	const ashMountPath = options.ashMountPath ?? "/ash";
+	const runtimeAFSOverride = args._scope_afs;
+	const onToolProgress = args._on_tool_progress;
+	const abortSignal = args._abort_signal;
+	const parentSession = typeof args._parent_session === "string" ? args._parent_session : void 0;
+	const chain = Array.isArray(args._chain) ? args._chain.filter((value) => typeof value === "string") : void 0;
+	const cleanArgs = { ...args };
+	delete cleanArgs._scope_afs;
+	delete cleanArgs._on_tool_progress;
+	delete cleanArgs._abort_signal;
+	delete cleanArgs._parent_session;
+	delete cleanArgs._chain;
+	delete cleanArgs._ui_session;
+	const writePath = cleanArgs.write_to_path;
+	delete cleanArgs.write_to_path;
+	const context = cleanArgs.context;
+	let task = cleanArgs.task;
+	if (typeof task !== "string" || !task) if (context && typeof context === "object") task = JSON.stringify(context);
+	else if (typeof context === "string" && context) task = context;
+	else throw new Error("agent-run requires 'task' parameter as string");
+	const model = cleanArgs.model;
+	if (typeof model !== "string" || !model) throw new Error("agent-run requires 'model' parameter as string");
+	const rawTools = cleanArgs.tools;
+	const tools = rawTools === "none" || rawTools === void 0 ? [] : rawTools;
+	if (!Array.isArray(tools)) throw new Error("agent-run 'tools' must be an array or 'none'");
+	const globalAFS = options.globalAfs;
+	if (!globalAFS && !runtimeAFSOverride) throw new Error("agent-run requires AFS root to be mounted");
+	const afs = runtimeAFSOverride ?? globalAFS;
+	const skillPaths = cleanArgs.skill_paths;
+	const resolvedModel = resolveAgentModelPath(model);
+	const isDirectActionPath = /\/\.actions\/(chat|embed|image|video)$/.test(resolvedModel);
+	let contextWindow;
+	try {
+		if (afs.stat) {
+			const statPath = isDirectActionPath ? resolvedModel.replace(/\/\.actions\/\w+$/, "") : resolvedModel;
+			if (statPath && statPath !== "/dev/ai") {
+				const cw = (await afs.stat(statPath)).data?.meta?.contextWindow;
+				if (typeof cw === "number" && cw > 0) contextWindow = cw;
+			}
+		}
+	} catch {}
+	let enrichedTask = task;
+	if (cleanArgs.context != null) if (typeof cleanArgs.context === "string") enrichedTask += `\n\nMessage metadata:\n${cleanArgs.context}`;
+	else {
+		const metaStr = JSON.stringify(cleanArgs.context, null, 2);
+		enrichedTask += `\n\nMessage metadata:\n\`\`\`json\n${metaStr}\n\`\`\``;
+	}
+	const systemPrompt = cleanArgs.system;
+	const spawnChain = chain ?? (typeof cleanArgs.session === "string" ? [cleanArgs.session] : []);
+	checkSpawnDepth(spawnChain);
+	const userBudget = cleanArgs.budget ?? {};
+	const params = {
+		task: enrichedTask,
+		model,
+		tools,
+		budget: {
+			max_rounds: userBudget.max_rounds,
+			actions_per_round: userBudget.actions_per_round,
+			total_tokens: userBudget.total_tokens,
+			context_window: contextWindow,
+			max_retries: userBudget.max_retries
+		},
+		system: systemPrompt,
+		session: cleanArgs.session,
+		skillPaths,
+		toolChoice: cleanArgs.tool_choice,
+		modelArgs: cleanArgs.model_args !== void 0 ? cleanArgs.model_args : cleanArgs.modelArgs,
+		onProgress: cleanArgs.on_progress,
+		onToolProgress,
+		responseSchema: cleanArgs.response_schema,
+		execContext: cleanArgs.exec_context,
+		parentSession,
+		chain: spawnChain,
+		memory: cleanArgs.memory,
+		index: cleanArgs.index,
+		skipAfsHint: cleanArgs.skip_afs_hint === true || cleanArgs.skipAfsHint === true || void 0,
+		abortSignal,
+		parentProcId: cleanArgs.parentProcId
+	};
+	let trustedAfsContext;
+	/** Merge the trusted context into an AFS options object (no-op when empty). */
+	const withCtx = (opts) => trustedAfsContext ? {
+		...opts,
+		context: trustedAfsContext
+	} : opts;
+	const deps = {
+		callLLM: async (llmArgs) => {
+			if (!afs.exec) return {
+				success: false,
+				data: { error: "exec not supported" }
+			};
+			const modelPath = isDirectActionPath ? resolvedModel : `${resolvedModel}/.actions/chat`;
+			const onChunk = llmArgs._onChunk;
+			const translated = { ...llmArgs };
+			delete translated._onChunk;
+			if (Array.isArray(translated.messages)) translated.messages = translated.messages.map((msg) => {
+				const m = { ...msg };
+				if (m.role === "assistant") m.role = "agent";
+				if (m.role === "tool" && m.tool_call_id && !m.toolCallId) {
+					m.toolCallId = m.tool_call_id;
+					delete m.tool_call_id;
+				}
+				const rawTCs = m.toolCalls ?? m.tool_calls;
+				if (Array.isArray(rawTCs)) {
+					m.toolCalls = normalizeToolCallsToAIGNE(rawTCs);
+					delete m.tool_calls;
+				}
+				return m;
+			});
+			try {
+				const raw = await afs.exec(modelPath, translated, withCtx(onChunk ? { onChunk } : {}));
+				if (raw.success && raw.data) {
+					const inner = raw.data;
+					const result$1 = inner.result;
+					const src = result$1 ?? inner;
+					const usage = src.usage ?? result$1;
+					const toolCalls = src.toolCalls;
+					raw.data = {
+						text: src.text,
+						json: src.json,
+						thoughts: src.thoughts,
+						toolCalls: toolCalls ? normalizeToolCallsToAIGNE(toolCalls) : void 0,
+						inputTokens: usage?.inputTokens ?? inner.inputTokens,
+						outputTokens: usage?.outputTokens ?? inner.outputTokens,
+						model: src.model,
+						usage: src.usage ?? usage,
+						finishReason: src.finishReason ?? src.finish_reason ?? src.stopReason ?? src.stop_reason,
+						reason: src.reason ?? inner.reason
+					};
+				}
+				return raw;
+			} catch (err) {
+				const errMsg = err instanceof Error ? err.message : String(err);
+				if (errMsg.includes("No module found")) return {
+					success: false,
+					data: { error: `Model provider not mounted: ${resolvedModel} — check if the provider started correctly (afs service restart)` }
+				};
+				return {
+					success: false,
+					data: { error: `LLM exec failed: ${errMsg}` }
+				};
+			}
+		},
+		runAsh: async (source, runArgs) => {
+			if (!afs.exec) return {
+				success: false,
+				data: { error: "exec not supported" }
+			};
+			return afs.exec(`${ashMountPath}/.actions/run`, {
+				source,
+				...runArgs,
+				_scope_afs: afs,
+				_return_written_data: true,
+				_skip_write_prefix: "/.results/"
+			}, withCtx({}));
+		},
+		callAFS: async (op, path, opArgs) => {
+			switch (op) {
+				case "read": {
+					const readEntries = opArgs?.entries;
+					if (readEntries && readEntries.length > 0) {
+						if (readEntries.length > 16) return {
+							success: false,
+							data: { error: `Too many entries (${readEntries.length} > 16) — split into chunks of 16` }
+						};
+						const paths = readEntries.map((e) => e.path);
+						const batchEntries = paths.map((p) => ({ path: p }));
+						const afsWithBatch = afs;
+						if (typeof afsWithBatch.batchRead === "function") return {
+							success: true,
+							data: { batch: await afsWithBatch.batchRead(batchEntries, withCtx({})) }
+						};
+						const results = [];
+						let succeeded = 0;
+						let failed = 0;
+						for (const p of paths) try {
+							const r = await afs.read(p, withCtx({}));
+							results.push({
+								path: p,
+								success: true,
+								data: r.data
+							});
+							succeeded++;
+						} catch (err) {
+							results.push({
+								path: p,
+								success: false,
+								error: err instanceof Error ? err.message : String(err)
+							});
+							failed++;
+						}
+						return {
+							success: true,
+							data: { batch: {
+								results,
+								succeeded,
+								failed
+							} }
+						};
+					}
+					return {
+						success: true,
+						data: (await afs.read(path, withCtx(opArgs ?? {}))).data
+					};
+				}
+				case "list": return {
+					success: true,
+					data: (await afs.list(path, withCtx(opArgs ?? {}))).data
+				};
+				case "search":
+					if (!afs.search) return {
+						success: false,
+						data: { error: "search not supported" }
+					};
+					return {
+						success: true,
+						data: { results: (await afs.search(path, opArgs?.query ?? "", withCtx(opArgs ?? {}))).data }
+					};
+				case "write": {
+					if (!afs.write) return {
+						success: false,
+						data: { error: "write not supported" }
+					};
+					const entries = opArgs?.entries;
+					if (entries && entries.length > 0) {
+						const batchEntries = entries.map((e) => ({
+							path: e.path,
+							content: e.content !== void 0 ? { content: e.content } : void 0,
+							mode: e.mode
+						}));
+						const afsWithBatch = afs;
+						if (typeof afsWithBatch.batchWrite === "function") return {
+							success: true,
+							data: { batch: await afsWithBatch.batchWrite(batchEntries, withCtx({})) }
+						};
+						const results = [];
+						let succeeded = 0;
+						let failed = 0;
+						for (const entry of batchEntries) try {
+							const r = await afs.write(entry.path, entry.content ?? {}, withCtx(entry.mode !== void 0 ? { mode: entry.mode } : {}));
+							results.push({
+								path: entry.path,
+								success: true,
+								data: r.data
+							});
+							succeeded++;
+						} catch (err) {
+							results.push({
+								path: entry.path,
+								success: false,
+								error: err instanceof Error ? err.message : String(err)
+							});
+							failed++;
+						}
+						return {
+							success: true,
+							data: { batch: {
+								results,
+								succeeded,
+								failed
+							} }
+						};
+					}
+					const writePayload = {};
+					if (opArgs?.content !== void 0) writePayload.content = opArgs.content;
+					const writeOpts = {};
+					if (opArgs?.mode !== void 0) writeOpts.mode = opArgs.mode;
+					if (opArgs?.field !== void 0) writeOpts.field = opArgs.field;
+					if (opArgs?.by !== void 0) writeOpts.by = opArgs.by;
+					if (opArgs?.ifMatch !== void 0) writeOpts.ifMatch = opArgs.ifMatch;
+					return {
+						success: true,
+						data: { written: (await afs.write(path, writePayload, withCtx(writeOpts))).data }
+					};
+				}
+				case "delete": {
+					if (!afs.delete) return {
+						success: false,
+						data: { error: "delete not supported" }
+					};
+					const deleteOpts = {};
+					if (opArgs?.where !== void 0) {
+						let where = opArgs.where;
+						if (typeof where === "string") try {
+							where = JSON.parse(where);
+						} catch (e) {
+							return {
+								success: false,
+								data: { error: `delete: 'where' is not valid JSON: ${e instanceof Error ? e.message : String(e)}` }
+							};
+						}
+						deleteOpts.where = where;
+					}
+					if (typeof opArgs?.maxItems === "number") deleteOpts.maxItems = opArgs.maxItems;
+					if (opArgs?.ifMatch !== void 0) deleteOpts.ifMatch = opArgs.ifMatch;
+					return {
+						success: true,
+						data: { deleted: await afs.delete(path, withCtx(deleteOpts)) }
+					};
+				}
+				case "stat":
+					if (!afs.stat) return {
+						success: false,
+						data: { error: "stat not supported" }
+					};
+					return {
+						success: true,
+						data: { stat: (await afs.stat(path, withCtx({}))).data }
+					};
+				case "explain":
+					if (!afs.explain) return {
+						success: false,
+						data: { error: "explain not supported" }
+					};
+					return {
+						success: true,
+						data: { content: (await afs.explain(path, withCtx({}))).content }
+					};
+				case "exec": {
+					if (!afs.exec) return {
+						success: false,
+						data: { error: "exec not supported" }
+					};
+					const execArgs = opArgs?.args && typeof opArgs.args === "object" && !Array.isArray(opArgs.args) ? opArgs.args : opArgs ?? {};
+					if (path.endsWith("/ash/.actions/run") || path.endsWith("/ash/.actions/run-job") || path.endsWith("/dev/agent/.actions/run")) execArgs._scope_afs = afs;
+					try {
+						return await afs.exec(path, execArgs, withCtx({}));
+					} catch (execErr) {
+						if (path.endsWith(".ash") && afs.read) {
+							const readResult = await afs.read(path, withCtx({}));
+							const source = String(readResult.data?.content ?? "");
+							if (source.trim()) return afs.exec(`${ashMountPath}/.actions/run`, {
+								source,
+								...execArgs
+							}, withCtx({}));
+						}
+						throw execErr;
+					}
+				}
+				default: return {
+					success: false,
+					data: { error: `Unsupported direct op: ${op}` }
+				};
+			}
+		},
+		loadHistory: async (sessionPath) => {
+			const historyPath = `${sessionPath}/history.jsonl`;
+			try {
+				const result$1 = await afs.read(historyPath, withCtx({}));
+				const content = String(result$1.data?.content ?? "");
+				if (!content.trim()) return [];
+				return content.trim().split("\n").flatMap((line) => {
+					try {
+						return [JSON.parse(line)];
+					} catch {
+						return [];
+					}
+				});
+			} catch {
+				return [];
+			}
+		},
+		appendHistory: async (sessionPath, messages) => {
+			const historyPath = `${sessionPath}/history.jsonl`;
+			const newLines = `${messages.map((m) => JSON.stringify(m)).join("\n")}\n`;
+			await afs.write(historyPath, { content: newLines }, withCtx({ mode: "append" }));
+		},
+		rewriteHistory: async (sessionPath, messages) => {
+			const historyPath = `${sessionPath}/history.jsonl`;
+			const content = `${messages.map((m) => JSON.stringify(m)).join("\n")}\n`;
+			await afs.write(historyPath, { content }, withCtx({}));
+		},
+		archiveHistory: async (sessionPath, messages) => {
+			const archivePath = `${sessionPath}/history-${(/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-")}.jsonl`;
+			const content = `${messages.map((m) => JSON.stringify(m)).join("\n")}\n`;
+			await afs.write(archivePath, { content }, withCtx({}));
+		}
+	};
+	const runId = randomUUID();
+	const shortId = runId.replace(/-/g, "").slice(0, 8);
+	const startedAt = Date.now();
+	const iso = new Date(startedAt).toISOString();
+	const date = iso.slice(0, 10);
+	const time = iso.slice(11, 19).replace(/:/g, "");
+	const callerContextResolved = options.callerContext ?? {};
+	const rawBlockletId = typeof callerContextResolved.blockletId === "string" ? callerContextResolved.blockletId : null;
+	const blockletId = rawBlockletId !== null && rawBlockletId.length > 0 && !/[\\/]/.test(rawBlockletId) && !rawBlockletId.split("/").includes("..") && rawBlockletId !== "." && rawBlockletId !== ".." ? rawBlockletId : null;
+	const runFileName = `${time}-${shortId}.jsonl`;
+	const probeLegacyRunPath = async () => {
+		const userInstanceRunPath = joinURL("/instance/logs/agent-runs", date, runFileName);
+		const blockletRunPath = blockletId ? joinURL("/blocklets", blockletId, "instance/logs/agent-runs", date, runFileName) : null;
+		const hostInboxRunPath = joinURL("/dev/observability/.host-inbox", date, runFileName);
+		let runPath = userInstanceRunPath;
+		if (blockletRunPath && blockletId) try {
+			if ((await deps.callAFS("stat", joinURL("/blocklets", blockletId, "instance")))?.success) runPath = blockletRunPath;
+		} catch {}
+		if (runPath === userInstanceRunPath) try {
+			if ((await deps.callAFS("stat", "/dev/observability/.host-inbox"))?.success) runPath = hostInboxRunPath;
+		} catch {}
+		return runPath;
+	};
+	const callerInfo = callerContextResolved.caller;
+	const callerDid = (callerInfo && typeof callerInfo.did === "string" ? callerInfo.did : null) ?? (typeof callerContextResolved.userId === "string" ? callerContextResolved.userId : null);
+	const callerRole = callerInfo?.role ?? callerInfo?.roles?.[0];
+	const callerAuthenticated = Boolean(callerDid) && callerRole !== "guest";
+	const instanceDid = typeof callerContextResolved.instanceDid === "string" ? callerContextResolved.instanceDid : null;
+	const rawOrigin = callerContextResolved.agentRunOrigin;
+	const agentRunOrigin = rawOrigin === "system" ? "system" : rawOrigin === "interactive" ? "interactive" : void 0;
+	const obsRuntime = options.observabilityRuntime;
+	const ownershipRoutingMode = obsRuntime?.ownershipRoutingMode ?? "observe-only";
+	let sink;
+	if (!obsRuntime) sink = {
+		kind: "legacy-current-afs",
+		persistenceClass: "instance",
+		path: await probeLegacyRunPath(),
+		reason: "no-observability-runtime"
+	};
+	else sink = await resolveTraceSink({
+		persistenceClass: derivePersistenceClass({
+			callerDid,
+			callerAuthenticated,
+			agentRunOrigin,
+			anonymousInteractivePersistence: obsRuntime.anonymousInteractivePersistence
+		}),
+		callerDid,
+		instanceDid,
+		spaceResolver: obsRuntime.spaceResolver,
+		ownershipRoutingMode,
+		fragmentRunPath: userFragmentRunPath(date, runFileName),
+		legacyProbe: probeLegacyRunPath
+	});
+	if (sink.kind === "none" && sink.dropped) log.warn(`[observability] drop mode=${ownershipRoutingMode} persistenceClass=${sink.persistenceClass} reason=${sink.reason}`);
+	else if (sink.reason.includes("missing")) log.warn(`[observability] observe mode=${ownershipRoutingMode} persistenceClass=${sink.persistenceClass} reason=${sink.reason}`);
+	const userDid = callerDid ?? (typeof callerContextResolved.userId === "string" ? callerContextResolved.userId : null);
+	const sessionIdFromCtx = (typeof callerContextResolved.sessionId === "string" ? callerContextResolved.sessionId : null) ?? (typeof args._ui_session === "string" ? args._ui_session : null);
+	{
+		const ctx = {};
+		if (callerInfo && typeof callerInfo.did === "string") ctx.caller = callerInfo;
+		if (callerDid) ctx.userId = callerDid;
+		if (instanceDid) ctx.instanceDid = instanceDid;
+		if (agentRunOrigin) ctx.agentRunOrigin = agentRunOrigin;
+		if (sessionIdFromCtx) ctx.sessionId = sessionIdFromCtx;
+		if (rawBlockletId) ctx.blockletId = rawBlockletId;
+		if (Object.keys(ctx).length > 0) trustedAfsContext = ctx;
+	}
+	const inputSnapshot = {
+		task: params.task,
+		model: params.model,
+		tools: (params.tools ?? []).map((t) => ({
+			path: t.path,
+			ops: t.ops
+		})),
+		budget: userBudget,
+		systemPrompt: params.system
+	};
+	let seq = 0;
+	const nextSeq = () => seq++;
+	const writeTrace = async (content) => {
+		if (sink.kind === "none") return;
+		if (sink.kind === "afs") {
+			try {
+				await sink.afs.write(sink.path, { content }, { mode: "replace" });
+			} catch (err) {
+				log.warn(`[observability] user-space emit threw: ${sink.path} — ${err instanceof Error ? err.message : String(err)}`);
+			}
+			return;
+		}
+		try {
+			const result$1 = await deps.callAFS("write", sink.path, {
+				content,
+				mode: "replace"
+			});
+			if (!result$1.success) {
+				const err = result$1.error?.message;
+				log.warn(`[observability] emit failed: ${sink.path} — ${err ?? "unknown"}`);
+			}
+		} catch (err) {
+			log.warn(`[observability] emit threw: ${sink.path} — ${err instanceof Error ? err.message : String(err)}`);
+		}
+	};
+	const emittedLines = [];
+	let emitChain = Promise.resolve();
+	const emit = (event) => {
+		const line = safeStringifyLine(event);
+		emittedLines.push(line);
+		const next = emitChain.then(() => writeTrace(`${emittedLines.join("\n")}\n`));
+		emitChain = next.catch(() => {});
+		return next;
+	};
+	deps.emit = emit;
+	deps.nextSeq = nextSeq;
+	await emit({
+		type: "run.start",
+		seq: nextSeq(),
+		ts: startedAt,
+		runId,
+		blockletId: rawBlockletId,
+		userDid,
+		sessionId: sessionIdFromCtx,
+		input: inputSnapshot,
+		ownership: {
+			persistenceClass: sink.persistenceClass,
+			agentRunOrigin: agentRunOrigin ?? "interactive",
+			ownershipRoutingMode,
+			instanceDid,
+			sinkKind: sink.kind,
+			sinkReason: sink.reason
+		}
+	});
+	const emitRunEnd = async (status, resultData, resultError, totalsSnap) => {
+		const endedAt = Date.now();
+		await emit({
+			type: "run.end",
+			seq: nextSeq(),
+			ts: endedAt,
+			runId,
+			durationMs: endedAt - startedAt,
+			status,
+			result: {
+				data: resultData,
+				errorMessage: resultError
+			},
+			totals: totalsSnap ?? {
+				rounds: 0,
+				totalTokensIn: 0,
+				totalTokensOut: 0,
+				totalCost: 0,
+				modelsUsed: [],
+				hubsUsed: [],
+				toolsUsed: []
+			}
+		});
+	};
+	let result;
+	try {
+		result = await runAgentLoop(params, deps);
+	} catch (err) {
+		const errMsg = err instanceof Error ? err.message : String(err);
+		await emitRunEnd("error", null, errMsg, void 0);
+		return {
+			success: false,
+			data: {
+				status: "error",
+				error: `agent-run crashed: ${errMsg}`
+			}
+		};
+	}
+	await emitRunEnd(result.status === "completed" ? "ok" : result.status === "budget_exhausted" ? "budget_exhausted" : "error", result.result ?? null, result.error ?? null, result.totals);
+	if (result.status === "budget_exhausted") return {
+		success: false,
+		error: {
+			code: "BUDGET_EXHAUSTED",
+			message: `Budget exhausted at round ${result.rounds}/${params.budget?.max_rounds ?? "?"} (${result.total_tokens} tokens). Increase budget.max_rounds or budget.total_tokens in agent.json to continue.`
+		},
+		data: result
+	};
+	if (writePath && result.status === "completed" && typeof result.result === "string") {
+		if (!afs.write) return {
+			success: false,
+			error: {
+				code: "WRITE_TO_PATH_FAILED",
+				message: `write_to_path '${writePath}' failed: write not supported on this AFS`
+			},
+			data: result
+		};
+		const writeResult = result.result;
+		try {
+			await afs.write(writePath, { content: writeResult }, withCtx({ mode: "replace" }));
+		} catch (writeErr) {
+			return {
+				success: false,
+				error: {
+					code: "WRITE_TO_PATH_FAILED",
+					message: `write_to_path '${writePath}' failed: ${writeErr instanceof Error ? writeErr.message : String(writeErr)}`
+				},
+				data: result
+			};
+		}
+		return {
+			success: true,
+			data: {
+				path: writePath,
+				byteCount: Buffer.byteLength(writeResult, "utf8"),
+				summary: writeResult.slice(0, 200)
+			}
+		};
+	}
+	return {
+		success: result.status === "completed",
+		data: result
+	};
+}
+
+//#endregion
+//#region src/session-queue.ts
+/**
+* Per-key Promise chain queue for serializing async operations.
+*
+* Used by ASHProvider to ensure same-session agent-run calls execute
+* sequentially, preventing history file race conditions.
+*/
+function deriveChildSession(parentSessionId) {
+	if (typeof parentSessionId !== "string" || parentSessionId.length === 0) throw new TypeError("parentSessionId must be a non-empty string");
+	if (parentSessionId.includes("..")) throw new Error("path traversal disallowed in session id");
+	if (parentSessionId.includes("\0")) throw new Error("null bytes disallowed in session id");
+	return `${parentSessionId}/sub/${randomUUID()}`;
+}
+const DEFAULT_MAX_DEPTH = 20;
+function createSessionQueue(maxDepth = DEFAULT_MAX_DEPTH) {
+	const queues = /* @__PURE__ */ new Map();
+	const depths = /* @__PURE__ */ new Map();
+	return {
+		queues,
+		depths,
+		async enqueue(session, fn) {
+			if (!session) return fn();
+			const depth = depths.get(session) ?? 0;
+			if (depth >= maxDepth) throw new Error(`QUEUE_FULL: session queue full (max ${maxDepth})`);
+			depths.set(session, depth + 1);
+			const current = (queues.get(session) ?? Promise.resolve()).catch(() => {}).then(() => fn());
+			queues.set(session, current);
+			try {
+				return await current;
+			} finally {
+				const d = (depths.get(session) ?? 1) - 1;
+				if (d <= 0) depths.delete(session);
+				else depths.set(session, d);
+				if (queues.get(session) === current) queues.delete(session);
+			}
+		},
+		destroy() {
+			queues.clear();
+			depths.clear();
+		}
+	};
+}
+
+//#endregion
+//#region \0@oxc-project+runtime@0.108.0/helpers/decorate.js
+function __decorate(decorators, target, key, desc) {
+	var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+	if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+	else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+	return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+
+//#endregion
+//#region src/provider.ts
+var AFSAgent = class AFSAgent extends AFSBaseProvider {
+	static manifest() {
+		return {
+			name: "agent-run",
+			description: "LLM agent runtime: multi-round inference + tool_call dispatch loop. Wraps a single agent manifest, model, and tool whitelist into a single-shot agentic execution.",
+			uriTemplate: "agent-run://",
+			category: "compute",
+			schema: z.object({
+				name: z.string().optional(),
+				description: z.string().optional(),
+				ashMountPath: z.string().optional(),
+				maxSessionQueueDepth: z.number().int().positive().optional()
+			}),
+			tags: [
+				"llm",
+				"agent",
+				"ai",
+				"runtime"
+			],
+			capabilityTags: [
+				"read-write",
+				"auth:none",
+				"local"
+			],
+			security: {
+				riskLevel: "system",
+				resourceAccess: ["process-spawn"],
+				dataSensitivity: ["code"],
+				notes: ["Executes LLM-driven multi-round agentic loops with tool dispatch. Uses @aigne/afs-ash's path-validator for tool whitelist enforcement and delegates ash DSL execution to the ash provider via AFS routing."]
+			}
+		};
+	}
+	static async load({ config } = {}) {
+		return new AFSAgent(config);
+	}
+	name;
+	description;
+	accessMode = "readwrite";
+	ashMountPath;
+	sessionQueue;
+	observabilityRuntime;
+	afsRoot;
+	constructor(options = {}) {
+		super();
+		this.name = options.name ?? "agent-run";
+		this.description = options.description;
+		this.ashMountPath = options.ashMountPath ?? "/ash";
+		this.sessionQueue = createSessionQueue(options.maxSessionQueueDepth);
+		this.observabilityRuntime = options.observabilityRuntime;
+	}
+	onMount(afs) {
+		this.afsRoot = afs;
+	}
+	destroy() {
+		this.sessionQueue.destroy();
+	}
+	async statRoot(_ctx) {
+		return { data: {
+			id: "agent",
+			path: "/",
+			meta: {
+				kind: "afs:node",
+				kinds: ["afs:node"],
+				name: "agent",
+				description: "Agentic run provider — exposes the `run` action",
+				childrenCount: 0
+			}
+		} };
+	}
+	async statRunAction(_ctx) {
+		return { data: {
+			id: "run",
+			path: "/.actions/run",
+			meta: {
+				kind: "afs:executable",
+				kinds: ["afs:executable", "afs:node"],
+				name: "run",
+				description: "Run a single-task agentic loop"
+			}
+		} };
+	}
+	async listRootActions(_ctx) {
+		return { data: [{
+			id: "run",
+			path: "/.actions/run",
+			summary: "Run a single-task agentic loop",
+			meta: {
+				kind: "afs:executable",
+				kinds: ["afs:executable", "afs:node"],
+				name: "run",
+				description: "Execute a multi-round agentic loop: LLM inference → tool_call validation → tool execution → result feedback. Stops when the LLM returns text or budget exhausts.",
+				inputSchema: {
+					type: "object",
+					properties: {
+						task: {
+							type: "string",
+							description: "The task for the agent to accomplish"
+						},
+						model: {
+							type: "string",
+							description: "AI model path, e.g. /dev/ai/.actions/chat"
+						},
+						tools: { description: "AFS path patterns the LLM may call. `none` or empty array → LLM-only mode (no tool calling)." },
+						budget: {
+							type: "object",
+							description: "Budget caps: { max_rounds?, total_tokens? }"
+						},
+						session: {
+							type: "string",
+							description: "Session id for queue + history"
+						},
+						system: {
+							type: "string",
+							description: "System prompt prefix"
+						},
+						skill_paths: {
+							type: "array",
+							items: { type: "string" },
+							description: "Paths to skill SKILL.md files for prompt augmentation"
+						},
+						write_to_path: {
+							type: "string",
+							description: "AFS path to write the completed result text. When set and the agent completes successfully with text output, the text is written to this path and the response returns { path, byteCount, summary } instead of the full result."
+						}
+					},
+					required: ["task", "model"]
+				}
+			}
+		}] };
+	}
+	async execRootAction(ctx, args) {
+		const actionName = ctx.params.action;
+		if (actionName === "__debug-runtime") return this.execDebugRuntime();
+		if (actionName !== "run") return {
+			success: false,
+			error: {
+				code: "ACTION_NOT_FOUND",
+				message: `Unknown action '${actionName}' on agent-run provider; only 'run' is supported`
+			}
+		};
+		if (!this.afsRoot) return {
+			success: false,
+			error: {
+				code: "AGENT_RUN_NOT_INITIALIZED",
+				message: "AFSAgent has not been mounted yet — onMount has not fired"
+			}
+		};
+		const session = args.session;
+		let result;
+		try {
+			result = await this.sessionQueue.enqueue(session, () => executeAgentRun(args, {
+				globalAfs: this.afsRoot,
+				ashMountPath: this.ashMountPath,
+				callerContext: ctx.context,
+				observabilityRuntime: this.observabilityRuntime
+			}));
+		} catch (err) {
+			if (err instanceof Error && err.message.startsWith("QUEUE_FULL")) return {
+				success: false,
+				error: {
+					code: "QUEUE_FULL",
+					message: err.message
+				}
+			};
+			throw err;
+		}
+		this.emit({
+			type: ASH_EVENT_TYPES.TASK_COMPLETE,
+			path: "/",
+			data: {
+				success: result.success,
+				errorCode: result.error?.code,
+				model: typeof args.model === "string" ? args.model : void 0,
+				durationMs: result.usage?.durationMs,
+				callerBlockletId: ctx.context?.blockletId ?? void 0,
+				session
+			}
+		});
+		return result;
+	}
+	/**
+	* Handler for the test-only `__debug-runtime` action (Phase 3b). Returns a
+	* boolean/string projection of the injected `observabilityRuntime` so E2E
+	* tests can assert the capability reached `/dev/agent` — but it deliberately
+	* omits the `spaceResolver` handle itself (object capability must not leave
+	* the host). Outside `AFS_TEST_MODE` it refuses with `AFS_PERMISSION` so
+	* production never exposes runtime wiring.
+	*/
+	execDebugRuntime() {
+		if (!process.env.AFS_TEST_MODE) return {
+			success: false,
+			error: {
+				code: "AFS_PERMISSION",
+				message: "__debug-runtime is only available under AFS_TEST_MODE"
+			}
+		};
+		const rt = this.observabilityRuntime;
+		return {
+			success: true,
+			data: { observabilityRuntime: {
+				hasResolver: Boolean(rt?.spaceResolver),
+				anonymousInteractivePersistence: rt?.anonymousInteractivePersistence ?? null,
+				ownershipRoutingMode: rt?.ownershipRoutingMode ?? "observe-only"
+			} }
+		};
+	}
+};
+__decorate([Stat("/")], AFSAgent.prototype, "statRoot", null);
+__decorate([Stat("/.actions/run")], AFSAgent.prototype, "statRunAction", null);
+__decorate([Actions("/")], AFSAgent.prototype, "listRootActions", null);
+__decorate([Actions.Exec("/", void 0, void 0, { effect: "write" })], AFSAgent.prototype, "execRootAction", null);
+
+//#endregion
+//#region src/scratchpad.ts
+/**
+* Scratchpad provisioning — allocates per-run scratch directories under
+* a session-scoped memory path.
+*
+* Provider internal: direct fs calls are allowed here (see CLAUDE.md).
+*/
+function validatePathComponent(value, label) {
+	if (typeof value !== "string" || value.length === 0) throw new TypeError(`${label} must be a non-empty string`);
+	if (value.includes("..")) throw new Error(`path traversal disallowed in ${label}`);
+	if (value.includes("\0")) throw new Error(`null byte disallowed in ${label}`);
+}
+function allocateScratch(memoryBasePath, session, runId) {
+	validatePathComponent(session, "session");
+	validatePathComponent(runId, "runId");
+	const basePath = join(memoryBasePath, "runs", session, "subruns", runId);
+	mkdirSync(basePath, { recursive: true });
+	const layout = {
+		basePath,
+		stateYml: join(basePath, "state.yml"),
+		messagesJsonl: join(basePath, "messages.jsonl"),
+		eventsJsonl: join(basePath, "events.jsonl"),
+		historyJsonl: join(basePath, "history.jsonl")
+	};
+	if (!existsSync(layout.stateYml)) writeFileSync(layout.stateYml, "");
+	if (!existsSync(layout.messagesJsonl)) writeFileSync(layout.messagesJsonl, "");
+	if (!existsSync(layout.eventsJsonl)) writeFileSync(layout.eventsJsonl, "");
+	if (!existsSync(layout.historyJsonl)) writeFileSync(layout.historyJsonl, "");
+	return layout;
+}
+function getStateProxy(layout) {
+	const raw = readFileSync(layout.stateYml, "utf8").trim();
+	if (!raw) return Object.freeze({});
+	let parsed;
+	try {
+		parsed = load(raw);
+	} catch {
+		return Object.freeze({});
+	}
+	if (parsed === null || parsed === void 0 || typeof parsed !== "object") return Object.freeze({});
+	return deepFreeze(parsed);
+}
+function deepFreeze(obj) {
+	for (const value of Object.values(obj)) if (value && typeof value === "object" && !Object.isFrozen(value)) deepFreeze(value);
+	return Object.freeze(obj);
+}
+function teardownSession(memoryBasePath, session, retention = "session") {
+	if (retention === "forever") return;
+	const sessionSubrunsDir = join(memoryBasePath, "runs", session, "subruns");
+	if (!existsSync(sessionSubrunsDir)) return;
+	if (retention === "session") {
+		rmSync(sessionSubrunsDir, {
+			recursive: true,
+			force: true
+		});
+		const sessionDir = join(memoryBasePath, "runs", session);
+		try {
+			rmSync(sessionDir, {
+				recursive: true,
+				force: true
+			});
+		} catch {}
+	}
+}
+
+//#endregion
+export { AFSAgent, allocateScratch, appendMessage, buildContext, buildToolSchema, checkSpawnDepth, computeLLMRetryDelayMs, createSessionQueue, deriveChildSession, estimateMessagesTokens, estimateTokens, executeAgentRun, generateAsh, getStateProxy, maybeCompress, normalizeToolCallsToAIGNE, readMessages, resetSeqCounter, resolveAgentModelPath, runAgentLoop, teardownSession };
+//# sourceMappingURL=index.mjs.map