live todo tracking, collapsible task list in final progress, hide set_output outside standalone (#492)
* fix false "without reporting progress" error + live todo tracking clean up orphaned progress comments when review is skipped or only set_output is used, preventing the false positive in handleAgentResult. parse todowrite events from OpenCode's NDJSON stream and render a live markdown checklist in the PR progress comment (2s debounce). agent's explicit report_progress always takes priority. Made-with: Cursor * fix contradictory review/progress prompting align Review and IncrementalReview mode prompts with their guidance — mode prompts said "always submit" while guidance said "skip if clean." remove the empty-approval submission that was silently dropped by the tool. make progress comment lifecycle explicit: created on first call, updated in place, removed after review submission. Made-with: Cursor * centralize todo tracking into shared TodoTracker module extract inline todo tracking logic (~95 lines) from opentoad.ts into action/utils/todoTracking.ts. the tracker is created once in main.ts and passed to agents via AgentRunContext.todoTracker, making it agent-agnostic and reusable for future agent implementations. Made-with: Cursor * fix todoTracker optional type to match file convention add | undefined to todoTracker in AgentRunContext, matching every other optional property in the same interface. Made-with: Cursor * instruct agents to always maintain a task list for live progress system prompt now tells agents to create an internal task list at the start of every run. the tracker renders it to the progress comment automatically. report_progress is reserved for final results only — no more intermediate "Checking..." messages that cancel the tracker and leave stale text on the comment. Made-with: Cursor * require report_progress summary at end of every run agents must always call report_progress with a final summary — the completed task list should never be the end state of the progress comment. updated all review mode prompts to call report_progress after submitting (or not submitting) a review. Made-with: Cursor * keep progress comment after review with final summary stop deleting the progress comment after review submission — the agent now always calls report_progress with a summary at the end, and that summary should persist as a record of what was done. Made-with: Cursor * harden stranded progress comment cleanup - main.ts: detect when tracker was last writer (agent never called report_progress) and delete the stranded checklist instead of leaving it as the final comment state - postCleanup.ts: expand stuck-comment detection to also catch stranded todo checklists (regex match for checklist patterns) when the process is killed before normal cleanup runs - modes.ts + selectMode.ts: add report_progress step to Summarize and SummaryUpdate modes (only modes that were missing it) Made-with: Cursor * fix stale comments, typo, and build mode redundancy - comment.ts: update deleteProgressComment docstring and inline comment to reflect current usage (stranded-comment cleanup, not post-review) - modes.ts: merge duplicate report_progress steps (8 + 10) into single step 9, fix "optimizatfixons" typo - wiki/post-cleanup.md: document checklist detection regex Made-with: Cursor * collapsible completed todos in final progress, hide set_output outside standalone mode - add renderCollapsible() to TodoTracker, append completed task list as <details> section when agent calls report_progress - cancel tracker after agent's final report_progress so it doesn't overwrite with raw checklist - conditionally register SetOutputTool only in standalone mode or when output_schema is provided - remove unconditional set_output instruction from orchestrator task section - update Summarize/SummaryUpdate mode guidance to not reference set_output Made-with: Cursor * show completion count in collapsible task list summary Made-with: Cursor * only count completed (not cancelled) in collapsible task list summary Made-with: Cursor * reinforce concise summary prompting across system prompt, modes, and tool description Made-with: Cursor * address review feedback: wasUpdated bypass, tracker false-positive, race condition - remove wasUpdated=true from cleanup paths so handleAgentResult correctly detects genuinely silent runs - add hadProgressComment to ToolState as immutable snapshot for the safety check - use todoTracker.hasPublished instead of enabled for stranded-comment cleanup - serialize onUpdate calls via inflightPromise chain with post-cancel guard - add settled() to wait for in-flight updates before writing final summary Made-with: Cursor * address round-2 review: hasPublished after success, finalSummaryWritten flag - set hasPublished only after onUpdate resolves (not before) so failed writes are not counted as published - add finalSummaryWritten flag to ToolState, set after successful non-plan reportProgress; decouple cleanup detection from todoTracker.enabled so it survives API failures where cancel() ran but the write didn't succeed Made-with: Cursor
This commit is contained in:
David Blass
committed by
pullfrog[bot]
pullfrog[bot]
parent
e9ce67fec6
commit
6b18b6730b
@@ -21,6 +21,7 @@ import { log } from "../utils/cli.ts";
|
||||
import { installFromNpmTarball } from "../utils/install.ts";
|
||||
import { spawn } from "../utils/subprocess.ts";
|
||||
import { ThinkingTimer } from "../utils/timer.ts";
|
||||
import type { TodoTracker } from "../utils/todoTracking.ts";
|
||||
import { type AgentResult, type AgentRunContext, type AgentUsage, agent } from "./shared.ts";
|
||||
|
||||
// pinned CLI version
|
||||
@@ -294,6 +295,7 @@ type RunParams = {
|
||||
args: string[];
|
||||
cwd: string;
|
||||
env: Record<string, string | undefined>;
|
||||
todoTracker?: TodoTracker | undefined;
|
||||
};
|
||||
|
||||
async function runOpenCode(params: RunParams): Promise<AgentResult> {
|
||||
@@ -394,6 +396,17 @@ async function runOpenCode(params: RunParams): Promise<AgentResult> {
|
||||
if (event.part?.state?.status === "completed" && event.part.state.output) {
|
||||
log.debug(` output: ${event.part.state.output}`);
|
||||
}
|
||||
|
||||
// agent's explicit MCP report_progress takes priority over todo tracking
|
||||
if (toolName.includes("report_progress") && params.todoTracker) {
|
||||
log.debug("» report_progress detected, disabling todo tracking");
|
||||
params.todoTracker.cancel();
|
||||
}
|
||||
|
||||
// parse todowrite events for live progress tracking
|
||||
if (toolName === "todowrite" && params.todoTracker?.enabled) {
|
||||
params.todoTracker.update(event.part?.state?.input);
|
||||
}
|
||||
},
|
||||
tool_result: (event: OpenCodeToolResultEvent) => {
|
||||
const toolId = event.part?.callID || event.tool_id;
|
||||
@@ -535,6 +548,12 @@ async function runOpenCode(params: RunParams): Promise<AgentResult> {
|
||||
},
|
||||
});
|
||||
|
||||
if (result.exitCode === 0) {
|
||||
await params.todoTracker?.flush();
|
||||
} else {
|
||||
params.todoTracker?.cancel();
|
||||
}
|
||||
|
||||
const duration = performance.now() - startTime;
|
||||
log.info(
|
||||
`» ${params.label} completed in ${Math.round(duration)}ms with exit code ${result.exitCode}`
|
||||
@@ -588,6 +607,7 @@ async function runOpenCode(params: RunParams): Promise<AgentResult> {
|
||||
|
||||
return { success: true, output: finalOutput || output, usage };
|
||||
} catch (error) {
|
||||
params.todoTracker?.cancel();
|
||||
const duration = performance.now() - startTime;
|
||||
const errorMessage = error instanceof Error ? error.message : String(error);
|
||||
const isActivityTimeout = errorMessage.includes("activity timeout");
|
||||
@@ -659,6 +679,7 @@ export const opentoad = agent({
|
||||
args,
|
||||
cwd: repoDir,
|
||||
env,
|
||||
todoTracker: ctx.todoTracker,
|
||||
});
|
||||
},
|
||||
});
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
import { log } from "../utils/cli.ts";
|
||||
import type { ResolvedInstructions } from "../utils/instructions.ts";
|
||||
import type { ResolvedPayload } from "../utils/payload.ts";
|
||||
import type { TodoTracker } from "../utils/todoTracking.ts";
|
||||
|
||||
/**
|
||||
* token/cost usage data from a single agent run
|
||||
@@ -33,6 +34,7 @@ export interface AgentRunContext {
|
||||
mcpServerUrl: string;
|
||||
tmpdir: string;
|
||||
instructions: ResolvedInstructions;
|
||||
todoTracker?: TodoTracker | undefined;
|
||||
}
|
||||
|
||||
export interface Agent {
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
// changes to tool permissions should be reflected in wiki/granular-tools.md
|
||||
|
||||
import * as core from "@actions/core";
|
||||
import { deleteProgressComment, reportProgress } from "./mcp/comment.ts";
|
||||
import {
|
||||
initToolState,
|
||||
startMcpHttpServer,
|
||||
@@ -35,6 +36,7 @@ import { createTempDirectory, setupGit } from "./utils/setup.ts";
|
||||
import { killTrackedChildren } from "./utils/subprocess.ts";
|
||||
import { parseTimeString, TIMEOUT_DISABLED } from "./utils/time.ts";
|
||||
import { Timer } from "./utils/timer.ts";
|
||||
import { createTodoTracker } from "./utils/todoTracking.ts";
|
||||
import { getJobToken, resolveTokens } from "./utils/token.ts";
|
||||
import { resolveRun } from "./utils/workflow.ts";
|
||||
|
||||
@@ -203,6 +205,8 @@ export async function main(): Promise<MainResult> {
|
||||
|
||||
const runInfo = await resolveRun({ octokit });
|
||||
let toolContext: ToolContext | undefined;
|
||||
let progressCallbackDisabled = false;
|
||||
let todoTracker: ReturnType<typeof createTodoTracker> | undefined;
|
||||
|
||||
try {
|
||||
if (payload.cwd && process.cwd() !== payload.cwd) {
|
||||
@@ -309,11 +313,22 @@ export async function main(): Promise<MainResult> {
|
||||
checkIntervalMs: DEFAULT_ACTIVITY_CHECK_INTERVAL_MS,
|
||||
});
|
||||
activityTimeout.promise.catch(() => {}); // prevent unhandled rejection if agent wins race
|
||||
todoTracker = createTodoTracker(async (body) => {
|
||||
if (progressCallbackDisabled || !toolContext) return;
|
||||
try {
|
||||
await reportProgress(toolContext, { body });
|
||||
} catch (err) {
|
||||
log.debug(`progress update failed: ${err}`);
|
||||
}
|
||||
});
|
||||
toolState.todoTracker = todoTracker;
|
||||
|
||||
const agentPromise = agent.run({
|
||||
payload,
|
||||
mcpServerUrl: mcpHttpServer.url,
|
||||
tmpdir,
|
||||
instructions,
|
||||
todoTracker,
|
||||
});
|
||||
|
||||
// timeout enforcement: default is 1 hour, but can be overridden via flags in the prompt:
|
||||
@@ -355,7 +370,7 @@ export async function main(): Promise<MainResult> {
|
||||
);
|
||||
}
|
||||
|
||||
// post-agent review cleanup: reportReviewNodeId → follow-up dispatch → delete progress comment.
|
||||
// post-agent review cleanup: reportReviewNodeId → follow-up re-review dispatch.
|
||||
// runs after the agent exits so ordering is architecturally guaranteed (no LLM involvement).
|
||||
// best-effort: cleanup failures must not turn a successful agent run into a failure.
|
||||
if (toolContext) {
|
||||
@@ -364,6 +379,25 @@ export async function main(): Promise<MainResult> {
|
||||
});
|
||||
}
|
||||
|
||||
// clean up stranded progress comments. two cases:
|
||||
// 1. wasUpdated=false: nothing wrote to the comment ("Leaping into action" orphan)
|
||||
// 2. tracker published a checklist but the agent never wrote a final summary
|
||||
// (hasPublished=true, finalSummaryWritten=false).
|
||||
// in both cases, delete the comment so it doesn't linger with stale content.
|
||||
// wasUpdated is intentionally NOT set here — cleanup is not a real progress update.
|
||||
// uses finalSummaryWritten (not todoTracker.enabled) so cleanup survives API failures
|
||||
// in report_progress where cancel() ran but the write didn't succeed.
|
||||
const trackerWasLastWriter = todoTracker?.hasPublished && !toolState.finalSummaryWritten;
|
||||
if (
|
||||
toolContext &&
|
||||
toolState.progressCommentId &&
|
||||
(!toolState.wasUpdated || trackerWasLastWriter)
|
||||
) {
|
||||
await deleteProgressComment(toolContext).catch((error) => {
|
||||
log.debug(`stranded progress comment cleanup failed: ${error}`);
|
||||
});
|
||||
}
|
||||
|
||||
await writeJobSummary(toolState);
|
||||
|
||||
// emit structured output marker for test validation
|
||||
@@ -379,6 +413,8 @@ export async function main(): Promise<MainResult> {
|
||||
});
|
||||
} catch (error) {
|
||||
const errorMessage = error instanceof Error ? error.message : "unknown error occurred";
|
||||
progressCallbackDisabled = true;
|
||||
todoTracker?.cancel();
|
||||
killTrackedChildren();
|
||||
log.error(errorMessage);
|
||||
|
||||
|
||||
+23
-8
@@ -329,7 +329,7 @@ export async function reportProgress(
|
||||
};
|
||||
}
|
||||
|
||||
// null = progress comment was deliberately deleted (e.g. by create_pull_request_review)
|
||||
// null = progress comment was deleted by stranded-comment cleanup in main.ts
|
||||
if (existingCommentId === null) {
|
||||
return { body, action: "skipped" };
|
||||
}
|
||||
@@ -400,17 +400,33 @@ export function ReportProgressTool(ctx: ToolContext) {
|
||||
return tool({
|
||||
name: "report_progress",
|
||||
description:
|
||||
"Share progress on the associated GitHub issue/PR. Call this to post updates as you work. The first call creates a comment, subsequent calls update it. Use this throughout your work to keep stakeholders informed.",
|
||||
"Share progress on the associated GitHub issue/PR. The first call creates a comment; subsequent calls update it in place. You MUST call this at the end of every run with a brief final summary (1-3 sentences). The completed task list is automatically appended in a collapsible section — do not restate individual steps.",
|
||||
parameters: ReportProgress,
|
||||
execute: execute(async (params) => {
|
||||
const reportParams: { body: string; target_plan_comment?: boolean } = { body: params.body };
|
||||
let body = params.body;
|
||||
|
||||
// for non-plan calls: stop auto-updates, wait for in-flight writes to settle,
|
||||
// then append completed task list collapsible
|
||||
if (!params.target_plan_comment && ctx.toolState.todoTracker) {
|
||||
ctx.toolState.todoTracker.cancel();
|
||||
await ctx.toolState.todoTracker.settled();
|
||||
const collapsible = ctx.toolState.todoTracker.renderCollapsible();
|
||||
if (collapsible) {
|
||||
body = `${body}\n\n${collapsible}`;
|
||||
}
|
||||
}
|
||||
|
||||
const reportParams: { body: string; target_plan_comment?: boolean } = { body };
|
||||
if (params.target_plan_comment !== undefined) {
|
||||
reportParams.target_plan_comment = params.target_plan_comment;
|
||||
}
|
||||
const result = await reportProgress(ctx, reportParams);
|
||||
|
||||
if (!params.target_plan_comment) {
|
||||
ctx.toolState.finalSummaryWritten = true;
|
||||
}
|
||||
|
||||
if (result.action === "skipped") {
|
||||
// no-op: no comment target, but progress is still tracked for job summary
|
||||
return {
|
||||
success: true,
|
||||
message:
|
||||
@@ -428,9 +444,9 @@ export function ReportProgressTool(ctx: ToolContext) {
|
||||
|
||||
/**
|
||||
* Delete the progress comment if it exists.
|
||||
* Used after submitting a PR review since the review body contains all necessary info.
|
||||
* Sets progressCommentId to null, which prevents future report_progress calls from
|
||||
* creating a new comment (the agent may call report_progress again after this).
|
||||
* Used by main.ts for stranded-comment cleanup (orphaned "Leaping into action" or
|
||||
* checklist left by the todo tracker when the agent didn't call report_progress).
|
||||
* Sets progressCommentId to null so subsequent report_progress calls are no-ops.
|
||||
*/
|
||||
export async function deleteProgressComment(ctx: ToolContext): Promise<boolean> {
|
||||
const existingCommentId = ctx.toolState.progressCommentId;
|
||||
@@ -455,7 +471,6 @@ export async function deleteProgressComment(ctx: ToolContext): Promise<boolean>
|
||||
|
||||
// set to null (not undefined) so report_progress skips instead of creating a new comment
|
||||
ctx.toolState.progressCommentId = null;
|
||||
ctx.toolState.wasUpdated = true;
|
||||
|
||||
return true;
|
||||
}
|
||||
|
||||
@@ -70,6 +70,7 @@ export function CreatePullRequestReviewTool(ctx: ToolContext) {
|
||||
description:
|
||||
"Submit a review for an existing pull request. " +
|
||||
"Each call creates a permanent, visible review on the PR — NEVER submit test or diagnostic reviews. " +
|
||||
"Reviews with no body AND no comments are silently skipped (nothing to post). " +
|
||||
"IMPORTANT: 95%+ of feedback should be in 'comments' array with file paths and line numbers. " +
|
||||
"Only use 'body' for a 1-2 sentence summary with urgency and critical callouts. " +
|
||||
"Use 'suggestion' to propose replacement code - MUST preserve exact indentation of original code. " +
|
||||
|
||||
+10
-10
@@ -111,10 +111,9 @@ ${learningsStep(6)}`,
|
||||
|
||||
3. Self-critique: review all drafted comments and drop any that are praise, style preferences, speculative/unverified claims, about pre-existing code unrelated to the PR, or not actionable.
|
||||
|
||||
4. Submit a **single** review:
|
||||
- call \`${ghPullfrogMcpName}/create_pull_request_review\` with all comments and a unified summary body
|
||||
- call \`${ghPullfrogMcpName}/report_progress\` with the summary
|
||||
- if no actionable issues found, skip the review — just call \`report_progress\` noting the PR was reviewed`,
|
||||
4. Submit:
|
||||
- **actionable issues found**: call \`${ghPullfrogMcpName}/create_pull_request_review\` with all comments, a 1-3 sentence summary body, and \`approved: false\`. Then call \`report_progress\` with a 1-sentence summary.
|
||||
- **no actionable issues found**: do NOT submit a review. Call \`${ghPullfrogMcpName}/report_progress\` with a brief note (e.g., "Reviewed — no issues found.").`,
|
||||
|
||||
IncrementalReview: `### Checklist
|
||||
|
||||
@@ -134,10 +133,9 @@ ${learningsStep(6)}`,
|
||||
|
||||
5. Self-critique: drop any comments that are praise, style preferences, speculative, about pre-existing code, or not actionable.
|
||||
|
||||
6. Submit a **single** review:
|
||||
- if actionable issues found: call \`${ghPullfrogMcpName}/create_pull_request_review\` with \`approved: false\`, all comments, and an **empty body** (do NOT include a summary — inline comments speak for themselves and a top-level comment clutters the PR conversation on every re-review)
|
||||
- if no actionable issues found: submit with \`approved: true\` and an **empty body** (no inline comments, no summary)
|
||||
- do NOT call \`${ghPullfrogMcpName}/report_progress\` — incremental reviews should be silent`,
|
||||
6. Submit:
|
||||
- **actionable issues found**: call \`${ghPullfrogMcpName}/create_pull_request_review\` with \`approved: false\`, all comments, and an **empty body** — inline comments speak for themselves, and a top-level body clutters the PR conversation on every re-review cycle. Then call \`report_progress\` with a 1-sentence summary.
|
||||
- **no actionable issues found**: do NOT submit a review. Call \`${ghPullfrogMcpName}/report_progress\` with a brief note (e.g., "Re-reviewed — no new issues found.").`,
|
||||
|
||||
Plan: `### Checklist
|
||||
|
||||
@@ -209,8 +207,9 @@ ${learningsStep(4)}`,
|
||||
- PR metadata (title, file count, commit count, base/head branches)
|
||||
- format instructions from EVENT INSTRUCTIONS (if any); otherwise use default format: TL;DR, key changes list, per-change sections with plain-language \`##\` titles and before/after framing
|
||||
- instruct it to use the TOC to selectively read relevant diff sections, not the entire file
|
||||
- instruct it to return the full summary markdown via \`${ghPullfrogMcpName}/set_output\`
|
||||
- instruct it to return the full summary markdown as its final response
|
||||
3. After the subagent completes, call \`${ghPullfrogMcpName}/create_issue_comment\` with \`type: "Summary"\` and the summary body.
|
||||
4. Call \`${ghPullfrogMcpName}/report_progress\` with a brief note (e.g., "Posted PR summary.").
|
||||
|
||||
### Effort
|
||||
|
||||
@@ -226,8 +225,9 @@ An existing summary comment was found for this PR. Update it rather than creatin
|
||||
- the diff file path and PR metadata
|
||||
- the existing summary body (\`previousSummaryBody\`) so it can update rather than rewrite from scratch
|
||||
- format instructions from EVENT INSTRUCTIONS (if any)
|
||||
- instruct it to produce an updated summary reflecting the current state of the PR and return via \`${ghPullfrogMcpName}/set_output\`
|
||||
- instruct it to produce an updated summary reflecting the current state of the PR and return it as its final response
|
||||
4. After the subagent completes, call \`${ghPullfrogMcpName}/edit_issue_comment\` with \`commentId: existingSummaryCommentId\` (from this response) and the updated summary body.
|
||||
5. Call \`${ghPullfrogMcpName}/report_progress\` with a brief note (e.g., "Updated PR summary.").
|
||||
|
||||
### Effort
|
||||
|
||||
|
||||
+14
-1
@@ -10,6 +10,7 @@ import { log } from "../utils/cli.ts";
|
||||
import type { OctokitWithPlugins } from "../utils/github.ts";
|
||||
import type { ResolvedPayload } from "../utils/payload.ts";
|
||||
import type { RunContextData } from "../utils/runContextData.ts";
|
||||
import type { TodoTracker } from "../utils/todoTracking.ts";
|
||||
import { CheckoutPrTool } from "./checkout.ts";
|
||||
import { GetCheckSuiteLogsTool } from "./checkSuite.ts";
|
||||
import {
|
||||
@@ -81,8 +82,14 @@ export interface ToolState {
|
||||
};
|
||||
// undefined = no comment yet, number = active comment, null = deliberately deleted
|
||||
progressCommentId: number | null | undefined;
|
||||
// immutable snapshot: true if a progress comment was pre-created at init time.
|
||||
// survives deleteProgressComment so handleAgentResult can still detect "expected but never reported".
|
||||
hadProgressComment: boolean;
|
||||
lastProgressBody?: string;
|
||||
wasUpdated?: boolean;
|
||||
// set after a non-plan report_progress successfully writes the final summary.
|
||||
// decoupled from todoTracker.enabled so cleanup detection survives API failures.
|
||||
finalSummaryWritten?: boolean;
|
||||
// set by select_mode when Plan + issue_number and plan-comment API returns existing plan (for report_progress target_plan_comment)
|
||||
existingPlanCommentId?: number;
|
||||
previousPlanBody?: string;
|
||||
@@ -91,6 +98,7 @@ export interface ToolState {
|
||||
output?: string;
|
||||
usageEntries: AgentUsage[];
|
||||
model?: string | undefined;
|
||||
todoTracker?: TodoTracker | undefined;
|
||||
}
|
||||
|
||||
interface InitToolStateParams {
|
||||
@@ -107,6 +115,7 @@ export function initToolState(params: InitToolStateParams): ToolState {
|
||||
|
||||
return {
|
||||
progressCommentId: resolvedId,
|
||||
hadProgressComment: !!resolvedId,
|
||||
backgroundProcesses: new Map(),
|
||||
usageEntries: [],
|
||||
};
|
||||
@@ -192,9 +201,13 @@ function buildCommonTools(ctx: ToolContext, outputSchema?: JsonSchema): Tool<any
|
||||
GitTool(ctx),
|
||||
GitFetchTool(ctx),
|
||||
UploadFileTool(ctx),
|
||||
SetOutputTool(ctx, outputSchema),
|
||||
];
|
||||
|
||||
const isStandalone = ctx.payload.event.trigger === "unknown";
|
||||
if (isStandalone || outputSchema) {
|
||||
tools.push(SetOutputTool(ctx, outputSchema));
|
||||
}
|
||||
|
||||
// MCP shell with filtered env (no secrets leaked to child processes)
|
||||
if (ctx.payload.shell === "restricted") {
|
||||
tools.push(ShellTool(ctx));
|
||||
|
||||
@@ -15,7 +15,7 @@ export const ModeSchema = type({
|
||||
prompt: "string",
|
||||
});
|
||||
|
||||
const reportProgressInstruction = `Use ${ghPullfrogMcpName}/report_progress to share progress and results. Continue calling it as you make progress — it will update the same comment. Never create additional comments manually.`;
|
||||
const reportProgressInstruction = `Use ${ghPullfrogMcpName}/report_progress to share your **final** results in 1-3 sentences. The completed task list is automatically preserved in a collapsible section below your summary — do not repeat individual steps in the summary. Focus on the outcome and link to any artifacts (PRs, branches). Never create additional comments manually.`;
|
||||
|
||||
const dependencyInstallationStep = `If this task will require running tests, builds, linters, or CLI commands that need installed packages, call \`${ghPullfrogMcpName}/start_dependency_installation\` NOW. This is non-blocking and allows dependencies to install in the background while you continue. Later, call \`${ghPullfrogMcpName}/await_dependency_installation\` before running commands that need them. Skip this step if only reading code or answering questions.`;
|
||||
|
||||
@@ -47,14 +47,12 @@ export function computeModes(): Mode[] {
|
||||
|
||||
7. **COMMIT** - Commit your changes using \`${ghPullfrogMcpName}/git\` (e.g., \`git add .\` then \`git commit -m "message"\`), then push with \`${ghPullfrogMcpName}/push_branch\`. Do NOT use \`git push\` directly - it requires credentials that only the MCP tool provides.
|
||||
|
||||
8. **PROGRESS** - ${reportProgressInstruction}
|
||||
|
||||
9. **PR** - Determine whether to create a PR (if not already on a PR branch):
|
||||
8. **PR** - Determine whether to create a PR (if not already on a PR branch):
|
||||
- **Default behavior**: Create a PR using ${ghPullfrogMcpName}/create_pull_request with an informative title and body. If you are working in the context of an issue (check EVENT DATA for \`issue_number\` where \`is_pr\` is not true), include "Closes #<issue_number>" in the PR body to auto-close the issue when merged.
|
||||
- **Draft PR request**: If the user explicitly asks for a draft PR (e.g. "draft PR", "create as draft", "WIP"), create a PR with \`draft: true\`.
|
||||
- **Branch-only request**: If the user explicitly asks for a branch without a PR (e.g. "don't create a PR", "branch only", "just create a branch"), do NOT create a PR. Simply push the branch and report the branch link.
|
||||
|
||||
10. **FINAL REPORT** - Call report_progress one final time ONLY if you haven't already included all the important information (PR links, branch links, summary) in a previous report_progress call. If you already called report_progress with complete information including PR links after creating the PR, you do NOT need to call it again. Only make a final call if you need to add missing information. When making the final call, ensure it includes:
|
||||
9. **FINAL REPORT** - ${reportProgressInstruction} Ensure the summary includes:
|
||||
- A summary of what was accomplished
|
||||
- Links to any artifacts created (PRs, branches, issues)
|
||||
- If you created a PR, ALWAYS include the PR link. e.g.:
|
||||
@@ -66,7 +64,6 @@ export function computeModes(): Mode[] {
|
||||
[\`pullfrog/branch-name\`](https://github.com/pullfrog/scratch/tree/pullfrog/branch-name) • [Create PR ➔](https://github.com/pullfrog/scratch/compare/main...pullfrog/branch-name?quick_pull=1&title=<informative_title>&body=<informative_body>)
|
||||
\`\`\`
|
||||
|
||||
Do NOT overwrite a good comment with links/details with a generic message like "I have completed the task. Please review the PR." If your previous report_progress call already contains all the necessary information and links, skip the final call entirely.
|
||||
`,
|
||||
},
|
||||
{
|
||||
@@ -120,14 +117,13 @@ Keep the progress comment extremely brief. The summary should be 1-2 sentences m
|
||||
- **Impact analysis**: Identify what was removed, renamed, or deprecated in the PR. Use grep to search the broader codebase for remaining references to those things in code, tests, docs, comments, and configs. Report stale references in the review body.
|
||||
- Do NOT stop at "this looks reasonable." Dig until you either find a problem or have concrete evidence there isn't one.
|
||||
|
||||
4. **DRAFT LINE-BY-LINE COMMENTS** - Every comment must be actionable: the author should need to change something in response. 2-3 sentences max. Use the NEW line number from the diff (second column: \`| OLD | NEW | TYPE | CODE\`). If no issues found, skip to step 5. NO COMPLIMENTS. NO NITPICKING ABOUT CHANGES UNRELATED TO THE MAIN CHANGE. Non-actionable comments (praise, style preferences, minor optimizatfixons, documentation nits) must not be drafted.
|
||||
4. **DRAFT LINE-BY-LINE COMMENTS** - Every comment must be actionable: the author should need to change something in response. 2-3 sentences max. Use the NEW line number from the diff (second column: \`| OLD | NEW | TYPE | CODE\`). If no issues found, skip to step 5. NO COMPLIMENTS. NO NITPICKING ABOUT CHANGES UNRELATED TO THE MAIN CHANGE. Non-actionable comments (praise, style preferences, minor optimizations, documentation nits) must not be drafted.
|
||||
|
||||
5. **WRITE SUMMARY** - Draft a 1-3 sentence summary for the review body. If issues were found, include urgency level and any concerns about code outside the diff. If no issues were found, write a brief approval summary (e.g., "Changes look good. No issues found.").
|
||||
|
||||
6. **SUBMIT** — Always submit a review via ${ghPullfrogMcpName}/create_pull_request_review:
|
||||
- \`body\`: The summary from step 5
|
||||
- \`comments\`: The inline comments from step 4
|
||||
- \`approved\`: Set to \`true\` ONLY if the review contains no actionable feedback — neither inline comments nor actionable content in the body. An approval signals "no changes needed."
|
||||
6. **SUBMIT** — Determine whether to submit a review:
|
||||
- **Issues found**: Submit via ${ghPullfrogMcpName}/create_pull_request_review with the summary body from step 5, the inline comments from step 4, and \`approved: false\`. Then call \`report_progress\` with a 1-sentence summary (e.g., "Reviewed — found 3 issues.").
|
||||
- **No issues found**: Do NOT submit a review. Call \`${ghPullfrogMcpName}/report_progress\` with a brief note (e.g., "Reviewed — no issues found.").
|
||||
|
||||
${permalinkTip}
|
||||
`,
|
||||
@@ -159,12 +155,9 @@ ${permalinkTip}
|
||||
|
||||
6. **DRAFT LINE-BY-LINE COMMENTS** - Every comment must be actionable. 2-3 sentences max. Use the NEW line number from the full PR diff. NO COMPLIMENTS. NO NITPICKING.
|
||||
|
||||
7. **WRITE SUMMARY** - Draft a 1-3 sentence summary for the review body. Focus on what changed since the last review and whether the new changes are sound. If issues were found, include urgency level. If no issues were found, write a brief approval summary.
|
||||
|
||||
8. **SUBMIT** — Use ${ghPullfrogMcpName}/create_pull_request_review:
|
||||
- \`body\`: The summary from step 7
|
||||
- \`comments\`: The inline comments from step 6
|
||||
- \`approved\`: Set to \`true\` ONLY if the review contains no actionable feedback — neither inline comments nor actionable content in the body. An approval signals "no changes needed."
|
||||
7. **SUBMIT** — Determine whether to submit a review:
|
||||
- **Issues found**: Submit via ${ghPullfrogMcpName}/create_pull_request_review with \`approved: false\`, the inline comments from step 6, and an **empty body** — inline comments speak for themselves, and a top-level body clutters the PR conversation on every re-review cycle. Then call \`report_progress\` with a 1-sentence summary (e.g., "Re-reviewed — found 2 issues in the new commits.").
|
||||
- **No issues found**: Do NOT submit a review. Call \`report_progress\` with a brief note (e.g., "Re-reviewed — no new issues found.").
|
||||
|
||||
${permalinkTip}
|
||||
`,
|
||||
@@ -308,9 +301,7 @@ Your job is to fix issues THIS PR introduced, not to fix all CI failures. If in
|
||||
- **Draft PR request**: If the user explicitly asks for a draft PR (e.g. "draft PR", "create as draft", "WIP"), create a PR with \`draft: true\`.
|
||||
- **Branch-only request**: If the user explicitly asks for a branch without a PR (e.g. "don't create a PR", "branch only", "just create a branch"), do NOT create a PR. Simply push the branch and report the branch link.
|
||||
|
||||
5. **PROGRESS** - ${reportProgressInstruction}
|
||||
|
||||
Do NOT overwrite a good comment with links/details with a generic message like "I have completed the task." If your previous report_progress call already contains all the necessary information and links, skip the final call entirely.`,
|
||||
5. **PROGRESS** - ${reportProgressInstruction}`,
|
||||
},
|
||||
{
|
||||
name: "Summarize",
|
||||
@@ -326,6 +317,8 @@ Do NOT overwrite a good comment with links/details with a generic message like "
|
||||
|
||||
4. **POST** - Call ${ghPullfrogMcpName}/create_issue_comment with type: 'Summary' and the summary body.
|
||||
|
||||
5. **PROGRESS** - ${reportProgressInstruction}
|
||||
|
||||
${permalinkTip}`,
|
||||
},
|
||||
];
|
||||
|
||||
@@ -41752,10 +41752,15 @@ async function validateStuckProgressComment(params) {
|
||||
repo: params.repo,
|
||||
comment_id: commentId
|
||||
});
|
||||
if (commentResult.data.body?.startsWith(LEAPING_INTO_ACTION_PREFIX)) {
|
||||
const body = commentResult.data.body ?? "";
|
||||
if (body.startsWith(LEAPING_INTO_ACTION_PREFIX)) {
|
||||
log.info(`[post] comment ${commentId} is stuck on "Leaping into action"`);
|
||||
return commentId;
|
||||
}
|
||||
if (/^- \[[ x]\] |^- \*\*→\*\* |^- ~~/.test(body)) {
|
||||
log.info(`[post] comment ${commentId} is stuck on a todo checklist`);
|
||||
return commentId;
|
||||
}
|
||||
log.info(`[post] comment ${commentId} is not stuck (already updated or different content)`);
|
||||
return null;
|
||||
} catch (error2) {
|
||||
|
||||
@@ -212,7 +212,13 @@ When posting comments via ${ghPullfrogMcpName}, write as a professional team mem
|
||||
|
||||
### Progress reporting
|
||||
|
||||
ALWAYS use \`report_progress\` to share your results and progress — never \`create_issue_comment\`. The \`report_progress\` tool updates the pre-created progress comment on the issue/PR. Using \`create_issue_comment\` instead creates duplicate comments and leaves the progress comment stuck in its initial state. The \`create_issue_comment\` tool is only for creating NEW standalone comments unrelated to your task progress.
|
||||
**Task list**: at the start of every run, create an internal task list based on the steps in your current mode. Update it as you complete each step. The system automatically renders this list to the progress comment — you do not need to call \`report_progress\` for this.
|
||||
|
||||
**\`report_progress\`**: you MUST call this exactly once at the end of every run with a brief final summary (1-3 sentences). Never call it for intermediate status updates (e.g., "Checking for changes...", "Starting review...") — the task list handles live progress automatically. Calling \`report_progress\` replaces the task list with your summary and preserves the completed task list in a collapsible section. Keep the summary concise — do not repeat what the task list already shows. Focus on the outcome (what was accomplished, links to artifacts) rather than listing individual steps.
|
||||
|
||||
Never use \`create_issue_comment\` for task progress — that creates duplicate comments and leaves the progress comment stuck in its initial state. \`create_issue_comment\` is only for standalone comments unrelated to your current task (e.g., Plan comments, PR Summary comments).
|
||||
|
||||
**After a PR review is submitted**, still call \`report_progress\` with your final summary. The progress comment persists as a record of what was done.
|
||||
|
||||
### If you get stuck
|
||||
|
||||
@@ -367,8 +373,6 @@ ${ctx.modes.map((m) => `- "${m.name}": ${m.description}`).join("\n")}
|
||||
|
||||
Follow the mode guidance to complete the task. Use your native file and shell tools for local operations, and the ${ghPullfrogMcpName} MCP tools for GitHub/git operations.
|
||||
|
||||
When done, call \`${ghPullfrogMcpName}/set_output\` with the final result. This makes it available as the GitHub Action output.
|
||||
|
||||
### No-action cases
|
||||
|
||||
If the task clearly requires no work, call \`${ghPullfrogMcpName}/report_progress\` directly to explain why no action is needed.`;
|
||||
|
||||
+10
-1
@@ -70,11 +70,20 @@ async function validateStuckProgressComment(
|
||||
comment_id: commentId,
|
||||
});
|
||||
|
||||
if (commentResult.data.body?.startsWith(LEAPING_INTO_ACTION_PREFIX)) {
|
||||
const body = commentResult.data.body ?? "";
|
||||
|
||||
if (body.startsWith(LEAPING_INTO_ACTION_PREFIX)) {
|
||||
log.info(`[post] comment ${commentId} is stuck on "Leaping into action"`);
|
||||
return commentId;
|
||||
}
|
||||
|
||||
// detect stranded todo checklists left by the tracker when the process was killed
|
||||
// before the agent could call report_progress with a final summary
|
||||
if (/^- \[[ x]\] |^- \*\*→\*\* |^- ~~/.test(body)) {
|
||||
log.info(`[post] comment ${commentId} is stuck on a todo checklist`);
|
||||
return commentId;
|
||||
}
|
||||
|
||||
log.info(`[post] comment ${commentId} is not stuck (already updated or different content)`);
|
||||
return null;
|
||||
} catch (error) {
|
||||
|
||||
@@ -1,5 +1,4 @@
|
||||
import type { WriteablePayload } from "../external.ts";
|
||||
import { deleteProgressComment } from "../mcp/comment.ts";
|
||||
import { reportReviewNodeId } from "../mcp/review.ts";
|
||||
import type { ToolContext } from "../mcp/server.ts";
|
||||
import { log } from "./cli.ts";
|
||||
@@ -34,8 +33,6 @@ export async function postReviewCleanup(ctx: ToolContext): Promise<void> {
|
||||
"follow-up re-review dispatch"
|
||||
);
|
||||
}
|
||||
|
||||
await bestEffort(() => deleteProgressComment(ctx), "delete progress comment");
|
||||
}
|
||||
|
||||
async function bestEffort(fn: () => Promise<unknown>, label: string): Promise<void> {
|
||||
|
||||
+1
-1
@@ -19,7 +19,7 @@ export async function handleAgentResult(ctx: HandleAgentResultParams): Promise<M
|
||||
};
|
||||
}
|
||||
|
||||
if (!ctx.toolState.wasUpdated && ctx.toolState.progressCommentId && !ctx.silent) {
|
||||
if (!ctx.toolState.wasUpdated && ctx.toolState.hadProgressComment && !ctx.silent) {
|
||||
const error = ctx.result.error || "agent completed without reporting progress";
|
||||
try {
|
||||
await reportErrorToComment({
|
||||
|
||||
@@ -0,0 +1,154 @@
|
||||
import { log } from "./log.ts";
|
||||
|
||||
type TodoItem = {
|
||||
id: string;
|
||||
content: string;
|
||||
status: "pending" | "in_progress" | "completed" | "cancelled";
|
||||
};
|
||||
|
||||
function isValidTodoStatus(value: string): value is TodoItem["status"] {
|
||||
return (
|
||||
value === "pending" || value === "in_progress" || value === "completed" || value === "cancelled"
|
||||
);
|
||||
}
|
||||
|
||||
function parseTodowriteInput(input: unknown): { todos: unknown[]; merge: boolean } | undefined {
|
||||
if (!input || typeof input !== "object" || !("todos" in input)) return undefined;
|
||||
if (!Array.isArray(input.todos)) return undefined;
|
||||
const merge = "merge" in input && input.merge === true;
|
||||
return { todos: input.todos, merge };
|
||||
}
|
||||
|
||||
function parseTodoItem(entry: unknown, index: number): TodoItem | undefined {
|
||||
if (!entry || typeof entry !== "object") return undefined;
|
||||
if (!("content" in entry) || typeof entry.content !== "string") return undefined;
|
||||
const id = "id" in entry && typeof entry.id === "string" ? entry.id : String(index);
|
||||
const status =
|
||||
"status" in entry && typeof entry.status === "string" && isValidTodoStatus(entry.status)
|
||||
? entry.status
|
||||
: "pending";
|
||||
return { id, content: entry.content, status };
|
||||
}
|
||||
|
||||
function renderTodoMarkdown(todos: TodoItem[]): string {
|
||||
return todos
|
||||
.map((todo) => {
|
||||
switch (todo.status) {
|
||||
case "completed":
|
||||
return `- [x] ${todo.content}`;
|
||||
case "cancelled":
|
||||
return `- ~~${todo.content}~~`;
|
||||
case "in_progress":
|
||||
return `- **→** ${todo.content}`;
|
||||
case "pending":
|
||||
return `- [ ] ${todo.content}`;
|
||||
default:
|
||||
todo.status satisfies never;
|
||||
return `- [ ] ${todo.content}`;
|
||||
}
|
||||
})
|
||||
.join("\n");
|
||||
}
|
||||
|
||||
export type TodoTracker = {
|
||||
update: (input: unknown) => void;
|
||||
flush: () => Promise<void>;
|
||||
cancel: () => void;
|
||||
/** resolves when any in-flight onUpdate call completes */
|
||||
settled: () => Promise<void>;
|
||||
renderCollapsible: () => string;
|
||||
readonly enabled: boolean;
|
||||
/** true after the tracker has successfully called onUpdate at least once */
|
||||
readonly hasPublished: boolean;
|
||||
};
|
||||
|
||||
const DEBOUNCE_MS = 2000;
|
||||
|
||||
export function createTodoTracker(onUpdate: (body: string) => Promise<void>): TodoTracker {
|
||||
const state = new Map<string, TodoItem>();
|
||||
let enabled = true;
|
||||
let hasPublished = false;
|
||||
let debounceTimer: ReturnType<typeof setTimeout> | null = null;
|
||||
let inflightPromise: Promise<void> = Promise.resolve();
|
||||
|
||||
function scheduleUpdate() {
|
||||
if (!enabled) return;
|
||||
if (debounceTimer) clearTimeout(debounceTimer);
|
||||
debounceTimer = setTimeout(() => {
|
||||
debounceTimer = null;
|
||||
if (!enabled || state.size === 0) return;
|
||||
const markdown = renderTodoMarkdown(Array.from(state.values()));
|
||||
inflightPromise = inflightPromise
|
||||
.then(async () => {
|
||||
if (!enabled) return;
|
||||
await onUpdate(markdown);
|
||||
hasPublished = true;
|
||||
})
|
||||
.catch((err) => {
|
||||
log.debug(`todo progress update failed: ${err}`);
|
||||
});
|
||||
}, DEBOUNCE_MS);
|
||||
}
|
||||
|
||||
return {
|
||||
update(input: unknown) {
|
||||
if (!enabled) return;
|
||||
const parsed = parseTodowriteInput(input);
|
||||
if (!parsed) return;
|
||||
if (!parsed.merge) state.clear();
|
||||
for (const [index, entry] of parsed.todos.entries()) {
|
||||
const item = parseTodoItem(entry, index);
|
||||
if (item) state.set(item.id, item);
|
||||
}
|
||||
log.debug(`» todowrite: ${state.size} items tracked`);
|
||||
scheduleUpdate();
|
||||
},
|
||||
|
||||
async flush() {
|
||||
if (debounceTimer) {
|
||||
clearTimeout(debounceTimer);
|
||||
debounceTimer = null;
|
||||
}
|
||||
if (!enabled || state.size === 0) return;
|
||||
const markdown = renderTodoMarkdown(Array.from(state.values()));
|
||||
inflightPromise = inflightPromise
|
||||
.then(async () => {
|
||||
if (!enabled) return;
|
||||
await onUpdate(markdown);
|
||||
hasPublished = true;
|
||||
})
|
||||
.catch((err) => {
|
||||
log.debug(`todo progress flush failed: ${err}`);
|
||||
});
|
||||
await inflightPromise;
|
||||
},
|
||||
|
||||
cancel() {
|
||||
enabled = false;
|
||||
if (debounceTimer) {
|
||||
clearTimeout(debounceTimer);
|
||||
debounceTimer = null;
|
||||
}
|
||||
},
|
||||
|
||||
async settled() {
|
||||
await inflightPromise;
|
||||
},
|
||||
|
||||
renderCollapsible(): string {
|
||||
if (state.size === 0) return "";
|
||||
const todos = Array.from(state.values());
|
||||
const completed = todos.filter((t) => t.status === "completed").length;
|
||||
const markdown = renderTodoMarkdown(todos);
|
||||
return `<details>\n<summary>Task list (${completed}/${todos.length} completed)</summary>\n\n${markdown}\n\n</details>`;
|
||||
},
|
||||
|
||||
get enabled() {
|
||||
return enabled;
|
||||
},
|
||||
|
||||
get hasPublished() {
|
||||
return hasPublished;
|
||||
},
|
||||
};
|
||||
}
|
||||
Reference in New Issue
Block a user