@xopcai/xopc 0.0.308 → 0.0.311

package/dist/src/agent/tools/delegation-policy.js

@@ -0,0 +1,93 @@
+//#region src/agent/tools/delegation-policy.ts
+const DELEGATION_CAPABILITIES = [
+	"local_read",
+	"web_read",
+	"knowledge_read",
+	"skills_read",
+	"external_read",
+	"local_write",
+	"command",
+	"browser"
+];
+/** Host-owned classifications. New tools fail closed until classified. */
+const DELEGATION_TOOL_CAPABILITIES = {
+	read_file: "local_read",
+	grep: "local_read",
+	find: "local_read",
+	list_dir: "local_read",
+	review_workspace: "local_read",
+	read_media: "local_read",
+	image: "local_read",
+	tool_manual: "local_read",
+	web_search: "web_read",
+	web_fetch: "web_read",
+	web_extract: "web_read",
+	knowledge_search: "knowledge_read",
+	knowledge_get: "knowledge_read",
+	session_search: "knowledge_read",
+	session_recall: "knowledge_read",
+	user_context_search: "knowledge_read",
+	user_context_get: "knowledge_read",
+	skills_list: "skills_read",
+	skill_view: "skills_read",
+	skills_marketplace_search: "skills_read",
+	xopc_tool_search: "external_read",
+	xopc_tool_describe: "external_read",
+	xopc_tool_execute: "external_read",
+	write_file: "local_write",
+	apply_patch: "local_write",
+	exec_command: "command",
+	language_diagnostics: "command",
+	browser_use: "browser"
+};
+const RESEARCH = [
+	"local_read",
+	"web_read",
+	"knowledge_read",
+	"skills_read",
+	"external_read"
+];
+function delegationCapabilities(mode, requested) {
+	const ceiling = mode === "implement" ? [
+		...RESEARCH,
+		"local_write",
+		"command",
+		"browser"
+	] : mode === "custom" ? [...RESEARCH, "browser"] : mode === "research" ? RESEARCH : ["local_read"];
+	const defaults = mode === "implement" ? ceiling.filter((capability) => capability !== "browser") : mode === "custom" ? [] : ceiling;
+	return new Set((requested ?? defaults).filter((capability) => ceiling.includes(capability)));
+}
+function resolveDelegationTools(parentNames, mode, requested, capabilities) {
+	const parent = new Set(parentNames);
+	const allowed = delegationCapabilities(mode, capabilities);
+	const granted = [];
+	const rejected = [];
+	for (const tool of new Set((requested ?? parentNames).map((name) => name.trim()).filter(Boolean))) {
+		const capability = DELEGATION_TOOL_CAPABILITIES[tool];
+		const reason = !parent.has(tool) ? "Unavailable to the parent agent" : !capability ? "Tool has no delegable capability" : !allowed.has(capability) ? `Capability ${capability} is outside this delegation` : void 0;
+		if (reason) {
+			if (requested) rejected.push({
+				tool,
+				reason
+			});
+		} else granted.push(tool);
+	}
+	return {
+		granted,
+		rejected
+	};
+}
+/** Always enforce the external read contract, even when the child explicitly sends readOnly:false. */
+function protectDelegatedTool(tool) {
+	if (tool.name !== "xopc_tool_execute") return tool;
+	return {
+		...tool,
+		execute: (id, args, signal, onUpdate) => tool.execute(id, {
+			...args,
+			readOnly: true,
+			approvalId: void 0
+		}, signal, onUpdate)
+	};
+}
+//#endregion
+export { DELEGATION_CAPABILITIES, DELEGATION_TOOL_CAPABILITIES, delegationCapabilities, protectDelegatedTool, resolveDelegationTools };

package/dist/src/agent/tools/factory.d.ts

@@ -1,3 +1,4 @@
+import type { SceneAccess } from '../../scenes/httpServices.js';
 /**
  * Agent Tools Factory - Creates and configures agent tools
  *
@@ -54,6 +55,7 @@ export interface ToolFactoryDeps {
     };
     /** Gateway: enables the `automation` tool. */
     getAutomationService?: () => AutomationService | undefined;
