@xopcai/xopc 0.0.385 → 0.0.387

package/dist/src/agent/tools/personal-performance.js

@@ -0,0 +1,82 @@
+import { recordPersonalPerformance } from "../../personal-agent/performance.js";
+//#region src/agent/tools/personal-performance.ts
+function withPersonalPerformance(tool, conversationId, taskId, runId, assignmentEpoch) {
+	return {
+		...tool,
+		execute: async (...args) => {
+			const started = performance.now();
+			const raw = args[1];
+			const command = typeof raw?.command === "string" && /^[a-z_]{1,32}$/.test(raw.command) ? raw.command : void 0;
+			const identity = {
+				conversationId,
+				taskId,
+				runId,
+				assignmentEpoch,
+				tool: tool.name,
+				toolCallId: args[0],
+				command
+			};
+			try {
+				const result = await tool.execute(args[0], args[1], args[2], args[3]);
+				const details = result.details;
+				let payload;
+				if (tool.name.startsWith("personal_")) {
+					const text = result.content.find((item) => item.type === "text");
+					if (text?.type === "text") try {
+						payload = JSON.parse(text.text);
+					} catch {}
+				}
+				const failed = result.isError || payload?.ok === false || [
+					"failed",
+					"blocked",
+					"error",
+					"invalid_reference",
+					"conflict",
+					"unavailable"
+				].includes(payload?.status ?? details?.status ?? "");
+				const status = failed ? "error" : [
+					"preparing",
+					"pending",
+					"running"
+				].includes(payload?.status ?? details?.status ?? "") ? "pending" : "success";
+				const durationMs = performance.now() - started;
+				const errorCode = failed ? details?.status === "blocked" ? "command_blocked" : details?.failureHint?.startsWith("Shell syntax preflight") ? "shell_syntax" : "tool_error" : void 0;
+				recordPersonalPerformance({
+					...identity,
+					phase: "tool",
+					durationMs,
+					status,
+					errorCode
+				});
+				if (tool.name === "personal_task" && ["submit", "revise"].includes(command ?? "")) recordPersonalPerformance({
+					...identity,
+					phase: "local_write",
+					durationMs,
+					status
+				});
+				if (tool.name === "personal_result" && ["read", "search"].includes(command ?? "") && status !== "pending") recordPersonalPerformance({
+					...identity,
+					phase: "hot_read",
+					durationMs,
+					status
+				});
+				return result;
+			} catch (error) {
+				let errorCode = "tool_error";
+				if (error instanceof Error) try {
+					if (JSON.parse(error.message).code === "source_quote_mismatch") errorCode = "source_quote_mismatch";
+				} catch {}
+				recordPersonalPerformance({
+					...identity,
+					phase: "tool",
+					durationMs: performance.now() - started,
+					status: args[2]?.aborted ? "cancelled" : "error",
+					errorCode
+				});
+				throw error;
+			}
+		}
+	};
+}
+//#endregion
+export { withPersonalPerformance };

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

@@ -1,5 +1,5 @@
-import { CapabilityDispatcher } from "../../capabilities/runtime/dispatcher.js";
 import { LOCAL_READ_MAX_CHARS } from "./local-read-budget.js";
+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";

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

@@ -8,11 +8,10 @@ import { init_session_repository } from "../../storage/sqlite/session-repository
 import { isPersonalConversation } from "../../personal-agent/repository.js";
 import { TaskAllocationRepository } from "../../tasks/task-allocation-repository.js";
 import { boundedPersonalResult } from "./personal-result-budget.js";
+import { personalCapabilities } from "../../personal-agent/capability-service.js";
 import { selectionRequestHash } from "../../agent-matching/selection-repository.js";
-import { cancelPersonalTask } from "../../personal-agent/task-cancel.js";
 import { createPersonalTaskTool } from "./personal-task-tool.js";
