@bakers-build/addon-pi 0.0.0-stage → 0.1.0-next.42

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 keytec GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,5 @@
-# Temporary Holding Version
+# @bakers-build/addon-pi
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+bakers.build agent plugin for the pi coding CLI, with a real transcript footprint.
+
+Part of the bakers.build CLI. Install the meta package `@bakers-build/bakers` to get the `bakers` CLI with all addons. Source: https://git.key-tec.de/bakers-build/bakers-build (bakers-cli/).

package/dist/src/footprint.d.ts

@@ -0,0 +1,19 @@
+import { type AgentFootprint } from '@bakers-build/conductor/contract';
+/**
+ * Parse a pi JSONL transcript into an agent footprint (BB-132).
+ *
+ * pi's transcript is one JSON object per line. `message` entries carry
+ * `message.role`, and pi uses THREE roles: `user` (a genuine prompt),
+ * `assistant` (an agent turn, with a per-turn `message.usage.totalTokens` and a
+ * `content[]` array whose `toolCall` parts are the tool invocations), and a
+ * distinct `toolResult` role for tool output. Tool results are cleanly
+ * separable from prompts by role — no string-vs-array heuristic (unlike
+ * claude). Blank or malformed lines are skipped — never throws.
+ *
+ * `duration_s` is the run's wall-clock length: the span between the first and
+ * last entry that carries a parseable top-level `timestamp` (BB-151); fewer
+ * than two timestamps → 0. `tokens` uses pi's own per-turn `totalTokens`, so no
+ * usage-bucket sum is needed. `model` is the last assistant turn's
+ * `provider/model`, falling back to the last `model_change`'s `provider/modelId`.
+ */
+export declare function parsePiTranscript(jsonl: string): AgentFootprint;

package/dist/src/footprint.js

@@ -0,0 +1,113 @@
+import { emptyAgentFootprint, } from '@bakers-build/conductor/contract';
+function num(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : 0;
+}
+function countWords(text) {
+    const trimmed = text.trim();
+    return trimmed === '' ? 0 : trimmed.split(/\s+/).length;
+}
+/** Words across the `text` parts of a pi `message.content[]` array. */
+function promptWords(content) {
+    if (!Array.isArray(content)) {
+        return 0;
+    }
+    let words = 0;
+    for (const part of content) {
+        if (part &&
+            typeof part === 'object' &&
+            part.type === 'text' &&
+            typeof part.text === 'string') {
+            words += countWords(part.text);
+        }
+    }
+    return words;
+}
+/**
+ * Parse a pi JSONL transcript into an agent footprint (BB-132).
+ *
+ * pi's transcript is one JSON object per line. `message` entries carry
+ * `message.role`, and pi uses THREE roles: `user` (a genuine prompt),
+ * `assistant` (an agent turn, with a per-turn `message.usage.totalTokens` and a
+ * `content[]` array whose `toolCall` parts are the tool invocations), and a
+ * distinct `toolResult` role for tool output. Tool results are cleanly
+ * separable from prompts by role — no string-vs-array heuristic (unlike
+ * claude). Blank or malformed lines are skipped — never throws.
+ *
+ * `duration_s` is the run's wall-clock length: the span between the first and
+ * last entry that carries a parseable top-level `timestamp` (BB-151); fewer
+ * than two timestamps → 0. `tokens` uses pi's own per-turn `totalTokens`, so no
+ * usage-bucket sum is needed. `model` is the last assistant turn's
+ * `provider/model`, falling back to the last `model_change`'s `provider/modelId`.
+ */
+export function parsePiTranscript(jsonl) {
+    const footprint = emptyAgentFootprint();
+    let minTs = Number.POSITIVE_INFINITY;
+    let maxTs = Number.NEGATIVE_INFINITY;
+    let lastModelChange;
+    for (const raw of jsonl.split('\n')) {
+        const trimmed = raw.trim();
+        if (trimmed === '') {
+            continue;
+        }
+        let entry;
+        try {
+            entry = JSON.parse(trimmed);
+        }
+        catch {
+            continue;
+        }
+        // Track the run span across ANY timestamped entry (session, message, …).
+        if (typeof entry.timestamp === 'string') {
+            const ts = Date.parse(entry.timestamp);
+            if (Number.isFinite(ts)) {
+                if (ts < minTs)
+                    minTs = ts;
+                if (ts > maxTs)
+                    maxTs = ts;
+            }
+        }
+        if (entry.type === 'model_change' &&
+            typeof entry.provider === 'string' &&
+            typeof entry.modelId === 'string') {
+            lastModelChange = `${entry.provider}/${entry.modelId}`;
+            continue;
+        }
+        if (entry.type !== 'message') {
+            continue;
+        }
+        const message = entry.message;
+        if (!message || typeof message !== 'object') {
+            continue;
+        }
+        if (message.role === 'assistant') {
+            footprint.agent_turns += 1;
+            footprint.tokens += num(message.usage?.totalTokens);
+            if (Array.isArray(message.content)) {
+                for (const part of message.content) {
+                    if (part &&
+                        typeof part === 'object' &&
+                        part.type === 'toolCall') {
+                        footprint.tool_calls += 1;
+                    }
+                }
+            }
+            if (typeof message.provider === 'string' &&
+                typeof message.model === 'string') {
+                footprint.model = `${message.provider}/${message.model}`;
+            }
+        }
+        else if (message.role === 'user') {
+            footprint.user_prompts += 1;
+            footprint.user_prompt_words += promptWords(message.content);
+        }
+        // `toolResult` messages are tool output — neither a prompt nor a turn.
+    }
+    if (Number.isFinite(minTs) && Number.isFinite(maxTs) && maxTs > minTs) {
+        footprint.duration_s = Math.floor((maxTs - minTs) / 1000);
+    }
+    // Prefer the last assistant turn's model; fall back to the last model_change.
+    if (footprint.model === undefined && lastModelChange !== undefined) {
+        footprint.model = lastModelChange;
+    }
+    return footprint;
+}

