@aigne/agent-runtime 1.12.0-beta.5

package/LICENSE.md

@@ -0,0 +1,26 @@
+# Proprietary License
+
+Copyright (c) 2024-2025 ArcBlock, Inc. All Rights Reserved.
+
+This software and associated documentation files (the "Software") are proprietary
+and confidential. Unauthorized copying, modification, distribution, or use of
+this Software, via any medium, is strictly prohibited.
+
+The Software is provided for internal use only within ArcBlock, Inc. and its
+authorized affiliates.
+
+## No License Granted
+
+No license, express or implied, is granted to any party for any purpose.
+All rights are reserved by ArcBlock, Inc.
+
+## Public Artifact Distribution
+
+Portions of this Software may be released publicly under separate open-source
+licenses (such as MIT License) through designated public repositories. Such
+public releases are governed by their respective licenses and do not affect
+the proprietary nature of this repository.
+
+## Contact
+
+For licensing inquiries, contact: legal@arcblock.io

package/README.md

@@ -0,0 +1,79 @@
+# @aigne/agent-runtime
+
+Agent dispatch and runner layer for the AFS stack. Extracted from `@aigne/arc-cli` so the same runtime can back non-Node hosts (Cloudflare Workers, future edge runtimes) without pulling in the CLI shell.
+
+## What this package owns
+
+Every agent execution path:
+
+| Agent type | What it does | Entry point |
+|------------|--------------|-------------|
+| `ai` | LLM inference + tool loop | `runAIAgent` |
+| `ash` | Agentic Shell DSL (plan → execute) | `runAshAgent` |
+| `team` | Sequential / parallel / reflection / iterate modes | `runTeamAgent` |
+| `orchestrator` | Planner → worker → completer multi-round loop | `runOrchestratorAgent` |
+
+Plus the cross-cutting machinery those runners share:
+
+- **Budget** (`BudgetTracker`, `resolveBudget`, rounds + tokens hard caps)
+- **Hooks** (`HookDispatcher`, `HookChannel`, skill-start / skill-end / tool-start / tool-end events)
+- **Memory binding** (`resolveMemoryBinding` — exposes `/modules/memory/.actions/*` as LLM tools)
+- **Scratchpad** (`provisionScratchViaAFS` — per-run scratch directory under `/modules/memory/`)
+- **Guide rails** (`runGuideRails` — pre-run validation)
+- **Stream router** (`onChunk` handling for UI-visible AI streams)
+- **Messaging** (`handlePostMessage`, `handleReadMessages` — `/proc/messaging/tools/*` tools, backed by `/proc/messaging/agents/<id>/msg/`)
+- **Result contract** (`_meta.env`, `_meta.scratchPath` sanitization; sub-agent envelope stripping)
+- **Session hierarchy** (spawn-depth gating + child session derivation)
+
+## How it fits in
+
+```
+┌─────────────────────────────────┐
+│  @aigne/arc-cli (Node CLI)      │
+│  - blocklet-manager             │
+│  - daemon                       │
+│  - messaging-provider           │
+└──────────────┬──────────────────┘
+               │ registerAgentActions / registerAgentSubscribes
+               ▼
+┌─────────────────────────────────┐
+│  @aigne/agent-runtime           │
+│  - agent-runners/*              │
+│  - program/                     │
+│    · agent-action               │
+│    · agent-subscribe            │
+│    · agent-tools                │
+│    · agent-runner-registry      │
+│    · result-contract            │
+└──────────────┬──────────────────┘
+               │ afs.read / afs.write / afs.exec
+               ▼
+         ┌───────────┐
+         │ @aigne/afs│
+         └───────────┘
+```
+
+Consumers wire it up through:
+
+```typescript
+import { registerAgentActions, registerAgentSubscribes } from "@aigne/agent-runtime";
+
+registerAgentActions({ afs, manifest, /* ... */ });
+registerAgentSubscribes({ afs, manifest, /* ... */ });
+```
+
+Runner-level helpers (`runAIAgent`, `runAshAgent`, ...) are exported too, for tests and tooling that need to bypass dispatch.
+
+## Principles
+
+1. **AFS-Only I/O** — every read / write / exec goes through `@aigne/afs`. No direct filesystem or network calls.
+2. **Runtime-agnostic** — no Node-specific imports. Runs under Bun, Node, and workerd.
+3. **Deterministic** — all state (budget, scratch, hooks) is derived from the AFS path; nothing lives in process memory past a single agent invocation.
+
+## Scripts
+
+```bash
+pnpm build          # tsdown bundle (ESM + CJS + dts)
+pnpm check-types    # tsc --noEmit
+pnpm test           # bun test (tests live under test/)
+```

