pullfrog 0.0.202 → 0.0.204

package/dist/agents/postRun.d.ts

@@ -0,0 +1,66 @@
+import { type AgentId } from "../external.ts";
+import { type AgentResult, type AgentUsage, type PostRunIssues, type StopHookFailure } from "./shared.ts";
+/**
+ * run the user-configured stop hook.
+ *
+ * parallel to `executeLifecycleHook` (which soft-fails with a warning), but
+ * returns structured output so agent harnesses can feed the failure back into
+ * the session as a resume prompt.
+ *
+ * - non-zero exit → `StopHookFailure`, actionable: the output is fed to the
+ *   agent so it can fix the underlying issue.
+ * - timeout / spawn error → null, treated as passed: we can't usefully ask the
+ *   agent to fix an infrastructure problem, and retrying would risk infinite
+ *   loops.
+ */
+export declare function executeStopHook(script: string): Promise<StopHookFailure | null>;
+export declare function buildStopHookPrompt(failure: StopHookFailure): string;
+/**
+ * check the two post-run gates: did the stop hook pass and is the working
+ * tree clean? returns everything that still needs fixing so the caller can
+ * render a single combined resume prompt.
+ */
+export declare function collectPostRunIssues(params: {
+    stopScript: string | null | undefined;
+}): Promise<PostRunIssues>;
+export declare function buildPostRunPrompt(issues: PostRunIssues): string;
+/**
+ * prompt for a dedicated post-run reflection turn nudging the agent to call
+ * `update_learnings` if it discovered anything worth persisting.
+ *
+ * this exists because the learnings step baked into mode checklists is
+ * frequently ignored — the agent stays focused on the task and the meta-ask
+ * falls through. delivering it as its own resume turn, with nothing competing
+ * for attention, raises the fire rate substantially.
+ */
+export declare function buildLearningsReflectionPrompt(agentId: AgentId): string;
+/**
+ * shared post-run retry loop used by every agent harness.
+ *
+ * checks the post-run gates (stop hook + dirty tree), and if either is
+ * failing, invokes `resume` to let the agent fix and push in the same turn.
+ * bails at `MAX_POST_RUN_RETRIES` attempts. the `canResume` predicate is
+ * consulted before each retry — harnesses that can't re-enter the session
+ * (e.g. claude without a sessionId) return false here.
+ *
+ * an optional `reflectionPrompt` fires exactly once, after the gates first
+ * observe a clean state. it's a one-shot nudge (e.g. "update learnings if
+ * relevant"), not a gate, so it does not consume the gate-retry budget. if
+ * the reflection turn dirties the tree, the loop picks that up on the next
+ * iteration via the normal dirty-tree gate.
+ *
+ * stop hook must pass for the run to succeed; persistent hook failures are
+ * surfaced as `AgentResult.error`. dirty-tree-only failures preserve prior
+ * behavior: they're logged but don't fail the run.
+ */
+export declare function runPostRunRetryLoop<R extends AgentResult>(params: {
+    initialResult: R;
+    initialUsage: AgentUsage | undefined;
+    stopScript: string | null | undefined;
+    resume: (context: {
+        prompt: string;
+        previousResult: R;
+    }) => Promise<R>;
+    canResume?: ((result: R) => boolean) | undefined;
+    reflectionPrompt?: string | undefined;
+}): Promise<AgentResult>;

package/dist/agents/reviewer.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Definition of the `reviewfrog` named subagent — the constrained
+ * read-only worker dispatched by Build mode self-review and the in-Pullfrog
+ * /anneal multi-lens review.
+ *
+ * The contract: non-mutative + non-recursive.
+ *   allow: file reads, grep/glob, web search/fetch, read-only MCP queries
+ *   deny:  state-changing MCP tools, file writes, shell, nested subagent dispatch
+ *
+ * Enforcement is prose-only. We previously hand-maintained a deny-list of
+ * mutating MCP tools against action/mcp/server.ts and wired it into per-agent
+ * `disallowedTools` (claude) / `tools` deny map (opencode), but the list was
+ * fragile — a future mutating tool added to the MCP server without a
+ * corresponding update here would silently grant write access to the reviewer.
+ * Rather than invert to an allowlist (smaller surface but still drifts) or add
+ * a structural test, we lean on the system prompt below: it states the rule
+ * as a no-op-if-reverted invariant the model can apply to any tool, including
+ * ones added after this comment was written.
+ *
+ * Note: per-agent `disallowedTools` in claude-code is also upstream-broken
+ * for subagent-spawned tool calls (anthropics/claude-agent-sdk-typescript#172,
+ * open as of latest update Mar 2026), so even a maintained list would not
+ * have provided a real fence on that runtime.
+ */
+export declare const REVIEWER_AGENT_NAME = "reviewfrog";
+/**
+ * System prompt baked into the named reviewer subagent. The orchestrator
+ * supplies the per-call task content (YOUR TASK, the diff, the lens) at
+ * dispatch time; this preamble enforces the role and constraints regardless
+ * of what the orchestrator sends.
+ */
+export declare const REVIEWER_SYSTEM_PROMPT: string;

