@xopcai/xopc 0.0.360 → 0.0.362

package/dist/src/agent/memory/idle-compaction-scheduler.js

@@ -0,0 +1,127 @@
+import { createLogger } from "../../utils/logger/index.js";
+import { init_logger } from "../../utils/logger.js";
+//#region src/agent/memory/idle-compaction-scheduler.ts
+init_logger();
+const log = createLogger("IdleCompaction");
+/** Generation checks protect commits even when a provider ignores cancellation. */
+var IdleCompactionScheduler = class {
+	states = /* @__PURE__ */ new Map();
+	running = false;
+	disposed = false;
+	metrics = {
+		committed: 0,
+		skipped: 0,
+		stale: 0,
+		cancelled: 0,
+		failed: 0
+	};
+	getMetrics() {
+		return { ...this.metrics };
+	}
+	interrupt(conversationId) {
+		const state = this.states.get(conversationId);
+		if (!state) return;
+		state.generation++;
+		if (state.timer) clearTimeout(state.timer);
+		state.timer = void 0;
+		state.job = void 0;
+		if (state.controller && !state.controller.signal.aborted) {
+			this.metrics.cancelled++;
+			state.controller.abort();
+		}
+	}
+	beginTurn(conversationId) {
+		this.interrupt(conversationId);
+		const state = this.states.get(conversationId) ?? {
+			generation: 0,
+			active: 0,
+			eligibleAt: 0
+		};
+		state.active++;
+		this.states.set(conversationId, state);
+		return state.generation;
+	}
+	endTurn(conversationId, generation, job, options) {
+		const state = this.states.get(conversationId);
+		if (!state) return;
+		state.active = Math.max(0, state.active - 1);
+		if (this.disposed || state.active || state.generation !== generation || !job || !options) return;
+		state.job = job;
+		state.queuedAt = Date.now();
+		state.options = options;
+		const delay = Math.max(options.idleMs, state.eligibleAt - Date.now());
+		state.timer = setTimeout(() => {
+			state.timer = void 0;
+			this.drain();
+		}, delay);
+		state.timer.unref?.();
+	}
+	cancelAll() {
+		for (const id of this.states.keys()) this.interrupt(id);
+	}
+	dispose() {
+		this.disposed = true;
+		this.cancelAll();
+		for (const state of this.states.values()) if (state.deadline) clearTimeout(state.deadline);
+		this.states.clear();
+	}
+	drain() {
+		if (this.running || this.disposed) return;
+		const entry = [...this.states.entries()].find(([, state]) => state.job && !state.timer && !state.active);
+		if (!entry) return;
+		const [conversationId, state] = entry;
+		const job = state.job;
+		const options = state.options;
+		state.job = void 0;
+		const generation = state.generation;
+		const controller = new AbortController();
+		state.controller = controller;
+		const startedAt = Date.now();
+		const waitMs = startedAt - (state.queuedAt ?? startedAt);
+		const isCurrent = () => !this.disposed && !controller.signal.aborted && state.generation === generation && !state.active;
+		this.running = true;
+		let timeout;
+		const deadline = new Promise((_, reject) => {
+			timeout = setTimeout(() => {
+				controller.abort();
+				reject(/* @__PURE__ */ new Error("Idle compaction deadline exceeded"));
+			}, options.timeoutMs);
+			state.deadline = timeout;
+			timeout.unref?.();
+		});
+		const operation = Promise.resolve().then(() => job(controller.signal, isCurrent));
+		Promise.race([operation, deadline]).then((outcome) => {
+			this.metrics[outcome]++;
+			if (outcome === "committed") state.eligibleAt = Date.now() + options.cooldownMs;
+			const fields = {
+				conversationId,
+				outcome,
+				waitMs,
+				durationMs: Date.now() - startedAt
+			};
+			if (outcome === "skipped") log.debug(fields, "Idle compaction skipped");
+			else log.info(fields, "Idle compaction finished");
+		}).catch((err) => {
+			if (state.generation === generation) {
+				this.metrics.failed++;
+				state.eligibleAt = Date.now() + options.cooldownMs;
+				log.warn({
+					err,
+					conversationId,
+					durationMs: Date.now() - startedAt
+				}, "Idle compaction failed; retry deferred");
+			}
+		}).finally(() => {
+			clearTimeout(timeout);
+			if (state.deadline === timeout) state.deadline = void 0;
+			if (state.controller === controller) state.controller = void 0;
+		});
+		const release = () => {
+			this.running = false;
+			this.drain();
+		};
+		operation.then(release, release);
+	}
+};
+//#endregion
+export { IdleCompactionScheduler };

