@taskforcehq/taskforce 0.3.326 → 0.3.328

package/dist/mcp/durableTaskMutationRouter.js

@@ -0,0 +1,217 @@
+import { randomUUID } from 'crypto';
+import { LocalSyncIdentityStore } from '../sync/v3/localSyncIdentityStore.js';
+import { enqueueLocalTaskLifecycleMutation, } from '../sync/v3/localTaskLifecycleOutboxService.js';
+import { enqueueLocalTaskStatusMutation, } from '../sync/v3/localTaskStatusOutboxService.js';
+import { WorkspaceSyncDurabilityStore, } from '../sync/v3/syncDurabilityStore.js';
+import { runDurableTaskLifecycleMutation, } from '../sync/v3/taskLifecycleMutationService.js';
+import { runDurableTaskStatusMutation, } from '../sync/v3/taskStatusMutationService.js';
+import { runDurableTaskWorkflowMutation, } from '../sync/v3/taskWorkflowMutationService.js';
+import { readDurableOperationReplay } from '../sync/v3/durableOperationReplay.js';
+const OPERATION_LEASE_MS = 30_000;
+function isEnabled(value) {
+    return /^(1|true|on|yes)$/i.test(String(value || '').trim());
+}
+export function resolveMcpTaskStatusActivationCapability(input) {
+    const env = input.env || process.env;
+    const surfaceKey = 'TASKFORCE_SYNC_V3_TASK_STATUS_MCP_ACTIVATION_ENABLED';
+    const persistedStatusOwnership = input.runtimeMode === 'local'
+        && !Object.prototype.hasOwnProperty.call(env, surfaceKey)
+        && input.readPersistedProjectionOwner?.() === 'v3';
+    const shared = isEnabled(env.TASKFORCE_SYNC_V3_TASKS_ENABLED)
+        && isEnabled(env.TASKFORCE_SYNC_V3_TASK_STATUS_ENABLED);
+    return {
+        taskStatusMcpActivation: persistedStatusOwnership || (shared && (input.runtimeMode === 'cloud' || (isEnabled(env.TASKFORCE_SYNC_V3_TASK_STATUS_MCP_ACTIVATION_ENABLED)
+            && isEnabled(env.TASKFORCE_SYNC_V3_LOCAL_CAPTURE_ENABLED)
+            && isEnabled(env.TASKFORCE_SYNC_V3_LOCAL_DISPATCH_ENABLED)
+            && isEnabled(env.TASKFORCE_SYNC_V3_TASK_LIFECYCLE_CAPTURE_ENABLED)))),
+    };
+}
+export class DurableTaskMutationRouterDisabledError extends Error {
+    code = 'WORKSPACE_SYNC_V3_TASK_STATUS_MCP_DISABLED';
+    constructor() {
+        super('Durable MCP task status activation is disabled.');
+        this.name = 'DurableTaskMutationRouterDisabledError';
+    }
+}
+export class DurableTaskMutationRouterInProgressError extends Error {
+    retryAt;
+    code = 'WORKSPACE_SYNC_OPERATION_IN_PROGRESS';
+    constructor(retryAt) {
+        super('The durable MCP task mutation is already in progress.');
+        this.retryAt = retryAt;
+        this.name = 'DurableTaskMutationRouterInProgressError';
+    }
+}
+function defaultOperationId() {
+    return `operation-${randomUUID()}`;
+}
+function requireText(value, label) {
+    const normalized = String(value || '').trim();
+    if (!normalized)
+        throw new Error(`${label} is required.`);
+    return normalized;
+}
+export function createDurableTaskMutationRouter(input) {
+    const tenantId = requireText(input.tenantId, 'Tenant id');
+    const workspaceId = requireText(input.workspaceId, 'Workspace id');
+    const store = new WorkspaceSyncDurabilityStore(input.core.getDatabaseAdapter());
+    const resolveCapability = () => {
+        let persistedStatusOwnershipChecked = false;
+        const capability = resolveMcpTaskStatusActivationCapability({
+            runtimeMode: input.runtimeMode,
+            env: input.env,
+            readPersistedProjectionOwner: () => {
+                persistedStatusOwnershipChecked = true;
+                return store.readCombinedProjectionOwnership({ tenantId, workspaceId }).owner;
+            },
+        });
+        return { capability, persistedStatusOwnershipChecked };
+    };
+    const identityStore = new LocalSyncIdentityStore(input.core.getDatabaseAdapter());
+    const createOperationId = input.createOperationId || defaultOperationId;
+    const now = input.now || (() => new Date());
+    const operationContext = (enabled, mutationKind, taskId) => {
+        if (!enabled)
+            throw new DurableTaskMutationRouterDisabledError();
+        const acceptedAt = now();
+        const acceptedAtIso = acceptedAt.toISOString();
+        const operationId = requireText(createOperationId({ mutationKind, taskId }), 'Operation id');
+        const clientId = input.runtimeMode === 'local'
+            ? identityStore.getOrCreateClientId(acceptedAtIso)
+            : requireText(input.cloudClientId || 'mcp-cloud', 'Cloud client id');
+        return {
+            acceptedAt,
+            acceptedAtIso,
+            operationId,
+            identity: { tenantId, workspaceId, clientId, operationId },
+        };
+    };
+    const canonicalTask = (taskId) => {
+        const task = input.core.getTask(taskId, workspaceId);
+        if (!task)
+            throw new Error(`Task ${taskId} not found after durable mutation.`);
+        return task;
+    };
+    const cloudCommon = (taskId, actorRef, context, revisions) => ({
+        store,
+        core: input.core,
+        tenantId,
+        workspaceId,
+        clientId: context.identity.clientId,
+        operationId: context.operationId,
+        taskId,
+        baseEntityRevision: revisions.entityRevision,
+        baseLifecycleRevision: revisions.lifecycleRevision,
+        now: context.acceptedAtIso,
+        leaseExpiresAt: new Date(context.acceptedAt.getTime() + OPERATION_LEASE_MS).toISOString(),
+        actorRef,
+        onPostCommitError: input.onPostCommitError,
+    });
+    const cloudRevisions = (taskId, mutationKind, context) => {
+        const committedResponseJson = store.readCommittedOperationResponse(context.identity);
+        if (committedResponseJson) {
+            const replay = readDurableOperationReplay({
+                responseJson: committedResponseJson,
+                operationId: context.operationId,
+                domain: 'task',
+                entityId: taskId,
+                mutationKind,
+                revisionMode: 'both',
+                requirePayload: true,
+            });
+            return {
+                entityRevision: replay.baseEntityRevision,
+                lifecycleRevision: replay.baseLifecycleRevision,
+            };
+        }
+        return store.readEntityRevisionCoordinates({ tenantId, workspaceId, domain: 'task', entityId: taskId });
+    };
+    return {
+        get enabled() { return resolveCapability().capability.taskStatusMcpActivation; },
+        setStatus(args) {
+            const taskId = requireText(args.taskId, 'Task id');
+            const actorRef = requireText(args.actorRef, 'Actor ref');
+            const resolved = resolveCapability();
+            const context = operationContext(resolved.capability.taskStatusMcpActivation, 'set-status', taskId);
+            if (input.runtimeMode === 'local') {
+                const result = enqueueLocalTaskStatusMutation({
+                    store,
+                    core: input.core,
+                    identity: context.identity,
+                    taskId,
+                    payload: args.payload,
+                    now: context.acceptedAtIso,
+                    actorRef,
+                    requireV3CombinedOwnership: resolved.persistedStatusOwnershipChecked,
+                    onPostCommitError: input.onPostCommitError,
+                });
+                return {
+                    state: 'pending',
+                    route: 'local-outbox',
+                    operationId: context.operationId,
+                    task: result.task || canonicalTask(taskId),
+                };
+            }
+            const revisions = cloudRevisions(taskId, 'set-status', context);
+            const result = runDurableTaskStatusMutation({
+                ...cloudCommon(taskId, actorRef, context, revisions),
+                payload: args.payload,
+            });
+            if (result.state === 'in_progress')
+                throw new DurableTaskMutationRouterInProgressError(result.retryAt);
+            return {
+                state: 'committed',
+                route: 'cloud-acceptance',
+                operationId: context.operationId,
+                task: canonicalTask(taskId),
+            };
+        },
+        mutateLifecycle(args) {
+            const taskId = requireText(args.taskId, 'Task id');
+            const actorRef = requireText(args.actorRef, 'Actor ref');
+            const resolved = resolveCapability();
+            const context = operationContext(resolved.capability.taskStatusMcpActivation, args.mutationKind, taskId);
+            if (input.runtimeMode === 'local') {
+                const result = enqueueLocalTaskLifecycleMutation({
+                    store,
+                    core: input.core,
+                    identity: context.identity,
+                    taskId,
+                    mutationKind: args.mutationKind,
+                    payload: args.payload,
+                    now: context.acceptedAtIso,
+                    actorRef,
+                    requireV3CombinedOwnership: resolved.persistedStatusOwnershipChecked,
+                    onPostCommitError: input.onPostCommitError,
+                });
+                return {
+                    state: 'pending',
+                    route: 'local-outbox',
+                    operationId: context.operationId,
+                    task: result.task || canonicalTask(taskId),
+                };
+            }
+            const revisions = cloudRevisions(taskId, args.mutationKind, context);
+            const common = cloudCommon(taskId, actorRef, context, revisions);
+            const result = args.mutationKind === 'archive' || args.mutationKind === 'unarchive'
+                ? runDurableTaskLifecycleMutation({
+                    ...common,
+                    mutationKind: args.mutationKind,
+                    payload: args.payload,
+                })
+                : runDurableTaskWorkflowMutation({
+                    ...common,
+                    mutationKind: args.mutationKind,
+                    payload: args.payload,
+                });
+            if (result.state === 'in_progress')
+                throw new DurableTaskMutationRouterInProgressError(result.retryAt);
+            return {
+                state: 'committed',
+                route: 'cloud-acceptance',
+                operationId: context.operationId,
+                task: canonicalTask(taskId),
+            };
+        },
+    };
+}

