pullfrog 0.0.202 → 0.0.204

package/dist/mcp/comment.d.ts

@@ -39,12 +39,15 @@ export declare const ReportProgress: import("arktype/internal/variants/object.ts
 /**
  * Report progress to a GitHub comment.
  *
- * progressCommentId has three states:
+ * progressComment has three states:
  *   - undefined: no comment yet — will create one if an issue/PR target exists
- *   - number:    active comment — will update it in place
+ *   - object:    active comment — will update it in place via the right REST endpoint for its type
  *   - null:      deliberately deleted (e.g. after submitting a PR review) — skips silently
  *
  * The body is always tracked in lastProgressBody for the job summary regardless of comment state.
+ *
+ * The "existing plan comment" path always targets a top-level issue comment (plan comments are
+ * created by create_issue_comment with type:"Plan", never as review-thread replies).
  */
 export declare function reportProgress(ctx: ToolContext, params: {
     body: string;
@@ -66,7 +69,7 @@ export declare function ReportProgressTool(ctx: ToolContext): import("fastmcp").
  * Delete the progress comment if it exists.
  * Used by main.ts for stranded-comment cleanup (orphaned "Leaping into action" or
  * checklist left by the todo tracker when the agent didn't call report_progress).
- * Sets progressCommentId to null so subsequent report_progress calls are no-ops.
+ * Sets progressComment to null so subsequent report_progress calls are no-ops.
  */
 export declare function deleteProgressComment(ctx: ToolContext): Promise<boolean>;
 export declare const ReplyToReviewComment: import("arktype/internal/variants/object.ts").ObjectType<{

package/dist/mcp/git.d.ts

@@ -6,6 +6,8 @@ export declare const PushBranch: import("arktype/internal/variants/object.ts").O
     force: import("arktype/internal/attributes.ts").Default<boolean, false>;
     branchName?: string;
 }, {}>;
+export type PushErrorKind = "concurrent-push" | "transient" | "unknown";
+export declare function classifyPushError(msg: string): PushErrorKind;
 export declare function PushBranchTool(ctx: ToolContext): import("fastmcp").Tool<any, import("@standard-schema/spec").StandardSchemaV1<{
     branchName?: string;
     force?: boolean;

package/dist/mcp/review.d.ts

@@ -36,6 +36,41 @@ export type ReviewSkipDecision = {
     kind: "empty-downgraded-approve";
     reason: string;
 };
+/**
+ * decision returned by duplicateReviewDecision when a session has already
+ * submitted a review and the current call would be a duplicate.
+ */
+export type DuplicateReviewDecision = {
+    kind: "already-submitted";
+    reviewId: number;
+    reason: string;
+};
+/**
+ * decide whether a second create_pull_request_review call in the same session
+ * is a duplicate of an earlier submission.
+ *
+ * the agent is instructed to call create_pull_request_review exactly once per
+ * Review-mode session (see action/modes.ts), but in practice it sometimes
+ * submits twice — once with substantive feedback, then again with the
+ * canonical "Reviewed — no issues found." body when the prompt's branch
+ * logic re-classifies non-blocking observations. the second submission is
+ * always redundant: the first review is the record, and the duplicate just
+ * adds noise to the PR.
+ *
+ * legitimate follow-up reviews after new commits ARE allowed: the
+ * new-commits-mid-review path advances toolState.checkoutSha past the
+ * previously reviewed sha, and a subsequent checkout_pr advances it again.
+ * any call where checkoutSha has moved past the prior reviewedSha is a real
+ * follow-up and goes through. anything else — same sha, or no checkoutSha
+ * to compare against — is a duplicate.
+ */
+export declare function duplicateReviewDecision(params: {
+    existing: {
+        id: number;
+        reviewedSha: string | undefined;
+    } | undefined;
+    currentCheckoutSha: string | undefined;
+}): DuplicateReviewDecision | null;
 /**
  * decide whether to skip a review submission before any network call.
  *

package/dist/mcp/reviewComments.d.ts

@@ -97,6 +97,35 @@ interface GetReviewDataInput {
     reviewId: number;
     approvedBy?: string | undefined;
 }
+export interface FormatReviewDataInput {
+    review: ReviewResponse;
+    threads: ReviewThread[];
+    prFiles: ReviewPrFile[];
+    pullNumber: number;
+    reviewId: number;
+}
+export type ReviewResponse = {
+    body: string | null | undefined;
+    user: {
+        login: string;
+    } | null | undefined;
+};
+export type ReviewPrFile = {
+    filename: string;
+    patch?: string | undefined;
+};
+export declare function formatReviewData(input: FormatReviewDataInput): {
+    threadBlocks: Array<{
+        path: string;
+        lineRange: string;
+        content: string[];
+    }>;
+    reviewer: string;
+    formatted: {
+        toc: string;
+        content: string;
+    };
+} | undefined;
 export declare function getReviewData(input: GetReviewDataInput): Promise<{
     threadBlocks: Array<{
         path: string;

package/dist/mcp/server.d.ts

@@ -6,6 +6,8 @@ import type { PrepResult } from "../prep/index.ts";
 import type { DiffCoverageState } from "../utils/diffCoverage.ts";
 import type { OctokitWithPlugins } from "../utils/github.ts";
 import type { ResolvedPayload } from "../utils/payload.ts";
+import { type ProgressComment, type ProgressCommentType } from "../utils/progressComment.ts";
+import type { AccountPlan } from "../utils/runContext.ts";
 import type { RunContextData } from "../utils/runContextData.ts";
 import type { TodoTracker } from "../utils/todoTracking.ts";
 import type { CommentableLines } from "./review.ts";
@@ -48,7 +50,7 @@ export interface ToolState {
         promise: Promise<PrepResult[]> | undefined;
         results: PrepResult[] | undefined;
     };
-    progressCommentId: number | null | undefined;
+    progressComment: ProgressComment | null | undefined;
     hadProgressComment: boolean;
     lastProgressBody?: string;
     wasUpdated?: boolean;
@@ -63,7 +65,10 @@ export interface ToolState {
     diffCoverage?: DiffCoverageState | undefined;
 }
 interface InitToolStateParams {
-    progressCommentId: string | undefined;
+    progressComment: {
+        id: string;
+        type: ProgressCommentType;
+    } | undefined;
 }
 export declare function initToolState(params: InitToolStateParams): ToolState;
 export interface ToolContext {
@@ -84,6 +89,8 @@ export interface ToolContext {
     jobId: string | undefined;
     mcpServerUrl: string;
     tmpdir: string;
+    oss: boolean;
+    plan: AccountPlan;
     resolvedModel: string | undefined;
 }
 type JsonSchema = Record<string, unknown>;

package/dist/models.d.ts

@@ -60,10 +60,27 @@ export declare function getModelEnvVars(slug: string): string[];
 export declare const modelAliases: ModelAlias[];
 /** resolve a model slug to its concrete models.dev specifier (e.g. "anthropic/claude-opus-4-6") */
 export declare function resolveModelSlug(slug: string): string | undefined;
+/**
+ * walk the fallback chain to the terminal (non-deprecated) alias.
+ * returns undefined if the chain is broken, exhausted, or cyclic.
+ *
+ * use this in UI display sites (dropdown trigger labels, PR-comment footers,
+ * etc.) so a deprecated stored slug renders as the model the user actually
+ * runs against — not the historical name. selectable lists should still hide
+ * deprecated aliases by filtering on `!a.fallback`.
+ */
+export declare function resolveDisplayAlias(slug: string): ModelAlias | undefined;
 /**
  * resolve a model slug to the CLI-ready model string, following the fallback
  * chain when a model is deprecated. returns the first non-deprecated resolve
  * target, or undefined if the chain is exhausted or broken.
  */
 export declare function resolveCliModel(slug: string): string | undefined;
+/**
+ * resolve a model slug to the OpenRouter-ready model string, following the
+ * fallback chain when a model is deprecated. returns undefined if the chain
+ * is exhausted/broken or the terminal alias has no openrouter equivalent
+ * (e.g. free opencode models).
+ */
+export declare function resolveOpenRouterModel(slug: string): string | undefined;
 export {};

package/dist/skills/git-archaeology/SKILL.md

@@ -0,0 +1,188 @@
+---
+name: git-archaeology
+description: Investigate how code reached its current state — when a line, function, import, or whole file was changed or deleted, who removed it, and what it looked like before. Use when `git blame` came up empty, when content has been refactored away, or when you need the full evolution of a function across commits.
+---
+
+# Git history archaeology
+
+`git blame` only sees what's still in the working tree. For anything that was
+deleted, moved, or refactored away, you need the commands below. Most agents
+under-use them and end up scrolling through `git log -p` instead.
+
+## Output discipline (read first)
+
+`git log -p` on a long-lived file can dump tens of thousands of lines and blow
+the context window. Always:
+
+1. **Start narrow.** Use `--oneline` or `--stat` to get a list of candidate
+   commits.
+2. **Drill in.** Use `git show <sha> -- <path>` for the diff of one specific
+   commit.
+3. **Scope the search.** Add `--since="3 months ago"`, `-n 20`, or a path
+   restriction (`-- <path>`) so output stays manageable.
+4. **Avoid `git log -p` without a path filter** on any non-trivial repo.
+
+## Decision tree (by agent intent)
+
+### "When did this exact line, string, or import disappear?"
+
+```bash
+git log -S'<exact-string>' --oneline -- <file>
+```
+
+The pickaxe. Returns commits that **changed the count** of that string in the
+file. The most recent hit is typically the removal commit. Add `-p` only after
+you've narrowed to a few candidates.
+
+Notes:
+- `-S` is exact-string by default. Add `--pickaxe-regex` to make it a regex.
+- The argument is "cuddled" with `-S` (`-S'foo bar'`), no space.
+- `-S` will not detect pure in-file moves (count unchanged). Use `-G` for that.
+- `--pickaxe-all` shows the entire changeset of matching commits, useful when
+  a commit changes both a definition and its call sites in other files.
+
+### "When did the diff stop matching this regex?"
+
+```bash
+git log -G'<regex>' --oneline -- <file>
+```
+
+Like `-S` but matches any added or removed hunk line against the regex. Use
+`-G` when:
+- You don't know the exact string but know a pattern.
+- You want to catch in-file moves (`-S` won't).
+- You want to find any diff that touched a pattern, even if the count was
+  preserved (e.g., a refactor that changed call sites without removing the
+  function).
+
+### "How did this function evolve over time?"
+
+```bash
+git log -L :<function-name>:<file>
+```
+
+Every commit that touched the function, with diffs scoped to just the function
+body. Works for languages git understands (most mainstream ones).
+
+### "How did lines N–M evolve?"
+
+```bash
+git log -L <N>,<M>:<file>
+```
+
+### "What's the full history of this file, including across renames?"
+
+```bash
+git log --follow --oneline -- <file>      # overview
+git log --follow -p -- <file>             # with diffs (use sparingly)
+```
+
+`--follow` only works for a single file, not directories.
+
+### "Where was a now-deleted line last present?"
+
+Two-step pattern when you have an exact deleted string:
+
+```bash
+# 1. find a historical commit that contained the string
+git log -S'<deleted-string>' --oneline --all -- <file>
+
+# 2. reverse-blame from that commit to find the last commit it survived in
+git blame --reverse <old-sha>..HEAD -- <file>
+```
+
+The reverse blame tells you, for each line, the last commit it survived in
+before being modified or deleted. Pinpoints the exact deletion commit.
+
+### "This file no longer exists — when was it deleted, and what was in it?"
+
+```bash
+# find all commits that touched the path, even on other branches
+git log --all --full-history --oneline -- <deleted-path>
+
+# the most recent of those is usually the deletion. confirm:
+git show <sha> --stat
+
+# view the file's contents at any commit where it existed
+git show <sha>^:<deleted-path>
+```
+
+If you don't know the path, find it from filename alone:
+
+```bash
+# list all delete events with paths
+git log --all --diff-filter=D --summary | grep -i '<filename>'
+
+# or glob across all branches
+git log --all --oneline -- '**/<filename>.*'
+```
+
+### "Who deleted it, in one shot?"
+
+```bash
+git rev-list -n 1 HEAD -- <deleted-path>     # the deletion commit
+git show $(git rev-list -n 1 HEAD -- <deleted-path>) -- <deleted-path>
+```
+
+### "Restore a deleted file (locally, no commit)"
+
+```bash
+git restore --source=<deletion-sha>^ -- <deleted-path>
+# or, on older git:
+git checkout <deletion-sha>^ -- <deleted-path>
+```
+
+The `^` is critical — at the deletion commit the file is already gone, so we
+read from its parent.
+
+### "Search commit messages, not content"
+
+```bash
+git log --all --grep='<text>' --oneline
+git log --all --grep='<text>' -i --oneline    # case-insensitive
+```
+
+Orthogonal to `-S`/`-G`, which only see the diff.
+
+## Standard workflow for "why does this code look like this"
+
+1. `git log --follow --oneline -- <file>` — overview of commits touching it.
+2. If a recent commit looks suspicious: `git show <sha> -- <file>`.
+3. If you expected to find something and it's missing:
+   `git log -S'<expected-string>' --oneline -- <file>`.
+4. For a specific function's full lifecycle:
+   `git log -L :<fn>:<file>`.
+5. For the deletion point of a known string: pickaxe to find an old commit
+   that contained it, then `git blame --reverse <old-sha>..HEAD -- <file>`.
+
+## Useful flags reference
+
+| Flag | Effect |
+|------|--------|
+| `--all` | Search all refs, not just the current branch. Use when investigating something that may have lived only on a feature branch. |
+| `--full-history` | Keeps commits that history-simplification would otherwise drop. Needed for accurate history across merges. |
+| `--follow` | Track a single file across renames. Single-file only. |
+| `-M` / `-C` | Detect renames (`-M`) and copies (`-C`) when reading diffs. |
+| `--diff-filter=D` | Restrict to commits that **deleted** something. `A`=added, `M`=modified, `R`=renamed. |
+| `--source` | When combined with `--all`, annotate each commit with the ref it was reached from. |
+| `--pickaxe-all` | With `-S`/`-G`, show all files in the matching commit, not just the matching file. |
+| `--pickaxe-regex` | Treat the `-S` argument as a regex. |
+| `--since` / `--until` | Time-bound the search. Cheap perf win on big repos. |
+| `-n <count>` | Cap result count. |
+| `--stat` | Per-commit file stats instead of full patches. Good first pass. |
+
+## Notes and pitfalls
+
+- Always include `--` before paths to disambiguate from refs (e.g.
+  `git log -S'foo' -- src/auth.ts`).
+- `-S` triggers on **count change**. A pure refactor that moves a line within
+  the same file will not match. Use `-G` for those.
+- `-G` runs diff twice and greps; it's slower than `-S`. Scope with paths and
+  `--since` on big repos.
+- Without `--all`, `git log -- <path>` shows nothing if the path never existed
+  on the current branch. When in doubt, add `--all`.
+- `git log --full-history -- <path>` alone has had bugs in some git versions
+  for deleted files; pair with `--all` for reliability.
+- For files that were renamed, `git log -- <new-path>` only shows post-rename
+  history. Use `--follow` (one file) or `git log --all -- <old-path>` when
+  hunting across rename events.

package/dist/utils/payload.d.ts

@@ -9,7 +9,10 @@ export declare const JsonPayload: import("arktype/internal/variants/object.ts").
     eventInstructions?: string;
     event?: object;
     timeout?: string | undefined;
-    progressCommentId?: string | undefined;
+    progressComment?: {
+        id: string;
+        type: "issue" | "review";
+    } | undefined;
 }, {}>;
 export declare const Inputs: import("arktype/internal/variants/object.ts").ObjectType<{
     prompt: string;
@@ -33,7 +36,10 @@ export declare function resolvePayload(resolvedPromptInput: ResolvedPromptInput,
     event: PayloadEvent;
     timeout: string | undefined;
     cwd: string | undefined;
-    progressCommentId: string | undefined;
+    progressComment: {
+        id: string;
+        type: "issue" | "review";
+    } | undefined;
     push: import("../external.ts").PushPermission;
     shell: import("../external.ts").ShellPermission;
     proxyModel: string | undefined;

package/dist/utils/progressComment.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Single source of truth for reading, updating, deleting, and creating "progress comments" —
+ * the GitHub comments Pullfrog uses to surface a run's status.
+ *
+ * A progress comment can be one of two distinct GitHub entities with non-overlapping IDs and
+ * distinct REST endpoints:
+ *   - "issue":  a top-level issue/PR timeline comment (octokit.rest.issues.*Comment)
+ *   - "review": an inline PR review-thread comment   (octokit.rest.pulls.*ReviewComment)
+ *
+ * Callers carry a `ProgressComment` (id + type) value end-to-end so the right endpoint is always
+ * picked. Adding a third comment type later means one new branch in this file, not six.
+ */
+export type ProgressCommentType = "issue" | "review";
+export type ProgressComment = {
+    id: number;
+    type: ProgressCommentType;
+};
+/**
+ * Parse the on-the-wire `{ id: string; type }` shape (the form carried in `JsonPayload`)
+ * into the in-memory `ProgressComment` shape. Returns undefined when the id isn't a
+ * positive integer so callers can short-circuit cleanly. Callers handle logging.
+ */
+export declare function parseProgressComment(raw: {
+    id: string;
+    type: ProgressCommentType;
+} | null | undefined): ProgressComment | undefined;
+interface CommentResponse {
+    data: {
+        id: number;
+        body?: string | null | undefined;
+        html_url: string;
+        node_id?: string;
+    };
+}
+export interface ProgressCommentOctokit {
+    rest: {
+        issues: {
+            createComment: (params: {
+                owner: string;
+                repo: string;
+                issue_number: number;
+                body: string;
+            }) => Promise<CommentResponse>;
+            getComment: (params: {
+                owner: string;
+                repo: string;
+                comment_id: number;
+            }) => Promise<CommentResponse>;
+            updateComment: (params: {
+                owner: string;
+                repo: string;
+                comment_id: number;
+                body: string;
+            }) => Promise<CommentResponse>;
+            deleteComment: (params: {
+                owner: string;
+                repo: string;
+                comment_id: number;
+            }) => Promise<unknown>;
+        };
+        pulls: {
+            createReplyForReviewComment: (params: {
+                owner: string;
+                repo: string;
+                pull_number: number;
+                comment_id: number;
+                body: string;
+            }) => Promise<CommentResponse>;
+            getReviewComment: (params: {
+                owner: string;
+                repo: string;
+                comment_id: number;
+            }) => Promise<CommentResponse>;
+            updateReviewComment: (params: {
+                owner: string;
+                repo: string;
+                comment_id: number;
+                body: string;
+            }) => Promise<CommentResponse>;
+            deleteReviewComment: (params: {
+                owner: string;
+                repo: string;
+                comment_id: number;
+            }) => Promise<unknown>;
+        };
+    };
+}
+interface ApiCtx {
+    octokit: ProgressCommentOctokit;
+    owner: string;
+    repo: string;
+}
+/**
+ * Fetch a progress comment via the appropriate REST endpoint for its type.
+ * Returns the common subset of fields callers actually use.
+ */
+export declare function getProgressComment(ctx: ApiCtx, comment: ProgressComment): Promise<{
+    id: number;
+    body: string | undefined;
+    html_url: string;
+}>;
+/**
+ * Update a progress comment in place via the appropriate REST endpoint.
+ * Returns the common subset of fields callers actually use.
+ */
+export declare function updateProgressComment(ctx: ApiCtx, comment: ProgressComment, body: string): Promise<{
+    id: number;
+    body: string | undefined;
+    html_url: string;
+    node_id: string | undefined;
+}>;
+/**
+ * Delete a progress comment via the appropriate REST endpoint.
+ * Lower-level than `deleteProgressComment` in mcp/comment.ts — that one also clears
+ * tool state. Callers that don't have a ToolContext (post cleanup, error handlers)
+ * should use this directly; the higher-level wrapper delegates here.
+ */
+export declare function deleteProgressCommentApi(ctx: ApiCtx, comment: ProgressComment): Promise<void>;
+/**
+ * Discriminated target for `createLeapingProgressComment`. The two variants map to the two
+ * distinct GitHub create endpoints; review-reply additionally needs the parent comment ID.
+ */
+export type CreateProgressCommentTarget = {
+    kind: "issue";
+    issueNumber: number;
+} | {
+    kind: "reviewReply";
+    pullNumber: number;
+    replyToCommentId: number;
+};
+export interface CreatedProgressComment {
+    comment: ProgressComment;
+    body: string | undefined;
+    html_url: string;
+}
+/**
+ * Create the initial "Leaping into action..." progress comment.
+ *
+ * Reliability: when `kind: "reviewReply"` fails (e.g. the parent comment was deleted or the
+ * thread is otherwise unreachable), falls back to a top-level issue comment on the same PR
+ * rather than leaving the run with no progress surface. The fallback is logged.
+ *
+ * (PR # === issue # in GitHub's number space, so `pullNumber` doubles as the fallback target.)
+ */
+export declare function createLeapingProgressComment(ctx: ApiCtx, target: CreateProgressCommentTarget, body: string): Promise<CreatedProgressComment>;
+export {};

package/dist/utils/runContext.d.ts

@@ -12,6 +12,7 @@ export interface RepoSettings {
     setupScript: string | null;
     postCheckoutScript: string | null;
     prepushScript: string | null;
+    stopScript: string | null;
     push: PushPermission;
     shell: ShellPermission;
     prApproveEnabled: boolean;
@@ -19,10 +20,26 @@ export interface RepoSettings {
     learnings: string | null;
     envAllowlist: string | null;
 }
+/**
+ * Account-level billing plan. Orthogonal to repo-level OSS status. Mirrors
+ * the server's `AccountPlan` in `utils/billing.ts`. `"none"` = free tier,
+ * `"payg"` = card on file / pay-as-you-go.
+ */
+export type AccountPlan = "none" | "payg";
+/**
+ * "Is Pullfrog absorbing marginal infra cost for this repo?" — composite
+ * predicate over the two orthogonal dimensions (repo-level OSS, account-level
+ * plan). Mirrors `isInfraCovered` in the server's `utils/billing.ts`.
+ */
+export declare function isInfraCovered(params: {
+    isOss: boolean;
+    plan: AccountPlan;
+}): boolean;
 export interface RunContext {
     settings: RepoSettings;
     apiToken: string;
     oss: boolean;
+    plan: AccountPlan;
     proxyModel?: string | undefined;
     dbSecrets?: Record<string, string> | undefined;
 }

package/dist/utils/runContextData.d.ts

@@ -1,6 +1,6 @@
 import type { Octokit } from "@octokit/rest";
 import { type OctokitWithPlugins } from "./github.ts";
-import { type RepoSettings } from "./runContext.ts";
+import { type AccountPlan, type RepoSettings } from "./runContext.ts";
 export interface RunContextData {
     repo: {
         owner: string;
@@ -10,6 +10,7 @@ export interface RunContextData {
     repoSettings: RepoSettings;
     apiToken: string;
     oss: boolean;
+    plan: AccountPlan;
     proxyModel?: string | undefined;
     dbSecrets?: Record<string, string> | undefined;
 }

package/dist/utils/skills.d.ts

@@ -1,3 +1,13 @@
+/**
+ * write all bundled skills into the fake HOME so OpenCode / Claude Code discover
+ * them via their auto-scan directories.
+ *
+ * called once per agent run from each agent's `run()`. cheap (small file
+ * writes), no network, idempotent.
+ */
+export declare function installBundledSkills(params: {
+    home: string;
+}): void;
 /**
  * install a skill globally via the `skills` CLI.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pullfrog",
-  "version": "0.0.202",
+  "version": "0.0.204",
   "type": "module",
   "bin": {
     "pullfrog": "dist/cli.mjs",