shariq-pi-extensions 0.1.0

package/extensions/shared/tui-dashboard.ts

@@ -0,0 +1,139 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+
+export type SemanticState =
+  | "active"
+  | "success"
+  | "warning"
+  | "error"
+  | "muted";
+
+const STATE_COLORS = {
+  active: "accent",
+  success: "success",
+  warning: "warning",
+  error: "error",
+  muted: "muted",
+} as const;
+
+export function stateDot(theme: Theme, state: SemanticState): string {
+  return theme.fg(STATE_COLORS[state], "●");
+}
+
+export function stateLabel(
+  theme: Theme,
+  state: SemanticState,
+  label: string,
+): string {
+  return `${stateDot(theme, state)} ${theme.fg(STATE_COLORS[state], label)}`;
+}
+
+export function sanitizeTerminalText(text: string): string {
+  return text
+    .replace(/(?:\u001b\]|\u009d)(?:[^\u0007\u001b\u009c]|\u001b(?!\\))*(?:\u0007|\u001b\\|\u009c)/g, "")
+    .replace(/(?:\u001b\[|\u009b)[0-?]*[ -/]*[@-~]/g, "")
+    .replace(/\u001b(?:[()][0-2A-Z]|[ -/]*[@-~])/g, "")
+    .replaceAll("\t", "  ")
+    .replace(/[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/g, "");
+}
+
+export function oneLine(text: string): string {
+  return sanitizeTerminalText(text).replace(/\s+/g, " ").trim();
+}
+
+export function padLine(text: string, width: number): string {
+  const safeWidth = Math.max(0, width);
+  const truncated = truncateToWidth(text, safeWidth, "");
+  return truncated + " ".repeat(Math.max(0, safeWidth - visibleWidth(truncated)));
+}
+
+export function joinSides(left: string, right: string, width: number): string {
+  const safeWidth = Math.max(0, width);
+  const rightWidth = visibleWidth(right);
+  if (rightWidth >= safeWidth) return truncateToWidth(right, safeWidth);
+  const leftWidth = Math.max(0, safeWidth - rightWidth - 1);
+  const fittedLeft = truncateToWidth(left, leftWidth, "…");
+  return truncateToWidth(
+    fittedLeft + " ".repeat(Math.max(1, safeWidth - visibleWidth(fittedLeft) - rightWidth)) + right,
+    safeWidth,
+  );
+}
+
+export function rule(theme: Theme, width: number, accent = false): string {
+  return theme.fg(accent ? "borderAccent" : "border", "─".repeat(Math.max(0, width)));
+}
+
+export function framedRow(
+  theme: Theme,
+  content: string,
+  width: number,
+  selected = false,
+): string {
+  const innerWidth = Math.max(0, width - 2);
+  const body = padLine(content, innerWidth);
+  const row = `${theme.fg(selected ? "borderAccent" : "border", "│")}${body}${theme.fg(selected ? "borderAccent" : "border", "│")}`;
+  return selected ? theme.bg("selectedBg", row) : row;
+}
+
+export function frameTop(theme: Theme, width: number, title = ""): string {
+  const inner = Math.max(0, width - 2);
+  const label = title ? ` ${oneLine(title)} ` : "";
+  const fitted = truncateToWidth(label, Math.max(0, inner - 1), "…");
+  return (
+    theme.fg("border", "╭") +
+    (fitted ? theme.fg("muted", fitted) : "") +
+    theme.fg("border", "─".repeat(Math.max(0, inner - visibleWidth(fitted)))) +
+    theme.fg("border", "╮")
+  );
+}
+
+export function frameBottom(theme: Theme, width: number): string {
+  return (
+    theme.fg("border", "╰") +
+    theme.fg("border", "─".repeat(Math.max(0, width - 2))) +
+    theme.fg("border", "╯")
+  );
+}
+
+export function meter(
+  theme: Theme,
+  value: number,
+  total: number,
+  width: number,
+  state: SemanticState = "active",
+): string {
+  const safeWidth = Math.max(3, width);
+  const ratio = total > 0 ? Math.min(1, Math.max(0, value / total)) : 0;
+  const percent = Math.round(ratio * 100);
+  const percentText = `${percent}%`;
+  const barWidth = Math.max(1, safeWidth - percentText.length - 1);
+  const filled = Math.min(barWidth, Math.round(barWidth * ratio));
+  const bar =
+    theme.fg(STATE_COLORS[state], "━".repeat(filled)) +
+    theme.fg("borderMuted", "─".repeat(Math.max(0, barWidth - filled)));
+  return `${bar} ${theme.fg("muted", percentText)}`;
+}
+
+export function formatDurationMs(milliseconds: number): string {
+  const seconds = Math.max(0, Math.floor(milliseconds / 1000));
+  const hours = Math.floor(seconds / 3600);
+  const minutes = Math.floor((seconds % 3600) / 60);
+  const remainder = seconds % 60;
+  if (hours > 0) return `${hours}h ${minutes.toString().padStart(2, "0")}m`;
+  if (minutes > 0) return `${minutes}m ${remainder.toString().padStart(2, "0")}s`;
+  return `${remainder}s`;
+}
+
+export function viewportSlice<T>(
+  items: ReadonlyArray<T>,
+  selectedIndex: number,
+  height: number,
+): { start: number; items: ReadonlyArray<T> } {
+  const safeHeight = Math.max(0, height);
+  if (items.length <= safeHeight) return { start: 0, items };
+  const start = Math.min(
+    Math.max(0, selectedIndex - Math.floor(safeHeight / 2)),
+    Math.max(0, items.length - safeHeight),
+  );
+  return { start, items: items.slice(start, start + safeHeight) };
+}

package/extensions/shell-shortcuts/README.md

@@ -0,0 +1,17 @@
+# Pi shell shortcuts
+
+Small always-on quality-of-life features for local Pi.
+
+## Features
+
+- `features/exit-alias.ts` — adds `/exit` as an alias for `/quit`.
+
+## Removed
+
+- `features/native-max-thinking.ts` was removed because Pi 0.80.7 supports `--thinking max` natively.
+
+## When to add here
+
+Add tiny, low-risk workflow conveniences here when they do not deserve a standalone extension.
+
+Keep larger or security-sensitive systems separate, such as provider auth, web search, subagents, MCP, and persistent goals.

package/extensions/shell-shortcuts/features/exit-alias.ts

@@ -0,0 +1,10 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+export default function exitAliasExtension(pi: ExtensionAPI) {
+	pi.registerCommand("exit", {
+		description: "Alias for /quit",
+		handler: async (_args, ctx) => {
+			ctx.shutdown();
+		},
+	});
+}

package/extensions/shell-shortcuts/index.ts

@@ -0,0 +1,6 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import exitAliasExtension from "./features/exit-alias.ts";
+
+export default function qolExtension(pi: ExtensionAPI) {
+  exitAliasExtension(pi);
+}

package/extensions/subagents/README.md

@@ -0,0 +1,89 @@
+# Pi subagents
+
+A Pi-only subagent system with an Effect-managed lifecycle, persistent child sessions, configurable profiles, context forks, resumability, worktree isolation, and a live takeover dashboard.
+
+## Topology
+
+The system is deliberately flat. Only the main Pi thread can spawn subagents. Children may list and message existing peers through the main-thread manager, but they do not receive spawn, agent-management, or workflow tools. This permits collaboration without recursive fan-out or runaway agent trees.
+
+## Parent tools
+
+- `spawn_agent` — start a background child with an optional profile, persona, capability mode, context fork, model override, or isolated worktree
+- `wait_agent` — collect results already available and report running children as pending without blocking
+- `close_agent` — interrupt children while retaining their transcripts
+- `check_agent` — inspect live activity without waiting
+- `list_agent_profiles` — discover active profiles, personas, defaults, and concurrency
+- `list_agents` — list live and globally archived/resumable children
+- `send_message` — steer a running child or start its next turn
+- `apply_agent_changes` — inspect, patch, cherry-pick, merge, or discard an isolated child worktree
+- `reply_question` — answer a child’s blocking `ask_parent` request
+- `task` — atomically reserve capacity for up to the configured limit (maximum 50), start the fan-out in the background, and return child ids immediately
+
+Child sessions receive `message_parent`, `ask_parent`, `list_peers`, and `message_peer`. Peer messages are routed through the main-thread manager and can steer a running child or continue a settled one; they cannot create agents. Background completions wake the parent automatically, so the main turn can continue independent work or end and remain available to the user.
+
+## Profiles and capabilities
+
+Built-in profiles:
+
+- `general-purpose` — unrestricted coding worker
+- `explore` — investigation with read and command execution, but no file edits
+- `plan` — investigation followed by a concrete implementation plan, with no file edits
+
+Capability modes:
+
+- `read-only` — allowlisted read/search and parent-communication tools only
+- `read-write` — the read-only allowlist plus direct file write/edit tools, without shell execution
+- `execute` — the read-only allowlist plus shell and background-terminal execution, without direct file edit tools
+- `all` — full child tool access
+
+Restrictive modes fail closed: newly registered extension tools remain unavailable until they are explicitly classified. This prevents another extension from silently bypassing the selected capability.
+
+Optional user profiles and personas can be defined in `~/.pi/agent/subagents.json`. Trusted projects may override them in `.pi/subagents.json`:
+
+```json
+{
+  "maxConcurrent": 6,
+  "profiles": {
+    "reviewer": {
+      "description": "Review changes without editing",
+      "instructions": "Find correctness and regression risks. Cite files and lines.",
+      "capability": "execute"
+    }
+  },
+  "personas": {
+    "concise": {
+      "instructions": "Return only findings, evidence, and the recommended action."
+    }
+  }
+}
+```
+
+Project configuration is ignored when the project is not trusted. Concurrency is bounded to 1–50; this private package defaults to 50. `/subagents profiles` provides discovery, while `/subagents config` opens a validated editor for global or trusted-project configuration.
+
+## Context and continuation
+
+New children start with independent context by default. `fork_turns` may be `all` or a positive number of recent user turns. Forking keeps user messages and final assistant text while removing thinking, tool calls, and tool results so the child never inherits an unresolved tool protocol.
+
+Every child uses a persistent Pi session file. `resume_from` continues a completed child with its full transcript, tool state, and logical agent id, including after a parent `/reload` or resume. Non-secret metadata is stored both in the parent session and in `~/.pi/agent/subagents/catalog.json`, so children created by an ephemeral or different parent process remain discoverable. Existing legacy ids remain valid catalog keys.
+
+## Worktree isolation
+
+Children share the requested workspace by default. Use `isolation: "worktree"` only when the user requests it, a configured profile requires it, or concurrent write tasks are likely to overlap or interfere. Read-only work and edits to clearly separate areas should stay in the shared workspace.
+
+`isolation: "worktree"` requires a clean source checkout, then creates a dedicated branch and persistent git worktree from `HEAD` under `~/.pi/agent/subagent-worktrees/`. A dirty source is rejected rather than silently giving the child stale code; commit or stash first, or use the shared workspace. `apply_agent_changes` supports `inspect`, checked patch application, commit-preserving cherry-pick, merge, and permanent discard. Cherry-pick and merge first run in a temporary worktree; conflicts leave the source checkout unchanged. Discard requires confirmation in interactive mode. A failed spawn removes the worktree it created; completed worktrees remain available for inspection or continuation.
+
+## UI
+
+`/subagents` or `/subagents agents` opens the live operations dashboard and takeover UI. `/btw <question>` starts a read-only, context-aware side investigation owned by the user; it opens directly in takeover view and records its answer without waking the parent model. Wide terminals use a split-pane agent list and selected-agent inspector with running/completed/failed counts, model/profile/access metadata, a context meter, current tool activity, queue state, elapsed time, turns, cwd, and latest output. The takeover view adds a live transcript, context meter, active-tool state, scrolling, child interruption, and follow-up input. `/subagents peers` shows the persistent peer-message audit trail. `/subagents profiles` browses profiles and personas, and `/subagents config` edits validated configuration.
+
+## Architecture
+
+- `src/manager.ts` — Effect service, bounded lifecycle, normalized snapshots, cancellation, and retention
+- `src/backends/pi.ts` — in-process Pi sessions, trust-gated resources, capability filtering, context seeding, resume, and parent bridge
+- `src/config.ts` — built-in and user/project profiles, personas, validation, and limits
+- `src/catalog.ts` — global non-secret resumable-agent catalog
+- `src/context.ts` — safe context-fork selection and profile prompt assembly
+- `src/worktree.ts` — isolated worktree creation, inspection, conflict preflight, integration, and cleanup
+- `src/runtime.ts` — managed runtime and Pi backend registry
+- `src/ui/` — dashboard, transcript, and takeover components
+- `src/result-delivery.ts` — deferred automatic result delivery