@rol1n/pi-kit 0.0.0-stage → 0.1.0

package/extensions/srp-theme/tps-meter.ts

@@ -0,0 +1,442 @@
+import type { ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
+import { visibleWidth } from "@earendil-works/pi-tui";
+
+export class TpsMeter {
+  // Constants
+  static readonly WINDOW_SIZE = 60;
+  static readonly WINDOW_MS = 60_000;
+  static readonly STREAM_INTERVAL_MS = 200;
+  static readonly SPARK_LEN = 12;
+  static readonly ALLTIME_CAP = 500;
+  static readonly FAST = 50;
+  static readonly MED = 20;
+
+  // Render glyphs
+  static readonly BLOCKS = ["▁", "▂", "▃", "▄", "▅", "▆", "▇", "█"];
+  static readonly HBLOCKS = [" ", "▏", "▎", "▍", "▌", "▋", "▊", "▉"];
+  static readonly GAUGE_LEN = 11;
+  static readonly GAUGE_FLOOR = 40;
+  static readonly TRACK = "·";
+  static readonly SPIN = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+
+  // State variables
+  private streamStartMs = 0;
+  private firstTokenMs = 0;
+  private streamChars = 0;
+  private streamTokens = 0;
+  private tickTimer: ReturnType<typeof setInterval> | null = null;
+  private streaming = false;
+
+  // 60-second rolling window (ring buffer: [tps, timestamp])
+  private readonly winBuf = new Float64Array(TpsMeter.WINDOW_SIZE * 2);
+  private winLen = 0;
+  private winHead = 0;
+
+  // Session-wide sampling (ring buffer: [tps])
+  private readonly atBuf = new Float64Array(TpsMeter.ALLTIME_CAP);
+  private atLen = 0;
+  private atHead = 0;
+  private atSum = 0;
+
+  // Sparkline history for last 12 messages
+  private readonly sparkBuf = new Float64Array(TpsMeter.SPARK_LEN);
+  private sparkLen = 0;
+  private sparkHead = 0;
+  private sparkMax = 1;
+  private sparkCache = "";
+  private sparkDirty = true;
+  private sparkTheme: Theme | null = null;
+  private spinI = 0;
+  private lastStatusText: string | undefined = undefined;
+
+  public enabled = true;
+
+  private applyStatus(ctx: ExtensionContext, text: string | undefined): void {
+    if (this.lastStatusText === text) return;
+    this.lastStatusText = text;
+    if (ctx.ui?.setStatus) {
+      ctx.ui.setStatus("tps", text);
+    }
+  }
+
+  reset(ctx?: ExtensionContext): void {
+    this.streaming = false;
+    this.stopTick();
+    this.streamStartMs = 0;
+    this.firstTokenMs = 0;
+    this.streamChars = 0;
+    this.streamTokens = 0;
+    this.winLen = 0;
+    this.winHead = 0;
+    this.atLen = 0;
+    this.atHead = 0;
+    this.atSum = 0;
+    this.sparkLen = 0;
+    this.sparkHead = 0;
+    this.sparkMax = 1;
+    this.sparkCache = "";
+    this.sparkDirty = true;
+    this.sparkTheme = null;
+    this.spinI = 0;
+    this.lastStatusText = undefined;
+    if (ctx) {
+      if (this.enabled) {
+        const theme = ctx.ui?.theme ?? safeFallbackTheme;
+        this.applyStatus(ctx, this.renderFinal(theme));
+      } else {
+        this.applyStatus(ctx, undefined);
+      }
+    }
+  }
+
+  private now(): number {
+    return Date.now();
+  }
+
+  private tokEst(ch: number): number {
+    return (ch >>> 2) + ((ch & 3) > 0 ? 1 : 0);
+  }
+
+  private winPush(tps: number, ms: number): void {
+    const b = this.winHead * 2;
+    this.winBuf[b] = tps;
+    this.winBuf[b + 1] = ms;
+    this.winHead = (this.winHead + 1) % TpsMeter.WINDOW_SIZE;
+    if (this.winLen < TpsMeter.WINDOW_SIZE) this.winLen++;
+  }
+
+  private atPush(tps: number): void {
+    this.atSum += tps;
+    if (this.atLen >= TpsMeter.ALLTIME_CAP) this.atSum -= this.atBuf[this.atHead];
+    this.atBuf[this.atHead] = tps;
+    this.atHead = (this.atHead + 1) % TpsMeter.ALLTIME_CAP;
+    if (this.atLen < TpsMeter.ALLTIME_CAP) this.atLen++;
+  }
+
+  private sparkPush(tps: number): void {
+    this.sparkBuf[this.sparkHead] = tps;
+    this.sparkHead = (this.sparkHead + 1) % TpsMeter.SPARK_LEN;
+    if (this.sparkLen < TpsMeter.SPARK_LEN) this.sparkLen++;
+    if (tps > this.sparkMax) this.sparkMax = tps;
+    if (this.sparkMax > 10) this.sparkMax *= 0.99;
+    this.sparkDirty = true;
+  }
+
+  winAvg(): number {
+    if (this.winLen === 0) return 0;
+    const cutoff = this.now() - TpsMeter.WINDOW_MS;
+    let sum = 0;
+    let n = 0;
+    const oldest = this.winLen < TpsMeter.WINDOW_SIZE ? 0 : this.winHead;
+    for (let i = 0; i < this.winLen; i++) {
+      const idx = (oldest + i) % TpsMeter.WINDOW_SIZE;
+      const b = idx * 2;
+      if (this.winBuf[b + 1] < cutoff) continue;
+      sum += this.winBuf[b];
+      n++;
+    }
+    return n === 0 ? 0 : sum / n;
+  }
+
+  atMean(): number {
+    return this.atLen === 0 ? 0 : this.atSum / this.atLen;
+  }
+
+  atP95(): number {
+    if (this.atLen === 0) return 0;
+    const tmp = new Float64Array(this.atLen);
+    const oldest = this.atLen < TpsMeter.ALLTIME_CAP ? 0 : this.atHead;
+    for (let i = 0; i < this.atLen; i++) tmp[i] = this.atBuf[(oldest + i) % TpsMeter.ALLTIME_CAP];
+    // Insertion sort
+    for (let i = 1; i < tmp.length; i++) {
+      const v = tmp[i];
+      let j = i - 1;
+      while (j >= 0 && tmp[j] > v) {
+        tmp[j + 1] = tmp[j];
+        j--;
+      }
+      tmp[j + 1] = v;
+    }
+    return tmp[Math.ceil(tmp.length * 0.95) - 1] || 0;
+  }
+
+  private fmt(v: number): string {
+    if (v < 10) return v.toFixed(1);
+    if (v < 100) return v.toFixed(0);
+    return `${Math.round(v)}`;
+  }
+
+  private speedColor(tps: number, text: string, theme: Theme): string {
+    if (tps >= TpsMeter.FAST) return theme.fg("success", text);
+    if (tps >= TpsMeter.MED) return theme.fg("warning", text);
+    if (tps === 0) return theme.fg("dim", text);
+    return theme.fg("error", text);
+  }
+
+  private spin(): string {
+    const s = TpsMeter.SPIN[this.spinI];
+    this.spinI = (this.spinI + 1) % TpsMeter.SPIN.length;
+    return s;
+  }
+
+  sparkline(theme: Theme, len = TpsMeter.SPARK_LEN): string {
+    len = Math.max(1, Math.min(TpsMeter.SPARK_LEN, Math.floor(len)));
+
+    if (this.sparkLen === 0) {
+      return theme.fg("dim", TpsMeter.TRACK.repeat(len));
+    }
+
+    const available = Math.min(this.sparkLen, len);
+    const vals = new Float64Array(available);
+    for (let i = 0; i < available; i++) {
+      const idx =
+        (this.sparkHead - available + i + TpsMeter.SPARK_LEN) %
+        TpsMeter.SPARK_LEN;
+      vals[i] = this.sparkBuf[idx];
+    }
+
+    let mn = Infinity;
+    let mx = 0;
+    for (let i = 0; i < available; i++) {
+      const v = vals[i];
+      if (v < mn) mn = v;
+      if (v > mx) mx = v;
+    }
+    const range = mx - mn;
+    const pad = len - available;
+    let result = pad > 0 ? theme.fg("dim", TpsMeter.TRACK.repeat(pad)) : "";
+
+    for (let i = 0; i < available; i++) {
+      const v = vals[i];
+      const norm =
+        range < 1e-6
+          ? mx > 0
+            ? 4
+            : 0
+          : Math.min(7, Math.max(0, Math.round(((v - mn) / range) * 7)));
+      const ch = TpsMeter.BLOCKS[norm];
+      result += this.speedColor(v, ch, theme);
+    }
+    return result;
+  }
+
+  gauge(tps: number, theme: Theme, gaugeLen = TpsMeter.GAUGE_LEN): string {
+    gaugeLen = Math.max(1, Math.floor(gaugeLen));
+    const scale = Math.max(this.sparkMax, TpsMeter.GAUGE_FLOOR);
+    let frac = scale > 0 ? tps / scale : 0;
+    if (frac < 0) frac = 0;
+    if (frac > 1) frac = 1;
+
+    const eighths = Math.round(frac * gaugeLen * 8);
+    const full = (eighths / 8) | 0;
+    const rem = eighths % 8;
+
+    let fill = "█".repeat(Math.min(gaugeLen, full));
+    let used = Math.min(gaugeLen, full);
+    if (full < gaugeLen && rem > 0) {
+      fill += TpsMeter.HBLOCKS[rem];
+      used++;
+    }
+    const track = TpsMeter.TRACK.repeat(Math.max(0, gaugeLen - used));
+
+    return (
+      theme.fg("dim", "▕") +
+      this.speedColor(tps, fill, theme) +
+      theme.fg("dim", track + "▏")
+    );
+  }
+
+  isStreaming(): boolean {
+    return this.streaming;
+  }
+
+  renderLive(theme: Theme, maxBudget?: number): string {
+    const ref = this.firstTokenMs > 0 ? this.firstTokenMs : this.streamStartMs;
+    const elapsed = (this.now() - ref) / 1000;
+    const tps = elapsed > 0.3 ? this.streamTokens / elapsed : 0;
+
+    const s = theme.fg("accent", this.spin());
+    const num = this.speedColor(tps, this.fmt(tps), theme);
+    const unit = theme.fg("dim", "tps");
+    const numUnit = `${num} ${unit}`;
+    const minCompact = `${s} ${numUnit}`;
+    const bareNumUnit = numUnit;
+
+    if (maxBudget == null) {
+      const g = this.gauge(tps, theme, TpsMeter.GAUGE_LEN);
+      return `${s} ${g} ${numUnit}`;
+    }
+
+    if (maxBudget < visibleWidth(bareNumUnit)) {
+      return "";
+    }
+
+    // Attempt full mode with gauge
+    const fixedOverhead = visibleWidth(s) + 1 + 2 + 1 + visibleWidth(numUnit);
+    const availableGaugeLen = maxBudget - fixedOverhead;
+
+    if (availableGaugeLen >= 3) {
+      const targetGaugeLen = Math.min(TpsMeter.GAUGE_LEN, availableGaugeLen);
+      const g = this.gauge(tps, theme, targetGaugeLen);
+      const fullStr = `${s} ${g} ${numUnit}`;
+      if (visibleWidth(fullStr) <= maxBudget) {
+        return fullStr;
+      }
+    }
+
+    if (maxBudget >= visibleWidth(minCompact)) {
+      return minCompact;
+    }
+
+    return bareNumUnit;
+  }
+
+  renderFinal(theme: Theme, maxBudget?: number): string {
+    const avg = this.winAvg();
+    const mu = this.atMean();
+    const p95 = this.atP95();
+
+    const a = this.speedColor(avg, this.fmt(avg), theme);
+    const label = theme.fg("dim", "tps");
+    const numUnit = `${a} ${label}`;
+
+    if (maxBudget == null) {
+      const sp = this.sparkline(theme, TpsMeter.SPARK_LEN);
+      const sep = theme.fg("dim", "·");
+      const m = `${theme.fg("dim", "μ")} ${this.speedColor(mu, this.fmt(mu), theme)}`;
+      const p = `${theme.fg("dim", "p95")} ${this.speedColor(p95, this.fmt(p95), theme)}`;
+      return `${sp} ${numUnit} ${sep} ${m} ${sep} ${p}`;
+    }
+
+    if (maxBudget < visibleWidth(numUnit)) {
+      return "";
+    }
+
+    // 1. Attempt full mode (sparkline 12 + numUnit + μ + p95)
+    const spFull = this.sparkline(theme, TpsMeter.SPARK_LEN);
+    const sep = theme.fg("dim", "·");
+    const m = `${theme.fg("dim", "μ")} ${this.speedColor(mu, this.fmt(mu), theme)}`;
+    const p = `${theme.fg("dim", "p95")} ${this.speedColor(p95, this.fmt(p95), theme)}`;
+    const l3 = `${spFull} ${numUnit} ${sep} ${m} ${sep} ${p}`;
+    if (visibleWidth(l3) <= maxBudget) {
+      return l3;
+    }
+
+    // 2. Dynamic sparkline (length 12 down to 2)
+    const fixedOverhead = 1 + visibleWidth(numUnit);
+    const availableSparkLen = maxBudget - fixedOverhead;
+
+    if (availableSparkLen >= 2) {
+      const targetSparkLen = Math.min(TpsMeter.SPARK_LEN, availableSparkLen);
+      const sp = this.sparkline(theme, targetSparkLen);
+      const l2 = `${sp} ${numUnit}`;
+      if (visibleWidth(l2) <= maxBudget) {
+        return l2;
+      }
+    }
+
+    // 3. Bare numUnit fallback
+    return numUnit;
+  }
+
+  renderAdaptive(theme: Theme, maxBudget: number): string {
+    if (!this.enabled) return "";
+    if (this.streaming) {
+      return this.renderLive(theme, maxBudget);
+    }
+    return this.renderFinal(theme, maxBudget);
+  }
+
+  private startTick(ctx: ExtensionContext): void {
+    if (this.tickTimer) return;
+    this.tickTimer = setInterval(() => {
+      if (!this.streaming || !this.enabled) {
+        this.stopTick(ctx);
+        return;
+      }
+      const theme = ctx.ui?.theme ?? safeFallbackTheme;
+      this.applyStatus(ctx, this.renderLive(theme));
+    }, TpsMeter.STREAM_INTERVAL_MS);
+    (this.tickTimer as any)?.unref?.();
+  }
+
+  stopTick(ctx?: ExtensionContext): void {
+    this.streaming = false;
+    if (this.tickTimer) {
+      clearInterval(this.tickTimer);
+      this.tickTimer = null;
+    }
+    if (ctx && this.enabled) {
+      const theme = ctx.ui?.theme ?? safeFallbackTheme;
+      this.applyStatus(ctx, this.renderFinal(theme));
+    }
+  }
+
+  onMessageStart(ctx: ExtensionContext): void {
+    if (!this.enabled) return;
+    this.streamStartMs = this.now();
+    this.firstTokenMs = 0;
+    this.streamChars = 0;
+    this.streamTokens = 0;
+    this.streaming = true;
+    this.spinI = 0;
+    this.startTick(ctx);
+  }
+
+  onMessageUpdate(evt?: { type: string; delta?: unknown }): void {
+    if (!this.enabled || !evt) return;
+    if (evt.type === "text_delta" || evt.type === "thinking_delta") {
+      const d = evt.delta as string;
+      if (!d) return;
+      if (this.firstTokenMs === 0) this.firstTokenMs = this.now();
+      this.streamChars += d.length;
+      this.streamTokens = this.tokEst(this.streamChars);
+    }
+  }
+
+  onMessageEnd(usageOutput: number | undefined, ctx: ExtensionContext): void {
+    if (!this.enabled) return;
+    this.streaming = false;
+    this.stopTick();
+
+    const realOut = usageOutput;
+    const tokens =
+      typeof realOut === "number" && realOut > 0 ? realOut : this.streamTokens;
+
+    const ref = this.firstTokenMs > 0 ? this.firstTokenMs : this.streamStartMs;
+    const elapsed = (this.now() - ref) / 1000;
+    if (elapsed >= 0.1 && tokens > 0) {
+      const tps = tokens / elapsed;
+      this.winPush(tps, this.now());
+      this.atPush(tps);
+      this.sparkPush(tps);
+    }
+
+    const theme = ctx.ui?.theme ?? safeFallbackTheme;
+    const txt = this.renderFinal(theme);
+    this.applyStatus(ctx, txt || undefined);
+  }
+
+  onToolStart(ctx: ExtensionContext): void {
+    this.stopTick(ctx);
+  }
+
+  onTurnEnd(ctx?: ExtensionContext): void {
+    this.stopTick(ctx);
+  }
+
+  onAgentEnd(ctx?: ExtensionContext): void {
+    this.stopTick(ctx);
+  }
+
+  onAgentSettled(ctx?: ExtensionContext): void {
+    this.stopTick(ctx);
+  }
+}
+
+export const safeFallbackTheme: Theme = {
+  fg: (_color: string, text: string) => text,
+  bg: (_color: string, text: string) => text,
+  bold: (text: string) => text,
+} as unknown as Theme;
+

package/extensions/subagent/README.md

@@ -0,0 +1,35 @@
+# subagent
+
+Delegate tasks to independent, full-powered Pi workers. The `subagent` tool returns after launch; completion or questions are delivered back to the parent session asynchronously.
+
+## Install
+
+```sh
+pi install npm:@rol1n/subagent
+```
+
+Also included in `@rol1n/pi-kit`. The parent and workers require the `pi` executable on PATH and their normal Pi authentication.
+
+## Use
+
+```json
+{"action":"spawn","name":"reviewer","cwd":"/existing/project","task":"Review the changed files and report findings."}
+{"action":"send","target":"reviewer","task":"Also inspect the error handling."}
+{"action":"stop","target":"reviewer"}
+```
+
+`model` optionally selects a worker model. `/subagent` shows active workers. Each worker inherits its own normal Pi capabilities; this is a delegation runtime, not a restricted execution environment.
+
+## Backends
+
+| Variable | Behavior |
+|---|---|
+| `PI_SUBAGENT_BACKEND=process` | Run silent background processes |
+| `PI_SUBAGENT_MUX=tmux` | Prefer tmux when running inside an available tmux session |
+| `PI_SUBAGENT_MUX=zellij` | Prefer Zellij when running inside an available Zellij session |
+
+Without a usable multiplexer, the worker backend falls back to a background process. Native Windows supports PowerShell launch commands and Zellij panes; tmux is for POSIX environments. Session transcripts and task artifacts are stored under `~/.pi/agent/`.
+
+## Other delegation packages
+
+Use [multi-harness](https://github.com/RolinShmily/pi-kit/tree/main/extensions/multi-harness) for Codex, Claude, or OpenCode peers. That package shares multiplexer helpers but provides a separate tool and does not automatically enable this extension's entrypoint. The bundled subagent skill file is reference material and is not registered by the package manifest.

package/extensions/subagent/bridge.ts

@@ -0,0 +1,171 @@
+/**
+ * subagent/bridge.ts — Subagent Worker Bridge
+ *
+ * Loaded exclusively inside the spawned worker Pi process via `-e <bridgePath>`.
+ * - Grants the worker an `ask_question` tool to consult the parent orchestrator.
+ * - Handles auto-exit on task completion (calling ctx.shutdown() so the pane closes cleanly).
+ * - Suppresses auto-exit while waiting for the parent's answer to `ask_question`.
+ * - Prevents recursive subagent spawning.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Box, Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import { existsSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+
+export default function subagentBridge(pi: ExtensionAPI) {
+  if (process.env.PI_SUBAGENT_ACTIVE !== "1") {
+    return;
+  }
+
+  const workerName = process.env.PI_SUBAGENT_NAME || "worker";
+  const sessionFile = process.env.PI_SUBAGENT_SESSION;
+
+  let awaitingAnswer = false;
+
+  // Render a minimal indicator in the child worker's terminal
+  pi.on("session_start", (_event, ctx) => {
+    ctx.ui.setWidget(
+      "subagent-worker-banner",
+      (_tui, theme) => {
+        const box = new Box(1, 0, (text: string) => {
+          try {
+            return theme.bg("toolSuccessBg", text);
+          } catch {
+            return text;
+          }
+        });
+        const badge = theme.bold(theme.fg("accent", `[Worker: ${workerName}]`));
+        const hint = theme.fg("dim", " · Full Pi worker · ask_question available");
+        box.addChild(new Text(`${badge}${hint}`, 0, 0));
+        return box;
+      },
+      { placement: "aboveEditor" },
+    );
+  });
+
+  // When input arrives (e.g. parent reply or manual steer), answer is received
+  pi.on("input", () => {
+    awaitingAnswer = false;
+  });
+
+  pi.on("agent_start", () => {
+    awaitingAnswer = false;
+  });
+
+  pi.on("agent_end", (event, ctx) => {
+    if (awaitingAnswer) {
+      // Park in waiting state, do not exit
+      return;
+    }
+
+    const messages = (event as any).messages as any[] | undefined;
+    let errorMessage: string | undefined;
+
+    if (messages && messages.length > 0) {
+      for (let i = messages.length - 1; i >= 0; i--) {
+        const msg = messages[i];
+        if (msg?.role === "assistant") {
+          if (msg.stopReason === "error") {
+            errorMessage = typeof msg.errorMessage === "string" ? msg.errorMessage : "Agent ended with error";
+          }
+          break;
+        }
+      }
+    }
+
+    if (sessionFile) {
+      try {
+        writeFileSync(
+          `${sessionFile}.exit`,
+          JSON.stringify({
+            type: errorMessage ? "error" : "done",
+            ...(errorMessage ? { errorMessage } : {}),
+          }),
+        );
+      } catch {
+        // best effort
+      }
+    }
+
+    ctx.shutdown();
+  });
+
+  // Register `ask_question` tool
+  pi.registerTool({
+    name: "ask_question",
+    label: "Ask Orchestrator",
+    description:
+      "Ask the orchestrator (the parent agent that spawned you) a clarifying question and pause until they reply. " +
+      "Use when requirements are ambiguous, a critical decision needs confirmation, or you are blocked. " +
+      "Your session stays open while you wait — the answer will arrive as your next turn message.",
+    parameters: Type.Object({
+      question: Type.String({
+        description: "The question for the parent orchestrator. Include enough context for them to decide.",
+      }),
+    }),
+    async execute(_toolCallId, params, signal) {
+      if (!sessionFile) {
+        throw new Error("ask_question is only available within a managed subagent session.");
+      }
+
+      awaitingAnswer = true;
+      const askFile = `${sessionFile}.ask`;
+      const replyFile = `${sessionFile}.reply`;
+
+      const askData = {
+        name: workerName,
+        question: params.question,
+        timestamp: new Date().toISOString(),
+      };
+
+      writeFileSync(askFile, JSON.stringify(askData));
+
+      try {
+        while (!existsSync(replyFile)) {
+          if (signal?.aborted) {
+            throw new Error("Cancelled while waiting for parent reply");
+          }
+          await new Promise<void>((resolve, reject) => {
+            const timer = setTimeout(resolve, 200);
+            if (signal) {
+              const onAbort = () => {
+                clearTimeout(timer);
+                signal.removeEventListener("abort", onAbort);
+                reject(new Error("Cancelled while waiting for parent reply"));
+              };
+              signal.addEventListener("abort", onAbort, { once: true });
+            }
+          });
+        }
+
+        const reply = readFileSync(replyFile, "utf-8");
+        try {
+          unlinkSync(replyFile);
+        } catch {}
+        awaitingAnswer = false;
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Orchestrator answer:\n\n${reply}`,
+            },
+          ],
+          details: { question: params.question, reply },
+        };
+      } finally {
+        awaitingAnswer = false;
+        try {
+          if (existsSync(askFile)) unlinkSync(askFile);
+        } catch {}
+      }
+    },
+    renderCall(args, theme) {
+      const text =
+        theme.fg("toolTitle", theme.bold("ask_question ")) +
+        theme.fg("muted", String((args as any).question ?? ""));
+      return new Text(text, 0, 0);
+    },
+  });
+}