@xopcai/xopc 0.0.180 → 0.0.187

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

@@ -0,0 +1,423 @@
+import { getSqliteDatabase, runSqliteWriteTransaction } from "../storage/sqlite/transaction.js";
+import { TaskRepository } from "./task-repository.js";
+import { TaskRunRepository } from "./task-run-repository.js";
+import { TaskReadModelProjector } from "./task-read-model-projector.js";
+import { TaskContextRepository } from "./task-context-repository.js";
+import { TaskDependencyService } from "./task-dependency-service.js";
+import { createHash, randomUUID } from "node:crypto";
+//#region src/tasks/task-application-service.ts
+function requestHash(value) {
+	return createHash("sha256").update(JSON.stringify(value)).digest("hex");
+}
+function executorRef(executor) {
+	switch (executor.kind) {
+		case "agent": return { agentId: executor.agentId };
+		case "workflow": return {
+			workflowId: executor.workflowId,
+			...executor.workflowVersion ? { workflowVersion: executor.workflowVersion } : {},
+			...executor.input === void 0 ? {} : { input: executor.input }
+		};
+		case "human": return { actorId: executor.actorId };
+		case "external": return {
+			provider: executor.provider,
+			config: executor.config
+		};
+	}
+}
+var TaskApplicationService = class {
+	#tasks = new TaskRepository();
+	#runs = new TaskRunRepository();
+	#context = new TaskContextRepository();
+	#dependencies = new TaskDependencyService();
+	#projector = new TaskReadModelProjector();
+	create(input, actor = { kind: "user" }) {
+		const existing = this.#tasks.getByIdempotencyKey(input.idempotencyKey);
+		if (existing) {
+			this.readCommand(input.idempotencyKey, requestHash(input));
+			return {
+				ok: true,
+				model: this.#projector.project(existing),
+				...this.#runs.getActiveRoot(existing.id) ? { runId: this.#runs.getActiveRoot(existing.id).id } : {}
+			};
+		}
+		return runSqliteWriteTransaction((db) => {
+			const task = this.#tasks.create({
+				idempotencyKey: input.idempotencyKey,
+				title: input.title,
+				body: input.body,
+				phase: input.activation.mode === "capture" ? input.activation.phase : "ready",
+				projectId: input.projectId,
+				milestoneId: input.milestoneId,
+				parentTaskId: input.parentTaskId,
+				priority: input.priority,
+				dueAt: input.dueAt,
+				ownerId: input.ownerId,
+				delegateAgentId: input.delegateAgentId,
+				source: "api",
+				locale: input.locale,
+				...input.contract,
+				createdBy: actor
+			});
+			let current = task;
+			if (input.dependencies.length > 0) current = this.#dependencies.replace({
+				taskId: task.id,
+				dependsOnTaskIds: input.dependencies,
+				expectedVersion: current.version
+			});
+			for (const edge of input.context) this.#context.add({
+				taskId: task.id,
+				...edge,
+				createdBy: actor
+			});
+			for (const grant of input.authorityGrants) this.#context.grant({
+				taskId: task.id,
+				...grant,
+				grantedBy: actor
+			});
+			this.recordCommand(db, {
+				key: input.idempotencyKey,
+				type: "task.create",
+				subjectId: task.id,
+				hash: requestHash(input),
+				result: { taskId: task.id }
+			});
+			this.enqueueEvent(db, "task.created.v2", task.id, input.idempotencyKey, {
+				taskId: task.id,
+				phase: current.phase,
+				projectId: current.projectId
+			});
+			if (input.activation.mode === "capture") return {
+				ok: true,
+				model: this.#projector.project(current)
+			};
+			return this.start(current.id, current.version, input.activation.executor, {
+				idempotencyKey: `${input.idempotencyKey}:start`,
+				scheduleAt: input.activation.scheduleAt,
+				actor,
+				correlationId: input.idempotencyKey
+			});
+		});
+	}
+	execute(input) {
+		const actor = input.actor ?? { kind: "user" };
+		const task = this.#tasks.get(input.taskId);
+		if (!task) return {
+			ok: false,
+			reason: "not_found"
+		};
+		const model = this.#projector.project(task);
+		if (task.version !== input.expectedVersion) return {
+			ok: false,
+			reason: "conflict",
+			model
+		};
+		if (this.readCommand(input.idempotencyKey, requestHash(input.command))) return {
+			ok: true,
+			model
+		};
+		return runSqliteWriteTransaction((db) => {
+			let result;
+			switch (input.command.type) {
+				case "mark_ready":
+					result = task.phase === "backlog" ? this.lifecycle(task.id, task.version, "ready") : {
+						ok: false,
+						reason: "invalid_transition",
+						model
+					};
+					break;
+				case "start":
+					result = this.start(task.id, task.version, input.command.executor, {
+						idempotencyKey: input.idempotencyKey,
+						scheduleAt: input.command.scheduleAt,
+						actor,
+						correlationId: input.idempotencyKey
+					});
+					break;
+				case "request_review":
+					result = task.phase === "active" ? this.lifecycle(task.id, task.version, "review") : {
+						ok: false,
+						reason: "invalid_transition",
+						model
+					};
+					break;
+				case "close":
+					result = this.lifecycle(task.id, task.version, "closed", input.command.resolution);
+					break;
+				case "reopen":
+					result = task.phase === "closed" ? this.lifecycle(task.id, task.version, input.command.phase) : {
+						ok: false,
+						reason: "invalid_transition",
+						model
+					};
+					break;
+				case "add_wait": {
+					const activeRun = this.#runs.getActiveRoot(task.id);
+					this.#runs.createWait({
+						taskId: task.id,
+						...activeRun ? { taskRunId: activeRun.id } : {},
+						actor,
+						...input.command.wait
+					});
+					if (activeRun && (activeRun.status === "queued" || activeRun.status === "running" || activeRun.status === "verifying")) this.#runs.setStatus({
+						runId: activeRun.id,
+						expectedVersion: activeRun.version,
+						from: [activeRun.status],
+						to: "waiting",
+						actor
+					});
+					result = {
+						ok: true,
+						model: this.#projector.get(task.id)
+					};
+					break;
+				}
+				case "resolve_wait": {
+					const wait = this.#runs.getWait(input.command.waitId);
+					if (!wait || wait.taskId !== task.id) result = {
+						ok: false,
+						reason: "not_found",
+						model
+					};
+					else {
+						this.#runs.resolveWait({
+							waitId: wait.id,
+							actor,
+							resolution: input.command.resolution
+						});
+						result = {
+							ok: true,
+							model: this.#projector.get(task.id)
+						};
+					}
+					break;
+				}
+				case "delegate": {
+					const updated = this.#tasks.update(task.id, {
+						expectedVersion: task.version,
+						delegateAgentId: input.command.agentId ?? null
+					});
+					result = updated ? {
+						ok: true,
+						model: this.#projector.project(updated)
+					} : {
+						ok: false,
+						reason: "conflict",
+						model: this.#projector.get(task.id)
+					};
+					break;
+				}
+				case "revise_contract": {
+					const updated = this.#tasks.reviseContract({
+						taskId: task.id,
+						expectedVersion: task.version,
+						...input.command.contract,
+						createdBy: actor
+					});
+					result = updated ? {
+						ok: true,
+						model: this.#projector.project(updated)
+					} : {
+						ok: false,
+						reason: "conflict",
+						model: this.#projector.get(task.id)
+					};
+					break;
+				}
+			}
+			if (result.ok === false) {
+				if (result.reason === "blocked") this.enqueueEvent(db, "task.attention_required.v2", task.id, input.idempotencyKey, {
+					taskId: task.id,
+					reason: "blocked",
+					projectId: task.projectId
+				});
+				return result;
+			}
+			this.recordCommand(db, {
+				key: input.idempotencyKey,
+				type: `task.${input.command.type}`,
+				subjectId: task.id,
+				hash: requestHash(input.command),
+				result: {
+					taskId: task.id,
+					runId: result.runId
+				}
+			});
+			this.enqueueEvent(db, "task.commanded.v2", task.id, input.idempotencyKey, {
+				taskId: task.id,
+				command: input.command.type,
+				phase: result.model.task.phase,
+				operationalState: result.model.operationalState,
+				projectId: result.model.task.projectId,
+				runId: result.runId
+			});
+			if (result.model.task.phase !== task.phase) this.enqueueEvent(db, "task.phase_changed.v2", task.id, input.idempotencyKey, {
+				taskId: task.id,
+				from: task.phase,
+				to: result.model.task.phase,
+				resolution: result.model.task.resolution,
+				projectId: result.model.task.projectId
+			});
+			return result;
+		});
+	}
+	completeRun(input) {
+		return runSqliteWriteTransaction(() => {
+			const run = this.#runs.get(input.runId);
+			if (!run) return {
+				ok: false,
+				reason: "not_found"
+			};
+			if (run.version !== input.expectedRunVersion) return {
+				ok: false,
+				reason: "conflict",
+				model: this.#projector.get(run.taskId)
+			};
+			if (!this.#runs.finalize({
+				runId: run.id,
+				expectedVersion: run.version,
+				receipt: input.receipt,
+				actor: input.actor,
+				terminalCode: input.terminalCode,
+				terminalMessage: input.terminalMessage
+			})) return {
+				ok: false,
+				reason: "conflict",
+				model: this.#projector.get(run.taskId)
+			};
+			const task = this.#tasks.require(run.taskId);
+			if (input.receipt.status !== "succeeded") return {
+				ok: true,
+				model: this.#projector.project(task)
+			};
+			const verified = input.receipt.verification.status === "passed";
+			const phase = task.contract?.acceptancePolicy === "verified_auto" && verified ? "closed" : "review";
+			const updated = this.#tasks.setLifecycle({
+				taskId: task.id,
+				expectedVersion: task.version,
+				phase,
+				...phase === "closed" ? { resolution: "done" } : {}
+			});
+			if (!updated) throw new Error("Task changed while its run was being finalized");
+			return {
+				ok: true,
+				model: this.#projector.project(updated)
+			};
+		});
+	}
+	start(taskId, expectedVersion, executor, options) {
+		const task = this.#tasks.get(taskId);
+		if (!task || task.version !== expectedVersion) return task ? {
+			ok: false,
+			reason: "conflict",
+			model: this.#projector.project(task)
+		} : {
+			ok: false,
+			reason: "not_found"
+		};
+		if (task.phase === "closed" || this.#runs.getActiveRoot(taskId)) return {
+			ok: false,
+			reason: "invalid_transition",
+			model: this.#projector.project(task)
+		};
+		const blocking = this.#dependencies.listBlocking(taskId);
+		if (blocking.length > 0) {
+			const existingWaits = this.#runs.listActiveWaits(taskId);
+			for (const dependency of blocking) {
+				if (existingWaits.some((wait) => wait.kind === "dependency" && wait.condition.dependsOnTaskId === dependency.id)) continue;
+				this.#runs.createWait({
+					taskId,
+					kind: "dependency",
+					reason: `Waiting for ${dependency.title}`,
+					condition: {
+						dependsOnTaskId: dependency.id,
+						executor
+					}
+				});
+			}
+			return {
+				ok: false,
+				reason: "blocked",
+				model: this.#projector.get(taskId)
+			};
+		}
+		const granted = new Set(this.#context.listActiveGrants(taskId).map((grant) => grant.capability));
+		const missing = (task.contract?.approvalRequired ?? []).filter((boundary) => !granted.has(boundary));
+		if (missing.length > 0) {
+			for (const capability of missing) this.#runs.createWait({
+				taskId,
+				kind: "approval",
+				reason: `Approval required: ${capability}`,
+				condition: {
+					capability,
+					executor
+				}
+			});
+			return {
+				ok: false,
+				reason: "blocked",
+				model: this.#projector.get(taskId)
+			};
+		}
+		const run = this.#runs.create({
+			taskId,
+			executorKind: executor.kind,
+			executorRef: executorRef(executor),
+			trigger: {
+				kind: options.actor.kind === "user" ? "user" : options.actor.id === "task-signal" ? "signal" : options.actor.kind,
+				actor: options.actor
+			},
+			correlationId: options.correlationId,
+			idempotencyKey: options.idempotencyKey,
+			contractVersion: task.latestContractVersion,
+			scheduledAt: options.scheduleAt,
+			retryPolicy: { maxAttempts: 3 }
+		});
+		const active = task.phase === "active" ? task : this.#tasks.setLifecycle({
+			taskId,
+			expectedVersion: task.version,
+			phase: "active"
+		});
+		if (!active) throw new Error("Task changed while its run was being created");
+		return {
+			ok: true,
+			model: this.#projector.project(active),
+			runId: run.id
+		};
+	}
+	lifecycle(taskId, expectedVersion, phase, resolution) {
+		const updated = this.#tasks.setLifecycle({
+			taskId,
+			expectedVersion,
+			phase,
+			resolution
+		});
+		return updated ? {
+			ok: true,
+			model: this.#projector.project(updated)
+		} : {
+			ok: false,
+			reason: "conflict",
+			model: this.#projector.get(taskId)
+		};
+	}
+	recordCommand(db, input) {
+		db.prepare(`INSERT INTO command_deduplication (
+        idempotency_key, command_type, subject_kind, subject_id,
+        request_hash, result_json, created_at
+      ) VALUES (?, ?, 'task', ?, ?, ?, ?)`).run(input.key, input.type, input.subjectId, input.hash, JSON.stringify(input.result), Date.now());
+	}
+	readCommand(key, hash) {
+		const row = getSqliteDatabase().prepare(`SELECT request_hash FROM command_deduplication WHERE idempotency_key = ?`).get(key);
+		if (!row) return false;
+		if (row.request_hash !== hash) throw new Error("Idempotency key was reused with different input");
+		return true;
+	}
+	enqueueEvent(db, eventType, subjectId, correlationId, payload) {
+		db.prepare(`INSERT INTO domain_outbox (
+        event_id, event_type, subject_kind, subject_id, correlation_id,
+        payload_json, created_at
+      ) VALUES (?, ?, 'task', ?, ?, ?, ?)`).run(randomUUID(), eventType, subjectId, correlationId, JSON.stringify(payload), Date.now());
+	}
+};
+//#endregion
+export { TaskApplicationService };

