@xopcai/xopc 0.0.312 → 0.0.314

package/dist/src/storage/sqlite/transaction.js

@@ -5,6 +5,12 @@ function nextSavepointName() {
 	nextSavepointId += 1;
 	return `xopc_tx_${nextSavepointId}`;
 }
+/** Schedule a synchronous effect after an owned transaction commits. Persist its recovery intent first. */
+function afterSqliteCommit(effect) {
+	const effects = commitEffectsByDatabase.get(getSqliteDatabase());
+	if (!effects) throw new Error("Commit effects require a transaction owned by runSqliteWriteTransaction");
+	effects.push(effect);
+}
 function getTransactionDepth(db) {
 	return transactionDepthByDatabase.get(db) ?? 0;
 }
@@ -54,6 +60,8 @@ function runSqliteWriteTransaction(fn) {
 	const { db } = getXopcDatabase();
 	const depth = getTransactionDepth(db);
 	if (depth > 0) {
+		const effects = commitEffectsByDatabase.get(db);
+		const effectCount = effects?.length ?? 0;
 		const savepoint = nextSavepointName();
 		db.exec(`SAVEPOINT ${savepoint}`);
 		setTransactionDepth(db, depth + 1);
@@ -63,6 +71,7 @@ function runSqliteWriteTransaction(fn) {
 			db.exec(`RELEASE SAVEPOINT ${savepoint}`);
 			return result;
 		} catch (error) {
+			effects?.splice(effectCount);
 			try {
 				db.exec(`ROLLBACK TO SAVEPOINT ${savepoint}`);
 			} finally {
@@ -75,12 +84,15 @@ function runSqliteWriteTransaction(fn) {
 	}
 	db.exec("BEGIN IMMEDIATE");
 	setTransactionDepth(db, 1);
+	const effects = [];
+	commitEffectsByDatabase.set(db, effects);
 	let transactionActive = true;
 	let result;
 	try {
 		result = fn(db);
 		assertSyncTransactionResult(result);
 	} catch (error) {
+		commitEffectsByDatabase.delete(db);
 		try {
 			abortImmediateTransaction(db);
 			transactionActive = false;
@@ -92,8 +104,8 @@ function runSqliteWriteTransaction(fn) {
 	try {
 		commitImmediateTransaction(db);
 		transactionActive = false;
-		return result;
 	} catch (error) {
+		commitEffectsByDatabase.delete(db);
 		try {
 			abortImmediateTransaction(db);
 			transactionActive = false;
@@ -102,6 +114,15 @@ function runSqliteWriteTransaction(fn) {
 	} finally {
 		if (!transactionActive) setTransactionDepth(db, 0);
 	}
+	commitEffectsByDatabase.delete(db);
+	let failure;
+	for (const effect of effects) try {
+		assertSyncTransactionResult(effect());
+	} catch (error) {
+		failure ??= { error };
+	}
+	if (failure) throw new SqliteCommitEffectError(failure.error);
+	return result;
 }
 function getSqliteDatabase() {
 	return getXopcDatabase().db;
@@ -110,6 +131,8 @@ function getSqliteDatabase() {
 function runSqliteSavepoint(db, operation) {
 	const name = nextSavepointName();
 	const depth = getTransactionDepth(db);
+	const effects = commitEffectsByDatabase.get(db);
+	const effectCount = effects?.length ?? 0;
 	db.exec(`SAVEPOINT ${name}`);
 	setTransactionDepth(db, depth + 1);
 	try {
@@ -118,6 +141,7 @@ function runSqliteSavepoint(db, operation) {
 		db.exec(`RELEASE ${name}`);
 		return result;
 	} catch (error) {
+		effects?.splice(effectCount);
 		db.exec(`ROLLBACK TO ${name}`);
 		db.exec(`RELEASE ${name}`);
 		throw error;
@@ -125,14 +149,21 @@ function runSqliteSavepoint(db, operation) {
 		setTransactionDepth(db, depth);
 	}
 }
-var RETRYABLE_COMMIT_CODES, MAX_COMMIT_ATTEMPTS, nextSavepointId, transactionDepthByDatabase;
+var RETRYABLE_COMMIT_CODES, MAX_COMMIT_ATTEMPTS, nextSavepointId, transactionDepthByDatabase, commitEffectsByDatabase, SqliteCommitEffectError;
 var init_transaction = __esmMin((() => {
 	init_connection();
 	RETRYABLE_COMMIT_CODES = new Set(["SQLITE_BUSY", "SQLITE_LOCKED"]);
 	MAX_COMMIT_ATTEMPTS = 8;
 	nextSavepointId = 0;
 	transactionDepthByDatabase = /* @__PURE__ */ new WeakMap();
+	commitEffectsByDatabase = /* @__PURE__ */ new WeakMap();
+	SqliteCommitEffectError = class extends Error {
+		constructor(cause) {
+			super("Transaction committed; post-commit work is pending recovery", { cause });
+			this.name = "SqliteCommitEffectError";
+		}
+	};
 }));
 //#endregion
 init_transaction();
-export { getSqliteDatabase, init_transaction, runSqliteSavepoint, runSqliteWriteTransaction };
+export { SqliteCommitEffectError, afterSqliteCommit, getSqliteDatabase, init_transaction, runSqliteSavepoint, runSqliteWriteTransaction };

package/dist/src/tasks/capabilities/management.d.ts

@@ -0,0 +1,195 @@
+import { z } from 'zod';
+import { type CapabilityDispatcher } from '../../capabilities/runtime/dispatcher.js';
+export declare const TaskEditOutputSchema: z.ZodObject<{
+    ok: z.ZodLiteral<true>;
+    task: z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        body: z.ZodOptional<z.ZodString>;
+        phase: z.ZodEnum<{
+            backlog: "backlog";
+            ready: "ready";
+            active: "active";
+            review: "review";
+            closed: "closed";
+        }>;
+        resolution: z.ZodOptional<z.ZodEnum<{
+            cancelled: "cancelled";
+            done: "done";
+            duplicate: "duplicate";
+            wont_do: "wont_do";
+        }>>;
+        priority: z.ZodEnum<{
+            low: "low";
+            normal: "normal";
+            high: "high";
+            critical: "critical";
+        }>;
+        dueAt: z.ZodOptional<z.ZodNumber>;
+        projectId: z.ZodOptional<z.ZodString>;
+        milestoneId: z.ZodOptional<z.ZodString>;
+        parentTaskId: z.ZodOptional<z.ZodString>;
+        ownerId: z.ZodOptional<z.ZodString>;
+        delegateAgentId: z.ZodOptional<z.ZodString>;
+        source: z.ZodString;
+        locale: z.ZodOptional<z.ZodEnum<{
+            en: "en";
+            zh: "zh";
+        }>>;
+        latestContractVersion: z.ZodNumber;
+        boardRank: z.ZodDefault<z.ZodNumber>;
+        version: z.ZodNumber;
+        contract: z.ZodOptional<z.ZodObject<{
+            taskId: z.ZodString;
+            version: z.ZodNumber;
+            objective: z.ZodString;
+            expectedOutputs: z.ZodArray<z.ZodString>;
+            acceptanceCriteria: z.ZodArray<z.ZodString>;
+            constraints: z.ZodArray<z.ZodString>;
+            approvalRequired: z.ZodArray<z.ZodString>;
+            assumptions: z.ZodArray<z.ZodString>;
+            risks: z.ZodArray<z.ZodString>;
+            acceptancePolicy: z.ZodEnum<{
+                verified_auto: "verified_auto";
+                verified_then_review: "verified_then_review";
+                manual: "manual";
+            }>;
+            outputDestinations: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+            createdBy: z.ZodObject<{
+                kind: z.ZodEnum<{
+                    user: "user";
+                    agent: "agent";
+                    system: "system";
+                    integration: "integration";
+                }>;
+                id: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>;
+            createdAt: z.ZodNumber;
+        }, z.core.$strip>>;
+        createdAt: z.ZodNumber;
+        updatedAt: z.ZodNumber;
+        closedAt: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export declare const TaskDeleteOutputSchema: z.ZodUnion<readonly [z.ZodObject<{
+    ok: z.ZodLiteral<true>;
+    task: z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        body: z.ZodOptional<z.ZodString>;
+        phase: z.ZodEnum<{
+            backlog: "backlog";
+            ready: "ready";
+            active: "active";
+            review: "review";
+            closed: "closed";
+        }>;
+        resolution: z.ZodOptional<z.ZodEnum<{
+            cancelled: "cancelled";
+            done: "done";
+            duplicate: "duplicate";
+            wont_do: "wont_do";
+        }>>;
+        priority: z.ZodEnum<{
+            low: "low";
+            normal: "normal";
+            high: "high";
+            critical: "critical";
+        }>;
+        dueAt: z.ZodOptional<z.ZodNumber>;
+        projectId: z.ZodOptional<z.ZodString>;
+        milestoneId: z.ZodOptional<z.ZodString>;
+        parentTaskId: z.ZodOptional<z.ZodString>;
+        ownerId: z.ZodOptional<z.ZodString>;
+        delegateAgentId: z.ZodOptional<z.ZodString>;
+        source: z.ZodString;
+        locale: z.ZodOptional<z.ZodEnum<{
+            en: "en";
+            zh: "zh";
+        }>>;
+        latestContractVersion: z.ZodNumber;
+        boardRank: z.ZodDefault<z.ZodNumber>;
+        version: z.ZodNumber;
+        contract: z.ZodOptional<z.ZodObject<{
+            taskId: z.ZodString;
+            version: z.ZodNumber;
+            objective: z.ZodString;
+            expectedOutputs: z.ZodArray<z.ZodString>;
+            acceptanceCriteria: z.ZodArray<z.ZodString>;
+            constraints: z.ZodArray<z.ZodString>;
+            approvalRequired: z.ZodArray<z.ZodString>;
+            assumptions: z.ZodArray<z.ZodString>;
+            risks: z.ZodArray<z.ZodString>;
+            acceptancePolicy: z.ZodEnum<{
+                verified_auto: "verified_auto";
+                verified_then_review: "verified_then_review";
+                manual: "manual";
+            }>;
+            outputDestinations: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+            createdBy: z.ZodObject<{
+                kind: z.ZodEnum<{
+                    user: "user";
+                    agent: "agent";
+                    system: "system";
+                    integration: "integration";
+                }>;
+                id: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>;
+            createdAt: z.ZodNumber;
+        }, z.core.$strip>>;
+        createdAt: z.ZodNumber;
+        updatedAt: z.ZodNumber;
+        closedAt: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    ok: z.ZodLiteral<false>;
+    reason: z.ZodLiteral<"not_found">;
+}, z.core.$strip>, z.ZodObject<{
+    ok: z.ZodLiteral<false>;
+    reason: z.ZodLiteral<"active_run">;
+    run: z.ZodObject<{
+        id: z.ZodString;
+        taskId: z.ZodString;
+        rootRunId: z.ZodString;
+        parentRunId: z.ZodOptional<z.ZodString>;
+        attempt: z.ZodNumber;
+        status: z.ZodEnum<{
+            failed: "failed";
+            succeeded: "succeeded";
+            waiting: "waiting";
+            cancelled: "cancelled";
+            queued: "queued";
+            running: "running";
+            verifying: "verifying";
+        }>;
+        executorKind: z.ZodEnum<{
+            agent: "agent";
+            workflow: "workflow";
+            human: "human";
+            external: "external";
+        }>;
+        executorRef: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        trigger: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        correlationId: z.ZodString;
+        causationId: z.ZodOptional<z.ZodString>;
+        idempotencyKey: z.ZodString;
+        contractVersion: z.ZodNumber;
+        contextSnapshotId: z.ZodOptional<z.ZodString>;
+        policySnapshot: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        conversationId: z.ZodOptional<z.ZodString>;
+        queuedAt: z.ZodNumber;
+        scheduledAt: z.ZodOptional<z.ZodNumber>;
+        startedAt: z.ZodOptional<z.ZodNumber>;
+        heartbeatAt: z.ZodOptional<z.ZodNumber>;
+        completedAt: z.ZodOptional<z.ZodNumber>;
+        timeoutAt: z.ZodOptional<z.ZodNumber>;
+        leaseOwner: z.ZodOptional<z.ZodString>;
+        leaseExpiresAt: z.ZodOptional<z.ZodNumber>;
+        retryPolicy: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        retryOfRunId: z.ZodOptional<z.ZodString>;
+        terminalCode: z.ZodOptional<z.ZodString>;
+        terminalMessage: z.ZodOptional<z.ZodString>;
+        version: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>]>;
+export declare function registerTaskManagementCapabilities(dispatcher: CapabilityDispatcher, wake?: (runs: boolean) => void): void;

package/dist/src/tasks/capabilities/management.js

@@ -0,0 +1,111 @@
+import { getSqliteDatabase, init_transaction } from "../../storage/sqlite/transaction.js";
+import { TaskRunSchema } from "../../../packages/gateway-contract/src/task-runs.js";
+import { TaskBoardPositionRequestSchema, TaskPatchRequestSchema, TaskSchema } from "../../../packages/gateway-contract/src/tasks.js";
+import { init_src } from "../../../packages/gateway-contract/src/index.js";
+import { enqueueTaskChangedEvent, init_task_change_events } from "../task-change-events.js";
+import { TaskRepository, init_task_repository } from "../task-repository.js";
+import { CapabilityError } from "../../capabilities/runtime/errors.js";
+import { defineAtomicCapability } from "../../capabilities/runtime/dispatcher.js";
+import { TaskDeletionService } from "../task-deletion-service.js";
+import { z } from "zod";
+//#region src/tasks/capabilities/management.ts
+init_src();
+init_transaction();
+init_task_change_events();
+init_task_repository();
+const TaskEditOutputSchema = z.object({
+	ok: z.literal(true),
+	task: TaskSchema
+});
+const TaskDeleteOutputSchema = z.union([
+	z.object({
+		ok: z.literal(true),
+		task: TaskSchema
+	}),
+	z.object({
+		ok: z.literal(false),
+		reason: z.literal("not_found")
+	}),
+	z.object({
+		ok: z.literal(false),
+		reason: z.literal("active_run"),
+		run: TaskRunSchema
+	})
+]);
+function registerTaskManagementCapabilities(dispatcher, wake) {
+	const tasks = new TaskRepository();
+	const policy = {
+		majorVersion: 1,
+		effect: "local-write",
+		surfaces: ["http"],
+		scopes: ["tasks.write"],
+		afterCommit: () => wake?.(false)
+	};
+	dispatcher.register(defineAtomicCapability({
+		...policy,
+		id: "xopc.tasks.update",
+		description: "Update task metadata at an exact version.",
+		input: TaskPatchRequestSchema.extend({ taskId: z.string().min(1) }),
+		output: TaskEditOutputSchema,
+		execute({ taskId, ...patch }, caller) {
+			const task = tasks.update(taskId, patch);
+			if (!task) throw new CapabilityError("REVISION_CONFLICT", "Task changed or was not found");
+			enqueueTaskChangedEvent(getSqliteDatabase(), {
+				taskId,
+				projectId: task.projectId,
+				version: task.version,
+				changedFields: Object.keys(patch).filter((field) => field !== "expectedVersion"),
+				actor: caller.actor
+			});
+			return {
+				ok: true,
+				task
+			};
+		}
+	}));
+	dispatcher.register(defineAtomicCapability({
+		...policy,
+		id: "xopc.tasks.reorder",
+		description: "Reorder a task in its current board at an exact version.",
+		input: TaskBoardPositionRequestSchema.extend({ taskId: z.string().min(1) }),
+		output: TaskEditOutputSchema,
+		execute(input, caller) {
+			let task;
+			try {
+				task = tasks.reorder(input);
+			} catch (error) {
+				throw new CapabilityError("INVALID_INPUT", error instanceof Error ? error.message : "Invalid board position");
+			}
+			if (!task) throw new CapabilityError("REVISION_CONFLICT", "Task changed or was not found");
+			enqueueTaskChangedEvent(getSqliteDatabase(), {
+				taskId: task.id,
+				projectId: task.projectId,
+				version: task.version,
+				changedFields: ["boardRank"],
+				actor: caller.actor
+			});
+			return {
+				ok: true,
+				task
+			};
+		}
+	}));
+	dispatcher.register(defineAtomicCapability({
+		...policy,
+		surfaces: ["http", "agent"],
+		id: "xopc.tasks.delete",
+		description: "Delete a task only when no active run exists.",
+		input: z.strictObject({
+			taskId: z.string().min(1),
+			expectedVersion: z.number().int().positive().optional()
+		}),
+		output: TaskDeleteOutputSchema,
+		execute(input) {
+			const task = tasks.get(input.taskId);
+			if (task && input.expectedVersion !== void 0 && task.version !== input.expectedVersion) throw new CapabilityError("REVISION_CONFLICT", "Task changed");
+			return new TaskDeletionService().delete(input.taskId);
+		}
+	}));
+}
+//#endregion
+export { TaskDeleteOutputSchema, TaskEditOutputSchema, registerTaskManagementCapabilities };

package/dist/src/tasks/capabilities/read.d.ts

@@ -0,0 +1,2 @@
+import { type CapabilityDispatcher } from '../../capabilities/runtime/dispatcher.js';
+export declare function registerTaskReadCapabilities(dispatcher: CapabilityDispatcher): void;

package/dist/src/tasks/capabilities/read.js

@@ -0,0 +1,141 @@
+import { ProductReadContracts } from "../../../packages/gateway-contract/src/capabilities.js";
+import { init_src } from "../../../packages/gateway-contract/src/index.js";
+import { TaskRepository, init_task_repository } from "../task-repository.js";
+import { TaskRunRepository, init_task_run_repository } from "../task-run-repository.js";
+import { TaskConversationRepository } from "../task-conversation-repository.js";
+import { TaskReadModelProjector } from "../task-read-model-projector.js";
+import { CapabilityError } from "../../capabilities/runtime/errors.js";
+import { defineReadCapability } from "../../capabilities/runtime/dispatcher.js";
+import { TaskContextRepository } from "../task-context-repository.js";
+import { TaskDependencyService } from "../task-dependency-service.js";
+import { TaskValueMetricsService } from "../task-value-metrics-service.js";
+//#region src/tasks/capabilities/read.ts
+init_src();
+init_task_repository();
+init_task_run_repository();
+function registerTaskReadCapabilities(dispatcher) {
+	dispatcher.register(defineReadCapability({
+		id: "xopc.tasks.metrics",
+		majorVersion: 1,
+		description: "Read task outcome metrics for this personal workspace.",
+		effect: "read",
+		surfaces: [
+			"http",
+			"agent",
+			"cli"
+		],
+		scopes: ["tasks.read"],
+		...ProductReadContracts["xopc.tasks.metrics"],
+		execute: () => ({
+			ok: true,
+			metrics: new TaskValueMetricsService().get()
+		})
+	}));
+	const tasks = new TaskRepository();
+	const runs = new TaskRunRepository();
+	const projector = new TaskReadModelProjector();
+	const context = new TaskContextRepository();
+	const conversations = new TaskConversationRepository();
+	const dependencies = new TaskDependencyService();
+	dispatcher.register(defineReadCapability({
+		id: "xopc.task_runs.get",
+		majorVersion: 1,
+		description: "Read a task run, receipt, events and active waits.",
+		effect: "read",
+		surfaces: [
+			"http",
+			"agent",
+			"cli"
+		],
+		scopes: ["tasks.read"],
+		...ProductReadContracts["xopc.task_runs.get"],
+		execute({ id }) {
+			const run = runs.get(id);
+			if (!run) throw new CapabilityError("NOT_FOUND", `TaskRun not found: ${id}`);
+			return {
+				ok: true,
+				run,
+				receipt: runs.getReceipt(id),
+				events: runs.listEvents(id),
+				activeWaits: runs.listActiveWaits(run.taskId)
+			};
+		}
+	}));
+	dispatcher.register(defineReadCapability({
+		id: "xopc.task_runs.list",
+		majorVersion: 1,
+		description: "List executions and receipts for a task.",
+		effect: "read",
+		surfaces: [
+			"http",
+			"agent",
+			"cli"
+		],
+		scopes: ["tasks.read"],
+		...ProductReadContracts["xopc.task_runs.list"],
+		execute({ taskId, limit }) {
+			if (!tasks.get(taskId)) throw new CapabilityError("NOT_FOUND", `Task not found: ${taskId}`);
+			return {
+				ok: true,
+				taskId,
+				items: runs.listByTask(taskId, limit),
+				receipts: runs.listReceipts(taskId, limit),
+				activeWaits: runs.listActiveWaits(taskId)
+			};
+		}
+	}));
+	dispatcher.register(defineReadCapability({
+		id: "xopc.tasks.get",
+		majorVersion: 1,
+		description: "Read a task, its current execution, context and dependencies.",
+		effect: "read",
+		surfaces: [
+			"http",
+			"agent",
+			"cli",
+			"extension"
+		],
+		scopes: ["tasks.read"],
+		...ProductReadContracts["xopc.tasks.get"],
+		execute({ id }) {
+			const task = tasks.get(id);
+			if (!task) throw new CapabilityError("NOT_FOUND", `Task not found: ${id}`);
+			return {
+				ok: true,
+				...projector.project(task),
+				waits: runs.listActiveWaits(id),
+				runs: runs.listByTask(id),
+				receipts: runs.listReceipts(id),
+				context: context.list(id),
+				conversation: conversations.requireState(id),
+				sessions: conversations.listSessions(id),
+				authorityGrants: context.listActiveGrants(id),
+				dependencies: dependencies.listDependencies(id),
+				dependents: dependencies.listDependents(id)
+			};
+		}
+	}));
+	dispatcher.register(defineReadCapability({
+		id: "xopc.tasks.list",
+		majorVersion: 1,
+		description: "List tasks with filters and pagination.",
+		effect: "read",
+		surfaces: [
+			"http",
+			"agent",
+			"cli",
+			"extension"
+		],
+		scopes: ["tasks.read"],
+		...ProductReadContracts["xopc.tasks.list"],
+		execute(input) {
+			return {
+				ok: true,
+				items: tasks.list(input).map((task) => projector.project(task)),
+				total: tasks.count(input)
+			};
+		}
+	}));
+}
+//#endregion
+export { registerTaskReadCapabilities };