@statista-oss/pi-beans 0.1.1

package/README.md

@@ -0,0 +1,127 @@
+# pi-beans
+
+A small [pi](https://github.com/badlogic/pi-mono) extension that gives the
+coding agent first-class access to [Beans](https://github.com/hmans/beans),
+an issue tracker that lives next to your code. The agent can list open work,
+read a bean before starting on it, and record progress as it goes — all
+through the existing `beans` CLI, with no extra config and no parsing of
+`.beans/*.md` on our side.
+
+## Prerequisites
+
+At runtime the extension expects:
+
+1. The `beans` binary to be on `PATH`.
+2. A `.beans.yml` file in the current working directory or any parent
+   (i.e. `beans init` has been run for the project).
+
+If either is missing the extension stays loaded but disables all of its
+tools and slash commands, and prints a single notice on session start. It
+will not crash pi.
+
+## Install / activation
+
+Install with this command:
+
+```bash
+pi install -l npm:@statista-oss/pi-beans@0.1.0
+```
+
+You can keep the extension permanently enabled in your shell alias if you
+want; it no-ops in projects without a `.beans.yml`.
+
+On `session_start` the extension runs `beans prime` once and injects its
+output into the system prompt (refreshed again on `session_before_compact`
+so it survives compaction).
+
+## Tools
+
+Registered only when the prerequisites above are met. All output is
+truncated through pi's standard `truncateHead` (50KB / 2000 lines) and
+non-zero exits are surfaced to the LLM as errors with stderr included.
+
+| Tool           | Parameters                                         | Description                                                                                              |
+| -------------- | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| `beans_list`   | `status?`, `include_archived?`, `query?`           | List beans (open by default).                                                                            |
+| `beans_show`   | `id`                                               | Show one bean's full markdown + metadata.                                                                |
+| `beans_create` | `title`, `body?`, `status?`                        | Create a new bean. Long bodies go via a temp file.                                                       |
+| `beans_update` | `id`, `status?`, `title?`, `body?`, `body_append?` | Update fields. `body` and `body_append` are mutually exclusive; at least one mutating field is required. |
+
+`beans_update` serializes its read-modify-write window through pi's
+`withFileMutationQueue` keyed on the bean's markdown file, so it interleaves
+correctly with built-in `edit` / `write`.
+
+## Slash commands
+
+Two thin commands for the human in the loop. They shell out directly and do
+not call the LLM.
+
+- `/beans` — runs `beans list` and shows the result via `ctx.ui.notify`.
+- `/bean <id>` — runs `beans show <id>` and pastes the result into the
+  editor as context for your next message.
+
+When the prerequisites are not met both commands print a clear
+`beans not configured` message instead.
+
+## Footer status line
+
+When the extension is active the footer shows a single line like:
+
+```
+beans: 12 open
+```
+
+The count is parsed best-effort from `beans list` on session start. It is
+cleared on `session_shutdown` and is intentionally not refreshed after every
+tool call (beans rarely change that fast; the agent can re-list explicitly).
+
+## Troubleshooting
+
+**`beans: binary not found on PATH`** — install the `beans` CLI and make
+sure `beans --version` works in the same shell you launch pi from. Tools
+will stay disabled until then.
+
+**`beans: no .beans.yml found`** — run `beans init` in your project root,
+or `cd` into a directory that has one above it. The extension walks up
+from the current directory looking for `.beans.yml`; the directory
+containing it is treated as the project root for every command.
+
+**`beans prime failed`** — the extension logs this to the status line and
+continues with tools enabled but without the prime injection. Run
+`beans prime` manually to see the underlying error; common causes are a
+corrupted `.beans/` directory or a CLI version mismatch.
+
+**A tool call returns a CLI error verbatim** — that is intentional. The
+extension forwards `beans`' own stderr (e.g. unknown bean ID, invalid
+status) so the LLM can react to it directly.
+
+## Releasing
+
+This repo uses [Changesets](https://github.com/changesets/changesets) for
+versioning and publishing to npm.
+
+1. After making user-facing changes, add a changeset:
+
+   ```bash
+   pnpm changeset
+   ```
+
+   Pick a bump type (`patch`, `minor`, `major`) and write a short summary.
+   Commit the generated `.changeset/*.md` file alongside your change.
+
+2. When changesets land on `main`, the `Release` GitHub Actions workflow
+   opens (or updates) a “Version Packages” PR that bumps the version and
+   updates `CHANGELOG.md`.
+
+3. Merging that PR triggers the same workflow to run `pnpm release`
+   (`changeset publish`), which publishes to npm and pushes the git tag.
+
+A repository secret `NPM_TOKEN` with publish rights is required for the
+publish step. The workflow requests `id-token: write` so npm provenance is
+attached automatically.
+
+## Status
+
+v1. No `archive` / `delete` tools, no GraphQL tool, no autocomplete, no
+custom config flags. See [`SPEC.md`](./SPEC.md) for the full design and the
+explicit out-of-scope list.

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@statista-oss/pi-beans",
+  "version": "0.1.1",
+  "description": "pi extension that integrates the Beans CLI into the coding agent.",
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "type": "module",
+  "main": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^2.31.0",
+    "@mariozechner/pi-ai": "^0.73.0",
+    "@mariozechner/pi-coding-agent": "^0.73.0",
+    "@mariozechner/pi-tui": "^0.73.0",
+    "@types/node": "^25.6.0",
+    "oxfmt": "^0.48.0",
+    "oxlint": "^1.63.0",
+    "oxlint-tsgolint": "^0.22.1",
+    "typebox": "^1.1.38",
+    "typescript": "^6.0.0",
+    "node": "runtime:^24"
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*"
+  },
+  "devEngines": {
+    "runtime": {
+      "name": "node",
+      "version": "^24",
+      "onFail": "download"
+    }
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "scripts": {
+    "start": "pi -e ./src/index.ts",
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint",
+    "fmt": "oxfmt",
+    "fmt:check": "oxfmt --check",
+    "changeset": "changeset",
+    "version": "changeset version",
+    "release": "changeset publish"
+  }
+}

package/src/commands.ts

@@ -0,0 +1,126 @@
+/**
+ * Track D — slash commands and footer status line for pi-beans.
+ *
+ * Registers two user-facing slash commands and maintains a small footer
+ * status entry that reflects the number of currently open beans. All work
+ * goes through the shared accessors in `./internal.js`, so this module has
+ * no direct dependency on Track A's implementation file.
+ *
+ * Commands:
+ *   /beans          — list open beans (notification).
+ *   /bean <id>      — show one bean and paste its content into the editor.
+ *
+ * Status line:
+ *   key "beans" — "beans: N open" when available, "beans: ?" on error,
+ *   cleared when beans is unavailable or the session shuts down.
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import { beansEvents, getEnv, getRunner } from "./internal.js";
+
+/**
+ * Wire up Track D into the given pi extension API.
+ *
+ * Safe to call exactly once per extension load. Subscribes to a few pi and
+ * beans events to keep the footer status entry in sync.
+ */
+export function registerCommands(pi: ExtensionAPI): void {
+  // Cache the most recent ExtensionContext so beans event listeners (which
+  // fire outside of a pi event handler) can still reach ctx.ui.setStatus.
+  let lastCtx: ExtensionContext | undefined;
+
+  pi.registerCommand("beans", {
+    description: "List open beans",
+    handler: async (_args, ctx) => {
+      const env = getEnv();
+      const runner = getRunner();
+      if (!env.available || !runner) {
+        ctx.ui.notify("beans not configured", "warning");
+        return;
+      }
+      try {
+        const out = await runner.run(["list"]);
+        ctx.ui.notify(out.trim() || "(no beans)", "info");
+      } catch (e) {
+        ctx.ui.notify(`beans list failed: ${(e as Error).message}`, "error");
+      }
+    },
+  });
+
+  pi.registerCommand("bean", {
+    description: "Show a bean and paste it into the editor",
+    handler: async (args, ctx) => {
+      const id = args.trim();
+      if (!id) {
+        ctx.ui.notify("usage: /bean <id>", "warning");
+        return;
+      }
+      const env = getEnv();
+      const runner = getRunner();
+      if (!env.available || !runner) {
+        ctx.ui.notify("beans not configured", "warning");
+        return;
+      }
+      try {
+        const out = await runner.run(["show", id]);
+        ctx.ui.pasteToEditor(out);
+      } catch (e) {
+        ctx.ui.notify(`beans show failed: ${(e as Error).message}`, "error");
+      }
+    },
+  });
+
+  /**
+   * Refresh the "beans" footer entry from the current env + runner.
+   *
+   * Counts open beans (excluding completed and scrapped) by running
+   * `beans list --json --no-status completed --no-status scrapped` and
+   * measuring the length of the returned JSON array — exact and format-independent.
+   */
+  async function refreshStatus(ctx: ExtensionContext): Promise<void> {
+    const env = getEnv();
+    const runner = getRunner();
+    if (!env.available || !runner) {
+      ctx.ui.setStatus("beans", undefined);
+      return;
+    }
+    try {
+      const out = await runner.run([
+        "list",
+        "--json",
+        "--no-status",
+        "completed",
+        "--no-status",
+        "scrapped",
+      ]);
+      const raw: unknown = JSON.parse(out);
+      // The CLI returns `null` (not `[]`) when no beans match the filter.
+      const parsed: unknown = raw === null ? [] : raw;
+      if (!Array.isArray(parsed)) throw new Error("beans list --json: expected array");
+      const count = parsed.length;
+      ctx.ui.setStatus("beans", ctx.ui.theme.fg("dim", `beans: ${count} open`));
+    } catch {
+      ctx.ui.setStatus("beans", ctx.ui.theme.fg("warning", "beans: ?"));
+    }
+  }
+
+  pi.on("session_start", (_e, ctx) => {
+    lastCtx = ctx;
+    // env_ready fires from Track A inside session_start; we also kick off
+    // an initial refresh so the footer reflects whatever state is cached.
+    void refreshStatus(ctx);
+  });
+
+  beansEvents.on("env_ready", () => {
+    if (lastCtx) void refreshStatus(lastCtx);
+  });
+
+  beansEvents.on("beans_mutated", () => {
+    if (lastCtx) void refreshStatus(lastCtx);
+  });
+
+  pi.on("session_shutdown", (_e, ctx) => {
+    ctx.ui.setStatus("beans", undefined);
+    lastCtx = undefined;
+  });
+}

package/src/env.ts

@@ -0,0 +1,187 @@
+/**
+ * Track A — Environment detection, runner, and lifecycle wiring.
+ *
+ * This module is the only place that touches the host filesystem to find the
+ * `beans` binary and the project's `.beans.yml`. Other tracks talk to it
+ * exclusively through the contracts in `./internal.ts` (events + cached state).
+ */
+
+import { constants as fsConstants } from "node:fs";
+import { access, stat } from "node:fs/promises";
+import { delimiter, dirname, isAbsolute, join, parse, resolve } from "node:path";
+
+import type { ExecOptions, ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+import {
+  beansEvents,
+  getEnv,
+  setEnv,
+  type BeansEnv,
+  type BeansRunOptions,
+  type BeansRunner,
+} from "./internal.js";
+
+/** Default per-call timeout for `beans` invocations (ms). */
+const DEFAULT_TIMEOUT_MS = 15_000;
+
+/** `pi.exec`-shaped function we use here and in `createRunner`. */
+type ExecFn = (
+  command: string,
+  args: string[],
+  options?: ExecOptions,
+) => Promise<{ stdout: string; stderr: string; code: number; killed: boolean }>;
+
+/**
+ * Detect whether beans is usable from `cwd`.
+ *
+ * Walks up the directory tree from `cwd` looking for `.beans.yml`; the
+ * directory containing it becomes the project root used for every CLI call.
+ * Then resolves the `beans` binary on `PATH` (honoring `PATHEXT` on Windows).
+ *
+ * Never throws — returns `{ available: false, reason }` on any failure.
+ */
+export async function detectBeansEnv(cwd: string): Promise<BeansEnv> {
+  const projectRoot = await findProjectRoot(cwd);
+  if (!projectRoot) {
+    return { available: false, reason: `no .beans.yml found above ${cwd}`, cwd, binary: "" };
+  }
+
+  const binary = await resolveBeansBinary();
+  if (!binary) {
+    return {
+      available: false,
+      reason: "`beans` binary not found on PATH",
+      cwd: projectRoot,
+      binary: "",
+    };
+  }
+
+  return { available: true, cwd: projectRoot, binary };
+}
+
+/**
+ * Build a {@link BeansRunner} bound to a detected env.
+ *
+ * The runner forwards to `exec(env.binary, args, { cwd, signal, timeout })`,
+ * defaults `cwd` to `env.cwd` and `timeout` to {@link DEFAULT_TIMEOUT_MS}, and
+ * throws an Error on non-zero exit (with stderr — or stdout if stderr is
+ * empty — in the message).
+ */
+export function createRunner(env: BeansEnv, exec: ExecFn): BeansRunner {
+  return {
+    async run(args: string[], opts?: BeansRunOptions): Promise<string> {
+      const result = await exec(env.binary, args, {
+        cwd: opts?.cwd ?? env.cwd,
+        signal: opts?.signal,
+        timeout: opts?.timeout ?? DEFAULT_TIMEOUT_MS,
+      });
+      if (result.code !== 0) {
+        const detail = result.stderr.trim() || result.stdout.trim();
+        throw new Error(`beans ${args.join(" ")} failed (exit ${result.code}): ${detail}`);
+      }
+      return result.stdout;
+    },
+  };
+}
+
+/**
+ * Wire env detection and lifecycle hooks into the extension API.
+ *
+ * - `session_start`: detect env, build runner, publish via `setEnv` (which
+ *   emits `env_ready`). On failure, surface a single warning notice. Track B
+ *   subscribes to `env_ready` itself to run `beans prime`.
+ * - `session_before_compact`: re-emit `env_ready` so Track B treats it as a
+ *   refresh signal and re-injects the prime output post-compaction. Track A
+ *   intentionally doesn't import Track B directly to keep tracks decoupled.
+ * - `session_shutdown`: clear our footer status and emit `shutdown` so other
+ *   tracks can release any per-session state.
+ */
+export function registerEnv(pi: ExtensionAPI): void {
+  pi.on("session_start", async (_event, ctx) => {
+    const env = await detectBeansEnv(ctx.cwd);
+    const runner = env.available ? createRunner(env, (...args) => pi.exec(...args)) : undefined;
+    setEnv(env, runner);
+    if (!env.available && env.reason) {
+      ctx.ui.notify(`pi-beans: ${env.reason}`, "warning");
+    }
+  });
+
+  pi.on("session_before_compact", async () => {
+    // Track B owns prime. We just re-emit env_ready so it refreshes its cache
+    // before the compacted system prompt is built.
+    beansEvents.emit("env_ready", getEnv());
+  });
+
+  pi.on("session_shutdown", (_event, ctx) => {
+    ctx.ui.setStatus("beans", undefined);
+    beansEvents.emit("shutdown");
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Walk up from `cwd` until a directory containing `.beans.yml` is found. */
+async function findProjectRoot(cwd: string): Promise<string | undefined> {
+  let dir = resolve(cwd);
+  const root = parse(dir).root;
+  // Bound the walk by filesystem root; `dirname(root) === root` terminates.
+  while (true) {
+    if (await isFile(join(dir, ".beans.yml"))) return dir;
+    if (dir === root) return undefined;
+    const parent = dirname(dir);
+    if (parent === dir) return undefined;
+    dir = parent;
+  }
+}
+
+/** Resolve the `beans` executable on `PATH`, honoring `PATHEXT` on Windows. */
+async function resolveBeansBinary(): Promise<string | undefined> {
+  const pathEnv = process.env.PATH ?? "";
+  if (!pathEnv) return undefined;
+
+  const isWindows = process.platform === "win32";
+  const exts = isWindows ? windowsPathExt() : [""];
+  const entries = pathEnv.split(delimiter).filter((p) => p.length > 0);
+
+  for (const entry of entries) {
+    const dir = isAbsolute(entry) ? entry : resolve(entry);
+    for (const ext of exts) {
+      const candidate = join(dir, `beans${ext}`);
+      if (await isExecutableFile(candidate)) return candidate;
+    }
+  }
+  return undefined;
+}
+
+/** Parse Windows `PATHEXT`, defaulting to a sensible set if unset. */
+function windowsPathExt(): string[] {
+  const raw = process.env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD";
+  return raw
+    .split(";")
+    .map((e) => e.trim())
+    .filter((e) => e.length > 0)
+    .map((e) => (e.startsWith(".") ? e : `.${e}`));
+}
+
+async function isFile(path: string): Promise<boolean> {
+  try {
+    const s = await stat(path);
+    return s.isFile();
+  } catch {
+    return false;
+  }
+}
+
+async function isExecutableFile(path: string): Promise<boolean> {
+  try {
+    const s = await stat(path);
+    if (!s.isFile()) return false;
+    if (process.platform === "win32") return true; // PATHEXT match is sufficient
+    await access(path, fsConstants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/index.ts

@@ -0,0 +1,29 @@
+/**
+ * pi-beans — Beans CLI integration for pi.
+ *
+ * This file is the single entry point pi loads via `pi -e ./src/index.ts`.
+ * Concrete behavior lives in the per-track modules below; this file just
+ * wires their `register*` functions into the ExtensionAPI.
+ *
+ * Track ownership (see PLAN.md):
+ *   - Track A → ./env.ts          (detection, lifecycle, runner)
+ *   - Track B → ./prime.ts        (`beans prime` injection)
+ *   - Track C → ./tools/*.ts      (LLM-callable tools)
+ *   - Track D → ./commands.ts     (slash commands + footer status)
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+import { registerEnv } from "./env.js";
+import { registerPrime } from "./prime.js";
+import { registerTools } from "./tools/index.js";
+import { registerCommands } from "./commands.js";
+
+export default function piBeans(pi: ExtensionAPI): void {
+  // Order matters only for readability — each register* call is independent
+  // and coordinates with the others through src/internal.ts (events + state).
+  registerEnv(pi);
+  registerPrime(pi);
+  registerTools(pi);
+  registerCommands(pi);
+}

package/src/internal.ts

@@ -0,0 +1,162 @@
+/**
+ * Shared internal contracts for pi-beans.
+ *
+ * Each parallel track only depends on this module (and pi's SDK), so the
+ * tracks can be implemented in isolation without stepping on each other.
+ */
+
+import type { ExecOptions } from "@mariozechner/pi-coding-agent";
+
+/**
+ * Result of detecting whether beans is usable in the current project.
+ *
+ * Detection never throws — if beans is unavailable for any reason we return
+ * `available: false` plus a human-readable `reason` so the extension can show
+ * a one-line notice and stay loaded.
+ */
+export interface BeansEnv {
+  /** True when `beans` is on PATH AND a `.beans.yml` was found. */
+  available: boolean;
+  /** Why beans isn't available, for the session_start notice. */
+  reason?: string;
+  /**
+   * Project root used for every CLI invocation. This is the directory that
+   * contains `.beans.yml`. When `available` is false this falls back to the
+   * pi cwd.
+   */
+  cwd: string;
+  /** Resolved absolute path to the `beans` executable (may be empty when unavailable). */
+  binary: string;
+}
+
+/**
+ * Thin wrapper around `pi.exec("beans", args, { cwd })`.
+ *
+ * - Always runs from `env.cwd` (the project root).
+ * - Returns stdout on success.
+ * - Throws on non-zero exit; the thrown Error's message includes stderr
+ *   (or stdout if stderr was empty) so tools can surface it to the LLM.
+ */
+export interface BeansRunner {
+  run(args: string[], opts?: BeansRunOptions): Promise<string>;
+}
+
+export interface BeansRunOptions {
+  /** Optional stdin. Currently unused by v1 tools; reserved for future use. */
+  stdin?: string;
+  /** Forwarded to pi.exec. */
+  signal?: AbortSignal;
+  /** Forwarded to pi.exec. Defaults to a sensible per-call timeout. */
+  timeout?: number;
+  /** Override cwd; defaults to `env.cwd`. */
+  cwd?: string;
+  /** Extra exec options (rarely needed). */
+  exec?: ExecOptions;
+}
+
+// ---------------------------------------------------------------------------
+// Stubs implemented by Track A (src/env.ts)
+// ---------------------------------------------------------------------------
+
+/**
+ * Detect whether beans is usable from `cwd`.
+ *
+ * Implemented in `./env.ts` (Track A). Declared here so the other tracks can
+ * import the type without introducing a build-time cycle.
+ */
+export type DetectBeansEnv = (cwd: string) => Promise<BeansEnv>;
+
+/**
+ * Build a runner bound to a detected env.
+ *
+ * Implemented in `./env.ts` (Track A).
+ */
+export type CreateRunner = (
+  env: BeansEnv,
+  exec: (
+    command: string,
+    args: string[],
+    options?: ExecOptions,
+  ) => Promise<{ stdout: string; stderr: string; code: number; killed: boolean }>,
+) => BeansRunner;
+
+// ---------------------------------------------------------------------------
+// Tiny pub/sub so tracks can react to env / prime / mutation events without
+// importing each other directly.
+// ---------------------------------------------------------------------------
+
+export type BeansEventName =
+  /** Fires when env detection finishes (whether or not beans is available). */
+  | "env_ready"
+  /** Fires when `beans prime` output is refreshed (or cleared on failure). */
+  | "prime_updated"
+  /** Fires when one of our tools mutated beans state (create/update). */
+  | "beans_mutated"
+  /** Fires on session shutdown so subscribers can clear status, etc. */
+  | "shutdown";
+
+type Listener = (...args: any[]) => void;
+
+class BeansEventBus {
+  private readonly listeners = new Map<BeansEventName, Set<Listener>>();
+
+  on(event: BeansEventName, fn: Listener): () => void {
+    let set = this.listeners.get(event);
+    if (!set) {
+      set = new Set();
+      this.listeners.set(event, set);
+    }
+    set.add(fn);
+    return () => set!.delete(fn);
+  }
+
+  emit(event: BeansEventName, ...args: any[]): void {
+    const set = this.listeners.get(event);
+    if (!set) return;
+    for (const fn of set) {
+      try {
+        fn(...args);
+      } catch {
+        // listeners must not break each other
+      }
+    }
+  }
+
+  clear(): void {
+    this.listeners.clear();
+  }
+}
+
+export const beansEvents = new BeansEventBus();
+
+// ---------------------------------------------------------------------------
+// Shared module state. Tracks read/write through these accessors so they
+// don't need to import each other's modules.
+// ---------------------------------------------------------------------------
+
+let cachedEnv: BeansEnv | undefined;
+let cachedRunner: BeansRunner | undefined;
+
+/** Set by Track A after detection. */
+export function setEnv(env: BeansEnv, runner: BeansRunner | undefined): void {
+  cachedEnv = env;
+  cachedRunner = runner;
+  beansEvents.emit("env_ready", env);
+}
+
+/** Read the cached env (returns a disabled fallback before detection completes). */
+export function getEnv(): BeansEnv {
+  return (
+    cachedEnv ?? {
+      available: false,
+      reason: "beans env not yet detected",
+      cwd: process.cwd(),
+      binary: "",
+    }
+  );
+}
+
+/** Read the cached runner (or undefined before detection / when unavailable). */
+export function getRunner(): BeansRunner | undefined {
+  return cachedRunner;
+}

package/src/prime.ts

@@ -0,0 +1,77 @@
+/**
+ * Track B — `beans prime` injection.
+ *
+ * Runs `beans prime` once after env detection (and again when Track A asks
+ * us to, e.g. on `session_before_compact`), caches the output in module
+ * state, and appends it to the system prompt via `before_agent_start`.
+ *
+ * All failures are non-fatal: if `beans prime` errors out we drop the cache
+ * and skip injection, but the rest of the extension keeps working.
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+import { beansEvents, getRunner, type BeansEnv, type BeansRunner } from "./internal.js";
+
+/** Latest `beans prime` output, or null when unavailable / failed / not yet run. */
+let cachedPrime: string | null = null;
+
+/**
+ * Run `beans prime` and update the module-level cache.
+ *
+ * Returns the new cached value (or null on failure / when env is unavailable).
+ * Emits `prime_updated` on success so subscribers can react.
+ */
+export async function runPrime(
+  env: BeansEnv,
+  runner: BeansRunner | undefined,
+): Promise<string | null> {
+  if (!env.available || !runner) {
+    cachedPrime = null;
+    return null;
+  }
+  try {
+    const stdout = await runner.run(["prime"]);
+    const trimmed = stdout.trim();
+    cachedPrime = trimmed.length > 0 ? trimmed : null;
+    beansEvents.emit("prime_updated", cachedPrime);
+    return cachedPrime;
+  } catch {
+    // Non-fatal: surface via status line is Track A's responsibility.
+    cachedPrime = null;
+    return null;
+  }
+}
+
+/** Read the cached prime output (null when unavailable / failed). */
+export function getCachedPrime(): string | null {
+  return cachedPrime;
+}
+
+/**
+ * Wire prime injection into pi.
+ *
+ * - Refreshes the prime cache whenever env detection finishes.
+ * - Appends the cached prime to the system prompt on `before_agent_start`.
+ * - Clears the cache on `session_shutdown`.
+ */
+export function registerPrime(pi: ExtensionAPI): void {
+  beansEvents.on("env_ready", async (env: BeansEnv) => {
+    const runner = getRunner();
+    if (!env.available || !runner) {
+      cachedPrime = null;
+      return;
+    }
+    await runPrime(env, runner);
+  });
+
+  pi.on("before_agent_start", async (event) => {
+    const prime = getCachedPrime();
+    if (!prime) return undefined;
+    return { systemPrompt: `${event.systemPrompt}\n\n${prime}` };
+  });
+
+  pi.on("session_shutdown", () => {
+    cachedPrime = null;
+  });
+}

package/src/tools/create.ts

@@ -0,0 +1,46 @@
+/**
+ * `beans_create` — file a new bean (task, bug, etc.).
+ */
+
+import { Type } from "@mariozechner/pi-ai";
+import { defineTool } from "@mariozechner/pi-coding-agent";
+
+import { beansEvents } from "../internal.js";
+import { buildToolResult, requireRunner, withTempBodyFile } from "./util.js";
+
+export const beansCreateTool = defineTool({
+  name: "beans_create",
+  label: "beans create",
+  description:
+    "Create a new Beans issue in this project. Returns the CLI output, which includes the new bean id.",
+  promptSnippet: "Create a new Beans issue.",
+  promptGuidelines: [
+    "Use `beans_create` when the user asks you to track a task, when turning a spec into work items, or when you discover a bug worth filing. Do not create duplicate beans — call `beans_list` first if you are unsure.",
+  ],
+  parameters: Type.Object({
+    title: Type.String({ description: "Short, human-readable title for the bean." }),
+    body: Type.Optional(
+      Type.String({ description: "Optional initial markdown body / description." }),
+    ),
+    status: Type.Optional(
+      Type.String({
+        description: "Optional initial status (defaults to the CLI's default, typically 'todo').",
+      }),
+    ),
+  }),
+  async execute(_id, params) {
+    const runner = requireRunner();
+    const baseArgs: string[] = ["create", "--title", params.title];
+    if (params.status) baseArgs.push("--status", params.status);
+
+    const out =
+      params.body && params.body.length > 0
+        ? await withTempBodyFile(params.body, (path) =>
+            runner.run([...baseArgs, "--body-file", path]),
+          )
+        : await runner.run(baseArgs);
+
+    beansEvents.emit("beans_mutated");
+    return buildToolResult(out);
+  },
+});

package/src/tools/index.ts

@@ -0,0 +1,28 @@
+/**
+ * Collects and registers all pi-beans LLM-callable tools.
+ *
+ * Registration is eager: all four tools are visible to the LLM as soon as
+ * the extension loads. Each tool's `execute()` calls {@link requireRunner}
+ * up-front, so a call made before env detection completes — or in a project
+ * where beans is unavailable — fails fast with a clear error message rather
+ * than silently doing nothing.
+ *
+ * (pi's ExtensionAPI does not expose unregisterTool, so eager registration
+ * plus a runtime guard is the simplest correct behavior here.)
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+import { beansCreateTool } from "./create.js";
+import { beansListTool } from "./list.js";
+import { beansShowTool } from "./show.js";
+import { beansUpdateTool } from "./update.js";
+
+export function registerTools(pi: ExtensionAPI): void {
+  pi.registerTool(beansListTool);
+  pi.registerTool(beansShowTool);
+  pi.registerTool(beansCreateTool);
+  pi.registerTool(beansUpdateTool);
+}
+
+export { beansCreateTool, beansListTool, beansShowTool, beansUpdateTool };

package/src/tools/list.ts

@@ -0,0 +1,39 @@
+/**
+ * `beans_list` — discover open work in the current project.
+ */
+
+import { Type } from "@mariozechner/pi-ai";
+import { defineTool } from "@mariozechner/pi-coding-agent";
+
+import { buildToolResult, requireRunner } from "./util.js";
+
+export const beansListTool = defineTool({
+  name: "beans_list",
+  label: "beans list",
+  description:
+    "List Beans issues in this project. By default only open (non-archived) beans are returned.",
+  promptSnippet: "List Beans issues (open by default; supports status/archived/query filters)",
+  promptGuidelines: [
+    "Use `beans_list` to discover open work in this project before proposing new changes from scratch.",
+  ],
+  parameters: Type.Object({
+    status: Type.Optional(
+      Type.String({ description: "Filter by status, e.g. 'todo', 'doing', 'done'." }),
+    ),
+    include_archived: Type.Optional(
+      Type.Boolean({ description: "Include archived beans (default false)." }),
+    ),
+    query: Type.Optional(
+      Type.String({ description: "Optional free-text filter forwarded to the CLI." }),
+    ),
+  }),
+  async execute(_id, params) {
+    const runner = requireRunner();
+    const args: string[] = ["list"];
+    if (params.status) args.push("--status", params.status);
+    if (params.include_archived) args.push("--archived");
+    if (params.query) args.push(params.query);
+    const out = await runner.run(args);
+    return buildToolResult(out);
+  },
+});

package/src/tools/show.ts

@@ -0,0 +1,26 @@
+/**
+ * `beans_show` — read a single bean by id.
+ */
+
+import { Type } from "@mariozechner/pi-ai";
+import { defineTool } from "@mariozechner/pi-coding-agent";
+
+import { buildToolResult, requireRunner } from "./util.js";
+
+export const beansShowTool = defineTool({
+  name: "beans_show",
+  label: "beans show",
+  description: "Read a single Beans issue by id, including its full markdown body and metadata.",
+  promptSnippet: "Read a single Beans issue by id.",
+  promptGuidelines: [
+    "Use `beans_show` to read the full description of a bean before starting work on it.",
+  ],
+  parameters: Type.Object({
+    id: Type.String({ description: "The bean id, e.g. 'myproj-1a2b'." }),
+  }),
+  async execute(_id, params) {
+    const runner = requireRunner();
+    const out = await runner.run(["show", params.id]);
+    return buildToolResult(out);
+  },
+});

package/src/tools/update.ts

@@ -0,0 +1,105 @@
+/**
+ * `beans_update` — record progress on an existing bean.
+ *
+ * Mutations against `.beans/<id>.md` go through {@link withFileMutationQueue}
+ * so they interleave correctly with built-in `edit` / `write` calls (per the
+ * SPEC "File mutation discipline" requirement).
+ */
+
+import path from "node:path";
+
+import { Type } from "@mariozechner/pi-ai";
+import { defineTool, withFileMutationQueue } from "@mariozechner/pi-coding-agent";
+
+import { beansEvents, getEnv } from "../internal.js";
+import type { BeansRunner } from "../internal.js";
+import { buildToolResult, requireRunner, withTempBodyFile } from "./util.js";
+
+/** Build the optional `--status` / `--title` flag list shared by every code path. */
+function optStatusTitle(params: { status?: string; title?: string }): string[] {
+  const out: string[] = [];
+  if (params.status) out.push("--status", params.status);
+  if (params.title) out.push("--title", params.title);
+  return out;
+}
+
+/** Resolve the on-disk path of a bean's markdown file under the project root. */
+function beanFilePath(id: string): string {
+  const env = getEnv();
+  return path.resolve(env.cwd, ".beans", `${id}.md`);
+}
+
+/** Run `beans update` with a body file plus optional status/title flags. */
+async function runUpdateWithBody(
+  runner: BeansRunner,
+  id: string,
+  body: string,
+  params: { status?: string; title?: string },
+): Promise<string> {
+  return withTempBodyFile(body, (p) =>
+    runner.run(["update", id, "--body-file", p, ...optStatusTitle(params)]),
+  );
+}
+
+export const beansUpdateTool = defineTool({
+  name: "beans_update",
+  label: "beans update",
+  description:
+    "Update an existing Beans issue: change status/title, replace the body, or append to it.",
+  promptSnippet: "Update a Beans issue (status/title/body, or append to body).",
+  promptGuidelines: [
+    "Use `beans_update` to record progress: set status to `doing` when you start, to `done` when finished, and append notes with `body_append` instead of rewriting the body.",
+  ],
+  parameters: Type.Object({
+    id: Type.String({ description: "The bean id to update, e.g. 'myproj-1a2b'." }),
+    status: Type.Optional(
+      Type.String({ description: "New status (e.g. 'todo', 'doing', 'done')." }),
+    ),
+    title: Type.Optional(Type.String({ description: "Replace the bean's title." })),
+    body: Type.Optional(
+      Type.String({
+        description:
+          "Replace the bean's full markdown body. Mutually exclusive with `body_append`.",
+      }),
+    ),
+    body_append: Type.Optional(
+      Type.String({
+        description: "Append text to the bean's existing body. Mutually exclusive with `body`.",
+      }),
+    ),
+  }),
+  async execute(_id, params) {
+    if (params.body !== undefined && params.body_append !== undefined) {
+      throw new Error("`body` and `body_append` are mutually exclusive");
+    }
+    if (
+      params.status === undefined &&
+      params.title === undefined &&
+      params.body === undefined &&
+      params.body_append === undefined
+    ) {
+      throw new Error("beans_update requires at least one of: status, title, body, body_append");
+    }
+
+    const runner = requireRunner();
+    let stdout: string;
+
+    if (params.body_append !== undefined) {
+      stdout = await withFileMutationQueue(beanFilePath(params.id), async () => {
+        // v1: the CLI has no body-only output, so we use the full `beans show`
+        // dump as the working body context. Appending is best-effort but
+        // preserves all existing content.
+        const current = await runner.run(["show", params.id]);
+        const newBody = `${current.trim()}\n\n${params.body_append}`;
+        return runUpdateWithBody(runner, params.id, newBody, params);
+      });
+    } else if (params.body !== undefined) {
+      stdout = await runUpdateWithBody(runner, params.id, params.body, params);
+    } else {
+      stdout = await runner.run(["update", params.id, ...optStatusTitle(params)]);
+    }
+
+    beansEvents.emit("beans_mutated");
+    return buildToolResult(stdout);
+  },
+});

package/src/tools/util.ts

@@ -0,0 +1,79 @@
+/**
+ * Shared helpers for the pi-beans tool implementations.
+ *
+ * These helpers exist so each tool file stays small and focused on its
+ * CLI-specific surface (argument shape, prompt copy). Anything that touches
+ * the filesystem, formats output, or performs cross-tool validation lives
+ * here.
+ */
+
+import { randomBytes } from "node:crypto";
+import { promises as fs } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { truncateHead } from "@mariozechner/pi-coding-agent";
+
+import { getRunner } from "../internal.js";
+import type { BeansRunner } from "../internal.js";
+
+/**
+ * Write `text` to a unique temporary file, invoke `fn` with its absolute
+ * path, then best-effort delete the file. The promise from `fn` is awaited
+ * (and its result returned/forwarded) before cleanup runs.
+ *
+ * The temp file lives under {@link tmpdir} as `pi-beans-body-<rand>.md`.
+ * Cleanup errors are swallowed because they are not actionable for callers.
+ */
+export async function withTempBodyFile<T>(
+  text: string,
+  fn: (path: string) => Promise<T>,
+): Promise<T> {
+  const path = join(tmpdir(), `pi-beans-body-${randomBytes(8).toString("hex")}.md`);
+  await fs.writeFile(path, text, "utf8");
+  try {
+    return await fn(path);
+  } finally {
+    try {
+      await fs.unlink(path);
+    } catch {
+      // best-effort cleanup
+    }
+  }
+}
+
+/**
+ * Run `truncateHead` with default 50KB / 2000-line limits and append a
+ * one-line notice when truncation occurred so the LLM knows output was
+ * dropped (per SPEC "Output > 50KB" handling).
+ */
+export function formatToolText(stdout: string): string {
+  const result = truncateHead(stdout);
+  if (!result.truncated) return result.content;
+  const reason =
+    result.truncatedBy === "lines" ? `${result.totalLines} lines` : `${result.totalBytes} bytes`;
+  return `${result.content}\n\n[pi-beans: output truncated; ${reason} total. Re-run a more specific query to see the rest.]`;
+}
+
+/**
+ * Standard tool result envelope: a single text block with truncated stdout.
+ */
+export interface BeansToolResult {
+  content: [{ type: "text"; text: string }];
+  details: undefined;
+}
+
+export function buildToolResult(stdout: string): BeansToolResult {
+  return { content: [{ type: "text", text: formatToolText(stdout) }], details: undefined };
+}
+
+/**
+ * Resolve the active {@link BeansRunner}, or throw a clear error so the LLM
+ * sees a useful message when env detection failed (e.g. missing CLI or
+ * `.beans.yml`). Tools call this at the top of `execute()`.
+ */
+export function requireRunner(): BeansRunner {
+  const runner = getRunner();
+  if (!runner) throw new Error("beans not configured for this project");
+  return runner;
+}