package/dist/mcp/durableTaskRelationshipMutationRouter.d.ts

@@ -0,0 +1,38 @@
+import type { TaskRelationshipInputType, TaskRelationshipRecord } from '../core/Taskforce.js';
+import type { DatabaseAdapter } from '../storage/databaseAdapter.js';
+import { type LocalTaskRelationshipOutboxCore } from '../sync/v3/localTaskRelationshipOutboxService.js';
+import { type DurableTaskRelationshipServiceCore } from '../sync/v3/taskRelationshipMutationService.js';
+export declare function resolveMcpTaskRelationshipActivation(input: {
+    runtimeMode: 'local' | 'cloud';
+    env?: NodeJS.ProcessEnv;
+}): boolean;
+export type DurableTaskRelationshipMutationRouterCore = DurableTaskRelationshipServiceCore & LocalTaskRelationshipOutboxCore & {
+    getDatabaseAdapter(): DatabaseAdapter;
+};
+export type DurableMcpTaskRelationshipResult = {
+    state: 'noop' | 'pending' | 'committed';
+    route: 'no-change' | 'local-outbox' | 'cloud-acceptance';
+    operationId: string | null;
+    relationship: TaskRelationshipRecord | null;
+    outcome: 'created' | 'reactivated' | 'existing' | 'removed' | 'already_absent';
+};
+export declare function createDurableTaskRelationshipMutationRouter(input: {
+    core: DurableTaskRelationshipMutationRouterCore;
+    runtimeMode: 'local' | 'cloud';
+    tenantId: string;
+    workspaceId: string;
+    env?: NodeJS.ProcessEnv;
+    cloudClientId?: string;
+    createOperationId?: () => string;
+    now?: () => Date;
+    onPostCommitError?: (error: unknown) => void;
+}): {
+    enabled: boolean;
+    mutate(args: {
+        sourceTaskId: string;
+        targetTaskId: string;
+        type: TaskRelationshipInputType;
+        mutationKind: "link" | "unlink";
+        actorRef: string;
+    }): DurableMcpTaskRelationshipResult;
+};

