@xopcai/xopc 0.0.385 → 0.0.387

package/dist/src/personal-agent/result-file-links.d.ts

@@ -0,0 +1,3 @@
+/** Preserve literal code; remove actionable local file references from prose. */
+export declare function sanitizePersonalResultFileLinks(text: string): string;
+export declare function hasPersonalResultFileLinks(text: string): boolean;

package/dist/src/personal-agent/result-file-links.js

@@ -0,0 +1,21 @@
+//#region src/personal-agent/result-file-links.ts
+/** File delivery belongs to structured artifacts, not model-authored host links. */
+function localTarget(value) {
+	let target = value.trim().replace(/^<|>$/g, "").replace(/\\([\\/])/g, "$1");
+	try {
+		target = decodeURIComponent(target);
+	} catch {}
+	return /^(?:\/|\\\\|~\/|\.\.?\/|[a-z]:[\\/]|file:|media:|xopc:\/\/workspace\/file)/i.test(target) || /^[^\s:?#]+\.(?:md|pdf|docx?|xlsx?|csv|pptx?|zip|png|jpe?g|webp|mp[34]|wav)(?:[?#].*)?$/i.test(target);
+}
+function cleanSegment(text) {
+	return text.replace(/^\s*MEDIA\s*:\s*.*$/gim, "").replace(/!?\[([^\]\n]*)\]\(\s*(<[^>]+>|[^\s)]+)(?:\s+["'][^\n]*?["'])?\s*\)/g, (match, label, target) => localTarget(target) ? label : match).replace(/^\s*\[[^\]\n]+\]:\s*(<[^>]+>|\S+).*$/gm, (match, target) => localTarget(target) ? "" : match).replace(/<([^<>\n]+)>/g, (match, target) => localTarget(target) ? "" : match).replace(/\b(?:file:\/\/|media:\/\/|xopc:\/\/workspace\/file)[^\s<>"'`]+/gi, "").replace(/(?<![\w:/])(?:\/(?:Users|home|tmp|private|workspace|var)\/|[a-z]:[\\/])[^\s<>"'`]+/gi, "");
+}
+/** Preserve literal code; remove actionable local file references from prose. */
+function sanitizePersonalResultFileLinks(text) {
+	return text.split(/(```[\s\S]*?```|~~~[\s\S]*?~~~|`[^`\n]+`)/g).map((part, index) => index % 2 ? part : cleanSegment(part)).join("").trim();
+}
+function hasPersonalResultFileLinks(text) {
+	return sanitizePersonalResultFileLinks(text) !== text.trim();
+}
+//#endregion
+export { hasPersonalResultFileLinks, sanitizePersonalResultFileLinks };

package/dist/src/personal-agent/result-read-continuations.d.ts

@@ -0,0 +1,13 @@
+import { type PersonalResultInput } from './result-reader.js';
+/** Preserve the original question while a cold extraction runs; no new business Task. */
+export declare function waitForPersonalResult(conversationId: string, request: PersonalResultInput): boolean;
+/** Existing result dispatch owns scheduling; stable input IDs recover an enqueue crash. */
+export declare function drainPersonalResultReads(options: {
+    isAvailable: (conversationId: string) => boolean;
+    submit: (input: {
+        conversationId: string;
+        clientMessageId: string;
+        expectedTranscriptId: string;
+        content: string;
+    }) => Promise<boolean>;
+}): Promise<void>;

package/dist/src/personal-agent/result-read-continuations.js

@@ -0,0 +1,78 @@
+import { getSqliteDatabase, init_transaction } from "../storage/sqlite/transaction.js";
+import { init_session_instance_repository, readCurrentTranscriptId } from "../storage/sqlite/session-instance-repository.js";
+import { findSessionInput, getSessionInputById, getSessionInputState, init_session_input_repository } from "../storage/sqlite/session-input-repository.js";
+import { readPersonalResult } from "./result-reader.js";
+import { personalConversationState } from "./conversation-state.js";
+//#region src/personal-agent/result-read-continuations.ts
+init_session_input_repository();
+init_session_instance_repository();
+init_transaction();
+/** Preserve the original question while a cold extraction runs; no new business Task. */
+function waitForPersonalResult(conversationId, request) {
+	const db = getSqliteDatabase();
+	const inputId = getSessionInputState(conversationId).activeInputId;
+	const input = inputId ? getSessionInputById(conversationId, inputId) : void 0;
+	const transcriptId = readCurrentTranscriptId(db, conversationId);
+	if (!input || !transcriptId || input.clientMessageId.startsWith("personal-result-read:")) return false;
+	const stored = db.prepare("SELECT requests_json FROM personal_result_read_waits WHERE input_id = ?").get(input.id);
+	const requests = stored ? JSON.parse(stored.requests_json) : [];
+	if (!requests.some((item) => JSON.stringify(item) === JSON.stringify(request)) && requests.length < 5) requests.push(request);
+	db.prepare(`INSERT INTO personal_result_read_waits(input_id, conversation_id, transcript_id, requests_json)
+    VALUES (?, ?, ?, ?) ON CONFLICT(input_id) DO UPDATE SET requests_json = excluded.requests_json`).run(input.id, conversationId, transcriptId, JSON.stringify(requests));
+	return true;
+}
+/** Existing result dispatch owns scheduling; stable input IDs recover an enqueue crash. */
+async function drainPersonalResultReads(options) {
+	const db = getSqliteDatabase();
+	const rows = db.prepare("SELECT * FROM personal_result_read_waits WHERE status IN ('pending','queued') LIMIT 20").all();
+	for (const row of rows) {
+		const original = getSessionInputById(row.conversation_id, row.input_id);
+		const update = (status) => db.prepare("UPDATE personal_result_read_waits SET status = ? WHERE input_id = ?").run(status, row.input_id);
+		if (!original || [
+			"cancelled",
+			"interrupted",
+			"failed"
+		].includes(original.status) || readCurrentTranscriptId(db, row.conversation_id) !== row.transcript_id) {
+			update("stale");
+			continue;
+		}
+		const clientMessageId = `personal-result-read:${row.input_id}`;
+		const queued = findSessionInput(row.conversation_id, clientMessageId);
+		if (queued) {
+			update(queued.status === "completed" ? "done" : [
+				"failed",
+				"cancelled",
+				"interrupted"
+			].includes(queued.status) ? "stale" : "queued");
+			continue;
+		}
+		if (original.status !== "completed" || !personalConversationState(row.conversation_id).idle || !options.isAvailable(row.conversation_id)) continue;
+		const requests = JSON.parse(row.requests_json);
+		const states = [];
+		let pending = false;
+		for (const request of requests) try {
+			const value = await readPersonalResult(row.conversation_id, request);
+			if (value.status === "preparing") pending = true;
+			states.push({
+				request,
+				status: value.status,
+				reason: value.reason ?? value.error
+			});
+		} catch {
+			states.push({
+				request,
+				status: "unavailable"
+			});
+		}
+		if (pending) continue;
+		if (readCurrentTranscriptId(db, row.conversation_id) !== row.transcript_id || !personalConversationState(row.conversation_id).idle) continue;
+		if (await options.submit({
+			conversationId: row.conversation_id,
+			clientMessageId,
+			expectedTranscriptId: row.transcript_id,
+			content: `Continue the existing user's result question after background text preparation. This is a read-only continuation, not a new Task or authorization. Read the prepared ranges with personal_result and answer the original question. Respect later user corrections; explain actual access failures. Do not recreate artifacts or execute new work.\nOriginal question (data): ${JSON.stringify(original.content)}\nPrepared reads (data): ${JSON.stringify(states)}`
+		})) update("queued");
+	}
+}
+//#endregion
+export { drainPersonalResultReads, waitForPersonalResult };

