diff --git a/apps/mobile/src/features/threads/NewTaskDraftScreen.tsx b/apps/mobile/src/features/threads/NewTaskDraftScreen.tsx index 1ee4e9bc4e852..5ba8abf06c068 100644 --- a/apps/mobile/src/features/threads/NewTaskDraftScreen.tsx +++ b/apps/mobile/src/features/threads/NewTaskDraftScreen.tsx @@ -50,6 +50,7 @@ import { ComposerToolbarRow, } from "../../components/ComposerToolbar"; import { AndroidScreenHeader } from "../../components/AndroidScreenHeader"; +import { ControlPillMenu } from "../../components/ControlPill"; import { MaterialScreenContent } from "../../components/MaterialScreenContent"; import { ComposerAttachmentButton } from "../../components/ComposerAttachmentButton"; import { ComposerAttachmentStrip } from "../../components/ComposerAttachmentStrip"; @@ -122,6 +123,7 @@ import { resolveDraftProjectSelection } from "./new-task-project-selection"; import { resolveNewTaskBranchLabel, resolveNewTaskWorkspaceLabel, + type NewTaskWorkspaceChoice, } from "./new-task-context-presentation"; import { useIncomingShare } from "../sharing/IncomingShareProvider"; import { selectIncomingShareAttachmentsForServer } from "../sharing/incoming-share-model"; @@ -129,9 +131,20 @@ import { appAtomRegistry } from "../../state/atom-registry"; import { serverEnvironment } from "../../state/server"; import { fileRoutePathSegments } from "../files/filePath"; +const WORKSPACE_CHOICES = [ + { id: "local", title: "Current checkout" }, + { id: "worktree", title: "New worktree" }, + { id: "sandbox", title: "New sandbox", subtitle: "New worktree in a Docker container" }, +] as const satisfies ReadonlyArray<{ + readonly id: NewTaskWorkspaceChoice; + readonly title: string; + readonly subtitle?: string; +}>; + function NewTaskWorkspaceIcon(props: { readonly workspaceMode: "local" | "worktree"; readonly worktreePath: string | null; + readonly sandbox: boolean; readonly size: number; }) { if (props.workspaceMode === "local" && props.worktreePath === null) { @@ -164,7 +177,7 @@ function NewTaskWorkspaceIcon(props: { } > { @@ -1549,24 +1565,62 @@ export function NewTaskDraftScreen(props: { ); + const workspaceControlDisabled = isComposerInteractionLocked || voiceInput.isBusy; + // Two workspaces toggle on tap. A server that offers sandboxes adds a third, + // so the control opens a menu instead. + const offersWorkspaceMenu = flow.canUseSandbox && !workspaceControlDisabled; + const workspaceControl = ( + ( + + )} + label={workspaceLabel} + maxWidth={flow.workspaceMode === "local" ? 220 : 148} + onPress={ + offersWorkspaceMenu + ? undefined + : () => flow.setWorkspaceChoice(flow.workspaceMode === "local" ? "worktree" : "local") + } + showChevron={offersWorkspaceMenu} + /> + ); + const workspaceControls = ( - ( - - )} - label={workspaceLabel} - maxWidth={flow.workspaceMode === "local" ? 220 : 148} - onPress={() => flow.setWorkspaceMode(flow.workspaceMode === "local" ? "worktree" : "local")} - showChevron={false} - /> + {offersWorkspaceMenu ? ( + ({ + ...choice, + ...(choice.id === "local" && flow.workspaceMode === "local" + ? { title: workspaceLabel } + : {}), + state: choice.id === workspaceChoice ? ("on" as const) : ("off" as const), + }))} + onPressAction={({ nativeEvent }) => { + const choice = WORKSPACE_CHOICES.find( + (candidate) => candidate.id === nativeEvent.event, + ); + if (choice) flow.setWorkspaceChoice(choice.id); + }} + > + {workspaceControl} + + ) : ( + workspaceControl + )} : null} + ); diff --git a/apps/mobile/src/features/threads/git/ThreadSandboxCard.tsx b/apps/mobile/src/features/threads/git/ThreadSandboxCard.tsx new file mode 100644 index 0000000000000..b772d91cebd1f --- /dev/null +++ b/apps/mobile/src/features/threads/git/ThreadSandboxCard.tsx @@ -0,0 +1,132 @@ +import { + isAtomCommandInterrupted, + squashAtomCommandFailure, +} from "@t3tools/client-runtime/state/runtime"; +import { findSandboxForWorktree } from "@t3tools/client-runtime/state/vcs"; +import type { EnvironmentId, SandboxStatus } from "@t3tools/contracts"; +import { useState } from "react"; +import { Alert, Platform, View } from "react-native"; + +import { AppText as Text } from "../../../components/AppText"; +import { showConfirmDialog } from "../../../components/ConfirmDialogHost"; +import { cn } from "../../../lib/cn"; +import { useEnvironmentServerConfig } from "../../../state/entities"; +import { useEnvironmentQuery } from "../../../state/query"; +import { useAtomCommand } from "../../../state/use-atom-command"; +import { vcsEnvironment } from "../../../state/vcs"; +import { SheetListRow } from "./gitSheetComponents"; + +const STATUS_LABEL: Record = { + starting: "Starting", + running: "Running", + stopped: "Stopped", + error: "Error", +}; + +function confirmRemove(onConfirm: () => void) { + const title = "Remove sandbox?"; + const message = "Later work in this worktree then runs on the host."; + if (Platform.OS === "ios") { + Alert.alert(title, message, [ + { text: "Cancel", style: "cancel" }, + { text: "Remove", style: "destructive", onPress: onConfirm }, + ]); + return; + } + showConfirmDialog({ title, message, confirmText: "Remove", destructive: true, onConfirm }); +} + +/** + * Status, forwarded ports, and stop/remove actions for a thread whose worktree + * runs in a Docker sandbox. Renders nothing for other threads, and only + * subscribes to the sandbox list when the server can run sandboxes. + */ +export function ThreadSandboxCard(props: { + readonly environmentId: EnvironmentId; + readonly worktreePath: string | null; +}) { + const serverConfig = useEnvironmentServerConfig(props.environmentId); + const sandboxes = useEnvironmentQuery( + serverConfig?.sandboxes === true && props.worktreePath !== null + ? vcsEnvironment.sandboxes({ environmentId: props.environmentId, input: {} }) + : null, + ); + const sandbox = findSandboxForWorktree(sandboxes.data?.sandboxes, props.worktreePath); + const stopSandbox = useAtomCommand(vcsEnvironment.stopSandbox, { reportFailure: false }); + const removeSandbox = useAtomCommand(vcsEnvironment.removeSandbox, { reportFailure: false }); + const [busy, setBusy] = useState(false); + + if (!sandbox) return null; + const canStop = sandbox.status === "running" || sandbox.status === "starting"; + const { worktreePath } = sandbox; + const run = async (failureTitle: string, command: typeof stopSandbox) => { + setBusy(true); + try { + const result = await command({ environmentId: props.environmentId, input: { worktreePath } }); + if (result._tag === "Success" || isAtomCommandInterrupted(result)) return; + const cause = squashAtomCommandFailure(result); + Alert.alert(failureTitle, cause instanceof Error ? cause.message : undefined); + } finally { + setBusy(false); + } + }; + + return ( + + + + Sandbox + + + {STATUS_LABEL[sandbox.status]} · {sandbox.containerName} + + {sandbox.status === "error" && sandbox.error ? ( + + {sandbox.error} + + ) : null} + {sandbox.ports.map((port) => ( + + :{port.containerPort} → 127.0.0.1:{port.hostPort} + + ))} + + + {canStop ? ( + <> + {Platform.OS !== "android" ? : null} + void run("Could not stop sandbox", stopSandbox)} + /> + + ) : null} + {Platform.OS !== "android" ? ( + + ) : null} + confirmRemove(() => void run("Could not remove sandbox", removeSandbox))} + /> + + + ); +} diff --git a/apps/mobile/src/features/threads/new-task-context-presentation.test.ts b/apps/mobile/src/features/threads/new-task-context-presentation.test.ts index f48ba92396e90..64ad720db1b41 100644 --- a/apps/mobile/src/features/threads/new-task-context-presentation.test.ts +++ b/apps/mobile/src/features/threads/new-task-context-presentation.test.ts @@ -5,8 +5,53 @@ import { resolveNewTaskBranchWorktreePath, resolveNewTaskBranchLabel, resolveNewTaskLocalWorkspaceSelection, + resolveNewTaskSandbox, + resolveNewTaskWorkspaceLabel, } from "./new-task-context-presentation"; +describe("resolveNewTaskSandbox", () => { + it("keeps a sandbox choice only for new worktrees", () => { + const serverConfig = { sandboxes: true }; + expect( + resolveNewTaskSandbox({ workspaceMode: "worktree", draftSandbox: true, serverConfig }), + ).toBe(true); + expect( + resolveNewTaskSandbox({ workspaceMode: "local", draftSandbox: true, serverConfig }), + ).toBe(false); + }); + + it("drops the choice on a server without sandboxes", () => { + expect( + resolveNewTaskSandbox({ workspaceMode: "worktree", draftSandbox: true, serverConfig: {} }), + ).toBe(false); + }); + + it("keeps the choice while the server config is unknown", () => { + expect( + resolveNewTaskSandbox({ workspaceMode: "worktree", draftSandbox: true, serverConfig: null }), + ).toBe(true); + }); +}); + +describe("resolveNewTaskWorkspaceLabel", () => { + it("names a sandboxed worktree", () => { + expect( + resolveNewTaskWorkspaceLabel({ + workspaceMode: "worktree", + worktreePath: null, + sandbox: true, + }), + ).toBe("New sandbox"); + expect( + resolveNewTaskWorkspaceLabel({ + workspaceMode: "worktree", + worktreePath: null, + sandbox: false, + }), + ).toBe("New worktree"); + }); +}); + describe("resolveNewTaskLocalWorkspaceSelection", () => { it("waits for refs instead of carrying a worktree base into Current checkout", () => { expect( diff --git a/apps/mobile/src/features/threads/new-task-context-presentation.ts b/apps/mobile/src/features/threads/new-task-context-presentation.ts index 87c9b2595f4f2..1a0146c9fc908 100644 --- a/apps/mobile/src/features/threads/new-task-context-presentation.ts +++ b/apps/mobile/src/features/threads/new-task-context-presentation.ts @@ -2,12 +2,33 @@ import { sanitizeNewRefName } from "@t3tools/shared/git"; type WorkspaceMode = "local" | "worktree"; +/** The workspace picker's options. A sandbox is a new worktree that runs in Docker. */ +export type NewTaskWorkspaceChoice = "local" | "worktree" | "sandbox"; + +/** + * Whether a new task starts in a sandbox. The draft keeps the user's choice; + * a server that does not offer sandboxes drops it, and an unknown config + * (offline or still loading) keeps it so editing a queued task cannot lose it. + */ +export function resolveNewTaskSandbox(input: { + readonly workspaceMode: WorkspaceMode; + readonly draftSandbox: boolean | undefined; + readonly serverConfig: { readonly sandboxes?: boolean } | null; +}): boolean { + return ( + input.workspaceMode === "worktree" && + input.draftSandbox === true && + (input.serverConfig === null || input.serverConfig.sandboxes === true) + ); +} + export function resolveNewTaskWorkspaceLabel(input: { readonly workspaceMode: WorkspaceMode; readonly worktreePath: string | null; -}): "Current checkout" | "Current worktree" | "New worktree" { + readonly sandbox: boolean; +}): "Current checkout" | "Current worktree" | "New worktree" | "New sandbox" { if (input.workspaceMode === "worktree") { - return "New worktree"; + return input.sandbox ? "New sandbox" : "New worktree"; } return input.worktreePath ? "Current worktree" : "Current checkout"; } diff --git a/apps/mobile/src/features/threads/new-task-flow-provider.tsx b/apps/mobile/src/features/threads/new-task-flow-provider.tsx index 18c023b45ee11..eed54123694b8 100644 --- a/apps/mobile/src/features/threads/new-task-flow-provider.tsx +++ b/apps/mobile/src/features/threads/new-task-flow-provider.tsx @@ -108,6 +108,8 @@ import { filterNewTaskBranches, resolveNewTaskBranchWorktreePath, resolveNewTaskLocalWorkspaceSelection, + resolveNewTaskSandbox, + type NewTaskWorkspaceChoice, } from "./new-task-context-presentation"; import { resolveEnvironmentProjectMatch } from "./new-task-project-selection"; import { resolveProjectThreadCreationBranch } from "./projectThreadCreationValidation"; @@ -158,8 +160,12 @@ type NewTaskFlowContextValue = { readonly selectedProjectKey: string | null; readonly selectedModelKey: string | null; readonly workspaceMode: WorkspaceMode; + /** Worktree mode only: the new worktree runs in a Docker sandbox. */ + readonly sandbox: boolean; /** False for threads without a project: their folder has no branch or worktree. */ readonly canChooseWorkspace: boolean; + /** True when the selected server can create sandboxes. */ + readonly canUseSandbox: boolean; readonly selectedBranchName: string | null; readonly selectedWorktreePath: string | null; readonly startFromOrigin: boolean; @@ -205,7 +211,7 @@ type NewTaskFlowContextValue = { key: string | null, options?: ReadonlyArray, ) => void; - readonly setWorkspaceMode: (mode: WorkspaceMode) => void; + readonly setWorkspaceChoice: (choice: NewTaskWorkspaceChoice) => void; readonly selectBranch: (branch: VcsRef) => void; readonly setStartFromOrigin: (value: boolean) => void; readonly beginEditingPendingTask: (messageId: string) => boolean; @@ -511,6 +517,12 @@ export function NewTaskFlowProvider(props: React.PropsWithChildren) { const workspaceMode = canChooseWorkspace ? (selectedProjectDraft.workspaceSelection?.mode ?? defaultWorkspaceMode) : "local"; + const sandbox = resolveNewTaskSandbox({ + workspaceMode, + draftSandbox: selectedProjectDraft.workspaceSelection?.sandbox, + serverConfig: selectedEnvironmentServerConfig, + }); + const canUseSandbox = canChooseWorkspace && selectedEnvironmentServerConfig?.sandboxes === true; const selectedBranchName = selectedProjectDraft.workspaceSelection?.branch ?? null; const selectedWorktreePath = selectedProjectDraft.workspaceSelection?.worktreePath ?? null; // Keep the user's explicit choice separate from the resolved display value: @@ -796,14 +808,15 @@ export function NewTaskFlowProvider(props: React.PropsWithChildren) { [projects, selectedProject, carryDraftContentTo], ); - const setWorkspaceMode = useCallback( - (mode: WorkspaceMode) => { + const setWorkspaceChoice = useCallback( + (choice: NewTaskWorkspaceChoice) => { if (!selectedProjectDraftKey) { return; } if (!selectedProject) { return; } + const mode: WorkspaceMode = choice === "local" ? "local" : "worktree"; const localSelection = resolveNewTaskLocalWorkspaceSelection({ branches: availableBranches, projectCwd: selectedProject.workspaceRoot, @@ -819,6 +832,7 @@ export function NewTaskFlowProvider(props: React.PropsWithChildren) { branch: mode === "local" ? localSelection.branch : selectedBranchName, worktreePath: mode === "local" ? localSelection.worktreePath : selectedWorktreePath, ...(draftStartFromOrigin !== undefined ? { startFromOrigin: draftStartFromOrigin } : {}), + ...(choice === "sandbox" ? { sandbox: true } : {}), }, }); }, @@ -882,10 +896,11 @@ export function NewTaskFlowProvider(props: React.PropsWithChildren) { branchWorktreePath: branch.worktreePath, }), ...(draftStartFromOrigin !== undefined ? { startFromOrigin: draftStartFromOrigin } : {}), + ...(sandbox ? { sandbox: true } : {}), }, }); }, - [draftStartFromOrigin, selectedProject, selectedProjectDraftKey, workspaceMode], + [draftStartFromOrigin, sandbox, selectedProject, selectedProjectDraftKey, workspaceMode], ); const setStartFromOrigin = useCallback( @@ -899,10 +914,11 @@ export function NewTaskFlowProvider(props: React.PropsWithChildren) { branch: selectedBranchName, worktreePath: selectedWorktreePath, startFromOrigin: value, + ...(sandbox ? { sandbox: true } : {}), }, }); }, - [selectedBranchName, selectedProjectDraftKey, selectedWorktreePath, workspaceMode], + [sandbox, selectedBranchName, selectedProjectDraftKey, selectedWorktreePath, workspaceMode], ); const refreshBranches = branchState.refresh; @@ -989,6 +1005,7 @@ export function NewTaskFlowProvider(props: React.PropsWithChildren) { branch: message.creation.branch, worktreePath: message.creation.worktreePath, startFromOrigin: message.creation.startFromOrigin ?? false, + ...(message.creation.sandbox ? { sandbox: true } : {}), }, }); } @@ -1080,6 +1097,13 @@ export function NewTaskFlowProvider(props: React.PropsWithChildren) { ...((workspaceSelection?.startFromOrigin ?? startFromOrigin) ? { startFromOrigin: true } : {}), + ...(resolveNewTaskSandbox({ + workspaceMode: mode, + draftSandbox: workspaceSelection?.sandbox, + serverConfig: selectedEnvironmentServerConfig, + }) + ? { sandbox: true } + : {}), }, createdAt: metadata.createdAt, }; @@ -1209,7 +1233,9 @@ export function NewTaskFlowProvider(props: React.PropsWithChildren) { selectedProjectKey, selectedModelKey, workspaceMode, + sandbox, canChooseWorkspace, + canUseSandbox, selectedBranchName, selectedWorktreePath, startFromOrigin, @@ -1243,7 +1269,7 @@ export function NewTaskFlowProvider(props: React.PropsWithChildren) { openDraft, selectEnvironment, setSelectedModelKey, - setWorkspaceMode, + setWorkspaceChoice, selectBranch, setStartFromOrigin, beginEditingPendingTask, @@ -1313,11 +1339,13 @@ export function NewTaskFlowProvider(props: React.PropsWithChildren) { setRuntimeMode, setSelectedModelKey, setStartFromOrigin, - setWorkspaceMode, + setWorkspaceChoice, startFromOrigin, submitting, workspaceMode, + sandbox, canChooseWorkspace, + canUseSandbox, appendAttachments, clearAttachments, removeAttachment, diff --git a/apps/mobile/src/features/threads/worktree-setup-card.tsx b/apps/mobile/src/features/threads/worktree-setup-card.tsx index 86b71992710f8..9e5f1446fd8c3 100644 --- a/apps/mobile/src/features/threads/worktree-setup-card.tsx +++ b/apps/mobile/src/features/threads/worktree-setup-card.tsx @@ -220,13 +220,13 @@ function SetupDetailsSheet({ paddingBottom: Math.max(20, insets.bottom), }} > - {/* Agent startup is the header handoff, not a fifth setup step. */} + {/* Agent startup is the header handoff, not another setup step. */} {snapshot.stages .filter((stage) => stage.id !== "agent") .map((stage) => ( - {stage.id === "setup-script" && + {(stage.id === "setup-script" || stage.id === "sandbox") && (stage.status === "running" || stage.status === "failed" || stage.tail.length > 0) ? ( ) : null} diff --git a/apps/mobile/src/lib/projectThreadStartTurn.test.ts b/apps/mobile/src/lib/projectThreadStartTurn.test.ts index f67a4649facef..b24fd5ecba077 100644 --- a/apps/mobile/src/lib/projectThreadStartTurn.test.ts +++ b/apps/mobile/src/lib/projectThreadStartTurn.test.ts @@ -135,3 +135,34 @@ describe("new thread on an existing branch", () => { }, ); }); + +describe("new thread in a sandbox", () => { + it("asks the server to prepare the new worktree in a sandbox", () => { + const input = buildProjectThreadStartTurnInput({ + projectId: ProjectId.make("project"), + projectCwd: "/workspace", + threadId: "sandbox-thread", + commandId: "command", + messageId: "message", + createdAt: "2026-10-03T00:00:00Z", + text: "Run the services", + uploadedAttachments: [], + modelSelection: { instanceId: ProviderInstanceId.make("codex"), model: "gpt-5.6-sol" }, + runtimeMode: "full-access", + interactionMode: "default", + workspaceMode: "worktree", + branch: "main", + worktreePath: null, + startFromOrigin: false, + sandbox: true, + worktreeBranchName: "t3code/abc123", + }); + + expect(input.bootstrap.prepareWorktree).toEqual({ + projectCwd: "/workspace", + baseBranch: "main", + branch: "t3code/abc123", + sandbox: true, + }); + }); +}); diff --git a/apps/mobile/src/lib/projectThreadStartTurn.ts b/apps/mobile/src/lib/projectThreadStartTurn.ts index fa1cc704219a6..c3ab7a9c3fdd3 100644 --- a/apps/mobile/src/lib/projectThreadStartTurn.ts +++ b/apps/mobile/src/lib/projectThreadStartTurn.ts @@ -32,6 +32,8 @@ export interface ProjectThreadStartTurnSpec { readonly branch: string | null; readonly worktreePath: string | null; readonly startFromOrigin: boolean; + /** Worktree mode only: run the new worktree in a Docker sandbox. */ + readonly sandbox?: boolean; /** Generated temp branch for worktree mode; unused for local mode. */ readonly worktreeBranchName: string; } @@ -77,6 +79,7 @@ export function buildProjectThreadStartTurnInput(spec: ProjectThreadStartTurnSpe baseBranch: spec.branch!, branch: spec.worktreeBranchName, ...(spec.startFromOrigin ? { startFromOrigin: true } : {}), + ...(spec.sandbox ? { sandbox: true } : {}), }, runSetupScript: true, } diff --git a/apps/mobile/src/state/thread-outbox-model.ts b/apps/mobile/src/state/thread-outbox-model.ts index 57a788cf5188f..c046d88b53fa4 100644 --- a/apps/mobile/src/state/thread-outbox-model.ts +++ b/apps/mobile/src/state/thread-outbox-model.ts @@ -43,6 +43,7 @@ const QueuedThreadCreationSchema = Schema.Struct({ branch: Schema.NullOr(Schema.String), worktreePath: Schema.NullOr(Schema.String), startFromOrigin: Schema.optional(Schema.Boolean), + sandbox: Schema.optional(Schema.Boolean), }); export const QueuedThreadMessageSchema = Schema.Struct({ @@ -75,6 +76,8 @@ export interface QueuedThreadCreation { readonly branch: string | null; readonly worktreePath: string | null; readonly startFromOrigin?: boolean; + /** Worktree mode only: run the new worktree in a Docker sandbox. */ + readonly sandbox?: boolean; } export interface QueuedThreadMessage { diff --git a/apps/mobile/src/state/use-composer-drafts.ts b/apps/mobile/src/state/use-composer-drafts.ts index 780485c0718f6..70a4a47f3db37 100644 --- a/apps/mobile/src/state/use-composer-drafts.ts +++ b/apps/mobile/src/state/use-composer-drafts.ts @@ -359,6 +359,8 @@ export interface ComposerDraftWorkspaceSelection { readonly branch: string | null; readonly worktreePath: string | null; readonly startFromOrigin?: boolean; + /** Worktree mode only: run the new worktree in a Docker sandbox. */ + readonly sandbox?: boolean; } export type ComposerDraftSettingsUpdate = Pick< @@ -371,6 +373,7 @@ const ComposerDraftWorkspaceSelectionSchema = Schema.Struct({ branch: Schema.NullOr(Schema.String), worktreePath: Schema.NullOr(Schema.String), startFromOrigin: Schema.optional(Schema.Boolean), + sandbox: Schema.optional(Schema.Boolean), }); const ComposerDraftProjectSchema = Schema.Struct({ @@ -1196,7 +1199,8 @@ export async function removeDeliveredCloudQueuedMessage( editor.workspaceSelection.branch !== message.creation?.branch || editor.workspaceSelection.worktreePath !== message.creation?.worktreePath || (editor.workspaceSelection.startFromOrigin ?? false) !== - (message.creation?.startFromOrigin ?? false)))) + (message.creation?.startFromOrigin ?? false) || + (editor.workspaceSelection.sandbox ?? false) !== (message.creation?.sandbox ?? false)))) ) continue; const drafts = { ...saved.drafts }; diff --git a/apps/mobile/src/state/use-thread-outbox-drain.ts b/apps/mobile/src/state/use-thread-outbox-drain.ts index 454980d404a5a..0237913b4573c 100644 --- a/apps/mobile/src/state/use-thread-outbox-drain.ts +++ b/apps/mobile/src/state/use-thread-outbox-drain.ts @@ -508,6 +508,7 @@ export async function restoreRejectedQueuedMessage( ...(queuedMessage.creation.startFromOrigin !== undefined ? { startFromOrigin: queuedMessage.creation.startFromOrigin } : {}), + ...(queuedMessage.creation.sandbox ? { sandbox: true } : {}), }, } : {}), @@ -1029,6 +1030,7 @@ export function useThreadOutboxDrain(): void { branch: creation.branch, worktreePath: creation.worktreePath, startFromOrigin: creation.startFromOrigin ?? false, + sandbox: creation.sandbox === true, worktreeBranchName: buildTemporaryWorktreeBranchName(randomHex), }), }); diff --git a/apps/server/src/auth/RpcAuthorization.ts b/apps/server/src/auth/RpcAuthorization.ts index 046bf8ab2186e..40a18fb7d7cef 100644 --- a/apps/server/src/auth/RpcAuthorization.ts +++ b/apps/server/src/auth/RpcAuthorization.ts @@ -151,6 +151,9 @@ export const RPC_REQUIRED_SCOPES = { [WS_METHODS.subscribeVcsStatus]: AuthOrchestrationReadScope, [WS_METHODS.subscribeWorktreeSetup]: AuthOrchestrationReadScope, [WS_METHODS.worktreeSetupCancel]: AuthOrchestrationOperateScope, + [WS_METHODS.subscribeSandboxes]: AuthOrchestrationReadScope, + [WS_METHODS.sandboxStop]: AuthOrchestrationOperateScope, + [WS_METHODS.sandboxRemove]: AuthOrchestrationOperateScope, [WS_METHODS.subscribeResourceTelemetry]: AuthOrchestrationReadScope, [WS_METHODS.vcsRefreshStatus]: AuthOrchestrationReadScope, [WS_METHODS.vcsPull]: AuthOrchestrationOperateScope, diff --git a/apps/server/src/git/GitWorkflowService.ts b/apps/server/src/git/GitWorkflowService.ts index 912e0c1f46208..8d84f402418c9 100644 --- a/apps/server/src/git/GitWorkflowService.ts +++ b/apps/server/src/git/GitWorkflowService.ts @@ -1,6 +1,7 @@ import * as Context from "effect/Context"; import * as Effect from "effect/Effect"; import * as Layer from "effect/Layer"; +import * as Option from "effect/Option"; import { GitManagerError, @@ -29,6 +30,7 @@ import { } from "@t3tools/contracts"; import * as GitManager from "./GitManager.ts"; +import * as SandboxService from "../sandbox/SandboxService.ts"; import * as GitVcsDriver from "../vcs/GitVcsDriver.ts"; import * as VcsDriverRegistry from "../vcs/VcsDriverRegistry.ts"; @@ -159,6 +161,7 @@ export const make = Effect.gen(function* () { const registry = yield* VcsDriverRegistry.VcsDriverRegistry; const git = yield* GitVcsDriver.GitVcsDriver; const gitManager = yield* GitManager.GitManager; + const sandboxes = yield* Effect.serviceOption(SandboxService.SandboxService); const ensureGit = Effect.fn("GitWorkflowService.ensureGit")(function* ( operation: string, @@ -372,6 +375,20 @@ export const make = Effect.gen(function* () { removeWorktree: (input) => ensureGitCommand("GitWorkflowService.removeWorktree", input.cwd).pipe( Effect.andThen(git.removeWorktree(input)), + // A removed worktree's sandbox has nothing left to run. A failure + // here only leaves the container behind; startup drops it later. + Effect.tap(() => + Option.isNone(sandboxes) + ? Effect.void + : sandboxes.value.remove(input.path).pipe( + Effect.catchCause((cause) => + Effect.logWarning("Failed to remove the worktree's sandbox", { + path: input.path, + cause, + }), + ), + ), + ), ), pruneWorktrees: (input) => ensureGitCommand("GitWorkflowService.pruneWorktrees", input.cwd).pipe( diff --git a/apps/server/src/mcp/toolkits/project/tools.ts b/apps/server/src/mcp/toolkits/project/tools.ts index 693a76854bb66..528e65dd813f8 100644 --- a/apps/server/src/mcp/toolkits/project/tools.ts +++ b/apps/server/src/mcp/toolkits/project/tools.ts @@ -102,7 +102,7 @@ const ProjectCloneTool = Tool.make("t3_project_clone", { const ThreadLaunchTool = Tool.make("t3_thread_launch", { ...shared, description: - 'Create an ordinary TOP-LEVEL thread with an explicit workspace binding before its agent starts. Use this when the user requests independent work, a new thread, or a PR stack in its own worktree; use delegate_task for child subagents. Set workspaceStrategy to {type:"worktree",baseRef:"parent-branch",branch:"new-branch",startFromOrigin:false} for a new worktree based on local commits, or {type:"existing_worktree",worktreePath:"/absolute/path",branch:"existing-branch"} to use an existing checkout. For upstream commits, set startFromOrigin:true. Omitted workspaceStrategy means the project root, NOT the caller\'s worktree. Omit projectId/modelSelection/modes to inherit those settings. Set scratch:true instead of projectId for a thread without a project: it runs in a fresh folder of its own, outside any repository. Put the task in message. Do not ask the agent to create its own worktree via shell: that does not update the thread binding. Each call creates a new launch with no retry key; retain threadId and use t3_thread_read/t3_thread_wait to follow preparation. After errors or lost responses, inspect t3_thread_list before retrying. Attachments must be pending uploads. Requires a full-access/default caller.', + 'Create an ordinary TOP-LEVEL thread with an explicit workspace binding before its agent starts. Use this when the user requests independent work, a new thread, or a PR stack in its own worktree; use delegate_task for child subagents. Set workspaceStrategy to {type:"worktree",baseRef:"parent-branch",branch:"new-branch",startFromOrigin:false} for a new worktree based on local commits, or {type:"existing_worktree",worktreePath:"/absolute/path",branch:"existing-branch"} to use an existing checkout. For upstream commits, set startFromOrigin:true. Add sandbox:true to a worktree strategy to run the thread\'s agent, terminals, and setup script in a Docker sandbox with its own ports and services (Claude and Codex only). Omitted workspaceStrategy means the project root, NOT the caller\'s worktree. Omit projectId/modelSelection/modes to inherit those settings. Set scratch:true instead of projectId for a thread without a project: it runs in a fresh folder of its own, outside any repository. Put the task in message. Do not ask the agent to create its own worktree via shell: that does not update the thread binding. Each call creates a new launch with no retry key; retain threadId and use t3_thread_read/t3_thread_wait to follow preparation. After errors or lost responses, inspect t3_thread_list before retrying. Attachments must be pending uploads. Requires a full-access/default caller.', parameters: Schema.Struct({ projectId: Schema.optional(ProjectId), scratch: Schema.optional( diff --git a/apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.ts b/apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.ts index 0aca36abe77c6..4d67452f63c37 100644 --- a/apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.ts +++ b/apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.ts @@ -33,7 +33,7 @@ import type { WebSearchOutput, } from "@anthropic-ai/claude-agent-sdk/sdk-tools"; import { parseCliArgs } from "@t3tools/shared/cliArgs"; -import { HostProcessEnvironment } from "@t3tools/shared/hostProcess"; +import { HostProcessEnvironment, HostProcessPlatform } from "@t3tools/shared/hostProcess"; import { applyClaudePromptEffortPrefix } from "@t3tools/shared/model"; import { CLAUDE_RESUME_COMPACTION_NEVER_ANSWER, @@ -92,6 +92,8 @@ import { planClaudeSkillDispatch } from "../../provider/Drivers/ClaudeSkillDispa import { discoverClaudeSkills } from "../../provider/Drivers/ClaudeSkills.ts"; import { compileClaudeModelSelection } from "../../claudeModelOptions.ts"; import * as ServerConfig from "../../config.ts"; +import { sandboxClaudeSpawn } from "../../sandbox/sandboxClaudeSpawn.ts"; +import * as SandboxService from "../../sandbox/SandboxService.ts"; import { expandHomePath } from "../../pathExpansion.ts"; import { claudeSignedOutMessage, @@ -801,6 +803,8 @@ export const claudeAgentSdkQueryRunnerLiveLayer: Layer.Layer< ); export function makeClaudeQueryOptions(input: { + /** Set for sandboxed worktrees: starts the CLI inside the sandbox. */ + readonly spawnClaudeCodeProcess?: ClaudeQueryOptions["spawnClaudeCodeProcess"]; readonly modelSelection: ModelSelection; readonly nativeThreadId: string; readonly resume: boolean; @@ -903,6 +907,9 @@ export function makeClaudeQueryOptions(input: { ? { pathToClaudeCodeExecutable: input.settings.binaryPath } : {}), ...(input.environment === undefined ? {} : { env: input.environment }), + ...(input.spawnClaudeCodeProcess === undefined + ? {} + : { spawnClaudeCodeProcess: input.spawnClaudeCodeProcess }), ...(input.mcpServers === undefined ? {} : { mcpServers: input.mcpServers }), systemPrompt: { type: "preset" as const, @@ -2925,6 +2932,8 @@ export interface ClaudeAdapterV2Options { readonly path: Path.Path; readonly idAllocator: IdAllocator.IdAllocatorV2Shape; readonly queryRunner: ClaudeAgentSdkQueryRunnerShape; + /** Runs turns whose cwd is in a sandboxed worktree inside its container. */ + readonly sandboxes?: SandboxService.SandboxService["Service"]; readonly scopedLimitNames?: Ref.Ref; readonly onUsageLimits?: ServerProviderShape["applyUsageLimits"]; /** Sink for wake-turn continuation requests; defaults to dropping them. */ @@ -2965,6 +2974,41 @@ export function makeClaudeAdapterV2( Effect.provideService(Path.Path, path), ); + // A sandboxed worktree runs the CLI in its container. On macOS the host + // keeps Claude's login in the Keychain, which a Linux container cannot + // read, so the sandbox needs a token or a credentials file. + const claudeSandboxSpawn = (cwd: string | null) => + Effect.gen(function* () { + if (adapterOptions.sandboxes === undefined || cwd === null) return undefined; + const target = yield* adapterOptions.sandboxes + .execTarget(cwd) + .pipe(Effect.mapError((cause) => queryRunnerError(cause, "sandbox"))); + if (Option.isNone(target)) return undefined; + const env = adapterOptions.environment; + if ( + (yield* HostProcessPlatform) === "darwin" && + !env.CLAUDE_CODE_OAUTH_TOKEN && + !env.ANTHROPIC_API_KEY && + !env.ANTHROPIC_AUTH_TOKEN && + !(yield* fileSystem + .exists( + path.join( + env.CLAUDE_CONFIG_DIR ?? path.join(env.HOME ?? "", ".claude"), + ".credentials.json", + ), + ) + .pipe(Effect.orElseSucceed(() => false))) + ) { + return yield* queryRunnerError( + new Error( + "Claude in a sandbox needs a token on macOS. Run `claude setup-token`, then add CLAUDE_CODE_OAUTH_TOKEN to the Claude provider's environment variables.", + ), + "sandbox", + ); + } + return sandboxClaudeSpawn(target.value); + }); + return ProviderAdapter.ProviderAdapterV2.of({ instanceId: adapterOptions.instanceId, driver: CLAUDE_PROVIDER, @@ -6934,7 +6978,9 @@ export function makeClaudeAdapterV2( const hasPersistedProviderTurn = turnInput.providerTurnOrdinal > 1; const shouldResume = resumeSessionAt !== undefined || openedWithResume || hasPersistedProviderTurn; + const sandbox = yield* claudeSandboxSpawn(turnInput.runtimePolicy.cwd); const queryOptions = makeClaudeQueryOptions({ + ...(sandbox === undefined ? {} : { spawnClaudeCodeProcess: sandbox }), modelSelection: turnInput.modelSelection, nativeThreadId, resume: shouldResume, @@ -7740,6 +7786,7 @@ export const createClaudeAdapterV2 = Effect.fn("ClaudeAdapterV2Driver.create")( const queryRunner = yield* ClaudeAgentSdkQueryRunner; const serverConfig = yield* ServerConfig.ServerConfig; const continuationRequests = yield* ProviderContinuationRequests.ProviderContinuationRequests; + const sandboxes = yield* Effect.serviceOption(SandboxService.SandboxService); const baseEnvironment = mergeProviderInstanceEnvironment(environment, hostEnvironment); const claudeEnvironment = yield* makeClaudeEnvironment(config, baseEnvironment); const path = yield* Path.Path; @@ -7757,6 +7804,7 @@ export const createClaudeAdapterV2 = Effect.fn("ClaudeAdapterV2Driver.create")( idAllocator, queryRunner, continuationRequests, + ...(Option.isSome(sandboxes) ? { sandboxes: sandboxes.value } : {}), ...hooks, }); }, diff --git a/apps/server/src/orchestration-v2/Adapters/CodexAdapterV2.ts b/apps/server/src/orchestration-v2/Adapters/CodexAdapterV2.ts index 19c3486f5af78..4e6ac65a1dc33 100644 --- a/apps/server/src/orchestration-v2/Adapters/CodexAdapterV2.ts +++ b/apps/server/src/orchestration-v2/Adapters/CodexAdapterV2.ts @@ -83,6 +83,7 @@ import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process"; import { resolveAttachmentPath } from "../../attachmentStore.ts"; import { getCodexServiceTierOptionValue } from "../../codexModelOptions.ts"; import { ServerConfig } from "../../config.ts"; +import * as SandboxService from "../../sandbox/SandboxService.ts"; import { expandHomePath } from "../../pathExpansion.ts"; import { buildCodexAdditionalContext, @@ -703,6 +704,12 @@ export function buildCodexTurnStartParams(input: { readonly deviceToolsAvailable?: boolean; /** ChatGPT token sharing does not accept service tiers. */ readonly omitServiceTier?: boolean; + /** + * The turn runs in a Docker sandbox. Codex's own sandbox cannot create + * namespaces inside a container, so the container is the boundary and the + * runtime mode's approval policy still applies. + */ + readonly sandboxed?: boolean; }) { return Effect.gen(function* () { const runtimeModeDefaults = codexRuntimeModeTurnDefaults(input.runtimePolicy.runtimeMode); @@ -711,9 +718,11 @@ export function buildCodexTurnStartParams(input: { ? runtimeModeDefaults.approvalPolicy : yield* decodeTurnApprovalPolicy(input.runtimePolicy.approvalPolicy); const sandboxPolicy = - input.runtimePolicy.sandboxPolicy === undefined - ? runtimeModeDefaults.sandboxPolicy - : yield* decodeTurnSandboxPolicy(input.runtimePolicy.sandboxPolicy); + input.runtimePolicy.sandboxPolicy !== undefined + ? yield* decodeTurnSandboxPolicy(input.runtimePolicy.sandboxPolicy) + : input.sandboxed === true + ? ({ type: "dangerFullAccess" } as const) + : runtimeModeDefaults.sandboxPolicy; const selectedEffort = getModelSelectionStringOptionValue( input.modelSelection, "reasoningEffort", @@ -1385,6 +1394,7 @@ export const codexAppServerClientFactoryFromSettingsLayer: Layer.Layer< Effect.gen(function* () { const spawner = yield* ChildProcessSpawner.ChildProcessSpawner; const { native: nativeEventLogger } = yield* ProviderEventLoggers; + const sandboxes = yield* Effect.serviceOption(SandboxService.SandboxService); return CodexAppServerClientFactory.of({ open: (input) => @@ -1394,13 +1404,47 @@ export const codexAppServerClientFactoryFromSettingsLayer: Layer.Layer< ...input.environment, ...(input.settings.homePath ? { CODEX_HOME: input.settings.homePath } : {}), }; - const command = yield* makeCodexAppServerSpawnCommand({ - command: input.settings.binaryPath || "codex", - args: codexAppServerArgs( - resolveCodexLaunchArgs(input.settings.launchArgs, input.environment), - ), - env: environment, - }); + const args = codexAppServerArgs( + resolveCodexLaunchArgs(input.settings.launchArgs, input.environment), + ); + const openError = (cause: unknown) => + new ProviderAdapterOpenSessionError({ + driver: CODEX_PROVIDER, + providerSessionId: input.providerSessionId, + cause, + }); + const cwd = input.runtimePolicy.cwd; + const sandbox = + Option.isNone(sandboxes) || cwd === null + ? Option.none() + : yield* sandboxes.value.execTarget(cwd).pipe(Effect.mapError(openError)); + // In a sandbox the image's own `codex` runs the app-server; the + // host binary may not even be a Linux build. + const command = Option.isSome(sandbox) + ? yield* Effect.try({ + try: () => + sandbox.value.command({ + command: "codex", + args, + cwd: cwd ?? sandbox.value.worktreePath, + env: environment, + tty: false, + }), + catch: openError, + }).pipe( + Effect.tap((plan) => Scope.addFinalizer(scope, Effect.sync(plan.release))), + Effect.map((plan) => + ChildProcess.make(plan.command, [...plan.args], { + env: plan.env, + extendEnv: false, + }), + ), + ) + : yield* makeCodexAppServerSpawnCommand({ + command: input.settings.binaryPath || "codex", + args, + env: environment, + }); const handle = yield* spawner.spawn(command).pipe( Effect.provideService(Scope.Scope, scope), Effect.mapError( @@ -1452,6 +1496,7 @@ export const createCodexAdapterV2 = ( const hostEnvironment = yield* HostProcessEnvironment; const idAllocator = yield* IdAllocatorV2; const serverConfig = yield* ServerConfig; + const sandboxes = yield* Effect.serviceOption(SandboxService.SandboxService); const homeLayout = yield* resolveCodexHomeLayout(config); yield* materializeCodexShadowHome(homeLayout).pipe( @@ -1482,6 +1527,7 @@ export const createCodexAdapterV2 = ( idAllocator, serverConfig, continuationRequests, + ...(Option.isSome(sandboxes) ? { sandboxes: sandboxes.value } : {}), ...hooks, }); }); @@ -1535,6 +1581,8 @@ export interface CodexAdapterV2Options { readonly fileSystem: FileSystem.FileSystem; readonly idAllocator: IdAllocatorV2Shape; readonly serverConfig: ServerConfig["Service"]; + /** Tells turns whether their cwd is in a sandboxed worktree. */ + readonly sandboxes?: SandboxService.SandboxService["Service"]; /** * Sink for post-settle background command completions so the orchestrator * can start a continuation run. Optional: adapters that omit it keep @@ -5546,6 +5594,10 @@ export function makeCodexAdapterV2(adapterOptions: CodexAdapterV2Options): Provi browserToolsAvailable: mcpSession?.browserToolsAvailable ?? true, deviceToolsAvailable: mcpSession?.capabilities?.has("device") ?? false, omitServiceTier: adapterOptions.resolveRuntime !== undefined, + sandboxed: + adapterOptions.sandboxes !== undefined && + turnInput.runtimePolicy.cwd !== null && + (yield* adapterOptions.sandboxes.isSandboxed(turnInput.runtimePolicy.cwd)), }); yield* Ref.update(pendingRootTurns, (current) => { const updated = new Map(current); diff --git a/apps/server/src/orchestration-v2/IdAllocator.ts b/apps/server/src/orchestration-v2/IdAllocator.ts index f619e45095c09..d19f760c9c72a 100644 --- a/apps/server/src/orchestration-v2/IdAllocator.ts +++ b/apps/server/src/orchestration-v2/IdAllocator.ts @@ -127,8 +127,13 @@ export interface IdAllocatorV2AllocateShape { } export interface IdAllocatorV2DeriveShape { + /** + * The shared session for adapters that serve many threads from one process. + * A sandboxed worktree gets its own, because its process runs in the container. + */ readonly providerSession: (input: { readonly providerInstanceId: ProviderInstanceId; + readonly sandboxWorktreePath?: string; }) => ProviderSessionId; readonly delegatedTaskNode: (input: { readonly commandId: CommandId }) => NodeId; readonly delegatedTaskThread: (input: { readonly commandId: CommandId }) => ThreadId; @@ -389,7 +394,16 @@ export const layer: Layer.Layer = Layer.succeed( derive: { providerSession: (input) => ProviderSessionId.make( - joinId("provider-session", "provider-instance", input.providerInstanceId, "shared"), + input.sandboxWorktreePath === undefined + ? joinId("provider-session", "provider-instance", input.providerInstanceId, "shared") + : joinId( + "provider-session", + "provider-instance", + input.providerInstanceId, + "shared", + "sandbox", + input.sandboxWorktreePath, + ), ), delegatedTaskNode: (input) => NodeId.make(joinId("node", "delegated-task", input.commandId)), delegatedTaskThread: (input) => diff --git a/apps/server/src/orchestration-v2/Orchestrator.ts b/apps/server/src/orchestration-v2/Orchestrator.ts index 2707fe5b83441..77c4730495d7c 100644 --- a/apps/server/src/orchestration-v2/Orchestrator.ts +++ b/apps/server/src/orchestration-v2/Orchestrator.ts @@ -103,6 +103,7 @@ import { ProviderSessionManagerV2 } from "./ProviderSessionManager.ts"; import { ProviderSwitchServiceV2 } from "./ProviderSwitchService.ts"; import { isAutomaticCompletionRun, queuedRunsInDeliveryOrder } from "./QueuedRunOrder.ts"; import { RuntimePolicyV2 } from "./RuntimePolicy.ts"; +import * as SandboxService from "../sandbox/SandboxService.ts"; import { makeSubagentChildThread, subagentResultForRun, @@ -741,6 +742,7 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio const providerSessions = yield* ProviderSessionManagerV2; const providerSwitchService = yield* ProviderSwitchServiceV2; const runtimePolicy = yield* RuntimePolicyV2; + const sandboxes = yield* Effect.serviceOption(SandboxService.SandboxService); const threadForkService = yield* ThreadForkServiceV2; const threadDispatch = yield* ThreadCommandExecutor; @@ -770,23 +772,53 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio ), ); + /** + * The shared session id for adapters that serve many threads from one + * process, or null for adapters with a session per thread. A shared process + * runs where it was opened, so threads in a sandbox never share one with + * the host or another sandbox. + */ + const sharedProviderSessionIdFor = (input: { + readonly adapter: ProviderAdapterV2Shape; + readonly providerInstanceId: ProviderInstanceId; + readonly worktreePath: string | null; + }) => + Effect.gen(function* () { + const capabilities = yield* input.adapter.getCapabilities(); + if (!capabilities.sessions.supportsMultipleProviderThreadsPerSession) return null; + const worktreePath = input.worktreePath; + const sandboxed = + worktreePath !== null && + Option.isSome(sandboxes) && + (yield* sandboxes.value.isSandboxed(worktreePath)); + return idAllocator.derive.providerSession({ + providerInstanceId: input.providerInstanceId, + ...(sandboxed ? { sandboxWorktreePath: worktreePath } : {}), + }); + }); + + /** + * The session a run uses. A shared session always comes from the thread's + * current worktree rather than `persisted`: a launch records one before its + * worktree and sandbox exist. For host threads that is the same id. + */ const providerSessionIdFor = (input: { readonly adapter: ProviderAdapterV2Shape; readonly providerInstanceId: ProviderInstanceId; readonly threadId: ThreadId; + readonly worktreePath: string | null; + readonly persisted: ProviderSessionId | null | undefined; }) => - input.adapter.getCapabilities().pipe( - Effect.flatMap((capabilities) => - capabilities.sessions.supportsMultipleProviderThreadsPerSession - ? Effect.succeed( - idAllocator.derive.providerSession({ + sharedProviderSessionIdFor(input).pipe( + Effect.flatMap((shared) => + shared !== null + ? Effect.succeed(shared) + : input.persisted !== null && input.persisted !== undefined + ? Effect.succeed(input.persisted) + : idAllocator.allocate.providerSession({ providerInstanceId: input.providerInstanceId, + threadId: input.threadId, }), - ) - : idAllocator.allocate.providerSession({ - providerInstanceId: input.providerInstanceId, - threadId: input.threadId, - }), ), ); @@ -1483,29 +1515,32 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio }), ), )); - const providerSessionId = - (!canResumeAcrossInstances && - queuedProviderThread.providerSessionId !== null && - !switchPlan?.releaseProviderSessionIds.includes(queuedProviderThread.providerSessionId) - ? queuedProviderThread.providerSessionId - : null) ?? - (yield* providerAdapters.get(queuedRun.providerInstanceId).pipe( - Effect.flatMap((adapter) => - providerSessionIdFor({ - adapter, - providerInstanceId: queuedRun.providerInstanceId, - threadId, + const providerSessionId = yield* providerAdapters.get(queuedRun.providerInstanceId).pipe( + Effect.flatMap((adapter) => + providerSessionIdFor({ + adapter, + providerInstanceId: queuedRun.providerInstanceId, + threadId, + worktreePath: projection.thread.worktreePath, + persisted: + !canResumeAcrossInstances && + queuedProviderThread.providerSessionId !== null && + !switchPlan?.releaseProviderSessionIds.includes( + queuedProviderThread.providerSessionId, + ) + ? queuedProviderThread.providerSessionId + : null, + }), + ), + Effect.mapError( + (cause) => + new OrchestratorDispatchError({ + commandId, + commandType: "message.dispatch", + cause, }), - ), - Effect.mapError( - (cause) => - new OrchestratorDispatchError({ - commandId, - commandType: "message.dispatch", - cause, - }), - ), - )); + ), + ); const providerThread: OrchestrationV2ProviderThread = { ...deliveryProviderThread, providerSessionId, @@ -3945,15 +3980,15 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio input.projection, input.modelSelection.instanceId, ).find((candidate) => candidate.id !== providerThread.id); - const targetProviderSessionId = - existingTargetProviderThread?.providerSessionId ?? - (yield* mapDispatchError(input.command)( - providerSessionIdFor({ - adapter: targetAdapter, - providerInstanceId: input.modelSelection.instanceId, - threadId: input.command.threadId, - }), - )); + const targetProviderSessionId = yield* mapDispatchError(input.command)( + providerSessionIdFor({ + adapter: targetAdapter, + providerInstanceId: input.modelSelection.instanceId, + threadId: input.command.threadId, + worktreePath: input.projection.thread.worktreePath, + persisted: existingTargetProviderThread?.providerSessionId, + }), + ); const targetProviderThreadBase: OrchestrationV2ProviderThread = existingTargetProviderThread === undefined ? { @@ -5024,15 +5059,15 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio }), ), ); - const providerSessionId = - activeProviderThread?.providerSessionId ?? - (yield* mapDispatchError(command)( - providerSessionIdFor({ - adapter, - providerInstanceId: modelSelection.instanceId, - threadId: command.threadId, - }), - )); + const providerSessionId = yield* mapDispatchError(command)( + providerSessionIdFor({ + adapter, + providerInstanceId: modelSelection.instanceId, + threadId: command.threadId, + worktreePath: projection.thread.worktreePath, + persisted: activeProviderThread?.providerSessionId, + }), + ); const providerThreadId = activeProviderThread?.id ?? idAllocator.derive.providerThread({ @@ -5409,15 +5444,15 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio isProviderSwitch && !canResumeAcrossInstances ? rootProviderThreadsForProvider(projection, modelSelection.instanceId)[0] : activeProviderThread; - const providerSessionId = - (canResumeAcrossInstances ? undefined : targetProviderThread?.providerSessionId) ?? - (yield* mapDispatchError(command)( - providerSessionIdFor({ - adapter, - providerInstanceId: modelSelection.instanceId, - threadId: command.threadId, - }), - )); + const providerSessionId = yield* mapDispatchError(command)( + providerSessionIdFor({ + adapter, + providerInstanceId: modelSelection.instanceId, + threadId: command.threadId, + worktreePath: projection.thread.worktreePath, + persisted: canResumeAcrossInstances ? undefined : targetProviderThread?.providerSessionId, + }), + ); const existingProviderSession = projection.providerSessions.find( (candidate) => candidate.id === providerSessionId, ); @@ -7576,6 +7611,33 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio }) .pipe(mapDispatchError(command)); const emitEvent = emit(events, command); + // The run's session was picked when the message arrived, before the + // worktree (and any sandbox) existed. Re-pick a shared one now. + const preparedAdapter = yield* providerAdapters + .get(state.run.providerInstanceId) + .pipe(mapDispatchError(command)); + const preparedSessionId = yield* sharedProviderSessionIdFor({ + adapter: preparedAdapter, + providerInstanceId: state.run.providerInstanceId, + worktreePath: projection.thread.worktreePath, + }).pipe(mapDispatchError(command)); + if ( + preparedSessionId !== null && + preparedSessionId !== state.providerThread.providerSessionId + ) { + yield* emitEvent({ + type: "provider-thread.updated", + threadId: command.threadId, + driver: state.providerThread.driver, + providerInstanceId: state.run.providerInstanceId, + occurredAt: now, + payload: { + ...state.providerThread, + providerSessionId: preparedSessionId, + updatedAt: now, + }, + }); + } yield* emitEvent({ type: "checkpoint-scope.created", threadId: command.threadId, diff --git a/apps/server/src/orchestration-v2/ProviderSessionManager.ts b/apps/server/src/orchestration-v2/ProviderSessionManager.ts index c1039c2a0207d..f0e85ccf37139 100644 --- a/apps/server/src/orchestration-v2/ProviderSessionManager.ts +++ b/apps/server/src/orchestration-v2/ProviderSessionManager.ts @@ -34,6 +34,7 @@ import * as ProjectService from "../project/ProjectService.ts"; import * as McpProviderSession from "../mcp/McpProviderSession.ts"; import * as ServerSettings from "../serverSettings.ts"; import * as McpSessionRegistry from "../mcp/McpSessionRegistry.ts"; +import * as SandboxService from "../sandbox/SandboxService.ts"; import * as EventSink from "./EventSink.ts"; import * as IdAllocator from "./IdAllocator.ts"; import { makeKeyedSerialExecutor } from "./KeyedSerialExecutor.ts"; @@ -70,6 +71,9 @@ export type ProviderSessionReleaseReason = typeof ProviderSessionReleaseReason.T * terminalizes provider-bound work and retires non-replayable effects; a later * user command or durable replay-safe operation opens a session lazily. */ +/** Provider drivers that run inside a worktree's Docker sandbox. */ +const SANDBOX_DRIVERS: ReadonlySet = new Set(["codex", "claudeAgent"]); + export class ProviderSessionOpenError extends Schema.TaggedError()( "ProviderSessionOpenError", { @@ -198,6 +202,8 @@ interface LiveSessionEntry { */ readonly mcpCredentialIdByThread: ReadonlyMap; readonly supportsMultipleProviderThreads: boolean; + /** Where the session's process runs. A sandboxed worktree's sessions die with its container. */ + readonly cwd: string | null; readonly runtime: ProviderAdapterV2SessionRuntime; readonly exposedRuntime: ProviderAdapterV2SessionRuntime; readonly eventSubscribers: Ref.Ref< @@ -308,6 +314,20 @@ export const layerWithOptions = ( Effect.gen(function* () { const registry = yield* ProviderAdapterRegistry.ProviderAdapterRegistryV2; const fileSystem = yield* FileSystem.FileSystem; + const sandboxes = yield* Effect.serviceOption(SandboxService.SandboxService); + // How often each sandboxed worktree stopped. An open that sees the count + // change holds a client whose process died with the container. + const sandboxStops = new Map(); + const isInside = (worktreePath: string, cwd: string) => + cwd === worktreePath || cwd.startsWith(`${worktreePath}/`); + const stopCount = (cwd: string | null) => { + if (cwd === null) return 0; + let count = 0; + for (const [worktreePath, stops] of sandboxStops) { + if (isInside(worktreePath, cwd)) count += stops; + } + return count; + }; const mcpSessionRegistry = yield* McpSessionRegistry.McpSessionRegistry; /** * Optional so the many focused tests that assemble this layer by hand do @@ -801,11 +821,19 @@ export const layerWithOptions = ( const removeLiveEntry = (input: { readonly providerSessionId: ProviderSessionId; readonly onlyIfIdleGeneration?: number; + /** + * Release only the session this entry holds, never a replacement that + * took its id. Compared by runtime: activity updates replace the entry. + */ + readonly onlyIfEntry?: LiveSessionEntry; }): Effect.Effect, DateTime.Utc]> => Effect.gen(function* () { const key = sessionKey(input.providerSessionId); const candidate = (yield* Ref.get(sessions)).get(key); - if (candidate === undefined) { + if ( + candidate === undefined || + (input.onlyIfEntry !== undefined && candidate.runtime !== input.onlyIfEntry.runtime) + ) { return [Option.none(), yield* DateTime.now] as const; } const removed = yield* Effect.zip( @@ -841,6 +869,7 @@ export const layerWithOptions = ( readonly detail?: string; readonly cancelIdleFiber?: boolean; readonly onlyIfIdleGeneration?: number; + readonly onlyIfEntry?: LiveSessionEntry; readonly gracefulSubscribers?: boolean; }) => Effect.acquireUseRelease( @@ -1660,6 +1689,34 @@ export const layerWithOptions = ( }); yield* Effect.addFinalizer(() => shutdown); + // A stopped or removed sandbox took its sessions' processes with it. + // Release them so the next turn opens a fresh session, restarting the + // sandbox, instead of reusing a dead client. + if (Option.isSome(sandboxes)) { + yield* sandboxes.value.stopped.pipe( + Stream.runForEach((worktreePath) => + Effect.gen(function* () { + sandboxStops.set(worktreePath, (sandboxStops.get(worktreePath) ?? 0) + 1); + const dead = [...(yield* Ref.get(sessions)).values()].filter( + (entry) => entry.cwd !== null && isInside(worktreePath, entry.cwd), + ); + yield* Effect.forEach( + dead, + (entry) => + releaseEntry({ + providerSessionId: entry.runtime.providerSessionId, + reason: "runtime_error", + detail: "The sandbox stopped.", + onlyIfEntry: entry, + }).pipe(Effect.ignore), + { discard: true }, + ); + }), + ), + Effect.forkScoped, + ); + } + return ProviderSessionManagerV2.of({ shutdown, open: (input) => @@ -1681,6 +1738,36 @@ export const layerWithOptions = ( } const key = sessionKey(input.providerSessionId); const existing = (yield* Ref.get(sessions)).get(key); + // Only these adapters start their CLI through the sandbox. Any + // other provider would run on the host, outside the sandbox the + // user chose, so it fails instead, also when it would reuse a + // session that is already open. + if ( + cwd !== null && + Option.isSome(sandboxes) && + (yield* sandboxes.value.isSandboxed(cwd)) + ) { + const driver = + existing?.runtime.driver ?? + (yield* registry.get(input.modelSelection.instanceId).pipe( + Effect.map((adapter) => adapter.driver), + Effect.mapError( + (cause) => + new ProviderSessionOpenError({ + instanceId: input.modelSelection.instanceId, + providerSessionId: input.providerSessionId, + cause, + }), + ), + )); + if (!SANDBOX_DRIVERS.has(driver)) { + return yield* new ProviderSessionOpenError({ + instanceId: input.modelSelection.instanceId, + providerSessionId: input.providerSessionId, + cause: `${driver} cannot run in a sandbox yet. Use Claude or Codex in this thread.`, + }); + } + } if (existing !== undefined) { if ( !existing.attachedThreadIds.has(input.threadId) && @@ -1727,6 +1814,7 @@ export const layerWithOptions = ( dropMcpCredentialReservation(input.threadId, mcpCredentialId); } }); + const stopsAtOpen = stopCount(cwd); const sessionScope = yield* Scope.make(); const runtime = yield* adapter .openSession({ @@ -1788,6 +1876,7 @@ export const layerWithOptions = ( supportsMultipleProviderThreads: runtime.providerSession.capabilities.sessions .supportsMultipleProviderThreadsPerSession, + cwd, runtime, exposedRuntime, eventSubscribers, @@ -1807,6 +1896,20 @@ export const layerWithOptions = ( // The entry now guards the credential via its recorded id, so // the pre-open reservation can be dropped. yield* dropReservation; + if (stopCount(cwd) !== stopsAtOpen) { + yield* releaseEntry({ + providerSessionId: input.providerSessionId, + reason: "runtime_error", + detail: "The sandbox stopped while the session was opening.", + onlyIfEntry: entry, + }).pipe(logReleaseFailure(input.providerSessionId)); + return yield* new ProviderSessionOpenError({ + instanceId: input.modelSelection.instanceId, + providerSessionId: input.providerSessionId, + cause: + "The sandbox stopped while the session was opening. Send the message again.", + }); + } yield* withActivityError( input.providerSessionId, writeProviderSessionEvents({ diff --git a/apps/server/src/orchestration-v2/ThreadLaunchService.ts b/apps/server/src/orchestration-v2/ThreadLaunchService.ts index faf6133769208..8c3a4a025423d 100644 --- a/apps/server/src/orchestration-v2/ThreadLaunchService.ts +++ b/apps/server/src/orchestration-v2/ThreadLaunchService.ts @@ -35,6 +35,7 @@ import * as ProjectService from "../project/ProjectService.ts"; import * as ProjectSetupScriptRunner from "../project/ProjectSetupScriptRunner.ts"; import * as ManagedProjectFolders from "../project/ManagedProjectFolders.ts"; import * as ProviderRegistry from "../provider/Services/ProviderRegistry.ts"; +import * as SandboxService from "../sandbox/SandboxService.ts"; import * as ServerSettings from "../serverSettings.ts"; import * as TextGeneration from "../textGeneration/TextGeneration.ts"; import * as CommandReceiptStore from "./CommandReceiptStore.ts"; @@ -55,6 +56,7 @@ export type ThreadLaunchWorkspaceStrategy = readonly baseRef: string; readonly branch?: string | undefined; readonly startFromOrigin?: boolean | undefined; + readonly sandbox?: boolean | undefined; }; export interface ThreadLaunchInitialMessage { @@ -104,6 +106,7 @@ export class ThreadLaunchError extends Schema.TaggedError()( "read-receipt", "generate-metadata", "provision-worktree", + "provision-sandbox", "run-setup-script", "create-thread", "update-thread", @@ -156,6 +159,7 @@ const make = Effect.gen(function* () { const ids = yield* IdAllocator.IdAllocatorV2; const threads = yield* ThreadManagement.ThreadManagementService; const managedFolders = yield* ManagedProjectFolders.ManagedProjectFolders; + const sandboxes = yield* Effect.serviceOption(SandboxService.SandboxService); const preparationScope = yield* Scope.make("sequential"); const scheduledLaunches = yield* Ref.make>(new Set()); yield* Effect.addFinalizer(() => Scope.close(preparationScope, Exit.void)); @@ -217,6 +221,7 @@ const make = Effect.gen(function* () { ); const tracked = input.workspaceStrategy.type === "worktree"; + const sandboxed = tracked && input.workspaceStrategy.sandbox === true; let createdWorktreePath: string | null = null; let setupTerminalId: string | null = null; if (tracked) { @@ -224,7 +229,9 @@ const make = Effect.gen(function* () { threadId, branch: input.workspaceStrategy.branch ?? null, baseRef: input.workspaceStrategy.baseRef, - stages: ["fetch", "checkout", "setup-script", "agent"], + stages: sandboxed + ? ["fetch", "checkout", "sandbox", "setup-script", "agent"] + : ["fetch", "checkout", "setup-script", "agent"], fiber: yield* Effect.fiber, }); } @@ -354,6 +361,25 @@ const make = Effect.gen(function* () { worktreePath = worktree.worktree.path; branch = worktree.worktree.refName; createdWorktreePath = worktreePath; + // Registered before the thread shows its worktree, so nothing opened + // there can start on the host while the sandbox is still starting. + if (sandboxed) { + if (Option.isNone(sandboxes)) { + return yield* mapError( + input, + "provision-sandbox", + threadId, + )("This server cannot run sandboxes."); + } + yield* sandboxes.value + .register({ + worktreePath, + projectRoot: project.workspaceRoot, + providers: yield* providerRegistry.getProviders, + homes: SandboxService.sandboxProviderHomes(yield* serverSettings.getSettings), + }) + .pipe(Effect.mapError(mapError(input, "provision-sandbox", threadId))); + } yield* setupTracker.update(threadId, (snapshot) => ({ ...snapshot, worktreePath, branch })); yield* setupTracker.stageStatus(threadId, "checkout", "done"); } @@ -410,6 +436,19 @@ const make = Effect.gen(function* () { ); } + // The sandbox starts before the setup script so the script installs + // dependencies and services inside it. + if (sandboxed && worktreePath !== null && Option.isSome(sandboxes)) { + yield* setupTracker.stageStatus(threadId, "sandbox", "running"); + yield* sandboxes.value + .start({ + worktreePath, + onOutput: (line) => setupTracker.appendTail(threadId, "sandbox", line), + }) + .pipe(Effect.mapError(mapError(input, "provision-sandbox", threadId))); + yield* setupTracker.stageStatus(threadId, "sandbox", "done"); + } + const cwd = worktreePath ?? project.workspaceRoot; if (runId !== null) { yield* threads diff --git a/apps/server/src/preview/PortScanner.ts b/apps/server/src/preview/PortScanner.ts index 9eee1a3e215ee..0523b20210991 100644 --- a/apps/server/src/preview/PortScanner.ts +++ b/apps/server/src/preview/PortScanner.ts @@ -39,6 +39,7 @@ import * as Semaphore from "effect/Semaphore"; import { FetchHttpClient, HttpClient } from "effect/unstable/http"; import * as ProcessRunner from "../processRunner.ts"; +import * as SandboxService from "../sandbox/SandboxService.ts"; export class PortDiscovery extends Context.Service< PortDiscovery, @@ -295,6 +296,7 @@ export const make = Effect.gen(function* PortDiscoveryMake() { const processRunner = yield* ProcessRunner.ProcessRunner; const hostPlatform = yield* HostProcessPlatform; const httpClient = (yield* HttpClient.HttpClient).pipe(HttpClient.withScope); + const sandboxes = yield* Effect.serviceOption(SandboxService.SandboxService); const stateRef = yield* Ref.make({ listeners: new Map(), terminalProcesses: new Map(), @@ -390,10 +392,46 @@ export const make = Effect.gen(function* PortDiscoveryMake() { return groups; }; - const probeWebServers = Effect.fn("PortDiscovery.probeWebServers")(function* ( + /** + * Sandbox apps listen inside their container; the server forwards each port + * to a host loopback port. Those listeners belong to the server process, so + * they are labeled with the container port, and added when no listener + * probe (lsof) found them. + */ + const withSandboxPorts = ( servers: ReadonlyArray, + ): ReadonlyArray => { + if (Option.isNone(sandboxes)) return servers; + const forwarded = new Map( + sandboxes.value.forwardedPorts().map((port) => [port.hostPort, port] as const), + ); + if (forwarded.size === 0) return servers; + const label = (containerPort: number) => `sandbox :${containerPort}`; + const labeled = servers.map((server) => { + const port = forwarded.get(server.port); + return port === undefined ? server : { ...server, processName: label(port.containerPort) }; + }); + const found = new Set(labeled.map((server) => server.port)); + return [ + ...labeled, + ...[...forwarded.values()] + .filter((port) => !found.has(port.hostPort)) + .map((port) => ({ + host: "127.0.0.1", + port: port.hostPort, + url: `http://127.0.0.1:${port.hostPort}`, + processName: label(port.containerPort), + pid: null, + terminal: null, + })), + ]; + }; + + const probeWebServers = Effect.fn("PortDiscovery.probeWebServers")(function* ( + listeners: ReadonlyArray, configuredUrls: ReadonlyArray, ) { + const servers = withSandboxPorts(listeners); const nowMillis = yield* Clock.currentTimeMillis; const cached = yield* Ref.get(webProbeCacheRef); const groups = makeWebProbeGroups(servers, configuredUrls); diff --git a/apps/server/src/processRunner.ts b/apps/server/src/processRunner.ts index 049125de3fbfd..c1e1c52c67f72 100644 --- a/apps/server/src/processRunner.ts +++ b/apps/server/src/processRunner.ts @@ -27,6 +27,8 @@ export interface ProcessRunInput { readonly stdin?: string | undefined; /** Receives every stdout chunk, including bytes beyond the buffered output limit. */ readonly onStdoutChunk?: ((chunk: Uint8Array) => void) | undefined; + /** Receives every stderr chunk, including bytes beyond the buffered output limit. */ + readonly onStderrChunk?: ((chunk: Uint8Array) => void) | undefined; readonly maxOutputBytes?: number | undefined; readonly outputMode?: "error" | "truncate" | undefined; readonly truncatedMarker?: string | undefined; @@ -335,6 +337,7 @@ const runProcessCore = Effect.fn("processRunner.runProcessCore")(function* ( const stdin = input.stdin; const onStdoutChunk = input.onStdoutChunk; + const onStderrChunk = input.onStderrChunk; const writeStdin = stdin === undefined ? Effect.void @@ -373,7 +376,9 @@ const runProcessCore = Effect.fn("processRunner.runProcessCore")(function* ( cwd: input.cwd, spawnCwd: input.spawnCwd, streamName: "stderr", - stream: child.stderr, + stream: onStderrChunk + ? child.stderr.pipe(Stream.tap((chunk) => Effect.sync(() => onStderrChunk(chunk)))) + : child.stderr, maxOutputBytes, outputMode, truncatedMarker, diff --git a/apps/server/src/project/ProjectSetupScriptRunner.ts b/apps/server/src/project/ProjectSetupScriptRunner.ts index f97c0f4df9c0a..7f55aba694afa 100644 --- a/apps/server/src/project/ProjectSetupScriptRunner.ts +++ b/apps/server/src/project/ProjectSetupScriptRunner.ts @@ -17,6 +17,7 @@ import * as Schema from "effect/Schema"; import * as ServerSettings from "../serverSettings.ts"; import * as TerminalManager from "../terminal/Manager.ts"; +import * as SandboxService from "../sandbox/SandboxService.ts"; import * as ProjectService from "./ProjectService.ts"; export interface ProjectSetupScriptRunnerResultNoScript { @@ -205,6 +206,7 @@ export const make = Effect.gen(function* () { yield* HostProcessPlatform, yield* HostProcessEnvironment, ); + const sandboxes = yield* Effect.serviceOption(SandboxService.SandboxService); /** * Watches the setup terminal for the completion sentinel. Terminal output is @@ -372,7 +374,10 @@ export const make = Effect.gen(function* () { observe && completionToken ? wrapCommandForCompletion( script.command, - completionShell, + // A sandbox terminal is bash in the container, whatever the host shell is. + Option.isSome(sandboxes) && (yield* sandboxes.value.isSandboxed(cwd)) + ? "posix" + : completionShell, completionSentinel(completionToken), ) : script.command; diff --git a/apps/server/src/sandbox/SandboxService.test.ts b/apps/server/src/sandbox/SandboxService.test.ts new file mode 100644 index 0000000000000..f4625acf5b760 --- /dev/null +++ b/apps/server/src/sandbox/SandboxService.test.ts @@ -0,0 +1,42 @@ +import { + DEFAULT_SERVER_SETTINGS, + ProviderDriverKind, + ProviderInstanceId, +} from "@t3tools/contracts"; +import { describe, expect, it } from "vite-plus/test"; + +import { sandboxProviderHomes } from "./SandboxService.ts"; + +describe("sandboxProviderHomes", () => { + it("collects Claude and Codex homes from providers, instances, and their env", () => { + const homes = sandboxProviderHomes({ + ...DEFAULT_SERVER_SETTINGS, + providers: { + ...DEFAULT_SERVER_SETTINGS.providers, + codex: { ...DEFAULT_SERVER_SETTINGS.providers.codex, homePath: "/homes/codex" }, + }, + providerInstances: { + [ProviderInstanceId.make("codex-work")]: { + driver: ProviderDriverKind.make("codex"), + config: { homePath: "/homes/codex-work", shadowHomePath: "/homes/codex-work-shadow" }, + }, + [ProviderInstanceId.make("claude-work")]: { + driver: ProviderDriverKind.make("claudeAgent"), + environment: [ + { name: "CLAUDE_CONFIG_DIR", value: "/homes/claude-work", sensitive: false }, + ], + }, + [ProviderInstanceId.make("other")]: { + driver: ProviderDriverKind.make("opencode"), + config: { homePath: "/homes/opencode" }, + }, + }, + }); + expect(homes).toEqual([ + "/homes/codex", + "/homes/codex-work", + "/homes/codex-work-shadow", + "/homes/claude-work", + ]); + }); +}); diff --git a/apps/server/src/sandbox/SandboxService.ts b/apps/server/src/sandbox/SandboxService.ts new file mode 100644 index 0000000000000..e996d5b89a435 --- /dev/null +++ b/apps/server/src/sandbox/SandboxService.ts @@ -0,0 +1,1040 @@ +// @effect-diagnostics nodeBuiltinImport:off - spawns the Docker CLI for long-lived relays and sync exec plans. +import * as NodeChildProcess from "node:child_process"; +import * as NodeCrypto from "node:crypto"; +import * as NodeOS from "node:os"; + +import type { + SandboxListStreamEvent, + SandboxStatus, + SandboxSummary, + ServerProvider, + ServerSettings, +} from "@t3tools/contracts"; +import { HostProcessPlatform } from "@t3tools/shared/hostProcess"; +import * as Context from "effect/Context"; +import * as Deferred from "effect/Deferred"; +import * as Effect from "effect/Effect"; +import * as FileSystem from "effect/FileSystem"; +import * as Layer from "effect/Layer"; +import * as Option from "effect/Option"; +import * as Path from "effect/Path"; +import * as PubSub from "effect/PubSub"; +import * as Queue from "effect/Queue"; +import * as Schema from "effect/Schema"; +import * as Semaphore from "effect/Semaphore"; +import * as Stream from "effect/Stream"; +import { HttpServer } from "effect/unstable/http"; +import * as NetAddress from "effect/unstable/net/NetAddress"; + +import { writeFileStringAtomically } from "../atomicWrite.ts"; +import * as ServerConfig from "../config.ts"; +import { expandHomePath } from "../pathExpansion.ts"; +import * as ProcessRunner from "../processRunner.ts"; +import { + dockerExecArgs, + dockerRunArgs, + isMountablePath, + preferredSandboxHostPort, + SANDBOX_DOCKERFILE, + SANDBOX_LABELS, + type SandboxCliVersions, + type SandboxMount, + sandboxContainerName, + sandboxEnvNames, + sandboxImageBuildArgs, + sandboxImageTag, + sandboxOwner, +} from "./sandboxDocker.ts"; +import { SANDBOX_KILL_SOURCE, SANDBOX_RELAY_SOURCE, SandboxTunnel } from "./SandboxTunnel.ts"; + +export class SandboxError extends Schema.TaggedError()("SandboxError", { + operation: Schema.Literals(["create", "start", "exec", "stop", "remove"]), + worktreePath: Schema.String, + detail: Schema.String, + cause: Schema.optional(Schema.Defect()), +}) { + override get message(): string { + return this.detail; + } +} + +/** Runs commands inside one sandbox. Plain functions, so sync spawn callbacks can use it. */ +export interface SandboxExecTarget { + readonly worktreePath: string; + readonly containerName: string; + /** + * Docker client command that runs `command` inside the sandbox. The caller + * spawns it and calls `release` when it exits or is killed: killing the + * Docker client alone leaves the command running in the container. + * Throws `SandboxError` when the env needs a folder the sandbox cannot see. + */ + readonly command: (input: { + readonly command: string; + readonly args: ReadonlyArray; + readonly cwd: string; + readonly env: NodeJS.ProcessEnv; + readonly tty: boolean; + }) => SandboxCommand; +} + +export interface SandboxCommand { + readonly command: string; + readonly args: ReadonlyArray; + /** Env for the Docker client. It holds the values `-e NAME` copies in. */ + readonly env: NodeJS.ProcessEnv; + /** Kills the command's processes in the container. Safe to call more than once. */ + readonly release: () => void; +} + +export interface SandboxForwardedPort { + readonly worktreePath: string; + readonly containerPort: number; + readonly hostPort: number; +} + +/** + * Docker sandboxes for worktrees. A sandbox is one long-running container + * that mounts its worktree (and the repository's git dir) at the same path, + * plus the user's Claude and Codex config folders. Agents, terminals, and + * setup scripts whose cwd is inside a sandboxed worktree run in it through + * `docker exec`, so parallel threads get separate ports, services, and + * machine state while T3 keeps reading the worktree on the host. + * + * A worktree is registered as sandboxed before anything slow happens, and + * stays registered when provisioning fails, so work there fails instead of + * running on the host. The list is persisted, and containers carry labels + * that rebuild it if the file is lost. + */ +export class SandboxService extends Context.Service< + SandboxService, + { + /** Whether this host can run sandboxes at all: Linux and macOS with Docker. */ + readonly supported: boolean; + /** + * Marks a new worktree as sandboxed and saves it. Fast; call it before + * anything can run in the worktree, then `start`. `providers` supplies + * the Claude and Codex versions to install; their home folders, plus + * `homes` (see `sandboxProviderHomes`), are mounted. + */ + readonly register: (input: { + readonly worktreePath: string; + /** The project checkout, mounted read-only for setup scripts that copy or link from it. */ + readonly projectRoot: string; + readonly providers: ReadonlyArray; + readonly homes: ReadonlyArray; + }) => Effect.Effect; + /** Builds the image if needed, then creates and starts a registered sandbox. */ + readonly start: (input: { + readonly worktreePath: string; + readonly onOutput?: (line: string) => Effect.Effect; + }) => Effect.Effect; + /** The started sandbox that owns `cwd`, or none when `cwd` is not sandboxed. */ + readonly execTarget: ( + cwd: string, + ) => Effect.Effect, SandboxError>; + /** Whether `cwd` is inside a sandboxed worktree. Does not start anything. */ + readonly isSandboxed: (cwd: string) => Effect.Effect; + /** Stops the container. The next command in the worktree starts it again. */ + readonly stop: (worktreePath: string) => Effect.Effect; + /** Deletes the container. Work in the worktree runs on the host afterwards. */ + readonly remove: (worktreePath: string) => Effect.Effect; + readonly list: Effect.Effect>; + /** Emits the full list first, then after every change. */ + readonly stream: Stream.Stream; + /** Every forwarded sandbox port, for preview discovery. */ + readonly forwardedPorts: () => ReadonlyArray; + /** + * Worktrees whose container stopped, was removed, or lost its relay. The + * processes T3 ran there are gone, so sessions holding them are dead. + */ + readonly stopped: Stream.Stream; + } +>()("t3/sandbox/SandboxService") {} + +const Mount = Schema.Struct({ path: Schema.String, readOnly: Schema.Boolean }); + +const RegistryEntry = Schema.Struct({ + worktreePath: Schema.String, + containerName: Schema.String, + image: Schema.String, + versions: Schema.Struct({ claude: Schema.String, codex: Schema.String }), + mounts: Schema.Array(Mount), +}); +const RegistryFile = Schema.Struct({ + version: Schema.Literal(1), + /** Saved while an unreadable list has not been rebuilt from Docker yet. */ + unverified: Schema.optional(Schema.Boolean), + sandboxes: Schema.Array(RegistryEntry), +}); +const RegistryJson = Schema.fromJsonString(RegistryFile); +const decodeRegistry = Schema.decodeUnknownEffect(RegistryJson); +const encodeRegistry = Schema.encodeEffect(RegistryJson); +const MarkerJson = Schema.fromJsonString(RegistryEntry); +const decodeMarker = Schema.decodeUnknownEffect(MarkerJson); +const encodeMarker = Schema.encodeEffect(MarkerJson); +/** Kept in the worktree's own git admin folder, which `git worktree remove` deletes. */ +const MARKER_FILE = "t3code-sandbox.json"; + +/** The parts of `docker inspect` output used to adopt a labeled container. */ +const InspectedContainers = Schema.fromJsonString( + Schema.Array( + Schema.Struct({ + Name: Schema.String, + Config: Schema.Struct({ + Image: Schema.String, + Labels: Schema.NullOr(Schema.Record(Schema.String, Schema.String)), + }), + State: Schema.Struct({ Running: Schema.Boolean }), + Mounts: Schema.NullOr( + Schema.Array( + Schema.Struct({ Source: Schema.String, Destination: Schema.String, RW: Schema.Boolean }), + ), + ), + }), + ), +); +const decodeInspected = Schema.decodeUnknownEffect(InspectedContainers); + +interface SandboxRecord { + readonly worktreePath: string; + readonly containerName: string; + readonly versions: SandboxCliVersions; + readonly mounts: ReadonlyArray; + /** Empty until the first image build finishes. */ + image: string; + status: SandboxStatus; + error: string | null; + tunnel: SandboxTunnel | null; + /** Commands left running by an earlier server process were killed. */ + reaped: boolean; + readonly lock: Semaphore.Semaphore; +} + +const DOCKER = "docker"; +const SUPPORTED_PLATFORMS: ReadonlySet = new Set(["linux", "darwin"]); +const SANDBOX_DRIVERS = { claude: "claudeAgent", codex: "codex" } as const; + +const containsPath = (root: string, candidate: string, separator: string) => + candidate === root || candidate.startsWith(root.endsWith(separator) ? root : root + separator); + +/** The version T3 runs for a driver: its default instance first, then any enabled one. */ +const providerVersion = (providers: ReadonlyArray, driver: string) => + ( + providers.find((provider) => provider.instanceId === driver && provider.version) ?? + providers.find((provider) => provider.driver === driver && provider.enabled && provider.version) + )?.version ?? "latest"; + +/** + * Claude and Codex home folders configured in settings: the built-in + * providers, provider instances, and their CLAUDE_CONFIG_DIR or CODEX_HOME. + * Sandboxes mount them so any of those providers can run inside. + */ +export const sandboxProviderHomes = (settings: ServerSettings): ReadonlyArray => { + const homes: Array = []; + const add = (value: unknown) => { + if (typeof value === "string" && value.trim().length > 0) { + homes.push(expandHomePath(value.trim())); + } + }; + add(settings.providers.codex.homePath); + add(settings.providers.codex.shadowHomePath); + add(settings.providers.claudeAgent.homePath); + for (const instance of Object.values(settings.providerInstances)) { + if (!Object.values(SANDBOX_DRIVERS).some((driver) => driver === instance.driver)) continue; + const config = instance.config; + if (typeof config === "object" && config !== null) { + if ("homePath" in config) add(config.homePath); + if ("shadowHomePath" in config) add(config.shadowHomePath); + } + for (const variable of instance.environment ?? []) { + if (variable.name === "CODEX_HOME" || variable.name === "CLAUDE_CONFIG_DIR") { + add(variable.value); + } + } + } + return homes; +}; + +const make = Effect.gen(function* () { + const platform = yield* HostProcessPlatform; + const fileSystem = yield* FileSystem.FileSystem; + const path = yield* Path.Path; + const processRunner = yield* ProcessRunner.ProcessRunner; + const serverConfig = yield* ServerConfig.ServerConfig; + const httpServer = yield* HttpServer.HttpServer; + const supported = SUPPORTED_PLATFORMS.has(platform); + const hostEnv = { ...process.env }; + const home = NodeOS.homedir(); + const registryPath = path.join(serverConfig.stateDir, "sandboxes.json"); + const owner = sandboxOwner(serverConfig.stateDir); + const records = new Map(); + const changes = yield* PubSub.unbounded(); + const stoppedWorktrees = yield* PubSub.unbounded(); + const registryLock = yield* Semaphore.make(1); + // Lookups wait until labeled containers missing from the saved list are adopted. + const ready = yield* Deferred.make(); + // Set while an unreadable list has not been rebuilt from Docker yet. Then + // no T3 worktree can be shown to be unsandboxed, so lookups there fail. + let unverified = false; + + // Agents reach T3's MCP endpoint on the server's own loopback address. The + // relay listens on that address and port inside the container and connects + // back. A wildcard bind is announced as 127.0.0.1; other addresses are + // reachable from the container without help. + const mcpReverse = (() => { + if (!NetAddress.isInetAddress(httpServer.address)) return null; + const host = NetAddress.isUnspecified(httpServer.address.address) + ? "127.0.0.1" + : NetAddress.formatIp(httpServer.address.address); + if (!host.startsWith("127.") && host !== "::1") return null; + return { host, port: httpServer.address.port }; + })(); + + const summarize = (record: SandboxRecord): SandboxSummary => ({ + worktreePath: record.worktreePath, + containerName: record.containerName, + image: record.image || "building", + status: record.status, + ports: record.tunnel?.ports ?? [], + error: record.error, + }); + const publish = () => PubSub.publishUnsafe(changes, undefined); + const setStatus = (record: SandboxRecord, status: SandboxStatus, error: string | null = null) => { + record.status = status; + record.error = error; + publish(); + }; + + const fail = + (operation: SandboxError["operation"], worktreePath: string, detail: string) => + (cause?: unknown) => + new SandboxError({ + operation, + worktreePath, + detail, + ...(cause === undefined ? {} : { cause }), + }); + + /** Runs a short Docker CLI command and returns trimmed stdout, failing on a non-zero exit. */ + const docker = ( + operation: SandboxError["operation"], + worktreePath: string, + args: ReadonlyArray, + options: { readonly stdin?: string; readonly onLine?: (line: string) => void } = {}, + ) => { + let partial = ""; + const onChunk = + options.onLine === undefined + ? undefined + : (chunk: Uint8Array) => { + const lines = (partial + Buffer.from(chunk).toString("utf8")).split("\n"); + partial = lines.pop() ?? ""; + for (const line of lines) if (line.trim().length > 0) options.onLine!(line); + }; + return processRunner + .run({ + command: DOCKER, + args, + env: hostEnv, + maxOutputBytes: 4 * 1024 * 1024, + outputMode: "truncate", + ...(options.stdin === undefined ? {} : { stdin: options.stdin }), + ...(onChunk === undefined ? {} : { onStdoutChunk: onChunk, onStderrChunk: onChunk }), + }) + .pipe( + Effect.mapError( + fail( + operation, + worktreePath, + "Docker is not installed or not on PATH. Install Docker to use sandboxes.", + ), + ), + Effect.flatMap((result) => + result.code === 0 + ? Effect.succeed(result.stdout.trim()) + : Effect.fail( + fail( + operation, + worktreePath, + `docker ${args[0]} failed: ${(result.stderr.trim() || result.stdout.trim()).slice(-400)}`, + )(), + ), + ), + ); + }; + + /** Saves the list. Writes are serialized so an older snapshot never lands last. */ + const persist = registryLock.withPermits(1)( + Effect.gen(function* () { + const contents = yield* encodeRegistry({ + version: 1, + ...(unverified ? { unverified: true } : {}), + sandboxes: [...records.values()].map((record) => ({ + worktreePath: record.worktreePath, + containerName: record.containerName, + image: record.image, + versions: record.versions, + mounts: record.mounts, + })), + }); + yield* writeFileStringAtomically({ filePath: registryPath, contents }); + }).pipe( + Effect.provideService(FileSystem.FileSystem, fileSystem), + Effect.provideService(Path.Path, path), + Effect.mapError(fail("create", registryPath, "Could not save the sandbox list.")), + ), + ); + const persistOrLog = persist.pipe( + Effect.catchCause((cause) => Effect.logError("Failed to save the sandbox list", { cause })), + ); + + const ensureImage = Effect.fn("SandboxService.ensureImage")(function* ( + record: SandboxRecord, + onOutput: (line: string) => void, + ) { + const input = { + uid: process.getuid?.() ?? 1000, + gid: process.getgid?.() ?? 1000, + home, + versions: record.versions, + }; + const tag = sandboxImageTag(input); + const exists = yield* docker("start", record.worktreePath, ["image", "inspect", tag]).pipe( + Effect.as(true), + Effect.orElseSucceed(() => false), + ); + if (!exists) { + onOutput(`Building sandbox image ${tag}`); + yield* docker("start", record.worktreePath, sandboxImageBuildArgs(input, tag), { + stdin: SANDBOX_DOCKERFILE, + onLine: onOutput, + }); + } + return tag; + }); + + /** Folders mounted at their own path. Only folders that exist are mounted. */ + const mountsFor = Effect.fn("SandboxService.mountsFor")(function* ( + worktreePath: string, + gitCommonDir: string, + projectRoot: string, + providers: ReadonlyArray, + homes: ReadonlyArray, + ) { + const providerHomes = providers + .filter((provider) => Object.values(SANDBOX_DRIVERS).some((d) => d === provider.driver)) + .flatMap((provider) => + provider.runtimePaths === undefined + ? [] + : [provider.runtimePaths.homePath, provider.runtimePaths.shadowHomePath ?? ""], + ) + .filter((home) => home.length > 0); + const candidates: ReadonlyArray = [ + { path: worktreePath, readOnly: false }, + { path: gitCommonDir, readOnly: false }, + { path: hostEnv.CLAUDE_CONFIG_DIR ?? path.join(home, ".claude"), readOnly: false }, + { path: hostEnv.CODEX_HOME ?? path.join(home, ".codex"), readOnly: false }, + ...[...providerHomes, ...homes].map((providerHome) => ({ + path: providerHome, + readOnly: false, + })), + { path: path.join(home, ".gitconfig"), readOnly: true }, + // Claude reads pasted images from T3's attachment folder. + { path: serverConfig.attachmentsDir, readOnly: true }, + // Setup scripts copy or link files such as .env from the checkout. A + // checkout that holds the home folder would hide the sandbox's own home. + ...(containsPath(projectRoot, home, path.sep) ? [] : [{ path: projectRoot, readOnly: true }]), + ]; + const mounts: Array = []; + for (const mount of candidates) { + if (!isMountablePath(mount.path)) continue; + // A writable mount already covers anything inside it; a read-only one + // covers only read-only paths, so the worktree and git dir stay writable. + const covered = mounts.some( + (existing) => + containsPath(existing.path, mount.path, path.sep) && + (!existing.readOnly || mount.readOnly), + ); + if (covered) continue; + if (yield* fileSystem.exists(mount.path).pipe(Effect.orElseSucceed(() => false))) { + mounts.push(mount); + } + } + return mounts; + }); + + const runContainer = Effect.fn("SandboxService.runContainer")(function* (record: SandboxRecord) { + yield* docker("start", record.worktreePath, ["rm", "--force", record.containerName]).pipe( + Effect.ignore, + ); + yield* docker( + "start", + record.worktreePath, + dockerRunArgs({ + owner, + containerName: record.containerName, + image: record.image, + worktreePath: record.worktreePath, + versions: record.versions, + mounts: record.mounts, + ipv6Loopback: mcpReverse?.host === "::1", + }), + ); + // Claude rewrites ~/.claude.json by renaming over it, which fails on a + // bind-mounted file. The sandbox gets its own copy; credentials stay + // shared through the mounted ~/.claude folder. + const claudeJson = path.join(home, ".claude.json"); + if (yield* fileSystem.exists(claudeJson).pipe(Effect.orElseSucceed(() => false))) { + yield* docker("start", record.worktreePath, [ + "cp", + "--archive", + claudeJson, + `${record.containerName}:${claudeJson}`, + ]).pipe(Effect.ignore); + } + }); + + const spawnDocker = (args: ReadonlyArray) => + NodeChildProcess.spawn(DOCKER, [...args], { env: hostEnv, stdio: ["pipe", "pipe", "pipe"] }); + + const startTunnel = (record: SandboxRecord) => { + const tunnel: SandboxTunnel = new SandboxTunnel({ + spawnRelay: () => + spawnDocker(["exec", "-i", record.containerName, "node", "-e", SANDBOX_RELAY_SOURCE]), + reversePorts: + mcpReverse === null + ? [] + : [{ host: mcpReverse.host, containerPort: mcpReverse.port, hostPort: mcpReverse.port }], + preferredHostPort: (containerPort) => + preferredSandboxHostPort(record.containerName, containerPort), + onPortsChanged: publish, + onExit: (detail) => { + if (record.tunnel !== tunnel) return; + record.tunnel = null; + // The relay only exits by itself when the container or Docker went away. + if (detail !== "closed") { + setStatus(record, "stopped"); + PubSub.publishUnsafe(stoppedWorktrees, record.worktreePath); + } else { + publish(); + } + }, + }); + record.tunnel = tunnel; + }; + + const release = (containerName: string, target: string) => { + const child = NodeChildProcess.spawn( + DOCKER, + ["exec", containerName, "node", "-e", SANDBOX_KILL_SOURCE, target], + { env: hostEnv, stdio: "ignore" }, + ); + child.on("error", () => {}); + child.unref(); + }; + + /** + * Builds the image and creates the container when either is missing, starts + * a stopped container, and starts the relay. Callers hold the record lock. + */ + const startUnlocked = (record: SandboxRecord, onOutput: (line: string) => void = () => {}) => + Effect.gen(function* () { + // A lookup can hold a record that Remove deleted while it waited for the lock. + if (records.get(record.worktreePath) !== record) return false; + if (record.status === "running" && record.tunnel?.alive === true) return true; + setStatus(record, "starting"); + const state = yield* docker("start", record.worktreePath, [ + "inspect", + "--format", + "{{.State.Running}}", + record.containerName, + ]).pipe(Effect.orElseSucceed(() => "missing")); + if (state === "missing") { + yield* docker("start", record.worktreePath, [ + "version", + "--format", + "{{.Server.Version}}", + ]).pipe( + Effect.mapError((error) => + fail( + "start", + record.worktreePath, + `Docker is not running. Start Docker and try again. (${error.detail})`, + )(error), + ), + ); + record.image = yield* ensureImage(record, onOutput); + yield* persistOrLog; + onOutput(`Starting container ${record.containerName}`); + yield* runContainer(record); + } else if (state !== "true") { + yield* docker("start", record.worktreePath, ["start", record.containerName]); + } + if (!record.reaped) { + // Commands an earlier server process started outlive it in the + // container; stop them like the host stops orphaned terminals. + yield* docker("start", record.worktreePath, [ + "exec", + record.containerName, + "node", + "-e", + SANDBOX_KILL_SOURCE, + "--all", + ]).pipe(Effect.ignore); + record.reaped = true; + } + if (record.tunnel?.alive !== true) startTunnel(record); + setStatus(record, "running"); + return true; + }).pipe( + Effect.tapError((error) => Effect.sync(() => setStatus(record, "error", error.detail))), + ); + + const ensureRunning = (record: SandboxRecord) => + record.lock.withPermits(1)(startUnlocked(record)); + + const recordFor = (cwd: string) => { + for (const record of records.values()) { + if (containsPath(record.worktreePath, cwd, path.sep)) return record; + } + return undefined; + }; + + /** True when `cwd` might be sandboxed but the list is unverified. Retries the rebuild once. */ + const unknownSandbox = (cwd: string) => + Effect.gen(function* () { + if (!unverified || !containsPath(serverConfig.worktreesDir, cwd, path.sep)) return false; + yield* reconcileOnce; + return unverified && recordFor(cwd) === undefined; + }); + + const makeExecTarget = (record: SandboxRecord): SandboxExecTarget => ({ + worktreePath: record.worktreePath, + containerName: record.containerName, + command: (input) => { + for (const name of ["CODEX_HOME", "CLAUDE_CONFIG_DIR"]) { + const value = input.env[name]; + if (value === undefined || value === hostEnv[name]) continue; + if (!record.mounts.some((mount) => containsPath(mount.path, value, path.sep))) { + throw fail( + "exec", + record.worktreePath, + `This provider uses ${name}=${value}, which this sandbox does not mount. Start a new sandbox after changing a provider's home folder.`, + )(); + } + } + const execId = NodeCrypto.randomUUID(); + let released = false; + return { + command: DOCKER, + args: dockerExecArgs({ + containerName: record.containerName, + execId, + cwd: input.cwd, + envNames: sandboxEnvNames(input.env, hostEnv), + tty: input.tty, + command: input.command, + args: input.args, + }), + env: { ...hostEnv, ...input.env }, + release: () => { + if (released) return; + released = true; + release(record.containerName, execId); + }, + }; + }, + }); + + /** + * The marker file for a worktree: `/t3code-sandbox.json`, + * found through the `.git` file a linked worktree has at its root. + */ + const markerPath = (worktreePath: string) => + fileSystem.readFileString(path.join(worktreePath, ".git")).pipe( + Effect.map((text) => /^gitdir:\s*(.+)$/m.exec(text)?.[1]?.trim()), + Effect.map((gitDir) => + gitDir === undefined + ? undefined + : path.join(path.resolve(worktreePath, gitDir), MARKER_FILE), + ), + Effect.orElseSucceed(() => undefined), + ); + + /** + * Rebuilds a sandbox from the marker in its worktree when the saved list + * lost it, so a lost list never lets sandboxed work start on the host. + */ + const recordFromMarker = (cwd: string) => + Effect.gen(function* () { + // Every ancestor is checked, so a submodule or nested repository inside + // a sandboxed worktree still finds the worktree's marker. + let dir = cwd; + while (true) { + const marker = yield* markerPath(dir); + const entry = + marker === undefined + ? undefined + : yield* fileSystem.readFileString(marker).pipe( + Effect.flatMap(decodeMarker), + Effect.orElseSucceed(() => undefined), + ); + if (entry !== undefined && entry.worktreePath === dir) { + const existing = records.get(entry.worktreePath); + if (existing !== undefined) return existing; + addLoadedRecord(entry); + publish(); + yield* persistOrLog; + return records.get(entry.worktreePath); + } + const parent = path.dirname(dir); + if (parent === dir) return undefined; + dir = parent; + } + }); + + /** The sandbox owning `cwd`, from memory or its worktree's marker. */ + const lookup = (cwd: string) => + Effect.suspend(() => { + const record = recordFor(cwd); + return record === undefined ? recordFromMarker(cwd) : Effect.succeed(record); + }); + + const register: SandboxService["Service"]["register"] = Effect.fn("SandboxService.register")( + function* (input) { + yield* Deferred.await(ready); + if (!supported) { + return yield* fail( + "create", + input.worktreePath, + "Sandboxes run on Linux and macOS hosts.", + )(); + } + if (!isMountablePath(input.worktreePath)) { + return yield* fail( + "create", + input.worktreePath, + "Sandboxes cannot mount a path that contains a comma.", + )(); + } + const gitCommonDir = yield* processRunner + .run({ + command: "git", + args: ["rev-parse", "--path-format=absolute", "--git-common-dir"], + cwd: input.worktreePath, + env: hostEnv, + }) + .pipe( + Effect.flatMap((result) => + result.code === 0 && result.stdout.trim().length > 0 + ? Effect.succeed(result.stdout.trim()) + : Effect.fail(result.stderr), + ), + Effect.mapError( + fail("create", input.worktreePath, "Could not find the worktree's git folder."), + ), + ); + records.get(input.worktreePath)?.tunnel?.close(); + const record: SandboxRecord = { + worktreePath: input.worktreePath, + containerName: sandboxContainerName(input.worktreePath), + versions: { + claude: providerVersion(input.providers, SANDBOX_DRIVERS.claude), + codex: providerVersion(input.providers, SANDBOX_DRIVERS.codex), + }, + mounts: yield* mountsFor( + input.worktreePath, + gitCommonDir, + input.projectRoot, + input.providers, + input.homes, + ), + image: "", + status: "starting", + error: null, + tunnel: null, + reaped: true, + lock: Semaphore.makeUnsafe(1), + }; + // Saved before the slow start, so terminals opened during the build wait + // for the sandbox instead of starting on the host. A failed start leaves + // the record in place for the next attempt. + records.set(record.worktreePath, record); + publish(); + const marker = yield* markerPath(record.worktreePath); + yield* persist.pipe( + Effect.andThen( + marker === undefined + ? fail("create", record.worktreePath, "The worktree has no git admin folder.")() + : encodeMarker(record).pipe( + Effect.flatMap((contents) => + writeFileStringAtomically({ filePath: marker, contents }), + ), + Effect.provideService(FileSystem.FileSystem, fileSystem), + Effect.provideService(Path.Path, path), + Effect.mapError( + fail("create", record.worktreePath, "Could not mark the worktree as sandboxed."), + ), + ), + ), + Effect.tapError(() => + Effect.sync(() => { + records.delete(record.worktreePath); + publish(); + }).pipe(Effect.andThen(persistOrLog)), + ), + ); + }, + ); + + const start: SandboxService["Service"]["start"] = Effect.fn("SandboxService.start")( + function* (input) { + const record = records.get(input.worktreePath); + if (record === undefined) { + return yield* fail("start", input.worktreePath, "This worktree has no sandbox.")(); + } + const onOutput = (line: string) => { + if (input.onOutput) Effect.runFork(input.onOutput(line)); + }; + yield* record.lock.withPermits(1)(startUnlocked(record, onOutput)); + return summarize(record); + }, + ); + + const execTarget: SandboxService["Service"]["execTarget"] = (cwd) => + Effect.gen(function* () { + yield* Deferred.await(ready); + if (yield* unknownSandbox(cwd)) { + return yield* fail( + "start", + cwd, + "T3 could not read its sandbox list and Docker is not reachable, so it cannot tell whether this worktree runs in a sandbox. Start Docker and try again.", + )(); + } + const record = yield* lookup(cwd); + if (record === undefined) return Option.none(); + return (yield* ensureRunning(record)) ? Option.some(makeExecTarget(record)) : Option.none(); + }); + + const stop: SandboxService["Service"]["stop"] = (worktreePath) => + Effect.gen(function* () { + const record = records.get(worktreePath); + if (record === undefined) return; + yield* record.lock.withPermits(1)( + Effect.gen(function* () { + record.tunnel?.close(); + record.tunnel = null; + yield* docker("stop", worktreePath, ["stop", "--time", "3", record.containerName]); + // The container's processes are gone, so nothing is left to reap. + record.reaped = true; + setStatus(record, "stopped"); + PubSub.publishUnsafe(stoppedWorktrees, worktreePath); + }), + ); + }); + + const remove: SandboxService["Service"]["remove"] = (worktreePath) => + Effect.gen(function* () { + const record = records.get(worktreePath); + if (record === undefined) return; + yield* record.lock.withPermits(1)( + Effect.gen(function* () { + record.tunnel?.close(); + record.tunnel = null; + // A failed first start can leave no container to delete. + yield* docker("remove", worktreePath, ["rm", "--force", record.containerName]).pipe( + Effect.catchIf( + (error) => /no such container/i.test(error.detail), + () => Effect.succeed(""), + ), + ); + records.delete(worktreePath); + publish(); + PubSub.publishUnsafe(stoppedWorktrees, worktreePath); + yield* persistOrLog; + const marker = yield* markerPath(worktreePath); + if (marker !== undefined) yield* fileSystem.remove(marker).pipe(Effect.ignore); + }), + ); + }); + + const list = Effect.sync(() => [...records.values()].map(summarize)); + + /** One-slot sliding mailbox: a slow client only ever holds the newest list. */ + const stream: SandboxService["Service"]["stream"] = Stream.callback( + (mailbox) => + Effect.gen(function* () { + const subscription = yield* PubSub.subscribe(changes); + Queue.offerUnsafe(mailbox, { sandboxes: yield* list }); + yield* Stream.fromSubscription(subscription).pipe( + Stream.runForEach(() => + Effect.map(list, (sandboxes) => Queue.offerUnsafe(mailbox, { sandboxes })), + ), + Effect.forkScoped, + ); + }), + { bufferSize: 1, strategy: "sliding" }, + ); + + const forwardedPorts: SandboxService["Service"]["forwardedPorts"] = () => + [...records.values()].flatMap((record) => + (record.tunnel?.ports ?? []).map((port) => ({ worktreePath: record.worktreePath, ...port })), + ); + + const worktreeExists = (worktreePath: string) => + fileSystem.exists(worktreePath).pipe(Effect.orElseSucceed(() => false)); + + const addLoadedRecord = (entry: { + readonly worktreePath: string; + readonly containerName: string; + readonly image: string; + readonly versions: SandboxCliVersions; + readonly mounts: ReadonlyArray; + }) => + records.set(entry.worktreePath, { + ...entry, + status: "stopped", + error: null, + tunnel: null, + reaped: false, + lock: Semaphore.makeUnsafe(1), + }); + + // Load the saved list. A missing file means no sandboxes yet; an unreadable + // one is logged, and the labeled containers below rebuild what they can. + const saved = yield* fileSystem.readFileString(registryPath).pipe( + Effect.flatMap(decodeRegistry), + Effect.map((registry) => { + if (registry.unverified === true) unverified = true; + return registry.sandboxes; + }), + Effect.catchCause((cause) => + fileSystem.exists(registryPath).pipe( + Effect.orElseSucceed(() => true), + Effect.flatMap((exists) => + exists + ? Effect.logError("Could not read the sandbox list", { registryPath, cause }).pipe( + Effect.tap(() => + Effect.sync(() => { + unverified = true; + }), + ), + ) + : Effect.void, + ), + Effect.as([]), + ), + ), + ); + for (const entry of saved) addLoadedRecord(entry); + + /** + * Adopts labeled containers the saved list does not know, drops sandboxes + * whose worktree is gone, and reconnects containers that are still running + * so their ports show up after a restart. + */ + const reconcile = Effect.gen(function* () { + const names = yield* docker("start", registryPath, [ + "ps", + "--all", + "--filter", + `label=${SANDBOX_LABELS.owner}=${owner}`, + "--format", + "{{.Names}}", + ]); + const containers = + names.length === 0 + ? [] + : yield* docker("start", registryPath, ["inspect", ...names.split("\n")]).pipe( + Effect.flatMap(decodeInspected), + ); + let changed = false; + for (const container of containers) { + const labels = container.Config.Labels ?? {}; + const worktreePath = labels[SANDBOX_LABELS.worktree]; + if (worktreePath === undefined || records.has(worktreePath)) continue; + addLoadedRecord({ + worktreePath, + containerName: container.Name.replace(/^\//, ""), + image: container.Config.Image, + versions: { + claude: labels[SANDBOX_LABELS.claude] ?? "latest", + codex: labels[SANDBOX_LABELS.codex] ?? "latest", + }, + mounts: (container.Mounts ?? []) + .filter((mount) => mount.Source === mount.Destination) + .map((mount) => ({ path: mount.Source, readOnly: !mount.RW })), + }); + changed = true; + } + for (const record of [...records.values()]) { + if (yield* worktreeExists(record.worktreePath)) continue; + records.delete(record.worktreePath); + changed = true; + yield* docker("remove", record.worktreePath, ["rm", "--force", record.containerName]).pipe( + Effect.ignore, + ); + } + if (unverified) changed = true; + unverified = false; + if (changed) { + publish(); + yield* persistOrLog; + } + const running = new Set( + containers.filter((container) => container.State.Running).map((c) => c.Name.slice(1)), + ); + return [...records.values()].filter((record) => running.has(record.containerName)); + }); + + const reconcileOnce = reconcile.pipe( + Effect.timeout("15 seconds"), + Effect.catchCause((cause) => + Effect.logWarning("Could not check sandbox containers", { cause }).pipe(Effect.as([])), + ), + ); + + yield* reconcile.pipe( + Effect.timeout("15 seconds"), + Effect.catchCause((cause) => + Effect.logWarning("Could not check sandbox containers", { cause }).pipe(Effect.as([])), + ), + Effect.tap(() => Deferred.succeed(ready, undefined)), + Effect.flatMap((running) => + Effect.forEach(running, (record) => ensureRunning(record).pipe(Effect.ignore), { + discard: true, + }), + ), + Effect.ensuring(Deferred.succeed(ready, undefined)), + Effect.forkScoped, + ); + yield* Effect.addFinalizer(() => + Effect.sync(() => { + for (const record of records.values()) record.tunnel?.close(); + }), + ); + + return SandboxService.of({ + supported, + register, + start, + execTarget, + isSandboxed: (cwd) => + Deferred.await(ready).pipe( + Effect.andThen(unknownSandbox(cwd)), + Effect.flatMap((unknown) => + unknown + ? Effect.succeed(true) + : lookup(cwd).pipe(Effect.map((record) => record !== undefined)), + ), + ), + stop, + remove, + list, + stream, + forwardedPorts, + stopped: Stream.fromPubSub(stoppedWorktrees), + }); +}); + +export const layer = Layer.effect(SandboxService, make); diff --git a/apps/server/src/sandbox/SandboxTunnel.test.ts b/apps/server/src/sandbox/SandboxTunnel.test.ts new file mode 100644 index 0000000000000..6c88d1f090f65 --- /dev/null +++ b/apps/server/src/sandbox/SandboxTunnel.test.ts @@ -0,0 +1,125 @@ +// @effect-diagnostics nodeBuiltinImport:off - drives the real relay script over sockets and pipes. +import * as NodeChildProcess from "node:child_process"; +import * as NodeFS from "node:fs"; +import * as NodeNet from "node:net"; +import * as NodeOS from "node:os"; +import * as NodePath from "node:path"; + +import type { SandboxPort } from "@t3tools/contracts"; +import { afterEach, describe, expect, it } from "vite-plus/test"; + +import { SANDBOX_RELAY_SOURCE, SandboxTunnel } from "./SandboxTunnel.ts"; + +// The relay normally runs in the container's network namespace. Here it runs +// on the host against a fake /proc, so forwarded and reverse ports must differ. +const cleanups: Array<() => void> = []; +afterEach(() => { + for (const cleanup of cleanups.splice(0).toReversed()) cleanup(); +}); + +const listenEcho = (prefix: string) => + new Promise((resolve) => { + const server = NodeNet.createServer((socket) => + socket.on("data", (chunk) => socket.write(`${prefix}${chunk.toString("utf8")}`)), + ); + cleanups.push(() => server.close()); + server.listen(0, "127.0.0.1", () => resolve(server)); + }); + +const portOf = (server: NodeNet.Server) => { + const address = server.address(); + if (address === null || typeof address !== "object") throw new Error("no address"); + return address.port; +}; + +const freePort = async () => { + const server = NodeNet.createServer(); + await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve)); + const port = portOf(server); + await new Promise((resolve) => server.close(() => resolve())); + return port; +}; + +const fakeProcRoot = (listeningPorts: ReadonlyArray) => { + const root = NodeFS.mkdtempSync(NodePath.join(NodeOS.tmpdir(), "t3-relay-proc-")); + cleanups.push(() => NodeFS.rmSync(root, { recursive: true, force: true })); + NodeFS.mkdirSync(NodePath.join(root, "net")); + const rows = listeningPorts.map( + (port, index) => + ` ${index}: 0100007F:${port.toString(16).toUpperCase().padStart(4, "0")} 00000000:0000 0A 00000000:00000000 00:00000000 00000000 1000 0 1 1 0 100 0 0 10 0`, + ); + NodeFS.writeFileSync( + NodePath.join(root, "net", "tcp"), + [" sl local_address rem_address st", ...rows].join("\n"), + ); + return root; +}; + +const roundTrip = (port: number, message: string) => + new Promise((resolve, reject) => { + const socket = NodeNet.connect({ host: "127.0.0.1", port }, () => socket.write(message)); + socket.once("data", (chunk) => { + socket.destroy(); + resolve(chunk.toString("utf8")); + }); + socket.once("error", reject); + }); + +describe("SandboxTunnel", () => { + it("forwards listening container ports to host loopback and reverse ports back", async () => { + const app = await listenEcho("app:"); + const mcp = await listenEcho("mcp:"); + const reverseContainerPort = await freePort(); + const procRoot = fakeProcRoot([portOf(app)]); + + let resolvePorts: (ports: ReadonlyArray) => void = () => {}; + const portsReady = new Promise>((resolve) => { + resolvePorts = resolve; + }); + const exits: Array = []; + const tunnel = new SandboxTunnel({ + spawnRelay: () => + NodeChildProcess.spawn(process.execPath, ["-e", SANDBOX_RELAY_SOURCE, procRoot], { + stdio: ["pipe", "pipe", "pipe"], + }), + reversePorts: [ + { host: "127.0.0.1", containerPort: reverseContainerPort, hostPort: portOf(mcp) }, + ], + preferredHostPort: () => 0, + onPortsChanged: (ports) => { + if (ports.length > 0) resolvePorts(ports); + }, + onExit: (detail) => exits.push(detail), + }); + cleanups.push(() => tunnel.close()); + + const [forwarded] = await portsReady; + expect(forwarded?.containerPort).toBe(portOf(app)); + expect(forwarded?.hostPort).not.toBe(portOf(app)); + expect(await roundTrip(forwarded!.hostPort, "hello")).toBe("app:hello"); + expect(await roundTrip(reverseContainerPort, "tools")).toBe("mcp:tools"); + + tunnel.close(); + expect(tunnel.alive).toBe(false); + expect(exits).toEqual(["closed"]); + }); + + it("reports the relay exiting on its own", async () => { + let resolveExit: (detail: string) => void = () => {}; + const exited = new Promise((resolve) => { + resolveExit = resolve; + }); + const tunnel = new SandboxTunnel({ + spawnRelay: () => + NodeChildProcess.spawn(process.execPath, ["-e", "process.exit(3)"], { + stdio: ["pipe", "pipe", "pipe"], + }), + reversePorts: [], + preferredHostPort: () => 0, + onPortsChanged: () => {}, + onExit: resolveExit, + }); + expect(await exited).toContain("relay exited (3)"); + expect(tunnel.alive).toBe(false); + }); +}); diff --git a/apps/server/src/sandbox/SandboxTunnel.ts b/apps/server/src/sandbox/SandboxTunnel.ts new file mode 100644 index 0000000000000..f5f676725e526 --- /dev/null +++ b/apps/server/src/sandbox/SandboxTunnel.ts @@ -0,0 +1,517 @@ +// @effect-diagnostics nodeBuiltinImport:off - the tunnel is plain sockets and pipes. +import type * as NodeChildProcess from "node:child_process"; +import * as NodeNet from "node:net"; + +import type { SandboxPort } from "@t3tools/contracts"; + +/** + * Network bridge between the server host and one sandbox container. + * + * A relay script runs inside the container under `docker exec -i` and talks + * to the host over its stdin and stdout with small frames. One relay carries + * every connection in both directions: + * + * - Ports apps open inside the container get a listener on the host's + * loopback, so previews reach them. The relay reports listening ports by + * reading `/proc/net/tcp`, so any port works without publishing it up front. + * - Reverse ports listen on the container's loopback and connect back to the + * same port on the host's loopback. Agents use this to reach T3's MCP + * endpoint at the same `127.0.0.1` URL they would use outside a sandbox. + * + * Only the Docker CLI is involved, so the same code works with Docker Engine + * on Linux and Docker Desktop on macOS, where container IPs are not routable. + * + * Frame: type (u8), connection id (u32), payload length (u32), payload. + * Host-opened connections use even ids and relay-opened ones odd ids. + */ +const FRAME = { + connect: 1, + accepted: 2, + data: 3, + end: 4, + close: 5, + ports: 6, + listen: 7, + error: 8, +} as const; + +const HEADER_BYTES = 9; + +/** + * Runs inside the container with `node -e [proc-root]`. Exits when + * the host closes its stdin. Tests pass a fake proc root. + */ +export const SANDBOX_RELAY_SOURCE = String.raw`"use strict"; +const net = require("net"); +const fs = require("fs"); +const T = { CONNECT: 1, ACCEPTED: 2, DATA: 3, END: 4, CLOSE: 5, PORTS: 6, LISTEN: 7, ERROR: 8 }; +const sockets = new Map(); +const pending = new Map(); +const relayPorts = new Set(); +let nextId = 1; +let paused = false; +let lastPorts = ""; +const procRoot = process.argv[1] || "/proc"; +function send(type, id, payload) { + const body = payload || Buffer.alloc(0); + const header = Buffer.allocUnsafe(9); + header.writeUInt8(type, 0); + header.writeUInt32BE(id, 1); + header.writeUInt32BE(body.length, 5); + if (!process.stdout.write(Buffer.concat([header, body])) && !paused) { + paused = true; + for (const socket of sockets.values()) socket.pause(); + process.stdout.once("drain", () => { + paused = false; + for (const socket of sockets.values()) socket.resume(); + }); + } +} +function port16(port) { + const buffer = Buffer.allocUnsafe(2); + buffer.writeUInt16BE(port, 0); + return buffer; +} +function attach(id, socket) { + sockets.set(id, socket); + if (paused) socket.pause(); + socket.on("data", (chunk) => send(T.DATA, id, chunk)); + socket.on("end", () => send(T.END, id)); + socket.on("error", () => {}); + socket.on("close", () => { + if (sockets.delete(id)) send(T.CLOSE, id); + }); +} +function writeTo(socket, chunk) { + if (socket.write(chunk)) return; + process.stdin.pause(); + const resume = () => { + socket.off("drain", resume); + socket.off("close", resume); + process.stdin.resume(); + }; + socket.on("drain", resume); + socket.on("close", resume); +} +function connectLocal(id, port) { + const entry = { chunks: [], ended: false, closed: false }; + pending.set(id, entry); + const attempt = (hosts) => { + const socket = net.connect({ host: hosts[0], port }); + const onError = () => { + if (entry.closed) return; + if (hosts.length > 1) return attempt(hosts.slice(1)); + pending.delete(id); + send(T.CLOSE, id); + }; + socket.once("error", onError); + socket.once("connect", () => { + socket.off("error", onError); + pending.delete(id); + if (entry.closed) return socket.destroy(); + for (const chunk of entry.chunks) socket.write(chunk); + if (entry.ended) socket.end(); + attach(id, socket); + }); + }; + attempt(["127.0.0.1", "::1"]); +} +function listen(port, host) { + relayPorts.add(port); + const server = net.createServer((socket) => { + const id = nextId; + nextId += 2; + send(T.ACCEPTED, id, port16(port)); + attach(id, socket); + }); + server.on("error", (error) => + send(T.ERROR, 0, Buffer.from("listen " + port + ": " + error.message)), + ); + server.listen(port, host); +} +function scanPorts() { + const ports = new Set(); + for (const file of [procRoot + "/net/tcp", procRoot + "/net/tcp6"]) { + let text = ""; + try { + text = fs.readFileSync(file, "utf8"); + } catch { + continue; + } + for (const line of text.split("\n").slice(1)) { + const columns = line.trim().split(/\s+/); + if (columns.length < 4 || columns[3] !== "0A") continue; + const port = parseInt(columns[1].split(":")[1], 16); + if (port > 0 && !relayPorts.has(port)) ports.add(port); + } + } + const list = [...ports].sort((a, b) => a - b); + const key = list.join(","); + if (key === lastPorts) return; + lastPorts = key; + send(T.PORTS, 0, Buffer.from(JSON.stringify(list))); +} +function handle(type, id, payload) { + if (type === T.CONNECT) return connectLocal(id, payload.readUInt16BE(0)); + if (type === T.LISTEN) return listen(payload.readUInt16BE(0), payload.toString("utf8", 2)); + const socket = sockets.get(id); + const entry = pending.get(id); + if (type === T.DATA) { + if (socket) writeTo(socket, payload); + else if (entry) entry.chunks.push(Buffer.from(payload)); + } else if (type === T.END) { + if (socket) socket.end(); + else if (entry) entry.ended = true; + } else if (type === T.CLOSE) { + if (socket) { + sockets.delete(id); + socket.destroy(); + } else if (entry) { + entry.closed = true; + pending.delete(id); + } + } +} +let buffer = Buffer.alloc(0); +process.stdin.on("data", (chunk) => { + buffer = buffer.length === 0 ? chunk : Buffer.concat([buffer, chunk]); + while (buffer.length >= 9) { + const length = buffer.readUInt32BE(5); + if (buffer.length < 9 + length) break; + const type = buffer.readUInt8(0); + const id = buffer.readUInt32BE(1); + const payload = buffer.subarray(9, 9 + length); + buffer = buffer.subarray(9 + length); + handle(type, id, payload); + } +}); +process.stdin.on("end", () => process.exit(0)); +setInterval(scanPorts, 1500); +scanPorts(); +`; + +/** + * Runs inside the container with `node -e `. Kills every + * process in the session of a command started through the sandbox exec + * launcher, or of every recorded command with `--all`. Killing a `docker exec` + * client leaves its process running in the container, so this is how commands + * stop. Each exec leads its own session, and children keep that session even + * after their parent exits, so none escape. A record whose leader is alive + * with a different start time belongs to a reused PID and is skipped. + */ +export const SANDBOX_KILL_SOURCE = String.raw`"use strict"; +const fs = require("fs"); +const dir = "/tmp/.t3-exec"; +const target = process.argv[1]; +let ids = [target]; +if (target === "--all") { + try { + ids = fs.readdirSync(dir); + } catch { + ids = []; + } +} +const stat = (pid) => { + try { + const text = fs.readFileSync("/proc/" + pid + "/stat", "utf8"); + const fields = text.slice(text.lastIndexOf(")") + 2).split(" "); + return { session: Number(fields[3]), start: fields[19] }; + } catch { + return null; + } +}; +const sessions = new Set(); +for (const id of ids) { + try { + const [pid, start] = fs.readFileSync(dir + "/" + id, "utf8").trim().split(" "); + fs.unlinkSync(dir + "/" + id); + const leader = stat(pid); + if (Number(pid) > 1 && (leader === null || leader.start === start)) sessions.add(Number(pid)); + } catch {} +} +const pids = []; +for (const entry of fs.readdirSync("/proc")) { + if (!/^\d+$/.test(entry) || Number(entry) === process.pid) continue; + const info = stat(entry); + if (info !== null && sessions.has(info.session)) pids.push(Number(entry)); +} +const signal = (name) => + pids.filter((pid) => { + try { + process.kill(pid, name); + return true; + } catch { + return false; + } + }).length; +if (signal("SIGTERM") > 0) setTimeout(() => signal("SIGKILL"), 2000); +`; + +/** + * Wraps a command so the container records its PID and start time under the + * exec id before running it. `SANDBOX_KILL_SOURCE` uses that record to stop + * it later. The launcher is `sh`, whose stat line has no spaces before field 22. + */ +export const sandboxExecLauncherArgs = ( + execId: string, + command: string, + args: ReadonlyArray, +): ReadonlyArray => [ + "/bin/sh", + "-c", + 'mkdir -p /tmp/.t3-exec && echo "$$ $(cut -d" " -f22 /proc/$$/stat)" > "/tmp/.t3-exec/$0" && exec "$@"', + execId, + command, + ...args, +]; + +export interface SandboxTunnelOptions { + /** Starts the relay: `docker exec -i node -e SANDBOX_RELAY_SOURCE`. */ + readonly spawnRelay: () => NodeChildProcess.ChildProcessWithoutNullStreams; + /** + * Loopback addresses that listen inside the container and connect back to + * the same address on the host, normally on the same port. + */ + readonly reversePorts: ReadonlyArray<{ + readonly host: string; + readonly containerPort: number; + readonly hostPort: number; + }>; + /** Host port to try first for a container port, so URLs stay stable across restarts. */ + readonly preferredHostPort: (containerPort: number) => number; + readonly onPortsChanged: (ports: ReadonlyArray) => void; + readonly onExit: (detail: string) => void; +} + +interface Forwarder { + readonly server: NodeNet.Server; + hostPort: number | null; +} + +interface PendingHostConnection { + readonly chunks: Array; + ended: boolean; + closed: boolean; +} + +/** Host side of the relay. Call `close` to stop it; `onExit` fires once either way. */ +export class SandboxTunnel { + private readonly relay: NodeChildProcess.ChildProcessWithoutNullStreams; + private readonly sockets = new Map(); + private readonly pendingHost = new Map(); + private readonly forwarders = new Map(); + private nextId = 2; + private paused = false; + private exited = false; + private buffer: Buffer = Buffer.alloc(0); + private stderrTail = ""; + private readonly options: SandboxTunnelOptions; + + constructor(options: SandboxTunnelOptions) { + this.options = options; + this.relay = options.spawnRelay(); + this.relay.stdout.on("data", (chunk: Buffer) => this.receive(chunk)); + this.relay.stderr.on("data", (chunk: Buffer) => { + this.stderrTail = (this.stderrTail + chunk.toString("utf8")).slice(-500); + }); + this.relay.stdin.on("error", () => {}); + this.relay.on("error", (error) => this.shutdown(`relay failed to start: ${error.message}`)); + this.relay.on("exit", (code, signal) => + this.shutdown( + `relay exited (${signal ?? code ?? "unknown"})${this.stderrTail ? `: ${this.stderrTail.trim()}` : ""}`, + ), + ); + for (const { host, containerPort } of options.reversePorts) { + this.send(FRAME.listen, 0, Buffer.concat([port16(containerPort), Buffer.from(host)])); + } + } + + /** Forwarded ports that currently have a host listener. */ + get ports(): ReadonlyArray { + const ports: Array = []; + for (const [containerPort, forwarder] of this.forwarders) { + if (forwarder.hostPort !== null) ports.push({ containerPort, hostPort: forwarder.hostPort }); + } + return ports.toSorted((left, right) => left.containerPort - right.containerPort); + } + + get alive(): boolean { + return !this.exited; + } + + close(): void { + this.relay.stdin.end(); + this.relay.kill("SIGTERM"); + this.shutdown("closed"); + } + + private shutdown(detail: string): void { + if (this.exited) return; + this.exited = true; + for (const socket of this.sockets.values()) socket.destroy(); + this.sockets.clear(); + this.pendingHost.clear(); + for (const forwarder of this.forwarders.values()) forwarder.server.close(); + this.forwarders.clear(); + this.options.onExit(detail); + } + + private send(type: number, id: number, payload: Buffer = Buffer.alloc(0)): void { + if (this.exited) return; + const header = Buffer.allocUnsafe(HEADER_BYTES); + header.writeUInt8(type, 0); + header.writeUInt32BE(id, 1); + header.writeUInt32BE(payload.length, 5); + if (!this.relay.stdin.write(Buffer.concat([header, payload])) && !this.paused) { + this.paused = true; + for (const socket of this.sockets.values()) socket.pause(); + this.relay.stdin.once("drain", () => { + this.paused = false; + for (const socket of this.sockets.values()) socket.resume(); + }); + } + } + + private receive(chunk: Buffer): void { + this.buffer = this.buffer.length === 0 ? chunk : Buffer.concat([this.buffer, chunk]); + while (this.buffer.length >= HEADER_BYTES) { + const length = this.buffer.readUInt32BE(5); + if (this.buffer.length < HEADER_BYTES + length) return; + const type = this.buffer.readUInt8(0); + const id = this.buffer.readUInt32BE(1); + const payload = Buffer.from(this.buffer.subarray(HEADER_BYTES, HEADER_BYTES + length)); + this.buffer = this.buffer.subarray(HEADER_BYTES + length); + this.handle(type, id, payload); + } + } + + private handle(type: number, id: number, payload: Buffer): void { + switch (type) { + case FRAME.ports: + this.syncForwarders(parsePorts(payload)); + return; + case FRAME.accepted: + this.connectHost(id, payload.readUInt16BE(0)); + return; + case FRAME.error: + // Reverse listeners only fail when the port is taken inside the + // container; the agent then cannot reach MCP, which it reports itself. + return; + } + const socket = this.sockets.get(id); + const pending = this.pendingHost.get(id); + if (type === FRAME.data) { + if (socket) this.writeTo(socket, payload); + else pending?.chunks.push(payload); + } else if (type === FRAME.end) { + if (socket) socket.end(); + else if (pending) pending.ended = true; + } else if (type === FRAME.close) { + if (socket) { + this.sockets.delete(id); + socket.destroy(); + } else if (pending) { + pending.closed = true; + this.pendingHost.delete(id); + } + } + } + + private writeTo(socket: NodeNet.Socket, chunk: Buffer): void { + if (socket.write(chunk)) return; + this.relay.stdout.pause(); + const resume = () => { + socket.off("drain", resume); + socket.off("close", resume); + this.relay.stdout.resume(); + }; + socket.on("drain", resume); + socket.on("close", resume); + } + + private attach(id: number, socket: NodeNet.Socket): void { + this.sockets.set(id, socket); + if (this.paused) socket.pause(); + socket.on("data", (chunk: Buffer) => this.send(FRAME.data, id, chunk)); + socket.on("end", () => this.send(FRAME.end, id)); + socket.on("error", () => {}); + socket.on("close", () => { + if (this.sockets.delete(id)) this.send(FRAME.close, id); + }); + } + + /** A connection opened inside the container on a reverse port. */ + private connectHost(id: number, containerPort: number): void { + const target = this.options.reversePorts.find((entry) => entry.containerPort === containerPort); + if (target === undefined) return this.send(FRAME.close, id); + const pending: PendingHostConnection = { chunks: [], ended: false, closed: false }; + this.pendingHost.set(id, pending); + const socket = NodeNet.connect({ host: target.host, port: target.hostPort }); + socket.once("error", () => { + if (this.pendingHost.delete(id)) this.send(FRAME.close, id); + }); + socket.once("connect", () => { + this.pendingHost.delete(id); + if (pending.closed || this.exited) return void socket.destroy(); + for (const chunk of pending.chunks) socket.write(chunk); + if (pending.ended) socket.end(); + this.attach(id, socket); + }); + } + + private syncForwarders(containerPorts: ReadonlyArray): void { + const wanted = new Set(containerPorts); + let changed = false; + for (const [containerPort, forwarder] of this.forwarders) { + if (wanted.has(containerPort)) continue; + forwarder.server.close(); + this.forwarders.delete(containerPort); + changed = true; + } + for (const containerPort of wanted) { + if (this.forwarders.has(containerPort)) continue; + this.openForwarder(containerPort); + } + if (changed) this.options.onPortsChanged(this.ports); + } + + private openForwarder(containerPort: number): void { + const server = NodeNet.createServer((socket) => { + const id = this.nextId; + this.nextId += 2; + this.send(FRAME.connect, id, port16(containerPort)); + this.attach(id, socket); + }); + const forwarder: Forwarder = { server, hostPort: null }; + this.forwarders.set(containerPort, forwarder); + const listen = (port: number) => server.listen(port, "127.0.0.1"); + server.on("listening", () => { + const address = server.address(); + if (this.forwarders.get(containerPort) !== forwarder || typeof address !== "object") return; + forwarder.hostPort = address?.port ?? null; + this.options.onPortsChanged(this.ports); + }); + server.on("error", (error: NodeJS.ErrnoException) => { + // The stable port is taken: fall back to any free port once. + if (error.code === "EADDRINUSE" && forwarder.hostPort === null) listen(0); + }); + listen(this.options.preferredHostPort(containerPort)); + } +} + +function port16(port: number): Buffer { + const buffer = Buffer.allocUnsafe(2); + buffer.writeUInt16BE(port, 0); + return buffer; +} + +function parsePorts(payload: Buffer): ReadonlyArray { + try { + const parsed: unknown = JSON.parse(payload.toString("utf8")); + return Array.isArray(parsed) + ? parsed.filter((port): port is number => Number.isInteger(port) && port > 0 && port < 65536) + : []; + } catch { + return []; + } +} diff --git a/apps/server/src/sandbox/sandboxClaudeSpawn.ts b/apps/server/src/sandbox/sandboxClaudeSpawn.ts new file mode 100644 index 0000000000000..17fc03ea36bfe --- /dev/null +++ b/apps/server/src/sandbox/sandboxClaudeSpawn.ts @@ -0,0 +1,39 @@ +// @effect-diagnostics nodeBuiltinImport:off - the Claude SDK spawn hook must return a Node child process. +import * as NodeChildProcess from "node:child_process"; +import * as NodePath from "node:path"; + +import type { SpawnedProcess, SpawnOptions } from "@anthropic-ai/claude-agent-sdk"; + +import type { SandboxExecTarget } from "./SandboxService.ts"; + +const SCRIPT_RUNTIMES = new Set(["node", "bun", "deno"]); + +/** + * `spawnClaudeCodeProcess` for a sandboxed worktree. The SDK passes the + * host's Claude executable, which may be a macOS binary; the image's own + * `claude` (pinned to the host version) runs instead with the same arguments. + */ +export const sandboxClaudeSpawn = + (target: SandboxExecTarget) => + (options: SpawnOptions): SpawnedProcess => { + const runtime = NodePath.basename(options.command).replace(/\.exe$/, ""); + const args = + SCRIPT_RUNTIMES.has(runtime) && /\.(c|m)?js$/.test(options.args[0] ?? "") + ? options.args.slice(1) + : options.args; + const command = target.command({ + command: "claude", + args, + cwd: options.cwd ?? target.worktreePath, + env: options.env, + tty: false, + }); + const child = NodeChildProcess.spawn(command.command, [...command.args], { + env: command.env, + stdio: ["pipe", "pipe", "pipe"], + signal: options.signal, + }); + child.once("exit", command.release); + child.once("error", command.release); + return child; + }; diff --git a/apps/server/src/sandbox/sandboxDocker.test.ts b/apps/server/src/sandbox/sandboxDocker.test.ts new file mode 100644 index 0000000000000..a578406e6050c --- /dev/null +++ b/apps/server/src/sandbox/sandboxDocker.test.ts @@ -0,0 +1,82 @@ +import { describe, expect, it } from "vite-plus/test"; + +import { + dockerExecArgs, + preferredSandboxHostPort, + sandboxContainerName, + sandboxEnvNames, +} from "./sandboxDocker.ts"; + +describe("sandboxEnvNames", () => { + const hostEnv = { + PATH: "/usr/local/bin:/usr/bin", + HOME: "/Users/theo", + XDG_RUNTIME_DIR: "/run/user/501", + EDITOR: "vim", + ANTHROPIC_API_KEY: "sk-host", + LANG: "en_US.UTF-8", + }; + + it("passes overrides and inherited credentials but not host plumbing", () => { + const names = sandboxEnvNames( + { + ...hostEnv, + PATH: "/managed/bin:/usr/local/bin:/usr/bin", + CLAUDE_CODE_ENTRYPOINT: "sdk-ts", + T3_THREAD: "thread-1", + }, + hostEnv, + ); + expect(names).toEqual(["ANTHROPIC_API_KEY", "CLAUDE_CODE_ENTRYPOINT", "LANG", "T3_THREAD"]); + }); + + it("skips unset values", () => { + expect(sandboxEnvNames({ OPENAI_API_KEY: undefined }, {})).toEqual([]); + }); +}); + +describe("dockerExecArgs", () => { + it("names env vars without their values and records the command's pid", () => { + const args = dockerExecArgs({ + containerName: "t3code-sandbox-x", + execId: "exec-1", + cwd: "/work/tree", + envNames: ["ANTHROPIC_API_KEY"], + tty: false, + command: "claude", + args: ["--output-format", "stream-json"], + }); + expect(args).toEqual([ + "exec", + "-i", + "-w", + "/work/tree", + "-e", + "ANTHROPIC_API_KEY", + "t3code-sandbox-x", + "/bin/sh", + "-c", + 'mkdir -p /tmp/.t3-exec && echo "$$ $(cut -d" " -f22 /proc/$$/stat)" > "/tmp/.t3-exec/$0" && exec "$@"', + "exec-1", + "claude", + "--output-format", + "stream-json", + ]); + }); +}); + +describe("sandbox names", () => { + it("derives a stable, Docker-safe container name per worktree", () => { + const name = sandboxContainerName("/Users/theo/.t3/worktrees/t3code/Feature Branch!"); + expect(name).toMatch(/^t3code-sandbox-feature-branch-[0-9a-f]{8}$/); + expect(sandboxContainerName("/Users/theo/.t3/worktrees/t3code/Feature Branch!")).toBe(name); + expect(sandboxContainerName("/other/Feature Branch!")).not.toBe(name); + }); + + it("keeps preferred host ports in a fixed range", () => { + const port = preferredSandboxHostPort("t3code-sandbox-x", 3000); + expect(port).toBeGreaterThanOrEqual(42000); + expect(port).toBeLessThan(50000); + expect(preferredSandboxHostPort("t3code-sandbox-x", 3000)).toBe(port); + }); +}); diff --git a/apps/server/src/sandbox/sandboxDocker.ts b/apps/server/src/sandbox/sandboxDocker.ts new file mode 100644 index 0000000000000..b5bbe4098ed96 --- /dev/null +++ b/apps/server/src/sandbox/sandboxDocker.ts @@ -0,0 +1,247 @@ +// @effect-diagnostics nodeBuiltinImport:off - hashing image and container names. +import * as NodeCrypto from "node:crypto"; +import * as NodePath from "node:path"; + +import { sandboxExecLauncherArgs } from "./SandboxTunnel.ts"; + +/** + * The sandbox image: a Debian Node image with Claude Code and Codex pinned to + * the versions T3 runs on the host, and a user whose uid, gid, and home path match the + * host. Matching ids keep files the agent writes in the worktree owned by the + * user. Matching the home path lets the provider config folders mount at the + * same paths, so session files the host reads stay where it expects them. + * The user has passwordless sudo so agents can install services like + * databases inside their own sandbox. + */ +export const SANDBOX_DOCKERFILE = `FROM node:24 +ARG SANDBOX_UID +ARG SANDBOX_GID +ARG SANDBOX_HOME +ARG CLAUDE_VERSION=latest +ARG CODEX_VERSION=latest +RUN apt-get update \\ + && apt-get install -y --no-install-recommends sudo ripgrep jq less procps lsof iproute2 \\ + && rm -rf /var/lib/apt/lists/* +RUN npm install -g "@anthropic-ai/claude-code@\${CLAUDE_VERSION}" "@openai/codex@\${CODEX_VERSION}" \\ + && npm cache clean --force +RUN userdel -r node 2>/dev/null || true \\ + && (getent group "\${SANDBOX_GID}" >/dev/null || groupadd -g "\${SANDBOX_GID}" t3) \\ + && useradd -o -u "\${SANDBOX_UID}" -g "\${SANDBOX_GID}" -d "\${SANDBOX_HOME}" -m -s /bin/bash t3 \\ + && echo "t3 ALL=(ALL) NOPASSWD:ALL" > /etc/sudoers.d/t3 \\ + && chmod 0440 /etc/sudoers.d/t3 +USER \${SANDBOX_UID}:\${SANDBOX_GID} +ENV HOME=\${SANDBOX_HOME} SHELL=/bin/bash \\ + GIT_CONFIG_COUNT=1 GIT_CONFIG_KEY_0=safe.directory GIT_CONFIG_VALUE_0=* +CMD ["sleep", "infinity"] +`; + +/** Labels on every container and image T3 creates. Containers carry enough to be adopted. */ +export const SANDBOX_LABELS = { + sandbox: "t3code.sandbox", + /** Hash of the owning server's state dir, so servers on one machine never adopt each other's. */ + owner: "t3code.sandbox.owner", + worktree: "t3code.sandbox.worktree", + claude: "t3code.sandbox.claude", + codex: "t3code.sandbox.codex", +} as const; + +/** Claude Code and Codex versions installed in the image, or "latest". */ +export interface SandboxCliVersions { + readonly claude: string; + readonly codex: string; +} + +export interface SandboxImageInput { + readonly uid: number; + readonly gid: number; + readonly home: string; + readonly versions: SandboxCliVersions; +} + +const shortHash = (value: string, length: number) => + NodeCrypto.createHash("sha256").update(value).digest("hex").slice(0, length); + +/** Images are content addressed, so a new CLI version builds a new image. */ +export const sandboxImageTag = (input: SandboxImageInput): string => + `t3code-sandbox:${shortHash( + JSON.stringify([ + SANDBOX_DOCKERFILE, + input.uid, + input.gid, + input.home, + input.versions.claude, + input.versions.codex, + ]), + 12, + )}`; + +export const sandboxImageBuildArgs = ( + input: SandboxImageInput, + tag: string, +): ReadonlyArray => [ + "build", + "--progress=plain", + "--label", + `${SANDBOX_LABELS.sandbox}=1`, + "--build-arg", + `SANDBOX_UID=${input.uid}`, + "--build-arg", + `SANDBOX_GID=${input.gid}`, + "--build-arg", + `SANDBOX_HOME=${input.home}`, + "--build-arg", + `CLAUDE_VERSION=${input.versions.claude}`, + "--build-arg", + `CODEX_VERSION=${input.versions.codex}`, + "-t", + tag, + "-", +]; + +/** Owner label value for a server state dir. */ +export const sandboxOwner = (stateDir: string): string => shortHash(stateDir, 16); + +/** Stable per worktree, readable in `docker ps`. */ +export const sandboxContainerName = (worktreePath: string): string => { + const slug = + NodePath.basename(worktreePath) + .toLowerCase() + .replace(/[^a-z0-9_.-]+/g, "-") + .slice(0, 40) + .replace(/^[^a-z0-9]+|[^a-z0-9]+$/g, "") || "worktree"; + return `t3code-sandbox-${slug}-${shortHash(worktreePath, 8)}`; +}; + +/** + * Host port to try first for a forwarded container port. Stable per + * container and port, so preview URLs survive server restarts. + */ +export const preferredSandboxHostPort = (containerName: string, containerPort: number): number => + 42000 + (Number.parseInt(shortHash(`${containerName}:${containerPort}`, 6), 16) % 8000); + +export interface SandboxMount { + readonly path: string; + readonly readOnly: boolean; +} + +/** Each mount lands at the same path inside the container. */ +export const dockerRunArgs = (input: { + readonly owner: string; + readonly containerName: string; + readonly image: string; + readonly worktreePath: string; + readonly versions: SandboxCliVersions; + readonly mounts: ReadonlyArray; + /** Docker disables IPv6 in containers by default; a server bound to ::1 needs it on loopback. */ + readonly ipv6Loopback: boolean; +}): ReadonlyArray => [ + "run", + "--detach", + "--init", + "--name", + input.containerName, + "--hostname", + "t3-sandbox", + "--label", + `${SANDBOX_LABELS.sandbox}=1`, + "--label", + `${SANDBOX_LABELS.owner}=${input.owner}`, + "--label", + `${SANDBOX_LABELS.worktree}=${input.worktreePath}`, + "--label", + `${SANDBOX_LABELS.claude}=${input.versions.claude}`, + "--label", + `${SANDBOX_LABELS.codex}=${input.versions.codex}`, + ...(input.ipv6Loopback ? ["--sysctl", "net.ipv6.conf.lo.disable_ipv6=0"] : []), + ...input.mounts.flatMap((mount) => [ + "--mount", + `type=bind,source=${mount.path},target=${mount.path}${mount.readOnly ? ",readonly" : ""}`, + ]), + input.image, +]; + +/** `--mount` is comma separated, so a comma in a path cannot be expressed. */ +export const isMountablePath = (path: string): boolean => !path.includes(","); + +const SKIPPED_NAMES = new Set([ + "PATH", + "HOME", + "USER", + "LOGNAME", + "SHELL", + "PWD", + "OLDPWD", + "SHLVL", + "_", + "TMPDIR", + "TMP", + "TEMP", + "HOSTNAME", + "DISPLAY", + "WAYLAND_DISPLAY", + "SSH_AUTH_SOCK", + "NODE_OPTIONS", + "NODE_PATH", + "APPIMAGE", + "APPDIR", + "OWD", + "ARGV0", +]); +const SKIPPED_PREFIXES = [ + "XDG_", + "DBUS_", + "LD_", + "DYLD_", + "ELECTRON_", + "VSCODE_", + "TERM_PROGRAM", + "__CF", + "npm_", + "CHROME_", +]; +/** Inherited host variables worth passing: provider credentials, proxies, locale. */ +const INHERITED_NAMES = + /^(ANTHROPIC_|CLAUDE_|OPENAI_|CODEX_|AWS_|GOOGLE_|GEMINI_|VERTEX_|AZURE_|LC_)|^(HTTPS?_PROXY|NO_PROXY|ALL_PROXY|https?_proxy|no_proxy|all_proxy|LANG|TERM|COLORTERM|TZ|GH_TOKEN|GITHUB_TOKEN)$/; + +/** + * Names of the variables a sandboxed command should receive. A command's env + * is usually the server's own env plus overrides. Host paths and session + * plumbing (PATH, HOME, XDG_*) would break inside the container, so only the + * overrides and a short list of inherited credentials and locale pass through. + */ +export const sandboxEnvNames = ( + env: NodeJS.ProcessEnv, + hostEnv: NodeJS.ProcessEnv, +): ReadonlyArray => + Object.keys(env) + .filter((name) => { + const value = env[name]; + if (value === undefined || name.includes("=")) return false; + if (SKIPPED_NAMES.has(name) || SKIPPED_PREFIXES.some((prefix) => name.startsWith(prefix))) { + return false; + } + return value !== hostEnv[name] || INHERITED_NAMES.test(name); + }) + .toSorted(); + +/** + * `docker exec` arguments for one command. Values travel in the Docker + * client's own env (`-e NAME` copies them), so secrets never appear in argv. + */ +export const dockerExecArgs = (input: { + readonly containerName: string; + readonly execId: string; + readonly cwd: string; + readonly envNames: ReadonlyArray; + readonly tty: boolean; + readonly command: string; + readonly args: ReadonlyArray; +}): ReadonlyArray => [ + "exec", + input.tty ? "-it" : "-i", + "-w", + input.cwd, + ...input.envNames.flatMap((name) => ["-e", name]), + input.containerName, + ...sandboxExecLauncherArgs(input.execId, input.command, input.args), +]; diff --git a/apps/server/src/server.ts b/apps/server/src/server.ts index 9e9d5c5e30644..af982f3eb50e1 100644 --- a/apps/server/src/server.ts +++ b/apps/server/src/server.ts @@ -70,6 +70,7 @@ import * as DeviceService from "./device/DeviceService.ts"; import { deviceHubProxyRouteLayer } from "./device/DeviceHubProxy.ts"; import * as PreviewManager from "./preview/Manager.ts"; import * as PortScanner from "./preview/PortScanner.ts"; +import * as SandboxService from "./sandbox/SandboxService.ts"; import * as ProcessRunner from "./processRunner.ts"; import * as GitManager from "./git/GitManager.ts"; import * as EnvironmentTheme from "./environmentTheme.ts"; @@ -594,6 +595,7 @@ const RuntimeCoreDependenciesLive = RuntimeCoreDependenciesBaseLive.pipe( OpenCodeRuntime.OpenCodeRuntimeLive.pipe(Layer.provide(OpenCodeServerLedger.layer)), ), Layer.provideMerge(WorkspaceLayerLive), + Layer.provideMerge(SandboxService.layer.pipe(Layer.provide(ProcessRunner.layer))), Layer.provideMerge(ProjectEnrichmentService.layer), Layer.provideMerge(Layer.mergeAll(NativeAppIconResolver.layer, ProjectFaviconResolverLayerLive)), Layer.provideMerge(RepositoryIdentityResolverLayerLive), diff --git a/apps/server/src/terminal/Manager.ts b/apps/server/src/terminal/Manager.ts index 6122c8606f0b0..be1a786a6930b 100644 --- a/apps/server/src/terminal/Manager.ts +++ b/apps/server/src/terminal/Manager.ts @@ -77,6 +77,7 @@ import * as ProcessRunner from "../processRunner.ts"; import * as PortScanner from "../preview/PortScanner.ts"; import * as NativeTelemetryClient from "../resourceTelemetry/NativeTelemetryClient.ts"; import * as PtyAdapter from "./PtyAdapter.ts"; +import * as SandboxService from "../sandbox/SandboxService.ts"; export { TerminalCwdError, @@ -1375,6 +1376,8 @@ interface TerminalManagerOptions { readonly threadId: string; readonly terminalId: string; }) => Effect.Effect; + /** Terminals whose cwd is in a sandboxed worktree open a shell in its container. */ + sandboxes?: SandboxService.SandboxService["Service"]; resolveProviderInstanceEnvironment?: ( providerInstanceId: string, env: Record | undefined, @@ -1432,6 +1435,7 @@ export const make = Effect.fn("TerminalManager.make")(function* () { const portDiscovery = yield* PortScanner.PortDiscovery; const nativeTelemetry = yield* NativeTelemetryClient.NativeTelemetryClient; const serverSettings = yield* ServerSettings.ServerSettingsService; + const sandboxes = yield* Effect.serviceOption(SandboxService.SandboxService); const path = yield* Path.Path; const resolveProviderInstanceEnvironment = Effect.fn( "terminal.resolveProviderInstanceEnvironment", @@ -1456,9 +1460,34 @@ export const make = Effect.fn("TerminalManager.make")(function* () { registerTerminalProcesses: portDiscovery.registerTerminalProcesses, unregisterTerminal: portDiscovery.unregisterTerminal, resolveProviderInstanceEnvironment, + ...(Option.isSome(sandboxes) ? { sandboxes: sandboxes.value } : {}), }); }); +/** + * Killing the `docker exec` client leaves the sandbox shell and its children + * running, so a sandbox terminal also stops its process tree in the container. + */ +function releaseSandboxOnExit( + process: PtyAdapter.PtyProcess, + release: () => void, +): PtyAdapter.PtyProcess { + process.onExit(release); + return { + get pid() { + return process.pid; + }, + write: (data) => process.write(data), + resize: (cols, rows) => process.resize(cols, rows), + kill: (signal) => { + process.kill(signal); + release(); + }, + onData: (callback) => process.onData(callback), + onExit: (callback) => process.onExit(callback), + }; +} + export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(function* ( options: TerminalManagerOptions, ) { @@ -2217,6 +2246,45 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func return yield* trySpawn(shellCandidates, spawnEnv, session, index + 1, spawnError); }); + /** + * Spawns the session's shell. In a sandboxed worktree the shell is bash + * inside the container, reached through `docker exec -it`. + */ + const spawnShell = Effect.fn("terminal.spawnShell")(function* ( + shellCandidates: ReadonlyArray, + spawnEnv: NodeJS.ProcessEnv, + session: TerminalSessionState, + ) { + const sandbox = + options.sandboxes === undefined + ? Option.none() + : yield* options.sandboxes + .execTarget(session.cwd) + .pipe( + Effect.mapError( + (cause) => new PtyAdapter.PtySpawnError({ adapter: "sandbox", cause }), + ), + ); + if (Option.isNone(sandbox)) return yield* trySpawn(shellCandidates, spawnEnv, session); + const command = yield* Effect.try({ + try: () => + sandbox.value.command({ + command: "/bin/bash", + args: ["-l"], + cwd: session.cwd, + env: spawnEnv, + tty: true, + }), + catch: (cause) => new PtyAdapter.PtySpawnError({ adapter: "sandbox", cause }), + }); + const spawned = yield* trySpawn( + [{ shell: command.command, args: [...command.args] }], + command.env, + session, + ).pipe(Effect.tapError(() => Effect.sync(command.release))); + return { ...spawned, process: releaseSandboxOnExit(spawned.process, command.release) }; + }); + const startSession = Effect.fn("terminal.startSession")(function* ( session: TerminalSessionState, input: TerminalStartInput, @@ -2290,7 +2358,7 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func } } } - const spawnResult = yield* trySpawn(shellCandidates, terminalEnv, session); + const spawnResult = yield* spawnShell(shellCandidates, terminalEnv, session); ptyProcess = spawnResult.process; startedShell = spawnResult.shellLabel; diff --git a/apps/server/src/ws.ts b/apps/server/src/ws.ts index 783377666f147..b7ee5b51abb8f 100644 --- a/apps/server/src/ws.ts +++ b/apps/server/src/ws.ts @@ -97,6 +97,7 @@ import { type TerminalMetadataStreamEvent, type PullRequestRef, WS_METHODS, + SandboxRequestError, WsRpcGroup, } from "@t3tools/contracts"; import { resolveServerBackgroundActivitySettings } from "@t3tools/shared/backgroundActivitySettings"; @@ -203,6 +204,7 @@ import * as ProjectSetupScriptRunner from "./project/ProjectSetupScriptRunner.ts import * as ProjectCloneTracker from "./project/ProjectCloneTracker.ts"; import * as RepositoryIdentityResolver from "./project/RepositoryIdentityResolver.ts"; import * as WorktreeSetupTracker from "./project/WorktreeSetupTracker.ts"; +import * as SandboxService from "./sandbox/SandboxService.ts"; import * as ServerEnvironment from "./environment/ServerEnvironment.ts"; import * as RemoteOpenTargets from "./environment/RemoteOpenTargets.ts"; import * as BackgroundPolicy from "./background/BackgroundPolicy.ts"; @@ -1236,6 +1238,7 @@ const makeWsRpcLayer = ( const usageLimitSources = yield* UsageLimitSources.UsageLimitSources; const projectSetupScriptRunner = yield* ProjectSetupScriptRunner.ProjectSetupScriptRunner; const worktreeSetupTracker = yield* WorktreeSetupTracker.WorktreeSetupTracker; + const sandboxes = yield* SandboxService.SandboxService; const projectCloneTracker = yield* ProjectCloneTracker.ProjectCloneTracker; const repositoryIdentityResolver = yield* RepositoryIdentityResolver.RepositoryIdentityResolver; @@ -1747,6 +1750,7 @@ const makeWsRpcLayer = ( shellResumeCompletionMarker: true, threadResumeCompletionMarker: true, threadSnapshotPagination: true, + ...(sandboxes.supported ? { sandboxes: true } : {}), ...Option.match(scratchWorkspaceRoot, { onNone: () => ({}), onSome: (root) => ({ scratchWorkspaceRoot: root }), @@ -3299,6 +3303,40 @@ const makeWsRpcLayer = ( .pipe(Effect.map((cancelled) => ({ cancelled }))), { "rpc.aggregate": "vcs" }, ), + [WS_METHODS.subscribeSandboxes]: () => + observeRpcStream(WS_METHODS.subscribeSandboxes, sandboxes.stream, { + "rpc.aggregate": "vcs", + }), + [WS_METHODS.sandboxStop]: (input) => + observeRpcEffect( + WS_METHODS.sandboxStop, + sandboxes.stop(input.worktreePath).pipe( + Effect.mapError( + (error) => + new SandboxRequestError({ + operation: "stop", + worktreePath: input.worktreePath, + detail: error.detail, + }), + ), + ), + { "rpc.aggregate": "vcs" }, + ), + [WS_METHODS.sandboxRemove]: (input) => + observeRpcEffect( + WS_METHODS.sandboxRemove, + sandboxes.remove(input.worktreePath).pipe( + Effect.mapError( + (error) => + new SandboxRequestError({ + operation: "remove", + worktreePath: input.worktreePath, + detail: error.detail, + }), + ), + ), + { "rpc.aggregate": "vcs" }, + ), [WS_METHODS.vcsRefreshStatus]: (input) => observeRpcEffect( WS_METHODS.vcsRefreshStatus, diff --git a/apps/web/src/components/BranchToolbar.logic.test.ts b/apps/web/src/components/BranchToolbar.logic.test.ts index 4de529a3d558a..6bbc0003f2678 100644 --- a/apps/web/src/components/BranchToolbar.logic.test.ts +++ b/apps/web/src/components/BranchToolbar.logic.test.ts @@ -15,6 +15,7 @@ import { resolveLockedWorkspaceLabel, resolveWorkspaceDisplayName, resolveLocalCheckoutBranchMismatch, + resolveSupportedEnvMode, resolvePreviousWorktreeLabel, resolvePreviousWorktreeSeed, sanitizeNewRefName, @@ -141,6 +142,31 @@ describe("resolveDraftEnvModeAfterBranchChange", () => { }), ).toBe("worktree"); }); + + it("keeps new-sandbox mode when selecting a base ref, and drops it for an existing worktree", () => { + expect( + resolveDraftEnvModeAfterBranchChange({ + nextWorktreePath: null, + currentWorktreePath: null, + effectiveEnvMode: "sandbox", + }), + ).toBe("sandbox"); + expect( + resolveDraftEnvModeAfterBranchChange({ + nextWorktreePath: "/repo/.t3/worktrees/feature-a", + currentWorktreePath: null, + effectiveEnvMode: "sandbox", + }), + ).toBe("worktree"); + }); +}); + +describe("resolveSupportedEnvMode", () => { + it("falls back to a plain worktree when the server cannot run sandboxes", () => { + expect(resolveSupportedEnvMode("sandbox", false)).toBe("worktree"); + expect(resolveSupportedEnvMode("sandbox", true)).toBe("sandbox"); + expect(resolveSupportedEnvMode("local", false)).toBe("local"); + }); }); describe("resolveBranchToolbarValue", () => { @@ -539,6 +565,7 @@ describe("resolveEnvModeLabel", () => { it("uses explicit workspace labels", () => { expect(resolveEnvModeLabel("local")).toBe("Current checkout"); expect(resolveEnvModeLabel("worktree")).toBe("New worktree"); + expect(resolveEnvModeLabel("sandbox")).toBe("New sandbox"); }); }); diff --git a/apps/web/src/components/BranchToolbar.logic.ts b/apps/web/src/components/BranchToolbar.logic.ts index cfa62ad7fe925..542d5bf1cd89a 100644 --- a/apps/web/src/components/BranchToolbar.logic.ts +++ b/apps/web/src/components/BranchToolbar.logic.ts @@ -22,9 +22,17 @@ export interface EnvironmentOption { machine: EnvironmentMachineKind; } -export const EnvMode = Schema.Literals(["local", "worktree"]); +// "worktree" and "sandbox" both start the thread in a new worktree. A sandbox +// also runs that worktree's agent, terminals, and setup script in Docker. +export const EnvMode = Schema.Literals(["local", "worktree", "sandbox"]); export type EnvMode = typeof EnvMode.Type; +// Sandboxes need server support. A draft that asked for one on a server +// without it (for example after a machine switch) gets a plain worktree. +export function resolveSupportedEnvMode(mode: EnvMode, sandboxesAvailable: boolean): EnvMode { + return mode === "sandbox" && !sandboxesAvailable ? "worktree" : mode; +} + const GENERIC_LOCAL_ENVIRONMENT_LABELS = new Set(["local", "local environment"]); function normalizeDisplayLabel(value: string | null | undefined): string | null { @@ -94,7 +102,14 @@ export function resolveContextStripLabelsCompact(input: { } export function resolveEnvModeLabel(mode: EnvMode): string { - return mode === "worktree" ? "New worktree" : "Current checkout"; + switch (mode) { + case "local": + return "Current checkout"; + case "worktree": + return "New worktree"; + case "sandbox": + return "New sandbox"; + } } export const WORKTREE_SUBMODULES_LABELS: Record = { @@ -114,7 +129,7 @@ export function resolveLockedWorkspaceLabel( effectiveEnvMode: EnvMode, ): string { if (activeWorktreePath) return "Worktree"; - return effectiveEnvMode === "worktree" ? resolveEnvModeLabel("worktree") : "Local checkout"; + return effectiveEnvMode === "local" ? "Local checkout" : resolveEnvModeLabel(effectiveEnvMode); } export function resolveWorkspaceDisplayName(path: string | null): string | null { @@ -186,7 +201,7 @@ export function resolveEffectiveEnvMode(input: { if (activeWorktreePath) { return "local"; } - return draftThreadEnvMode === "worktree" ? "worktree" : "local"; + return draftThreadEnvMode ?? "local"; } return activeWorktreePath || preparingWorktree ? "worktree" : "local"; } @@ -200,8 +215,8 @@ export function resolveDraftEnvModeAfterBranchChange(input: { if (nextWorktreePath) { return "worktree"; } - if (effectiveEnvMode === "worktree" && !currentWorktreePath) { - return "worktree"; + if (effectiveEnvMode !== "local" && !currentWorktreePath) { + return effectiveEnvMode; } return "local"; } @@ -213,7 +228,7 @@ export function resolveBranchToolbarValue(input: { currentGitBranch: string | null; }): string | null { const { envMode, activeWorktreePath, activeThreadBranch, currentGitBranch } = input; - if (envMode === "worktree" && !activeWorktreePath) { + if (envMode !== "local" && !activeWorktreePath) { return activeThreadBranch ?? currentGitBranch; } return currentGitBranch ?? activeThreadBranch; @@ -236,7 +251,7 @@ export function resolveBranchTriggerLabel(input: { if (!resolvedActiveBranch) { return "Select ref"; } - if (effectiveEnvMode === "worktree" && !activeWorktreePath) { + if (effectiveEnvMode !== "local" && !activeWorktreePath) { const baseRef = startFromOrigin && resolvedActiveBranchIsRemote === false ? `origin/${resolvedActiveBranch}` diff --git a/apps/web/src/components/BranchToolbar.tsx b/apps/web/src/components/BranchToolbar.tsx index 7e7d4a71d7d65..7a73cf465a356 100644 --- a/apps/web/src/components/BranchToolbar.tsx +++ b/apps/web/src/components/BranchToolbar.tsx @@ -2,6 +2,7 @@ import { ComposerContextLabel } from "./ComposerContextLabel"; import { scopeProjectRef, scopeThreadRef } from "@t3tools/client-runtime/environment"; import type { EnvironmentId, ThreadId } from "@t3tools/contracts"; import { + BoxIcon, ChevronDownIcon, FolderGit2Icon, FolderGitIcon, @@ -78,6 +79,8 @@ interface BranchToolbarProps { onEnvModeChange: (mode: EnvMode) => void; /** The thread's env mode as ChatView resolves it. */ envMode: EnvMode; + /** The thread's server can run new worktrees in Docker sandboxes. */ + sandboxesAvailable?: boolean; activeThreadBranchOverride?: string | null; onActiveThreadBranchOverrideChange?: (branch: string | null) => void; startFromOrigin: boolean; @@ -107,6 +110,7 @@ interface MobileRunContextSelectorProps { effectiveEnvMode: EnvMode; activeWorktreePath: string | null; onEnvModeChange: (mode: EnvMode) => void; + sandboxesAvailable: boolean; previousWorktreeLabel: string | null; previousWorktreeBranch: string | null; onUsePreviousWorktree: () => void; @@ -126,6 +130,7 @@ const MobileRunContextSelector = memo(function MobileRunContextSelector({ effectiveEnvMode, activeWorktreePath, onEnvModeChange, + sandboxesAvailable, previousWorktreeLabel, previousWorktreeBranch, onUsePreviousWorktree, @@ -136,18 +141,20 @@ const MobileRunContextSelector = memo(function MobileRunContextSelector({ [availableEnvironments, environmentId], ); const WorkspaceIcon = - effectiveEnvMode === "worktree" - ? FolderGit2Icon - : activeWorktreePath - ? FolderGitIcon - : FolderIcon; + effectiveEnvMode === "sandbox" + ? BoxIcon + : effectiveEnvMode === "worktree" + ? FolderGit2Icon + : activeWorktreePath + ? FolderGitIcon + : FolderIcon; const workspaceLabel = forceNewWorktree ? resolveEnvModeLabel("worktree") : envModeLocked ? resolveLockedWorkspaceLabel(activeWorktreePath, effectiveEnvMode) - : effectiveEnvMode === "worktree" - ? resolveEnvModeLabel("worktree") - : resolveCurrentWorkspaceLabel(activeWorktreePath); + : effectiveEnvMode === "local" + ? resolveCurrentWorkspaceLabel(activeWorktreePath) + : resolveEnvModeLabel(effectiveEnvMode); const isLocked = envLocked || envModeLocked; const workspaceIcon = ( @@ -295,6 +302,14 @@ const MobileRunContextSelector = memo(function MobileRunContextSelector({ {resolveEnvModeLabel("worktree")} + {sandboxesAvailable ? ( + + + + {resolveEnvModeLabel("sandbox")} + + + ) : null} {previousWorktreeLabel ? ( @@ -509,6 +524,7 @@ export const BranchToolbar = memo(function BranchToolbar({ draftId, onEnvModeChange, envMode, + sandboxesAvailable = false, activeThreadBranchOverride, onActiveThreadBranchOverrideChange, startFromOrigin, @@ -625,6 +641,7 @@ export const BranchToolbar = memo(function BranchToolbar({ activeWorktreePath={activeWorktreePath} workspaceRoot={activeProject.workspaceRoot} onEnvModeChange={onEnvModeChange} + sandboxesAvailable={sandboxesAvailable} /> ) : null} {panelSection !== "workspace" ? ( @@ -676,6 +693,7 @@ export const BranchToolbar = memo(function BranchToolbar({ effectiveEnvMode={effectiveEnvMode} activeWorktreePath={activeWorktreePath} onEnvModeChange={onEnvModeChange} + sandboxesAvailable={sandboxesAvailable} previousWorktreeLabel={previousWorktreeLabel} previousWorktreeBranch={previousWorktreeSeed?.branch ?? null} onUsePreviousWorktree={onUsePreviousWorktree} @@ -716,6 +734,7 @@ export const BranchToolbar = memo(function BranchToolbar({ effectiveEnvMode={effectiveEnvMode} activeWorktreePath={activeWorktreePath} onEnvModeChange={onEnvModeChange} + sandboxesAvailable={sandboxesAvailable} previousWorktreeLabel={previousWorktreeLabel} previousWorktreeBranch={previousWorktreeSeed?.branch ?? null} onUsePreviousWorktree={onUsePreviousWorktree} diff --git a/apps/web/src/components/BranchToolbarBranchSelector.tsx b/apps/web/src/components/BranchToolbarBranchSelector.tsx index 12952829566e1..9060fff189f92 100644 --- a/apps/web/src/components/BranchToolbarBranchSelector.tsx +++ b/apps/web/src/components/BranchToolbarBranchSelector.tsx @@ -52,6 +52,7 @@ import { resolveEffectiveEnvMode, sanitizeNewRefName, shouldIncludeBranchPickerItem, + type EnvMode, } from "./BranchToolbar.logic"; import { ThreadPullRequestBadgeControl, @@ -79,7 +80,7 @@ interface BranchToolbarBranchSelectorProps { threadId: ThreadId; draftId?: DraftId; envLocked: boolean; - effectiveEnvModeOverride?: "local" | "worktree"; + effectiveEnvModeOverride?: EnvMode; activeThreadBranchOverride?: string | null; onActiveThreadBranchOverrideChange?: (refName: string | null) => void; startFromOrigin: boolean; @@ -270,8 +271,7 @@ export function BranchToolbarBranchSelector({ ); const normalizedDeferredBranchQuery = deferredTrimmedBranchQuery.toLowerCase(); const prReference = parsePullRequestReference(trimmedBranchQuery); - const isSelectingWorktreeBase = - effectiveEnvMode === "worktree" && !envLocked && !activeWorktreePath; + const isSelectingWorktreeBase = effectiveEnvMode !== "local" && !envLocked && !activeWorktreePath; const checkoutPullRequestItemValue = prReference && onCheckoutPullRequestRequest ? `__checkout_pull_request__:${prReference}` : null; const canCreateBranch = !isSelectingWorktreeBase && trimmedBranchQuery.length > 0; @@ -508,7 +508,7 @@ export function BranchToolbarBranchSelector({ useEffect(() => { if ( - effectiveEnvMode !== "worktree" || + effectiveEnvMode === "local" || activeWorktreePath || activeThreadBranch || !worktreeBaseBranchCandidate diff --git a/apps/web/src/components/BranchToolbarEnvModeSelector.tsx b/apps/web/src/components/BranchToolbarEnvModeSelector.tsx index 3afa31e2acee1..5c088b6cdf706 100644 --- a/apps/web/src/components/BranchToolbarEnvModeSelector.tsx +++ b/apps/web/src/components/BranchToolbarEnvModeSelector.tsx @@ -1,6 +1,6 @@ import { ThreadDetailsSelectControl } from "./chat/ThreadDetailsControl"; import { ComposerContextLabel } from "./ComposerContextLabel"; -import { FolderGit2Icon, FolderGitIcon, FolderIcon } from "lucide-react"; +import { BoxIcon, FolderGit2Icon, FolderGitIcon, FolderIcon } from "lucide-react"; import { memo, useMemo, type MouseEvent as ReactMouseEvent } from "react"; import { writeTextToClipboard } from "../hooks/useCopyToClipboard"; import { readLocalApi } from "../localApi"; @@ -39,6 +39,8 @@ interface BranchToolbarEnvModeSelectorProps { activeWorktreePath: string | null; workspaceRoot?: string | null; onEnvModeChange: (mode: EnvMode) => void; + /** The server can run new worktrees in Docker sandboxes. */ + sandboxesAvailable?: boolean; displayMode?: "toolbar" | "panel"; previousWorktreeLabel?: string | null; previousWorktreeBranch?: string | null; @@ -52,6 +54,7 @@ export const BranchToolbarEnvModeSelector = memo(function BranchToolbarEnvModeSe activeWorktreePath, workspaceRoot = null, onEnvModeChange, + sandboxesAvailable = false, displayMode = "toolbar", previousWorktreeLabel, previousWorktreeBranch = null, @@ -63,9 +66,10 @@ export const BranchToolbarEnvModeSelector = memo(function BranchToolbarEnvModeSe const workspaceKind = activeWorktreePath ? "Worktree" : null; const lockedWorkspaceKind = forceNewWorktree ? "Worktree" : workspaceKind; const selectWorkspaceKind = - effectiveEnvMode === "worktree" && !activeWorktreePath ? "Create" : workspaceKind; + effectiveEnvMode !== "local" && !activeWorktreePath ? "Create" : workspaceKind; const composerFloatingLayerProps = useComposerMenuProps(); const showPreviousWorktree = Boolean(previousWorktreeLabel && onUsePreviousWorktree); + const NewWorkspaceIcon = effectiveEnvMode === "sandbox" ? BoxIcon : FolderGit2Icon; const envModeItems = useMemo( () => [ { @@ -73,11 +77,18 @@ export const BranchToolbarEnvModeSelector = memo(function BranchToolbarEnvModeSe label: workspaceDisplayName ?? resolveCurrentWorkspaceLabel(activeWorktreePath), }, { value: "worktree", label: resolveEnvModeLabel("worktree") }, + ...(sandboxesAvailable ? [{ value: "sandbox", label: resolveEnvModeLabel("sandbox") }] : []), ...(showPreviousWorktree && previousWorktreeLabel ? [{ value: PREVIOUS_WORKTREE_SELECT_VALUE, label: previousWorktreeLabel }] : []), ], - [activeWorktreePath, previousWorktreeLabel, showPreviousWorktree, workspaceDisplayName], + [ + activeWorktreePath, + previousWorktreeLabel, + sandboxesAvailable, + showPreviousWorktree, + workspaceDisplayName, + ], ); const handleWorkspaceContextMenu = (event: ReactMouseEvent) => { @@ -136,8 +147,8 @@ export const BranchToolbarEnvModeSelector = memo(function BranchToolbarEnvModeSe - ) : effectiveEnvMode === "worktree" ? ( - ) : ( @@ -198,8 +209,8 @@ export const BranchToolbarEnvModeSelector = memo(function BranchToolbarEnvModeSe /> } > - {effectiveEnvMode === "worktree" ? ( - ) : activeWorktreePath ? ( @@ -222,9 +233,9 @@ export const BranchToolbarEnvModeSelector = memo(function BranchToolbarEnvModeSe {workspacePath ?? - (effectiveEnvMode === "worktree" - ? resolveEnvModeLabel("worktree") - : resolveCurrentWorkspaceLabel(activeWorktreePath))} + (effectiveEnvMode === "local" + ? resolveCurrentWorkspaceLabel(activeWorktreePath) + : resolveEnvModeLabel(effectiveEnvMode))} + {sandboxesAvailable ? ( + + + + {resolveEnvModeLabel("sandbox")} + + + ) : null} {showPreviousWorktree && previousWorktreeLabel ? ( diff --git a/apps/web/src/components/ChatView.logic.ts b/apps/web/src/components/ChatView.logic.ts index 3323a8f3e0b98..c7408df2a1028 100644 --- a/apps/web/src/components/ChatView.logic.ts +++ b/apps/web/src/components/ChatView.logic.ts @@ -848,7 +848,7 @@ export function resolveBackgroundDraftWorkspaceOptions(input: { envMode: input.envMode, branch: input.branch, worktreePath: null, - startFromOrigin: input.envMode === "worktree" && input.startFromOrigin, + startFromOrigin: input.envMode !== "local" && input.startFromOrigin, }; } diff --git a/apps/web/src/components/ChatView.tsx b/apps/web/src/components/ChatView.tsx index 92400fedd9b3b..3969fb4e000c9 100644 --- a/apps/web/src/components/ChatView.tsx +++ b/apps/web/src/components/ChatView.tsx @@ -437,7 +437,9 @@ import { NoActiveThreadState } from "./NoActiveThreadState"; import { type EnvironmentOption, resolveEffectiveEnvMode, + resolveEnvModeLabel, resolveLocalCheckoutBranchMismatch, + resolveSupportedEnvMode, shouldShowComposerContextStrip, shouldShowEnvironmentIndicator, } from "./BranchToolbar.logic"; @@ -6445,9 +6447,13 @@ export default function ChatView(props: ChatViewProps) { activeThread.worktreePath === null && !envLocked, ); - const envMode: DraftThreadEnvMode = canOverrideServerThreadEnvMode - ? (pendingServerThreadEnvMode ?? draftThread?.envMode ?? derivedEnvMode) - : derivedEnvMode; + const sandboxesAvailable = serverConfig?.sandboxes === true; + const envMode: DraftThreadEnvMode = resolveSupportedEnvMode( + canOverrideServerThreadEnvMode + ? (pendingServerThreadEnvMode ?? draftThread?.envMode ?? derivedEnvMode) + : derivedEnvMode, + sandboxesAvailable, + ); const activeThreadBranch = canOverrideServerThreadEnvMode && pendingServerThreadBranch !== undefined ? pendingServerThreadBranch @@ -8571,16 +8577,19 @@ export default function ChatView(props: ChatViewProps) { const threadIdForSend = activeThread.id; const isFirstMessage = !isServerThread || activeMessageCount === 0; const baseBranchForWorktree = - isFirstMessage && sendEnvMode === "worktree" && !activeThread.worktreePath + isFirstMessage && sendEnvMode !== "local" && !activeThread.worktreePath ? activeThreadBranch : null; - // In worktree mode, require an explicit base branch so we don't silently + // In worktree or sandbox mode, require an explicit base branch so we don't silently // fall back to local execution when branch selection is missing. const shouldCreateWorktree = - isFirstMessage && sendEnvMode === "worktree" && !activeThread.worktreePath; + isFirstMessage && sendEnvMode !== "local" && !activeThread.worktreePath; if (shouldCreateWorktree && !activeThreadBranch) { - setThreadError(threadIdForSend, "Select a base branch before sending in New worktree mode."); + setThreadError( + threadIdForSend, + `Select a base branch before sending in ${resolveEnvModeLabel(sendEnvMode)} mode.`, + ); return; } @@ -9211,6 +9220,7 @@ export default function ChatView(props: ChatViewProps) { projectCwd: activeProject.workspaceRoot, baseBranch: baseBranchForWorktree, ...(startFromOrigin ? { startFromOrigin: true } : {}), + ...(sendEnvMode === "sandbox" ? { sandbox: true } : {}), }, runSetupScript: true, } @@ -10104,7 +10114,7 @@ export default function ChatView(props: ChatViewProps) { envMode: mode, newWorktreesStartFromOrigin: activeProjectSettings.settings.newWorktreesStartFromOrigin, }), - ...(mode === "worktree" && draftThread?.worktreePath ? { worktreePath: null } : {}), + ...(mode !== "local" && draftThread?.worktreePath ? { worktreePath: null } : {}), }); } scheduleComposerFocus(); @@ -10425,6 +10435,7 @@ export default function ChatView(props: ChatViewProps) { environmentId: activeThread.environmentId, threadId: activeThread.id, ...(draftId ? { draftId } : {}), + worktreePath: activeWorktreePath, activeProjectName: activeProject?.title, activeProjectScripts: activeProject ? activeProjectScripts : undefined, preferredScriptId: activeProject @@ -10445,6 +10456,7 @@ export default function ChatView(props: ChatViewProps) { onEnvironmentChange, onEnvModeChange, envMode, + sandboxesAvailable, ...(canOverrideServerThreadEnvMode ? { activeThreadBranchOverride: activeThreadBranch, @@ -11068,6 +11080,7 @@ export default function ChatView(props: ChatViewProps) { startFromOrigin={startFromOrigin} onStartFromOriginChange={onStartFromOriginChange} envMode={envMode} + sandboxesAvailable={sandboxesAvailable} {...(canOverrideServerThreadEnvMode ? { activeThreadBranchOverride: activeThreadBranch, diff --git a/apps/web/src/components/GitActionsControl.tsx b/apps/web/src/components/GitActionsControl.tsx index e6635d8921657..6d0e985440e50 100644 --- a/apps/web/src/components/GitActionsControl.tsx +++ b/apps/web/src/components/GitActionsControl.tsx @@ -1209,8 +1209,8 @@ export default function GitActionsControl({ ); const isSelectingWorktreeBase = !activeServerThread && - activeDraftThread?.envMode === "worktree" && - activeDraftThread.worktreePath === null; + activeDraftThread?.worktreePath === null && + activeDraftThread.envMode !== "local"; useEffect(() => { if (isGitActionRunning || isSelectingWorktreeBase || activeServerThread) { diff --git a/apps/web/src/components/chat/ThreadDetailsPanel.test.tsx b/apps/web/src/components/chat/ThreadDetailsPanel.test.tsx index ec7d84aef49b3..8795c1ac93cbf 100644 --- a/apps/web/src/components/chat/ThreadDetailsPanel.test.tsx +++ b/apps/web/src/components/chat/ThreadDetailsPanel.test.tsx @@ -27,6 +27,9 @@ vi.mock("./ThreadAutomationsPanel", () => ({ vi.mock("./ThreadRelationshipsControl", () => ({ ThreadRelationshipsPanel: () => null, })); +vi.mock("./ThreadSandboxControl", () => ({ + ThreadSandboxControl: () => null, +})); vi.mock("./ThreadDetailsCard", () => ({ ThreadDetailsCard: ({ children }: { children: (density: "full") => React.ReactNode }) => children("full"), @@ -58,6 +61,7 @@ describe("ThreadDetailsPanel", () => { onPresentationChange: vi.fn(), environmentId, threadId: "thread:thread-details" as ThreadId, + worktreePath: null, activeProjectName: undefined, activeProjectScripts: [], preferredScriptId: null, @@ -71,6 +75,7 @@ describe("ThreadDetailsPanel", () => { onEnvironmentChange: vi.fn(), onEnvModeChange: vi.fn(), envMode: "local", + sandboxesAvailable: false, startFromOrigin: false, onStartFromOriginChange: vi.fn(), onComposerFocusRequest: vi.fn(), diff --git a/apps/web/src/components/chat/ThreadDetailsPanel.tsx b/apps/web/src/components/chat/ThreadDetailsPanel.tsx index 5b79f0c00f572..0126415b5c2bc 100644 --- a/apps/web/src/components/chat/ThreadDetailsPanel.tsx +++ b/apps/web/src/components/chat/ThreadDetailsPanel.tsx @@ -28,6 +28,7 @@ import { OpenInPicker } from "./OpenInPicker"; import { ThreadDetailsSection } from "./ThreadDetailsSection"; import { ThreadAutomationsPanel } from "./ThreadAutomationsPanel"; import { ThreadRelationshipsPanel } from "./ThreadRelationshipsControl"; +import { ThreadSandboxControl } from "./ThreadSandboxControl"; interface VersionMismatchIssue { readonly clientVersion: string; @@ -43,6 +44,8 @@ export interface ThreadDetailsPanelProps extends Pick< environmentId: EnvironmentId; threadId: ThreadId; draftId?: DraftId; + /** The thread's worktree, matched against the environment's sandboxes. */ + worktreePath: string | null; activeProjectName: string | undefined; activeProjectScripts: ReadonlyArray | undefined; preferredScriptId: string | null; @@ -59,6 +62,8 @@ export interface ThreadDetailsPanelProps extends Pick< onEnvModeChange: (mode: EnvMode) => void; /** The thread's env mode as ChatView resolves it. */ envMode: EnvMode; + /** The thread's server can run new worktrees in Docker sandboxes. */ + sandboxesAvailable: boolean; activeThreadBranchOverride?: string | null; onActiveThreadBranchOverrideChange?: (branch: string | null) => void; startFromOrigin: boolean; @@ -99,6 +104,7 @@ export function ThreadDetailsPanel(props: ThreadDetailsPanelProps) { startFromOrigin: props.startFromOrigin, onStartFromOriginChange: props.onStartFromOriginChange, envMode: props.envMode, + sandboxesAvailable: props.sandboxesAvailable, ...(props.activeThreadBranchOverride !== undefined ? { activeThreadBranchOverride: props.activeThreadBranchOverride } : {}), @@ -168,6 +174,14 @@ export function ThreadDetailsPanel(props: ThreadDetailsPanelProps) { ) : null} + {density !== "essential" && props.sandboxesAvailable ? ( + + ) : null} + {density !== "essential" && props.showOpenInPicker ? ( = { + starting: "Starting", + running: "Running", + stopped: "Stopped", + error: "Error", +}; + +const REMOVE_SANDBOX_CONFIRMATION = [ + "Remove the sandbox for this worktree?", + "This deletes its container, services, and machine state. The worktree files stay.", + "Later work in this worktree runs on the host.", +].join("\n"); + +/** + * Thread details row for a thread whose worktree runs in a Docker sandbox. + * Renders nothing for other threads. Mount it only for servers that can run + * sandboxes: it subscribes to the environment's sandboxes while mounted and + * the thread has a worktree. + */ +export function ThreadSandboxControl({ + environmentId, + threadId, + worktreePath, +}: { + environmentId: EnvironmentId; + threadId: ThreadId; + worktreePath: string | null; +}) { + const threadRef = useMemo( + () => scopeThreadRef(environmentId, threadId), + [environmentId, threadId], + ); + const sandboxesQuery = useEnvironmentQuery( + worktreePath !== null ? vcsEnvironment.sandboxes({ environmentId, input: {} }) : null, + ); + const sandbox = findSandboxForWorktree(sandboxesQuery.data?.sandboxes, worktreePath); + const stopSandbox = useAtomCommand(vcsEnvironment.stopSandbox, { reportFailure: false }); + const removeSandbox = useAtomCommand(vcsEnvironment.removeSandbox, { reportFailure: false }); + const openLink = useOpenLink(threadRef); + const [pending, setPending] = useState(false); + + if (!sandbox) return null; + + const runAction = async (action: "stop" | "remove") => { + if (action === "remove") { + const confirmed = await readLocalApi()?.dialogs.confirm(REMOVE_SANDBOX_CONFIRMATION, { + variant: "destructive", + }); + if (!confirmed) return; + } + setPending(true); + const command = action === "stop" ? stopSandbox : removeSandbox; + const result = await command({ + environmentId, + input: { worktreePath: sandbox.worktreePath }, + }); + setPending(false); + if (result._tag === "Success") return; + const error = squashAtomCommandFailure(result); + toastManager.add( + stackedThreadToast({ + type: "error", + title: action === "stop" ? "Could not stop sandbox" : "Could not remove sandbox", + description: error instanceof Error ? error.message : "An error occurred.", + }), + ); + }; + + const openPort = (port: SandboxPort) => { + // The forwarded port listens on the server's loopback; remote clients need + // the environment's own route to it. + const url = resolveDiscoveredServerUrl(environmentId, `http://127.0.0.1:${port.hostPort}`); + void openLink(url).catch((error: unknown) => { + toastManager.add( + stackedThreadToast({ + type: "error", + title: "Could not open port", + description: error instanceof Error ? error.message : "An error occurred.", + }), + ); + }); + }; + + return ( + + }> + + Sandbox + {sandbox.status !== "running" ? ( + + {SANDBOX_STATUS_LABELS[sandbox.status]} + + ) : null} + + + + {SANDBOX_STATUS_LABELS[sandbox.status]} + {sandbox.status === "error" && sandbox.error ? ( +

{sandbox.error}

+ ) : null} +
+ {sandbox.ports.length > 0 ? ( + + Ports + {sandbox.ports.map((port) => ( + openPort(port)}> + + :{port.containerPort} → 127.0.0.1:{port.hostPort} + + + ))} + + ) : null} + + void runAction("stop")} + > + + Stop sandbox + + void runAction("remove")}> + + Remove sandbox + +
+
+ ); +} diff --git a/apps/web/src/components/chat/WorktreeSetupCard.tsx b/apps/web/src/components/chat/WorktreeSetupCard.tsx index 0d0a0bc1b415b..ad4119f24b478 100644 --- a/apps/web/src/components/chat/WorktreeSetupCard.tsx +++ b/apps/web/src/components/chat/WorktreeSetupCard.tsx @@ -34,6 +34,21 @@ interface WorktreeSetupCardProps { onOpenTerminal: (() => void) | null; } +/** + * Stages that stream command output: the sandbox image build and the setup + * script. The tail box is part of the row's footprint while the stage runs + * (and after it failed, so the last lines explain the failure). It mounts + * with the first output line at its full fixed height, so the card grows + * once instead of with each line. A stage that ends before printing + * anything never flashes an empty box. + */ +function showsStageTail(stage: WorktreeSetupStage): boolean { + return ( + (stage.id === "sandbox" || stage.id === "setup-script") && + (stage.status === "failed" || (stage.status === "running" && stage.tail.length > 0)) + ); +} + function stageElapsedMs(stage: WorktreeSetupStage, nowMs: number): number | null { if (!stage.startedAt) return null; const start = Date.parse(stage.startedAt); @@ -361,15 +376,6 @@ export function WorktreeSetupCard({ // that slot when the agent takes over). The card only brings its own // header for a failed or cancelled setup that has no working row above it. const showHeader = !embedded && !running && snapshot.phase !== "done"; - // The tail box is part of the script row's footprint while the script runs - // (and after it failed, so the last lines explain the failure). It mounts - // with the first output line at its full fixed height, so the card grows - // once instead of with each line. A script that ends before printing - // anything never flashes an empty box. - const showTail = - setupStage !== undefined && - (setupStage.status === "failed" || - (setupStage.status === "running" && setupStage.tail.length > 0)); return (
@@ -385,7 +391,7 @@ export function WorktreeSetupCard({ nowMs={nowMs} scriptName={snapshot.setupScript?.name ?? null} /> - {stage.id === "setup-script" && showTail ? ( + {showsStageTail(stage) ? ( ) : null} diff --git a/apps/web/src/composerDraftStore.ts b/apps/web/src/composerDraftStore.ts index f3ad5f9aecf99..e61138ec4b803 100644 --- a/apps/web/src/composerDraftStore.ts +++ b/apps/web/src/composerDraftStore.ts @@ -88,7 +88,9 @@ const isPreviewAnnotationPayload = Schema.is(PreviewAnnotationPayloadSchema); export const COMPOSER_DRAFT_STORAGE_KEY = "t3code:composer-drafts:v1"; const COMPOSER_DRAFT_STORAGE_VERSION = 9; -const DraftThreadEnvModeSchema = Schema.Literals(["local", "worktree"]); +// Mirrors `EnvMode` in BranchToolbar.logic.ts. "sandbox" is a new worktree +// that runs in a Docker sandbox. +const DraftThreadEnvModeSchema = Schema.Literals(["local", "worktree", "sandbox"]); export type DraftThreadEnvMode = typeof DraftThreadEnvModeSchema.Type; export const DraftId = Schema.String.pipe(Schema.brand("DraftId")); @@ -1436,7 +1438,7 @@ function normalizeDraftThreadEnvMode( value: unknown, fallbackWorktreePath: string | null, ): DraftThreadEnvMode { - if (value === "local" || value === "worktree") { + if (value === "local" || value === "worktree" || value === "sandbox") { return value; } return fallbackWorktreePath ? "worktree" : "local"; diff --git a/apps/web/src/lib/chatThreadActions.ts b/apps/web/src/lib/chatThreadActions.ts index c14a26d03d1c0..765cd2317072e 100644 --- a/apps/web/src/lib/chatThreadActions.ts +++ b/apps/web/src/lib/chatThreadActions.ts @@ -41,7 +41,7 @@ export function resolveNewDraftStartFromOrigin(input: { envMode: DraftThreadEnvMode; newWorktreesStartFromOrigin: boolean; }): boolean { - return input.envMode === "worktree" && input.newWorktreesStartFromOrigin; + return input.envMode !== "local" && input.newWorktreesStartFromOrigin; } export function resolveNewThreadModelSelectionOverride(input: { diff --git a/docs/README.md b/docs/README.md index dd59f4417bbb4..003ddb1c78f2c 100644 --- a/docs/README.md +++ b/docs/README.md @@ -8,6 +8,7 @@ - [Permission modes](./user/permission-modes.md) - [Terminal history](./user/terminal.md) - [Source control](./user/source-control.md) +- [Sandboxes](./user/sandboxes.md) - [Project settings](./user/project-settings.md) - [Appearance and themes](./user/appearance.md) - [Keyboard shortcuts](./user/keybindings.md) @@ -36,6 +37,7 @@ source alone does not explain. Most code changes do not need an internal documen - [Glossary](./internals/glossary.md) - [Connection runtime](./internals/connection-runtime.md) - [Providers](./internals/providers.md) +- [Sandboxes](./internals/sandboxes.md) - [Pull request file revisions](./internals/pull-request-file-revisions.md) - [Model classification](./internals/model-manifest.md) - [Remote environments](./internals/remote.md) diff --git a/docs/internals/sandboxes.md b/docs/internals/sandboxes.md new file mode 100644 index 0000000000000..74e2af25d2214 --- /dev/null +++ b/docs/internals/sandboxes.md @@ -0,0 +1,63 @@ +# Sandboxes + +A sandbox is one long-running Docker container per worktree. See +[`SandboxService`](../../apps/server/src/sandbox/SandboxService.ts) and the +[user guide](../user/sandboxes.md). + +## The provider CLI runs inside + +The point of a sandbox is separate ports and services, which only works if the commands an agent +runs share the container's network. Providers have no reliable hook to redirect their shell +commands, so the whole CLI runs in the container: Claude through the SDK's +`spawnClaudeCodeProcess`, Codex by wrapping the app-server command, and terminals by opening +`bash` with `docker exec -it`. The setup script runs in a terminal, so it follows. Other adapters +fail in `ProviderSessionManager` rather than run on the host unnoticed. + +A process runs where it was opened, so a shared provider session (Codex serves every thread of an +instance from one app-server) is scoped per sandbox. The Orchestrator picks the session id from the +thread's current worktree each time a run starts, because a launch records one before the +worktree and sandbox exist. When a sandbox stops or is removed, `ProviderSessionManager` releases +the sessions that ran in it, so the next turn opens a fresh one and restarts the container. + +The image installs Claude Code and Codex at the host's versions. Host binaries can be macOS +builds, so they are never mounted. + +## Same paths inside and out + +The worktree, the repository's git dir, `~/.claude`, `~/.codex`, `~/.gitconfig`, the attachments +folder, and the project checkout (read-only, for setup scripts) mount at their host paths, and the image user has the host's uid, gid, and home +path. T3 keeps reading worktree files, Claude session files, and git state on the host without any +path translation. `~/.claude.json` is copied in, not mounted, because Claude replaces it by rename, +which fails on a bind-mounted file. + +## One relay, no published ports + +Container IPs are not routable on Docker Desktop, and a server bound to `127.0.0.1` is not +reachable from a Linux bridge network. [`SandboxTunnel`](../../apps/server/src/sandbox/SandboxTunnel.ts) +avoids both: a Node relay runs under `docker exec -i` and multiplexes TCP over its stdio. It +forwards every port that starts listening in the container to a host loopback port, and listens +on T3's own port inside the container so the unchanged `127.0.0.1` MCP URL reaches the host. + +## Killing `docker exec` kills nothing + +Killing a `docker exec` client leaves its process running in the container. Every sandboxed +command starts through a launcher that records its PID, and each spawn site calls `release` when +its process exits or is killed. Each exec leads its own session, so `release` kills the whole +session, including children whose parent already exited. The first use after a server restart +kills everything an earlier server process left behind. + +## Codex's own sandbox is off + +Codex's bubblewrap sandbox cannot create namespaces in an unprivileged container. Sandboxed turns +send `dangerFullAccess` and keep the runtime mode's approval policy. + +## Fail closed + +A worktree is registered and saved as sandboxed before the image build, and stays registered when +provisioning fails, so a terminal or turn waits or fails instead of running on the host. A +sandboxed worktree whose container is missing gets a new one. Containers carry labels with their +worktree, CLI versions, and an owner hash of the server's state directory, so a lost or unreadable +list is rebuilt from the containers this server owns. Each sandboxed worktree also keeps its record +in `t3code-sandbox.json` in its git admin folder, so a lookup can rebuild the sandbox from the +worktree itself even when both the list and its container are gone. Entries for deleted worktrees +are dropped at startup. diff --git a/docs/user/sandboxes.md b/docs/user/sandboxes.md new file mode 100644 index 0000000000000..8b349826d6164 --- /dev/null +++ b/docs/user/sandboxes.md @@ -0,0 +1,45 @@ +# Sandboxes + +A sandbox is a new worktree that runs in its own Docker container. The agent, the thread's +terminals, and the project's setup script all run inside it. Each sandbox has its own ports, +services, and installed tools, so two threads can both run an app on port 3000, or use different +database data and migrations, at the same time. + +The worktree's files stay on your machine. Diffs, checkpoints, source control, and your editor +work as they do for any worktree. + +## Start a sandbox + +Choose **New sandbox** where you would choose **New worktree** for a new thread. The first sandbox +builds an image, which takes a few minutes. Later sandboxes start in seconds. Agents can also start +one with `sandbox: true` in a worktree launch. + +You need Docker on a Linux or macOS machine running T3 Code. Claude and Codex can run in a sandbox. +Other providers report an error in a sandboxed thread. + +## What is inside + +The image is Debian with Node 24, git, and the same Claude Code and Codex versions as your machine. +Your Claude and Codex settings and logins are shared with the sandbox, along with your git +identity. The agent can use `sudo` to install anything else, for example +`sudo apt-get install postgresql`. Services and data outside the worktree stay inside that sandbox. + +On macOS, Claude keeps its login in the Keychain, which a container cannot read. Run +`claude setup-token` and add the token as `CLAUDE_CODE_OAUTH_TOKEN` to the Claude provider's +environment variables. + +In a sandbox, Codex does not use its own command sandbox; the container is the boundary. +Approval prompts still follow the thread's permission mode. + +## Previews + +When an app listens on a port inside the sandbox, T3 Code forwards it to a port on your machine +and lists it in the preview panel as `sandbox :3000`. The forwarded port stays the same across +restarts when it is free. + +## Stop or remove + +A sandbox keeps running until you stop it. A stopped sandbox starts again the next time the agent +or a terminal needs it. Removing a sandbox deletes the container and everything in it outside the +worktree; later work in that worktree runs on your machine. Deleting the worktree removes its +sandbox. diff --git a/packages/client-runtime/src/operations/commands.ts b/packages/client-runtime/src/operations/commands.ts index c0cb8e67504c9..c64f1cbb402fa 100644 --- a/packages/client-runtime/src/operations/commands.ts +++ b/packages/client-runtime/src/operations/commands.ts @@ -158,6 +158,8 @@ interface StartThreadBootstrap { readonly baseBranch: string; readonly branch?: string; readonly startFromOrigin?: boolean; + /** Run the new worktree in a Docker sandbox. */ + readonly sandbox?: boolean; }; readonly runSetupScript?: boolean; } @@ -647,6 +649,7 @@ export const startThreadTurn = Effect.fn("EnvironmentCommands.startThreadTurn")( ...(prepareWorktree.startFromOrigin === undefined ? {} : { startFromOrigin: prepareWorktree.startFromOrigin }), + ...(prepareWorktree.sandbox === true ? { sandbox: true } : {}), } : bootstrap?.worktreePath ? { diff --git a/packages/client-runtime/src/rpc/client.ts b/packages/client-runtime/src/rpc/client.ts index 4ce45cf3ff1b9..f42ca6a1a6721 100644 --- a/packages/client-runtime/src/rpc/client.ts +++ b/packages/client-runtime/src/rpc/client.ts @@ -64,6 +64,7 @@ export type EnvironmentSubscriptionRpcTag = | typeof WS_METHODS.previewAutomationConnect | typeof WS_METHODS.subscribeVcsStatus | typeof WS_METHODS.subscribeWorktreeSetup + | typeof WS_METHODS.subscribeSandboxes | typeof WS_METHODS.subscribeProjectClones | typeof WS_METHODS.terminalAttach; diff --git a/packages/client-runtime/src/state/vcs.ts b/packages/client-runtime/src/state/vcs.ts index c5dee0f752804..eb4176bc00b1a 100644 --- a/packages/client-runtime/src/state/vcs.ts +++ b/packages/client-runtime/src/state/vcs.ts @@ -1,5 +1,6 @@ import { type EnvironmentId, + type SandboxSummary, type VcsListRefsInput, type VcsListRefsResult, type VcsStatusResult, @@ -327,6 +328,21 @@ export function createVcsEnvironmentAtoms( label: "environment-data:vcs:cancel-worktree-setup", tag: WS_METHODS.worktreeSetupCancel, }), + // Docker sandboxes on the environment. A thread is sandboxed when its + // worktree path matches one; `findSandboxForWorktree` does the lookup. + sandboxes: createEnvironmentRpcSubscriptionAtomFamily(runtime, { + label: "environment-data:vcs:sandboxes", + tag: WS_METHODS.subscribeSandboxes, + idleTtlMs: VCS_STATUS_IDLE_TTL_MS, + }), + stopSandbox: createEnvironmentRpcCommand(runtime, { + label: "environment-data:vcs:stop-sandbox", + tag: WS_METHODS.sandboxStop, + }), + removeSandbox: createEnvironmentRpcCommand(runtime, { + label: "environment-data:vcs:remove-sandbox", + tag: WS_METHODS.sandboxRemove, + }), removeWorktree: createEnvironmentRpcCommand(runtime, { label: "environment-data:vcs:remove-worktree", tag: WS_METHODS.vcsRemoveWorktree, @@ -358,6 +374,15 @@ export function createVcsEnvironmentAtoms( }; } +/** The sandbox that runs a thread's worktree, if any. */ +export function findSandboxForWorktree( + sandboxes: ReadonlyArray | undefined, + worktreePath: string | null | undefined, +): SandboxSummary | null { + if (!sandboxes || !worktreePath) return null; + return sandboxes.find((sandbox) => sandbox.worktreePath === worktreePath) ?? null; +} + export * from "./gitActions.ts"; export * from "./vcsAction.ts"; export * from "./vcsRef.ts"; diff --git a/packages/contracts/src/index.ts b/packages/contracts/src/index.ts index 8690bb1b2390b..188e18f98b751 100644 --- a/packages/contracts/src/index.ts +++ b/packages/contracts/src/index.ts @@ -60,3 +60,4 @@ export * from "./worktreeMcp.ts"; export * from "./resourceTelemetry.ts"; export * from "./rpc.ts"; export * from "./worktreeSetup.ts"; +export * from "./sandbox.ts"; diff --git a/packages/contracts/src/orchestrationV2.ts b/packages/contracts/src/orchestrationV2.ts index 6004ab119917d..a71aa87a1f2da 100644 --- a/packages/contracts/src/orchestrationV2.ts +++ b/packages/contracts/src/orchestrationV2.ts @@ -2976,6 +2976,8 @@ export const OrchestrationV2ThreadLaunchWorkspaceStrategy = Schema.Union([ baseRef: TrimmedNonEmptyString, branch: Schema.optional(TrimmedNonEmptyString), startFromOrigin: Schema.optional(Schema.Boolean), + /** Run the new worktree's agents, terminals, and setup script in a Docker sandbox. */ + sandbox: Schema.optional(Schema.Boolean), }), ]); export type OrchestrationV2ThreadLaunchWorkspaceStrategy = diff --git a/packages/contracts/src/rpc.ts b/packages/contracts/src/rpc.ts index ed6df13a69471..e52572625356f 100644 --- a/packages/contracts/src/rpc.ts +++ b/packages/contracts/src/rpc.ts @@ -98,6 +98,7 @@ import { WorktreeSetupStreamEvent, WorktreeSetupSubscribeInput, } from "./worktreeSetup.ts"; +import { SandboxListStreamEvent, SandboxRequestError, SandboxWorktreeInput } from "./sandbox.ts"; import { GitActionProgressEvent, VcsSwitchRefInput, @@ -522,6 +523,9 @@ export const WS_METHODS = { subscribeVcsStatus: "subscribeVcsStatus", subscribeWorktreeSetup: "subscribeWorktreeSetup", worktreeSetupCancel: "worktreeSetup.cancel", + subscribeSandboxes: "subscribeSandboxes", + sandboxStop: "sandbox.stop", + sandboxRemove: "sandbox.remove", subscribeTerminalEvents: "subscribeTerminalEvents", subscribeTerminalMetadata: "subscribeTerminalMetadata", subscribePreviewEvents: "subscribePreviewEvents", @@ -1254,6 +1258,25 @@ const WsSubscribeWorktreeSetupRpc = Rpc.make(WS_METHODS.subscribeWorktreeSetup, stream: true, }); +const WsSubscribeSandboxesRpc = Rpc.make(WS_METHODS.subscribeSandboxes, { + payload: Schema.Struct({}), + success: SandboxListStreamEvent, + error: EnvironmentAuthorizationError, + stream: true, +}); + +const WsSandboxStopRpc = Rpc.make(WS_METHODS.sandboxStop, { + payload: SandboxWorktreeInput, + success: Schema.Void, + error: Schema.Union([SandboxRequestError, EnvironmentAuthorizationError]), +}); + +const WsSandboxRemoveRpc = Rpc.make(WS_METHODS.sandboxRemove, { + payload: SandboxWorktreeInput, + success: Schema.Void, + error: Schema.Union([SandboxRequestError, EnvironmentAuthorizationError]), +}); + const WsWorktreeSetupCancelRpc = Rpc.make(WS_METHODS.worktreeSetupCancel, { payload: WorktreeSetupCancelInput, success: WorktreeSetupCancelResult, @@ -1797,6 +1820,9 @@ export const WsRpcGroup = RpcGroup.make( WsSubscribeVcsStatusRpc, WsSubscribeWorktreeSetupRpc, WsWorktreeSetupCancelRpc, + WsSubscribeSandboxesRpc, + WsSandboxStopRpc, + WsSandboxRemoveRpc, WsVcsPullRpc, WsVcsRefreshStatusRpc, WsGitRunStackedActionRpc, diff --git a/packages/contracts/src/sandbox.ts b/packages/contracts/src/sandbox.ts new file mode 100644 index 0000000000000..f422d82ce2055 --- /dev/null +++ b/packages/contracts/src/sandbox.ts @@ -0,0 +1,56 @@ +import * as Schema from "effect/Schema"; + +import { TrimmedNonEmptyString } from "./baseSchemas.ts"; + +/** + * A Docker sandbox belongs to one worktree. The server runs that worktree's + * agents, terminals, and setup script inside the sandbox's container, so each + * sandbox has its own ports, services, and files outside the worktree. Clients + * match a thread to its sandbox by the thread's worktree path. + */ +export const SandboxStatus = Schema.Literals(["starting", "running", "stopped", "error"]); +export type SandboxStatus = typeof SandboxStatus.Type; + +const PortNumber = Schema.Int.check(Schema.isGreaterThan(0)).check(Schema.isLessThan(65536)); + +/** A port an app listens on inside the sandbox, forwarded to the server host's loopback. */ +export const SandboxPort = Schema.Struct({ + containerPort: PortNumber, + hostPort: PortNumber, +}); +export type SandboxPort = typeof SandboxPort.Type; + +export const SandboxSummary = Schema.Struct({ + worktreePath: TrimmedNonEmptyString, + containerName: TrimmedNonEmptyString, + image: TrimmedNonEmptyString, + status: SandboxStatus, + ports: Schema.Array(SandboxPort), + /** Human readable reason when status is error. */ + error: Schema.NullOr(Schema.String), +}); +export type SandboxSummary = typeof SandboxSummary.Type; + +/** The full sandbox list. Sent first, then after every change. */ +export const SandboxListStreamEvent = Schema.Struct({ + sandboxes: Schema.Array(SandboxSummary), +}); +export type SandboxListStreamEvent = typeof SandboxListStreamEvent.Type; + +export const SandboxWorktreeInput = Schema.Struct({ + worktreePath: TrimmedNonEmptyString, +}); +export type SandboxWorktreeInput = typeof SandboxWorktreeInput.Type; + +export class SandboxRequestError extends Schema.TaggedError()( + "SandboxRequestError", + { + operation: Schema.Literals(["stop", "remove"]), + worktreePath: Schema.String, + detail: Schema.String, + }, +) { + override get message(): string { + return `Could not ${this.operation} the sandbox for ${this.worktreePath}: ${this.detail}`; + } +} diff --git a/packages/contracts/src/server.ts b/packages/contracts/src/server.ts index e152a3dbf0726..d6de5185d9e32 100644 --- a/packages/contracts/src/server.ts +++ b/packages/contracts/src/server.ts @@ -629,6 +629,11 @@ export const ServerConfig = Schema.Struct({ shellRevealInFileManagerKind: Schema.optionalKey(FileManagerRevealKind), /** Whether thread subscriptions can emit an opt-in catch-up completion marker. */ threadResumeCompletionMarker: Schema.optionalKey(Schema.Boolean), + /** + * Whether this server can run new worktrees in Docker sandboxes (Linux and + * macOS hosts). Docker itself is checked when a sandbox starts. + */ + sandboxes: Schema.optionalKey(Schema.Boolean), /** * Whether thread detail reads accept a turn window (`turnLimit`/ * `beforeCursor`) and return `page` metadata. Clients must not send window diff --git a/packages/contracts/src/worktreeSetup.ts b/packages/contracts/src/worktreeSetup.ts index 203cfd6a4929b..8f1fb77889e1d 100644 --- a/packages/contracts/src/worktreeSetup.ts +++ b/packages/contracts/src/worktreeSetup.ts @@ -16,6 +16,7 @@ export const WorktreeSetupStageId = Schema.Literals([ "fetch", "checkout", "submodules", + "sandbox", "setup-script", "agent", ]); @@ -104,6 +105,7 @@ export const WORKTREE_SETUP_STAGE_ORDER: ReadonlyArray = [ "fetch", "checkout", "submodules", + "sandbox", "setup-script", "agent", ]; @@ -116,6 +118,8 @@ export function worktreeSetupStageLabel(id: WorktreeSetupStageId): string { return "Check out files"; case "submodules": return "Init submodules"; + case "sandbox": + return "Start sandbox"; case "setup-script": return "Run setup script"; case "agent":