refactor delegation system, add PR summary comments, and improve code quality (#334)
* refactor delegation system and add PR summary comments Delegation system: - replace mode-based delegation with select_mode → delegate two-step flow - orchestrator crafts self-contained subagent prompts (clean context — no system/repo/event instructions leak) - add role-based tool filtering via FastMCP authenticate hook (?role=subagent hides orchestrator-only tools) - add select_mode tool for orchestrator guidance per mode - add ask_question tool for lightweight research subagents - extract shared subagent lifecycle into subagent.ts (create, complete, stdout, instructions) - route set_output to per-subagent state when activeSubagentId is set - track per-subagent state (SubagentState Map) replacing boolean delegationActive flag - capture and aggregate AgentUsage across all agents (claude, codex, gemini, opencode) - write usage summary table to GitHub job summary - block built-in subagent spawning (Task for Claude, Task(*) for Cursor) - increase activity timeout from 60s to 300s (subagent thinking phases) - fix gh CLI misguidance in system prompt — explicitly forbid usage PR summary comments: - add prSummaryComment trigger (DB schema + migrations + Zod + UI toggle) - dispatch mini-effort summary job alongside PR review on pr.created - add update_pull_request_body MCP tool - add defaultEffort option to webhook dispatch Hardening: - rewrite delegate/selectMode tests with simulated state management - add toolFiltering.test.ts for role extraction, canAccess, set_output routing - remove non-null assertions for PULLFROG_TEMP_DIR (proper error throws) - use fetchWithRetry for direct tarball downloads - DRY fix for rate limit check in test runner Co-authored-by: Cursor <cursoragent@cursor.com> * fix: add type keyword to Effort import in handleWebhook.ts Co-authored-by: Cursor <cursoragent@cursor.com> * clean up delegation system, improve code quality across the codebase - simplify delegate tool to instructions + effort params with subagent lifecycle in subagent.ts - add select_mode and ask_question orchestrator-only tools with canAccess filtering - replace delegate.test.ts/selectMode.test.ts with toolFiltering.test.ts (live MCP integration) - add set_output routing for subagent context and AgentUsage tracking across all agents - add PR summary comment trigger (schema, UI, webhook dispatch with silent flag) - add update_pull_request_body MCP tool - fix changed-agents.sh to always include claude canary for non-agent action changes - fix cursor pagination bug in getSelectedInstallationReposPage - remove destructuring patterns, inline type definitions, and unsafe type casts - replace non-null assertions with explicit checks in install.ts - convert multi-param functions to single param objects (postCleanup, runActionLocal, etc.) - use isHttpError helper in API routes instead of catch-any patterns - add adhoc test fixtures for delegation scenarios (context isolation, error handling, synthesis, etc.) Co-authored-by: Cursor <cursoragent@cursor.com> * no subagent mutation, one mcp per subagent * address review feedback: parallel-safe usage tracking, subagent isolation, minor improvements * fix subagent state isolation: replace Object.freeze with shallow copy Object.freeze throws TypeErrors when subagent tools (checkout_pr, report_progress) write scalar properties to toolState. A shallow copy achieves the same isolation for scalar fields while allowing tools to work normally. Shared references (subagents Map, usageEntries array) remain shared for coordination. --------- Co-authored-by: Cursor <cursoragent@cursor.com> Co-authored-by: pullfrog[bot] <226033991+pullfrog[bot]@users.noreply.github.com>
This commit is contained in:
David Blass
committed by
pullfrog[bot]
pullfrog[bot]
parent
a90743e9fe
commit
cfd38d82fc
+31
-100
@@ -1,129 +1,60 @@
|
||||
import { type } from "arktype";
|
||||
import { Effort } from "../external.ts";
|
||||
import type { Mode } from "../modes.ts";
|
||||
import { markActivity } from "../utils/activity.ts";
|
||||
import { log } from "../utils/cli.ts";
|
||||
import { resolveSubagentInstructions } from "../utils/instructions.ts";
|
||||
import type { ToolContext } from "./server.ts";
|
||||
import { execute, tool } from "./shared.ts";
|
||||
import { createSubagentState, runSubagent } from "./subagent.ts";
|
||||
|
||||
export const DelegateParams = type({
|
||||
mode: type.string.describe(
|
||||
"the name of the mode to delegate to (e.g., 'Build', 'Plan', 'Review', 'Fix', 'AddressReviews')"
|
||||
instructions: type.string.describe(
|
||||
"the complete prompt for the subagent. the subagent receives ONLY this text — include all context it needs (file paths, constraints, conventions, tool usage instructions). craft a focused, self-contained task description."
|
||||
),
|
||||
"effort?": Effort.describe(
|
||||
'effort level for the subagent: "mini" (low-effort and fast, only for simple tasks), "auto" (medium-effort, good for typical tasks that don\'t require significant reasoning), or "max" (high-effort, good for PR reviews and complex coding tasks)'
|
||||
),
|
||||
"instructions?": type.string.describe(
|
||||
"optional additional context or instructions for the subagent — use this to pass results from earlier delegations or narrow the subagent's focus"
|
||||
),
|
||||
});
|
||||
|
||||
// exported for unit testing
|
||||
export function resolveMode(modes: Mode[], modeName: string): Mode | null {
|
||||
return modes.find((m) => m.name.toLowerCase() === modeName.toLowerCase()) ?? null;
|
||||
}
|
||||
|
||||
// cap subagent output to avoid bloating the orchestrator's context window.
|
||||
// the orchestrator needs enough to understand what happened, not the full NDJSON stream.
|
||||
const MAX_OUTPUT_CHARS = 20_000;
|
||||
|
||||
// exported for unit testing
|
||||
export function truncateOutput(output: string | undefined): string | undefined {
|
||||
if (!output || output.length <= MAX_OUTPUT_CHARS) return output;
|
||||
const truncated = output.slice(-MAX_OUTPUT_CHARS);
|
||||
return `[truncated — showing last ${MAX_OUTPUT_CHARS} chars]\n${truncated}`;
|
||||
}
|
||||
|
||||
export function DelegateTool(ctx: ToolContext) {
|
||||
return tool({
|
||||
name: "delegate",
|
||||
description:
|
||||
"Delegate a task to a subagent with a specific mode and effort level. The subagent runs as a separate process with the mode's step-by-step instructions.",
|
||||
"Delegate a task to a subagent. The subagent receives ONLY the instructions you provide — no other context is added. Use select_mode first to get guidance on how to craft the instructions for a given mode.",
|
||||
parameters: DelegateParams,
|
||||
execute: execute(async (params) => {
|
||||
// guard: prevent subagent recursion
|
||||
if (ctx.toolState.delegationActive) {
|
||||
if (ctx.toolState.activeSubagentId) {
|
||||
return {
|
||||
error:
|
||||
"delegation is not available inside a subagent. you are already running as a delegated subagent. complete the task directly using the available tools. do not attempt to delegate further. your last agent message will be passed to your supervisor and it will decide what to do next.",
|
||||
};
|
||||
}
|
||||
|
||||
// resolve mode
|
||||
const selectedMode = resolveMode(ctx.modes, params.mode);
|
||||
if (!selectedMode) {
|
||||
const availableModes = ctx.modes.map((m) => m.name).join(", ");
|
||||
return {
|
||||
error: `mode "${params.mode}" not found. available modes: ${availableModes}`,
|
||||
availableModes: ctx.modes.map((m) => ({
|
||||
name: m.name,
|
||||
description: m.description,
|
||||
})),
|
||||
"delegation is not available inside a subagent. you are already running as a delegated subagent. complete the task directly using the available tools.",
|
||||
};
|
||||
}
|
||||
|
||||
const effort = params.effort ?? "auto";
|
||||
|
||||
// track state
|
||||
ctx.toolState.selectedMode = selectedMode.name;
|
||||
ctx.toolState.delegationActive = true;
|
||||
|
||||
log.info(
|
||||
`» delegating to ${selectedMode.name} mode (effort=${effort})${params.instructions ? " with orchestrator instructions" : ""}`
|
||||
);
|
||||
|
||||
// keep the process-level activity timeout alive while the subagent runs.
|
||||
// agent CLIs can have long silent thinking phases (>60s) with no stdout,
|
||||
// which would trigger the activity timeout. the overall run timeout (default 1h)
|
||||
// is the real safety net for stalled agents.
|
||||
const keepAliveInterval = setInterval(markActivity, 30_000);
|
||||
|
||||
try {
|
||||
// build subagent payload with effort override
|
||||
const subagentPayload = { ...ctx.payload, effort };
|
||||
|
||||
// build subagent instructions with mode prompt baked in
|
||||
const subagentInstructions = resolveSubagentInstructions({
|
||||
payload: subagentPayload,
|
||||
repo: ctx.repo,
|
||||
modes: ctx.modes,
|
||||
mode: selectedMode,
|
||||
orchestratorInstructions: params.instructions,
|
||||
});
|
||||
|
||||
// spawn subagent — reuses same MCP server, same toolState
|
||||
const result = await ctx.agent.run({
|
||||
payload: subagentPayload,
|
||||
mcpServerUrl: ctx.mcpServerUrl,
|
||||
tmpdir: ctx.tmpdir,
|
||||
instructions: subagentInstructions,
|
||||
});
|
||||
|
||||
log.info(`» delegation to ${selectedMode.name} completed (success=${result.success})`);
|
||||
|
||||
return {
|
||||
success: result.success,
|
||||
mode: selectedMode.name,
|
||||
effort,
|
||||
output: truncateOutput(result.output),
|
||||
error: result.error,
|
||||
};
|
||||
} catch (err) {
|
||||
// normalize agent crashes into the same return shape as clean failures
|
||||
const errorMessage = err instanceof Error ? err.message : String(err);
|
||||
log.info(`» delegation to ${selectedMode.name} crashed: ${errorMessage}`);
|
||||
return {
|
||||
success: false,
|
||||
mode: selectedMode.name,
|
||||
effort,
|
||||
error: errorMessage,
|
||||
};
|
||||
} finally {
|
||||
clearInterval(keepAliveInterval);
|
||||
// always release the lock so the orchestrator can delegate again
|
||||
ctx.toolState.delegationActive = false;
|
||||
const mode = ctx.toolState.selectedMode ?? "unknown";
|
||||
if (!ctx.toolState.selectedMode) {
|
||||
log.info(`» warning: delegating without calling select_mode first (mode=${mode})`);
|
||||
}
|
||||
const subagent = createSubagentState({ ctx, mode });
|
||||
|
||||
log.info(`» delegating subagent=${subagent.id} (mode=${mode}, effort=${effort})`);
|
||||
const result = await runSubagent({
|
||||
ctx,
|
||||
subagent,
|
||||
effort,
|
||||
instructions: params.instructions,
|
||||
});
|
||||
log.info(`» delegation completed (mode=${mode}, success=${result.success})`);
|
||||
|
||||
return {
|
||||
success: result.success,
|
||||
mode,
|
||||
effort,
|
||||
summary:
|
||||
subagent.output ??
|
||||
result.error ??
|
||||
"no output produced — the subagent may not have called set_output. check stdoutFile for full logs.",
|
||||
stdoutFile: subagent.stdoutFilePath,
|
||||
error: result.error,
|
||||
};
|
||||
}),
|
||||
});
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user