@taskforcehq/taskforce 0.3.328 → 0.3.330

package/dist/server/routes/agents.js

@@ -6,15 +6,23 @@
  *   POST   /api/taskforce/agents
  *   PATCH  /api/taskforce/agents/:agentId
  *   DELETE /api/taskforce/agents/:agentId
+ *   GET    /api/taskforce/agents/:agentId/connection-binding
+ *   PUT    /api/taskforce/agents/:agentId/connection-binding
+ *   DELETE /api/taskforce/agents/:agentId/connection-binding
  *   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 { createHash } from 'node:crypto';
 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 { CodexAppServerModelGateway } from '../../services/codexAppServerModelGateway.js';
+import { OwnerScopedModelConnectionGateway } from '../../services/ownerScopedModelConnectionGateway.js';
+import { ModelProviderConnectionService } from '../../services/modelProviderConnectionService.js';
+import { ModelProviderCredentialHomeManager } from '../../services/modelProviderCredentialHome.js';
 import { saveAiProfileAvatarAssets } from '../aiProfileAvatarAssets.js';
 import { ModelGatewayConfigurationError, normalizePersistedModelGatewayMessages } from '../../services/modelGateway.js';
 import { BedrockAvatarImageProvider, buildTaskforceAgentAvatarPrompt, } from '../../services/taskforceAgentAvatarImageProvider.js';
