@taskforcehq/taskforce 0.3.326 → 0.3.327

package/dist/hooks/sync/useDataVersionRefresh.js

@@ -1,6 +1,122 @@
-import { useEffect } from 'react';
+import { useEffect, useRef } from 'react';
 import { shouldSkipDataVersionPolling, shouldSkipDataVersionTick } from '../auth/useAuthGuardPolicy';
-export function useDataVersionRefresh({ isOpen, authBlocked, authRequiredForApi, isAuthenticated, canCallProtectedApi, shouldGateProtectedApiCalls, authSessionResolvedRef, authRequiredForApiRef, isAuthenticatedRef, dataVersionRef, refreshTaskCollectionsForDataVersion }) {
+import { dispatchTaskforceWorkspaceResourcesInvalidated } from '../../utils/workspaceResourceEvents';
+export function useDataVersionRefresh({ workspaceId, isOpen, authBlocked, authRequiredForApi, isAuthenticated, canCallProtectedApi, shouldGateProtectedApiCalls, authSessionResolvedRef, authRequiredForApiRef, isAuthenticatedRef, dataVersionRef, refreshTaskCollectionsForDataVersion, coordinatorDataVersion = null, }) {
+    const refreshTaskCollectionsRef = useRef(refreshTaskCollectionsForDataVersion);
+    refreshTaskCollectionsRef.current = refreshTaskCollectionsForDataVersion;
+    const refreshStateRef = useRef({
+        scopeKey: null,
+        workspaceId: '',
+        scopeEpoch: 0,
+        renderedVersion: null,
+        pendingVersion: null,
+        sourceVersions: new Map(),
+        inFlight: null,
+    });
+    const mountedRef = useRef(true);
+    useEffect(() => {
+        mountedRef.current = true;
+        return () => {
+            mountedRef.current = false;
+        };
+    }, []);
+    const hasAuthoritativeCoordinatorVersion = Boolean(coordinatorDataVersion
+        && Number.isSafeInteger(coordinatorDataVersion.coordinatorGeneration)
+        && coordinatorDataVersion.coordinatorGeneration > 0
+        && Number.isSafeInteger(coordinatorDataVersion.localDataVersion)
+        && coordinatorDataVersion.localDataVersion >= 0);
+    const pumpRefresh = () => {
+        const state = refreshStateRef.current;
+        if (!mountedRef.current
+            || state.inFlight
+            || state.pendingVersion === null
+            || typeof document === 'undefined'
+            || document.visibilityState !== 'visible')
+            return;
+        const targetVersion = state.pendingVersion;
+        if (state.renderedVersion !== null
+            && targetVersion <= state.renderedVersion)
+            return;
+        const scopeKey = state.scopeKey;
+        const scopeEpoch = state.scopeEpoch;
+        let succeeded = false;
+        let superseded = false;
+        const request = refreshTaskCollectionsRef.current()
+            .then(() => {
+            if (!mountedRef.current
+                || refreshStateRef.current.scopeKey !== scopeKey
+                || refreshStateRef.current.scopeEpoch !== scopeEpoch) {
+                superseded = true;
+                return;
+            }
+            succeeded = true;
+            refreshStateRef.current.renderedVersion = targetVersion;
+            dataVersionRef.current = targetVersion;
+            dispatchTaskforceWorkspaceResourcesInvalidated({
+                workspaceId: refreshStateRef.current.workspaceId,
+                source: 'data-version',
+                dataVersion: targetVersion,
+            });
+        })
+            .catch(() => {
+            // A later coordinator status, poll, or lifecycle signal retries.
+        })
+            .finally(() => {
+            if (refreshStateRef.current.inFlight === request) {
+                refreshStateRef.current.inFlight = null;
+            }
+            if (succeeded || superseded)
+                pumpRefresh();
+        });
+        state.inFlight = request;
+    };
+    const observeVersion = (sourceKey, version, options) => {
+        if (!Number.isSafeInteger(version) || version < 0)
+            return;
+        const state = refreshStateRef.current;
+        const scopeKey = workspaceId;
+        if (state.scopeKey !== scopeKey) {
+            state.scopeKey = scopeKey;
+            state.workspaceId = workspaceId;
+            state.scopeEpoch += 1;
+            state.renderedVersion = null;
+            state.pendingVersion = null;
+            state.sourceVersions = new Map();
+            dataVersionRef.current = null;
+        }
+        const previousSourceVersion = state.sourceVersions.get(sourceKey);
+        if (previousSourceVersion !== undefined && (options.monotonic
+            ? version <= previousSourceVersion
+            : version === previousSourceVersion)) {
+            pumpRefresh();
+            return;
+        }
+        state.sourceVersions.set(sourceKey, version);
+        if (options.establishBaseline && previousSourceVersion === undefined) {
+            if (state.renderedVersion === null
+                && state.pendingVersion === null
+                && !state.inFlight) {
+                state.renderedVersion = version;
+                state.pendingVersion = version;
+                dataVersionRef.current = version;
+            }
+            return;
+        }
+        const currentHighWater = Math.max(state.renderedVersion ?? 0, state.pendingVersion ?? 0);
+        state.pendingVersion = currentHighWater === 0
+            ? version
+            : Math.max(currentHighWater + 1, version);
+        pumpRefresh();
+    };
+    useEffect(() => {
+        if (!hasAuthoritativeCoordinatorVersion || !coordinatorDataVersion)
+            return;
+        observeVersion(`${workspaceId}:coordinator:${coordinatorDataVersion.coordinatorGeneration}`, coordinatorDataVersion.localDataVersion, { monotonic: true, establishBaseline: false });
+    }, [
+        coordinatorDataVersion,
+        hasAuthoritativeCoordinatorVersion,
+        workspaceId,
+    ]);
     useEffect(() => {
         if (typeof window === 'undefined' || typeof document === 'undefined')
             return;
@@ -29,16 +145,9 @@ export function useDataVersionRefresh({ isOpen, authBlocked, authRequiredForApi,
                     return;
                 const data = await res.json();
                 const version = Number(data?.dataVersion);
-                if (!Number.isFinite(version))
-                    return;
-                if (dataVersionRef.current === null) {
-                    dataVersionRef.current = version;
+                if (cancelled)
                     return;
-                }
-                if (version !== dataVersionRef.current) {
-                    dataVersionRef.current = version;
-                    await refreshTaskCollectionsForDataVersion();
-                }
+                observeVersion(`${workspaceId}:legacy`, version, { monotonic: false, establishBaseline: true });
             }
             catch {
                 // best effort only
@@ -49,16 +158,23 @@ export function useDataVersionRefresh({ isOpen, authBlocked, authRequiredForApi,
                 void checkDataVersion();
             }
         };
+        const onFocus = () => { void checkDataVersion(); };
+        const onOnline = () => { void checkDataVersion(); };
         const intervalId = window.setInterval(() => { void checkDataVersion(); }, 3000);
         document.addEventListener('visibilitychange', onVisibilityChange);
+        window.addEventListener('focus', onFocus);
+        window.addEventListener('online', onOnline);
         void checkDataVersion();
         return () => {
             cancelled = true;
             window.clearInterval(intervalId);
             document.removeEventListener('visibilitychange', onVisibilityChange);
+            window.removeEventListener('focus', onFocus);
+            window.removeEventListener('online', onOnline);
         };
     }, [
         isOpen,
+        workspaceId,
         authBlocked,
         authRequiredForApi,
         isAuthenticated,
@@ -68,6 +184,5 @@ export function useDataVersionRefresh({ isOpen, authBlocked, authRequiredForApi,
         authRequiredForApiRef,
         isAuthenticatedRef,
         dataVersionRef,
-        refreshTaskCollectionsForDataVersion
     ]);
 }

package/dist/hooks/sync/useDurableLocalOutboxDrain.d.ts

@@ -0,0 +1,14 @@
+import type { WorkspaceSyncV3LocalOutboxStatus } from '../../sync/v3/localOutboxDrainClient.js';
+import type { WorkspaceSyncEngineLocalServices } from '../../sync/engine/workspaceSyncEngineLocalServices.js';
+import type { WorkspaceSyncEngineRemoteServices } from '../../sync/engine/workspaceSyncEngineRemoteServices.js';
+export declare function useDurableLocalOutboxDrain(input: {
+    enabled: boolean;
+    workspaceId: string;
+    mutationFingerprint: string;
+    authorityScope: object;
+    remoteServices: Pick<WorkspaceSyncEngineRemoteServices, 'pullWorkspaceContent' | 'abandonTransferReceipts' | 'buildV2ApplyCompletionGroup'> | null;
+    localServices: Pick<WorkspaceSyncEngineLocalServices, 'applyV2Batch'>;
+    isAuthorityCurrent?: (authorityScope: object) => boolean;
+    onHydratedEventIds?: (eventIds: string[]) => void;
+    onOutboxStatus?: (status: WorkspaceSyncV3LocalOutboxStatus | null) => void;
+}): void;

package/dist/hooks/sync/useDurableLocalOutboxDrain.js

@@ -0,0 +1,208 @@
+import { useCallback, useEffect, useRef } from 'react';
+import { drainLocalOutbox } from '../../sync/v3/localOutboxDrainClient.js';
+import { hydrateWorkspaceSyncV3AttachmentAsset } from '../../sync/v3/workspaceSyncV3AttachmentAssetHydration.js';
+const RECOVERY_SWEEP_INTERVAL_MS = 30_000;
+const BUDGET_RETRY_DELAY_MS = 1_000;
+const DEPENDENCY_RETRY_DELAY_MS = 30_000;
+export function useDurableLocalOutboxDrain(input) {
+    const activeRequestRef = useRef(null);
+    const rerunRequestedKeyRef = useRef('');
+    const retryTimerRef = useRef(null);
+    const retryNotBeforeRef = useRef(null);
+    const configRef = useRef({
+        enabled: input.enabled,
+        workspaceId: input.workspaceId,
+        authorityScope: input.authorityScope,
+        remoteServices: input.remoteServices,
+        localServices: input.localServices,
+        isAuthorityCurrent: input.isAuthorityCurrent,
+        onHydratedEventIds: input.onHydratedEventIds,
+        onOutboxStatus: input.onOutboxStatus,
+    });
+    configRef.current = {
+        enabled: input.enabled,
+        workspaceId: input.workspaceId,
+        authorityScope: input.authorityScope,
+        remoteServices: input.remoteServices,
+        localServices: input.localServices,
+        isAuthorityCurrent: input.isAuthorityCurrent,
+        onHydratedEventIds: input.onHydratedEventIds,
+        onOutboxStatus: input.onOutboxStatus,
+    };
+    const clearRetry = useCallback(() => {
+        if (retryTimerRef.current !== null) {
+            window.clearTimeout(retryTimerRef.current);
+            retryTimerRef.current = null;
+        }
+    }, []);
+    const run = useCallback(async () => {
+        const config = configRef.current;
+        if (!config.enabled || !config.workspaceId || !config.remoteServices)
+            return;
+        const key = config.workspaceId;
+        const remoteServices = config.remoteServices;
+        const retryNotBefore = retryNotBeforeRef.current;
+        if (retryNotBefore?.key === key
+            && retryNotBefore.authorityScope === config.authorityScope
+            && retryNotBefore.at > Date.now()) {
+            if (retryTimerRef.current === null) {
+                retryTimerRef.current = window.setTimeout(() => {
+                    retryTimerRef.current = null;
+                    void run();
+                }, retryNotBefore.at - Date.now());
+            }
+            return;
+        }
+        if (retryNotBefore?.key !== key
+            || retryNotBefore.authorityScope !== config.authorityScope
+            || retryNotBefore.at <= Date.now()) {
+            retryNotBeforeRef.current = null;
+        }
+        const active = activeRequestRef.current;
+        if (active?.key === key
+            && active.authorityScope === config.authorityScope) {
+            rerunRequestedKeyRef.current = key;
+            return;
+        }
+        if (active)
+            active.controller.abort();
+        clearRetry();
+        const request = {
+            key,
+            authorityScope: config.authorityScope,
+            controller: new AbortController(),
+        };
+        activeRequestRef.current = request;
+        let retryDelay = 0;
+        try {
+            const result = await drainLocalOutbox({
+                workspaceId: key,
+                signal: request.controller.signal,
+                hydrateAsset: async (assetId) => {
+                    const latest = configRef.current;
+                    if (request.controller.signal.aborted
+                        || !latest.enabled
+                        || latest.workspaceId !== key
+                        || latest.authorityScope !== request.authorityScope
+                        || latest.remoteServices !== remoteServices
+                        || latest.isAuthorityCurrent?.(request.authorityScope) === false) {
+                        return false;
+                    }
+                    const hydration = await hydrateWorkspaceSyncV3AttachmentAsset({
+                        workspaceId: key,
+                        assetId,
+                        remoteServices,
+                        localServices: config.localServices,
+                    }).catch(() => ({ success: false, error: 'Attachment hydration failed.' }));
+                    const settled = configRef.current;
+                    if (request.controller.signal.aborted
+                        || !settled.enabled
+                        || settled.workspaceId !== key
+                        || settled.authorityScope !== request.authorityScope
+                        || settled.remoteServices !== remoteServices
+                        || settled.isAuthorityCurrent?.(request.authorityScope) === false) {
+                        return false;
+                    }
+                    if (!hydration.success)
+                        return false;
+                    if (hydration.emittedEventIds.length > 0) {
+                        config.onHydratedEventIds?.(hydration.emittedEventIds);
+                    }
+                    return true;
+                },
+            });
+            const latest = configRef.current;
+            if (!latest.enabled
+                || latest.workspaceId !== key
+                || latest.authorityScope !== request.authorityScope) {
+                return;
+            }
+            if (result.retryRecommended) {
+                retryDelay = result.budgetExhausted ? BUDGET_RETRY_DELAY_MS : DEPENDENCY_RETRY_DELAY_MS;
+                retryNotBeforeRef.current = {
+                    key,
+                    authorityScope: request.authorityScope,
+                    at: Date.now() + retryDelay,
+                };
+            }
+            if (result.outbox)
+                config.onOutboxStatus?.(result.outbox);
+        }
+        catch {
+            // The periodic local-only sweep owns transport recovery.
+        }
+        finally {
+            if (activeRequestRef.current === request)
+                activeRequestRef.current = null;
+        }
+        if (!configRef.current.enabled || configRef.current.workspaceId !== key) {
+            return;
+        }
+        if (rerunRequestedKeyRef.current === key) {
+            rerunRequestedKeyRef.current = '';
+            void run();
+            return;
+        }
+        if (retryDelay > 0) {
+            retryTimerRef.current = window.setTimeout(() => {
+                retryTimerRef.current = null;
+                void run();
+            }, retryDelay);
+        }
+    }, [clearRetry]);
+    useEffect(() => {
+        input.onOutboxStatus?.(null);
+    }, [input.onOutboxStatus, input.workspaceId]);
+    useEffect(() => {
+        if (!input.enabled) {
+            activeRequestRef.current?.controller.abort();
+            activeRequestRef.current = null;
+            rerunRequestedKeyRef.current = '';
+            retryNotBeforeRef.current = null;
+            configRef.current.onOutboxStatus?.(null);
+            clearRetry();
+            return;
+        }
+        void run();
+    }, [
+        clearRetry,
+        input.enabled,
+        input.mutationFingerprint,
+        input.authorityScope,
+        input.remoteServices,
+        input.workspaceId,
+        run,
+    ]);
+    useEffect(() => {
+        if (!input.enabled)
+            return;
+        const handleOnline = () => { void run(); };
+        const handleVisibility = () => {
+            if (document.visibilityState === 'visible')
+                void run();
+        };
+        const recoverySweep = window.setInterval(() => { void run(); }, RECOVERY_SWEEP_INTERVAL_MS);
+        window.addEventListener('online', handleOnline);
+        document.addEventListener('visibilitychange', handleVisibility);
+        return () => {
+            window.removeEventListener('online', handleOnline);
+            document.removeEventListener('visibilitychange', handleVisibility);
+            window.clearInterval(recoverySweep);
+            const active = activeRequestRef.current;
+            if (active?.key === input.workspaceId) {
+                active.controller.abort();
+                activeRequestRef.current = null;
+            }
+            if (rerunRequestedKeyRef.current === input.workspaceId)
+                rerunRequestedKeyRef.current = '';
+            clearRetry();
+        };
+    }, [
+        clearRetry,
+        input.authorityScope,
+        input.enabled,
+        input.remoteServices,
+        input.workspaceId,
+        run,
+    ]);
+}

package/dist/hooks/sync/useDurableTaskCreateMutation.d.ts

@@ -0,0 +1,15 @@
+import type { TaskItem } from '../../types.js';
+import { createLocalTaskCreateClient, type LocalTaskCreateMutationResult } from '../../sync/v3/localTaskCreateClient.js';
+export type DurableTaskCreateMutationAdapter = ((task: Partial<TaskItem>) => Promise<LocalTaskCreateMutationResult | null>) & {
+    resetDraft?: () => void;
+};
+type LocalTaskCreateClient = ReturnType<typeof createLocalTaskCreateClient>;
+export declare function useDurableTaskCreateMutation(input: {
+    enabled: boolean;
+    localRuntime: boolean;
+    workspaceId: string;
+    isAuthenticated: boolean;
+    dispatchEnabled?: boolean;
+    client?: LocalTaskCreateClient;
+}): DurableTaskCreateMutationAdapter;
+export {};

package/dist/hooks/sync/useDurableTaskCreateMutation.js

@@ -0,0 +1,152 @@
+import { useCallback, useEffect, useRef } from 'react';
+import { createLocalTaskCreateClient, } from '../../sync/v3/localTaskCreateClient.js';
+import { fingerprintLocalOperation } from '../../sync/v3/localOperationIdentityStore.js';
+import { selectTaskCreateActivationInput } from '../../sync/v3/taskCreateActivation.js';
+function createParticipantId() {
+    if (!globalThis.crypto?.randomUUID)
+        throw new Error('Secure task-create participant ID generation is unavailable.');
+    return globalThis.crypto.randomUUID();
+}
+function participantStorageKey(workspaceId) {
+    return `taskforce.sync.v3.task-create-participant-v2:${workspaceId}`;
+}
+function writeParticipantState(workspaceId, state) {
+    globalThis.sessionStorage?.setItem(participantStorageKey(workspaceId), JSON.stringify(state));
+}
+function readOrCreateParticipantState(workspaceId) {
+    const key = participantStorageKey(workspaceId);
+    const existing = globalThis.sessionStorage?.getItem(key)?.trim();
+    if (existing) {
+        try {
+            const parsed = JSON.parse(existing);
+            if (typeof parsed.participantId === 'string' && parsed.participantId.trim()) {
+                return {
+                    participantId: parsed.participantId.trim(),
+                    draftFingerprint: typeof parsed.draftFingerprint === 'string'
+                        ? parsed.draftFingerprint
+                        : null,
+                };
+            }
+        }
+        catch { /* replace malformed or legacy state below */ }
+    }
+    const state = { participantId: createParticipantId(), draftFingerprint: null };
+    writeParticipantState(workspaceId, state);
+    return state;
+}
+async function registerLiveParticipant(workspaceId) {
+    let state = readOrCreateParticipantState(workspaceId);
+    return {
+        get participantId() { return state.participantId; },
+        prepareForDraft(fingerprint) {
+            if (state.draftFingerprint && state.draftFingerprint !== fingerprint) {
+                state = { participantId: createParticipantId(), draftFingerprint: fingerprint };
+            }
+            else {
+                state = { ...state, draftFingerprint: fingerprint };
+            }
+            writeParticipantState(workspaceId, state);
+            return state.participantId;
+        },
+        rotate() {
+            state = { participantId: createParticipantId(), draftFingerprint: null };
+            writeParticipantState(workspaceId, state);
+            return state.participantId;
+        },
+        close() { },
+    };
+}
+async function fingerprintTaskDraft(task) {
+    const { createdAt: _createdAt, updatedAt: _updatedAt, ...stableDraft } = task;
+    return fingerprintLocalOperation(stableDraft);
+}
+export function useDurableTaskCreateMutation(input) {
+    const clientRef = useRef(null);
+    const participantRef = useRef(null);
+    const getParticipant = useCallback((workspaceId) => {
+        if (participantRef.current?.workspaceId !== workspaceId) {
+            void participantRef.current?.promise.then((participant) => participant.close());
+            participantRef.current = { workspaceId, promise: registerLiveParticipant(workspaceId) };
+        }
+        return participantRef.current.promise;
+    }, []);
+    useEffect(() => {
+        if (!input.localRuntime)
+            return;
+        const workspaceId = String(input.workspaceId || '').trim();
+        if (workspaceId && workspaceId.toLowerCase() !== 'default') {
+            void getParticipant(workspaceId);
+            if (input.enabled) {
+                if (!clientRef.current)
+                    clientRef.current = input.client || createLocalTaskCreateClient();
+                if (typeof clientRef.current.recoverPending === 'function') {
+                    void clientRef.current.recoverPending({
+                        workspaceId,
+                        isAuthenticated: input.isAuthenticated,
+                        dispatchEnabled: input.dispatchEnabled,
+                    });
+                }
+            }
+        }
+        return () => {
+            const current = participantRef.current;
+            participantRef.current = null;
+            void current?.promise.then((participant) => participant.close());
+        };
+    }, [getParticipant, input.client, input.dispatchEnabled, input.enabled, input.isAuthenticated, input.localRuntime, input.workspaceId]);
+    const mutate = useCallback(async (candidate) => {
+        if (!input.localRuntime)
+            return null;
+        const workspaceId = String(input.workspaceId || '').trim();
+        if (!workspaceId || workspaceId.toLowerCase() === 'default')
+            return null;
+        if (!clientRef.current)
+            clientRef.current = input.client || createLocalTaskCreateClient();
+        const participant = await getParticipant(workspaceId);
+        const selected = selectTaskCreateActivationInput(candidate);
+        const participantId = selected
+            ? participant.prepareForDraft(await fingerprintTaskDraft(selected.localTask))
+            : participant.participantId;
+        let result;
+        if (!input.enabled || !selected) {
+            result = await clientRef.current.resumePending({
+                workspaceId,
+                participantId,
+                isAuthenticated: input.isAuthenticated,
+                dispatchEnabled: input.dispatchEnabled,
+            });
+            if (!result && !input.enabled)
+                return null;
+            if (!result && input.enabled && !selected) {
+                return {
+                    state: 'rejected', phase: 'capture', fallbackEligible: false,
+                    operationId: participantId, retryable: false,
+                    errorCode: 'TASK_CREATE_UNSUPPORTED_INPUT',
+                };
+            }
+        }
+        else {
+            result = await clientRef.current.create({
+                workspaceId,
+                participantId,
+                task: selected.task,
+                localTask: selected.localTask,
+                isAuthenticated: input.isAuthenticated,
+                dispatchEnabled: input.dispatchEnabled,
+            });
+        }
+        if (!result)
+            return null;
+        if (result.state === 'accepted' || result.state === 'pending' || result.state === 'blocked') {
+            participant.rotate();
+        }
+        return result;
+    }, [getParticipant, input.client, input.dispatchEnabled, input.enabled, input.isAuthenticated, input.localRuntime, input.workspaceId]);
+    mutate.resetDraft = () => {
+        const workspaceId = String(input.workspaceId || '').trim();
+        if (!workspaceId || workspaceId.toLowerCase() === 'default')
+            return;
+        void getParticipant(workspaceId).then((participant) => participant.rotate());
+    };
+    return mutate;
+}

package/dist/hooks/sync/useDurableTaskDeleteMutation.d.ts

@@ -0,0 +1,11 @@
+import { createLocalTaskDeleteClient, type LocalTaskDeleteMutationResult } from '../../sync/v3/localTaskDeleteClient.js';
+export type DurableTaskDeleteMutationAdapter = (taskId: string) => Promise<LocalTaskDeleteMutationResult | null>;
+type LocalTaskDeleteClient = ReturnType<typeof createLocalTaskDeleteClient>;
+export declare function useDurableTaskDeleteMutation(input: {
+    enabled: boolean;
+    workspaceId: string;
+    isAuthenticated: boolean;
+    dispatchEnabled?: boolean;
+    client?: LocalTaskDeleteClient;
+}): DurableTaskDeleteMutationAdapter;
+export {};

package/dist/hooks/sync/useDurableTaskDeleteMutation.js

@@ -0,0 +1,21 @@
+import { useCallback, useRef } from 'react';
+import { createLocalTaskDeleteClient, } from '../../sync/v3/localTaskDeleteClient.js';
+export function useDurableTaskDeleteMutation(input) {
+    const clientRef = useRef(null);
+    return useCallback(async (taskId) => {
+        if (!input.enabled)
+            return null;
+        const workspaceId = String(input.workspaceId || '').trim();
+        const entityId = String(taskId || '').trim();
+        if (!workspaceId || workspaceId.toLowerCase() === 'default' || !entityId)
+            return null;
+        if (!clientRef.current)
+            clientRef.current = input.client || createLocalTaskDeleteClient();
+        return clientRef.current.delete({
+            workspaceId,
+            entityId,
+            isAuthenticated: input.isAuthenticated,
+            dispatchEnabled: input.dispatchEnabled,
+        });
+    }, [input.client, input.dispatchEnabled, input.enabled, input.isAuthenticated, input.workspaceId]);
+}

package/dist/hooks/sync/useDurableTaskLifecycleMutation.d.ts

@@ -0,0 +1,12 @@
+import { createLocalTaskLifecycleClient, type LocalTaskLifecycleMutationInput, type LocalTaskLifecycleMutationResult } from '../../sync/v3/localTaskLifecycleClient.js';
+export type DurableTaskLifecycleMutationAdapter = (taskId: string, mutation: LocalTaskLifecycleMutation) => Promise<LocalTaskLifecycleMutationResult | null>;
+type LocalTaskLifecycleMutation = LocalTaskLifecycleMutationInput extends infer Mutation ? Mutation extends LocalTaskLifecycleMutationInput ? Omit<Mutation, 'workspaceId' | 'entityId' | 'isAuthenticated' | 'dispatchEnabled'> : never : never;
+type LocalTaskLifecycleClient = ReturnType<typeof createLocalTaskLifecycleClient>;
+export declare function useDurableTaskLifecycleMutation(input: {
+    enabled: boolean;
+    workspaceId: string;
+    isAuthenticated: boolean;
+    dispatchEnabled?: boolean;
+    client?: LocalTaskLifecycleClient;
+}): DurableTaskLifecycleMutationAdapter;
+export {};

package/dist/hooks/sync/useDurableTaskLifecycleMutation.js

@@ -0,0 +1,22 @@
+import { useCallback, useRef } from 'react';
+import { createLocalTaskLifecycleClient, } from '../../sync/v3/localTaskLifecycleClient.js';
+export function useDurableTaskLifecycleMutation(input) {
+    const clientRef = useRef(null);
+    return useCallback(async (taskId, mutation) => {
+        if (!input.enabled)
+            return null;
+        const workspaceId = String(input.workspaceId || '').trim();
+        const entityId = String(taskId || '').trim();
+        if (!workspaceId || workspaceId.toLowerCase() === 'default' || !entityId)
+            return null;
+        if (!clientRef.current)
+            clientRef.current = input.client || createLocalTaskLifecycleClient();
+        return clientRef.current.mutate({
+            workspaceId,
+            entityId,
+            isAuthenticated: input.isAuthenticated,
+            dispatchEnabled: input.dispatchEnabled,
+            ...mutation,
+        });
+    }, [input.client, input.dispatchEnabled, input.enabled, input.isAuthenticated, input.workspaceId]);
+}

package/dist/hooks/sync/useDurableTaskMetadataMutation.d.ts

@@ -0,0 +1,14 @@
+import type { TaskItem } from '../../types.js';
+import { createLocalTaskMetadataClient, type LocalTaskMetadataMutationResult } from '../../sync/v3/localTaskMetadataClient.js';
+export type DurableTaskMetadataMutationAdapter = (taskId: string, patch: Partial<TaskItem>, options?: {
+    saveSource?: 'manual' | 'autosave';
+}) => Promise<LocalTaskMetadataMutationResult | null>;
+type LocalTaskMetadataClient = ReturnType<typeof createLocalTaskMetadataClient>;
+export declare function useDurableTaskMetadataMutation(input: {
+    enabled: boolean;
+    workspaceId: string;
+    isAuthenticated: boolean;
+    dispatchEnabled?: boolean;
+    client?: LocalTaskMetadataClient;
+}): DurableTaskMetadataMutationAdapter;
+export {};