@gaia-ai/addon-pi 0.6.1

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

@@ -0,0 +1,5 @@
+# @gaia-ai/addon-pi
+
+GAIA agent plugin for the pi coding CLI, with a real transcript footprint.
+
+Part of the GAIA CLI. Install the meta package `@gaia-ai/gaia` to get the `gaia` CLI with all addons. Source: https://git.key-tec.de/keytec/gaia (gaia-cli/).

package/dist/src/footprint.d.ts

@@ -0,0 +1,19 @@
+import { type AgentFootprint } from '@gaia-ai/conductor/contract';
+/**
+ * Parse a pi JSONL transcript into an agent footprint (GAIA-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` (GAIA-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 '@gaia-ai/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 (GAIA-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` (GAIA-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,43 @@
+import type { AgentFootprint, AgentPlugin, GaiaAgent } from '@gaia-ai/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>/.gaia/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 = ".gaia/pi-sessions";
+/**
+ * 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/gaia` →
+ * `--home-cw-projects-gaia--`.
+ */
+export declare function encodePiHomeSessionSlug(cwd: string): string;
+export interface PiAgentOptions {
+    model?: string;
+    provider?: string;
+    thinking?: 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 gaia worktree ships no project-local pi files
+     * a run needs.
+     */
+    approve?: boolean;
+}
+export declare class PiAgent implements GaiaAgent {
+    private readonly options;
+    private readonly home;
+    readonly id = "pi";
+    constructor(options: PiAgentOptions, home?: string);
+    launchCommand(prompt: string): string;
+    getRunLog(worktreePath: string): 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,123 @@
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { shellQuote } from '@gaia-ai/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>/.gaia/pi-sessions`). `launchCommand` gets no
+ * `worktreePath`, so a relative pin is the one path both sides can agree on.
+ */
+export const PI_SESSION_DIR = '.gaia/pi-sessions';
+/**
+ * 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/gaia` →
+ * `--home-cw-projects-gaia--`.
+ */
+export function encodePiHomeSessionSlug(cwd) {
+    return `-${cwd.replaceAll('/', '-')}--`;
+}
+/** Newest `*.jsonl` in `dir` by mtime, or `''`. Swallows every fs error. */
+async function newestJsonl(dir) {
+    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 (!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 {
+    options;
+    home;
+    id = 'pi';
+    constructor(options, home = homedir()) {
+        this.options = options;
+        this.home = home;
+    }
+    launchCommand(prompt) {
+        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.options.provider) {
+            parts.push('--provider', this.options.provider);
+        }
+        if (this.options.model) {
+            parts.push('--model', this.options.model);
+        }
+        if (this.options.thinking) {
+            parts.push('--thinking', this.options.thinking);
+        }
+        parts.push('--session-dir', PI_SESSION_DIR);
+        if (this.options.approve) {
+            parts.push('--approve');
+        }
+        return parts.join(' ');
+    }
+    async getRunLog(worktreePath) {
+        // Primary: the relative --session-dir pinned at launch, joined onto the
+        // worktree — the deterministic location launchCommand wrote to.
+        const primary = await newestJsonl(join(worktreePath, PI_SESSION_DIR));
+        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).
+        return newestJsonl(join(this.home, '.pi', 'agent', 'sessions', encodePiHomeSessionSlug(worktreePath)));
+    }
+    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,2 @@
+import type { Preset } from '@gaia-ai/conductor/contract';
+export declare const agents: Preset['agents'];

package/dist/src/preset.js

@@ -0,0 +1,5 @@
+import piAgent from './index.js';
+export const agents = (acc, opts) => [
+    ...acc,
+    { agent: piAgent(opts) },
+];

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@gaia-ai/addon-pi",
+  "version": "0.6.1",
+  "description": "GAIA 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/keytec/gaia.git",
+    "directory": "gaia-cli/addons/pi"
+  },
+  "peerDependencies": {
+    "@gaia-ai/conductor": "^0.6.1",
+    "@gaia-ai/core": "^0.6.1"
+  }
+}