pi-better-harness 0.3.2 → 0.3.4

package/node_modules/pi-better-plan/src/plan-render.ts

@@ -0,0 +1,97 @@
+import type { Component } from "@earendil-works/pi-tui";
+import { matchesKey, truncateToWidth } from "@earendil-works/pi-tui";
+
+import { planProgress } from "./plan-state.js";
+import type { PlanSnapshot, PlanStep } from "./types.js";
+
+export interface PlanRenderTheme {
+  fg(color: string, value: string): string;
+}
+
+export function renderCompactPlan(
+  plan: PlanSnapshot,
+  width: number,
+  theme: PlanRenderTheme,
+  options: { focused?: boolean; selectedIndex?: number } = {},
+): string[] {
+  const progress = planProgress(plan);
+  const selected = clampIndex(options.selectedIndex ?? progress.activeIndex ?? firstIncompleteIndex(plan), plan.steps.length);
+  const stateLabel = progress.blocked > 0
+    ? `${progress.blocked} blocked`
+    : progress.state === "complete"
+      ? "complete"
+      : progress.state.replace("_", " ");
+  const lines = [
+    theme.fg(progress.blocked > 0 ? "warning" : "accent", `plan ${progress.completed}/${progress.total} steps`) +
+      theme.fg("dim", ` · ${stateLabel}`),
+  ];
+
+  for (let index = 0; index < plan.steps.length; index += 1) {
+    const item = plan.steps[index]!;
+    const selectedPrefix = options.focused && index === selected ? theme.fg("accent", "› ") : "  ";
+    lines.push(`${selectedPrefix}${stepGlyph(item, theme)} ${index + 1}  ${stepText(item, theme)}`);
+  }
+  lines.push("");
+  return lines.map((line) => truncateToWidth(line, Math.max(1, width)));
+}
+
+export function renderFullPlan(plan: PlanSnapshot, width: number, theme: PlanRenderTheme, selectedIndex = -1): string[] {
+  const progress = planProgress(plan);
+  const heading = `Practical Plan · ${progress.completed}/${progress.total} completed`;
+  const lines = [theme.fg("accent", rule(heading, width)), ""];
+  for (let index = 0; index < plan.steps.length; index += 1) {
+    const item = plan.steps[index]!;
+    const prefix = index === selectedIndex ? theme.fg("accent", "› ") : "  ";
+    lines.push(`${prefix}${stepGlyph(item, theme)}  ${String(index + 1).padStart(2, " ")}  ${stepText(item, theme)}`);
+  }
+  lines.push("", theme.fg("dim", rule("", width)));
+  return lines.map((line) => truncateToWidth(line, Math.max(1, width)));
+}
+
+export function createFullPlanComponent(
+  plan: PlanSnapshot,
+  theme: PlanRenderTheme,
+  onClose: () => void,
+): Component {
+  let selected = planProgress(plan).activeIndex ?? firstIncompleteIndex(plan);
+  return {
+    render: (width) => renderFullPlan(plan, width, theme, selected),
+    handleInput(data) {
+      if (matchesKey(data, "up")) selected = clampIndex(selected - 1, plan.steps.length);
+      else if (matchesKey(data, "down")) selected = clampIndex(selected + 1, plan.steps.length);
+      else if (matchesKey(data, "escape") || matchesKey(data, "left") || matchesKey(data, "ctrl+c")) onClose();
+    },
+    invalidate() {},
+  };
+}
+
+function firstIncompleteIndex(plan: PlanSnapshot): number {
+  const index = plan.steps.findIndex((item) => item.status !== "completed");
+  return index >= 0 ? index : Math.max(0, plan.steps.length - 1);
+}
+
+function clampIndex(index: number, total: number): number {
+  return Math.min(Math.max(0, index), Math.max(0, total - 1));
+}
+
+function stepGlyph(item: PlanStep, theme: PlanRenderTheme): string {
+  switch (item.status) {
+    case "completed": return theme.fg("success", "✓");
+    case "in_progress": return theme.fg("accent", "●");
+    case "blocked": return theme.fg("warning", "!");
+    case "pending": return theme.fg("dim", "○");
+  }
+}
+
+function stepText(item: PlanStep, theme: PlanRenderTheme): string {
+  if (item.status === "completed" || item.status === "pending") return theme.fg("muted", item.step);
+  if (item.status === "blocked") return theme.fg("warning", `BLOCKED · ${item.step}`);
+  return item.step;
+}
+
+function rule(label: string, width: number): string {
+  const size = Math.max(1, Math.floor(width));
+  if (!label) return "━".repeat(size);
+  const prefix = `━━ ${label} `;
+  return prefix + "━".repeat(Math.max(0, size - prefix.length));
+}

