pullfrog 0.1.6 → 0.1.8

package/dist/utils/apiKeys.d.ts

@@ -8,3 +8,21 @@ export declare function validateAgentApiKey(params: {
     owner: string;
     name: string;
 }): void;
+/**
+ * Detect agent-runtime auth failures that should be reformatted as an actionable
+ * key-fix CTA before being shown to the user. Covers the two shapes we see:
+ *   - missing key (validateAgentApiKey throw): contains MISSING_KEY_MARKER
+ *   - revoked / invalid key (Claude CLI 401 surfaced via api_error_status):
+ *     "Invalid API key · Fix external API key" + similar provider variants
+ */
+export declare function isApiKeyAuthError(text: string): boolean;
+/**
+ * Friendly Markdown summary for both the missing-key and invalid-key cases.
+ * Used in the catch / result-failure paths in `main.ts` to overwrite the raw
+ * agent error before it's posted to the PR progress comment.
+ */
+export declare function formatApiKeyErrorSummary(params: {
+    owner: string;
+    name: string;
+    raw: string;
+}): string;

package/dist/utils/gitAuth.d.ts

@@ -44,4 +44,31 @@ export declare function setGitAuthServer(server: GitAuthServer): void;
  * await $git("push", ["-u", "origin", "feature"], { token });
  */
 export declare function $git(subcommand: SafeGitSubcommand, args: string[], options: GitAuthOptions): Promise<GitResult>;
+/**
+ * shallow-clone unreachable: when an existing local depth is too shallow for
+ * git to traverse to the requested ref's ancestry, the remote walk fails with
+ * one of these wordings (git emits the full OID via oid_to_hex, so the bound
+ * is 40 for SHA-1 or 64 for SHA-256). detecting both lets a single deepen
+ * retry recover before the error reaches the agent — see issue #564 for the
+ * original `git_fetch` precedent and #656 for the `checkout_pr` follow-up.
+ */
+export declare const SHALLOW_UNREACHABLE_PATTERNS: RegExp[];
+/**
+ * large enough to clear the merge base on most real-world PRs without
+ * downloading the full history; matches the fallback used by
+ * `checkoutPrBranch` when the GitHub compare API is unavailable.
+ */
+export declare const DEEPEN_RETRY_DEPTH = 1000;
+/**
+ * authenticated `git fetch` that recovers from shallow-unreachable errors
+ * by retrying once with `--deepen=1000`. callers pass the same args they
+ * would to `$git("fetch", ...)`; on shallow-unreachable failures in a
+ * shallow repo, the second attempt prepends `--deepen=N` and strips any
+ * caller-supplied `--depth=` (the two flags are mutually exclusive, and
+ * the caller's depth is what got us into this mess).
+ *
+ * non-shallow-unreachable errors and non-shallow repos rethrow unchanged,
+ * so this is safe to wrap any fetch without changing fast-path behavior.
+ */
+export declare function $gitFetchWithDeepen(args: string[], options: GitAuthOptions, label?: string): Promise<GitResult>;
 export {};

package/dist/utils/instructions.d.ts

@@ -1,6 +1,7 @@
 import { type AgentId } from "../external.ts";
 import type { Mode } from "../modes.ts";
 import type { ResolvedPayload } from "./payload.ts";