package/dist/src/personal-agent/result-reader.d.ts

@@ -0,0 +1,43 @@
+import { type TaskResultDelivery } from '@xopcai/gateway-contract';
+export interface PersonalResultInput {
+    command: 'list' | 'get' | 'read' | 'search';
+    resultId?: string;
+    taskId?: string;
+    sourceId?: string;
+    revision?: string;
+    sectionId?: string;
+    offset?: number;
+    limit?: number;
+    query?: string;
+    cursor?: string;
+}
+/** A delegated reader must retain the source account's current Agent access restrictions. */
+export declare function assertPersonalResultDelegateAccess(conversationId: string, delivery: TaskResultDelivery, agentId: string): void;
+export declare function resolvePersonalResultReference(conversationId: string, resultId: string): TaskResultDelivery;
+/** Retry only an exhausted delivery outbox; never reopen execution, parsing, or a historical revision. */
+export declare function retryPersonalResultDelivery(conversationId: string, resultId: string): Record<string, unknown>;
+/** Metadata-only directory; no extraction, model calls or file IO on the prompt path. */
+export declare function listPersonalResults(conversationId: string, options?: {
+    taskId?: string;
+    limit?: number;
+    offset?: number;
+}): {
+    offset: number;
+    nextOffset?: number;
+    items: {
+        resultId: string;
+        taskId: unknown;
+        title: string;
+        runId: unknown;
+        status: unknown;
+        deliveryState: unknown;
+        baselineVersion: string;
+        resultRevision: unknown;
+        previousResultId: unknown;
+        createdAt: unknown;
+    }[];
+};
+export declare function stopPersonalResultPreparations(): Promise<void>;
+/** Warm only bounded source counts after delivery; never wait for a parser or hold a main conversation lock. */
+export declare function warmPersonalResult(conversationId: string, resultId: string): void;
+export declare function readPersonalResult(conversationId: string, raw: PersonalResultInput): Promise<Record<string, unknown>>;

