@taskforcehq/taskforce 0.3.327 → 0.3.329

package/dist/hooks/useUiNotice.js

@@ -35,6 +35,10 @@ export function useUiNotice() {
             ttlMs,
             actionLabel: action?.label,
             onAction: action?.onAction,
+            actionPrimary: action?.primary,
+            secondaryActionLabel: action?.secondaryLabel,
+            onSecondaryAction: action?.onSecondaryAction,
+            dismissible: action?.dismissible,
             ownerKey: action?.ownerKey
         });
         // Actionable notices stay available until the action or explicit

package/dist/mcp/adminWorkspaceRegistrar.js

@@ -78,11 +78,11 @@ export function registerAdminWorkspaceTools(registerTool, executeTool) {
                         description: { type: 'string' },
                         category: { type: 'string' },
                         type: { type: 'string' },
-                        priority: { type: 'number', description: context.priorityDesc },
+                        priority: { type: 'integer', description: context.priorityDesc, enum: context.priorityEnum },
                         assignee: { type: 'string', description: `${context.assigneeHint} Call list_assignees to inspect the current eligible IDs.` },
                         owner: { type: 'string', description: `${context.assigneeHint} Alias for assignee.` },
                         status: { type: 'string', enum: ['task', 'on-hold', 'in-progress', 'review', 'done', 'cancelled'] },
-                        complexity: { type: 'number', description: context.complexityDesc },
+                        complexity: { type: 'integer', minimum: 1, maximum: 5, description: context.complexityDesc },
                     },
                     required: ['id'],
                 }),
@@ -101,7 +101,7 @@ export function registerAdminWorkspaceTools(registerTool, executeTool) {
                 priorities: arrayProperty('Ordered priority definitions to save.', {
                     type: 'object',
                     properties: {
-                        value: { type: 'number' },
+                        value: { type: 'integer', minimum: 1 },
                         label: { type: 'string' },
                     },
                 }),

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'],
         },

package/dist/mcp/documentAssetRegistrar.js

@@ -2,8 +2,16 @@ import { bindDomainTool } from './toolCatalog.js';
 function stringProperty(description, enumValues) {
     return enumValues ? { type: 'string', description, enum: enumValues } : { type: 'string', description };
 }
