@taskforcehq/taskforce 0.3.326 → 0.3.327

package/dist/mcp/localServiceProxy.js

@@ -0,0 +1,255 @@
+import { randomUUID } from 'crypto';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { JSONRPCMessageSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { normalizeMcpConnectionId, parseMcpClientId } from './clientRegistry.js';
+import { normalizeMcpToolProfile } from './toolProfiles.js';
+import { discoverOrStartLocalService, LOCAL_SERVICE_API_BASE_PATH, LOCAL_SERVICE_PROTOCOL_VERSION, } from '../service/localServiceClientLifecycle.js';
+const REQUEST_TIMEOUT_MS = 120_000;
+const MAX_IN_FLIGHT = 32;
+const MCP_PROTOCOL_ERROR = -32_000;
+const MCP_REQUEST_CANCELLED = -32_800;
+function timeoutSignal(timeoutMs = REQUEST_TIMEOUT_MS) {
+    return AbortSignal.timeout(timeoutMs);
+}
+async function readJson(response, label) {
+    const text = await response.text();
+    if (!response.ok) {
+        throw new Error(`${label} failed (${response.status}): ${text.slice(0, 500)}`);
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new Error(`${label} returned invalid JSON.`);
+    }
+}
+function validateReadiness(readiness, descriptor) {
+    if (!readiness.ready)
+        throw new Error('Taskforce shared local service is not accepting new work.');
+    if (readiness.protocolVersion !== LOCAL_SERVICE_PROTOCOL_VERSION
+        || readiness.protocolVersion !== descriptor.protocolVersion
+        || readiness.generation !== descriptor.generation
+        || readiness.pid !== descriptor.pid
+        || readiness.endpoint !== descriptor.endpoint
+        || readiness.dataIdentity !== descriptor.ownershipKey) {
+        throw new Error('Taskforce shared local service readiness does not match its descriptor.');
+    }
+}
+function requestId(message) {
+    return 'id' in message && (typeof message.id === 'string' || typeof message.id === 'number')
+        ? message.id
+        : null;
+}
+function cancellationTarget(message) {
+    if (!('method' in message) || message.method !== 'notifications/cancelled')
+        return null;
+    const value = message.params?.requestId;
+    return typeof value === 'string' || typeof value === 'number' ? value : null;
+}
+function idKey(id) {
+    return `${typeof id}:${String(id)}`;
+}
+function errorResponse(id, message, code, numericCode = MCP_PROTOCOL_ERROR) {
+    return {
+        jsonrpc: '2.0',
+        id,
+        error: { code: numericCode, message, data: { code } },
+    };
+}
+export async function startLocalServiceMcpProxy(options) {
+    const env = options.env || process.env;
+    const configuredSharedService = String(env.TASKFORCE_SHARED_LOCAL_MCP_ENABLED || '').trim();
+    if (configuredSharedService && !/^(1|true|yes|on)$/i.test(configuredSharedService)) {
+        throw new Error('Shared local MCP service is disabled. Set TASKFORCE_SHARED_LOCAL_MCP_ENABLED=true to use proxy mode.');
+    }
+    const rawClientId = String(env.TASKFORCE_MCP_CLIENT_ID || '').trim();
+    const clientId = rawClientId ? parseMcpClientId(rawClientId) : 'general';
+    if (!clientId)
+        throw new Error(`Unsupported TASKFORCE_MCP_CLIENT_ID: ${rawClientId}`);
+    const configuredWorkspaceId = String(env.TASKFORCE_WORKSPACE_ID || '').trim();
+    const workspaceId = configuredWorkspaceId && configuredWorkspaceId.toLowerCase() !== 'default'
+        ? configuredWorkspaceId
+        : undefined;
+    const rawToolProfile = String(env.TASKFORCE_MCP_TOOL_PROFILE || '').trim();
+    const toolProfile = normalizeMcpToolProfile(rawToolProfile, 'full');
+    if (rawToolProfile && toolProfile !== rawToolProfile.toLowerCase()) {
+        throw new Error(`Unsupported TASKFORCE_MCP_TOOL_PROFILE: ${rawToolProfile}`);
+    }
+    const configuredConnection = normalizeMcpConnectionId(env.TASKFORCE_MCP_CONNECTION_ID);
+    if (env.TASKFORCE_MCP_CONNECTION_ID && !configuredConnection) {
+        throw new Error('TASKFORCE_MCP_CONNECTION_ID is invalid.');
+    }
+    const connectionInstance = options.connectionInstance
+        || `${configuredConnection || 'stdio'}:${process.pid}:${randomUUID()}`;
+    const maxInFlight = options.maxInFlight ?? MAX_IN_FLIGHT;
+    if (!Number.isInteger(maxInFlight) || maxInFlight < 1)
+        throw new Error('Local MCP proxy maxInFlight must be a positive integer.');
+    const requestTimeoutMs = options.requestTimeoutMs ?? REQUEST_TIMEOUT_MS;
+    if (!Number.isFinite(requestTimeoutMs) || requestTimeoutMs < 1)
+        throw new Error('Local MCP proxy requestTimeoutMs must be positive.');
+    const fetchFn = options.fetch || fetch;
+    const descriptor = await (options.discover || discoverOrStartLocalService)({
+        projectRoot: options.projectRoot,
+        env,
+        executablePath: options.executablePath,
+        cliEntryPath: options.cliEntryPath,
+        execArgv: options.execArgv,
+    });
+    const readiness = await readJson(await fetchFn(`${descriptor.endpoint}${LOCAL_SERVICE_API_BASE_PATH}/readiness`, { signal: timeoutSignal() }), 'Local service readiness');
+    validateReadiness(readiness, descriptor);
+    const registration = await readJson(await fetchFn(`${descriptor.endpoint}${LOCAL_SERVICE_API_BASE_PATH}/sessions`, {
+        method: 'POST',
+        headers: {
+            'content-type': 'application/json',
+            'x-taskforce-local-service-capability': descriptor.bootstrapCapability,
+        },
+        body: JSON.stringify({
+            clientId,
+            connectionInstance,
+            workspaceId,
+            permissions: ['tasks:read', 'tasks:write', 'workspace:read'],
+            toolProfile,
+            protocolVersion: descriptor.protocolVersion,
+            generation: descriptor.generation,
+            profileToken: String(env.TASKFORCE_AI_PROFILE_TOKEN || '').trim() || undefined,
+        }),
+        signal: timeoutSignal(),
+    }), 'Local service session registration');
+    if (!registration.session?.id || !registration.bearerToken) {
+        throw new Error('Local service session registration returned an invalid response.');
+    }
+    const stdio = new StdioServerTransport(options.stdin, options.stdout);
+    const requests = new Map();
+    const inFlight = new Set();
+    let protocolVersion = null;
+    let initializeRequestId = null;
+    let terminal = false;
+    let closePromise = null;
+    let sendChain = Promise.resolve();
+    const send = (message) => {
+        sendChain = sendChain.then(() => stdio.send(message));
+        return sendChain;
+    };
+    const failTerminal = async (error, id) => {
+        if (terminal)
+            return;
+        terminal = true;
+        for (const pending of inFlight)
+            pending.controller.abort();
+        if (id !== null) {
+            await send(errorResponse(id, 'Taskforce shared local service connection failed.', 'LOCAL_SERVICE_UNAVAILABLE'));
+        }
+        else {
+            (options.logError || console.error)(`[Taskforce MCP proxy] ${error.message}`);
+        }
+        options.onFatal?.(error);
+    };
+    const forward = async (message) => {
+        const id = requestId(message);
+        if (terminal) {
+            if (id !== null)
+                await send(errorResponse(id, 'Taskforce MCP proxy is closed.', 'PROXY_CLOSED'));
+            return;
+        }
+        const cancelId = cancellationTarget(message);
+        let cancelCorrelation = null;
+        if (cancelId !== null) {
+            const pending = requests.get(idKey(cancelId));
+            if (pending) {
+                cancelCorrelation = pending.correlationId;
+                pending.cancelled = true;
+                pending.controller.abort();
+            }
+        }
+        if (inFlight.size >= maxInFlight && cancelId === null) {
+            if (id !== null)
+                await send(errorResponse(id, 'Taskforce MCP proxy is at its in-flight request limit.', 'PROXY_OVERLOADED'));
+            else
+                (options.logError || console.error)('[Taskforce MCP proxy] Dropped notification at the in-flight limit.');
+            return;
+        }
+        const controller = new AbortController();
+        const key = id === null ? null : idKey(id);
+        const state = { controller, cancelled: false, correlationId: randomUUID() };
+        const requestTimer = setTimeout(() => controller.abort(), requestTimeoutMs);
+        requestTimer.unref?.();
+        inFlight.add(state);
+        if (key)
+            requests.set(key, state);
+        if ('method' in message && message.method === 'initialize' && id !== null)
+            initializeRequestId = id;
+        try {
+            const response = await fetchFn(`${descriptor.endpoint}/mcp`, {
+                method: 'POST',
+                headers: {
+                    authorization: `Bearer ${registration.bearerToken}`,
+                    'content-type': 'application/json',
+                    accept: 'application/json, text/event-stream',
+                    ...(protocolVersion ? { 'mcp-protocol-version': protocolVersion } : {}),
+                    'x-taskforce-mcp-request-correlation': state.correlationId,
+                    ...(cancelCorrelation ? { 'x-taskforce-mcp-cancel-correlation': cancelCorrelation } : {}),
+                },
+                body: JSON.stringify(message),
+                signal: controller.signal,
+            });
+            if (response.status === 202) {
+                await response.body?.cancel();
+                return;
+            }
+            const body = await readJson(response, 'MCP relay');
+            const messages = (Array.isArray(body) ? body : [body]).map((value) => JSONRPCMessageSchema.parse(value));
+            for (const responseMessage of messages) {
+                if (initializeRequestId !== null
+                    && requestId(responseMessage) === initializeRequestId
+                    && 'result' in responseMessage
+                    && typeof responseMessage.result?.protocolVersion === 'string') {
+                    protocolVersion = responseMessage.result.protocolVersion;
+                }
+                await send(responseMessage);
+            }
+        }
+        catch (error) {
+            if (state.cancelled && id !== null) {
+                await send(errorResponse(id, 'Client stopped waiting; the operation may still complete.', 'REQUEST_CANCELLED_ADVISORY', MCP_REQUEST_CANCELLED));
+                return;
+            }
+            await failTerminal(error instanceof Error ? error : new Error(String(error)), id);
+        }
+        finally {
+            clearTimeout(requestTimer);
+            inFlight.delete(state);
+            if (key)
+                requests.delete(key);
+        }
+    };
+    stdio.onmessage = (message) => { void forward(message); };
+    stdio.onerror = (error) => { void failTerminal(error, null); };
+    try {
+        await stdio.start();
+    }
+    catch (error) {
+        await fetchFn(`${descriptor.endpoint}${LOCAL_SERVICE_API_BASE_PATH}/sessions/${encodeURIComponent(registration.session.id)}`, {
+            method: 'DELETE',
+            headers: { authorization: `Bearer ${registration.bearerToken}` },
+            signal: timeoutSignal(2_000),
+        }).then((response) => response.body?.cancel()).catch(() => undefined);
+        throw error;
+    }
+    const close = () => {
+        if (closePromise)
+            return closePromise;
+        terminal = true;
+        closePromise = (async () => {
+            for (const pending of inFlight)
+                pending.controller.abort();
+            await stdio.close().catch(() => undefined);
+            await fetchFn(`${descriptor.endpoint}${LOCAL_SERVICE_API_BASE_PATH}/sessions/${encodeURIComponent(registration.session.id)}`, {
+                method: 'DELETE',
+                headers: { authorization: `Bearer ${registration.bearerToken}` },
+                signal: timeoutSignal(2_000),
+            }).then((response) => response.body?.cancel()).catch(() => undefined);
+        })();
+        return closePromise;
+    };
+    return { close, sessionId: registration.session.id };
+}

package/dist/mcp/mcpInputValidator.d.ts

@@ -0,0 +1,17 @@
+import type { McpToolInputSchema } from './toolCatalog.js';
+export type McpInputValidationIssue = {
+    instancePath: string;
+    keyword: string;
+    message: string;
+    params?: Record<string, unknown>;
+};
+export type McpInputValidationResult = {
+    valid: true;
+} | {
+    valid: false;
+    issues: McpInputValidationIssue[];
+};
+export declare function createMcpInputValidator(): {
+    validate(toolName: string, schema: McpToolInputSchema, input: unknown): McpInputValidationResult;
+    cacheSize(): number;
+};

package/dist/mcp/mcpInputValidator.js

@@ -0,0 +1,58 @@
+import Ajv from 'ajv';
+import { createHash } from 'node:crypto';
+const MAX_VALIDATION_ISSUES = 8;
+function schemaFingerprint(schema) {
+    return createHash('sha256').update(JSON.stringify(schema)).digest('hex');
+}
+function safeErrorParams(error) {
+    if (error.keyword === 'required' && typeof error.params.missingProperty === 'string') {
+        return { missingProperty: error.params.missingProperty };
+    }
+    if (error.keyword === 'type' && typeof error.params.type === 'string') {
+        return { type: error.params.type };
+    }
+    if (error.keyword === 'enum' && Array.isArray(error.params.allowedValues)) {
+        return { allowedValues: error.params.allowedValues.slice(0, 20) };
+    }
+    return undefined;
+}
+function formatValidationIssues(errors) {
+    return (errors || []).slice(0, MAX_VALIDATION_ISSUES).map((error) => ({
+        instancePath: error.instancePath || '/',
+        keyword: error.keyword,
+        message: error.message || 'does not match the declared schema',
+        ...(safeErrorParams(error) ? { params: safeErrorParams(error) } : {}),
+    }));
+}
+export function createMcpInputValidator() {
+    const ajv = new Ajv({
+        allErrors: true,
+        coerceTypes: false,
+        useDefaults: false,
+        removeAdditional: false,
+        strict: false,
+    });
+    const cache = new Map();
+    return {
+        validate(toolName, schema, input) {
+            const fingerprint = schemaFingerprint(schema);
+            let cached = cache.get(toolName);
+            if (!cached || cached.fingerprint !== fingerprint) {
+                cached = {
+                    fingerprint,
+                    validate: ajv.compile(schema),
+                };
+                cache.set(toolName, cached);
+            }
+            if (cached.validate(input))
+                return { valid: true };
+            return {
+                valid: false,
+                issues: formatValidationIssues(cached.validate.errors),
+            };
+        },
+        cacheSize() {
+            return cache.size;
+        },
+    };
+}

package/dist/mcp/planningAttachmentCommandAdapter.d.ts

@@ -0,0 +1,127 @@
+import type { WorkspaceAssetEntry, WorkspaceAssetKind, WorkspaceAssetLinkEntry, WorkspaceAssetLinkRole, WorkspaceAssetScanStatus, WorkspaceDocumentEntry } from '../storage/workspaceAssetStore.js';
+import type { McpTaskAttachmentDescriptor, TaskAttachmentRecord } from './taskAttachmentTypes.js';
+export type PlanningAttachmentTargetType = 'initiative' | 'workstream';
+export interface PlanningAttachmentTarget {
+    type: PlanningAttachmentTargetType;
+    id: string;
+    entity: {
+        attachments?: Array<string | TaskAttachmentRecord> | null;
+        [key: string]: unknown;
+    };
+    referenceLabel: string | null;
+}
+export interface SavePlanningAttachmentInput {
+    id?: unknown;
+    filename?: unknown;
+    content?: unknown;
+    sourcePath?: unknown;
+    caption?: unknown;
+    overwrite?: unknown;
+}
+export interface DeletePlanningAttachmentInput {
+    initiativeId?: unknown;
+    workstreamId?: unknown;
+    attachmentId?: unknown;
+}
+export type PlanningAttachmentSaveStatus = 'attached' | 'already-attached' | 'overwritten';
+export interface SavePlanningAttachmentResult {
+    targetType: PlanningAttachmentTargetType;
+    targetId: string;
+    target: PlanningAttachmentTarget;
+    attachment: TaskAttachmentRecord;
+    status: PlanningAttachmentSaveStatus;
+    auditAttachmentId?: string;
+}
+export interface DeletePlanningAttachmentResult {
+    success: true;
+    targetType: PlanningAttachmentTargetType;
+    targetId: string;
+    target: PlanningAttachmentTarget;
+    attachmentId: string;
+    canonicalAssetDeleted: boolean;
+}
+type CanonicalOverwriteTarget = {
+    index: number;
+    attachment: TaskAttachmentRecord;
+    asset: WorkspaceAssetEntry;
+    descriptor: McpTaskAttachmentDescriptor;
+    relativePath: string;
+    absolutePath: string;
+    logicalFilename: string;
+};
+type EnsureCanonicalAttachmentOptions = {
+    originalFilename?: string;
+    logicalName?: string;
+    assetId?: string;
+    documentId?: string | null;
+    createdAt?: string;
+    createdByUserId?: string | null;
+    scanStatus?: WorkspaceAssetScanStatus;
+    scanEngine?: string | null;
+    scanDetails?: string | null;
+    createLink?: boolean;
+};
+export interface PlanningAttachmentCommandAdapterDependencies {
+    activeWorkspaceId: string;
+    runtimeMode: 'local' | 'cloud';
+    resolveTarget(targetType: PlanningAttachmentTargetType, inputId: unknown): PlanningAttachmentTarget;
+    updateTarget(targetType: PlanningAttachmentTargetType, targetId: string, attachments: Array<string | TaskAttachmentRecord>): unknown;
+    getPaths(): {
+        projectRoot: string;
+        basePath: string;
+    };
+    sanitizeFilenameForPath(filename: unknown): string;
+    inferMimeTypeFromPath(filePath: string): string;
+    inferAssetKind(filePath: string, mimeType: string): WorkspaceAssetKind;
+    isApprovedAttachmentSourcePath(filePath: string, projectRootReal: string): boolean;
+    validateStructuredDocForAttach(relativePath: string, content: string): {
+        ok: true;
+    } | {
+        ok: false;
+        message: string;
+    };
+    isDurableMutationEnabled(targetType: PlanningAttachmentTargetType): boolean;
+    describeAttachment(targetId: string, attachment: string | TaskAttachmentRecord): McpTaskAttachmentDescriptor;
+    listAttachmentDescriptors(target: PlanningAttachmentTarget): McpTaskAttachmentDescriptor[];
+    resolveCanonicalOverwriteTarget(target: {
+        id: string;
+        attachments: Array<string | TaskAttachmentRecord>;
+    }, filename: string, describeAttachment: (targetId: string, attachment: string | TaskAttachmentRecord) => McpTaskAttachmentDescriptor): CanonicalOverwriteTarget | null;
+    buildCanonicalWorkspaceAssetRelativePath(input: {
+        workspaceIdRaw: unknown;
+        kind: WorkspaceAssetKind;
+        filename: string;
+    }): {
+        relativePath: string;
+        assetId: string;
+    };
+    ensureCanonicalAttachment(relativePath: string, targetType: PlanningAttachmentTargetType, targetId: string, caption: string | undefined, timestamp: string, role: WorkspaceAssetLinkRole, options?: EnsureCanonicalAttachmentOptions): Promise<WorkspaceAssetEntry | null>;
+    isValidCanonicalDocumentAsset(asset: WorkspaceAssetEntry): boolean;
+    getImageReferenceLabel(asset: WorkspaceAssetEntry | null | undefined): string | null;
+    getDocumentReferenceLabel(asset: WorkspaceAssetEntry | null | undefined): string | null;
+    workspaceAssetStore?: {
+        getDocument?(assetId: string, workspaceId: string): Pick<WorkspaceDocumentEntry, 'title'> | null;
+        listLinksForTarget(targetType: PlanningAttachmentTargetType, targetId: string, workspaceId: string): WorkspaceAssetLinkEntry[];
+        deleteLink(input: {
+            workspaceId: string;
+            assetId: string;
+            targetType: PlanningAttachmentTargetType;
+            targetId: string;
+            role: WorkspaceAssetLinkRole;
+        }): unknown;
+        listLinksForAsset(assetId: string, workspaceId: string): WorkspaceAssetLinkEntry[];
+        markDeleted(assetId: string, workspaceId: string, deletedAt: string, purgeAfter: string | null): unknown;
+    } | null;
+    now?: () => Date;
+    createError(message: string, code?: string, statusCode?: number): Error;
+}
+export declare class PlanningAttachmentCommandError extends Error {
+    readonly code: string;
+    readonly statusCode: number;
+    constructor(message: string, code?: string, statusCode?: number);
+}
+export declare function createPlanningAttachmentCommandAdapter(deps: PlanningAttachmentCommandAdapterDependencies): {
+    save: (targetType: PlanningAttachmentTargetType, input: SavePlanningAttachmentInput) => Promise<SavePlanningAttachmentResult>;
+    delete: (targetType: PlanningAttachmentTargetType, input: DeletePlanningAttachmentInput) => Promise<DeletePlanningAttachmentResult>;
+};
+export {};

package/dist/mcp/planningAttachmentCommandAdapter.js

@@ -0,0 +1,188 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+export class PlanningAttachmentCommandError extends Error {
+    code;
+    statusCode;
+    constructor(message, code = 'MCP_INVALID_ARGUMENT', statusCode = 400) {
+        super(message);
+        this.code = code;
+        this.statusCode = statusCode;
+        this.name = 'PlanningAttachmentCommandError';
+    }
+}
+const attachmentsFor = (target) => (Array.isArray(target.entity.attachments) ? target.entity.attachments : []);
+export function createPlanningAttachmentCommandAdapter(deps) {
+    const now = () => (deps.now ? deps.now() : new Date());
+    const createError = (message, code, statusCode) => (deps.createError(message, code, statusCode));
+    const save = async (targetType, input) => {
+        const { id: inputId, filename, content, sourcePath, caption, overwrite = false } = input;
+        const target = deps.resolveTarget(targetType, inputId);
+        if (!filename || typeof filename !== 'string')
+            throw createError('filename is required');
+        const hasContent = typeof content === 'string';
+        const hasSourcePath = typeof sourcePath === 'string' && sourcePath.trim().length > 0;
+        if (hasContent === hasSourcePath) {
+            throw createError('Provide exactly one of: content or sourcePath');
+        }
+        if (hasSourcePath && deps.runtimeMode === 'cloud') {
+            throw createError('sourcePath is only available in local runtimes. In cloud runtime, provide content instead.');
+        }
+        const timestamp = now().toISOString();
+        const safeCaption = typeof caption === 'string' && caption.trim().length > 0
+            ? caption.trim()
+            : undefined;
+        const safeFilename = deps.sanitizeFilenameForPath(filename);
+        const { projectRoot, basePath } = deps.getPaths();
+        const existing = attachmentsFor(target);
+        const overwriteTarget = overwrite === true
+            ? deps.resolveCanonicalOverwriteTarget({ id: target.id, attachments: existing }, safeFilename, deps.describeAttachment)
+            : null;
+        const canonicalAsset = overwriteTarget
+            ? null
+            : deps.buildCanonicalWorkspaceAssetRelativePath({
+                workspaceIdRaw: deps.activeWorkspaceId,
+                kind: deps.inferAssetKind(safeFilename, deps.inferMimeTypeFromPath(safeFilename)),
+                filename: safeFilename,
+            });
+        const destinationPath = overwriteTarget
+            ? overwriteTarget.absolutePath
+            : path.join(basePath, canonicalAsset.relativePath);
+        fs.mkdirSync(path.dirname(destinationPath), { recursive: true });
+        if (hasContent) {
+            fs.writeFileSync(destinationPath, content, 'utf8');
+        }
+        else {
+            const trimmedSource = sourcePath.trim();
+            const sourceResolved = path.isAbsolute(trimmedSource)
+                ? path.resolve(trimmedSource)
+                : path.resolve(projectRoot, trimmedSource);
+            if (!fs.existsSync(sourceResolved)) {
+                throw createError(`File not found: ${trimmedSource}`);
+            }
+            const sourceReal = fs.realpathSync(sourceResolved);
+            const projectRootReal = fs.realpathSync(projectRoot);
+            if (!deps.isApprovedAttachmentSourcePath(sourceReal, projectRootReal)) {
+                throw createError("sourcePath must be within project root, a registered Git worktree, a Taskforce-managed source, an approved agent workspace, or the bound profile's QA artifacts root");
+            }
+            if (!fs.statSync(sourceReal).isFile()) {
+                throw createError(`Path is not a file: ${trimmedSource}`);
+            }
+            fs.copyFileSync(sourceReal, destinationPath);
+        }
+        const relativePath = overwriteTarget
+            ? overwriteTarget.relativePath
+            : path.relative(projectRoot, destinationPath).split(path.sep).join('/');
+        if (relativePath.endsWith('.md')) {
+            const validation = deps.validateStructuredDocForAttach(relativePath, fs.readFileSync(destinationPath, 'utf8'));
+            if (!validation.ok)
+                throw createError(validation.message);
+        }
+        const isMarkdownDocument = relativePath.toLowerCase().endsWith('.md')
+            || relativePath.toLowerCase().endsWith('.markdown');
+        const overwriteTitle = overwriteTarget
+            ? deps.workspaceAssetStore?.getDocument?.(overwriteTarget.asset.assetId, deps.activeWorkspaceId)?.title
+            : null;
+        const canonicalName = safeCaption || overwriteTitle || safeFilename;
+        const persistedCaption = isMarkdownDocument
+            ? canonicalName
+            : (safeCaption || overwriteTarget?.attachment.caption || safeFilename);
+        const asset = await deps.ensureCanonicalAttachment(relativePath, targetType, target.id, persistedCaption, timestamp, 'attachment', {
+            originalFilename: safeFilename,
+            logicalName: isMarkdownDocument ? canonicalName : safeFilename,
+            ...(deps.isDurableMutationEnabled(targetType) ? { createLink: false } : {}),
+            ...(overwriteTarget ? {
+                assetId: overwriteTarget.asset.assetId,
+                documentId: overwriteTarget.asset.documentId,
+                createdAt: overwriteTarget.asset.createdAt,
+                createdByUserId: overwriteTarget.asset.createdByUserId,
+                scanStatus: overwriteTarget.asset.scanStatus,
+                scanEngine: overwriteTarget.asset.scanEngine,
+                scanDetails: overwriteTarget.asset.scanDetails,
+            } : {}),
+        });
+        const attachmentReferenceLabel = asset?.kind === 'image'
+            ? deps.getImageReferenceLabel(asset)
+            : (asset && deps.isValidCanonicalDocumentAsset(asset)
+                ? deps.getDocumentReferenceLabel(asset)
+                : null);
+        const attachment = {
+            path: overwriteTarget?.attachment.path || (asset?.kind === 'document' && deps.isValidCanonicalDocumentAsset(asset) && asset.assetId
+                ? `/api/taskforce/documents/${encodeURIComponent(asset.assetId)}/content`
+                : `/api/taskforce/context/${encodeURIComponent((canonicalAsset || { relativePath: overwriteTarget?.descriptor.fsPath || '' }).relativePath)}`),
+            fsPath: overwriteTarget?.attachment.fsPath || canonicalAsset?.relativePath || overwriteTarget?.descriptor.fsPath,
+            caption: isMarkdownDocument ? canonicalName : persistedCaption,
+            displayName: isMarkdownDocument ? canonicalName : safeFilename,
+            originalFilename: safeFilename,
+            ...(asset?.assetId ? { assetId: asset.assetId } : {}),
+            ...(typeof asset?.referenceNumber === 'number' ? { referenceNumber: asset.referenceNumber } : {}),
+            ...(attachmentReferenceLabel ? { referenceLabel: attachmentReferenceLabel } : {}),
+            timestamp,
+        };
+        if (overwriteTarget) {
+            deps.updateTarget(targetType, target.id, existing.map((item, index) => (index === overwriteTarget.index ? attachment : item)));
+            return {
+                targetType,
+                targetId: target.id,
+                target,
+                attachment,
+                status: 'overwritten',
+                auditAttachmentId: asset?.assetId || overwriteTarget.descriptor.attachmentId,
+            };
+        }
+        const duplicate = existing.some((item) => {
+            if (typeof item === 'string')
+                return item === attachment.path || item === attachment.fsPath;
+            if (!item || typeof item !== 'object')
+                return false;
+            return item.path === attachment.path || item.fsPath === attachment.fsPath;
+        });
+        if (duplicate) {
+            return { targetType, targetId: target.id, target, attachment, status: 'already-attached' };
+        }
+        deps.updateTarget(targetType, target.id, [...existing, attachment]);
+        return { targetType, targetId: target.id, target, attachment, status: 'attached' };
+    };
+    const deleteAttachment = async (targetType, input) => {
+        const inputId = targetType === 'initiative' ? input.initiativeId : input.workstreamId;
+        const { attachmentId } = input;
+        if (!attachmentId || typeof attachmentId !== 'string')
+            throw createError('attachmentId is required');
+        const target = deps.resolveTarget(targetType, inputId);
+        const existing = attachmentsFor(target);
+        const descriptors = deps.listAttachmentDescriptors(target);
+        const targetIndex = descriptors.findIndex((entry) => entry.attachmentId === attachmentId);
+        if (targetIndex < 0) {
+            throw createError(`Attachment ${attachmentId} not found on ${targetType} ${String(inputId || '').trim() || target.id}`, 'MCP_NOT_FOUND', 404);
+        }
+        const descriptor = descriptors[targetIndex];
+        const targetAssetLink = descriptor.assetId && deps.workspaceAssetStore
+            ? deps.workspaceAssetStore.listLinksForTarget(targetType, target.id, deps.activeWorkspaceId)
+                .find((link) => link.assetId === descriptor.assetId)
+            : null;
+        deps.updateTarget(targetType, target.id, existing.filter((_, index) => index !== targetIndex));
+        let canonicalAssetDeleted = false;
+        if (descriptor.source === 'canonical' && descriptor.assetId && deps.workspaceAssetStore) {
+            deps.workspaceAssetStore.deleteLink({
+                workspaceId: deps.activeWorkspaceId,
+                assetId: descriptor.assetId,
+                targetType,
+                targetId: target.id,
+                role: targetAssetLink?.role || 'attachment',
+            });
+            const remainingLinks = deps.workspaceAssetStore.listLinksForAsset(descriptor.assetId, deps.activeWorkspaceId);
+            if (targetAssetLink?.role !== 'reference' && remainingLinks.length === 0) {
+                deps.workspaceAssetStore.markDeleted(descriptor.assetId, deps.activeWorkspaceId, now().toISOString(), null);
+                canonicalAssetDeleted = true;
+            }
+        }
+        return {
+            success: true,
+            targetType,
+            targetId: target.id,
+            target,
+            attachmentId,
+            canonicalAssetDeleted,
+        };
+    };
+    return { save, delete: deleteAttachment };
+}

package/dist/mcp/programScaffoldCommandAdapter.d.ts

@@ -0,0 +1,6 @@
+export interface ProgramScaffoldCommandAdapterDependencies {
+    resolvePlanningOwner(value: unknown): unknown;
+    resolveTaskAssignee(value: unknown): unknown;
+    resolveTaskTaxonomy(field: 'category' | 'type' | 'priority' | 'complexity', value: unknown): unknown;
+}
+export declare function prepareProgramScaffoldRequest(input: Record<string, unknown>, deps: ProgramScaffoldCommandAdapterDependencies): Record<string, unknown>;