@xopcai/xopc 0.0.386 → 0.0.387

package/dist/src/agent/source-context/types.js

@@ -17,7 +17,7 @@ function summarizeSourceContext(context) {
 function isTurnContextRef(value) {
 	if (!value || typeof value !== "object") return false;
 	const row = value;
-	return (row.kind === "note" || row.kind === "task" || row.kind === "file" || row.kind === "session" || row.kind === "browser_tab" || row.kind === "user_assertion") && typeof row.sourceId === "string" && row.sourceId.trim().length > 0 && (row.refId === void 0 || typeof row.refId === "string" && /^[A-Za-z0-9_-]{1,64}$/.test(row.refId)) && (row.expectedVersion === void 0 || typeof row.expectedVersion === "string");
+	return (row.kind === "result" || row.kind === "note" || row.kind === "task" || row.kind === "file" || row.kind === "session" || row.kind === "browser_tab" || row.kind === "user_assertion") && typeof row.sourceId === "string" && row.sourceId.trim().length > 0 && (row.refId === void 0 || typeof row.refId === "string" && /^[A-Za-z0-9_-]{1,64}$/.test(row.refId)) && (row.expectedVersion === void 0 || typeof row.expectedVersion === "string");
 }
 function parseTurnContextRefs(value, max = 5) {
 	if (value === void 0) return [];

package/dist/src/agent/tools/exec-command.js

@@ -1,3 +1,4 @@
+import { runProcess } from "../../process/run-process.js";
 import { commandRegistry, commandTimeout } from "../commands/command-registry.js";
 import { evaluateExecPolicy } from "../sandbox/exec-policy.js";
 import { formatSize, truncateTail } from "./truncate.js";
@@ -58,6 +59,7 @@ function createExecCommandTool(workspaceCwd, options) {
 			"Unix and Docker use /bin/sh, not your interactive shell. Do not use Bash process substitution <(...) or other Bash-only syntax unless invoking an installed bash explicitly. Prefer separate portable commands or a script file. Windows hosts use cmd.exe.",
 			"Use apply_patch for file edits; do not edit files by shell redirection unless explicitly necessary.",
 			"Relative cwd values resolve under the current agent workspace.",
+			"Use a fresh output directory with mkdir -p. Avoid destructive cleanup such as rm -rf on variable paths; blocked cleanup should be removed, never disguised or moved to bypass policy. A syntax preflight on Unix host commands prevents partial writes from malformed shell syntax.",
 			"When the command creates final user-facing files, declare all final paths in outputs so they are persisted with this command."
 		].join(" "),
 		parameters: ExecCommandSchema,
@@ -99,7 +101,7 @@ function createExecCommandTool(workspaceCwd, options) {
 				allowedEnvVars: options?.getSkillPassthroughEnvVarNames?.() ?? []
 			});
 			if (!policy.allowed) {
-				const text = `Sandbox blocked command: ${policy.reason}`;
+				const text = `Sandbox blocked command: ${policy.reason}\nNothing was executed. Remove destructive cleanup and use a fresh output directory with mkdir -p, or narrow the operation. Do not repeat unchanged or rephrase the blocked operation to bypass policy.`;
 				return {
 					content: [{
 						type: "text",
@@ -125,12 +127,55 @@ function createExecCommandTool(workspaceCwd, options) {
 			}
 			const timeoutMs = commandTimeout(params.timeoutMs, policy.timeoutMs);
 			const maxOutputChars = clampMaxOutputChars(params.maxOutputChars);
+			const isolation = options?.getCommandIsolation?.();
+			if (process.platform !== "win32" && isolation?.mode !== "docker") {
+				const started = performance.now();
+				const syntax = await runProcess({
+					program: "/bin/sh",
+					args: [
+						"-n",
+						"-c",
+						command
+					],
+					cwd: policy.effectiveCwd,
+					env: policy.sanitizedEnv,
+					timeoutMs: 5e3,
+					maxOutputBytes: 8e3,
+					signal,
+					terminationPolicy: "tree"
+				});
+				if (syntax.exitCode !== 0) {
+					const details = {
+						command,
+						cwd: policy.effectiveCwd,
+						status: syntax.timedOut ? "timed_out" : "failed",
+						exitCode: syntax.exitCode,
+						durationMs: performance.now() - started,
+						timedOut: syntax.timedOut,
+						truncated: false,
+						outputBytes: Buffer.byteLength(syntax.stderr),
+						totalOutputBytes: Buffer.byteLength(syntax.stderr),
+						captureTruncated: syntax.outputTruncated,
+						stdout: "",
+						stderr: syntax.stderr,
+						aggregatedOutput: syntax.stderr,
+						failureHint: "Shell syntax preflight failed; nothing was executed. Use portable POSIX sh syntax (for example diff file1 file2), or explicitly invoke an installed bash for Bash syntax. Fix the command; no side effects need replaying."
+					};
+					return {
+						content: [{
+							type: "text",
+							text: formatOutputForModel(details, maxOutputChars).text
+						}],
+						details
+					};
+				}
+			}
 			const runtimeEnv = options?.prepareEnv ? await options.prepareEnv(policy.sanitizedEnv, policy.effectiveCwd) : policy.sanitizedEnv;
 			const owner = options?.getConversationId?.() ?? workspaceCwd;
 			const registry = commandRegistry();
 			let commandResult = await registry.start({
 				workspace: workspaceCwd,
-				isolation: options?.getCommandIsolation?.(),
+				isolation,
 				owner,
 				command,
 				cwd: policy.effectiveCwd,

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

@@ -8,9 +8,10 @@ import { getSessionMetadata } from "../../storage/sqlite/session-read-repository
 import { patchSessionMetadata } from "../../storage/sqlite/session-repository.js";
 import { getSessionTaskPlan, setSessionTaskPlan } from "../../storage/sqlite/session-task-plan-repository.js";
 import { init_sqlite } from "../../storage/sqlite/index.js";
-import { init_agent_scope, resolveDefaultAgentId } from "../agent-scope.js";
 import { resolveUserContextSessionAccess } from "../../user-context/access-policy.js";
+import { init_agent_scope, resolveDefaultAgentId } from "../agent-scope.js";
 import { resolveEffectiveAgentConfigForAgent, resolveEffectiveAgentConfigForSession } from "../../config/agent-profile.js";
+import { TaskConversationRepository } from "../../tasks/task-conversation-repository.js";
 import { LOCAL_READ_MAX_CHARS } from "./local-read-budget.js";
 import { createPersonalAttentionTool } from "./personal-attention-tool.js";
 import { markCodemodeCoreRead } from "./codemode-permissions.js";
@@ -72,7 +73,10 @@ import { createImageGenerateTool } from "./image-generate-tool.js";
 import { createPersonalReadTool } from "./personal-read-tool.js";
 import { createTaskCollaborationTool } from "./task-collaboration-tool.js";
 import "./index.js";
+import { createPersonalResultTool } from "./personal-result-tool.js";
 import { createPersonalTaskTool } from "./personal-task-tool.js";
+import { withTaskEvidenceIdentity } from "./task-evidence.js";
+import { withPersonalPerformance } from "./personal-performance.js";
 import { createPersonalRequestTools } from "./personal-request-tool.js";
 import { createPersonalRequestConnectionTool, createPersonalRequestResultTool } from "./personal-request-result-tool.js";
 import { createPersonalPreferenceTool } from "./personal-preference-tool.js";
@@ -429,6 +433,11 @@ var AgentToolsFactory = class AgentToolsFactory {
 			createSendMediaTool(workspace, bus, deliveryContext),
 			createPublishArtifactsTool(workspace),
 			createTaskResultTool(currentConversationId),
+			createTaskCollaborationTool({
+				...productToolDeps,
+				getWorkspace: () => workspace,
+				getCurrentConversationId: currentConversationId
+			}),
 			createReadMediaTool(personalToolsConfigured ? {
 				textOnly: true,
 				maxChars: LOCAL_READ_MAX_CHARS,
@@ -532,6 +541,7 @@ var AgentToolsFactory = class AgentToolsFactory {
 			...this.deps.getAutomationService || this.deps.getSceneAccess || this.deps.getProjectService || this.deps.getNotesService || this.deps.getLocalAppService || this.deps.getChatPreviewService || this.deps.dispatchTaskEvents || this.deps.dispatchTaskRuns ? [createXopcUseTool(productToolDeps), ...personalToolsConfigured ? [
 				createPersonalTaskTool(productToolDeps),
 				createPersonalReadTool(productToolDeps),
+				createPersonalResultTool(currentConversationId),
 				...createPersonalRequestTools(productToolDeps),
 				createPersonalAttentionTool({
 					getConversationId: () => this.deps.getCurrentContext()?.conversationId,
@@ -616,14 +626,7 @@ var AgentToolsFactory = class AgentToolsFactory {
 				}
 			})] : [],
 			...optionalTools,
-			...personalExecution ? [
-				createPersonalRequestResultTool(currentConversationId),
-				createPersonalRequestConnectionTool(currentConversationId),
-				createTaskCollaborationTool({
-					...productToolDeps,
-					getCurrentConversationId: currentConversationId
-				})
-			] : []
+			...personalExecution ? [createPersonalRequestResultTool(currentConversationId), createPersonalRequestConnectionTool(currentConversationId)] : []
 		];
 		if ([
 			"read_file",
@@ -668,7 +671,11 @@ var AgentToolsFactory = class AgentToolsFactory {
 		return ["create_desktop_pet"];
 	}
 	createAllTools(coreOptions) {
-		return sortToolsForPromptCache(wrapToolsWithProtection(this.createCoreTools(coreOptions), this.deps.toolExecutorConfig));
+		const wrapped = wrapToolsWithProtection(this.createCoreTools(coreOptions), this.deps.toolExecutorConfig);
+		const executionId = coreOptions?.conversationId ?? getEmbeddedExecutionSession() ?? this.deps.getCurrentContext()?.conversationId;
+		const taskExecution = executionId && isXopcDatabaseOpen() && new TaskConversationRepository().resolveActiveExecutionSession(executionId);
+		const observed = wrapped.map((tool) => taskExecution || tool.name.startsWith("personal_") ? withPersonalPerformance(tool, executionId, taskExecution ? taskExecution.taskId : void 0, taskExecution ? taskExecution.runId : void 0, taskExecution ? taskExecution.assignmentEpoch : void 0) : tool);
+		return sortToolsForPromptCache(taskExecution ? observed.map((tool) => withTaskEvidenceIdentity(tool)) : observed);
 	}
 };
 function filterToolsByDisabledSet(tools, disabled) {

package/dist/src/agent/tools/personal-performance.d.ts

@@ -0,0 +1,2 @@
+import type { AgentTool } from '@earendil-works/pi-agent-core';
+export declare function withPersonalPerformance<T extends AgentTool>(tool: T, conversationId?: string, taskId?: string, runId?: string, assignmentEpoch?: number): T;

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,9 +8,9 @@ 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 { createPersonalTaskTool } from "./personal-task-tool.js";
-import { personalCapabilities } from "../../personal-agent/capability-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

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,7 +12,7 @@ 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>;
@@ -22,14 +22,24 @@ declare const PersonalTaskModelSchema: import("@sinclair/typebox").TObject<{
     objective: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     expectedOutputs: 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>;
     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,14 +8,16 @@ 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 { 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 { 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 { cancelPersonalTask } from "../../personal-agent/task-cancel.js";
@@ -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",
@@ -127,6 +158,7 @@ const PersonalTaskModelSchema = Type.Object({
 	]).properties,
 	requirements: Type.Optional(Type.Omit(PersonalTaskSchema.properties.requirements, ["requiredTools", "requiredSkills"], { additionalProperties: false })),
 	command: Type.Union([
+		"revise",
 		"submit",
 		"list",
 		"get",
@@ -141,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"]
@@ -194,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?.();
@@ -305,6 +349,7 @@ function createPersonalTaskTool(deps) {
 					sourceInput: inputId ?? toolCallId,
 					brief,
 					requirements,
+					sourceRefs: modelInput.sourceRefs,
 					expectedOutputs: input.expectedOutputs,
 					acceptanceCriteria: input.acceptanceCriteria,
 					constraints: input.constraints
@@ -314,6 +359,7 @@ function createPersonalTaskTool(deps) {
 					...brief,
 					createMode: "allocate",
 					requirements,
+					sourceRefs: modelInput.sourceRefs,
 					includeConversationContext: false,
 					expectedOutputs: input.expectedOutputs,
 					acceptanceCriteria: input.acceptanceCriteria,
@@ -413,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") {
@@ -551,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",
@@ -589,6 +692,7 @@ function createPersonalTaskTool(deps) {
 						content: [{
 							type: "text",
 							text: JSON.stringify({
+								revisionBaseline: read.revisionBaseline,
 								...read,
 								pagination
 							})