+    getSceneAccess?: () => SceneAccess | undefined;
     getBrowserAutomationService?: () => BrowserAutomationService | undefined;
     emitBrowserEvent?: (type: string, payload: unknown) => void;
     /** Gateway: enables the `xopc_use` product-object tool. */
@@ -83,6 +85,8 @@ export interface ToolFactoryDeps {
     installSkillFromMarketplace?: (opts: MarketplaceSkillInstallToolOptions) => Promise<MarketplaceSkillInstallToolResult>;
 }
 export interface CreateCoreToolsOptions {
+    getParentTools?: () => AgentTool<any, any>[];
+    createDelegationPolicy?: () => import('../orchestration/agent-turn-policy.js').AgentTurnPolicy;
     /** Workspace root for file/command tools (defaults to factory workspace). */
     workspace?: string;
     /** Canonical `agents/<id>/profile/`: bare SOUL.md / IDENTITY.md resolve here after the workspace. */

package/dist/src/agent/tools/factory.js

@@ -3,7 +3,7 @@ import { createLogger } from "../../utils/logger/index.js";
 import { init_logger } from "../../utils/logger.js";
 import { isXopcDatabaseOpen } from "../../storage/sqlite/connection.js";
 import { getBrowserTabBinding } from "../../storage/sqlite/browser-tab-binding-repository.js";
-import { getSessionMetadata } from "../../storage/sqlite/session-repository.js";
+import { getSessionMetadata } from "../../storage/sqlite/session-read-repository.js";
 import { getSessionTaskPlan, setSessionTaskPlan } from "../../storage/sqlite/session-task-plan-repository.js";
 import "../../storage/sqlite/index.js";
 import { init_agent_scope, resolveDefaultAgentId } from "../agent-scope.js";
@@ -15,6 +15,7 @@ import { EXTERNAL_TOOL_NAMES } from "../external-tools/gateway-tools.js";
 import { buildRuntimeEnvironment } from "../../runtime-tools/environment.js";
 import { createDefaultExternalToolGatewayTools } from "../external-tools/index.js";
 import { createReadFileTool } from "./read.js";
+import { createDataBatchTool } from "./dataBatch.js";
 import { skillEnvironmentId } from "../skills/installer.js";
 import { createWriteFileTool } from "./write.js";
 import { createListDirTool } from "./list-dir.js";
@@ -64,6 +65,7 @@ import { ComputerRuntime } from "../../computer/runtime.js";
 import { createComputerUseTool } from "./computer-use-tool.js";
 import { createReviewWorkspaceTool } from "./review-workspace.js";
 import { createLanguageDiagnosticsTool } from "./language-diagnostics.js";
+import { createDelegationParentPolicy } from "./delegation-parent-policy.js";
 import { createWorkflowCatalog } from "../workflow/catalog.js";
 import { mergeTtsConfigFromAppConfig } from "../../voice/tts/merge-config.js";
 import { createTextToSpeechTool } from "./tts-tool.js";
@@ -256,7 +258,7 @@ var AgentToolsFactory = class AgentToolsFactory {
 		const listDir = createListDirTool(workspace);
 		const grep = createGrepTool(workspace);
 		const find = createFindTool(workspace);
-		return filterToolsByDisabledSet([
+		const core = [
 			createSessionStatusTool(),
 			createMemoryMaintenanceTool({ getConfig: () => this.deps.getConfig?.() }),
 			createToolManualTool(),
@@ -423,12 +425,13 @@ var AgentToolsFactory = class AgentToolsFactory {
 			})] : [],
 			...this.deps.getAutomationService ? [createAutomationTool({ getAutomationService: this.deps.getAutomationService })] : [],
 			...browserEnabled && this.deps.getBrowserAutomationService ? [createBrowserAutomationTool({ getBrowserAutomationService: this.deps.getBrowserAutomationService })] : [],
-			...this.deps.getAutomationService || this.deps.getProjectService || this.deps.getNotesService || this.deps.getLocalAppService || this.deps.dispatchTaskEvents || this.deps.dispatchTaskRuns ? [createXopcUseTool({
+			...this.deps.getAutomationService || this.deps.getSceneAccess || this.deps.getProjectService || this.deps.getNotesService || this.deps.getLocalAppService || this.deps.dispatchTaskEvents || this.deps.dispatchTaskRuns ? [createXopcUseTool({
 				getWorkspace: () => this.deps.workspace,
 				getConfig: () => this.deps.getConfig?.(),
 				getCurrentAgentId: () => options.agentId,
 				getCurrentConversationId: () => this.deps.getCurrentContext()?.conversationId,
 				getAutomationService: this.deps.getAutomationService,
+				getSceneAccess: this.deps.getSceneAccess,
 				getNotesService: this.deps.getNotesService,
 				getProjectService: this.deps.getProjectService,
 				getLocalAppService: this.deps.getLocalAppService,
@@ -461,6 +464,12 @@ var AgentToolsFactory = class AgentToolsFactory {
 			})] : [],
 			...primary ? [createDelegateTool({
 				workspace,
+				getParentTools: () => options?.getParentTools?.() ?? filterToolsByDisabledSet(core, disabled),
+				createParentPolicy: options?.createDelegationPolicy ?? (() => createDelegationParentPolicy({
+					getConfig: () => this.deps.getConfig?.(),
+					conversationId: currentConversationId(),
+					agentId: resolvedAgentId
+				})),
 				getSubagentModel: () => {
 					const m = (options?.getPrimaryModel ?? this.deps.getPrimaryModel)?.();
 					if (!m) throw new Error("No primary model configured for delegate_task");
@@ -468,7 +477,14 @@ var AgentToolsFactory = class AgentToolsFactory {
 				},
 				bus: this.deps.bus,
 				getConfig: () => this.deps.getConfig?.(),
-				getCurrentContext: () => this.deps.getCurrentContext?.() ?? null,
+				getCurrentContext: () => {
+					const context = this.deps.getCurrentContext?.();
+					const conversationId = currentConversationId();
+					return conversationId ? {
+						...context,
+						conversationId
+					} : context ?? null;
+				},
 				toolExecutorConfig: this.deps.toolExecutorConfig,
 				buildChildTools: (childOpts) => {
 					return new AgentToolsFactory({
@@ -485,6 +501,7 @@ var AgentToolsFactory = class AgentToolsFactory {
 						agentId: options?.agentId ?? childOpts.agentId,
 						conversationId: childOpts.browserConversationId,
 						disabledTools: new Set([
+							...disabled ?? [],
 							EXTERNAL_TOOL_NAMES.search,
 							EXTERNAL_TOOL_NAMES.describe,
 							EXTERNAL_TOOL_NAMES.execute,
@@ -495,7 +512,30 @@ var AgentToolsFactory = class AgentToolsFactory {
 				}
 			})] : [],
 			...optionalTools
-		], disabled);
+		];
+		if ([
+			"read_file",
+			"grep",
+			"exec_command",
+			"knowledge_search",
+			"knowledge_get",
+			"web_search",
+			"web_fetch",
+			"xopc_tool_execute"
+		].some((name) => !disabled?.has(name))) {
+			const dataTools = () => {
+				const config = this.deps.getConfig?.();
+				const policies = config ? (currentConversationId() ? resolveEffectiveAgentConfigForSession(config, currentConversationId()) : resolveEffectiveAgentConfigForAgent(config, resolvedAgentId)).config.tools : void 0;
+				if (policies?.data_batch?.mode === "deny") return [];
+				return filterToolsByDisabledSet(core, disabled).filter((tool) => policies?.[tool.name]?.mode !== "deny");
+			};
+			core.push(createDataBatchTool(workspace, () => new Set(dataTools().map((tool) => tool.name)), {
+				getTools: dataTools,
+				canExecute: (name) => dataTools().some((tool) => tool.name === name),
+				allowHostGit: () => getCommandIsolation()?.mode !== "docker"
+			}));
+		}
+		return filterToolsByDisabledSet(core, disabled);
 	}
 	createCapabilityTools(capabilityNames, options) {
 		const disabled = options?.disabledTools;

package/dist/src/agent/tools/fetch-text.d.ts

@@ -0,0 +1,7 @@
+import { type WebsiteBlocklistConfig } from './url-safety.js';
+/** Validate each redirect and the address actually used for the connection. */
+export declare function fetchPublicText(input: string, blocklist: WebsiteBlocklistConfig | undefined, signal?: AbortSignal): Promise<{
+    text: string;
+    contentType: string;
+    url: string;
+}>;

package/dist/src/agent/tools/fetch-text.js

@@ -0,0 +1,86 @@
+import { checkUrlSafety, checkWebsiteBlocklist } from "./url-safety.js";
+import { Agent, fetch } from "undici";
+import { lookup } from "node:dns";
+//#region src/agent/tools/fetch-text.ts
+/** Validate each redirect and the address actually used for the connection. */
+async function fetchPublicText(input, blocklist, signal) {
+	const deadline = AbortSignal.any([...signal ? [signal] : [], AbortSignal.timeout(25e3)]);
+	const dispatcher = new Agent({ connect: { lookup(hostname, options, callback) {
+		lookup(hostname, { all: true }, (error, addresses) => {
+			if (error) {
+				callback(error, "", 4);
+				return;
+			}
+			if (!addresses.length || addresses.some((item) => !checkUrlSafety(`http://${item.family === 6 ? `[${item.address}]` : item.address}`).safe)) {
+				callback(/* @__PURE__ */ new Error("DNS resolved to a non-public address"), "", 4);
+				return;
+			}
+			if (options.all) callback(null, addresses);
+			else callback(null, addresses[0].address, addresses[0].family);
+		});
+	} } });
+	try {
+		let url = input;
+		for (let redirects = 0; redirects <= 5; redirects++) {
+			deadline.throwIfAborted();
+			const safety = checkUrlSafety(url);
+			if (!safety.safe) throw new Error(`Blocked: ${safety.reason}`);
+			const blocked = checkWebsiteBlocklist(url, blocklist);
+			if (blocked) throw new Error(`Blocked: ${blocked.message}`);
+			const response = await fetch(url, {
+				signal: deadline,
+				redirect: "manual",
+				dispatcher
+			});
+			if ([
+				301,
+				302,
+				303,
+				307,
+				308
+			].includes(response.status)) {
+				await response.body?.cancel();
+				const location = response.headers.get("location");
+				if (!location) throw new Error("Redirect has no location");
+				url = new URL(location, url).href;
+				continue;
+			}
+			if (!response.ok) {
+				await response.body?.cancel();
+				throw new Error(`HTTP ${response.status}`);
+			}
+			const reader = response.body?.getReader();
+			if (!reader) return {
+				text: "",
+				contentType: response.headers.get("content-type") ?? "",
+				url
+			};
+			const decoder = new TextDecoder();
+			let text = "", bytes = 0;
+			try {
+				for (;;) {
+					deadline.throwIfAborted();
+					const chunk = await reader.read();
+					if (chunk.done) break;
+					bytes += chunk.value.byteLength;
+					if (bytes > 6e6) throw new Error("Response too large");
+					text += decoder.decode(chunk.value, { stream: true });
+				}
+				text += decoder.decode();
+			} finally {
+				await reader.cancel().catch(() => {});
+				reader.releaseLock();
+			}
+			return {
+				text,
+				contentType: response.headers.get("content-type") ?? "",
+				url
+			};
+		}
+		throw new Error("Too many redirects");
+	} finally {
+		await dispatcher.close();
+	}
+}
+//#endregion
+export { fetchPublicText };

package/dist/src/agent/tools/find.js

@@ -1,6 +1,6 @@
 import { evaluateFilePolicy } from "../sandbox/exec-policy.js";
-import { resolveToCwd } from "../../utils/helpers.js";
 import { isSearchFileAllowed, repositorySearch } from "./repository-search.js";
+import { resolveToCwd } from "../../utils/helpers.js";
 import { Type } from "@sinclair/typebox";
 //#region src/agent/tools/find.ts
 const findSchema = Type.Object({

package/dist/src/agent/tools/grep.js

@@ -1,6 +1,6 @@
 import { evaluateFilePolicy } from "../sandbox/exec-policy.js";
+import { parseRepositoryMatch, repositorySearch } from "./repository-search.js";
 import { resolveToCwd } from "../../utils/helpers.js";
-import { isSearchFileAllowed, repositorySearch } from "./repository-search.js";
 import { Type } from "@sinclair/typebox";
 //#region src/agent/tools/grep.ts
 const grepSchema = Type.Object({
@@ -36,7 +36,9 @@ function createGrepTool(cwd) {
 			if (!policy.allowed) throw new Error(policy.reason);
 			path = policy.canonicalPath;
 			const limit = Math.min(1e3, Math.max(1, params.limit ?? 100));
-			const result = await repositorySearch(cwd, [
+			const lines = [];
+			const outputLimit = limit * (1 + 2 * (params.context ?? 0));
+			const truncated = (await repositorySearch(cwd, [
 				"--json",
 				"--line-number",
 				"--with-filename",
@@ -45,8 +47,6 @@ function createGrepTool(cwd) {
 				"--max-columns",
 				"300",
 				"--max-columns-preview",
-				"--max-count",
-				String(limit),
 				"--context",
 				String(params.context ?? 0),
 				...params.ignoreCase ? ["--ignore-case"] : [],
@@ -56,25 +56,13 @@ function createGrepTool(cwd) {
 				params.pattern,
 				"--",
 				path
-			], signal);
-			const lines = [];
-			for (const row of result.output.split("\n")) {
-				if (!row) continue;
-				let event;
-				try {
-					event = JSON.parse(row);
-				} catch {
-					if (result.truncated) continue;
-					throw new Error("Invalid search output");
-				}
-				if (event.type !== "match" && event.type !== "context") continue;
-				const data = event.data;
-				if (!data?.path?.text || !data.lines?.text || !isSearchFileAllowed(cwd, data.path.text)) continue;
-				const separator = event.type === "match" ? ":" : "-";
-				lines.push(`${data.path.text}${separator}${data.line_number}${separator}${data.lines.text.replace(/\r?\n$/, "")}`);
-			}
-			const outputLimit = limit * (1 + 2 * (params.context ?? 0));
-			const truncated = result.truncated || lines.length > outputLimit;
+			], signal, { onLine: (row) => {
+				const match = parseRepositoryMatch(cwd, row);
+				if (!match) return;
+				const separator = match.match ? ":" : "-";
+				lines.push(`${match.path}${separator}${match.line}${separator}${match.text}`);
+				if (lines.length > outputLimit) return false;
+			} })).truncated || lines.length > outputLimit;
 			return {
 				content: [{
 					type: "text",

package/dist/src/agent/tools/index.d.ts

@@ -1,6 +1,7 @@
 export { getToolMetadata, DEFAULT_TOOL_METADATA, type AgentToolWithMetadata, type ToolMutationScope, type ToolVerificationKind, type XopcToolMetadata, } from './metadata.js';
 export { ToolConcurrencyController, resolveToolLockMode, type ToolLockMode, } from './concurrency.js';
 export { createReadFileTool, type CreateReadFileToolOptions } from './read.js';
+export { createDataBatchTool } from './dataBatch.js';
 export { createWriteFileTool, writeFileTool } from './write.js';
 export { createListDirTool, listDirTool } from './list-dir.js';
 export { createExecCommandTool, type ExecCommandDetails, type ExecCommandUpdateDetails, } from './exec-command.js';

package/dist/src/agent/tools/index.js

@@ -2,6 +2,7 @@ import { DEFAULT_TOOL_METADATA, getToolMetadata } from "./metadata.js";
 import { ToolConcurrencyController, resolveToolLockMode } from "./concurrency.js";
 import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, GREP_MAX_LINE_LENGTH, formatSize, truncateHead, truncateLine, truncateTail } from "./truncate.js";
 import { createReadFileTool } from "./read.js";
+import { createDataBatchTool } from "./dataBatch.js";
 import { createWriteFileTool, writeFileTool } from "./write.js";
 import { createListDirTool, listDirTool } from "./list-dir.js";
 import { createPublishArtifactsTool } from "./publish-artifacts.js";
@@ -43,4 +44,4 @@ import { createDesktopPetTool } from "./desktop-pet-tool.js";
 import { createManagedJobTool } from "./managed-job-tool.js";
 import { createImageTool } from "./image-tool.js";
 import { createImageGenerateTool, resolveImageGenerationModelConfigForTool } from "./image-generate-tool.js";
-export { BrowserRuntime, DEFAULT_DELEGATE_TOOLS, DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, DEFAULT_TOOL_METADATA, DEFAULT_WEB_EXTRACT_MAX_LENGTH, DELEGATE_BLOCKED_TOOLS, GREP_MAX_LINE_LENGTH, MAX_RAW_HTML_CHARS_FOR_WEB_EXTRACT, TodoStore, ToolConcurrencyController, assertBrowserUrlAllowed, createApplyPatchTool, createAutomationTool, createBrowserAutomationTool, createClarifyTool, createCreateShareTool, createDelegateTool, createDesktopPetTool, createExecCommandTool, createFindTool, createGrepTool, createImageGenerateTool, createImageTool, createKnowledgeGetTool, createKnowledgeSearchTool, createKnowledgeWriteTool, createListDirTool, createManagedJobTool, createMemoryMaintenanceTool, createMessageTool, createPublishArtifactsTool, createReadFileTool, createReadMediaTool, createSendMediaTool, createSessionRecallTool, createSessionSearchTool, createSessionStatusTool, createSkillInstallTool, createSkillManageTool, createSkillViewTool, createSkillsListTool, createSkillsMarketplaceSearchTool, createTodoTool, createToolManualTool, createUpdatePlanTool, createUserContextGetTool, createUserContextSearchTool, createUserContextUpdateTool, createWebExtractTool, createWebFetchTool, createWebSearchTool, createWorkflowTool, createWriteFileTool, createXopcUseTool, findTool, formatSize, fuzzyFindText, generateDiffString, getToolMetadata, grepTool, isShareToolAvailable, listDirTool, normalizeForFuzzyMatch, normalizeToLF, resolveImageGenerationModelConfigForTool, resolveImageModelConfigForTool, resolveToolLockMode, restoreLineEndings, stripBom, stripHtmlBoilerplate, truncateHead, truncateLine, truncateTail, writeFileTool };
+export { BrowserRuntime, DEFAULT_DELEGATE_TOOLS, DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, DEFAULT_TOOL_METADATA, DEFAULT_WEB_EXTRACT_MAX_LENGTH, DELEGATE_BLOCKED_TOOLS, GREP_MAX_LINE_LENGTH, MAX_RAW_HTML_CHARS_FOR_WEB_EXTRACT, TodoStore, ToolConcurrencyController, assertBrowserUrlAllowed, createApplyPatchTool, createAutomationTool, createBrowserAutomationTool, createClarifyTool, createCreateShareTool, createDataBatchTool, createDelegateTool, createDesktopPetTool, createExecCommandTool, createFindTool, createGrepTool, createImageGenerateTool, createImageTool, createKnowledgeGetTool, createKnowledgeSearchTool, createKnowledgeWriteTool, createListDirTool, createManagedJobTool, createMemoryMaintenanceTool, createMessageTool, createPublishArtifactsTool, createReadFileTool, createReadMediaTool, createSendMediaTool, createSessionRecallTool, createSessionSearchTool, createSessionStatusTool, createSkillInstallTool, createSkillManageTool, createSkillViewTool, createSkillsListTool, createSkillsMarketplaceSearchTool, createTodoTool, createToolManualTool, createUpdatePlanTool, createUserContextGetTool, createUserContextSearchTool, createUserContextUpdateTool, createWebExtractTool, createWebFetchTool, createWebSearchTool, createWorkflowTool, createWriteFileTool, createXopcUseTool, findTool, formatSize, fuzzyFindText, generateDiffString, getToolMetadata, grepTool, isShareToolAvailable, listDirTool, normalizeForFuzzyMatch, normalizeToLF, resolveImageGenerationModelConfigForTool, resolveImageModelConfigForTool, resolveToolLockMode, restoreLineEndings, stripBom, stripHtmlBoilerplate, truncateHead, truncateLine, truncateTail, writeFileTool };

package/dist/src/agent/tools/knowledge-memory-tool.js

@@ -48,6 +48,7 @@ function createKnowledgeSearchTool(options) {
 		label: "Knowledge Search",
 		description: "Search project, workspace, and session knowledge for prior decisions, facts, lessons, and commitments.",
 		parameters: SearchSchema,
+		supportsParallel: true,
 		async execute(_toolCallId, raw) {
 			if (!options.canRead()) return {
 				content: [{
@@ -82,6 +83,7 @@ function createKnowledgeGetTool(options) {
 		label: "Knowledge Get",
 		description: "Read one knowledge item returned by knowledge_search.",
 		parameters: GetSchema,
+		supportsParallel: true,
 		async execute(_toolCallId, raw) {
 			if (!options.canRead()) return {
 				content: [{
@@ -97,13 +99,19 @@ function createKnowledgeGetTool(options) {
 					type: "text",
 					text: JSON.stringify(item, null, 2)
 				}],
-				details: { item }
+				details: {
+					item,
+					complete: true
+				}
 			} : {
 				content: [{
 					type: "text",
 					text: `Knowledge item not found: ${id}`
 				}],
-				details: { id }
+				details: {
+					id,
+					error: "knowledge_not_found"
+				}
 			};
 		}
 	};

package/dist/src/agent/tools/read.js

@@ -1,4 +1,5 @@
-import { checkedFilePath, readWorkspaceFile } from "../sandbox/fileAccess.js";
+import { checkedFilePath, readWorkspaceFileAsync } from "../sandbox/fileAccess.js";
+import { dataScheduler } from "../data-acquisition/scheduler.js";
 import { checkFileSafety } from "../prompt/safety.js";
 import { DEFAULT_MAX_BYTES, formatSize, truncateHead } from "./truncate.js";
 import { isBareProfileMarkdownFileName, resolvePathUnderWorkspace, resolveProfileMarkdownPathIfBareName } from "./tool-paths.js";
@@ -27,12 +28,12 @@ function createReadFileTool(workspace, options) {
 		label: "📄 Read",
 		supportsParallel: true,
 		idempotent: true,
-		async execute(_toolCallId, params, _signal) {
-			return executeReadFile(workspace, options?.profileMarkdownRoot, params);
+		async execute(_toolCallId, params, signal) {
+			return dataScheduler.run(workspace, signal, () => executeReadFile(workspace, options?.profileMarkdownRoot, params, signal));
 		}
 	};
 }
-async function executeReadFile(workspace, profileMarkdownRoot, params) {
+async function executeReadFile(workspace, profileMarkdownRoot, params, signal) {
 	try {
 		const safety = checkFileSafety("read", params.path);
 		if (!safety.allowed) return {
@@ -66,7 +67,7 @@ async function executeReadFile(workspace, profileMarkdownRoot, params) {
 			}],
 			details: { status: "failed" }
 		};
-		const content = readWorkspaceFile(activeRoot, normalized, MAX_FILE_SIZE).toString("utf8");
+		const content = (await readWorkspaceFileAsync(activeRoot, normalized, signal, MAX_FILE_SIZE)).toString("utf8");
 		const offset = Math.max(1, params.offset ?? 1);
 		const lines = content.split("\n");
 		if (offset > lines.length) throw new Error(`Offset ${offset} exceeds ${lines.length} lines`);
@@ -90,6 +91,7 @@ async function executeReadFile(workspace, profileMarkdownRoot, params) {
 			}
 		};
 	} catch (error) {
+		signal?.throwIfAborted();
 		return {
 			content: [{
 				type: "text",

package/dist/src/agent/tools/repository-search.d.ts

@@ -1,5 +1,15 @@
-/** Bounded native search; unavailable tools and invalid regexes are explicit failures. */
-export declare function repositorySearch(cwd: string, args: string[], signal?: AbortSignal): Promise<{
+export interface RepositorySearchOptions {
+    maxBytes?: number;
+    onLine?: (line: string) => boolean | void;
+}
+export declare function parseRepositoryMatch(workspace: string, line: string): {
+    path: string;
+    line: number;
+    text: string;
+    match: boolean;
+} | undefined;
+/** One bounded process path for raw filename output and streamed JSON events. */
+export declare function repositorySearch(cwd: string, args: string[], signal?: AbortSignal, options?: RepositorySearchOptions): Promise<{
     output: string;
     truncated: boolean;
 }>;