package/dist/src/tasks/task-context-assembler.d.ts

@@ -0,0 +1,36 @@
+import { type TaskAggregate } from './task-repository.js';
+import { TaskRunRepository } from './task-run-repository.js';
+export interface TaskContextAllocation {
+    profile: 'standard' | 'deep' | 'critical';
+    maxResults: number;
+    maxChars: number;
+    reason: string;
+}
+export interface TaskContextManifest {
+    taskId: string;
+    sources: Array<{
+        kind: string;
+        id: string;
+        description: string;
+    }>;
+    assumptions: string[];
+    unresolvedCriteria: string[];
+    allocation: 'deep' | 'critical';
+}
+export interface AssembledTaskContext {
+    taskId?: string;
+    retrievalQuery: string;
+    allocation: TaskContextAllocation;
+    manifest?: TaskContextManifest;
+}
+export interface TaskExecutionBrief {
+    task: TaskAggregate;
+    remainingCriteria: string[];
+    allocation: TaskContextAllocation;
+    manifest: TaskContextManifest;
+    latestReceipt?: ReturnType<TaskRunRepository['getReceipt']>;
+}
+export declare function getTaskExecutionBrief(taskId: string): TaskExecutionBrief | undefined;
+export declare function getTaskContextManifest(taskId: string): TaskContextManifest | undefined;
+export declare function assembleTaskContext(sessionKey: string, userQuery: string): AssembledTaskContext;
+export declare function buildTaskExecutionDirective(sessionKey: string): string;