package/dist/agent-runners/ai-runner.cjs

@@ -0,0 +1,133 @@
+const require_agent_tools = require('../program/agent-tools.cjs');
+const require_budget = require('./budget.cjs');
+const require_memory_archive = require('./memory-archive.cjs');
+const require_template_context = require('./template-context.cjs');
+let _aigne_afs_agent = require("@aigne/afs-agent");
+let ufo = require("ufo");
+
+//#region src/agent-runners/ai-runner.ts
+const TEMPLATE_MODULE = "@aigne/ash/src/prompt/template.ts";
+async function loadRenderTemplate() {
+	return (await import(TEMPLATE_MODULE)).renderTemplate;
+}
+async function runAIAgent(opts) {
+	const { afs, manifest, input, session, parentSession, chain, parentAgentInfo, mountPath, memoryBasePath } = opts;
+	const inputKey = manifest.inputKey ?? "message";
+	manifest.outputKey;
+	const task = String(input[inputKey] ?? "");
+	const runId = crypto.randomUUID();
+	const scratch = manifest.scratch && memoryBasePath && session ? (0, _aigne_afs_agent.allocateScratch)(memoryBasePath, session, runId) : null;
+	try {
+		const tools = (manifest.tools ?? []).map((t) => {
+			if (typeof t === "string") return t;
+			return t;
+		});
+		let catalogResult = null;
+		if (tools.length > 0) catalogResult = await require_agent_tools.compileToolCatalog(afs, {
+			tools,
+			blockletRoot: mountPath,
+			skillPaths: manifest.skillPaths,
+			mountPath
+		});
+		let instructionsTemplate = "";
+		if (manifest.instructions) {
+			const candidates = [(0, ufo.joinURL)(mountPath, manifest.instructions), (0, ufo.joinURL)("/packages", manifest.instructions)];
+			let lastTried = candidates[0];
+			let found = false;
+			for (const candidate of candidates) {
+				lastTried = candidate;
+				try {
+					const readResult = await afs.read(candidate);
+					instructionsTemplate = typeof readResult === "string" ? readResult : (readResult?.data)?.content ?? String(readResult?.data ?? "");
+					if (instructionsTemplate) {
+						found = true;
+						break;
+					}
+				} catch {}
+			}
+			if (!found) throw new Error(`INSTRUCTIONS_NOT_FOUND: cannot read "${manifest.instructions}" at ${lastTried}`);
+		}
+		const templateCtx = require_template_context.buildTemplateContext({
+			input,
+			manifest,
+			session,
+			parentInfo: parentAgentInfo ?? null,
+			envWhitelist: manifest.envVars,
+			scratch,
+			catalogResult
+		});
+		let renderedSystem;
+		if (instructionsTemplate) renderedSystem = await (await loadRenderTemplate())(instructionsTemplate, templateCtx, {
+			blockletRoot: mountPath,
+			afs
+		});
+		if (opts.systemAppend) renderedSystem = renderedSystem ? `${renderedSystem}\n\n${opts.systemAppend}` : opts.systemAppend;
+		else if (require_memory_archive.isHandoffReadThroughEnabled(manifest.memory)) {
+			const scopeDomain = afs?.scope?.memoryDomain;
+			const manifestDomain = manifest.memory && typeof manifest.memory === "object" ? manifest.memory.domain : void 0;
+			const domain = scopeDomain ?? manifestDomain;
+			if (domain) {
+				const appendix = require_memory_archive.formatRecallForPrompt(await require_memory_archive.recallForHandoff({
+					afs,
+					domain
+				}));
+				if (appendix) renderedSystem = renderedSystem ? `${renderedSystem}\n\n${appendix}` : appendix;
+			}
+		}
+		const model = typeof manifest.model === "string" ? manifest.model : manifest.model ? `${manifest.model.provider}/${manifest.model.name}` : "/dev/ai/.actions/chat";
+		const toolEntries = (manifest.tools ?? []).map((t) => {
+			if (typeof t === "string") return { path: t };
+			return t;
+		});
+		if (manifest.memory) {
+			if (!toolEntries.some((t) => t.path === "/memory/**" || t.path === "/memory" || t.path.startsWith("/memory/"))) toolEntries.push({
+				path: "/memory/**",
+				ops: [
+					"read",
+					"list",
+					"exec"
+				]
+			});
+		}
+		const resolved = require_budget.resolveBudget({ manifest: manifest.budget });
+		const tracker = require_budget.createBudgetTracker(resolved);
+		const execArgs = {
+			task,
+			model,
+			tools: toolEntries,
+			budget: {
+				max_rounds: resolved.maxRounds,
+				total_tokens: resolved.totalTokens
+			},
+			session: session ? `/instance/.sessions/agent/${session}` : void 0,
+			system: renderedSystem,
+			skill_paths: manifest.skillPaths,
+			_parent_session: parentSession,
+			_chain: [...chain ?? [], session ?? "root"],
+			_abort_signal: tracker.signal,
+			parentAgentInfo: parentAgentInfo ?? void 0
+		};
+		if (typeof input._ui_session === "string") execArgs._ui_session = input._ui_session;
+		const userProgress = input._on_tool_progress;
+		if (require_memory_archive.isMemoryArchiveEnabled(manifest.memory)) execArgs._on_tool_progress = require_memory_archive.wrapToolProgress(userProgress, {
+			afs,
+			session: session ?? "default"
+		});
+		else if (userProgress) execArgs._on_tool_progress = userProgress;
+		const result = await afs.exec("/dev/agent/.actions/run", execArgs, {});
+		const finalResult = {
+			success: result.success,
+			data: result.data
+		};
+		finalResult._meta = {
+			render: { template_vars: Object.keys(templateCtx) },
+			context: { system: renderedSystem ?? "" }
+		};
+		return finalResult;
+	} finally {
+		if (scratch && memoryBasePath && session) (0, _aigne_afs_agent.teardownSession)(memoryBasePath, session, manifest.scratchRetention ?? "session");
+	}
+}
+
+//#endregion
+exports.runAIAgent = runAIAgent;

