@grackle-ai/web-components 0.108.4 → 0.110.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grackle-ai/web-components",
-  "version": "0.108.4",
+  "version": "0.110.1",
   "description": "Presentational React component library for the Grackle web UI",
   "license": "MIT",
   "repository": {
@@ -40,7 +40,7 @@
     "remark-gfm": "^4.0.0",
     "lucide-react": "~0.474.0",
     "react-router": "^7.0.0",
-    "@grackle-ai/common": "0.108.4"
+    "@grackle-ai/common": "0.110.1"
   },
   "devDependencies": {
     "@rushstack/heft": "1.2.7",

package/rush-logs/web-components._phase_build.cache.log

@@ -1,4 +1,4 @@
 Build cache hit.
-Cache key: 116390ecbdd70f01703a1a6dbb1dd805d1a6f702
+Cache key: 3629cc83b3804ac8bcea27905e83162210fb5dd6
 Clearing cached folders: dist, storybook-static, .rush/temp/operation/_phase_build
 Successfully restored output from the build cache.

package/rush-logs/web-components._phase_build.log

@@ -10,9 +10,9 @@ transforming...
 ✓ 2574 modules transformed.
 rendering chunks...
 computing gzip size...
-dist/index.css    156.05 kB │ gzip:  20.36 kB
-dist/index.js   1,373.42 kB │ gzip: 351.63 kB
-✓ built in 6.72s
+dist/index.css    156.09 kB │ gzip:  20.37 kB
+dist/index.js   1,377.68 kB │ gzip: 352.31 kB
+✓ built in 5.19s
 [build:vite-build] Vite build completed.
- ---- build finished (96.180s) ---- 
--------------------- Finished (96.184s) --------------------
+ ---- build finished (73.056s) ---- 
+-------------------- Finished (73.061s) --------------------

package/rush-logs/web-components._phase_test.cache.log

@@ -1,4 +1,4 @@
 Build cache hit.
-Cache key: ddb88821de1bbf09dbde855d6172b545d74acf2a
+Cache key: f2b8b611fc00c7b912256986db4cc966d6560387
 Clearing cached folders: .rush/temp/operation/_phase_test
 Successfully restored output from the build cache.

package/rush-logs/web-components._phase_test.log

@@ -5,26 +5,26 @@ The provided list of phases does not contain all phase dependencies. You may nee
 
  RUN  v3.2.4 /home/runner/work/grackle/grackle/packages/web-components
 
- ✓ src/utils/sessionEvents.test.ts (14 tests) 52ms
- ✓ src/utils/eventContent.test.ts (38 tests) 120ms
- ✓ src/utils/dashboard.test.ts (4 tests) 17ms
- ✓ src/utils/route-config.test.ts (23 tests) 25ms
- ✓ src/utils/scrollUtils.test.ts (11 tests) 23ms
- ✓ src/utils/breadcrumbs.test.ts (18 tests) 52ms
- ✓ src/components/tools/classifyTool.test.ts (6 tests) 21ms
- ✓ src/components/tools/toolCardHelpers.test.ts (10 tests) 18ms
+ ✓ src/utils/sessionEvents.test.ts (14 tests) 55ms
+ ✓ src/utils/eventContent.test.ts (38 tests) 103ms
+ ✓ src/utils/dashboard.test.ts (4 tests) 25ms
+ ✓ src/utils/route-config.test.ts (23 tests) 72ms
+ ✓ src/utils/breadcrumbs.test.ts (18 tests) 24ms
+ ✓ src/utils/scrollUtils.test.ts (11 tests) 24ms
+ ✓ src/components/tools/classifyTool.test.ts (6 tests) 37ms
+ ✓ src/components/tools/toolCardHelpers.test.ts (10 tests) 17ms
  ✓ src/components/display/extractText.test.tsx (8 tests) 12ms
- ✓ src/components/editable/useEditableField.test.tsx (17 tests) 144ms
- ✓ src/hooks/useEventSelection.test.ts (13 tests) 69ms
- ✓ src/components/notifications/UpdateBanner.test.tsx (4 tests) 130ms
+ ✓ src/components/editable/useEditableField.test.tsx (17 tests) 181ms
+ ✓ src/hooks/useEventSelection.test.ts (13 tests) 182ms
+ ✓ src/components/notifications/UpdateBanner.test.tsx (4 tests) 125ms
 
  Test Files  12 passed (12)
       Tests  166 passed (166)
-   Start at  07:58:51
-   Duration  13.47s (transform 2.63s, setup 0ms, collect 16.01s, tests 682ms, environment 6.83s, prepare 3.98s)
+   Start at  20:39:06
+   Duration  13.92s (transform 2.79s, setup 0ms, collect 15.06s, tests 856ms, environment 6.97s, prepare 5.20s)
 
 [test:vitest] Vitest completed.
-[test:storybook-test] Starting Storybook static server on port 33833...
+[test:storybook-test] Starting Storybook static server on port 43017...
 [test:storybook-test] Storybook server ready. Running interaction tests...
 jest-haste-map: duplicate manual mock found: adapter-manager
   The following files share their name; please delete one of them:
@@ -117,5 +117,5 @@ jest-haste-map: duplicate manual mock found: utils/network
     * <rootDir>/packages/server/src/__mocks__/utils/network.ts
 
 [test:storybook-test] Storybook interaction tests completed.
- ---- test finished (112.215s) ---- 
--------------------- Finished (112.221s) --------------------
+ ---- test finished (112.648s) ---- 
+-------------------- Finished (112.652s) --------------------

package/src/components/layout/AppNav.module.scss

@@ -80,3 +80,9 @@
   color: var(--text-primary);
   font-weight: var(--font-weight-medium);
 }