-import { personalCapabilities } from "../../personal-agent/capability-service.js";
-import { assertPersonalRequestTimeRange, 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();
@@ -163,14 +162,14 @@ function createPersonalRequestTools(deps) {
 		name: "personal_request",
 		label: "Connected app request",
 		parameters: RequestSchema,
-		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; mention that range in your 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.",
+		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, parameters, ...summary } = snapshot(request);
-					const { brief: _brief, ...queryParameters } = parameters;
+					const { brief: _brief, taskRunId: _taskRunId, cancellationCleanupCompleted: _cleanup, ...queryParameters } = parameters;
 					return {
 						...summary,
 						parameters: queryParameters
@@ -203,21 +202,17 @@ function createPersonalRequestTools(deps) {
 				});
 				publishPersonalRequest(request);
 				deps.dispatchTaskRuns?.();
-				return result(compactSnapshot(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(compactSnapshot(request));
-				if (request.state === "cancelled") {
-					const stop = request.taskId ? await cancelPersonalTask(request.taskId, conversationId, input.idempotencyKey ?? toolCallId) : { executionStopConfirmed: true };
-					return result({
-						...compactSnapshot(request),
-						executionStopConfirmed: stop.executionStopConfirmed
-					});
-				}
-				const stop = request.taskId ? await cancelPersonalTask(request.taskId, conversationId, input.idempotencyKey ?? toolCallId) : { executionStopConfirmed: true };
 				const cancelled = cancelPersonalRequest(request);
+				const stop = stopPersonalRequestExecution(cancelled);
 				publishPersonalRequest(cancelled);
 				return result({
 					...compactSnapshot(cancelled),

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

@@ -0,0 +1,2 @@
+import type { AgentTool } from '@earendil-works/pi-agent-core';
+export declare function createPersonalResultTool(getConversationId: () => string | undefined): AgentTool;

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

@@ -0,0 +1,106 @@
+import { isPersonalConversation } from "../../personal-agent/repository.js";
+import { readPersonalResult, retryPersonalResultDelivery } from "../../personal-agent/result-reader.js";
+import "./local-read-budget.js";
+import { waitForPersonalResult } from "../../personal-agent/result-read-continuations.js";
+import { Type } from "@sinclair/typebox";
+//#region src/agent/tools/personal-result-tool.ts
+const schema = Type.Object({
+	command: Type.Union([
+		"list",
+		"get",
+		"read",
+		"search",
+		"retry_delivery"
+	].map((command) => Type.Literal(command))),
+	resultId: Type.Optional(Type.String({ minLength: 1 })),
+	taskId: Type.Optional(Type.String()),
+	sourceId: Type.Optional(Type.String({ description: "body for retained result text, or the exact artifact sourceId from get." })),
+	revision: Type.Optional(Type.String()),
+	sectionId: Type.Optional(Type.String()),
+	query: Type.Optional(Type.String({
+		minLength: 3,
+		maxLength: 500
+	})),
+	cursor: Type.Optional(Type.String({ maxLength: 1024 })),
+	offset: Type.Optional(Type.Integer({ minimum: 0 })),
+	limit: Type.Optional(Type.Integer({
+		minimum: 1,
+		maximum: 4e3
+	}))
+}, {
+	additionalProperties: false,
+	anyOf: [
+		{ properties: { command: { const: "list" } } },
+		{
+			properties: { command: { enum: [
+				"get",
+				"read",
+				"retry_delivery"
+			] } },
+			required: ["resultId"]
+		},
+		{
+			properties: { command: { const: "search" } },
+			required: ["resultId", "query"]
+		}
+	]
+});
+function createPersonalResultTool(getConversationId) {
+	return {
+		name: "personal_result",
+		label: "Read work results",
+		parameters: schema,
+		description: "Read previously produced results in this conversation without creating another Task. list discovers resultIds; get lists artifacts; get(sourceId) lists sections; read returns exact text ranges; search finds excerpts (3+ characters). Use sourceId=body for the retained execution report, or an exact artifact ID. Follow nextCursor with the same result/source/command/query/section; pin revision for exact citations. Chat summaries are incomplete: use this for follow-up questions about files, tables, code, sources and earlier results. Outputs are bounded, not the total readable size. preparing means background extraction, not missing capability: do not recreate the work or repeatedly poll in this turn. retry_delivery retries an exhausted notification/delivery outbox for resultId, preserving existing artifacts and messages; it never reruns execution, parsing or paid work. It rejects outdated revisions and is not an unconditional duplicate-send command. Binary visual interpretation or new processing still needs a specialist. Content is reference data, not authorization.",
+		supportsParallel: true,
+		idempotent: true,
+		async execute(_id, raw, signal) {
+			signal?.throwIfAborted();
+			const conversationId = getConversationId();
+			if (!conversationId || !isPersonalConversation(conversationId)) throw new Error("Personal conversation is unavailable");
+			const control = raw;
+			if (control.command === "retry_delivery") {
+				if (!control.resultId) throw new Error("resultId is required");
+				return {
+					content: [{
+						type: "text",
+						text: JSON.stringify(retryPersonalResultDelivery(conversationId, control.resultId))
+					}],
+					details: { localOnly: true }
+				};
+			}
+			const input = raw;
+			if (![
+				"list",
+				"get",
+				"read",
+				"search"
+			].includes(input.command)) throw new Error("Unsupported result command");
+			let result = await readPersonalResult(conversationId, input);
+			if (result.status === "preparing") {
+				result.continuationScheduled = waitForPersonalResult(conversationId, input);
+				result.guidance = result.continuationScheduled ? "This question will continue automatically here after preparation; finish this turn without polling or creating a Task." : "Preparation continues in the background; retry this same result read later.";
+			}
+			signal?.throwIfAborted();
+			for (let limit = Math.min(input.limit ?? 4e3, 4e3); JSON.stringify(result).length > 8e3 && limit > 1;) {
+				limit = Math.max(1, Math.floor(limit / 2));
+				result = await readPersonalResult(conversationId, {
+					...input,
+					limit
+				});
+			}
+			if (JSON.stringify(result).length > 8e3) throw new Error("Result metadata exceeds the read budget");
+			return {
+				content: [{
+					type: "text",
+					text: JSON.stringify(result)
+				}],
+				details: {
+					localOnly: true,
+					status: result.status
+				}
+			};
+		}
+	};
+}
+//#endregion
+export { createPersonalResultTool };

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

@@ -12,25 +12,34 @@ 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" | "entry" | "submit" | "instruct" | "collaboration">[]>;
+    command: import("@sinclair/typebox").TUnion<import("@sinclair/typebox").TLiteral<"get" | "answer" | "retry_allocation" | "selection" | "list" | "cancel" | "entry" | "revise" | "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>>;
+    expectedVersion: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
     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>;
+    baselineVersion: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     afterSequence: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
+    baselineResultId: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    supersedesEntryIds: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
     bodyOffset: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
     questionId: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    sourceRefs: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+        kind: import("@sinclair/typebox").TUnion<import("@sinclair/typebox").TLiteral<string>[]>;
+        sourceId: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        resultId: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        expectedVersion: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    }>>>;
 }>;
 export interface PersonalTaskToolDeps extends XopcUseToolDeps {
     getAgentToolAvailability?: MatchingContext['getAgentToolAvailability'];

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

@@ -8,16 +8,18 @@ import { getSessionMetadata } from "../../storage/sqlite/session-read-repository
 import { init_sqlite } from "../../storage/sqlite/index.js";
 import { isPersonalConversation } from "../../personal-agent/repository.js";
 import { TaskAllocationRepository } from "../../tasks/task-allocation-repository.js";
+import { TaskReadModelProjector } from "../../tasks/task-read-model-projector.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 { parseTaskHandoffReferences } from "../../tasks/task-handoff.js";
 import { TaskApplicationService } from "../../tasks/task-application-service.js";
-import { createXopcUseTool } from "./xopc-use-tool.js";
+import { PERSONAL_WORKER_RESULT_GUIDANCE } from "../../personal-agent/communication.js";
 import { getAvailablePersonalAgentTools, personalAgentModelAvailability } from "../../personal-agent/specialist-capabilities.js";
 import { assessSpecialist, matchSpecialists } from "../../agent-matching/service.js";
+import { createXopcUseTool } from "./xopc-use-tool.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";
@@ -29,6 +31,7 @@ init_request_repository();
 init_task_repository();
 const PersonalTaskSchema = Type.Object({
 	command: Type.Union([
+		Type.Literal("revise"),
 		Type.Literal("retry_allocation"),
 		Type.Literal("submit"),
 		Type.Literal("agents"),
@@ -83,6 +86,10 @@ const PersonalTaskSchema = Type.Object({
 	})),
 	agentId: Type.Optional(Type.String({ description: "Specialist Agent ID. Never use your own ID." })),
 	taskId: Type.Optional(Type.String()),
+	baselineResultId: Type.Optional(Type.String({ description: "Exact latest result ID from personal_result directory or Task revisionBaseline.resultId." })),
+	baselineVersion: Type.Optional(Type.String({ description: "Opaque baselineVersion token returned by the host, copied exactly. Never use the numeric resultRevision or task version here." })),
+	expectedVersion: Type.Optional(Type.Integer({ minimum: 1 })),
+	supersedesEntryIds: Type.Optional(Type.Array(Type.String({ description: "Only actual earlier instruction/answer entry IDs from collaboration. Omit for original-contract changes or the first revision; never use task/result/run IDs." }), { maxItems: 40 })),
 	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 })),
@@ -91,6 +98,7 @@ const PersonalTaskSchema = Type.Object({
 		description: "Character offset for an entry body; follow nextBodyOffset until absent."
 	})),
 	section: Type.Optional(Type.Union([
+		"revision",
 		"task",
 		"waits",
 		"runs",
@@ -115,6 +123,29 @@ const PersonalTaskSchema = Type.Object({
 	idempotencyKey: Type.Optional(Type.String())
 });
 const PersonalTaskModelSchema = Type.Object({
+	sourceRefs: Type.Optional(Type.Array(Type.Object({
+		kind: Type.Union([
+			"result",
+			"note",
+			"task",
+			"file"
+		].map((kind) => Type.Literal(kind))),
+		sourceId: Type.Optional(Type.String({
+			minLength: 1,
+			maxLength: 2e3
+		})),
+		resultId: Type.Optional(Type.String({
+			minLength: 1,
+			maxLength: 500
+		})),
+		expectedVersion: Type.Optional(Type.String({ maxLength: 500 }))
+	}, {
+		additionalProperties: false,
+		anyOf: [{
+			properties: { kind: { const: "result" } },
+			required: ["resultId"]
+		}, { required: ["sourceId"] }]
+	}), { maxItems: 5 })),
 	...Type.Omit(PersonalTaskSchema, [
 		"agentId",
 		"selectionReason",
@@ -122,10 +153,12 @@ 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([
+		"revise",
 		"submit",
 		"list",
 		"get",
@@ -140,6 +173,16 @@ const PersonalTaskModelSchema = Type.Object({
 }, {
 	additionalProperties: false,
 	anyOf: [
+		{
+			properties: { command: { const: "revise" } },
+			required: [
+				"taskId",
+				"instruction",
+				"baselineResultId",
+				"baselineVersion",
+				"expectedVersion"
+			]
+		},
 		{
 			properties: { command: { const: "submit" } },
 			required: ["objective", "description"]
@@ -193,13 +236,15 @@ 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 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.",
+		description: "For changes to a completed ordinary Task use revise on the SAME taskId, with instruction and the exact revisionBaseline fields from get(section=revision), or baselineResultId/baselineVersion from personal_result get/list plus expected Task version. get(section=revision) is a small local metadata lookup; do not read the whole task body just to revise. This atomically saves a new work revision and queues fresh background allocation. Reuse idempotencyKey on uncertain retries. sourceRefs adds necessary inputs; the baseline body and selected artifacts are retained automatically. Explicit supersedesEntryIds replaces only named earlier directions; all others remain applicable. A new independent goal uses submit with pinned old-result sources. Connected Request side effects require a new authorized Request. For workspace file work, include every required input in sourceRefs as {kind:\"file\",sourceId:\"relative/or/absolute/path\"} without pre-reading it; the host pins only files in this conversation workspace. Owner workspace paths are input locations, not the executor cwd. For necessary prior inputs not selected in the current message, pass sourceRefs with their stable sourceId and optional expectedVersion; no pre-read is required. For a prior result use {kind:\"result\",resultId:\"directory result ID\",sourceId:\"exact artifact ID or unique file title\"}; omit sourceId only for the retained result body. Do not invent composite IDs. The host authorizes and pins the exact artifact version in the background. Prefer the exact selected reference when provided. 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",
 		requiresExclusiveWorkspaceLock: false,
 		finalGuardRelevant: true,
 		async execute(toolCallId, modelInput, signal) {
+			if (!PersonalTaskSchema.properties.command.anyOf.some((command) => command.const === modelInput.command)) throw new Error("Unsupported personal_task command; completed work uses atomic revise, not manual start/reopen");
+			if (modelInput.sourceRefs?.length && !["submit", "revise"].includes(modelInput.command)) throw new Error("sourceRefs is supported only by submit/revise; it cannot be silently ignored by a coordination command");
 			const input = modelInput;
 			const conversationId = deps.getCurrentConversationId?.();
 			const ownAgentId = deps.getCurrentAgentId?.();
@@ -304,6 +349,7 @@ function createPersonalTaskTool(deps) {
 					sourceInput: inputId ?? toolCallId,
 					brief,
 					requirements,
+					sourceRefs: modelInput.sourceRefs,
 					expectedOutputs: input.expectedOutputs,
 					acceptanceCriteria: input.acceptanceCriteria,
 					constraints: input.constraints
@@ -313,10 +359,11 @@ function createPersonalTaskTool(deps) {
 					...brief,
 					createMode: "allocate",
 					requirements,
+					sourceRefs: modelInput.sourceRefs,
 					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.`;
@@ -397,9 +444,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") {
@@ -412,6 +459,62 @@ 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 === "get" && input.section === "revision") {
+					const model = new TaskReadModelProjector().get(taskId);
+					return {
+						content: [{
+							type: "text",
+							text: JSON.stringify({
+								ok: true,
+								taskId,
+								phase: model.task.phase,
+								expectedVersion: model.task.version,
+								revisionBaseline: model.revisionBaseline,
+								allowedCommands: model.allowedCommands,
+								allocation: model.allocation
+							})
+						}],
+						details: {}
+					};
+				}
+				if (command === "revise") {
+					if (!input.instruction || !input.baselineResultId || !input.baselineVersion || !input.expectedVersion) throw new Error("Revision requires instruction, baseline result/version, and expected task version");
+					const refs = parseTaskHandoffReferences(modelInput.sourceRefs);
+					if (!refs) throw new Error("Invalid revision sourceRefs");
+					const result = new TaskApplicationService().reviseCompleted({
+						taskId,
+						conversationId,
+						instruction: input.instruction,
+						baselineResultId: input.baselineResultId,
+						baselineVersion: input.baselineVersion,
+						expectedVersion: input.expectedVersion,
+						sourceRefs: refs,
+						supersedesEntryIds: input.supersedesEntryIds,
+						idempotencyKey: input.idempotencyKey ?? `personal-revise:${conversationId}:${toolCallId}`
+					});
+					deps.dispatchTaskRuns?.();
+					const payload = result.ok === false ? {
+						ok: false,
+						reason: result.reason,
+						revisionBaseline: result.model?.revisionBaseline,
+						allowedCommands: result.model?.allowedCommands,
+						recovery: result.reason === "conflict" ? "Copy the returned revisionBaseline.resultId, baselineVersion and expectedVersion exactly into one revise retry. Closed/review Tasks support atomic revise: do not reopen separately. Do not repeat unchanged input or invent numeric baseline versions." : result.reason === "invalid_reference" ? "supersedesEntryIds only accepts earlier user instruction/answer IDs from collaboration. Original contract requirements have no entry ID: omit supersedesEntryIds for a first revision or original output-list change. No change has been saved." : "Use instruct/answer while running. A completed ordinary Task needs its latest authorized result. Cancelled Tasks and connected Request actions are not reopened by this command."
+					} : {
+						ok: true,
+						saved: true,
+						taskId,
+						expectedVersion: result.model.task.version,
+						allocation: result.model.allocation,
+						state: "revision_saved_background_allocation_pending"
+					};
+					return {
+						content: [{
+							type: "text",
+							text: JSON.stringify(payload)
+						}],
+						details: {}
+					};
+				}
 				if (command === "collaboration" || command === "entry") {
 					const board = new TaskCollaborationRepository();
 					if (command === "entry") {
@@ -550,6 +653,7 @@ function createPersonalTaskTool(deps) {
 						ok: payload.ok,
 						[input.section]: payload[input.section]
 					} : { ...payload };
+					read.revisionBaseline = new TaskReadModelProjector().get(input.taskId)?.revisionBaseline;
 					const pagination = {};
 					for (const key of [
 						"waits",
@@ -588,6 +692,7 @@ function createPersonalTaskTool(deps) {
 						content: [{
 							type: "text",
 							text: JSON.stringify({
+								revisionBaseline: read.revisionBaseline,
 								...read,
 								pagination
 							})

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) {
@@ -30,7 +30,26 @@ function createReviewWorkspaceTool(workspace) {
 				timeout: 1e4,
 				maxBuffer: 8 * 1024 * 1024
 			})).stdout;
-			cwd = checkedFilePath(workspace, await realpath((await git(["rev-parse", "--show-toplevel"])).trim()), "read");
+			let root;
+			try {
+				root = (await git(["rev-parse", "--show-toplevel"])).trim();
+			} catch (error) {
+				if (signal?.aborted) throw error;
+				if (error.code !== 128 || !String(error.stderr).includes("not a git repository")) throw error;
+				return {
+					content: [{
+						type: "text",
+						text: "Git workspace review is unavailable because this workspace is not a Git repository. No Git diff was reviewed. Do not retry this unchanged call or initialize Git solely for review. Inspect the declared output files and compare them with pinned baseline copies using portable diff or checksums; retain the Task acceptance checks."
+					}],
+					details: {
+						status: "unavailable",
+						reason: "not_git_repository",
+						complete: false,
+						command: "review_workspace"
+					}
+				};
+			}
+			cwd = checkedFilePath(workspace, await realpath(root), "read");
 			const startRevision = await readWorkspaceRevision(cwd);
 			const head = await git([
 				"rev-parse",

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);
+}