package/dist/agent-runners/ai-runner.d.cts

@@ -0,0 +1,33 @@
+import { ParentAgentInfo } from "./template-context.cjs";
+import { AFSRoot, AgentManifest } from "@aigne/afs";
+
+//#region src/agent-runners/ai-runner.d.ts
+interface AIRunnerInput {
+  afs: AFSRoot;
+  manifest: AgentManifest;
+  input: Record<string, unknown>;
+  session?: string;
+  parentSession?: string;
+  chain?: string[];
+  parentAgentInfo?: ParentAgentInfo;
+  mountPath: string;
+  memoryBasePath?: string;
+  systemAppend?: string;
+}
+interface AIRunnerResult {
+  success: boolean;
+  data?: Record<string, unknown>;
+  result?: Record<string, unknown>;
+  _meta?: {
+    render?: {
+      template_vars: string[];
+    };
+    context?: {
+      system: string;
+    };
+  };
+}
+declare function runAIAgent(opts: AIRunnerInput): Promise<AIRunnerResult>;
+//#endregion
+export { AIRunnerInput, AIRunnerResult, runAIAgent };
+//# sourceMappingURL=ai-runner.d.cts.map

package/dist/agent-runners/ai-runner.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-runner.d.cts","names":[],"sources":["../../src/agent-runners/ai-runner.ts"],"mappings":";;;;UAeiB,aAAA;EACf,GAAA,EAAK,OAAA;EACL,QAAA,EAAU,aAAA;EACV,KAAA,EAAO,MAAA;EACP,OAAA;EACA,aAAA;EACA,KAAA;EACA,eAAA,GAAkB,eAAA;EAClB,SAAA;EACA,cAAA;EACA,YAAA;AAAA;AAAA,UAGe,cAAA;EACf,OAAA;EACA,IAAA,GAAO,MAAA;EACP,MAAA,GAAS,MAAA;EACT,KAAA;IACE,MAAA;MAAW,aAAA;IAAA;IACX,OAAA;MAAY,MAAA;IAAA;EAAA;AAAA;AAAA,iBAiBM,UAAA,CAAW,IAAA,EAAM,aAAA,GAAgB,OAAA,CAAQ,cAAA"}

package/dist/agent-runners/ai-runner.d.mts