package/dist/mcp/durableTaskRelationshipMutationRouter.js

@@ -0,0 +1,168 @@
+import { randomUUID } from 'crypto';
+import { LocalSyncIdentityStore } from '../sync/v3/localSyncIdentityStore.js';
+import { enqueueLocalTaskRelationshipMutation, } from '../sync/v3/localTaskRelationshipOutboxService.js';
+import { WorkspaceSyncDurabilityStore } from '../sync/v3/syncDurabilityStore.js';
+import { runDurableTaskRelationshipMutation, } from '../sync/v3/taskRelationshipMutationService.js';
+import { DurableOperationReplayIdentityConflictError, readDurableOperationReplay, } from '../sync/v3/durableOperationReplay.js';
+const OPERATION_LEASE_MS = 30_000;
+function enabled(value) {
+    return /^(1|true|on|yes)$/i.test(String(value || '').trim());
+}
+export function resolveMcpTaskRelationshipActivation(input) {
+    const env = input.env || process.env;
+    const shared = enabled(env.TASKFORCE_SYNC_V3_TASK_RELATIONSHIP_MCP_ACTIVATION_ENABLED)
+        && enabled(env.TASKFORCE_SYNC_V3_TASKS_ENABLED);
+    return shared && (input.runtimeMode === 'cloud' || (enabled(env.TASKFORCE_SYNC_V3_LOCAL_CAPTURE_ENABLED)
+        && enabled(env.TASKFORCE_SYNC_V3_LOCAL_DISPATCH_ENABLED)
+        && enabled(env.TASKFORCE_SYNC_V3_TASK_RELATIONSHIP_CAPTURE_ENABLED)));
+}
+export function createDurableTaskRelationshipMutationRouter(input) {
+    const isActive = resolveMcpTaskRelationshipActivation(input);
+    const store = new WorkspaceSyncDurabilityStore(input.core.getDatabaseAdapter());
+    const identityStore = new LocalSyncIdentityStore(input.core.getDatabaseAdapter());
+    const now = input.now || (() => new Date());
+    const createOperationId = input.createOperationId || (() => `operation-${randomUUID()}`);
+    return {
+        enabled: isActive,
+        mutate(args) {
+            if (!isActive)
+                throw new Error('Durable MCP task relationship activation is disabled.');
+            const canonical = input.core.resolveTaskRelationshipIdentity(args.sourceTaskId, args.targetTaskId, args.type, input.workspaceId);
+            const acceptedAt = now();
+            const acceptedAtIso = acceptedAt.toISOString();
+            const operationId = String(createOperationId() || '').trim();
+            if (!operationId)
+                throw new Error('Operation id is required.');
+            const clientId = input.runtimeMode === 'local'
+                ? identityStore.getOrCreateClientId(acceptedAtIso)
+                : String(input.cloudClientId || 'mcp-cloud').trim();
+            if (!clientId)
+                throw new Error('Client id is required.');
+            const identity = {
+                tenantId: input.tenantId,
+                workspaceId: input.workspaceId,
+                clientId,
+                operationId,
+            };
+            const current = input.core.getTaskRelationshipForSync(canonical.id, input.workspaceId);
+            const linkOutcome = (relationship) => (relationship.createdAt === relationship.updatedAt ? 'created' : 'reactivated');
+            if (input.runtimeMode === 'local') {
+                const persisted = store.readOutboxOperation(identity);
+                if (persisted && (persisted.domain !== 'task-relationship'
+                    || persisted.entityId !== canonical.id
+                    || persisted.mutationKind !== args.mutationKind)) {
+                    throw new Error('Operation identity is already assigned to another task relationship mutation.');
+                }
+                if (!persisted && args.mutationKind === 'link' && current && !current.deletedAt) {
+                    return { state: 'noop', route: 'no-change', operationId: null, relationship: current, outcome: 'existing' };
+                }
+                if (!persisted && args.mutationKind === 'unlink' && (!current || current.deletedAt)) {
+                    return { state: 'noop', route: 'no-change', operationId: null, relationship: current, outcome: 'already_absent' };
+                }
+                const captured = enqueueLocalTaskRelationshipMutation({
+                    store,
+                    core: input.core,
+                    identity,
+                    relationshipId: canonical.id,
+                    sourceTaskId: args.sourceTaskId,
+                    targetTaskId: args.targetTaskId,
+                    type: args.type,
+                    mutationKind: args.mutationKind,
+                    now: acceptedAtIso,
+                    actorRef: args.actorRef,
+                    onPostCommitError: input.onPostCommitError,
+                });
+                const relationship = captured.relationship
+                    || input.core.getTaskRelationshipForSync(canonical.id, input.workspaceId);
+                return {
+                    state: 'pending',
+                    route: 'local-outbox',
+                    operationId,
+                    relationship,
+                    outcome: args.mutationKind === 'unlink'
+                        ? 'removed'
+                        : captured.enqueued
+                            ? current ? 'reactivated' : 'created'
+                            : BigInt(persisted?.baseLifecycleRevision || '0') > 0n
+                                ? 'reactivated'
+                                : relationship ? linkOutcome(relationship) : 'created',
+                };
+            }
+            const operationState = store.readOperationStateForUpdate(identity);
+            if (operationState?.status === 'committed') {
+                let replay;
+                try {
+                    replay = readDurableOperationReplay({
+                        responseJson: String(operationState.responseJson || ''),
+                        operationId,
+                        domain: 'task-relationship',
+                        entityId: canonical.id,
+                        mutationKind: args.mutationKind,
+                        revisionMode: 'metadata',
+                        requirePayload: true,
+                    });
+                }
+                catch (error) {
+                    if (error instanceof DurableOperationReplayIdentityConflictError) {
+                        throw new Error('Operation identity is already assigned to another task relationship mutation.');
+                    }
+                    throw new Error('Committed durable task relationship response is invalid.');
+                }
+                const relationship = replay.authoritative.payload;
+                return {
+                    state: 'committed',
+                    route: 'cloud-acceptance',
+                    operationId,
+                    relationship,
+                    outcome: args.mutationKind === 'unlink'
+                        ? 'removed'
+                        : BigInt(replay.authoritative.lifecycleRevision || '0') > 0n ? 'reactivated' : 'created',
+                };
+            }
+            if (!operationState && args.mutationKind === 'link' && current && !current.deletedAt) {
+                return { state: 'noop', route: 'no-change', operationId: null, relationship: current, outcome: 'existing' };
+            }
+            if (!operationState && args.mutationKind === 'unlink' && (!current || current.deletedAt)) {
+                return { state: 'noop', route: 'no-change', operationId: null, relationship: current, outcome: 'already_absent' };
+            }
+            const revisions = store.readEntityRevisionCoordinates({
+                tenantId: input.tenantId,
+                workspaceId: input.workspaceId,
+                domain: 'task-relationship',
+                entityId: canonical.id,
+            });
+            const result = runDurableTaskRelationshipMutation({
+                store,
+                core: input.core,
+                tenantId: input.tenantId,
+                workspaceId: input.workspaceId,
+                clientId,
+                operationId,
+                sourceTaskId: args.sourceTaskId,
+                targetTaskId: args.targetTaskId,
+                type: args.type,
+                mutationKind: args.mutationKind,
+                baseEntityRevision: revisions.entityRevision,
+                baseLifecycleRevision: revisions.lifecycleRevision,
+                now: acceptedAtIso,
+                leaseExpiresAt: new Date(acceptedAt.getTime() + OPERATION_LEASE_MS).toISOString(),
+                actorRef: args.actorRef,
+                onPostCommitError: input.onPostCommitError,
+            });
+            if (result.state === 'in_progress') {
+                const error = new Error('The durable task relationship mutation is already in progress.');
+                Object.assign(error, { code: 'WORKSPACE_SYNC_OPERATION_IN_PROGRESS', statusCode: 409, retryAt: result.retryAt });
+                throw error;
+            }
+            return {
+                state: 'committed',
+                route: 'cloud-acceptance',
+                operationId,
+                relationship: result.response.authoritative.payload,
+                outcome: args.mutationKind === 'unlink'
+                    ? 'removed'
+                    : BigInt(result.response.authoritative.lifecycleRevision) > 0n ? 'reactivated' : 'created',
+            };
+        },
+    };
+}