package/dist/src/tasks/task-context-assembler.js

@@ -0,0 +1,125 @@
+import { isXopcDatabaseOpen } from "../storage/sqlite/connection.js";
+import { getSessionMetadata } from "../storage/sqlite/session-repository.js";
+import "../storage/sqlite/index.js";
+import { TaskRepository } from "./task-repository.js";
+import { TaskRunRepository } from "./task-run-repository.js";
+import { TaskContextRepository } from "./task-context-repository.js";
+//#region src/tasks/task-context-assembler.ts
+const STANDARD = {
+	profile: "standard",
+	maxResults: 12,
+	maxChars: 12e3,
+	reason: "No active task requires expanded context."
+};
+function taskIdForSession(sessionKey) {
+	const value = getSessionMetadata(sessionKey)?.customData?.taskId;
+	return typeof value === "string" && value.trim() ? value.trim() : void 0;
+}
+function getTaskExecutionBrief(taskId) {
+	if (!isXopcDatabaseOpen()) return void 0;
+	const task = new TaskRepository().get(taskId);
+	if (!task?.contract) return void 0;
+	const runs = new TaskRunRepository();
+	const latestRun = runs.getLatestRoot(taskId);
+	const latestReceipt = latestRun ? runs.getReceipt(latestRun.id) : void 0;
+	const remainingCriteria = latestReceipt?.verification.checks.length ? latestReceipt.verification.checks.filter((check) => check.status !== "passed").map((check) => check.criterion) : task.contract.acceptanceCriteria;
+	const critical = task.priority === "critical" || task.contract.risks.length > 0 || task.contract.approvalRequired.length > 0;
+	const allocation = critical ? {
+		profile: "critical",
+		maxResults: 32,
+		maxChars: 64e3,
+		reason: "Task risk or authority boundaries require full context."
+	} : {
+		profile: "deep",
+		maxResults: 20,
+		maxChars: 32e3,
+		reason: "An active task benefits from complete context."
+	};
+	const edges = new TaskContextRepository().list(taskId);
+	return {
+		task,
+		remainingCriteria,
+		allocation,
+		manifest: {
+			taskId,
+			sources: [
+				{
+					kind: "task_contract",
+					id: `${taskId}:${task.contract.version}`,
+					description: "Current task contract"
+				},
+				...edges.map((edge) => ({
+					kind: edge.targetKind,
+					id: edge.targetId,
+					description: edge.title ?? edge.role
+				})),
+				...latestReceipt ? [{
+					kind: "task_run_receipt",
+					id: latestReceipt.runId,
+					description: "Latest run result"
+				}] : []
+			],
+			assumptions: task.contract.assumptions,
+			unresolvedCriteria: remainingCriteria,
+			allocation: critical ? "critical" : "deep"
+		},
+		...latestReceipt ? { latestReceipt } : {}
+	};
+}
+function getTaskContextManifest(taskId) {
+	return getTaskExecutionBrief(taskId)?.manifest;
+}
+function assembleTaskContext(sessionKey, userQuery) {
+	const query = userQuery.trim();
+	if (!isXopcDatabaseOpen()) return {
+		retrievalQuery: query,
+		allocation: STANDARD
+	};
+	const taskId = taskIdForSession(sessionKey);
+	if (!taskId) return {
+		retrievalQuery: query,
+		allocation: STANDARD
+	};
+	const brief = getTaskExecutionBrief(taskId);
+	if (!brief) return {
+		taskId,
+		retrievalQuery: query,
+		allocation: STANDARD
+	};
+	const { task, latestReceipt, remainingCriteria, allocation, manifest } = brief;
+	const contract = task.contract;
+	return {
+		taskId,
+		retrievalQuery: [
+			query,
+			`Task: ${contract.objective}`,
+			contract.expectedOutputs.length ? `Expected outputs: ${contract.expectedOutputs.join("; ")}` : "",
+			remainingCriteria.length ? `Remaining acceptance criteria: ${remainingCriteria.join("; ")}` : "",
+			contract.constraints.length ? `Constraints: ${contract.constraints.join("; ")}` : "",
+			contract.risks.length ? `Risks: ${contract.risks.join("; ")}` : "",
+			latestReceipt?.summary ? `Latest run: ${latestReceipt.summary}` : ""
+		].filter(Boolean).join("\n"),
+		allocation,
+		manifest
+	};
+}
+function buildTaskExecutionDirective(sessionKey) {
+	const taskId = isXopcDatabaseOpen() ? taskIdForSession(sessionKey) : void 0;
+	const brief = taskId ? getTaskExecutionBrief(taskId) : void 0;
+	if (!brief) return "";
+	const { task, remainingCriteria } = brief;
+	const contract = task.contract;
+	return [
+		"<xopc_task_execution>",
+		"This conversation is executing a durable task.",
+		`Task: ${contract.objective}`,
+		`Expected outputs: ${contract.expectedOutputs.join("; ")}`,
+		`Remaining acceptance criteria: ${remainingCriteria.join("; ")}`,
+		contract.constraints.length ? `Constraints: ${contract.constraints.join("; ")}` : "",
+		contract.approvalRequired.length ? `Authority required: ${contract.approvalRequired.join("; ")}` : "",
+		"Take safe in-scope steps and produce inspectable evidence. Do not claim completion without verification.",
+		"</xopc_task_execution>"
+	].filter(Boolean).join("\n");
+}
+//#endregion
+export { assembleTaskContext, buildTaskExecutionDirective, getTaskContextManifest, getTaskExecutionBrief };

