diff --git a/.agents-docs/AGENTS-architecture.md b/.agents-docs/AGENTS-architecture.md
index 160be94..0a8abb2 100644
--- a/.agents-docs/AGENTS-architecture.md
+++ b/.agents-docs/AGENTS-architecture.md
@@ -227,7 +227,7 @@ Optional local browser UI shipped with **every** skill. Source lives in `src/web
| `public/screens/docs.js` | documents: tabs, blocks, print and download, and the brief button |
| `public/screens/ending.js` | how a session ends: the finished screen, its offers, Stop and the way home |
| `public/screens/git-host.js` | hosts the git board: tabs, panels and what each click sends |
-| `public/screens/help-dialog.js` | the Help dialog and the first-run Welcome (named so it is never confused with the pure help.js) |
+| `public/screens/help-dialog.js` | the Help dialog and the first-run Welcome (named so it is never confused with the pure help.js). Help reads right in both modes: a phrase that differs under the desktop app carries its app wording in `data-app` (swapped in by `renderAppWording()`), and a paragraph that differs is a `.for-browser` / `.for-app` sibling pair, switched by `:root.in-app` (set in `core.js` from `page.inApp`, rule in `help.css`). The older `render*Help()` functions patch a few ids the same way. `scripts/test-web-console-page-help.mjs` sweeps every topic's visible text in each mode for the other mode's wording |
| `public/screens/looks.js` | User Preferences: looks, sounds and the launcher's model menus |
| `public/screens/starting.js` | the launching, starting and waiting screens, with Planny's poses |
| `public/screens/workspace.js` | the read-only Workspace of extra folders, and @mentions |
@@ -253,6 +253,7 @@ Optional local browser UI shipped with **every** skill. Source lives in `src/web
| `public/meter.js` | PURE, imports only `skills.js`: the session meter. `WEIGHTS` (the events that are not a skill's own launch, merged with each skill's `weight` from `skills.js`; its keys are also `RUN_EVENTS`, the `run` events `post` accepts), `LAUNCH_COUNTED` (workflows whose launch itself scores), the built-phase sizing (`TASK_EVENTS`, the keys of `TASK_BONUS`: `implement-phase` +0 and `implement-review-phase` +1; `isTaskCount()` accepts a whole `tasks` from 1 to `MAX_TASKS` 999; `runPoints()` scores such a run `ceil(tasks / TASKS_PER_POINT)` (3) plus its bonus, and any other run its `WEIGHTS` value), `ANSWERS_PER_POINT` 2 (`answer` entries score per skill run, `floor(count / 2)`), `breakdownFrom()` (the click-the-ring list: one row per scoring entry plus one answers row per skill run), `pointsFrom()` (the count, its sum, folded from `ledger.ndjson` and deduplicated by id, never stored), `levelFor()` with `YELLOW_AT` 5 / `RED_AT` 10, `ringFraction()` (full at `RING_FULL` 15), `WORDS`, `tooltipFor()`, `RED_BANNER` and `meterView()` |
| `public/mentions.js` | PURE, no imports: the `@name` popover's logic — `mentionAt()` finds an `@partial` at the caret, `matchNames()` filters the workspace names, `applyMention()` splices a pick in and returns the new caret. Used by the Ask box, notes and text answers |
| `public/favicon.js` | The tab icon's status bar. `faviconState({ mood, spin, finished })` (PURE) maps the call `renderStatus()` makes for Planny's line to `busy` (the spinning ring), `ready` (`point`), `attention` (`adrift`, `gone`, or `work` without the ring — the stale line) or `plain` (finished, `happy`); `faviconSvg()` is `FAVICON_BODY` (kept equal to `favicon.svg` by a test) plus a bar along the bottom edge in the `FAVICON_COLORS` color (busy dashed on a white strip, so the states differ by pattern; the rest solid); `setFavicon()` swaps both `` hrefs only on a change — the SVG as a data URL, the PNG link drawn through a canvas. Called from `say()` in `renderStatus()`, which runs every second |
+| `public/app-bridge.js` | The messages the page posts to the desktop app that frames it. `framed()` is true inside a frame; `tellApp(kind, extra)` posts `{ plan2code: kind }`, a named request with no free text: `looks` (the highlight's dark shades, from `applyLooks()`, for the app bar's buttons), `agent-continue` (the in-app **continue** button on the Not running line: the app types `continue` and Enter into the agent's terminal) and `new-session` (the meter popover's New Session: the app presses its own bar button, confirm and all). Nothing outside a frame |
| `public/subagents.js` | PURE, no imports: the Subagents switch. `SUBAGENT_WORKFLOWS` / `offered()` (the opt-in table: `implement`, `implement-review`, `quick-task`, `review`, `pathfinder`, each with its default instruction), `cleanSetting()` (`{ on, instruction, max }` or `{ error }`: `bad`, `too-long` past 2,000 characters, `max` outside 1-20), `FRAME_LINES`, `blockFor(setting, told)` (the `Subagents:` lines and `subagents` field an agent is owed, given the session setting and its cursor; never says "off" to an agent not told "on"), `checkHelper()` / `checkHelpers()` (the `helpers` house rule) and the page's view rules `showSwitch()`, `switchLabel()`, `helperRows()`, `showTab()`, `CHECKIN_LINE`. Imported by the server, the `cmd-*.mjs` files, `patches.mjs`, `settings.mjs`, the page and the tests; in `SERVABLE` and preloaded |
| `handoffs.mjs` | the handoff store, the only code that names, lists, marks, deletes and sweeps handoffs, all in `~/.plan2code/handoffs/` (`PLAN2CODE_HANDOFFS_DIR` for tests; `PLAN2CODE_NOW` pins its clock): `newHandoff()` claims `YYYY-MM-DD-HHmm-handoff` (`-2`, `-3` on a clash, the `.json` created exclusively) and writes only `.json` (`{ v: 1, id, title, worktree, project, spec, workflow, skill, written, fromStop, usedAt }`), the agent writing `.md`; `listHandoffs(worktree)` (unused, same worktree, `.md` present, newest first, title and Next task read off the document); `readHandoffMeta()`, `markHandoffUsed()`; `removeHandoff()` (`HANDOFF_ID` only, regular files, never a link, realpath inside the folder, throws on any refusal); `staleHandoffs()` / `removeHandoffs()` for the sweep |
| `notepads.mjs` | the notebook store (the feature is named Notebook; its code, routes and storage folder keep the name `notepad`), the only code that names, reads, writes and removes notebooks, one per folder Plan2Code runs in, in `~/.plan2code/notepads/-<12 hex>/` (`PLAN2CODE_NOTEPADS_DIR` for tests), split into named tabs: `meta.json` (`{ v: 2, folder, created }`), `tabs.json` (`{ v: 1, order, last, tabs: { id: { name, created } } }`) and `tabs//note.md` with `tabs//images/`. `notepadKey()` (the folder's basename slug and the first 12 hex of `sha256(foldKey(folder))`), `listTabs()` / `defaultTabId()`, `readNotepad(folder, tab)` (never creates or writes anything; `{ tabs, last, tab }` with the tab's `text`, `savedAt` and `images` repeated at the top), the tab changes `createTab()` / `renameTab()` / `reorderTabs()` / `setLastTab()` / `deleteTab()` (index first, then the folder; names pass `normalizeTabName()`, `TAB_NAME_MAX` 40, any case compared by `nameKey()`, `NOTEPAD_MAX_TABS` 20), `saveNote(folder, tab, text)` (1 MB cap, atomic), `addImage()` / `addThumb()` / `removeImage()` (JPEG bytes only, 200 pictures per tab, UUID names), `imagePath()` (regular files whose realpath stays inside the folder), `staleNotepads(now, maxAgeMs)` (the real folders directly under it named like a key, never a link or a file, whose newest file is at least `maxAgeMs` old, as `{ key, folder, path }` with `folder` from `meta.json` or null), `removeNotepad(key)` (the key checked against `NOTEPAD_KEY_RE`, the path kept inside the notepads folder by `path.relative`, a link refused, then the whole folder removed; User Preferences, Cleanup is its only caller) and `NotepadError` (`code` and `status`, turned into `{ error }` by the `/notepad` routes). **Migration:** a notepad in the first shape (`note.md` and `images/` at the top) reads as one virtual tab, Notes (`LEGACY_TAB_ID`), and writes nothing; its first write moves the files into `tabs//` and writes `tabs.json` last, every step safe to run again after a crash. A `tabs.json` that does not hold up is set aside as `tabs.json.corrupt` and rebuilt from the tab folders on the next write. Every write runs under a `notepad.lock` in the notepad's folder. The agent CLI never imports it: nothing in a notepad reaches the agent |
diff --git a/CHANGELOG.md b/CHANGELOG.md
index e30a5e1..8e98fae 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -14,8 +14,11 @@ All notable changes to Plan2Code will be documented in this file.
### 🔧 Changed
- **launcher**: `plan2code` no longer treats an SSH or service session on macOS or Windows as having a desktop, and asks before opening a folder that looks like it is not a project (no `.git`, `AGENTS.md` or `specs/`).
+- **web console**: Help's "When an update is out" line now knows when it is read inside the app too: there, it names **Update skills** in the bar instead of describing the dashboard's UPDATE AVAILABLE banner and a terminal command, since that banner never shows under the app and the command has no terminal to run in.
+- **desktop app**: the agent no longer prints the console's web address in the terminal panel, since the page is already in the window beside it: `terminalLine` under the app points at the dashboard instead, and the agent contract says to give no link there.
- **web console**: the **Wrapping up** dialog after **Stop session** no longer closes itself when the stop lands: it turns into **Done**, with every step ticked, and stays up until you close it, so someone who stepped away comes back to an answer. Its "you can close the window/tab if you need to" line is gone.
- **web console**: a plan's **Build order** card has a **Combine phases** button beside **No changes**. One click fills the box with a request to merge phases where possible while keeping each to a clear concern. It shows only in Plan and Revise plan, where the breakdown is phases.
+- **web console**: Help now reads right in the desktop app throughout, not just in the topics fixed before: what this page is and how long it runs, the troubleshooting table and its diagram, scroll memory, drafts, the session meter's red advice, Ask's "no agent" line and Privacy's link and address notes all name the app's window, its terminal panel, **New Session** and **Reconnect the console** instead of a browser tab, a link or a new conversation. The status line's approval hint says "the terminal panel" there too. In a browser, Help is unchanged.
## v2.11.1
diff --git a/scripts/page-test-helpers.mjs b/scripts/page-test-helpers.mjs
index de6be59..5620afb 100644
--- a/scripts/page-test-helpers.mjs
+++ b/scripts/page-test-helpers.mjs
@@ -46,10 +46,10 @@ export function tempProject(files = {}) {
// test still cleans up, and a page error fails the test. `clock: true` gives
// the page Playwright's fake clock before it loads (s.page.clock), so a test
// can jump past the page's silence limits instead of sitting through them.
-export async function openSession(browser, { t, workflow, payload: first, project, open = [], clock = false }) {
+export async function openSession(browser, { t, workflow, payload: first, project, open = [], clock = false, env, init } = {}) {
fs.rmSync(REMEMBERED, { force: true });
const cwd = project || tempProject();
- const opened = cli(["open", "--workflow", workflow, "--no-open", ...open], { cwd }).json;
+ const opened = cli(["open", "--workflow", workflow, "--no-open", ...open], { cwd, env }).json;
const s = {
sid: opened.sid,
session: opened.session,
@@ -95,6 +95,8 @@ export async function openSession(browser, { t, workflow, payload: first, projec
if (first) s.post(first);
s.context = await browser.newContext({ viewport: { width: 1280, height: 800 } });
if (clock) await s.context.clock.install();
+ // A script run before the page's own, such as a stand-in for the app's frame.
+ if (init) await s.context.addInitScript(init);
s.page = await s.context.newPage();
// Playwright's own default (30s) assumes a dedicated machine: the whole
// suite runs dozens of these pages at once, and a host under that load can
diff --git a/scripts/test-web-console-page-dashboard.mjs b/scripts/test-web-console-page-dashboard.mjs
index f76a7c7..74ecf69 100644
--- a/scripts/test-web-console-page-dashboard.mjs
+++ b/scripts/test-web-console-page-dashboard.mjs
@@ -257,9 +257,9 @@ function handoffProject(t) {
return { project, made };
}
-async function openHandoffMenu(t) {
+async function openHandoffMenu(t, env) {
const { project, made } = handoffProject(t);
- const s = await openSession(await suite.browser(), { t, workflow: "dashboard", payload: MENU, project });
+ const s = await openSession(await suite.browser(), { t, workflow: "dashboard", payload: MENU, project, env });
const main = await toTheMenu(s);
const chip = chipFor(main, "Lunch vote");
await chip.waitFor();
@@ -320,6 +320,20 @@ test("Read it all opens the handoff's text, and Copy puts a prompt naming its fi
assert.ok(text.includes(made.id), `the prompt names the handoff's file: ${text}`);
});
+// Under the app, "a new conversation" is this console's own wording for what
+// New Session does, so the handoff's copy button says "another session"
+// instead, still naming the same clipboard prompt.
+test("under the app, a handoff's copy button says Copy for another session, and still works", async (t) => {
+ const { s, main, chip } = await openHandoffMenu(t, { PLAN2CODE_IN_APP: "1" });
+ await s.context.grantPermissions(["clipboard-read", "clipboard-write"], { origin: new URL(s.url).origin });
+ await chip.click();
+ assert.equal(await main.getByRole("button", { name: "Copy for a new conversation" }).count(), 0, "no classic-mode wording under the app");
+ const copy = main.getByRole("button", { name: "Copy for another session" });
+ await copy.click();
+ await main.getByRole("button", { name: "Copied" }).waitFor();
+ await copy.waitFor();
+});
+
// What a person would see break: Delete asks for a name, or sends a spec
// delete instead of the handoff's.
test("a handoff's Delete asks once in its own dialog and sends a delete naming the handoff", async (t) => {
@@ -366,6 +380,39 @@ test("the update banner shows on the dashboard only, and its dismiss hides it",
await banner.waitFor({ state: "hidden" });
});
+// Under the desktop app (PLAN2CODE_IN_APP=1) the app's own top bar already
+// nags about a skills/app mismatch and updates in one click, so this banner
+// (a copy-pasted shell command) must never show there, newer release or not.
+test("under the app, the update banner never shows", async (t) => {
+ aNewerReleaseExists(t);
+ const dash = await openSession(await suite.browser(), {
+ t,
+ workflow: "dashboard",
+ payload: MENU,
+ project: tempProject(DRAFT_PROJECT),
+ env: { PLAN2CODE_IN_APP: "1" },
+ });
+ const main = await toTheMenu(dash);
+ await main.getByText("One spec on disk, with a plan drafted.").waitFor();
+ assert.equal(await main.getByText("UPDATE AVAILABLE").count(), 0, "no banner under the app");
+});
+
+// Same reasoning for the dashboard's own red-meter banner: under the app it
+// must point at New Session, never at starting a new console session.
+test("under the app, the dashboard's red-meter banner points at New Session", async (t) => {
+ const dash = await openSession(await suite.browser(), {
+ t,
+ workflow: "dashboard",
+ payload: MENU,
+ project: tempProject(DRAFT_PROJECT),
+ env: { PLAN2CODE_IN_APP: "1" },
+ });
+ const main = await toTheMenu(dash);
+ dash.post({ run: { event: "implement-phase", id: "phase-1", tasks: 30 } });
+ await main.getByText("Press New Session at the top of the window to start the agent fresh.").waitFor();
+ assert.equal(await main.getByText("Starting a new console session").count(), 0, "no classic-mode wording under the app");
+});
+
// What a person would see break: two dashboard tabs of one session, on
// different picks, keep taking the workspace's folders back from each other.
test("two dashboard tabs on different picks leave the workspace scope with the last pick and ask for it no more", async (t) => {
diff --git a/scripts/test-web-console-page-help.mjs b/scripts/test-web-console-page-help.mjs
index 564a9c8..ab04d7b 100644
--- a/scripts/test-web-console-page-help.mjs
+++ b/scripts/test-web-console-page-help.mjs
@@ -12,9 +12,17 @@ import path from "node:path";
import test from "node:test";
import assert from "node:assert/strict";
import { pageSuite, openSession, tempProject, textOf, drawn } from "./page-test-helpers.mjs";
-import { HOME } from "./web-console-test-helpers.mjs";
+import { HOME, cli, until } from "./web-console-test-helpers.mjs";
import { HELP_TABS } from "../src/web-console/public/help.js";
import { CATALOG_GROUPS, SKILL_CATALOG } from "../src/web-console/public/answers.js";
+import { GONE_AFTER_MS } from "../src/web-console/public/screens/core.js";
+
+// The agent's side of `stop`, leaving the browser context open (s.stop()
+// closes it, which would hide what the page does next).
+async function stopServer(s) {
+ cli(["stop", "--session", s.sid], { cwd: s.project });
+ assert.ok(await until(async () => !(await s.answers()), 5000), "the server still answers after stop");
+}
const suite = pageSuite(test);
@@ -290,3 +298,252 @@ test("the update banner opens a modal with the exact update commands, and its di
await toTheDashboard(s);
assert.equal(await main.getByRole("button", { name: /UPDATE AVAILABLE/ }).count(), 0, "the banner came back after a reload");
});
+
+// Under the app the dashboard's own UPDATE AVAILABLE banner never shows (a
+// separate test already covers that), so Help's own line about it must not
+// send an in-app reader to a terminal command for a banner they can never see.
+test("under the app, Help's update line points at Update skills, not the dashboard banner's terminal command", async (t) => {
+ savedLooks(t, { welcomeSeen: true });
+ const s = await openSession(await suite.browser(), {
+ t,
+ workflow: "dashboard",
+ payload: { agent: { status: "waiting" } },
+ project: tempProject(),
+ env: { PLAN2CODE_IN_APP: "1" },
+ });
+ await toTheDashboard(s);
+ await openHelp(s);
+ await tabButton(s, "dashboard").click();
+ const text = s.page.locator("#help-update-text");
+ await text.getByText("Update skills", { exact: false }).waitFor();
+ assert.equal(await text.locator("code").count(), 0, "no terminal command under the app");
+ assert.equal(await text.getByText("UPDATE AVAILABLE", { exact: false }).count(), 0, "no mention of a banner that never shows there");
+});
+
+// Under the app, when the console server itself is gone, the live "About"
+// line must not send the reader hunting for a link in a terminal: the app's
+// own bar already notices and offers to reconnect it.
+test("under the app, Help's live line about a gone console names the app's bar, not a terminal link", async (t) => {
+ savedLooks(t, { welcomeSeen: true });
+ const s = await openSession(await suite.browser(), {
+ t,
+ workflow: "plan",
+ payload: { items: [{ id: "q1", kind: "text", title: "What to call it", body: "A short name." }], agent: { status: "waiting" } },
+ env: { PLAN2CODE_IN_APP: "1" },
+ clock: true,
+ });
+ await stopServer(s);
+ for (let i = 0; i < 20 && !(await s.page.locator("#planny.is-gone").count()); i++) {
+ await s.page.clock.fastForward(GONE_AFTER_MS);
+ await new Promise((r) => setTimeout(r, 250));
+ }
+ await openHelp(s);
+ // Help opens on "stuck" while gone (helpTabFor); the live line itself lives
+ // on "about", built the same regardless of which tab is first shown.
+ await tabButton(s, "about").click();
+ const live = s.page.locator("#about-live");
+ await live.getByText("The app's own bar notices and offers to reconnect it", { exact: false }).waitFor();
+ assert.equal(await live.getByText("link from the terminal", { exact: false }).count(), 0, "no terminal-link wording under the app");
+});
+
+// Help's own "Running the next command" explainer (the Finishing topic) said
+// "paste into the terminal... in a new conversation": wrong under the app,
+// where it's the one terminal panel, not a separate conversation.
+test("under the app, Help's Finishing topic says to paste into the terminal panel, not a new conversation", async (t) => {
+ savedLooks(t, { welcomeSeen: true });
+ const s = await openSession(await suite.browser(), {
+ t,
+ workflow: "plan",
+ payload: { items: [{ id: "q1", kind: "text", title: "What to call it", body: "A short name." }], agent: { status: "waiting" } },
+ project: tempProject(),
+ env: { PLAN2CODE_IN_APP: "1" },
+ });
+ await openHelp(s);
+ await tabButton(s, "finishing").click();
+ const text = s.page.locator("#help-finishing-command-text");
+ await text.getByText("terminal panel below", { exact: false }).waitFor();
+ assert.equal(await text.getByText("new conversation", { exact: false }).count(), 0, "no classic-mode wording under the app");
+});
+
+// The same topic's "Back to the dashboard" and "Continue here" explainers
+// also described classic-only behavior the screens themselves no longer show
+// under the app: a command to copy, and a new conversation to start fresh in.
+test("under the app, Help's dashboard and Continue here explainers point at the app's own controls", async (t) => {
+ savedLooks(t, { welcomeSeen: true });
+ const s = await openSession(await suite.browser(), {
+ t,
+ workflow: "plan",
+ payload: { items: [{ id: "q1", kind: "text", title: "What to call it", body: "A short name." }], agent: { status: "waiting" } },
+ project: tempProject(),
+ env: { PLAN2CODE_IN_APP: "1" },
+ });
+ await openHelp(s);
+ await tabButton(s, "finishing").click();
+ const dash = s.page.locator("#help-finishing-dashboard-text");
+ await dash.getByText("the app's own bar notices and offers to reconnect it", { exact: false }).waitFor();
+ assert.equal(await dash.locator("code").count(), 0, "no /plan2code command under the app");
+ const cont = s.page.locator("#help-finishing-continue-text");
+ await cont.getByText("press New Session at the top of the window", { exact: false }).waitFor();
+ assert.equal(await cont.getByText("new conversation", { exact: false }).count(), 0, "no classic-mode wording under the app");
+});
+
+// The Welcome dialog's own onboarding tip gave the same classic-only advice.
+test("under the app, the Welcome dialog's refresh tip names New Session, not a new conversation", async (t) => {
+ savedLooks(t, null);
+ const s = await openSession(await suite.browser(), {
+ t,
+ workflow: "dashboard",
+ payload: { agent: { status: "waiting" } },
+ project: tempProject(),
+ env: { PLAN2CODE_IN_APP: "1" },
+ });
+ await toTheDashboard(s);
+ const welcome = s.page.locator("#welcome-modal");
+ await welcome.waitFor();
+ const text = s.page.locator("#welcome-refresh-text");
+ await text.getByText("press New Session at the top of the window", { exact: false }).waitFor();
+ assert.equal(await text.getByText("new conversation", { exact: false }).count(), 0, "no classic-mode wording under the app");
+});
+
+// The Troubleshooting tab's own "getting a new link" recovery flow is
+// classic-only (it ends in a command that prints a fresh browser link);
+// under the app, Reconnect the console in the bar already does this.
+test("under the app, Help's Troubleshooting topic names Reconnect the console, not a new link to print", async (t) => {
+ savedLooks(t, { welcomeSeen: true });
+ const s = await openSession(await suite.browser(), {
+ t,
+ workflow: "plan",
+ payload: { items: [{ id: "q1", kind: "text", title: "What to call it", body: "A short name." }], agent: { status: "waiting" } },
+ project: tempProject(),
+ env: { PLAN2CODE_IN_APP: "1" },
+ });
+ await openHelp(s);
+ await tabButton(s, "stuck").click();
+ const ref = s.page.locator("#help-stuck-not-connected-ref");
+ await ref.getByText("the app's own bar notices and offers to reconnect it", { exact: false }).waitFor();
+ await s.page.locator("#help-stuck-reconnect-title").getByText("Reconnecting").waitFor();
+ const text = s.page.locator("#help-stuck-reconnect-text");
+ await text.getByText("Reconnect the console", { exact: false }).waitFor();
+ assert.equal(await text.getByText("in the terminal", { exact: false }).count(), 0, "no classic-mode wording under the app");
+ assert.equal(await s.page.locator("#help-stuck-reconnect-command").isVisible(), false, "no command to copy under the app");
+ // The "What you might see" symptom table has its own, separate "Not
+ // connected" row making the same classic-only claim.
+ const tableRow = s.page.locator("#help-stuck-table-reconnect-text");
+ await tableRow.getByText("Reconnect the console", { exact: false }).waitFor();
+ assert.equal(await tableRow.getByText("new link", { exact: false }).count(), 0, "no classic-mode wording under the app");
+});
+
+// The Ask tab's "carry away" prompt is meant to start a genuinely fresh task:
+// under the app that means New Session first, then the terminal panel, not
+// "a new conversation" that does not exist there.
+test("under the app, Help's Ask topic says to press New Session and paste into the terminal panel, not a new conversation", async (t) => {
+ savedLooks(t, { welcomeSeen: true });
+ const s = await openSession(await suite.browser(), {
+ t,
+ workflow: "plan",
+ payload: { items: [{ id: "q1", kind: "text", title: "What to call it", body: "A short name." }], agent: { status: "waiting" } },
+ project: tempProject(),
+ env: { PLAN2CODE_IN_APP: "1" },
+ });
+ await openHelp(s);
+ await tabButton(s, "ask").click();
+ const text = s.page.locator("#help-ask-prompt-text");
+ await text.getByText("Press New Session for a clean context, then paste it into the terminal panel", { exact: false }).waitFor();
+ assert.equal(await text.getByText("new conversation", { exact: false }).count(), 0, "no classic-mode wording under the app");
+});
+
+// "Stopping early" also pointed to a terminal command "in a new conversation":
+// matches ending.js's own renderStopping, which already says the terminal panel.
+test("under the app, Help's Stopping early topic says to paste into the terminal panel, not a new conversation", async (t) => {
+ savedLooks(t, { welcomeSeen: true });
+ const s = await openSession(await suite.browser(), {
+ t,
+ workflow: "plan",
+ payload: { items: [{ id: "q1", kind: "text", title: "What to call it", body: "A short name." }], agent: { status: "waiting" } },
+ project: tempProject(),
+ env: { PLAN2CODE_IN_APP: "1" },
+ });
+ await openHelp(s);
+ await tabButton(s, "finishing").click();
+ const text = s.page.locator("#help-finishing-stop-text");
+ await text.getByText("to paste into the terminal panel", { exact: false }).waitFor();
+ assert.equal(await text.getByText("new conversation", { exact: false }).count(), 0, "no classic-mode wording under the app");
+});
+
+// The Planny-poses catalog's own "Done" entry also said "close the tab":
+// there is no tab under the app, only the one window.
+test("under the app, Planny's Done pose says to close the window, not the tab", async (t) => {
+ savedLooks(t, { welcomeSeen: true });
+ const s = await openSession(await suite.browser(), {
+ t,
+ workflow: "plan",
+ payload: { items: [{ id: "q1", kind: "text", title: "What to call it", body: "A short name." }], agent: { status: "waiting" } },
+ project: tempProject(),
+ env: { PLAN2CODE_IN_APP: "1" },
+ });
+ await openHelp(s);
+ await tabButton(s, "planny").click();
+ const text = s.page.locator("#help-planny-done-text");
+ await text.getByText("close the window", { exact: false }).waitFor();
+ assert.equal(await text.getByText("close the tab", { exact: false }).count(), 0, "no classic-mode wording under the app");
+});
+
+// Help's own description of the handoff Copy button named "a new conversation",
+// the console's own wording for what New Session does under the app.
+test("under the app, Help's dashboard topic calls the handoff copy button Copy for another session", async (t) => {
+ savedLooks(t, { welcomeSeen: true });
+ const s = await openSession(await suite.browser(), {
+ t,
+ workflow: "dashboard",
+ payload: { agent: { status: "waiting" } },
+ project: tempProject(),
+ env: { PLAN2CODE_IN_APP: "1" },
+ });
+ await toTheDashboard(s);
+ await openHelp(s);
+ await tabButton(s, "dashboard").click();
+ const text = s.page.locator("#help-handoff-copy-text");
+ await text.getByText("Copy for another session", { exact: false }).waitFor();
+ assert.equal(await text.getByText("Copy for a new conversation", { exact: false }).count(), 0, "no classic-mode wording under the app");
+});
+
+// Every Help topic, as the reader sees it in each mode: the visible text of
+// each panel in turn. A browser tab's wording never shows under the app, and
+// the app's never shows in a browser, wherever in Help it sits.
+async function visibleHelpText(s) {
+ await openHelp(s);
+ const texts = {};
+ for (const t of HELP_TABS) {
+ await tabButton(s, t.id).click();
+ texts[t.id] = await s.page.locator("#help-panel-" + t.id).innerText();
+ }
+ return texts;
+}
+
+const BROWSER_ONLY = [/browser tab/i, /this tab\b/i, /close the tab/i, /closed tab/i, /in your browser/i, /your terminal/i, /in a new conversation/i, /new link/i, /same link/i, /address bar/i, /terminal you started/i];
+const APP_ONLY = [/terminal panel/i, /app's window/i, /app's own bar/i, /New Session/];
+
+for (const inApp of [true, false]) {
+ test(`every Help topic reads right ${inApp ? "under the app" : "in a browser"}`, async (t) => {
+ savedLooks(t, { welcomeSeen: true });
+ const s = await openSession(await suite.browser(), {
+ t,
+ workflow: "plan",
+ payload: { items: [{ id: "q1", kind: "text", title: "What to call it", body: "A short name." }], agent: { status: "waiting" } },
+ project: tempProject(),
+ ...(inApp ? { env: { PLAN2CODE_IN_APP: "1" } } : {}),
+ });
+ const texts = await visibleHelpText(s);
+ const hits = [];
+ for (const [tab, text] of Object.entries(texts)) {
+ for (const re of inApp ? BROWSER_ONLY : APP_ONLY) {
+ const hit = text.match(re);
+ if (hit) hits.push(`${tab}: ...${text.slice(Math.max(0, hit.index - 50), hit.index + 50).replace(/\s+/g, " ")}...`);
+ }
+ }
+ assert.deepEqual(hits, [], "wording from the other mode");
+ // And each mode's own wording is really there, so the sweep is reading the panels.
+ const all = Object.values(texts).join(" ");
+ assert.match(all, inApp ? /terminal panel/ : /your terminal/);
+ });
+}
diff --git a/scripts/test-web-console-page-session.mjs b/scripts/test-web-console-page-session.mjs
index 3532d20..a1f9cf8 100644
--- a/scripts/test-web-console-page-session.mjs
+++ b/scripts/test-web-console-page-session.mjs
@@ -161,6 +161,98 @@ test("Continue here is hidden once the session meter is red, and the command and
assert.equal(await closeGuide(s).count(), 1, "the fresh-session advice stays");
});
+// Under the desktop app (PLAN2CODE_IN_APP=1) the fresh-session advice in the
+// meter's popover and the dashboard's red banner must point at the app's own
+// New Session, never a command to copy into a terminal that is not there:
+// the popover's is a button filled with the user's highlight colour.
+test("under the app, the meter popover and the dashboard's red banner point at New Session, not a command", async (t) => {
+ const s = await openSession(await suite.browser(), {
+ t,
+ workflow: "implement",
+ payload: { agent: { status: "working", activity: "Task 1 of 1" } },
+ env: { PLAN2CODE_IN_APP: "1" },
+ });
+ s.post({ run: { event: "implement-phase", id: "phase-1", tasks: 30 } });
+ const pill = s.page.locator("#meter-pill[data-level='red']");
+ await pill.waitFor();
+ await pill.click();
+ const fresh = s.page.locator("#meter-fresh");
+ const press = fresh.getByRole("button", { name: "Start a New Session" });
+ await press.waitFor();
+ assert.equal(await fresh.locator(".meter-fresh-text").count(), 0, "the button is the whole note, no sentence around it");
+ // The page's highlight, resolved the same way the button's fill is.
+ const [fill, highlight] = await press.evaluate((n) => {
+ const probe = document.createElement("i");
+ probe.style.color = "var(--accent)";
+ n.append(probe);
+ const colour = getComputedStyle(probe).color;
+ probe.remove();
+ return [getComputedStyle(n).backgroundColor, colour];
+ });
+ assert.equal(fill, highlight, "filled with the user's highlight colour");
+ assert.equal(await fresh.locator("code").count(), 0, "no command to copy under the app");
+});
+
+// The desktop app's frame, as the page sees it: a parent that keeps every
+// message posted to it, for the test to read back.
+const FAKE_APP_FRAME = () => {
+ window.__toApp = [];
+ Object.defineProperty(window, "parent", { configurable: true, get: () => ({ postMessage: (m) => window.__toApp.push(m) }) });
+};
+const toApp = (s, kind) => s.page.evaluate((k) => window.__toApp.filter((m) => m.plan2code === k), kind);
+
+test("under the app, the meter popover's Start a New Session button asks the app for its New Session", async (t) => {
+ const s = await openSession(await suite.browser(), {
+ t,
+ workflow: "implement",
+ payload: { agent: { status: "working", activity: "Task 1 of 1" } },
+ env: { PLAN2CODE_IN_APP: "1" },
+ init: FAKE_APP_FRAME,
+ });
+ s.post({ run: { event: "implement-phase", id: "phase-1", tasks: 30 } });
+ const pill = s.page.locator("#meter-pill[data-level='red']");
+ await pill.waitFor();
+ await pill.click();
+ await s.page.locator("#meter-fresh").getByRole("button", { name: "Start a New Session" }).click();
+ await until(async () => (await toApp(s, "new-session")).length === 1, 5000);
+ assert.deepEqual(await toApp(s, "new-session"), [{ plan2code: "new-session" }], "a named request, nothing else in it");
+});
+
+test("under the app, the not running line's continue is a button that asks the app to type it, and the page hands the app its highlight", async (t) => {
+ const s = await openSession(await suite.browser(), {
+ t,
+ workflow: "implement",
+ clock: true,
+ payload: { items: [{ id: "q1", kind: "text", title: "What to call it", body: "A short name." }], agent: { status: "waiting" } },
+ env: { PLAN2CODE_IN_APP: "1" },
+ init: FAKE_APP_FRAME,
+ });
+ const looks = await toApp(s, "looks");
+ assert.ok(looks.length >= 1, "the page told the app its highlight");
+ assert.deepEqual(looks.at(-1).accent, ["#619fe5", "#1a2533", "#0c1117", "#3d5978"], "the default highlight, in its dark shades");
+
+ await s.page.clock.fastForward(200_000);
+ await lineSays(s, /^Plan2Code is not running right now\./);
+ const press = s.page.locator("#agent-text .agent-key-btn");
+ assert.equal(await press.textContent(), "continue");
+ await press.click();
+ await until(async () => (await toApp(s, "agent-continue")).length === 1, 5000);
+ assert.ok(await press.isDisabled(), "held off, so a double press does not type it twice");
+});
+
+test("outside the app, the not running line's continue stays a word to type", async (t) => {
+ const s = await openSession(await suite.browser(), {
+ t,
+ workflow: "implement",
+ clock: true,
+ payload: { items: [{ id: "q1", kind: "text", title: "What to call it", body: "A short name." }], agent: { status: "waiting" } },
+ });
+ await s.page.clock.fastForward(200_000);
+ await lineSays(s, /^Plan2Code is not running right now\./);
+ assert.equal(await s.page.locator("#agent-text .agent-key-btn").count(), 0);
+ assert.equal(await s.page.locator("#agent-text strong.agent-key").textContent(), "continue");
+});
+
test("Stop session, confirmed, sends __stop with no handoff", async (t) => {
const s = await openSession(await suite.browser(), { t, workflow: "plan", payload: PLAN_QUESTION });
await s.page.click("#btn-stop");
@@ -553,6 +645,71 @@ test("every finished shape shows Before you close this with its three rows, and
assert.equal(await s.page.locator("#btn-home").isVisible(), false, "a finished screen carries its own way back");
});
+// Under the app the same three rows point at the app's own controls instead:
+// New Session for "Start fresh", the top bar's dashboard button for "Carry
+// on", and no stray command to copy into a shell that is not there.
+test("under the app, Before you close this points at New Session, and never at a \"new conversation\" that does not exist there", async (t) => {
+ const s = await openSession(await suite.browser(), {
+ t,
+ workflow: "implement",
+ payload: { agent: { status: "working", activity: "Task 1 of 1" } },
+ env: { PLAN2CODE_IN_APP: "1" },
+ });
+ const main = s.page.locator("#main");
+ s.post({ finish: { headline: "A skill next", command: "/plan2code-4-finalize" } });
+ await main.getByRole("heading", { name: "A skill next" }).waitFor();
+ const guide = closeGuide(s);
+ const text = await textOf(guide);
+ assert.ok(text.includes("Press New Session at the top of the window to start the agent fresh."), "Start fresh points at New Session");
+ assert.ok(text.includes("Paste the command above into the terminal panel, or start from the dashboard with /plan2code."), "Carry on names the terminal panel");
+ assert.ok(!text.includes("new session") && !text.includes("new conversation"), "no classic-mode wording under the app");
+ // The extra "To start something else..." paragraph a classic finish also
+ // shows is left out here: the row above already says it once.
+ assert.equal(await main.getByText("To start something else, run").count(), 0, "no second mention of the same command");
+
+ // Nothing left to run: the all-done shape still offers the command (the
+ // app's terminal panel is a real terminal the agent runs in, so pasting it
+ // there works), worded for the one panel rather than a new conversation.
+ s.post({ finish: { headline: "AGENTS.md is updated" } });
+ await main.getByText(/paste .* into the terminal panel below/).waitFor();
+ assert.ok(await main.locator("code").filter({ hasText: /^\/plan2code --web$/ }).count(), "the command is still offered");
+
+ // The live dashboard button's own note, under it, also points at New
+ // Session instead of typing `/clear` by hand.
+ s.post({ finish: { headline: "A skill next, with a live dashboard offer", command: "/plan2code-4-finalize", dashboard: true } });
+ await main.getByRole("button", { name: "Back to the dashboard" }).waitFor();
+ assert.ok(await main.getByText("press New Session at the top of the window for a clean start instead").count(), "the dashboard note points at New Session");
+ assert.equal(await main.getByText("type `/clear`", { exact: false }).count(), 0, "no hand-typed /clear under the app");
+});
+
+// Once the console server itself is gone (not just finished), the review and
+// dashboard offers' own "new conversation" fallback text must say the same:
+// paste into the terminal panel, under the app, and never claim a command is
+// needed to reconnect, since the app's own bar already does that on its own.
+test("under the app, a gone session's review and dashboard fallbacks name the terminal panel, and reconnect needs no command", async (t) => {
+ const s = await openSession(await suite.browser(), {
+ t,
+ workflow: "quick-task",
+ payload: { agent: { status: "working", activity: "Task 1 of 1" } },
+ env: { PLAN2CODE_IN_APP: "1" },
+ clock: true,
+ });
+ s.post({ finish: OFFERS });
+ await s.page.locator("#main").getByRole("heading", { name: "Quick task done" }).waitFor();
+ await s.page.locator("#main").getByRole("button", { name: "Review it now" }).click();
+ collect(s);
+ await stopServer(s);
+ for (let i = 0; i < 20 && !(await s.page.locator("#planny.is-gone").count()); i++) {
+ await s.page.clock.fastForward(GONE_AFTER_MS);
+ await new Promise((r) => setTimeout(r, 250));
+ }
+ const main = s.page.locator("#main");
+ await main.getByText(/paste this into the terminal panel/i).first().waitFor();
+ assert.equal(await main.getByText(/new conversation/i).count(), 0, "no classic-mode wording under the app");
+ await main.getByText("Plan2Code will try to reconnect the console on its own; if it cannot, the app's bar offers Reconnect the console.").waitFor();
+ assert.equal(await main.getByText(/run this in a new conversation/i).count(), 0, "no stray reconnect command under the app");
+});
+
// What a person sees break: the triangle leaving answers behind, or sending a
// finish-style stop instead of the way home.
test("the top bar's back triangle asks first, then sends __dashboard with the typed answers and the home reply", async (t) => {
@@ -629,3 +786,18 @@ test("Back to default in Preferences returns the theme to follow the system and
await s.page.waitForFunction(() => !document.documentElement.hasAttribute("data-theme"));
assert.equal(await s.page.locator('input[name="looks-theme"][value="system"]').isChecked(), true, "the system choice is ticked again");
});
+
+// Planny's own spoken line said "close this tab": under the app there is no
+// tab, only the one window.
+test("under the app, Planny's finished line says to close the window, not the tab", async (t) => {
+ const s = await openSession(await suite.browser(), {
+ t,
+ workflow: "implement",
+ payload: { agent: { status: "working", activity: "Task 1 of 1" } },
+ env: { PLAN2CODE_IN_APP: "1" },
+ });
+ s.post({ finish: { headline: "All done", dashboard: true } });
+ await s.page.locator("#main").getByRole("heading", { name: "All done" }).waitFor();
+ const line = await lineSays(s, /close this window/);
+ assert.doesNotMatch(line, /close this tab/, "no classic-mode wording under the app");
+});
diff --git a/scripts/test-web-console-server.mjs b/scripts/test-web-console-server.mjs
index 7c547bc..1a7cada 100644
--- a/scripts/test-web-console-server.mjs
+++ b/scripts/test-web-console-server.mjs
@@ -256,6 +256,10 @@ test("a working agent's line falls back to its headline note", () => {
test("the terminal line is the exact text every command hands back", () => {
assert.equal(terminalLine("http://127.0.0.1:1/s/abc/"), "→ Look at the web console: http://127.0.0.1:1/s/abc/");
+ // Under the desktop app the page is beside the terminal: no address to print.
+ const inApp = terminalLine("http://127.0.0.1:1/s/abc/", { PLAN2CODE_IN_APP: "1" });
+ assert.equal(inApp.includes("127.0.0.1"), false, "no address under the app");
+ assert.equal(terminalLine("http://127.0.0.1:1/s/abc/", {}), "→ Look at the web console: http://127.0.0.1:1/s/abc/");
});
test("repoRoots reads the branch off disk: named, detached, a linked worktree's own, and none", () => {
diff --git a/scripts/test-web-console-state.mjs b/scripts/test-web-console-state.mjs
index 032179d..e739627 100644
--- a/scripts/test-web-console-state.mjs
+++ b/scripts/test-web-console-state.mjs
@@ -43,6 +43,7 @@ test("state: the rest of the shared state starts as app.js always started it", (
wsFrame: null,
meterFrame: null,
updateFrame: null,
+ inApp: false,
subagentsFrame: null,
overview: { key: null, text: null },
wake: null,
diff --git a/src/web-console/console.md b/src/web-console/console.md
index bc292b8..30298f5 100644
--- a/src/web-console/console.md
+++ b/src/web-console/console.md
@@ -80,7 +80,9 @@ terminal — that path loses nothing, and they can switch either way at any time
first so the page says what you are doing.
4. Tell the person, in one line, the link and how many questions are waiting.
While the session is open, end every terminal message with the latest
- `terminalLine`, verbatim.
+ `terminalLine`, verbatim. When `open` printed `"inApp":true` the page is
+ already in the desktop app's window: never print the link (here, after a
+ resume or anywhere else), only the count; `terminalLine` leaves it out too.
Keep `sid`: every later command takes `--session `.
diff --git a/src/web-console/public/answers.js b/src/web-console/public/answers.js
index cdbc13e..8dfd311 100644
--- a/src/web-console/public/answers.js
+++ b/src/web-console/public/answers.js
@@ -319,6 +319,9 @@ export function finishPaused(fin) {
// read as one sentence.
export const ALL_DONE_LEAD = "All done, nothing left to run.";
export const ALL_DONE_REST = "To start something else, run `/plan2code` in a new conversation to open the dashboard.";
+// The same line for the desktop app: there is no separate "new conversation"
+// to paste this into, only the one terminal panel the agent already runs in.
+export const ALL_DONE_REST_IN_APP = "To start something else, paste `/plan2code` into the terminal panel below to open the dashboard.";
export const DASHBOARD_COMMAND = "/plan2code";
/**
@@ -440,6 +443,10 @@ export const CHANGELOG_REPLY = "Update the CHANGELOG before I commit: open Chang
// conversation, which carries a long skill's context into the next one.
export const DASHBOARD_NOTE =
"This picks up in the same conversation. That's fine after a quick or small skill; after a long one, type `/clear` in your terminal and run `/plan2code` for a clean start.";
+// Under the app, a clean start is New Session, not typing `/clear` by hand:
+// it also leaves the dashboard a handoff brief of where this step left off.
+export const DASHBOARD_NOTE_IN_APP =
+ "This picks up in the same conversation. That's fine after a quick or small skill; after a long one, press New Session at the top of the window for a clean start instead.";
/**
* Whether a finish offers the way back to the dashboard. The agent opts in
@@ -1016,6 +1023,8 @@ export function nextOpenAfter(openIds, staged, sent, currentId) {
export const APPROVAL_TIP =
"Your agent may pause for approvals in the terminal. A hands-off mode (e.g. `auto` mode in Claude Code, `smart` mode in Devin) can help avoid that, but additional attention may still be required.";
export const APPROVAL_HINT = "Still working, or waiting on an approval in your terminal?";
+// The same line under the desktop app, where the terminal is the window's own panel.
+export const APPROVAL_HINT_IN_APP = "Still working, or waiting on an approval in the terminal panel?";
export const APPROVAL_HINT_MS = 30_000;
// When a working agent's silence turns into "has not checked in".
export const STALE_MS = 2 * 60 * 1000;
diff --git a/src/web-console/public/app-bridge.js b/src/web-console/public/app-bridge.js
new file mode 100644
index 0000000..fabb4f5
--- /dev/null
+++ b/src/web-console/public/app-bridge.js
@@ -0,0 +1,19 @@
+// Plan2Code Web Console - the few messages this page sends the desktop app that frames it; defines only.
+//
+// Each one is a named request with no free text in it, so the app decides what
+// it does: a page can ask for "continue" to be typed, never for anything else.
+
+/** True inside a frame: the desktop app's window, the only place that frames this page. */
+export function framed() {
+ return Boolean(window.parent) && window.parent !== window;
+}
+
+/** Post `message` to the frame's parent, as `{ plan2code: kind, ...extra }`; nothing outside a frame. */
+export function tellApp(kind, extra = {}) {
+ if (!framed()) return;
+ try {
+ window.parent.postMessage({ ...extra, plan2code: kind }, "*");
+ } catch {
+ /* no parent to tell */
+ }
+}
diff --git a/src/web-console/public/index.html b/src/web-console/public/index.html
index 04eaa74..290428e 100644
--- a/src/web-console/public/index.html
+++ b/src/web-console/public/index.html
@@ -48,6 +48,7 @@
+
@@ -825,12 +826,12 @@
You
- in your browser
+ in your browserThis pageSmall programon 127.0.0.1Plan2Code
- in your terminal
+ in your terminal
@@ -840,18 +841,24 @@
A small program running on your own machine, started for you by
- Plan2Code in your terminal. Nothing here goes over the internet, and
+ Plan2Code in your terminal. Nothing here goes over the internet, and
there is no account and nothing to install.
On this machine only
-
+
The address starts with 127.0.0.1, which always means
"this computer". Nothing you type leaves your machine, and a colleague
cannot open your link from theirs. To work through a session together,
share your screen.
+
+ The app loads this page from 127.0.0.1, which always
+ means "this computer". Nothing you type leaves your machine, and the
+ page's address stays inside the app, so there is no link to pass
+ around. To work through a session together, share your screen.
+
How long it runs
-
+
It stays up while this tab is open. Close the tab and
it shuts itself down 2 minutes
later. It also stops after 30
@@ -859,19 +866,35 @@
4 hours regardless. Reopening the same link brings everything back: nothing you
typed is kept in the browser alone.
+
+ It stays up while the app's window shows it. Close the
+ window and it shuts itself down 2
+ minutes later. It also stops after 30
+ minutes without hearing from anyone, and after
+ 4 hours regardless. When it
+ stops, the app's own bar notices and brings it back on the same
+ session, or offers Reconnect the console: nothing you
+ typed is kept in the window alone.
+
Two halves, both running
-
+
The terminal is the other half. This page collects your
answers; Plan2Code, in the terminal you started it from, is what reads
them and writes the files. Both have to be running for a question to
reach you or an answer to reach it.
+
+ The terminal panel is the other half. This page collects
+ your answers; Plan2Code, the agent running in the app's terminal panel,
+ is what reads them and writes the files. Both have to be running for a
+ question to reach you or an answer to reach it.
+
If it stops. Press Send anyway. Answers are written to
disk the moment they leave this page and are held until something
collects them, so starting Plan2Code again picks them up where you
- left off. Nothing is lost by closing this tab either.
+ left off. Nothing is lost by closing this tab either.
@@ -879,7 +902,7 @@
When something looks stuck
- This page and Plan2Code in your terminal are two programs, and either
+ This page and Plan2Code in your terminal are two programs, and either
can stop without the other. Nothing you have typed is lost either way.
@@ -891,7 +914,7 @@
Check this first
- If nothing seems to be happening, look at your terminal. Plan2Code
+ If nothing seems to be happening, look at your terminal. Plan2Code
often stops there to ask your permission, and this page cannot see it.
@@ -901,7 +924,7 @@
You see
The line beside Planny stays quiet for half a minute or more while it is working.
-
Likely cause
A permission prompt is waiting in your terminal.
+
Likely cause
A permission prompt is waiting in your terminal.
Do this
Switch to the terminal and answer it.
@@ -909,14 +932,14 @@
You see
Not running (Planny grey and still).
Likely cause
Plan2Code has not checked in for a few minutes.
-
Do this
Look at the terminal. If it is idle, type continue there.
+
Do this
Look at the terminal. If it is idle, type continue there.
Look at the terminal panel. If it is idle, press continue in the line beside Planny, which types it there for you.
You see
Not connected (Planny faded, his star shut).
Likely cause
The program behind this page shut itself down.
-
Do this
Ask Plan2Code to resume the session (or run the command again), and use the new link.
+
Do this
Ask Plan2Code to resume the session (or run the command again), and use the new link.
@@ -947,8 +970,8 @@
Says Notconnected?
- Run the command again,
- use the new link
+ Run the command again,
+ use the new linkyes
@@ -984,7 +1007,7 @@
Not connected (Planny faded, arms hanging, his star shut in red):
this page cannot reach its own program, after
8 seconds without contact.
- Usually it has shut itself down; see "Getting a new link" below.
+ Usually it has shut itself down; see "Getting a new link" below.
"Reading Planny" shows every mood side by side.
@@ -993,8 +1016,8 @@
Plan2Code sometimes stops in the terminal to ask your permission
before it runs a command or changes a file, and this page cannot see
that. After about 30 seconds of silence while it is working, the line
- beside Planny asks "Still working, or waiting on an approval in your
- terminal?" Have a look at the terminal: answering there sets it going
+ beside Planny asks "Still working, or waiting on an approval in your
+ terminal?" Have a look at the terminal: answering there sets it going
again.
@@ -1016,13 +1039,17 @@
What you send is written to disk and held until something collects it,
so starting Plan2Code again picks it up where you left off.
-
Getting a new link
+
Getting a new link
The program behind this page shuts itself down:
-
+
2 minutes after the last tab
showing it closes,
+
+ 2 minutes after the app's
+ window closes,
+
after 30 minutes without hearing
from anyone, or
@@ -1032,12 +1059,12 @@
happening.
-
+
To get it back, ask Plan2Code in the terminal to resume the session,
or run the step's command again, and use the new link it gives you.
Everything you typed, sent or not, is still there.
-
+
resume the session and print the web console address here
@@ -1119,10 +1146,14 @@
beside it opens User Preferences: your role first,
then your colors, theme, card width and sounds.
-
+
The megaphone button at the far right opens GitHub in a
new tab, where you can report a bug or suggest an idea.
+
+ The megaphone button at the far right opens Plan2Code's
+ GitHub issues, where you can report a bug or suggest an idea.
+
Stop session ends the session and saves your place.
See "Stopping and finishing".
@@ -1146,8 +1177,8 @@
Overview when the session is working on a spec, then
one tab per document Plan2Code has written, and Ask,
always last.
- Each tab remembers where you scrolled for as long as this browser tab
- stays open.
+ Each tab remembers where you scrolled for as long as this browser tab
+ stays open.
Moving between questions
@@ -1342,8 +1373,8 @@
Star turning, arms pumping, feet walking on the spot. Plan2Code has your answers and is thinking, or is
busy building. The line beside him says what it is doing. After about
- 30 seconds of silence it asks "Still working, or waiting on an approval
- in your terminal?", because the terminal may have stopped to ask your
+ 30 seconds of silence it asks "Still working, or waiting on an approval
+ in your terminal?", because the terminal may have stopped to ask your
permission for something, and this page cannot see that.
All caught up
@@ -1352,7 +1383,7 @@
answered and Plan2Code has nothing new yet.
Done
-
A green star and both arms up. The session is finished. You can close the tab.
+
A green star and both arms up. The session is finished. You can close the tab.
Not running
Grey, still, arms down out of sight. This page is fine, but Plan2Code has not checked in
@@ -1488,10 +1519,14 @@
Everything you pick or type is a draft that Plan2Code cannot see
yet, and every bit of it can be undone.
-
+
Drafts survive a closed tab and a reload: open the same link again and
your half-typed answers are still there.
+
+ Drafts survive a closed window and a reload: when the app shows this
+ session again, your half-typed answers are still there.
+
The footer says what is ready to go, and the Send button pulses gently
while there is something to send.
@@ -1560,7 +1595,7 @@
images and documents counted together.
- Images are shrunk in your browser to a JPEG at most
+ Images are shrunk in your browser to a JPEG at most
2000 px on the long edge, and must
be under 4 MB after shrinking.
@@ -1709,7 +1744,7 @@
button.
When an update is out
-
+
When a newer Plan2Code release is out, the dashboard shows
UPDATE AVAILABLE at the top. Click it for the command
to run in your terminal, plan2code update; × hides it until the next
@@ -1740,7 +1775,7 @@
bug has its own Delete button at the bottom of its
chip instead, and needs just one confirm, since the work is done.
-
+
A Handoff is a note a step left when you stopped it
with a handoff. It shows as a dashed chip after the specs. Pick one
and the cards give way to a preview with its Next task and four
@@ -1812,12 +1847,19 @@
miss things, and the ring is there to remind you.
What red means
-
+
Starting a new console session will keep Plan2Code
sharp: stop this one, then start Plan2Code again in a new
conversation. Resuming this session carries its count along, so it
does not help. Your work is all on disk, so nothing is lost.
+
+ A fresh start will keep Plan2Code sharp: finish the step, then press
+ New Session at the top of the window. The agent starts
+ again on a clean context, in a new console session whose meter starts
+ over, and the dashboard offers a brief of where you were. Your work is
+ all on disk, so nothing is lost.
+
The meter never blocks anything. Red is advice; you can keep going.
@@ -2085,7 +2127,7 @@
your answers to the cards, and sending those never holds up a question.
Prompts to carry away
-
+
When what you ask is really a new task, or you ask for a prompt,
the answer ends with a ready-to-paste prompt in a box with a
Copy button. Copy it into a new conversation: it
@@ -2155,11 +2197,16 @@
"That's 10 questions in this conversation" means press
New conversation to keep going.
-
+
"No agent is available right now" means the session has finished or
Plan2Code has gone quiet. Check the terminal, or resume the session,
to ask.
+
+ "No agent is available right now" means the session has finished or
+ Plan2Code has gone quiet. Check the terminal panel, or press
+ New Session if the agent has ended, to ask.
+
Either way, the conversation above stays readable.
When an answer lands
@@ -2177,7 +2224,7 @@
run next, whether it finished on its own or you stopped it.
Stopping early
-
+
Stop session, at the top, ends the session and saves
your place. Any answers you have ready go with it, and Plan2Code
gives you a command to pick up where you left off, in a new
@@ -2239,7 +2286,7 @@
this step is over.
Running the next command
-
+
Press Copy, then paste the command into the terminal
where you started Plan2Code, in a new conversation. When the next
step is another Plan2Code step, the command already ends with
@@ -2247,7 +2294,7 @@
you carry on here rather than in the terminal.
Back to the dashboard
-
+
A finished screen (never a paused one) has a Back to the
dashboard button. It turns this page back into the cards, in
the same conversation, so the next step starts right here.
@@ -2266,7 +2313,7 @@
"Commit this now?" and you say yes, it carries on to Git.
Continue here
-
+
When the next step is another Plan2Code step, the Next step block also
has a Continue here button. It starts that step in
this same conversation, the way a dashboard card would, with this page
@@ -2405,20 +2452,33 @@
your project.
On this machine only
-
+
The page is served on 127.0.0.1, which only this
computer can reach. It is not visible on your network, so sharing the
link with someone on another machine will not work, by design. To work
through a session together, share your screen.
+
+ The page is served on 127.0.0.1, which only this
+ computer can reach. It is not visible on your network, and the app
+ shows it in its own window, so there is no link to share. To work
+ through a session together, share your screen.
+
The link is a key
-
+
The link carries a long private code. The first time it is opened, the
page swaps that code for a cookie in this browser and takes it out of
the address bar, so it does not linger in your history or show in a
screenshot. Treat the link like a password all the same: anyone on
this machine who has it can open the session.
+
+ The page's address carries a long private code. The app opens it for
+ you, and the page swaps that code for a cookie in the app's own web
+ view, so it never shows in the window, and the agent leaves it out of
+ the terminal panel. Anyone on this machine who has the address can
+ still open the session, so treat it like a password if you ever see it.
+
What is kept, and where
Everything lives in your home folder, under
@@ -2755,7 +2815,7 @@
Refresh at half way
-
Once the session meter passes half, finish the step and start a new conversation.
+
Once the session meter passes half, finish the step and start a new conversation.
diff --git a/src/web-console/public/looks.js b/src/web-console/public/looks.js
index d14533a..c3a8c36 100644
--- a/src/web-console/public/looks.js
+++ b/src/web-console/public/looks.js
@@ -8,6 +8,7 @@ import { DEFAULT_ACCENT, soundPrefs, DEFAULT_CARD_WIDTH, ACCENTS, cardWidth, sou
import { normalizeRole, ROLE_NOT_SET } from "./starters.js";
import { bootData, hooks } from "./state.js";
import { el } from "./render.js";
+import { tellApp } from "./app-bridge.js";
const $ = (id) => document.getElementById(id);
@@ -129,6 +130,9 @@ const effectiveTheme = () => (looks.theme === "system" ? (systemDark() ? "dark"
export function applyLooks() {
const root = document.documentElement;
+ // The desktop app's bar lights its buttons in the same highlight. That bar
+ // is always dark, so it gets the dark shades whatever this page's theme is.
+ tellApp("looks", { accent: ACCENTS[looks.accent].dark });
// The server's stand-in for the saved accent, which only has to last until
// this runs. From here on the colors are set below, and a stale rule left
// switched on would win over "Back to default".
diff --git a/src/web-console/public/meter.js b/src/web-console/public/meter.js
index 5f62b6a..207bd51 100644
--- a/src/web-console/public/meter.js
+++ b/src/web-console/public/meter.js
@@ -291,6 +291,12 @@ export function tooltipFor(points) {
export const RED_BANNER =
"This console session has done a lot. Starting a new console session will keep the agent sharp.";
+// The same advice, worded for the desktop app: there the app's own New
+// Session button already replaces the agent on a fresh context in one click,
+// so this never tells anyone to copy a command into a new conversation.
+export const RED_BANNER_IN_APP =
+ "This console session has done a lot. Press New Session at the top of the window to start the agent fresh.";
+
// Everything the pill draws, from the ledger alone.
export function meterView(entries) {
const points = pointsFrom(entries);
diff --git a/src/web-console/public/screens/core.js b/src/web-console/public/screens/core.js
index 2e99252..5bcfdea 100644
--- a/src/web-console/public/screens/core.js
+++ b/src/web-console/public/screens/core.js
@@ -19,6 +19,7 @@ import {
STALE_MS,
agentRepliedAfterSend,
approvalHint,
+ APPROVAL_HINT_IN_APP,
cardAvailability,
cardPresentation,
finishPaused,
@@ -66,6 +67,7 @@ import { renderBriefButton, renderDoc, renderOverview } from "./docs.js";
import { board, renderGitBoard, resetBoard } from "./git-host.js";
import { renderWorkspace, tellFolderIssues } from "./workspace.js";
import { openHelpOn } from "./help-dialog.js";
+import { tellApp } from "../app-bridge.js";
import { askOfflineFlipped, askState, declineOpen, renderAside, renderAsk, renderSubagents, renderSubagentsButton } from "./ask.js";
import { renderHandoff, renderHomeButton, renderStopButton, renderStopControls, renderStopping, stopInProgress, stopWarning } from "./ending.js";
import { renderNotepadButton } from "./notepad.js";
@@ -238,6 +240,10 @@ export function adopt(body) {
page.chatFrame = body.chat || null;
if (body.workspace) page.wsFrame = body.workspace;
if (body.meter) page.meterFrame = body.meter;
+ // Fixed for the session's whole life, but cheap enough to just copy.
+ page.inApp = Boolean(body.inApp);
+ // Help's `.for-app` / `.for-browser` wording switches on this (help.css).
+ document.documentElement.classList.toggle("in-app", page.inApp);
// Always replaced: an absent key means no update.
page.updateFrame = body.update || null;
// Always replaced too: an older server sends none, and then there is no switch.
@@ -925,11 +931,21 @@ function renderMeter() {
return li;
})
);
- // Once the session is past fresh, say how to start a new one.
+ // Once the session is past fresh, say how to start a new one. Under the app
+ // that is one button doing what the app bar's New Session does, instead of
+ // a command to copy into a new conversation.
const fresh = $("meter-fresh");
fresh.hidden = page.meterFrame.level === "green";
if (fresh.hidden || fresh.dataset.built) return;
fresh.dataset.built = "1";
+ if (page.inApp) {
+ // The same press as the app bar's New Session, confirm and all.
+ const press = el("button", "btn small primary meter-fresh-btn", "Start a New Session");
+ press.type = "button";
+ press.addEventListener("click", () => tellApp("new-session"));
+ fresh.append(press);
+ return;
+ }
const text = handoffText({ command: DASHBOARD_COMMAND });
const code = el("code", "handoff-code", text);
const row = el("div", "handoff-command meter-fresh-row");
@@ -1007,6 +1023,23 @@ let moodNow = null;
let moodVar = 0;
+// The status line's **continue**, under the app: a press asks the app to type
+// it into the agent's terminal. Held off for a few seconds after, so a double
+// press does not send it twice.
+const CONTINUE_HOLD_MS = 4000;
+
+function continueButton() {
+ const btn = el("button", "agent-key agent-key-btn", "continue");
+ btn.type = "button";
+ btn.title = "Type continue in the agent's terminal";
+ btn.addEventListener("click", () => {
+ btn.disabled = true;
+ tellApp("agent-continue");
+ setTimeout(() => (btn.disabled = false), CONTINUE_HOLD_MS);
+ });
+ return btn;
+}
+
export function renderStatus() {
if (!page.S) return;
const bot = $("planny");
@@ -1031,6 +1064,9 @@ export function renderStatus() {
text.dataset.line = shown;
const parts = line.split(/\*\*(.+?)\*\*/).map((part, i) => {
if (i % 2 === 0) return document.createTextNode(part);
+ // Under the app the terminal is in the same window, so the word to
+ // type is a button that types it there instead.
+ if (page.inApp && part === "continue") return continueButton();
const key = document.createElement("strong");
key.className = "agent-key";
key.textContent = part;
@@ -1064,15 +1100,17 @@ export function renderStatus() {
if (page.local.afterBuild === "changelog" && !page.gone) return say("work", "Opening Changelog…", "", true);
if (page.local.afterBuild === "launch" && !page.gone) return say("work", "Starting the next step…", "", true);
const offer = reviewPending();
+ // There is no tab to close under the app, only the one window.
+ const closeWord = page.inApp ? "window" : "tab";
if (dashboardLive(finish()) && !page.gone && !offer) {
- return say("point", "Done. Head back to the dashboard, or close this tab.");
+ return say("point", `Done. Head back to the dashboard, or close this ${closeWord}.`);
}
if (offer === "asked") return say("work", "Review requested. Plan2Code is starting it.", "", true);
- if (offer === "open") return say("point", "Done. Review it here first, or close this tab.");
+ if (offer === "open") return say("point", `Done. Review it here first, or close this ${closeWord}.`);
// A stop past a warning kept nothing, so it promises no saved place.
if (finishPaused(finish()))
return say("done", stopWarning() ? "Paused. The command above starts it again." : "Paused. Your place is saved: the command above picks it up.");
- return say("done", "All done. You can close this tab.");
+ return say("done", `All done. You can close this ${closeWord}.`);
}
if (page.gone) return say("gone", "Not connected. Your answers are saved.", "", false, true);
// On the way home: the request is sent, and the page stays this skill's
@@ -1121,7 +1159,8 @@ export function renderStatus() {
}
// Same clock as agentStale(), so the soft line at 30 s hands over to the
// stale message at two minutes on one timeline.
- const hint = page.agentLastSeen ? approvalHint(page.S.agent, Date.now() - Date.parse(page.agentLastSeen)) : "";
+ const quiet = page.agentLastSeen ? approvalHint(page.S.agent, Date.now() - Date.parse(page.agentLastSeen)) : "";
+ const hint = quiet && page.inApp ? APPROVAL_HINT_IN_APP : quiet;
return say("work", hint || activity() || "Plan2Code is thinking…", fmtMs(workingMs()), true, Boolean(hint));
}
// Between pressing Send and the agent picking it up, the agent's own status
diff --git a/src/web-console/public/screens/dashboard.js b/src/web-console/public/screens/dashboard.js
index 4631e86..c1408f3 100644
--- a/src/web-console/public/screens/dashboard.js
+++ b/src/web-console/public/screens/dashboard.js
@@ -14,7 +14,7 @@ import { hooks, page, redraw, saveNow } from "../state.js";
import { el, approvalTip, mdInto, releasesLink, copyButton, lightDismiss } from "../render.js";
import { needsRoleNudge, ROLE_NOT_SET } from "../starters.js";
import { looks, renderSwatches, saveLooks } from "../looks.js";
-import { RED_BANNER } from "../meter.js";
+import { RED_BANNER, RED_BANNER_IN_APP } from "../meter.js";
import {
dashNoteKind,
defaultSpec,
@@ -148,12 +148,14 @@ export function renderDashboard(main) {
if (needsRoleNudge(looks)) wrap.appendChild(roleNudge());
// Advice only: words, never a button, and nothing is blocked.
if (page.meterFrame && page.meterFrame.level === "red") {
- const warn = el("div", "dash-nudge meter-banner", RED_BANNER);
+ const warn = el("div", "dash-nudge meter-banner", page.inApp ? RED_BANNER_IN_APP : RED_BANNER);
warn.setAttribute("role", "status");
wrap.appendChild(warn);
}
- // Built here only, so no other workflow's page ever shows it.
- if (page.updateFrame && !updateDismissed()) {
+ // Built here only, so no other workflow's page ever shows it. Under the app
+ // this never shows at all: the app's own top bar already says so and, unlike
+ // this banner's copy-pasted command, updates the skills itself in one click.
+ if (page.updateFrame && !page.inApp && !updateDismissed()) {
const notice = el("div", "dash-nudge update-banner");
notice.setAttribute("role", "status");
const open = el("button", "update-banner-open", "UPDATE AVAILABLE · v" + page.updateFrame.latest);
@@ -556,13 +558,14 @@ function renderHandoffPreview(h) {
const read = el("button", "btn", "Read it all");
read.type = "button";
read.addEventListener("click", () => readHandoff(h));
- const copy = el("button", "btn", "Copy for a new conversation");
+ const copyLabel = page.inApp ? "Copy for another session" : "Copy for a new conversation";
+ const copy = el("button", "btn", copyLabel);
copy.type = "button";
copy.addEventListener("click", () => {
const dir = (scan() && scan().handoffsDir) || "";
const sep = dir.includes("\\") ? "\\" : "/";
const file = dir ? dir.replace(/[\\/]+$/, "") + sep + h.id + ".md" : h.id + ".md";
- copyHandoffText(handoffCopyText(file), copy);
+ copyHandoffText(handoffCopyText(file), copy, copyLabel);
});
const del = el("button", "btn danger", "Delete");
del.type = "button";
@@ -575,14 +578,14 @@ function renderHandoffPreview(h) {
// The prompt that sends a new conversation to the handoff. A refused
// clipboard gets a plain word on the button instead of a silent nothing.
-async function copyHandoffText(text, button) {
+async function copyHandoffText(text, button, label) {
try {
await navigator.clipboard.writeText(text);
button.textContent = "Copied";
} catch {
button.textContent = "Copy was refused";
}
- setTimeout(() => (button.textContent = "Copy for a new conversation"), 1500);
+ setTimeout(() => (button.textContent = label), 1500);
}
// Pick it up here: a hop like a card launch. The page sends only the id; the
diff --git a/src/web-console/public/screens/ending.js b/src/web-console/public/screens/ending.js
index 4b4c1c3..670c937 100644
--- a/src/web-console/public/screens/ending.js
+++ b/src/web-console/public/screens/ending.js
@@ -11,11 +11,13 @@ import {
handoffShape,
ALL_DONE_LEAD,
ALL_DONE_REST,
+ ALL_DONE_REST_IN_APP,
handoffText,
DASHBOARD_COMMAND,
resumeCommand,
afterFinishButton,
DASHBOARD_NOTE,
+ DASHBOARD_NOTE_IN_APP,
turnGate,
homeButtonState,
HOME_REPLY,
@@ -88,25 +90,43 @@ function renderCloseGuide(shape, fin = {}) {
const title = el("h3", "handoff-guide-title", "Before you close this");
title.id = "handoff-guide-title";
panel.appendChild(title);
+ // Under the app this reads differently: there is one window, not a tab, and
+ // the app's own New Session button already starts the agent fresh in one
+ // click, so nothing here asks anyone to close a session or open another.
const rows = [
- ["safe", "Safe to close", "This tab is only a window: whatever this session wrote is on disk, and nothing here needs you."],
+ [
+ "safe",
+ "Safe to close",
+ page.inApp
+ ? "This window is only a view: whatever this session wrote is on disk, and nothing here needs you."
+ : "This tab is only a window: whatever this session wrote is on disk, and nothing here needs you.",
+ ],
[
"fresh",
"Start fresh",
- shape === "paused"
- ? stopWarning()
- ? "Restart your agent window, or close the old session and start a new one. The command above starts it again."
- : "Restart your agent window, or close the old session and start a new one. Your saved place is picked up by the resume command above."
- : "Restart your agent window, or close the old session and start a new one. A new session starts from clean context. This one is full of this step's instructions, so continuing in it is slower and can confuse the next step.",
+ page.inApp
+ ? "Press New Session at the top of the window to start the agent fresh."
+ : shape === "paused"
+ ? stopWarning()
+ ? "Restart your agent window, or close the old session and start a new one. The command above starts it again."
+ : "Restart your agent window, or close the old session and start a new one. Your saved place is picked up by the resume command above."
+ : "Restart your agent window, or close the old session and start a new one. A new session starts from clean context. This one is full of this step's instructions, so continuing in it is slower and can confuse the next step.",
],
[
"carry",
"Carry on",
+ // The app's terminal panel runs the agent itself, so a slash command
+ // still goes there, not into some other "new session" or "new
+ // conversation" that does not exist under the app.
shape === "all-done"
- ? `In the new session, start from the dashboard with \`${DASHBOARD_COMMAND}\`.`
+ ? page.inApp
+ ? `In the terminal panel, start from the dashboard with \`${DASHBOARD_COMMAND}\`.`
+ : `In the new session, start from the dashboard with \`${DASHBOARD_COMMAND}\`.`
: shell
? `Run the command above in your terminal, then start the next step from the dashboard with \`${DASHBOARD_COMMAND}\`.`
- : `Paste the command above in the new session, or start from the dashboard with \`${DASHBOARD_COMMAND}\`.`,
+ : page.inApp
+ ? `Paste the command above into the terminal panel, or start from the dashboard with \`${DASHBOARD_COMMAND}\`.`
+ : `Paste the command above in the new session, or start from the dashboard with \`${DASHBOARD_COMMAND}\`.`,
],
];
const list = el("ul", "handoff-guide-rows");
@@ -160,7 +180,10 @@ export function renderHandoff(fin) {
const shape = handoffShape(fin);
if (shape === "all-done") {
const done = el("div", "handoff-done");
- done.appendChild(md(`${ALL_DONE_LEAD} ${ALL_DONE_REST}`, "md handoff-done-text"));
+ done.appendChild(md(`${ALL_DONE_LEAD} ${page.inApp ? ALL_DONE_REST_IN_APP : ALL_DONE_REST}`, "md handoff-done-text"));
+ // The command still works under the app: its terminal panel runs the
+ // agent itself, so pasting this there reaches the dashboard exactly as
+ // it would in a plain terminal.
const text = handoffText({ command: DASHBOARD_COMMAND });
const row = el("div", "handoff-command");
const code = el("code", "handoff-code", text);
@@ -182,7 +205,9 @@ export function renderHandoff(fin) {
"handoff-where",
fin.where ||
(command.startsWith("/")
- ? "Run this in the terminal where you started Plan2Code, in a new conversation:"
+ ? page.inApp
+ ? "Paste this into the terminal panel below:"
+ : "Run this in the terminal where you started Plan2Code, in a new conversation:"
: "Run this in your terminal:")
)
);
@@ -213,7 +238,12 @@ export function renderHandoff(fin) {
if (shape === "next") {
const offerDash = dashboardLive(fin);
if (offerDash) card.appendChild(renderDashboardOffer(false));
- if (!(offerDash && page.gone)) {
+ // Under the app this paragraph never shows: renderCloseGuide's own
+ // "carry" row already says the same thing ("Paste the command above
+ // into the terminal panel, or start from the dashboard with
+ // `/plan2code`"), right below this card, so repeating it here would
+ // be the third mention of the one action on this screen.
+ if (!page.inApp && !(offerDash && page.gone)) {
card.appendChild(
textWithCode(
"p",
@@ -303,9 +333,13 @@ function renderReviewOffer(offer) {
el(
"p",
"review-offer-text",
- asked
- ? "The session closed before the review could start. To run it now, use this in the terminal, in a new conversation:"
- : "This session has closed, so the review cannot start from here any more. To run it, use this in the terminal, in a new conversation:"
+ page.inApp
+ ? asked
+ ? "The session closed before the review could start. To run it now, paste this into the terminal panel:"
+ : "This session has closed, so the review cannot start from here any more. To run it, paste this into the terminal panel:"
+ : asked
+ ? "The session closed before the review could start. To run it now, use this in the terminal, in a new conversation:"
+ : "This session has closed, so the review cannot start from here any more. To run it, use this in the terminal, in a new conversation:"
)
);
const text = "/plan2code-review";
@@ -422,6 +456,19 @@ function renderChangelogOffer() {
function renderDashboardOffer(primary) {
const box = el("section", "dashboard-offer");
if (page.gone) {
+ if (page.inApp) {
+ // The app's own bar already notices a dead console and offers to
+ // reconnect it (its next-step slot, "Reconnect the console"); nothing here
+ // is a command for anyone to run themselves.
+ box.appendChild(
+ el(
+ "p",
+ null,
+ "This session has closed. Plan2Code will try to reconnect the console on its own; if it cannot, the app's bar offers Reconnect the console."
+ )
+ );
+ return box;
+ }
box.appendChild(
el(
"p",
@@ -447,7 +494,7 @@ function renderDashboardOffer(primary) {
go.disabled = disabled;
go.addEventListener("click", () => sendAfterBuild("dashboard"));
box.appendChild(go);
- box.appendChild(textWithCode("p", "dashboard-note", DASHBOARD_NOTE));
+ box.appendChild(textWithCode("p", "dashboard-note", page.inApp ? DASHBOARD_NOTE_IN_APP : DASHBOARD_NOTE));
return box;
}
@@ -733,9 +780,13 @@ export function renderStopping() {
el(
"p",
"stop-note",
- page.gone
- ? "The session closed without saying how to pick it up. Your answers and the stop are saved, and the next session collects them. To carry on, run this in the terminal, in a new conversation (or alternatively run `/plan2code` to relaunch the dashboard):"
- : "Plan2Code is not running right now, so nothing new has been saved yet. Your answers and the stop are held, and the next session collects them. To carry on, run this in the terminal, in a new conversation (or alternatively run `/plan2code` to relaunch the dashboard):"
+ page.inApp
+ ? (page.gone
+ ? "The session closed without saying how to pick it up. Your answers and the stop are saved, and the next session collects them. Paste this into the terminal panel below to carry on:"
+ : "Plan2Code is not running right now, so nothing new has been saved yet. Your answers and the stop are held, and the next session collects them. Paste this into the terminal panel below to carry on:")
+ : page.gone
+ ? "The session closed without saying how to pick it up. Your answers and the stop are saved, and the next session collects them. To carry on, run this in the terminal, in a new conversation (or alternatively run `/plan2code` to relaunch the dashboard):"
+ : "Plan2Code is not running right now, so nothing new has been saved yet. Your answers and the stop are held, and the next session collects them. To carry on, run this in the terminal, in a new conversation (or alternatively run `/plan2code` to relaunch the dashboard):"
)
);
const text = handoffText({ command: resumeCommand(page.S) });
diff --git a/src/web-console/public/screens/help-dialog.js b/src/web-console/public/screens/help-dialog.js
index 3b43995..45c56aa 100644
--- a/src/web-console/public/screens/help-dialog.js
+++ b/src/web-console/public/screens/help-dialog.js
@@ -19,7 +19,15 @@ export function maybeWelcome() {
openWelcome();
}
+// The same "finish the step and start fresh" tip the meter popover and the
+// dashboard's own red banner give, worded for the app's New Session button there.
+function renderWelcomeRefreshHelp() {
+ if (!page.inApp) return;
+ $("welcome-refresh-text").textContent = "Once the session meter passes half, finish the step and press New Session at the top of the window.";
+}
+
export function openWelcome() {
+ renderWelcomeRefreshHelp();
if ($("help-modal").open) $("help-modal").close();
const slot = $("welcome-bot");
if (!slot.firstElementChild) {
@@ -44,18 +52,149 @@ function renderAbout() {
line.textContent = "Right now: the session is finished, and the command above is all that is left to do.";
} else if (page.gone) {
line.classList.add("is-bad");
- line.textContent =
- "Right now: this page cannot reach that program. Either it has stopped, or the machine went to sleep. The link from the terminal will bring it back.";
+ line.textContent = page.inApp
+ ? "Right now: this page cannot reach that program. Either it has stopped, or the machine went to sleep. The app's own bar notices and offers to reconnect it."
+ : "Right now: this page cannot reach that program. Either it has stopped, or the machine went to sleep. The link from the terminal will bring it back.";
} else if (agentAdrift()) {
line.classList.add("is-bad");
- line.textContent =
- "Right now: this page is fine, but Plan2Code has not checked in for a few minutes. Have a look at the terminal; it may have finished its turn, hit an error, or be waiting on you there. If it is idle, type continue there to wake it.";
+ line.textContent = page.inApp
+ ? "Right now: this page is fine, but Plan2Code has not checked in for a few minutes. Have a look at the terminal panel; it may have finished its turn, hit an error, or be waiting on you there. If it is idle, press continue in the line beside Planny to wake it."
+ : "Right now: this page is fine, but Plan2Code has not checked in for a few minutes. Have a look at the terminal; it may have finished its turn, hit an error, or be waiting on you there. If it is idle, type continue there to wake it.";
} else {
line.classList.add("is-good");
line.textContent = "Right now: both halves are talking to each other.";
}
}
+// Under the app, the dashboard's own UPDATE AVAILABLE banner never shows (the
+// app's bar already nags about a skills/app mismatch and updates in one
+// click, see docs/desktop-app.md), so this line would describe a banner the
+// reader can never find and send them to a terminal the app's own button
+// already makes unnecessary. Patched once, the first time Help opens, since
+// page.inApp never changes for the session's life.
+function renderUpdateHelp() {
+ if (!page.inApp) return;
+ $("help-update-text").replaceChildren(
+ "When the app and the installed skills fall out of step, its own top bar says so and offers ",
+ el("strong", null, "Update skills"),
+ ", which brings them level in one click, no terminal needed."
+ );
+}
+
+// Same reasoning as ending.js's own close guide: the command still works
+// under the app (its terminal panel runs the agent itself), just not in "a
+// new conversation" that does not exist there.
+function renderFinishingHelp() {
+ if (!page.inApp) return;
+ $("help-finishing-command-text").replaceChildren(
+ "Press ",
+ el("strong", null, "Copy"),
+ ", then paste the command into the terminal panel below. When the next step is another Plan2Code step, the command already ends with ",
+ el("code", null, "--web"),
+ ", which asks Plan2Code to open this page again, so you carry on here rather than in the terminal panel."
+ );
+}
+
+// Two more Finishing explainers that describe behavior already reworded for
+// the app elsewhere (renderDashboardOffer's gone branch, the meter-fresh
+// popover): kept in sync here so Help never teaches the classic-only version
+// of something the screen itself no longer does under the app.
+function renderFinishingDashboardHelp() {
+ if (!page.inApp) return;
+ $("help-finishing-dashboard-text").replaceChildren(
+ "A finished screen (never a paused one) has a ",
+ el("strong", null, "Back to the dashboard"),
+ " button. It turns this page back into the cards, in the same conversation, so the next step starts right here. Plan2Code listens for it for as long as the session is open. Once the session has closed, the app's own bar notices and offers to reconnect it, no command needed."
+ );
+}
+
+function renderFinishingContinueHelp() {
+ if (!page.inApp) return;
+ $("help-finishing-continue-text").replaceChildren(
+ "When the next step is another Plan2Code step, the Next step block also has a ",
+ el("strong", null, "Continue here"),
+ " button. It starts that step in this same conversation, the way a dashboard card would, with this page turning into the new step. It goes away once the session meter is red, because a long conversation is the reason to start a fresh one: press New Session at the top of the window instead."
+ );
+}
+
+// The Troubleshooting tab's own "getting a new link" recovery flow: classic
+// only, since it ends with a command that prints a fresh browser link. Under
+// the app there is no link to print or open: the bar's next-step slot and its
+// Reconnect the console (app.js) already notice and bring the page back.
+function renderStuckReconnectHelp() {
+ if (!page.inApp) return;
+ $("help-stuck-not-connected-ref").textContent = "the app's own bar notices and offers to reconnect it";
+ $("help-stuck-table-reconnect-text").textContent = "The app's own bar notices and offers Reconnect the console.";
+ $("help-stuck-reconnect-title").textContent = "Reconnecting";
+ $("help-stuck-reconnect-text").textContent =
+ "To get it back, press Reconnect the console in the app's own bar (it tries on its own first). Everything you typed, sent or not, is still there.";
+ // Not just .hidden: .handoff-command's own display:flex outranks the
+ // default [hidden] rule, so the element comes out of the DOM instead.
+ $("help-stuck-reconnect-command").remove();
+}
+
+// A handoff's "Copy for a new conversation" button is for carrying work to
+// a wholly separate agent (another machine, another terminal); under the app
+// that still works, but "a new conversation" is this one's own wording for
+// what New Session does, so name that instead to avoid sounding like a
+// second, missing feature.
+function renderHandoffCopyHelp() {
+ if (!page.inApp) return;
+ $("help-handoff-copy-text").replaceChildren(
+ "A ",
+ el("strong", null, "Handoff"),
+ " is a note a step left when you stopped it with a handoff. It shows as a dashed chip after the specs. Pick one and the cards give way to a preview with its Next task and four buttons: ",
+ el("strong", null, "Pick it up here"),
+ " carries on in the same step and spec, ",
+ el("strong", null, "Read it all"),
+ " shows the whole note, ",
+ el("strong", null, "Copy for another session"),
+ " puts a ready prompt on the clipboard, for pasting into the terminal panel after a New Session or anywhere else you carry the work, and ",
+ el("strong", null, "Delete"),
+ " removes it. A picked-up handoff drops off the list, but stays in ",
+ el("code", null, "~/.plan2code/handoffs/"),
+ " until the 30-day sweep."
+ );
+}
+
+// The Ask tab's "carry away" prompt is meant to start a genuinely fresh,
+// separate task: under the app that means pasting it into the terminal panel
+// after a New Session, not into "a new conversation" that does not exist there.
+function renderAskPromptHelp() {
+ if (!page.inApp) return;
+ $("help-ask-prompt-text").replaceChildren(
+ "When what you ask is really a new task, or you ask for a prompt, the answer ends with a ready-to-paste prompt in a box with a ",
+ el("strong", null, "Copy"),
+ " button. Press New Session for a clean context, then paste it into the terminal panel: it names the skill to use and the files to read, so nothing said here needs repeating."
+ );
+}
+
+// Matches ending.js's own renderStopping, which already says "paste into the
+// terminal panel" under the app instead of "a new conversation".
+// The Planny-poses catalog's own "Done" entry said the same "close the tab":
+// there is no tab under the app, only the one window.
+function renderPlannyDoneHelp() {
+ if (!page.inApp) return;
+ $("help-planny-done-text").textContent = "A green star and both arms up. The session is finished. You can close the window.";
+}
+
+function renderFinishingStopHelp() {
+ if (!page.inApp) return;
+ $("help-finishing-stop-text").replaceChildren(
+ el("strong", null, "Stop session"),
+ ", at the top, ends the session and saves your place. Any answers you have ready go with it, and Plan2Code gives you a command to pick up where you left off, to paste into the terminal panel."
+ );
+}
+
+// A phrase that reads differently under the app carries its app wording in
+// `data-app`, and the browser wording stays in the markup as it was. Whole
+// paragraphs that differ are `.for-app` / `.for-browser` siblings instead,
+// switched by help.css. Plain text only: anything with markup in it is a pair.
+function renderAppWording(root) {
+ if (!page.inApp) return;
+ for (const node of root.querySelectorAll("[data-app]")) node.textContent = node.getAttribute("data-app");
+}
+
let helpBuilt = false;
async function renderHelpVersion() {
@@ -162,7 +301,19 @@ export function selectHelpTab(id) {
}
export function openHelp() {
- if (!helpBuilt) buildHelp();
+ if (!helpBuilt) {
+ buildHelp();
+ renderAppWording($("help-panels"));
+ renderUpdateHelp();
+ renderFinishingHelp();
+ renderFinishingDashboardHelp();
+ renderFinishingContinueHelp();
+ renderStuckReconnectHelp();
+ renderAskPromptHelp();
+ renderFinishingStopHelp();
+ renderPlannyDoneHelp();
+ renderHandoffCopyHelp();
+ }
const id = helpTabFor({
view: page.view,
dashboard: isDashboard(),
diff --git a/src/web-console/public/state.js b/src/web-console/public/state.js
index fdc53d0..26924a7 100644
--- a/src/web-console/public/state.js
+++ b/src/web-console/public/state.js
@@ -101,6 +101,10 @@ export const page = {
// The frame's update ({ installed, latest }), present only when a newer
// release is out; null otherwise.
updateFrame: null,
+ // Whether the desktop app is driving this session (the frame's `inApp`):
+ // false until the first frame lands, same as every other flag here, and
+ // from an older server that sends none.
+ inApp: false,
// The frame's Subagents switch ({ offered, supported, on, instruction, max,
// revision }), or null before a server that sends it.
subagentsFrame: null,
diff --git a/src/web-console/public/styles/help.css b/src/web-console/public/styles/help.css
index 0bfd609..20edc37 100644
--- a/src/web-console/public/styles/help.css
+++ b/src/web-console/public/styles/help.css
@@ -175,3 +175,10 @@
.about-live.is-good { background: var(--ok-soft); border-color: var(--ok); color: var(--ok); }
.about-live.is-bad { background: var(--stage-soft); border-color: var(--stage); color: var(--stage); }
+
+/* Help says some things two ways, once for a browser tab and once for the
+ desktop app's window: `.for-browser` and `.for-app` siblings, with the root
+ marked `in-app` under the app (core.js). Important, because a block's own
+ display (a flex row, say) would otherwise outrank this. */
+:root:not(.in-app) .for-app,
+:root.in-app .for-browser { display: none !important; }
diff --git a/src/web-console/public/styles/responsive.css b/src/web-console/public/styles/responsive.css
index a514d0e..51454bf 100644
--- a/src/web-console/public/styles/responsive.css
+++ b/src/web-console/public/styles/responsive.css
@@ -127,6 +127,15 @@
color: var(--accent);
font-weight: 700;
}
+/* Under the app, the word is a button that types it into the agent's terminal. */
+.agent-key-btn {
+ font: inherit; font-weight: 700; color: var(--accent);
+ background: var(--accent-soft); border: 1px solid var(--accent-line); border-radius: 6px;
+ padding: 0 6px; cursor: pointer;
+}
+.agent-key-btn:hover:not(:disabled) { border-color: var(--accent); }
+.agent-key-btn:disabled { opacity: 0.55; cursor: default; }
+.agent-key-btn:focus-visible { outline: 2px solid var(--focus); outline-offset: 2px; }
/* "What to check", beside the quiet and Not running lines. A link in a button's clothes. */
.status-help {
diff --git a/src/web-console/public/styles/shell.css b/src/web-console/public/styles/shell.css
index 4214e72..5c93eee 100644
--- a/src/web-console/public/styles/shell.css
+++ b/src/web-console/public/styles/shell.css
@@ -146,6 +146,8 @@
.meter-fresh { margin: 0 0 8px; padding-top: 6px; border-top: 1px solid var(--rule); }
.meter-fresh[hidden] { display: none; }
.meter-fresh-text { margin: 0 0 6px; font-size: 12px; color: var(--ink-2); }
+/* Under the app the whole note is one button: a press is the bar's New Session. */
+.meter-fresh-btn { display: block; width: 100%; margin: 2px 0 6px; }
.meter-fresh-row .handoff-code { flex-basis: 180px; font-size: 12px; padding: 6px 10px; }
.meter-item-points { flex: none; font-weight: 600; color: var(--ink); font-variant-numeric: tabular-nums; }
diff --git a/src/web-console/server.mjs b/src/web-console/server.mjs
index 120c292..0e06a31 100644
--- a/src/web-console/server.mjs
+++ b/src/web-console/server.mjs
@@ -45,6 +45,7 @@ import {
} from "./inbox.mjs";
import { serverWorkspace } from "./workspace.mjs";
import { serverSubagents } from "./settings.mjs";
+import { inAppSignal } from "./in-app.mjs";
import { chatOffline } from "./public/chat.js";
import { meterView } from "./public/meter.js";
import { startsClean } from "./public/hops.js";
@@ -246,6 +247,13 @@ function ensureConversation(state) {
// writer, this server.
const subagents = serverSubagents({ dir: DIR, worktree: sessionWorktree });
+// Whether the agent driving this session is the desktop app: fixed for the
+// process's whole life (the env var that says so is set once, at spawn), so
+// read once rather than on every frame. The page uses it to drop advice that
+// only makes sense in a plain terminal (a command to copy into a new
+// conversation) in favour of the app's own Restart and Update skills buttons.
+const IN_APP = Boolean(inAppSignal());
+
// What the page needs to draw itself, in the shape of the SSE state frame.
// `have` names that exact view, for the page to hand back when it opens its
// stream (see /events).
@@ -261,6 +269,7 @@ function stateFrame(state) {
workspace: workspace.workspaceView(),
meter: meterView(ledgerEntries()),
subagents: subagents.view(state),
+ inApp: IN_APP,
...(updateInfo ? { update: updateInfo } : {}),
have: haveKey(),
};
diff --git a/src/web-console/sessions.mjs b/src/web-console/sessions.mjs
index 0516d51..4b9dcc9 100644
--- a/src/web-console/sessions.mjs
+++ b/src/web-console/sessions.mjs
@@ -514,7 +514,10 @@ export async function readOverview(root, specDir) {
}
// The line every CLI command hands the agent to end its terminal messages with.
-export function terminalLine(url) {
+// Under the desktop app the page is already in the window beside the terminal,
+// so the address would only be noise there: the line points at the window.
+export function terminalLine(url, env = process.env) {
+ if (env.PLAN2CODE_IN_APP === "1") return "→ Look at the dashboard beside this terminal.";
return `→ Look at the web console: ${url}`;
}
diff --git a/src/web-console/static.mjs b/src/web-console/static.mjs
index 6732f94..a0fd0ae 100644
--- a/src/web-console/static.mjs
+++ b/src/web-console/static.mjs
@@ -46,6 +46,7 @@ export const SERVABLE = new Set([
"subagents.js",
"mentions.js",
"favicon.js",
+ "app-bridge.js",
"git-board.js",
"git-board-view.js",
"pr-url.js",