Skip to content
Python

A live plan card above the composer (#851)

Rohit Prasad0899fc4106cb
diff --git a/surfaces/gui/e2e/fixtures.ts b/surfaces/gui/e2e/fixtures.ts
index bbb486d4..e51afd94 100644
--- a/surfaces/gui/e2e/fixtures.ts
+++ b/surfaces/gui/e2e/fixtures.ts
@@ -806,6 +806,42 @@ export async function mockApi(page: import("@playwright/test").Page) {
return;
}
// A deliverable turn ending in an artifact chip (§34) — for the chip-open flow.
+ // Plan dock: every step done — the receipt state with the ✕.
+ if (/finish the plan/i.test(msg.text)) {
+ send("tool_proposed", {
+ name: "todo_write",
+ arguments: {
+ todos: [
+ { content: "Read README, config and deployment setup", status: "done" },
+ { content: "Read server and client source", status: "done" },
+ { content: "Check tests and git history", status: "done" },
+ { content: "Assess and propose improvements", status: "done" },
+ ],
+ },
+ });
+ send("tool_finished", { name: "todo_write", status: "ok" });
+ send("assistant_message", { text: "All steps are done." });
+ send("turn_done");
+ return;
+ }
+ // Plan dock: a todo_write mid-task — the dock above the composer mirrors it.
+ if (/make a plan/i.test(msg.text)) {
+ send("tool_proposed", {
+ name: "todo_write",
+ arguments: {
+ todos: [
+ { content: "Read README, config and deployment setup", status: "done" },
+ { content: "Read server and client source", status: "done" },
+ { content: "Check tests and git history", status: "in_progress" },
+ { content: "Assess and propose improvements", status: "pending" },
+ ],
+ },
+ });
+ send("tool_finished", { name: "todo_write", status: "ok" });
+ send("assistant_message", { text: "Filed the plan; working through it." });
+ send("turn_done");
+ return;
+ }
// Async subagents (OPE-257): spawn → the registry row + started event arrive
// while the parent carries on; the finish event lands after the turn, like a
// real background run.
diff --git a/surfaces/gui/e2e/plan-dock.spec.ts b/surfaces/gui/e2e/plan-dock.spec.ts
new file mode 100644
index 00000000..60ddf965
--- /dev/null
+++ b/surfaces/gui/e2e/plan-dock.spec.ts
@@ -0,0 +1,35 @@
+// The plan dock: the current task's plan rides the composer — collapsed it names the
+// live step and count, expanded it is the step card; the transcript stays untouched.
+import { expect } from "@playwright/test";
+import { test } from "./fixtures";
+
+test("a filed plan docks to the composer and expands into the step card", async ({ page }) => {
+ await page.goto("/");
+ await expect(page.getByTestId("plan-dock")).toHaveCount(0); // no plan, no chrome
+
+ await page.getByPlaceholder(/Ask the coworker/).fill("make a plan");
+ await page.getByRole("button", { name: "Send" }).click();
+
+ const head = page.getByTestId("plan-dock-toggle");
+ await expect(head).toContainText("Check tests and git history"); // the live step
+ await expect(head).toContainText("2 of 4");
+
+ await head.click();
+ const steps = page.getByTestId("plan-dock-steps");
+ await expect(steps.locator(".plandock-step")).toHaveCount(4);
+ await expect(steps.locator(".plandock-step.done").first()).toContainText("Read README");
+});
+
+test("a finished plan stays as the Last-plan receipt until the ✕ clears it", async ({ page }) => {
+ await page.goto("/");
+ await page.getByPlaceholder(/Ask the coworker/).fill("finish the plan");
+ await page.getByRole("button", { name: "Send" }).click();
+
+ const head = page.getByTestId("plan-dock-toggle");
+ await expect(head).toContainText("Last plan");
+ await expect(head).toContainText("All steps done");
+ await expect(head).toContainText("4 of 4");
+
+ await page.getByTestId("plan-dock-clear").click();
+ await expect(page.getByTestId("plan-dock")).toHaveCount(0);
+});
diff --git a/surfaces/gui/src/App.tsx b/surfaces/gui/src/App.tsx
index 8ec5d7cf..d2619565 100644
--- a/surfaces/gui/src/App.tsx
+++ b/surfaces/gui/src/App.tsx
@@ -79,6 +79,7 @@ import { Icon } from "./components/Icon";
import { Sidebar } from "./components/Sidebar";
import { ThinkingBlock, Transcript } from "./components/Transcript";
import { Composer } from "./components/Composer";
+import { PlanDock } from "./components/PlanDock";
import { Markdown } from "./components/Markdown";
import { SearchModal } from "./components/SearchModal";
import { SessionIntro } from "./components/SessionIntro";
@@ -2457,6 +2458,9 @@ export function App() {
</div>
)}
<Composer
+ /* The plan dock rides the composer (owner mock 2026-11-07): undefined
+ when there is no plan, so the box keeps its rounded top. */
+ planSlot={todo.length > 0 ? <PlanDock todo={todo} /> : undefined}
statusSlot={activeInfo?.liveness === "sleeping" && !running ? (
<div className="sleep-strip" data-testid="sleep-strip">
<span className="sleep-dot" />
diff --git a/surfaces/gui/src/components/Composer.tsx b/surfaces/gui/src/components/Composer.tsx
index 78d7a31e..d5702a0e 100644
--- a/surfaces/gui/src/components/Composer.tsx
+++ b/surfaces/gui/src/components/Composer.tsx
@@ -146,6 +146,8 @@ interface Props {
approvalSlot?: ReactNode;
statusSlot?: ReactNode;
teamSlot?: ReactNode;
+ // The plan dock: rendered fused to the input box's top edge (flattens its corners).
+ planSlot?: ReactNode;
// UX-044: "View & edit…" in the Project memory submenu routes to the memory panel.
onOpenMemory?: () => void;
// Push text + attachments into the composer (e.g. a start-panel task card). The `nonce` makes
@@ -665,9 +667,11 @@ export function Composer(props: Props) {
)}
{props.teamSlot}
+ {props.planSlot}
<div
className={
"composer max-w-3xl mx-auto rounded-2xl border border-ink/[0.08] bg-panel shadow-[0_1px_2px_rgba(0,0,0,0.03),0_4px_14px_-10px_rgba(0,0,0,0.08)]" +
+ (props.planSlot ? " rounded-t-none" : "") +
(dragging ? " dragging" : "")
}
onDragOver={(e) => {
diff --git a/surfaces/gui/src/components/PlanDock.test.tsx b/surfaces/gui/src/components/PlanDock.test.tsx
new file mode 100644
index 00000000..14959b3e
--- /dev/null
+++ b/surfaces/gui/src/components/PlanDock.test.tsx
@@ -0,0 +1,67 @@
+// The plan dock: collapsed carries the live step and count; the card is on demand;
+// a finished plan folds itself back to the quiet line.
+import { cleanup, fireEvent, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+import type { TodoItem } from "../types";
+import { PlanDock } from "./PlanDock";
+
+const plan = (statuses: TodoItem["status"][]): TodoItem[] =>
+ statuses.map((status, i) => ({ content: `step ${i + 1}`, status }));
+
+afterEach(cleanup);
+
+describe("PlanDock", () => {
+ it("renders nothing without a plan", () => {
+ render(<PlanDock todo={[]} />);
+ expect(screen.queryByTestId("plan-dock")).toBeNull();
+ });
+
+ it("collapsed: shows the in-progress step and the count", () => {
+ render(<PlanDock todo={plan(["done", "done", "in_progress", "pending"])} />);
+ const head = screen.getByTestId("plan-dock-toggle");
+ expect(head.textContent).toContain("step 3");
+ expect(head.textContent).toContain("2 of 4");
+ expect(screen.queryByTestId("plan-dock-steps")).toBeNull();
+ });
+
+ it("expanded: lists every step with its state", () => {
+ render(<PlanDock todo={plan(["done", "in_progress", "pending"])} />);
+ fireEvent.click(screen.getByTestId("plan-dock-toggle"));
+ const steps = screen.getByTestId("plan-dock-steps");
+ expect(steps.querySelectorAll(".plandock-step").length).toBe(3);
+ expect(steps.querySelector(".plandock-step.done")?.textContent).toContain("step 1");
+ expect(steps.querySelector(".plandock-step.in_progress")?.textContent).toContain("step 2");
+ expect(steps.querySelector(".plandock-step.pending")?.textContent).toContain("step 3");
+ });
+
+ it("auto-collapses into the Last-plan receipt once every step is done", () => {
+ const { rerender } = render(<PlanDock todo={plan(["done", "in_progress"])} />);
+ fireEvent.click(screen.getByTestId("plan-dock-toggle"));
+ expect(screen.getByTestId("plan-dock-steps")).toBeTruthy();
+ expect(screen.queryByTestId("plan-dock-clear")).toBeNull(); // live plans aren't clearable
+ rerender(<PlanDock todo={plan(["done", "done"])} />);
+ expect(screen.queryByTestId("plan-dock-steps")).toBeNull();
+ const head = screen.getByTestId("plan-dock-toggle");
+ expect(head.textContent).toContain("Last plan");
+ expect(head.textContent).toContain("All steps done");
+ });
+
+ it("the ✕ clears the receipt; a superseding plan brings the dock back", () => {
+ const { rerender } = render(<PlanDock todo={plan(["done", "done"])} />);
+ fireEvent.click(screen.getByTestId("plan-dock-clear"));
+ expect(screen.queryByTestId("plan-dock")).toBeNull();
+ // Same finished plan stays cleared across re-renders…
+ rerender(<PlanDock todo={plan(["done", "done"])} />);
+ expect(screen.queryByTestId("plan-dock")).toBeNull();
+ // …but a NEW plan (different steps) supersedes and shows again.
+ rerender(
+ <PlanDock
+ todo={[
+ { content: "fresh step A", status: "in_progress" },
+ { content: "fresh step B", status: "pending" },
+ ]}
+ />,
+ );
+ expect(screen.getByTestId("plan-dock-toggle").textContent).toContain("fresh step A");
+ });
+});
diff --git a/surfaces/gui/src/components/PlanDock.tsx b/surfaces/gui/src/components/PlanDock.tsx
new file mode 100644
index 00000000..04debe24
--- /dev/null
+++ b/surfaces/gui/src/components/PlanDock.tsx
@@ -0,0 +1,84 @@
+import { useEffect, useRef, useState } from "react";
+import { useTranslation } from "react-i18next";
+import type { TodoItem } from "../types";
+import { Icon } from "./Icon";
+
+// The plan dock (owner mock approved 2026-11-07): the coworker's plan for the CURRENT
+// task, fused to the top of the composer — the transcript stays untouched, and the
+// glance lives where the eye already is when typing. Collapsed: a PLAN tag, the step
+// in progress, "2 of 4" and a micro meter. Expanded: the step list. It feeds off the
+// same todo_write state as the rail's Progress section (which remains the per-session
+// summary), auto-collapses when every step is done, and renders nothing with no plan.
+
+export function PlanDock({ todo }: { todo: TodoItem[] }) {
+ const { t } = useTranslation();
+ const [open, setOpen] = useState(false);
+ // A finished plan stays docked as the receipt ("Last plan — done") until the user
+ // clears it with the ✕ or a new plan supersedes it (owner ruling 2026-11-07).
+ // Dismissal is keyed to the plan's CONTENT, so the next todo_write — even one
+ // replacing a half-finished plan — brings the dock back for the new plan.
+ const [dismissed, setDismissed] = useState(false);
+ const signature = todo.map((i) => i.content).join("\u0000");
+ const lastSignature = useRef(signature);
+ useEffect(() => {
+ if (signature !== lastSignature.current) {
+ lastSignature.current = signature;
+ setDismissed(false);
+ }
+ }, [signature]);
+ const done = todo.filter((i) => i.status === "done").length;
+ const allDone = todo.length > 0 && done === todo.length;
+ // The plan finished: fold the card back to the quiet line on its own.
+ useEffect(() => {
+ if (allDone) setOpen(false);
+ }, [allDone]);
+ if (!todo.length || dismissed) return null;
+ const current =
+ todo.find((i) => i.status === "in_progress") || todo.find((i) => i.status !== "done");
+ const pct = Math.round((done / todo.length) * 100);
+ return (
+ <div className={"plandock max-w-3xl mx-auto" + (allDone ? " done" : "")} data-testid="plan-dock">
+ <button
+ className="plandock-head"
+ data-testid="plan-dock-toggle"
+ aria-expanded={open}
+ onClick={() => setOpen((v) => !v)}
+ >
+ <span className="plandock-tag">
+ {allDone ? t("plandock.tag_finished") : t("plandock.tag")}
+ </span>
+ {!open && (
+ <span className="plandock-now">
+ {allDone ? t("plandock.all_done") : current?.content || ""}
+ </span>
+ )}
+ <span className="plandock-count">{t("plandock.count", { done, total: todo.length })}</span>
+ <span className="plandock-meter" aria-hidden>
+ <i style={{ width: `${pct}%` }} />
+ </span>
+ <Icon name={open ? "chevronDown" : "chevronRight"} size={13} className="plandock-chev" />
+ </button>
+ {allDone && (
+ <button
+ className="plandock-x"
+ data-testid="plan-dock-clear"
+ title={t("plandock.clear")}
+ aria-label={t("plandock.clear")}
+ onClick={() => setDismissed(true)}
+ >
+ <Icon name="x" size={12} />
+ </button>
+ )}
+ {open && (
+ <div className="plandock-body" data-testid="plan-dock-steps">
+ {todo.map((item, index) => (
+ <div className={"plandock-step " + item.status} key={index}>
+ <span className="plandock-mark" />
+ <span className="plandock-text">{item.content}</span>
+ </div>
+ ))}
+ </div>
+ )}
+ </div>
+ );
+}
diff --git a/surfaces/gui/src/locales/en.json b/surfaces/gui/src/locales/en.json
index bdfbdfd4..cb2605ac 100644
--- a/surfaces/gui/src/locales/en.json
+++ b/surfaces/gui/src/locales/en.json
@@ -321,6 +321,13 @@
"moved_to": "to"
}
},
+ "plandock": {
+ "tag": "Plan",
+ "tag_finished": "Last plan",
+ "count": "{{done}} of {{total}}",
+ "all_done": "All steps done",
+ "clear": "Clear the finished plan"
+ },
"rail": {
"progress_title": "Progress",
"context_title": "Context",
diff --git a/surfaces/gui/src/locales/zh.json b/surfaces/gui/src/locales/zh.json
index 9e2abb1f..29f853f4 100644
--- a/surfaces/gui/src/locales/zh.json
+++ b/surfaces/gui/src/locales/zh.json
@@ -314,6 +314,13 @@
"moved_to": "至"
}
},
+ "plandock": {
+ "tag": "计划",
+ "tag_finished": "上一个计划",
+ "count": "{{done}}/{{total}}",
+ "all_done": "全部步骤已完成",
+ "clear": "清除已完成的计划"
+ },
"rail": {
"progress_title": "进度",
"context_title": "上下文",
diff --git a/surfaces/gui/src/styles.css b/surfaces/gui/src/styles.css
index 0e7f47be..1bdab24c 100644
--- a/surfaces/gui/src/styles.css
+++ b/surfaces/gui/src/styles.css
@@ -800,6 +800,33 @@ html[data-theme="dark"] .aglyph-f7 { color: #9aa5b3; }
.agent-grid { display: flex; flex-wrap: wrap; gap: 7px 9px; padding: 8px 2px 2px; margin-top: 6px; border-top: 1px solid var(--line); }
.agent-grid-item { opacity: 0.75; display: inline-flex; }
.agent-grid-item:hover { opacity: 1; }
+/* Plan dock (owner mock 2026-11-07): the current task's plan, fused to the composer's
+ top edge. Quiet by default — one line with the live step; the card only on demand. */
+.plandock { position: relative; border: 1px solid var(--line); border-bottom: none; border-radius: 16px 16px 0 0; background: var(--paper); overflow: hidden; }
+/* Finished plan: the receipt state — a ✕ clears it; the head makes room for it. */
+.plandock.done .plandock-head { padding-right: 36px; }
+.plandock-x { position: absolute; top: 5px; right: 8px; width: 22px; height: 22px; display: grid; place-items: center; border: 0; border-radius: 6px; background: transparent; color: var(--faint); cursor: pointer; }
+.plandock-x:hover { color: var(--ink); background: var(--chrome-hover); }
+.plandock-head { display: flex; align-items: center; gap: 9px; width: 100%; padding: 7px 14px; border: 0; background: transparent; cursor: pointer; font: inherit; text-align: left; min-height: 32px; }
+.plandock-tag { font-size: var(--fs-label); font-weight: 600; color: var(--muted); flex: none; }
+.plandock-now { font-size: var(--fs-meta); font-weight: 500; color: var(--ink); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; min-width: 0; flex: 1; }
+.plandock-count { font-size: var(--fs-label); color: var(--muted); flex: none; margin-left: auto; }
+.plandock-now + .plandock-count { margin-left: 0; }
+.plandock-meter { width: 42px; height: 4px; border-radius: 999px; background: var(--line); overflow: hidden; flex: none; }
+.plandock-meter i { display: block; height: 100%; border-radius: 999px; background: var(--muted); }
+.plandock-chev { color: var(--faint); flex: none; }
+.plandock-body { display: flex; flex-direction: column; gap: 7px; padding: 3px 14px 11px; border-top: 1px solid color-mix(in srgb, var(--line) 55%, transparent); }
+.plandock-step { display: flex; gap: 9px; align-items: center; font-size: var(--fs-meta); color: var(--muted); min-width: 0; }
+.plandock-step .plandock-text { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.plandock-step.done { color: var(--faint); }
+.plandock-step.in_progress { color: var(--ink); font-weight: 500; }
+.plandock-mark { width: 13px; height: 13px; border-radius: 999px; flex: none; display: grid; place-items: center; }
+.plandock-step.done .plandock-mark { background: var(--muted); }
+.plandock-step.done .plandock-mark::after { content: "✓"; color: var(--paper); font-size: 8px; font-weight: 700; }
+/* No accent in the composer (UX-056): the live step is a neutral target mark. */
+.plandock-step.in_progress .plandock-mark { border: 1.6px solid var(--muted); }
+.plandock-step.in_progress .plandock-mark::after { content: ""; width: 5px; height: 5px; border-radius: 999px; background: var(--muted); }
+.plandock-step.pending .plandock-mark { border: 1.4px dashed var(--faint); }
.agent-label { display: flex; align-items: baseline; gap: 8px; min-width: 0; font-size: var(--fs-ui); font-weight: 500; color: var(--ink); overflow: hidden; }
.agent-name { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
.agent-sub { font-size: var(--fs-label); color: var(--faint); flex: none; }