shariq-pi-extensions 0.1.0

package/extensions/goal/index.ts

@@ -0,0 +1,2 @@
+import goalExtension from "./extension.ts";
+export default goalExtension;

package/extensions/goal/types.ts

@@ -0,0 +1,56 @@
+export type GoalStatus = "active" | "paused" | "blocked" | "usage_limited" | "budget_limited" | "complete";
+export type GoalProgressStatus = "pending" | "in_progress" | "complete" | "blocked";
+export type GoalSuppressionReason = "no_tool_progress" | "interrupted" | "error";
+
+export type GoalProgressItem = {
+  id: string;
+  title: string;
+  status: GoalProgressStatus;
+  evidence?: string;
+  updatedAt: number;
+};
+
+export type GoalContinuationSuppression = {
+  reason: GoalSuppressionReason;
+  message: string;
+  at: number;
+};
+
+export type GoalState = {
+  id: string;
+  objective: string;
+  status: GoalStatus;
+  tokenBudget: number | null;
+  tokensUsed: number;
+  timeUsedSeconds: number;
+  createdAt: number;
+  updatedAt: number;
+  activeStartedAt: number | null;
+  progress: GoalProgressItem[];
+  blockedTurnStreak: number;
+  blockedSignature: string | null;
+  continuationSuppressed: GoalContinuationSuppression | null;
+};
+
+export type GoalSnapshot = {
+  goal: GoalState | null;
+};
+
+export type GoalCreateParams = {
+  objective: string;
+  token_budget?: number;
+};
+
+export type GoalUpdateParams = {
+  status: "complete" | "blocked";
+};
+
+export type GoalProgressParams = {
+  items: Array<{
+    id: string;
+    title: string;
+    status: GoalProgressStatus;
+    evidence?: string;
+  }>;
+  remove_ids?: string[];
+};

package/extensions/goal/ui.ts

