@taskforcehq/taskforce 0.3.306 → 0.3.307

package/dist/core/Taskforce.d.ts

@@ -44,10 +44,25 @@ export interface TaskEventDetails {
     changes?: Record<string, TaskEventChange>;
     [key: string]: unknown;
 }
+export type ActivityEntityType = 'task' | 'initiative' | 'workstream';
+interface BaseEntityEvent {
+    id: string;
+    workspaceId: string;
+    entityType: ActivityEntityType;
+    entityId: string;
+    action: string;
+    actor: string;
+    actorType: 'human' | 'ai' | 'system';
+    createdAt: string;
+    details?: TaskEventDetails;
+    actorProfile?: TaskActor | null;
+}
 export interface TaskEvent {
     id: string;
     taskId: string;
     workspaceId: string;
+    entityType?: 'task';
+    entityId?: string;
     action: string;
     actor: string;
     actorType: 'human' | 'ai' | 'system';
@@ -55,6 +70,11 @@ export interface TaskEvent {
     details?: TaskEventDetails;
     actorProfile?: TaskActor | null;
 }
+export interface PlanningEntityEvent extends BaseEntityEvent {
+    entityType: 'initiative' | 'workstream';
+    entityId: string;
+}
+export type EntityEvent = TaskEvent | PlanningEntityEvent;
 export interface CommentActivityItem {
     id: string;
     type: 'comment';
@@ -68,6 +88,13 @@ export interface AuditActivityItem {
     event: TaskEvent;
 }
 export type TaskActivityItem = CommentActivityItem | AuditActivityItem;
+export interface EntityAuditActivityItem {
+    id: string;
+    type: 'event';
+    timestamp: string;
+    event: EntityEvent;
+}
+export type EntityActivityItem = CommentActivityItem | EntityAuditActivityItem;
 export type DeletedTaskSource = 'ui' | 'mcp' | 'sync' | 'workspace-delete' | 'system';
 export interface DeletedTaskDetails {
     reason?: string | null;
@@ -110,12 +137,7 @@ export interface TaskItem {
     comments?: Comment[];
     activity?: TaskActivityItem[];
     taskEvents?: TaskEvent[];
-    attachments?: Array<string | {
-        path: string;
-        fsPath?: string;
-        caption?: string;
-        timestamp?: string;
-    }>;
+    attachments?: AttachmentItem[];
     /** @deprecated Use status='done'. Safe to remove after v0.4.x migration gate. */
     completed?: boolean;
     /** @deprecated Use status='cancelled'. Safe to remove after v0.4.x migration gate. */
@@ -134,6 +156,18 @@ export interface TaskItem {
     workstreamId?: string | null;
     checklistItems?: ChecklistItem[];
 }
+export type AttachmentItem = string | {
+    path: string;
+    fsPath?: string;
+    caption?: string;
+    displayName?: string;
+    originalFilename?: string;
+    timestamp?: string;
+    assetId?: string | null;
+    referenceNumber?: number | null;
+    referenceLabel?: string | null;
+    taskId?: string | null;
+};
 export interface InitiativeItem {
     id: string;
     referenceNumber?: number | null;
@@ -142,12 +176,9 @@ export interface InitiativeItem {
     description: string | null;
     ownerId?: string | null;
     comments?: Comment[];
-    attachments?: Array<string | {
-        path: string;
-        fsPath?: string;
-        caption?: string;
-        timestamp?: string;
-    }>;
+    activity?: EntityActivityItem[];
+    entityEvents?: PlanningEntityEvent[];
+    attachments?: AttachmentItem[];
     createdAt: string;
     updatedAt?: string;
     order?: number | null;
@@ -162,12 +193,9 @@ export interface WorkstreamItem {
     description: string | null;
     ownerId?: string | null;
     comments?: Comment[];
-    attachments?: Array<string | {
-        path: string;
-        fsPath?: string;
-        caption?: string;
-        timestamp?: string;
-    }>;
+    activity?: EntityActivityItem[];
+    entityEvents?: PlanningEntityEvent[];
+    attachments?: AttachmentItem[];
     createdAt: string;
     updatedAt?: string;
     order?: number | null;
@@ -388,6 +416,21 @@ interface UserAvatarUploadDraftRecord {
     createdAt: string;
     updatedAt: string;
 }
+interface TaskAttachmentUploadDraftRecord {
+    draftId: string;
+    workspaceId: string;
+    taskId: string;
+    actorRef: string;
+    storageKey: string;
+    mimeType: string;
+    originalFilename: string;
+    sizeBytes: number;
+    storageProvider: 'local' | 'r2' | 'external';
+    consumedAt?: string | null;
+    discardedAt?: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
 interface WorkspaceUserRecord {
     userId: string;
     email: string;
@@ -412,6 +455,8 @@ export interface AiProfileRecord {
     color: string;
     avatarUrl?: string | null;
     avatarSourceUrl?: string | null;
+    avatarRevision?: number;
+    avatarUpdatedAt?: string | null;
     description?: string | null;
     role?: string | null;
     provider?: string | null;
@@ -714,6 +759,9 @@ export interface McpOAuthAccessTokenAuthResult {
     provider: McpOAuthProvider;
     scopes: McpAccessTokenScope[];
     status: McpOAuthGrantStatus;
+    aiProfileId?: string | null;
+    aiProfileToken?: string | null;
+    aiProfileName?: string | null;
 }
 /**
  * Subset of TaskforceCore methods required by the sync route.
@@ -780,6 +828,21 @@ export interface TaskforceSyncCapable {
     listTaskEventsForSync(input: {
         workspaceId?: string | null;
     }): TaskEvent[];
+    getTaskEventForSync(input: {
+        workspaceId?: string | null;
+        taskId: string;
+        eventId: string;
+    }): TaskEvent | null;
+    taskExistsForSync(id: string, workspaceId?: string | null): boolean;
+    listEntityEventsForSync(input: {
+        workspaceId?: string | null;
+    }): EntityEvent[];
+    getEntityEventForSync(input: {
+        workspaceId?: string | null;
+        eventId: string;
+    }): EntityEvent | null;
+    initiativeExistsForSync(id: string, workspaceId?: string | null): boolean;
+    workstreamExistsForSync(id: string, workspaceId?: string | null): boolean;
     upsertAiProfileForSync(profile: AiProfileRecord): AiProfileRecord;
     replaceWorkspaceUsersForSync(input: {
         workspaceId: string;
@@ -791,6 +854,7 @@ export interface TaskforceSyncCapable {
     upsertDocumentReviewCommentForSync(comment: DocumentReviewCommentSyncRecord): DocumentReviewCommentSyncRecord;
     upsertAnnotatedAttachmentSessionForSync(session: AnnotatedAttachmentSessionRecord): AnnotatedAttachmentSessionRecord;
     upsertTaskEventForSync(event: TaskEvent): TaskEvent;
+    upsertEntityEventForSync(event: EntityEvent): EntityEvent;
     deleteDocumentReviewSessionForSync(input: {
         workspaceId?: string | null;
         sessionId: string;
@@ -823,6 +887,11 @@ export interface TaskforceSyncCapable {
         avatarUrl?: string | null;
         avatarSourceUrl?: string | null;
     }): AiProfileRecord;
+    updateAiProfileSurfaceType(input: {
+        workspaceId: string;
+        profileId: string;
+        surfaceType?: AiProfileSurfaceType | null;
+    }): AiProfileRecord;
     resolveWorkspaceActor(workspaceId: string, actorRef: unknown): TaskActor | null;
 }
 export declare class TaskforceCore implements TaskforceSyncCapable {
@@ -856,6 +925,7 @@ export declare class TaskforceCore implements TaskforceSyncCapable {
     private isGenericAiActorReference;
     private isKnownAiModelName;
     private isHumanActorReference;
+    private isStableActorReference;
     private normalizeAiProfileName;
     private normalizeAiProfileUsername;
     private normalizeAiProfileIcon;
@@ -866,6 +936,9 @@ export declare class TaskforceCore implements TaskforceSyncCapable {
     private workspaceUserToActor;
     private aiProfileRowToRecord;
     private aiProfileToActor;
+    private resolveCanonicalAiProfileId;
+    private findCanonicalAiProfileIdsByAlias;
+    private resolveUniqueAiProfileActorByAlias;
     private canonicalizeActorReference;
     private normalizeCreatedBy;
     private normalizeCommentAuthor;
@@ -874,9 +947,13 @@ export declare class TaskforceCore implements TaskforceSyncCapable {
     private normalizePlanningAttachments;
     private replaceTaskComments;
     private normalizeTaskEventActor;
+    private listEntityEventsInternal;
     private listTaskEventsInternal;
+    private buildEntityActivity;
     private buildTaskActivity;
+    private addEntityEvent;
     private addTaskEvent;
+    private replaceEntityEvents;
     private replaceTaskEvents;
     private mapDeletedTaskRow;
     private pruneDeletedTasks;
@@ -917,6 +994,9 @@ export declare class TaskforceCore implements TaskforceSyncCapable {
     private initiativeExists;
     private workstreamExists;
     private valueEqualsForBulkUpdate;
+    private buildPlanningEntityEventChanges;
+    private getPlanningEntityEventAction;
+    private addWorkstreamTaskMembershipEvents;
     private assertWorkstreamLinkAllowed;
     private assertInitiativeLinkAllowed;
     constructor(config: TaskforceConfig);
@@ -986,6 +1066,7 @@ export declare class TaskforceCore implements TaskforceSyncCapable {
     private migrateUserBetaAccessBackfillIfNeeded;
     private migrateDuplicateAiProfilesIfNeeded;
     private migrateLegacyActorReferencesIfNeeded;
+    private migrateLegacyCommentActorReferencesIfNeeded;
     private getWorkspaceOwnerUserId;
     getWorkspacePlanMode(workspaceId: string): 'personal' | 'team';
     setWorkspacePlanMode(workspaceId: string, mode: 'personal' | 'team', source?: string): 'personal' | 'team';
@@ -1065,6 +1146,7 @@ export declare class TaskforceCore implements TaskforceSyncCapable {
     getJsonBackupEnabled(workspaceId?: string, userId?: string): boolean;
     private listCanonicalTaskAttachments;
     private syncCanonicalTaskAttachmentLinks;
+    private syncCanonicalPlanningAttachmentLinks;
     private rowToTask;
     private rowToInitiative;
     private rowToWorkstream;
@@ -1076,17 +1158,44 @@ export declare class TaskforceCore implements TaskforceSyncCapable {
     resolveTaskIdentifier(value: string, workspaceId?: string): TaskItem | null;
     getInitiative(id: string, workspaceId?: string): InitiativeItem | null;
     listInitiatives(workspaceId?: string): InitiativeItem[];
-    createInitiative(input: Partial<InitiativeItem>, workspaceId?: string): InitiativeItem;
-    updateInitiative(id: string, patch: Partial<InitiativeItem>, workspaceId?: string): InitiativeItem;
-    archiveInitiative(id: string, workspaceId?: string): InitiativeItem;
-    unarchiveInitiative(id: string, workspaceId?: string): InitiativeItem;
+    private isTransientPlanningHydrationError;
+    private getInitiativeForWriteResult;
+    private getWorkstreamForWriteResult;
+    createInitiative(input: Partial<InitiativeItem>, workspaceId?: string, options?: {
+        actorRef?: string;
+        skipEntityEvents?: boolean;
+    }): InitiativeItem;
+    updateInitiative(id: string, patch: Partial<InitiativeItem>, workspaceId?: string, options?: {
+        actorRef?: string;
+        skipEntityEvents?: boolean;
+    }): InitiativeItem;
+    archiveInitiative(id: string, workspaceId?: string, options?: {
+        actorRef?: string;
+        skipEntityEvents?: boolean;
+    }): InitiativeItem;
+    unarchiveInitiative(id: string, workspaceId?: string, options?: {
+        actorRef?: string;
+        skipEntityEvents?: boolean;
+    }): InitiativeItem;
     getWorkstream(id: string, workspaceId?: string): WorkstreamItem | null;
     listWorkstreams(workspaceId?: string): WorkstreamItem[];
     listPlanningBootstrap(workspaceId?: string, diagnostics?: PlanningBootstrapDiagnostics): PlanningBootstrapPayload;
-    createWorkstream(input: Partial<WorkstreamItem>, workspaceId?: string): WorkstreamItem;
-    updateWorkstream(id: string, patch: Partial<WorkstreamItem>, workspaceId?: string): WorkstreamItem;
-    archiveWorkstream(id: string, workspaceId?: string): WorkstreamItem;
-    unarchiveWorkstream(id: string, workspaceId?: string): WorkstreamItem;
+    createWorkstream(input: Partial<WorkstreamItem>, workspaceId?: string, options?: {
+        actorRef?: string;
+        skipEntityEvents?: boolean;
+    }): WorkstreamItem;
+    updateWorkstream(id: string, patch: Partial<WorkstreamItem>, workspaceId?: string, options?: {
+        actorRef?: string;
+        skipEntityEvents?: boolean;
+    }): WorkstreamItem;
+    archiveWorkstream(id: string, workspaceId?: string, options?: {
+        actorRef?: string;
+        skipEntityEvents?: boolean;
+    }): WorkstreamItem;
+    unarchiveWorkstream(id: string, workspaceId?: string, options?: {
+        actorRef?: string;
+        skipEntityEvents?: boolean;
+    }): WorkstreamItem;
     upsertInitiativeForSync(initiative: InitiativeItem, workspaceId?: string | null): InitiativeItem;
     upsertWorkstreamForSync(workstream: WorkstreamItem, workspaceId?: string | null): WorkstreamItem;
     listChecklistItems(taskId: string, workspaceId?: string): ChecklistItem[];
@@ -1229,6 +1338,20 @@ export declare class TaskforceCore implements TaskforceSyncCapable {
     markUserAvatarUploadDraftConsumed(userId: string, draftId: string): UserAvatarUploadDraftRecord | null;
     discardUserAvatarUploadDraft(userId: string, draftId: string): UserAvatarUploadDraftRecord | null;
     cleanupStaleUserAvatarUploadDrafts(userId: string, olderThanIso: string): UserAvatarUploadDraftRecord[];
+    createTaskAttachmentUploadDraft(input: {
+        draftId: string;
+        workspaceId: string;
+        taskId: string;
+        actorRef: string;
+        storageKey: string;
+        mimeType: string;
+        originalFilename: string;
+        sizeBytes: number;
+        storageProvider?: 'local' | 'r2' | 'external';
+    }): TaskAttachmentUploadDraftRecord;
+    getTaskAttachmentUploadDraft(draftId: string): TaskAttachmentUploadDraftRecord | null;
+    markTaskAttachmentUploadDraftConsumed(draftId: string): TaskAttachmentUploadDraftRecord | null;
+    discardTaskAttachmentUploadDraft(draftId: string): TaskAttachmentUploadDraftRecord | null;
     getSystemRole(userId: string): SystemRole;
     getUserBetaAccess(userId: string): boolean;
     countSystemAdmins(): number;
@@ -1287,6 +1410,11 @@ export declare class TaskforceCore implements TaskforceSyncCapable {
         avatarUrl?: string | null;
         avatarSourceUrl?: string | null;
     }): AiProfileRecord;
+    updateAiProfileSurfaceType(input: {
+        workspaceId: string;
+        profileId: string;
+        surfaceType?: AiProfileSurfaceType | null;
+    }): AiProfileRecord;
     resolveAiProfile(input: ResolveAiProfileInput, options?: ResolveAiProfileOptions): ResolveAiProfileResult;
     listAnnotatedAttachmentSessions(input: {
         workspaceId?: string | null;
@@ -1362,6 +1490,7 @@ export declare class TaskforceCore implements TaskforceSyncCapable {
     upsertDocumentReviewCommentForSync(comment: DocumentReviewCommentSyncRecord): DocumentReviewCommentSyncRecord;
     upsertAnnotatedAttachmentSessionForSync(session: AnnotatedAttachmentSessionRecord): AnnotatedAttachmentSessionRecord;
     upsertTaskEventForSync(event: TaskEvent): TaskEvent;
+    upsertEntityEventForSync(event: EntityEvent): EntityEvent;
     deleteDocumentReviewSessionForSync(input: {
         workspaceId?: string | null;
         sessionId: string;
@@ -1732,6 +1861,11 @@ export declare class TaskforceCore implements TaskforceSyncCapable {
         workspaceId: string;
         tokenId: string;
     }): McpAccessTokenRecord;
+    deleteMcpAccessToken(input: {
+        actorUserId: string;
+        workspaceId: string;
+        tokenId: string;
+    }): boolean;
     regenerateMcpAccessToken(input: {
         actorUserId: string;
         workspaceId: string;
@@ -1783,6 +1917,13 @@ export declare class TaskforceCore implements TaskforceSyncCapable {
         grantId: string;
     }): McpOAuthConnectorGrantRecord;
     authenticateMcpOAuthAccessToken(token: string, workspaceId?: string): McpOAuthAccessTokenAuthResult | null;
+    bindMcpOAuthConnectorGrantAiProfile(input: {
+        grantId: string;
+        workspaceId: string;
+        profileId: string;
+        profileToken: string;
+        profileName: string;
+    }): boolean;
     recordMcpOAuthConnectorGrantUsage(input: {
         grantId: string;
         workspaceId: string;
@@ -1882,9 +2023,32 @@ export declare class TaskforceCore implements TaskforceSyncCapable {
     updateWorkspaceUserRole(userId: string, workspaceId: string, role: AccessRole): boolean;
     getTask(id: string, workspaceId?: string): TaskItem | null;
     listTaskEvents(taskId: string, workspaceId?: string): TaskEvent[];
+    taskExistsForSync(id: string, workspaceId?: string | null): boolean;
+    initiativeExistsForSync(id: string, workspaceId?: string | null): boolean;
+    workstreamExistsForSync(id: string, workspaceId?: string | null): boolean;
+    recordTaskEvent(input: {
+        taskId: string;
+        workspaceId?: string | null;
+        action: string;
+        actor?: unknown;
+        createdAt?: string;
+        details?: TaskEventDetails;
+    }): void;
     listTaskEventsForSync(input: {
         workspaceId?: string | null;
     }): TaskEvent[];
+    getTaskEventForSync(input: {
+        workspaceId?: string | null;
+        taskId: string;
+        eventId: string;
+    }): TaskEvent | null;
+    listEntityEventsForSync(input: {
+        workspaceId?: string | null;
+    }): EntityEvent[];
+    getEntityEventForSync(input: {
+        workspaceId?: string | null;
+        eventId: string;
+    }): EntityEvent | null;
     getScheduleBoard(weekKey: string, showWeekends?: boolean, workspaceId?: string): ScheduleBoardResult;
     updateTaskSchedule(id: string, input: {
         scheduledDate: string | null;

package/dist/core/Taskforce.ids.test.js

@@ -426,6 +426,31 @@ describe('TaskforceCore id policy', () => {
                     })
                 })
             ]);
+            const removalSnapshotResult = core.applyWorkspaceSyncSnapshot({
+                tasks: [
+                    {
+                        id: 'task-sync-comments-update',
+                        title: 'Comment sync task',
+                        status: 'task',
+                        updatedAt: '2026-02-20T12:00:00.000Z',
+                        comments: [
+                            {
+                                id: 'comment-new',
+                                author: 'ai',
+                                text: 'Newer synced comment',
+                                timestamp: '2026-02-20T11:00:00.000Z'
+                            }
+                        ]
+                    }
+                ]
+            }, 'workspace-test');
+            expect(removalSnapshotResult.updated).toBe(1);
+            expect(core.getTask('task-sync-comments-update', 'workspace-test')?.comments).toEqual([
+                expect.objectContaining({
+                    id: 'comment-new',
+                    text: 'Newer synced comment',
+                })
+            ]);
             const staleResult = core.applyWorkspaceSyncSnapshot({
                 tasks: [
                     {
@@ -463,6 +488,39 @@ describe('TaskforceCore id policy', () => {
             cleanup();
         }
     });
+    it('keeps task sync watermarks monotonic when adding comments', () => {
+        const { core, cleanup } = makeCore();
+        try {
+            const task = core.createTask({
+                title: 'Comment watermark task',
+                status: 'task'
+            }, { workspaceId: 'workspace-test' });
+            const futureWatermark = '2099-02-20T10:00:00.000Z';
+            const db = core.db;
+            db.prepare(`
+                UPDATE tasks
+                SET updated_at = ?
+                WHERE tenant_id = ? AND workspace_id = ? AND id = ?
+            `).run(futureWatermark, 'default', 'workspace-test', task.id);
+            const updated = core.addComment(task.id, 'Comment should advance sync', 'user', 'workspace-test');
+            expect(Date.parse(String(updated?.updatedAt || ''))).toBeGreaterThan(Date.parse(futureWatermark));
+            const syncRows = core.listTasksForSync('workspace-test', {
+                watermark: futureWatermark,
+                id: task.id
+            }, 10);
+            expect(syncRows).toHaveLength(1);
+            expect(syncRows[0]?.task.comments).toEqual([
+                expect.objectContaining({
+                    author: 'user',
+                    submittedAuthor: 'user',
+                    text: 'Comment should advance sync'
+                })
+            ]);
+        }
+        finally {
+            cleanup();
+        }
+    });
     it('applies incoming sync update when timestamps are equal (deterministic tie behavior)', () => {
         const { core, cleanup } = makeCore();
         try {