package/dist/src/index.d.ts

@@ -0,0 +1,58 @@
+import { type AgentFootprint, type AgentPlugin, type AgentRunIdentity, type BbAgent } from '@bakers-build/conductor/contract';
+export { parsePiTranscript } from './footprint.js';
+/**
+ * The relative `--session-dir` pin — the single source of truth shared by
+ * `launchCommand` (which pins pi's transcript there at launch) and `getRunLog`
+ * (which reads it back). Relative → resolves against the run's cwd, i.e. the
+ * worktree (`<worktree>/.bakers/pi-sessions`). `launchCommand` gets no
+ * `worktreePath`, so a relative pin is the one path both sides can agree on.
+ */
+export declare const PI_SESSION_DIR = ".bakers/pi-sessions";
+/**
+ * The `--session-dir` value for a given run (BB-473): scoped to the run's
+ * own subdirectory when its identity is known, so `getRunLog` reads only that
+ * run's own transcripts — never a foreign one left behind by a resumed
+ * run/re-dispatch/reused worktree in the shared {@link PI_SESSION_DIR}. Falls
+ * back to the shared dir when no run identity is given (today's behaviour).
+ */
+export declare function piSessionDir(run?: AgentRunIdentity): string;
+/**
+ * Encode an absolute cwd the way pi names its per-cwd home-session directory
+ * under `~/.pi/agent/sessions/`: only `/` is replaced with `-`, and the slug is
+ * wrapped in leading + trailing `--` (a leading `/` yields the leading `--`).
+ * `.` and `-` are preserved — this is NOT claude's all-non-alnum scheme.
+ * Verified against pi v0.82.1: `/home/cw/projects/bakers` →
+ * `--home-cw-projects-bakers--`.
+ */
+export declare function encodePiHomeSessionSlug(cwd: string): string;
+export interface PiAgentOptions {
+    model?: string;
+    provider?: string;
+    thinking?: string;
+    effort?: string;
+    args?: string[];
+    /**
+     * Trust the worktree's project-local pi files (extensions/skills/themes) for
+     * the run — pi's `-a/--approve`. Opt-in (default off): pi has no
+     * tool-permission gate, and the bakers worktree ships no project-local pi files
+     * a run needs.
+     */
+    approve?: boolean;
+}
+export declare class PiAgent implements BbAgent {
+    private readonly home;
+    readonly id = "pi";
+    private readonly args;
+    private readonly model;
+    private readonly provider;
+    private readonly thinking;
+    private readonly approve;
+    private readonly overrides;
+    constructor(options?: PiAgentOptions, home?: string);
+    launchCommand(prompt: string, run?: AgentRunIdentity): string;
+    getRunLog(worktreePath: string, run?: AgentRunIdentity): Promise<string>;
+    parseFootprint(log: string): AgentFootprint;
+}
+/** Config-facing factory: `piAgent({ model: 'kimi-coding/k3' })`. */
+export declare function piAgent(options?: PiAgentOptions): AgentPlugin;
+export default piAgent;