@@ -0,0 +1,33 @@
+import { ParentAgentInfo } from "./template-context.mjs";
+import { AFSRoot, AgentManifest } from "@aigne/afs";
+
+//#region src/agent-runners/ai-runner.d.ts
+interface AIRunnerInput {
+  afs: AFSRoot;
+  manifest: AgentManifest;
+  input: Record<string, unknown>;
+  session?: string;
+  parentSession?: string;
+  chain?: string[];
+  parentAgentInfo?: ParentAgentInfo;
+  mountPath: string;
+  memoryBasePath?: string;
+  systemAppend?: string;
+}
+interface AIRunnerResult {
+  success: boolean;
+  data?: Record<string, unknown>;
+  result?: Record<string, unknown>;
+  _meta?: {
+    render?: {
+      template_vars: string[];
+    };
+    context?: {
+      system: string;
+    };
+  };
+}
+declare function runAIAgent(opts: AIRunnerInput): Promise<AIRunnerResult>;
+//#endregion
+export { AIRunnerInput, AIRunnerResult, runAIAgent };
+//# sourceMappingURL=ai-runner.d.mts.map

package/dist/agent-runners/ai-runner.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-runner.d.mts","names":[],"sources":["../../src/agent-runners/ai-runner.ts"],"mappings":";;;;UAeiB,aAAA;EACf,GAAA,EAAK,OAAA;EACL,QAAA,EAAU,aAAA;EACV,KAAA,EAAO,MAAA;EACP,OAAA;EACA,aAAA;EACA,KAAA;EACA,eAAA,GAAkB,eAAA;EAClB,SAAA;EACA,cAAA;EACA,YAAA;AAAA;AAAA,UAGe,cAAA;EACf,OAAA;EACA,IAAA,GAAO,MAAA;EACP,MAAA,GAAS,MAAA;EACT,KAAA;IACE,MAAA;MAAW,aAAA;IAAA;IACX,OAAA;MAAY,MAAA;IAAA;EAAA;AAAA;AAAA,iBAiBM,UAAA,CAAW,IAAA,EAAM,aAAA,GAAgB,OAAA,CAAQ,cAAA"}

package/dist/agent-runners/ai-runner.mjs