package/dist/src/personal-agent/result-reader.js

@@ -0,0 +1,461 @@
+import { createLogger } from "../utils/logger/index.js";
+import { init_logger } from "../utils/logger.js";
+import { getSqliteDatabase, init_transaction, runSqliteWriteTransaction } from "../storage/sqlite/transaction.js";
+import { TaskResultDeliverySchema } from "../../packages/gateway-contract/src/task-result-delivery.js";
+import { init_src } from "../../packages/gateway-contract/src/index.js";
+import { init_session_instance_repository, readCurrentTranscriptId } from "../storage/sqlite/session-instance-repository.js";
+import { init_request_repository, personalRequestForTask } from "./request-repository.js";
+import { getConnectorAccount, init_connector_account_repository } from "../storage/sqlite/connector-account-repository.js";
+import { getConnectorConnection, getConnectorInstallation, init_connector_repository } from "../storage/sqlite/connector-repository.js";
+import { isPersonalConversation } from "./repository.js";
+import { canAccessConnectorAccount } from "../connectors/account-access.js";
+import { connectorPrincipalForSession } from "../connectors/principal.js";
+import { resolveMediaReference } from "../media/media-reference.js";
+import { createRequire } from "node:module";
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { createHash, randomUUID } from "node:crypto";
+import { lstat } from "node:fs/promises";
+import { Worker } from "node:worker_threads";
+//#region src/personal-agent/result-reader.ts
+init_src();
+init_connector_account_repository();
+init_connector_repository();
+init_session_instance_repository();
+init_transaction();
+init_logger();
+init_request_repository();
+const PARSER_VERSION = 1;
+const workers = /* @__PURE__ */ new Map();
+const shuttingDownWorkers = /* @__PURE__ */ new WeakSet();
+const log = createLogger("PersonalResultRead");
+let preparationGeneration = 0;
+const require = createRequire(import.meta.url);
+const hash = (value) => createHash("sha256").update(value).digest("hex");
+function databasePath() {
+	return getSqliteDatabase().prepare("PRAGMA database_list").all().find((row) => row.name === "main").file;
+}
+function assertAccess(conversationId, delivery) {
+	const db = getSqliteDatabase();
+	if (!isPersonalConversation(conversationId) || delivery.conversationId !== conversationId || !readCurrentTranscriptId(db, conversationId) || !db.prepare("SELECT 1 FROM task_origin_links WHERE task_id = ? AND conversation_id = ?").get(delivery.taskId, conversationId)) throw new Error("Result is unavailable in this conversation");
+	const request = personalRequestForTask(delivery.taskId);
+	if (!request) return;
+	const principal = connectorPrincipalForSession(conversationId);
+	const account = request.accountId ? getConnectorAccount(request.accountId) : void 0;
+	const connection = account?.currentConnectionId ? getConnectorConnection(account.currentConnectionId) : void 0;
+	const installation = getConnectorInstallation(`${request.connectorId}-${principal.principalId}`);
+	if (request.state === "cancelled" || request.transcriptId !== readCurrentTranscriptId(db, conversationId) || !principal.isLocalOwner || !installation || !connection || connection.status !== "active" || account?.connectorId !== request.connectorId || !canAccessConnectorAccount(connection, installation, principal.agentId) || !canAccessConnectorAccount(connection, installation, request.executorAgentId)) throw new Error("Result account access is no longer available");
+}
+function resolve(conversationId, resultId) {
+	const row = getSqliteDatabase().prepare(`SELECT delivery_id, payload_json, reply_payload_json, status FROM task_result_deliveries
+    WHERE delivery_id = ? AND conversation_id = ? AND status IN ('pending','delivered','stale','failed')`).get(resultId, conversationId);
+	if (!row) throw new Error("Result is unavailable in this conversation");
+	const delivery = TaskResultDeliverySchema.parse(JSON.parse(row.payload_json));
+	assertAccess(conversationId, delivery);
+	return {
+		row,
+		delivery
+	};
+}
+/** A delegated reader must retain the source account's current Agent access restrictions. */
+function assertPersonalResultDelegateAccess(conversationId, delivery, agentId) {
+	assertAccess(conversationId, delivery);
+	const request = personalRequestForTask(delivery.taskId);
+	if (!request) return;
+	const principal = connectorPrincipalForSession(conversationId);
+	const account = request.accountId ? getConnectorAccount(request.accountId) : void 0;
+	const connection = account?.currentConnectionId ? getConnectorConnection(account.currentConnectionId) : void 0;
+	const installation = getConnectorInstallation(`${request.connectorId}-${principal.principalId}`);
+	if (!connection || !installation || !canAccessConnectorAccount(connection, installation, agentId)) throw new Error("Result account access does not permit this Task executor");
+}
+function resolvePersonalResultReference(conversationId, resultId) {
+	return resolve(conversationId, resultId).delivery;
+}
+/** Retry only an exhausted delivery outbox; never reopen execution, parsing, or a historical revision. */
+function retryPersonalResultDelivery(conversationId, resultId) {
+	const { delivery } = resolve(conversationId, resultId);
+	return runSqliteWriteTransaction((db) => {
+		const task = db.prepare("SELECT latest_contract_version, resolution FROM tasks WHERE task_id = ?").get(delivery.taskId);
+		const latest = db.prepare("SELECT run_id, status FROM task_runs WHERE task_id = ? AND parent_run_id IS NULL ORDER BY queued_at DESC, rowid DESC LIMIT 1").get(delivery.taskId);
+		if (!latest || latest.run_id !== delivery.taskRunId || !["succeeded", "failed"].includes(latest.status) || task.resolution && task.resolution !== "done" || delivery.contractVersion !== void 0 && delivery.contractVersion !== task.latest_contract_version || delivery.instructionSequence !== void 0 && delivery.instructionSequence !== Number(db.prepare("SELECT COALESCE(MAX(sequence),0) AS n FROM task_collaboration_entries WHERE task_id = ? AND author_kind IN ('main_agent','user') AND kind IN ('instruction','answer')").get(delivery.taskId)?.n ?? 0)) return {
+			retryQueued: false,
+			resultId,
+			reason: "historical_or_changed_requirements",
+			guidance: "Read this historical result. Do not resend it as the completion of newer or cancelled work."
+		};
+		const row = db.prepare("SELECT status, notified_at, reply_attempts, reply_notified_at FROM task_result_deliveries WHERE delivery_id = ?").get(resultId);
+		if (row.status !== "failed" && row.notified_at !== -1 && row.reply_attempts < 8 && row.reply_notified_at !== -1) return {
+			retryQueued: false,
+			resultId,
+			reason: "already_pending_or_delivered"
+		};
+		db.prepare(`UPDATE task_result_deliveries SET status = CASE WHEN status = 'failed' THEN 'pending' ELSE status END,
+      attempts = 0, next_attempt_at = 0, last_error = NULL, notified_at = CASE WHEN status = 'failed' OR notified_at = -1 THEN NULL ELSE notified_at END,
+      reply_attempts = 0, reply_next_attempt_at = 0, reply_last_error = NULL, reply_lease_until = 0, reply_lease_token = NULL,
+      reply_notified_at = CASE WHEN reply_notified_at = -1 THEN NULL ELSE reply_notified_at END WHERE delivery_id = ?`).run(resultId);
+		return {
+			retryQueued: true,
+			resultId,
+			taskId: delivery.taskId,
+			scope: "delivery_only",
+			executionRestarted: false
+		};
+	});
+}
+/** Metadata-only directory; no extraction, model calls or file IO on the prompt path. */
+function listPersonalResults(conversationId, options = {}) {
+	const db = getSqliteDatabase();
+	const limit = Math.min(10, Math.max(1, options.limit ?? 5));
+	const offset = Math.max(0, options.offset ?? 0);
+	const rows = db.prepare(`SELECT delivery_id, json_extract(payload_json, '$.taskId') AS taskId,
+    json_extract(payload_json, '$.taskTitle') AS title, json_extract(payload_json, '$.taskRunId') AS runId,
+    status AS deliveryState, json_extract(payload_json, '$.assignmentEpoch') AS assignmentEpoch, json_extract(payload_json, '$.outcome.outcomeId') AS outcomeId,
+    json_extract(payload_json, '$.outcome.status') AS status, json_extract(payload_json, '$.resultRevision') AS resultRevision,
+    json_extract(payload_json, '$.previousResultId') AS previousResultId, created_at AS createdAt
+    FROM task_result_deliveries WHERE conversation_id = ? AND status IN ('pending','delivered','stale','failed')
+    AND (? IS NULL OR json_extract(payload_json, '$.taskId') = ?)
+    ORDER BY created_at DESC, delivery_id DESC LIMIT ? OFFSET ?`).all(conversationId, options.taskId ?? null, options.taskId ?? null, limit + 1, offset);
+	return {
+		items: rows.slice(0, limit).flatMap((row) => {
+			try {
+				assertAccess(conversationId, {
+					taskId: String(row.taskId),
+					conversationId
+				});
+				return [{
+					resultId: String(row.delivery_id),
+					taskId: row.taskId,
+					title: String(row.title).slice(0, 200),
+					runId: row.runId,
+					status: row.status,
+					deliveryState: row.deliveryState,
+					baselineVersion: `${row.runId}:${row.assignmentEpoch}:${row.outcomeId}`,
+					resultRevision: row.resultRevision ?? 1,
+					previousResultId: row.previousResultId,
+					createdAt: row.createdAt
+				}];
+			} catch {
+				return [];
+			}
+		}),
+		...rows.length > limit ? { nextOffset: offset + limit } : {},
+		offset
+	};
+}
+function documentRow(documentId) {
+	return getSqliteDatabase().prepare(`SELECT document_id, status, content_revision, sections_json, limitations_json, fingerprint,
+    error, length(content) AS length, lease_until FROM personal_result_documents WHERE document_id = ?`).get(documentId);
+}
+function launch(input) {
+	if (workers.size >= 2) return false;
+	const entry = new URL("./result-extraction.js", import.meta.url);
+	const source = existsSync(fileURLToPath(entry)) ? entry.href : new URL("./result-extraction.ts", import.meta.url).href;
+	const worker = new Worker(`
+    const { workerData, parentPort } = require('node:worker_threads');
+    (async () => {
+      const module = workerData.source.endsWith('.ts')
+        ? await require(workerData.tsx).tsImport(workerData.source, workerData.source)
+        : await import(workerData.source);
+      await module.prepareResultDocument(workerData.input);
+      parentPort.postMessage('complete');
+    })().catch(error => { throw error; });
+  `, {
+		eval: true,
+		execArgv: [],
+		resourceLimits: { maxOldGenerationSizeMb: 256 },
+		workerData: {
+			source,
+			...source.endsWith(".ts") ? { tsx: require.resolve("tsx/esm/api") } : {},
+			input
+		}
+	});
+	const key = `${input.database}:${input.documentId}`;
+	workers.set(key, worker);
+	const fail = (err) => {
+		if (shuttingDownWorkers.has(worker)) return;
+		try {
+			if (getSqliteDatabase().prepare(`UPDATE personal_result_documents SET status = 'failed', error = ?,
+        lease_until = 0 WHERE document_id = ? AND status = 'pending' AND lease_token = ?`).run((err?.message ?? "Background preparation stopped").slice(0, 500), input.documentId, input.lease).changes) log.warn({
+				err,
+				documentId: input.documentId,
+				phase: "result_preparation"
+			}, "Background result preparation stopped");
+		} catch {}
+	};
+	const timer = setTimeout(() => {
+		fail();
+		worker.terminate();
+	}, 45e3);
+	timer.unref();
+	worker.once("error", fail);
+	worker.once("exit", () => {
+		clearTimeout(timer);
+		workers.delete(key);
+		fail();
+	});
+	worker.unref();
+	return true;
+}
+async function stopPersonalResultPreparations() {
+	preparationGeneration++;
+	for (const worker of workers.values()) shuttingDownWorkers.add(worker);
+	try {
+		getSqliteDatabase().prepare("UPDATE personal_result_documents SET lease_until = 0 WHERE status = 'pending' AND lease_token LIKE ?").run(`${process.pid}:%`);
+	} catch {}
+	await Promise.all([...workers.values()].map((worker) => worker.terminate()));
+	workers.clear();
+}
+async function prepare(conversationId, resultId, sourceId) {
+	const { row, delivery } = resolve(conversationId, resultId);
+	const documentId = hash(`${resultId}:${sourceId}:parser:${PARSER_VERSION}`);
+	const db = getSqliteDatabase();
+	let file;
+	let expectedSha256;
+	let text;
+	let title = delivery.taskTitle;
+	let mimeType;
+	if (sourceId === "body") {
+		const packet = row.reply_payload_json ? JSON.parse(row.reply_payload_json) : void 0;
+		text = delivery.text ?? (packet ? [packet.report, packet.preservedText].filter(Boolean).join("\n\n") : void 0);
+		if (!text) return {
+			status: "unavailable",
+			reason: "No complete result body was retained. Read an artifact; the summary is not the full result."
+		};
+	} else {
+		const artifact = delivery.outcome.deliverables.find((item) => item.artifactId === sourceId);
+		if (!artifact || artifact.availability !== "available" || !artifact.uri?.startsWith("media://")) return {
+			status: "unavailable",
+			reason: "No readable published artifact for this source ID"
+		};
+		({path: file} = await resolveMediaReference(artifact.uri));
+		expectedSha256 = artifact.sha256;
+		title = artifact.title;
+		mimeType = artifact.mimeType;
+	}
+	const existing = documentRow(documentId);
+	if (file) {
+		const info = await lstat(file).catch(() => void 0);
+		if (!info?.isFile()) return {
+			status: "unavailable",
+			reason: "Published file is missing or is not a regular file"
+		};
+		const fingerprint = `${info.size}:${info.mtimeMs}:${info.ctimeMs}`;
+		if (existing?.status === "ready" && fingerprint !== existing.fingerprint) return {
+			status: "changed",
+			reason: "Published bytes changed; the indexed version is not current"
+		};
+	}
+	resolve(conversationId, resultId);
+	if (existing && existing.status !== "pending") return {
+		...existing,
+		documentId
+	};
+	let ownerAlive = true;
+	const owner = db.prepare("SELECT lease_token FROM personal_result_documents WHERE document_id = ?").get(documentId)?.lease_token;
+	if (typeof owner === "string" && /^\d+:/.test(owner)) try {
+		process.kill(Number(owner.split(":")[0]), 0);
+	} catch {
+		ownerAlive = false;
+	}
+	if (existing && existing.lease_until > Date.now() && ownerAlive) return {
+		status: "preparing",
+		preparationId: documentId
+	};
+	if (existing && !ownerAlive) db.prepare("UPDATE personal_result_documents SET lease_until = 0 WHERE document_id = ? AND lease_token = ?").run(documentId, owner);
+	if (workers.size >= 2) return {
+		status: "preparing",
+		preparationId: documentId,
+		reason: "Preparation capacity is busy; retry this same read later"
+	};
+	const lease = `${process.pid}:${randomUUID()}`;
+	if (db.prepare(`INSERT INTO personal_result_documents(document_id, delivery_id, source_id, status, parser_version, lease_token, lease_until)
+    VALUES (?, ?, ?, 'pending', ?, ?, ?) ON CONFLICT(document_id) DO UPDATE SET lease_token = excluded.lease_token,
+    lease_until = excluded.lease_until WHERE personal_result_documents.status = 'pending' AND personal_result_documents.lease_until <= ?`).run(documentId, resultId, sourceId, PARSER_VERSION, lease, Date.now() + 5e4, Date.now()).changes) launch({
+		database: databasePath(),
+		documentId,
+		lease,
+		file,
+		expectedSha256,
+		title,
+		mimeType,
+		text
+	});
+	return {
+		status: "preparing",
+		preparationId: documentId
+	};
+}
+/** Warm only bounded source counts after delivery; never wait for a parser or hold a main conversation lock. */
+function warmPersonalResult(conversationId, resultId) {
+	const generation = preparationGeneration;
+	setImmediate(() => {
+		if (generation !== preparationGeneration) return;
+		try {
+			const { delivery } = resolve(conversationId, resultId);
+			const sources = ["body", ...delivery.outcome.deliverables.slice(0, 50).map((item) => item.artifactId)];
+			(async () => {
+				for (const sourceId of sources) {
+					if (generation !== preparationGeneration) return;
+					await prepare(conversationId, resultId, sourceId);
+					while (workers.size >= 2 && generation === preparationGeneration) await new Promise((resolve) => {
+						setTimeout(resolve, 100).unref();
+					});
+				}
+			})().catch(() => {});
+		} catch {}
+	});
+}
+async function readPersonalResult(conversationId, raw) {
+	if (raw.command === "list") return listPersonalResults(conversationId, raw);
+	const input = { ...raw };
+	if (!input.resultId) throw new Error("resultId is required; use list to discover results");
+	const { delivery, row } = resolve(conversationId, input.resultId);
+	const sourceId = input.sourceId ?? "body";
+	const scope = hash(JSON.stringify([
+		input.resultId,
+		sourceId,
+		input.command,
+		input.query,
+		input.sectionId
+	]));
+	if (input.cursor) {
+		if (input.cursor.length > 1024) throw new Error("Invalid result cursor");
+		if (JSON.parse(Buffer.from(input.cursor, "base64url").toString("utf8")).scope !== scope) throw new Error("Cursor belongs to a different result, query or revision");
+	}
+	const current = getSqliteDatabase().prepare("SELECT latest_contract_version FROM tasks WHERE task_id = ?").get(delivery.taskId);
+	const base = {
+		...delivery.contractVersion === void 0 ? {} : { currentRequirementsSatisfied: delivery.contractVersion === current.latest_contract_version && delivery.outcome.status === "succeeded" && delivery.instructionSequence === Number(getSqliteDatabase().prepare("SELECT COALESCE(MAX(sequence),0) AS n FROM task_collaboration_entries WHERE task_id = ? AND author_kind IN ('main_agent','user') AND kind IN ('instruction','answer')").get(delivery.taskId)?.n ?? 0) },
+		deliveryState: row.status,
+		resultId: input.resultId,
+		taskId: delivery.taskId,
+		runId: delivery.taskRunId,
+		sourceId
+	};
+	if (input.command === "get" && !input.sourceId) {
+		const offset = input.offset ?? 0;
+		const limit = Math.min(10, input.limit ?? 10);
+		return {
+			...base,
+			status: delivery.outcome.status,
+			baselineVersion: `${delivery.taskRunId}:${delivery.assignmentEpoch}:${delivery.outcome.outcomeId}`,
+			resultRevision: delivery.resultRevision ?? 1,
+			previousResultId: delivery.previousResultId,
+			contractVersion: delivery.contractVersion,
+			instructionSequence: delivery.instructionSequence,
+			adoption: delivery.adoption?.slice(offset, offset + limit),
+			...delivery.adoption && offset + limit < delivery.adoption.length ? { nextAdoptionOffset: offset + limit } : {},
+			body: {
+				sourceId: "body",
+				description: "Retained execution result, not the composed chat reply"
+			},
+			sources: delivery.outcome.deliverables.slice(offset, offset + limit).map((item) => ({
+				sourceId: item.artifactId,
+				title: item.title.slice(0, 200),
+				kind: item.kind,
+				availability: item.availability,
+				mimeType: item.mimeType
+			})),
+			...offset + limit < delivery.outcome.deliverables.length ? { nextOffset: offset + limit } : {},
+			guidance: "Use read/search with sourceId=body or an exact artifact sourceId. Omitted chat text is available here when retained."
+		};
+	}
+	const prepared = await prepare(conversationId, input.resultId, sourceId);
+	if (prepared.status !== "ready") return {
+		...base,
+		...prepared,
+		complete: false
+	};
+	const doc = prepared;
+	if (input.revision && input.revision !== doc.content_revision) throw new Error("Result content revision changed");
+	let offset = Math.max(0, input.offset ?? 0);
+	const binding = hash(JSON.stringify([
+		input.resultId,
+		sourceId,
+		doc.content_revision,
+		input.command,
+		input.query,
+		input.sectionId
+	]));
+	if (input.cursor) {
+		if (input.cursor.length > 1024) throw new Error("Invalid result cursor");
+		const cursor = JSON.parse(Buffer.from(input.cursor, "base64url").toString("utf8"));
+		if (cursor.binding !== binding || !Number.isSafeInteger(cursor.offset) || cursor.offset < 0) throw new Error("Cursor belongs to a different result, query or revision");
+		offset = cursor.offset;
+	}
+	const cursorAt = (next) => Buffer.from(JSON.stringify({
+		binding,
+		scope,
+		offset: next
+	})).toString("base64url");
+	const metadata = {
+		...base,
+		revision: doc.content_revision,
+		status: "ready",
+		representation: "extracted_text",
+		limitations: JSON.parse(doc.limitations_json),
+		totalChars: doc.length
+	};
+	const sectionFromRow = (row) => ({
+		id: String(row.section_id),
+		title: String(row.title),
+		offset: Number(row.start_offset),
+		length: Number(row.char_length),
+		locator: JSON.parse(String(row.locator_json))
+	});
+	const db = getSqliteDatabase();
+	if (input.command === "get") {
+		const limit = Math.min(10, input.limit ?? 10);
+		const rows = db.prepare("SELECT * FROM personal_result_sections WHERE document_id = ? ORDER BY ordinal LIMIT ? OFFSET ?").all(doc.documentId, limit + 1, offset);
+		return {
+			...metadata,
+			sections: rows.slice(0, limit).map(sectionFromRow),
+			...rows.length > limit ? { nextCursor: cursorAt(offset + limit) } : {},
+			complete: rows.length <= limit
+		};
+	}
+	if (input.command === "search") {
+		const query = input.query?.trim();
+		if (!query || [...query].length < 3 || query.length > 500) throw new Error("Search requires 3–500 characters; use read for shorter terms");
+		const limit = Math.min(5, Math.max(1, input.limit ?? 5));
+		const rows = db.prepare(`SELECT CAST(start_offset AS INTEGER) AS offset, text
+      FROM personal_result_search WHERE personal_result_search MATCH ? AND document_id = ?
+      ORDER BY CAST(start_offset AS INTEGER) LIMIT ? OFFSET ?`).all(`"${query.replaceAll("\"", "\"\"")}"`, doc.documentId, limit + 1, offset);
+		const items = rows.slice(0, limit).map((row) => {
+			const start = Math.max(0, row.text.toLowerCase().indexOf(query.toLowerCase()) - 120);
+			const hitOffset = row.offset + [...row.text.slice(0, start)].length;
+			return {
+				offset: hitOffset,
+				text: row.text.slice(start, start + 800),
+				section: db.prepare(`SELECT section_id FROM personal_result_sections WHERE document_id = ?
+        AND start_offset <= ? AND start_offset + char_length > ? ORDER BY ordinal DESC LIMIT 1`).get(doc.documentId, hitOffset, hitOffset)?.section_id
+			};
+		});
+		return {
+			...metadata,
+			query,
+			items,
+			complete: rows.length <= limit,
+			...rows.length > limit ? { nextCursor: cursorAt(offset + items.length) } : {}
+		};
+	}
+	const sectionRow = input.sectionId ? db.prepare("SELECT * FROM personal_result_sections WHERE document_id = ? AND section_id = ?").get(doc.documentId, input.sectionId) : void 0;
+	const section = sectionRow ? sectionFromRow(sectionRow) : void 0;
+	if (input.sectionId && !section) throw new Error("Section is unavailable");
+	const start = section?.offset ?? 0;
+	const length = section?.length ?? doc.length;
+	if (offset > length) throw new Error("Offset exceeds source range");
+	const count = Math.min(4e3, Math.max(1, input.limit ?? 4e3), length - offset);
+	const value = db.prepare("SELECT substr(content, ?, ?) AS text FROM personal_result_documents WHERE document_id = ?").get(start + offset + 1, count, doc.documentId);
+	const next = offset + [...value.text].length;
+	return {
+		...metadata,
+		section,
+		offset,
+		text: value.text,
+		rangeComplete: next >= length,
+		complete: !section && next >= length,
+		...next < length ? { nextCursor: cursorAt(next) } : {}
+	};
+}
+//#endregion
+export { assertPersonalResultDelegateAccess, listPersonalResults, readPersonalResult, resolvePersonalResultReference, retryPersonalResultDelivery, stopPersonalResultPreparations, warmPersonalResult };