package/node_modules/pi-better-plan/src/plan-state.ts

@@ -0,0 +1,154 @@
+import type { PlanDisplayMode, PlanEntry, PlanProgress, PlanSnapshot, PlanStep, PlanStepInput } from "./types.js";
+import { EXTENSION_NAME } from "./types.js";
+
+const MAX_STEPS = 50;
+const MAX_STEP_CHARS = 500;
+const MAX_EXPLANATION_CHARS = 2_000;
+
+interface SessionEntryLike {
+  type: string;
+  customType?: string;
+  data?: unknown;
+}
+
+export interface ReconstructedPlanState {
+  plan: PlanSnapshot | null;
+  displayMode: PlanDisplayMode;
+}
+
+function nowSeconds(): number {
+  return Math.floor(Date.now() / 1_000);
+}
+
+function nextPlanId(now: number): string {
+  return `plan_${now.toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+}
+
+export function validatePlanInput(steps: readonly PlanStepInput[], explanation?: string): string | null {
+  if (steps.length === 0) return "A plan must contain at least one step.";
+  if (steps.length > MAX_STEPS) return `A plan cannot contain more than ${MAX_STEPS} steps.`;
+  if (explanation !== undefined && explanation.length > MAX_EXPLANATION_CHARS) {
+    return `Plan explanation cannot exceed ${MAX_EXPLANATION_CHARS} characters.`;
+  }
+
+  let inProgress = 0;
+  const normalized = new Set<string>();
+  for (let index = 0; index < steps.length; index += 1) {
+    const item = steps[index]!;
+    const text = item.step.trim();
+    if (!text) return `Plan step ${index + 1} cannot be empty.`;
+    if (text.length > MAX_STEP_CHARS) {
+      return `Plan step ${index + 1} cannot exceed ${MAX_STEP_CHARS} characters.`;
+    }
+    const key = text.toLocaleLowerCase();
+    if (normalized.has(key)) return `Plan step ${index + 1} duplicates an earlier step.`;
+    normalized.add(key);
+    if (item.status === "in_progress") inProgress += 1;
+  }
+  if (inProgress > 1) return "A plan can have at most one step in progress.";
+  return null;
+}
+
+export function replacePlan(
+  current: PlanSnapshot | null,
+  steps: readonly PlanStepInput[],
+  explanation?: string,
+  now = nowSeconds(),
+): PlanSnapshot {
+  const error = validatePlanInput(steps, explanation);
+  if (error) throw new Error(error);
+
+  const reusableIds = new Map(current?.steps.map((item) => [item.step.trim().toLocaleLowerCase(), item.id]) ?? []);
+  const revision = (current?.revision ?? 0) + 1;
+  const normalizedSteps: PlanStep[] = steps.map((item, index) => {
+    const step = item.step.trim();
+    return {
+      id: reusableIds.get(step.toLocaleLowerCase()) ?? `step_${revision}_${index + 1}`,
+      step,
+      status: item.status,
+    };
+  });
+
+  return {
+    version: 1,
+    planId: current?.planId ?? nextPlanId(now),
+    revision,
+    ...(explanation?.trim() ? { explanation: explanation.trim() } : {}),
+    steps: normalizedSteps,
+    createdAt: current?.createdAt ?? now,
+    updatedAt: now,
+  };
+}
+
+export function planProgress(plan: PlanSnapshot): PlanProgress {
+  const completed = plan.steps.filter((item) => item.status === "completed").length;
+  const pending = plan.steps.filter((item) => item.status === "pending").length;
+  const blocked = plan.steps.filter((item) => item.status === "blocked").length;
+  const inProgress = plan.steps.filter((item) => item.status === "in_progress").length;
+  const activeIndex = plan.steps.findIndex((item) => item.status === "in_progress" || item.status === "blocked");
+  return {
+    total: plan.steps.length,
+    completed,
+    pending,
+    blocked,
+    inProgress,
+    activeIndex: activeIndex >= 0 ? activeIndex : null,
+    state:
+      completed === plan.steps.length
+        ? "complete"
+        : inProgress > 0
+          ? "in_progress"
+          : blocked > 0
+            ? "blocked"
+            : "draft",
+  };
+}
+
+export function planSetEntry(plan: PlanSnapshot, at = nowSeconds()): PlanEntry {
+  return { version: 1, kind: "set", plan, at };
+}
+
+export function planClearEntry(at = nowSeconds()): PlanEntry {
+  return { version: 1, kind: "clear", at };
+}
+
+export function planDisplayEntry(mode: PlanDisplayMode, at = nowSeconds()): PlanEntry {
+  return { version: 1, kind: "display", mode, at };
+}
+
+export function reconstructPlanState(entries: Iterable<SessionEntryLike>): ReconstructedPlanState {
+  let plan: PlanSnapshot | null = null;
+  let displayMode: PlanDisplayMode = "auto";
+  for (const entry of entries) {
+    if (entry.type !== "custom" || entry.customType !== EXTENSION_NAME || !isPlanEntry(entry.data)) continue;
+    if (entry.data.kind === "set") plan = entry.data.plan;
+    else if (entry.data.kind === "clear") plan = null;
+    else displayMode = entry.data.mode;
+  }
+  return { plan, displayMode };
+}
+
+function isPlanEntry(value: unknown): value is PlanEntry {
+  if (!value || typeof value !== "object") return false;
+  const candidate = value as Partial<PlanEntry>;
+  if (candidate.version !== 1) return false;
+  if (candidate.kind === "clear") return true;
+  if (candidate.kind === "display") {
+    return candidate.mode === "auto" || candidate.mode === "on" || candidate.mode === "off" || candidate.mode === "hidden";
+  }
+  if (candidate.kind !== "set") return false;
+  return isPlanSnapshot(candidate.plan);
+}
+
+function isPlanSnapshot(value: unknown): value is PlanSnapshot {
+  if (!value || typeof value !== "object") return false;
+  const candidate = value as Partial<PlanSnapshot>;
+  return (
+    candidate.version === 1 &&
+    typeof candidate.planId === "string" &&
+    typeof candidate.revision === "number" &&
+    Array.isArray(candidate.steps) &&
+    typeof candidate.createdAt === "number" &&
+    typeof candidate.updatedAt === "number"
+  );
+}

package/node_modules/pi-better-plan/src/types.ts

@@ -0,0 +1,38 @@
+export const EXTENSION_NAME = "pi-better-plan";
+
+export type PlanStepStatus = "pending" | "in_progress" | "completed" | "blocked";
+export type PlanDisplayMode = "auto" | "on" | "off" | "hidden";
+
+export interface PlanStepInput {
+  step: string;
+  status: PlanStepStatus;
+}
+
+export interface PlanStep extends PlanStepInput {
+  id: string;
+}
+
+export interface PlanSnapshot {
+  version: 1;
+  planId: string;
+  revision: number;
+  explanation?: string;
+  steps: PlanStep[];
+  createdAt: number;
+  updatedAt: number;
+}
+
+export interface PlanProgress {
+  total: number;
+  completed: number;
+  pending: number;
+  blocked: number;
+  inProgress: number;
+  activeIndex: number | null;
+  state: "draft" | "in_progress" | "blocked" | "complete";
+}
+
+export type PlanEntry =
+  | { version: 1; kind: "set"; plan: PlanSnapshot; at: number }
+  | { version: 1; kind: "clear"; at: number }
+  | { version: 1; kind: "display"; mode: PlanDisplayMode; at: number };

package/node_modules/pi-better-ssh/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 1aboveio
+
+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/node_modules/pi-better-ssh/README.md

@@ -0,0 +1,99 @@
+# pi-better-ssh
+
+`pi-better-ssh` runs short synchronous remote commands over safe, reusable SSH connections. It adds explicit remote tools; Pi's built-in `bash` remains local and is never overridden.
+
+## Install
+
+```sh
+pi install npm:pi-better-ssh
+```
+
+For one session without changing Pi settings:
+
+```sh
+pi -e npm:pi-better-ssh
+```
+
+## Choose The Right Tool
+
+Use `remote_bash` when the foreground turn should wait for a short remote command's output and exit code. Use `bg_task_spawn` and the `bg_task_*` lifecycle tools with structured `ssh` for long-running or durable remote jobs; those jobs use remote tmux for lifecycle control.
+
+| Tool | Purpose |
+| --- | --- |
+| `remote_bash` | Run one short remote bash command and wait for its result. |
+| `ssh_profile` | List SSH aliases or manage the active session's host, workdir, and environment defaults. |
+| `ssh_mux` | Inspect or stop reusable ControlMaster connections. |
+
+## SSH Hosts
+
+Prefer a literal `Host` alias in `~/.ssh/config`; OpenSSH applies its configured hostname, user, port, key, jump host, and other policy. Wildcard entries are honored by OpenSSH but are not listed by `ssh_profile`.
+
+```sshconfig
+Host airflow-prod
+  HostName airflow.internal.example
+  User deploy
+  IdentityFile ~/.ssh/airflow_ed25519
+  ProxyJump bastion.example
+```
+
+Tool calls can use the alias (`airflow-prod`) or an explicit `user@host` target. Structured `user`, `port`, `identity_file`, `jump`, and `options` fields override connection details without constructing a shell command.
+
+## Run A Command
+
+`remote_bash` requires `command`. It requires `host` unless an active profile supplies one. `workdir` and `env` apply on the remote host; `timeout` is an optional positive number of seconds.
+
+```json
+{
+  "command": "airflow dags list",
+  "host": "airflow-prod",
+  "workdir": "/opt/airflow",
+  "env": { "AIRFLOW_HOME": "/opt/airflow" },
+  "timeout": 30
+}
+```
+
+A remote non-zero exit is a normal tool result with output and `exitCode`, so agents can inspect command failures. Output follows Pi bash limits: the last 2,000 lines or 50KB, whichever is reached first. Complete truncated output is retained in a local temporary file.
+
+## Session Profile
+
+A profile sets defaults for later `remote_bash` calls. `use` accepts a configured Host alias or `user@host`, plus optional remote `workdir` and `env`. The active profile is stored in the Pi session and survives `/reload`; it is not a separate host inventory.
+
+```json
+{ "action": "list" }
+```
+
+```json
+{
+  "action": "use",
+  "host": "airflow-prod",
+  "workdir": "/opt/airflow",
+  "env": { "AIRFLOW_HOME": "/opt/airflow" }
+}
+```
+
+Call `ssh_profile` with `status` to inspect the active profile or `clear` to remove it. A footer chip shows the active target, workdir, and whether its mux is up or down. An explicit `host`, `workdir`, or environment entry on `remote_bash` takes precedence over the corresponding profile default.
+
+## ControlMaster
+
+`remote_bash` checks for a reusable ControlMaster and opens one when needed. Its ControlPath lives under the harness-owned `~/.pi/agent/ssh-control` directory, which is forced to mode `0700`; the socket key includes the connection identity and Pi session. A stale socket is removed and reopened once. Repeated commands for the same target and session reuse the master.
+
+Use `ssh_mux` with `status` or `stop` and either a target, the active profile, or `all:true` for masters observed in the current Pi process and session:
+
+```json
+{ "action": "status", "host": "airflow-prod" }
+```
+
+```json
+{ "action": "stop", "all": true }
+```
+
+Stopping a mux does not stop remote tmux jobs. A `remote_bash` timeout terminates only that slave SSH process; a healthy reusable master remains available.
+
+## Safety Defaults
+
+- SSH is launched as argv with `shell:false`; connection fields are never interpolated into a local shell command.
+- `BatchMode=yes`, a bounded connect timeout, and no TTY are always enforced, so password prompts fail fast.
+- Caller `options` cannot disable required SSH or mux safety settings.
+- Remote workdir and environment values are shell-quoted by the shared SSH core before `bash -c` runs.
+- Identity file paths may appear in status details, but key material is never read or displayed.
+- This package provides no interactive shell, PTY attach, remote IDE mode, or local `bash` override.

package/node_modules/pi-better-ssh/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "pi-better-ssh",
+  "version": "0.1.1",
+  "description": "Pi extension for safe synchronous remote bash commands over reusable SSH connections.",
+  "license": "MIT",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi",
+    "ssh",
+    "remote-bash"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/1aboveio/pi-better-harness.git",
+    "directory": "packages/pi-better-ssh"
+  },
+  "bugs": {
+    "url": "https://github.com/1aboveio/pi-better-harness/issues"
+  },
+  "homepage": "https://github.com/1aboveio/pi-better-harness/tree/main/packages/pi-better-ssh#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "pretest": "node ../../scripts/sync-shared-ssh-core.mjs",
+    "prepack": "node ../../scripts/sync-shared-ssh-core.mjs",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "files": [
+    "src/**/*.ts",
+    "!src/**/*.test.ts",
+    "!src/shared-ssh-core/test-support/**",
+    "README.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.0",
+    "typebox": "^1.1.39",
+    "typescript": "^6.0.0",
+    "vitest": "^3.0.0"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  }
+}