my-pi 0.1.26 → 0.1.28

package/README.md

@@ -15,6 +15,18 @@ presets, local SQLite telemetry for evals, and a programmatic API.
 Extension stacking patterns inspired by
 [pi-vs-claude-code](https://github.com/disler/pi-vs-claude-code).
 
+## What this is for
+
+`my-pi` is a composable Pi-based coding-agent harness for local agent
+work, eval runs, and agent-ops experiments. It is intentionally more
+of a cockpit than a single-purpose assistant: the default CLI combines
+MCP, LSP, skills, prompt presets, secret-safe tooling, local
+telemetry, session recall, and optional team-mode orchestration.
+
+The main design goal is repeatability: run an agent task, capture
+structured telemetry, preserve session context, and reuse the same
+configuration in interactive, print, JSON, RPC, or SDK-driven flows.
+
 ## Not a Pi package
 
 Do not install this with `pi install npm:my-pi`.
@@ -44,6 +56,22 @@ directly as its own CLI.
 - **Bundled themes + extension stacking** — ship defaults, then layer
   extra project or ad-hoc extensions on top.
 
+## Requirements
+
+- **Node.js `>=24.15.0` minimum.** my-pi uses native `node:sqlite`
+  through the context sidecar and telemetry packages, and uses Node's
+  built-in TypeScript type stripping for small local scripts.
+- **Node 24 is used in CI.** `node:sqlite` is a release-candidate Node
+  API line, so CI runs both the minimum supported Node 24 release and
+  the current Node 24 line while the code keeps SQLite usage small and
+  synchronous.
+- **SQLite warning policy:** the `my-pi` CLI suppresses Node's
+  expected `node:sqlite` `ExperimentalWarning` before built-ins load.
+  Standalone package/API consumers own their process warning policy
+  until Node marks `node:sqlite` stable.
+- **pnpm 10** is used for local development. End users can run with
+  `pnpx`, `npx`, or `bunx`.
+
 ## Get Started
 
 ```bash
@@ -51,6 +79,13 @@ pnpx my-pi@latest
 # or: npx my-pi@latest / bunx my-pi@latest
 ```
 
+With pnpm 10's build-script approval gate, use explicit build
+allowances if you want a warning-free `pnpx` install:
+
+```bash
+pnpm dlx --allow-build=@google/genai --allow-build=koffi --allow-build=protobufjs my-pi@latest
+```
+
 ### API Keys
 
 Pi handles authentication natively via `AuthStorage`. Options (in
@@ -137,7 +172,9 @@ Team state is stored under `~/.pi/agent/teams-local` by default, or
 Telemetry is **disabled by default**. When enabled, my-pi records
 operational telemetry for each run in a local SQLite database. This is
 intended for eval harnesses, latency analysis, tool failure analysis,
-and local debugging.
+and local debugging. Telemetry captures structured operational data;
+`pirecall` complements it by retrieving the surrounding session
+transcript and prior-work context.
 
 ```bash
 pnpx my-pi@latest --telemetry --json "solve this task"
@@ -182,6 +219,66 @@ Recommended eval env vars for correlation:
 - `MY_PI_EVAL_ATTEMPT`
 - `MY_PI_EVAL_SUITE`
 
+A typical eval loop is:
+
+1. Create a stable eval run/case id.
+2. Run my-pi with `--telemetry`, usually with an isolated
+   `PI_CODING_AGENT_DIR` and `--untrusted` for reproducibility.
+3. Query or export telemetry for timings, tool calls, provider
+   requests, and success/failure state.
+4. Use `pirecall` to inspect the transcript context around the same
+   task when the structured rows are not enough.
+5. Compare attempts by `MY_PI_EVAL_RUN_ID`, `MY_PI_EVAL_CASE_ID`,
+   `MY_PI_EVAL_ATTEMPT`, and `MY_PI_EVAL_SUITE`.
+
+Example:
+
+```bash
+export MY_PI_EVAL_RUN_ID="smoke-$(date +%Y%m%d-%H%M%S)"
+export MY_PI_EVAL_CASE_ID="readme-review"
+export MY_PI_EVAL_ATTEMPT=1
+export MY_PI_EVAL_SUITE="smoke"
+
+PI_CODING_AGENT_DIR="$PWD/.tmp/pi-agent" \
+  pnpx my-pi@latest \
+  --untrusted \
+  --telemetry \
+  --telemetry-db "$PWD/.tmp/evals.db" \
+  --json "review the README and report the top issue"
+
+pnpx pirecall sync --json
+pnpx pirecall recall "readme-review smoke" --json
+```
+
+For repeatable local cases after `pnpm run build`, use the TypeScript
+wrapper script:
+
+```bash
+pnpm run eval:local -- \
+  --suite smoke \
+  --case readme-review \
+  --prompt "review the README and report the top issue"
+```
+
+It sets `MY_PI_EVAL_*`, uses an isolated `.tmp/pi-agent`, writes
+telemetry to `.tmp/evals.db`, and passes `--untrusted` by default. Add
+extra my-pi flags after `--`, for example `-- --model openai:gpt-5`.
+
+For assertion-backed regression gates, run the committed smoke suite
+after `pnpm run build`:
+
+```bash
+pnpm run eval:suite
+pnpm run eval:suite -- --case no-mcp-removes-mcp-tools
+pnpm run eval:suite -- --json
+```
+
+Suites live in `evals/*.json`. Each case declares a command plus
+objective assertions for exit code and expected/forbidden stdout,
+stderr, or combined output. Cases can declare required environment
+variable names; missing values are reported as skips without printing
+secret values.
+
 Recorded tables:
 
 - `runs`
@@ -189,6 +286,11 @@ Recorded tables:
 - `tool_calls`
 - `provider_requests`
 
+A telemetry export is JSON with one object per run and nested
+summaries for turns, tool calls, and provider requests, keyed by
+run/eval ids so it can be compared with the matching `pirecall`
+transcript.
+
 Query and export helpers:
 
 - `/telemetry query ...` shows recent run summaries
@@ -295,7 +397,10 @@ built-in extensions.
 
 Built-in extension choices can also be saved interactively with
 `/extensions`. Startup flags like `--no-recall` and `--no-skills`
-still force-disable those extensions for the current process only.
+still force-disable those extensions for the current process only. The
+built-in registry in `src/extensions/builtin-registry.ts` is the
+source of truth for built-in order, API option names, disable flags,
+labels, and runtime-mode constraints.
 
 ### Themes
 
@@ -493,8 +598,17 @@ In interactive mode:
 
 The filter-output extension automatically redacts secrets (API keys,
 tokens, passwords, private keys) from tool output before the LLM sees
-them. Detection patterns from
-[nopeek](https://github.com/spences10/nopeek).
+them. Detection patterns come from
+[nopeek](https://github.com/spences10/nopeek). This is a defensive
+last-mile guard, not a substitute for secret hygiene: prefer `nopeek`
+for loading credentials and avoid printing secrets in the first place.
+
+The redactor intentionally errs on the side of caution, which means it
+can occasionally hide benign metadata such as URLs or documentation
+examples. If that happens in a trusted local context, inspect the file
+directly or temporarily run with `--no-filter`; do not disable the
+filter when reading unknown logs, `.env` files, or untrusted command
+output.
 
 Use `/redact-stats` to see how many secrets were caught. Disable with
 `--no-filter`.
@@ -666,6 +780,18 @@ pi install npm:@spences10/pi-themes
 Each package README is the entry point for install instructions,
 commands, runtime behavior, and development notes.
 
+## Monorepo build model
+
+Workspace package ordering comes from `workspace:*` dependencies in
+each `packages/*/package.json`. Root `build`, `check`, and `test`
+first run package `build:self` scripts through pnpm's filtered
+workspace graph, so sibling `dist` output is fresh before root packing
+or tests. Individual package `build`, `check`, and `test` scripts use
+the package name from `$npm_package_name^...` to build transitive
+workspace dependencies from metadata, then run their local `*:self`
+task. Do not hand-code sibling package names into scripts; add the
+dependency to `dependencies` instead.
+
 ## Project Structure
 
 ```
@@ -673,6 +799,7 @@ src/
   index.ts                 CLI entry point (citty + pi SDK)
   api.ts                   Programmatic API (create_my_pi + re-exports)
   extensions/
+    builtin-registry.ts    Built-in extension metadata, ordering, flags, and loaders
     manager/               Built-in extension manager and config
     prompt-presets/        Runtime prompt preset selection and editing
     session-name/          Session auto-naming

package/dist/api.d.ts

@@ -1,33 +1,210 @@
 import { Api, Model } from "@mariozechner/pi-ai";
 import * as _$_mariozechner_pi_coding_agent0 from "@mariozechner/pi-coding-agent";
-import { AgentSessionRuntime, CreateAgentSessionFromServicesOptions, ExtensionFactory, ExtensionFactory as ExtensionFactory$1, InteractiveMode, InteractiveModeOptions, PrintModeOptions, runPrintMode, runRpcMode } from "@mariozechner/pi-coding-agent";
+import { AgentSessionRuntime, CreateAgentSessionFromServicesOptions, ExtensionAPI, ExtensionFactory, ExtensionFactory as ExtensionFactory$1, InteractiveMode, InteractiveModeOptions, PrintModeOptions, runPrintMode, runRpcMode } from "@mariozechner/pi-coding-agent";
+import * as _$_spences10_pi_context0 from "@spences10/pi-context";
+import * as _$_spences10_pi_mcp0 from "@spences10/pi-mcp";
+import * as _$_spences10_pi_skills0 from "@spences10/pi-skills";
+import * as _$_spences10_pi_redact0 from "@spences10/pi-redact";
+import * as _$_spences10_pi_recall0 from "@spences10/pi-recall";
+import * as _$_spences10_pi_nopeek0 from "@spences10/pi-nopeek";
+import * as _$_spences10_pi_omnisearch0 from "@spences10/pi-omnisearch";
+import * as _$_spences10_pi_sqlite_tools0 from "@spences10/pi-sqlite-tools";
+import * as _$_spences10_pi_confirm_destructive0 from "@spences10/pi-confirm-destructive";
+import * as _$_spences10_pi_team_mode0 from "@spences10/pi-team-mode";
 
-//#region src/extensions/manager/config.d.ts
-type BuiltinExtensionKey = 'context-sidecar' | 'mcp' | 'skills' | 'filter-output' | 'recall' | 'nopeek' | 'omnisearch' | 'sqlite-tools' | 'prompt-presets' | 'lsp' | 'session-name' | 'confirm-destructive' | 'hooks-resolution' | 'team-mode';
+//#region src/extensions/prompt-presets/index.d.ts
+declare function prompt_presets(pi: ExtensionAPI): Promise<void>;
+//#endregion
+//#region src/extensions/session-name/index.d.ts
+declare function session_name(pi: ExtensionAPI): Promise<void>;
+//#endregion
+//#region src/extensions/builtin-registry.d.ts
+declare const BUILTIN_EXTENSION_REGISTRY: readonly [{
+  readonly key: "context-sidecar";
+  readonly label: "Context sidecar";
+  readonly docs_label: "SQLite context sidecar";
+  readonly description: "Local SQLite FTS sidecar for oversized tool output";
+  readonly default_enabled: true;
+  readonly option_name: "context_sidecar";
+  readonly cli_arg: "no-context-sidecar";
+  readonly cli_flag: "--no-context-sidecar";
+  readonly cli_description: "Disable SQLite context sidecar for large tool output";
+  readonly aliases: readonly ["context-sidecar", "context", "sidecar"];
+  readonly load: () => Promise<typeof _$_spences10_pi_context0.default>;
+}, {
+  readonly key: "mcp";
+  readonly label: "MCP";
+  readonly docs_label: "MCP";
+  readonly description: "MCP server integration and /mcp command";
+  readonly default_enabled: true;
+  readonly option_name: "mcp";
+  readonly cli_arg: "no-mcp";
+  readonly cli_flag: "--no-mcp";
+  readonly cli_description: "Disable built-in MCP extension";
+  readonly aliases: readonly ["mcp"];
+  readonly load: () => Promise<typeof _$_spences10_pi_mcp0.default>;
+}, {
+  readonly key: "skills";
+  readonly label: "Skills";
+  readonly docs_label: "Skills";
+  readonly description: "Managed pi-native skills and /skills command";
+  readonly default_enabled: true;
+  readonly option_name: "skills";
+  readonly cli_arg: "no-skills";
+  readonly cli_flag: "--no-skills";
+  readonly cli_description: "Disable built-in skills extension";
+  readonly aliases: readonly ["skills", "skill"];
+  readonly load: () => Promise<typeof _$_spences10_pi_skills0.default>;
+}, {
+  readonly key: "filter-output";
+  readonly label: "Filter output";
+  readonly docs_label: "Output filtering";
+  readonly description: "Secret redaction for tool output";
+  readonly default_enabled: true;
+  readonly option_name: "filter_output";
+  readonly cli_arg: "no-filter";
+  readonly cli_flag: "--no-filter";
+  readonly cli_description: "Disable secret redaction in tool output";
+  readonly aliases: readonly ["filter-output", "filter_output", "filter", "redaction"];
+  readonly load: () => Promise<typeof _$_spences10_pi_redact0.default>;
+}, {
+  readonly key: "recall";
+  readonly label: "Recall";
+  readonly docs_label: "Recall";
+  readonly description: "pirecall reminder and background session sync";
+  readonly default_enabled: true;
+  readonly option_name: "recall";
+  readonly cli_arg: "no-recall";
+  readonly cli_flag: "--no-recall";
+  readonly cli_description: "Disable recall extension";
+  readonly aliases: readonly ["recall", "pirecall"];
+  readonly load: () => Promise<typeof _$_spences10_pi_recall0.default>;
+}, {
+  readonly key: "nopeek";
+  readonly label: "Nopeek";
+  readonly docs_label: "Nopeek";
+  readonly description: "nopeek reminder for secret-safe environment loading";
+  readonly default_enabled: true;
+  readonly option_name: "nopeek";
+  readonly cli_arg: "no-nopeek";
+  readonly cli_flag: "--no-nopeek";
+  readonly cli_description: "Disable nopeek reminder extension";
+  readonly aliases: readonly ["nopeek", "secrets", "secret-loading"];
+  readonly load: () => Promise<typeof _$_spences10_pi_nopeek0.default>;
+}, {
+  readonly key: "omnisearch";
+  readonly label: "Omnisearch";
+  readonly docs_label: "Omnisearch";
+  readonly description: "mcp-omnisearch reminder for verified web research";
+  readonly default_enabled: true;
+  readonly option_name: "omnisearch";
+  readonly cli_arg: "no-omnisearch";
+  readonly cli_flag: "--no-omnisearch";
+  readonly cli_description: "Disable mcp-omnisearch reminder extension";
+  readonly aliases: readonly ["omnisearch", "search", "web-search", "research"];
+  readonly load: () => Promise<typeof _$_spences10_pi_omnisearch0.default>;
+}, {
+  readonly key: "sqlite-tools";
+  readonly label: "SQLite tools";
+  readonly docs_label: "SQLite tools";
+  readonly description: "mcp-sqlite-tools reminder for safer SQLite database work";
+  readonly default_enabled: true;
+  readonly option_name: "sqlite_tools";
+  readonly cli_arg: "no-sqlite-tools";
+  readonly cli_flag: "--no-sqlite-tools";
+  readonly cli_description: "Disable mcp-sqlite-tools reminder extension";
+  readonly aliases: readonly ["sqlite-tools", "sqlite", "mcp-sqlite-tools"];
+  readonly load: () => Promise<typeof _$_spences10_pi_sqlite_tools0.default>;
+}, {
+  readonly key: "prompt-presets";
+  readonly label: "Prompt presets";
+  readonly docs_label: "Prompt presets";
+  readonly description: "Runtime prompt preset selection and /prompt-preset command";
+  readonly default_enabled: true;
+  readonly option_name: "prompt_presets";
+  readonly cli_arg: "no-prompt-presets";
+  readonly cli_flag: "--no-prompt-presets";
+  readonly cli_description: "Disable prompt presets extension";
+  readonly aliases: readonly ["prompt-presets", "prompt-preset", "preset", "presets"];
+  readonly load: () => Promise<typeof prompt_presets>;
+}, {
+  readonly key: "lsp";
+  readonly label: "LSP";
+  readonly docs_label: "LSP";
+  readonly description: "Language Server Protocol tools (diagnostics, hover, definition, references)";
+  readonly default_enabled: true;
+  readonly option_name: "lsp";
+  readonly cli_arg: "no-lsp";
+  readonly cli_flag: "--no-lsp";
+  readonly cli_description: "Disable LSP extension";
+  readonly aliases: readonly ["lsp", "language-server"];
+  readonly load: () => Promise<(pi: _$_mariozechner_pi_coding_agent0.ExtensionAPI) => Promise<void>>;
+}, {
+  readonly key: "session-name";
+  readonly label: "Session name";
+  readonly docs_label: "Session auto-naming";
+  readonly description: "AI-powered session auto-naming and /session-name command";
+  readonly default_enabled: true;
+  readonly option_name: "session_name";
+  readonly cli_arg: "no-session-name";
+  readonly cli_flag: "--no-session-name";
+  readonly cli_description: "Disable session name extension";
+  readonly aliases: readonly ["session-name", "session", "auto-name"];
+  readonly mode_constraints: {
+    readonly disabled_in: readonly ["print", "json", "rpc"];
+    readonly reason: "UI-only session naming is only useful in interactive mode";
+  };
+  readonly load: () => Promise<typeof session_name>;
+}, {
+  readonly key: "confirm-destructive";
+  readonly label: "Confirm destructive";
+  readonly docs_label: "Destructive action confirmation";
+  readonly description: "Prompt before destructive tool calls like file deletes, overwrites, and hard resets";
+  readonly default_enabled: true;
+  readonly option_name: "confirm_destructive";
+  readonly cli_arg: "no-confirm-destructive";
+  readonly cli_flag: "--no-confirm-destructive";
+  readonly cli_description: "Disable destructive action confirmations";
+  readonly aliases: readonly ["confirm-destructive", "confirm"];
+  readonly load: () => Promise<typeof _$_spences10_pi_confirm_destructive0.default>;
+}, {
+  readonly key: "hooks-resolution";
+  readonly label: "Hooks resolution";
+  readonly docs_label: "Hooks resolution";
+  readonly description: "Claude Code style PostToolUse hook compatibility from .claude, .rulesync, and .pi configs";
+  readonly default_enabled: true;
+  readonly option_name: "hooks_resolution";
+  readonly cli_arg: "no-hooks";
+  readonly cli_flag: "--no-hooks";
+  readonly cli_description: "Disable Claude-style hook execution";
+  readonly aliases: readonly ["hooks-resolution", "hooks"];
+  readonly load: () => Promise<ExtensionFactory$1>;
+}, {
+  readonly key: "team-mode";
+  readonly label: "Team mode";
+  readonly docs_label: "Team mode";
+  readonly description: "Experimental orchestrator/team mode with RPC teammates, tasks, and mailboxes";
+  readonly default_enabled: true;
+  readonly option_name: "team_mode";
+  readonly cli_arg: "no-team-mode";
+  readonly cli_flag: "--no-team-mode";
+  readonly cli_description: "Disable experimental team mode extension";
+  readonly aliases: readonly ["team-mode", "team", "teammates"];
+  readonly load: () => Promise<typeof _$_spences10_pi_team_mode0.default>;
+}];
+type BuiltinExtensionKey = (typeof BUILTIN_EXTENSION_REGISTRY)[number]['key'];
+type BuiltinExtensionOptionName = (typeof BUILTIN_EXTENSION_REGISTRY)[number]['option_name'];
 //#endregion
 //#region src/api.d.ts
 type MyPiRuntimeMode = 'interactive' | 'print' | 'json' | 'rpc';
 type MyPiThinkingLevel = NonNullable<CreateAgentSessionFromServicesOptions['thinkingLevel']>;
-interface CreateMyPiOptions {
+type BuiltinExtensionOptions = Partial<Record<BuiltinExtensionOptionName, boolean>>;
+interface CreateMyPiOptions extends BuiltinExtensionOptions {
   cwd?: string;
   agent_dir?: string;
   extensions?: string[];
   extensionFactories?: ExtensionFactory$1[];
   runtime_mode?: MyPiRuntimeMode;
-  context_sidecar?: boolean;
-  mcp?: boolean;
-  skills?: boolean;
-  filter_output?: boolean;
-  recall?: boolean;
-  nopeek?: boolean;
-  omnisearch?: boolean;
-  sqlite_tools?: boolean;
-  prompt_presets?: boolean;
-  lsp?: boolean;
-  session_name?: boolean;
-  confirm_destructive?: boolean;
-  hooks_resolution?: boolean;
-  team_mode?: boolean;
   telemetry?: boolean;
   telemetry_db_path?: string;
   model?: string;
@@ -39,6 +216,7 @@ interface CreateMyPiOptions {
   append_system_prompt?: string;
   untrusted_repo?: boolean;
 }
+type BuiltinExtensionLoader = () => Promise<ExtensionFactory$1>;
 declare function apply_untrusted_repo_defaults(env?: NodeJS.ProcessEnv): string[];
 declare function is_project_local_skill_path(cwd: string, file_path: string | undefined): boolean;
 interface ModelRegistryLike {
@@ -46,8 +224,9 @@ interface ModelRegistryLike {
 }
 declare function resolve_model_reference(model_reference: string | undefined, model_registry: ModelRegistryLike): Model<Api> | undefined;
 declare function resolve_effective_thinking_level(model: Model<Api> | undefined, thinking: MyPiThinkingLevel | undefined): MyPiThinkingLevel | undefined;
-declare function get_force_disabled_builtins(options: Pick<CreateMyPiOptions, 'runtime_mode' | 'context_sidecar' | 'mcp' | 'skills' | 'filter_output' | 'recall' | 'nopeek' | 'omnisearch' | 'sqlite_tools' | 'prompt_presets' | 'lsp' | 'session_name' | 'confirm_destructive' | 'hooks_resolution' | 'team_mode'>): ReadonlySet<BuiltinExtensionKey>;
+declare function get_force_disabled_builtins(options: Pick<CreateMyPiOptions, 'runtime_mode'> & BuiltinExtensionOptions): ReadonlySet<BuiltinExtensionKey>;
+declare function create_lazy_builtin_extension_factory(key: BuiltinExtensionKey, load_extension: BuiltinExtensionLoader, force_disabled: ReadonlySet<BuiltinExtensionKey>): ExtensionFactory$1;
 declare function create_my_pi(options?: CreateMyPiOptions): Promise<_$_mariozechner_pi_coding_agent0.AgentSessionRuntime>;
 //#endregion
-export { type AgentSessionRuntime, CreateMyPiOptions, type ExtensionFactory, InteractiveMode, type InteractiveModeOptions, MyPiRuntimeMode, MyPiThinkingLevel, type PrintModeOptions, apply_untrusted_repo_defaults, create_my_pi, get_force_disabled_builtins, is_project_local_skill_path, resolve_effective_thinking_level, resolve_model_reference, runPrintMode, runRpcMode };
+export { type AgentSessionRuntime, CreateMyPiOptions, type ExtensionFactory, InteractiveMode, type InteractiveModeOptions, MyPiRuntimeMode, MyPiThinkingLevel, type PrintModeOptions, apply_untrusted_repo_defaults, create_lazy_builtin_extension_factory, create_my_pi, get_force_disabled_builtins, is_project_local_skill_path, resolve_effective_thinking_level, resolve_model_reference, runPrintMode, runRpcMode };
 //# sourceMappingURL=api.d.ts.map