hotmilk 0.1.13 → 0.1.15

package/src/config/bundled-extensions.ts

@@ -73,12 +73,30 @@ export const BUNDLED_EXTENSION_DEFINITIONS = [
     module: "graphify-pi/extensions/graphify.ts",
     group: "Agent tools",
   },
+  {
+    id: "shazam",
+    package: { packageName: "pi-shazam" },
+    module: "pi-shazam/dist/index.js",
+    group: "Agent tools",
+  },
+  {
+    id: "prompt-template-model",
+    package: { packageName: "pi-prompt-template-model" },
+    module: "pi-prompt-template-model/index.ts",
+    group: "Agent tools",
+  },
   {
     id: "subagents",
     package: { packageName: "pi-subagents" },
     module: "pi-subagents/src/extension/index.ts",
     group: "Agent tools",
   },
+  {
+    id: "pi-actors",
+    package: { packageName: "@llblab/pi-actors" },
+    module: "@llblab/pi-actors/index.ts",
+    group: "Agent tools",
+  },
   {
     id: "goal",
     package: { packageName: "pi-goal" },
@@ -116,6 +134,18 @@ export const BUNDLED_EXTENSION_DEFINITIONS = [
     group: "Context & performance",
     loadPhase: "context-stack",
   },
+  {
+    id: "observational-memory",
+    package: { packageName: "pi-observational-memory" },
+    module: "pi-observational-memory/src/index.ts",
+    group: "Context & performance",
+  },
+  {
+    id: "supi-context",
+    package: { packageName: "@mrclrchtr/supi-context" },
+    module: "@mrclrchtr/supi-context/src/extension.ts",
+    group: "Context & performance",
+  },
   {
     id: "mcp-adapter",
     package: { packageName: "pi-mcp-adapter" },
@@ -128,6 +158,12 @@ export const BUNDLED_EXTENSION_DEFINITIONS = [
     module: "@tomxprime/planning-with-files/extensions/planning-with-files/index.ts",
     group: "Workflow",
   },
+  {
+    id: "plannotator",
+    package: { packageName: "@plannotator/pi-extension" },
+    module: "@plannotator/pi-extension/index.ts",
+    group: "Workflow",
+  },
   {
     id: "caveman",
     package: { packageName: "pi-caveman" },
@@ -140,6 +176,12 @@ export const BUNDLED_EXTENSION_DEFINITIONS = [
     module: "pi-red-green/dist/index.js",
     group: "Workflow",
   },
+  {
+    id: "autoresearch",
+    package: { packageName: "pi-autoresearch" },
+    module: "pi-autoresearch/extensions/pi-autoresearch/index.ts",
+    group: "Experiments",
+  },
   {
     id: "agent-dashboard",
     package: {

package/src/config/bundled-package-registry.ts

@@ -8,13 +8,16 @@ export type { BundledPackageSpec };
 
 export { BUNDLED_EXTENSION_PACKAGES };
 
+/** Canonical npm package name for hotmilk itself. */
 export const HOTMILK_PACKAGE_NAME = "hotmilk";
 
+/** Return all package names (primary + aliases) that satisfy a bundled extension id. */
 export function packageNamesForBundledExtension(id: BundledExtensionId): readonly string[] {
   const spec = BUNDLED_EXTENSION_PACKAGES[id];
   return spec.aliases ? [spec.packageName, ...spec.aliases] : [spec.packageName];
 }
 
+/** Return the installed package name that provides a bundled id globally, if any. */
 export function detectGlobalProviderForBundledExtension(
   id: BundledExtensionId,
   installedPackageNames: ReadonlySet<string>,

package/src/config/hotmilk.ts

@@ -1,3 +1,10 @@
+/**
+ * hotmilk user configuration loading and defaults.
+ *
+ * Reads/writes `~/.pi/agent/hotmilk.json` and derives the in-memory default
+ * config from the bundled `hotmilk.json` template.
+ */
+
 import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
@@ -16,11 +23,16 @@ function readBundledHotmilkTemplate(): HotmilkConfig {
   return JSON.parse(readFileSync(BUNDLED_TEMPLATE_PATH, "utf8")) as HotmilkConfig;
 }
 
+function isProjectTrustMode(value: unknown): value is ProjectTrustMode {
+  return value === "delegate" || value === "prompt" || value === "always" || value === "never";
+}
+
 function buildDefaultConfigFromTemplate(template: HotmilkConfig): {
   extensions: Record<BundledExtensionId, boolean>;
   graph: ResolvedGraphSettings;
   defaults: ResolvedDefaults;
   mcp: ResolvedMcpSettings;
+  projectTrust: ResolvedProjectTrust;
 } {
   const extensions = {} as Record<BundledExtensionId, boolean>;
   for (const id of BUNDLED_EXTENSION_IDS) {
@@ -33,6 +45,7 @@ function buildDefaultConfigFromTemplate(template: HotmilkConfig): {
 
   const language = template.defaults?.language?.trim();
   const persona = template.defaults?.persona;
+  const projectTrustMode = template.projectTrust?.mode;
 
   return {
     extensions,
@@ -47,16 +60,33 @@ function buildDefaultConfigFromTemplate(template: HotmilkConfig): {
     mcp: {
       seedOnStart: template.mcp?.seedOnStart ?? false,
     },
+    projectTrust: {
+      mode: isProjectTrustMode(projectTrustMode) ? projectTrustMode : "delegate",
+      remember: template.projectTrust?.remember ?? false,
+    },
   };
 }
 
+/** Filename used for hotmilk config under the config root. */
 export const CONFIG_FILENAME = "hotmilk.json";
+/** Human-readable label for the agent-level config path. */
 export const AGENT_HOTMILK_CONFIG_LABEL = "~/.pi/agent/hotmilk.json";
 
 export { BUNDLED_EXTENSION_IDS, type BundledExtensionId } from "./bundled-extensions.ts";
 
+/** Supported persona modes. */
 export type PersonaMode = "gentleman" | "neutral";
 
+/** Supported project-trust decision modes. */
+export type ProjectTrustMode = "delegate" | "prompt" | "always" | "never";
+
+/** Resolved project-trust settings. */
+export type ResolvedProjectTrust = {
+  mode: ProjectTrustMode;
+  remember: boolean;
+};
+
+/** User-editable hotmilk config schema. */
 export type HotmilkConfig = {
   extensions?: Partial<Record<BundledExtensionId, boolean>>;
   graph?: {
@@ -70,6 +100,10 @@ export type HotmilkConfig = {
   mcp?: {
     seedOnStart?: boolean;
   };
+  projectTrust?: {
+    mode?: ProjectTrustMode;
+    remember?: boolean;
+  };
 };
 
 type ConfigPathResult = {
@@ -85,23 +119,36 @@ type SeedHotmilkConfigResult = ConfigPathResult & {
   seeded: boolean;
 };
 
+/** Resolved graphify-related settings. */
 export type ResolvedGraphSettings = {
   warnOnStale: boolean;
   autoSuggestUpdate: boolean;
 };
 
+/** Resolved default persona/language settings. */
 export type ResolvedDefaults = {
   language?: string;
   persona: PersonaMode;
 };
 
+/** Resolved MCP bootstrap settings. */
 export type ResolvedMcpSettings = {
   seedOnStart: boolean;
 };
 
-/** Derived from the bundled `hotmilk.json` template (single source of truth). */
+/**
+ * In-memory default config derived from the bundled `hotmilk.json` template.
+ *
+ * This is the single source of truth for bundled defaults.
+ */
 export const DEFAULT_HOTMILK_CONFIG = buildDefaultConfigFromTemplate(readBundledHotmilkTemplate());
 
+/**
+ * Resolve the directory that holds `hotmilk.json`.
+ *
+ * @param configRoot - explicit override
+ * @returns config root directory
+ */
 export function resolveHotmilkConfigRoot(configRoot?: string): string {
   if (configRoot) {
     return configRoot;
@@ -112,6 +159,11 @@ export function resolveHotmilkConfigRoot(configRoot?: string): string {
   return join(homedir(), ".pi", "agent");
 }
 
+/**
+ * Resolve the full path to `hotmilk.json`.
+ *
+ * @param configRoot - explicit config root override
+ */
 export function getHotmilkConfigPath(configRoot?: string): string {
   return join(resolveHotmilkConfigRoot(configRoot), CONFIG_FILENAME);
 }
@@ -129,6 +181,12 @@ function writeHotmilkConfigFile(path: string, config: HotmilkConfig): void {
   writeFileSync(path, `${JSON.stringify(config, null, 2)}\n`, "utf8");
 }
 
+/**
+ * Copy the bundled `hotmilk.json` template to the agent config directory.
+ *
+ * @param configRoot - explicit config root override
+ * @returns seed result, with `error` set on filesystem failure
+ */
 export function seedHotmilkConfigIfMissing(configRoot?: string): SeedHotmilkConfigResult {
   const configPath = getHotmilkConfigPath(configRoot);
   if (existsSync(configPath)) {
@@ -139,6 +197,11 @@ export function seedHotmilkConfigIfMissing(configRoot?: string): SeedHotmilkConf
   return { seeded: true, path: configPath };
 }
 
+/**
+ * Load hotmilk config from disk, falling back to {@link DEFAULT_HOTMILK_CONFIG}.
+ *
+ * @param configRoot - explicit config root override
+ */
 export function loadHotmilkConfig(configRoot?: string): LoadedHotmilkConfig {
   const configPath = getHotmilkConfigPath(configRoot);
   if (!existsSync(configPath)) {
@@ -153,6 +216,12 @@ export function loadHotmilkConfig(configRoot?: string): LoadedHotmilkConfig {
   }
 }
 
+/**
+ * Persist hotmilk config to disk.
+ *
+ * @param config - config object to write
+ * @param configRoot - explicit config root override
+ */
 export function saveHotmilkConfig(config: HotmilkConfig, configRoot?: string): ConfigPathResult {
   const configPath = getHotmilkConfigPath(configRoot);
   try {
@@ -163,6 +232,11 @@ export function saveHotmilkConfig(config: HotmilkConfig, configRoot?: string): C
   }
 }
 
+/**
+ * Load and resolve bundled-extension toggle state.
+ *
+ * @param configRoot - explicit config root override
+ */
 export function loadBundledExtensionToggles(
   configRoot?: string,
 ): Record<BundledExtensionId, boolean> {
@@ -174,4 +248,5 @@ export {
   resolveDefaults,
   resolveGraphSettings,
   resolveMcpSettings,
+  resolveProjectTrust,
 } from "./resolve.ts";

package/src/config/mcp.ts

@@ -1,3 +1,11 @@
+/**
+ * MCP config seeding and legacy context-mode cleanup.
+ *
+ * Seeds the agent `mcp.json` from the bundled template and prunes duplicate
+ * `context-mode` MCP server entries because context-mode exposes `ctx_*`
+ * through its own extension bridge.
+ */
+
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
@@ -11,6 +19,11 @@ type AgentMcpFile = {
   mcpServers?: Record<string, unknown>;
 };
 
+/**
+ * Copy the bundled `mcp.json` template into the agent directory when absent.
+ *
+ * @returns seed result
+ */
 export function seedAgentMcpJsonIfMissing(): { seeded: boolean; path: string } {
   const agentMcpPath = join(getAgentDir(), "mcp.json");
   if (existsSync(agentMcpPath)) {
@@ -25,29 +38,49 @@ export function seedAgentMcpJsonIfMissing(): { seeded: boolean; path: string } {
 }
 
 /**
- * Option A: context-mode extension registers ctx_* via its built-in MCP bridge.
- * A hotmilk-seeded `context-mode` MCP server duplicates that path via pi-mcp-adapter.
+ * Remove the legacy `context-mode` MCP server entry from a given `mcp.json`.
+ *
+ * Context-mode exposes `ctx_*` through its own extension bridge, so a seeded
+ * MCP server for it would duplicate functionality.
+ *
+ * @param mcpJsonPath - path to the MCP config file
+ * @returns prune result, with `error` set on filesystem failure
  */
-export function pruneContextModeFromMcpJsonAt(mcpJsonPath: string): boolean {
+export function pruneContextModeFromMcpJsonAt(mcpJsonPath: string): {
+  pruned: boolean;
+  path: string;
+  error?: string;
+} {
   if (!existsSync(mcpJsonPath)) {
-    return false;
+    return { pruned: false, path: mcpJsonPath };
   }
 
   try {
     const parsed = JSON.parse(readFileSync(mcpJsonPath, "utf8")) as AgentMcpFile;
     if (!parsed.mcpServers?.[CONTEXT_MODE_MCP_SERVER_ID]) {
-      return false;
+      return { pruned: false, path: mcpJsonPath };
     }
     delete parsed.mcpServers[CONTEXT_MODE_MCP_SERVER_ID];
     writeFileSync(mcpJsonPath, `${JSON.stringify(parsed, null, 2)}\n`, "utf8");
-    return true;
-  } catch {
-    return false;
+    return { pruned: true, path: mcpJsonPath };
+  } catch (error) {
+    return {
+      pruned: false,
+      path: mcpJsonPath,
+      error: error instanceof Error ? error.message : String(error),
+    };
   }
 }
 
-export function pruneContextModeMcpServerFromAgentConfig(): { pruned: boolean; path: string } {
-  const agentMcpPath = join(getAgentDir(), "mcp.json");
-  const pruned = pruneContextModeFromMcpJsonAt(agentMcpPath);
-  return { pruned, path: agentMcpPath };
+/**
+ * Prune legacy `context-mode` MCP server entry from the agent `mcp.json`.
+ *
+ * @returns prune result
+ */
+export function pruneContextModeMcpServerFromAgentConfig(): {
+  pruned: boolean;
+  path: string;
+  error?: string;
+} {
+  return pruneContextModeFromMcpJsonAt(join(getAgentDir(), "mcp.json"));
 }

package/src/config/resolve.ts

@@ -4,15 +4,18 @@ import {
   type BundledExtensionId,
   type HotmilkConfig,
   type PersonaMode,
+  type ProjectTrustMode,
   type ResolvedDefaults,
   type ResolvedGraphSettings,
   type ResolvedMcpSettings,
+  type ResolvedProjectTrust,
 } from "./hotmilk.ts";
 
 function isPersonaMode(value: unknown): value is PersonaMode {
   return value === "neutral" || value === "gentleman";
 }
 
+/** Resolve final bundled-extension toggles by overlaying user config on bundled defaults. */
 export function resolveBundledExtensionToggles(
   config: HotmilkConfig,
 ): Record<BundledExtensionId, boolean> {
@@ -24,6 +27,7 @@ export function resolveBundledExtensionToggles(
   ) as Record<BundledExtensionId, boolean>;
 }
 
+/** Resolve graphify settings from user config with bundled defaults fallback. */
 export function resolveGraphSettings(config: HotmilkConfig): ResolvedGraphSettings {
   return {
     warnOnStale: config.graph?.warnOnStale ?? DEFAULT_HOTMILK_CONFIG.graph.warnOnStale,
@@ -32,6 +36,7 @@ export function resolveGraphSettings(config: HotmilkConfig): ResolvedGraphSettin
   };
 }
 
+/** Resolve default runtime settings (language, persona) from user config. */
 export function resolveDefaults(config: HotmilkConfig): ResolvedDefaults {
   const language = config.defaults?.language?.trim();
   const persona = config.defaults?.persona;
@@ -41,8 +46,24 @@ export function resolveDefaults(config: HotmilkConfig): ResolvedDefaults {
   };
 }
 
+/** Resolve MCP settings from user config with bundled defaults fallback. */
 export function resolveMcpSettings(config: HotmilkConfig): ResolvedMcpSettings {
   return {
     seedOnStart: config.mcp?.seedOnStart ?? DEFAULT_HOTMILK_CONFIG.mcp.seedOnStart,
   };
 }
+
+function isProjectTrustMode(value: unknown): value is ProjectTrustMode {
+  return value === "delegate" || value === "prompt" || value === "always" || value === "never";
+}
+
+/** Resolve project-trust settings from user config with bundled defaults fallback. */
+export function resolveProjectTrust(config: HotmilkConfig): ResolvedProjectTrust {
+  const mode = config.projectTrust?.mode;
+  const remember = config.projectTrust?.remember;
+  return {
+    mode: isProjectTrustMode(mode) ? mode : DEFAULT_HOTMILK_CONFIG.projectTrust.mode,
+    remember:
+      typeof remember === "boolean" ? remember : DEFAULT_HOTMILK_CONFIG.projectTrust.remember,
+  };
+}

package/src/config/runtime.ts

@@ -6,14 +6,17 @@ import {
   type ResolvedDefaults,
   type ResolvedGraphSettings,
   type ResolvedMcpSettings,
+  type ResolvedProjectTrust,
 } from "./hotmilk.ts";
 import {
   resolveBundledExtensionToggles,
   resolveDefaults,
   resolveGraphSettings,
   resolveMcpSettings,
+  resolveProjectTrust,
 } from "./resolve.ts";
 
+/** Aggregated hotmilk configuration and resolved runtime settings. */
 export type HotmilkRuntime = {
   config: HotmilkConfig;
   configPath: string;
@@ -24,8 +27,10 @@ export type HotmilkRuntime = {
   defaults: ResolvedDefaults;
   graph: ResolvedGraphSettings;
   mcp: ResolvedMcpSettings;
+  projectTrust: ResolvedProjectTrust;
 };
 
+/** Load hotmilk config and resolve all runtime settings into a single object. */
 export function createHotmilkRuntime(configRoot?: string): HotmilkRuntime {
   const loaded = loadHotmilkConfig(configRoot);
   return {
@@ -37,5 +42,6 @@ export function createHotmilkRuntime(configRoot?: string): HotmilkRuntime {
     defaults: resolveDefaults(loaded.config),
     graph: resolveGraphSettings(loaded.config),
     mcp: resolveMcpSettings(loaded.config),
+    projectTrust: resolveProjectTrust(loaded.config),
   };
 }

package/src/controller/input.ts

@@ -1,8 +1,14 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { openModeSettingsModal } from "./mode.ts";
 
+/** Prefix for interrupt commands. */
 const INTERRUPT_PREFIX = "/interrupt ";
 
+/**
+ * Handle /stop command input.
+ *
+ * @param ctx - extension context
+ */
 function handleStopInput(ctx: ExtensionContext): void {
   if (!ctx.isIdle()) {
     ctx.abort();
@@ -12,6 +18,13 @@ function handleStopInput(ctx: ExtensionContext): void {
   ctx.ui.notify("No running work to stop.", "info");
 }
 
+/**
+ * Handle /interrupt command input.
+ *
+ * @param interruptPrompt - interrupt prompt text
+ * @param pi - Pi extension API
+ * @param ctx - extension context
+ */
 function handleInterruptInput(
   interruptPrompt: string,
   pi: ExtensionAPI,
@@ -28,6 +41,7 @@ function handleInterruptInput(
   ctx.ui.notify("Interrupt prompt sent.", "info");
 }
 
+/** Route typed slash commands (`/stop`, `/interrupt`, `/mode`) to their handlers. */
 export function routeInputCommand(text: string, pi: ExtensionAPI, ctx: ExtensionContext): void {
   const normalizedText = text.trim();
   if (normalizedText === "/stop") {
@@ -41,6 +55,7 @@ export function routeInputCommand(text: string, pi: ExtensionAPI, ctx: Extension
   }
 }
 
+/** Register `/stop`, `/interrupt`, and `/mode` as Pi commands. */
 export function registerInputCommands(pi: ExtensionAPI): void {
   pi.registerCommand("stop", {
     description: "Stop current running work.",

package/src/controller/mode.ts

@@ -9,10 +9,22 @@ import {
   saveHotmilkConfig,
 } from "../config/hotmilk.ts";
 
+/**
+ * Format toggle state as "on" or "off".
+ *
+ * @param enabled - toggle state
+ * @returns formatted state
+ */
 function formatToggleState(enabled: boolean): "on" | "off" {
   return enabled ? "on" : "off";
 }
 
+/**
+ * Format toggle rows for notification display.
+ *
+ * @param toggles - extension toggle states
+ * @returns formatted toggle rows
+ */
 function formatToggleRows(toggles: Record<BundledExtensionId, boolean>): string {
   return BUNDLED_EXTENSION_GROUPS.map((group) => {
     const rows = group.ids.map((id) => `  ${id}: ${formatToggleState(toggles[id])}`);
@@ -20,6 +32,12 @@ function formatToggleRows(toggles: Record<BundledExtensionId, boolean>): string
   }).join("\n\n");
 }
 
+/**
+ * Create setting items for the mode settings modal.
+ *
+ * @param toggles - extension toggle states
+ * @returns setting items
+ */
 function createModeSettingItems(toggles: Record<BundledExtensionId, boolean>): SettingItem[] {
   return BUNDLED_EXTENSION_GROUPS.flatMap((group) => [
     {
@@ -36,6 +54,12 @@ function createModeSettingItems(toggles: Record<BundledExtensionId, boolean>): S
   ]);
 }
 
+/**
+ * Notify current config state.
+ *
+ * @param ctx - extension context
+ * @param toggles - extension toggle states
+ */
 function notifyCurrentConfig(
   ctx: ExtensionContext,
   toggles: Record<BundledExtensionId, boolean>,
@@ -43,6 +67,13 @@ function notifyCurrentConfig(
   ctx.ui.notify(`${AGENT_HOTMILK_CONFIG_LABEL}\n${formatToggleRows(toggles)}`, "info");
 }
 
+/**
+ * Save extension toggle state to config.
+ *
+ * @param ctx - extension context
+ * @param extensionId - extension ID
+ * @param enabled - toggle state
+ */
 function saveExtensionToggle(
   ctx: ExtensionContext,
   extensionId: BundledExtensionId,
@@ -58,6 +89,7 @@ function saveExtensionToggle(
   }
 }
 
+/** Open the interactive TUI modal for toggling bundled extensions. */
 export async function openModeSettingsModal(ctx: ExtensionContext): Promise<void> {
   const toggles = loadBundledExtensionToggles();
   const items = createModeSettingItems(toggles);

package/src/index.ts

@@ -12,11 +12,15 @@ import { registerSessionHandlers } from "./bootstrap/session.ts";
 import { registerInputCommands, routeInputCommand } from "./controller/input.ts";
 import { registerHotmilkSessionLogo } from "./ui/session-logo.ts";
 import { installHotmilkCtxSearchCapture } from "./bootstrap/btw.ts";
+import { registerProjectTrustHandlers } from "./bootstrap/project-trust.ts";
 import { registerSubagentsDoctorCommand } from "./bootstrap/subagents-doctor.ts";
 
+/** Main Pi extension entry point: register all hotmilk handlers and bundled extensions. */
 export default async function registerHotmilk(pi: ExtensionAPI): Promise<void> {
   const runtime = createHotmilkRuntime();
 
+  registerProjectTrustHandlers(pi, runtime.projectTrust);
+
   // Register before bundled imports so session_start handlers exist when bindExtensions emits.
   registerHotmilkSessionLogo(pi);
   installHotmilkCtxSearchCapture(pi);
@@ -25,6 +29,7 @@ export default async function registerHotmilk(pi: ExtensionAPI): Promise<void> {
 
   const bundled = await registerBundledExtensions(pi, runtime.extensionToggles, {
     cwd: process.cwd(),
+    includeProjectSettings: false,
   });
   if (runtime.extensionToggles.subagents === true) {
     await registerSubagentsDoctorCommand(pi);