package/dist/src/personal-agent/service.js

@@ -1,15 +1,15 @@
 import { getSessionMetadata } from "../storage/sqlite/session-read-repository.js";
 import { init_session_repository, patchSessionMetadata } from "../storage/sqlite/session-repository.js";
 import { init_config_repository, setSessionConfig } from "../storage/sqlite/config-repository.js";
+import { createConversation, init_conversation_repository } from "../storage/sqlite/conversation-repository.js";
 import { ResponsePreferencesSchema } from "../agent-config/schema.js";
 import { init_agent_config } from "../agent-config/index.js";
 import { AgentCatalogRepository, init_repository } from "../agent-catalog/repository.js";
-import { AgentCatalogService } from "../agent-catalog/service.js";
-import { createConversation, init_conversation_repository } from "../storage/sqlite/conversation-repository.js";
 import { getAvailableModels, init_providers } from "../providers/index.js";
 import { DEFAULT_PERSONAL_PREFERENCES, getPersonalAgent, personalAgentId } from "./repository.js";
 import { PERSONAL_MAIN_TOOL_IDS, PERSONAL_READ_TOOL_ALIASES } from "./policy.js";
 import { getModelThinking } from "../providers/model-thinking.js";
+import { AgentCatalogService } from "../agent-catalog/service.js";
 import { personalInstructions, upgradePersonalInstructions } from "./prompts.js";
 import { completePersonalOnboarding } from "./onboarding.js";
 import { z } from "zod";