@taskforcehq/taskforce 0.3.327 → 0.3.328

package/dist/hooks/useTaskforce.d.ts

@@ -31,9 +31,10 @@
  *   === SECTION: Settings Model ===         Line ~4625 — settingsModel object
  *   === SECTION: Return Value ===           Line ~4817 — final return object (public API shape)
  */
-import { type SetStateAction } from 'react';
+import { type Dispatch, type SetStateAction } from 'react';
 import type { TaskforceConfig, TaskforceTheme, Comment, AttachmentItem, CategoryConfig, TaskItem, TaxonomyDefinition, TaskAssignee, TaskStatus, DeletedTaskRecord, InitiativeItem, WorkstreamItem, ChecklistItem, PlanningBootstrapPayload, PlanningBootstrapWorkstreamTaskSummary, PlanningLoadState } from '../types';
 import { type FirstClassTaxonomyDisplayLabels } from '../shared/taxonomyState.js';
+import type { PlanningIdentityColor, PlanningIdentityIcon } from '../shared/planningIdentity.js';
 import type { UiNotice } from '../utils/uiNotice';
 import type { TaskAssigneeOption } from '../utils/assignees';
 import { type WorkspaceModuleId } from './workspace/workspaceLocalState';
@@ -137,31 +138,31 @@ export declare function useTaskforce({ config, initialTaskId, initialActivityEnt
         showTaskCardStatusLabel: boolean;
     };
     isOpen: boolean;
-    setIsOpen: import("react").Dispatch<SetStateAction<boolean>>;
+    setIsOpen: Dispatch<SetStateAction<boolean>>;
     activeTab: "tasks" | "settings" | "add";
     setActiveTab: (tab: "add" | "tasks" | "settings") => void;
     currentTheme: "light" | "dawn" | "dark" | "midnight";
-    setCurrentTheme: import("react").Dispatch<SetStateAction<"light" | "dawn" | "dark" | "midnight">>;
+    setCurrentTheme: Dispatch<SetStateAction<"light" | "dawn" | "dark" | "midnight">>;
     configLoaded: boolean;
     storagePath: string;
     saveSettings: () => Promise<boolean>;
     pathSaved: boolean;
     keyShortcut: string;
-    setKeyShortcut: import("react").Dispatch<SetStateAction<string>>;
+    setKeyShortcut: Dispatch<SetStateAction<string>>;
     globalWeekStartsOn: WeekStartsOn;
     locale: "en-US" | "es-419" | "pt-BR";
     supportedLocales: ("en-US" | "es-419" | "pt-BR")[];
     saveLocale: (nextLocale: string) => Promise<boolean>;
     jsonBackupEnabled: boolean;
-    setJsonBackupEnabled: import("react").Dispatch<SetStateAction<boolean>>;
+    setJsonBackupEnabled: Dispatch<SetStateAction<boolean>>;
     manualComplexityEnabled: boolean;
     checklistDropdownEnabled: boolean;
     showTaskCardStatusLabel: boolean;
-    setManualComplexityEnabled: import("react").Dispatch<SetStateAction<boolean>>;
+    setManualComplexityEnabled: Dispatch<SetStateAction<boolean>>;
     mcpHostRoot: string;
-    setMcpHostRoot: import("react").Dispatch<SetStateAction<string>>;
+    setMcpHostRoot: Dispatch<SetStateAction<string>>;
     settingsSection: "mcp" | "categories" | "types" | "general" | "agents" | "taxonomy" | "documents" | "appearance-application" | "appearance-task-cards" | "appearance-task-forms" | "integrations" | null;
-    setSettingsSection: import("react").Dispatch<SetStateAction<"mcp" | "categories" | "types" | "general" | "agents" | "taxonomy" | "documents" | "appearance-application" | "appearance-task-cards" | "appearance-task-forms" | "integrations" | null>>;
+    setSettingsSection: Dispatch<SetStateAction<"mcp" | "categories" | "types" | "general" | "agents" | "taxonomy" | "documents" | "appearance-application" | "appearance-task-cards" | "appearance-task-forms" | "integrations" | null>>;
     runtimeMode: "local" | "cloud";
     workspaceMode: "single-local" | "multi-cloud";
     workspaceSwitchingEnabled: boolean;
@@ -432,7 +433,7 @@ export declare function useTaskforce({ config, initialTaskId, initialActivityEnt
     }>;
     logout: () => Promise<void>;
     showFolderBrowser: boolean;
-    setShowFolderBrowser: import("react").Dispatch<SetStateAction<boolean>>;
+    setShowFolderBrowser: Dispatch<SetStateAction<boolean>>;
     folders: string[];
     files: string[];
     currentBrowsePath: string;
@@ -441,16 +442,16 @@ export declare function useTaskforce({ config, initialTaskId, initialActivityEnt
         type: "category";
         value: string;
     } | null;
-    setBrowserTarget: import("react").Dispatch<SetStateAction<"storage" | {
+    setBrowserTarget: Dispatch<SetStateAction<"storage" | {
         type: "category";
         value: string;
     } | null>>;
     groupBy: "category" | "type" | "priority" | "status" | "complexity" | "assignee" | "schedule";
-    setGroupBy: import("react").Dispatch<SetStateAction<"category" | "type" | "priority" | "status" | "complexity" | "assignee" | "schedule">>;
+    setGroupBy: Dispatch<SetStateAction<"category" | "type" | "priority" | "status" | "complexity" | "assignee" | "schedule">>;
     activeWorkspaceModule: WorkspaceModuleId;
-    setActiveWorkspaceModule: import("react").Dispatch<SetStateAction<WorkspaceModuleId>>;
+    setActiveWorkspaceModule: Dispatch<SetStateAction<WorkspaceModuleId>>;
     emptyColumnMode: "show" | "collapse" | "hide";
-    setEmptyColumnMode: import("react").Dispatch<SetStateAction<"show" | "collapse" | "hide">>;
+    setEmptyColumnMode: Dispatch<SetStateAction<"show" | "collapse" | "hide">>;
     zenMode: boolean;
     setZenMode: () => Promise<void>;
     handleSelectPath: (path: string) => void;
@@ -484,38 +485,38 @@ export declare function useTaskforce({ config, initialTaskId, initialActivityEnt
     taxonomyDisplayLabels: FirstClassTaxonomyDisplayLabels;
     taxonomies: TaxonomyDefinition[];
     searchQuery: string;
-    setSearchQuery: import("react").Dispatch<SetStateAction<string>>;
+    setSearchQuery: Dispatch<SetStateAction<string>>;
     filterCategories: string[];
-    setFilterCategories: import("react").Dispatch<SetStateAction<string[]>>;
+    setFilterCategories: Dispatch<SetStateAction<string[]>>;
     filterTypes: string[];
-    setFilterTypes: import("react").Dispatch<SetStateAction<string[]>>;
+    setFilterTypes: Dispatch<SetStateAction<string[]>>;
     filterPriorities: (string | number)[];
-    setFilterPriorities: import("react").Dispatch<SetStateAction<(string | number)[]>>;
+    setFilterPriorities: Dispatch<SetStateAction<(string | number)[]>>;
     filterStatus: (string | number)[];
-    setFilterStatus: import("react").Dispatch<SetStateAction<(string | number)[]>>;
+    setFilterStatus: Dispatch<SetStateAction<(string | number)[]>>;
     filterAssignees: string[];
     setFilterAssignees: (nextValues: TaskAssignee[] | ((prev: TaskAssignee[]) => TaskAssignee[])) => void;
     filterTaxonomies: Record<string, (string | number)[]>;
-    setFilterTaxonomies: import("react").Dispatch<SetStateAction<Record<string, (string | number)[]>>>;
+    setFilterTaxonomies: Dispatch<SetStateAction<Record<string, (string | number)[]>>>;
     hasInitedFilters: boolean;
     sortBy: import("../utils/taxonomySorting").TaskSortKey;
-    setSortBy: import("react").Dispatch<SetStateAction<import("../utils/taxonomySorting").TaskSortKey>>;
+    setSortBy: Dispatch<SetStateAction<import("../utils/taxonomySorting").TaskSortKey>>;
     sortOrder: "asc" | "desc";
-    setSortOrder: import("react").Dispatch<SetStateAction<"asc" | "desc">>;
+    setSortOrder: Dispatch<SetStateAction<"asc" | "desc">>;
     toggleSortOrder: () => void;
     showArchive: boolean;
-    setShowArchive: import("react").Dispatch<SetStateAction<boolean>>;
+    setShowArchive: Dispatch<SetStateAction<boolean>>;
     taskScope: TaskScope;
-    setTaskScope: import("react").Dispatch<SetStateAction<TaskScope>>;
+    setTaskScope: Dispatch<SetStateAction<TaskScope>>;
     compressedCards: boolean;
-    setCompressedCards: import("react").Dispatch<SetStateAction<boolean>>;
+    setCompressedCards: Dispatch<SetStateAction<boolean>>;
     clearFilters: () => void;
     filteredTasks: TaskItem[];
     searchAgnosticTasks: TaskItem[];
     filteredArchive: TaskItem[];
     groupedTasks: Record<string, TaskItem[]>;
     collapsedCategories: Record<string, boolean>;
-    setCollapsedCategories: import("react").Dispatch<SetStateAction<Record<string, boolean>>>;
+    setCollapsedCategories: Dispatch<SetStateAction<Record<string, boolean>>>;
     fetchTasks: (isSilent?: boolean, options?: {
         ignoreAuthGuard?: boolean;
         highlightChangedTaskIds?: readonly string[];
@@ -539,6 +540,10 @@ export declare function useTaskforce({ config, initialTaskId, initialActivityEnt
     }>;
     createInitiative: (payload: Partial<InitiativeItem>) => Promise<InitiativeItem>;
     updateInitiative: (id: string, payload: Partial<InitiativeItem>) => Promise<InitiativeItem>;
+    updatePlanningIdentity: (entityType: "initiative" | "workstream", id: string, patch: {
+        icon?: PlanningIdentityIcon | null;
+        color?: PlanningIdentityColor | null;
+    }) => Promise<InitiativeItem | WorkstreamItem>;
     archiveInitiative: (id: string) => Promise<InitiativeItem>;
     unarchiveInitiative: (id: string) => Promise<InitiativeItem>;
     createWorkstream: (payload: Partial<WorkstreamItem>) => Promise<WorkstreamItem>;
@@ -574,55 +579,59 @@ export declare function useTaskforce({ config, initialTaskId, initialActivityEnt
     error: string;
     clearTaskError: () => void;
     title: string;
-    setTitle: import("react").Dispatch<SetStateAction<string>>;
+    setTitle: Dispatch<SetStateAction<string>>;
     setTitleDraft: (value: string) => void;
     description: string;
-    setDescription: import("react").Dispatch<SetStateAction<string>>;
+    setDescription: Dispatch<SetStateAction<string>>;
     setDescriptionDraft: (value: string) => void;
     checklistItems: ChecklistItem[];
-    setChecklistItems: import("react").Dispatch<SetStateAction<ChecklistItem[]>>;
+    setChecklistItems: Dispatch<SetStateAction<ChecklistItem[]>>;
     category: string;
-    setCategory: import("react").Dispatch<SetStateAction<string>>;
+    setCategory: Dispatch<SetStateAction<string>>;
     type: string;
-    setType: import("react").Dispatch<SetStateAction<string>>;
+    setType: Dispatch<SetStateAction<string>>;
     priority: string | number;
-    setPriority: import("react").Dispatch<SetStateAction<string | number>>;
+    setPriority: Dispatch<SetStateAction<string | number>>;
     complexity: string | number;
-    setComplexity: import("react").Dispatch<SetStateAction<string | number>>;
+    setComplexity: Dispatch<SetStateAction<string | number>>;
     status: TaskStatus;
-    setStatus: import("react").Dispatch<SetStateAction<TaskStatus>>;
+    setStatus: Dispatch<SetStateAction<TaskStatus>>;
     assignee: string;
-    setAssignee: import("react").Dispatch<SetStateAction<string>>;
+    setAssignee: Dispatch<SetStateAction<string>>;
     scheduledDate: string;
-    setScheduledDate: import("react").Dispatch<SetStateAction<string>>;
+    setScheduledDate: Dispatch<SetStateAction<string>>;
     dueDate: string;
-    setDueDate: import("react").Dispatch<SetStateAction<string>>;
+    setDueDate: Dispatch<SetStateAction<string>>;
     workstreamInput: string;
-    setWorkstreamInput: import("react").Dispatch<SetStateAction<string>>;
+    setWorkstreamInput: Dispatch<SetStateAction<string>>;
     formTaxonomies: Record<string, string | number | string[] | number[]>;
-    setFormTaxonomies: import("react").Dispatch<SetStateAction<Record<string, string | number | string[] | number[]>>>;
+    setFormTaxonomies: Dispatch<SetStateAction<Record<string, string | number | string[] | number[]>>>;
     comments: Comment[];
     newCommentText: string;
-    setNewCommentText: import("react").Dispatch<SetStateAction<string>>;
+    setNewCommentText: Dispatch<SetStateAction<string>>;
     attachments: (string | AttachmentItem)[];
-    setAttachments: import("react").Dispatch<SetStateAction<(string | AttachmentItem)[]>>;
+    setAttachments: Dispatch<SetStateAction<(string | AttachmentItem)[]>>;
     attachmentsDirty: boolean;
-    setAttachmentsDirty: import("react").Dispatch<SetStateAction<boolean>>;
+    setAttachmentsDirty: Dispatch<SetStateAction<boolean>>;
+    descriptionImageUploadPending: boolean;
+    descriptionImageDraftId: string;
+    registerDescriptionImageUpload: (upload: Promise<void>) => void;
     descriptionFocused: boolean;
-    setDescriptionFocused: import("react").Dispatch<SetStateAction<boolean>>;
+    setDescriptionFocused: Dispatch<SetStateAction<boolean>>;
     showMarkdownHelp: boolean;
-    setShowMarkdownHelp: import("react").Dispatch<SetStateAction<boolean>>;
+    setShowMarkdownHelp: Dispatch<SetStateAction<boolean>>;
     isCapturingScreenshot: boolean;
-    setIsCapturingScreenshot: import("react").Dispatch<SetStateAction<boolean>>;
+    setIsCapturingScreenshot: Dispatch<SetStateAction<boolean>>;
     handleSubmit: (event: React.FormEvent) => Promise<void>;
     resetForm: () => void;
+    discardDescriptionImageDraft: () => Promise<void>;
     handleAddComment: (text: string) => Promise<void>;
     handleSetWorkstreamForCurrentTask: (workstreamIdOverride?: string | null) => Promise<void>;
     handleOpenTaskById: (taskId: string) => void;
     returnToPreviousTask: () => boolean;
     autoSaveState: import("./tasks/useTaskFormActions").TaskAutoSaveState;
     unsavedModalOpen: boolean;
-    setUnsavedModalOpen: import("react").Dispatch<SetStateAction<boolean>>;
+    setUnsavedModalOpen: Dispatch<SetStateAction<boolean>>;
     pendingNavigation: (() => void) | null;
     handleNavigation: (action: () => void) => Promise<void>;
     handleClose: () => void;
@@ -648,13 +657,13 @@ export declare function useTaskforce({ config, initialTaskId, initialActivityEnt
     confirmScheduleWarning: () => Promise<void>;
     cancelScheduleWarning: () => void;
     tasksScrollRef: import("react").RefObject<HTMLDivElement | null>;
-    setTasksScrollPos: import("react").Dispatch<SetStateAction<number>>;
+    setTasksScrollPos: Dispatch<SetStateAction<number>>;
     taskforceAgentId: string;
-    setTaskforceAgentId: import("react").Dispatch<SetStateAction<string>>;
+    setTaskforceAgentId: Dispatch<SetStateAction<string>>;
     taskforceAgentConversationId: string;
-    setTaskforceAgentConversationId: import("react").Dispatch<SetStateAction<string>>;
+    setTaskforceAgentConversationId: Dispatch<SetStateAction<string>>;
     taskforceAgentConversationByAgentId: Record<string, string>;
-    setTaskforceAgentConversationByAgentId: import("react").Dispatch<SetStateAction<Record<string, string>>>;
+    setTaskforceAgentConversationByAgentId: Dispatch<SetStateAction<Record<string, string>>>;
     uiStateReady: boolean;
     handleUpdateCategory: (updatedCat: CategoryConfig, oldLabel?: string) => Promise<void>;
     handleRemoveCategory: (catValue: string) => Promise<void>;
@@ -685,7 +694,7 @@ export declare function useTaskforce({ config, initialTaskId, initialActivityEnt
     validatePaths: (paths: string[]) => Promise<void>;
     getCategoryPaths: (cat: CategoryConfig) => string[];
     customCategories: CategoryConfig[];
-    setCustomCategories: import("react").Dispatch<SetStateAction<CategoryConfig[]>>;
+    setCustomCategories: Dispatch<SetStateAction<CategoryConfig[]>>;
     projectRoot: string;
     projectName: string;
     mcpScriptPath: string;

package/dist/hooks/useTaskforce.js

@@ -1494,7 +1494,46 @@ export function useTaskforce({ config = {}, initialTaskId, initialActivityEntryI
     const [activeWorkspaceModule, setActiveWorkspaceModuleState] = useState('tasks');
     const [descriptionFocused, setDescriptionFocused] = useState(false);
     const [isCapturingScreenshot, setIsCapturingScreenshot] = useState(false);
-    const [attachments, setAttachments] = useState([]);
+    const attachmentsDraftRef = useRef([]);
+    const [attachments, setAttachmentsState] = useState([]);
+    const setAttachments = useCallback((next) => {
+        const nextAttachments = typeof next === 'function'
+            ? next(attachmentsDraftRef.current)
+            : next;
+        attachmentsDraftRef.current = nextAttachments;
+        setAttachmentsState(nextAttachments);
+    }, []);
+    const getAttachmentsDraft = useCallback(() => [...attachmentsDraftRef.current], []);
+    const pendingDescriptionImageUploadRef = useRef(null);
+    const [descriptionImageUploadPending, setDescriptionImageUploadPending] = useState(false);
+    const createDescriptionImageDraftId = useCallback(() => (`task-description-${globalThis.crypto?.randomUUID?.() || `${Date.now()}-${Math.random().toString(16).slice(2)}`}`), []);
+    const descriptionImageDraftIdRef = useRef(createDescriptionImageDraftId());
+    const [descriptionImageDraftId, setDescriptionImageDraftId] = useState(descriptionImageDraftIdRef.current);
+    const rotateDescriptionImageDraftId = useCallback(() => {
+        const nextDraftId = createDescriptionImageDraftId();
+        descriptionImageDraftIdRef.current = nextDraftId;
+        setDescriptionImageDraftId(nextDraftId);
+    }, [createDescriptionImageDraftId]);
+    const registerDescriptionImageUpload = useCallback((upload) => {
+        pendingDescriptionImageUploadRef.current = upload;
+        setDescriptionImageUploadPending(true);
+        void upload.then(() => {
+            if (pendingDescriptionImageUploadRef.current !== upload)
+                return;
+            pendingDescriptionImageUploadRef.current = null;
+            setDescriptionImageUploadPending(false);
+        }, () => {
+            if (pendingDescriptionImageUploadRef.current !== upload)
+                return;
+            pendingDescriptionImageUploadRef.current = null;
+            setDescriptionImageUploadPending(false);
+        });
+    }, []);
+    const awaitPendingDescriptionImageUpload = useCallback(async () => {
+        const upload = pendingDescriptionImageUploadRef.current;
+        if (upload)
+            await upload;
+    }, []);
     const [attachmentsDirty, setAttachmentsDirty] = useState(false);
     const dataVersionRef = useRef(null);
     const ambiguousRealtimeConfirmationTimerRef = useRef(null);
@@ -2804,6 +2843,24 @@ export function useTaskforce({ config = {}, initialTaskId, initialActivityEntryI
         setInitiatives((current) => upsertEntityById(current, data));
         return data;
     }, [fetchPlanningEntities, runInitiativeMutation]);
+    const updatePlanningIdentity = useCallback(async (entityType, id, patch) => {
+        const res = await runInitiativeMutation(`/api/taskforce/${entityType}/${encodeURIComponent(id)}/identity`, {
+            method: 'PATCH',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(patch),
+        });
+        const data = await res.json().catch(() => ({}));
+        if (!res.ok)
+            throw new Error(data?.error || `Failed to update ${entityType} identity (${res.status})`);
+        if (entityType === 'initiative') {
+            setInitiatives((current) => upsertEntityById(current, data));
+        }
+        else {
+            setWorkstreams((current) => upsertEntityById(current, data));
+        }
+        void fetchPlanningEntities();
+        return data;
+    }, [fetchPlanningEntities, runInitiativeMutation]);
     const refreshPlanningEntitiesInBackground = useCallback(() => {
         void fetchPlanningEntities();
     }, [fetchPlanningEntities]);
@@ -3784,6 +3841,22 @@ export function useTaskforce({ config = {}, initialTaskId, initialActivityEntryI
         durableTaskHttpRootActivationEnabled: runtimeConfigOverride.syncV3TaskCloudHttpRootActivation,
         workspaceId: currentWorkspaceId,
     });
+    const promoteDescriptionImageDraft = useCallback(async () => {
+        const draftId = descriptionImageDraftIdRef.current;
+        const response = await fetch('/api/taskforce/context-upload/draft/promote', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                workspaceId: currentWorkspaceId,
+                draftUploadId: draftId,
+                uploadPurpose: 'task-description-draft',
+            }),
+        });
+        if (!response.ok) {
+            throw new Error('Task was created, but its draft upload records could not be finalized.');
+        }
+        rotateDescriptionImageDraftId();
+    }, [currentWorkspaceId, rotateDescriptionImageDraftId]);
     const { autoSaveState, flushAutoSave, scheduleWarningPrompt, handleSubmit, confirmScheduleWarning, cancelScheduleWarning, handleAddComment } = useTaskFormActions({
         activeCategories,
         activeTab,
@@ -3804,9 +3877,12 @@ export function useTaskforce({ config = {}, initialTaskId, initialActivityEntryI
         editingTaskId,
         fetchTasks,
         formTaxonomies,
+        getAttachmentsDraft,
         getDescriptionDraft,
         getPreferredCategoryValue,
         getTitleDraft,
+        awaitPendingDescriptionImageUpload,
+        onTaskCreateAccepted: promoteDescriptionImageDraft,
         mergeTaskFromServer,
         onTaskCreated: handleEdit,
         workstreamInput,
@@ -3831,6 +3907,27 @@ export function useTaskforce({ config = {}, initialTaskId, initialActivityEntryI
         textDraftOccupied,
         type
     });
+    const discardDescriptionImageDraft = useCallback(async () => {
+        const draftId = descriptionImageDraftIdRef.current;
+        rotateDescriptionImageDraftId();
+        try {
+            await awaitPendingDescriptionImageUpload();
+            const response = await fetch('/api/taskforce/context-upload/draft/discard', {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    workspaceId: currentWorkspaceId,
+                    draftUploadId: draftId,
+                    uploadPurpose: 'task-description-draft',
+                }),
+            });
+            if (!response.ok)
+                throw new Error('Draft upload cleanup was rejected.');
+        }
+        catch (error) {
+            console.warn('[Taskforce] Failed to clean discarded Description image uploads.', error);
+        }
+    }, [awaitPendingDescriptionImageUpload, currentWorkspaceId, rotateDescriptionImageDraftId]);
     useEffect(() => {
         flushAutoSaveRef.current = flushAutoSave;
     }, [flushAutoSave]);
@@ -4181,6 +4278,7 @@ export function useTaskforce({ config = {}, initialTaskId, initialActivityEntryI
         fetchAssigneeOptions,
         createInitiative,
         updateInitiative,
+        updatePlanningIdentity,
         archiveInitiative,
         unarchiveInitiative,
         createWorkstream,
@@ -4244,6 +4342,9 @@ export function useTaskforce({ config = {}, initialTaskId, initialActivityEntryI
         setAttachments,
         attachmentsDirty,
         setAttachmentsDirty,
+        descriptionImageUploadPending,
+        descriptionImageDraftId,
+        registerDescriptionImageUpload,
         descriptionFocused,
         setDescriptionFocused,
         showMarkdownHelp,
@@ -4253,6 +4354,7 @@ export function useTaskforce({ config = {}, initialTaskId, initialActivityEntryI
         // Form Actions
         handleSubmit,
         resetForm,
+        discardDescriptionImageDraft,
         handleAddComment,
         handleSetWorkstreamForCurrentTask,
         handleOpenTaskById,

package/dist/mcp/canonicalAssetHelpers.d.ts

@@ -35,12 +35,23 @@ export interface CanonicalAssetHelpersDeps {
         assetId: string;
     };
 }
+export declare class CanonicalDocumentHeadStaleError extends Error {
+    readonly details: Record<string, unknown>;
+    readonly code = "MCP_DOCUMENT_HEAD_STALE";
+    readonly statusCode = 409;
+    constructor(details: Record<string, unknown>);
+}
 export declare function createCanonicalAssetHelpers(deps: CanonicalAssetHelpersDeps): {
     normalizeAttachmentStorageKey: (pathValue: unknown, fsPathValue: unknown) => string | null;
     buildSyntheticAttachmentId: (taskId: string, attachment: TaskAttachmentRecord) => string;
     getAttachmentAssetRecord: (attachment: TaskAttachmentRecord) => WorkspaceAssetEntry | null;
     buildAttachmentDownloadUrl: (attachment: McpTaskAttachmentDescriptor) => string;
     buildDocumentDownloadUrl: (asset: WorkspaceAssetEntry | WorkspaceDocumentEntry) => string;
+    assertCanonicalDocumentHeadCurrent: (asset: WorkspaceAssetEntry | WorkspaceDocumentEntry) => import("../sync/engine/workspaceSyncPublishedContentResolver.js").WorkspaceSyncPublishedLegacyContent | import("../sync/engine/workspaceSyncPublishedContentResolver.js").WorkspaceSyncPublishedVersionedContent | {
+        source: "legacy";
+        physicalKey: string;
+        storageProvider: import("../storage/objectStorage.js").ObjectStorageProvider;
+    };
     readCanonicalAttachmentBuffer: (taskId: string, attachment: McpTaskAttachmentDescriptor, targetLabel?: string) => Promise<Buffer>;
     readCanonicalDocumentBuffer: (asset: WorkspaceAssetEntry | WorkspaceDocumentEntry) => Promise<Buffer>;
     toTaskAttachmentRecord: (attachment: string | TaskAttachmentRecord) => TaskAttachmentRecord;
@@ -68,6 +79,7 @@ export declare function createCanonicalAssetHelpers(deps: CanonicalAssetHelpersD
         scanEngine?: string | null;
         scanDetails?: string | null;
         createLink?: boolean;
+        displayName?: string;
     }) => Promise<WorkspaceAssetEntry | null>;
     ensureCanonicalTaskAttachment: (relativePathRaw: string, taskIdRaw: string, captionRaw: string | undefined, timestampRaw: string | undefined, role: WorkspaceAssetLinkRole, options?: Parameters<(relativePathRaw: string, targetTypeRaw: WorkspaceAssetLinkTargetType, targetIdRaw: string, captionRaw: string | undefined, timestampRaw: string | undefined, role: WorkspaceAssetLinkRole, options?: {
         originalFilename?: string;
@@ -80,6 +92,7 @@ export declare function createCanonicalAssetHelpers(deps: CanonicalAssetHelpersD
         scanEngine?: string | null;
         scanDetails?: string | null;
         createLink?: boolean;
+        displayName?: string;
     }) => Promise<WorkspaceAssetEntry | null>>[6]) => Promise<WorkspaceAssetEntry | null>;
     buildCanonicalWorkspaceAssetRelativePath: (params: {
         workspaceIdRaw: unknown;

package/dist/mcp/canonicalAssetHelpers.js

@@ -3,6 +3,16 @@ import * as path from 'path';
 import { createHash, randomUUID } from 'node:crypto';
 import { verifyWorkspaceSyncPublishedContentBody, } from '../sync/engine/workspaceSyncPublishedContentResolver.js';
 import { normalizeRelativeStorageKey, resolveExistingStorageKeyFilePathInsideRoot, resolveStorageKeyWritePathInsideRoot } from '../utils/pathSafety.js';
+export class CanonicalDocumentHeadStaleError extends Error {
+    details;
+    code = 'MCP_DOCUMENT_HEAD_STALE';
+    statusCode = 409;
+    constructor(details) {
+        super('The published document head does not match the current canonical document metadata.');
+        this.details = details;
+        this.name = 'CanonicalDocumentHeadStaleError';
+    }
+}
 export function createCanonicalAssetHelpers(deps) {
     const normalizeAttachmentStorageKey = (pathValue, fsPathValue) => {
         const fsPathRaw = String(fsPathValue || '').trim().replace(/\\/g, '/');
@@ -50,6 +60,30 @@ export function createCanonicalAssetHelpers(deps) {
             legacyProvider: asset.storageProvider,
         });
     };
+    const assertCanonicalDocumentHeadCurrent = (asset) => {
+        const resolved = resolveCanonicalContentRead(asset, 'document');
+        if (resolved.source === 'deleted') {
+            throw new Error(`Document ${asset.assetId} not found in workspace ${deps.activeWorkspaceId}.`);
+        }
+        if (resolved.source === 'versioned' && (resolved.storageProvider !== asset.storageProvider
+            || resolved.contentSha256 !== asset.contentSha256
+            || resolved.sizeBytes !== asset.sizeBytes)) {
+            throw new CanonicalDocumentHeadStaleError({
+                assetId: asset.assetId,
+                currentVersion: asset.version,
+                currentStorageProvider: asset.storageProvider,
+                currentContentSha256: asset.contentSha256,
+                currentSizeBytes: asset.sizeBytes,
+                headVersionId: resolved.versionId,
+                headStorageProvider: resolved.storageProvider,
+                headContentSha256: resolved.contentSha256,
+                headSizeBytes: resolved.sizeBytes,
+                nextTool: 'update_document',
+                guidance: 'Retry update_document with the complete current body and expectedVersion to republish the canonical immutable head. Do not use the returned download until the repair succeeds.',
+            });
+        }
+        return resolved;
+    };
     const buildSyntheticAttachmentId = (taskId, attachment) => {
         const stableSource = [
             taskId,
@@ -157,10 +191,7 @@ export function createCanonicalAssetHelpers(deps) {
         if (asset.scanStatus === 'pending') {
             throw new Error('Document scan pending');
         }
-        const resolved = resolveCanonicalContentRead(asset, 'document');
-        if (resolved.source === 'deleted') {
-            throw new Error(`Document ${asset.assetId} not found in workspace ${deps.activeWorkspaceId}.`);
-        }
+        const resolved = assertCanonicalDocumentHeadCurrent(asset);
         if (resolved.storageProvider === 'r2') {
             if (!normalizeRelativeStorageKey(resolved.physicalKey)) {
                 throw new Error(`Document ${asset.assetId} not found in workspace ${deps.activeWorkspaceId}.`);
@@ -324,7 +355,9 @@ export function createCanonicalAssetHelpers(deps) {
                 targetType,
                 targetId,
                 role,
-                displayName: kind === 'document' ? null : (captionRaw || null),
+                displayName: options?.displayName !== undefined
+                    ? options.displayName
+                    : kind === 'document' ? null : (captionRaw || null),
                 updatedAt: timestamp,
                 deletedAt: null
             });
@@ -338,6 +371,7 @@ export function createCanonicalAssetHelpers(deps) {
         getAttachmentAssetRecord,
         buildAttachmentDownloadUrl,
         buildDocumentDownloadUrl,
+        assertCanonicalDocumentHeadCurrent,
         readCanonicalAttachmentBuffer,
         readCanonicalDocumentBuffer,
         toTaskAttachmentRecord,

package/dist/mcp/collaborationRegistrar.js

@@ -23,7 +23,7 @@ export function registerCollaborationTools(registerTool, executeTool) {
         });
     };
     register('list_assignees', (context) => ({
-        description: context.describeTool('List eligible assignees for the active workspace. Returns human workspace members and AI profiles that can own tasks. Use query to match a known ID, label, or username without loading the full catalog. Calls without query or limit preserve full-catalog discovery.'),
+        description: context.describeTool('List eligible assignees for the active workspace. Includes members and AI profiles. Use query for a bounded ID, label, or username match.'),
         inputSchema: {
             properties: {
                 query: stringProperty('Optional case-insensitive substring matched against assignee ID, label, and username. When non-empty, returns at most 25 matches unless limit is set.'),
@@ -32,7 +32,7 @@ export function registerCollaborationTools(registerTool, executeTool) {
         },
     }));
     register('get_current_profile', (context) => ({
-        description: context.describeTool('Inspect current AI identity for this call (ambient session, connection bootstrap, or explicit profileToken). Returns identityBound (true if this invocation has a resolved identity), bindingSource, profile, taskFilter, suggestedArgs, and guidance. Stateless/scheduled agents: call with profileToken if no ambient bind; use the returned suggestedArgs (with assignee) for list_tasks and pass profileToken on writes. Call before mutating or to decide on resolve_profile.'),
+        description: context.describeTool('Inspect current AI identity for this call and write readiness. Stateless/scheduled agents may pass profileToken. Use before writes or to decide whether resolve_profile is needed.'),
         inputSchema: {
             properties: {
                 profileToken: stringProperty('Optional AI profile token to inspect when no profile is currently bound in session state. Pass only a token previously issued to this AI identity.'),
@@ -40,24 +40,25 @@ export function registerCollaborationTools(registerTool, executeTool) {
         },
     }));
     register('resolve_profile', (context) => ({
-        description: context.describeTool('Resolve or create this AI collaborator profile. Use a stable collaborator/product name that does not change with the active model. For stateless agents (no ambient binding): call with name + surfaceType (and profileToken to re-use); the response includes created, profileToken, profile, *plus* identityBound, bindingSource, taskFilter, suggestedArgs, nextTool, guidance. Store profileToken privately only. Use suggestedArgs for list_tasks; pass profileToken on mutating calls. Never write profileToken to repos, tasks, logs, or docs.'),
+        description: context.describeTool('Resolve or create this AI collaborator profile using a stable product name. Stateless agents use name + surfaceType and may reuse profileToken. If OAuth recovery returns candidates, retry with profileId. Store profileToken privately only; pass it on writes. Never write profileToken to repos, tasks, logs, or docs.'),
         inputSchema: {
             properties: {
-                name: stringProperty('Stable display name for the AI collaborator or product identity. Do not include the active model name or version.'),
-                icon: stringProperty('Optional icon name or emoji saved with the AI profile. Omit to leave unchanged when profileToken is provided.'),
-                color: stringProperty('Optional signature color as a Taskforce palette token or hex color. Omit on first registration to receive a stable application-assigned product or palette default. Omit to leave unchanged when profileToken is provided; workspace user overrides remain authoritative.'),
-                description: stringProperty('Optional short description stored on the AI profile. Omit to leave unchanged when profileToken is provided.'),
-                role: stringProperty('Optional role label stored on the AI profile. Omit to leave unchanged when profileToken is provided.'),
-                provider: stringProperty('Optional provider name stored as secondary diagnostic metadata on the AI profile. Omit to leave unchanged when profileToken is provided.'),
-                model: stringProperty('Optional model name stored as secondary diagnostic metadata on the AI profile. Omit to leave unchanged when profileToken is provided.'),
+                name: stringProperty('Stable collaborator or product name; exclude model names and versions.'),
+                icon: stringProperty('Optional profile icon or emoji; omit to leave unchanged.'),
+                color: stringProperty('Optional Taskforce palette token or hex color; omit to use the assigned default or retain the current value.'),
+                description: stringProperty('Optional profile description; omit to leave unchanged.'),
+                role: stringProperty('Optional role label; omit to leave unchanged.'),
+                provider: stringProperty('Optional provider metadata; omit to leave unchanged.'),
+                model: stringProperty('Optional model metadata; omit to leave unchanged.'),
                 surfaceType: {
                     anyOf: [
                         { type: 'string', enum: [...AI_PROFILE_SURFACE_TYPES] },
                         { type: 'null' },
                     ],
-                    description: 'Optional self-declared AI surface type. Use agent for a persistent named AI collaborator in Taskforce, cli for terminal-native coding agents, coding_tool for coding surfaces that are not specifically CLI or IDE-native, chat_app for a conversational app identity, and ide for an IDE-native copilot identity. If you are unsure or none of those fit, choose agent. Omit to leave unchanged; pass null or an empty string to clear.',
+                    description: 'Optional surface: agent (persistent collaborator), cli (terminal coding agent), coding_tool (other coding surface), chat_app (chat app), or ide (IDE copilot). Use agent when unsure. Omit to retain; null or empty clears.',
                 },
-                profileToken: stringProperty('Previously issued Taskforce profile token for this AI identity. Keep it in private agent/client state; when provided, Taskforce resolves the existing profile instead of creating a new one, and applies any supplied presentation field updates to that profile.'),
+                profileId: stringProperty('Compatible profile ID from a prior selection-required response.'),
+                profileToken: stringProperty('Private token previously issued for this AI identity; reuses and optionally updates that profile.'),
             },
             required: ['name'],
         },
@@ -73,11 +74,12 @@ export function registerCollaborationTools(registerTool, executeTool) {
         },
     }));
     register('add_comment', (context) => ({
-        description: context.describeTool('Add a comment to a task. Use this for agent progress notes, handoff summaries, decision logs, and audit trails. Comments are visible in the task timeline.'),
+        description: context.describeTool('Add a comment to a task. Pass idempotencyKey when retrying after an ambiguous timeout; reuse it only with the exact same target and text.'),
         inputSchema: {
             properties: {
                 id: stringProperty('Task ID or task reference such as T-123.'),
                 text: stringProperty('Comment text.'),
+                idempotencyKey: { type: 'string', minLength: 1, maxLength: 128, description: 'Optional opaque retry key scoped to the active workspace, actor, and tool.' },
             },
             required: ['id', 'text'],
         },