@xopcai/xopc 0.0.384 → 0.0.386

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

@@ -1,13 +1,23 @@
-import { getSqliteDatabase, init_transaction } from "../../storage/sqlite/transaction.js";
-import { getPersonalRequest, init_request_repository, listPersonalRequests } from "../../personal-agent/request-repository.js";
+import { getSqliteDatabase, init_transaction, runSqliteWriteTransaction } from "../../storage/sqlite/transaction.js";
+import { init_session_instance_repository, readCurrentTranscriptId } from "../../storage/sqlite/session-instance-repository.js";
+import { getSessionInputState, init_session_input_repository } from "../../storage/sqlite/session-input-repository.js";
+import { getPersonalRequest, init_request_repository, listPersonalRequests, updatePersonalRequest } from "../../personal-agent/request-repository.js";
+import { getActiveConnectionWait, init_connection_wait_repository, reviseCurrentConnectionObjective, updateConnectionWait } from "../../storage/sqlite/connection-wait-repository.js";
+import { getSessionMetadata } from "../../storage/sqlite/session-read-repository.js";
+import { init_session_repository } from "../../storage/sqlite/session-repository.js";
 import { isPersonalConversation } from "../../personal-agent/repository.js";
 import { TaskAllocationRepository } from "../../tasks/task-allocation-repository.js";
 import { boundedPersonalResult } from "./personal-result-budget.js";
-import { cancelPersonalTask } from "../../personal-agent/task-cancel.js";
+import { selectionRequestHash } from "../../agent-matching/selection-repository.js";
+import { createPersonalTaskTool } from "./personal-task-tool.js";
 import { personalCapabilities } from "../../personal-agent/capability-service.js";
-import { cancelPersonalRequest, personalRequestSnapshot, publishPersonalRequest, submitPersonalRequest } from "../../personal-agent/request-service.js";
+import { assertPersonalRequestTimeRange, cancelPersonalRequest, personalRequestSnapshot, publishPersonalRequest, stopPersonalRequestExecution, submitPersonalRequest } from "../../personal-agent/request-service.js";
 import { Type } from "@sinclair/typebox";
 //#region src/agent/tools/personal-request-tool.ts