+import type { LearningsHeading } from "./runContext.ts";
 import type { RunContextData } from "./runContextData.ts";
 interface InstructionsContext {
     payload: ResolvedPayload;
@@ -12,6 +13,10 @@ interface InstructionsContext {
      * couldn't be seeded for some reason. main.ts always seeds, so in
      * practice this is always set; the null case keeps the type honest. */
     learningsFilePath: string | null;
+    /** server-parsed TOC for the body of the learnings tmpfile. rendered
+     * inline into the LEARNINGS prompt section so the agent can `read_file`
+     * targeted line ranges instead of pulling the whole file into context. */
+    learningsHeadings: LearningsHeading[];
 }
 export interface ResolvedInstructions {
     full: string;
@@ -21,5 +26,19 @@ export interface ResolvedInstructions {
     event: string;
     runtime: string;
 }
+/** render the heading list as an indented bullet TOC. ranges shown in
+ * parentheses (`(L3-L18)`); the start line is always the heading line
+ * itself, so reading the listed range gives the agent the heading +
+ * body together. shallowest heading depth in the body sits at the root
+ * column; deeper levels indent by `(depth - rootDepth) * 2` spaces. */
+export declare function renderLearningsToc(headings: LearningsHeading[]): string;
+/** assemble the LEARNINGS prompt section: file path + intro + either
+ * the rendered heading TOC (when the body has structure) or a no-headings
+ * affordance pointing the agent at the reflection turn for restructuring.
+ * empty string when the seed step failed and there's no path to surface. */
+export declare function buildLearningsSection(ctx: {
+    filePath: string | null;
+    headings: LearningsHeading[];
+}): string;
 export declare function resolveInstructions(ctx: InstructionsContext): ResolvedInstructions;
 export {};

package/dist/utils/learnings.d.ts

@@ -4,23 +4,34 @@
  * back into future runs as durable context. Modeled on the PR-summary tmpfile
  * pattern (see action/utils/prSummary.ts):
  *
- *   1. server seeds `pullfrog-learnings.md` from `Repo.learnings` (or empty
- *      when the repo has none yet)
- *   2. the agent reads the file at startup as part of its context, and may
- *      edit it in place at end-of-run when prompted by the reflection turn
- *   3. main.ts reads the file back at end-of-run and PATCHes
- *      `/api/repo/[owner]/[repo]/learnings` if it changed (byte-trim equality
- *      against the seed determines change detection)
+ *   1. server seeds `pullfrog-learnings.md` with the verbatim body of
+ *      `Repo.learnings` (or empty for fresh repos), and parses headings
+ *      server-side (`utils/learningsToc.ts`) — the parsed TOC is rendered
+ *      into the LEARNINGS prompt section, not into the file
+ *   2. the agent reads the TOC in the prompt and uses listed line ranges
+ *      to read just the sections relevant to the current task — file can
+ *      grow large, but only targeted ranges hit the agent's context
+ *   3. agent edits the file in place at end-of-run during the reflection
+ *      turn (see action/agents/postRun.ts buildLearningsReflectionPrompt)
+ *   4. main.ts reads the file back at end-of-run and PATCHes
+ *      `/api/repo/[owner]/[repo]/learnings` if the body changed
  *
  * Edit-in-place avoids stuffing the entire learnings list into both the
  * prompt context and an `update_learnings` MCP tool call (which previously
  * required passing the FULL merged list as a string parameter — an
  * output-token tax that grew linearly with the learnings size).
+ *
+ * Section structure is agent-curated. The reflection prompt teaches
+ * hierarchy + a soft 300-line-per-section cap to keep TOC ranges
+ * agent-targetable on long-lived repos; there is no fixed taxonomy.
  */
 export declare const LEARNINGS_FILE_NAME = "pullfrog-learnings.md";
 export declare function learningsFilePath(tmpdir: string): string;
-/** seed the learnings file with the repo's current learnings, or an empty
- * file when the repo has none yet. returns the absolute path. */
+/** seed the rolling learnings tmpfile with the verbatim DB body (or empty
+ * string for fresh repos). returns the absolute path. the parsed TOC is
+ * carried separately via `RepoSettings.learningsHeadings` and rendered
+ * into the prompt by `resolveInstructions`, so the file on disk is just
+ * the body — no markers, no scaffold, no in-file TOC. */
 export declare function seedLearningsFile(params: {
     tmpdir: string;
     current: string | null;

package/dist/utils/providerErrors.d.ts

@@ -1,2 +1,13 @@
+/**
+ * Result of a provider-error scan: the classification label plus a
+ * human-readable excerpt centered on the matched line. The excerpt is what
+ * gets surfaced in `» provider error detected (...)` log lines — see
+ * `extractExcerpt` for the windowing/byte-cap policy.
+ */
+export type ProviderErrorMatch = {
+    label: string;
+    excerpt: string;
+};
+export declare function findProviderErrorMatch(text: string): ProviderErrorMatch | null;
 export declare function detectProviderError(text: string): string | null;
 export declare function isRouterKeylimitExhaustedError(text: string): boolean;

package/dist/utils/runContext.d.ts

@@ -6,6 +6,21 @@ export interface Mode {
     description: string;
     prompt: string;
 }
+/**
+ * server-parsed TOC entry for `Repo.learnings`. depth is 1-6 (h1-h6),
+ * line numbers are 1-indexed against the raw body. computed by
+ * `parseLearningsHeadings` in `utils/learningsToc.ts` (server side) and
+ * shipped over the run-context JSON boundary; the canonical declaration
+ * lives there. duplicated here because the action runtime can't reach
+ * across into the proprietary root-level codebase, and the JSON wire
+ * means typecheck can't enforce shape equality across both sides.
+ */
+export interface LearningsHeading {
+    depth: 1 | 2 | 3 | 4 | 5 | 6;
+    title: string;
+    startLine: number;
+    endLine: number;
+}
 export interface RepoSettings {
     model: string | null;
     modes: Mode[];
@@ -18,6 +33,7 @@ export interface RepoSettings {
     prApproveEnabled: boolean;
     modeInstructions: Record<string, string>;
     learnings: string | null;
+    learningsHeadings: LearningsHeading[];
     envAllowlist: string | null;
 }
 /**

package/package.json

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