hotmilk 0.1.13 → 0.1.15

package/src/ui/footer.ts

@@ -13,7 +13,12 @@ import {
   resolveGithubFooterContextAsync,
 } from "./github-user.ts";
 
-/** Pure footer clock formatting (no pi-coding-agent imports — safe for unit tests). */
+/**
+ * Pure footer clock formatting (no pi-coding-agent imports — safe for unit tests).
+ *
+ * @param date - Date to format
+ * @returns formatted time string in HH:mm:ss format
+ */
 export function formatFooterTime(date: Date): string {
   return new Intl.DateTimeFormat(undefined, {
     hour: "2-digit",
@@ -23,6 +28,12 @@ export function formatFooterTime(date: Date): string {
   }).format(date);
 }
 
+/**
+ * Sanitize footer status text by removing newlines, tabs, and extra spaces.
+ *
+ * @param text - raw status text
+ * @returns sanitized text
+ */
 function sanitizeStatusText(text: string): string {
   return text
     .replace(/[\r\n\t]/g, " ")
@@ -30,6 +41,15 @@ function sanitizeStatusText(text: string): string {
     .trim();
 }
 
+/**
+ * Format extension status lines for the footer.
+ *
+ * @param footerData - footer data provider
+ * @param width - terminal width
+ * @param dim - dimming function
+ * @param ellipsis - ellipsis string
+ * @returns formatted status lines
+ */
 function extensionStatusLines(
   footerData: ReadonlyFooterDataProvider,
   width: number,
@@ -48,10 +68,24 @@ function extensionStatusLines(
     .map((text) => truncateToWidth(dim(text), width, ellipsis));
 }
 
+/**
+ * Check if a footer line has visible content.
+ *
+ * @param line - line to check
+ * @returns true if line has visible content
+ */
 function isVisibleFooterLine(line: string): boolean {
   return visibleWidth(line) > 0;
 }
 
+/**
+ * Append metadata (time, term program) to the last footer line if it fits.
+ *
+ * @param lines - existing footer lines
+ * @param meta - metadata to append
+ * @param width - terminal width
+ * @returns updated lines
+ */
 function appendMetaToLastLine(lines: string[], meta: string, width: number): string[] {
   const visibleLines = lines.filter(isVisibleFooterLine);
   if (visibleLines.length === 0) {
@@ -75,6 +109,12 @@ function appendMetaToLastLine(lines: string[], meta: string, width: number): str
 
 const FOOTER_TIME_REFRESH_MS = 30_000;
 
+/**
+ * Get the latest thinking level from session manager entries.
+ *
+ * @param sessionManager - Pi session manager
+ * @returns latest thinking level
+ */
 function latestThinkingLevel(sessionManager: ExtensionContext["sessionManager"]): ThinkingLevel {
   const entries = sessionManager.getEntries();
   for (let i = entries.length - 1; i >= 0; i--) {
@@ -86,6 +126,12 @@ function latestThinkingLevel(sessionManager: ExtensionContext["sessionManager"])
   return "off";
 }
 
+/**
+ * Create a footer-compatible session object from extension context.
+ *
+ * @param ctx - extension context
+ * @returns agent session for footer
+ */
 function footerSessionFromContext(ctx: ExtensionContext): AgentSession {
   return {
     get state() {
@@ -100,6 +146,16 @@ function footerSessionFromContext(ctx: ExtensionContext): AgentSession {
   } as AgentSession;
 }
 
+/**
+ * Decorate the pwd line with GitHub user handle if available.
+ *
+ * @param pwdLine - current working directory line
+ * @param githubUser - resolved GitHub user
+ * @param repoOwner - repo owner
+ * @param width - terminal width
+ * @param theme - Pi theme
+ * @returns decorated pwd line
+ */
 function decoratePwdLine(
   pwdLine: string,
   githubUser: string | undefined,
@@ -118,6 +174,12 @@ function decoratePwdLine(
   return truncateToWidth(decorated, width, theme.fg("dim", "..."));
 }
 
+/**
+ * Install the hotmilk footer with GitHub user, clock, and extension status lines.
+ *
+ * @param ctx - extension context
+ * @param termProgram - terminal program identifier
+ */
 export function setupHotmilkFooter(ctx: ExtensionContext, termProgram: string): void {
   if (!ctx.hasUI) {
     return;

package/src/ui/github-user.ts

@@ -1,3 +1,10 @@
+/**
+ * GitHub user / repo-owner resolution for the footer.
+ *
+ * Reads `$GITHUB_USER`, `gh api user`, git config, and the `origin` remote
+ * to show `@handle` and highlight repo ownership in the status bar.
+ */
+
 import { execFile, execFileSync } from "node:child_process";
 import { promisify } from "node:util";
 
@@ -57,11 +64,23 @@ async function runCommandAsync(
 const GITHUB_REMOTE_OWNER =
   /^(?:git@github\.com:|https?:\/\/github\.com\/|ssh:\/\/git@github\.com\/)([^/]+)\//;
 
-/** Parse `owner` from common github.com remote URL shapes. */
+/**
+ * Parse the owner/user from common github.com remote URL shapes.
+ *
+ * @param url - remote URL like `https://github.com/owner/repo.git`
+ * @returns the owner string, or undefined if not a GitHub remote
+ */
 export function parseGithubUserFromRemote(url: string): string | undefined {
   return GITHUB_REMOTE_OWNER.exec(url.trim())?.[1];
 }
 
+/**
+ * Append the GitHub handle to the prompt path segment.
+ *
+ * @param pwd - current working directory string
+ * @param githubUser - resolved GitHub handle
+ * @returns footer path text
+ */
 export function formatFooterPwdWithGithubUser(pwd: string, githubUser: string | undefined): string {
   if (!githubUser) {
     return pwd;
@@ -69,16 +88,28 @@ export function formatFooterPwdWithGithubUser(pwd: string, githubUser: string |
   return `${pwd} · @${githubUser}`;
 }
 
+/**
+ * Check whether the GitHub user owns the current repo.
+ *
+ * @param githubUser - resolved GitHub handle
+ * @param repoOwner - owner parsed from `origin`
+ */
 export function isGithubRepoOwner(githubUser: string, repoOwner: string | undefined): boolean {
   return repoOwner !== undefined && githubUser.toLowerCase() === repoOwner.toLowerCase();
 }
 
+/** Options for {@link resolveRepoOwner}. */
 export type ResolveRepoOwnerOptions = {
   cwd?: string;
+  /** Override command executor for tests. */
   runCommand?: (file: string, args: string[], cwd?: string) => string | undefined;
 };
 
-/** GitHub owner from `origin` remote, when the cwd is a git checkout. */
+/**
+ * Resolve the GitHub repo owner from the `origin` remote.
+ *
+ * @param opts - options, including optional command executor for tests
+ */
 export function resolveRepoOwner(opts: ResolveRepoOwnerOptions = {}): string | undefined {
   const cwd = opts.cwd ?? process.cwd();
   const exec = opts.runCommand ?? runCommand;
@@ -89,13 +120,21 @@ export function resolveRepoOwner(opts: ResolveRepoOwnerOptions = {}): string | u
   return parseGithubUserFromRemote(remote);
 }
 
+/** Options for {@link resolveGithubUsername}. */
 export type ResolveGithubUsernameOptions = {
   cwd?: string;
   env?: NodeJS.ProcessEnv;
+  /** Override command executor for tests. */
   runCommand?: (file: string, args: string[], cwd?: string) => string | undefined;
 };
 
-/** Best-effort GitHub login for footer display (env → gh → git config → origin remote). */
+/**
+ * Best-effort GitHub login for footer display.
+ *
+ * Resolution order: `$GITHUB_USER` → `gh api user` → git config → origin remote.
+ *
+ * @param opts - options, including optional command executor for tests
+ */
 export function resolveGithubUsername(opts: ResolveGithubUsernameOptions = {}): string | undefined {
   const cwd = opts.cwd ?? process.cwd();
   const env = opts.env ?? process.env;
@@ -117,18 +156,27 @@ export function resolveGithubUsername(opts: ResolveGithubUsernameOptions = {}):
   return remote ? parseGithubUserFromRemote(remote) : undefined;
 }
 
+/** Footer payload containing the GitHub handle and repo owner. */
 export type GithubFooterContext = {
   githubUser?: string;
   repoOwner?: string;
 };
 
+/** Options for {@link resolveGithubFooterContextAsync}. */
 export type ResolveGithubFooterContextOptions = {
   cwd?: string;
   env?: NodeJS.ProcessEnv;
+  /** Override async command executor for tests. */
   runCommandAsync?: (file: string, args: string[], cwd?: string) => Promise<string | undefined>;
 };
 
-/** Resolve footer GitHub handle + repo owner without blocking UI startup. */
+/**
+ * Resolve footer GitHub handle and repo owner asynchronously.
+ *
+ * Non-blocking so the footer can refresh after UI startup.
+ *
+ * @param opts - options, including optional async command executor for tests
+ */
 export async function resolveGithubFooterContextAsync(
   opts: ResolveGithubFooterContextOptions = {},
 ): Promise<GithubFooterContext> {

package/src/ui/session-logo.ts

@@ -13,10 +13,18 @@ const LOGO_LINES = HOTMILK_LOGO.split("\n");
 /** Same lead time as gentle-pi `startup-banner.ts`. */
 const LOGO_SHOW_DELAY_MS = 50;
 
+/** Timeout handle for delayed logo display. */
 let showTimeout: ReturnType<typeof setTimeout> | undefined;
+/** Active TUI instance for logo rendering. */
 let activeTui: TUI | undefined;
 
-/** Center fixed-width ASCII lines within the terminal width. */
+/**
+ * Center fixed-width ASCII lines within the terminal width.
+ *
+ * @param lines - ASCII lines to center
+ * @param width - terminal width
+ * @returns centered lines
+ */
 export function centerAsciiLines(lines: readonly string[], width: number): string[] {
   const contentWidth = Math.max(...lines.map((line) => line.length), 1);
   const pad = Math.max(0, Math.floor((width - contentWidth) / 2));
@@ -24,11 +32,17 @@ export function centerAsciiLines(lines: readonly string[], width: number): strin
   return lines.map((line) => prefix + line.padEnd(contentWidth));
 }
 
-/** Skip only `/reload`; show on fresh launch and session resume (gentle-pi shows every session_start). */
+/**
+ * Skip only `/reload`; show on fresh launch and session resume (gentle-pi shows every session_start).
+ *
+ * @param reason - session start reason
+ * @returns true if logo should be shown
+ */
 export function shouldShowSessionLogo(reason: string): boolean {
   return reason !== "reload";
 }
 
+/** Clear any pending logo display timers. */
 function clearLogoTimers(): void {
   if (showTimeout) {
     clearTimeout(showTimeout);
@@ -36,6 +50,11 @@ function clearLogoTimers(): void {
   }
 }
 
+/**
+ * Dismiss the hotmilk logo from the header.
+ *
+ * @param ctx - extension context
+ */
 function dismissHotmilkLogo(ctx: ExtensionContext): void {
   if (!ctx.hasUI) return;
   ctx.ui.setHeader(undefined);
@@ -43,6 +62,11 @@ function dismissHotmilkLogo(ctx: ExtensionContext): void {
   activeTui = undefined;
 }
 
+/**
+ * Show the hotmilk session logo with a delay.
+ *
+ * @param ctx - extension context
+ */
 function showHotmilkSessionLogo(ctx: ExtensionContext): void {
   if (!ctx.hasUI) return;
 
@@ -65,7 +89,11 @@ function showHotmilkSessionLogo(ctx: ExtensionContext): void {
   }, LOGO_SHOW_DELAY_MS);
 }
 
-/** Register persistent header logo on session start; clear on shutdown only. */
+/**
+ * Register persistent header logo on session start; clear on shutdown only.
+ *
+ * @param pi - Pi extension API
+ */
 export function registerHotmilkSessionLogo(pi: ExtensionAPI): void {
   pi.on("session_start", (event, ctx) => {
     if (!shouldShowSessionLogo(event.reason)) return;

package/themes/monokai.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "https://raw.githubusercontent.com/badlogic/pi-mono/main/packages/coding-agent/src/modes/interactive/theme/theme-schema.json",
+  "$schema": "https://raw.githubusercontent.com/earendil-works/pi/main/packages/coding-agent/src/modes/interactive/theme/theme-schema.json",
   "name": "monokai",
   "vars": {
     "bg": "#272822",

package/skills/empirical-prompt-tuning/SKILL.md

@@ -1,232 +0,0 @@
----
-name: empirical-prompt-tuning
-description: "Harden prompts: fresh executor each iteration, checklist scoring, one themed delta per loop until convergence. After editing skills, AGENTS.md, CLAUDE.md, or task prompts. [Triggers: empirical prompt tuning, prompt evaluation, tune prompt, fresh agent evaluation]"
----
-
-# Empirical Prompt Tuning
-
-A prompt's quality is opaque to its author. **Dispatch a fresh agent, run the prompt, evaluate on two axes, iterate until plateau.** Do not stop before the plateau.
-
-## Core Concept: Fresh Agent
-
-Any executor with **no authoring context** and **no memory of prior iterations**. The implementation does not matter; the absence of authoring bias does. Self re-reading never qualifies.
-
-### Dispatch Methods (pick one)
-
-| Method                         | How                                                                                                                  | Notes                                                                             |
-| ------------------------------ | -------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
-| **pi-subagents** (recommended) | `subagent({ agent: "assistant", task: "...", context: "fresh", model: "<model-id>", skill: false, clarify: false })` | Always set `context: "fresh"`, explicit `model`, `skill: false`, `clarify: false` |
-| **Claude Code Task**           | `{ agent: "worker", task: "...", context: "fresh" }`                                                                 | Alternative when PI unavailable                                                   |
-| **Separate session**           | New terminal: `claude` or `pi`                                                                                       | Manual but reliable                                                               |
-| **Direct API**                 | POST to `/v1/messages` with empty history                                                                            | For programmatic testing                                                          |
-
-**NOT fresh**: `context: "fork"` (inherits history), same session, self re-reading.
-
-For parallel scenarios, use `subagent({ tasks: [...] })` with models from the **same provider** to avoid cross-provider timeouts.
-
-## Workflow
-
-```
-0. Static coherence check (no dispatch)
-1. Baseline: stakes tier + scenarios + requirement checklists
-2. Dispatch fresh agent → execute → self-report
-3. Two-sided evaluation (self-report + instructor metrics)
-4. Apply ONE themed delta
-5. New fresh agent → re-evaluate
-6. Stop at 2 consecutive clears (or 3 for high-stakes)
-```
-
-### Step 0 — Static Coherence Check
-
-Compare what the prompt **advertises** vs what the body **delivers**. Fix divergences before any dispatch.
-
-| Target type                 | "Advertises" source          | Check                                       |
-| --------------------------- | ---------------------------- | ------------------------------------------- |
-| Skill file                  | Frontmatter `description`    | Triggers/use-cases match body coverage?     |
-| CLAUDE.md section           | Section heading              | Heading promise matches actionable content? |
-| Task prompt / system prompt | Opening instruction or title | Stated goal matches the actual rules?       |
-
-Skipping this causes false positives — the fresh agent silently re-interprets the body.
-
-### Step 1 — Baseline Preparation
-
-**Choose and freeze a stakes tier** before anything else:
-
-| Stakes                            | Scenarios             | `[critical]` tags | Stop condition       | Iteration cap |
-| --------------------------------- | --------------------- | ----------------- | -------------------- | ------------- |
-| **High** (core skill, automation) | 3 (1 median + 2 edge) | ≥ 2               | 3 consecutive clears | none          |
-| **Standard** (default)            | 2 (1 median + 1 edge) | ≥ 1               | 2 consecutive clears | 5             |
-| **Low** (small, low-blast)        | 2 (1 median + 1 edge) | ≥ 1               | ship at 80%          | 3             |
-
-For each scenario, write a **requirement checklist** (3–7 items). Rules:
-
-- At least one item tagged `[critical]` — without it, success judgment is vacuous.
-- Fix the checklist before running. Do not adjust after seeing results.
-- **Translating user complaints into checklist items**: If the user says "it produces shallow output", decompose "shallow" into observable, testable criteria (e.g., "identifies at least one concrete bug", "includes line references", "provides actionable suggestions"). Each criterion becomes a checklist item. The user's complaint itself is not a valid checklist item.
-- `[critical]` means: if this item fails, the whole scenario fails (binary ×), regardless of other items.
-- Non-critical items score: ○ = 1, partial = 0.5, × = 0. Accuracy = sum / total.
-
-### Step 2–3 — Dispatch and Execute
-
-Hand the fresh agent this contract:
-
-```
-You are an executor reading <target prompt name> as a blank slate.
-You have no prior exposure to this prompt; treat it as newly encountered.
-
-## Target Prompt
-<paste the full target prompt here>
-
-## Scenario
-<one paragraph describing the situation>
-
-## Requirement Checklist
-1. [critical] <item>
-2. <item>
-...
-
-## Task
-1. Execute the scenario following the target prompt and produce the deliverable.
-2. On completion, respond with the report below.
-
-## Report Structure
-- Deliverable: <the artifact or run summary>
-- Requirement status: for each item, ○ / × / partial (with reason)
-- Ambiguities: places where wording was open to interpretation (bullets)
-- Discretionary fills: decisions the instructions did not specify (bullets)
-- Retries: how many times you redid a decision and why
-```
-
-**Always paste the full prompt** in the contract (not a file path) — ensures portability across all harness types.
-
-### Step 4 — Two-Sided Evaluation
-
-| Axis                    | Source               | How to measure                                                                                                                                                                                                                                                                                 |
-| ----------------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Success/Failure**     | Instructor           | ○ only if every `[critical]` met. Binary.                                                                                                                                                                                                                                                      |
-| **Accuracy**            | Instructor           | ○/partial/× per item → percentage                                                                                                                                                                                                                                                              |
-| **Step count**          | Environment metadata | `tool_uses` (Claude Code), tool-use blocks (API). For **text-generation targets** (no tool use): substitute with a concrete output-unit count — e.g., number of review comments, checklist items produced, or code blocks emitted. State the chosen unit once at the top of the iteration log. |
-| **Duration**            | Environment metadata | `duration_ms` or wall-clock                                                                                                                                                                                                                                                                    |
-| **Retry count**         | Self-report          | Times the agent redid a decision                                                                                                                                                                                                                                                               |
-| **Ambiguities**         | Self-report          | Qualitative — primary signal for improvement                                                                                                                                                                                                                                                   |
-| **Discretionary fills** | Self-report          | Surfaces implicit requirements                                                                                                                                                                                                                                                                 |
-
-**Weighting**: Qualitative signals (ambiguities, fills) are primary. Quantitative metrics (time, steps) are supporting. Chasing time alone makes prompts brittle.
-
-**On failure**: append one line to Ambiguities naming which `[critical]` item dropped.
-
-#### Step Count as Structure Signal
-
-Even at 100% accuracy, step-count skew across scenarios exposes structural flaws:
-
-- One scenario at 3–5× the others → the prompt lacks self-containment for that case (executor wandered).
-- Fix: add inline guidance or a minimal complete example.
-
-### Step 5 — Apply ONE Delta
-
-1. Identify the most impactful ambiguity.
-2. **State which checklist item the edit satisfies** before editing — edits inferred from axis names alone rarely land.
-3. Apply the minimum edit. One semantic theme per iteration. A cluster of 2–3 related micro-edits is one theme; unrelated edits go to the next iteration.
-
-#### Correction Propagation Patterns
-
-| Pattern            | What happens                                | Lesson                                                      |
-| ------------------ | ------------------------------------------- | ----------------------------------------------------------- |
-| Conservative drift | Edit aimed at multiple axes, only one moved | Multi-axis shots usually miss                               |
-| Upside drift       | One structural edit satisfied multiple axes | Information combos are naturally multi-axis                 |
-| Null drift         | Edit didn't move any axis                   | Axis names ≠ judgment text. Tie edits to threshold wording. |
-
-### Step 6 — Re-evaluate
-
-Dispatch a **new** fresh agent. Never reuse — it learned from the prior run. Repeat from Step 2.
-
-### Step 7 — Stopping Criteria
-
-**Converged** when for N consecutive iterations (N = 2 standard, 3 high-stakes):
-
-- New ambiguities: 0
-- Accuracy gain: ≤ +3 points
-- Step count change: within ±10%
-- Duration change: within ±15%
-
-**At convergence** (all tiers): add one hold-out scenario not used in any prior iteration. If accuracy drops ≥ 15 points → overfitting. Return to scenario design. This is mandatory, not optional.
-
-**Diverged**: after 3+ iterations ambiguities aren't decreasing → the prompt's design is wrong. Stop patching, rewrite.
-
-**Resource cutoff**: ship at 80% when improvement cost exceeds prompt importance.
-
-### Presentation Format
-
-Record each iteration as:
-
-```
-## Iteration N
-
-### Changes (delta from previous)
-- <one-line edit description>
-
-### Results
-| Scenario | Success | Accuracy | Steps | Duration | Retries |
-|---|---|---|---|---|---|
-| A | ○ | 90% | 4 | 20s | 0 |
-| B | × | 60% | 9 | 41s | 2 |
-
-### Ambiguities (new this iteration)
-- <Scenario B>: [critical] item N was × — <reason>
-- <Scenario A>: (none new)
-
-### Discretionary fills (new this iteration)
-- <Scenario B>: <what was filled>
-
-### Next edit
-- <one-line minimal edit>
-
-(Convergence: X consecutive clears / Y iterations until stop)
-```
-
-- Never leave an axis blank (write "0", not "—").
-- "None new" is explicit signal.
-- Steps column may be replaced with turn count in plain-chat environments — note the substitution once.
-
-## Red Flags
-
-| Rationalization                                  | Reality                                                              |
-| ------------------------------------------------ | -------------------------------------------------------------------- |
-| "Re-reading it myself is equivalent."            | Structurally impossible to objectively view text you just wrote.     |
-| "One scenario is enough."                        | Overfits. Minimum 2.                                                 |
-| "Zero ambiguities once, so done."                | May be coincidence. Require consecutive clears.                      |
-| "Fix multiple things in one pass."               | Lose attribution. One theme per iteration.                           |
-| "Metrics look good, ignore qualitative."         | Faster ≠ better. Qualitative is primary.                             |
-| "Reuse the same fresh agent."                    | It learned. Dispatch anew every time.                                |
-| "Split every micro-edit into its own iteration." | Over-splitting. One semantic unit = one iteration.                   |
-| "Rewrite from scratch."                          | Valid only after 3+ stalled iterations. Before that, it's an escape. |
-
-## Environment Constraints
-
-### When Fresh Agent Is Unavailable
-
-This skill **requires** a fresh agent. Do not apply it when:
-
-- Inside a subagent with no dispatch privileges
-- `subagent` / Task tool is disabled
-- No API key or rate-limited
-- Cannot obtain fresh context through any method
-
-### Fallback Order
-
-1. Ask the user to open a separate session
-2. Report: "empirical evaluation skipped: no fresh agent available"
-3. **Never substitute self re-reading**
-
-### Structural-Audit Mode
-
-For coherence/clarity checks only (not empirical behavior): mark the request with _"structural-audit mode: check textual coherence only, do not execute."_ This is a supplement — it cannot count toward consecutive-clear convergence.
-
-### pi-subagents Troubleshooting
-
-| Symptom                     | Cause                    | Fix                        |
-| --------------------------- | ------------------------ | -------------------------- |
-| "No API key found"          | Default model resolution | Specify `model` explicitly |
-| Agent reads wrong files     | Skill/cwd pollution      | Add `skill: false`         |
-| Parallel timeout (exit 143) | Cross-provider mixing    | Same-provider models only  |
-| Subagent hangs              | Provider instability     | Try different model id     |