@taskforcehq/taskforce 0.3.328 → 0.3.330

package/dist/core/McpTokenService.d.ts

@@ -1,5 +1,5 @@
 import type { DatabaseAdapter } from '../storage/databaseAdapter.js';
-import type { McpOAuthProvider, McpAccessTokenRecord, McpAccessTokenListResult, McpAccessTokenIssueResult, McpAccessTokenAuthResult, McpAccessTokenInspectionResult, McpOAuthClientRecord, McpOAuthConnectorGrantRecord, McpOAuthTokenExchangeResult, McpOAuthAccessTokenAuthResult } from './types.js';
+import type { McpCloudToolProfile, McpOAuthProvider, McpAccessTokenRecord, McpAccessTokenListResult, McpAccessTokenIssueResult, McpAccessTokenAuthResult, McpAccessTokenInspectionResult, McpOAuthClientRecord, McpOAuthConnectorGrantRecord, McpOAuthTokenExchangeResult, McpOAuthAccessTokenAuthResult } from './types.js';
 export interface McpTokenServiceDeps {
     /** Resolve plan/account access state for a given user */
     getAccountAccessStatus: (userId: string) => {
@@ -19,6 +19,8 @@ export declare class McpTokenService {
     private normalizeAccessRole;
     private normalizePermissionMode;
     private normalizeMcpAccessTokenScopes;
+    private normalizeMcpCloudToolProfile;
+    private requireMcpCloudToolProfile;
     private createMcpAccessTokenPrefix;
     private parseMcpAccessToken;
     private normalizeMcpOAuthProvider;
@@ -38,6 +40,7 @@ export declare class McpTokenService {
     private resolveMcpAccessTokenStatus;
     private rowToMcpAccessTokenRecord;
     private assertCanManageOwnMcpAccessToken;
+    private requireMcpToolProfileAdministrator;
     private countActiveMcpAccessTokens;
     revokeMcpCredentialsForUserWorkspace(userId: string, workspaceId: string, revokedByUserId?: string | null): void;
     revokeMcpCredentialsForWorkspace(workspaceId: string, revokedByUserId?: string | null): void;
@@ -52,6 +55,7 @@ export declare class McpTokenService {
         workspaceId: string;
         name: string;
         scopes: unknown;
+        toolProfile?: McpCloudToolProfile;
         expiresAt?: string | null;
         createdByIp?: string | null;
     }): McpAccessTokenIssueResult;
@@ -71,6 +75,15 @@ export declare class McpTokenService {
         tokenId: string;
         createdByIp?: string | null;
     }): McpAccessTokenIssueResult;
+    updateMcpAccessTokenToolProfile(input: {
+        actorUserId: string;
+        workspaceId: string;
+        tokenId: string;
+        toolProfile: unknown;
+    }): {
+        record: McpAccessTokenRecord;
+        previousToolProfile: McpCloudToolProfile;
+    };
     authenticateMcpAccessToken(token: string, workspaceId?: string): McpAccessTokenAuthResult | null;
     inspectMcpAccessToken(token: string): McpAccessTokenInspectionResult | null;
     recordMcpAccessTokenUsage(input: {
@@ -116,6 +129,15 @@ export declare class McpTokenService {
         workspaceId: string;
         grantId: string;
     }): McpOAuthConnectorGrantRecord;
+    updateMcpOAuthConnectorGrantToolProfile(input: {
+        actorUserId: string;
+        workspaceId: string;
+        grantId: string;
+        toolProfile: unknown;
+    }): {
+        record: McpOAuthConnectorGrantRecord;
+        previousToolProfile: McpCloudToolProfile;
+    };
     authenticateMcpOAuthAccessToken(token: string, workspaceId?: string): McpOAuthAccessTokenAuthResult | null;
     bindMcpOAuthConnectorGrantAiProfile(input: {
         grantId: string;

package/dist/core/McpTokenService.js

@@ -7,6 +7,7 @@ const MCP_ACCESS_TOKEN_DEFAULT_PAGE_SIZE = 20;
 const MCP_ACCESS_TOKEN_MAX_PAGE_SIZE = 100;
 const MCP_ACCESS_TOKEN_ALLOWED_SCOPES = ['tasks:read', 'tasks:write', 'workspace:read'];
 const MCP_OAUTH_AUTH_CODE_TTL_MS = 10 * 60 * 1000;
+const MCP_CLOUD_TOOL_PROFILES = ['default', 'extended'];
 /**
  * Handles MCP direct-access tokens and MCP OAuth connector flow
  * (client registration, authorization codes, token exchange, grant lifecycle).
@@ -52,6 +53,19 @@ export class McpTokenService {
         }
         return unique;
     }
+    normalizeMcpCloudToolProfile(value, fallback = 'default') {
+        const normalized = String(value || '').trim().toLowerCase();
+        return MCP_CLOUD_TOOL_PROFILES.includes(normalized)
+            ? normalized
+            : fallback;
+    }
+    requireMcpCloudToolProfile(value) {
+        const normalized = String(value || '').trim().toLowerCase();
+        if (!MCP_CLOUD_TOOL_PROFILES.includes(normalized)) {
+            throw new TaskforceRuleError('toolProfile must be default or extended', 400, 'MCP_TOOL_PROFILE_INVALID');
+        }
+        return normalized;
+    }
     createMcpAccessTokenPrefix() {
         return `tfmcp_${randomBytes(6).toString('hex')}`;
     }
@@ -204,6 +218,7 @@ export class McpTokenService {
             workspaceId: String(row?.workspace_id || ''),
             userId: String(row?.user_id || ''),
             scopes,
+            toolProfile: this.normalizeMcpCloudToolProfile(row?.tool_profile),
             tokenPrefix: String(row?.token_prefix || ''),
             status: this.resolveMcpOAuthGrantStatus(row),
             lastUsedAt: row?.last_used_at ? String(row.last_used_at) : null,
@@ -286,6 +301,7 @@ export class McpTokenService {
                 u.email AS user_email,
                 t.name,
                 t.scopes_json,
+                t.tool_profile,
                 t.token_prefix,
                 t.token_hash,
                 t.status,
@@ -331,6 +347,7 @@ export class McpTokenService {
             userEmail: row.user_email ? String(row.user_email) : null,
             name: String(row.name || ''),
             scopes,
+            toolProfile: this.normalizeMcpCloudToolProfile(row.tool_profile),
             tokenPrefix: String(row.token_prefix || ''),
             status: this.resolveMcpAccessTokenStatus(row),
             lastUsedAt: row.last_used_at ? String(row.last_used_at) : null,
@@ -353,6 +370,12 @@ export class McpTokenService {
             throw new TaskforceRuleError('Forbidden', 403, 'FORBIDDEN');
         }
     }
+    requireMcpToolProfileAdministrator(actorUserId, workspaceId) {
+        const member = this.getActiveWorkspaceMemberForMcp(actorUserId, workspaceId);
+        if (member.role !== 'owner' && member.role !== 'admin') {
+            throw new TaskforceRuleError('Workspace owner or admin access is required', 403, 'MCP_TOOL_PROFILE_ADMIN_REQUIRED');
+        }
+    }
     countActiveMcpAccessTokens(userId, workspaceId) {
         const now = new Date().toISOString();
         const row = this.db.prepare(`
@@ -446,6 +469,7 @@ export class McpTokenService {
                 u.email AS user_email,
                 t.name,
                 t.scopes_json,
+                t.tool_profile,
                 t.token_prefix,
                 t.token_hash,
                 t.status,
@@ -480,6 +504,7 @@ export class McpTokenService {
             throw new TaskforceRuleError('Token name is required', 400, 'MCP_TOKEN_NAME_REQUIRED');
         }
         const scopes = this.normalizeMcpAccessTokenScopes(input.scopes);
+        const toolProfile = this.normalizeMcpCloudToolProfile(input.toolProfile);
         const expiresAt = input.expiresAt ? String(input.expiresAt).trim() : null;
         const now = new Date().toISOString();
         if (expiresAt && expiresAt <= now) {
@@ -501,12 +526,12 @@ export class McpTokenService {
         const createdByIp = input.createdByIp ? String(input.createdByIp).trim() : null;
         this.db.prepare(`
             INSERT INTO mcp_access_tokens (
-                id, tenant_id, workspace_id, user_id, name, scopes_json, token_prefix, token_hash, status,
+                id, tenant_id, workspace_id, user_id, name, scopes_json, tool_profile, token_prefix, token_hash, status,
                 last_used_at, last_used_ip, last_used_user_agent, created_by_ip, expires_at, revoked_at,
                 revoked_by_user_id, created_at, updated_at
             )
-            VALUES (?, ?, ?, ?, ?, ?, ?, ?, 'active', NULL, NULL, NULL, ?, ?, NULL, NULL, ?, ?)
-        `).run(tokenId, this.tenantId, member.workspaceId, member.userId, name, JSON.stringify(scopes), tokenPrefix, tokenHash, createdByIp, expiresAt, now, now);
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 'active', NULL, NULL, NULL, ?, ?, NULL, NULL, ?, ?)
+        `).run(tokenId, this.tenantId, member.workspaceId, member.userId, name, JSON.stringify(scopes), toolProfile, tokenPrefix, tokenHash, createdByIp, expiresAt, now, now);
         const row = this.getMcpAccessTokenRow(tokenId, member.workspaceId);
         if (!row) {
             throw new TaskforceRuleError('Failed to create MCP token', 500, 'MCP_TOKEN_CREATE_FAILED');
@@ -573,18 +598,39 @@ export class McpTokenService {
                 workspaceId: revoked.workspaceId,
                 name: revoked.name,
                 scopes: revoked.scopes,
+                toolProfile: revoked.toolProfile,
                 expiresAt: revoked.expiresAt || null,
                 createdByIp: input.createdByIp || null,
             });
         });
         return tx();
     }
+    updateMcpAccessTokenToolProfile(input) {
+        this.requireMcpToolProfileAdministrator(input.actorUserId, input.workspaceId);
+        const row = this.getMcpAccessTokenRow(input.tokenId, input.workspaceId);
+        if (!row) {
+            throw new TaskforceRuleError('MCP token not found', 404, 'MCP_TOKEN_NOT_FOUND');
+        }
+        const previousToolProfile = this.normalizeMcpCloudToolProfile(row.tool_profile);
+        const toolProfile = this.requireMcpCloudToolProfile(input.toolProfile);
+        const now = new Date().toISOString();
+        this.db.prepare(`
+            UPDATE mcp_access_tokens
+            SET tool_profile = ?, updated_at = ?
+            WHERE tenant_id = ? AND workspace_id = ? AND id = ?
+        `).run(toolProfile, now, this.tenantId, input.workspaceId, row.id);
+        const updated = this.getMcpAccessTokenRow(row.id, input.workspaceId);
+        if (!updated) {
+            throw new TaskforceRuleError('MCP token not found', 404, 'MCP_TOKEN_NOT_FOUND');
+        }
+        return { record: this.rowToMcpAccessTokenRecord(updated), previousToolProfile };
+    }
     authenticateMcpAccessToken(token, workspaceId) {
         const parsed = this.parseMcpAccessToken(token);
         if (!parsed)
             return null;
         const row = this.db.prepare(`
-            SELECT id, workspace_id, user_id, scopes_json, token_hash, status, expires_at, revoked_at
+            SELECT id, workspace_id, user_id, scopes_json, tool_profile, token_hash, status, expires_at, revoked_at
             FROM mcp_access_tokens
             WHERE tenant_id = ?
               AND token_prefix = ?
@@ -612,6 +658,7 @@ export class McpTokenService {
             workspaceId: row.workspace_id,
             userId: row.user_id,
             scopes,
+            toolProfile: this.normalizeMcpCloudToolProfile(row.tool_profile),
             status,
         };
     }
@@ -620,7 +667,7 @@ export class McpTokenService {
         if (!parsed)
             return null;
         const row = this.db.prepare(`
-            SELECT id, workspace_id, user_id, name, scopes_json, token_hash, status, expires_at, revoked_at
+            SELECT id, workspace_id, user_id, name, scopes_json, tool_profile, token_hash, status, expires_at, revoked_at
             FROM mcp_access_tokens
             WHERE tenant_id = ?
               AND token_prefix = ?
@@ -644,6 +691,7 @@ export class McpTokenService {
             userId: row.user_id,
             name: String(row.name || ''),
             scopes,
+            toolProfile: this.normalizeMcpCloudToolProfile(row.tool_profile),
             status: this.resolveMcpAccessTokenStatus(row),
         };
     }
@@ -783,7 +831,7 @@ export class McpTokenService {
         const clientName = String(client.client_name || this.defaultMcpOAuthClientName(provider)).trim() || this.defaultMcpOAuthClientName(provider);
         const tx = this.db.transaction(() => {
             const existingRows = this.db.prepare(`
-                SELECT id, ai_profile_id, ai_profile_token, ai_profile_name
+                SELECT id, tool_profile, ai_profile_id, ai_profile_token, ai_profile_name
                 FROM mcp_oauth_connector_grants
                 WHERE tenant_id = ?
                   AND provider = ?
@@ -794,6 +842,7 @@ export class McpTokenService {
                 ORDER BY created_at DESC
             `).all(this.tenantId, provider, String(client.id), String(row.user_id), String(row.workspace_id));
             const previousBinding = existingRows.find((existing) => existing.ai_profile_id && existing.ai_profile_token && existing.ai_profile_name) || null;
+            const toolProfile = this.normalizeMcpCloudToolProfile(existingRows[0]?.tool_profile);
             const revokeTime = new Date().toISOString();
             existingRows.forEach((existing) => {
                 if (!existing?.id)
@@ -819,12 +868,12 @@ export class McpTokenService {
             const tokenHash = hashMcpOAuthSecret(secret);
             this.db.prepare(`
                 INSERT INTO mcp_oauth_connector_grants (
-                    id, tenant_id, provider, client_id, client_name, product_client_id, user_id, workspace_id, scopes_json,
+                    id, tenant_id, provider, client_id, client_name, product_client_id, user_id, workspace_id, scopes_json, tool_profile,
                     token_prefix, token_hash, status, last_used_at, revoked_at, revoked_by_user_id,
                     ai_profile_id, ai_profile_token, ai_profile_name, created_at, updated_at
                 )
-                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'active', NULL, NULL, NULL, ?, ?, ?, ?, ?)
-            `).run(grantId, this.tenantId, provider, String(client.id || ''), clientName, client.product_client_id ? String(client.product_client_id) : null, String(row.user_id), String(row.workspace_id), JSON.stringify(scopes), tokenPrefix, tokenHash, previousBinding?.ai_profile_id || null, previousBinding?.ai_profile_token || null, previousBinding?.ai_profile_name || null, now, now);
+                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'active', NULL, NULL, NULL, ?, ?, ?, ?, ?)
+            `).run(grantId, this.tenantId, provider, String(client.id || ''), clientName, client.product_client_id ? String(client.product_client_id) : null, String(row.user_id), String(row.workspace_id), JSON.stringify(scopes), toolProfile, tokenPrefix, tokenHash, previousBinding?.ai_profile_id || null, previousBinding?.ai_profile_token || null, previousBinding?.ai_profile_name || null, now, now);
             this.db.prepare(`
                 UPDATE mcp_oauth_auth_codes
                 SET used_at = ?
@@ -909,12 +958,45 @@ export class McpTokenService {
         }
         return this.rowToMcpOAuthConnectorGrantRecord(updated);
     }
+    updateMcpOAuthConnectorGrantToolProfile(input) {
+        this.requireMcpToolProfileAdministrator(input.actorUserId, input.workspaceId);
+        const row = this.db.prepare(`
+            SELECT *
+            FROM mcp_oauth_connector_grants
+            WHERE tenant_id = ? AND workspace_id = ? AND id = ?
+            LIMIT 1
+        `).get(this.tenantId, input.workspaceId, String(input.grantId || '').trim());
+        if (!row?.id) {
+            throw new TaskforceRuleError('MCP connector grant not found', 404, 'MCP_OAUTH_GRANT_NOT_FOUND');
+        }
+        const previousToolProfile = this.normalizeMcpCloudToolProfile(row.tool_profile);
+        const toolProfile = this.requireMcpCloudToolProfile(input.toolProfile);
+        const now = new Date().toISOString();
+        this.db.prepare(`
+            UPDATE mcp_oauth_connector_grants
+            SET tool_profile = ?, updated_at = ?
+            WHERE tenant_id = ? AND workspace_id = ? AND id = ?
+        `).run(toolProfile, now, this.tenantId, input.workspaceId, String(row.id));
+        const updated = this.db.prepare(`
+            SELECT *
+            FROM mcp_oauth_connector_grants
+            WHERE tenant_id = ? AND workspace_id = ? AND id = ?
+            LIMIT 1
+        `).get(this.tenantId, input.workspaceId, String(row.id));
+        if (!updated) {
+            throw new TaskforceRuleError('MCP connector grant not found', 404, 'MCP_OAUTH_GRANT_NOT_FOUND');
+        }
+        return {
+            record: this.rowToMcpOAuthConnectorGrantRecord(updated),
+            previousToolProfile,
+        };
+    }
     authenticateMcpOAuthAccessToken(token, workspaceId) {
         const parsed = this.parseMcpOAuthOpaqueSecret(token, 'tfmcpoauth_');
         if (!parsed)
             return null;
         const row = this.db.prepare(`
-            SELECT id, provider, client_id, product_client_id, user_id, workspace_id, scopes_json, token_hash, status, revoked_at,
+            SELECT id, provider, client_id, product_client_id, user_id, workspace_id, scopes_json, tool_profile, token_hash, status, revoked_at,
                    ai_profile_id, ai_profile_token, ai_profile_name
             FROM mcp_oauth_connector_grants
             WHERE tenant_id = ?
@@ -945,6 +1027,7 @@ export class McpTokenService {
             provider: this.normalizeMcpOAuthProvider(row.provider),
             productClientId: row?.product_client_id ? String(row.product_client_id) : null,
             scopes,
+            toolProfile: this.normalizeMcpCloudToolProfile(row.tool_profile),
             status: this.resolveMcpOAuthGrantStatus(row),
             aiProfileId: row?.ai_profile_id ? String(row.ai_profile_id) : null,
             aiProfileToken: row?.ai_profile_token ? String(row.ai_profile_token) : null,

package/dist/core/TaskAttachmentLinksDurableMutationService.d.ts

@@ -8,7 +8,7 @@ export declare class DurableTaskAttachmentLinksApplyError extends Error {
     constructor(message: string, code: 'TASK_ATTACHMENT_ASSET_NOT_READY' | 'TASK_ATTACHMENT_ASSET_INVALID' | 'TASK_ATTACHMENT_LINK_INVALID', statusCode: number, assetId?: string | undefined);
 }
 export interface DurableTaskAttachmentLinksCore {
-    getWorkspaceAssetStore(): Pick<WorkspaceAssetStore, 'get' | 'listLinksForTask' | 'adoptReadableReferenceNumber'>;
+    getWorkspaceAssetStore(): Pick<WorkspaceAssetStore, 'get' | 'listLinksForTask' | 'adoptReadableReferenceNumber' | 'restoreDeleted'>;
     getWorkspaceAssetDispatchReadiness(assetId: string, workspaceId: string): {
         ready: boolean;
         retryable: boolean;
@@ -16,7 +16,7 @@ export interface DurableTaskAttachmentLinksCore {
     };
 }
 export interface DurableWorkspaceTaskAttachmentLinksCore extends DurableTaskAttachmentLinksCore {
-    getWorkspaceAssetStore(): Pick<WorkspaceAssetStore, 'get' | 'listLinksForTask' | 'listLinksForWorkspace' | 'listAllNormalizedByWorkspace' | 'adoptReadableReferenceNumber'>;
+    getWorkspaceAssetStore(): Pick<WorkspaceAssetStore, 'get' | 'listLinksForTask' | 'listLinksForWorkspace' | 'listAllNormalizedByWorkspace' | 'adoptReadableReferenceNumber' | 'restoreDeleted'>;
 }
 export declare function resolveTaskCardCoverAssetIdForLinks(input: {
     currentCardCoverAssetId?: string | null;
@@ -29,6 +29,7 @@ export declare function resolveTaskAttachmentLinksForDurableSync(core: DurableTa
     requireDispatchReady?: boolean;
     adoptAuthoritativeReferenceNumber?: boolean;
     ignoreAssetMetadataSnapshots?: boolean;
+    restoreDeletedExternalAssetForAuthoritativeSync?: boolean;
 }): AttachmentItem[];
 export declare function normalizeTaskAttachmentDescriptorsForDurableSync(core: DurableTaskAttachmentLinksCore, workspaceId: string, attachments: readonly AttachmentItem[], options?: {
     requireDispatchReady?: boolean;

package/dist/core/TaskAttachmentLinksDurableMutationService.js

@@ -53,6 +53,12 @@ function canonicalRole(asset, requested) {
     }
     return expected;
 }
+function canonicalPersistedRole(asset, persisted) {
+    // Historical external links predate the reference-only invariant. Repair
+    // projections must publish the current canonical shape, while mutation
+    // inputs continue through canonicalRole and remain strictly validated.
+    return asset.storageProvider === 'external' ? 'reference' : canonicalRole(asset, persisted);
+}
 function referenceFields(asset) {
     if (!asset.referenceNumber)
         return { referenceNumber: null, referenceLabel: null };
@@ -83,9 +89,13 @@ function assertReady(core, workspaceId, asset, options) {
     }
 }
 function canonicalLink(asset, link, fallbackOrder) {
+    // Historical task links could persist an external asset as an attachment.
+    // External assets are references by contract, so repair/export must emit the
+    // canonical role rather than reproducing an un-installable legacy link.
+    const role = asset.storageProvider === 'external' ? 'reference' : link.role;
     return {
         assetId: asset.assetId,
-        role: link.role,
+        role,
         order: Number.isSafeInteger(link.sortOrder) && Number(link.sortOrder) >= 0
             ? Number(link.sortOrder)
             : fallbackOrder,
@@ -107,7 +117,7 @@ export function listTaskAttachmentLinksForDurableSync(core, workspaceId, taskId)
             fail(`Task attachment asset is deleted: ${link.assetId}`, 'TASK_ATTACHMENT_ASSET_INVALID', 400);
         }
         assertReady(core, workspaceId, asset);
-        return canonicalLink(asset, link, index);
+        return canonicalLink(asset, { ...link, role: canonicalPersistedRole(asset, link.role) }, index);
     })
         .sort((left, right) => left.order - right.order
         || (left.assetId < right.assetId ? -1 : left.assetId > right.assetId ? 1 : 0)
@@ -139,7 +149,7 @@ export function listWorkspaceTaskAttachmentLinksForDurableSync(core, workspaceId
                 fail(`Task attachment asset is deleted: ${link.assetId}`, 'TASK_ATTACHMENT_ASSET_INVALID', 400);
             }
             assertReady(core, workspaceId, asset);
-            return canonicalLink(asset, link, index);
+            return canonicalLink(asset, { ...link, role: canonicalPersistedRole(asset, link.role) }, index);
         }).sort((left, right) => left.order - right.order
             || (left.assetId < right.assetId ? -1 : left.assetId > right.assetId ? 1 : 0)
             || (left.role < right.role ? -1 : left.role > right.role ? 1 : 0))
@@ -156,6 +166,14 @@ export function resolveTaskAttachmentLinksForDurableSync(core, workspaceId, link
         if (!asset) {
             fail(`Task attachment asset is unavailable because it has not reached this runtime: ${link.assetId}`, 'TASK_ATTACHMENT_ASSET_NOT_READY', 425, link.assetId);
         }
+        if (asset.deletedAt
+            && asset.storageProvider === 'external'
+            && options?.restoreDeletedExternalAssetForAuthoritativeSync === true) {
+            // External pointers do not travel through binary content hydration.
+            // An active authoritative link is the lifecycle proof needed to
+            // revive the existing local placeholder inside the apply transaction.
+            asset = store.restoreDeleted(asset.assetId, workspaceId, asset.updatedAt) || asset;
+        }
         assertReady(core, workspaceId, asset, options);
         // Replicated apply may align independently hydrated local D-/I- numbers
         // to cloud authority. Ordinary local/cloud mutation writers must never
@@ -175,8 +193,8 @@ export function resolveTaskAttachmentLinksForDurableSync(core, workspaceId, link
         const displayName = String(link.displayName
             || (options?.ignoreAssetMetadataSnapshots === true ? '' : link.originalFilename)
             || (options?.ignoreAssetMetadataSnapshots === true ? '' : link.caption)
-            || asset.originalFilename
-            || asset.logicalName).trim() || null;
+            || (options?.ignoreAssetMetadataSnapshots === true ? '' : asset.originalFilename)
+            || (options?.ignoreAssetMetadataSnapshots === true ? '' : asset.logicalName)).trim() || null;
         const projected = canonicalLink(asset, { role, displayName, sortOrder: index }, index);
         if (options?.ignoreAssetMetadataSnapshots !== true
             && ((link.referenceNumber ?? null) !== (projected.referenceNumber ?? null)
@@ -187,12 +205,18 @@ export function resolveTaskAttachmentLinksForDurableSync(core, workspaceId, link
             path: canonicalAssetPath(asset),
             assetId: asset.assetId,
             linkRole: role,
-            ...(asset.kind === 'document' && asset.storageProvider !== 'external' && projected.caption !== undefined
+            ...(options?.ignoreAssetMetadataSnapshots !== true
+                && asset.kind === 'document'
+                && asset.storageProvider !== 'external'
+                && projected.caption !== undefined
                 ? { caption: projected.caption } : {}),
             ...(projected.displayName !== undefined ? { displayName: projected.displayName } : {}),
-            ...(projected.originalFilename !== undefined ? { originalFilename: projected.originalFilename } : {}),
-            ...(projected.referenceNumber !== undefined ? { referenceNumber: projected.referenceNumber } : {}),
-            ...(projected.referenceLabel !== undefined ? { referenceLabel: projected.referenceLabel } : {}),
+            ...(options?.ignoreAssetMetadataSnapshots !== true && projected.originalFilename !== undefined
+                ? { originalFilename: projected.originalFilename } : {}),
+            ...(options?.ignoreAssetMetadataSnapshots !== true && projected.referenceNumber !== undefined
+                ? { referenceNumber: projected.referenceNumber } : {}),
+            ...(options?.ignoreAssetMetadataSnapshots !== true && projected.referenceLabel !== undefined
+                ? { referenceLabel: projected.referenceLabel } : {}),
         };
     });
 }

package/dist/core/TaskChecklistCommandService.d.ts

@@ -9,11 +9,23 @@ export interface TaskChecklistItem {
 }
 export interface TaskChecklistTask {
     id: string;
+    checklistItems?: TaskChecklistItem[];
 }
 export interface TaskChecklistReplaceMutation {
     taskId: string;
     items: TaskChecklistItem[];
     operationId: string;
+    expectedDetailRevision?: string;
+    requireDurableIdempotency?: boolean;
+    itemUpdateIntent?: {
+        kind: 'item-update';
+        itemId: string;
+        patch: {
+            text?: string;
+            done?: boolean;
+            order?: number;
+        };
+    };
 }
 export interface TaskChecklistCommandServiceDependencies {
     resolveTask(identifier: unknown): TaskChecklistTask;
@@ -35,6 +47,9 @@ export type ReplaceTaskChecklistCommandResult = {
 export type AddTaskChecklistItemCommandResult = ReplaceTaskChecklistCommandResult & {
     item: TaskChecklistItem | null;
 };
+export type UpdateTaskChecklistItemCommandResult = ReplaceTaskChecklistCommandResult & {
+    item: TaskChecklistItem;
+};
 export declare function createTaskChecklistCommandService(deps: TaskChecklistCommandServiceDependencies): {
     replace(input: {
         taskId: unknown;
@@ -47,4 +62,16 @@ export declare function createTaskChecklistCommandService(deps: TaskChecklistCom
         isCompleted?: unknown;
         done?: unknown;
     }): AddTaskChecklistItemCommandResult;
+    update(input: {
+        taskId: unknown;
+        itemId: unknown;
+        title?: unknown;
+        text?: unknown;
+        isCompleted?: unknown;
+        done?: unknown;
+        order?: unknown;
+        expectedDetailRevision?: unknown;
+        operationId?: string;
+        requireDurableIdempotency?: boolean;
+    }): UpdateTaskChecklistItemCommandResult;
 };

package/dist/core/TaskChecklistCommandService.js

@@ -26,13 +26,21 @@ function requireMutationResult(task, taskId) {
     throw new TaskChecklistCommandError(`Task ${taskId} not found`, 'TASK_NOT_FOUND', 404, { taskId });
 }
 export function createTaskChecklistCommandService(deps) {
-    const replaceItems = (taskId, items, operationKey) => {
-        requireMutationResult(deps.replace({
+    const replaceItems = (taskId, items, operationKey, options) => {
+        const mutated = deps.replace({
             taskId,
             items,
-            operationId: deps.createId('operation', operationKey),
-        }), taskId);
-        return deps.listItems(taskId);
+            operationId: options?.operationId || deps.createId('operation', operationKey),
+            ...(options?.expectedDetailRevision
+                ? { expectedDetailRevision: options.expectedDetailRevision }
+                : {}),
+            ...(options?.requireDurableIdempotency
+                ? { requireDurableIdempotency: true }
+                : {}),
+            ...(options?.itemUpdateIntent ? { itemUpdateIntent: options.itemUpdateIntent } : {}),
+        });
+        requireMutationResult(mutated, taskId);
+        return mutated?.checklistItems || deps.listItems(taskId);
     };
     return {
         replace(input) {
@@ -107,5 +115,75 @@ export function createTaskChecklistCommandService(deps) {
                 items,
             };
         },
+        update(input) {
+            const task = deps.resolveTask(input.taskId);
+            const itemId = String(input.itemId ?? '').trim();
+            if (!itemId) {
+                throw new TaskChecklistCommandError('update_task_checklist_item requires itemId.');
+            }
+            const currentItems = deps.listItems(task.id);
+            const existingItem = currentItems.find((item) => item.id === itemId);
+            if (!existingItem) {
+                throw new TaskChecklistCommandError(`Checklist item ${itemId} was not found on task ${task.id}.`, 'TASK_CHECKLIST_ITEM_NOT_FOUND', 404, { taskId: task.id, itemId });
+            }
+            const hasTitle = input.title !== undefined || input.text !== undefined;
+            const hasCompleted = input.isCompleted !== undefined || input.done !== undefined;
+            const hasOrder = input.order !== undefined;
+            if (!hasTitle && !hasCompleted && !hasOrder) {
+                throw new TaskChecklistCommandError('update_task_checklist_item requires at least one of text, done, or order.');
+            }
+            const title = hasTitle
+                ? normalizeTitle(input.title ?? input.text, 'update_task_checklist_item text')
+                : existingItem.title;
+            const completedInput = input.isCompleted ?? input.done;
+            if (hasCompleted && typeof completedInput !== 'boolean') {
+                throw new TaskChecklistCommandError('update_task_checklist_item done must be a boolean.');
+            }
+            const isCompleted = hasCompleted ? completedInput : existingItem.isCompleted;
+            const parsedOrder = hasOrder ? Number(input.order) : existingItem.order;
+            if (hasOrder && (!Number.isInteger(parsedOrder) || parsedOrder < 0)) {
+                throw new TaskChecklistCommandError('update_task_checklist_item order must be a non-negative integer.');
+            }
+            const expectedDetailRevision = input.expectedDetailRevision === undefined
+                ? undefined
+                : String(input.expectedDetailRevision).trim();
+            if (input.expectedDetailRevision !== undefined && !expectedDetailRevision) {
+                throw new TaskChecklistCommandError('update_task_checklist_item expectedDetailRevision must contain non-whitespace text.');
+            }
+            const unchanged = existingItem.title === title
+                && existingItem.isCompleted === isCompleted
+                && existingItem.order === parsedOrder;
+            const nextItem = unchanged
+                ? existingItem
+                : {
+                    ...existingItem,
+                    title,
+                    isCompleted,
+                    order: parsedOrder,
+                    updatedAt: deps.now(),
+                };
+            const nextItems = currentItems.map((item) => item.id === itemId ? nextItem : item);
+            const items = replaceItems(task.id, nextItems, `task-checklist-update:${task.id}:${itemId}`, {
+                operationId: input.operationId,
+                expectedDetailRevision,
+                requireDurableIdempotency: input.requireDurableIdempotency,
+                ...(input.requireDurableIdempotency ? {
+                    itemUpdateIntent: {
+                        kind: 'item-update',
+                        itemId,
+                        patch: {
+                            ...(hasTitle ? { text: title } : {}),
+                            ...(hasCompleted ? { done: isCompleted } : {}),
+                            ...(hasOrder ? { order: parsedOrder } : {}),
+                        },
+                    },
+                } : {}),
+            });
+            const item = items.find((candidate) => candidate.id === itemId);
+            if (!item) {
+                throw new TaskChecklistCommandError(`Checklist item ${itemId} was not found after updating task ${task.id}.`, 'TASK_CHECKLIST_ITEM_NOT_FOUND', 404, { taskId: task.id, itemId });
+            }
+            return { taskId: task.id, item, items };
+        },
     };
 }

package/dist/core/TaskLifecycleCommandService.d.ts

@@ -30,6 +30,7 @@ export interface TaskLifecycleCommandServiceDependencies {
         updates: Record<string, unknown>;
         forceDurable?: boolean;
         assigneeIntent?: TaskLifecycleAssigneeIntent;
+        handoffComment?: string;
     }): TaskLifecycleTask;
     mutateLifecycle(input: {
         taskId: string;
@@ -40,7 +41,7 @@ export interface TaskLifecycleCommandServiceDependencies {
             reason: string | undefined;
         };
     }): TaskLifecycleTask | null;
-    resolveReviewer(task: TaskLifecycleTask): TaskLifecycleReviewerResolution;
+    resolveReviewer(task: TaskLifecycleTask, reviewer?: unknown): TaskLifecycleReviewerResolution;
 }
 export declare class TaskLifecycleCommandError extends Error {
     readonly code: string;
@@ -81,6 +82,7 @@ export declare function createTaskLifecycleCommandService(deps: TaskLifecycleCom
     finish(task: TaskLifecycleTask, input: {
         outcome: unknown;
         comment?: unknown;
+        reviewer?: unknown;
     }): FinishTaskCommandResult;
     reopen(task: TaskLifecycleTask, input: {
         activeAiProfileId: string | null | undefined;

package/dist/core/TaskLifecycleCommandService.js

@@ -88,8 +88,12 @@ export function createTaskLifecycleCommandService(deps) {
                     nextTool: 'reopen_task',
                 });
             }
+            const normalizedComment = typeof input.comment === 'string' ? input.comment.trim() : '';
+            if (normalizedOutcome === 'review' && !normalizedComment) {
+                throw new TaskLifecycleCommandError('finish_task requires a nonblank handoff comment when outcome is review.', 'TASK_FINISH_REVIEW_COMMENT_REQUIRED', 400, { taskId: task.id, outcome: normalizedOutcome });
+            }
             const reviewerResolution = normalizedOutcome === 'review'
-                ? deps.resolveReviewer(task)
+                ? deps.resolveReviewer(task, input.reviewer)
                 : undefined;
             const updated = deps.setStatus({
                 task,
@@ -99,8 +103,8 @@ export function createTaskLifecycleCommandService(deps) {
                 ...(reviewerResolution
                     ? { assigneeIntent: { kind: 'set', value: reviewerResolution.assignee } }
                     : {}),
+                ...(normalizedOutcome === 'review' ? { handoffComment: normalizedComment } : {}),
             });
-            const normalizedComment = typeof input.comment === 'string' ? input.comment.trim() : '';
             return {
                 task: updated,
                 completion: {