package/dist/src/agent/service/process-direct-one-shot.js

@@ -8,6 +8,7 @@ function isReviewOutput(value) {
 	return !!value && typeof value === "object" && !Array.isArray(value) && value.type === "review";
 }
 async function runProcessDirect(deps, input) {
+	deps.sessionStore?.idleCompaction?.interrupt(input.conversationId);
 	const { channel, chatId } = await deps.resolveSessionEndpoint(input.conversationId);
 	deps.initSessionContext(input.conversationId, channel, chatId, input.origin);
 	try {

package/dist/src/agent/service/process-direct-streaming.js

@@ -138,6 +138,7 @@ function pushAssistantReceipt(queue, text, runId, metadata) {
 }
 async function* runProcessDirectStreaming(deps, input) {
 	const conversationId = input.conversationId ?? resolveAgentMainConversationId({ agentId: resolveDefaultAgentId() });
+	deps.sessionStore?.idleCompaction?.interrupt(conversationId);
 	const isConnectionResume = Boolean(input.runId && getConnectionResumeInput(conversationId, input.runId));
 	const isClarificationResume = Boolean(input.runId && getClarificationResumeInput(conversationId, input.runId));
 	const isInternalResume = isConnectionResume || isClarificationResume;

package/dist/src/agent/service.js

@@ -1,13 +1,13 @@
 import { createLogger } from "../utils/logger/index.js";
 import { init_logger } from "../utils/logger.js";
 import { init_attachment_ref, parseNoteAttachmentTarget } from "../notes/attachment-ref.js";
-import { init_agent_scope, resolveAgentHomeDir, resolveDefaultAgentId } from "./agent-scope.js";
-import { extractTextContent } from "./context/workspace.js";
 import { getAgentDefaultModelRef, init_schema } from "../config/schema.js";
 import { applyConfigOverrides } from "../config/runtime-overrides.js";
+import { init_agent_scope, resolveAgentHomeDir, resolveDefaultAgentId } from "./agent-scope.js";
 import { init_agent_session_key, resolveAgentIdFromConversationId } from "../routing/agent-session-key.js";
 import { extractProfileAgentId, resolveEffectiveAgentConfigForSession } from "../config/agent-profile.js";
 import { init_providers, resolveModel } from "../providers/index.js";
+import { extractTextContent } from "./context/workspace.js";
 import { effectiveWorkspacePathForSession } from "../session/session-workspace.js";
 import { getProjectForSession } from "../projects/workspace.js";
 import { runWithEmbeddedExecutionSession } from "./embedded/execution-context.js";
@@ -878,6 +878,7 @@ var AgentService = class {
 		}
 	}
 	dispose() {
+		this.sessionStore.idleCompaction.dispose();
 		this.sessionTracker.dispose();
 		this.sessionState.disposeAll();
 		this.agentManager.dispose();

package/dist/src/agent/session/session-config-service.js

@@ -6,8 +6,8 @@ import { ResponseLanguageSchema, init_response_language } from "../../i18n/respo
 import { resolveEffectiveAgentConfigForSession } from "../../config/agent-profile.js";
 import { normalizeWorkingDirectoryInput } from "../../session/session-workspace.js";
 import { getProjectWorkspacePathForSession } from "../../projects/workspace.js";
-import { getModelThinking } from "../../providers/model-thinking.js";
 import { isPersonalConversation } from "../../personal-agent/repository.js";
+import { getModelThinking } from "../../providers/model-thinking.js";
 import { savePersonalModelConfig } from "../../personal-agent/model-config.js";
 import { normalizeReasoningLevel, normalizeThinkLevel, normalizeVerboseLevel } from "../transcript/thinking-types.js";
 import "../../session/index.js";

package/dist/src/agent/skills/hub-lock.js

@@ -1,5 +1,5 @@
-import { init_write_file_atomic, writeTextAtomicSync } from "../../infra/write-file-atomic.js";
 import { init_paths, resolveSkillsLockPath } from "../../config/paths.js";
+import { init_write_file_atomic, writeTextAtomicSync } from "../../infra/write-file-atomic.js";
 import { existsSync, readFileSync } from "node:fs";
 //#region src/agent/skills/hub-lock.ts
 /**

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

@@ -1,8 +1,8 @@
 import { resolveStateDir } from "../../config/paths-state.js";
 import { createLogger } from "../../utils/logger/index.js";
 import { init_logger } from "../../utils/logger.js";
-import { parseFrontmatter } from "../../markdown/frontmatter.js";
 import { init_paths } from "../../config/paths.js";
+import { parseFrontmatter } from "../../markdown/frontmatter.js";
 import { findInstallSpec, hasBinary, installSkill } from "./installer.js";
 import { applySkillEnvOverrides, createSkillConfigManager, getSkillEnvironment, isSkillEnabled, resolveSkillConfig, validateSkillConfig } from "./config.js";
 import { parseSkillToolConditions } from "./skill-tool-gating.js";

package/dist/src/agent/skills/managed-store.js

@@ -1,5 +1,5 @@
-import { parseFrontmatter } from "../../markdown/frontmatter.js";
 import { init_paths, resolveSkillsDir } from "../../config/paths.js";
+import { parseFrontmatter } from "../../markdown/frontmatter.js";
 import { loadSkillsLock } from "./hub-lock.js";
 import { dirname, join, resolve, sep } from "node:path";
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";

package/dist/src/agent/skills/skill-manage-ops.js

@@ -1,5 +1,5 @@
-import { parseFrontmatter } from "../../markdown/frontmatter.js";
 import { init_paths, resolveSkillsDir } from "../../config/paths.js";
+import { parseFrontmatter } from "../../markdown/frontmatter.js";
 import { resolveWorkspaceSkillsDir } from "./workspace-skills-dir.js";
 import { formatScanSummary, scanSkillDirectory } from "./scanner.js";
 import { fuzzyFindText, normalizeForFuzzyMatch, normalizeToLF, restoreLineEndings } from "../tools/edit-diff.js";

package/dist/src/agent/tasks/task-judge-service.js

@@ -207,7 +207,7 @@ var TaskJudgeService = class {
 				expectedRunVersion: run.version,
 				receipt: {
 					status: "succeeded",
-					summary: payload.assistantPlainText.slice(-2e3) || "Agent run completed",
+					summary: payload.assistantPlainText || "Agent run completed",
 					changes: [],
 					evidence,
 					verification: {

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

@@ -16,6 +16,7 @@ const DELEGATION_TOOL_CAPABILITIES = {
 	find: "local_read",
 	list_dir: "local_read",
 	review_workspace: "local_read",
+	personal_read: "local_read",
 	read_media: "local_read",
 	image: "local_read",
 	tool_manual: "local_read",

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

@@ -62,6 +62,7 @@ import { createDesktopPetTool } from "./desktop-pet-tool.js";
 import { createManagedJobTool } from "./managed-job-tool.js";
 import { createImageTool } from "./image-tool.js";
 import { createImageGenerateTool } from "./image-generate-tool.js";
+import { createPersonalReadTool } from "./personal-read-tool.js";
 import "./index.js";
 import { createPersonalTaskTool } from "./personal-task-tool.js";
 import { createPersonalRequestTools } from "./personal-request-tool.js";
@@ -279,7 +280,14 @@ var AgentToolsFactory = class AgentToolsFactory {
 			canAccessMemory: () => currentAccess().knowledge
 		});
 		const optionalTools = [imageTool, imageGenerateTool].filter((t) => t != null);
-		const readTool = createReadFileTool(workspace, { profileMarkdownRoot: options?.profileMarkdownRoot });
+		const readTool = createReadFileTool(workspace, {
+			profileMarkdownRoot: options?.profileMarkdownRoot,
+			...personalToolsConfigured ? {
+				defaultMaxLines: 150,
+				maxOutputBytes: 8e3,
+				maxReadBytes: 12e3
+			} : {}
+		});
 		const writeTool = createWriteFileTool(workspace, { profileMarkdownRoot: options?.profileMarkdownRoot });
 		const applyPatchTool = createApplyPatchTool(workspace);
 		const listDir = createListDirTool(workspace);
@@ -395,7 +403,11 @@ var AgentToolsFactory = class AgentToolsFactory {
 			})] : [],
 			createSendMediaTool(workspace, bus, deliveryContext),
 			createPublishArtifactsTool(workspace),
-			createReadMediaTool(),
+			createReadMediaTool(personalToolsConfigured ? {
+				textOnly: true,
+				maxChars: 8e3,
+				maxReadBytes: 12e3
+			} : void 0),
 			...isShareToolAvailable(cfg) ? [createCreateShareTool({
 				workspace,
 				getConfig: () => this.deps.getConfig?.()
@@ -461,6 +473,7 @@ var AgentToolsFactory = class AgentToolsFactory {
 				getCurrentConversationId: () => this.deps.getCurrentContext()?.conversationId
 			})] : [],
 			...this.deps.getSessionStore && getPrimary ? [createSessionSearchTool({
+				localOnly: personalToolsConfigured,
 				getSessionStore: this.deps.getSessionStore,
 				getPrimaryModel: getPrimary,
 				getCurrentConversationId: () => this.deps.getCurrentContext()?.conversationId,
@@ -474,6 +487,7 @@ var AgentToolsFactory = class AgentToolsFactory {
 			...browserEnabled && this.deps.getBrowserAutomationService ? [createBrowserAutomationTool({ getBrowserAutomationService: this.deps.getBrowserAutomationService })] : [],
 			...this.deps.getAutomationService || this.deps.getSceneAccess || this.deps.getProjectService || this.deps.getNotesService || this.deps.getLocalAppService || this.deps.getChatPreviewService || this.deps.dispatchTaskEvents || this.deps.dispatchTaskRuns ? [createXopcUseTool(productToolDeps), ...personalToolsConfigured ? [
 				createPersonalTaskTool(productToolDeps),
+				createPersonalReadTool(productToolDeps),
 				...createPersonalRequestTools(productToolDeps),
 				createPersonalPreferenceTool({
 					getCurrentConversationId: () => this.deps.getCurrentContext()?.conversationId,

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

@@ -42,3 +42,4 @@ export { createImageTool, resolveImageModelConfigForTool } from './image-tool.js
 export { createImageGenerateTool, resolveImageGenerationModelConfigForTool } from './image-generate-tool.js';
 export { truncateHead, truncateTail, truncateLine, formatSize, type TruncationResult, type TruncationOptions, DEFAULT_MAX_LINES, DEFAULT_MAX_BYTES, GREP_MAX_LINE_LENGTH, } from './truncate.js';
 export { normalizeToLF, restoreLineEndings, normalizeForFuzzyMatch, fuzzyFindText, stripBom, generateDiffString, type FuzzyMatchResult, } from './edit-diff.js';
+export { createPersonalReadTool } from './personal-read-tool.js';

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

@@ -45,4 +45,5 @@ 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, 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, createWorkflowManageTool, createWorkflowTool, createWriteFileTool, createXopcUseTool, findTool, formatSize, fuzzyFindText, generateDiffString, getToolMetadata, grepTool, isShareToolAvailable, listDirTool, normalizeForFuzzyMatch, normalizeToLF, resolveImageGenerationModelConfigForTool, resolveImageModelConfigForTool, resolveToolLockMode, restoreLineEndings, stripBom, stripHtmlBoilerplate, truncateHead, truncateLine, truncateTail, writeFileTool };
+import { createPersonalReadTool } from "./personal-read-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, createDataBatchTool, createDelegateTool, createDesktopPetTool, createExecCommandTool, createFindTool, createGrepTool, createImageGenerateTool, createImageTool, createKnowledgeGetTool, createKnowledgeSearchTool, createKnowledgeWriteTool, createListDirTool, createManagedJobTool, createMemoryMaintenanceTool, createMessageTool, createPersonalReadTool, createPublishArtifactsTool, createReadFileTool, createReadMediaTool, createSendMediaTool, createSessionRecallTool, createSessionSearchTool, createSessionStatusTool, createSkillInstallTool, createSkillManageTool, createSkillViewTool, createSkillsListTool, createSkillsMarketplaceSearchTool, createTodoTool, createToolManualTool, createUpdatePlanTool, createUserContextGetTool, createUserContextSearchTool, createUserContextUpdateTool, createWebExtractTool, createWebFetchTool, createWebSearchTool, createWorkflowManageTool, 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/media-read-tool.d.ts

@@ -1,2 +1,6 @@
 import type { AgentTool } from '@earendil-works/pi-agent-core';
-export declare function createReadMediaTool(): AgentTool;
+export declare function createReadMediaTool(options?: {
+    textOnly?: boolean;
+    maxChars?: number;
+    maxReadBytes?: number;
+}): AgentTool;

package/dist/src/agent/tools/media-read-tool.js

@@ -15,12 +15,14 @@ function clampMaxBytes(raw) {
 	if (typeof raw !== "number" || !Number.isFinite(raw) || raw <= 0) return DEFAULT_MAX_BYTES;
 	return Math.min(Math.floor(raw), HARD_MAX_BYTES);
 }
-function createReadMediaTool() {
+function createReadMediaTool(options) {
 	return {
 		name: "read_media",
 		label: "Read Media Attachment",
 		description: "Read an attachment by media:// URI. Use this for xopc-media-uri attachments in user messages.",
 		parameters: ReadMediaSchema,
+		supportsParallel: true,
+		idempotent: true,
 		async execute(_toolCallId, params, _signal) {
 			const uri = typeof params.uri === "string" ? params.uri.trim() : "";
 			if (!uri) return {
@@ -34,7 +36,7 @@ function createReadMediaTool() {
 				}
 			};
 			try {
-				const { buffer, path } = await readMediaReference(uri, clampMaxBytes(params.maxBytes));
+				const { buffer, path } = await readMediaReference(uri, Math.min(clampMaxBytes(params.maxBytes), options?.maxReadBytes ?? HARD_MAX_BYTES));
 				const mimeType = mimeTypeFromMediaPath(path);
 				const metadata = {
 					ok: true,
@@ -43,14 +45,35 @@ function createReadMediaTool() {
 					size: buffer.byteLength,
 					path
 				};
-				if (isLikelyText(mimeType)) return {
+				if (isLikelyText(mimeType)) {
+					const fullText = buffer.toString("utf8");
+					const maxChars = options?.maxChars ?? fullText.length;
+					const truncated = fullText.length > maxChars;
+					return {
+						content: [{
+							type: "text",
+							text: fullText.slice(0, maxChars) + (truncated ? "\n[Attachment truncated; delegate full analysis to a specialist.]" : "")
+						}],
+						details: {
+							...metadata,
+							kind: "text",
+							truncated,
+							...truncated && options?.textOnly ? {
+								requiresSpecialist: true,
+								reason: "large_attachment"
+							} : {}
+						}
+					};
+				}
+				if (options?.textOnly) return {
 					content: [{
 						type: "text",
-						text: buffer.toString("utf8")
+						text: "Binary attachment: delegate document parsing or media analysis to a specialist."
 					}],
 					details: {
 						...metadata,
-						kind: "text"
+						kind: "binary",
+						requiresSpecialist: true
 					}
 				};
 				return {
@@ -68,6 +91,22 @@ function createReadMediaTool() {
 					}
 				};
 			} catch (err) {
+				if (options?.textOnly && err?.code === "MEDIA_READ_LIMIT") {
+					const size = err.size;
+					return {
+						content: [{
+							type: "text",
+							text: `Attachment is large (${size} bytes; local read limit ${options.maxReadBytes ?? HARD_MAX_BYTES} bytes). Tell the user briefly, then delegate reading and processing with this URI: ${uri}`
+						}],
+						details: {
+							ok: true,
+							uri,
+							size,
+							requiresSpecialist: true,
+							reason: "large_attachment"
+						}
+					};
+				}
 				const message = err instanceof Error ? err.message : String(err);
 				return {
 					content: [{

package/dist/src/agent/tools/personal-read-tool.d.ts

@@ -0,0 +1,3 @@
+import type { AgentTool } from '@earendil-works/pi-agent-core';
+import type { XopcUseToolDeps } from './xopc-use-tool.js';
+export declare function createPersonalReadTool(deps: XopcUseToolDeps): AgentTool;

package/dist/src/agent/tools/personal-read-tool.js

@@ -0,0 +1,155 @@
+import { CapabilityDispatcher } from "../../capabilities/runtime/dispatcher.js";
+import { registerNoteReadCapabilities } from "../../notes/capabilities/read.js";
+import { registerProjectReadCapabilities } from "../../projects/capabilities/read.js";
+import { registerAutomationReadCapabilities } from "../../automations/capabilities/read.js";
+import { Type } from "@sinclair/typebox";
+//#region src/agent/tools/personal-read-tool.ts
+const schema = Type.Object({
+	kind: Type.Union([
+		Type.Literal("note"),
+		Type.Literal("project"),
+		Type.Literal("automation")
+	]),
+	command: Type.Union([Type.Literal("list"), Type.Literal("get")]),
+	id: Type.Optional(Type.String()),
+	search: Type.Optional(Type.String({ maxLength: 500 })),
+	projectId: Type.Optional(Type.String()),
+	offset: Type.Optional(Type.Integer({ minimum: 0 })),
+	limit: Type.Optional(Type.Integer({
+		minimum: 1,
+		maximum: 10
+	}))
+});
+const fields = [
+	"id",
+	"name",
+	"title",
+	"status",
+	"kind",
+	"projectId",
+	"description",
+	"markdown",
+	"objective",
+	"enabled",
+	"createdAt",
+	"updatedAt",
+	"createdAtMs",
+	"updatedAtMs",
+	"trigger",
+	"action",
+	"state"
+];
+/** Small projections keep local reads from expanding the next model request. */
+function compact(value, textLimit) {
+	if (!value || typeof value !== "object") return {};
+	const source = value;
+	const result = {};
+	const truncatedFields = [];
+	for (const key of fields) {
+		const entry = source[key];
+		if (typeof entry === "string") {
+			result[key] = entry.slice(0, textLimit);
+			if (entry.length > textLimit) truncatedFields.push(key);
+		} else if (typeof entry === "number" || typeof entry === "boolean" || entry === null) result[key] = entry;
+		else if (entry && typeof entry === "object" && !Array.isArray(entry)) result[key] = Object.fromEntries(Object.entries(entry).slice(0, 12).filter(([, item]) => [
+			"string",
+			"number",
+			"boolean"
+		].includes(typeof item) || item === null).map(([field, item]) => [field, typeof item === "string" ? item.slice(0, 200) : item]));
+	}
+	if (truncatedFields.length) result.truncatedFields = truncatedFields;
+	return result;
+}
+function createPersonalReadTool(deps) {
+	const dispatcher = new CapabilityDispatcher();
+	if (deps.getNotesService) registerNoteReadCapabilities(dispatcher, () => {
+		const notes = deps.getNotesService();
+		if (!notes) throw new Error("Notes service unavailable");
+		return notes;
+	});
+	const projects = deps.getProjectService?.();
+	if (projects) registerProjectReadCapabilities(dispatcher, projects);
+	const automations = deps.getAutomationService?.();
+	if (automations) registerAutomationReadCapabilities(dispatcher, automations, projects);
+	return {
+		name: "personal_read",
+		label: "Read local objects",
+		description: "Read local notes, projects or automation state. Only list/get; bounded excerpts, no network or model calls. Use personal_task for delegated tasks.",
+		parameters: schema,
+		supportsParallel: true,
+		idempotent: true,
+		async execute(_id, raw, signal) {
+			const input = raw;
+			if (![
+				"note",
+				"project",
+				"automation"
+			].includes(input.kind) || !["list", "get"].includes(input.command)) throw new Error("Only local note/project/automation list/get is supported");
+			if (input.command === "get" && !input.id?.trim()) throw new Error("id is required");
+			if (input.kind === "automation" && input.search) throw new Error("Automation search is unsupported; use list");
+			const operation = `xopc.${input.kind === "note" ? "notes" : input.kind === "project" ? "projects" : "automations"}.${input.command}`;
+			const limit = Math.min(10, Math.max(1, input.limit ?? 5));
+			const offset = Math.max(0, input.offset ?? 0);
+			const args = input.command === "get" ? { id: input.id } : input.kind === "automation" ? { ...input.projectId ? { projectId: input.projectId } : {} } : {
+				limit,
+				offset,
+				...input.search ? { search: input.search } : {},
+				...input.kind === "note" && input.projectId ? { projectId: input.projectId } : {}
+			};
+			const result = await dispatcher.call(operation, args, {
+				principalId: `agent:${deps.getCurrentAgentId?.() ?? "main"}`,
+				surface: "agent",
+				scopes: ["workspace.read", "automations.read"],
+				allowedCapabilities: [operation],
+				authorize: deps.authorizeCapability ?? (() => true),
+				signal
+			});
+			let payload;
+			if (input.command === "get") payload = {
+				kind: input.kind,
+				item: compact(result[input.kind], 6e3),
+				excerpts: true
+			};
+			else {
+				const rows = result.items ?? [];
+				const selected = input.kind === "automation" ? rows.slice(offset, offset + limit) : rows;
+				payload = {
+					kind: input.kind,
+					items: selected.map((row) => compact(row, 200)),
+					offset,
+					total: result.total ?? rows.length,
+					nextOffset: selected.length === limit ? offset + selected.length : void 0,
+					excerpts: true
+				};
+			}
+			const serialized = JSON.stringify(payload);
+			const requiresSpecialist = input.command === "get" && (serialized.length > 12e3 || Boolean(payload.item?.truncatedFields));
+			if (requiresSpecialist) payload = {
+				...payload,
+				requiresSpecialist: true,
+				reason: "large_object",
+				id: input.id,
+				guidance: "Briefly tell the user the material is large, then delegate full reading and processing using this object kind and ID."
+			};
+			const output = JSON.stringify(payload);
+			return {
+				content: [{
+					type: "text",
+					text: output.length <= 12e3 ? output : JSON.stringify({
+						kind: input.kind,
+						excerpt: output.slice(0, 1e4),
+						truncated: true,
+						requiresSpecialist: true,
+						id: input.id
+					})
+				}],
+				details: {
+					localOnly: true,
+					requiresSpecialist: requiresSpecialist || output.length > 12e3
+				}
+			};
+		}
+	};
+}
+//#endregion
+export { createPersonalReadTool };

package/dist/src/agent/tools/personal-task-tool.js

@@ -3,9 +3,9 @@ import { init_agent_config } from "../../agent-config/index.js";
 import { AgentCatalogRepository, init_repository } from "../../agent-catalog/repository.js";
 import { resolveEffectiveAgentConfigForAgent } from "../../config/agent-profile.js";
 import { init_providers, isProviderConfiguredSync, resolveModel } from "../../providers/index.js";
+import { isPersonalConversation } from "../../personal-agent/repository.js";
 import { TaskOriginRepository } from "../../tasks/task-origin-repository.js";
 import { createXopcUseTool } from "./xopc-use-tool.js";
-import { isPersonalConversation } from "../../personal-agent/repository.js";
 import { PERSONAL_WORKER_RESULT_GUIDANCE } from "../../personal-agent/communication.js";
 import { randomUUID } from "node:crypto";
 import { Type } from "@sinclair/typebox";

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

@@ -2,5 +2,8 @@ import type { AgentTool } from '@earendil-works/pi-agent-core';
 export interface CreateReadFileToolOptions {
     /** When set and the path is a bare profile filename (e.g. SOUL.md), try this root if not in workspace. */
     profileMarkdownRoot?: string;
+    defaultMaxLines?: number;
+    maxOutputBytes?: number;
+    maxReadBytes?: number;
 }
 export declare function createReadFileTool(workspace: string, options?: CreateReadFileToolOptions): AgentTool;

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

@@ -1,7 +1,7 @@
 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 { formatSize, truncateHead } from "./truncate.js";
 import { isBareProfileMarkdownFileName, resolvePathUnderWorkspace, resolveProfileMarkdownPathIfBareName } from "./tool-paths.js";
 import { stat } from "fs/promises";
 import { Type } from "@sinclair/typebox";
@@ -29,11 +29,13 @@ function createReadFileTool(workspace, options) {
 		supportsParallel: true,
 		idempotent: true,
 		async execute(_toolCallId, params, signal) {
-			return dataScheduler.run(workspace, signal, () => executeReadFile(workspace, options?.profileMarkdownRoot, params, signal));
+			return dataScheduler.run(workspace, signal, () => executeReadFile(workspace, options, params, signal));
 		}
 	};
 }
-async function executeReadFile(workspace, profileMarkdownRoot, params, signal) {
+async function executeReadFile(workspace, options, params, signal) {
+	const profileMarkdownRoot = options?.profileMarkdownRoot;
+	const maxOutputBytes = options?.maxOutputBytes ?? 51200;
 	try {
 		const safety = checkFileSafety("read", params.path);
 		if (!safety.allowed) return {
@@ -60,6 +62,18 @@ async function executeReadFile(workspace, profileMarkdownRoot, params, signal) {
 				}
 			} else throw e;
 		}
+		if (options?.maxReadBytes && stats.size > options.maxReadBytes) return {
+			content: [{
+				type: "text",
+				text: `File is large (${formatSize(stats.size)}; local read limit ${formatSize(options.maxReadBytes)}). Tell the user briefly, then delegate reading and processing. Path: ${normalized}`
+			}],
+			details: {
+				path: normalized,
+				size: stats.size,
+				requiresSpecialist: true,
+				reason: "large_file"
+			}
+		};
 		if (stats.size > MAX_FILE_SIZE) return {
 			content: [{
 				type: "text",
@@ -72,12 +86,12 @@ async function executeReadFile(workspace, profileMarkdownRoot, params, signal) {
 		const lines = content.split("\n");
 		if (offset > lines.length) throw new Error(`Offset ${offset} exceeds ${lines.length} lines`);
 		const truncation = truncateHead(lines.slice(offset - 1).join("\n"), {
-			maxLines: params.limit || DEFAULT_MAX_LINES,
-			maxBytes: DEFAULT_MAX_BYTES
+			maxLines: params.limit || options?.defaultMaxLines || DEFAULT_MAX_LINES,
+			maxBytes: maxOutputBytes
 		});
 		let outputText = truncation.content;
-		if (truncation.truncated) if (truncation.firstLineExceedsLimit) outputText = `(Line exceeds ${formatSize(DEFAULT_MAX_BYTES)})`;
-		else outputText += `\n\n[Lines ${offset}-${offset + truncation.outputLines - 1} of ${lines.length}; continue with offset=${offset + truncation.outputLines}]`;
+		if (truncation.truncated) if (truncation.firstLineExceedsLimit) outputText = `(Line exceeds ${formatSize(maxOutputBytes)})`;
+		else outputText += options?.maxReadBytes ? `\n\n[File excerpt only. Tell the user briefly and delegate full reading and processing. Path: ${normalized}]` : `\n\n[Lines ${offset}-${offset + truncation.outputLines - 1} of ${lines.length}; continue with offset=${offset + truncation.outputLines}]`;
 		return {
 			content: [{
 				type: "text",
@@ -87,7 +101,11 @@ async function executeReadFile(workspace, profileMarkdownRoot, params, signal) {
 				path: normalized,
 				offset,
 				totalLines: lines.length,
-				truncated: truncation.truncated
+				truncated: truncation.truncated,
+				...options?.maxReadBytes && truncation.truncated ? {
+					requiresSpecialist: true,
+					reason: "large_file"
+				} : {}
 			}
 		};
 	} catch (error) {