refactor: replace narrow parameter types with context objects (#519)

* refactor: replace narrow parameter types with context objects across action/

pass broader context objects (ToolContext, PromptContext, PostCleanupContext) to
utility functions instead of cherry-picking fields into single-use interfaces.
deletes 8 narrow types, simplifies call sites, and makes buildCommentFooter
synchronous by reading ctx.runId/ctx.jobId directly instead of re-deriving
from env vars and making an extra API call.

Made-with: Cursor

* fix: replace non-null assertion with local guard in validatePushDestination

addresses review feedback — the function now validates pushUrl itself instead
of relying on the caller's check, eliminating the ! assertion.

Made-with: Cursor

* revert: remove GH_TOKEN injection from restricted shell

the original change exposed the git token in restricted-mode shell so
`gh` CLI would work. this is a security regression for public repos: MCP
tools are deliberately constrained (no merge, no release, no arbitrary
API calls), but `gh api` with the token gives full GitHub API access to
any prompt-injected agent.

Made-with: Cursor

mcp/checkout.test.ts

@@ -1,7 +1,8 @@
-import { Octokit } from "@octokit/rest";
+import type { RestEndpointMethodTypes } from "@octokit/rest";
 import { describe, expect, it } from "vitest";
-import { acquireNewToken } from "../utils/github.ts";
+import { acquireNewToken, createOctokit } from "../utils/github.ts";
 import { fetchAndFormatPrDiff } from "./checkout.ts";
+import type { ToolContext } from "./server.ts";
 
 /**
  * parses TOC entries like "- src/math.ts → lines 7-42" into structured data.
@@ -33,13 +34,16 @@ describe("fetchAndFormatPrDiff", () => {
     { timeout: 30000 },
     async () => {
       const token = await getToken();
-      const octokit = new Octokit({ auth: token });
-      const result = await fetchAndFormatPrDiff({
+      const octokit = createOctokit(token);
+      const ctx = {
         octokit,
-        owner: "pullfrog",
-        repo: "test-repo",
-        pullNumber: 1,
-      });
+        repo: {
+          owner: "pullfrog",
+          name: "test-repo",
+          data: {} as RestEndpointMethodTypes["repos"]["get"]["response"]["data"],
+        },
+      } as ToolContext;
+      const result = await fetchAndFormatPrDiff(ctx, 1);
 
       // verify content includes TOC at the start
       expect(result.content.startsWith(result.toc)).toBe(true);

mcp/checkout.ts

@@ -145,22 +145,18 @@ export type CheckoutPrResult = {
   instructions: string;
 };
 
-type FetchPrDiffParams = {
-  octokit: Octokit;
-  owner: string;
-  repo: string;
-  pullNumber: number;
-};
-
 /**
  * fetches PR files from GitHub and formats them with line numbers and TOC.
  * this is the core diff formatting logic, extracted for testability.
  */
-export async function fetchAndFormatPrDiff(params: FetchPrDiffParams): Promise<FormatFilesResult> {
-  const files = await params.octokit.paginate(params.octokit.rest.pulls.listFiles, {
-    owner: params.owner,
-    repo: params.repo,
-    pull_number: params.pullNumber,
+export async function fetchAndFormatPrDiff(
+  ctx: ToolContext,
+  pullNumber: number
+): Promise<FormatFilesResult> {
+  const files = await ctx.octokit.paginate(ctx.octokit.rest.pulls.listFiles, {
+    owner: ctx.repo.owner,
+    repo: ctx.repo.name,
+    pull_number: pullNumber,
     per_page: 100,
   });
   return formatFilesWithLineNumbers(files);
@@ -502,12 +498,7 @@ export function CheckoutPrTool(ctx: ToolContext) {
       }
 
       // fetch PR files and format with line numbers
-      const formatResult = await fetchAndFormatPrDiff({
-        octokit: ctx.octokit,
-        owner: ctx.repo.owner,
-        repo: ctx.repo.name,
-        pullNumber: pull_number,
-      });
+      const formatResult = await fetchAndFormatPrDiff(ctx, pull_number);
       const diffPreview = formatResult.content.split("\n").slice(0, 100).join("\n");
       log.debug(`formatted diff preview (first 100 lines):\n${diffPreview}`);
       const diffPath = join(tempDir, `pr-${pull_number}-${headShort}.diff`);

mcp/comment.ts

@@ -4,7 +4,6 @@ import { getApiUrl } from "../utils/apiUrl.ts";
 import { buildPullfrogFooter, stripExistingFooter } from "../utils/buildPullfrogFooter.ts";
 import { log } from "../utils/cli.ts";
 import { fixDoubleEscapedString } from "../utils/fixDoubleEscapedString.ts";
-import { type OctokitWithPlugins, parseRepoContext } from "../utils/github.ts";
 import { retry } from "../utils/retry.ts";
 import type { ToolContext } from "./server.ts";
 import { execute, tool } from "./shared.ts";
@@ -52,65 +51,37 @@ export async function updateCommentNodeId(
  */
 export const LEAPING_INTO_ACTION_PREFIX = "Leaping into action";
 
-interface BuildCommentFooterParams {
-  octokit?: OctokitWithPlugins | undefined;
-  customParts?: string[] | undefined;
-  model?: string | undefined;
-}
-
-async function buildCommentFooter(params: BuildCommentFooterParams): Promise<string> {
-  const repoContext = parseRepoContext();
-  const runId = process.env.GITHUB_RUN_ID
-    ? Number.parseInt(process.env.GITHUB_RUN_ID, 10)
-    : undefined;
-
-  let jobId: string | undefined;
-  if (runId && params.octokit) {
-    try {
-      const { data: jobs } = await params.octokit.rest.actions.listJobsForWorkflowRun({
-        owner: repoContext.owner,
-        repo: repoContext.name,
-        run_id: runId,
-      });
-      jobId = jobs.jobs[0]?.id.toString();
-    } catch {
-      // fall back to computed URL from runId alone
-    }
-  }
-
+function buildCommentFooter(ctx: ToolContext, customParts?: string[]): string {
+  const runId = ctx.runId;
   return buildPullfrogFooter({
     triggeredBy: true,
-    workflowRun: runId
-      ? { owner: repoContext.owner, repo: repoContext.name, runId, jobId }
-      : undefined,
-    customParts: params.customParts,
-    model: params.model,
+    workflowRun:
+      runId !== undefined
+        ? {
+            owner: ctx.repo.owner,
+            repo: ctx.repo.name,
+            runId,
+            jobId: ctx.jobId,
+          }
+        : undefined,
+    customParts,
+    model: ctx.toolState.model,
   });
 }
 
-function buildImplementPlanLink(
-  owner: string,
-  repo: string,
-  issueNumber: number,
-  commentId: number
-): string {
+function buildImplementPlanLink(ctx: ToolContext, issueNumber: number, commentId: number): string {
   const apiUrl = getApiUrl();
-  return `[Implement plan ➔](${apiUrl}/trigger/${owner}/${repo}/${issueNumber}?action=implement&comment_id=${commentId})`;
+  return `[Implement plan ➔](${apiUrl}/trigger/${ctx.repo.owner}/${ctx.repo.name}/${issueNumber}?action=implement&comment_id=${commentId})`;
 }
 
-export interface AddFooterCtx {
-  octokit?: OctokitWithPlugins | undefined;
-  toolState?: { model?: string | undefined } | undefined;
-}
-
-export async function addFooter(ctx: AddFooterCtx, body: string): Promise<string> {
+export function addFooter(ctx: ToolContext, body: string): string {
   if (/<br\s*\/?>[ \t]*\n(?!\s*\n)/i.test(body)) {
     throw new Error(
       "body contains <br/> followed by a non-blank line, which breaks GitHub markdown rendering. always add a blank line after <br/> tags."
     );
   }
   const bodyWithoutFooter = stripExistingFooter(fixDoubleEscapedString(body));
-  const footer = await buildCommentFooter({ octokit: ctx.octokit, model: ctx.toolState?.model });
+  const footer = buildCommentFooter(ctx);
   return `${bodyWithoutFooter}${footer}`;
 }
 
@@ -132,7 +103,7 @@ export function CreateCommentTool(ctx: ToolContext) {
       "Create a comment on a GitHub issue or PR. For progress/plan updates on the current run use report_progress instead. Use type: 'Plan' for plan comments, type: 'Summary' for PR summary comments.",
     parameters: Comment,
     execute: execute(async ({ issueNumber, body, type: commentType }) => {
-      const bodyWithFooter = await addFooter(ctx, body);
+      const bodyWithFooter = addFooter(ctx, body);
 
       // if a summary comment already exists (found by select_mode), update instead of creating
       if (commentType === "Summary" && ctx.toolState.existingSummaryCommentId) {
@@ -193,7 +164,7 @@ export function EditCommentTool(ctx: ToolContext) {
     description: "Edit a GitHub issue comment by its ID",
     parameters: EditComment,
     execute: execute(async ({ commentId, body }) => {
-      const bodyWithFooter = await addFooter(ctx, body);
+      const bodyWithFooter = addFooter(ctx, body);
 
       const result = await ctx.octokit.rest.issues.updateComment({
         owner: ctx.repo.owner,
@@ -260,14 +231,10 @@ export async function reportProgress(
     const commentId = ctx.toolState.existingPlanCommentId;
     const customParts =
       isPlanMode && issueNumber !== undefined
-        ? [buildImplementPlanLink(ctx.repo.owner, ctx.repo.name, issueNumber, commentId)]
+        ? [buildImplementPlanLink(ctx, issueNumber, commentId)]
         : undefined;
     const bodyWithoutFooter = stripExistingFooter(body);
-    const footer = await buildCommentFooter({
-      octokit: ctx.octokit,
-      customParts,
-      model: ctx.toolState.model,
-    });
+    const footer = buildCommentFooter(ctx, customParts);
     const bodyWithFooter = `${bodyWithoutFooter}${footer}`;
 
     const result = await ctx.octokit.rest.issues.updateComment({
@@ -297,15 +264,11 @@ export async function reportProgress(
   if (existingCommentId) {
     const customParts =
       isPlanMode && issueNumber !== undefined
-        ? [buildImplementPlanLink(ctx.repo.owner, ctx.repo.name, issueNumber, existingCommentId)]
+        ? [buildImplementPlanLink(ctx, issueNumber, existingCommentId)]
         : undefined;
 
     const bodyWithoutFooter = stripExistingFooter(body);
-    const footer = await buildCommentFooter({
-      octokit: ctx.octokit,
-      customParts,
-      model: ctx.toolState.model,
-    });
+    const footer = buildCommentFooter(ctx, customParts);
     const bodyWithFooter = `${bodyWithoutFooter}${footer}`;
 
     const result = await ctx.octokit.rest.issues.updateComment({
@@ -343,7 +306,7 @@ export async function reportProgress(
   }
 
   // for new comments, we need to create first, then update with Plan link if in Plan mode
-  const initialBody = await addFooter(ctx, body);
+  const initialBody = addFooter(ctx, body);
 
   const result = await ctx.octokit.rest.issues.createComment({
     owner: ctx.repo.owner,
@@ -358,15 +321,9 @@ export async function reportProgress(
 
   // if Plan mode, update the comment to add the "Implement plan" link
   if (isPlanMode) {
-    const customParts = [
-      buildImplementPlanLink(ctx.repo.owner, ctx.repo.name, issueNumber, result.data.id),
-    ];
+    const customParts = [buildImplementPlanLink(ctx, issueNumber, result.data.id)];
     const bodyWithoutFooter = stripExistingFooter(body);
-    const footer = await buildCommentFooter({
-      octokit: ctx.octokit,
-      customParts,
-      model: ctx.toolState.model,
-    });
+    const footer = buildCommentFooter(ctx, customParts);
     const bodyWithPlanLink = `${bodyWithoutFooter}${footer}`;
 
     const updateResult = await ctx.octokit.rest.issues.updateComment({
@@ -490,7 +447,7 @@ export function ReplyToReviewCommentTool(ctx: ToolContext) {
       "Reply to a PR review comment thread (NOT issue comments — this only works for inline review comments on PR diffs). Call this for EACH comment you address in AddressReviews mode. Keep replies extremely brief (1 sentence max).",
     parameters: ReplyToReviewComment,
     execute: execute(async ({ pull_number, comment_id, body }) => {
-      const bodyWithFooter = await addFooter(ctx, body);
+      const bodyWithFooter = addFooter(ctx, body);
 
       const result = await ctx.octokit.rest.pulls.createReplyForReviewComment({
         owner: ctx.repo.owner,

mcp/git.ts

@@ -57,23 +57,20 @@ function normalizeUrl(url: string): string {
   return url.replace(/\.git$/, "").toLowerCase();
 }
 
-type ValidatePushParams = {
-  branch: string;
-  pushUrl: string;
-  storedDest: StoredPushDest | undefined;
-};
-
 /**
  * validate that the push destination matches expected URL.
  * pushUrl is set by setupGit (base repo) and updated by checkout_pr (fork repo).
  */
-function validatePushDestination(params: ValidatePushParams): PushDestination {
-  const dest = getPushDestination(params.branch, params.storedDest);
+function validatePushDestination(ctx: ToolContext, branch: string): PushDestination {
+  const pushUrl = ctx.toolState.pushUrl;
+  if (!pushUrl) throw new Error("pushUrl not set - setupGit must run before push_branch");
 
-  if (normalizeUrl(dest.url) !== normalizeUrl(params.pushUrl)) {
+  const dest = getPushDestination(branch, ctx.toolState.pushDest);
+
+  if (normalizeUrl(dest.url) !== normalizeUrl(pushUrl)) {
     throw new Error(
       `Push blocked: destination does not match expected repository.\n` +
-        `Expected: ${params.pushUrl}\n` +
+        `Expected: ${pushUrl}\n` +
         `Actual: ${dest.url}\n` +
         `Git configuration may have been tampered with.`
     );
@@ -119,15 +116,7 @@ export function PushBranchTool(ctx: ToolContext) {
       }
 
       // validate push destination matches expected URL
-      const pushUrl = ctx.toolState.pushUrl;
-      if (!pushUrl) {
-        throw new Error("pushUrl not set - setupGit must run before push_branch");
-      }
-      const pushDest = validatePushDestination({
-        branch,
-        pushUrl,
-        storedDest: ctx.toolState.pushDest,
-      });
+      const pushDest = validatePushDestination(ctx, branch);
 
       // block pushes to default branch in restricted mode
       if (pushPermission === "restricted" && pushDest.remoteBranch === defaultBranch) {

mcp/selectMode.ts

@@ -65,15 +65,14 @@ const modeInstructionParent: Record<string, string> = {
   Fix: "Build",
 };
 
-type BuildGuidanceOpts = {
-  modeInstructions?: Record<string, string>;
-  overrideGuidance?: string;
-};
-
-function buildOrchestratorGuidance(mode: Mode, opts: BuildGuidanceOpts = {}): OrchestratorGuidance {
-  const hardcoded = opts.overrideGuidance ?? mode.prompt ?? "";
+function buildOrchestratorGuidance(
+  ctx: ToolContext,
+  mode: Mode,
+  overrideGuidance?: string
+): OrchestratorGuidance {
+  const hardcoded = overrideGuidance ?? mode.prompt ?? "";
   const lookupKey = modeInstructionParent[mode.name] ?? mode.name;
-  const userInstructions = opts.modeInstructions?.[lookupKey] ?? "";
+  const userInstructions = ctx.modeInstructions[lookupKey] ?? "";
   const guidance = [hardcoded, userInstructions].filter(Boolean).join("\n\n");
   return {
     modeName: mode.name,
@@ -172,8 +171,6 @@ export function SelectModeTool(ctx: ToolContext) {
 
       ctx.toolState.selectedMode = selectedMode.name;
 
-      const guidanceOpts: BuildGuidanceOpts = { modeInstructions: ctx.modeInstructions };
-
       if (selectedMode.name === "Plan") {
         const issueNumber = params.issue_number ?? ctx.payload.event.issue_number;
         if (issueNumber !== undefined) {
@@ -182,10 +179,7 @@ export function SelectModeTool(ctx: ToolContext) {
             ctx.toolState.existingPlanCommentId = existing.commentId;
             ctx.toolState.previousPlanBody = existing.body;
             return {
-              ...buildOrchestratorGuidance(selectedMode, {
-                ...guidanceOpts,
-                overrideGuidance: overrides.PlanEdit,
-              }),
+              ...buildOrchestratorGuidance(ctx, selectedMode, overrides.PlanEdit),
               previousPlanBody: existing.body,
             };
           }
@@ -199,10 +193,7 @@ export function SelectModeTool(ctx: ToolContext) {
           if (existing !== null) {
             ctx.toolState.existingSummaryCommentId = existing.commentId;
             return {
-              ...buildOrchestratorGuidance(selectedMode, {
-                ...guidanceOpts,
-                overrideGuidance: overrides.SummaryUpdate,
-              }),
+              ...buildOrchestratorGuidance(ctx, selectedMode, overrides.SummaryUpdate),
               existingSummaryCommentId: existing.commentId,
               previousSummaryBody: existing.body,
             };
@@ -210,7 +201,7 @@ export function SelectModeTool(ctx: ToolContext) {
         }
       }
 
-      return buildOrchestratorGuidance(selectedMode, guidanceOpts);
+      return buildOrchestratorGuidance(ctx, selectedMode);
     }),
   });
 }

post

@@ -37812,6 +37812,33 @@ ${PULLFROG_DIVIDER}
 <sup>${FROG_LOGO}&nbsp;&nbsp;\uFF5C ${allParts.join(" \uFF5C ")}</sup>`;
 }
 
+// mcp/comment.ts
+var LEAPING_INTO_ACTION_PREFIX = "Leaping into action";
+var Comment = type({
+  issueNumber: type.number.describe("the issue number to comment on"),
+  body: type.string.describe("the comment body content"),
+  type: type.enumerated("Plan", "Summary", "Comment").describe(
+    "Plan: record as the plan for this run. Summary: record as the PR summary comment (one per PR, updated in place). Comment: regular comment (default)."
+  ).optional()
+});
+var EditComment = type({
+  commentId: type.number.describe("the ID of the comment to edit"),
+  body: type.string.describe("the new comment body content")
+});
+var ReportProgress = type({
+  body: type.string.describe("the progress update content to share"),
+  "target_plan_comment?": type("boolean").describe(
+    "when true, update the existing plan comment (from select_mode lookup) instead of the progress comment; use when editing an existing plan"
+  )
+});
+var ReplyToReviewComment = type({
+  pull_number: type.number.describe("the pull request number"),
+  comment_id: type.number.describe("the ID of the review comment to reply to"),
+  body: type.string.describe(
+    "extremely brief reply (1 sentence max) explaining what was fixed, e.g. 'Fixed by renaming to X' or 'Added null check'"
+  )
+});
+
 // utils/github.ts
 var core2 = __toESM(require_core(), 1);
 
@@ -41526,33 +41553,6 @@ function createOctokit(token) {
   return octokit;
 }
 
-// mcp/comment.ts
-var LEAPING_INTO_ACTION_PREFIX = "Leaping into action";
-var Comment = type({
-  issueNumber: type.number.describe("the issue number to comment on"),
-  body: type.string.describe("the comment body content"),
-  type: type.enumerated("Plan", "Summary", "Comment").describe(
-    "Plan: record as the plan for this run. Summary: record as the PR summary comment (one per PR, updated in place). Comment: regular comment (default)."
-  ).optional()
-});
-var EditComment = type({
-  commentId: type.number.describe("the ID of the comment to edit"),
-  body: type.string.describe("the new comment body content")
-});
-var ReportProgress = type({
-  body: type.string.describe("the progress update content to share"),
-  "target_plan_comment?": type("boolean").describe(
-    "when true, update the existing plan comment (from select_mode lookup) instead of the progress comment; use when editing an existing plan"
-  )
-});
-var ReplyToReviewComment = type({
-  pull_number: type.number.describe("the pull request number"),
-  comment_id: type.number.describe("the ID of the review comment to reply to"),
-  body: type.string.describe(
-    "extremely brief reply (1 sentence max) explaining what was fixed, e.g. 'Fixed by renaming to X' or 'Added null check'"
-  )
-});
-
 // utils/payload.ts
 var core3 = __toESM(require_core(), 1);
 
@@ -41725,40 +41725,44 @@ function getJobToken() {
 
 // utils/postCleanup.ts
 var SHOULD_CHECK_REASON = true;
-function buildErrorCommentBody(params) {
-  let errorMessage = params.isCancellation ? `This run was cancelled \u{1F6D1}
+function buildErrorCommentBody(ctx, isCancellation) {
+  let errorMessage = isCancellation ? `This run was cancelled \u{1F6D1}
 
 The workflow was cancelled before completion.` : `This run croaked \u{1F635}
 
 The workflow encountered an error before any progress could be reported.`;
-  if (params.runId) {
+  if (ctx.runId) {
     errorMessage += " Please check the link below for details.";
   }
   const customParts = [];
-  if (!params.isCancellation && params.runId) {
+  if (!isCancellation && ctx.runId) {
     const apiUrl = getApiUrl();
     customParts.push(
-      `[Rerun failed job \u2794](${apiUrl}/trigger/${params.owner}/${params.repo}/${params.runId}?action=rerun)`
+      `[Rerun failed job \u2794](${apiUrl}/trigger/${ctx.repoContext.owner}/${ctx.repoContext.name}/${ctx.runId}?action=rerun)`
     );
   }
   const footer = buildPullfrogFooter({
     triggeredBy: true,
-    workflowRun: params.runId ? { owner: params.owner, repo: params.repo, runId: params.runId } : void 0,
+    workflowRun: ctx.runId ? {
+      owner: ctx.repoContext.owner,
+      repo: ctx.repoContext.name,
+      runId: ctx.runId
+    } : void 0,
     customParts
   });
   return `${errorMessage}${footer}`;
 }
-async function validateStuckProgressComment(params) {
-  if (!params.promptInput?.progressCommentId) {
+async function validateStuckProgressComment(ctx) {
+  if (!ctx.promptInput?.progressCommentId) {
     log.info("[post] no progressCommentId in prompt input, skipping cleanup");
     return null;
   }
-  const commentId = parseInt(params.promptInput.progressCommentId, 10);
+  const commentId = parseInt(ctx.promptInput.progressCommentId, 10);
   log.info(`[post] validating progressCommentId from prompt input: ${commentId}`);
   try {
-    const commentResult = await params.octokit.rest.issues.getComment({
-      owner: params.owner,
-      repo: params.repo,
+    const commentResult = await ctx.octokit.rest.issues.getComment({
+      owner: ctx.repoContext.owner,
+      repo: ctx.repoContext.name,
       comment_id: commentId
     });
     const body = commentResult.data.body ?? "";
@@ -41778,13 +41782,13 @@ async function validateStuckProgressComment(params) {
     return null;
   }
 }
-async function getIsCancelled(params) {
-  if (!params.runId) return false;
+async function getIsCancelled(ctx) {
+  if (!ctx.runId) return false;
   try {
-    const jobsResult = await params.octokit.rest.actions.listJobsForWorkflowRun({
-      owner: params.repoContext.owner,
-      repo: params.repoContext.name,
-      run_id: params.runId
+    const jobsResult = await ctx.octokit.rest.actions.listJobsForWorkflowRun({
+      owner: ctx.repoContext.owner,
+      repo: ctx.repoContext.name,
+      run_id: ctx.runId
     });
     const currentJobName = process.env.GITHUB_JOB;
     const currentJob = currentJobName ? jobsResult.data.jobs.find(
@@ -41824,24 +41828,18 @@ async function runPostCleanup() {
   const token = getJobToken();
   const repoContext = parseRepoContext();
   const octokit = createOctokit(token);
-  const commentId = await validateStuckProgressComment({
-    promptInput,
-    octokit,
-    owner: repoContext.owner,
-    repo: repoContext.name
-  });
+  const ctx = { repoContext, octokit, runId, promptInput };
+  const commentId = await validateStuckProgressComment(ctx);
   if (!commentId) return log.info("\xBB [post] no stuck progress comment to update, skipping cleanup");
   log.info(`\xBB [post] validated stuck comment: ${commentId}, updating with error message`);
   try {
-    const body = buildErrorCommentBody({
-      owner: repoContext.owner,
-      repo: repoContext.name,
-      runId,
-      isCancellation: SHOULD_CHECK_REASON ? await getIsCancelled({ octokit, repoContext, runId }) : false
-    });
-    await octokit.rest.issues.updateComment({
-      owner: repoContext.owner,
-      repo: repoContext.name,
+    const body = buildErrorCommentBody(
+      ctx,
+      SHOULD_CHECK_REASON ? await getIsCancelled(ctx) : false
+    );
+    await ctx.octokit.rest.issues.updateComment({
+      owner: ctx.repoContext.owner,
+      repo: ctx.repoContext.name,
       comment_id: commentId,
       body
     });

utils/instructions.ts

@@ -15,6 +15,14 @@ interface InstructionsContext {
   learnings: string | null;
 }
 
+interface PromptContext extends InstructionsContext {
+  t: (name: string) => string;
+  eventTitle: string;
+  eventMetadata: string;
+  runtime: string;
+  userQuoted: string;
+}
+
 function buildRuntimeContext(ctx: InstructionsContext): string {
   // extract payload fields excluding prompt/instructions/event (those are rendered separately)
   const {
@@ -136,24 +144,25 @@ In case of conflict between instructions, follow this precedence (highest to low
 // ---------------------------------------------------------------------------
 
 // the user's task: blockquoted user prompt, or event-level instructions for auto-triggers
-function buildTaskSection(ctx: { userQuoted: string; eventInstructions: string }): string {
+function buildTaskSection(ctx: PromptContext): string {
   if (ctx.userQuoted) {
     return `************* YOUR TASK *************
 
 ${ctx.userQuoted}`;
   }
 
-  if (ctx.eventInstructions) {
+  const eventInstructions = ctx.payload.eventInstructions ?? "";
+  if (eventInstructions) {
     return `************* YOUR TASK *************
 
-${ctx.eventInstructions}`;
+${eventInstructions}`;
   }
 
   return "";
 }
 
 // mode selection and execution steps
-function buildProcedure(ctx: { modes: Mode[]; t: (name: string) => string }): string {
+function buildProcedure(ctx: PromptContext): string {
   const t = ctx.t;
   return `************* PROCEDURE *************
 
@@ -180,11 +189,7 @@ Eagerly inspect the MCP tools available to you via the \`${pullfrogMcpName}\` MC
 }
 
 // event title + metadata (omitted when empty, e.g. workflow_dispatch)
-function buildEventContext(ctx: {
-  payload: ResolvedPayload;
-  eventTitle: string;
-  eventMetadata: string;
-}): string {
+function buildEventContext(ctx: PromptContext): string {
   const isPr = ctx.payload.event.is_pr === true;
   const relatedLabel = isPr ? "--- related PR ---" : "--- related issue ---";
 
@@ -200,12 +205,7 @@ ${content}`;
 }
 
 // persona, environment, priority, security, tools, workflow
-function buildSystemBody(ctx: {
-  shell: ResolvedPayload["shell"];
-  trigger: string;
-  t: (name: string) => string;
-  outputSchema?: Record<string, unknown> | undefined;
-}): string {
+function buildSystemBody(ctx: PromptContext): string {
   const t = ctx.t;
   return `************* SYSTEM *************
 
@@ -257,11 +257,11 @@ Rules:
 
 Use MCP tools from ${pullfrogMcpName} for all GitHub operations. Never use the \`gh\` CLI — it is not authenticated and will fail. The MCP tools handle authentication and enforce permissions.
 
-${getShellInstructions(ctx.shell, t)}
+${getShellInstructions(ctx.payload.shell, t)}
 
 ${getFileInstructions()}
 
-${getStandaloneModeInstructions(ctx.trigger, t, ctx.outputSchema)}
+${getStandaloneModeInstructions(ctx.payload.event.trigger, t, ctx.outputSchema)}
 
 ## Workflow
 
@@ -312,38 +312,20 @@ function buildToc(entries: TocEntry[]): string {
 ${entries.map((e) => `- ${e.label} — ${e.description}`).join("\n")}`;
 }
 
-// shared computation for all instruction builders
-interface CommonInputs {
-  eventTitle: string;
-  eventMetadata: string;
-  runtime: string;
-  user: string;
-  eventInstructions: string;
-  event: string;
-  userQuoted: string;
-}
-
-function buildCommonInputs(ctx: InstructionsContext): CommonInputs {
-  const eventTitle = buildEventTitle(ctx.payload.event);
-  const eventMetadata = buildEventMetadata(ctx.payload.event);
-  const runtime = buildRuntimeContext(ctx);
+function buildPromptContext(ctx: InstructionsContext): PromptContext {
   const user = ctx.payload.prompt;
-  const eventInstructions = ctx.payload.eventInstructions ?? "";
-  const event = [eventTitle, eventMetadata].filter(Boolean).join("\n\n---\n\n");
-  const userQuoted = user
-    ? user
-        .split("\n")
-        .map((line) => `> ${line}`)
-        .join("\n")
-    : "";
   return {
-    eventTitle,
-    eventMetadata,
-    runtime,
-    user,
-    eventInstructions,
-    event,
-    userQuoted,
+    ...ctx,
+    t: (toolName: string) => formatMcpToolRef(ctx.agentId, toolName),
+    eventTitle: buildEventTitle(ctx.payload.event),
+    eventMetadata: buildEventMetadata(ctx.payload.event),
+    runtime: buildRuntimeContext(ctx),
+    userQuoted: user
+      ? user
+          .split("\n")
+          .map((line) => `> ${line}`)
+          .join("\n")
+      : "",
   };
 }
 
@@ -387,28 +369,12 @@ function assembleFullPrompt(ctx: {
 }
 
 export function resolveInstructions(ctx: InstructionsContext): ResolvedInstructions {
-  const inputs = buildCommonInputs(ctx);
-  const t = (toolName: string) => formatMcpToolRef(ctx.agentId, toolName);
+  const pctx = buildPromptContext(ctx);
 
-  const task = buildTaskSection({
-    userQuoted: inputs.userQuoted,
-    eventInstructions: inputs.eventInstructions,
-  });
-
-  const procedure = buildProcedure({ modes: ctx.modes, t });
-
-  const eventContext = buildEventContext({
-    payload: ctx.payload,
-    eventTitle: inputs.eventTitle,
-    eventMetadata: inputs.eventMetadata,
-  });
-
-  const system = buildSystemBody({
-    shell: ctx.payload.shell,
-    trigger: ctx.payload.event.trigger,
-    t,
-    outputSchema: ctx.outputSchema,
-  });
+  const task = buildTaskSection(pctx);
+  const procedure = buildProcedure(pctx);
+  const eventContext = buildEventContext(pctx);
+  const system = buildSystemBody(pctx);
 
   // build TOC from present sections (PROCEDURE, SYSTEM, RUNTIME are always present)
   const tocEntries: TocEntry[] = [];
@@ -417,7 +383,7 @@ export function resolveInstructions(ctx: InstructionsContext): ResolvedInstructi
   if (eventContext)
     tocEntries.push({ label: "EVENT CONTEXT", description: "related PR/issue data" });
   tocEntries.push({ label: "SYSTEM", description: "persona, security, tools, workflow rules" });
-  if (ctx.learnings)
+  if (pctx.learnings)
     tocEntries.push({ label: "LEARNINGS", description: "repo-specific knowledge" });
   tocEntries.push({ label: "RUNTIME", description: "environment metadata" });
 
@@ -429,16 +395,18 @@ export function resolveInstructions(ctx: InstructionsContext): ResolvedInstructi
     procedure,
     eventContext,
     system,
-    learnings: ctx.learnings,
-    runtime: inputs.runtime,
+    learnings: pctx.learnings,
+    runtime: pctx.runtime,
   });
 
+  const event = [pctx.eventTitle, pctx.eventMetadata].filter(Boolean).join("\n\n---\n\n");
+
   return {
     full,
     system,
-    user: inputs.user,
-    eventInstructions: inputs.eventInstructions,
-    event: inputs.event,
-    runtime: inputs.runtime,
+    user: pctx.payload.prompt,
+    eventInstructions: pctx.payload.eventInstructions ?? "",
+    event,
+    runtime: pctx.runtime,
   };
 }

utils/postCleanup.ts

@@ -8,65 +8,61 @@ import { getJobToken } from "./token.ts";
 
 type JsonPromptInput = Extract<ResolvedPromptInput, object>; // not string
 
+interface PostCleanupContext {
+  repoContext: ReturnType<typeof parseRepoContext>;
+  octokit: ReturnType<typeof createOctokit>;
+  runId: number | undefined;
+  promptInput: JsonPromptInput | null;
+}
+
 // controls whether the script should check the reason for the workflow termination.
 // it can be either canceled or failed.
 // YAML file cannot supply it (not in ENV), so an extra request is required to check it.
 const SHOULD_CHECK_REASON = true;
 
-type BuildErrorCommentBodyParams = {
-  owner: string;
-  repo: string;
-  runId: number | undefined;
-  isCancellation: boolean;
-};
-
-function buildErrorCommentBody(params: BuildErrorCommentBodyParams): string {
-  let errorMessage = params.isCancellation
+function buildErrorCommentBody(ctx: PostCleanupContext, isCancellation: boolean): string {
+  let errorMessage = isCancellation
     ? `This run was cancelled 🛑\n\nThe workflow was cancelled before completion.`
     : `This run croaked 😵\n\nThe workflow encountered an error before any progress could be reported.`;
 
-  if (params.runId) {
+  if (ctx.runId) {
     errorMessage += " Please check the link below for details.";
   }
 
   const customParts: string[] = [];
-  if (!params.isCancellation && params.runId) {
+  if (!isCancellation && ctx.runId) {
     const apiUrl = getApiUrl();
     customParts.push(
-      `[Rerun failed job ➔](${apiUrl}/trigger/${params.owner}/${params.repo}/${params.runId}?action=rerun)`
+      `[Rerun failed job ➔](${apiUrl}/trigger/${ctx.repoContext.owner}/${ctx.repoContext.name}/${ctx.runId}?action=rerun)`
     );
   }
   const footer = buildPullfrogFooter({
     triggeredBy: true,
-    workflowRun: params.runId
-      ? { owner: params.owner, repo: params.repo, runId: params.runId }
+    workflowRun: ctx.runId
+      ? {
+          owner: ctx.repoContext.owner,
+          repo: ctx.repoContext.name,
+          runId: ctx.runId,
+        }
       : undefined,
     customParts,
   });
   return `${errorMessage}${footer}`;
 }
 
-type ValidateStuckCommentParams = {
-  promptInput: JsonPromptInput | null;
-  octokit: ReturnType<typeof createOctokit>;
-  owner: string;
-  repo: string;
-};
-async function validateStuckProgressComment(
-  params: ValidateStuckCommentParams
-): Promise<number | null> {
-  if (!params.promptInput?.progressCommentId) {
+async function validateStuckProgressComment(ctx: PostCleanupContext): Promise<number | null> {
+  if (!ctx.promptInput?.progressCommentId) {
     log.info("[post] no progressCommentId in prompt input, skipping cleanup");
     return null;
   }
 
-  const commentId = parseInt(params.promptInput.progressCommentId, 10);
+  const commentId = parseInt(ctx.promptInput.progressCommentId, 10);
   log.info(`[post] validating progressCommentId from prompt input: ${commentId}`);
 
   try {
-    const commentResult = await params.octokit.rest.issues.getComment({
-      owner: params.owner,
-      repo: params.repo,
+    const commentResult = await ctx.octokit.rest.issues.getComment({
+      owner: ctx.repoContext.owner,
+      repo: ctx.repoContext.name,
       comment_id: commentId,
     });
 
@@ -93,19 +89,13 @@ async function validateStuckProgressComment(
   }
 }
 
-type GetIsCancelledParams = {
-  repoContext: ReturnType<typeof parseRepoContext>;
-  octokit: ReturnType<typeof createOctokit>;
-  runId: number | undefined;
-};
-
-async function getIsCancelled(params: GetIsCancelledParams): Promise<boolean> {
-  if (!params.runId) return false; // can't check without a run ID — assume failure
+async function getIsCancelled(ctx: PostCleanupContext): Promise<boolean> {
+  if (!ctx.runId) return false; // can't check without a run ID — assume failure
   try {
-    const jobsResult = await params.octokit.rest.actions.listJobsForWorkflowRun({
-      owner: params.repoContext.owner,
-      repo: params.repoContext.name,
-      run_id: params.runId,
+    const jobsResult = await ctx.octokit.rest.actions.listJobsForWorkflowRun({
+      owner: ctx.repoContext.owner,
+      repo: ctx.repoContext.name,
+      run_id: ctx.runId,
     });
 
     // find current job by matching GITHUB_JOB env var.
@@ -166,30 +156,23 @@ export async function runPostCleanup(): Promise<void> {
   const repoContext = parseRepoContext();
   const octokit = createOctokit(token);
 
-  const commentId = await validateStuckProgressComment({
-    promptInput,
-    octokit,
-    owner: repoContext.owner,
-    repo: repoContext.name,
-  });
+  const ctx: PostCleanupContext = { repoContext, octokit, runId, promptInput };
+
+  const commentId = await validateStuckProgressComment(ctx);
 
   if (!commentId) return log.info("» [post] no stuck progress comment to update, skipping cleanup");
 
   log.info(`» [post] validated stuck comment: ${commentId}, updating with error message`);
 
   try {
-    const body = buildErrorCommentBody({
-      owner: repoContext.owner,
-      repo: repoContext.name,
-      runId,
-      isCancellation: SHOULD_CHECK_REASON
-        ? await getIsCancelled({ octokit, repoContext, runId })
-        : false,
-    });
+    const body = buildErrorCommentBody(
+      ctx,
+      SHOULD_CHECK_REASON ? await getIsCancelled(ctx) : false
+    );
 
-    await octokit.rest.issues.updateComment({
-      owner: repoContext.owner,
-      repo: repoContext.name,
+    await ctx.octokit.rest.issues.updateComment({
+      owner: ctx.repoContext.owner,
+      repo: ctx.repoContext.name,
       comment_id: commentId,
       body,
     });