+
+// Pins this tab (and any after it) to the right edge by absorbing the free
+// space to its left. Inert on mobile, where the nav scrolls horizontally.
+.tabEnd {
+  margin-left: auto;
+}

package/src/components/layout/AppNav.stories.tsx

@@ -66,6 +66,53 @@ export const AllTabsExplicit: Story = {
   },
 };
 
+/**
+ * Settings is pinned to the right edge even when the incoming tab list places it
+ * mid-list (as `buildTabs` does: core tabs, including Settings, come before
+ * orchestration and knowledge tabs). The component reorders end-aligned tabs last.
+ */
+export const SettingsPinnedRight: Story = {
+  // Fullscreen so the nav fills the viewport and the auto margin has free space
+  // to absorb (otherwise margin-left: auto would resolve to 0).
+  parameters: { layout: "fullscreen" },
+  args: {
+    tabs: [
+      { view: "dashboard", label: "Dashboard", icon: <Home size={ICON_LG} />, route: HOME_URL, testId: "sidebar-tab-dashboard" },
+      { view: "chat", label: "Chat", icon: <MessageSquare size={ICON_LG} />, route: CHAT_URL, testId: "sidebar-tab-chat" },
+      { view: "environments", label: "Environments", icon: <Monitor size={ICON_LG} />, route: ENVIRONMENTS_URL, testId: "sidebar-tab-environments" },
+      { view: "settings", label: "Settings", icon: <Settings size={ICON_LG} />, route: SETTINGS_CREDENTIALS_URL, testId: "sidebar-tab-settings", align: "end" },
+      { view: "tasks", label: "Tasks", icon: <ClipboardList size={ICON_LG} />, route: TASKS_URL, testId: "sidebar-tab-tasks" },
+      { view: "findings", label: "Findings", icon: <Search size={ICON_LG} />, route: FINDINGS_URL, testId: "sidebar-tab-findings" },
+      { view: "knowledge", label: "Knowledge", icon: <Brain size={ICON_LG} />, route: KNOWLEDGE_URL, testId: "sidebar-tab-knowledge" },
+    ],
+  },
+  play: async ({ canvas }) => {
+    const renderedTabs = canvas.getAllByRole("tab");
+    // Despite Settings being 4th in the input, it must render last (rightmost).
+    const settingsTab = renderedTabs[renderedTabs.length - 1];
+    await expect(settingsTab).toHaveAccessibleName(/Settings/);
+
+    // The end-alignment lives on the flex item (the Tooltip wrapper around the
+    // button), not the button itself. Verify margin-left: auto resolves to a
+    // positive used value there, so Settings is actually pushed to the right edge.
+    const settingsFlexItem = settingsTab.parentElement;
+    if (!settingsFlexItem) {
+      throw new Error("expected the Settings tab to have a flex-item wrapper");
+    }
+    const settingsMarginLeft = Number.parseFloat(globalThis.getComputedStyle(settingsFlexItem).marginLeft);
+    await expect(settingsMarginLeft).toBeGreaterThan(0);
+
+    // The neighbor immediately before it (Knowledge) must NOT have an auto
+    // margin, confirming the spacer is applied only to the pinned tab.
+    const neighborFlexItem = renderedTabs[renderedTabs.length - 2].parentElement;
+    if (!neighborFlexItem) {
+      throw new Error("expected the neighbor tab to have a flex-item wrapper");
+    }
+    const neighborMarginLeft = Number.parseFloat(globalThis.getComputedStyle(neighborFlexItem).marginLeft);
+    await expect(neighborMarginLeft).toBe(0);
+  },
+};
+
 /** Arrow keys navigate between tabs horizontally. */
 export const KeyboardNavigation: Story = {
   play: async ({ canvas }) => {

package/src/components/layout/AppNav.tsx

@@ -1,4 +1,4 @@
-import { useCallback, useRef, type JSX, type KeyboardEvent, type ReactNode } from "react";
+import { useCallback, useMemo, useRef, type JSX, type KeyboardEvent, type ReactNode } from "react";
 import { useLocation } from "react-router";
 import { Brain, ClipboardList, Home, MessageSquare, Monitor, Search, Settings } from "lucide-react";
 import { CHAT_URL, ENVIRONMENTS_URL, FINDINGS_URL, HOME_URL, KNOWLEDGE_URL, SETTINGS_URL, SETTINGS_CREDENTIALS_URL, TASKS_URL, useAppNavigate } from "../../utils/navigation.js";
@@ -21,6 +21,8 @@ export interface AppTab {
   route: string;
   /** data-testid suffix. */
   testId: string;
+  /** Horizontal alignment within the nav bar. `"end"` pins the tab to the right edge. */
+  align?: "end";
 }
 
 /** Ordered list of all app navigation tabs. Exported for plugin registry use. */
@@ -31,7 +33,7 @@ export const TABS: AppTab[] = [
   { view: "environments", label: "Environments", icon: <Monitor size={ICON_LG} />, route: ENVIRONMENTS_URL, testId: "sidebar-tab-environments" },
   { view: "knowledge", label: "Knowledge", icon: <Brain size={ICON_LG} />, route: KNOWLEDGE_URL, testId: "sidebar-tab-knowledge" },
   { view: "findings", label: "Findings", icon: <Search size={ICON_LG} />, route: FINDINGS_URL, testId: "sidebar-tab-findings" },
-  { view: "settings", label: "Settings", icon: <Settings size={ICON_LG} />, route: SETTINGS_CREDENTIALS_URL, testId: "sidebar-tab-settings" },
+  { view: "settings", label: "Settings", icon: <Settings size={ICON_LG} />, route: SETTINGS_CREDENTIALS_URL, testId: "sidebar-tab-settings", align: "end" },
 ];
 
 /** Derive the active application view from a URL pathname. */
@@ -65,6 +67,17 @@ export function AppNav({ tabs = TABS }: { tabs?: AppTab[] }): JSX.Element {
 
   const activeView = getActiveView(location.pathname);
 
+  // Render end-aligned tabs (e.g. Settings) last regardless of the incoming order,
+  // so they stay pinned to the right edge no matter which plugins contribute tabs.
+  const orderedTabs = useMemo(
+    () => [
+      ...tabs.filter((t) => t.align !== "end"),
+      ...tabs.filter((t) => t.align === "end"),
+    ],
+    [tabs],
+  );
+  const firstEndAlignedView = orderedTabs.find((t) => t.align === "end")?.view;
+
   const handleClick = useCallback((tab: AppTab) => {
     navigate(tab.route);
   }, [navigate]);
@@ -75,28 +88,28 @@ export function AppNav({ tabs = TABS }: { tabs?: AppTab[] }): JSX.Element {
       return;
     }
     const focusedIndex = Array.from(buttons).findIndex((b) => b === document.activeElement);
-    const currentIndex = focusedIndex >= 0 ? focusedIndex : tabs.findIndex((t) => t.view === activeView);
+    const currentIndex = focusedIndex >= 0 ? focusedIndex : orderedTabs.findIndex((t) => t.view === activeView);
     let nextIndex = currentIndex;
 
     if (e.key === "ArrowRight" || e.key === "j" || e.key === "J") {
       e.preventDefault();
-      nextIndex = (currentIndex + 1) % tabs.length;
+      nextIndex = (currentIndex + 1) % orderedTabs.length;
     } else if (e.key === "ArrowLeft" || e.key === "k" || e.key === "K") {
       e.preventDefault();
-      nextIndex = (currentIndex - 1 + tabs.length) % tabs.length;
+      nextIndex = (currentIndex - 1 + orderedTabs.length) % orderedTabs.length;
     } else if (e.key === "Home") {
       e.preventDefault();
       nextIndex = 0;
     } else if (e.key === "End") {
       e.preventDefault();
-      nextIndex = tabs.length - 1;
+      nextIndex = orderedTabs.length - 1;
     } else {
       return;
     }
 
-    navigate(tabs[nextIndex].route);
+    navigate(orderedTabs[nextIndex].route);
     buttons[nextIndex]?.focus(); // eslint-disable-line @typescript-eslint/no-unnecessary-condition -- index may be out of bounds
-  }, [activeView, navigate, tabs]);
+  }, [activeView, navigate, orderedTabs]);
 
   return (
     <nav
@@ -108,10 +121,11 @@ export function AppNav({ tabs = TABS }: { tabs?: AppTab[] }): JSX.Element {
       onKeyDown={handleKeyDown}
       data-testid="sidebar-nav"
     >
-      {tabs.map((tab) => {
+      {orderedTabs.map((tab) => {
         const isActive = tab.view === activeView;
+        const isFirstEndAligned = tab.view === firstEndAlignedView;
         return (
-          <Tooltip key={tab.view} text={tab.label} placement="bottom">
+          <Tooltip key={tab.view} text={tab.label} placement="bottom" className={isFirstEndAligned ? styles.tabEnd : undefined}>
             <button
               role="tab"
               type="button"

package/src/components/panels/EnvironmentEditPanel.stories.tsx

@@ -18,6 +18,9 @@ const meta: Meta<typeof EnvironmentEditPanel> = {
     codespaceListError: "",
     codespaceCreating: false,
     onCreateCodespace: fn(),
+    onListDockerContainers: fn(),
+    dockerContainers: [],
+    dockerContainersError: "",
     onShowToast: fn(),
   },
 };
@@ -133,13 +136,96 @@ export const SwitchingAdapterShowsFields: Story = {
     await expect(canvas.getByTestId("env-create-port")).toBeInTheDocument();
     await expect(canvas.getByTestId("env-create-identity")).toBeInTheDocument();
 
-    // Switch to Docker — shows image and repo
+    // Switch to Docker — shows the source toggle plus image and repo (create mode default)
     await userEvent.selectOptions(adapterSelect, "docker");
+    await expect(canvas.getByTestId("env-docker-mode")).toBeInTheDocument();
     await expect(canvas.getByTestId("env-create-image")).toBeInTheDocument();
     await expect(canvas.getByTestId("env-create-repo")).toBeInTheDocument();
   },
 };
 
+/** Docker attach mode lists running containers and requests them when selected. */
+export const DockerAttachLists: Story = {
+  args: {
+    dockerContainers: [
+      { id: "abc123", name: "demo-ext", image: "node:22", state: "running", status: "Up 3 minutes" },
+    ],
+  },
+  play: async ({ canvas, args }) => {
+    const adapterSelect = canvas.getByTestId("env-create-adapter");
+    await userEvent.selectOptions(adapterSelect, "docker");
+
+    // Switch the docker source to "attach" — the container list should be requested
+    const modeSelect = canvas.getByTestId("env-docker-mode");
+    await userEvent.selectOptions(modeSelect, "attach");
+    await expect(args.onListDockerContainers).toHaveBeenCalled();
+
+    // The picker replaces the image/repo fields
+    await expect(canvas.getByTestId("env-docker-container-select")).toBeInTheDocument();
+    await expect(canvas.queryByTestId("env-create-image")).not.toBeInTheDocument();
+  },
+};
+
+/** Selecting a container in attach mode builds an { attach } config on Create. */
+export const DockerAttachCreatesConfig: Story = {
+  args: {
+    dockerContainers: [
+      { id: "abc123", name: "demo-ext", image: "node:22", state: "running", status: "Up 3 minutes" },
+    ],
+  },
+  play: async ({ canvas, args }) => {
+    await userEvent.selectOptions(canvas.getByTestId("env-create-adapter"), "docker");
+    await userEvent.selectOptions(canvas.getByTestId("env-docker-mode"), "attach");
+
+    // Pick the running container; the env name auto-fills from it
+    await userEvent.selectOptions(canvas.getByTestId("env-docker-container-select"), "demo-ext");
+
+    const createButton = canvas.getByTestId("env-create-submit");
+    await expect(createButton).toBeEnabled();
+    await userEvent.click(createButton);
+
+    await expect(args.onAddEnvironment).toHaveBeenCalledWith(
+      "demo-ext",
+      "docker",
+      { attach: "demo-ext" },
+      undefined,
+    );
+  },
+};
+
+/** When docker container listing fails, a manual entry input appears. */
+export const DockerAttachManualEntry: Story = {
+  args: {
+    dockerContainersError: "docker: command not found",
+  },
+  play: async ({ canvas }) => {
+    await userEvent.selectOptions(canvas.getByTestId("env-create-adapter"), "docker");
+    await userEvent.selectOptions(canvas.getByTestId("env-docker-mode"), "attach");
+
+    await expect(canvas.getByTestId("env-docker-container-manual")).toBeInTheDocument();
+    await expect(canvas.queryByTestId("env-docker-container-select")).not.toBeInTheDocument();
+  },
+};
+
+/** When discovery succeeds but finds no running containers, manual entry is still offered. */
+export const DockerAttachEmptyListManualEntry: Story = {
+  args: {
+    dockerContainers: [],
+  },
+  play: async ({ canvas }) => {
+    await userEvent.selectOptions(canvas.getByTestId("env-create-adapter"), "docker");
+    await userEvent.selectOptions(canvas.getByTestId("env-docker-mode"), "attach");
+
+    // No select (nothing to pick), but a manual input is available
+    await expect(canvas.queryByTestId("env-docker-container-select")).not.toBeInTheDocument();
+    const manual = canvas.getByTestId("env-docker-container-manual");
+    await userEvent.type(manual, "demo-ext");
+
+    const createButton = canvas.getByTestId("env-create-submit");
+    await expect(createButton).toBeEnabled();
+  },
+};
+
 /** When codespace listing fails, a manual entry input appears and the select dropdown is hidden. */
 export const CodespaceManualEntry: Story = {
   args: {

package/src/components/panels/EnvironmentEditPanel.tsx

@@ -1,6 +1,6 @@
 import { useState, useCallback, type JSX } from "react";
 import type { ToastVariant } from "../../context/ToastContext.js";
-import type { Environment, Codespace, GitHubAccountData } from "../../hooks/types.js";
+import type { Environment, Codespace, DockerContainer, GitHubAccountData } from "../../hooks/types.js";
 import { ENVIRONMENTS_URL, environmentUrl, useAppNavigate } from "../../utils/navigation.js";
 import { EditableTextField } from "../editable/EditableTextField.js";
 import styles from "./EnvironmentEditPanel.module.scss";
@@ -35,6 +35,12 @@ interface Props {
   codespaceCreating: boolean;
   /** Callback to create a new codespace. */
   onCreateCodespace: (repo: string, machine?: string) => void;
+  /** Callback to list running Docker containers available to attach to. */
+  onListDockerContainers: () => void;
+  /** Running Docker containers available to attach to (docker attach mode). */
+  dockerContainers: DockerContainer[];
+  /** Non-fatal error from listing Docker containers (e.g. docker CLI unavailable). */
+  dockerContainersError: string;
   /** Display a toast notification. */
   onShowToast?: (message: string, variant?: ToastVariant) => void;
 }
@@ -202,7 +208,7 @@ function CodespacePicker({ codespaceName, onCodespaceNameChange, envName, onEnvN
  * - edit: pre-populated form; uses click-to-edit fields that auto-save via
  *         updateEnvironment.
  */
-export function EnvironmentEditPanel({ mode, environmentId, environments, githubAccounts, onAddEnvironment, onUpdateEnvironment, onListCodespaces, codespaces, codespaceError, codespaceListError, codespaceCreating, onCreateCodespace, onShowToast }: Props): JSX.Element {
+export function EnvironmentEditPanel({ mode, environmentId, environments, githubAccounts, onAddEnvironment, onUpdateEnvironment, onListCodespaces, codespaces, codespaceError, codespaceListError, codespaceCreating, onCreateCodespace, onListDockerContainers, dockerContainers, dockerContainersError, onShowToast }: Props): JSX.Element {
   const navigate = useAppNavigate();
 
   const isEdit = mode === "edit";
@@ -222,6 +228,9 @@ export function EnvironmentEditPanel({ mode, environmentId, environments, github
   const [repo, setRepo] = useState("");
   const [codespaceName, setCodespaceName] = useState("");
   const [githubAccountId, setGithubAccountId] = useState("");
+  // Docker: "create" a new container vs "attach" to an existing one (issue #1223).
+  const [dockerMode, setDockerMode] = useState<"create" | "attach">("create");
+  const [attachContainer, setAttachContainer] = useState("");
 
   // ─── Edit mode state ───────────────────────────────
 
@@ -257,17 +266,24 @@ export function EnvironmentEditPanel({ mode, environmentId, environments, github
         config.identityFile = identityFile.trim();
       }
     } else if (adapterType === "docker") {
-      if (image.trim()) {
-        config.image = image.trim();
-      }
-      if (repo.trim()) {
-        config.repo = repo.trim();
+      if (dockerMode === "attach") {
+        // Attach mode: target an existing container; image/repo are ignored.
+        if (attachContainer.trim()) {
+          config.attach = attachContainer.trim();
+        }
+      } else {
+        if (image.trim()) {
+          config.image = image.trim();
+        }
+        if (repo.trim()) {
+          config.repo = repo.trim();
+        }
       }
     } else if (adapterType === "codespace") {
       config.codespaceName = codespaceName.trim();
     }
     return config;
-  }, [adapterType, host, port, user, identityFile, image, repo, codespaceName]);
+  }, [adapterType, host, port, user, identityFile, image, repo, codespaceName, dockerMode, attachContainer]);
 
   const isCreateValid = (): boolean => {
     if (!envName.trim()) {
@@ -279,6 +295,9 @@ export function EnvironmentEditPanel({ mode, environmentId, environments, github
     if (adapterType === "codespace" && !codespaceName.trim()) {
       return false;
     }
+    if (adapterType === "docker" && dockerMode === "attach" && !attachContainer.trim()) {
+      return false;
+    }
     if ((adapterType === "local" || adapterType === "ssh") && !isPortValid(port)) {
       return false;
     }
@@ -533,7 +552,25 @@ export function EnvironmentEditPanel({ mode, environmentId, environments, github
               </>
             )}
 
-            {existingEnv.adapterType === "docker" && (
+            {existingEnv.adapterType === "docker" && config.attach !== undefined && (
+              <div className={styles.section}>
+                <label className={styles.label}>Attach (container)</label>
+                <EditableTextField
+                  value={String(config.attach ?? "")}
+                  onSave={(v) => saveConfigField("attach", v)}
+                  validate={(v) => v.trim() === "" ? "Container name is required" : undefined}
+                  mode="edit"
+                  fieldId="attach"
+                  activeFieldId={activeFieldId}
+                  onActivate={setActiveFieldId}
+                  placeholder="container name or ID"
+                  ariaLabel="Attach container"
+                  data-testid="env-edit-attach"
+                />
+              </div>
+            )}
+
+            {existingEnv.adapterType === "docker" && config.attach === undefined && (
               <>
                 <div className={styles.section}>
                   <label className={styles.label}>Image</label>
@@ -792,33 +829,105 @@ export function EnvironmentEditPanel({ mode, environmentId, environments, github
           {adapterType === "docker" && (
             <>
               <div className={styles.section}>
-                <label className={styles.label} htmlFor="env-create-image">
-                  Image
+                <label className={styles.label} htmlFor="env-docker-mode">
+                  Source
                 </label>
-                <input
-                  id="env-create-image"
-                  type="text"
-                  value={image}
-                  onChange={(e) => setImage(e.target.value)}
-                  placeholder="Image (optional)..."
-                  className={styles.fieldInput}
-                  data-testid="env-create-image"
-                />
-              </div>
-              <div className={styles.section}>
-                <label className={styles.label} htmlFor="env-create-repo">
-                  Repo
-                </label>
-                <input
-                  id="env-create-repo"
-                  type="text"
-                  value={repo}
-                  onChange={(e) => setRepo(e.target.value)}
-                  placeholder="Repo (optional)..."
-                  className={styles.fieldInput}
-                  data-testid="env-create-repo"
-                />
+                <select
+                  id="env-docker-mode"
+                  value={dockerMode}
+                  onChange={(e) => {
+                    const next = e.target.value as "create" | "attach";
+                    setDockerMode(next);
+                    if (next === "attach") {
+                      onListDockerContainers();
+                    }
+                  }}
+                  className={styles.adapterSelect}
+                  data-testid="env-docker-mode"
+                >
+                  <option value="create">Create new container</option>
+                  <option value="attach">Attach to existing container</option>
+                </select>
               </div>
+
+              {dockerMode === "create" ? (
+                <>
+                  <div className={styles.section}>
+                    <label className={styles.label} htmlFor="env-create-image">
+                      Image
+                    </label>
+                    <input
+                      id="env-create-image"
+                      type="text"
+                      value={image}
+                      onChange={(e) => setImage(e.target.value)}
+                      placeholder="Image (optional)..."
+                      className={styles.fieldInput}
+                      data-testid="env-create-image"
+                    />
+                  </div>
+                  <div className={styles.section}>
+                    <label className={styles.label} htmlFor="env-create-repo">
+                      Repo
+                    </label>
+                    <input
+                      id="env-create-repo"
+                      type="text"
+                      value={repo}
+                      onChange={(e) => setRepo(e.target.value)}
+                      placeholder="Repo (optional)..."
+                      className={styles.fieldInput}
+                      data-testid="env-create-repo"
+                    />
+                  </div>
+                </>
+              ) : (
+                <div className={styles.section}>
+                  <label className={styles.label}>Container</label>
+                  {!dockerContainersError && dockerContainers.length > 0 && (
+                    <select
+                      value={attachContainer}
+                      onChange={(e) => {
+                        setAttachContainer(e.target.value);
+                        if (e.target.value && !envName.trim()) {
+                          setEnvName(e.target.value);
+                        }
+                      }}
+                      className={styles.adapterSelect}
+                      data-testid="env-docker-container-select"
+                    >
+                      <option value="">Select a container...</option>
+                      {dockerContainers.map((c) => (
+                        <option key={c.id} value={c.name}>
+                          {c.name} ({c.image}) {c.status}
+                        </option>
+                      ))}
+                    </select>
+                  )}
+                  {/* Manual entry fallback: shown on listing error OR when no running
+                      containers were found, so the user is never stuck with an empty picker. */}
+                  {(dockerContainersError || dockerContainers.length === 0) && (
+                    <>
+                      {dockerContainersError
+                        ? <span className={styles.errorHint}>{dockerContainersError}</span>
+                        : <span className={styles.creatingHint}>No running containers found.</span>}
+                      <input
+                        type="text"
+                        value={attachContainer}
+                        onChange={(e) => {
+                          setAttachContainer(e.target.value);
+                          if (e.target.value && !envName.trim()) {
+                            setEnvName(e.target.value);
+                          }
+                        }}
+                        placeholder="Enter container name/ID..."
+                        className={styles.fieldInput}
+                        data-testid="env-docker-container-manual"
+                      />
+                    </>
+                  )}
+                </div>
+              )}
             </>
           )}
 

package/src/context/GrackleContextTypes.ts

@@ -10,7 +10,7 @@ import type {
   UsageStats, UseKnowledgeResult,
   UseEnvironmentsResult, UseSessionsResult, UseWorkspacesResult,
   UseTasksResult, UseFindingsResult, UseTokensResult,
-  UseCredentialsResult, UseCodespacesResult, UsePersonasResult,
+  UseCredentialsResult, UseCodespacesResult, UseDockerContainersResult, UsePersonasResult,
   UsePluginsResult,
   UseSchedulesResult,
   UseStreamsResult,
@@ -38,6 +38,8 @@ export interface UseGrackleSocketResult {
   credentials: Omit<UseCredentialsResult, "handleEvent" | "loadCredentials">;
   /** GitHub Codespace state and actions. */
   codespaces: UseCodespacesResult;
+  /** Docker container discovery (attach mode) state and actions. */
+  dockerContainers: UseDockerContainersResult;
   /** Persona state and actions. */
   personas: Omit<UsePersonasResult, "handleEvent" | "loadPersonas">;
   /** Schedule state and actions. */

package/src/hooks/types.ts

@@ -162,6 +162,15 @@ export interface Codespace {
   gitStatus: string;
 }
 
+/** A running Docker container an environment can attach to (`docker ps`). */
+export interface DockerContainer {
+  id: string;
+  name: string;
+  image: string;
+  state: string;
+  status: string;
+}
+
 /** An agent or script persona configuration. */
 export interface PersonaData {
   id: string;
@@ -496,6 +505,18 @@ export interface UseCodespacesResult {
   domainHook: DomainHook;
 }
 
+/** Values returned by the docker-containers domain hook. */
+export interface UseDockerContainersResult {
+  /** Running Docker containers available to attach to. */
+  dockerContainers: DockerContainer[];
+  /** Error message from the most recent list attempt, or empty string. */
+  dockerContainersError: string;
+  /** Request the current running-container list from the server. */
+  listDockerContainers: () => Promise<void>;
+  /** Lifecycle hook for connect/disconnect/event routing. */
+  domainHook: DomainHook;
+}
+
 /** Values returned by the personas domain hook. */
 export interface UsePersonasResult {
   /** All known personas. */