package/dist/mcp/durableTaskRootMutationRouter.d.ts

@@ -0,0 +1,64 @@
+import type { TaskItem } from '../core/Taskforce.js';
+import type { DatabaseAdapter } from '../storage/databaseAdapter.js';
+import { type LocalTaskCreateOutboxCore } from '../sync/v3/localTaskCreateOutboxService.js';
+import { type LocalTaskMetadataOutboxCore } from '../sync/v3/localTaskMetadataOutboxService.js';
+import { type DurableTaskCreateServiceCore } from '../sync/v3/taskCreateMutationService.js';
+import { type DurableTaskMetadataServiceCore } from '../sync/v3/taskMetadataMutationService.js';
+export declare function resolveMcpTaskRootActivationCapability(input: {
+    runtimeMode: 'local' | 'cloud';
+    env?: NodeJS.ProcessEnv;
+    readPersistedProjectionOwner?: () => 'v2' | 'v3';
+}): {
+    taskCreateMcpActivation: boolean;
+    taskMetadataMcpActivation: boolean;
+};
+export type DurableTaskRootMutationRouterCore = DurableTaskCreateServiceCore & LocalTaskCreateOutboxCore & DurableTaskMetadataServiceCore & LocalTaskMetadataOutboxCore & {
+    getDatabaseAdapter(): DatabaseAdapter;
+    getTask(id: string, workspaceId?: string): TaskItem | null;
+};
+export type DurableMcpTaskRootMutationResult = {
+    state: 'pending' | 'committed';
+    route: 'local-outbox' | 'cloud-acceptance';
+    operationId: string;
+    replayed: boolean;
+    task: TaskItem;
+};
+export declare class DurableTaskRootMutationRouterDisabledError extends Error {
+    readonly code = "WORKSPACE_SYNC_V3_TASK_ROOT_MCP_DISABLED";
+    constructor();
+}
+export declare class DurableTaskRootMutationRouterInProgressError extends Error {
+    readonly retryAt: string;
+    readonly code = "WORKSPACE_SYNC_OPERATION_IN_PROGRESS";
+    constructor(retryAt: string);
+}
+export declare function createDurableTaskRootMutationRouter(input: {
+    core: DurableTaskRootMutationRouterCore;
+    runtimeMode: 'local' | 'cloud';
+    tenantId: string;
+    workspaceId: string;
+    env?: NodeJS.ProcessEnv;
+    cloudClientId?: string;
+    createOperationId?: (input: {
+        mutationKind: 'create' | 'metadata-update';
+        taskId: string;
+        operationKey?: string;
+    }) => string;
+    now?: () => Date;
+    onPostCommitError?: (error: unknown) => void;
+}): {
+    readonly createEnabled: boolean;
+    readonly metadataEnabled: boolean;
+    create(args: {
+        taskId: string;
+        task: Partial<TaskItem>;
+        actorRef: string;
+        operationKey?: string;
+    }): DurableMcpTaskRootMutationResult;
+    updateMetadata(args: {
+        taskId: string;
+        patch: Partial<TaskItem>;
+        actorRef: string;
+        operationKey?: string;
+    }): DurableMcpTaskRootMutationResult;
+};