pullfrog 0.1.5 → 0.1.7

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/normalizeEnv.d.ts

@@ -1,3 +1,22 @@
+/**
+ * Trim surrounding whitespace from a sensitive value and register it as a
+ * GitHub Actions log mask. Trailing newlines from terminal-copy paste are a
+ * common footgun: the value travels through GH Actions logs and any tool
+ * that re-emits parts of it leaks the unmasked tail. Trimming canonicalises
+ * the value so the mask matches exactly what downstream tools will print.
+ *
+ * Masking is delegated to `core.setSecret` (not raw `console.log`) so the
+ * toolkit percent-encodes `\r`/`\n`; the runner V2 parser decodes them and
+ * registers the full value plus every non-empty line as separate masks. That
+ * keeps us safe for embedded-newline values (PEMs, kubeconfigs, JSON blobs)
+ * even though they aren't currently used.
+ *
+ * Returns the trimmed value, or `null` when the input was whitespace-only —
+ * callers must leave `process.env` untouched in that case so a misconfigured
+ * value surfaces as a clear "missing key" downstream rather than silently
+ * mutating to the empty string.
+ */
+export declare function sanitizeSecret(key: string, value: string): string | null;
 /**
  * Normalize environment variables to uppercase.
  * This handles case-insensitive env var names (e.g., `anthropic_api_key` -> `ANTHROPIC_API_KEY`).
@@ -5,6 +24,7 @@
  * If there are conflicts (same key with different capitalizations but different values),
  * logs a warning and keeps the uppercase version.
  *
- * Also registers sensitive values as masks in GitHub Actions.
+ * Also trims and masks sensitive values so accidental trailing whitespace
+ * doesn't defeat GitHub Actions log masking.
  */
 export declare function normalizeEnv(): void;

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/dist/utils/subprocess.d.ts

@@ -14,6 +14,27 @@ export declare function trackChild(options: TrackChildOptions): void;
 export declare function untrackChild(child: ChildProcess): void;
 export declare function setSignalHandler(handler: SignalHandler | null): void;
 export declare function killTrackedChildren(): void;
+/**
+ * Controls what the wrapper retains in memory across the child's lifetime
+ * for the post-hoc `SpawnResult.stdout` / `SpawnResult.stderr` snapshots.
+ *
+ * Streaming callbacks (`onStdout` / `onStderr`) fire regardless — `retain`
+ * only governs the buffered snapshot returned in `SpawnResult`.
+ *
+ * - `"tail"` (default): keep the last `maxRetainedBytes` UTF-16 code units
+ *   of each stream. Once the cap is exceeded, oldest bytes are sliced off
+ *   and the result is prefixed with a `... [N MiB truncated] ...` sentinel.
+ *   Right default for short-lived commands whose failure mode is in their
+ *   final output (git errors, install failures, hook scripts).
+ * - `"none"`: skip the buffer entirely. `SpawnResult.stdout` / `.stderr`
+ *   are empty strings. Use this for long-lived streaming agents that already
+ *   drain via `onStdout` / `onStderr` and never read the buffered snapshot.
+ *
+ * Default cap is 8 MiB — well below V8's ~1 GiB `kMaxLength` so `+= chunk`
+ * can never throw `RangeError: Invalid string length`.
+ */
+export type RetainMode = "tail" | "none";
+export declare const DEFAULT_MAX_RETAINED_BYTES: number;
 export interface SpawnOptions {
     cmd: string;
     args: string[];
@@ -27,6 +48,25 @@ export interface SpawnOptions {
     onStdout?: (chunk: string) => void;
     onStderr?: (chunk: string) => void;
     killGroup?: boolean;
+    retain?: RetainMode;
+    maxRetainedBytes?: number;
+}
+/**
+ * Bounded string accumulator that keeps the tail of appended chunks.
+ * Once the cap is exceeded, oldest bytes are sliced off and `toString()`
+ * prefixes the survivors with a sentinel describing the elided byte count.
+ *
+ * Exported because long-lived agent runtimes (opencode, claude) also
+ * accumulate per-run narration strings independently of the spawn wrapper
+ * and need the same protection against V8's `kMaxLength`.
+ */
+export declare class TailBuffer {
+    private readonly cap;
+    private buffer;
+    private truncatedBytes;
+    constructor(cap: number);
+    append(chunk: string): void;
+    toString(): string;
 }
 export interface SpawnResult {
     stdout: string;

package/dist/utils/timer.d.ts

@@ -4,9 +4,20 @@ export declare class Timer {
     constructor();
     checkpoint(name: string): void;
 }
+/**
+ * Measures wall-clock gap between the last tool_result and the next tool_call,
+ * surfacing it as a "thought for Xs" log when over `THINKING_THRESHOLD`.
+ *
+ * Use one instance per logical session (orchestrator, each subagent) — sharing
+ * a single timer across sessions conflates cross-session interleaving as
+ * thinking time. The optional `formatLine` lets the caller prefix output with
+ * a session label so attribution is visible in the merged log stream.
+ */
 export declare class ThinkingTimer {
     private readonly durationFormatter;
     private lastToolResultTimestamp;
+    private readonly formatLine;
+    constructor(formatLine?: (line: string) => string);
     markToolResult(): void;
     markToolCall(): void;
 }

package/package.json

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