@taskforcehq/taskforce 0.3.328 → 0.3.329

package/dist/mcp/runtime.js

@@ -32,7 +32,8 @@ import { WorkspaceSyncContentVersionStore, } from '../sync/engine/workspaceSyncC
 import { WorkspaceSyncPublishedContentResolver } from '../sync/engine/workspaceSyncPublishedContentResolver.js';
 import { createWorkspaceSyncServerContentRuntime } from '../sync/engine/workspaceSyncServerContentRuntime.js';
 import { resolveVirusScanConfigFromEnv, scanBufferForThreats } from '../security/virusScan.js';
-import { ANNOTATED_ATTACHMENTS_WORKSPACE_FEATURE_KEY, resolveAppGateAccess, } from '../runtime/appGates.js';
+import { ANNOTATED_ATTACHMENTS_WORKSPACE_FEATURE_KEY, } from '../runtime/appGates.js';
+import { resolveNodeAppGateAccess } from '../runtime/nodeAppGates.js';
 import { getDocumentReferenceLabel, parseDocumentReference } from '../utils/documentReferences.js';
 import { getImageReferenceLabel, parseImageReference } from '../utils/imageReferences.js';
 import { inferCanonicalAssetKind, isValidCanonicalDocumentAsset } from '../utils/canonicalAssetKind.js';
@@ -1208,7 +1209,9 @@ export function createTaskforceMcpServer(options = {}) {
             },
             tools: {},
         },
