@taskforcehq/taskforce 0.3.326 → 0.3.327

package/dist/server/routes/agents.js

@@ -0,0 +1,1455 @@
+/**
+ * Taskforce Agents route module.
+ *
+ * Routes registered here:
+ *   GET    /api/taskforce/agents
+ *   POST   /api/taskforce/agents
+ *   PATCH  /api/taskforce/agents/:agentId
+ *   DELETE /api/taskforce/agents/:agentId
+ *   GET    /api/taskforce/agents/:agentId/conversations
+ *   POST   /api/taskforce/agents/:agentId/conversation/new
+ *   POST   /api/taskforce/agents/model-gateway/test
+ *   PATCH  /api/taskforce/agents/:agentId/conversations/:conversationId
+ */
+import { assignedAiProfileColor, normalizeAiProfileColor } from '../../shared/aiProfileColors.js';
+import { BedrockAnthropicMessagesModelGateway } from '../../services/bedrockAnthropicMessagesModelGateway.js';
+import { BedrockMantleModelGateway } from '../../services/bedrockMantleModelGateway.js';
+import { BedrockModelGateway } from '../../services/bedrockModelGateway.js';
+import { saveAiProfileAvatarAssets } from '../aiProfileAvatarAssets.js';
+import { ModelGatewayConfigurationError, normalizePersistedModelGatewayMessages } from '../../services/modelGateway.js';
+import { BedrockAvatarImageProvider, buildTaskforceAgentAvatarPrompt, } from '../../services/taskforceAgentAvatarImageProvider.js';
+import { hashTaskforceAgentMcpToolContract, isTaskforceAgentMutationToolName, prepareTaskforceAgentMcpBridge, serializeTaskforceAgentMcpToolResult, taskforceAgentMutationCallKey, } from '../../services/taskforceAgentMcpBridge.js';
+import { TaskforceAgentConversationStore } from '../../storage/taskforceAgentConversationStore.js';
+import { TaskforceAgentDefinitionConflictError, TaskforceAgentStore, } from '../../storage/taskforceAgentStore.js';
+import { TaskforceAgentSkillStore } from '../../storage/taskforceAgentSkillStore.js';
+import { WorkflowStore } from '../../storage/workflowStore.js';
+import { WorkspaceSyncDurabilityStore } from '../../sync/v3/syncDurabilityStore.js';
+import { projectLegacyTaskforceAgentResponse } from '../../compat/taskforceAgentDefinitionCompat.js';
+import { TASKFORCE_AGENTS_WORKSPACE_FEATURE_KEY, resolveAppGateAccess, } from '../../runtime/appGates.js';
+import { DEFAULT_TASKFORCE_AGENT_MODEL_KEY, DEFAULT_TASKFORCE_AGENT_PROVIDER_KEY, getTaskforceAgentModel, isTaskforceAgentModelVisible, labelForTaskforceAgentModel, labelForTaskforceAgentProvider, normalizeTaskforceAgentModelKey, normalizeTaskforceAgentModelSelection, normalizeTaskforceAgentProviderKey, } from '../../shared/taskforceAgentModels.js';
+import { buildTaskforceAgentRunContext } from '../../shared/taskforceAgentRunContext.js';
+import { inspectAgentDefinition } from '../../shared/taskforceAgentDefinition.js';
+import { buildResolvedTaskforceAgentSystemPrompt, resolveTaskforceAgentRuntimeConfiguration, TaskforceAgentRuntimeResolutionError, } from '../../shared/taskforceAgentRuntimeResolution.js';
+import { serializeTaskforceAgentExecutionSnapshot } from '../../shared/taskforceAgentExecutionSnapshot.js';
+import { getTaskReferenceLabel } from '../../utils/taskReferences.js';
+import { parseJsonBody } from './primitives.js';
+import { resolveErrorStatusCode } from './shared.js';
+const DEFAULT_AGENT_SYSTEM_PROMPT = 'Be concise and actionable.';
+const MAX_MCP_TOOL_ITERATIONS = 6;
+function writeJson(res, statusCode, payload) {
+    res.writeHead(statusCode, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify(payload));
+}
+function normalizeTier(value) {
+    const tier = String(value || process.env.TASKFORCE_BEDROCK_MODEL_TIER || 'balanced').trim().toLowerCase();
+    if (tier === 'fast' || tier === 'balanced' || tier === 'advanced')
+        return tier;
+    return 'balanced';
+}
+function normalizeSystemPrompt(value) {
+    return String(value || DEFAULT_AGENT_SYSTEM_PROMPT).trim() || DEFAULT_AGENT_SYSTEM_PROMPT;
+}
+function buildAgentSystemPrompt(system, agentName) {
+    const normalizedName = String(agentName || '').trim();
+    if (!normalizedName)
+        return system;
+    return [
+        `You are ${normalizedName}, a Taskforce Agent.`,
+        system,
+    ].join('\n\n');
+}
+function normalizeMessages(value, fallbackPrompt) {
+    if (Array.isArray(value)) {
+        if (value.length === 0)
+            return { error: 'Prompt is required.' };
+        const messages = [];
+        for (const item of value) {
+            const role = String(item?.role || '').trim();
+            const content = String(item?.content || '').trim();
+            if (role !== 'user' && role !== 'assistant') {
+                return { error: 'Prompt messages must use user or assistant roles.' };
+            }
+            if (!content) {
+                return { error: 'Prompt messages cannot be empty.' };
+            }
+            if (content.length > 4000) {
+                return { error: 'Prompt messages must be 4,000 characters or less.' };
+            }
+            const message = { role, content };
+            const agentId = String(item?.agentId || '').trim();
+            const agentName = String(item?.agentName || '').trim();
+            const providerKey = String(item?.providerKey || '').trim();
+            const providerLabel = String(item?.providerLabel || '').trim();
+            const modelKey = String(item?.modelKey || '').trim();
+            const modelLabel = String(item?.modelLabel || '').trim();
+            const modelId = String(item?.modelId || '').trim();
+            if (agentId)
+                message.agentId = agentId;
+            if (agentName)
+                message.agentName = agentName;
+            if (providerKey)
+                message.providerKey = providerKey;
+            if (providerLabel)
+                message.providerLabel = providerLabel;
+            if (modelKey)
+                message.modelKey = modelKey;
+            if (modelLabel)
+                message.modelLabel = modelLabel;
+            if (modelId)
+                message.modelId = modelId;
+            const toolActivity = normalizePersistedModelGatewayMessages([item])[0]?.toolActivity;
+            if (role === 'assistant' && toolActivity?.length)
+                message.toolActivity = toolActivity;
+            messages.push(message);
+        }
+        if (!messages.some((message) => message.role === 'user'))
+            return { error: 'Prompt is required.' };
+        return { messages };
+    }
+    const prompt = String(fallbackPrompt || '').trim();
+    if (!prompt)
+        return { error: 'Prompt is required.' };
+    if (prompt.length > 4000)
+        return { error: 'Prompt must be 4,000 characters or less.' };
+    return { messages: [{ role: 'user', content: prompt }] };
+}
+function toGatewayMessages(messages) {
+    return messages.map((message) => ({
+        role: message.role,
+        content: message.content,
+    }));
+}
+function requestsWorkflowStepCompletion(messages) {
+    const latestUserMessage = [...messages].reverse().find((message) => message.role === 'user');
+    const content = String(latestUserMessage?.content || '').trim().toLowerCase();
+    return /^(?:please\s+|(?:can|could|would)\s+you\s+)?(?:perform\s+and\s+complete|complete|finish)\s+(?:your|the|this)\s+(?:current\s+)?workflow\s+step[.!?]*$/.test(content);
+}
+function normalizeTaskId(value) {
+    const taskId = String(value || '').trim();
+    if (!taskId)
+        return null;
+    return taskId.length > 120 ? taskId.slice(0, 120) : taskId;
+}
+function normalizeTaskContextValue(value) {
+    const text = String(value || '').replace(/\s+/g, ' ').trim();
+    return text.length > 160 ? text.slice(0, 157).trim() + '...' : text;
+}
+function normalizeTaskContextDescription(value) {
+    const text = String(value || '').replace(/\s+/g, ' ').trim();
+    return text.length > 700 ? text.slice(0, 697).trim() + '...' : text;
+}
+function resolveTaskContextTask(core, workspaceId, taskId) {
+    if (!core || !taskId)
+        return null;
+    return core.getTask(taskId, workspaceId)
+        || (typeof core.resolveTaskIdentifier === 'function' ? core.resolveTaskIdentifier(taskId, workspaceId) : null);
+}
+function resolveTaskScopeContext(core, workspaceId, input) {
+    const taskId = String(input.taskId || '').trim();
+    if (!taskId)
+        return null;
+    const task = resolveTaskContextTask(core, workspaceId, taskId);
+    return {
+        taskId,
+        taskReference: normalizeTaskContextValue(task?.referenceLabel || input.taskReference) || taskId,
+        taskTitle: normalizeTaskContextValue(task?.title || input.taskTitle),
+        taskDescription: normalizeTaskContextDescription(task?.description),
+        taskStatus: normalizeTaskContextValue(task?.status),
+        taskType: normalizeTaskContextValue(task?.type),
+        taskCategory: normalizeTaskContextValue(task?.category),
+        taskPriority: normalizeTaskContextValue(task?.priority),
+    };
+}
+function buildTaskScopedSystemPrompt(system, input) {
+    const taskId = String(input.taskId || '').trim();
+    if (!taskId)
+        return system;
+    const taskReference = normalizeTaskContextValue(input.taskReference) || taskId;
+    const taskTitle = normalizeTaskContextValue(input.taskTitle);
+    const taskDescription = normalizeTaskContextDescription(input.taskDescription);
+    const details = [
+        `Reference: ${taskReference}`,
+        taskTitle ? `Title: ${taskTitle}` : '',
+        input.taskStatus ? `Status: ${normalizeTaskContextValue(input.taskStatus)}` : '',
+        input.taskType ? `Type: ${normalizeTaskContextValue(input.taskType)}` : '',
+        input.taskCategory ? `Category: ${normalizeTaskContextValue(input.taskCategory)}` : '',
+        input.taskPriority ? `Priority: ${normalizeTaskContextValue(input.taskPriority)}` : '',
+        taskDescription ? `Description: ${taskDescription}` : '',
+    ].filter(Boolean);
+    return [
+        system,
+        [
+            `Task scope: ${details.join('; ')}`,
+            `Treat "this task" as this task. Use Taskforce tools with id ${taskId} when current task data or mutations are needed.`,
+        ].join('\n'),
+    ].join('\n\n');
+}
+function normalizeConversationTitle(value) {
+    const title = String(value || '').trim();
+    return title.length > 120 ? title.slice(0, 120) : title;
+}
+function serializeModelGatewayResult(result) {
+    return {
+        text: result.text,
+        provider: result.provider,
+        modelId: result.modelId,
+        stopReason: result.stopReason || null,
+        latencyMs: result.latencyMs ?? null,
+        usage: result.usage || null,
+    };
+}
+export function serializeWorkflowCompletionProjection(core, workspaceId, _taskId, toolResults) {
+    if (!core)
+        return null;
+    const completedCall = [...toolResults].reverse().find((toolResult) => (toolResult.name === 'complete_workflow_step' && toolResult.ok));
+    const executionId = String(completedCall?.arguments?.executionId || '').trim();
+    if (!executionId)
+        return null;
+    const assignmentSnapshot = new WorkflowStore(core.getDatabaseAdapter(), core.getTenantId()).getAssignmentForExecutionSync(workspaceId, executionId);
+    if (!assignmentSnapshot)
+        return null;
+    const taskId = assignmentSnapshot.execution.taskId;
+    const taskSnapshot = core.getTask(taskId, workspaceId);
+    let taskAuthoritative = null;
+    if (taskSnapshot) {
+        const ownership = new WorkspaceSyncDurabilityStore(core.getDatabaseAdapter())
+            .readWorkspaceDomainOwnership({
+            tenantId: core.getTenantId(),
+            workspaceId,
+            domain: 'task',
+            entityId: taskSnapshot.id,
+        });
+        if (ownership.owned && ownership.lastSequence && ownership.canonicalFingerprint) {
+            taskAuthoritative = {
+                payload: taskSnapshot,
+                entityRevision: ownership.entityRevision,
+                lifecycleRevision: ownership.lifecycleRevision,
+                sequence: ownership.lastSequence,
+                canonicalFingerprint: ownership.canonicalFingerprint,
+            };
+        }
+    }
+    return {
+        executionId,
+        taskId,
+        assignmentSnapshot,
+        taskSnapshot,
+        taskAuthoritative,
+    };
+}
+function createDefaultModelGateway(selection) {
+    const model = getTaskforceAgentModel(selection?.modelKey);
+    if (model && selection?.providerKey && model.providerKey !== selection.providerKey) {
+        throw new ModelGatewayConfigurationError('The selected model does not belong to this provider.', 'MODEL_UNAVAILABLE');
+    }
+    const source = selection?.modelSource || model?.source || 'bedrock';
+    const runtime = selection?.runtime || model?.runtime || 'bedrock-runtime';
+    if (source !== 'bedrock') {
+        throw new ModelGatewayConfigurationError('Selected model source is not configured yet.', 'MODEL_SOURCE_NOT_IMPLEMENTED');
+    }
+    if (runtime === 'bedrock-anthropic-messages')
+        return new BedrockAnthropicMessagesModelGateway();
+    if (runtime === 'bedrock-mantle')
+        return new BedrockMantleModelGateway();
+    if (runtime === 'bedrock-runtime')
+        return new BedrockModelGateway();
+    throw new ModelGatewayConfigurationError('Selected model runtime is not configured yet.', 'MODEL_RUNTIME_UNAVAILABLE');
+}
+function buildModelGatewayInput(input) {
+    return {
+        tier: input.tier,
+        providerKey: input.providerKey,
+        modelKey: input.modelKey,
+        system: input.system,
+        messages: input.messages,
+        maxTokens: input.model.defaultMaxTokens,
+        runContext: input.runContext,
+        ...(input.model.supportsTemperature ? { temperature: 0 } : {}),
+    };
+}
+function serializeAgent(agent, profile) {
+    return {
+        id: agent.id,
+        workspaceId: agent.workspaceId,
+        ...(typeof agent.definitionRevision === 'number' ? {
+            lifecycleStatus: agent.lifecycleStatus,
+            managedProfileId: agent.managedProfileId ?? profile?.id ?? null,
+            definition: agent.definitionValue,
+            definitionRevision: agent.definitionRevision,
+            definitionHash: agent.definitionHash,
+            configurationState: agent.configurationState,
+            configurationIssues: agent.configurationIssues,
+        } : {}),
+        ...projectLegacyTaskforceAgentResponse(agent),
+        ...(profile ? {
+            profileId: profile.id,
+            username: profile.username,
+            color: profile.color,
+            colorSource: profile.colorSource,
+            avatarUrl: profile.avatarUrl ?? null,
+            avatarSourceUrl: profile.avatarSourceUrl ?? null,
+            avatarRevision: profile.avatarRevision ?? 0,
+            avatarUpdatedAt: profile.avatarUpdatedAt ?? null,
+        } : {}),
+        createdAt: agent.createdAt,
+        updatedAt: agent.updatedAt,
+    };
+}
+function buildTaskforceAgentProfileMetadata(agent, existing) {
+    const currentTaskforceMetadata = existing?.taskforce && typeof existing.taskforce === 'object' && !Array.isArray(existing.taskforce)
+        ? existing.taskforce
+        : {};
+    return {
+        ...(existing || {}),
+        taskforce: {
+            ...currentTaskforceMetadata,
+            managedSource: 'taskforce_agents',
+            taskforceAgentId: agent.id,
+        },
+    };
+}
+function isAiProfileForTaskforceAgent(profile, agent) {
+    if (agent.managedProfileId)
+        return profile.id === agent.managedProfileId;
+    const taskforceMetadata = profile.providerMetadata?.taskforce;
+    if (taskforceMetadata && typeof taskforceMetadata === 'object' && !Array.isArray(taskforceMetadata)) {
+        const metadata = taskforceMetadata;
+        const linkedAgentId = String(metadata.taskforceAgentId || '').trim();
+        if (linkedAgentId)
+            return linkedAgentId === agent.id;
+        if (String(metadata.managedSource || '').trim() !== 'taskforce_agents')
+            return false;
+    }
+    else {
+        return false;
+    }
+    return profile.name === agent.name
+        && profile.surfaceType === 'agent'
+        && profile.provider === agent.providerKey
+        && profile.model === agent.modelKey;
+}
+function repairTaskforceAgentProfileMirror(core, agent, profile) {
+    const taskforceMetadata = profile.providerMetadata?.taskforce;
+    const linkedAgentId = taskforceMetadata && typeof taskforceMetadata === 'object' && !Array.isArray(taskforceMetadata)
+        ? String(taskforceMetadata.taskforceAgentId || '').trim()
+        : '';
+    let repaired = linkedAgentId === agent.id ? profile : core.updateAiProfileProviderMetadata({
+        workspaceId: agent.workspaceId,
+        profileId: profile.id,
+        providerMetadata: buildTaskforceAgentProfileMetadata(agent, profile.providerMetadata),
+    });
+    const currentColor = normalizeAiProfileColor(repaired.color);
+    const defaultColor = assignedAiProfileColor(agent.id);
+    if (currentColor && repaired.colorSource !== 'user_override'
+        && (currentColor !== defaultColor || repaired.colorSource !== 'assigned_default')) {
+        repaired = core.updateAiProfileColorGroup({
+            workspaceId: agent.workspaceId,
+            profileIds: [repaired.id],
+            reset: true,
+            allowTaskforceManaged: true,
+        })[0] || repaired;
+    }
+    return repaired;
+}
+function buildTaskforceAgentProfileMap(core, workspaceId, agents) {
+    const profiles = typeof core?.listAiProfiles === 'function' ? core.listAiProfiles(workspaceId) : [];
+    const byAgentId = new Map();
+    const claimedProfileIds = new Set();
+    for (const agent of agents) {
+        if (!agent.managedProfileId)
+            continue;
+        const profile = profiles.find((candidate) => candidate.id === agent.managedProfileId);
+        if (!profile)
+            continue;
+        byAgentId.set(agent.id, core ? repairTaskforceAgentProfileMirror(core, agent, profile) : profile);
+        claimedProfileIds.add(profile.id);
+    }
+    for (const profile of profiles) {
+        const taskforceMetadata = profile.providerMetadata?.taskforce;
+        if (!taskforceMetadata || typeof taskforceMetadata !== 'object' || Array.isArray(taskforceMetadata))
+            continue;
+        const agentId = String(taskforceMetadata.taskforceAgentId || '').trim();
+        const agent = agents.find((candidate) => candidate.id === agentId);
+        if (!agent || byAgentId.has(agentId))
+            continue;
+        byAgentId.set(agentId, core ? repairTaskforceAgentProfileMirror(core, agent, profile) : profile);
+        claimedProfileIds.add(profile.id);
+    }
+    for (const agent of agents) {
+        if (byAgentId.has(agent.id))
+            continue;
+        const candidates = profiles.filter((profile) => (!claimedProfileIds.has(profile.id)
+            && isAiProfileForTaskforceAgent(profile, agent)
+            && agents.filter((candidate) => isAiProfileForTaskforceAgent(profile, candidate)).length === 1));
+        if (candidates.length !== 1)
+            continue;
+        const profile = core ? repairTaskforceAgentProfileMirror(core, agent, candidates[0]) : candidates[0];
+        byAgentId.set(agent.id, profile);
+        claimedProfileIds.add(profile.id);
+    }
+    return byAgentId;
+}
+function resolveExactTaskforceAgentProfile(core, agent) {
+    if (agent.managedProfileId) {
+        const profile = core.listAiProfiles(agent.workspaceId).find((candidate) => (candidate.id === agent.managedProfileId
+            && !candidate.archivedAt
+            && !candidate.mergedIntoProfileId));
+        return profile ? repairTaskforceAgentProfileMirror(core, agent, profile) : null;
+    }
+    const matches = core.listAiProfiles(agent.workspaceId).filter((profile) => {
+        if (profile.archivedAt || profile.mergedIntoProfileId)
+            return false;
+        const metadata = profile.providerMetadata?.taskforce;
+        if (!metadata || typeof metadata !== 'object' || Array.isArray(metadata))
+            return false;
+        const values = metadata;
+        return values.managedSource === 'taskforce_agents'
+            && values.taskforceAgentId === agent.id;
+    });
+    if (matches.length !== 1)
+        return null;
+    return repairTaskforceAgentProfileMirror(core, agent, matches[0]);
+}
+function mirrorTaskforceAgentAiProfile(core, agent) {
+    if (!core)
+        return null;
+    const existingProfile = typeof core.listAiProfiles === 'function'
+        ? core.listAiProfiles(agent.workspaceId).find((profile) => (agent.managedProfileId
+            ? profile.id === agent.managedProfileId
+            : isAiProfileForTaskforceAgent(profile, agent)))
+        : null;
+    const providerMetadata = buildTaskforceAgentProfileMetadata(agent, existingProfile?.providerMetadata);
+    const resolved = core.resolveAiProfile({
+        workspaceId: agent.workspaceId,
+        name: agent.name,
+        provider: agent.providerKey,
+        model: agent.modelKey,
+        surfaceType: 'agent',
+        providerMetadata,
+        ...(existingProfile?.profileToken ? { profileToken: existingProfile.profileToken } : {}),
+    }, {
+        trustedSeatScope: 'cloud_metered',
+    });
+    const profile = resolved.created
+        ? core.updateAiProfileColorGroup({
+            workspaceId: agent.workspaceId,
+            profileIds: [resolved.profile.id],
+            reset: true,
+            allowTaskforceManaged: true,
+        })[0] || resolved.profile
+        : resolved.profile;
+    return core.updateAiProfileProviderMetadata({
+        workspaceId: agent.workspaceId,
+        profileId: profile.id,
+        providerMetadata: buildTaskforceAgentProfileMetadata(agent, profile.providerMetadata),
+    });
+}
+function validateSignatureColorRequest(body) {
+    if (body.resetSignatureColor === true)
+        return { reset: true };
+    if (body.signatureColor === undefined)
+        return {};
+    const color = normalizeAiProfileColor(body.signatureColor);
+    return color ? { color } : { error: 'Signature color must be a Taskforce palette token or hex color.' };
+}
+function applyTaskforceAgentSignatureColor(core, agent, profile, request) {
+    if (!core || !profile || (!request.color && !request.reset))
+        return profile;
+    const [updated] = core.updateAiProfileColorGroup({
+        workspaceId: agent.workspaceId,
+        profileIds: [profile.id],
+        ...(request.reset ? { reset: true } : { color: request.color }),
+        allowTaskforceManaged: true,
+    });
+    return updated || profile;
+}
+function archiveMirroredTaskforceAgentAiProfile(core, agent, actorUserId) {
+    if (!core)
+        return;
+    const profile = core.listAiProfiles(agent.workspaceId)
+        .find((candidate) => isAiProfileForTaskforceAgent(candidate, agent));
+    if (!profile)
+        return;
+    core.archiveAiProfile({
+        workspaceId: agent.workspaceId,
+        profileId: profile.id,
+        archivedBy: actorUserId,
+        reason: 'taskforce_agent_archived',
+    });
+}
+function resolveConversationContext(core, conversation) {
+    const taskId = normalizeTaskId(conversation.taskId);
+    if (!taskId)
+        return null;
+    const task = resolveTaskContextTask(core, conversation.workspaceId, taskId);
+    return {
+        type: 'task',
+        taskId,
+        taskReference: normalizeTaskContextValue(getTaskReferenceLabel(task)) || null,
+        taskTitle: normalizeTaskContextValue(task?.title) || null,
+    };
+}
+function serializeConversation(conversation, core) {
+    if (!conversation)
+        return null;
+    const context = resolveConversationContext(core, conversation);
+    return {
+        id: conversation.id,
+        workspaceId: conversation.workspaceId,
+        agentId: conversation.agentId,
+        title: conversation.title,
+        messages: conversation.messages,
+        modelProvider: conversation.modelProvider || null,
+        modelId: conversation.modelId || null,
+        taskId: conversation.taskId || null,
+        taskReference: context?.taskReference || null,
+        taskTitle: context?.taskTitle || null,
+        context,
+        usage: conversation.usage || null,
+        latencyMs: conversation.latencyMs ?? null,
+        createdAt: conversation.createdAt,
+        updatedAt: conversation.updatedAt,
+    };
+}
+function serializeConversationSummary(conversation, core) {
+    const context = resolveConversationContext(core, conversation);
+    return {
+        id: conversation.id,
+        workspaceId: conversation.workspaceId,
+        agentId: conversation.agentId,
+        title: conversation.title,
+        messageCount: conversation.messages.length,
+        modelProvider: conversation.modelProvider || null,
+        modelId: conversation.modelId || null,
+        taskId: conversation.taskId || null,
+        taskReference: context?.taskReference || null,
+        taskTitle: context?.taskTitle || null,
+        context,
+        usage: conversation.usage || null,
+        latencyMs: conversation.latencyMs ?? null,
+        createdAt: conversation.createdAt,
+        updatedAt: conversation.updatedAt,
+    };
+}
+function formatModelGatewayError(error) {
+    const message = String(error?.message || error || 'Model gateway test failed.');
+    return message
+        .replace(/\bAmazon Bedrock\b/gi, 'Taskforce HQ')
+        .replace(/\bBedrock\b/gi, 'Taskforce HQ')
+        .replace(/\bbedrock\b/g, 'model gateway');
+}
+function formatAvatarGenerationError(error) {
+    const record = error;
+    const message = String(error?.message
+        || record?.Message
+        || record?.name
+        || error
+        || 'Unable to generate agent avatar.');
+    return message
+        .replace(/\bAmazon Bedrock\b/gi, 'Taskforce HQ')
+        .replace(/\bBedrock\b/gi, 'Taskforce HQ')
+        .replace(/\bbedrock\b/g, 'image provider');
+}
+function avatarGenerationErrorDetails(error, diagnostics) {
+    const record = error;
+    return {
+        name: String(record?.name || record?.code || 'Error'),
+        message: formatAvatarGenerationError(error),
+        statusCode: record?.$metadata?.httpStatusCode ?? null,
+        requestId: record?.$metadata?.requestId ?? null,
+        provider: diagnostics?.provider ?? null,
+        region: diagnostics?.region ?? null,
+        modelId: diagnostics?.modelId ?? null,
+    };
+}
+function agentAvatarOriginalNameBase(agentName) {
+    return agentName.replace(/[^a-z0-9._-]+/gi, '-').replace(/^-+|-+$/g, '') || 'agent';
+}
+function resolveWorkspaceId(req, body, requestWorkspaceId) {
+    const url = new URL(req.url || '', 'http://localhost');
+    const authoritativeWorkspaceId = String(requestWorkspaceId?.(req) || '').trim();
+    const requestedWorkspaceId = String(body?.workspaceId || url.searchParams.get('workspaceId') || '').trim();
+    if (authoritativeWorkspaceId
+        && requestedWorkspaceId
+        && requestedWorkspaceId !== authoritativeWorkspaceId) {
+        throw Object.assign(new Error('The requested workspace does not match the authorized workspace.'), { statusCode: 403, code: 'TASKFORCE_AGENT_WORKSPACE_FORBIDDEN' });
+    }
+    return authoritativeWorkspaceId || requestedWorkspaceId || 'default';
+}
+function validateAgentInput(body, workspaceId, actorUserId) {
+    const name = String(body?.name || '').trim();
+    if (!name)
+        return { error: 'Agent name is required.' };
+    if (name.length > 80)
+        return { error: 'Agent name must be 80 characters or less.' };
+    const systemPrompt = normalizeSystemPrompt(body?.systemPrompt);
+    if (systemPrompt.length > 4000)
+        return { error: 'Agent instructions must be 4,000 characters or less.' };
+    const providerKey = normalizeTaskforceAgentProviderKey(body?.providerKey || DEFAULT_TASKFORCE_AGENT_PROVIDER_KEY);
+    const requestedModel = body?.modelKey !== undefined ? getTaskforceAgentModel(body.modelKey) : null;
+    if (requestedModel && !isTaskforceAgentModelVisible(requestedModel)) {
+        return { error: 'Selected model is not available for this account.' };
+    }
+    const modelKey = normalizeTaskforceAgentModelKey(body?.modelKey || DEFAULT_TASKFORCE_AGENT_MODEL_KEY, providerKey);
+    if (!modelKey)
+        return { error: 'Select a configured model for this provider.' };
+    return {
+        workspaceId,
+        name,
+        providerKey,
+        modelKey,
+        modelTier: normalizeTier(body?.modelTier),
+        systemPrompt,
+        enabled: body?.enabled === false ? false : true,
+        actorUserId,
+    };
+}
+function canonicalMutationError(error) {
+    if (error instanceof TaskforceAgentDefinitionConflictError) {
+        return {
+            statusCode: 409,
+            payload: {
+                success: false,
+                error: error.message,
+                code: error.code,
+                currentDefinitionRevision: error.currentDefinitionRevision,
+                currentDefinitionHash: error.currentDefinitionHash,
+            },
+        };
+    }
+    const candidate = error;
+    if (candidate?.code !== 'INVALID_AGENT_DEFINITION')
+        return null;
+    return {
+        statusCode: 400,
+        payload: {
+            success: false,
+            error: candidate.message || 'Agent definition is invalid.',
+            code: candidate.code,
+            configurationState: candidate.configurationState || 'invalid',
+            configurationIssues: Array.isArray(candidate.issues) ? candidate.issues : [],
+        },
+    };
+}
+export function registerAgentsRoutes(deps) {
+    const { addRoute, ensureAppAccess, core, requestWorkspaceId, resolveAuthenticatedUserId, resolveRuntimeMode = () => 'local', ensureWorkspaceAdminRole, agentStore, skillStore, conversationStore, createModelGateway = createDefaultModelGateway, prepareMcpBridge = prepareTaskforceAgentMcpBridge, aiProfileAvatarAssetDeps, avatarImageProvider, saveAiProfileAvatarAssets: saveAvatarAssets = saveAiProfileAvatarAssets, agentRuntimeReferenceResolvers, agentRuntimeReferenceResolversForWorkspace, } = deps;
+    let resolvedAgentStore = agentStore || null;
+    let resolvedSkillStore = skillStore || null;
+    let resolvedConversationStore = conversationStore || null;
+    let resolvedAvatarImageProvider = avatarImageProvider || null;
+    const getAgentStore = () => {
+        if (resolvedAgentStore)
+            return resolvedAgentStore;
+        if (!core)
+            throw new Error('Taskforce agent store is unavailable.');
+        resolvedAgentStore = new TaskforceAgentStore(core.getDatabaseAdapter(), core.getTenantId());
+        return resolvedAgentStore;
+    };
+    const getConversationStore = () => {
+        if (resolvedConversationStore)
+            return resolvedConversationStore;
+        if (!core)
+            throw new Error('Taskforce agent conversation store is unavailable.');
+        resolvedConversationStore = new TaskforceAgentConversationStore(core.getDatabaseAdapter(), core.getTenantId());
+        return resolvedConversationStore;
+    };
+    const getSkillStore = () => {
+        if (resolvedSkillStore)
+            return resolvedSkillStore;
+        if (!core)
+            return null;
+        resolvedSkillStore = new TaskforceAgentSkillStore(core.getDatabaseAdapter(), core.getTenantId());
+        return resolvedSkillStore;
+    };
+    const resolveRuntimeReferenceResolversForWorkspace = (workspaceId) => {
+        const baseResolvers = agentRuntimeReferenceResolversForWorkspace?.(workspaceId)
+            || agentRuntimeReferenceResolvers
+            || {};
+        return {
+            ...baseResolvers,
+            resolveBehaviorReference: (kind, reference) => {
+                const provided = baseResolvers.resolveBehaviorReference?.(kind, reference)
+                    || null;
+                if (provided || kind !== 'skill')
+                    return provided;
+                return getSkillStore()?.resolve(workspaceId, reference) || null;
+            },
+        };
+    };
+    const getAvatarImageProvider = () => {
+        if (resolvedAvatarImageProvider)
+            return resolvedAvatarImageProvider;
+        resolvedAvatarImageProvider = new BedrockAvatarImageProvider();
+        return resolvedAvatarImageProvider;
+    };
+    const persistManagedProfileLink = (agent, profile, actorUserId) => {
+        if (!profile || agent.managedProfileId === profile.id)
+            return agent;
+        const store = getAgentStore();
+        if (typeof store.setManagedProfileId !== 'function')
+            return agent;
+        return store.setManagedProfileId(agent.workspaceId, agent.id, profile.id, actorUserId) || agent;
+    };
+    const ensureTaskforceAgentsAccess = (req, res) => {
+        if (!ensureAppAccess(req, res))
+            return false;
+        const gate = resolveAppGateAccess(TASKFORCE_AGENTS_WORKSPACE_FEATURE_KEY);
+        if (gate.allowed)
+            return true;
+        writeJson(res, 403, {
+            success: false,
+            error: 'Taskforce Agents are unavailable for this workspace.',
+            code: gate.code || 'TASKFORCE_AGENTS_UNAVAILABLE',
+        });
+        return false;
+    };
+    addRoute('GET', '/api/taskforce/agents', async (req, res) => {
+        if (!ensureTaskforceAgentsAccess(req, res))
+            return;
+        try {
+            const workspaceId = resolveWorkspaceId(req, undefined, requestWorkspaceId);
+            const savedAgents = getAgentStore().list(workspaceId);
+            const profileMap = buildTaskforceAgentProfileMap(core, workspaceId, savedAgents);
+            const actorUserId = resolveAuthenticatedUserId?.(req) || null;
+            const agents = savedAgents
+                .map((agent) => {
+                const profile = profileMap.get(agent.id) || null;
+                return serializeAgent(persistManagedProfileLink(agent, profile, actorUserId), profile);
+            });
+            writeJson(res, 200, { success: true, agents });
+        }
+        catch (error) {
+            writeJson(res, resolveErrorStatusCode(error, 500), {
+                success: false,
+                error: String(error?.message || error || 'Unable to load Taskforce agents.'),
+            });
+        }
+    });
+    addRoute('POST', '/api/taskforce/agents', async (req, res) => {
+        if (!ensureTaskforceAgentsAccess(req, res))
+            return;
+        try {
+            const body = await parseJsonBody(req);
+            const workspaceId = resolveWorkspaceId(req, body, requestWorkspaceId);
+            const actorUserId = resolveAuthenticatedUserId?.(req) || null;
+            const colorRequest = validateSignatureColorRequest(body);
+            if ('error' in colorRequest) {
+                writeJson(res, 400, { success: false, error: colorRequest.error });
+                return;
+            }
+            let agent;
+            if (Object.prototype.hasOwnProperty.call(body, 'definition')) {
+                if (body.lifecycleStatus !== undefined
+                    && body.lifecycleStatus !== 'active'
+                    && body.lifecycleStatus !== 'disabled') {
+                    writeJson(res, 400, {
+                        success: false,
+                        error: 'lifecycleStatus must be active or disabled when creating an agent.',
+                        code: 'INVALID_AGENT_LIFECYCLE_STATUS',
+                    });
+                    return;
+                }
+                agent = getAgentStore().createFromDefinition({
+                    workspaceId,
+                    definition: body.definition,
+                    lifecycleStatus: body.lifecycleStatus === 'disabled' ? 'disabled' : 'active',
+                    actorUserId,
+                });
+            }
+            else {
+                const input = validateAgentInput(body, workspaceId, actorUserId);
+                if ('error' in input) {
+                    writeJson(res, 400, { success: false, error: input.error });
+                    return;
+                }
+                agent = getAgentStore().create(input);
+            }
+            const profile = applyTaskforceAgentSignatureColor(core, agent, mirrorTaskforceAgentAiProfile(core, agent), colorRequest);
+            agent = persistManagedProfileLink(agent, profile, actorUserId);
+            writeJson(res, 201, { success: true, agent: serializeAgent(agent, profile) });
+        }
+        catch (error) {
+            const mutationError = canonicalMutationError(error);
+            if (mutationError) {
+                writeJson(res, mutationError.statusCode, mutationError.payload);
+                return;
+            }
+            writeJson(res, resolveErrorStatusCode(error, 500), {
+                success: false,
+                error: String(error?.message || error || 'Unable to save Taskforce agent.'),
+            });
+        }
+    });
+    addRoute('PATCH', '/api/taskforce/agents/:agentId', async (req, res, params) => {
+        if (!ensureTaskforceAgentsAccess(req, res))
+            return;
+        try {
+            const body = await parseJsonBody(req);
+            const workspaceId = resolveWorkspaceId(req, body, requestWorkspaceId);
+            const actorUserId = resolveAuthenticatedUserId?.(req) || null;
+            const colorRequest = validateSignatureColorRequest(body);
+            if ('error' in colorRequest) {
+                writeJson(res, 400, { success: false, error: colorRequest.error });
+                return;
+            }
+            let agent;
+            if (Object.prototype.hasOwnProperty.call(body, 'definition')) {
+                if (body.lifecycleStatus !== undefined
+                    && body.lifecycleStatus !== 'active'
+                    && body.lifecycleStatus !== 'disabled') {
+                    writeJson(res, 400, {
+                        success: false,
+                        error: 'lifecycleStatus must be active or disabled when updating an agent.',
+                        code: 'INVALID_AGENT_LIFECYCLE_STATUS',
+                    });
+                    return;
+                }
+                const expectedDefinitionHash = String(body.expectedDefinitionHash || '').trim();
+                if (!expectedDefinitionHash) {
+                    writeJson(res, 400, {
+                        success: false,
+                        error: 'expectedDefinitionHash is required for Agent Definition updates.',
+                        code: 'EXPECTED_DEFINITION_HASH_REQUIRED',
+                    });
+                    return;
+                }
+                agent = getAgentStore().updateDefinition(workspaceId, params.agentId, {
+                    definition: body.definition,
+                    expectedDefinitionHash,
+                    actorUserId,
+                });
+                if (agent && (body.lifecycleStatus === 'active' || body.lifecycleStatus === 'disabled')) {
+                    agent = getAgentStore().setLifecycleStatus(workspaceId, params.agentId, body.lifecycleStatus, actorUserId);
+                }
+            }
+            else {
+                const input = validateAgentInput(body, workspaceId, actorUserId);
+                if ('error' in input) {
+                    writeJson(res, 400, { success: false, error: input.error });
+                    return;
+                }
+                agent = getAgentStore().update(workspaceId, params.agentId, input);
+            }
+            if (!agent) {
+                writeJson(res, 404, { success: false, error: 'Taskforce agent not found.' });
+                return;
+            }
+            const profile = applyTaskforceAgentSignatureColor(core, agent, mirrorTaskforceAgentAiProfile(core, agent), colorRequest);
+            agent = persistManagedProfileLink(agent, profile, actorUserId);
+            writeJson(res, 200, { success: true, agent: serializeAgent(agent, profile) });
+        }
+        catch (error) {
+            const mutationError = canonicalMutationError(error);
+            if (mutationError) {
+                writeJson(res, mutationError.statusCode, mutationError.payload);
+                return;
+            }
+            writeJson(res, resolveErrorStatusCode(error, 500), {
+                success: false,
+                error: String(error?.message || error || 'Unable to save Taskforce agent.'),
+            });
+        }
+    });
+    addRoute('DELETE', '/api/taskforce/agents/:agentId', async (req, res, params) => {
+        if (!ensureTaskforceAgentsAccess(req, res))
+            return;
+        try {
+            const body = await parseJsonBody(req);
+            const workspaceId = resolveWorkspaceId(req, body, requestWorkspaceId);
+            const existingAgent = getAgentStore().get(workspaceId, params.agentId);
+            if (!existingAgent) {
+                writeJson(res, 404, { success: false, error: 'Taskforce agent not found.' });
+                return;
+            }
+            const actorUserId = resolveAuthenticatedUserId?.(req) || null;
+            archiveMirroredTaskforceAgentAiProfile(core, existingAgent, actorUserId);
+            const agent = getAgentStore().archive(workspaceId, params.agentId, actorUserId);
+            if (!agent) {
+                writeJson(res, 404, { success: false, error: 'Taskforce agent not found.' });
+                return;
+            }
+            writeJson(res, 200, { success: true, agent: serializeAgent(agent) });
+        }
+        catch (error) {
+            writeJson(res, resolveErrorStatusCode(error, 500), {
+                success: false,
+                error: String(error?.message || error || 'Unable to archive Taskforce agent.'),
+            });
+        }
+    });
+    addRoute('POST', '/api/taskforce/agents/:agentId/avatar/generate', async (req, res, params) => {
+        if (!ensureTaskforceAgentsAccess(req, res))
+            return;
+        let resolvedWorkspaceIdForLog = null;
+        try {
+            const body = await parseJsonBody(req);
+            const workspaceId = resolveWorkspaceId(req, body, requestWorkspaceId);
+            resolvedWorkspaceIdForLog = workspaceId;
+            if (!ensureWorkspaceAdminRole?.(req, workspaceId)) {
+                writeJson(res, 403, { success: false, error: 'Workspace admin access is required to generate agent avatars.' });
+                return;
+            }
+            if (!core || !aiProfileAvatarAssetDeps) {
+                writeJson(res, 503, { success: false, error: 'Agent avatar generation is not configured.' });
+                return;
+            }
+            const agent = getAgentStore().get(workspaceId, params.agentId);
+            if (!agent) {
+                writeJson(res, 404, { success: false, error: 'Taskforce agent not found.' });
+                return;
+            }
+            const profile = mirrorTaskforceAgentAiProfile(core, agent);
+            if (!profile) {
+                writeJson(res, 500, { success: false, error: 'Unable to resolve the agent profile.' });
+                return;
+            }
+            const avatarProvider = getAvatarImageProvider();
+            const generated = await avatarProvider.generate(buildTaskforceAgentAvatarPrompt({
+                agentName: agent.name,
+                visualDescription: agent.definition?.presentation.avatar.visualDescription,
+                artStyle: agent.definition?.presentation.avatar.artStyle,
+            }));
+            const originalNameBase = agentAvatarOriginalNameBase(agent.name);
+            const result = await saveAvatarAssets(aiProfileAvatarAssetDeps, {
+                workspaceId,
+                profileId: profile.id,
+                display: {
+                    buffer: generated.buffer,
+                    mimeType: generated.mimeType,
+                    originalName: `${originalNameBase}-avatar.png`,
+                },
+                source: {
+                    buffer: generated.buffer,
+                    mimeType: generated.mimeType,
+                    originalName: `${originalNameBase}-avatar-source.png`,
+                },
+                actorId: resolveAuthenticatedUserId?.(req) || null,
+            });
+            writeJson(res, 200, {
+                success: true,
+                agent: serializeAgent(agent, result.profile),
+                avatar: {
+                    modelId: generated.modelId,
+                    profileId: result.profile.id,
+                    avatarUrl: result.profile.avatarUrl ?? null,
+                    avatarRevision: result.profile.avatarRevision ?? 0,
+                },
+            });
+        }
+        catch (error) {
+            const diagnostics = resolvedAvatarImageProvider?.getDiagnostics?.() ?? null;
+            console.warn('[taskforce-agents] avatar generation failed', {
+                workspaceId: resolvedWorkspaceIdForLog,
+                agentId: params.agentId,
+                ...avatarGenerationErrorDetails(error, diagnostics),
+            });
+            writeJson(res, resolveErrorStatusCode(error, 500), {
+                success: false,
+                error: formatAvatarGenerationError(error),
+                details: avatarGenerationErrorDetails(error, diagnostics),
+            });
+        }
+    });
+    addRoute('GET', '/api/taskforce/agents/:agentId/conversations', async (req, res, params) => {
+        if (!ensureTaskforceAgentsAccess(req, res))
+            return;
+        try {
+            const workspaceId = resolveWorkspaceId(req, undefined, requestWorkspaceId);
+            const agent = getAgentStore().get(workspaceId, params.agentId);
+            if (!agent) {
+                writeJson(res, 404, { success: false, error: 'Taskforce agent not found.' });
+                return;
+            }
+            const conversations = getConversationStore()
+                .listForAgent(workspaceId, agent.id)
+                .map((conversation) => serializeConversationSummary(conversation, core));
+            writeJson(res, 200, { success: true, conversations });
+        }
+        catch (error) {
+            writeJson(res, resolveErrorStatusCode(error, 500), {
+                success: false,
+                error: String(error?.message || error || 'Unable to load agent conversations.'),
+            });
+        }
+    });
+    addRoute('GET', '/api/taskforce/agents/:agentId/conversation', async (req, res, params) => {
+        if (!ensureTaskforceAgentsAccess(req, res))
+            return;
+        try {
+            const workspaceId = resolveWorkspaceId(req, undefined, requestWorkspaceId);
+            const agent = getAgentStore().get(workspaceId, params.agentId);
+            if (!agent) {
+                writeJson(res, 404, { success: false, error: 'Taskforce agent not found.' });
+                return;
+            }
+            const url = new URL(req.url || '', 'http://localhost');
+            const conversationId = String(url.searchParams.get('conversationId') || '').trim();
+            const conversation = conversationId
+                ? getConversationStore().getById(workspaceId, agent.id, conversationId)
+                : getConversationStore().getLatest(workspaceId, agent.id);
+            if (conversationId && !conversation) {
+                writeJson(res, 404, { success: false, error: 'Agent conversation not found.' });
+                return;
+            }
+            writeJson(res, 200, { success: true, conversation: serializeConversation(conversation, core) });
+        }
+        catch (error) {
+            writeJson(res, resolveErrorStatusCode(error, 500), {
+                success: false,
+                error: String(error?.message || error || 'Unable to load agent conversation.'),
+            });
+        }
+    });
+    addRoute('POST', '/api/taskforce/agents/:agentId/conversation/new', async (req, res, params) => {
+        if (!ensureTaskforceAgentsAccess(req, res))
+            return;
+        try {
+            const body = await parseJsonBody(req);
+            const workspaceId = resolveWorkspaceId(req, body, requestWorkspaceId);
+            const agent = getAgentStore().get(workspaceId, params.agentId);
+            if (!agent) {
+                writeJson(res, 404, { success: false, error: 'Taskforce agent not found.' });
+                return;
+            }
+            const taskId = normalizeTaskId(body?.taskId);
+            const conversation = getConversationStore().createEmpty(workspaceId, agent.id, resolveAuthenticatedUserId?.(req) || null, taskId);
+            writeJson(res, 201, { success: true, conversation: serializeConversation(conversation, core) });
+        }
+        catch (error) {
+            writeJson(res, resolveErrorStatusCode(error, 500), {
+                success: false,
+                error: String(error?.message || error || 'Unable to start agent conversation.'),
+            });
+        }
+    });
+    addRoute('PATCH', '/api/taskforce/agents/:agentId/conversations/:conversationId', async (req, res, params) => {
+        if (!ensureTaskforceAgentsAccess(req, res))
+            return;
+        try {
+            const body = await parseJsonBody(req);
+            const workspaceId = resolveWorkspaceId(req, body, requestWorkspaceId);
+            const agent = getAgentStore().get(workspaceId, params.agentId);
+            if (!agent) {
+                writeJson(res, 404, { success: false, error: 'Taskforce agent not found.' });
+                return;
+            }
+            const title = normalizeConversationTitle(body?.title);
+            if (!title) {
+                writeJson(res, 400, { success: false, error: 'Chat name is required.' });
+                return;
+            }
+            const conversation = getConversationStore().rename(workspaceId, agent.id, params.conversationId, title, resolveAuthenticatedUserId?.(req) || null);
+            if (!conversation) {
+                writeJson(res, 404, { success: false, error: 'Agent conversation not found.' });
+                return;
+            }
+            writeJson(res, 200, {
+                success: true,
+                conversation: serializeConversation(conversation, core),
+                summary: serializeConversationSummary(conversation, core),
+            });
+        }
+        catch (error) {
+            writeJson(res, resolveErrorStatusCode(error, 500), {
+                success: false,
+                error: String(error?.message || error || 'Unable to rename agent conversation.'),
+            });
+        }
+    });
+    addRoute('POST', '/api/taskforce/agents/model-gateway/test', async (req, res) => {
+        if (!ensureTaskforceAgentsAccess(req, res))
+            return;
+        try {
+            const body = await parseJsonBody(req);
+            const normalizedMessages = normalizeMessages(body?.messages, body?.prompt);
+            if ('error' in normalizedMessages) {
+                writeJson(res, 400, { success: false, error: normalizedMessages.error });
+                return;
+            }
+            const system = normalizeSystemPrompt(body?.system);
+            if (system.length > 4000) {
+                writeJson(res, 400, { success: false, error: 'Agent instructions must be 4,000 characters or less.' });
+                return;
+            }
+            const workspaceId = resolveWorkspaceId(req, body, requestWorkspaceId);
+            const agentId = String(body?.agentId || '').trim();
+            const conversationId = String(body?.conversationId || '').trim() || null;
+            const hasTaskId = Object.prototype.hasOwnProperty.call(body, 'taskId');
+            const hasDraftDefinition = Object.prototype.hasOwnProperty.call(body, 'draftDefinition');
+            const bodyTaskId = hasTaskId ? normalizeTaskId(body?.taskId) : undefined;
+            const actorUserId = resolveAuthenticatedUserId?.(req) || null;
+            let savedAgent = null;
+            let resolvedRuntimeConfiguration = null;
+            let savedConversation = null;
+            if (hasDraftDefinition) {
+                if (agentId || conversationId || hasTaskId) {
+                    writeJson(res, 400, {
+                        success: false,
+                        error: 'Draft Agent tests cannot use saved conversations or task-scoped context.',
+                        code: 'TASKFORCE_AGENT_DRAFT_TEST_NOT_ISOLATED',
+                    });
+                    return;
+                }
+                const inspected = inspectAgentDefinition(body.draftDefinition);
+                if (!inspected.definition || inspected.state !== 'valid') {
+                    writeJson(res, 400, {
+                        success: false,
+                        error: 'The Agent draft contains invalid configuration.',
+                        code: 'INVALID_AGENT_DEFINITION',
+                        configurationState: inspected.state,
+                        configurationIssues: inspected.issues,
+                    });
+                    return;
+                }
+                try {
+                    resolvedRuntimeConfiguration = resolveTaskforceAgentRuntimeConfiguration({
+                        lifecycleStatus: 'active',
+                        configurationState: 'valid',
+                        definition: inspected.definition,
+                    }, resolveRuntimeReferenceResolversForWorkspace(workspaceId));
+                }
+                catch (error) {
+                    if (error instanceof TaskforceAgentRuntimeResolutionError) {
+                        writeJson(res, error.statusCode, {
+                            success: false,
+                            error: error.message,
+                            code: error.code,
+                            configurationState: inspected.state,
+                        });
+                        return;
+                    }
+                    throw error;
+                }
+            }
+            if (agentId) {
+                savedAgent = getAgentStore().get(workspaceId, agentId);
+                if (!savedAgent) {
+                    writeJson(res, 404, { success: false, error: 'Taskforce agent not found.' });
+                    return;
+                }
+                if (typeof savedAgent.definitionRevision === 'number') {
+                    try {
+                        resolvedRuntimeConfiguration = resolveTaskforceAgentRuntimeConfiguration(savedAgent, resolveRuntimeReferenceResolversForWorkspace(workspaceId));
+                    }
+                    catch (error) {
+                        if (error instanceof TaskforceAgentRuntimeResolutionError) {
+                            writeJson(res, error.statusCode, {
+                                success: false,
+                                error: error.message,
+                                code: error.code,
+                                configurationState: savedAgent.configurationState,
+                            });
+                            return;
+                        }
+                        throw error;
+                    }
+                }
+                if (conversationId) {
+                    savedConversation = getConversationStore().getById(workspaceId, savedAgent.id, conversationId);
+                }
+            }
+            const savedConversationTaskId = savedConversation?.taskId ? normalizeTaskId(savedConversation.taskId) : null;
+            const taskId = hasTaskId ? bodyTaskId : savedConversationTaskId;
+            const taskReference = taskId ? normalizeTaskContextValue(body?.taskReference) : '';
+            const taskTitle = taskId ? normalizeTaskContextValue(body?.taskTitle) : '';
+            if (resolvedRuntimeConfiguration) {
+                const definition = resolvedRuntimeConfiguration.definition;
+                const draftDiffers = ((body?.providerKey !== undefined
+                    && String(body.providerKey || '').trim() !== definition.model.providerKey)
+                    || (body?.modelKey !== undefined
+                        && String(body.modelKey || '').trim() !== definition.model.modelKey)
+                    || (body?.modelSource !== undefined
+                        && String(body.modelSource || '').trim() !== definition.model.modelSource)
+                    || (body?.tier !== undefined
+                        && String(body.tier || '').trim().toLowerCase() !== definition.model.tier)
+                    || (body?.system !== undefined
+                        && String(body.system || '').trim() !== (definition.behavior.workingGuidelines || '')));
+                if (draftDiffers) {
+                    writeJson(res, 409, {
+                        success: false,
+                        error: 'Save or reset the Agent draft before running the saved Agent.',
+                        code: 'TASKFORCE_AGENT_UNSAVED_DRAFT',
+                    });
+                    return;
+                }
+            }
+            const providerKey = resolvedRuntimeConfiguration
+                ? resolvedRuntimeConfiguration.definition.model.providerKey
+                : body?.providerKey !== undefined
+                    ? normalizeTaskforceAgentProviderKey(body.providerKey)
+                    : savedAgent?.providerKey || normalizeTaskforceAgentProviderKey(undefined);
+            if (body?.modelKey !== undefined && !String(body.modelKey || '').trim()) {
+                writeJson(res, 400, { success: false, error: 'Select a configured model for this provider.' });
+                return;
+            }
+            const requestedModel = body?.modelKey !== undefined ? getTaskforceAgentModel(body.modelKey) : null;
+            if (requestedModel && !isTaskforceAgentModelVisible(requestedModel)) {
+                writeJson(res, 400, { success: false, error: 'Selected model is not available for this account.' });
+                return;
+            }
+            const modelKey = resolvedRuntimeConfiguration
+                ? resolvedRuntimeConfiguration.definition.model.modelKey
+                : body?.modelKey !== undefined || body?.providerKey !== undefined
+                    ? normalizeTaskforceAgentModelKey(body?.modelKey, providerKey)
+                    : savedAgent?.modelKey || normalizeTaskforceAgentModelKey(undefined, providerKey);
+            if (!modelKey) {
+                writeJson(res, 400, { success: false, error: 'Select a configured model for this provider.' });
+                return;
+            }
+            const model = getTaskforceAgentModel(modelKey);
+            if (!model || !isTaskforceAgentModelVisible(model)) {
+                writeJson(res, 400, { success: false, error: 'Selected model is not available for this account.' });
+                return;
+            }
+            const modelSelection = normalizeTaskforceAgentModelSelection({
+                providerKey,
+                modelKey,
+                modelSource: resolvedRuntimeConfiguration?.definition.model.modelSource ?? body?.modelSource ?? model.source,
+                connectionScope: resolvedRuntimeConfiguration?.definition.model.connectionScope ?? body?.connectionScope,
+                connectionId: resolvedRuntimeConfiguration?.definition.model.connectionId ?? body?.connectionId,
+            });
+            if (!modelSelection) {
+                writeJson(res, 400, { success: false, error: 'Selected model source is not available for this model.' });
+                return;
+            }
+            const gateway = createModelGateway({
+                providerKey: modelSelection.providerKey,
+                modelKey: modelSelection.modelKey,
+                modelSource: modelSelection.modelSource,
+                runtime: model.runtime,
+                workspaceId,
+                actorUserId,
+                connectionScope: modelSelection.connectionScope,
+                connectionId: modelSelection.connectionId,
+            });
+            const runContext = buildTaskforceAgentRunContext({
+                source: 'agent-manager-test',
+                workspaceId,
+                agentId: savedAgent?.id || agentId || null,
+                conversationId,
+                taskId: taskId ?? null,
+                actorUserId,
+            });
+            const resolvedAgentName = String(resolvedRuntimeConfiguration?.definition.name || savedAgent?.name || body?.agentName || '').trim();
+            const agentName = resolvedAgentName || 'Taskforce Agent';
+            const agentSystem = resolvedRuntimeConfiguration
+                ? buildResolvedTaskforceAgentSystemPrompt(resolvedRuntimeConfiguration)
+                : resolvedAgentName
+                    ? buildAgentSystemPrompt(system, resolvedAgentName)
+                    : system;
+            const taskScopeContext = resolveTaskScopeContext(core, workspaceId, {
+                taskId: taskId ?? null,
+                taskReference,
+                taskTitle,
+            });
+            const scopedAgentSystem = buildTaskScopedSystemPrompt(agentSystem, taskScopeContext || {
+                taskId: taskId ?? null,
+                taskReference,
+                taskTitle,
+            });
+            let agentProfileId = null;
+            if (savedAgent && core) {
+                const profile = resolveExactTaskforceAgentProfile(core, savedAgent);
+                agentProfileId = profile?.id || null;
+                if (!agentProfileId) {
+                    writeJson(res, 409, {
+                        success: false,
+                        error: 'This agent profile is not ready. Save the agent and try again.',
+                        code: 'TASKFORCE_AGENT_PROFILE_UNAVAILABLE',
+                    });
+                    return;
+                }
+            }
+            const mcpBridge = await prepareMcpBridge({
+                core,
+                runtimeMode: resolveRuntimeMode(req),
+                workspaceId,
+                actorUserId,
+                agentProfileId,
+                agentName,
+                providerKey: modelSelection.providerKey,
+                modelKey: modelSelection.modelKey,
+                allowedMutationTaskId: taskId ?? null,
+                readOnly: !savedAgent,
+                toolPolicy: resolvedRuntimeConfiguration?.definition.toolPolicy,
+                system: scopedAgentSystem,
+            });
+            const executionSnapshot = savedAgent && resolvedRuntimeConfiguration
+                ? serializeTaskforceAgentExecutionSnapshot({
+                    agentId: savedAgent.id,
+                    definitionRevision: savedAgent.definitionRevision,
+                    definitionHash: savedAgent.definitionHash,
+                    resolved: resolvedRuntimeConfiguration,
+                    modelCatalog: model,
+                    toolNames: mcpBridge?.availableToolNames || [],
+                    toolContractHash: mcpBridge?.toolContractHash
+                        || hashTaskforceAgentMcpToolContract((mcpBridge?.availableToolNames || []).map((name) => ({ name }))),
+                })
+                : null;
+            const gatewayInput = buildModelGatewayInput({
+                tier: resolvedRuntimeConfiguration?.definition.model.tier || normalizeTier(body?.tier),
+                providerKey,
+                modelKey,
+                system: mcpBridge?.system || scopedAgentSystem,
+                messages: toGatewayMessages(normalizedMessages.messages),
+                model,
+                runContext,
+            });
+            let result = await gateway.generate(gatewayInput);
+            const mcpToolResults = [];
+            const unresolvedFailedMutations = new Map();
+            const toolMessages = [...gatewayInput.messages];
+            let requestedToolCall = mcpBridge?.parseToolCall(result.text);
+            const workflowCompletionRequested = Boolean(taskId
+                && mcpBridge?.availableToolNames.includes('complete_workflow_step')
+                && requestsWorkflowStepCompletion(gatewayInput.messages));
+            let workflowCompletionCorrectionSent = false;
+            while (mcpBridge) {
+                if (requestedToolCall) {
+                    if (mcpToolResults.length >= MAX_MCP_TOOL_ITERATIONS)
+                        break;
+                    const blocksWorkflowCompletion = requestedToolCall.name === 'complete_workflow_step'
+                        && unresolvedFailedMutations.size > 0;
+                    const unresolvedMutationNames = [...new Set(unresolvedFailedMutations.values())];
+                    const toolResult = blocksWorkflowCompletion
+                        ? {
+                            name: requestedToolCall.name,
+                            arguments: requestedToolCall.arguments,
+                            ok: false,
+                            text: `Taskforce refused workflow completion because these earlier changes failed: ${unresolvedMutationNames.join(', ')}. Retry the failed changes successfully before completing the step.`,
+                        }
+                        : await mcpBridge.executeToolCall(requestedToolCall);
+                    mcpToolResults.push(toolResult);
+                    if (isTaskforceAgentMutationToolName(toolResult.name)
+                        && toolResult.name !== 'complete_workflow_step') {
+                        const mutationKey = taskforceAgentMutationCallKey(toolResult.name, toolResult.arguments);
+                        if (mutationKey) {
+                            if (toolResult.ok)
+                                unresolvedFailedMutations.delete(mutationKey);
+                            else
+                                unresolvedFailedMutations.set(mutationKey, toolResult.name);
+                        }
+                    }
+                    toolMessages.push({ role: 'assistant', content: result.text }, { role: 'user', content: mcpBridge.buildToolResultMessage(toolResult) });
+                    try {
+                        result = await gateway.generate({
+                            ...gatewayInput,
+                            messages: toolMessages,
+                        });
+                    }
+                    catch (error) {
+                        if (mcpToolResults.some((completedToolResult) => (completedToolResult.name === 'complete_workflow_step' && completedToolResult.ok))) {
+                            result = {
+                                ...result,
+                                text: 'Workflow step completed successfully.',
+                            };
+                            requestedToolCall = null;
+                            break;
+                        }
+                        throw error;
+                    }
+                    requestedToolCall = mcpBridge.parseToolCall(result.text);
+                    continue;
+                }
+                const workflowStepCompleted = mcpToolResults.some((toolResult) => (toolResult.name === 'complete_workflow_step' && toolResult.ok));
+                if (workflowCompletionRequested && !workflowStepCompleted && !workflowCompletionCorrectionSent) {
+                    workflowCompletionCorrectionSent = true;
+                    toolMessages.push({ role: 'assistant', content: result.text }, {
+                        role: 'user',
+                        content: unresolvedFailedMutations.size > 0
+                            ? `The workflow step is not complete because these Taskforce changes failed: ${[...new Set(unresolvedFailedMutations.values())].join(', ')}. Retry those exact changes successfully before calling complete_workflow_step. If they cannot succeed, respond exactly WORKFLOW_STEP_INCOMPLETE: followed by the reason.`
+                            : 'The workflow step is not authoritatively complete. If all required work succeeded, call complete_workflow_step now. Otherwise respond exactly WORKFLOW_STEP_INCOMPLETE: followed by the reason. Do not claim completion without a successful tool result.',
+                    });
+                    result = await gateway.generate({
+                        ...gatewayInput,
+                        messages: toolMessages,
+                    });
+                    requestedToolCall = mcpBridge.parseToolCall(result.text);
+                    continue;
+                }
+                break;
+            }
+            if (requestedToolCall) {
+                throw new Error('Taskforce tool call limit reached before the agent returned a final response.');
+            }
+            if (workflowCompletionRequested && !mcpToolResults.some((toolResult) => (toolResult.name === 'complete_workflow_step' && toolResult.ok))) {
+                const incompletePrefix = 'WORKFLOW_STEP_INCOMPLETE:';
+                const reportedIncompleteReason = result.text.trim().startsWith(incompletePrefix)
+                    ? result.text.trim().slice(incompletePrefix.length).trim()
+                    : '';
+                const incompleteReason = /\b(?:complete|completed|finished)\b/i.test(reportedIncompleteReason)
+                    ? ''
+                    : reportedIncompleteReason;
+                result = {
+                    ...result,
+                    text: incompleteReason
+                        ? `Workflow step remains incomplete. ${incompleteReason}`
+                        : 'Taskforce could not confirm workflow step completion. Review Tool Activity and retry; the workflow state may have changed.',
+                };
+            }
+            const serializedResult = serializeModelGatewayResult(result);
+            const workflowCompletion = (deps.resolveWorkflowCompletionProjection || serializeWorkflowCompletionProjection)(core, workspaceId, taskId ?? null, mcpToolResults);
+            const assistantContent = result.text.trim() || (mcpToolResults.length > 0
+                ? mcpToolResults.some((toolResult) => !toolResult.ok)
+                    ? 'One or more Taskforce actions failed.'
+                    : 'Taskforce actions completed.'
+                : '');
+            const assistantMessage = assistantContent
+                ? {
+                    role: 'assistant',
+                    content: assistantContent,
+                    ...(savedAgent ? { agentId: savedAgent.id } : {}),
+                    agentName,
+                    providerKey,
+                    providerLabel: labelForTaskforceAgentProvider(providerKey),
+                    modelKey,
+                    modelLabel: labelForTaskforceAgentModel(modelKey),
+                    modelId: result.modelId,
+                    ...(mcpToolResults.length > 0 ? {
+                        toolActivity: mcpToolResults.map((toolResult) => ({
+                            name: toolResult.name,
+                            arguments: toolResult.arguments,
+                            ok: toolResult.ok,
+                            resultText: toolResult.text,
+                        })),
+                    } : {}),
+                }
+                : null;
+            const conversation = savedAgent
+                ? getConversationStore().save({
+                    workspaceId,
+                    agentId: savedAgent.id,
+                    conversationId,
+                    ...(taskId || hasTaskId ? { taskId: taskId || null } : {}),
+                    messages: assistantMessage
+                        ? [...normalizedMessages.messages, assistantMessage]
+                        : normalizedMessages.messages,
+                    modelProvider: result.provider,
+                    modelId: result.modelId,
+                    usage: result.usage || null,
+                    latencyMs: result.latencyMs ?? null,
+                    actorUserId,
+                })
+                : null;
+            writeJson(res, 200, {
+                success: true,
+                result: serializedResult,
+                runContext,
+                ...(executionSnapshot ? { executionSnapshot } : {}),
+                ...(mcpToolResults.length > 0 ? {
+                    mcpToolCalls: mcpToolResults.map(serializeTaskforceAgentMcpToolResult),
+                } : {}),
+                ...(workflowCompletion ? { workflowCompletion } : {}),
+                conversation: serializeConversation(conversation, core),
+            });
+        }
+        catch (error) {
+            const errorCode = String(error?.code || '').trim();
+            writeJson(res, resolveErrorStatusCode(error, 500), {
+                success: false,
+                error: formatModelGatewayError(error),
+                ...(errorCode ? { code: errorCode } : {}),
+            });
+        }
+    });
+}