package/dist/src/index.js

@@ -0,0 +1,180 @@
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { resolveAgentCliOptions, validateOptionalBoolean, validateOptionalString, } from '@bakers-build/conductor/contract';
+import { shellQuote } from '@bakers-build/core';
+import { parsePiTranscript } from './footprint.js';
+export { parsePiTranscript } from './footprint.js';
+/**
+ * The relative `--session-dir` pin — the single source of truth shared by
+ * `launchCommand` (which pins pi's transcript there at launch) and `getRunLog`
+ * (which reads it back). Relative → resolves against the run's cwd, i.e. the
+ * worktree (`<worktree>/.bakers/pi-sessions`). `launchCommand` gets no
+ * `worktreePath`, so a relative pin is the one path both sides can agree on.
+ */
+export const PI_SESSION_DIR = '.bakers/pi-sessions';
+/**
+ * The `--session-dir` value for a given run (BB-473): scoped to the run's
+ * own subdirectory when its identity is known, so `getRunLog` reads only that
+ * run's own transcripts — never a foreign one left behind by a resumed
+ * run/re-dispatch/reused worktree in the shared {@link PI_SESSION_DIR}. Falls
+ * back to the shared dir when no run identity is given (today's behaviour).
+ */
+export function piSessionDir(run) {
+    return run?.sessionId ? `${PI_SESSION_DIR}/${run.sessionId}` : PI_SESSION_DIR;
+}
+/**
+ * Encode an absolute cwd the way pi names its per-cwd home-session directory
+ * under `~/.pi/agent/sessions/`: only `/` is replaced with `-`, and the slug is
+ * wrapped in leading + trailing `--` (a leading `/` yields the leading `--`).
+ * `.` and `-` are preserved — this is NOT claude's all-non-alnum scheme.
+ * Verified against pi v0.82.1: `/home/cw/projects/bakers` →
+ * `--home-cw-projects-bakers--`.
+ */
+export function encodePiHomeSessionSlug(cwd) {
+    return `-${cwd.replaceAll('/', '-')}--`;
+}
+const PI_RESERVED = [
+    '--session-dir',
+    '--approve',
+    '-a',
+    '--no-approve',
+    '-na',
+];
+const PI_KNOWN = [
+    { kind: 'model', flags: ['--model'] },
+    { kind: 'effort', flags: ['--thinking'] },
+];
+/**
+ * Newest `*.jsonl` in `dir` by mtime, or `''`. Swallows every fs error.
+ * `minMtimeMs`, when given, excludes anything older — the fallback scan's
+ * defence against selecting a transcript from a PRIOR run left in the shared,
+ * cwd-keyed home session dir (BB-473 finding 2).
+ */
+async function newestJsonl(dir, minMtimeMs) {
+    let entries;
+    try {
+        entries = await readdir(dir);
+    }
+    catch {
+        return '';
+    }
+    let latest = null;
+    for (const name of entries) {
+        if (!name.endsWith('.jsonl')) {
+            continue;
+        }
+        const full = join(dir, name);
+        try {
+            const s = await stat(full);
+            if (minMtimeMs !== undefined &&
+                Number.isFinite(minMtimeMs) &&
+                s.mtimeMs < minMtimeMs) {
+                continue;
+            }
+            if (!latest || s.mtimeMs > latest.mtimeMs) {
+                latest = { path: full, mtimeMs: s.mtimeMs };
+            }
+        }
+        catch {
+            // entry vanished between readdir and stat — skip.
+        }
+    }
+    if (!latest) {
+        return '';
+    }
+    try {
+        return await readFile(latest.path, 'utf8');
+    }
+    catch {
+        return '';
+    }
+}
+export class PiAgent {
+    home;
+    id = 'pi';
+    args;
+    model;
+    provider;
+    thinking;
+    approve;
+    overrides;
+    constructor(options = {}, home = homedir()) {
+        this.home = home;
+        const cli = resolveAgentCliOptions(options, PI_RESERVED, PI_KNOWN);
+        this.args = cli.args;
+        this.model = cli.model;
+        this.provider = validateOptionalString(options.provider, 'provider');
+        this.thinking =
+            cli.effort ?? validateOptionalString(options.thinking, 'thinking');
+        this.approve = validateOptionalBoolean(options.approve, 'approve') === true;
+        this.overrides = cli.overrides;
+    }
+    launchCommand(prompt, run) {
+        if (prompt === '') {
+            return 'pi';
+        }
+        // Positional prompt → an attachable interactive TUI (no `-p`/`--print`,
+        // which would leave the herdr pane without a session to attach to). Order:
+        // provider/model/thinking, then the transcript-pinning --session-dir, then
+        // the opt-in --approve.
+        const parts = ['pi', shellQuote(prompt)];
+        if (this.provider) {
+            parts.push('--provider', shellQuote(this.provider));
+        }
+        if (this.model !== undefined && !this.overrides.model) {
+            parts.push('--model', shellQuote(this.model));
+        }
+        if (this.thinking !== undefined && !this.overrides.effort) {
+            parts.push('--thinking', shellQuote(this.thinking));
+        }
+        // Scoped to this run's own subdirectory (BB-473) when a run identity is
+        // given, so getRunLog needs no ambiguity-prone scan of the shared
+        // session dir a resumed/re-dispatched/reused worktree could have left
+        // other transcripts in.
+        parts.push('--session-dir', piSessionDir(run));
+        if (this.approve) {
+            parts.push('--approve');
+        }
+        parts.push(...this.args.map(shellQuote));
+        return parts.join(' ');
+    }
+    async getRunLog(worktreePath, run) {
+        // Primary: the relative --session-dir pinned at launch (per-run scoped
+        // when `run` is given), joined onto the worktree — the deterministic
+        // location launchCommand wrote to.
+        const primary = await newestJsonl(join(worktreePath, piSessionDir(run)));
+        if (primary !== '') {
+            return primary;
+        }
+        // Fallback: pi's home session dir for the worktree cwd — covers a run
+        // launched without the pin (a human who ran bare `pi`, or a pre-addon
+        // run). BB-473 finding 2: that dir is shared/cwd-keyed like the other
+        // addons' scans, so it is bounded by `run.startedAt` where known — a
+        // transcript from a PRIOR run left in the same worktree can never be
+        // selected for this one even when it is the newest match.
+        const startedAtMs = run?.startedAt !== undefined ? new Date(run.startedAt).getTime() : null;
+        return newestJsonl(join(this.home, '.pi', 'agent', 'sessions', encodePiHomeSessionSlug(worktreePath)), startedAtMs !== null && Number.isFinite(startedAtMs)
+            ? startedAtMs
+            : undefined);
+    }
+    parseFootprint(log) {
+        return parsePiTranscript(log);
+    }
+}
+/** Config-facing factory: `piAgent({ model: 'kimi-coding/k3' })`. */
+export function piAgent(options = {}) {
+    const agent = new PiAgent(options);
+    return {
+        kind: 'agent',
+        id: 'pi',
+        requiredModules: [],
+        async createAgent() {
+            return agent;
+        },
+    };
+}
+// Default export: this module also exports the `PiAgent` class, so the config
+// resolver's auto-pick (no `export:`) would see multiple function exports and
+// throw "specify export". The default export makes the factory win.
+export default piAgent;