-        instructions: `Before writes, check get_current_profile; if unbound, use resolve_profile. Keep profileToken private. Use T-, IN-, WS-, I-, and D- references. Link url as [reference](url). For tracked work, prefer start_task and finish_task.`,
+        instructions: runtimeMode === 'cloud' && options.auth?.actorType === 'token'
+            ? `Cloud access-token clients must pass profileToken on every write; obtain it from resolve_profile and keep it private. Use T-, IN-, WS-, I-, and D- references. Link url as [reference](url). For tracked work, prefer start_task and finish_task.`
+            : `Before writes, check get_current_profile; if unbound, use resolve_profile. Keep profileToken private. Use T-, IN-, WS-, I-, and D- references. Link url as [reference](url). For tracked work, prefer start_task and finish_task.`,
     });
     const TOOL_PERMISSIONS = MCP_TOOL_PERMISSIONS;
     const RESOURCE_PERMISSIONS = {
@@ -1311,9 +1314,10 @@ export function createTaskforceMcpServer(options = {}) {
     function buildBoundedTextContent(content, maxChars) {
         const requestedMaxChars = Number(maxChars);
         const hasRequestedMaxChars = maxChars !== undefined && maxChars !== null && maxChars !== '';
-        const resolvedMaxChars = hasRequestedMaxChars && Number.isFinite(requestedMaxChars)
-            ? Math.max(1, Math.floor(requestedMaxChars))
-            : 200000;
+        if (hasRequestedMaxChars && (!Number.isInteger(requestedMaxChars) || requestedMaxChars < 1)) {
+            throw new McpPublicError('maxChars must be a positive integer');
+        }
+        const resolvedMaxChars = hasRequestedMaxChars ? requestedMaxChars : 200000;
         const characters = Array.from(content);
         const totalChars = characters.length;
         const boundedContent = totalChars > resolvedMaxChars
@@ -1405,8 +1409,10 @@ export function createTaskforceMcpServer(options = {}) {
         }
         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 allImages = workspaceAssetStore.listAllByWorkspace(ACTIVE_WORKSPACE_ID, { kind: 'image' });
@@ -1450,8 +1456,10 @@ export function createTaskforceMcpServer(options = {}) {
             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 searchDocumentAssets = documentHelpers.searchDocumentAssets;
     function buildImageDescriptor(asset) {
@@ -1465,7 +1473,9 @@ export function createTaskforceMcpServer(options = {}) {
             sizeBytes: typeof asset.sizeBytes === 'number' ? asset.sizeBytes : null,
             ...(runtimeMode === 'local' ? { storageKey: asset.storageKey ?? null } : {}),
             updatedAt: asset.updatedAt ?? null,
-            apiUrl: `/api/taskforce/context/${encodeURIComponent(String(asset.storageKey || '').trim())}`,
+            ...(runtimeMode === 'local'
+                ? { apiUrl: `/api/taskforce/context/${encodeURIComponent(String(asset.storageKey || '').trim())}` }
+                : {}),
         };
         return withAttachmentUrl({ ...descriptor, kind: 'image' });
     }
@@ -1518,6 +1528,7 @@ export function createTaskforceMcpServer(options = {}) {
             || `Image ${normalizedValue} not found in workspace ${ACTIVE_WORKSPACE_ID}. If you only know a keyword, filename, or rough title, call search_images first.`, 'MCP_NOT_FOUND', 404);
     }
     const auditActorType = options.auth?.actorType || (runtimeMode === 'cloud' ? 'user' : 'local');
+    const requiresExplicitTokenAuthorship = runtimeMode === 'cloud' && auditActorType === 'token';
     const auditActorUserId = String(options.auth?.userId || (runtimeMode === 'cloud' ? 'anonymous' : 'local-mcp')).trim() || 'anonymous';
     const auditTokenId = options.auth?.tokenId ? String(options.auth.tokenId).trim() : null;
     const configuredAiProfileId = options.auth?.aiProfileId ? String(options.auth.aiProfileId).trim() || null : null;
@@ -1591,7 +1602,7 @@ export function createTaskforceMcpServer(options = {}) {
         const shouldBindOAuthGrant = auditActorType === 'oauth'
             && Boolean(auditTokenId)
             && configuredAiProfileId !== profileId;
-        const shouldApplyClientContext = Boolean((configuredMcpClientId && configuredMcpClientId !== 'general')
+        const shouldApplyClientContext = auditActorType !== 'token' && Boolean((configuredMcpClientId && configuredMcpClientId !== 'general')
             || configuredMcpConnectionId);
         if (!shouldBindOAuthGrant && !shouldApplyClientContext)
             return;
@@ -1755,6 +1766,10 @@ export function createTaskforceMcpServer(options = {}) {
         return resolved;
     }
     function findTrustedBoundProfile(options) {
+        // A generic access token proves workspace/tool authorization, not which AI
+        // is acting. Never use its historical connection row as authorship proof.
+        if (requiresExplicitTokenAuthorship)
+            return null;
         const grantProfile = findProfileForConfiguredGrant();
         const connectionProfile = findProfileForConfiguredConnection(options);
         if (grantProfile && connectionProfile && grantProfile.id !== connectionProfile.id) {
@@ -1771,6 +1786,19 @@ export function createTaskforceMcpServer(options = {}) {
         }
         return profile;
     }
+    function assertOAuthProfileClientCompatibility(profile) {
+        if (auditActorType !== 'oauth' || !configuredMcpClientId)
+            return;
+        const connection = profile.providerMetadata?.connection;
+        const storedClientId = connection && typeof connection === 'object' && !Array.isArray(connection)
+            ? parseMcpClientId(connection.clientId)
+            : null;
+        const inferredClientId = inferLegacyMcpClientIdFromProfile(profile);
+        const profileClientId = storedClientId || inferredClientId;
+        if (!profileClientId || profileClientId === configuredMcpClientId)
+            return;
+        throw new TaskforceRuleError('The supplied AI profile is not compatible with this OAuth client product.', 409, 'AI_PROFILE_SELECTION_INVALID', { profileId: profile.id, profileClientId, configuredClientId: configuredMcpClientId });
+    }
     function listSelectableOAuthProfiles(profileName) {
         if (auditActorType !== 'oauth')
             return [];
@@ -2383,6 +2411,8 @@ export function createTaskforceMcpServer(options = {}) {
     function ensureResolvedProfileFromConnection(defaults) {
         if (activeAiProfileId)
             return;
+        if (requiresExplicitTokenAuthorship)
+            return;
         const boundProfile = findTrustedBoundProfile({ repairConnection: false });
         if (boundProfile) {
             if (configuredAiProfileIdentityAsserted) {
@@ -2457,6 +2487,25 @@ export function createTaskforceMcpServer(options = {}) {
             throw new TaskforceRuleError('Writes are blocked because this MCP session requested an identity that conflicts with its OAuth-bound profile. Reconnect with the intended profile and retry resolve_profile.', 409, 'AI_PROFILE_BINDING_CONFLICT', { reason: 'session_identity_quarantined', nextTool: 'resolve_profile' });
         }
         const profileToken = resolveProfileTokenFromArgs(args);
+        if (requiresExplicitTokenAuthorship) {
+            if (!profileToken) {
+                throw new McpPublicError('Cloud access-token clients must pass profileToken on every mutating call. Call resolve_profile to obtain it, keep it private, and retry this write.', 'AI_PROFILE_PROOF_REQUIRED', 401);
+            }
+            const tokenProfile = core.getAiProfileByToken({
+                workspaceId: ACTIVE_WORKSPACE_ID,
+                profileToken,
+                seatScope: configuredAiProfileSeatScope,
+            });
+            if (!tokenProfile) {
+                throw new McpPublicError('Invalid AI profile token. Call resolve_profile again and retry.', 'INVALID_AI_PROFILE_TOKEN', 401);
+            }
+            if (activeAiProfileId && activeAiProfileId !== tokenProfile.id) {
+                failAiProfileBindingConflict('The supplied profile token conflicts with the AI profile already active for this request.', { reason: 'request_token_mismatch', boundProfileId: activeAiProfileId, suppliedProfileId: tokenProfile.id });
+            }
+            if (!activeAiProfileId)
+                activateAiProfile(tokenProfile.id, 'token_lookup');
+            return;
+        }
         if (activeAiProfileId) {
             if (!profileToken)
                 return;
@@ -2491,6 +2540,8 @@ export function createTaskforceMcpServer(options = {}) {
                     suppliedProfileId: profile.id,
                 });
             }
+            if (!trustedBoundProfile)
+                assertOAuthProfileClientCompatibility(profile);
             if (trustedBoundProfile && configuredAiProfileIdentityAsserted) {
                 assertRequestedIdentityMatchesBoundProfile(trustedBoundProfile, {
                     name: configuredAiProfileName,
@@ -2525,7 +2576,7 @@ export function createTaskforceMcpServer(options = {}) {
         throw new McpPublicError('This tool requires an AI profile. Call resolve_profile first, then retry. If your MCP client is stateless, pass profileToken on mutating calls.', 'AI_PROFILE_REQUIRED');
     }
     function assertAnnotatedAttachmentReadAccess() {
-        const gate = resolveAppGateAccess(ANNOTATED_ATTACHMENTS_WORKSPACE_FEATURE_KEY);
+        const gate = resolveNodeAppGateAccess(ANNOTATED_ATTACHMENTS_WORKSPACE_FEATURE_KEY);
         if (!gate.allowed) {
             throw new TaskforceRuleError('Annotated attachments are unavailable for this workspace.', 403, gate.code || 'ANNOTATED_ATTACHMENTS_UNAVAILABLE');
         }
@@ -3340,6 +3391,17 @@ export function createTaskforceMcpServer(options = {}) {
             offset: Number(normalizedOffset),
         };
     }
+    function normalizeSearchReadPage(limit, offset, defaultLimit) {
+        const normalizedLimit = limit === undefined ? defaultLimit : limit;
+        const normalizedOffset = offset === undefined ? 0 : offset;
+        if (!Number.isInteger(normalizedLimit) || Number(normalizedLimit) < 1 || Number(normalizedLimit) > 50) {
+            throw new McpPublicError('limit must be an integer from 1 to 50');
+        }
+        if (!Number.isInteger(normalizedOffset) || Number(normalizedOffset) < 0) {
+            throw new McpPublicError('offset must be a non-negative integer');
+        }
+        return { limit: Number(normalizedLimit), offset: Number(normalizedOffset) };
+    }
     function buildCompactPlanningHistory(targetType, entity) {
         const duplicatedCommentAction = `${targetType}-comment-added`;
         const activity = Array.isArray(entity?.activity) ? entity.activity : [];
@@ -3516,17 +3578,26 @@ export function createTaskforceMcpServer(options = {}) {
             workstreamsByInitiativeId.set(normalizedInitiativeId, current);
         }
         const taskCountsByWorkstreamId = buildHistoricalTaskCountSnapshot();
-        const initiatives = core.listInitiatives(ACTIVE_WORKSPACE_ID)
-            .filter((initiative) => matchesInitiativePlanningQuery(initiative, query, workstreamsByInitiativeId.get(initiative.id) || []))
-            .map((initiative) => buildInitiativeResourcePayload(initiative, {
-            workstreamsByInitiativeId,
-            taskCountsByWorkstreamId,
-            detail: 'compact',
-        }));
+        const matches = core.listInitiatives(ACTIVE_WORKSPACE_ID)
+            .filter((initiative) => matchesInitiativePlanningQuery(initiative, query, workstreamsByInitiativeId.get(initiative.id) || []));
+        const offset = options?.offset ?? 0;
+        const limit = options?.limit ?? 25;
+        const initiatives = matches.slice(offset, offset + limit).map((initiative) => {
+            const compact = buildInitiativeResourcePayload(initiative, {
+                workstreamsByInitiativeId,
+                taskCountsByWorkstreamId,
+                detail: 'compact',
+            });
+            const { nextDetailOption: _nextDetailOption, ...summary } = compact;
+            return summary;
+        });
+        const pagination = buildPlanningPagination(matches.length, offset, limit, initiatives.length);
         return {
-            total: initiatives.length,
+            total: matches.length,
             ...(query ? { query } : {}),
             initiatives,
+            pagination,
+            guidance: 'Use get_initiative with the initiative ID or reference for details.',
         };
     }
     function buildWorkstreamsResourcePayload(options) {
@@ -3536,13 +3607,22 @@ export function createTaskforceMcpServer(options = {}) {
             initiativesById.set(initiative.id, initiative);
         }
         const taskCountsByWorkstreamId = buildHistoricalTaskCountSnapshot();
-        const workstreams = core.listWorkstreams(ACTIVE_WORKSPACE_ID)
-            .filter((workstream) => matchesWorkstreamPlanningQuery(workstream, query, initiativesById.get(workstream.initiativeId || '')))
-            .map((workstream) => buildWorkstreamResourcePayload(workstream, { taskCountsByWorkstreamId, detail: 'compact' }));
+        const matches = core.listWorkstreams(ACTIVE_WORKSPACE_ID)
+            .filter((workstream) => matchesWorkstreamPlanningQuery(workstream, query, initiativesById.get(workstream.initiativeId || '')));
+        const offset = options?.offset ?? 0;
+        const limit = options?.limit ?? 25;
+        const workstreams = matches.slice(offset, offset + limit).map((workstream) => {
+            const compact = buildWorkstreamResourcePayload(workstream, { taskCountsByWorkstreamId, detail: 'compact' });
+            const { nextDetailOption: _nextDetailOption, nextTaskTool: _nextTaskTool, suggestedTaskArgs: _suggestedTaskArgs, ...summary } = compact;
+            return summary;
+        });
+        const pagination = buildPlanningPagination(matches.length, offset, limit, workstreams.length);
         return {
-            total: workstreams.length,
+            total: matches.length,
             ...(query ? { query } : {}),
             workstreams,
+            pagination,
+            guidance: 'Use get_workstream for details or list_tasks with workstreamId for active tasks.',
         };
     }
     function buildPlanningWriteEntitySummary(targetType, entity) {
@@ -3843,7 +3923,9 @@ export function createTaskforceMcpServer(options = {}) {
     registerAdminWorkspaceTools(registerTool, (name, args) => executeRegisteredTool(name, args));
     const mutatingProfileTokenProperty = {
         type: 'string',
-        description: 'Optional profileToken from resolve_profile for stateless MCP clients.'
+        description: requiresExplicitTokenAuthorship
+            ? 'Required authorship proof for cloud access-token clients; obtain from resolve_profile.'
+            : 'Optional profileToken from resolve_profile for stateless MCP clients.'
     };
     const nonDestructiveWriteTools = new Set([
         'add_annotated_attachment_marker',
@@ -3876,6 +3958,9 @@ export function createTaskforceMcpServer(options = {}) {
             get priorityDesc() {
                 return `Priority level: ${getActivePriorities().map((priority) => `${priority.value} (${priority.label})`).join(', ')}`;
             },
+            get priorityEnum() {
+                return getActivePriorities().map((priority) => priority.value);
+            },
             get typeEnum() {
                 return getActiveTypes().map((type) => type.value);
             },
@@ -3916,6 +4001,11 @@ export function createTaskforceMcpServer(options = {}) {
             inputSchema: {
                 ...descriptor.inputSchema,
                 properties,
+                ...(requiresExplicitTokenAuthorship
+                    && descriptor.name !== 'resolve_profile'
+                    && isMcpWriteToolName(descriptor.name)
+                    ? { required: Array.from(new Set([...(descriptor.inputSchema.required || []), 'profileToken'])) }
+                    : {}),
                 additionalProperties: false,
             },
             annotations: {
@@ -4992,15 +5082,15 @@ export function createTaskforceMcpServer(options = {}) {
                     : resolveWorkstreamByIdentifierOrThrow(workstreamId).id;
                 const paginated = resolvedWorkstreamId !== undefined || offset !== undefined;
                 const parsedOffset = offset === undefined ? 0 : Number(offset);
-                if (!Number.isFinite(parsedOffset) || parsedOffset < 0)
-                    throw new McpPublicError('offset must be a non-negative number');
-                const normalizedOffset = Math.floor(parsedOffset);
+                if (!Number.isInteger(parsedOffset) || parsedOffset < 0)
+                    throw new McpPublicError('offset must be a non-negative integer');
+                const normalizedOffset = parsedOffset;
                 const parsedLimit = limit === undefined ? (paginated ? 50 : 0) : Number(limit);
-                if (!Number.isFinite(parsedLimit) || parsedLimit < 0)
-                    throw new McpPublicError('limit must be a non-negative number');
+                if (!Number.isInteger(parsedLimit) || parsedLimit < 0 || parsedLimit > 200)
+                    throw new McpPublicError('limit must be an integer from 1 to 200');
                 const normalizedLimit = paginated
-                    ? Math.min(200, Math.max(1, Math.floor(parsedLimit || 50)))
-                    : Math.floor(parsedLimit);
+                    ? (parsedLimit || 50)
+                    : parsedLimit;
                 const queriedTasks = core.listTasksSlim(ACTIVE_WORKSPACE_ID, {
                     category,
                     status,
@@ -5087,6 +5177,15 @@ export function createTaskforceMcpServer(options = {}) {
                     failAiProfileBindingConflict('The selected AI profile conflicts with the profile already bound to this MCP session or authenticated connection.', { reason: 'selected_profile_mismatch', boundProfileId: alreadyBoundProfile.id, selectedProfileId: explicitlySelectedProfile.id });
                 }
                 const boundProfile = alreadyBoundProfile || explicitlySelectedProfile;
+                if (!boundProfile && suppliedProfileToken) {
+                    const suppliedProfile = core.getAiProfileByToken({
+                        workspaceId: ACTIVE_WORKSPACE_ID,
+                        profileToken: suppliedProfileToken,
+                        seatScope: configuredAiProfileSeatScope,
+                    });
+                    if (suppliedProfile)
+                        assertOAuthProfileClientCompatibility(suppliedProfile);
+                }
                 if (boundProfile && suppliedProfileToken) {
                     const tokenProfile = core.getAiProfileByToken({
                         workspaceId: ACTIVE_WORKSPACE_ID,
@@ -5291,10 +5390,19 @@ export function createTaskforceMcpServer(options = {}) {
                 };
             }
             case "search_tasks": {
-                const { query, scope = "all" } = args;
-                const results = core.searchTaskSummaries(query, scope, ACTIVE_WORKSPACE_ID);
+                const { query, scope = "all", limit, offset } = args;
+                const page = normalizeSearchReadPage(limit, offset, 25);
+                const queried = core.searchTaskSummaries(query, scope, ACTIVE_WORKSPACE_ID, {
+                    limit: page.limit + 1,
+                    offset: page.offset,
+                });
+                const hasMore = queried.length > page.limit;
+                const results = hasMore ? queried.slice(0, page.limit) : queried;
                 return {
-                    content: [{ type: "text", text: renderTaskTable(results) }],
+                    content: [{
+                            type: "text",
+                            text: `${renderTaskTable(results)}\n\nPage: offset ${page.offset}, limit ${page.limit}, returned ${results.length}, hasMore ${hasMore}${hasMore ? `, nextOffset ${page.offset + results.length}` : ''}`,
+                        }],
                 };
             }
             case "get_task": {
@@ -5498,9 +5606,10 @@ export function createTaskforceMcpServer(options = {}) {
                 return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
             }
             case "list_initiatives": {
-                const { query } = args;
+                const { query, limit, offset } = args;
+                const page = normalizePlanningReadPage(limit, offset);
                 return {
-                    content: [{ type: "text", text: JSON.stringify(buildInitiativesResourcePayload({ query }), null, 2) }],
+                    content: [{ type: "text", text: JSON.stringify(buildInitiativesResourcePayload({ query, ...page }), null, 2) }],
                 };
             }
             case "get_initiative": {
@@ -5771,9 +5880,10 @@ export function createTaskforceMcpServer(options = {}) {
                 };
             }
             case "list_workstreams": {
-                const { query } = args;
+                const { query, limit, offset } = args;
+                const page = normalizePlanningReadPage(limit, offset);
                 return {
-                    content: [{ type: "text", text: JSON.stringify(buildWorkstreamsResourcePayload({ query }), null, 2) }],
+                    content: [{ type: "text", text: JSON.stringify(buildWorkstreamsResourcePayload({ query, ...page }), null, 2) }],
                 };
             }
             case "get_workstream": {
@@ -6190,8 +6300,11 @@ export function createTaskforceMcpServer(options = {}) {
             }
             case "search_images": {
                 assertAnnotatedAttachmentReadAccess();
-                const { query, limit } = args;
-                const results = searchImageAssets(query, { limit }).map(({ asset, matchedOn, score }) => ({
+                const { query, limit, offset } = args;
+                const page = normalizeSearchReadPage(limit, offset, 10);
+                const queried = searchImageAssets(query, { limit: page.limit + 1, offset: page.offset });
+                const hasMore = queried.length > page.limit;
+                const results = (hasMore ? queried.slice(0, page.limit) : queried).map(({ asset, matchedOn, score }) => ({
                     image: buildImageDescriptor(asset),
                     matchedOn,
                     score,
@@ -6207,6 +6320,13 @@ export function createTaskforceMcpServer(options = {}) {
                                 workspaceId: ACTIVE_WORKSPACE_ID,
                                 query: typeof query === 'string' ? query.trim() : '',
                                 results,
+                                pagination: {
+                                    offset: page.offset,
+                                    limit: page.limit,
+                                    returned: results.length,
+                                    hasMore,
+                                    ...(hasMore ? { nextOffset: page.offset + results.length } : {}),
+                                },
                                 guidance: results.length > 0
                                     ? 'After picking a match, call get_image with the suggestedArgs.imageId to inspect linked tasks and image notes.'
                                     : 'No matching canonical images were found. Try an I-123 reference, title keyword, or filename fragment.',
@@ -6277,8 +6397,11 @@ export function createTaskforceMcpServer(options = {}) {
                 };
             }
             case "search_documents": {
-                const { query, limit } = args;
-                const results = searchDocumentAssets(query, { limit }).map(({ asset, matchedOn, score }) => ({
+                const { query, limit, offset } = args;
+                const page = normalizeSearchReadPage(limit, offset, 10);
+                const queried = searchDocumentAssets(query, { limit: page.limit + 1, offset: page.offset });
+                const hasMore = queried.length > page.limit;
+                const results = (hasMore ? queried.slice(0, page.limit) : queried).map(({ asset, matchedOn, score }) => ({
                     document: buildDocumentDescriptor(asset),
                     matchedOn,
                     score,
@@ -6295,6 +6418,13 @@ export function createTaskforceMcpServer(options = {}) {
                                 workspaceId: ACTIVE_WORKSPACE_ID,
                                 query: typeof query === 'string' ? query.trim() : '',
                                 results,
+                                pagination: {
+                                    offset: page.offset,
+                                    limit: page.limit,
+                                    returned: results.length,
+                                    hasMore,
+                                    ...(hasMore ? { nextOffset: page.offset + results.length } : {}),
+                                },
                                 guidance: results.length > 0
                                     ? 'After picking a match, call get_document with the suggestedArgs.documentId. Pass includeContent=true when you need the body.'
                                     : 'No matching canonical documents were found. Try a D-123 reference, document id, title keyword, or filename fragment.',