package/dist/agents/sessionLabeler.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Track per-session labels so log lines from parallel subagents can be
+ * differentiated. The orchestrator dispatches lens subagents (e.g. reviewfrog)
+ * via the Task tool; each subagent runs in its own opencode/claude Session
+ * with its own `sessionID` (or `session_id`) tag on the NDJSON event stream.
+ *
+ * Without per-session prefixing, parallel subagent tool_use / tool_result /
+ * text events appear as a single interleaved stream tagged with `[Pullfrog]`,
+ * making it impossible for a human reading the logs to attribute work to a
+ * specific lens.
+ *
+ * The labeler is deliberately runtime-agnostic — both opencode.ts and
+ * claude.ts feed it the same shape. The contract is FIFO: when the orchestrator
+ * dispatches N task tool_use blocks in a single assistant turn (the parallel
+ * fan-out the multi-lens prompt requires), the i-th new sessionID is assumed
+ * to belong to the i-th task dispatch. This is correct as long as parallel
+ * dispatches are emitted in source-order and the runtimes respect that order
+ * when assigning child sessions; we do not depend on it for correctness of
+ * the read-only contract — only for log readability.
+ */
+export interface TaskDispatchInput {
+    description?: string | undefined;
+    subagent_type?: string | undefined;
+    prompt?: string | undefined;
+}
+export declare const ORCHESTRATOR_LABEL = "orchestrator";
+/**
+ * Extract a human-readable label from a Task tool's input. Tries (in order):
+ *   1. explicit `lens: <name>` marker on a line in the prompt — preferred,
+ *      lets the orchestrator name the lens deterministically
+ *   2. the Task tool's `description` field — short, written by orchestrator
+ *      per call, usually enough
+ *   3. the `subagent_type` (e.g. `reviewfrog`) — falls back to the named
+ *      subagent identity when description is missing
+ *   4. generic "subagent" — last resort
+ */
+export declare function deriveLabelFromTaskInput(input: TaskDispatchInput): string;
+/**
+ * Stateful tracker mapping sessionIDs to human labels.
+ *
+ * Lifecycle:
+ *   - First call to `labelFor()` returns ORCHESTRATOR_LABEL and binds that
+ *     sessionID to it. Every subsequent event from that session gets the
+ *     same label.
+ *   - When the orchestrator emits a Task tool_use, the harness calls
+ *     `recordTaskDispatch()` to push the dispatch's derived label onto a
+ *     pending FIFO queue.
+ *   - The next previously-unseen sessionID consumes the head of the queue.
+ *   - If `labelFor()` is called for a new session with an empty queue
+ *     (e.g. a subagent emitted events before the parent's tool_use was
+ *     parsed, or the runtime spawned a session we didn't expect), the
+ *     labeler falls back to `subagent#N` so log lines remain attributable.
+ */
+export declare class SessionLabeler {
+    private readonly labels;
+    private readonly pendingLabels;
+    private fallbackCounter;
+    recordTaskDispatch(input: TaskDispatchInput): string;
+    /**
+     * Return a label for the given sessionID. Binds on first call.
+     * Pass undefined/empty for events that lack a session id — the caller
+     * gets ORCHESTRATOR_LABEL so the line is still attributable.
+     */
+    labelFor(sessionID: string | undefined | null): string;
+    /** number of distinct sessions seen so far (for diagnostics) */
+    size(): number;
+    /** all (sessionID, label) pairs, oldest first */
+    entries(): Array<[string, string]>;
+    /** how many pending labels are queued waiting to bind to a new session */
+    pendingDispatchCount(): number;
+}
+/**
+ * Format a log message with a session label prefix in magenta. Mirrors the
+ * style of utils/log.ts:prefixLines() so per-session prefixes look the same
+ * as the dormant withLogPrefix-based ones.
+ */
+export declare function formatWithLabel(label: string, message: string): string;

package/dist/agents/shared.d.ts

@@ -3,9 +3,22 @@ import type { ResolvedInstructions } from "../utils/instructions.ts";
 import type { ResolvedPayload } from "../utils/payload.ts";
 import type { TodoTracker } from "../utils/todoTracking.ts";
 export declare const MAX_STDERR_LINES = 20;
-export declare const MAX_COMMIT_RETRIES = 3;
+/**
+ * how many times the post-run loop may resume the agent to fix a dirty tree
+ * or a failing stop hook before giving up.
+ */
+export declare const MAX_POST_RUN_RETRIES = 3;
 export declare function getGitStatus(): string;
-export declare function buildCommitPrompt(_agentId: AgentId, status: string): string;
+export declare function buildCommitPrompt(status: string): string;
+export interface StopHookFailure {
+    exitCode: number;
+    output: string;
+}
+export interface PostRunIssues {
+    stopHook?: StopHookFailure;
+    dirtyTree?: string;
+}
+export declare function hasPostRunIssues(issues: PostRunIssues): boolean;
 /**
  * token/cost usage data from a single agent run.
  *
@@ -52,6 +65,12 @@ export interface AgentRunContext {
     tmpdir: string;
     instructions: ResolvedInstructions;
     todoTracker?: TodoTracker | undefined;
+    /**
+     * user-configured stop hook script. runs after the agent finishes each
+     * attempt; non-zero exit resumes the agent with the hook output as
+     * guidance. null when the repo has no stop hook configured.
+     */
+    stopScript?: string | null | undefined;
     /**
      * called synchronously when the agent subprocess is killed for inner
      * activity timeout. lets main.ts tear down shared resources (MCP HTTP
@@ -72,7 +91,7 @@ export declare function formatCostUsd(costUsd: number): string;
  * merge two AgentUsage snapshots into one running total.
  *
  * both agent harnesses invoke their runner multiple times per `run()` when the
- * post-run dirty-tree loop kicks in (MAX_COMMIT_RETRIES). each invocation
+ * post-run retry loop kicks in (MAX_POST_RUN_RETRIES). each invocation
  * produces its own AgentUsage; we sum them so downstream callers (usage
  * summary, WorkflowRun persistence) see the whole session — not just the
  * final retry's slice.