package/dist/src/preset.d.ts

@@ -0,0 +1,4 @@
+import type { Preset } from '@bakers-build/conductor/contract';
+import { type PiAgentOptions } from './index.js';
+export declare const agents: Preset<Partial<PiAgentOptions> | undefined>['agents'];
+export declare const scopes: Preset['scopes'];

package/dist/src/preset.js

@@ -0,0 +1,15 @@
+import piAgent from './index.js';
+export const agents = (acc, opts) => {
+    const model = opts?.model;
+    return [
+        ...acc,
+        {
+            alias: 'pi',
+            description: 'General coding with the locally configured Pi model.',
+            ...(model !== undefined ? { model } : {}),
+            agent: piAgent(opts),
+        },
+    ];
+};
+// Agents are per machine: list this addon in ~/.bakers/machine.config.js addons[].
+export const scopes = ['machine'];

package/package.json

@@ -1,6 +1,26 @@
 {
   "name": "@bakers-build/addon-pi",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-next.42",
+  "description": "bakers.build agent plugin for the pi coding CLI, with a real transcript footprint.",
+  "type": "module",
+  "license": "MIT",
+  "exports": {
+    ".": "./dist/src/index.js",
+    "./preset": "./dist/src/preset.js"
+  },
+  "files": [
+    "dist/src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://git.key-tec.de/bakers-build/bakers-build.git",
+    "directory": "bakers-cli/addons/pi"
+  },
+  "peerDependencies": {
+    "@bakers-build/conductor": "^0.1.0-next.42",
+    "@bakers-build/core": "^0.1.0-next.42"
+  }
+}