@@ -0,0 +1,334 @@
+import type {
+  ExtensionCommandContext,
+  KeybindingsManager,
+  Theme,
+} from "@earendil-works/pi-coding-agent";
+import type { Component, TUI } from "@earendil-works/pi-tui";
+import { truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import {
+  frameBottom,
+  framedRow,
+  frameTop,
+  joinSides,
+  meter,
+  oneLine,
+  padLine,
+  stateLabel,
+  type SemanticState,
+  viewportSlice,
+} from "../shared/tui-dashboard.ts";
+import type { GoalProgressItem, GoalState, GoalStatus } from "./types.ts";
+
+export type GoalDashboardAction =
+  | "close"
+  | "edit"
+  | "pause"
+  | "resume"
+  | "clear";
+
+interface GoalDashboardOptions {
+  getGoal(): GoalState | null;
+  elapsedSeconds(goal: GoalState): number;
+  formatTokens(tokens: number): string;
+}
+
+function configuredKeys(
+  keybindings: KeybindingsManager,
+  binding: Parameters<KeybindingsManager["getKeys"]>[0],
+): string {
+  return keybindings.getKeys(binding).join("/") || "unbound";
+}
+
+function statusState(status: GoalStatus): SemanticState {
+  switch (status) {
+    case "active":
+      return "active";
+    case "complete":
+      return "success";
+    case "blocked":
+    case "usage_limited":
+    case "budget_limited":
+      return "warning";
+    case "paused":
+      return "muted";
+  }
+}
+
+function progressState(item: GoalProgressItem): SemanticState {
+  switch (item.status) {
+    case "complete":
+      return "success";
+    case "blocked":
+      return "error";
+    case "in_progress":
+      return "active";
+    case "pending":
+      return "muted";
+  }
+}
+
+function progressColor(item: GoalProgressItem): "accent" | "success" | "warning" | "error" | "muted" {
+  switch (progressState(item)) {
+    case "active":
+      return "accent";
+    case "success":
+      return "success";
+    case "error":
+      return "error";
+    case "warning":
+      return "warning";
+    case "muted":
+      return "muted";
+  }
+}
+
+function progressGlyph(item: GoalProgressItem): string {
+  switch (item.status) {
+    case "complete":
+      return "✓";
+    case "blocked":
+      return "!";
+    case "in_progress":
+      return "◆";
+    case "pending":
+      return "○";
+  }
+}
+
+function formatElapsed(seconds: number): string {
+  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 class GoalDashboard implements Component {
+  private selected = 0;
+  private closed = false;
+  private readonly ticker: ReturnType<typeof setInterval>;
+  private readonly tui: TUI;
+  private readonly theme: Theme;
+  private readonly keybindings: KeybindingsManager;
+  private readonly options: GoalDashboardOptions;
+  private readonly done: (action: GoalDashboardAction) => void;
+
+  constructor(
+    tui: TUI,
+    theme: Theme,
+    keybindings: KeybindingsManager,
+    options: GoalDashboardOptions,
+    done: (action: GoalDashboardAction) => void,
+  ) {
+    this.tui = tui;
+    this.theme = theme;
+    this.keybindings = keybindings;
+    this.options = options;
+    this.done = done;
+    this.ticker = setInterval(() => this.tui.requestRender(), 1000);
+    this.ticker.unref?.();
+  }
+
+  private close(action: GoalDashboardAction): void {
+    if (this.closed) return;
+    this.closed = true;
+    clearInterval(this.ticker);
+    this.done(action);
+  }
+
+  dispose(): void {
+    if (!this.closed) clearInterval(this.ticker);
+    this.closed = true;
+  }
+
+  handleInput(data: string): void {
+    const goal = this.options.getGoal();
+    const progress = goal?.progress ?? [];
+    this.selected = Math.min(this.selected, Math.max(0, progress.length - 1));
+
+    if (
+      this.keybindings.matches(data, "tui.select.cancel") ||
+      data === "q"
+    ) {
+      this.close("close");
+      return;
+    }
+    if (this.keybindings.matches(data, "tui.select.up") || data === "k") {
+      if (progress.length > 0) {
+        this.selected = (this.selected - 1 + progress.length) % progress.length;
+        this.tui.requestRender();
+      }
+      return;
+    }
+    if (this.keybindings.matches(data, "tui.select.down") || data === "j") {
+      if (progress.length > 0) {
+        this.selected = (this.selected + 1) % progress.length;
+        this.tui.requestRender();
+      }
+      return;
+    }
+    if (data === "e") {
+      this.close("edit");
+      return;
+    }
+    if (data === "x") {
+      this.close("clear");
+      return;
+    }
+    if (data === "p" || data === " ") {
+      if (goal?.status === "active") this.close("pause");
+      else if (goal && goal.status !== "complete" && goal.status !== "budget_limited") {
+        this.close("resume");
+      }
+      return;
+    }
+    if (data === "r" && goal && goal.status !== "active" && goal.status !== "complete") {
+      this.close("resume");
+    }
+  }
+
+  render(width: number): string[] {
+    const theme = this.theme;
+    const goal = this.options.getGoal();
+    if (!goal) {
+      return [
+        frameTop(theme, width, "Goal"),
+        framedRow(theme, theme.fg("muted", "No goal is currently set."), width),
+        frameBottom(theme, width),
+      ];
+    }
+
+    const rows = this.tui.terminal.rows || 30;
+    const completed = goal.progress.filter((item) => item.status === "complete").length;
+    const current = goal.progress.find((item) => item.status === "in_progress");
+    const status = stateLabel(theme, statusState(goal.status), goal.status.replaceAll("_", " "));
+    const elapsed = formatElapsed(this.options.elapsedSeconds(goal));
+    const titleLeft = theme.fg("accent", theme.bold("Goal control center"));
+    const titleRight = `${status}${theme.fg("dim", ` · ${elapsed}`)}`;
+    const lines: string[] = [joinSides(`  ${titleLeft}`, `${titleRight}  `, width)];
+
+    const progressText = goal.progress.length > 0
+      ? `${completed}/${goal.progress.length} complete`
+      : "checklist not started";
+    const progressMeter = goal.progress.length > 0
+      ? meter(theme, completed, goal.progress.length, Math.min(28, Math.max(12, width - 48)), completed === goal.progress.length ? "success" : "active")
+      : theme.fg("borderMuted", "────────");
+    lines.push(
+      joinSides(
+        `  ${theme.fg("muted", "PROGRESS")}  ${progressMeter} ${theme.fg("text", progressText)}`,
+        goal.tokenBudget == null
+          ? `${theme.fg("muted", "TOKENS")} ${theme.fg("text", this.options.formatTokens(goal.tokensUsed))}  `
+          : `${theme.fg("muted", "BUDGET")} ${theme.fg("text", `${this.options.formatTokens(goal.tokensUsed)} / ${this.options.formatTokens(goal.tokenBudget)}`)}  `,
+        width,
+      ),
+    );
+    if (goal.tokenBudget != null && width >= 72) {
+      lines.push(
+        `  ${theme.fg("muted", "TOKEN BUDGET")}  ${meter(theme, goal.tokensUsed, goal.tokenBudget, Math.max(12, width - 24), goal.tokensUsed >= goal.tokenBudget ? "warning" : "active")}`,
+      );
+    }
+
+    lines.push(frameTop(theme, width, "objective"));
+    const objectiveWidth = Math.max(10, width - 4);
+    const objectiveLines = wrapTextWithAnsi(oneLine(goal.objective), objectiveWidth).slice(0, 3);
+    for (const line of objectiveLines) {
+      lines.push(framedRow(theme, ` ${theme.fg("text", line)}`, width));
+    }
+    if (objectiveLines.length === 0) lines.push(framedRow(theme, "", width));
+    lines.push(frameBottom(theme, width));
+
+    const chromeRows = lines.length + 5;
+    const detailRows = current || goal.continuationSuppressed || goal.blockedTurnStreak > 0 ? 2 : 0;
+    const listHeight = Math.max(3, rows - chromeRows - detailRows);
+    lines.push(frameTop(theme, width, `checklist · ${completed}/${goal.progress.length}`));
+
+    if (goal.progress.length === 0) {
+      lines.push(
+        framedRow(
+          theme,
+          ` ${theme.fg("muted", "No checklist yet — the agent creates one for meaningful multi-step work.")}`,
+          width,
+        ),
+      );
+      for (let index = 1; index < listHeight; index++) lines.push(framedRow(theme, "", width));
+    } else {
+      this.selected = Math.min(this.selected, goal.progress.length - 1);
+      const viewport = viewportSlice(goal.progress, this.selected, listHeight);
+      for (let row = 0; row < listHeight; row++) {
+        const item = viewport.items[row];
+        if (!item) {
+          lines.push(framedRow(theme, "", width));
+          continue;
+        }
+        const index = viewport.start + row;
+        const selected = index === this.selected;
+        const marker = selected ? theme.fg("accent", "❯") : " ";
+        const glyph = theme.fg(progressColor(item), progressGlyph(item));
+        const id = theme.fg("dim", `[${oneLine(item.id)}]`);
+        const itemStatus = theme.fg(
+          progressColor(item),
+          item.status.replaceAll("_", " "),
+        );
+        const right = `${itemStatus} `;
+        const left = ` ${marker} ${glyph} ${id} ${selected ? theme.fg("accent", oneLine(item.title)) : theme.fg("text", oneLine(item.title))}`;
+        lines.push(framedRow(theme, joinSides(left, right, Math.max(0, width - 2)), width, selected));
+      }
+    }
+    lines.push(frameBottom(theme, width));
+
+    const selectedItem = goal.progress[this.selected];
+    if (selectedItem?.evidence) {
+      lines.push(
+        truncateToWidth(
+          `  ${theme.fg("success", "evidence")} ${theme.fg("muted", oneLine(selectedItem.evidence))}`,
+          width,
+        ),
+      );
+    } else if (goal.continuationSuppressed) {
+      lines.push(
+        truncateToWidth(
+          `  ${theme.fg("warning", "waiting")} ${theme.fg("muted", oneLine(goal.continuationSuppressed.message))}`,
+          width,
+        ),
+      );
+    } else if (goal.blockedTurnStreak > 0) {
+      lines.push(
+        `  ${theme.fg("warning", `blocked gate ${goal.blockedTurnStreak}/3 turns`)}`,
+      );
+    }
+
+    const toggle = goal.status === "active" ? "p pause" : goal.status === "complete" ? "" : "r resume";
+    const hints = [
+      `${configuredKeys(this.keybindings, "tui.select.up")}/${configuredKeys(this.keybindings, "tui.select.down")}/jk select`,
+      toggle,
+      "e edit",
+      "x clear",
+      `${configuredKeys(this.keybindings, "tui.select.cancel")} close`,
+    ].filter(Boolean).join(" · ");
+    lines.push(truncateToWidth(theme.fg("dim", `  ${hints}`), width));
+    return lines.map((line) => padLine(line, width));
+  }
+
+  invalidate(): void {}
+}
+
+export async function openGoalDashboard(
+  ctx: ExtensionCommandContext,
+  options: GoalDashboardOptions,
+): Promise<GoalDashboardAction> {
+  if (ctx.mode !== "tui") return "close";
+  return ctx.ui.custom<GoalDashboardAction>(
+    (tui, theme, keybindings, done) =>
+      new GoalDashboard(tui, theme, keybindings, options, done),
+    {
+      overlay: true,
+      overlayOptions: {
+        anchor: "center",
+        width: "100%",
+        minWidth: 48,
+        maxHeight: "100%",
+      },
+    },
+  );
+}

package/extensions/orchestration/README.md

@@ -0,0 +1,58 @@
+# Orchestration
+
+Orchestration coordinates large, explicitly requested software tasks through one dedicated orchestrator and configurable specialist agents. It uses the suite's Subagents runtime rather than creating a competing execution system.
+
+## Workflow
+
+1. Open `/orchestration`, choose **New**, and describe the objective.
+2. The dedicated orchestrator creates a dependency-aware plan and routes tasks to explorer, frontend, backend, or general workers.
+3. Review the plan in the dashboard. Give feedback if needed, then approve it once.
+4. Workers run autonomously. Git-backed writing tasks use one worktree per task; non-Git projects allow only one writer at a time.
+5. The configured reviewer checks each task, may make small obvious fixes, and sends larger findings back to the same worker session with its existing context.
+6. Reviewed changes integrate into a temporary orchestration branch. A final holistic review gates application to the source checkout.
+7. The extension applies the reviewed result without committing or pushing.
+
+The orchestrator sleeps while agents work and wakes automatically at execution boundaries. It asks the user only for a genuine blocker or scope-changing decision.
+
+## Roles and settings
+
+Use `/orchestration settings` to choose a global provider/model and thinking level for:
+
+- orchestrator
+- explorer
+- frontend worker
+- backend worker
+- general worker
+- reviewer
+
+Settings are stored with restrictive permissions under Pi's active agent directory at `orchestration/settings.json`. They apply globally and are changed only through the settings UI.
+
+Each project has up to 10 concurrent worker, explorer, or reviewer sessions. The dedicated orchestrator does not consume one of those slots. Multiple projects may run concurrently with independent pools.
+
+## Dashboard
+
+`/orchestration` opens the full-screen operations dashboard.
+
+- `j` / `k`: select a run
+- `Enter`: inspect tasks and reviews
+- `n`: create a run
+- `s`: configure role models
+- `a`: approve the initial plan
+- `f`: give plan feedback
+- `p`: pause, resume, or recover
+- `x`: cancel while preserving artifacts
+- `Esc`: go back or close
+
+Interrupted runs recover in a paused state and require explicit resume. Run state is machine-local under Pi's active agent directory at `orchestration/runs/<run-id>/`.
+
+## Safety boundaries
+
+- Orchestration starts only from `/orchestration` or an explicit natural-language request.
+- A Git source checkout must be clean before writing begins.
+- Writing workers never share a Git worktree.
+- Reviewers make only small localized fixes; larger fixes return to the original worker session.
+- A task gets at most two automatic fix rounds before the run blocks.
+- Source changes integrate sequentially only after review.
+- The extension never commits or pushes the source repository.
+- Agent thinking is not copied into orchestration artifacts.
+- Disabling Subagents makes Orchestration unavailable rather than falling back to another runtime.

package/extensions/orchestration/dashboard.ts

@@ -0,0 +1,192 @@
+import type {
+  ExtensionContext,
+  KeybindingsManager,
+} from "@earendil-works/pi-coding-agent";
+import {
+  Key,
+  matchesKey,
+  truncateToWidth,
+  visibleWidth,
+  type TUI,
+} from "@earendil-works/pi-tui";
+import type { OrchestrationEngine } from "./engine.ts";
+import type { OrchestrationRun } from "./types.ts";
+
+interface DashboardActions {
+  create(): void;
+  settings(): void;
+  feedback(run: OrchestrationRun): void;
+  approve(run: OrchestrationRun): void;
+  togglePause(run: OrchestrationRun): void;
+  cancel(run: OrchestrationRun): void;
+}
+
+type Theme = ExtensionContext["ui"]["theme"];
+
+class OrchestrationDashboard {
+  private selected = 0;
+  private detail = false;
+  private unsubscribe: () => void;
+  private readonly tui: TUI;
+  private readonly theme: Theme;
+  private readonly keys: KeybindingsManager;
+  private readonly engine: OrchestrationEngine;
+  private readonly actions: DashboardActions;
+  private readonly close: () => void;
+
+  constructor(
+    tui: TUI,
+    theme: Theme,
+    keys: KeybindingsManager,
+    engine: OrchestrationEngine,
+    actions: DashboardActions,
+    close: () => void,
+  ) {
+    this.tui = tui;
+    this.theme = theme;
+    this.keys = keys;
+    this.engine = engine;
+    this.actions = actions;
+    this.close = close;
+    this.unsubscribe = engineChangeSubscription(engine, () => tui.requestRender());
+  }
+
+  dispose() {
+    this.unsubscribe();
+  }
+
+  invalidate() {}
+
+  handleInput(data: string) {
+    const runs = this.engine.list();
+    if (matchesKey(data, Key.escape)) {
+      if (this.detail) this.detail = false;
+      else {
+        this.dispose();
+        this.close();
+        return;
+      }
+    } else if (!this.detail && (this.keys.matches(data, "tui.select.up") || data === "k")) {
+      this.selected = Math.max(0, this.selected - 1);
+    } else if (!this.detail && (this.keys.matches(data, "tui.select.down") || data === "j")) {
+      this.selected = Math.min(Math.max(0, runs.length - 1), this.selected + 1);
+    } else if (!this.detail && this.keys.matches(data, "tui.select.confirm") && runs[this.selected]) {
+      this.detail = true;
+    } else if (data === "n") this.actions.create();
+    else if (data === "s") this.actions.settings();
+    else if (this.detail && runs[this.selected]) {
+      const run = runs[this.selected];
+      if (data === "a" && run.status === "awaiting-approval") this.actions.approve(run);
+      else if (data === "f" && run.status === "awaiting-approval") this.actions.feedback(run);
+      else if (data === "p") this.actions.togglePause(run);
+      else if (data === "x") this.actions.cancel(run);
+    }
+    this.tui.requestRender();
+  }
+
+  render(width: number) {
+    const runs = this.engine.list();
+    this.selected = Math.min(this.selected, Math.max(0, runs.length - 1));
+    const lines = this.detail && runs[this.selected]
+      ? this.renderDetail(runs[this.selected], width)
+      : this.renderList(runs, width);
+    return lines.map((line) => truncateToWidth(line, width, ""));
+  }
+
+  private split(left: string, right: string, width: number) {
+    const rightWidth = visibleWidth(right);
+    const clipped = truncateToWidth(left, Math.max(0, width - rightWidth - 1), "…");
+    return clipped + " ".repeat(Math.max(1, width - visibleWidth(clipped) - rightWidth)) + right;
+  }
+
+  private renderList(runs: OrchestrationRun[], width: number) {
+    const lines = [
+      this.split(
+        this.theme.fg("accent", this.theme.bold("Orchestration")),
+        this.theme.fg("dim", `${runs.length} run${runs.length === 1 ? "" : "s"}`),
+        width,
+      ),
+      this.theme.fg("borderMuted", "─".repeat(Math.max(0, width))),
+    ];
+    if (!runs.length) lines.push(this.theme.fg("muted", "No runs yet. Press n to create one."));
+    for (const [index, run] of runs.entries()) {
+      const marker = index === this.selected ? this.theme.fg("accent", "❯") : " ";
+      const complete = run.tasks.filter((task) => task.status === "completed").length;
+      const color = run.status === "completed" ? "success" : run.status === "blocked" ? "error" : run.status === "running" ? "warning" : "muted";
+      lines.push(
+        this.split(
+          `${marker} ${this.theme.fg(color, "■")} ${this.theme.fg(index === this.selected ? "accent" : "text", run.objective.slice(0, 72))}`,
+          this.theme.fg("dim", `${complete}/${run.tasks.length} · ${run.status}`),
+          width,
+        ),
+      );
+      lines.push(`    ${this.theme.fg("dim", `${run.id} · ${run.cwd}`)}`);
+    }
+    lines.push("", this.theme.fg("dim", "j/k select · enter open · n new · s settings · esc close"));
+    return lines;
+  }
+
+  private renderDetail(run: OrchestrationRun, width: number) {
+    const lines = [
+      this.split(
+        this.theme.fg("accent", this.theme.bold(run.objective.slice(0, 100))),
+        this.theme.fg(run.status === "completed" ? "success" : run.status === "blocked" ? "error" : "warning", run.status),
+        width,
+      ),
+      this.theme.fg("dim", `${run.id} · ${run.cwd}`),
+      this.theme.fg("borderMuted", "─".repeat(Math.max(0, width))),
+      this.theme.fg("muted", run.summary || "No summary yet."),
+      "",
+      this.theme.fg("accent", this.theme.bold("Tasks")),
+    ];
+    for (const task of run.tasks) {
+      const color = task.status === "completed" ? "success" : task.status === "blocked" ? "error" : ["implementing", "reviewing", "integrating"].includes(task.status) ? "warning" : "muted";
+      lines.push(
+        this.split(
+          ` ${this.theme.fg(color, "■")} ${this.theme.fg("text", task.title)} ${this.theme.fg("dim", `(${task.role})`)}`,
+          this.theme.fg(color, task.status),
+          width,
+        ),
+      );
+      if (task.dependencies.length) lines.push(`   ${this.theme.fg("dim", `depends: ${task.dependencies.join(", ")}`)}`);
+      if (task.reviewSummary) lines.push(`   ${this.theme.fg("muted", `review: ${task.reviewSummary.slice(0, 140)}`)}`);
+      if (task.error) lines.push(`   ${this.theme.fg("error", task.error.slice(0, 180))}`);
+    }
+    if (run.finalReviewSummary) lines.push("", this.theme.fg("accent", `Final review: ${run.finalReviewSummary}`));
+    if (run.error) lines.push("", this.theme.fg("error", run.error));
+    const controls = [
+      run.status === "awaiting-approval" ? "a approve · f feedback" : "",
+      ["paused", "interrupted", "blocked"].includes(run.status) ? "p resume" : run.status === "running" ? "p pause" : "",
+      !["completed", "cancelled"].includes(run.status) ? "x cancel" : "",
+      "esc back",
+    ].filter(Boolean).join(" · ");
+    lines.push("", this.theme.fg("dim", controls));
+    return lines;
+  }
+}
+
+const listeners = new WeakMap<OrchestrationEngine, Set<() => void>>();
+export function notifyDashboard(engine: OrchestrationEngine) {
+  for (const listener of listeners.get(engine) ?? []) listener();
+}
+function engineChangeSubscription(engine: OrchestrationEngine, listener: () => void) {
+  const set = listeners.get(engine) ?? new Set<() => void>();
+  set.add(listener);
+  listeners.set(engine, set);
+  return () => set.delete(listener);
+}
+
+export async function openOrchestrationDashboard(
+  ctx: ExtensionContext,
+  engine: OrchestrationEngine,
+  actions: DashboardActions,
+) {
+  await ctx.ui.custom<void>(
+    (tui, theme, keys, done) =>
+      new OrchestrationDashboard(tui, theme, keys, engine, actions, () => done(undefined)),
+    {
+      overlay: true,
+      overlayOptions: { anchor: "center", width: "100%", maxHeight: "100%" },
+    },
+  );
+}