Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active
TypeScript aianthropicartifactsawsazurechatgptchatgpt-cloneclaudeclonedeepseekgeminigooglegpt-5librechatmcpo1openairesponses-apivisionwebui
import { useCallback, useMemo } from 'react';
import {
EModelEndpoint,
Tools,
isEphemeralAgentId,
isCodeWorkspaceSelections,
isCodeWorkspaceCheckoutAvailable,
resolveCodeEnvironmentSelection,
} from 'librechat-data-provider';
import {
AgentCapabilities,
CODE_ENVIRONMENT_DECISION_VERSION,
CODE_ENVIRONMENT_MOVE_VERSION,
CODE_ENVIRONMENT_TRANSITION_VERSION,
CODE_WORKSPACE_RECOVERY_VERSION,
CODE_WORKSPACE_INHERITANCE_VERSION,
PermissionTypes,
Permissions,
} from 'librechat-data-provider';
import type {
Agent,
CodeEnvironmentMode,
CodeWorkspaceDescriptor,
CodeWorkspaceSelection,
TConfig,
TCodeEnvironmentStatusResponse,
TConversation,
TPublicCodeEnvironment,
} from 'librechat-data-provider';
import type { CodeEnvironmentReconciliation } from '~/store/codeEnvironmentReconciliation';
import {
collectReachableAgents,
findExecutionEnvironment,
getCodeEnvironmentChoiceIds,
findCodeWorkspaceDiscoveryEnvironment,
resolveReachableCodeWorkspaceInheritance,
} from './useCodeApprovalMode';
import {
useCodeEnvironmentStatusQueries,
useGetStartupConfig,
useIsReplacingConversationCodeEnvironment,
useConversationCodeEnvironmentRecovery,
} from '~/data-provider';
import { useWorkspacePreferences } from './workspacePreferences';
import useAgentToolPermissions from './useAgentToolPermissions';
import useHasAccess from '~/hooks/Roles/useHasAccess';
import useGetAgentsConfig from './useGetAgentsConfig';
import { useAgentsMapContext } from '~/Providers';
export type CodeWorkspaceState =
| 'not_required'
| 'without_attached'
| 'loading'
| 'choose'
| 'relocatable'
| 'ready'
| 'missing'
| 'unavailable'
| 'unsupported';
export interface CodeWorkspaceEnvironmentResult {
environment: TPublicCodeEnvironment;
/** Coding agents whose execution requires this machine, including reachable subagents. */
requiredBy?: Array<{ id: string; name?: string | null }>;
/** Selectable agents whose binding must be retained when this target is explicitly moved. */
selectionOwners?: string[];
state: Exclude<CodeWorkspaceState, 'not_required' | 'relocatable'>;
workspaces: CodeWorkspaceDescriptor[];
selected?: CodeWorkspaceSelection;
}
/**
* A change of a saved chat's sealed decision that its owner may make from the composer. The
* decision stays sealed against implicit changes; only this explicit transition replaces it, and
* it never touches the chat's messages or copies a file between machines.
*
* - `move`: the attached decision no longer covers every environment the chat's agents use, most
* often because an agent was pointed at a different machine or its saved workspace disappeared.
* - `attach`: the chat has been running without an attached environment and can now take one, so
* switching a saved chat to a coding agent is a transition rather than a dead end.
* - `detach`: the attached workspace is healthy, but its owner wants to continue ordinary chat.
*/
export interface CodeWorkspaceTransition {
kind: 'move' | 'attach' | 'detach';
conversationId: string;
/** The persisted selections this replaces, exactly as the conversation stores them; empty for a
* chat that has been running without an attached environment. */
from: CodeWorkspaceSelection[];
/** Environments the decision covered that the agents no longer use. */
previous: Array<
Pick<TPublicCodeEnvironment, 'id'> & Partial<Pick<TPublicCodeEnvironment, 'name'>>
>;
/** Registered sealed selections the agents still use; a move carries them over unchanged. */
retained: CodeWorkspaceSelection[];
/** Environments needing a new selection, including those whose workspace disappeared. */
targets: CodeWorkspaceEnvironmentResult[];
/** Leaving attached execution is always explicit, whether its machine is healthy or unavailable. */
detachable: boolean;
}
export interface CodeWorkspaceResult {
recovery?: CodeEnvironmentReconciliation;
required: boolean;
supportsEnvironmentDecisions: boolean;
locked: boolean;
mode?: CodeEnvironmentMode;
state: CodeWorkspaceState;
canSubmit: boolean;
/** Whether the composer shows the workspace control. A chat running without an attached
* environment keeps it, so the state it is in stays visible and reversible. */
visible: boolean;
environments: CodeWorkspaceEnvironmentResult[];
/** Alternative machines are discovered on demand; an idle machine never blocks this chat. */
machineOptions?: TPublicCodeEnvironment[];
/** Each group belongs to one reachable coding agent, not the whole graph. */
machineOptionGroups?: string[][];
machineChoiceOwners?: Array<{ agentId: string; environmentIds: string[] }>;
/** Fixed graph targets must survive an alternative pick for a different agent. */
fixedMachineIds?: string[];
transition?: CodeWorkspaceTransition;
selections?: CodeWorkspaceSelection[];
resolveSelections: (
selections?: CodeWorkspaceSelection[],
) => CodeWorkspaceSelection[] | undefined;
resolveSubmission: (
selections?: CodeWorkspaceSelection[],
mode?: CodeEnvironmentMode,
) =>
| { codeEnvironmentMode?: CodeEnvironmentMode; codeWorkspaces?: CodeWorkspaceSelection[] }
| undefined;
rememberSelection: (selection: CodeWorkspaceSelection) => void;
}
function aggregateState(
required: boolean,
complete: boolean,
environments: CodeWorkspaceEnvironmentResult[],
selections: CodeWorkspaceSelection[] | undefined,
): CodeWorkspaceState {
if (!required) return 'not_required';
if (!complete || environments.some(({ state }) => state === 'unavailable')) return 'unavailable';
if (environments.some(({ state }) => state === 'unsupported')) return 'unsupported';
if (environments.some(({ state }) => state === 'missing')) return 'missing';
if (environments.some(({ state }) => state === 'loading')) return 'loading';
if (selections == null) return 'choose';
return 'ready';
}
function resolveEnvironmentSelection({
environment,
status,
workspaces,
stored,
hasStoredSelections,
}: {
environment: TPublicCodeEnvironment;
status?: TCodeEnvironmentStatusResponse;
workspaces: CodeWorkspaceDescriptor[];
stored?: CodeWorkspaceSelection;
hasStoredSelections: boolean;
}): CodeWorkspaceSelection | undefined {
if (status?.status !== 'ready' || status.environmentId !== environment.id) return undefined;
if (stored != null && workspaces.some(({ id }) => id === stored.workspaceId)) {
return { ...stored, environmentId: environment.id };
}
if (!hasStoredSelections && workspaces.length === 1) {
return { environmentId: environment.id, workspaceId: workspaces[0].id };
}
return undefined;
}
export default function useCodeWorkspace(
conversation: TConversation | null,
addedConversation?: TConversation | null,
): CodeWorkspaceResult {
const { data: startupConfig } = useGetStartupConfig();
const supportsEnvironmentDecisions =
startupConfig?.codeEnvironmentDecisionVersion === CODE_ENVIRONMENT_DECISION_VERSION;
const supportsEnvironmentMoves =
startupConfig?.codeEnvironmentMoveVersion === CODE_ENVIRONMENT_MOVE_VERSION;
/** Attaching an environment and leaving attached execution are advertised beside the move rather
* than as a higher move version, so a deployment mid-rollout keeps serving the move to a client
* that predates them, and a client that has them never offers a replica an attach it refuses as
* `locked` or an empty target set it calls `invalid`. */
const supportsEnvironmentTransitions =
supportsEnvironmentDecisions &&
startupConfig?.codeEnvironmentTransitionVersion === CODE_ENVIRONMENT_TRANSITION_VERSION;
const recovery = useConversationCodeEnvironmentRecovery(conversation?.conversationId);
const replacingDecision = useIsReplacingConversationCodeEnvironment(conversation?.conversationId);
const supportsWorkspaceRecovery =
supportsEnvironmentMoves &&
startupConfig?.codeWorkspaceRecoveryVersion === CODE_WORKSPACE_RECOVERY_VERSION;
/** An API that predates inheritance still routes each subagent to its own machine, so only an
* advertising one lets the composer drop that machine's workspace. */
const supportsWorkspaceInheritance =
startupConfig?.codeWorkspaceInheritanceVersion === CODE_WORKSPACE_INHERITANCE_VERSION;
const preferences = useWorkspacePreferences(conversation?.agent_id);
const { agentsConfig, endpointsConfig } = useGetAgentsConfig();
const canRunCode = useHasAccess({
permissionType: PermissionTypes.RUN_CODE,
permission: Permissions.USE,
});
const codeEnabled =
canRunCode &&
agentsConfig?.capabilities?.includes(AgentCapabilities.execute_code) === true &&
agentsConfig.capabilities.includes(AgentCapabilities.stateful_code_sessions);
const agentsMap = useAgentsMapContext();
const { agent: primaryAgent } = useAgentToolPermissions(conversation?.agent_id);
const { agent: addedAgent } = useAgentToolPermissions(addedConversation?.agent_id);
const statefulCodeSessions = agentsConfig?.statefulCodeSessions as
| TConfig['statefulCodeSessions']
| undefined;
const reachable = useMemo(
() =>
collectReachableAgents([primaryAgent, addedAgent], agentsMap, [
conversation?.agent_id,
addedConversation?.agent_id,
]),
[addedAgent, agentsMap, primaryAgent, conversation?.agent_id, addedConversation?.agent_id],
);
const storedSelections = conversation?.codeWorkspaces;
const isNewChat =
conversation != null &&
(conversation.conversationId == null || conversation.conversationId === 'new');
/** Only a recorded decision is sealed. A saved chat whose turns never involved a code-capable
* agent stores none, so switching one to a coding agent still gets to choose; treating it as
* sealed leaves the composer showing a decision its owner never made, with no workspace to
* select and no way to submit.
*
* Until the deployment advertises the decision protocol, a replica that still reads a
* field-less row as a sealed `without_attached` may serve the next turn and reject an attached
* choice as `locked`, so the legacy lock stays for the whole rollout window. Nothing is lost by
* waiting: the composer only reports that unmade decision once the same flag is on. */
const holdsDecision =
conversation?.codeEnvironmentMode != null || (storedSelections?.length ?? 0) > 0;
const locked =
conversation != null && !isNewChat && (holdsDecision || !supportsEnvironmentDecisions);
/** A new chat and a saved chat that never decided are both still choosing, so agent defaults, a
* remembered selection, and a sole workspace apply to each. */
const undecided = conversation != null && !locked;
const workspaceMetadata = useMemo(() => {
const unique = new Map<string, TPublicCodeEnvironment>();
const defaults = new Map<string, Set<string>>();
const preferenceAgentIds = new Map<string, Set<string>>();
const requiredBy = new Map<string, Array<{ id: string; name?: string | null }>>();
const inheritance = supportsWorkspaceInheritance
? resolveReachableCodeWorkspaceInheritance(
[primaryAgent, addedAgent],
agentsMap,
statefulCodeSessions?.environments,
statefulCodeSessions?.allowEnvironmentSelection,
conversation?.codeWorkspaces,
undecided,
)
: new Map<string, string>();
/** A decision may still select the machine an inheriting subagent ran on before it followed
* its parent. No agent runs there now, so that selection is echoed as sealed but neither
* required, nor checked for readiness, nor read as a foreign choice that needs a move. */
const formerEnvironmentIds = new Set<string>();
const retainInheritedFromSelection = (agent: Agent) => {
if (!inheritance.has(agent.id)) return;
const own = resolveCodeEnvironmentSelection({
agentId: agent.id,
environmentId:
agent.code_environment_id ??
statefulCodeSessions?.environments?.find(({ default: isDefault }) => isDefault)?.id,
environmentIds: agent.code_environment_ids,
allowSelection:
getCodeEnvironmentChoiceIds(
agent,
statefulCodeSessions?.environments,
statefulCodeSessions?.allowEnvironmentSelection,
) != null,
selections: conversation?.codeWorkspaces,
});
const ownId = own.valid ? own.environmentId : undefined;
if (
ownId &&
conversation?.codeWorkspaces?.some(({ environmentId }) => environmentId === ownId)
) {
formerEnvironmentIds.add(ownId);
}
};
let complete = true;
for (const agent of reachable.agents) {
if (agent.stateful_code_sessions !== true || !agent.tools?.includes(Tools.execute_code)) {
continue;
}
const environment = findCodeWorkspaceDiscoveryEnvironment(
agent,
statefulCodeSessions?.environments,
statefulCodeSessions?.allowEnvironmentSelection,
conversation?.codeWorkspaces,
inheritance.get(agent.id),
);
/** Discovery must remain available while a graph draft is partial or its sealed
* route needs recovery. Only final submission resolves the entire graph strictly. */
if (environment == null && agent.code_environment_id) {
complete = false;
}
retainInheritedFromSelection(agent);
if (environment?.type !== 'attached') continue;
unique.set(environment.id, environment);
const owners = requiredBy.get(environment.id) ?? [];
owners.push({ id: agent.id, name: agent.name });
requiredBy.set(environment.id, owners);
if (agent.code_environment_id === environment.id && agent.code_workspace_id) {
const choices = defaults.get(environment.id) ?? new Set<string>();
choices.add(agent.code_workspace_id);
defaults.set(environment.id, choices);
}
}
for (const [rootAgent, rootAgentId] of [
[primaryAgent, conversation?.agent_id],
[addedAgent, addedConversation?.agent_id],
] as const) {
if (!rootAgent || !rootAgentId) continue;
const rootReachable = collectReachableAgents([rootAgent], agentsMap, [rootAgentId]);
for (const agent of rootReachable.agents) {
if (agent.stateful_code_sessions !== true || !agent.tools?.includes(Tools.execute_code)) {
continue;
}
const environment = findCodeWorkspaceDiscoveryEnvironment(
agent,
statefulCodeSessions?.environments,
statefulCodeSessions?.allowEnvironmentSelection,
conversation?.codeWorkspaces,
inheritance.get(agent.id),
);
if (environment?.type !== 'attached') continue;
const owners = preferenceAgentIds.get(environment.id) ?? new Set<string>();
owners.add(rootAgentId);
preferenceAgentIds.set(environment.id, owners);
}
}
return {
complete,
defaults,
preferenceAgentIds,
requiredBy,
formerEnvironmentIds: new Set([...formerEnvironmentIds].filter((id) => !unique.has(id))),
environments: [...unique.values()].sort((a, b) => a.id.localeCompare(b.id)),
};
}, [
addedAgent,
addedConversation?.agent_id,
agentsMap,
conversation?.agent_id,
conversation?.codeWorkspaces,
primaryAgent,
reachable.agents,
statefulCodeSessions?.environments,
statefulCodeSessions?.allowEnvironmentSelection,
supportsWorkspaceInheritance,
undecided,
]);
const isAgentsConversation =
(conversation?.endpointType ?? conversation?.endpoint) === EModelEndpoint.agents;
const expectedRoot = conversation?.agent_id != null || addedConversation?.agent_id != null;
const expectedSavedAgent = [conversation?.agent_id, addedConversation?.agent_id].some(
(agentId) => agentId != null && !isEphemeralAgentId(agentId),
);
const configurationLoaded = endpointsConfig !== undefined || agentsConfig != null;
const configurationPending =
canRunCode && isAgentsConversation && expectedSavedAgent && !configurationLoaded;
const attachedEnvironments = workspaceMetadata.environments;
const metadataComplete =
!isAgentsConversation || !expectedRoot || (reachable.complete && workspaceMetadata.complete);
const required =
configurationPending ||
(codeEnabled && isAgentsConversation && (!metadataComplete || attachedEnvironments.length > 0));
const selectionMetadataComplete = !configurationPending && metadataComplete;
const statuses = useCodeEnvironmentStatusQueries(
attachedEnvironments.map(({ id }) => id),
required && selectionMetadataComplete,
// Poll progress is not workspace state; keep unchanged refreshes off the send path.
{ notifyOnChangeProps: ['data', 'isLoading', 'isError'] },
);
const attachedEnvironmentIds = useMemo(
() => new Set(attachedEnvironments.map(({ id }) => id)),
[attachedEnvironments],
);
const { formerEnvironmentIds } = workspaceMetadata;
const hasForeignStoredSelection = storedSelections?.some(
({ environmentId }) =>
!attachedEnvironmentIds.has(environmentId) && !formerEnvironmentIds.has(environmentId),
);
const machineChoiceOwners =
required &&
supportsEnvironmentDecisions &&
statefulCodeSessions?.allowEnvironmentSelection === true
? reachable.agents.flatMap((agent) => {
if (agent.stateful_code_sessions !== true || !agent.tools?.includes(Tools.execute_code)) {
return [];
}
const ids = getCodeEnvironmentChoiceIds(agent, statefulCodeSessions.environments, true);
return ids == null ? [] : [{ agentId: agent.id, environmentIds: ids }];
})
: undefined;
const machineOptionGroups = undecided
? machineChoiceOwners?.map(({ environmentIds }) => environmentIds)
: undefined;
const machineOptions = machineOptionGroups?.length
? statefulCodeSessions?.environments?.filter(
({ id, type }) =>
type === 'attached' && machineOptionGroups.some((ids) => ids.includes(id)),
)
: undefined;
const fixedMachineIds = reachable.agents.flatMap((agent) => {
if (agent.stateful_code_sessions !== true || !agent.tools?.includes(Tools.execute_code))
return [];
if (
getCodeEnvironmentChoiceIds(
agent,
statefulCodeSessions?.environments,
statefulCodeSessions?.allowEnvironmentSelection,
) != null
)
return [];
const environment = findExecutionEnvironment(agent, statefulCodeSessions?.environments);
return environment?.type === 'attached' ? [environment.id] : [];
});
const environmentResults = attachedEnvironments.map((environment, index) => {
const status = statuses[index];
const workspaces =
status?.data?.status === 'ready' && Array.isArray(status.data.workspaces)
? status.data.workspaces
: [];
let stored = storedSelections?.find(({ environmentId }) => environmentId === environment.id);
let conflictingDefaults = false;
if (stored == null && undecided && !hasForeignStoredSelection) {
const defaults = workspaceMetadata.defaults.get(environment.id) ?? new Set<string>();
let preferred: string | undefined;
if (defaults.size === 1) preferred = [...defaults][0];
else if (defaults.size === 0) {
preferred = [...(workspaceMetadata.preferenceAgentIds.get(environment.id) ?? [])]
.map((agentId) => preferences.get(environment.id, agentId))
.find((workspaceId) => workspaces.some(({ id }) => id === workspaceId));
}
if (preferred && (defaults.size > 0 || workspaces.some(({ id }) => id === preferred))) {
stored = { environmentId: environment.id, workspaceId: preferred };
}
conflictingDefaults = defaults.size > 1;
}
const selected = resolveEnvironmentSelection({
environment,
status: status?.data,
workspaces,
stored,
/** A saved chat already holds the server's decision, so a sole workspace is not a draft
* choice there: auto-selecting it would submit a selection its persisted decision rejects.
* Attached selections are sealed whether or not selection-less decisions are advertised. */
hasStoredSelections:
(locked && (supportsEnvironmentDecisions || (storedSelections?.length ?? 0) > 0)) ||
stored != null ||
conflictingDefaults ||
hasForeignStoredSelection === true,
});
let state: CodeWorkspaceEnvironmentResult['state'] = 'choose';
if (status == null || status.isLoading) state = 'loading';
else if (
status.isError ||
status.data?.status !== 'ready' ||
status.data.environmentId !== environment.id
) {
state = 'unavailable';
} else if (status.data.workspaces == null) state = 'unsupported';
else if (selected != null) {
state = isCodeWorkspaceCheckoutAvailable(
selected,
workspaces.find(({ id }) => id === selected.workspaceId),
environment.configSchema?.workspaces?.allowCheckoutSelection === true,
)
? 'ready'
: 'unsupported';
} else if (stored != null) state = 'missing';
else if (workspaces.length === 0) state = 'unavailable';
return {
environment,
state,
workspaces,
selected,
requiredBy: workspaceMetadata.requiredBy.get(environment.id),
selectionOwners: workspaceMetadata.requiredBy
.get(environment.id)
?.filter(({ id }) => machineChoiceOwners?.some(({ agentId }) => agentId === id))
.map(({ id }) => id),
};
});
const resolveSelections = useCallback(
(selections?: CodeWorkspaceSelection[]): CodeWorkspaceSelection[] | undefined => {
if (!required || !selectionMetadataComplete || !isCodeWorkspaceSelections(selections ?? [])) {
return undefined;
}
/** Never silently discard a machine the user picked. A sealed choice needs a transition;
* a draft choice not used by the graph must be corrected before it can execute elsewhere. */
if (
selections?.some(
({ environmentId }) =>
!attachedEnvironmentIds.has(environmentId) && !formerEnvironmentIds.has(environmentId),
)
) {
return undefined;
}
const resolved: CodeWorkspaceSelection[] =
selections?.filter(({ environmentId }) => formerEnvironmentIds.has(environmentId)) ?? [];
for (const result of environmentResults) {
const requested = selections?.find(
({ environmentId }) => environmentId === result.environment.id,
);
if (
requested != null &&
result.state !== 'loading' &&
result.state !== 'unavailable' &&
result.state !== 'unsupported' &&
result.workspaces.some(
(descriptor) =>
descriptor.id === requested.workspaceId &&
isCodeWorkspaceCheckoutAvailable(
requested,
descriptor,
result.environment.configSchema?.workspaces?.allowCheckoutSelection === true,
),
)
) {
resolved.push({
environmentId: result.environment.id,
workspaceId: requested.workspaceId,
...(requested.checkout == null ? {} : { checkout: requested.checkout }),
...(requested.agentIds == null ? {} : { agentIds: requested.agentIds }),
});
continue;
}
if (requested == null && result.selected != null && result.state === 'ready') {
resolved.push(result.selected);
continue;
}
return undefined;
}
const inheritance =
supportsWorkspaceInheritance && statefulCodeSessions?.allowEnvironmentSelection === true
? resolveReachableCodeWorkspaceInheritance(
[primaryAgent, addedAgent],
agentsMap,
statefulCodeSessions.environments,
true,
resolved,
)
: undefined;
if (
statefulCodeSessions?.allowEnvironmentSelection === true &&
reachable.agents.some(
(agent) =>
agent.stateful_code_sessions === true &&
agent.tools?.includes(Tools.execute_code) &&
getCodeEnvironmentChoiceIds(agent, statefulCodeSessions.environments, true) != null &&
!resolveCodeEnvironmentSelection({
agentId: agent.id,
environmentId:
agent.code_environment_id ??
statefulCodeSessions.environments?.find(({ default: isDefault }) => isDefault)?.id,
environmentIds: agent.code_environment_ids,
allowSelection: true,
selections: resolved,
inheritedEnvironmentId: inheritance?.get(agent.id),
}).valid,
)
)
return undefined;
return resolved.sort((a, b) => a.environmentId.localeCompare(b.environmentId));
},
[
addedAgent,
agentsMap,
attachedEnvironmentIds,
environmentResults,
formerEnvironmentIds,
primaryAgent,
required,
selectionMetadataComplete,
reachable.agents,
statefulCodeSessions,
supportsWorkspaceInheritance,
],
);
const selections = resolveSelections(storedSelections);
let inferredMode: CodeEnvironmentMode | undefined = conversation?.codeEnvironmentMode;
if (inferredMode == null && storedSelections != null) {
inferredMode = 'attached';
} else if (inferredMode == null && !isNewChat && supportsEnvironmentDecisions) {
// Suggestions are not consent. Existing non-coding chats start without workspace access;
// only an explicit selection in the composer may attach their first coding turn.
inferredMode = 'without_attached';
} else if (inferredMode == null && selections != null) {
inferredMode = 'attached';
} else if (inferredMode == null && required && supportsEnvironmentDecisions) {
inferredMode = 'without_attached';
}
let state: CodeWorkspaceState;
const hasLockedWithoutAttachedDecision =
inferredMode === 'without_attached' &&
(conversation?.codeEnvironmentMode === 'without_attached' || locked);
if (hasLockedWithoutAttachedDecision) {
state = 'without_attached';
} else if (configurationPending) {
state = 'loading';
} else {
state = aggregateState(required, metadataComplete, environmentResults, selections);
}
const resolveSubmission = useCallback(
(
candidateSelections?: CodeWorkspaceSelection[],
candidateMode?: CodeEnvironmentMode,
):
| { codeEnvironmentMode?: CodeEnvironmentMode; codeWorkspaces?: CodeWorkspaceSelection[] }
| undefined => {
if (recovery != null) return undefined;
if (!required) return {};
/**
* A replacement in flight has no decided answer yet. The server checks for active work
* before it polls the target workspace, so a turn submitted during that poll starts under
* the decision being replaced, runs without the workspace its owner just chose, and the
* replacement still lands afterwards because the stored decision it swaps is unchanged.
* Nothing reports that to the reader, so the send waits instead.
*/
if (replacingDecision) return undefined;
const requestedMode =
candidateMode ??
inferredMode ??
(isCodeWorkspaceSelections(candidateSelections) && candidateSelections.length > 0
? 'attached'
: undefined);
if (requestedMode === 'without_attached') {
return supportsEnvironmentDecisions
? { codeEnvironmentMode: 'without_attached' }
: undefined;
}
if (requestedMode == null && supportsEnvironmentDecisions) {
return { codeEnvironmentMode: 'without_attached' };
}
const codeWorkspaces = resolveSelections(candidateSelections);
return codeWorkspaces == null
? undefined
: { codeEnvironmentMode: 'attached', codeWorkspaces };
},
[
inferredMode,
recovery,
replacingDecision,
required,
resolveSelections,
supportsEnvironmentDecisions,
],
);
const canSubmit = resolveSubmission(storedSelections, conversation?.codeEnvironmentMode) != null;
let transition: CodeWorkspaceTransition | undefined;
if (
supportsEnvironmentMoves &&
locked &&
selectionMetadataComplete &&
state !== 'loading' &&
conversation?.conversationId != null
) {
const configuredEnvironments = statefulCodeSessions?.environments;
const base = {
conversationId: conversation.conversationId,
from: storedSelections ?? [],
previous: (storedSelections ?? [])
.filter(({ environmentId }) => !attachedEnvironmentIds.has(environmentId))
.map(({ environmentId }) => ({
id: environmentId,
name: configuredEnvironments?.find(({ id }) => id === environmentId)?.name,
})),
retained: environmentResults.flatMap((result) =>
result.state === 'ready' && result.selected != null ? [result.selected] : [],
),
targets: environmentResults.filter(
(result) =>
result.state === 'choose' || (supportsWorkspaceRecovery && result.state === 'missing'),
),
};
/**
* A transition replaces the decision whole, so one that named only some of the environments
* the agents use would seal a decision the next turn refuses: `resolveSelections` resolves
* every environment or none. An environment that is unreachable, missing its workspace or on
* an outdated worker is neither carried over nor selectable, so no set of picks covers it, and
* offering the transition anyway would trade one dead end for a sealed one that needs a second
* transition to escape. Leaving attached execution stays available, since that is the escape.
*/
const coversEveryEnvironment =
base.retained.length + base.targets.length === environmentResults.length;
if (
supportsEnvironmentTransitions &&
state === 'without_attached' &&
conversation.codeEnvironmentMode === 'without_attached' &&
base.targets.length > 0 &&
coversEveryEnvironment
) {
/** Only a decision this chat actually recorded is sealed, so a chat that merely lacks the
* fields still chooses in the composer and needs no transition. */
transition = { ...base, kind: 'attach', detachable: false };
} else if (
inferredMode === 'attached' &&
(storedSelections?.length ?? 0) > 0 &&
// Dropping the last attached agent makes ordinary chat sendable, but does not remove
// its persisted seal. Keep the explicit detach action available for that conversation.
(state === 'choose' || !canSubmit || attachedEnvironments.length === 0)
) {
const move: CodeWorkspaceTransition = {
...base,
kind: 'move',
detachable: supportsEnvironmentTransitions,
...(coversEveryEnvironment ? {} : { retained: [], targets: [] }),
};
/** An uncoverable environment leaves nothing to move onto, so the transition is worth
* offering only where leaving attached execution is also served. */
if (move.targets.length > 0 || move.retained.length > 0 || move.detachable) {
transition = move;
if (
state === 'choose' ||
(supportsWorkspaceRecovery && state === 'missing' && coversEveryEnvironment)
)
state = 'relocatable';
}
} else if (
supportsEnvironmentTransitions &&
inferredMode === 'attached' &&
(storedSelections?.length ?? 0) > 0 &&
state === 'ready'
) {
transition = { ...base, kind: 'detach', detachable: true };
}
}
/** Keep explicit transitions visible without offering mutable picks for a sealed decision. */
const visible =
recovery != null ||
transition != null ||
(required &&
(!locked || !canSubmit || transition != null || inferredMode === 'without_attached'));
const rememberSelection = useCallback(
(selection: CodeWorkspaceSelection) => {
preferences.remember(selection.environmentId, selection.workspaceId, [
...(workspaceMetadata.preferenceAgentIds.get(selection.environmentId) ?? []),
]);
},
[preferences, workspaceMetadata.preferenceAgentIds],
);
return {
recovery,
required,
supportsEnvironmentDecisions,
locked,
mode: inferredMode,
state,
canSubmit,
visible,
environments: environmentResults,
machineOptions,
machineOptionGroups,
machineChoiceOwners,
fixedMachineIds,
transition,
selections,
resolveSelections,
resolveSubmission,
rememberSelection,
};
}