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
@@ -0,0 +1,54 @@
|
||||
import { type } from "arktype";
|
||||
import { ghPullfrogMcpName } from "../external.ts";
|
||||
import { log } from "../utils/cli.ts";
|
||||
import type { ToolContext } from "./server.ts";
|
||||
import { execute, tool } from "./shared.ts";
|
||||
import { createSubagentState, runSubagent } from "./subagent.ts";
|
||||
|
||||
export const AskQuestionParams = type({
|
||||
question: type.string.describe(
|
||||
"the question to answer about the codebase, architecture, or implementation details"
|
||||
),
|
||||
});
|
||||
|
||||
function buildQuestionPrompt(question: string): string {
|
||||
return `You are a focused research subagent. Answer the following question by exploring the codebase using the available MCP tools (${ghPullfrogMcpName}/file_read, ${ghPullfrogMcpName}/list_directory, etc.).
|
||||
|
||||
Be thorough in your investigation but concise in your answer. When done, call ${ghPullfrogMcpName}/set_output with a maximally concise answer — key facts only, no filler, no preamble.
|
||||
|
||||
Question: ${question}`;
|
||||
}
|
||||
|
||||
export function AskQuestionTool(ctx: ToolContext) {
|
||||
return tool({
|
||||
name: "ask_question",
|
||||
description:
|
||||
"Ask a question about the codebase and get a concise answer from a lightweight research subagent. The intermediate exploration context stays in the subagent — only the concise answer returns to you.",
|
||||
parameters: AskQuestionParams,
|
||||
execute: execute(async (params) => {
|
||||
if (ctx.toolState.activeSubagentId) {
|
||||
return { error: "cannot ask questions while a subagent is already running" };
|
||||
}
|
||||
|
||||
const subagent = createSubagentState({ ctx, mode: "ask_question" });
|
||||
log.info(`» ask_question subagent=${subagent.id}: ${params.question.slice(0, 100)}`);
|
||||
|
||||
const result = await runSubagent({
|
||||
ctx,
|
||||
subagent,
|
||||
effort: "mini",
|
||||
instructions: buildQuestionPrompt(params.question),
|
||||
});
|
||||
log.info(`» ask_question completed (success=${result.success})`);
|
||||
|
||||
return {
|
||||
success: result.success,
|
||||
answer:
|
||||
subagent.output ??
|
||||
result.error ??
|
||||
"no answer produced — the subagent may not have called set_output. check stdoutFile for details.",
|
||||
stdoutFile: subagent.stdoutFilePath,
|
||||
};
|
||||
}),
|
||||
});
|
||||
}
|
||||
@@ -169,6 +169,12 @@ export async function reportProgress(
|
||||
// always track the body for job summary
|
||||
ctx.toolState.lastProgressBody = body;
|
||||
|
||||
// silent events (e.g., auto-label, PR summary) should never create or update progress comments.
|
||||
// the body is still tracked above for the GitHub Actions job summary.
|
||||
if (ctx.payload.event.silent) {
|
||||
return { body, action: "skipped" };
|
||||
}
|
||||
|
||||
const existingCommentId = ctx.toolState.progressCommentId;
|
||||
const issueNumber = ctx.toolState.issueNumber ?? ctx.payload.event.issue_number;
|
||||
const isPlanMode = ctx.toolState.selectedMode === "Plan";
|
||||
|
||||
@@ -1,356 +0,0 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
import type { Mode } from "../modes.ts";
|
||||
import { resolveMode, truncateOutput } from "./delegate.ts";
|
||||
|
||||
// ─── mode resolution tests ─────────────────────────────────────────────
|
||||
|
||||
const testModes: Mode[] = [
|
||||
{ name: "Build", description: "build things", prompt: "build prompt" },
|
||||
{ name: "Plan", description: "plan things", prompt: "plan prompt" },
|
||||
{ name: "Review", description: "review things", prompt: "review prompt" },
|
||||
{ name: "Fix", description: "fix things", prompt: "fix prompt" },
|
||||
{ name: "AddressReviews", description: "address reviews", prompt: "address prompt" },
|
||||
];
|
||||
|
||||
describe("delegate - mode resolution", () => {
|
||||
it("resolves valid mode name", () => {
|
||||
const mode = resolveMode(testModes, "Build");
|
||||
expect(mode).not.toBeNull();
|
||||
expect(mode!.name).toBe("Build");
|
||||
});
|
||||
|
||||
it("resolves case-insensitively (lowercase)", () => {
|
||||
const mode = resolveMode(testModes, "build");
|
||||
expect(mode).not.toBeNull();
|
||||
expect(mode!.name).toBe("Build");
|
||||
});
|
||||
|
||||
it("resolves case-insensitively (uppercase)", () => {
|
||||
const mode = resolveMode(testModes, "BUILD");
|
||||
expect(mode).not.toBeNull();
|
||||
expect(mode!.name).toBe("Build");
|
||||
});
|
||||
|
||||
it("resolves case-insensitively (mixed case)", () => {
|
||||
const mode = resolveMode(testModes, "pLaN");
|
||||
expect(mode).not.toBeNull();
|
||||
expect(mode!.name).toBe("Plan");
|
||||
});
|
||||
|
||||
it("returns null for invalid mode name", () => {
|
||||
const mode = resolveMode(testModes, "nonexistent");
|
||||
expect(mode).toBeNull();
|
||||
});
|
||||
|
||||
it("returns null for empty string", () => {
|
||||
const mode = resolveMode(testModes, "");
|
||||
expect(mode).toBeNull();
|
||||
});
|
||||
|
||||
it("resolves custom modes appended alongside built-in modes", () => {
|
||||
const modesWithCustom: Mode[] = [
|
||||
...testModes,
|
||||
{ name: "CustomLabel", description: "label issues", prompt: "label prompt" },
|
||||
];
|
||||
const mode = resolveMode(modesWithCustom, "customlabel");
|
||||
expect(mode).not.toBeNull();
|
||||
expect(mode!.name).toBe("CustomLabel");
|
||||
});
|
||||
|
||||
it("returns null when modes list is empty", () => {
|
||||
const mode = resolveMode([], "Build");
|
||||
expect(mode).toBeNull();
|
||||
});
|
||||
|
||||
it("resolves all built-in modes", () => {
|
||||
for (const m of testModes) {
|
||||
const resolved = resolveMode(testModes, m.name);
|
||||
expect(resolved).not.toBeNull();
|
||||
expect(resolved!.name).toBe(m.name);
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
// ─── output truncation tests ────────────────────────────────────────────
|
||||
|
||||
describe("delegate - output truncation", () => {
|
||||
it("returns undefined for undefined input", () => {
|
||||
expect(truncateOutput(undefined)).toBeUndefined();
|
||||
});
|
||||
|
||||
it("returns empty string as-is", () => {
|
||||
expect(truncateOutput("")).toBe("");
|
||||
});
|
||||
|
||||
it("returns short output unchanged", () => {
|
||||
const short = "a".repeat(100);
|
||||
expect(truncateOutput(short)).toBe(short);
|
||||
});
|
||||
|
||||
it("returns output at exactly the limit unchanged", () => {
|
||||
const exact = "x".repeat(20_000);
|
||||
expect(truncateOutput(exact)).toBe(exact);
|
||||
});
|
||||
|
||||
it("truncates output exceeding the limit", () => {
|
||||
const long = "a".repeat(30_000);
|
||||
const result = truncateOutput(long);
|
||||
expect(result).not.toBe(long);
|
||||
expect(result).toContain("[truncated");
|
||||
expect(result).toContain("20000");
|
||||
});
|
||||
|
||||
it("keeps the tail of the output (last N chars)", () => {
|
||||
const prefix = "START_".repeat(5000);
|
||||
const suffix = "END_MARKER";
|
||||
const long = prefix + suffix;
|
||||
const result = truncateOutput(long)!;
|
||||
expect(result).toContain("END_MARKER");
|
||||
// the very beginning of the original is lost (starts with truncation prefix, not original content)
|
||||
expect(result.startsWith("START_")).toBe(false);
|
||||
});
|
||||
|
||||
it("adds truncation prefix before the content", () => {
|
||||
const long = "x".repeat(25_000);
|
||||
const result = truncateOutput(long)!;
|
||||
expect(result).toMatch(/^\[truncated.*\]\n/);
|
||||
});
|
||||
});
|
||||
|
||||
// ─── effort validation tests ────────────────────────────────────────────
|
||||
|
||||
// mirrors the effort default logic in the delegate handler
|
||||
function resolveEffort(effort: string | undefined): string {
|
||||
return effort ?? "auto";
|
||||
}
|
||||
|
||||
describe("delegate - effort defaults", () => {
|
||||
it("defaults to 'auto' when undefined", () => {
|
||||
expect(resolveEffort(undefined)).toBe("auto");
|
||||
});
|
||||
|
||||
it("passes through 'mini'", () => {
|
||||
expect(resolveEffort("mini")).toBe("mini");
|
||||
});
|
||||
|
||||
it("passes through 'auto'", () => {
|
||||
expect(resolveEffort("auto")).toBe("auto");
|
||||
});
|
||||
|
||||
it("passes through 'max'", () => {
|
||||
expect(resolveEffort("max")).toBe("max");
|
||||
});
|
||||
});
|
||||
|
||||
// ─── delegation guard tests ─────────────────────────────────────────────
|
||||
|
||||
// mirrors the delegationActive guard logic
|
||||
function checkDelegationGuard(delegationActive: boolean): string | null {
|
||||
if (delegationActive) {
|
||||
return "delegation is not available inside a delegated subagent";
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
describe("delegate - delegation guard", () => {
|
||||
it("allows delegation when delegationActive is false", () => {
|
||||
expect(checkDelegationGuard(false)).toBeNull();
|
||||
});
|
||||
|
||||
it("blocks delegation when delegationActive is true", () => {
|
||||
const error = checkDelegationGuard(true);
|
||||
expect(error).not.toBeNull();
|
||||
expect(error).toContain("not available");
|
||||
});
|
||||
});
|
||||
|
||||
// ─── delegation lifecycle tests ─────────────────────────────────────────
|
||||
|
||||
// simulates the delegationActive lifecycle across sequential delegations
|
||||
describe("delegate - delegation lifecycle", () => {
|
||||
it("delegationActive resets after successful delegation", () => {
|
||||
let delegationActive = false;
|
||||
|
||||
// first delegation
|
||||
delegationActive = true;
|
||||
// ... agent.run() succeeds ...
|
||||
delegationActive = false; // finally block
|
||||
|
||||
expect(delegationActive).toBe(false);
|
||||
});
|
||||
|
||||
it("delegationActive resets after failed delegation (finally block)", () => {
|
||||
let delegationActive = false;
|
||||
|
||||
// delegation that fails — finally block still runs
|
||||
delegationActive = true;
|
||||
try {
|
||||
throw new Error("agent failed");
|
||||
} catch {
|
||||
// agent error handled
|
||||
} finally {
|
||||
delegationActive = false;
|
||||
}
|
||||
|
||||
expect(delegationActive).toBe(false);
|
||||
});
|
||||
|
||||
it("supports sequential delegations", () => {
|
||||
let delegationActive = false;
|
||||
let selectedMode: string | undefined;
|
||||
|
||||
// first delegation: Plan
|
||||
expect(checkDelegationGuard(delegationActive)).toBeNull();
|
||||
delegationActive = true;
|
||||
selectedMode = "Plan";
|
||||
delegationActive = false; // completed
|
||||
|
||||
expect(selectedMode).toBe("Plan");
|
||||
|
||||
// second delegation: Build
|
||||
expect(checkDelegationGuard(delegationActive)).toBeNull();
|
||||
delegationActive = true;
|
||||
selectedMode = "Build";
|
||||
delegationActive = false; // completed
|
||||
|
||||
expect(selectedMode).toBe("Build");
|
||||
});
|
||||
|
||||
it("blocks during active delegation", () => {
|
||||
let delegationActive = false;
|
||||
|
||||
// start delegation
|
||||
delegationActive = true;
|
||||
|
||||
// attempt second delegation while first is active
|
||||
expect(checkDelegationGuard(delegationActive)).not.toBeNull();
|
||||
|
||||
// first completes
|
||||
delegationActive = false;
|
||||
|
||||
// now second should be allowed
|
||||
expect(checkDelegationGuard(delegationActive)).toBeNull();
|
||||
});
|
||||
});
|
||||
|
||||
// ─── subagent payload construction tests ────────────────────────────────
|
||||
|
||||
type MinimalPayload = {
|
||||
effort: string;
|
||||
prompt: string;
|
||||
bash: string;
|
||||
push: string;
|
||||
web: string;
|
||||
};
|
||||
|
||||
function buildSubagentPayload(payload: MinimalPayload, delegatedEffort: string): MinimalPayload {
|
||||
return { ...payload, effort: delegatedEffort };
|
||||
}
|
||||
|
||||
describe("delegate - subagent payload construction", () => {
|
||||
const basePayload: MinimalPayload = {
|
||||
effort: "auto",
|
||||
prompt: "test prompt",
|
||||
bash: "restricted",
|
||||
push: "restricted",
|
||||
web: "enabled",
|
||||
};
|
||||
|
||||
it("overrides effort in subagent payload", () => {
|
||||
const subPayload = buildSubagentPayload(basePayload, "mini");
|
||||
expect(subPayload.effort).toBe("mini");
|
||||
});
|
||||
|
||||
it("preserves other payload fields", () => {
|
||||
const subPayload = buildSubagentPayload(basePayload, "mini");
|
||||
expect(subPayload.prompt).toBe("test prompt");
|
||||
expect(subPayload.bash).toBe("restricted");
|
||||
expect(subPayload.push).toBe("restricted");
|
||||
expect(subPayload.web).toBe("enabled");
|
||||
});
|
||||
|
||||
it("does not mutate original payload", () => {
|
||||
const subPayload = buildSubagentPayload(basePayload, "max");
|
||||
expect(basePayload.effort).toBe("auto");
|
||||
expect(subPayload.effort).toBe("max");
|
||||
});
|
||||
|
||||
it("handles same effort as original", () => {
|
||||
const subPayload = buildSubagentPayload(basePayload, "auto");
|
||||
expect(subPayload.effort).toBe("auto");
|
||||
});
|
||||
});
|
||||
|
||||
// ─── return shape tests ─────────────────────────────────────────────────
|
||||
|
||||
type DelegateResult = {
|
||||
success: boolean;
|
||||
mode: string;
|
||||
effort: string;
|
||||
output: string | undefined;
|
||||
error: string | undefined;
|
||||
};
|
||||
|
||||
type BuildDelegateResultInput = {
|
||||
agentResult: {
|
||||
success: boolean;
|
||||
output?: string;
|
||||
error?: string;
|
||||
};
|
||||
mode: string;
|
||||
effort: string;
|
||||
};
|
||||
|
||||
function buildDelegateResult(input: BuildDelegateResultInput): DelegateResult {
|
||||
return {
|
||||
success: input.agentResult.success,
|
||||
mode: input.mode,
|
||||
effort: input.effort,
|
||||
output: input.agentResult.output,
|
||||
error: input.agentResult.error,
|
||||
};
|
||||
}
|
||||
|
||||
describe("delegate - return shape", () => {
|
||||
it("returns success shape on successful delegation", () => {
|
||||
const result = buildDelegateResult({
|
||||
agentResult: { success: true, output: "agent output" },
|
||||
mode: "Build",
|
||||
effort: "auto",
|
||||
});
|
||||
expect(result.success).toBe(true);
|
||||
expect(result.mode).toBe("Build");
|
||||
expect(result.effort).toBe("auto");
|
||||
expect(result.output).toBe("agent output");
|
||||
expect(result.error).toBeUndefined();
|
||||
});
|
||||
|
||||
it("returns failure shape on failed delegation", () => {
|
||||
const result = buildDelegateResult({
|
||||
agentResult: { success: false, error: "agent crashed" },
|
||||
mode: "Review",
|
||||
effort: "mini",
|
||||
});
|
||||
expect(result.success).toBe(false);
|
||||
expect(result.mode).toBe("Review");
|
||||
expect(result.effort).toBe("mini");
|
||||
expect(result.error).toBe("agent crashed");
|
||||
});
|
||||
|
||||
it("includes mode and effort in both success and failure", () => {
|
||||
const success = buildDelegateResult({
|
||||
agentResult: { success: true },
|
||||
mode: "Plan",
|
||||
effort: "max",
|
||||
});
|
||||
const failure = buildDelegateResult({
|
||||
agentResult: { success: false },
|
||||
mode: "Fix",
|
||||
effort: "mini",
|
||||
});
|
||||
expect(success.mode).toBe("Plan");
|
||||
expect(success.effort).toBe("max");
|
||||
expect(failure.mode).toBe("Fix");
|
||||
expect(failure.effort).toBe("mini");
|
||||
});
|
||||
});
|
||||
+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,
|
||||
};
|
||||
}),
|
||||
});
|
||||
}
|
||||
|
||||
+14
-2
@@ -1,4 +1,5 @@
|
||||
import { type } from "arktype";
|
||||
import { log } from "../utils/cli.ts";
|
||||
import type { ToolContext } from "./server.ts";
|
||||
import { execute, tool } from "./shared.ts";
|
||||
|
||||
@@ -10,11 +11,22 @@ export function SetOutputTool(ctx: ToolContext) {
|
||||
return tool({
|
||||
name: "set_output",
|
||||
description:
|
||||
"Set the action output for consumption by subsequent workflow steps. The value will be available as the 'result' output of the action.",
|
||||
"Set the action output. When called by a subagent, returns a summary result to the orchestrator. When called in standalone mode, exposes the value as the 'result' GitHub Action output.",
|
||||
parameters: SetOutputParams,
|
||||
execute: execute(async (params) => {
|
||||
const activeId = ctx.toolState.activeSubagentId;
|
||||
if (activeId) {
|
||||
const subagent = ctx.toolState.subagents.get(activeId);
|
||||
if (subagent) {
|
||||
subagent.output = params.value;
|
||||
return { success: true, routed: "subagent" };
|
||||
}
|
||||
log.warning(
|
||||
`set_output: activeSubagentId=${activeId} but subagent not found in map — routing to action output`
|
||||
);
|
||||
}
|
||||
ctx.toolState.output = params.value;
|
||||
return { success: true };
|
||||
return { success: true, routed: "action_output" };
|
||||
}),
|
||||
});
|
||||
}
|
||||
|
||||
@@ -24,31 +24,60 @@ function buildPrBodyWithFooter(ctx: ToolContext, body: string): string {
|
||||
return `${bodyWithoutFooter}${footer}`;
|
||||
}
|
||||
|
||||
export const UpdatePullRequestBody = type({
|
||||
pull_number: type.number.describe("the pull request number to update"),
|
||||
body: type.string.describe("the new body content for the pull request"),
|
||||
});
|
||||
|
||||
export function UpdatePullRequestBodyTool(ctx: ToolContext) {
|
||||
return tool({
|
||||
name: "update_pull_request_body",
|
||||
description: "Update the body/description of an existing pull request",
|
||||
parameters: UpdatePullRequestBody,
|
||||
execute: execute(async (params) => {
|
||||
const bodyWithFooter = buildPrBodyWithFooter(ctx, params.body);
|
||||
|
||||
const result = await ctx.octokit.rest.pulls.update({
|
||||
owner: ctx.repo.owner,
|
||||
repo: ctx.repo.name,
|
||||
pull_number: params.pull_number,
|
||||
body: bodyWithFooter,
|
||||
});
|
||||
|
||||
return {
|
||||
success: true,
|
||||
number: result.data.number,
|
||||
url: result.data.html_url,
|
||||
};
|
||||
}),
|
||||
});
|
||||
}
|
||||
|
||||
export function CreatePullRequestTool(ctx: ToolContext) {
|
||||
return tool({
|
||||
name: "create_pull_request",
|
||||
description: "Create a pull request from the current branch",
|
||||
parameters: PullRequest,
|
||||
execute: execute(async ({ title, body, base }) => {
|
||||
execute: execute(async (params) => {
|
||||
const currentBranch = $("git", ["rev-parse", "--abbrev-ref", "HEAD"], { log: false });
|
||||
log.debug(`Current branch: ${currentBranch}`);
|
||||
|
||||
const bodyWithFooter = buildPrBodyWithFooter(ctx, body);
|
||||
const bodyWithFooter = buildPrBodyWithFooter(ctx, params.body);
|
||||
|
||||
const result = await ctx.octokit.rest.pulls.create({
|
||||
owner: ctx.repo.owner,
|
||||
repo: ctx.repo.name,
|
||||
title: title,
|
||||
title: params.title,
|
||||
body: bodyWithFooter,
|
||||
head: currentBranch,
|
||||
base: base,
|
||||
base: params.base,
|
||||
});
|
||||
|
||||
// best-effort: request review from the user who triggered the workflow
|
||||
const reviewer = ctx.payload.triggeringUser;
|
||||
if (reviewer) {
|
||||
try {
|
||||
log.debug(`Requesting review from ${reviewer} on PR #${result.data.number}`);
|
||||
log.debug(`requesting review from ${reviewer} on PR #${result.data.number}`);
|
||||
await ctx.octokit.rest.pulls.requestReviewers({
|
||||
owner: ctx.repo.owner,
|
||||
repo: ctx.repo.name,
|
||||
|
||||
@@ -0,0 +1,151 @@
|
||||
import { type } from "arktype";
|
||||
import { ghPullfrogMcpName } from "../external.ts";
|
||||
import type { Mode } from "../modes.ts";
|
||||
import type { ToolContext } from "./server.ts";
|
||||
import { execute, tool } from "./shared.ts";
|
||||
|
||||
export const SelectModeParams = type({
|
||||
mode: type.string.describe(
|
||||
"the name of the mode to select (e.g., 'Build', 'Plan', 'Review', 'Fix', 'AddressReviews', 'Prompt')"
|
||||
),
|
||||
});
|
||||
|
||||
function resolveMode(modes: Mode[], modeName: string): Mode | null {
|
||||
return modes.find((m) => m.name.toLowerCase() === modeName.toLowerCase()) ?? null;
|
||||
}
|
||||
|
||||
function defaultGuidance(mode: Mode): string {
|
||||
return `Delegate a single subagent for this "${mode.name}" task. Craft a self-contained prompt that includes all context the subagent needs. Include \`${ghPullfrogMcpName}/report_progress\` for user-facing updates and \`${ghPullfrogMcpName}/set_output\` to return results back to you. Subagents do NOT have push or PR creation tools — if the task involves code changes, you must push and create the PR yourself after the subagent completes.`;
|
||||
}
|
||||
|
||||
const modeGuidance: Record<string, string> = {
|
||||
Build: `For Build tasks, consider a multi-phase approach:
|
||||
|
||||
1. **plan phase** (optional, for complex tasks): delegate a subagent to analyze the requirements, read AGENTS.md and relevant code, and produce a step-by-step implementation plan. Include \`${ghPullfrogMcpName}/set_output\` with the plan so it returns to you. Use mini or auto effort.
|
||||
|
||||
2. **build phase**: delegate a subagent with the implementation task. Include in its prompt:
|
||||
- the plan (if you ran a plan phase)
|
||||
- specific files to modify and why
|
||||
- branch naming: \`pullfrog/<issue-number>-<description>\`
|
||||
- testing expectations: run relevant tests/lints before committing
|
||||
- commit changes locally (do NOT instruct to push or create a PR — subagents cannot do that)
|
||||
- call \`${ghPullfrogMcpName}/report_progress\` with a summary of changes
|
||||
- call \`${ghPullfrogMcpName}/set_output\` with a concise summary including the branch name (this is how results get back to you)
|
||||
|
||||
3. **post-delegation** (your responsibility as orchestrator): after the build subagent completes:
|
||||
- push the branch via \`${ghPullfrogMcpName}/push_branch\`
|
||||
- create a PR via \`${ghPullfrogMcpName}/create_pull_request\`
|
||||
- call \`${ghPullfrogMcpName}/report_progress\` with the final summary including PR link
|
||||
|
||||
4. **review phase** (optional, for high-stakes changes): delegate a review subagent to verify the implementation.
|
||||
|
||||
For simple, well-defined tasks, a single build subagent is sufficient — skip the plan and review phases.
|
||||
|
||||
Your subagent receives ONLY what you write. Include file paths, constraints, conventions, and any context from AGENTS.md or the codebase directly in the prompt. Subagents do NOT have push_branch, create_pull_request, or other remote-mutating tools.`,
|
||||
|
||||
AddressReviews: `Delegate a single subagent to address PR review feedback:
|
||||
|
||||
Include in its prompt:
|
||||
- the PR number to checkout via \`${ghPullfrogMcpName}/checkout_pr\`
|
||||
- instruct it to fetch review comments via \`${ghPullfrogMcpName}/get_review_comments\`
|
||||
- reply to EACH comment individually via \`${ghPullfrogMcpName}/reply_to_review_comment\`
|
||||
- resolve threads via \`${ghPullfrogMcpName}/resolve_review_thread\` after addressing them
|
||||
- test changes and commit locally (do NOT instruct to push — subagents cannot do that)
|
||||
- call \`${ghPullfrogMcpName}/report_progress\` with a brief summary
|
||||
- call \`${ghPullfrogMcpName}/set_output\` with a concise summary of what was addressed (this is how results get back to you)
|
||||
|
||||
After the subagent completes, push the changes via \`${ghPullfrogMcpName}/push_branch\`.
|
||||
|
||||
Use auto or max effort depending on review complexity.`,
|
||||
|
||||
Review: `Delegate a single review subagent:
|
||||
|
||||
Include in its prompt:
|
||||
- the PR number to checkout via \`${ghPullfrogMcpName}/checkout_pr\`
|
||||
- what aspects to focus on (if any specific concerns exist)
|
||||
- instruct it to read the diff, trace data flow, check boundaries, and verify assumptions
|
||||
- draft inline comments with NEW line numbers from the diff
|
||||
- submit via \`${ghPullfrogMcpName}/create_pull_request_review\`
|
||||
- use GitHub permalink format for code references
|
||||
- call \`${ghPullfrogMcpName}/set_output\` with a concise review summary (this is how results get back to you)
|
||||
|
||||
Use max effort for thorough reviews.`,
|
||||
|
||||
Plan: `Delegate a single planning subagent:
|
||||
|
||||
Include in its prompt:
|
||||
- the task to plan for
|
||||
- relevant codebase context (file paths, architecture notes from AGENTS.md)
|
||||
- instruct it to produce a structured, actionable plan with clear milestones
|
||||
- call \`${ghPullfrogMcpName}/report_progress\` with the plan
|
||||
- call \`${ghPullfrogMcpName}/set_output\` with the plan (this is how results get back to you — you'll need the plan to craft the next subagent's prompt)
|
||||
|
||||
Use mini or auto effort. After receiving the plan, you may delegate a Build subagent to implement it.`,
|
||||
|
||||
Fix: `For CI fix tasks, consider a focused single-phase approach:
|
||||
|
||||
Delegate a single fix subagent with:
|
||||
- the check_suite_id to fetch logs via \`${ghPullfrogMcpName}/get_check_suite_logs\`
|
||||
- the PR number to checkout via \`${ghPullfrogMcpName}/checkout_pr\`
|
||||
- CRITICAL: instruct it to verify the failure was INTRODUCED BY THIS PR before fixing. If unrelated, abort and report.
|
||||
- instruct it to read the workflow file, reproduce locally, fix, verify, and commit (do NOT instruct to push — subagents cannot do that)
|
||||
- call \`${ghPullfrogMcpName}/report_progress\` with what was fixed
|
||||
- call \`${ghPullfrogMcpName}/set_output\` with a concise summary of the fix (this is how results get back to you)
|
||||
|
||||
After the subagent completes, push the changes via \`${ghPullfrogMcpName}/push_branch\`.
|
||||
|
||||
Use auto effort.`,
|
||||
|
||||
Prompt: `Delegate a single subagent for this general-purpose task:
|
||||
|
||||
Include in its prompt:
|
||||
- the full task description with all relevant context
|
||||
- if code changes are needed: branch naming, testing, commit instructions (do NOT instruct to push or create PR)
|
||||
- call \`${ghPullfrogMcpName}/report_progress\` with results
|
||||
- call \`${ghPullfrogMcpName}/set_output\` with a concise summary (this is how results get back to you)
|
||||
|
||||
If the task involved code changes, push via \`${ghPullfrogMcpName}/push_branch\` and create a PR via \`${ghPullfrogMcpName}/create_pull_request\` after the subagent completes.
|
||||
|
||||
Use mini effort for simple tasks (labeling, commenting), auto for typical tasks.`,
|
||||
};
|
||||
|
||||
type OrchestratorGuidance = {
|
||||
modeName: string;
|
||||
description: string;
|
||||
orchestratorGuidance: string;
|
||||
};
|
||||
|
||||
function buildOrchestratorGuidance(mode: Mode): OrchestratorGuidance {
|
||||
const guidance = modeGuidance[mode.name] ?? defaultGuidance(mode);
|
||||
return {
|
||||
modeName: mode.name,
|
||||
description: mode.description,
|
||||
orchestratorGuidance: guidance,
|
||||
};
|
||||
}
|
||||
|
||||
export function SelectModeTool(ctx: ToolContext) {
|
||||
return tool({
|
||||
name: "select_mode",
|
||||
description:
|
||||
"Select a mode and receive orchestrator-level guidance on how to handle it, including suggested delegation flows and prompt-crafting tips. Call this before delegating to understand the best approach for the task.",
|
||||
parameters: SelectModeParams,
|
||||
execute: execute(async (params) => {
|
||||
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,
|
||||
})),
|
||||
};
|
||||
}
|
||||
|
||||
ctx.toolState.selectedMode = selectedMode.name;
|
||||
return buildOrchestratorGuidance(selectedMode);
|
||||
}),
|
||||
});
|
||||
}
|
||||
+106
-26
@@ -1,8 +1,8 @@
|
||||
// this must be imported first
|
||||
import "./arkConfig.ts";
|
||||
import { createServer } from "node:net";
|
||||
// this must be imported first
|
||||
import { FastMCP, type Tool } from "fastmcp";
|
||||
import type { Agent } from "../agents/index.ts";
|
||||
import type { Agent, AgentUsage } from "../agents/index.ts";
|
||||
import { ghPullfrogMcpName } from "../external.ts";
|
||||
import type { Mode } from "../modes.ts";
|
||||
import type { PrepResult } from "../prep/index.ts";
|
||||
@@ -21,6 +21,19 @@ export type StoredPushDest = {
|
||||
localBranch: string;
|
||||
};
|
||||
|
||||
export type SubagentStatus = "running" | "completed" | "failed";
|
||||
|
||||
export type SubagentState = {
|
||||
id: string;
|
||||
status: SubagentStatus;
|
||||
mode: string;
|
||||
stdoutFilePath: string;
|
||||
output: string | undefined;
|
||||
usage: AgentUsage | undefined;
|
||||
startedAt: number;
|
||||
keepAliveInterval: ReturnType<typeof setInterval> | undefined;
|
||||
};
|
||||
|
||||
export interface ToolState {
|
||||
// where we're allowed to push - base repo initially, fork URL for fork PRs
|
||||
// set by setupGit, updated by checkout_pr. always set before push validation.
|
||||
@@ -31,8 +44,10 @@ export interface ToolState {
|
||||
// issue or PR number (same number space in GitHub)
|
||||
issueNumber?: number;
|
||||
selectedMode?: string;
|
||||
// true while a subagent is running via the delegate tool — prevents recursive delegation
|
||||
delegationActive: boolean;
|
||||
// per-subagent lifecycle tracking (keyed by subagent uuid)
|
||||
subagents: Map<string, SubagentState>;
|
||||
// set while a subagent is running — routes set_output to the correct subagent and prevents nesting
|
||||
activeSubagentId: string | undefined;
|
||||
backgroundProcesses: Map<string, BackgroundProcess>;
|
||||
review?: {
|
||||
id: number;
|
||||
@@ -48,6 +63,7 @@ export interface ToolState {
|
||||
lastProgressBody?: string;
|
||||
wasUpdated?: boolean;
|
||||
output?: string;
|
||||
usageEntries: AgentUsage[];
|
||||
}
|
||||
|
||||
interface InitToolStateParams {
|
||||
@@ -56,7 +72,7 @@ interface InitToolStateParams {
|
||||
|
||||
export function initToolState(params: InitToolStateParams): ToolState {
|
||||
const parsed = params.progressCommentId ? parseInt(params.progressCommentId, 10) : NaN;
|
||||
const resolvedId = Number.isNaN(parsed) ? undefined : parsed;
|
||||
const resolvedId = Number.isNaN(parsed) || parsed <= 0 ? undefined : parsed;
|
||||
|
||||
if (resolvedId) {
|
||||
log.info(`» using pre-created progress comment: ${resolvedId}`);
|
||||
@@ -64,8 +80,10 @@ export function initToolState(params: InitToolStateParams): ToolState {
|
||||
|
||||
return {
|
||||
progressCommentId: resolvedId,
|
||||
delegationActive: false,
|
||||
subagents: new Map(),
|
||||
activeSubagentId: undefined,
|
||||
backgroundProcesses: new Map(),
|
||||
usageEntries: [],
|
||||
};
|
||||
}
|
||||
|
||||
@@ -87,8 +105,27 @@ export interface ToolContext {
|
||||
tmpdir: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* tool names that are only available to the orchestrator.
|
||||
* subagent MCP servers are started with these tools excluded.
|
||||
*
|
||||
* - delegation tools: only the orchestrator can spawn/manage subagents
|
||||
* - remote-mutating tools: subagents work locally; the orchestrator pushes and creates PRs
|
||||
*/
|
||||
export const ORCHESTRATOR_ONLY_TOOLS = [
|
||||
"select_mode",
|
||||
"delegate",
|
||||
"ask_question",
|
||||
"push_branch",
|
||||
"push_tags",
|
||||
"delete_branch",
|
||||
"create_pull_request",
|
||||
"update_pull_request_body",
|
||||
] as const;
|
||||
|
||||
import { log } from "../utils/cli.ts";
|
||||
import type { RunContextData } from "../utils/runContextData.ts";
|
||||
import { AskQuestionTool } from "./askQuestion.ts";
|
||||
import { BashTool, KillBackgroundTool } from "./bash.ts";
|
||||
import { CheckoutPrTool } from "./checkout.ts";
|
||||
import { GetCheckSuiteLogsTool } from "./checkSuite.ts";
|
||||
@@ -118,7 +155,7 @@ import { GetIssueEventsTool } from "./issueEvents.ts";
|
||||
import { IssueInfoTool } from "./issueInfo.ts";
|
||||
import { AddLabelsTool } from "./labels.ts";
|
||||
import { SetOutputTool } from "./output.ts";
|
||||
import { CreatePullRequestTool } from "./pr.ts";
|
||||
import { CreatePullRequestTool, UpdatePullRequestBodyTool } from "./pr.ts";
|
||||
import { PullRequestInfoTool } from "./prInfo.ts";
|
||||
import { CreatePullRequestReviewTool } from "./review.ts";
|
||||
import {
|
||||
@@ -126,6 +163,7 @@ import {
|
||||
ListPullRequestReviewsTool,
|
||||
ResolveReviewThreadTool,
|
||||
} from "./reviewComments.ts";
|
||||
import { SelectModeTool } from "./selectMode.ts";
|
||||
import { addTools } from "./shared.ts";
|
||||
import { UploadFileTool } from "./upload.ts";
|
||||
|
||||
@@ -165,9 +203,10 @@ function isAddressInUse(error: unknown): boolean {
|
||||
const message = getErrorMessage(error).toLowerCase();
|
||||
return message.includes("eaddrinuse") || message.includes("address already in use");
|
||||
}
|
||||
function buildTools(ctx: ToolContext): Tool<any, any>[] {
|
||||
|
||||
// tools shared by both orchestrator and subagent servers
|
||||
function buildCommonTools(ctx: ToolContext): Tool<any, any>[] {
|
||||
const tools: Tool<any, any>[] = [
|
||||
DelegateTool(ctx),
|
||||
StartDependencyInstallationTool(ctx),
|
||||
AwaitDependencyInstallationTool(ctx),
|
||||
CreateCommentTool(ctx),
|
||||
@@ -177,7 +216,6 @@ function buildTools(ctx: ToolContext): Tool<any, any>[] {
|
||||
IssueInfoTool(ctx),
|
||||
GetIssueCommentsTool(ctx),
|
||||
GetIssueEventsTool(ctx),
|
||||
CreatePullRequestTool(ctx),
|
||||
CreatePullRequestReviewTool(ctx),
|
||||
PullRequestInfoTool(ctx),
|
||||
CommitInfoTool(ctx),
|
||||
@@ -187,11 +225,8 @@ function buildTools(ctx: ToolContext): Tool<any, any>[] {
|
||||
ResolveReviewThreadTool(ctx),
|
||||
GetCheckSuiteLogsTool(ctx),
|
||||
AddLabelsTool(ctx),
|
||||
PushBranchTool(ctx),
|
||||
GitTool(ctx),
|
||||
GitFetchTool(ctx),
|
||||
DeleteBranchTool(ctx),
|
||||
PushTagsTool(ctx),
|
||||
UploadFileTool(ctx),
|
||||
SetOutputTool(ctx),
|
||||
FileReadTool(ctx),
|
||||
@@ -199,6 +234,7 @@ function buildTools(ctx: ToolContext): Tool<any, any>[] {
|
||||
FileEditTool(ctx),
|
||||
FileDeleteTool(ctx),
|
||||
ListDirectoryTool(ctx),
|
||||
ReportProgressTool(ctx),
|
||||
];
|
||||
|
||||
// only add BashTool when bash is "restricted"
|
||||
@@ -210,23 +246,41 @@ function buildTools(ctx: ToolContext): Tool<any, any>[] {
|
||||
tools.push(KillBackgroundTool(ctx));
|
||||
}
|
||||
|
||||
tools.push(ReportProgressTool(ctx));
|
||||
|
||||
return tools;
|
||||
}
|
||||
|
||||
// orchestrator gets common tools + delegation + remote-mutating tools
|
||||
function buildOrchestratorTools(ctx: ToolContext): Tool<any, any>[] {
|
||||
return [
|
||||
...buildCommonTools(ctx),
|
||||
SelectModeTool(ctx),
|
||||
DelegateTool(ctx),
|
||||
AskQuestionTool(ctx),
|
||||
PushBranchTool(ctx),
|
||||
PushTagsTool(ctx),
|
||||
DeleteBranchTool(ctx),
|
||||
CreatePullRequestTool(ctx),
|
||||
UpdatePullRequestBodyTool(ctx),
|
||||
];
|
||||
}
|
||||
|
||||
// subagent gets only common tools (no delegation, no remote mutation)
|
||||
function buildSubagentTools(ctx: ToolContext): Tool<any, any>[] {
|
||||
return buildCommonTools(ctx);
|
||||
}
|
||||
|
||||
type McpStartResult = {
|
||||
server: FastMCP;
|
||||
url: string;
|
||||
port: number;
|
||||
};
|
||||
|
||||
async function tryStartMcpServer(ctx: ToolContext, port: number): Promise<McpStartResult | null> {
|
||||
const server = new FastMCP({
|
||||
name: ghPullfrogMcpName,
|
||||
version: "0.0.1",
|
||||
});
|
||||
const tools = buildTools(ctx);
|
||||
async function tryStartMcpServer(
|
||||
ctx: ToolContext,
|
||||
tools: Tool<any, any>[],
|
||||
port: number
|
||||
): Promise<McpStartResult | null> {
|
||||
const server = new FastMCP({ name: ghPullfrogMcpName, version: "0.0.1" });
|
||||
addTools(ctx, server, tools);
|
||||
|
||||
try {
|
||||
@@ -253,13 +307,13 @@ async function tryStartMcpServer(ctx: ToolContext, port: number): Promise<McpSta
|
||||
}
|
||||
}
|
||||
|
||||
async function selectMcpPort(ctx: ToolContext): Promise<McpStartResult> {
|
||||
async function selectMcpPort(ctx: ToolContext, tools: Tool<any, any>[]): Promise<McpStartResult> {
|
||||
let lastError: unknown = null;
|
||||
|
||||
const requestedPort = readEnvPort();
|
||||
if (requestedPort !== null) {
|
||||
if (await isPortAvailable(requestedPort)) {
|
||||
const requestedResult = await tryStartMcpServer(ctx, requestedPort);
|
||||
const requestedResult = await tryStartMcpServer(ctx, tools, requestedPort);
|
||||
if (requestedResult) {
|
||||
return requestedResult;
|
||||
}
|
||||
@@ -275,7 +329,7 @@ async function selectMcpPort(ctx: ToolContext): Promise<McpStartResult> {
|
||||
if (!(await isPortAvailable(port))) {
|
||||
continue;
|
||||
}
|
||||
const result = await tryStartMcpServer(ctx, port);
|
||||
const result = await tryStartMcpServer(ctx, tools, port);
|
||||
if (result) {
|
||||
return result;
|
||||
}
|
||||
@@ -315,12 +369,13 @@ async function killBackgroundProcesses(toolState: ToolState): Promise<void> {
|
||||
}
|
||||
|
||||
/**
|
||||
* Start the MCP HTTP server and return the URL and close function
|
||||
* Start the orchestrator MCP HTTP server (has all tools including push/PR/delegation).
|
||||
*/
|
||||
export async function startMcpHttpServer(
|
||||
ctx: ToolContext
|
||||
): Promise<{ url: string; [Symbol.asyncDispose]: () => Promise<void> }> {
|
||||
const startResult = await selectMcpPort(ctx);
|
||||
const tools = buildOrchestratorTools(ctx);
|
||||
const startResult = await selectMcpPort(ctx, tools);
|
||||
|
||||
return {
|
||||
url: startResult.url,
|
||||
@@ -330,3 +385,28 @@ export async function startMcpHttpServer(
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
export type ManagedMcpServer = {
|
||||
url: string;
|
||||
stop: () => Promise<void>;
|
||||
};
|
||||
|
||||
/**
|
||||
* Start a per-subagent MCP server (common tools only — no push/PR/delegation).
|
||||
* Each subagent gets its own server; call stop() when the subagent completes.
|
||||
*
|
||||
* The subagent gets its own shallow copy of toolState so scalar writes
|
||||
* (pushUrl, pushDest, selectedMode, etc.) don't mutate the orchestrator's state.
|
||||
* Shared references (subagents Map, usageEntries array, dependencyInstallation)
|
||||
* are intentionally shared for coordination (set_output routing, usage tracking).
|
||||
*/
|
||||
export async function startSubagentMcpServer(ctx: ToolContext): Promise<ManagedMcpServer> {
|
||||
const subagentToolState: ToolState = {
|
||||
...ctx.toolState,
|
||||
backgroundProcesses: new Map(),
|
||||
};
|
||||
const subagentCtx: ToolContext = { ...ctx, toolState: subagentToolState };
|
||||
const tools = buildSubagentTools(subagentCtx);
|
||||
const startResult = await selectMcpPort(subagentCtx, tools);
|
||||
return { url: startResult.url, stop: () => startResult.server.stop() };
|
||||
}
|
||||
|
||||
+1
-2
@@ -58,7 +58,6 @@ export const execute = <T, R extends Record<string, any> | string>(
|
||||
return handleToolError(error);
|
||||
}
|
||||
};
|
||||
(_fn as any).raw = fn;
|
||||
return _fn;
|
||||
};
|
||||
|
||||
@@ -183,7 +182,7 @@ function sanitizeTool<T extends Tool<any, any>>(tool: T): T {
|
||||
} as T;
|
||||
}
|
||||
|
||||
export const addTools = (ctx: ToolContext, server: FastMCP, tools: Tool<any, any>[]) => {
|
||||
export const addTools = (ctx: ToolContext, server: FastMCP<any>, tools: Tool<any, any>[]) => {
|
||||
// sanitize schemas for gemini agent and opencode (when using Google API)
|
||||
// both have issues with draft-2020-12 schemas and any_of enum constructs
|
||||
const shouldSanitize = ctx.agent.name === "gemini" || ctx.agent.name === "opencode";
|
||||
|
||||
+103
@@ -0,0 +1,103 @@
|
||||
import { randomUUID } from "node:crypto";
|
||||
import { writeFileSync } from "node:fs";
|
||||
import { join } from "node:path";
|
||||
import type { Effort } from "../external.ts";
|
||||
import { markActivity } from "../utils/activity.ts";
|
||||
import type { ResolvedInstructions } from "../utils/instructions.ts";
|
||||
import { type SubagentState, startSubagentMcpServer, type ToolContext } from "./server.ts";
|
||||
|
||||
type CreateSubagentParams = {
|
||||
ctx: ToolContext;
|
||||
mode: string;
|
||||
};
|
||||
|
||||
export function createSubagentState(params: CreateSubagentParams): SubagentState {
|
||||
const id = randomUUID();
|
||||
const stdoutFilePath = join(params.ctx.tmpdir, `subagent-${id}.log`);
|
||||
const state: SubagentState = {
|
||||
id,
|
||||
status: "running",
|
||||
mode: params.mode,
|
||||
stdoutFilePath,
|
||||
output: undefined,
|
||||
usage: undefined,
|
||||
startedAt: Date.now(),
|
||||
keepAliveInterval: undefined,
|
||||
};
|
||||
params.ctx.toolState.subagents.set(id, state);
|
||||
params.ctx.toolState.activeSubagentId = id;
|
||||
return state;
|
||||
}
|
||||
|
||||
type CompleteSubagentParams = {
|
||||
ctx: ToolContext;
|
||||
subagent: SubagentState;
|
||||
success: boolean;
|
||||
};
|
||||
|
||||
function completeSubagent(params: CompleteSubagentParams): void {
|
||||
params.subagent.status = params.success ? "completed" : "failed";
|
||||
if (params.subagent.keepAliveInterval) {
|
||||
clearInterval(params.subagent.keepAliveInterval);
|
||||
params.subagent.keepAliveInterval = undefined;
|
||||
}
|
||||
if (params.subagent.usage) {
|
||||
params.ctx.toolState.usageEntries.push(params.subagent.usage);
|
||||
}
|
||||
params.ctx.toolState.activeSubagentId = undefined;
|
||||
// keep completed subagents in the map for post-completion inspection
|
||||
}
|
||||
|
||||
export function buildSubagentInstructions(orchestratorPrompt: string): ResolvedInstructions {
|
||||
return {
|
||||
full: orchestratorPrompt,
|
||||
system: "",
|
||||
user: orchestratorPrompt,
|
||||
eventInstructions: "",
|
||||
repo: "",
|
||||
event: "",
|
||||
runtime: "",
|
||||
};
|
||||
}
|
||||
|
||||
type RunSubagentParams = {
|
||||
ctx: ToolContext;
|
||||
subagent: SubagentState;
|
||||
effort: Effort;
|
||||
instructions: string;
|
||||
};
|
||||
|
||||
type RunSubagentResult = {
|
||||
success: boolean;
|
||||
error: string | undefined;
|
||||
};
|
||||
|
||||
export async function runSubagent(params: RunSubagentParams): Promise<RunSubagentResult> {
|
||||
params.subagent.keepAliveInterval = setInterval(markActivity, 30_000);
|
||||
const mcpServer = await startSubagentMcpServer(params.ctx);
|
||||
try {
|
||||
const subagentPayload = { ...params.ctx.payload, effort: params.effort };
|
||||
const subagentInstructions = buildSubagentInstructions(params.instructions);
|
||||
const result = await params.ctx.agent.run({
|
||||
payload: subagentPayload,
|
||||
mcpServerUrl: mcpServer.url,
|
||||
tmpdir: params.ctx.tmpdir,
|
||||
instructions: subagentInstructions,
|
||||
});
|
||||
params.subagent.usage = result.usage;
|
||||
writeFileSync(params.subagent.stdoutFilePath, result.output ?? "", "utf-8");
|
||||
completeSubagent({ ctx: params.ctx, subagent: params.subagent, success: result.success });
|
||||
return { success: result.success, error: result.error };
|
||||
} catch (err) {
|
||||
const errorMessage = err instanceof Error ? err.message : String(err);
|
||||
try {
|
||||
writeFileSync(params.subagent.stdoutFilePath, "", "utf-8");
|
||||
} catch {
|
||||
// best-effort
|
||||
}
|
||||
completeSubagent({ ctx: params.ctx, subagent: params.subagent, success: false });
|
||||
return { success: false, error: errorMessage };
|
||||
} finally {
|
||||
await mcpServer.stop();
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,167 @@
|
||||
import { createServer } from "node:net";
|
||||
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
|
||||
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
|
||||
import { type } from "arktype";
|
||||
import { FastMCP } from "fastmcp";
|
||||
import { afterAll, beforeAll, describe, expect, it } from "vitest";
|
||||
import { ORCHESTRATOR_ONLY_TOOLS } from "./server.ts";
|
||||
import { execute, tool } from "./shared.ts";
|
||||
import { buildSubagentInstructions } from "./subagent.ts";
|
||||
|
||||
// ─── unit tests for pure exported functions ─────────────────────────────
|
||||
|
||||
describe("ORCHESTRATOR_ONLY_TOOLS", () => {
|
||||
it("includes delegation tools", () => {
|
||||
expect(ORCHESTRATOR_ONLY_TOOLS).toContain("select_mode");
|
||||
expect(ORCHESTRATOR_ONLY_TOOLS).toContain("delegate");
|
||||
expect(ORCHESTRATOR_ONLY_TOOLS).toContain("ask_question");
|
||||
});
|
||||
|
||||
it("includes remote-mutating tools", () => {
|
||||
expect(ORCHESTRATOR_ONLY_TOOLS).toContain("push_branch");
|
||||
expect(ORCHESTRATOR_ONLY_TOOLS).toContain("push_tags");
|
||||
expect(ORCHESTRATOR_ONLY_TOOLS).toContain("delete_branch");
|
||||
expect(ORCHESTRATOR_ONLY_TOOLS).toContain("create_pull_request");
|
||||
expect(ORCHESTRATOR_ONLY_TOOLS).toContain("update_pull_request_body");
|
||||
});
|
||||
});
|
||||
|
||||
describe("buildSubagentInstructions", () => {
|
||||
it("returns clean-room instructions with only the orchestrator prompt", () => {
|
||||
const prompt = "Read file.ts and fix the type error.";
|
||||
const instructions = buildSubagentInstructions(prompt);
|
||||
expect(instructions).toEqual({
|
||||
full: prompt,
|
||||
system: "",
|
||||
user: prompt,
|
||||
eventInstructions: "",
|
||||
repo: "",
|
||||
event: "",
|
||||
runtime: "",
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
// ─── per-server tool isolation integration test ─────────────────────────
|
||||
// demonstrates the architecture: orchestrator and subagent get separate servers
|
||||
|
||||
function getRandomPort(): Promise<number> {
|
||||
return new Promise((resolve, reject) => {
|
||||
const srv = createServer();
|
||||
srv.listen(0, "127.0.0.1", () => {
|
||||
const addr = srv.address();
|
||||
if (!addr || typeof addr === "string") return reject(new Error("bad address"));
|
||||
const port = addr.port;
|
||||
srv.close(() => resolve(port));
|
||||
});
|
||||
});
|
||||
}
|
||||
|
||||
async function connectMcpClient(url: string): Promise<Client> {
|
||||
const transport = new StreamableHTTPClientTransport(new URL(url));
|
||||
const client = new Client({ name: "test-client", version: "0.0.1" });
|
||||
// @ts-expect-error — exactOptionalPropertyTypes mismatch: SDK Transport.sessionId?: string vs StreamableHTTPClientTransport getter returning string | undefined
|
||||
await client.connect(transport);
|
||||
return client;
|
||||
}
|
||||
|
||||
function mockTool(name: string, description: string) {
|
||||
return tool({
|
||||
name,
|
||||
description,
|
||||
parameters: type({ value: "string" }),
|
||||
execute: execute(async () => ({ ok: true })),
|
||||
});
|
||||
}
|
||||
|
||||
describe("per-server tool isolation - integration", () => {
|
||||
let orchestratorServer: FastMCP;
|
||||
let subagentServer: FastMCP;
|
||||
let orchestratorUrl: string;
|
||||
let subagentUrl: string;
|
||||
const clients: Client[] = [];
|
||||
|
||||
beforeAll(async () => {
|
||||
const [orchestratorPort, subagentPort] = await Promise.all([getRandomPort(), getRandomPort()]);
|
||||
orchestratorUrl = `http://127.0.0.1:${orchestratorPort}/mcp`;
|
||||
subagentUrl = `http://127.0.0.1:${subagentPort}/mcp`;
|
||||
|
||||
// orchestrator gets ALL tools (common + delegation + remote mutation)
|
||||
orchestratorServer = new FastMCP({ name: "orchestrator", version: "0.0.1" });
|
||||
orchestratorServer.addTool(mockTool("file_read", "read a file"));
|
||||
orchestratorServer.addTool(mockTool("git", "run git commands"));
|
||||
orchestratorServer.addTool(mockTool("set_output", "set output"));
|
||||
orchestratorServer.addTool(mockTool("select_mode", "select a mode"));
|
||||
orchestratorServer.addTool(mockTool("delegate", "delegate a task"));
|
||||
orchestratorServer.addTool(mockTool("ask_question", "ask a question"));
|
||||
orchestratorServer.addTool(mockTool("push_branch", "push branch"));
|
||||
orchestratorServer.addTool(mockTool("create_pull_request", "create PR"));
|
||||
|
||||
// subagent gets ONLY common tools (no delegation, no remote mutation)
|
||||
subagentServer = new FastMCP({ name: "subagent", version: "0.0.1" });
|
||||
subagentServer.addTool(mockTool("file_read", "read a file"));
|
||||
subagentServer.addTool(mockTool("git", "run git commands"));
|
||||
subagentServer.addTool(mockTool("set_output", "set output"));
|
||||
|
||||
await Promise.all([
|
||||
orchestratorServer.start({
|
||||
transportType: "httpStream",
|
||||
httpStream: { port: orchestratorPort, host: "127.0.0.1", endpoint: "/mcp" },
|
||||
}),
|
||||
subagentServer.start({
|
||||
transportType: "httpStream",
|
||||
httpStream: { port: subagentPort, host: "127.0.0.1", endpoint: "/mcp" },
|
||||
}),
|
||||
]);
|
||||
});
|
||||
|
||||
afterAll(async () => {
|
||||
for (const client of clients) {
|
||||
try {
|
||||
await client.close();
|
||||
} catch {
|
||||
// best-effort cleanup
|
||||
}
|
||||
}
|
||||
await Promise.all([orchestratorServer.stop(), subagentServer.stop()]);
|
||||
});
|
||||
|
||||
it("orchestrator sees all tools including delegation and mutation", async () => {
|
||||
const client = await connectMcpClient(orchestratorUrl);
|
||||
clients.push(client);
|
||||
const result = await client.listTools();
|
||||
const names = result.tools.map((t) => t.name);
|
||||
expect(names).toContain("select_mode");
|
||||
expect(names).toContain("delegate");
|
||||
expect(names).toContain("ask_question");
|
||||
expect(names).toContain("push_branch");
|
||||
expect(names).toContain("create_pull_request");
|
||||
expect(names).toContain("file_read");
|
||||
expect(names).toContain("git");
|
||||
expect(names).toContain("set_output");
|
||||
expect(names.length).toBe(8);
|
||||
});
|
||||
|
||||
it("subagent cannot see delegation or mutation tools", async () => {
|
||||
const client = await connectMcpClient(subagentUrl);
|
||||
clients.push(client);
|
||||
const result = await client.listTools();
|
||||
const names = result.tools.map((t) => t.name);
|
||||
expect(names).not.toContain("select_mode");
|
||||
expect(names).not.toContain("delegate");
|
||||
expect(names).not.toContain("ask_question");
|
||||
expect(names).not.toContain("push_branch");
|
||||
expect(names).not.toContain("create_pull_request");
|
||||
});
|
||||
|
||||
it("subagent sees only common tools", async () => {
|
||||
const client = await connectMcpClient(subagentUrl);
|
||||
clients.push(client);
|
||||
const result = await client.listTools();
|
||||
const names = result.tools.map((t) => t.name);
|
||||
expect(names).toContain("file_read");
|
||||
expect(names).toContain("git");
|
||||
expect(names).toContain("set_output");
|
||||
expect(names.length).toBe(3);
|
||||
});
|
||||
});
|
||||
Reference in New Issue
Block a user