package/dist/src/tasks/task-context-repository.d.ts

@@ -0,0 +1,52 @@
+import type { ActorRef, TaskAuthorityGrant, TaskContextEdge, TaskContextRole } from '@xopcai/gateway-contract';
+export declare class TaskContextRepository {
+    captureSnapshot(input: {
+        ownerKind: 'task_run' | 'task' | 'session' | 'proactive_run';
+        ownerId: string;
+        query: string;
+        selectedItems?: unknown[];
+        rejectedItems?: unknown[];
+        consentRequests?: unknown[];
+        relationshipPolicy?: Record<string, unknown>;
+        authorizationSnapshot?: Record<string, unknown>;
+        sessionKey?: string;
+        estimatedTokens?: number;
+        allocation?: Record<string, unknown>;
+        contentHash?: string;
+        now?: number;
+    }): {
+        id: string;
+        traceId: string;
+    };
+    add(input: {
+        taskId: string;
+        targetKind: TaskContextEdge['targetKind'];
+        targetId: string;
+        role: TaskContextRole;
+        title?: string;
+        pinned?: boolean;
+        retrievalPolicy?: Record<string, unknown>;
+        metadata?: Record<string, unknown>;
+        createdBy: ActorRef;
+        now?: number;
+    }): TaskContextEdge;
+    list(taskId: string): TaskContextEdge[];
+    remove(taskId: string, edgeId: string): boolean;
+    grant(input: {
+        taskId: string;
+        capability: string;
+        scope?: Record<string, unknown>;
+        grantedBy: ActorRef;
+        expiresAt?: number;
+        now?: number;
+    }): TaskAuthorityGrant;
+    listActiveGrants(taskId: string, now?: number): TaskAuthorityGrant[];
+    revoke(grantId: string, now?: number): boolean;
+    linkSession(input: {
+        taskId: string;
+        sessionKey: string;
+        role: 'primary' | 'discussion' | 'execution';
+        now?: number;
+    }): void;
+    private requireGrant;
+}