@taskforcehq/taskforce 0.3.329 → 0.3.332

package/dist/server/routes/agents.js

@@ -6,6 +6,9 @@
  *   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
@@ -17,6 +20,9 @@ import { BedrockAnthropicMessagesModelGateway } from '../../services/bedrockAnth
 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';
@@ -24,12 +30,16 @@ 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, } from '../../runtime/appGates.js';
 import { resolveNodeAppGateAccess } from '../../runtime/nodeAppGates.js';
-import { DEFAULT_TASKFORCE_AGENT_MODEL_KEY, DEFAULT_TASKFORCE_AGENT_PROVIDER_KEY, getTaskforceAgentModel, isTaskforceAgentModelVisible, labelForTaskforceAgentModel, labelForTaskforceAgentProvider, normalizeTaskforceAgentModelKey, normalizeTaskforceAgentModelSelection, normalizeTaskforceAgentProviderKey, } from '../../shared/taskforceAgentModels.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, serializeCanonicalJson } from '../../shared/taskforceAgentDefinition.js';
 import { buildResolvedTaskforceAgentSystemPrompt, resolveTaskforceAgentRuntimeConfiguration, TaskforceAgentRuntimeResolutionError, } from '../../shared/taskforceAgentRuntimeResolution.js';
@@ -222,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) {
@@ -263,7 +274,7 @@ 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');
@@ -271,8 +282,22 @@ function createDefaultModelGateway(selection) {
     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('Subscription-dev models require local_dev connection scope.', 'MODEL_SOURCE_UNAVAILABLE');
+            throw new ModelGatewayConfigurationError('A personal model connection is required.', 'MODEL_PROVIDER_CONNECTION_REQUIRED');
         }
         return new CodexAppServerModelGateway();
     }
@@ -608,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.' };
@@ -619,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 {
@@ -664,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)
@@ -693,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
@@ -735,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;
@@ -748,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), {
@@ -757,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;
@@ -771,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') {
@@ -789,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;
@@ -826,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') {
@@ -855,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;
@@ -1156,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') {
@@ -1236,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({
@@ -1259,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',

package/dist/server/routes/billing.js

@@ -1857,7 +1857,11 @@ export function registerBillingRoutes(deps) {
             const userIdentity = core.resolveUserIdentity(userId);
             const normalizedUserEmail = normalizeEmail(userIdentity?.email);
             if (pricing.pricingType === 'free') {
-                if (currentEntitlement?.plan_version_id && String(currentEntitlement.plan_version_id).trim() === planVersionId) {
+                const currentEntitlementPlanVersionId = String(currentEntitlement?.plan_version_id || '').trim();
+                const currentEntitlementState = String(currentEntitlement?.entitlement_state || '').trim();
+                if (currentEntitlementPlanVersionId
+                    && currentEntitlementPlanVersionId === planVersionId
+                    && isCommercialStateAppAccessible(currentEntitlementState)) {
                     res.writeHead(200, { 'Content-Type': 'application/json' });
                     res.end(JSON.stringify({
                         checkoutState: 'already_current_plan',

package/dist/server/routes/durableTaskHttpRouters.d.ts

@@ -43,6 +43,7 @@ export declare function createTaskHttpDurableRouters(input: {
             taskId: string;
             items: readonly Partial<import("../../core/Taskforce.js").ChecklistItem>[];
             expectedDetailRevision?: string;
+            itemUpdateIntent?: import("../../sync/v3/taskChecklistMutationService.js").TaskChecklistItemUpdateIntent;
         }): {
             state: "pending" | "committed";
             route: "local-outbox" | "cloud-acceptance";
@@ -70,6 +71,7 @@ export declare function createTaskHttpDurableRouters(input: {
             taskId: string;
             items: readonly Partial<import("../../core/Taskforce.js").ChecklistItem>[];
             expectedDetailRevision?: string;
+            itemUpdateIntent?: import("../../sync/v3/taskChecklistMutationService.js").TaskChecklistItemUpdateIntent;
         }): {
             state: "pending" | "committed";
             route: "local-outbox" | "cloud-acceptance";

package/dist/server/routes/executorPhaseAApprovals.d.ts

@@ -0,0 +1,19 @@
+import type { IncomingMessage, ServerResponse } from 'http';
+import type { ExecutorPhaseAApprovalService } from '../../services/executorPhaseAApprovalService.js';
+import { type RouteHandler } from './primitives.js';
+export declare const EXECUTOR_PHASE_A_APPROVAL_PAGE_PATH = "/taskforce/admin/executor/phase-a-approval";
+export declare const EXECUTOR_PHASE_A_APPROVAL_PAGE_SCRIPT_PATH = "/taskforce/admin/executor/phase-a-approval.js";
+export declare const EXECUTOR_PHASE_A_APPROVAL_ISSUE_PATH = "/api/taskforce/admin/executor/phase-a-approval-receipts";
+export interface ExecutorPhaseAApprovalRouteDependencies {
+    addRoute: (method: string, path: string, handler: RouteHandler) => void;
+    service: ExecutorPhaseAApprovalService | null;
+    requireCloudRuntime: (res: ServerResponse, feature: string) => boolean;
+    ensureAppAccess: (req: IncomingMessage, res: ServerResponse) => boolean;
+    resolveHumanSystemAdminActor: (req: IncomingMessage) => string | null;
+    hasActiveWorkspaceMembership: (workspaceId: string, userId: string) => boolean;
+    auditAuthAction: (req: IncomingMessage, action: string, details: Record<string, unknown>, workspaceIdOverride?: string | null) => void;
+    workspaceId: string;
+    allowedOrigin: string;
+    performanceEnvironment: boolean;
+}
+export declare function registerExecutorPhaseAApprovalRoutes(deps: ExecutorPhaseAApprovalRouteDependencies): void;