@@ -22,13 +30,18 @@ import { hashTaskforceAgentMcpToolContract, isTaskforceAgentMutationToolName, pr
 import { TaskforceAgentConversationStore } from '../../storage/taskforceAgentConversationStore.js';
 import { TaskforceAgentDefinitionConflictError, TaskforceAgentStore, } from '../../storage/taskforceAgentStore.js';
 import { TaskforceAgentSkillStore } from '../../storage/taskforceAgentSkillStore.js';
+import { ModelProviderConnectionError, ModelProviderConnectionStore, } from '../../storage/modelProviderConnectionStore.js';
+import { TaskforceAgentConnectionBindingStore } from '../../storage/taskforceAgentConnectionBindingStore.js';
+import { TaskforceAgentConnectionBindingError, TaskforceAgentConnectionBindingService, } from '../../services/taskforceAgentConnectionBindingService.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 { TASKFORCE_AGENTS_WORKSPACE_FEATURE_KEY, } from '../../runtime/appGates.js';
+import { resolveNodeAppGateAccess } from '../../runtime/nodeAppGates.js';
+import { DEFAULT_TASKFORCE_AGENT_MODEL_KEY, DEFAULT_TASKFORCE_AGENT_PROVIDER_KEY, TASKFORCE_AGENT_MODEL_OPTIONS, getTaskforceAgentModel, isTaskforceAgentModelVisible, labelForTaskforceAgentModel, labelForTaskforceAgentProvider, normalizeTaskforceAgentModelKey, normalizeTaskforceAgentModelSelection, normalizeTaskforceAgentProviderKey, } from '../../shared/taskforceAgentModels.js';
+import { INTERNAL_SUBSCRIPTION_MODEL_FEATURE_KEY } from '../../shared/userFeatureGrants.js';
 import { buildTaskforceAgentRunContext } from '../../shared/taskforceAgentRunContext.js';
-import { inspectAgentDefinition } from '../../shared/taskforceAgentDefinition.js';
+import { inspectAgentDefinition, serializeCanonicalJson } from '../../shared/taskforceAgentDefinition.js';
 import { buildResolvedTaskforceAgentSystemPrompt, resolveTaskforceAgentRuntimeConfiguration, TaskforceAgentRuntimeResolutionError, } from '../../shared/taskforceAgentRuntimeResolution.js';
 import { serializeTaskforceAgentExecutionSnapshot } from '../../shared/taskforceAgentExecutionSnapshot.js';
 import { getTaskReferenceLabel } from '../../utils/taskReferences.js';
@@ -113,6 +126,11 @@ function normalizeMessages(value, fallbackPrompt) {
         return { error: 'Prompt must be 4,000 characters or less.' };
     return { messages: [{ role: 'user', content: prompt }] };
 }
+function buildManagedAgentExecutionRequestId(input) {
+    return createHash('sha256')
+        .update(serializeCanonicalJson(input))
+        .digest('hex');
+}
 function toGatewayMessages(messages) {
     return messages.map((message) => ({
         role: message.role,
@@ -122,7 +140,13 @@ function toGatewayMessages(messages) {
 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);
+    return /^(?:(?:hey|hi|hello)\b[^,!?]{0,80},?\s+)?(?: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(?:\s+(?:on|for)\s+(?:task\s+)?(?:t-\d+|[a-z0-9][a-z0-9-]{0,119}))?[.!?]*$/.test(content);
+}
+function extractLatestExplicitTaskReference(messages) {
+    const latestUserMessage = [...messages].reverse().find((message) => message.role === 'user');
+    const matches = String(latestUserMessage?.content || '').match(/\bT-\d+\b/gi) || [];
+    const references = [...new Set(matches.map((match) => match.toUpperCase()))];
+    return references.length === 1 ? references[0] : null;
 }
 function normalizeTaskId(value) {
     const taskId = String(value || '').trim();
@@ -144,6 +168,18 @@ function resolveTaskContextTask(core, workspaceId, taskId) {
     return core.getTask(taskId, workspaceId)
         || (typeof core.resolveTaskIdentifier === 'function' ? core.resolveTaskIdentifier(taskId, workspaceId) : null);
 }
+function workflowToolCallsTargetSameTask(core, workspaceId, left, right) {
+    const resolveCanonicalId = (value) => {
+        const taskId = normalizeTaskId(value);
+        if (!taskId)
+            return null;
+        const task = resolveTaskContextTask(core, workspaceId, taskId);
+        return normalizeTaskId(task?.id)?.toLowerCase() || taskId.toLowerCase();
+    };
+    const leftTaskId = resolveCanonicalId(left);
+    const rightTaskId = resolveCanonicalId(right);
+    return Boolean(leftTaskId && rightTaskId && leftTaskId === rightTaskId);
+}
 function resolveTaskScopeContext(core, workspaceId, input) {
     const taskId = String(input.taskId || '').trim();
     if (!taskId)
@@ -196,6 +232,7 @@ function serializeModelGatewayResult(result) {
         stopReason: result.stopReason || null,
         latencyMs: result.latencyMs ?? null,
         usage: result.usage || null,
+        ...(result.sourceMetadata ? { sourceMetadata: result.sourceMetadata } : {}),
     };
 }
 export function serializeWorkflowCompletionProjection(core, workspaceId, _taskId, toolResults) {
@@ -237,13 +274,33 @@ export function serializeWorkflowCompletionProjection(core, workspaceId, _taskId
         taskAuthoritative,
     };
 }
-function createDefaultModelGateway(selection) {
+function createDefaultModelGateway(selection, connectionService) {
     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 === 'subscription_dev' && runtime === 'subscription-dev') {
+        if (selection?.connectionScope === 'personal'
+            || (selection?.connectionScope === 'local_dev' && selection.connectionId)) {
+            const connectionId = String(selection.connectionId || '').trim();
+            const ownerUserId = String(selection.connectionOwnerUserId || '').trim();
+            if (!connectionService || !connectionId || !ownerUserId) {
+                throw new ModelGatewayConfigurationError('A verified personal model connection is required.', 'MODEL_PROVIDER_CONNECTION_REQUIRED');
+            }
+            return new OwnerScopedModelConnectionGateway(connectionService, ownerUserId, connectionId, (context) => new CodexAppServerModelGateway({
+                env: context.environment,
+                credentialPaths: context.environment.CODEX_HOME
+                    ? [context.environment.CODEX_HOME]
+                    : [],
+            }));
+        }
+        if (selection?.connectionScope !== 'local_dev') {
+            throw new ModelGatewayConfigurationError('A personal model connection is required.', 'MODEL_PROVIDER_CONNECTION_REQUIRED');
+        }
+        return new CodexAppServerModelGateway();
+    }
     if (source !== 'bedrock') {
         throw new ModelGatewayConfigurationError('Selected model source is not configured yet.', 'MODEL_SOURCE_NOT_IMPLEMENTED');
     }
@@ -576,7 +633,7 @@ function resolveWorkspaceId(req, body, requestWorkspaceId) {
     }
     return authoritativeWorkspaceId || requestedWorkspaceId || 'default';
 }
-function validateAgentInput(body, workspaceId, actorUserId) {
+function validateAgentInput(body, workspaceId, actorUserId, isModelVisible = isTaskforceAgentModelVisible) {
     const name = String(body?.name || '').trim();
     if (!name)
         return { error: 'Agent name is required.' };
@@ -587,10 +644,14 @@ function validateAgentInput(body, workspaceId, actorUserId) {
         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)) {
+    if (requestedModel && !isModelVisible(requestedModel)) {
         return { error: 'Selected model is not available for this account.' };
     }
-    const modelKey = normalizeTaskforceAgentModelKey(body?.modelKey || DEFAULT_TASKFORCE_AGENT_MODEL_KEY, providerKey);
+    const modelKey = requestedModel
+        && requestedModel.providerKey === providerKey
+        && isModelVisible(requestedModel)
+        ? requestedModel.key
+        : normalizeTaskforceAgentModelKey(body?.modelKey || DEFAULT_TASKFORCE_AGENT_MODEL_KEY, providerKey);
     if (!modelKey)
         return { error: 'Select a configured model for this provider.' };
     return {
@@ -632,10 +693,13 @@ function canonicalMutationError(error) {
     };
 }
 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;
+    const { addRoute, ensureAppAccess, core, requestWorkspaceId, resolveAuthenticatedUserId, resolveRuntimeMode = () => 'local', ensureWorkspaceAdminRole, agentStore, skillStore, conversationStore, connectionBindingService, createModelGateway, prepareMcpBridge = prepareTaskforceAgentMcpBridge, aiProfileAvatarAssetDeps, avatarImageProvider, saveAiProfileAvatarAssets: saveAvatarAssets = saveAiProfileAvatarAssets, agentRuntimeReferenceResolvers, agentRuntimeReferenceResolversForWorkspace, } = deps;
     let resolvedAgentStore = agentStore || null;
     let resolvedSkillStore = skillStore || null;
     let resolvedConversationStore = conversationStore || null;
+    let resolvedConnectionBindingService = connectionBindingService || null;
+    let resolvedModelConnectionService = deps.modelConnectionService || null;
+    let resolvedCredentialHomeManager = null;
     let resolvedAvatarImageProvider = avatarImageProvider || null;
     const getAgentStore = () => {
         if (resolvedAgentStore)
@@ -661,6 +725,66 @@ export function registerAgentsRoutes(deps) {
         resolvedSkillStore = new TaskforceAgentSkillStore(core.getDatabaseAdapter(), core.getTenantId());
         return resolvedSkillStore;
     };
+    const getModelConnectionService = () => {
+        if (resolvedModelConnectionService)
+            return resolvedModelConnectionService;
+        if (!core)
+            throw new Error('Model connection service is unavailable.');
+        resolvedCredentialHomeManager ||= new ModelProviderCredentialHomeManager();
+        resolvedModelConnectionService = new ModelProviderConnectionService(new ModelProviderConnectionStore(core.getDatabaseAdapter(), core.getTenantId()), resolvedCredentialHomeManager, (userId) => core.hasUserFeatureGrant(userId, INTERNAL_SUBSCRIPTION_MODEL_FEATURE_KEY));
+        return resolvedModelConnectionService;
+    };
+    const getConnectionBindingService = () => {
+        if (resolvedConnectionBindingService)
+            return resolvedConnectionBindingService;
+        if (!core)
+            throw new Error('Agent connection binding service is unavailable.');
+        resolvedConnectionBindingService = new TaskforceAgentConnectionBindingService(new TaskforceAgentConnectionBindingStore(core.getDatabaseAdapter(), core.getTenantId()), getAgentStore(), new ModelProviderConnectionStore(core.getDatabaseAdapter(), core.getTenantId()), getModelConnectionService(), (userId) => core.hasUserFeatureGrant(userId, INTERNAL_SUBSCRIPTION_MODEL_FEATURE_KEY));
+        return resolvedConnectionBindingService;
+    };
+    const buildModelGateway = (selection) => {
+        if (createModelGateway)
+            return createModelGateway(selection);
+        const needsPersonalConnection = selection?.modelSource === 'subscription_dev'
+            && Boolean(selection.connectionId);
+        return createDefaultModelGateway(selection, needsPersonalConnection ? getModelConnectionService() : undefined);
+    };
+    const authorizeConnectionBindingRequest = (req, res) => {
+        if (resolveRuntimeMode(req) !== 'cloud') {
+            writeJson(res, 404, {
+                success: false,
+                error: 'Agent connection bindings are unavailable in this runtime.',
+                code: 'AGENT_CONNECTION_BINDINGS_CLOUD_ONLY',
+            });
+            return null;
+        }
+        const actorUserId = String(resolveAuthenticatedUserId?.(req) || '').trim();
+        if (!actorUserId) {
+            writeJson(res, 401, {
+                success: false,
+                error: 'Authentication is required.',
+                code: 'AUTH_REQUIRED',
+            });
+            return null;
+        }
+        return actorUserId;
+    };
+    const writeConnectionBindingError = (res, error) => {
+        if (error instanceof TaskforceAgentConnectionBindingError
+            || error instanceof ModelProviderConnectionError) {
+            writeJson(res, error.statusCode, {
+                success: false,
+                error: error.message,
+                code: error.code,
+            });
+            return;
+        }
+        writeJson(res, 500, {
+            success: false,
+            error: 'Agent connection request failed.',
+            code: 'AGENT_CONNECTION_REQUEST_FAILED',
+        });
+    };
     const resolveRuntimeReferenceResolversForWorkspace = (workspaceId) => {
         const baseResolvers = agentRuntimeReferenceResolversForWorkspace?.(workspaceId)
             || agentRuntimeReferenceResolvers
@@ -693,7 +817,7 @@ export function registerAgentsRoutes(deps) {
     const ensureTaskforceAgentsAccess = (req, res) => {
         if (!ensureAppAccess(req, res))
             return false;
-        const gate = resolveAppGateAccess(TASKFORCE_AGENTS_WORKSPACE_FEATURE_KEY);
+        const gate = resolveNodeAppGateAccess(TASKFORCE_AGENTS_WORKSPACE_FEATURE_KEY);
         if (gate.allowed)
             return true;
         writeJson(res, 403, {
@@ -703,6 +827,34 @@ export function registerAgentsRoutes(deps) {
         });
         return false;
     };
+    const isModelVisibleForRequest = (req, model) => {
+        if (resolveRuntimeMode(req) !== 'cloud' || model.source !== 'subscription_dev') {
+            return isTaskforceAgentModelVisible(model);
+        }
+        const actorUserId = resolveAuthenticatedUserId?.(req) || null;
+        return Boolean(model.visible
+            && model.availability !== 'account_unavailable'
+            && actorUserId
+            && core?.hasUserFeatureGrant(actorUserId, INTERNAL_SUBSCRIPTION_MODEL_FEATURE_KEY));
+    };
+    const isModelPersistableForRequest = (req, model) => {
+        if (resolveRuntimeMode(req) === 'local' && model.source === 'subscription_dev') {
+            return model.visible && model.availability !== 'account_unavailable';
+        }
+        return isModelVisibleForRequest(req, model);
+    };
+    const ensureDefinitionModelAccess = (req, res, definition) => {
+        const modelKey = String(definition?.model?.modelKey || '').trim();
+        const model = getTaskforceAgentModel(modelKey);
+        if (!model || isModelPersistableForRequest(req, model))
+            return true;
+        writeJson(res, model.source === 'subscription_dev' ? 403 : 400, {
+            success: false,
+            error: 'Selected model is not available for this account.',
+            code: model.source === 'subscription_dev' ? 'SUBSCRIPTION_MODEL_ACCESS_REQUIRED' : 'MODEL_UNAVAILABLE',
+        });
+        return false;
+    };
     addRoute('GET', '/api/taskforce/agents', async (req, res) => {
         if (!ensureTaskforceAgentsAccess(req, res))
             return;
@@ -716,7 +868,8 @@ export function registerAgentsRoutes(deps) {
                 const profile = profileMap.get(agent.id) || null;
                 return serializeAgent(persistManagedProfileLink(agent, profile, actorUserId), profile);
             });
-            writeJson(res, 200, { success: true, agents });
+            const modelCatalog = TASKFORCE_AGENT_MODEL_OPTIONS.filter((model) => isModelVisibleForRequest(req, model));
+            writeJson(res, 200, { success: true, agents, modelCatalog });
         }
         catch (error) {
             writeJson(res, resolveErrorStatusCode(error, 500), {
@@ -725,6 +878,80 @@ export function registerAgentsRoutes(deps) {
             });
         }
     });
+    addRoute('GET', '/api/taskforce/agents/model-catalog', async (req, res) => {
+        if (!ensureTaskforceAgentsAccess(req, res))
+            return;
+        const modelCatalog = TASKFORCE_AGENT_MODEL_OPTIONS.filter((model) => isModelVisibleForRequest(req, model));
+        writeJson(res, 200, { success: true, modelCatalog });
+    });
+    addRoute('GET', '/api/taskforce/agents/:agentId/connection-binding', async (req, res, params) => {
+        if (!ensureTaskforceAgentsAccess(req, res))
+            return;
+        const actorUserId = authorizeConnectionBindingRequest(req, res);
+        if (!actorUserId)
+            return;
+        try {
+            const workspaceId = resolveWorkspaceId(req, undefined, requestWorkspaceId);
+            const binding = getConnectionBindingService().inspect({
+                workspaceId,
+                agentId: params.agentId,
+                callerUserId: actorUserId,
+            });
+            writeJson(res, 200, { success: true, binding });
+        }
+        catch (error) {
+            writeConnectionBindingError(res, error);
+        }
+    });
+    addRoute('PUT', '/api/taskforce/agents/:agentId/connection-binding', async (req, res, params) => {
+        if (!ensureTaskforceAgentsAccess(req, res))
+            return;
+        const actorUserId = authorizeConnectionBindingRequest(req, res);
+        if (!actorUserId)
+            return;
+        try {
+            const body = await parseJsonBody(req, 16 * 1024);
+            const workspaceId = resolveWorkspaceId(req, body, requestWorkspaceId);
+            await getConnectionBindingService().bind({
+                workspaceId,
+                agentId: params.agentId,
+                connectionId: String(body?.connectionId || ''),
+                actorUserId,
+            });
+            const binding = getConnectionBindingService().inspect({
+                workspaceId,
+                agentId: params.agentId,
+                callerUserId: actorUserId,
+            });
+            writeJson(res, 200, { success: true, binding });
+        }
+        catch (error) {
+            writeConnectionBindingError(res, error);
+        }
+    });
+    addRoute('DELETE', '/api/taskforce/agents/:agentId/connection-binding', async (req, res, params) => {
+        if (!ensureTaskforceAgentsAccess(req, res))
+            return;
+        const actorUserId = authorizeConnectionBindingRequest(req, res);
+        if (!actorUserId)
+            return;
+        try {
+            const body = await parseJsonBody(req, 16 * 1024);
+            const workspaceId = resolveWorkspaceId(req, body, requestWorkspaceId);
+            getConnectionBindingService().clear({
+                workspaceId,
+                agentId: params.agentId,
+                actorUserId,
+            });
+            writeJson(res, 200, {
+                success: true,
+                binding: { bound: false, available: false },
+            });
+        }
+        catch (error) {
+            writeConnectionBindingError(res, error);
+        }
+    });
     addRoute('POST', '/api/taskforce/agents', async (req, res) => {
         if (!ensureTaskforceAgentsAccess(req, res))
             return;
@@ -739,6 +966,8 @@ export function registerAgentsRoutes(deps) {
             }
             let agent;
             if (Object.prototype.hasOwnProperty.call(body, 'definition')) {
+                if (!ensureDefinitionModelAccess(req, res, body.definition))
+                    return;
                 if (body.lifecycleStatus !== undefined
                     && body.lifecycleStatus !== 'active'
                     && body.lifecycleStatus !== 'disabled') {
@@ -757,7 +986,7 @@ export function registerAgentsRoutes(deps) {
                 });
             }
             else {
-                const input = validateAgentInput(body, workspaceId, actorUserId);
+                const input = validateAgentInput(body, workspaceId, actorUserId, (model) => isModelPersistableForRequest(req, model));
                 if ('error' in input) {
                     writeJson(res, 400, { success: false, error: input.error });
                     return;
@@ -794,6 +1023,8 @@ export function registerAgentsRoutes(deps) {
             }
             let agent;
             if (Object.prototype.hasOwnProperty.call(body, 'definition')) {
+                if (!ensureDefinitionModelAccess(req, res, body.definition))
+                    return;
                 if (body.lifecycleStatus !== undefined
                     && body.lifecycleStatus !== 'active'
                     && body.lifecycleStatus !== 'disabled') {
@@ -823,7 +1054,7 @@ export function registerAgentsRoutes(deps) {
                 }
             }
             else {
-                const input = validateAgentInput(body, workspaceId, actorUserId);
+                const input = validateAgentInput(body, workspaceId, actorUserId, (model) => isModelPersistableForRequest(req, model));
                 if ('error' in input) {
                     writeJson(res, 400, { success: false, error: input.error });
                     return;
@@ -1124,7 +1355,11 @@ export function registerAgentsRoutes(deps) {
             if (agentId) {
                 savedAgent = getAgentStore().get(workspaceId, agentId);
                 if (!savedAgent) {
-                    writeJson(res, 404, { success: false, error: 'Taskforce agent not found.' });
+                    writeJson(res, 409, {
+                        success: false,
+                        error: 'This Agent is not available in Taskforce Cloud yet. Wait for synchronization and try again.',
+                        code: 'AGENT_NOT_AVAILABLE_IN_CLOUD',
+                    });
                     return;
                 }
                 if (typeof savedAgent.definitionRevision === 'number') {
@@ -1149,9 +1384,30 @@ export function registerAgentsRoutes(deps) {
                 }
             }
             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) : '';
+            const explicitTaskReference = extractLatestExplicitTaskReference(normalizedMessages.messages);
+            const explicitTask = explicitTaskReference
+                ? resolveTaskContextTask(core, workspaceId, explicitTaskReference)
+                : null;
+            if (explicitTaskReference
+                && !explicitTask
+                && requestsWorkflowStepCompletion(normalizedMessages.messages)) {
+                writeJson(res, 404, {
+                    success: false,
+                    error: `Task ${explicitTaskReference} was not found.`,
+                    code: 'TASK_NOT_FOUND',
+                });
+                return;
+            }
+            const taskId = normalizeTaskId(explicitTask?.id)
+                || (explicitTaskReference ? null : hasTaskId ? bodyTaskId : savedConversationTaskId);
+            const taskReference = taskId
+                ? normalizeTaskContextValue(getTaskReferenceLabel(explicitTask)
+                    || (explicitTask ? explicitTaskReference : null)
+                    || body?.taskReference)
+                : '';
+            const taskTitle = taskId
+                ? normalizeTaskContextValue(explicitTask?.title || body?.taskTitle)
+                : '';
             if (resolvedRuntimeConfiguration) {
                 const definition = resolvedRuntimeConfiguration.definition;
                 const draftDiffers = ((body?.providerKey !== undefined
@@ -1183,22 +1439,38 @@ export function registerAgentsRoutes(deps) {
                 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.' });
+            if (requestedModel && !isModelVisibleForRequest(req, requestedModel)) {
+                writeJson(res, requestedModel.source === 'subscription_dev' ? 403 : 400, {
+                    success: false,
+                    error: 'Selected model is not available for this account.',
+                    code: requestedModel.source === 'subscription_dev' ? 'SUBSCRIPTION_MODEL_ACCESS_REQUIRED' : 'MODEL_UNAVAILABLE',
+                });
                 return;
             }
-            const modelKey = resolvedRuntimeConfiguration
-                ? resolvedRuntimeConfiguration.definition.model.modelKey
-                : body?.modelKey !== undefined || body?.providerKey !== undefined
-                    ? normalizeTaskforceAgentModelKey(body?.modelKey, providerKey)
-                    : savedAgent?.modelKey || normalizeTaskforceAgentModelKey(undefined, providerKey);
+            let modelKey;
+            if (resolvedRuntimeConfiguration) {
+                modelKey = resolvedRuntimeConfiguration.definition.model.modelKey;
+            }
+            else if (requestedModel && requestedModel.providerKey === providerKey) {
+                modelKey = requestedModel.key;
+            }
+            else if (body?.modelKey !== undefined || body?.providerKey !== undefined) {
+                modelKey = normalizeTaskforceAgentModelKey(body?.modelKey, providerKey);
+            }
+            else {
+                modelKey = 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.' });
+            if (!model || !isModelVisibleForRequest(req, model)) {
+                writeJson(res, model?.source === 'subscription_dev' ? 403 : 400, {
+                    success: false,
+                    error: 'Selected model is not available for this account.',
+                    code: model?.source === 'subscription_dev' ? 'SUBSCRIPTION_MODEL_ACCESS_REQUIRED' : 'MODEL_UNAVAILABLE',
+                });
                 return;
             }
             const modelSelection = normalizeTaskforceAgentModelSelection({
@@ -1206,21 +1478,55 @@ export function registerAgentsRoutes(deps) {
                 modelKey,
                 modelSource: resolvedRuntimeConfiguration?.definition.model.modelSource ?? body?.modelSource ?? model.source,
                 connectionScope: resolvedRuntimeConfiguration?.definition.model.connectionScope ?? body?.connectionScope,
-                connectionId: resolvedRuntimeConfiguration?.definition.model.connectionId ?? body?.connectionId,
+                connectionId: body?.connectionId,
             });
             if (!modelSelection) {
                 writeJson(res, 400, { success: false, error: 'Selected model source is not available for this model.' });
                 return;
             }
-            const gateway = createModelGateway({
+            let runtimeConnectionId = null;
+            let runtimeConnectionOwnerUserId = null;
+            if (modelSelection.modelSource === 'subscription_dev'
+                && (modelSelection.connectionScope === 'personal'
+                    || (modelSelection.connectionScope === 'local_dev' && resolveRuntimeMode(req) === 'cloud'))) {
+                if (!actorUserId) {
+                    writeJson(res, 401, {
+                        success: false,
+                        error: 'Authentication is required.',
+                        code: 'AUTH_REQUIRED',
+                    });
+                    return;
+                }
+                const resolvedBinding = savedAgent
+                    ? getConnectionBindingService().resolveSaved({
+                        workspaceId,
+                        agentId: savedAgent.id,
+                        callerUserId: actorUserId,
+                    })
+                    : null;
+                const resolvedConnection = resolvedBinding?.connection
+                    || getConnectionBindingService().resolveDraft({
+                        callerUserId: actorUserId,
+                        connectionId: modelSelection.connectionId || '',
+                        providerKey: modelSelection.providerKey,
+                    });
+                runtimeConnectionId = resolvedConnection.id;
+                runtimeConnectionOwnerUserId = resolvedBinding?.binding.ownerUserId || actorUserId;
+            }
+            const gateway = buildModelGateway({
                 providerKey: modelSelection.providerKey,
                 modelKey: modelSelection.modelKey,
                 modelSource: modelSelection.modelSource,
                 runtime: model.runtime,
                 workspaceId,
                 actorUserId,
-                connectionScope: modelSelection.connectionScope,
-                connectionId: modelSelection.connectionId,
+                ...(modelSelection.connectionScope
+                    ? { connectionScope: modelSelection.connectionScope }
+                    : {}),
+                ...(runtimeConnectionId ? { connectionId: runtimeConnectionId } : {}),
+                ...(runtimeConnectionOwnerUserId
+                    ? { connectionOwnerUserId: runtimeConnectionOwnerUserId }
+                    : {}),
             });
             const runContext = buildTaskforceAgentRunContext({
                 source: 'agent-manager-test',
@@ -1272,6 +1578,13 @@ export function registerAgentsRoutes(deps) {
                 allowedMutationTaskId: taskId ?? null,
                 readOnly: !savedAgent,
                 toolPolicy: resolvedRuntimeConfiguration?.definition.toolPolicy,
+                executionRequestId: buildManagedAgentExecutionRequestId({
+                    workspaceId,
+                    agentId: savedAgent?.id || agentId || null,
+                    conversationId,
+                    taskId: taskId ?? null,
+                    messages: normalizedMessages.messages,
+                }),
                 system: scopedAgentSystem,
             });
             const executionSnapshot = savedAgent && resolvedRuntimeConfiguration
@@ -1304,21 +1617,40 @@ export function registerAgentsRoutes(deps) {
                 && mcpBridge?.availableToolNames.includes('complete_workflow_step')
                 && requestsWorkflowStepCompletion(gatewayInput.messages));
             let workflowCompletionCorrectionSent = false;
+            let reservedWorkflowCompletionUsed = false;
             while (mcpBridge) {
                 if (requestedToolCall) {
-                    if (mcpToolResults.length >= MAX_MCP_TOOL_ITERATIONS)
+                    const activeToolCall = requestedToolCall;
+                    const workflowStepAlreadyCompleted = mcpToolResults.some((toolResult) => (toolResult.name === 'complete_workflow_step' && toolResult.ok));
+                    const workflowStepLoaded = activeToolCall.name === 'complete_workflow_step'
+                        && mcpToolResults.some((toolResult) => (toolResult.name === 'get_task_workflow'
+                            && toolResult.ok
+                            && workflowToolCallsTargetSameTask(core, workspaceId, toolResult.arguments?.taskId, activeToolCall.arguments?.taskId)));
+                    const canUseReservedWorkflowCompletion = Boolean(workflowCompletionRequested
+                        && !workflowStepAlreadyCompleted
+                        && !reservedWorkflowCompletionUsed
+                        && activeToolCall.name === 'complete_workflow_step'
+                        && workflowStepLoaded
+                        && unresolvedFailedMutations.size === 0);
+                    if (mcpToolResults.length >= MAX_MCP_TOOL_ITERATIONS
+                        && !canUseReservedWorkflowCompletion)
                         break;
-                    const blocksWorkflowCompletion = requestedToolCall.name === 'complete_workflow_step'
-                        && unresolvedFailedMutations.size > 0;
+                    if (mcpToolResults.length >= MAX_MCP_TOOL_ITERATIONS) {
+                        reservedWorkflowCompletionUsed = true;
+                    }
+                    const blocksWorkflowCompletion = activeToolCall.name === 'complete_workflow_step'
+                        && (!workflowStepLoaded || unresolvedFailedMutations.size > 0);
                     const unresolvedMutationNames = [...new Set(unresolvedFailedMutations.values())];
                     const toolResult = blocksWorkflowCompletion
                         ? {
-                            name: requestedToolCall.name,
-                            arguments: requestedToolCall.arguments,
+                            name: activeToolCall.name,
+                            arguments: activeToolCall.arguments,
                             ok: false,
-                            text: `Taskforce refused workflow completion because these earlier changes failed: ${unresolvedMutationNames.join(', ')}. Retry the failed changes successfully before completing the step.`,
+                            text: !workflowStepLoaded
+                                ? 'Taskforce refused workflow completion because the current workflow step was not loaded successfully. Call get_task_workflow first, perform its instructions, then retry completion.'
+                                : `Taskforce refused workflow completion because these earlier changes failed: ${unresolvedMutationNames.join(', ')}. Retry the failed changes successfully before completing the step.`,
                         }
-                        : await mcpBridge.executeToolCall(requestedToolCall);
+                        : await mcpBridge.executeToolCall(activeToolCall);
                     mcpToolResults.push(toolResult);
                     if (isTaskforceAgentMutationToolName(toolResult.name)
                         && toolResult.name !== 'complete_workflow_step') {
@@ -1349,6 +1681,17 @@ export function registerAgentsRoutes(deps) {
                         throw error;
                     }
                     requestedToolCall = mcpBridge.parseToolCall(result.text);
+                    if (toolResult.name === 'complete_workflow_step'
+                        && toolResult.ok
+                        && requestedToolCall
+                        && mcpToolResults.length >= MAX_MCP_TOOL_ITERATIONS) {
+                        result = {
+                            ...result,
+                            text: 'Workflow step completed successfully.',
+                        };
+                        requestedToolCall = null;
+                        break;
+                    }
                     continue;
                 }
                 const workflowStepCompleted = mcpToolResults.some((toolResult) => (toolResult.name === 'complete_workflow_step' && toolResult.ok));
@@ -1358,7 +1701,7 @@ export function registerAgentsRoutes(deps) {
                         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.',
+                            : 'The workflow step is not authoritatively complete. Call get_task_workflow first if it has not succeeded in this response, perform the returned step instructions, then call complete_workflow_step. Otherwise respond exactly WORKFLOW_STEP_INCOMPLETE: followed by the reason. Do not claim completion without successful tool results.',
                     });
                     result = await gateway.generate({
                         ...gatewayInput,
@@ -1370,7 +1713,19 @@ export function registerAgentsRoutes(deps) {
                 break;
             }
             if (requestedToolCall) {
-                throw new Error('Taskforce tool call limit reached before the agent returned a final response.');
+                mcpToolResults.push({
+                    name: requestedToolCall.name,
+                    arguments: requestedToolCall.arguments,
+                    ok: false,
+                    text: 'Taskforce did not execute this call because the per-message tool limit was reached.',
+                });
+                result = {
+                    ...result,
+                    text: workflowCompletionRequested
+                        ? 'WORKFLOW_STEP_INCOMPLETE: Taskforce reached the per-message tool limit before finishing the workflow step. Review Tool Activity and retry.'
+                        : 'Taskforce reached the per-message tool limit. Review Tool Activity and retry.',
+                };
+                requestedToolCall = null;
             }
             if (workflowCompletionRequested && !mcpToolResults.some((toolResult) => (toolResult.name === 'complete_workflow_step' && toolResult.ok))) {
                 const incompletePrefix = 'WORKFLOW_STEP_INCOMPLETE:';