-function numberProperty(description) {
-    return { type: 'number', description };
+function boundedNumberProperty(description, minimum, maximum) {
+    return { type: 'number', description, minimum, maximum };
+}
+function integerProperty(description, minimum, maximum) {
+    return {
+        type: 'integer',
+        description,
+        ...(minimum === undefined ? {} : { minimum }),
+        ...(maximum === undefined ? {} : { maximum }),
+    };
 }
 function booleanProperty(description) {
     return { type: 'boolean', description };
@@ -17,12 +25,12 @@ function annotatedAttachmentMarkerProperty() {
         properties: {
             type: { type: 'string' },
             kind: { type: 'string' },
-            x: { type: 'number' },
-            y: { type: 'number' },
-            width: { type: 'number' },
-            height: { type: 'number' },
-            x2: { type: 'number' },
-            y2: { type: 'number' },
+            x: { type: 'number', minimum: 0, maximum: 1 },
+            y: { type: 'number', minimum: 0, maximum: 1 },
+            width: { type: 'number', minimum: 0, maximum: 1 },
+            height: { type: 'number', minimum: 0, maximum: 1 },
+            x2: { type: 'number', minimum: 0, maximum: 1 },
+            y2: { type: 'number', minimum: 0, maximum: 1 },
             text: { type: 'string' },
             instruction: { type: 'string' },
             instructionType: { type: 'string' },
@@ -85,6 +93,7 @@ export function registerDocumentAssetTools(registerTool, executeTool) {
                         properties: descriptor.inputSchema.properties,
                         ...(descriptor.inputSchema.required ? { required: descriptor.inputSchema.required } : {}),
                     },
+                    ...(descriptor.annotations ? { annotations: descriptor.annotations } : {}),
                 };
             },
             handler: bindDomainTool(executeTool, name),
@@ -95,11 +104,11 @@ export function registerDocumentAssetTools(registerTool, executeTool) {
         inputSchema: {
             properties: {
                 taskId: stringProperty('Task ID or task reference such as T-123.'),
-                id: stringProperty('Alias for taskId. Task ID or task reference such as T-123.'),
                 attachmentId: stringProperty('Optional attachment descriptor id to include content for one attachment.'),
                 format: stringProperty('Optional read format when attachmentId is provided. Use metadata for descriptors or download for a download URL.', ['text', 'metadata', 'download']),
-                maxChars: numberProperty('Optional max inline character count for readable text attachments. Longer content is truncated with size metadata and a download hint.'),
+                maxChars: integerProperty('Optional max inline character count for readable text attachments. Longer content is truncated with size metadata and a download hint.', 1),
             },
+            required: ['taskId'],
         },
     }));
     register('get_workstream_attachments', (context) => ({
@@ -109,13 +118,14 @@ export function registerDocumentAssetTools(registerTool, executeTool) {
                 id: stringProperty('Workstream ID or workstream reference such as WS-123.'),
                 attachmentId: stringProperty('Optional attachment descriptor id to include content for one attachment.'),
                 format: stringProperty('Optional read format when attachmentId is provided. Use metadata for descriptors or download for a download URL.', ['text', 'metadata', 'download']),
-                maxChars: numberProperty('Optional max inline character count for readable text attachments. Longer content is truncated with size metadata and a download hint.'),
+                maxChars: integerProperty('Optional max inline character count for readable text attachments. Longer content is truncated with size metadata and a download hint.', 1),
             },
             required: ['id'],
         },
     }));
     register('link_document', (context) => ({
         description: context.describeTool('Link an existing canonical document to a task, initiative, or workstream without copying it. The operation is idempotent. Use search_documents first when you do not know the exact D-123 reference or asset id.'),
+        annotations: { idempotentHint: true },
         inputSchema: {
             properties: {
                 documentId: stringProperty('Canonical document reference such as D-123, document id, or asset id.'),
@@ -139,6 +149,7 @@ export function registerDocumentAssetTools(registerTool, executeTool) {
     }));
     register('rehome_document', (context) => ({
         description: context.describeTool('Atomically move an existing canonical document reference between a task, initiative, or workstream without copying or deleting the document. Use this instead of separate link_document and unlink_document calls when correcting planning scope.'),
+        annotations: { idempotentHint: true },
         inputSchema: {
             properties: {
                 documentId: stringProperty('Canonical document reference such as D-123, document id, or asset id.'),
@@ -159,18 +170,18 @@ export function registerDocumentAssetTools(registerTool, executeTool) {
     }));
     register('save_workstream_attachment', (context) => ({
         description: context.describeTool(context.runtimeMode === 'cloud'
-            ? 'Save generated content and attach it to a workstream. Provide inline content. Set overwrite=true to replace an existing canonical attachment with the same filename.'
-            : 'Save a file and attach it to a workstream. Provide inline content or an approved local sourcePath. Set overwrite=true to replace an existing canonical attachment with the same filename.'),
+            ? 'Save inline content as a workstream-owned attachment. Use overwrite=true to replace the same filename.'
+            : 'Save inline content or an approved local file as a workstream-owned attachment. Use overwrite=true to replace the same filename.'),
         inputSchema: {
             properties: {
                 id: stringProperty('Workstream ID or workstream reference such as WS-123.'),
                 filename: stringProperty('Destination filename for the attachment.'),
-                content: stringProperty('Inline file content; use this for AI-authored markdown/text attachments.'),
+                content: stringProperty('Inline text content.'),
                 ...(context.runtimeMode === 'local' ? {
                     sourcePath: stringProperty("Existing local file. Allowed roots: project, registered Git worktrees, Taskforce-managed sources, approved agent workspaces, or the bound profile's ~/.taskforce/qa/<username>/artifacts."),
                 } : {}),
                 caption: stringProperty('Optional attachment caption.'),
-                overwrite: booleanProperty('When true, overwrite an existing canonical workstream attachment with the same filename instead of creating a new one.'),
+                overwrite: booleanProperty('Replace the existing attachment with the same filename.'),
             },
             required: ['id', 'filename'],
         },
@@ -192,25 +203,25 @@ export function registerDocumentAssetTools(registerTool, executeTool) {
                 id: stringProperty('Initiative ID or initiative reference such as IN-123.'),
                 attachmentId: stringProperty('Optional attachment descriptor id to include content for one attachment.'),
                 format: stringProperty('Optional read format when attachmentId is provided. Use metadata for descriptors or download for a download URL.', ['text', 'metadata', 'download']),
-                maxChars: numberProperty('Optional max inline character count for readable text attachments. Longer content is truncated with size metadata and a download hint.'),
+                maxChars: integerProperty('Optional max inline character count for readable text attachments. Longer content is truncated with size metadata and a download hint.', 1),
             },
             required: ['id'],
         },
     }));
     register('save_initiative_attachment', (context) => ({
         description: context.describeTool(context.runtimeMode === 'cloud'
-            ? 'Save generated content and attach it to an initiative. Provide inline content. Set overwrite=true to replace an existing canonical attachment with the same filename.'
-            : 'Save a file and attach it to an initiative. Provide inline content or an approved local sourcePath. Set overwrite=true to replace an existing canonical attachment with the same filename.'),
+            ? 'Save inline content as an initiative-owned attachment. Use overwrite=true to replace the same filename.'
+            : 'Save inline content or an approved local file as an initiative-owned attachment. Use overwrite=true to replace the same filename.'),
         inputSchema: {
             properties: {
                 id: stringProperty('Initiative ID or initiative reference such as IN-123.'),
                 filename: stringProperty('Destination filename for the attachment.'),
-                content: stringProperty('Inline file content; use this for AI-authored markdown/text attachments.'),
+                content: stringProperty('Inline text content.'),
                 ...(context.runtimeMode === 'local' ? {
                     sourcePath: stringProperty("Existing local file. Allowed roots: project, registered Git worktrees, Taskforce-managed sources, approved agent workspaces, or the bound profile's ~/.taskforce/qa/<username>/artifacts."),
                 } : {}),
                 caption: stringProperty('Optional attachment caption.'),
-                overwrite: booleanProperty('When true, overwrite an existing canonical initiative attachment with the same filename instead of creating a new one.'),
+                overwrite: booleanProperty('Replace the existing attachment with the same filename.'),
             },
             required: ['id', 'filename'],
         },
@@ -226,11 +237,12 @@ export function registerDocumentAssetTools(registerTool, executeTool) {
         },
     }));
     register('search_images', (context) => ({
-        description: context.describeTool('Search image assets by keyword, title, filename, caption, or I-123 reference. Use this before get_image when you only know a rough identifier.'),
+        description: context.describeTool('Search image assets by keyword, title, filename, caption, or I-123 reference. Use offset/limit to continue broad searches, then call get_image for the selected result.'),
         inputSchema: {
             properties: {
                 query: stringProperty('Search term for image lookup, including I-123 references.'),
-                limit: numberProperty('Max images to return.'),
+                limit: integerProperty('Page size (default 10; max 50).', 1, 50),
+                offset: integerProperty('Non-negative result offset (default 0).', 0),
             },
             required: ['query'],
         },
@@ -239,17 +251,18 @@ export function registerDocumentAssetTools(registerTool, executeTool) {
         description: context.describeTool('Get a single image by asset id or image reference such as I-123. Use this first when the user references an image, then use get_image_annotations for saved annotation sessions and payloads. When the image is being used for UI, placement, or visual correction feedback, read the saved annotation payload before making changes.'),
         inputSchema: {
             properties: {
-                id: stringProperty('Image asset id or image reference such as I-123.'),
-                imageId: stringProperty('Alias for id. Image asset id or image reference such as I-123.'),
+                imageId: stringProperty('Image asset id or image reference such as I-123.'),
             },
+            required: ['imageId'],
         },
     }));
     register('search_documents', (context) => ({
-        description: context.describeTool('Search document assets by keyword, title, filename, caption, or D-123 reference. Use this before get_document when you only know a rough identifier. Search results guide the next step into get_document.'),
+        description: context.describeTool('Search document assets by keyword, title, filename, caption, or D-123 reference. Use offset/limit to continue broad searches, then call get_document for the selected result.'),
         inputSchema: {
             properties: {
                 query: stringProperty('Search term for document lookup, including D-123 references.'),
-                limit: numberProperty('Max documents to return.'),
+                limit: integerProperty('Page size (default 10; max 50).', 1, 50),
+                offset: integerProperty('Non-negative result offset (default 0).', 0),
             },
             required: ['query'],
         },
@@ -261,8 +274,9 @@ export function registerDocumentAssetTools(registerTool, executeTool) {
                 documentId: stringProperty('Document asset id or document reference such as D-123.'),
                 includeContent: booleanProperty('When true, include bounded inline text content or a download reference for binary documents.'),
                 format: stringProperty('Optional read mode when including content.', ['metadata', 'text', 'content', 'full', 'download']),
-                maxChars: numberProperty('Optional max inline character count for readable documents. Longer content is truncated with size metadata and a download hint.'),
+                maxChars: integerProperty('Optional max inline character count for readable documents. Longer content is truncated with size metadata and a download hint.', 1),
             },
+            required: ['documentId'],
         },
     }));
     register('update_document', (context) => ({
@@ -285,7 +299,6 @@ export function registerDocumentAssetTools(registerTool, executeTool) {
         inputSchema: {
             properties: {
                 imageId: stringProperty('Image asset id or image reference such as I-123.'),
-                imageAssetId: stringProperty('Alias for imageId. Image asset id or image reference such as I-123.'),
                 taskId: stringProperty('Optional task ID or task reference such as T-123 to narrow sessions linked to one task.'),
                 sessionId: stringProperty('Optional annotated attachment session id to include the structured payload for one session.'),
             },
@@ -344,16 +357,16 @@ export function registerDocumentAssetTools(registerTool, executeTool) {
                 sessionId: stringProperty('Annotated attachment session id.'),
                 type: stringProperty('Marker type.'),
                 kind: stringProperty('Alias for type. Marker kind: pin, box, arrow, or text-note.'),
-                x: numberProperty('Normalized x coordinate in the 0..1 range.'),
-                y: numberProperty('Normalized y coordinate in the 0..1 range.'),
-                width: numberProperty('Optional normalized width in the 0..1 range.'),
-                height: numberProperty('Optional normalized height in the 0..1 range.'),
+                x: boundedNumberProperty('Normalized x coordinate in the 0..1 range.', 0, 1),
+                y: boundedNumberProperty('Normalized y coordinate in the 0..1 range.', 0, 1),
+                width: boundedNumberProperty('Optional normalized width in the 0..1 range.', 0, 1),
+                height: boundedNumberProperty('Optional normalized height in the 0..1 range.', 0, 1),
                 text: stringProperty('Optional marker text or note.'),
                 instruction: stringProperty('Alias for text. Marker instruction or note.'),
                 instructionType: stringProperty('Optional marker instruction category.'),
                 color: stringProperty('Optional marker color.'),
-                x2: numberProperty('Arrow endpoint normalized x coordinate.'),
-                y2: numberProperty('Arrow endpoint normalized y coordinate.'),
+                x2: boundedNumberProperty('Arrow endpoint normalized x coordinate.', 0, 1),
+                y2: boundedNumberProperty('Arrow endpoint normalized y coordinate.', 0, 1),
             },
             required: ['sessionId'],
         },
@@ -374,12 +387,12 @@ export function registerDocumentAssetTools(registerTool, executeTool) {
             properties: {
                 sessionId: stringProperty('Annotated attachment session id.'),
                 markerId: stringProperty('Marker id within the session.'),
-                x: numberProperty('Updated normalized x coordinate.'),
-                y: numberProperty('Updated normalized y coordinate.'),
-                width: numberProperty('Updated normalized width.'),
-                height: numberProperty('Updated normalized height.'),
-                x2: numberProperty('Updated arrow endpoint normalized x coordinate.'),
-                y2: numberProperty('Updated arrow endpoint normalized y coordinate.'),
+                x: boundedNumberProperty('Updated normalized x coordinate.', 0, 1),
+                y: boundedNumberProperty('Updated normalized y coordinate.', 0, 1),
+                width: boundedNumberProperty('Updated normalized width.', 0, 1),
+                height: boundedNumberProperty('Updated normalized height.', 0, 1),
+                x2: boundedNumberProperty('Updated arrow endpoint normalized x coordinate.', 0, 1),
+                y2: boundedNumberProperty('Updated arrow endpoint normalized y coordinate.', 0, 1),
                 instruction: stringProperty('Updated marker instruction.'),
                 instructionType: stringProperty('Updated marker instruction category.'),
                 color: stringProperty('Updated marker color.'),
@@ -393,7 +406,7 @@ export function registerDocumentAssetTools(registerTool, executeTool) {
             properties: {
                 sessionId: stringProperty('Annotated attachment session id.'),
                 markerId: stringProperty('Marker id within the session.'),
-                toIndex: numberProperty('Target zero-based review order.'),
+                toIndex: integerProperty('Target zero-based review order.', 0),
             },
             required: ['sessionId', 'markerId', 'toIndex'],
         },
@@ -466,13 +479,14 @@ export function registerDocumentAssetTools(registerTool, executeTool) {
         },
     }));
     register('add_document_review_comment', (context) => ({
-        description: context.describeTool('Add one follow-up comment to an existing review session. Prefer review_document for multi-comment first-pass reviews.'),
+        description: context.describeTool('Add one follow-up comment to an existing review session. Prefer review_document for a complete review. Pass idempotencyKey only for exact retries after an ambiguous timeout.'),
         inputSchema: {
             properties: {
                 sessionId: stringProperty('Document review session id.'),
                 body: stringProperty('Comment text.'),
                 anchor: documentReviewAnchorProperty(),
                 parentCommentId: stringProperty('Optional root comment id. When supplied, adds a reply to that one-level thread; replies cannot target other replies.'),
+                idempotencyKey: { type: 'string', minLength: 1, maxLength: 128, description: 'Optional opaque retry key scoped to the active workspace, actor, and tool.' },
             },
             required: ['sessionId', 'body'],
         },
@@ -536,10 +550,11 @@ export function registerDocumentAssetTools(registerTool, executeTool) {
                     uploadedPath: stringProperty('Finalize a previously staged remote upload by passing the uploaded Taskforce storage path returned by save_task_attachment init mode.'),
                     uploadDraftId: stringProperty('Finalize a previously staged remote upload by passing the uploadDraftId returned by save_task_attachment init mode.'),
                     mimeType: stringProperty('Mime type for staged remote uploads such as image/png or image/jpeg. Provide this with sizeBytes to start a staged upload.'),
-                    sizeBytes: numberProperty('File size in bytes for staged remote uploads. Provide this with mimeType to start a staged upload.'),
+                    sizeBytes: integerProperty('File size in bytes for staged remote uploads. Provide this with mimeType to start a staged upload.', 0),
                 }),
-                expectedSizeBytes: numberProperty('Optional exact byte count for integrity verification. The save is rejected before attachment when the persisted bytes would differ.'),
+                expectedSizeBytes: integerProperty('Optional exact byte count for integrity verification. The save is rejected before attachment when the persisted bytes would differ.', 0),
                 expectedSha256: stringProperty('Optional lowercase or uppercase SHA-256 hex digest for integrity verification. The save is rejected before attachment when the persisted bytes would differ.'),
+                displayName: stringProperty('Optional attachment display name. Defaults to filename and is independent from caption.'),
                 caption: stringProperty('Optional attachment caption.'),
                 overwrite: booleanProperty('When true, overwrite an existing canonical task attachment with the same filename instead of creating a new one.'),
             },
@@ -548,6 +563,7 @@ export function registerDocumentAssetTools(registerTool, executeTool) {
     }));
     register('set_task_plan', (context) => ({
         description: context.describeTool('Create or replace the canonical Markdown implementation plan for a task. Identical retries are no-ops. Optionally replace the task description with a concise summary after the plan is verified; a description failure preserves the valid plan and returns partial-success recovery guidance.'),
+        annotations: { idempotentHint: true },
         inputSchema: {
             properties: {
                 taskId: stringProperty('Task ID or task reference such as T-123.'),

package/dist/mcp/documentHelpers.d.ts

@@ -43,6 +43,7 @@ export declare function createDocumentHelpers(deps: DocumentHelpersDeps): {
     } | null;
     searchDocumentAssets: (queryRaw: unknown, options?: {
         limit?: unknown;
+        offset?: unknown;
     }) => Array<{
         asset: WorkspaceDocumentEntry;
         matchedOn: string[];

package/dist/mcp/documentHelpers.js

@@ -51,8 +51,10 @@ export function createDocumentHelpers(deps) {
         }
         const requestedLimit = Number(options?.limit);
         const limit = Number.isFinite(requestedLimit)
-            ? Math.max(1, Math.min(50, Math.trunc(requestedLimit)))
+            ? Math.max(1, Math.min(51, Math.trunc(requestedLimit)))
             : 10;
+        const requestedOffset = Number(options?.offset);
+        const offset = Number.isFinite(requestedOffset) ? Math.max(0, Math.trunc(requestedOffset)) : 0;
         const normalize = (value) => typeof value === 'string' ? value.trim().toLowerCase() : '';
         const tokenize = (value) => normalize(value).split(/[^a-z0-9]+/i).filter(Boolean);
         const allDocuments = deps.workspaceAssetStore.listDocumentsByWorkspace(deps.activeWorkspaceId);
@@ -103,8 +105,10 @@ export function createDocumentHelpers(deps) {
             return [{ asset, matchedOn: Array.from(matchedOn), score }];
         });
         return scoredMatches
-            .sort((a, b) => b.score - a.score || String(b.asset.updatedAt || '').localeCompare(String(a.asset.updatedAt || '')))
-            .slice(0, limit);
+            .sort((a, b) => b.score - a.score
+            || String(b.asset.updatedAt || '').localeCompare(String(a.asset.updatedAt || ''))
+            || a.asset.assetId.localeCompare(b.asset.assetId))
+            .slice(offset, offset + limit);
     };
     const resolveDocumentAssetByIdentifierOrThrow = (documentIdentifier, options) => {
         const normalizedValue = typeof documentIdentifier === 'string' ? documentIdentifier.trim() : '';

package/dist/mcp/localServiceProxy.js

@@ -3,6 +3,7 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { JSONRPCMessageSchema, } from '@modelcontextprotocol/sdk/types.js';
 import { normalizeMcpConnectionId, parseMcpClientId } from './clientRegistry.js';
 import { normalizeMcpToolProfile } from './toolProfiles.js';
+import { localServiceCloudTargetsEqual, parseLocalServiceCloudTarget, } from '../config/localServiceCloudTarget.js';
 import { discoverOrStartLocalService, LOCAL_SERVICE_API_BASE_PATH, LOCAL_SERVICE_PROTOCOL_VERSION, } from '../service/localServiceClientLifecycle.js';
 const REQUEST_TIMEOUT_MS = 120_000;
 const MAX_IN_FLIGHT = 32;
@@ -24,6 +25,7 @@ async function readJson(response, label) {
     }
 }
 function validateReadiness(readiness, descriptor) {
+    const readinessCloudTarget = parseLocalServiceCloudTarget(readiness.cloudTarget);
     if (!readiness.ready)
         throw new Error('Taskforce shared local service is not accepting new work.');
     if (readiness.protocolVersion !== LOCAL_SERVICE_PROTOCOL_VERSION
@@ -31,7 +33,8 @@ function validateReadiness(readiness, descriptor) {
         || readiness.generation !== descriptor.generation
         || readiness.pid !== descriptor.pid
         || readiness.endpoint !== descriptor.endpoint
-        || readiness.dataIdentity !== descriptor.ownershipKey) {
+        || readiness.dataIdentity !== descriptor.ownershipKey
+        || !localServiceCloudTargetsEqual(readinessCloudTarget, descriptor.cloudTarget)) {
         throw new Error('Taskforce shared local service readiness does not match its descriptor.');
     }
 }

package/dist/mcp/runtime.d.ts

@@ -16,6 +16,18 @@ import { createDurableTaskCommentMutationRouter } from '../sync/v3/durableTaskCo
 import { createDurableTaskChecklistMutationRouter } from '../sync/v3/durableTaskChecklistMutationRouter.js';
 import { createDurableTaskAttachmentLinksMutationRouter } from '../sync/v3/durableTaskAttachmentLinksMutationRouter.js';
 import type { LocalDataOwnerPermit } from '../server/localDataOwnerPermit.js';
+export type McpToolCallTiming = {
+    requestId: string | null;
+    toolName: string;
+    isWrite: boolean;
+    outcome: 'success' | 'failure';
+    totalMs: number;
+    preparationMs: number;
+    validationMs: number;
+    handlerMs: number;
+    responseBytes: number;
+    subphases: Record<string, number>;
+};
 export interface TaskforceMcpServerOptions {
     projectRoot?: string;
     tenantId?: string;
@@ -34,6 +46,7 @@ export interface TaskforceMcpServerOptions {
         mutationKind: string;
         payloadFingerprint: string;
     }) => void;
+    onToolCallTiming?: (timing: McpToolCallTiming) => void;
     operationIdentityScope?: {
         generation: string;
         sessionId: string;
@@ -45,10 +58,12 @@ export interface TaskforceMcpServerOptions {
     durableTaxonomyMutationRouter?: ReturnType<typeof createDurableTaxonomyMutationRouter>;
     durableInitiativeMutationRouterFactory?: (actorRef: string, options?: {
         operationId?: string;
+        commentId?: string;
         deferPostCommitNotification?: (notify: () => void) => void;
     }) => ReturnType<typeof createDurableInitiativeMutationRouter>;
     durableWorkstreamMutationRouterFactory?: (actorRef: string, options?: {
         operationId?: string;
+        commentId?: string;
         deferPostCommitNotification?: (notify: () => void) => void;
     }) => ReturnType<typeof createDurableWorkstreamMutationRouter>;
     durableTaskRelationshipMutationRouter?: ReturnType<typeof createDurableTaskRelationshipMutationRouter>;
@@ -62,6 +77,7 @@ export interface TaskforceMcpServerOptions {
         userId?: string | null;
         tokenId?: string | null;
         aiProfileId?: string | null;
+        aiProfileIdentityAsserted?: boolean;
         aiProfileToken?: AiProfileBootstrapConfig['aiProfileToken'];
         aiProfileName?: AiProfileBootstrapConfig['aiProfileName'];
         aiProfileIcon?: AiProfileBootstrapConfig['aiProfileIcon'];