pullfrog 0.1.2 → 0.1.3

package/dist/agents/claude.d.ts

@@ -1 +1,20 @@
+import type { TodoTracker } from "../utils/todoTracking.ts";
+import { type AgentResult } from "./shared.ts";
+type RunParams = {
+    label: string;
+    args: string[];
+    cwd: string;
+    env: Record<string, string | undefined>;
+    todoTracker?: TodoTracker | undefined;
+    onActivityTimeout?: (() => void) | undefined;
+    onToolUse?: ((event: {
+        toolName: string;
+        input: unknown;
+    }) => void) | undefined;
+};
+type ClaudeRunResult = AgentResult & {
+    sessionId?: string | undefined;
+};
+export declare function runClaude(params: RunParams): Promise<ClaudeRunResult>;
 export declare const claude: import("./shared.ts").Agent;
+export {};

package/dist/agents/postRun.d.ts

@@ -1,4 +1,15 @@
-import { type AgentResult, type AgentUsage, type PostRunIssues, type StopHookFailure } from "./shared.ts";
+import type { ToolState } from "../toolState.ts";
+import { type AgentResult, type AgentRunContext, type AgentUsage, type PostRunIssues, type StopHookFailure } from "./shared.ts";
+/**
+ * derive "agent picked a review mode but never produced visible output" from
+ * the literal facts on `toolState`. returns the selected mode when the gate
+ * should fire, `null` otherwise — pure read, no side effects, safe to invoke
+ * after every agent attempt.
+ *
+ * the gate is anchored to `hadProgressComment` so silent runs (non-issue
+ * events, dispatcher skipped seeding) don't fire a nudge there's no UI for.
+ */
+export declare function getUnsubmittedReview(toolState: ToolState): "Review" | "IncrementalReview" | null;
 /**
  * run the user-configured stop hook.
  *
@@ -15,23 +26,21 @@ import { type AgentResult, type AgentUsage, type PostRunIssues, type StopHookFai
 export declare function executeStopHook(script: string): Promise<StopHookFailure | null>;
 export declare function buildStopHookPrompt(failure: StopHookFailure): string;
 export declare function buildSummaryStalePrompt(filePath: string): string;
+export declare function buildUnsubmittedReviewPrompt(mode: "Review" | "IncrementalReview"): string;
 /**
  * check the post-run gates: did the stop hook pass, is the working tree
  * clean, and (when applicable) did the agent touch the rolling PR summary
- * snapshot? returns everything that still needs nudging so the caller can
- * render a single combined resume prompt.
+ * snapshot or produce review output? returns everything that still needs
+ * nudging so the caller can render a single combined resume prompt.
  *
- * the summary-stale check is skipped when `summaryFilePath` / `summarySeed`
- * are not provided; this is the common case (non-PR runs, runs where the
- * dispatcher didn't request snapshot generation, runs where the seed step
- * failed). loop callers also pass these as undefined after the agent has
- * already been nudged once, to avoid burning the retry budget on a soft
- * non-blocking gate.
+ * reads run state directly off `ctx.toolState` so each invocation sees the
+ * latest mutations from MCP tool calls. `skipSummaryStale` lets the loop
+ * suppress the summary-stale check after the one-shot nudge has been
+ * delivered (re-firing it would burn the retry budget on a soft gate the
+ * agent has already decided not to act on).
  */