+init_session_input_repository();
+init_session_repository();
+init_session_instance_repository();
+init_connection_wait_repository();
 init_request_repository();
 init_transaction();
 const CapabilitySchema = Type.Object({
@@ -22,8 +32,20 @@ const RequestSchema = Type.Object({
 		"submit",
 		"get",
 		"list",
-		"cancel"
+		"cancel",
+		"answer",
+		"instruct",
+		"collaboration",
+		"entry"
 	].map((command) => Type.Literal(command))),
+	instruction: Type.Optional(Type.String({
+		minLength: 1,
+		maxLength: 8e3
+	})),
+	questionId: Type.Optional(Type.String({ minLength: 1 })),
+	entryId: Type.Optional(Type.String({ minLength: 1 })),
+	afterSequence: Type.Optional(Type.Integer({ minimum: 0 })),
+	bodyOffset: Type.Optional(Type.Integer({ minimum: 0 })),
 	requestId: Type.Optional(Type.String()),
 	offset: Type.Optional(Type.Integer({ minimum: 0 })),
 	limit: Type.Optional(Type.Integer({
@@ -32,6 +54,11 @@ const RequestSchema = Type.Object({
 	})),
 	connectorId: Type.Optional(Type.String()),
 	accountId: Type.Optional(Type.String()),
+	description: Type.Optional(Type.String({
+		minLength: 1,
+		maxLength: 16e3,
+		description: "Complete task brief preserving all user requirements, stages, inputs, outputs and constraints. Do not replace exact specifications with a short objective or a reference to an unspecified process."
+	})),
 	objective: Type.Optional(Type.String({
 		minLength: 1,
 		maxLength: 4e3
@@ -51,12 +78,36 @@ const RequestSchema = Type.Object({
 	anyOf: [
 		{
 			properties: { command: { const: "submit" } },
-			required: ["objective", "connectorId"]
+			required: [
+				"objective",
+				"connectorId",
+				"description"
+			]
 		},
 		{ properties: { command: { const: "list" } } },
 		{
-			properties: { command: { enum: ["get", "cancel"] } },
+			properties: { command: { enum: [
+				"get",
+				"cancel",
+				"collaboration"
+			] } },
 			required: ["requestId"]
+		},
+		{
+			properties: { command: { const: "entry" } },
+			required: ["requestId", "entryId"]
+		},
+		{
+			properties: { command: { const: "instruct" } },
+			required: ["requestId", "instruction"]
+		},
+		{
+			properties: { command: { const: "answer" } },
+			required: [
+				"requestId",
+				"questionId",
+				"instruction"
+			]
 		}
 	]
 });
@@ -74,6 +125,20 @@ function createPersonalRequestTools(deps) {
 			...value.taskId ? { allocation: new TaskAllocationRepository().summary(value.taskId) } : {}
 		};
 	};
+	const compactSnapshot = (request) => {
+		const value = snapshot(request);
+		return {
+			requestId: value.requestId,
+			taskId: value.taskId,
+			state: value.state,
+			version: value.version,
+			connectorId: value.connectorId,
+			accountId: value.accountId,
+			executorAgentId: value.executorAgentId,
+			..."allocation" in value ? { allocation: value.allocation } : {},
+			parameters: { timeRange: value.parameters.timeRange }
+		};
+	};
 	const result = (value) => ({
 		content: [{
 			type: "text",
@@ -97,14 +162,18 @@ function createPersonalRequestTools(deps) {
 		name: "personal_request",
 		label: "Connected app request",
 		parameters: RequestSchema,
-		description: "Submit a read-only connected-app request using the exact connectorId from personal_capability. The background Task Router chooses an executor after account authorization. Preserves the objective, displays connection or account selection in this main chat, and starts a specialist Task automatically once connected. Return quickly after submission. Never claim data was read until the Task result arrives. Resolve absolute query dates and include timeRange. If mail has no user-specified range, the host returns an explicit last-7-days default; mention that range in your confirmation. Use paginated get/list for status without polling; preserve idempotencyKey on uncertain retries; cancel only when the user requests it.",
+		description: "Submit a read-only connected-app request with a short objective and complete description using the exact connectorId from personal_capability. The background Task Router chooses an executor after account authorization. Preserves the objective, displays connection or account selection in this main chat, and starts a specialist Task automatically once connected. Return quickly after submission. Never claim data was read until the Task result arrives. Resolve absolute query dates and include timeRange. If mail has no user-specified range, the host returns an explicit last-7-days default; state that range and proceed without asking for confirmation. get includes complete Task coordination state; collaboration/entry read the same board and full questions. answer forwards the exact questionId; instruct forwards new requirements to the existing Task. Answers and instructions cannot change the connector/account, grant access or allow writes; reconnection stays in the existing connection UI. Saved, delivered, executor-confirmed and verified are distinct states. Use get/list for status without polling; preserve idempotencyKey on uncertain retries; cancel only when the user requests it.",
 		async execute(toolCallId, input) {
 			const conversationId = conversation();
 			if (input.command === "list") {
 				const offset = input.offset ?? 0;
 				const items = listPersonalRequests(conversationId, input.limit ?? 10, offset).map((request) => {
-					const { result: _result, ...summary } = snapshot(request);
-					return summary;
+					const { result: _result, parameters, ...summary } = snapshot(request);
+					const { brief: _brief, taskRunId: _taskRunId, cancellationCleanupCompleted: _cleanup, ...queryParameters } = parameters;
+					return {
+						...summary,
+						parameters: queryParameters
+					};
 				});
 				const total = getSqliteDatabase().prepare("SELECT count(*) AS count FROM personal_requests WHERE conversation_id = ?").get(conversationId).count;
 				return result(boundedPersonalResult({
@@ -120,33 +189,106 @@ function createPersonalRequestTools(deps) {
 					connectorId: input.connectorId,
 					accountId: input.accountId,
 					objective: input.objective.trim(),
+					description: input.description?.trim(),
 					timeRange: input.timeRange,
-					idempotencyKey: input.idempotencyKey ?? toolCallId
+					idempotencyKey: input.idempotencyKey ?? `personal-request-submit:${selectionRequestHash({
+						inputId: getSessionInputState(conversationId).activeInputId ?? toolCallId,
+						objective: input.objective.trim(),
+						description: input.description?.trim(),
+						connectorId: input.connectorId,
+						accountId: input.accountId,
+						timeRange: input.timeRange
+					})}`
 				});
 				publishPersonalRequest(request);
 				deps.dispatchTaskRuns?.();
-				return result(boundedPersonalResult(snapshot(request)));
+				return result({
+					...compactSnapshot(request),
+					guidance: request.state === "waiting_connection" ? "The objective is saved. The host presents the required connection or account selection and continues automatically afterward. Stop this turn; do not ask the user to confirm the read or reply continue." : "The request was accepted. No further user confirmation is needed. Report the returned state accurately, do not submit a duplicate, and wait for delivery without polling."
+				});
 			}
 			const request = input.requestId ? getPersonalRequest(input.requestId) : void 0;
 			if (!request || request.conversationId !== conversationId) throw new Error("Request does not belong to this conversation");
 			if (input.command === "cancel") {
-				if (["completed", "failed"].includes(personalRequestSnapshot(request).state)) return result(boundedPersonalResult(snapshot(request)));
-				if (request.state === "cancelled") {
-					const stop = request.taskId ? await cancelPersonalTask(request.taskId, conversationId, input.idempotencyKey ?? toolCallId) : { executionStopConfirmed: true };
-					return result({
-						...snapshot(request),
-						executionStopConfirmed: stop.executionStopConfirmed
-					});
-				}
-				const stop = request.taskId ? await cancelPersonalTask(request.taskId, conversationId, input.idempotencyKey ?? toolCallId) : { executionStopConfirmed: true };
+				if (["completed", "failed"].includes(personalRequestSnapshot(request).state)) return result(compactSnapshot(request));
 				const cancelled = cancelPersonalRequest(request);
+				const stop = stopPersonalRequestExecution(cancelled);
 				publishPersonalRequest(cancelled);
 				return result({
-					...cancelled,
+					...compactSnapshot(cancelled),
 					executionStopConfirmed: stop.executionStopConfirmed
 				});
 			}
-			return result(boundedPersonalResult(snapshot(request)));
+			const taskTool = createPersonalTaskTool({
+				...deps,
+				getCurrentAgentId: () => deps.getCurrentAgentId?.() ?? getSessionMetadata(conversationId)?.agentId
+			});
+			if (input.command === "instruct" && input.timeRange) assertPersonalRequestTimeRange(input.timeRange);
+			const instruction = input.command === "instruct" && input.timeRange ? `${input.instruction}\n\nUpdated absolute query range: ${JSON.stringify(input.timeRange)}` : input.instruction;
+			if (input.command === "answer" || input.command === "instruct") {
+				if ([
+					"completed",
+					"failed",
+					"cancelled"
+				].includes(personalRequestSnapshot(request).state)) throw new Error("Request is no longer active");
+				if (readCurrentTranscriptId(getSqliteDatabase(), conversationId) !== request.transcriptId) throw new Error("SESSION_CHANGED");
+				if (!request.taskId && input.command === "instruct" && request.state === "waiting_connection") {
+					const addition = `\n\nSupplemental requirement:\n${instruction.trim()}`;
+					if (!request.objective.endsWith(addition)) runSqliteWriteTransaction(() => {
+						if (getActiveConnectionWait(conversationId)?.id !== request.connectionWaitId) throw new Error("Connection objective changed");
+						reviseCurrentConnectionObjective(conversationId, request.objective + addition);
+						const revised = getActiveConnectionWait(conversationId);
+						updateConnectionWait({
+							...revised,
+							checkpoint: {
+								...revised.checkpoint,
+								timeRange: input.timeRange ?? request.parameters.timeRange
+							}
+						}, revised.version);
+						updatePersonalRequest(request, {
+							objective: request.objective + addition,
+							parameters: {
+								...request.parameters,
+								...input.timeRange ? { timeRange: input.timeRange } : {}
+							}
+						});
+					});
+					return result({
+						...snapshot(getPersonalRequest(request.requestId)),
+						instructionStatus: "saved",
+						guidance: "Account authorization is still required. The existing Request will create its Task with this requirement after authorization."
+					});
+				}
+			}
+			if (input.command !== "get" || request.taskId) {
+				if (!request.taskId) throw new Error("No Task yet; complete account authorization in the main connection UI");
+				const coordinated = await taskTool.execute(toolCallId, {
+					...input,
+					instruction,
+					taskId: request.taskId
+				});
+				if (input.command === "instruct" && input.timeRange && JSON.parse(coordinated.content[0].text).ok === true) runSqliteWriteTransaction(() => {
+					const current = getPersonalRequest(request.requestId);
+					updatePersonalRequest(current, { parameters: {
+						...current.parameters,
+						timeRange: input.timeRange
+					} });
+					const wait = getActiveConnectionWait(conversationId);
+					if (wait && wait.id === current.connectionWaitId) updateConnectionWait({
+						...wait,
+						checkpoint: {
+							...wait.checkpoint,
+							timeRange: input.timeRange
+						}
+					}, wait.version);
+				});
+				if (input.command !== "get") return coordinated;
+				return result({
+					...snapshot(request),
+					coordination: JSON.parse(coordinated.content[0].text)
+				});
+			}
+			return result(snapshot(request));
 		}
 	}];
 }

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

@@ -12,20 +12,23 @@ declare const PersonalTaskModelSchema: import("@sinclair/typebox").TObject<{
         taskType: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
         requestedAgentId: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     }>>;
-    command: import("@sinclair/typebox").TUnion<import("@sinclair/typebox").TLiteral<"get" | "answer" | "retry_allocation" | "selection" | "list" | "cancel" | "submit" | "instruct">[]>;
+    command: import("@sinclair/typebox").TUnion<import("@sinclair/typebox").TLiteral<"get" | "answer" | "retry_allocation" | "selection" | "list" | "cancel" | "entry" | "submit" | "instruct" | "collaboration">[]>;
     requestId: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    instruction: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     title: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     taskId: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     requiredSkills: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
     idempotencyKey: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     objective: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     expectedOutputs: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
-    acceptanceCriteria: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
     constraints: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
     description: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     limit: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
     offset: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
-    instruction: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    section: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<import("@sinclair/typebox").TLiteral<string>[]>>;
+    entryId: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    afterSequence: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
+    bodyOffset: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
     questionId: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
 }>;
 export interface PersonalTaskToolDeps extends XopcUseToolDeps {

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

@@ -10,13 +10,14 @@ import { isPersonalConversation } from "../../personal-agent/repository.js";
 import { TaskAllocationRepository } from "../../tasks/task-allocation-repository.js";
 import { TaskOriginRepository } from "../../tasks/task-origin-repository.js";
 import { boundedPersonalResult } from "./personal-result-budget.js";
+import { TaskCollaborationRepository } from "../../tasks/task-collaboration-repository.js";
 import { TaskApplicationService } from "../../tasks/task-application-service.js";
+import { PERSONAL_WORKER_RESULT_GUIDANCE } from "../../personal-agent/communication.js";
 import { createXopcUseTool } from "./xopc-use-tool.js";
 import { getAvailablePersonalAgentTools, personalAgentModelAvailability } from "../../personal-agent/specialist-capabilities.js";
 import { assessSpecialist, matchSpecialists } from "../../agent-matching/service.js";
 import { AgentSelectionRepository, selectionRequestHash } from "../../agent-matching/selection-repository.js";
 import { assertSpecialistEligible, createSelectedTask } from "../../agent-matching/delegation-service.js";
-import { PERSONAL_WORKER_RESULT_GUIDANCE } from "../../personal-agent/communication.js";
 import { cancelPersonalTask } from "../../personal-agent/task-cancel.js";
 import { randomUUID } from "node:crypto";
 import { Type } from "@sinclair/typebox";
@@ -36,6 +37,8 @@ const PersonalTaskSchema = Type.Object({
 		Type.Literal("create"),
 		Type.Literal("list"),
 		Type.Literal("get"),
+		Type.Literal("collaboration"),
+		Type.Literal("entry"),
 		Type.Literal("instruct"),
 		Type.Literal("answer"),
 		Type.Literal("cancel")
@@ -81,6 +84,25 @@ const PersonalTaskSchema = Type.Object({
 	agentId: Type.Optional(Type.String({ description: "Specialist Agent ID. Never use your own ID." })),
 	taskId: Type.Optional(Type.String()),
 	instruction: Type.Optional(Type.String({ description: "The user’s new direction for this delegated Task." })),
+	entryId: Type.Optional(Type.String({ description: "Read one complete collaboration entry, including its question or instruction body." })),
+	afterSequence: Type.Optional(Type.Integer({ minimum: 0 })),
+	bodyOffset: Type.Optional(Type.Integer({
+		minimum: 0,
+		description: "Character offset for an entry body; follow nextBodyOffset until absent."
+	})),
+	section: Type.Optional(Type.Union([
+		"task",
+		"waits",
+		"runs",
+		"receipts",
+		"context",
+		"conversation",
+		"sessions",
+		"authorityGrants",
+		"dependencies",
+		"dependents",
+		"criterionReviews"
+	].map((value) => Type.Literal(value)))),
 	questionId: Type.Optional(Type.String({ description: "Collaboration question ID to answer." })),
 	expectedOutputs: Type.Optional(Type.Array(Type.String())),
 	acceptanceCriteria: Type.Optional(Type.Array(Type.String())),
@@ -100,13 +122,16 @@ const PersonalTaskModelSchema = Type.Object({
 		"previousSelectionId",
 		"matchId",
 		"cursor",
-		"requiredTools"
+		"requiredTools",
+		"acceptanceCriteria"
 	]).properties,
 	requirements: Type.Optional(Type.Omit(PersonalTaskSchema.properties.requirements, ["requiredTools", "requiredSkills"], { additionalProperties: false })),
 	command: Type.Union([
 		"submit",
 		"list",
 		"get",
+		"collaboration",
+		"entry",
 		"instruct",
 		"answer",
 		"retry_allocation",
@@ -124,11 +149,16 @@ const PersonalTaskModelSchema = Type.Object({
 		{
 			properties: { command: { enum: [
 				"get",
+				"collaboration",
 				"retry_allocation",
 				"cancel"
 			] } },
 			required: ["taskId"]
 		},
+		{
+			properties: { command: { const: "entry" } },
+			required: ["taskId", "entryId"]
+		},
 		{
 			properties: { command: { const: "instruct" } },
 			required: ["taskId", "instruction"]
@@ -164,7 +194,7 @@ function createPersonalTaskTool(deps) {
 	return {
 		name: "personal_task",
 		label: "Personal Task",
-		description: "Submit objective and a concise complete description, then return after local persistence. Preserve the user request and source references without inventing an execution plan or extra requirements. Omit optional structured fields when they merely repeat the description. Describe required capabilities in the brief; the background Task Router selects one executor and checks its tools. Do not read input files, select Agents or invent tool names before submit. Set requirements.requestedAgentId only for an executor explicitly named by the user, using their ID or display name; preserve explicitly requested requiredSkills. get/list inspect existing Tasks with limit/offset; cancel stops a Task on explicit user instruction and reports execution stop confirmation; instruct/answer send context; retry_allocation retries selection before execution; selection explains assignment. Status and results return automatically. Preserve idempotencyKey on uncertain retries. Report only confirmed states.",
+		description: "Submit objective and a concise complete description, then return after local persistence. Preserve the user request and source references without inventing an execution plan or extra requirements. Omit optional structured fields when they merely repeat the description. Describe required capabilities in the brief; the background Task Router selects one executor and checks its tools. Do not read input files, select Agents or invent tool names before submit. Set requirements.requestedAgentId only for an executor explicitly named by the user, using their ID or display name; preserve explicitly requested requiredSkills. get reads Task state, waits, runs, receipts and context; use section and limit/offset for complete paginated details. collaboration reads ordered message previews with afterSequence; entry reads exact message bodies using entryId and nextBodyOffset. Read full questions before answering. Delivery pending means saved, delivered means sent, confirmed means the executor acknowledged it; confirmation alone is not verified completion. get/list inspect existing Tasks with limit/offset; cancel stops a Task on explicit user instruction and reports execution stop confirmation; instruct/answer send context; retry_allocation retries selection before execution; selection explains assignment. Status and results return automatically. Preserve idempotencyKey on uncertain retries. Report only confirmed states.",
 		parameters: PersonalTaskModelSchema,
 		mutatesWorkspace: true,
 		mutationScope: "external",
@@ -285,9 +315,9 @@ function createPersonalTaskTool(deps) {
 					createMode: "allocate",
 					requirements,
 					includeConversationContext: false,
-					expectedOutputs: input.expectedOutputs ?? [],
-					acceptanceCriteria: input.acceptanceCriteria ?? [],
-					constraints: input.constraints ?? [],
+					expectedOutputs: input.expectedOutputs,
+					acceptanceCriteria: input.acceptanceCriteria,
+					constraints: input.constraints,
 					idempotencyKey: `personal-submit:${conversationId}:${selectionRequestHash(submissionKey)}`
 				};
 				if (requirements.requiredSkills?.length) args.body = `${brief.body}\n\nRequired Skills: ${requirements.requiredSkills.join(", ")}. Read and follow these Skills before execution.`;
@@ -368,9 +398,9 @@ function createPersonalTaskTool(deps) {
 					agentId,
 					createMode: "start",
 					includeConversationContext: false,
-					expectedOutputs: input.expectedOutputs ?? [],
-					acceptanceCriteria: input.acceptanceCriteria ?? [],
-					constraints: input.constraints ?? [],
+					expectedOutputs: input.expectedOutputs,
+					acceptanceCriteria: input.acceptanceCriteria,
+					constraints: input.constraints,
 					idempotencyKey: key
 				};
 			} else if (command === "list") {
@@ -383,6 +413,54 @@ function createPersonalTaskTool(deps) {
 				const taskId = input.taskId?.trim();
 				if (!taskId) throw new Error("taskId is required");
 				if (!new TaskOriginRepository().owns(taskId, conversationId)) throw new Error("Task does not belong to this personal conversation");
+				if (command === "collaboration" || command === "entry") {
+					const board = new TaskCollaborationRepository();
+					if (command === "entry") {
+						const entry = input.entryId ? board.get(input.entryId) : void 0;
+						if (!entry || entry.taskId !== taskId) throw new Error("Entry does not belong to this Task");
+						const offset = input.bodyOffset ?? 0;
+						const body = entry.body.slice(offset, offset + 4e3);
+						const payload = {
+							ok: true,
+							entry: {
+								...entry,
+								body
+							},
+							bodyOffset: offset,
+							bodyLength: entry.body.length,
+							...offset + body.length < entry.body.length ? { nextBodyOffset: offset + body.length } : {}
+						};
+						return {
+							content: [{
+								type: "text",
+								text: JSON.stringify(payload)
+							}],
+							details: {}
+						};
+					}
+					const limit = input.limit ?? 10;
+					const entries = board.list(taskId, input.afterSequence ?? 0, limit + 1);
+					const items = entries.slice(0, limit).map((entry) => ({
+						...entry,
+						body: entry.body.slice(0, 600),
+						bodyLength: entry.body.length,
+						...entry.body.length > 600 ? {
+							excerpt: true,
+							readEntryId: entry.id
+						} : {}
+					}));
+					return {
+						content: [{
+							type: "text",
+							text: JSON.stringify({
+								ok: true,
+								items,
+								...entries.length > limit ? { nextAfterSequence: items.at(-1)?.sequence } : {}
+							})
+						}],
+						details: {}
+					};
+				}
 				if (command === "cancel") {
 					const result = await cancelPersonalTask(taskId, conversationId, input.idempotencyKey ?? toolCallId);
 					deps.dispatchTaskRuns?.();
@@ -410,6 +488,13 @@ function createPersonalTaskTool(deps) {
 						taskId,
 						kind: input.command === "answer" ? "answer" : "instruction",
 						body,
+						idempotencyKey: input.idempotencyKey?.trim() || `personal-collaboration:${selectionRequestHash({
+							inputId: getSessionInputState(conversationId).activeInputId ?? toolCallId,
+							taskId,
+							kind: input.command,
+							body,
+							questionId: input.questionId
+						})}`,
 						...input.command === "answer" ? { causationId: input.questionId.trim() } : {}
 					};
 				} else args = { taskId };
@@ -459,20 +544,58 @@ function createPersonalTaskTool(deps) {
 						details: {}
 					};
 				}
-				if (payload && input.command === "get") return {
-					content: [{
-						type: "text",
-						text: JSON.stringify(boundedPersonalResult({
-							ok: payload.ok,
-							task: payload.task,
-							allocation: new TaskAllocationRepository().summary(input.taskId),
-							operationalState: payload.operationalState,
-							attention: payload.attention,
-							allowedCommands: payload.allowedCommands
-						}))
-					}],
-					details: {}
-				};
+				if (payload && input.command === "get") {
+					const offset = input.offset ?? 0;
+					const limit = input.limit ?? 10;
+					const read = input.section ? {
+						ok: payload.ok,
+						[input.section]: payload[input.section]
+					} : { ...payload };
+					const pagination = {};
+					for (const key of [
+						"waits",
+						"runs",
+						"receipts",
+						"context",
+						"sessions",
+						"authorityGrants",
+						"dependencies",
+						"dependents",
+						"criterionReviews"
+					]) {
+						const value = read[key];
+						if (!Array.isArray(value)) continue;
+						read[key] = value.slice(offset, offset + limit);
+						pagination[key] = {
+							total: value.length,
+							offset,
+							...offset + limit < value.length ? { nextOffset: offset + limit } : {}
+						};
+					}
+					if (!input.section) {
+						read.collaboration = new TaskCollaborationRepository().recent(input.taskId, void 0, 10).map((entry) => ({
+							...entry,
+							body: entry.body.slice(0, 600),
+							bodyLength: entry.body.length,
+							...entry.body.length > 600 ? {
+								excerpt: true,
+								readEntryId: entry.id
+							} : {}
+						}));
+						read.allocation = new TaskAllocationRepository().summary(input.taskId);
+						read.guidance = "Read entry for complete question/instruction bodies; collaboration with afterSequence pages the whole board. get(section, offset) pages state details. pending is saved, delivered is sent, confirmed is acknowledged; verification and Task acceptance are separate.";
+					}
+					return {
+						content: [{
+							type: "text",
+							text: JSON.stringify({
+								...read,
+								pagination
+							})
+						}],
+						details: {}
+					};
+				}
 				if (payload && input.command === "list") return {
 					content: [{
 						type: "text",

package/dist/src/agent/tools/publish-artifacts.js

@@ -6,8 +6,8 @@ import { resolvePathUnderWorkspace } from "./tool-paths.js";
 import { fileResourceId, fileSpaceId } from "../../files/file-service.js";
 import { persistToolMedia } from "./tool-media.js";
 import { basename, isAbsolute, relative, sep } from "node:path";
-import { realpath } from "node:fs/promises";
 import { Type } from "@sinclair/typebox";
+import { realpath } from "node:fs/promises";
 //#region src/agent/tools/publish-artifacts.ts
 init_src();
 const PublishArtifactsSchema = Type.Object({ paths: Type.Array(Type.String({ minLength: 1 }), {

package/dist/src/agent/tools/research-checkpoint-tool.d.ts

@@ -0,0 +1,3 @@
+import type { AgentTool } from '@earendil-works/pi-agent-core';
+import { ResearchCheckpointUpdateSchema, type ResearchCheckpointSink } from '../orchestration/research-checkpoint.js';
+export declare function createResearchCheckpointTool(sink: ResearchCheckpointSink): AgentTool<typeof ResearchCheckpointUpdateSchema>;

package/dist/src/agent/tools/research-checkpoint-tool.js

@@ -0,0 +1,28 @@
+import { ResearchCheckpointUpdateSchema, init_research_checkpoint } from "../orchestration/research-checkpoint.js";
+//#region src/agent/tools/research-checkpoint-tool.ts
+init_research_checkpoint();
+function createResearchCheckpointTool(sink) {
+	return {
+		name: "research_checkpoint",
+		label: "Save research checkpoint",
+		description: "Persist findings immediately after verifying each source. Use stable finding ids to update fields; omitted findings are retained. Include public source URLs for confirmed claims. not_disclosed is a valid result; never invent missing prices or limits. nextSteps replaces the unfinished-work list; set it to [] only when all requested fields are addressed, including explicitly undisclosed fields. This writes only this delegated research checkpoint.",
+		parameters: ResearchCheckpointUpdateSchema,
+		async execute(_id, update, signal) {
+			signal?.throwIfAborted();
+			const checkpoint = sink.save(update);
+			return {
+				content: [{
+					type: "text",
+					text: JSON.stringify({
+						saved: true,
+						findingCount: checkpoint.findings.length,
+						nextSteps: checkpoint.nextSteps
+					})
+				}],
+				details: {}
+			};
+		}
+	};
+}
+//#endregion
+export { createResearchCheckpointTool };

package/dist/src/agent/tools/review-workspace.js

@@ -5,8 +5,8 @@ import { checkedFilePath, readWorkspaceFile } from "../sandbox/fileAccess.js";
 import { resolve } from "node:path";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
-import { lstat, readlink, realpath } from "node:fs/promises";
 import { Type } from "@sinclair/typebox";
+import { lstat, readlink, realpath } from "node:fs/promises";
 //#region src/agent/tools/review-workspace.ts
 const exec = promisify(execFile);
 function createReviewWorkspaceTool(workspace) {

package/dist/src/agent/tools/search/cache.d.ts

@@ -0,0 +1,20 @@
+import type { SearchResult } from './types.js';
+export declare const SEARCH_CACHE_TTL_MS: number;
+export interface SearchCacheEntry {
+    key: string;
+    query: string;
+    count: number;
+    results: SearchResult[];
+    provider: string;
+    capturedAt: number;
+}
+export interface SearchCache {
+    get(key: string): SearchCacheEntry | undefined;
+    set(entry: SearchCacheEntry): void;
+}
+/** Research owns this scope. No account-wide or cross-conversation cache exists. */
+export declare function withSearchCache<T>(cache: SearchCache, run: () => T): T;
+export declare function currentSearchCache(): SearchCache | undefined;
+export declare class SearchCacheWriteError extends Error {
+    constructor(cause: unknown);
+}

package/dist/src/agent/tools/search/cache.js

@@ -0,0 +1,19 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+//#region src/agent/tools/search/cache.ts
+const SEARCH_CACHE_TTL_MS = 10 * 6e4;
+const searchCache = new AsyncLocalStorage();
+/** Research owns this scope. No account-wide or cross-conversation cache exists. */
+function withSearchCache(cache, run) {
+	return searchCache.run(cache, run);
+}
+function currentSearchCache() {
+	return searchCache.getStore();
+}
+var SearchCacheWriteError = class extends Error {
+	constructor(cause) {
+		super("Search completed but its checkpoint could not be saved", { cause });
+		this.name = "SearchCacheWriteError";
+	}
+};
+//#endregion
+export { SEARCH_CACHE_TTL_MS, SearchCacheWriteError, currentSearchCache, withSearchCache };