@taskforcehq/taskforce 0.3.306 → 0.3.307

package/dist/mcp/clientIntegrations.test.js

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { MCP_CLIENT_OPTIONS, buildCloudMcpClientIntegration, buildLocalMcpClientIntegration, buildCloudMcpServerId, } from './clientIntegrations';
+import { MCP_CLIENT_OPTIONS, buildCloudMcpClientIntegration, buildLocalMcpClientIntegration, buildCloudMcpServerId, buildLocalAiProfileEnv, } from './clientIntegrations';
 describe('clientIntegrations', () => {
     it('builds a readable cloud MCP server id from workspace name', () => {
         expect(buildCloudMcpServerId('Workspace Alpha', null)).toBe('taskforce-workspace-alpha');
@@ -78,7 +78,7 @@ describe('clientIntegrations', () => {
             aiProfileRole: 'Coding Agent',
             aiProfileProvider: 'OpenAI',
             aiProfileModel: 'Codex',
-            aiProfileSurfaceType: 'coding_tool',
+            aiProfileSurfaceType: 'cli',
         });
         const vscode = buildCloudMcpClientIntegration({
             clientId: 'vscode',
@@ -98,7 +98,7 @@ describe('clientIntegrations', () => {
         expect(codex.renderedText).toContain('X-Taskforce-AI-Role = "Coding Agent"');
         expect(codex.renderedText).toContain('X-Taskforce-AI-Provider = "OpenAI"');
         expect(codex.renderedText).toContain('X-Taskforce-AI-Model = "Codex"');
-        expect(codex.renderedText).toContain('X-Taskforce-AI-Surface-Type = "coding_tool"');
+        expect(codex.renderedText).toContain('X-Taskforce-AI-Surface-Type = "cli"');
         expect(codex.instructionText).toContain('Use the generated config exactly as shown.');
         expect(codex.instructionText).toContain('generated AI bootstrap headers');
         expect(vscode.serverConfig).toEqual({
@@ -180,6 +180,17 @@ describe('clientIntegrations', () => {
         expect(integration.renderedText).toContain('TASKFORCE_TENANT_ID = "tenant-alpha"');
         expect(integration.renderedText).not.toContain('Authorization');
     });
+    it('builds non-secret local AI profile env metadata for stdio clients', () => {
+        expect(buildLocalAiProfileEnv('codex')).toEqual({
+            TASKFORCE_AI_NAME: 'Codex',
+            TASKFORCE_AI_ICON: 'Bot',
+            TASKFORCE_AI_ROLE: 'Coding agent',
+            TASKFORCE_AI_PROVIDER: 'OpenAI',
+            TASKFORCE_AI_MODEL: 'Codex',
+            TASKFORCE_AI_SURFACE_TYPE: 'cli',
+        });
+        expect(buildLocalAiProfileEnv('codex')).not.toHaveProperty('TASKFORCE_AI_PROFILE_TOKEN');
+    });
     it('builds local VS Code config with stdio transport', () => {
         const integration = buildLocalMcpClientIntegration({
             clientId: 'vscode',

package/dist/mcp/clientProfileDefaults.js

@@ -7,15 +7,15 @@ const CLIENT_LABELS = {
 export function getDefaultAiProfileMetadataForClient(clientId) {
     switch (clientId) {
         case 'codex':
-            return { icon: 'Code2', color: '#10a37f', description: 'OpenAI Codex coding agent connected through MCP.', role: 'Coding Agent', provider: 'OpenAI', model: 'Codex', surfaceType: 'coding_tool' };
+            return { icon: 'Code2', color: '#10a37f', description: 'OpenAI Codex CLI coding agent connected through MCP.', role: 'CLI Coding Agent', provider: 'OpenAI', model: 'Codex', surfaceType: 'cli' };
         case 'chatgpt-desktop':
             return { icon: 'MessageSquare', color: '#10a37f', description: 'ChatGPT desktop app connected through the Taskforce MCP connector.', role: 'AI Assistant', provider: 'OpenAI', model: 'ChatGPT', surfaceType: 'chat_app' };
         case 'claude-code':
-            return { icon: 'Sparkles', color: '#d97706', description: 'Claude Code coding agent connected through MCP.', role: 'Coding Agent', provider: 'Anthropic', model: 'Claude Code', surfaceType: 'coding_tool' };
+            return { icon: 'Sparkles', color: '#d97706', description: 'Claude Code CLI coding agent connected through MCP.', role: 'CLI Coding Agent', provider: 'Anthropic', model: 'Claude Code', surfaceType: 'cli' };
         case 'claude-desktop':
             return { icon: 'MessageSquareMore', color: '#d97706', description: 'Claude Desktop connected through the Taskforce MCP connector.', role: 'AI Assistant', provider: 'Anthropic', model: 'Claude', surfaceType: 'chat_app' };
         case 'gemini-cli':
-            return { icon: 'Gem', color: '#2563eb', description: 'Gemini CLI coding agent connected through MCP.', role: 'Coding Agent', provider: 'Google', model: 'Gemini', surfaceType: 'coding_tool' };
+            return { icon: 'Gem', color: '#2563eb', description: 'Gemini CLI coding agent connected through MCP.', role: 'CLI Coding Agent', provider: 'Google', model: 'Gemini', surfaceType: 'cli' };
         case 'vscode':
             return { icon: 'Code2', color: '#2563eb', description: 'VS Code MCP-connected coding agent.', role: 'Coding Agent', provider: null, model: null, surfaceType: 'ide' };
         case 'cline':

package/dist/mcp/collaborationRegistrar.js

@@ -27,15 +27,15 @@ export function registerCollaborationTools(registerTool, executeTool) {
         inputSchema: { properties: {} },
     }));
     register('get_current_profile', (context) => ({
-        description: context.describeTool('Inspect the effective AI profile for this session. Use this when an agent needs to know its current profile id before filtering for tasks assigned to itself. If no profile is currently bound, this tool explains how to bootstrap with resolve_profile. You may also pass profileToken to inspect a stateless AI profile without mutating session state. The response includes the profileToken so automations can persist it after first bootstrap.'),
+        description: context.describeTool('Inspect the effective AI profile for this session. Use this when an agent needs to know its current profile id before filtering for tasks assigned to itself. If no profile is currently bound, this tool explains how to bootstrap with resolve_profile. You may also pass your own profileToken to inspect a stateless AI profile without mutating session state. The response includes your profileToken only for private agent/client storage; do not write it to repos, task comments, task attachments, logs, generated docs, or shared output.'),
         inputSchema: {
             properties: {
-                profileToken: stringProperty('Optional AI profile token to inspect when no profile is currently bound in session state.'),
+                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.'),
             },
         },
     }));
     register('resolve_profile', (context) => ({
-        description: context.describeTool('Resolve or create the current AI collaborator profile for this workspace. On first bootstrap, omit profileToken and Taskforce will create a named AI profile, issue a stable profileToken, and return the profile id to use in assignee, createdBy, and comment author fields on later calls. When a valid profileToken is provided, Taskforce resolves the existing profile and updates any supplied presentation fields such as name, icon, color, description, role, provider, model, and surfaceType. Update semantics: omitted optional fields leave existing stored values unchanged. For description, role, provider, and model, empty strings are ignored rather than clearing. For surfaceType, null or an empty string clears the stored value; valid enum values replace it.'),
+        description: context.describeTool('Resolve or create the current AI collaborator profile for this workspace. On first bootstrap, omit profileToken and Taskforce will create a named AI profile, issue a stable profileToken, and return the profile id to use in assignee, createdBy, and comment author fields on later calls. Store the returned profileToken only in private agent/client state and include it on future mutating calls when your MCP client does not preserve session identity. Never write profileToken values to repos, task comments, task attachments, logs, generated docs, or shared output. When a valid profileToken is provided, Taskforce resolves the existing profile and updates any supplied presentation fields such as name, icon, color, description, role, provider, model, and surfaceType. Update semantics: omitted optional fields leave existing stored values unchanged. For description, role, provider, and model, empty strings are ignored rather than clearing. For surfaceType, null or an empty string clears the stored value; valid enum values replace it.'),
         inputSchema: {
             properties: {
                 name: stringProperty('Display name for the AI collaborator.'),
@@ -50,9 +50,9 @@ export function registerCollaborationTools(registerTool, executeTool) {
                         { 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, coding_tool for the coding surface or terminal tool itself, chat_app for a conversational app identity, ide for an IDE-native copilot identity, and other only when none of those fit. If you are unsure and you are registering a named collaborator such as a teammate-style AI persona, choose agent. Omit to leave unchanged; pass null or an empty string to clear.',
+                    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.',
                 },
-                profileToken: stringProperty('Previously issued Taskforce profile token. When provided, Taskforce resolves the existing profile instead of creating a new one, and applies any supplied presentation field updates to that profile.'),
+                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.'),
             },
             required: ['name'],
         },
@@ -63,9 +63,9 @@ export function registerCollaborationTools(registerTool, executeTool) {
             properties: {
                 id: stringProperty('Task ID or task reference such as T-123.'),
                 text: stringProperty('Comment text.'),
-                author: stringProperty('Comment author identity. Use your AI profile id from resolve_profile, or use user for human-authored comments.'),
+                author: stringProperty('Optional comment author identity. Defaults to your resolved AI profile. Prefer stable actor IDs for overrides (`ai-profile-*`, workspace user IDs, `user`, `system`). Display names are not authoritative and may be canonicalized back to the bound actor; use `user` only for human-authored comments.'),
             },
-            required: ['id', 'text', 'author'],
+            required: ['id', 'text'],
         },
     }));
 }

package/dist/mcp/documentAssetRegistrar.js

@@ -35,8 +35,8 @@ 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.'),
             },
-            required: ['taskId'],
         },
     }));
     register('read_task_attachment', (context) => ({
@@ -50,6 +50,96 @@ export function registerDocumentAssetTools(registerTool, executeTool) {
             required: ['taskId', 'attachmentId'],
         },
     }));
+    register('get_workstream_attachments', (context) => ({
+        description: context.describeTool('List attachment descriptors for one workstream. This returns metadata only; use read_workstream_attachment for file contents.'),
+        inputSchema: {
+            properties: {
+                id: stringProperty('Workstream ID or workstream reference such as WS-123.'),
+            },
+            required: ['id'],
+        },
+    }));
+    register('read_workstream_attachment', (context) => ({
+        description: context.describeTool('Read one workstream attachment by attachmentId. Prefer this tool over opening attachment path URLs directly.'),
+        inputSchema: {
+            properties: {
+                workstreamId: stringProperty('Workstream ID or workstream reference such as WS-123.'),
+                attachmentId: stringProperty('Attachment descriptor id from get_workstream_attachments.'),
+                format: stringProperty('Read format. Use metadata for descriptors or download for a download URL.', ['text', 'metadata', 'download']),
+                maxChars: numberProperty('Optional max inline character count for readable text attachments.'),
+            },
+            required: ['workstreamId', 'attachmentId'],
+        },
+    }));
+    register('save_workstream_attachment', (context) => ({
+        description: context.describeTool('Save a file and attach it to a workstream. Use this for generated content or existing files from disk. Set overwrite=true to replace an existing canonical attachment with 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.'),
+                sourcePath: stringProperty('Path to an existing source file. Must be within project root, a Taskforce-managed attachment source, or an approved agent workspace root.'),
+                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.'),
+            },
+            required: ['id', 'filename'],
+        },
+    }));
+    register('delete_workstream_attachment', (context) => ({
+        description: context.describeTool('Delete one workstream attachment. Use get_workstream_attachments first to inspect attachment ids before removing one.'),
+        inputSchema: {
+            properties: {
+                workstreamId: stringProperty('Workstream ID or workstream reference such as WS-123.'),
+                attachmentId: stringProperty('Attachment descriptor id from get_workstream_attachments.'),
+            },
+            required: ['workstreamId', 'attachmentId'],
+        },
+    }));
+    register('get_initiative_attachments', (context) => ({
+        description: context.describeTool('List attachment descriptors for one initiative. This returns metadata only; use read_initiative_attachment for file contents.'),
+        inputSchema: {
+            properties: {
+                id: stringProperty('Initiative ID or initiative reference such as IN-123.'),
+            },
+            required: ['id'],
+        },
+    }));
+    register('read_initiative_attachment', (context) => ({
+        description: context.describeTool('Read one initiative attachment by attachmentId. Prefer this tool over opening attachment path URLs directly.'),
+        inputSchema: {
+            properties: {
+                initiativeId: stringProperty('Initiative ID or initiative reference such as IN-123.'),
+                attachmentId: stringProperty('Attachment descriptor id from get_initiative_attachments.'),
+                format: stringProperty('Read format. Use metadata for descriptors or download for a download URL.', ['text', 'metadata', 'download']),
+                maxChars: numberProperty('Optional max inline character count for readable text attachments.'),
+            },
+            required: ['initiativeId', 'attachmentId'],
+        },
+    }));
+    register('save_initiative_attachment', (context) => ({
+        description: context.describeTool('Save a file and attach it to an initiative. Use this for generated content or existing files from disk. Set overwrite=true to replace an existing canonical attachment with 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.'),
+                sourcePath: stringProperty('Path to an existing source file. Must be within project root, a Taskforce-managed attachment source, or an approved agent workspace root.'),
+                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.'),
+            },
+            required: ['id', 'filename'],
+        },
+    }));
+    register('delete_initiative_attachment', (context) => ({
+        description: context.describeTool('Delete one initiative attachment. Use get_initiative_attachments first to inspect attachment ids before removing one.'),
+        inputSchema: {
+            properties: {
+                initiativeId: stringProperty('Initiative ID or initiative reference such as IN-123.'),
+                attachmentId: stringProperty('Attachment descriptor id from get_initiative_attachments.'),
+            },
+            required: ['initiativeId', 'attachmentId'],
+        },
+    }));
     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.'),
         inputSchema: {
@@ -65,8 +155,8 @@ export function registerDocumentAssetTools(registerTool, executeTool) {
         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.'),
             },
-            required: ['id'],
         },
     }));
     register('search_documents', (context) => ({
@@ -84,8 +174,8 @@ export function registerDocumentAssetTools(registerTool, executeTool) {
         inputSchema: {
             properties: {
                 id: stringProperty('Document asset id or document reference such as D-123.'),
+                documentId: stringProperty('Alias for id. Document asset id or document reference such as D-123.'),
             },
-            required: ['id'],
         },
     }));
     register('read_document_content', (context) => ({
@@ -161,13 +251,14 @@ export function registerDocumentAssetTools(registerTool, executeTool) {
             properties: {
                 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.'),
                 text: stringProperty('Optional marker text or note.'),
+                instruction: stringProperty('Alias for text. Marker instruction or note.'),
             },
-            required: ['sessionId', 'type', 'x', 'y'],
         },
     }));
     register('bulk_add_annotated_attachment_markers', (context) => ({
@@ -179,13 +270,14 @@ export function registerDocumentAssetTools(registerTool, executeTool) {
                     type: 'object',
                     properties: {
                         type: { type: 'string' },
+                        kind: { type: 'string' },
                         x: { type: 'number' },
                         y: { type: 'number' },
                         width: { type: 'number' },
                         height: { type: 'number' },
                         text: { type: 'string' },
+                        instruction: { type: 'string' },
                     },
-                    required: ['type', 'x', 'y'],
                 }),
             },
             required: ['sessionId', 'markers'],
@@ -273,9 +365,19 @@ export function registerDocumentAssetTools(registerTool, executeTool) {
         inputSchema: {
             properties: {
                 documentId: stringProperty('Document asset id or document reference such as D-123.'),
+                id: stringProperty('Alias for documentId. Document asset id or document reference such as D-123.'),
+                sessionId: stringProperty('Optional existing review session id.'),
+                title: stringProperty('Optional review session title when a new session is created.'),
                 prompt: stringProperty('Review instructions or focus areas.'),
+                comments: arrayProperty('Explicit review comments to add. When omitted, prompt is saved as a single review comment.', {
+                    type: 'object',
+                    properties: {
+                        body: { type: 'string' },
+                        anchor: { type: 'object' },
+                    },
+                    required: ['body'],
+                }),
             },
-            required: ['documentId', 'prompt'],
         },
     }));
     register('add_document_review_comment', (context) => ({
@@ -320,13 +422,17 @@ export function registerDocumentAssetTools(registerTool, executeTool) {
         },
     }));
     register('save_task_attachment', (context) => ({
-        description: context.describeTool('Save a file and attach it to a task. Use this for generated content or existing files from disk. Set overwrite=true to replace an existing canonical attachment with the same filename. For AI-authored markdown/text, use inline content for AI-authored markdown/text rather than writing an external temp file first.'),
+        description: context.describeTool('Save a file and attach it to a task. Use this for generated content, existing files from disk, or staged remote uploads for binary files in cloud MCP. Set overwrite=true to replace an existing canonical attachment with the same filename. For AI-authored markdown/text, use inline content for AI-authored markdown/text rather than writing an external temp file first.'),
         inputSchema: {
             properties: {
                 id: stringProperty('Task ID or task reference such as T-123.'),
                 filename: stringProperty('Destination filename for the attachment.'),
                 content: stringProperty('Inline file content; use this for AI-authored markdown/text attachments.'),
                 sourcePath: stringProperty('Path to an existing source file. Must be within project root, a Taskforce-managed attachment source, or an approved agent workspace root.'),
+                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.'),
                 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.'),
             },

package/dist/mcp/runtime.d.ts

@@ -7,6 +7,7 @@ export interface TaskforceMcpServerOptions {
     projectRoot?: string;
     tenantId?: string;
     workspaceId?: string;
+    core?: TaskforceCore;
     serverName?: string;
     version?: string;
     logStartup?: boolean;