@@ -0,0 +1,134 @@
+import { compileToolCatalog } from "../program/agent-tools.mjs";
+import { createBudgetTracker, resolveBudget } from "./budget.mjs";
+import { formatRecallForPrompt, isHandoffReadThroughEnabled, isMemoryArchiveEnabled, recallForHandoff, wrapToolProgress } from "./memory-archive.mjs";
+import { buildTemplateContext } from "./template-context.mjs";
+import { allocateScratch, teardownSession } from "@aigne/afs-agent";
+import { joinURL } from "ufo";
+
+//#region src/agent-runners/ai-runner.ts
+const TEMPLATE_MODULE = "@aigne/ash/src/prompt/template.ts";
+async function loadRenderTemplate() {
+	return (await import(TEMPLATE_MODULE)).renderTemplate;
+}
+async function runAIAgent(opts) {
+	const { afs, manifest, input, session, parentSession, chain, parentAgentInfo, mountPath, memoryBasePath } = opts;
+	const inputKey = manifest.inputKey ?? "message";
+	manifest.outputKey;
+	const task = String(input[inputKey] ?? "");
+	const runId = crypto.randomUUID();
+	const scratch = manifest.scratch && memoryBasePath && session ? allocateScratch(memoryBasePath, session, runId) : null;
+	try {
+		const tools = (manifest.tools ?? []).map((t) => {
+			if (typeof t === "string") return t;
+			return t;
+		});
+		let catalogResult = null;
+		if (tools.length > 0) catalogResult = await compileToolCatalog(afs, {
+			tools,
+			blockletRoot: mountPath,
+			skillPaths: manifest.skillPaths,
+			mountPath
+		});
+		let instructionsTemplate = "";
+		if (manifest.instructions) {
+			const candidates = [joinURL(mountPath, manifest.instructions), joinURL("/packages", manifest.instructions)];
+			let lastTried = candidates[0];
+			let found = false;
+			for (const candidate of candidates) {
+				lastTried = candidate;
+				try {
+					const readResult = await afs.read(candidate);
+					instructionsTemplate = typeof readResult === "string" ? readResult : (readResult?.data)?.content ?? String(readResult?.data ?? "");
+					if (instructionsTemplate) {
+						found = true;
+						break;
+					}
+				} catch {}
+			}
+			if (!found) throw new Error(`INSTRUCTIONS_NOT_FOUND: cannot read "${manifest.instructions}" at ${lastTried}`);
+		}
+		const templateCtx = buildTemplateContext({
+			input,
+			manifest,
+			session,
+			parentInfo: parentAgentInfo ?? null,
+			envWhitelist: manifest.envVars,
+			scratch,
+			catalogResult
+		});
+		let renderedSystem;
+		if (instructionsTemplate) renderedSystem = await (await loadRenderTemplate())(instructionsTemplate, templateCtx, {
+			blockletRoot: mountPath,
+			afs
+		});
+		if (opts.systemAppend) renderedSystem = renderedSystem ? `${renderedSystem}\n\n${opts.systemAppend}` : opts.systemAppend;
+		else if (isHandoffReadThroughEnabled(manifest.memory)) {
+			const scopeDomain = afs?.scope?.memoryDomain;
+			const manifestDomain = manifest.memory && typeof manifest.memory === "object" ? manifest.memory.domain : void 0;
+			const domain = scopeDomain ?? manifestDomain;
+			if (domain) {
+				const appendix = formatRecallForPrompt(await recallForHandoff({
+					afs,
+					domain
+				}));
+				if (appendix) renderedSystem = renderedSystem ? `${renderedSystem}\n\n${appendix}` : appendix;
+			}
+		}
+		const model = typeof manifest.model === "string" ? manifest.model : manifest.model ? `${manifest.model.provider}/${manifest.model.name}` : "/dev/ai/.actions/chat";
+		const toolEntries = (manifest.tools ?? []).map((t) => {
+			if (typeof t === "string") return { path: t };
+			return t;
+		});
+		if (manifest.memory) {
+			if (!toolEntries.some((t) => t.path === "/memory/**" || t.path === "/memory" || t.path.startsWith("/memory/"))) toolEntries.push({
+				path: "/memory/**",
+				ops: [
+					"read",
+					"list",
+					"exec"
+				]
+			});
+		}
+		const resolved = resolveBudget({ manifest: manifest.budget });
+		const tracker = createBudgetTracker(resolved);
+		const execArgs = {
+			task,
+			model,
+			tools: toolEntries,
+			budget: {
+				max_rounds: resolved.maxRounds,
+				total_tokens: resolved.totalTokens
+			},
+			session: session ? `/instance/.sessions/agent/${session}` : void 0,
+			system: renderedSystem,
+			skill_paths: manifest.skillPaths,
+			_parent_session: parentSession,
+			_chain: [...chain ?? [], session ?? "root"],
+			_abort_signal: tracker.signal,
+			parentAgentInfo: parentAgentInfo ?? void 0
+		};
+		if (typeof input._ui_session === "string") execArgs._ui_session = input._ui_session;
+		const userProgress = input._on_tool_progress;
+		if (isMemoryArchiveEnabled(manifest.memory)) execArgs._on_tool_progress = wrapToolProgress(userProgress, {
+			afs,
+			session: session ?? "default"
+		});
+		else if (userProgress) execArgs._on_tool_progress = userProgress;
+		const result = await afs.exec("/dev/agent/.actions/run", execArgs, {});
+		const finalResult = {
+			success: result.success,
+			data: result.data
+		};
+		finalResult._meta = {
+			render: { template_vars: Object.keys(templateCtx) },
+			context: { system: renderedSystem ?? "" }
+		};
+		return finalResult;
+	} finally {
+		if (scratch && memoryBasePath && session) teardownSession(memoryBasePath, session, manifest.scratchRetention ?? "session");
+	}
+}
+
+//#endregion
+export { runAIAgent };
+//# sourceMappingURL=ai-runner.mjs.map