-export declare function collectPostRunIssues(params: {
-    stopScript: string | null | undefined;
-    summaryFilePath?: string | undefined;
-    summarySeed?: string | undefined;
+export declare function collectPostRunIssues(ctx: AgentRunContext, options?: {
+    skipSummaryStale?: boolean;
 }): Promise<PostRunIssues>;
 export declare function buildPostRunPrompt(issues: PostRunIssues): string;
 /**
@@ -69,17 +78,9 @@ export declare function buildLearningsReflectionPrompt(filePath: string): string
  * behavior: they're logged but don't fail the run.
  */
 export declare function runPostRunRetryLoop<R extends AgentResult>(params: {
+    ctx: AgentRunContext;
     initialResult: R;
     initialUsage: AgentUsage | undefined;
-    stopScript: string | null | undefined;
-    /** absolute path to the seeded PR summary file. when set together with
-     * `summarySeed`, the loop checks after each agent attempt whether the
-     * file has been edited; if not, it nudges the agent ONCE via a resume
-     * turn (subsequent iterations skip the check so we don't keep burning
-     * retries on a soft gate when the agent has decided no edit is warranted). */
-    summaryFilePath?: string | undefined;
-    /** exact bytes of the seeded summary file used for the unchanged-check. */
-    summarySeed?: string | undefined;
     resume: (context: {
         prompt: string;
         previousResult: R;

package/dist/agents/shared.d.ts

@@ -1,4 +1,5 @@
 import type { AgentId } from "../external.ts";
+import type { ToolState } from "../toolState.ts";
 import type { ResolvedInstructions } from "../utils/instructions.ts";
 import type { ResolvedPayload } from "../utils/payload.ts";
 import type { TodoTracker } from "../utils/todoTracking.ts";
@@ -25,6 +26,17 @@ export interface PostRunIssues {
      * seed, i.e. the agent never touched it. soft gate — nudges once via a
      * resume turn but never fails the run, parallel to dirtyTree semantics. */
     summaryStale?: SummaryStale;
+    /**
+     * populated when the agent selected a review mode but the post-run check
+     * over toolState shows neither a `create_pull_request_review` submission
+     * nor a final `report_progress` write happened. derived inline from
+     * `toolState.selectedMode` + `toolState.review` + `toolState.finalSummaryWritten`
+     * via {@link getUnsubmittedReview} — no parallel toolState flag is stored.
+     * carries the mode name so the resume prompt can reference it. handled like
+     * `stopHook`: nudge via resume, hard-fail if still unsatisfied after
+     * `MAX_POST_RUN_RETRIES`.
+     */
+    unsubmittedReview?: "Review" | "IncrementalReview";
 }
 export declare function hasPostRunIssues(issues: PostRunIssues): boolean;
 /**
@@ -64,7 +76,14 @@ export interface AgentResult {
     usage?: AgentUsage | undefined;
 }
 /**
- * Minimal context passed to agent.run()
+ * Context passed to agent.run() and threaded through the post-run loop.
+ *
+ * design rule: this is the single object that flows through the harness and
+ * downstream utilities by reference. derived predicates (e.g.
+ * `getUnsubmittedReview`), tmpfile paths, and seed bytes live on
+ * `toolState` — read them at the call site, do not duplicate them onto this
+ * interface. utilities that need run state should accept `ctx` whole, not
+ * destructure a narrow subset.
  */
 export interface AgentRunContext {
     payload: ResolvedPayload;
@@ -80,26 +99,13 @@ export interface AgentRunContext {
      */
     stopScript?: string | null | undefined;
     /**
-     * absolute path to the rolling PR summary tmpfile, when one was seeded
-     * for this run (Review / IncrementalReview / pr-summary Task). enables
-     * a post-run sanity nudge that prompts the agent if the file is still
-     * byte-identical to its seed.
-     */
-    summaryFilePath?: string | undefined;
-    /**
-     * exact bytes of the seeded summary file. compared against the current
-     * file content after each agent attempt to detect "agent forgot to edit
-     * the summary" — particularly common with smaller models that lose
-     * track of multi-step instructions.
-     */
-    summarySeed?: string | undefined;
-    /**
-     * absolute path to the rolling repo-level learnings tmpfile. seeded for
-     * every run from `Repo.learnings`. used by the post-run reflection turn
-     * so the prompt can point the agent at a concrete path to edit; the
-     * file's content is read back and persisted by main.ts after the run.
+     * mutable per-run state shared with the MCP server (by reference). post-run
+     * gates read fresh values from it after each agent attempt — `summaryFilePath`,
+     * `summarySeed`, `selectedMode`, `review`, `finalSummaryWritten`,
+     * `hadProgressComment` are all consulted by `collectPostRunIssues`. see
+     * `action/toolState.ts` for the literal-state design rule.
      */
-    learningsFilePath?: string | undefined;
+    toolState: ToolState;
     /**
      * called synchronously when the agent subprocess is killed for inner
      * activity timeout. lets main.ts tear down shared resources (MCP HTTP