@xopcai/xopc 0.0.386 → 0.0.387

package/dist/src/tasks/task-contract-planner.js

@@ -4,6 +4,7 @@ import { getAgentDefaultChatModelConfig, init_schema } from "../config/schema.js
 import { completeTaskModelCall } from "./task-model-call.js";
 import { defineTaskContract } from "./task-contract-definition.js";
 import { PERSONAL_WORKER_RESULT_GUIDANCE } from "../personal-agent/communication.js";
+import { EXECUTION_CAPABILITIES } from "./task-execution-capabilities.js";
 //#region src/tasks/task-contract-planner.ts
 init_schema();
 init_logger();
@@ -30,18 +31,36 @@ function strings(value, max) {
 function parseTaskContractResponse(raw) {
 	const parsed = parseObject(raw);
 	if (!parsed) return void 0;
+	if ([
+		"expectedOutputs",
+		"acceptanceCriteria",
+		"constraints",
+		"approvalRequired",
+		"assumptions",
+		"risks"
+	].some((key) => parsed[key] !== void 0 && (!Array.isArray(parsed[key]) || parsed[key].some((value) => typeof value !== "string")))) return void 0;
 	const objective = typeof parsed.objective === "string" ? parsed.objective.trim() : "";
 	const expectedOutputs = strings(parsed.expectedOutputs, 8);
 	const plannedCriteria = strings(parsed.acceptanceCriteria, 40);
 	const writeBoundary = (criterion) => /(?:仅|只)(?:能)?写入|未(?:覆盖|修改).*其他文件|(?:write only|only write)|(?:not|never) (?:overwrite|modify).*other files/i.test(criterion);
-	const acceptanceCriteria = plannedCriteria.filter((criterion) => !writeBoundary(criterion)).filter((criterion) => !(/publish_task_result/.test(criterion) && /调用|使用|提交|返回|检查|验收|call|submit|review/i.test(criterion) && !/报告.*(?:说明|描述)|文档.*(?:说明|描述)|(?:report|document).*describe/i.test(criterion)));
+	const deliveryPhrase = /最终(?:的)?(?:回复|答复)|交付说明(?:仅|只|中|不|未)|(?:final|future) (?:chat )?(?:reply|response)|(?:delivery|chat) (?:message|reply)/i;
+	const deliveryBoundary = (criterion) => deliveryPhrase.test(criterion);
+	const boundary = (criterion) => writeBoundary(criterion) || deliveryBoundary(criterion);
+	const acceptanceCriteria = plannedCriteria.filter((criterion) => !writeBoundary(criterion)).flatMap((criterion) => {
+		const position = criterion.search(deliveryPhrase);
+		if (position < 0) return [criterion];
+		const prefix = criterion.slice(0, position).replace(/[，,;；。\s]*(?:并且|且|并|and)?\s*$/i, "").trim();
+		return prefix && /运行|执行|发布|生成|校验|\b(?:run|execut|publish|generat|verif)/i.test(prefix) ? [prefix] : [];
+	}).filter((criterion) => !(/publish_task_result/.test(criterion) && /调用|使用|提交|返回|检查|验收|call|submit|review/i.test(criterion) && !/报告.*(?:说明|描述)|文档.*(?:说明|描述)|(?:report|document).*describe/i.test(criterion)));
 	if (Array.isArray(parsed.acceptanceCriteria) && parsed.acceptanceCriteria.length > 40) return void 0;
 	if (!objective || expectedOutputs.length === 0 || acceptanceCriteria.length === 0) return void 0;
+	if (parsed.requiredCapabilities !== void 0 && (!Array.isArray(parsed.requiredCapabilities) || parsed.requiredCapabilities.some((name) => typeof name !== "string" || !Object.hasOwn(EXECUTION_CAPABILITIES, name)))) return void 0;
 	return {
 		objective,
+		...parsed.requiredCapabilities === void 0 ? {} : { requiredCapabilities: strings(parsed.requiredCapabilities, 6) },
 		expectedOutputs,
 		acceptanceCriteria,
-		constraints: [...new Set([...strings(parsed.constraints, 10), ...plannedCriteria.filter(writeBoundary)])],
+		constraints: [...new Set([...strings(parsed.constraints, 10), ...plannedCriteria.filter(boundary)])],
 		approvalRequired: strings(parsed.approvalRequired, 8),
 		assumptions: strings(parsed.assumptions, 10),
 		risks: strings(parsed.risks, 10)
@@ -51,9 +70,10 @@ var ModelTaskContractPlanner = class {
 	async plan(input) {
 		const fallback = defineTaskContract(input.objective, input.locale);
 		try {
+			if ((input.taskContext?.length ?? 0) > 96e3) throw new Error("Task context exceeds planning budget");
 			const models = getAgentDefaultChatModelConfig();
 			if (!models) throw new Error("No default task planning model is configured");
-			const planned = parseTaskContractResponse(extractText((await completeTaskModelCall(models, { messages: [{
+			const messages = [{
 				role: "user",
 				content: [
 					"Define the smallest complete, verifiable contract for the user task.",
@@ -62,29 +82,43 @@ var ModelTaskContractPlanner = class {
 					"Write boundaries and prohibitions on unrelated actions belong in constraints, not criteria requiring proof that no unobserved action ever occurred. Criteria may check the actual delivered output paths and unchanged supplied input bytes. Never remove an explicit scope restriction.",
 					"Keep each criterion concise and concrete; do not repeat the full brief. Include all required deliverable conditions without splitting trivial wording into unnecessary items.",
 					"Define criteria for the specialist deliverables only. Do not create self-referential criteria about calling publish_task_result, receiving this review, or what a future Personal Agent reply will say. Those are runtime delivery checks, evaluated after completion. Keep source support, calculations, completeness and requested limitations as separate criteria. User-specified files and content remain required.",
+					"requiredCapabilities is a minimal subset of read_input, execute_code, publish_files, web_research, browser, generate_image. Include only operations necessary for the requested inputs/outputs; this list selects registered tools and grants no permissions. Do not require browser when ordinary web fetch suffices. Preserve explicit executor/Skill and scope constraints.",
 					"List assumptions explicitly. Put only irreversible, external, financial, privacy, or permission decisions in approvalRequired.",
-					"Return one JSON object only with keys: objective, expectedOutputs, acceptanceCriteria, constraints, approvalRequired, assumptions, risks.",
+					"Return one JSON object only. Every array contains flat strings, never objects or nested arrays. Schema example: {\"objective\":\"Deliver the requested work\",\"expectedOutputs\":[\"report.md\"],\"acceptanceCriteria\":[\"report.md contains the requested evidence\"],\"constraints\":[],\"approvalRequired\":[],\"assumptions\":[],\"risks\":[],\"requiredCapabilities\":[\"read_input\",\"publish_files\"]}. Capabilities must use the allowed enum values.",
 					input.locale ? `Write all user-facing JSON values in ${input.locale === "zh" ? "Simplified Chinese" : "English"}. Preserve schema keys, identifiers, paths, and proper nouns.` : "Write all user-facing JSON values in the language of the user request, regardless of the language of project or attached context. Preserve schema keys and identifiers.",
 					"",
 					`User request:\n${input.objective.trim()}`,
-					input.taskContext ? `\nUser-provided task context:\n${input.taskContext.replace(PERSONAL_WORKER_RESULT_GUIDANCE, "").trim().slice(0, 16e3)}` : "",
+					input.taskContext ? `\nUser-provided task context:\n${input.taskContext.replace(PERSONAL_WORKER_RESULT_GUIDANCE, "").trim()}` : "",
 					input.projectContext ? `\nProject context:\n${input.projectContext.slice(0, 8e3)}` : "",
 					input.userContext ? `\nUser context:\n${input.userContext.slice(0, 8e3)}` : ""
 				].join("\n"),
 				timestamp: Date.now()
-			}] }, {
-				maxTokens: 4e3,
-				temperature: 0,
-				signal: input.signal
-			}, { operation: "task.plan_contract" })).content));
-			if (!planned) throw new Error("Task planning response did not contain a verifiable contract");
-			return {
-				...planned,
-				objective: fallback.objective
-			};
+			}];
+			for (let attempt = 0; attempt < 2; attempt++) {
+				input.signal?.throwIfAborted();
+				const planned = parseTaskContractResponse(extractText((await completeTaskModelCall(models, { messages }, {
+					maxTokens: 4e3,
+					temperature: 0,
+					signal: input.signal
+				}, { operation: "task.plan_contract" })).content));
+				if (planned?.requiredCapabilities) return {
+					...planned,
+					objective: fallback.objective,
+					capabilityPlanning: "complete"
+				};
+				if (attempt === 0) messages.push({
+					role: "user",
+					timestamp: Date.now(),
+					content: "Your previous response did not match the required schema. Return the same task contract as one JSON object. expectedOutputs, acceptanceCriteria, constraints, approvalRequired, assumptions and risks must be flat string arrays, never objects. requiredCapabilities must be an array drawn only from read_input, execute_code, publish_files, web_research, browser, generate_image. Keep all user constraints; do not add criteria about a future chat reply. Return no commentary."
+				});
+			}
+			throw new Error("Task planning response did not contain a verifiable contract and operation requirements");
 		} catch (err) {
 			log.warn({ err }, "Task contract planning fell back to deterministic criteria");
-			return fallback;
+			return {
+				...fallback,
+				capabilityPlanning: "unavailable"
+			};
 		}
 	}
 };

package/dist/src/tasks/task-conversation-repository.js

@@ -91,7 +91,7 @@ var TaskConversationRepository = class {
 			const existing = db.prepare("SELECT * FROM task_conversation_state WHERE task_id = ?").get(input.taskId);
 			const current = db.prepare(`SELECT * FROM task_sessions
          WHERE task_id = ? AND role = 'execution' AND status = 'active'`).get(input.taskId);
-			const sameSession = current?.conversation_id === input.conversationId;
+			const sameSession = current?.conversation_id === input.conversationId && (!input.runId || current.run_id === input.runId);
 			const assignmentEpoch = sameSession ? current.assignment_epoch : (existing?.assignment_epoch ?? 0) + 1;
 			if (!sameSession) db.prepare(`UPDATE task_sessions SET status = 'superseded', ended_at = ?
            WHERE task_id = ? AND role = 'execution' AND status = 'active'`).run(now, input.taskId);

package/dist/src/tasks/task-evidence-ranges.d.ts

@@ -0,0 +1,7 @@
+export type EvidenceRange = {
+    start: number;
+    end: number;
+};
+/** Offsets are Unicode code points into a persisted successful tool result, never the input command. */
+export declare function observedEvidenceExcerpt(body: string, range: EvidenceRange): string;
+export declare function suggestedEvidenceRanges(body: string): EvidenceRange[];

package/dist/src/tasks/task-evidence-ranges.js

@@ -0,0 +1,20 @@
+//#region src/tasks/task-evidence-ranges.ts
+/** Offsets are Unicode code points into a persisted successful tool result, never the input command. */
+function observedEvidenceExcerpt(body, range) {
+	const points = Array.from(body);
+	if (!Number.isInteger(range.start) || !Number.isInteger(range.end) || range.start < 0 || range.end <= range.start || range.end > points.length || range.end - range.start > 1e3) throw new Error("Evidence range must select 1..1000 observed Unicode characters within the successful read");
+	return points.slice(range.start, range.end).join("");
+}
+function suggestedEvidenceRanges(body) {
+	const length = Array.from(body).length;
+	if (!length) return [];
+	return [{
+		start: 0,
+		end: Math.min(1e3, length)
+	}, ...length > 1e3 ? [{
+		start: Math.max(1e3, length - 1e3),
+		end: length
+	}] : []];
+}
+//#endregion
+export { observedEvidenceExcerpt, suggestedEvidenceRanges };

package/dist/src/tasks/task-execution-capabilities.d.ts

@@ -0,0 +1,26 @@
+import type { SpecialistTaskRequirements } from '@xopcai/gateway-contract';
+import { type MatchingContext, type SpecialistAssessment } from '../agent-matching/service.js';
+import { type TaskAggregate } from './task-repository.js';
+export declare const EXECUTION_CAPABILITIES: {
+    readonly read_input: readonly ["read_file", "read_media", "exec_command"];
+    readonly execute_code: readonly ["exec_command"];
+    readonly publish_files: readonly ["publish_artifacts"];
+    readonly web_research: readonly ["web_fetch", "browser_use"];
+    readonly browser: readonly ["browser_use"];
+    readonly generate_image: readonly ["image_generate"];
+};
+export type ExecutionCapability = keyof typeof EXECUTION_CAPABILITIES;
+export interface ExecutionRequirement {
+    capability: ExecutionCapability;
+    source: 'structured_input' | 'background_inference';
+    reason: string;
+}
+export declare function taskExecutionRequirements(task: TaskAggregate, requirements: SpecialistTaskRequirements, inferred?: ExecutionCapability[]): ExecutionRequirement[];
+export declare function assessTaskExecutor(agentId: string, requirements: SpecialistTaskRequirements, needs: ExecutionRequirement[], context: MatchingContext, taskId?: string): SpecialistAssessment;
+export declare function captureExecutionRequirements(task: TaskAggregate, requirements: SpecialistTaskRequirements, needs: ExecutionRequirement[]): void;
+export declare function savedExecutionRequirements(taskId: string): {
+    requirements: SpecialistTaskRequirements;
+    needs: ExecutionRequirement[];
+    contractVersion: number;
+} | undefined;
+export declare function assertTaskExecutorReady(taskId: string, originConversationId: string, agentId: string, context: MatchingContext): void;

package/dist/src/tasks/task-execution-capabilities.js

@@ -0,0 +1,117 @@
+import { getSqliteDatabase, init_transaction } from "../storage/sqlite/transaction.js";
+import { TaskRepository, init_task_repository } from "./task-repository.js";
+import { TaskContextRepository } from "./task-context-repository.js";
+import { assertTaskHandoffExecutorAccess } from "./task-handoff.js";
+import { assessSpecialist } from "../agent-matching/service.js";
+import { personalCapabilities } from "../personal-agent/capability-service.js";
+//#region src/tasks/task-execution-capabilities.ts
+init_transaction();
+init_task_repository();
+const EXECUTION_CAPABILITIES = {
+	read_input: [
+		"read_file",
+		"read_media",
+		"exec_command"
+	],
+	execute_code: ["exec_command"],
+	publish_files: ["publish_artifacts"],
+	web_research: ["web_fetch", "browser_use"],
+	browser: ["browser_use"],
+	generate_image: ["image_generate"]
+};
+function taskExecutionRequirements(task, requirements, inferred = []) {
+	const needs = /* @__PURE__ */ new Map();
+	const add = (capability, source, reason) => needs.set(capability, {
+		capability,
+		source,
+		reason
+	});
+	for (const capability of inferred) if (capability in EXECUTION_CAPABILITIES) add(capability, "background_inference", "Minimal operation inferred by the background contract planner; no authority granted");
+	if (requirements.inputKinds?.some((kind) => /^(csv|xlsx|pdf|docx|pptx|file|document|spreadsheet|text)$/.test(kind))) add("read_input", "structured_input", "Structured file input requires a registered reader or execution tool");
+	if (requirements.outputKinds?.some((kind) => /^(file|pdf|docx|pptx|xlsx|csv|spreadsheet|document)$/.test(kind))) add("publish_files", "structured_input", "Requested file output requires publication");
+	if (requirements.inputKinds?.some((kind) => /^(pdf|docx|pptx|xlsx)$/.test(kind))) add("execute_code", "structured_input", "Binary input requires an executable parser; text readers alone do not establish binary processing capability");
+	if (!requirements.connector && (task.body?.length ?? 0) > 12e3) requirements.requiredTools = [...new Set([...requirements.requiredTools ?? [], "task_collaboration"])];
+	return [...needs.values()];
+}
+function assessTaskExecutor(agentId, requirements, needs, context, taskId) {
+	const assessment = assessSpecialist(agentId, requirements, context);
+	for (const need of needs) {
+		const options = EXECUTION_CAPABILITIES[need.capability].map((tool) => assessSpecialist(agentId, {
+			...requirements,
+			requiredSkills: [],
+			requiredTools: [tool]
+		}, context));
+		const available = options.find((option) => option.checks.some((check) => check.condition.startsWith("tool:") && check.state === "verified"));
+		assessment.checks.push({
+			condition: `capability:${need.capability}`,
+			state: available ? "verified" : "blocked",
+			reasonCode: available ? "registered_operation_available" : "required_operation_unavailable",
+			detail: available ? available.checks.find((check) => check.condition.startsWith("tool:"))?.condition : JSON.stringify(options.flatMap((option) => option.checks.filter((check) => check.condition.startsWith("tool:"))))
+		});
+	}
+	if (taskId) try {
+		assertTaskHandoffExecutorAccess(taskId, agentId);
+	} catch (error) {
+		assessment.checks.push({
+			condition: "source_authorization",
+			state: "blocked",
+			reasonCode: "selected_source_unavailable",
+			detail: error instanceof Error ? error.message : String(error)
+		});
+	}
+	assessment.eligibility = assessment.checks.some((check) => check.state === "blocked") ? "blocked" : assessment.checks.some((check) => check.state === "unknown") ? "needs_verification" : "eligible";
+	return assessment;
+}
+function captureExecutionRequirements(task, requirements, needs) {
+	new TaskContextRepository().captureSnapshot({
+		ownerKind: "task",
+		ownerId: task.id,
+		query: task.contract?.objective ?? task.title,
+		relationshipPolicy: {
+			kind: "task_execution_requirements",
+			contractVersion: task.latestContractVersion
+		},
+		selectedItems: [{
+			requirements,
+			needs,
+			contractVersion: task.latestContractVersion,
+			requirementOrigins: {
+				requestedAgentId: "provided_requirement",
+				requiredSkills: "provided_requirement",
+				requiredTools: "provided_requirement_or_host_bounded_reader",
+				acceptanceCriteria: "current_contract"
+			}
+		}],
+		authorizationSnapshot: {
+			expandsAuthority: false,
+			liveRecheckRequired: true
+		}
+	});
+}
+function savedExecutionRequirements(taskId) {
+	const row = getSqliteDatabase().prepare(`SELECT selected_items_json FROM context_snapshots
+    WHERE owner_kind = 'task' AND owner_id = ? AND json_extract(relationship_policy_json, '$.kind') = 'task_execution_requirements'
+    ORDER BY created_at DESC, rowid DESC LIMIT 1`).get(taskId);
+	return row ? JSON.parse(row.selected_items_json)[0] : void 0;
+}
+function assertTaskExecutorReady(taskId, originConversationId, agentId, context) {
+	const saved = savedExecutionRequirements(taskId);
+	if (!saved) return;
+	if (new TaskRepository().require(taskId).latestContractVersion !== saved.contractVersion) throw new Error("Task contract changed after capability validation; reallocate before execution");
+	const connector = saved.requirements.connector;
+	if (connector) {
+		const permitted = personalCapabilities(originConversationId, connector.connectorId, connector.accountId).some((capability) => capability.status === "ready" && capability.accounts.some((account) => account.accountId === connector.accountId && account.executorAgentIds.includes(agentId)));
+		context = {
+			...context,
+			checkConnector: () => ({
+				condition: "connector",
+				state: permitted ? "verified" : "blocked",
+				reasonCode: permitted ? "account_authorized" : "account_unavailable"
+			})
+		};
+	}
+	const fresh = assessTaskExecutor(agentId, saved.requirements, saved.needs, context, taskId);
+	if (fresh.eligibility !== "eligible") throw new Error(`Task executor capability changed: ${JSON.stringify(fresh.checks.filter((check) => ["blocked", "unknown"].includes(check.state)))}`);
+}
+//#endregion
+export { EXECUTION_CAPABILITIES, assertTaskExecutorReady, assessTaskExecutor, captureExecutionRequirements, savedExecutionRequirements, taskExecutionRequirements };

package/dist/src/tasks/task-handoff-service.js

@@ -2,9 +2,9 @@ import { createLogger } from "../utils/logger/index.js";
 import { init_logger } from "../utils/logger.js";
 import { TaskRepository, init_task_repository } from "./task-repository.js";
 import { TaskRunRepository, init_task_run_repository } from "./task-run-repository.js";
+import { init_session_key, resolveConversationId, sanitizeSegment } from "../routing/session-key.js";
 import { normalizeAgentId } from "../agent-catalog/id.js";
 import { init_agent_scope, listAgentEntries } from "../agent/agent-scope.js";
-import { init_session_key, resolveConversationId, sanitizeSegment } from "../routing/session-key.js";
 import { TaskConversationRepository } from "./task-conversation-repository.js";
 import { TaskContextRepository } from "./task-context-repository.js";
 //#region src/tasks/task-handoff-service.ts

package/dist/src/tasks/task-handoff.d.ts

@@ -0,0 +1,56 @@
+import { type TurnContextRef } from '../agent/source-context/types.js';
+import type { Config } from '../config/schema.js';
+import { type PersonalResultInput } from '../personal-agent/result-reader.js';
+export interface TaskHandoff {
+    version: 1;
+    conversationId: string;
+    transcriptId: string;
+    inputId?: string;
+    originalRequest?: string;
+    interpretation: string;
+    baseline: {
+        contractVersion: number;
+        assignmentEpoch: number;
+        instructionSequence: number;
+    };
+    sources: Array<{
+        kind: string;
+        sourceId: string;
+        version: string;
+        title: string;
+        text: string;
+        truncated: boolean;
+        representation?: 'text' | 'metadata' | 'directory';
+        purpose: string;
+        contentHash: string;
+    }>;
+    requestedSources?: TurnContextRef[];
+    attachments: unknown[];
+    completeness: {
+        originalInput: 'captured' | 'unavailable';
+        omitted: string[];
+        unresolvedReferences: string[];
+    };
+}
+/** Normalize model-facing references without fetching any source on the submission path. */
+export declare function parseTaskHandoffReferences(raw: unknown): TurnContextRef[] | null;
+/** Called inside task.create's transaction; no discovery, parsing or remote IO. */
+export declare function captureTaskHandoff(taskId: string, conversationId: string, interpretation: string, references?: TurnContextRef[]): void;
+export declare function getTaskHandoff(taskId: string): TaskHandoff | undefined;
+export declare function assertTaskHandoffAccess(handoff: TaskHandoff): void;
+/** Selected result pointers delegate only the pinned source, never the owner's result directory. */
+export declare function readTaskHandoffSource(taskId: string, sourceIndex: number, input: PersonalResultInput, config?: Config): Promise<Record<string, unknown>>;
+/** Resolve the main Agent's selected history pointers only after the foreground commit. */
+export declare function resolveTaskHandoffReferences(taskId: string, config?: Config): Promise<TaskHandoff | undefined>;
+/** Copy only the selected pinned input into this executor's workspace, without granting access to the owner's root. */
+export declare function materializeTaskHandoffFile(taskId: string, sourceIndex: number, workspace: string, config: Config): Promise<{
+    materialized: boolean;
+    sourceId: string;
+    version: string;
+    readOnlyPath: string;
+    executionInputRoot: string;
+    sha256: string;
+    bytes: number;
+    scope: string;
+}>;
+export declare function assertTaskHandoffExecutorAccess(taskId: string, agentId: string): void;