package/dist/agent-runners/ai-runner.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-runner.mjs","names":[],"sources":["../../src/agent-runners/ai-runner.ts"],"sourcesContent":["import type { AFSRoot, AgentManifest } from \"@aigne/afs\";\nimport { allocateScratch, teardownSession } from \"@aigne/afs-agent\";\nimport { joinURL } from \"ufo\";\nimport { type CatalogResult, compileToolCatalog } from \"../program/agent-tools.js\";\nimport { createBudgetTracker, resolveBudget } from \"./budget.js\";\nimport {\n  formatRecallForPrompt,\n  isHandoffReadThroughEnabled,\n  isMemoryArchiveEnabled,\n  recallForHandoff,\n  type ToolProgressEvent,\n  wrapToolProgress,\n} from \"./memory-archive.js\";\nimport { buildTemplateContext, type ParentAgentInfo } from \"./template-context.js\";\n\nexport interface AIRunnerInput {\n  afs: AFSRoot;\n  manifest: AgentManifest;\n  input: Record<string, unknown>;\n  session?: string;\n  parentSession?: string;\n  chain?: string[];\n  parentAgentInfo?: ParentAgentInfo;\n  mountPath: string;\n  memoryBasePath?: string;\n  systemAppend?: string;\n}\n\nexport interface AIRunnerResult {\n  success: boolean;\n  data?: Record<string, unknown>;\n  result?: Record<string, unknown>;\n  _meta?: {\n    render?: { template_vars: string[] };\n    context?: { system: string };\n  };\n}\n\nconst TEMPLATE_MODULE = \"@aigne/ash/src/prompt/template.ts\";\n\nasync function loadRenderTemplate(): Promise<\n  (\n    template: string,\n    vars: Record<string, unknown>,\n    opts?: { blockletRoot?: string; afs?: any },\n  ) => Promise<string>\n> {\n  const mod = await import(TEMPLATE_MODULE);\n  return mod.renderTemplate;\n}\n\nexport async function runAIAgent(opts: AIRunnerInput): Promise<AIRunnerResult> {\n  const {\n    afs,\n    manifest,\n    input,\n    session,\n    parentSession,\n    chain,\n    parentAgentInfo,\n    mountPath,\n    memoryBasePath,\n  } = opts;\n\n  const inputKey = manifest.inputKey ?? \"message\";\n  const _outputKey = manifest.outputKey;\n  const task = String(input[inputKey] ?? \"\");\n\n  const runId = crypto.randomUUID();\n  const scratch =\n    manifest.scratch && memoryBasePath && session\n      ? allocateScratch(memoryBasePath, session, runId)\n      : null;\n\n  try {\n    const tools = (manifest.tools ?? []).map((t) => {\n      if (typeof t === \"string\") return t;\n      return t;\n    });\n\n    let catalogResult: CatalogResult | null = null;\n    if (tools.length > 0) {\n      catalogResult = await compileToolCatalog(afs as any, {\n        tools,\n        blockletRoot: mountPath,\n        skillPaths: manifest.skillPaths,\n        mountPath,\n      });\n    }\n\n    let instructionsTemplate = \"\";\n    if (manifest.instructions) {\n      // B12: Runtime AFS projects the blocklet directory at /packages; the\n      // external mountPath isn't a valid internal path after activation.\n      // Try mountPath first (works in tests + pre-activation), fall back to\n      // /packages (production post-activation).\n      const candidates = [\n        joinURL(mountPath, manifest.instructions),\n        joinURL(\"/packages\", manifest.instructions),\n      ];\n      let lastTried = candidates[0]!;\n      let found = false;\n      for (const candidate of candidates) {\n        lastTried = candidate;\n        try {\n          const readResult = await afs.read!(candidate);\n          instructionsTemplate =\n            typeof readResult === \"string\"\n              ? readResult\n              : ((readResult?.data as any)?.content ?? String(readResult?.data ?? \"\"));\n          if (instructionsTemplate) {\n            found = true;\n            break;\n          }\n        } catch {\n          // Try next candidate\n        }\n      }\n      if (!found) {\n        throw new Error(\n          `INSTRUCTIONS_NOT_FOUND: cannot read \"${manifest.instructions}\" at ${lastTried}`,\n        );\n      }\n    }\n\n    const templateCtx = buildTemplateContext({\n      input,\n      manifest,\n      session,\n      parentInfo: parentAgentInfo ?? null,\n      envWhitelist: manifest.envVars,\n      scratch,\n      catalogResult,\n    });\n\n    let renderedSystem: string | undefined;\n    if (instructionsTemplate) {\n      const renderTemplate = await loadRenderTemplate();\n      renderedSystem = await renderTemplate(\n        instructionsTemplate,\n        templateCtx as unknown as Record<string, unknown>,\n        { blockletRoot: mountPath, afs: afs as any },\n      );\n    }\n\n    if (opts.systemAppend) {\n      renderedSystem = renderedSystem\n        ? `${renderedSystem}\\n\\n${opts.systemAppend}`\n        : opts.systemAppend;\n    } else if (isHandoffReadThroughEnabled(manifest.memory)) {\n      // Top-level single-agent recall. When `opts.systemAppend` is unset,\n      // there's no parent team that already paid the recall cost — this\n      // run owns the read-through. The team-runner does the same step at\n      // its own layer (see `team-runner.ts:230`); doing it here closes\n      // the gap so a `type: ai` agent with `memory.handoffReadThrough` can\n      // surface prior observations across sessions without needing a\n      // dummy team wrapper.\n      const scopeDomain = (afs as { scope?: { memoryDomain?: string } } | undefined)?.scope\n        ?.memoryDomain;\n      const manifestDomain =\n        manifest.memory && typeof manifest.memory === \"object\"\n          ? (manifest.memory as { domain?: string }).domain\n          : undefined;\n      const domain = scopeDomain ?? manifestDomain;\n      if (domain) {\n        const recalled = await recallForHandoff({ afs, domain });\n        const appendix = formatRecallForPrompt(recalled);\n        if (appendix) {\n          renderedSystem = renderedSystem ? `${renderedSystem}\\n\\n${appendix}` : appendix;\n        }\n      }\n    }\n\n    const model =\n      typeof manifest.model === \"string\"\n        ? manifest.model\n        : manifest.model\n          ? `${manifest.model.provider}/${manifest.model.name}`\n          : \"/dev/ai/.actions/chat\";\n\n    const toolEntries = (manifest.tools ?? []).map((t) => {\n      if (typeof t === \"string\") return { path: t };\n      return t;\n    });\n\n    // AFS conformance: top-level AI agents with `manifest.memory` enabled\n    // get standard read/list/exec on `/memory/**` so the agent can both\n    // observe (`afs_list /memory/<domain>`) and operate (`recall`,\n    // `remember`) the memory store. For child scopes, `projectForChild`\n    // (scoped-afs.ts → ensureMemoryTool) does the same.\n    if (manifest.memory) {\n      const hasMemoryTool = toolEntries.some(\n        (t: { path: string }) =>\n          t.path === \"/memory/**\" || t.path === \"/memory\" || t.path.startsWith(\"/memory/\"),\n      );\n      if (!hasMemoryTool) {\n        toolEntries.push({ path: \"/memory/**\", ops: [\"read\", \"list\", \"exec\"] });\n      }\n    }\n\n    const resolved = resolveBudget({ manifest: manifest.budget });\n    const tracker = createBudgetTracker(resolved);\n\n    const execArgs: Record<string, unknown> = {\n      task,\n      model,\n      tools: toolEntries,\n      budget: {\n        max_rounds: resolved.maxRounds,\n        total_tokens: resolved.totalTokens,\n      },\n      session: session ? `/instance/.sessions/agent/${session}` : undefined,\n      system: renderedSystem,\n      skill_paths: manifest.skillPaths,\n      _parent_session: parentSession,\n      _chain: [...(chain ?? []), session ?? \"root\"],\n      _abort_signal: tracker.signal,\n      parentAgentInfo: parentAgentInfo ?? undefined,\n    };\n\n    // Forward the UI surface id (ask_user routing) — `session` above is the\n    // agent's history session, distinct from the originating UI sessionId.\n    if (typeof input._ui_session === \"string\") {\n      execArgs._ui_session = input._ui_session;\n    }\n\n    const userProgress = input._on_tool_progress as\n      | ((event: ToolProgressEvent) => void)\n      | undefined;\n    if (isMemoryArchiveEnabled(manifest.memory)) {\n      execArgs._on_tool_progress = wrapToolProgress(userProgress, {\n        afs,\n        session: session ?? \"default\",\n      });\n    } else if (userProgress) {\n      execArgs._on_tool_progress = userProgress;\n    }\n\n    const result = (await afs.exec!(\"/dev/agent/.actions/run\", execArgs, {})) as any;\n\n    const finalResult: AIRunnerResult = {\n      success: result.success,\n      data: result.data,\n    };\n\n    finalResult._meta = {\n      render: {\n        template_vars: Object.keys(templateCtx),\n      },\n      context: {\n        system: renderedSystem ?? \"\",\n      },\n    };\n\n    return finalResult;\n  } finally {\n    if (scratch && memoryBasePath && session) {\n      const retention = (manifest as any).scratchRetention ?? \"session\";\n      teardownSession(memoryBasePath, session, retention);\n    }\n  }\n}\n"],"mappings":"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"}