diff --git a/progress/README.md b/progress/README.md index 48284e8..ef034c5 100644 --- a/progress/README.md +++ b/progress/README.md @@ -96,7 +96,7 @@ On Paseo 0.14 and later, Progress hands agents a tool for each common command, s | `progress_question_answer` | `question answer` | | `progress_deliverable_add` | `deliverable add` | | `progress_activity_add` | `activity add` | -| `progress_ticker` | `ticker set`, or `ticker clear` when the text is empty | +| `progress_ticker` | `ticker set` | | `progress_finish` | `finish` | | `paseo_progress` | Any command, given as the list of words you'd type after `paseo-progress` | @@ -125,7 +125,7 @@ for dir in ~/.agents/skills ~/.claude/skills ~/.codex/skills; do mkdir -p "$dir" ## Recording progress -Run `paseo-progress --help` for every command, and `paseo-progress --help` for one. Commands find the worktree root from the current directory. +Run `paseo-progress --help` for every command, and `paseo-progress --help` for one. Commands find the worktree root from the current directory. A Claude Code subagent that works in its own checkout under `.claude/worktrees/` records on the dashboard of the worktree its Paseo agent runs in. ```sh paseo-progress start "Loan Options snapshots" --subtitle "4 tickets" @@ -154,7 +154,7 @@ paseo-progress finish "Snapshots ship for all four tables" - Paseo keeps the question mode in its own settings, which only the plugin's server can read, so the server copies it to `~/.local/state/paseo-progress/settings.json` for the command. Without that file, for example while the plugin is off, the command uses Work around. - Deliverable paths are stored relative to the worktree root. Web links open in Paseo's browser. Pressing an image (PNG, JPEG, GIF, WebP, up to 10 MB) or text deliverable (Markdown, text, logs, JSON, YAML, CSV; the first 256 KB) previews it in a dialog inside Paseo, which also works from a phone. Markdown shows formatted, with links and images relative to the file's own folder; **Open** there opens the file in its default app. **Open** shows only when the computer running Paseo can open files. A Linux server with no desktop can't, so there a file Paseo can't preview copies its path and says why. A video (MP4, MOV, WebM, up to 200 MB) plays in the same dialog in the desktop app, and a PDF (up to 100 MB) shows there too. When there are several files, **Previous** and **Next** step through them, and so do the left and right arrow keys. Pressing a folder lists its files in the same dialog. Press a file to preview it, or a folder inside to list that one, and **Back** returns to the list. Pressing an audio file opens it with its default app on the machine running the Paseo daemon. Pressing an HTML page opens it in a Paseo tab with Paseo's own preview, on desktop and on phones, never in your browser. The preview runs the page's own scripts but loads nothing from the web, so a report needs its CSS and images inside the file. Progress hands no other file or folder to a default app, because a script or an app would run, so pressing one copies its path. On macOS, **Open** sends text files to your default browser. Previews and **Open** work only for recorded deliverables inside the worktree; for any other file the path is copied. An HTML page or PDF opens in a Paseo tab from the path the agent recorded. The copy icon on each row copies the path. - Several agents can share one run. When another session adds a ticket, each agent sees it at the end of its next command's output (and in `show`), and the skill has it work that ticket in order after its current one. An agent only hears about tickets added since its own last update in the run, and only once. -- Subagents record their own progress. A Claude Code subagent can call the Progress tools too, and its updates carry its parent chat's agent id. Since Paseo 0.11, an agent waiting on background subagents shows as idle, so only the subagents' updates show the work is still going. The skill has the agent give each subagent the worktree path and ticket id, and the subagent records its stages and a ticker line on that worktree's dashboard. +- Subagents record their own progress. A Claude Code subagent can call the Progress tools too, and its updates carry its parent chat's agent id. Since Paseo 0.11, an agent waiting on background subagents shows as idle, so only the subagents' updates show the work is still going. The skill has the agent give each subagent its ticket id, and the subagent records its stages and a ticker line on the agent's dashboard. - `start` begins a fresh dashboard. Earlier runs stay in the file. Question references stay unique across runs. - `finish ""` closes the run once every ticket is done or skipped, no question is open, and nothing is flagged stuck; otherwise it says what is left. The run stays on the dashboard, marked Finished with its outcome, and takes no more updates, so the next agent in the worktree starts a new run instead of adding to it. @@ -178,6 +178,12 @@ The progress file, `progress.jsonl`, holds one JSON event per line, each with a ## Changelog +### 1.14.7 + +- [Fixed] **Subagents record progress from their own folder.** Claude Code can give a subagent its own copy of the repo. To record progress from there, the subagent had to switch to its agent's worktree first, and Claude Code refused the command whenever it also ran git. The `paseo-progress` command now sends a subagent's progress to its agent's dashboard from the subagent's own folder, and the skill no longer tells subagents to switch folders. +- [Fixed] **A step can start in a stage.** Agents often add a step that is already under way and name its stage in the same call. Progress refused the stage, the step was never added, and every later step that waited for it failed too. `paseo-progress ticket add` and the Add ticket tool now take a stage. +- [Fixed] **An empty ticker hides it from the command too.** `paseo-progress ticker set ""` asked for text, though the ticker tool hides the line when it gets `""`. Both now hide it. + ### 1.14.6 - [Fixed] **The Progress pill spins only while work is happening.** It used to show a spinner until you first opened the panel, even after every ticket was done or the agent had stopped. Now it spins while an agent in the worktree is running and tickets are left, and shows the checklist icon otherwise. On phones, the pill that stays above the message box follows the same rule. diff --git a/progress/package-lock.json b/progress/package-lock.json index 546d469..aa48f94 100644 --- a/progress/package-lock.json +++ b/progress/package-lock.json @@ -1,12 +1,12 @@ { "name": "@stevecastaneda/paseo-progress", - "version": "1.14.6", + "version": "1.14.7", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@stevecastaneda/paseo-progress", - "version": "1.14.6", + "version": "1.14.7", "license": "MIT", "devDependencies": { "@getpaseo/client": "0.14.0", diff --git a/progress/package.json b/progress/package.json index 8215e0f..416f11f 100644 --- a/progress/package.json +++ b/progress/package.json @@ -1,6 +1,6 @@ { "name": "@stevecastaneda/paseo-progress", - "version": "1.14.6", + "version": "1.14.7", "description": "A live progress dashboard per worktree for Paseo, drawn from a file agents write with the Progress tools or the paseo-progress command.", "keywords": [ "coding-agents", diff --git a/progress/server/cli.ts b/progress/server/cli.ts index 732f589..2b2b138 100644 --- a/progress/server/cli.ts +++ b/progress/server/cli.ts @@ -8,7 +8,7 @@ import { isSettled, type Dashboard, type NextIds, type Ticket } from "../shared/ import { DELIVERABLE_KINDS, TICKET_STATUSES, type FileLink, type ProgressEvent } from "../shared/events.ts"; import { QUESTION_MODE_RULES, type QuestionMode } from "../shared/question-modes.ts"; import { appendProgress, InvalidEvent, readLatestRun, readProgress, type EventDraft } from "./progress-file.ts"; -import { findRoot, outside } from "./paths.ts"; +import { outside, progressRoot } from "./paths.ts"; import { installLauncher } from "./launcher.ts"; import { findStore, saveRunCopy } from "./store.ts"; import { readQuestionMode } from "./question-mode.ts"; @@ -23,6 +23,7 @@ export interface CliOptions { out?: (line: string) => void; // The Paseo agent running the command, recorded on each event it writes. agentId?: string; + agentCwd?: string; } class UsageError extends Error {} @@ -188,6 +189,10 @@ function shown(value: unknown) { return typeof value === "object" ? ((value as FileLink).path ?? (value as FileLink).url) : value; } +function clearTicker() { + return { event: { type: "ticker.clear" as const }, message: "Ticker cleared" }; +} + const commands: Record = { start: { usage: `start "" [--subtitle <text>] [--item-label <word>]`, @@ -214,20 +219,27 @@ const commands: Record<string, Command> = { }, }, "ticket add": { - usage: `ticket add "<title>" --estimate <minutes> [--status <status>] [--waits-for <id>] [--source <path or http(s) URL>[=<label>]]`, + usage: `ticket add "<title>" --estimate <minutes> [--status <status>] [--stage <name>] [--waits-for <id>] [--source <path or http(s) URL>[=<label>]]`, summary: - "Add a ticket. Prints its id (T01, T02, ...). --waits-for names a ticket it can't start before; that is the order of work, not a blocker. --source is where the ticket is written up, like its spec file or issue link.", - options: { estimate: { type: "string" }, status: { type: "string" }, "waits-for": { type: "string" }, source: { type: "string" } }, + "Add a ticket. Prints its id (T01, T02, ...). --stage names the step in progress when it starts as working, like Build. --waits-for names a ticket it can't start before; that is the order of work, not a blocker. --source is where the ticket is written up, like its spec file or issue link.", + options: { + estimate: { type: "string" }, + status: { type: "string" }, + stage: { type: "string" }, + "waits-for": { type: "string" }, + source: { type: "string" }, + }, run({ positionals, values, state, cwd, root }) { const waitsFor = values["waits-for"] === undefined ? undefined : existingTicket(state, stringOption(values["waits-for"])).id; const title = required(positionals[0], "ticket title"); const estimateMin = minutesOption(values.estimate, "estimate"); if (estimateMin === undefined) throw new UsageError("Missing --estimate <minutes>."); const source = values.source === undefined ? undefined : parseFile(String(values.source), cwd, root); + const stage = stringOption(values.stage)?.trim() || undefined; const id = state.nextIds.ticket; return { - event: { type: "ticket.add", id, title, estimateMin, status: statusOption(values.status), waitsFor, source }, - message: `Added ${id}: ${title} (${formatMinutes(estimateMin)})${waitsFor ? `, waits for ${waitsFor}` : ""}${source ? `, source ${source.path ?? source.url}` : ""}`, + event: { type: "ticket.add", id, title, estimateMin, status: statusOption(values.status), stage, waitsFor, source }, + message: `Added ${id}: ${title} (${formatMinutes(estimateMin)})${stage ? `, stage ${stage}` : ""}${waitsFor ? `, waits for ${waitsFor}` : ""}${source ? `, source ${source.path ?? source.url}` : ""}`, }; }, }, @@ -466,8 +478,9 @@ const commands: Record<string, Command> = { }, "ticker set": { usage: `ticker set "<text>"`, - summary: "Show one line at the top saying what you are doing right now.", + summary: 'Show one line at the top saying what you are doing right now. Pass "" to hide it.', run({ positionals }) { + if (positionals[0]?.trim() === "") return clearTicker(); const text = required(positionals[0], "ticker text"); return { event: { type: "ticker.set", text }, message: `Ticker: ${text}` }; }, @@ -475,9 +488,7 @@ const commands: Record<string, Command> = { "ticker clear": { usage: `ticker clear`, summary: "Hide the ticker line.", - run() { - return { event: { type: "ticker.clear" }, message: "Ticker cleared" }; - }, + run: clearTicker, }, "stuck set": { usage: `stuck set "<reason>" [--ticket <id>]`, @@ -564,7 +575,7 @@ export async function runCli(argv: string[], options: CliOptions): Promise<numbe return 0; } if (first === "show") { - const root = findRoot(options.cwd); + const root = progressRoot(options.cwd, options.agentCwd); const store = await findStore(root); const { dashboard } = await readProgress(store.directory, now()); const added = addedByOthersText(addedByOthers(await readLatestRun(store.directory), dashboard, options.agentId), dashboard); @@ -593,7 +604,7 @@ export async function runCli(argv: string[], options: CliOptions): Promise<numbe } catch (error) { throw new UsageError((error as Error).message); } - const root = findRoot(options.cwd); + const root = progressRoot(options.cwd, options.agentCwd); const store = await findStore(root); const mode = await readQuestionMode(); const message = await appendProgress( @@ -631,7 +642,11 @@ function isMain(): boolean { } if (isMain()) { - runCli(process.argv.slice(2), { cwd: process.cwd(), agentId: process.env.PASEO_AGENT_ID || undefined }).then( + runCli(process.argv.slice(2), { + cwd: process.cwd(), + agentId: process.env.PASEO_AGENT_ID || undefined, + agentCwd: process.env.PASEO_AGENT_CWD || undefined, + }).then( (code) => { process.exitCode = code; }, diff --git a/progress/server/paths.ts b/progress/server/paths.ts index bd8f744..80b4fff 100644 --- a/progress/server/paths.ts +++ b/progress/server/paths.ts @@ -1,5 +1,5 @@ import { existsSync } from "node:fs"; -import { dirname, isAbsolute, join, resolve, sep } from "node:path"; +import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path"; // Whether a path from relative(root, target) leaves the root. "..notes" is a // name inside it, not a step out. @@ -32,3 +32,15 @@ export function findRoot(cwd: string): string { directory = parent; } } + +// The worktree a command records progress for. Claude Code gives an isolated +// subagent its own checkout at .claude/worktrees/<name>, in the repo's main +// checkout unless a WorktreeCreate hook moves it. The user watches the +// dashboard of the Paseo agent's workspace, which Paseo names in +// PASEO_AGENT_CWD, so progress from a subagent's checkout goes there. +export function progressRoot(cwd: string, agentCwd: string | undefined): string { + const root = findRoot(cwd); + const folder = dirname(root); + const subagentCheckout = basename(folder) === "worktrees" && basename(dirname(folder)) === ".claude"; + return agentCwd && subagentCheckout ? findRoot(agentCwd) : root; +} diff --git a/progress/server/progress.test.ts b/progress/server/progress.test.ts index 78f2d59..3f757b6 100644 --- a/progress/server/progress.test.ts +++ b/progress/server/progress.test.ts @@ -415,6 +415,66 @@ test("commands find the worktree root from a subdirectory", async (t) => { assert.equal((await w.dashboard()).dashboard.run?.title, "From below"); }); +async function checkout(parent: string, ...folders: string[]) { + const directory = join(parent, ...folders); + await mkdir(join(directory, "shots"), { recursive: true }); + await git(directory, "init", "-q"); + await writeFile(join(directory, "shots", "after.png"), ""); + return directory; +} + +// Claude Code refuses an isolated subagent's command that changes to the +// agent's workspace and then runs git, so the subagent records from where it is. +test("a subagent in its own checkout records on its agent's dashboard", async (t) => { + const w = await worktree(t); + const main = await worktree(t); + const output: string[] = []; + const runIn = (cwd: string, agentCwd: string | undefined, ...argv: string[]) => + runCli(argv, { cwd, agentCwd, now: () => minutes(0), out: (line) => output.push(line) }); + const inWorkspace = await checkout(w.directory, ".claude", "worktrees", "agent-1"); + const inMainCheckout = await checkout(main.directory, ".claude", "worktrees", "agent-2"); + const vendored = await checkout(w.directory, "vendor", "library"); + await w.run("start", "Run"); + await w.run("ticket", "add", "Ticket 01: Button", "--estimate", "30"); + + assert.equal(await runIn(inWorkspace, w.directory, "ticket", "update", "T01", "--stage", "Build"), 0, output.join("\n")); + assert.equal(await runIn(inWorkspace, w.directory, "deliverable", "add", "After", "shots/after.png"), 0, output.join("\n")); + assert.equal(await runIn(inMainCheckout, w.directory, "ticker", "set", "Reviewing"), 0, output.join("\n")); + const { dashboard } = await w.dashboard(); + assert.equal(dashboard.tickets[0].stage, "Build"); + assert.equal( + dashboard.deliverables[0].path, + join(".claude", "worktrees", "agent-1", "shots", "after.png"), + "a path from the checkout opens from the workspace", + ); + assert.equal(dashboard.ticker?.text, "Reviewing"); + output.length = 0; + await runIn(inMainCheckout, w.directory, "show"); + assert.equal(output.join("\n").split("\n")[0], `Worktree: ${w.directory}`); + + assert.equal(await runIn(vendored, w.directory, "start", "Another repo"), 0, "a checkout that isn't a subagent's keeps its own dashboard"); + assert.equal(await runIn(inMainCheckout, undefined, "start", "Outside Paseo"), 0, "so does a subagent's checkout outside Paseo"); + assert.equal((await readProgress(outsideDirectory(vendored), minutes(0))).dashboard.run?.title, "Another repo"); + assert.equal((await readProgress(outsideDirectory(inMainCheckout), minutes(0))).dashboard.run?.title, "Outside Paseo"); + assert.equal((await w.dashboard()).dashboard.run?.title, "Run"); +}); + +test("a ticket can start in a stage, and an empty ticker hides it", async (t) => { + const w = await worktree(t); + await w.run("start", "Run"); + const added = await w.run("ticket", "add", "Step 01: Reproduce it", "--estimate", "20", "--status", "working", "--stage", "Verify"); + assert.equal(added.text, "Added T01: Step 01: Reproduce it (20m), stage Verify"); + const [ticket] = (await w.dashboard()).dashboard.tickets; + assert.deepEqual( + { stage: ticket.stage, stageSince: ticket.stageSince, history: ticket.history }, + { stage: "Verify", stageSince: minutes(0).toISOString(), history: [{ at: minutes(0).toISOString(), status: "working", stage: "Verify" }] }, + ); + await w.run("ticker", "set", "Reproducing"); + assert.equal((await w.run("ticker", "set", "")).text, "Ticker cleared"); + assert.equal((await w.dashboard()).dashboard.ticker, null); + assert.match((await w.run("ticker", "set")).text, /^Missing ticker text\./); +}); + // A Paseo project registered at a subfolder of the repo: the workspace // directory is <worktree>/apps/client, but the agent writes at the root. test("a workspace below the worktree root reads the root's progress and attachments", async (t) => { diff --git a/progress/server/tool.test.ts b/progress/server/tool.test.ts index 30268c7..11e0fa9 100644 --- a/progress/server/tool.test.ts +++ b/progress/server/tool.test.ts @@ -245,6 +245,14 @@ test("the note after a question names the answer tool's fields", () => { for (const field of fields) assert.match(ANSWER_NOTE, new RegExp(`\\b${field} is `)); }); +test("a ticket added through the tool can start in a stage", async (t) => { + const w = await worktree(t); + await w.call("progress_start", { title: "Bug" }); + const added = await w.call("progress_ticket_add", { title: "Step 01: Reproduce it", estimateMinutes: 20, status: "working", stage: "Verify" }); + assert.equal(added.text, "Added T01: Step 01: Reproduce it (20m), stage Verify"); + assert.equal((await w.dashboard()).tickets[0].stage, "Verify"); +}); + test("the skill loads every tool in one search", async () => { const skill = await readFile(new URL("../skills/paseo-progress/SKILL.md", import.meta.url), "utf8"); const query = /^select:(.+)$/m.exec(skill)?.[1].split(","); diff --git a/progress/server/tool.ts b/progress/server/tool.ts index ad4c1fd..3c786b4 100644 --- a/progress/server/tool.ts +++ b/progress/server/tool.ts @@ -47,10 +47,10 @@ function toolSummary(command: string): string { ); } -function commandTool<Input extends z.ZodType>(title: string, command: string, input: Input, args: (input: z.output<Input>) => string[], extra = "") { +function commandTool<Input extends z.ZodType>(title: string, command: string, input: Input, args: (input: z.output<Input>) => string[]) { return agentTool({ title: `Progress: ${title}`, - description: `Progress dashboard for this worktree in Paseo. ${toolSummary(command)}${extra}`, + description: `Progress dashboard for this worktree in Paseo. ${toolSummary(command)}`, input, execute: (value, context) => run(args(value), context), }); @@ -95,11 +95,12 @@ const tools: Record<ProgressToolName, Tool> = { title: z.string().describe('Like "Ticket 01: Export button"'), estimateMinutes: estimate, status: ticketStatusSchema.optional(), + stage: z.string().optional().describe("The step in progress when it starts as working, like Build"), waitsFor: ticketId("A ticket this one can't start before").optional(), source: ticketSource.optional(), }), - ({ title, estimateMinutes, status, waitsFor, source }) => - commandArgs("ticket add", [title], { estimate: estimateMinutes, status, "waits-for": waitsFor, source }), + ({ title, estimateMinutes, status, stage, waitsFor, source }) => + commandArgs("ticket add", [title], { estimate: estimateMinutes, status, stage, "waits-for": waitsFor, source }), ), progress_ticket_update: commandTool( "Update ticket", @@ -183,13 +184,7 @@ const tools: Record<ProgressToolName, Tool> = { z.object({ text: z.string(), ticket: ticketId("The ticket it's about").optional() }), ({ text, ticket }) => commandArgs("activity add", [text], { ticket }), ), - progress_ticker: commandTool( - "Set ticker", - "ticker set", - z.object({ text: z.string() }), - ({ text }) => (text.trim() ? commandArgs("ticker set", [text]) : commandArgs("ticker clear", [])), - ' Pass "" to hide it.', - ), + progress_ticker: commandTool("Set ticker", "ticker set", z.object({ text: z.string() }), ({ text }) => commandArgs("ticker set", [text])), progress_finish: commandTool("Finish run", "finish", z.object({ outcome: z.string().describe("One line") }), ({ outcome }) => commandArgs("finish", [outcome]), ), diff --git a/progress/shared/dashboard.ts b/progress/shared/dashboard.ts index d6edf47..08778fc 100644 --- a/progress/shared/dashboard.ts +++ b/progress/shared/dashboard.ts @@ -265,7 +265,9 @@ export function reduceProgress( status: event.status ?? "not_started", statusSince: event.ts, workingSince: event.status === "working" ? event.ts : undefined, - history: [{ at: event.ts, status: event.status ?? "not_started" }], + stage: event.stage, + stageSince: event.stage ? event.ts : undefined, + history: [{ at: event.ts, status: event.status ?? "not_started", ...(event.stage ? { stage: event.stage } : {}) }], waitsFor: event.waitsFor, source: event.source, agentId: event.by, diff --git a/progress/shared/events.ts b/progress/shared/events.ts index 2d3dccf..742c9f0 100644 --- a/progress/shared/events.ts +++ b/progress/shared/events.ts @@ -52,6 +52,7 @@ export const eventSchema = z.discriminatedUnion("type", [ title: text, estimateMin: minutes, status: ticketStatusSchema.optional(), + stage: text.optional(), // Another ticket in the run this one can't start until it's done. waitsFor: text.optional(), // Where the ticket is written up: a spec file or an issue link. diff --git a/progress/skills/paseo-progress/SKILL.md b/progress/skills/paseo-progress/SKILL.md index 14126a9..b2aeee4 100644 --- a/progress/skills/paseo-progress/SKILL.md +++ b/progress/skills/paseo-progress/SKILL.md @@ -41,16 +41,16 @@ Move each ticket through `--status working --stage Build`, then the stages `Revi - A ticket past its estimate with no update turns stuck. Keep its stage current, or raise its `--estimate`. - A ticket another session adds is part of the plan. Work it in order. - `--status blocked` and `stuck set` are for things outside the run, like a service that's down or missing access. -- Put this in a subagent's prompt, with the worktree path and ticket id filled in. While you wait on it, its updates are the dashboard's only sign the work is moving: +- Put this in a subagent's prompt, with the ticket id filled in. While you wait on it, its updates are the dashboard's only sign the work is moving: ```text Record progress on the Paseo dashboard as you work. Use the Progress tools if you have them (search your tools for progress_), otherwise the paseo-progress command. If a tool call says the tool isn't found, use the command for the rest of that reply. - at each new stage: progress_ticket_update with id T03 and stage <stage>, - or: cd <worktree> && paseo-progress ticket update T03 --stage <stage> + or: paseo-progress ticket update T03 --stage <stage> - between stages: progress_ticker with "<what you are doing now>", - or: cd <worktree> && paseo-progress ticker set "<what you are doing now>" + or: paseo-progress ticker set "<what you are doing now>" ``` Done when every ticket is done or skipped, or waits on a question.