@taskforcehq/taskforce 0.3.305 → 0.3.307

package/dist/localization/locales/pt-BR.js

@@ -12,7 +12,6 @@ export const ptBR = {
         updatedLabel: 'Atualizado:',
         completedLabel: 'Concluido:',
         emptyValue: '—',
-        parentCannotSchedule: 'Tarefas pai nao podem ser agendadas. Agende as tarefas folha.',
         dueBeforeScheduled: 'A data de vencimento e anterior a data agendada.',
         overdue: 'Esta tarefa esta atrasada.'
     },

package/dist/mcp/canonicalAssetHelpers.d.ts

@@ -1,4 +1,4 @@
-import type { WorkspaceAssetEntry, WorkspaceAssetKind, WorkspaceAssetLinkRole, WorkspaceAssetScanStatus, WorkspaceAssetStore } from '../storage/workspaceAssetStore.js';
+import type { WorkspaceAssetEntry, WorkspaceAssetKind, WorkspaceAssetLinkRole, WorkspaceAssetLinkTargetType, WorkspaceAssetScanStatus, WorkspaceAssetStore } from '../storage/workspaceAssetStore.js';
 import type { McpTaskAttachmentDescriptor, TaskAttachmentRecord } from './taskAttachmentTypes.js';
 export interface CanonicalAssetHelpersDeps {
     activeWorkspaceId: string;
@@ -9,6 +9,7 @@ export interface CanonicalAssetHelpersDeps {
         getObject(storageKey: string): Promise<{
             body: Buffer;
         } | null>;
+        putObject?(storageKey: string, body: Buffer, contentType: string): Promise<void>;
     } | null;
     sanitizeFilenameForPath: (filenameRaw: unknown, fallback?: string) => string;
     sanitizeDisplayName: (valueRaw: unknown, fallback: string) => string;
@@ -31,7 +32,7 @@ export declare function createCanonicalAssetHelpers(deps: CanonicalAssetHelpersD
     getAttachmentAssetRecord: (attachment: TaskAttachmentRecord) => WorkspaceAssetEntry | null;
     buildAttachmentDownloadUrl: (attachment: McpTaskAttachmentDescriptor) => string;
     buildDocumentDownloadUrl: (asset: WorkspaceAssetEntry) => string;
-    readCanonicalAttachmentBuffer: (taskId: string, attachment: McpTaskAttachmentDescriptor) => Promise<Buffer>;
+    readCanonicalAttachmentBuffer: (taskId: string, attachment: McpTaskAttachmentDescriptor, targetLabel?: string) => Promise<Buffer>;
     readCanonicalDocumentBuffer: (asset: WorkspaceAssetEntry) => Promise<Buffer>;
     toTaskAttachmentRecord: (attachment: string | TaskAttachmentRecord) => TaskAttachmentRecord;
     resolveAttachmentLogicalFilename: (attachmentInput: string | TaskAttachmentRecord, assetOverride?: ReturnType<(attachment: TaskAttachmentRecord) => WorkspaceAssetEntry | null> | null) => string;
@@ -47,7 +48,7 @@ export declare function createCanonicalAssetHelpers(deps: CanonicalAssetHelpersD
         absolutePath: string;
         logicalFilename: string;
     };
-    ensureCanonicalTaskAttachment: (relativePathRaw: string, taskIdRaw: string, captionRaw: string | undefined, timestampRaw: string | undefined, role: WorkspaceAssetLinkRole, options?: {
+    ensureCanonicalAttachment: (relativePathRaw: string, targetTypeRaw: WorkspaceAssetLinkTargetType, targetIdRaw: string, captionRaw: string | undefined, timestampRaw: string | undefined, role: WorkspaceAssetLinkRole, options?: {
         originalFilename?: string;
         logicalName?: string;
         assetId?: string;
@@ -57,7 +58,18 @@ export declare function createCanonicalAssetHelpers(deps: CanonicalAssetHelpersD
         scanStatus?: WorkspaceAssetScanStatus;
         scanEngine?: string | null;
         scanDetails?: string | null;
-    }) => WorkspaceAssetEntry | null;
+    }) => 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;
+        logicalName?: string;
+        assetId?: string;
+        documentId?: string | null;
+        createdAt?: string;
+        createdByUserId?: string | null;
+        scanStatus?: WorkspaceAssetScanStatus;
+        scanEngine?: string | null;
+        scanDetails?: string | null;
+    }) => Promise<WorkspaceAssetEntry | null>>[6]) => Promise<WorkspaceAssetEntry | null>;
     buildCanonicalWorkspaceAssetRelativePath: (params: {
         workspaceIdRaw: unknown;
         kind: WorkspaceAssetKind;

package/dist/mcp/canonicalAssetHelpers.js

@@ -65,13 +65,13 @@ export function createCanonicalAssetHelpers(deps) {
         ];
         return parts.join(', ');
     };
-    const readCanonicalAttachmentBuffer = async (taskId, attachment) => {
+    const readCanonicalAttachmentBuffer = async (taskId, attachment, targetLabel = 'task') => {
         const assetId = String(attachment.assetId || '').trim();
         const asset = assetId && deps.workspaceAssetStore
             ? deps.workspaceAssetStore.get(assetId, deps.activeWorkspaceId)
             : null;
         if (!asset || asset.deletedAt) {
-            throw new Error(`Attachment ${attachment.attachmentId} not found on task ${taskId}`);
+            throw new Error(`Attachment ${attachment.attachmentId} not found on ${targetLabel} ${taskId}`);
         }
         if (asset.scanStatus === 'infected') {
             throw new Error('Attachment is quarantined');
@@ -93,16 +93,16 @@ export function createCanonicalAssetHelpers(deps) {
                 throw new Error(`Attachment read failed from R2 (${attachmentContext}): ${message || 'Unknown object storage error'}`);
             }
             if (!object) {
-                throw new Error(`Attachment ${attachment.attachmentId} not found on task ${taskId}`);
+                throw new Error(`Attachment ${attachment.attachmentId} not found on ${targetLabel} ${taskId}`);
             }
             return object.body;
         }
         const resolvedPath = path.resolve(deps.basePath, asset.storageKey);
         if (!resolvedPath.startsWith(path.resolve(deps.basePath))) {
-            throw new Error(`Attachment ${attachment.attachmentId} not found on task ${taskId}`);
+            throw new Error(`Attachment ${attachment.attachmentId} not found on ${targetLabel} ${taskId}`);
         }
         if (!fs.existsSync(resolvedPath) || !fs.statSync(resolvedPath).isFile()) {
-            throw new Error(`Attachment ${attachment.attachmentId} not found on task ${taskId}`);
+            throw new Error(`Attachment ${attachment.attachmentId} not found on ${targetLabel} ${taskId}`);
         }
         return fs.readFileSync(resolvedPath);
     };
@@ -189,12 +189,13 @@ export function createCanonicalAssetHelpers(deps) {
         }
         return null;
     };
-    const ensureCanonicalTaskAttachment = (relativePathRaw, taskIdRaw, captionRaw, timestampRaw, role, options) => {
+    const ensureCanonicalAttachment = async (relativePathRaw, targetTypeRaw, targetIdRaw, captionRaw, timestampRaw, role, options) => {
         if (!deps.workspaceAssetStore)
             return null;
         const relativePath = String(relativePathRaw || '').trim();
-        const taskId = String(taskIdRaw || '').trim();
-        if (!relativePath || !taskId)
+        const targetType = String(targetTypeRaw || 'task').trim();
+        const targetId = String(targetIdRaw || '').trim();
+        if (!relativePath || !targetId)
             return null;
         const absolutePath = path.resolve(deps.projectRoot, relativePath);
         if (!fs.existsSync(absolutePath) || !fs.statSync(absolutePath).isFile())
@@ -206,6 +207,10 @@ export function createCanonicalAssetHelpers(deps) {
         const kind = deps.inferAssetKind(relativePath, mimeType);
         const timestamp = String(timestampRaw || new Date().toISOString()).trim() || new Date().toISOString();
         const existing = deps.workspaceAssetStore.getByStorageKey(storageKey, deps.activeWorkspaceId);
+        const shouldPersistToObjectStorage = typeof deps.objectStorageClient?.putObject === 'function';
+        if (shouldPersistToObjectStorage) {
+            await deps.objectStorageClient.putObject(storageKey, buffer, mimeType || 'application/octet-stream');
+        }
         const originalFilename = deps.sanitizeFilenameForPath(options?.originalFilename || existing?.originalFilename || path.basename(relativePath));
         const logicalName = deps.sanitizeDisplayName(options?.logicalName || existing?.logicalName || originalFilename, originalFilename);
         const asset = deps.workspaceAssetStore.upsertAsset({
@@ -215,7 +220,7 @@ export function createCanonicalAssetHelpers(deps) {
             logicalName,
             originalFilename,
             mimeType,
-            storageProvider: 'local',
+            storageProvider: shouldPersistToObjectStorage ? 'r2' : 'local',
             storageKey,
             contentSha256: createHash('sha256').update(buffer).digest('hex'),
             sizeBytes: stats.size,
@@ -234,7 +239,8 @@ export function createCanonicalAssetHelpers(deps) {
         deps.workspaceAssetStore.upsertLink({
             workspaceId: deps.activeWorkspaceId,
             assetId: asset.assetId,
-            taskId,
+            targetType,
+            targetId,
             role,
             displayName: kind === 'document' ? null : (captionRaw || null),
             updatedAt: timestamp,
@@ -242,6 +248,7 @@ export function createCanonicalAssetHelpers(deps) {
         });
         return asset;
     };
+    const ensureCanonicalTaskAttachment = (relativePathRaw, taskIdRaw, captionRaw, timestampRaw, role, options) => ensureCanonicalAttachment(relativePathRaw, 'task', taskIdRaw, captionRaw, timestampRaw, role, options);
     return {
         normalizeAttachmentStorageKey,
         buildSyntheticAttachmentId,
@@ -253,6 +260,7 @@ export function createCanonicalAssetHelpers(deps) {
         toTaskAttachmentRecord,
         resolveAttachmentLogicalFilename,
         resolveCanonicalOverwriteTarget,
+        ensureCanonicalAttachment,
         ensureCanonicalTaskAttachment,
         buildCanonicalWorkspaceAssetRelativePath: deps.buildCanonicalWorkspaceAssetRelativePath,
     };

package/dist/mcp/canonicalAssetHelpers.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/mcp/canonicalAssetHelpers.test.js

@@ -0,0 +1,67 @@
+import { describe, expect, it, vi } from 'vitest';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { TaskforceCore } from '../core/Taskforce';
+import { createCanonicalAssetHelpers } from './canonicalAssetHelpers';
+function makeCore() {
+    const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'taskforce-mcp-canonical-assets-'));
+    const core = new TaskforceCore({
+        projectRoot,
+        storagePath: path.join(projectRoot, '.taskforce')
+    });
+    return {
+        projectRoot,
+        core,
+        cleanup: () => fs.rmSync(projectRoot, { recursive: true, force: true })
+    };
+}
+describe('MCP canonical asset helpers', () => {
+    it('uploads canonical attachments to object storage before recording durable cloud metadata', async () => {
+        const { projectRoot, core, cleanup } = makeCore();
+        try {
+            core.createWorkspace({ workspaceId: 'workspace-1', name: 'Workspace 1' });
+            const task = core.createTask({ title: 'Object-backed attachment' }, { workspaceId: 'workspace-1' });
+            const relativePath = '.taskforce/workspaces/workspace-1/assets/documents/asset-test-note.md';
+            const absolutePath = path.join(projectRoot, relativePath);
+            fs.mkdirSync(path.dirname(absolutePath), { recursive: true });
+            fs.writeFileSync(absolutePath, '# Stored in object storage\n', 'utf8');
+            const putObject = vi.fn(async () => { });
+            const helpers = createCanonicalAssetHelpers({
+                activeWorkspaceId: 'workspace-1',
+                projectRoot,
+                basePath: core.getPaths().basePath,
+                workspaceAssetStore: core.getWorkspaceAssetStore(),
+                objectStorageClient: {
+                    getObject: vi.fn(async () => null),
+                    putObject,
+                },
+                sanitizeFilenameForPath: (value, fallback = 'file.txt') => String(value || fallback).trim() || fallback,
+                sanitizeDisplayName: (value, fallback) => String(value || fallback).trim() || fallback,
+                toPosixPath: (value) => value.replace(/\\/g, '/'),
+                inferMimeTypeFromPath: (value) => value.endsWith('.md') ? 'text/markdown' : 'application/octet-stream',
+                inferAssetKind: (value, mimeType) => (value.endsWith('.md') || mimeType === 'text/markdown' ? 'document' : 'file'),
+                buildCanonicalWorkspaceAssetRelativePath: () => ({
+                    assetId: 'asset-test-note',
+                    relativePath: 'workspaces/workspace-1/assets/documents/asset-test-note.md'
+                })
+            });
+            const asset = await helpers.ensureCanonicalTaskAttachment(relativePath, task.id, 'note.md', '2026-04-27T01:00:00.000Z', 'attachment', { originalFilename: 'note.md', logicalName: 'note.md' });
+            expect(putObject).toHaveBeenCalledWith('workspaces/workspace-1/assets/documents/asset-test-note.md', Buffer.from('# Stored in object storage\n', 'utf8'), 'text/markdown');
+            expect(asset?.storageProvider).toBe('r2');
+            expect(core.getWorkspaceAssetStore().get(asset.assetId, 'workspace-1')?.storageProvider).toBe('r2');
+            expect(core.getWorkspaceAssetStore().listLinksForTask(task.id, 'workspace-1')).toEqual(expect.arrayContaining([
+                expect.objectContaining({
+                    assetId: asset?.assetId,
+                    targetType: 'task',
+                    role: 'attachment',
+                    deletedAt: null,
+                })
+            ]));
+        }
+        finally {
+            core.close();
+            cleanup();
+        }
+    });
+});

package/dist/mcp/clientIntegrations.d.ts

@@ -31,6 +31,7 @@ export interface CloudMcpClientIntegration {
     serverConfig?: unknown;
     renderedText?: string;
 }
+export declare function buildLocalAiProfileEnv(clientId: McpClientId): Record<string, string>;
 export declare const MCP_CLIENT_OPTIONS: McpClientOption[];
 export declare function sanitizeMcpId(value: string, fallback: string): string;
 export declare function buildCloudMcpServerId(workspaceName?: string | null, projectName?: string | null): string;

package/dist/mcp/clientIntegrations.js

@@ -1,4 +1,29 @@
 import { buildAiProfileBootstrapHeaders } from './aiProfileBootstrap.js';
+const LOCAL_AI_PROFILE_DEFAULTS = {
+    general: { name: 'Taskforce MCP Agent', icon: 'Bot', role: 'AI collaborator', provider: 'MCP client', model: 'Local MCP', surfaceType: 'agent' },
+    cursor: { name: 'Cursor', icon: 'Bot', role: 'IDE coding assistant', provider: 'Cursor', model: 'Cursor', surfaceType: 'ide' },
+    cline: { name: 'Cline', icon: 'Bot', role: 'IDE coding assistant', provider: 'Cline', model: 'Cline', surfaceType: 'ide' },
+    vscode: { name: 'VS Code Copilot', icon: 'Bot', role: 'IDE coding assistant', provider: 'Microsoft', model: 'Copilot', surfaceType: 'ide' },
+    windsurf: { name: 'Windsurf', icon: 'Bot', role: 'IDE coding assistant', provider: 'Windsurf', model: 'Windsurf', surfaceType: 'ide' },
+    antigravity: { name: 'Antigravity', icon: 'Bot', role: 'Coding agent', provider: 'Google', model: 'Antigravity', surfaceType: 'coding_tool' },
+    openclaw: { name: 'OpenClaw', icon: 'Bot', role: 'AI agent', provider: 'OpenClaw', model: 'OpenClaw', surfaceType: 'agent' },
+    codex: { name: 'Codex', icon: 'Bot', role: 'Coding agent', provider: 'OpenAI', model: 'Codex', surfaceType: 'cli' },
+    'claude-code': { name: 'Claude Code', icon: 'Bot', role: 'Coding agent', provider: 'Anthropic', model: 'Claude Code', surfaceType: 'cli' },
+    'gemini-cli': { name: 'Gemini CLI', icon: 'Bot', role: 'Coding agent', provider: 'Google', model: 'Gemini CLI', surfaceType: 'cli' },
+    'claude-desktop': { name: 'Claude Desktop', icon: 'Bot', role: 'Desktop AI collaborator', provider: 'Anthropic', model: 'Claude Desktop', surfaceType: 'chat_app' },
+    'chatgpt-desktop': { name: 'ChatGPT Desktop', icon: 'Bot', role: 'Desktop AI collaborator', provider: 'OpenAI', model: 'ChatGPT Desktop', surfaceType: 'chat_app' },
+};
+export function buildLocalAiProfileEnv(clientId) {
+    const defaults = LOCAL_AI_PROFILE_DEFAULTS[clientId] || LOCAL_AI_PROFILE_DEFAULTS.general;
+    return {
+        TASKFORCE_AI_NAME: defaults.name,
+        TASKFORCE_AI_ICON: defaults.icon,
+        TASKFORCE_AI_ROLE: defaults.role,
+        TASKFORCE_AI_PROVIDER: defaults.provider,
+        TASKFORCE_AI_MODEL: defaults.model,
+        TASKFORCE_AI_SURFACE_TYPE: defaults.surfaceType,
+    };
+}
 export const MCP_CLIENT_OPTIONS = [
     { id: 'general', label: 'General' },
     { id: 'antigravity', label: 'Antigravity' },

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: {
@@ -61,12 +151,12 @@ export function registerDocumentAssetTools(registerTool, executeTool) {
         },
     }));
     register('get_image', (context) => ({
-        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_annotated_attachment_sessions and read_annotated_attachment_payload for annotation details.'),
+        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_annotated_attachment_sessions and read_annotated_attachment_payload for annotation details. 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.'),
             },
-            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) => ({
@@ -99,7 +189,7 @@ export function registerDocumentAssetTools(registerTool, executeTool) {
         },
     }));
     register('get_annotated_attachment_sessions', (context) => ({
-        description: context.describeTool('List saved annotation sessions for one image. Use this after get_image when you need the saved annotation sessions before opening one payload.'),
+        description: context.describeTool('List saved annotation sessions for one image. Use this after get_image when you need the saved annotation sessions before opening one payload. If the user is pointing at a visual target in I-123, do not stop at the screenshot alone; inspect the saved session payload next.'),
         inputSchema: {
             properties: {
                 imageId: stringProperty('Image asset id or image reference such as I-123.'),
@@ -108,7 +198,7 @@ export function registerDocumentAssetTools(registerTool, executeTool) {
         },
     }));
     register('read_annotated_attachment_payload', (context) => ({
-        description: context.describeTool('Read the structured payload for one annotated attachment session, including markers, geometry, and derived crop hints.'),
+        description: context.describeTool('Read the structured payload for one annotated attachment session, including markers, geometry, and derived crop hints. Use this as the authoritative instruction source when I-123 is being used for UI placement or visual change requests.'),
         inputSchema: {
             properties: {
                 sessionId: stringProperty('Annotated attachment session id.'),
@@ -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

@@ -2,10 +2,12 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { McpAccessTokenScope, TaskforceCore } from '../core/Taskforce.js';
 import { type AiProfileBootstrapConfig } from './aiProfileBootstrap.js';
+import { type AiProfileSeatScope } from '../shared/aiProfileSeatScope.js';
 export interface TaskforceMcpServerOptions {
     projectRoot?: string;
     tenantId?: string;
     workspaceId?: string;
+    core?: TaskforceCore;
     serverName?: string;
     version?: string;
     logStartup?: boolean;
@@ -23,6 +25,7 @@ export interface TaskforceMcpServerOptions {
         aiProfileProvider?: AiProfileBootstrapConfig['aiProfileProvider'];
         aiProfileModel?: AiProfileBootstrapConfig['aiProfileModel'];
         aiProfileSurfaceType?: AiProfileBootstrapConfig['aiProfileSurfaceType'];
+        aiProfileSeatScope?: AiProfileSeatScope | null;
         actorType?: 'local' | 'user' | 'token' | 'oauth';
         requestId?: string | null;
         ip?: string | null;