@pify/autopilot 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pifydev
+
+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,51 @@
+# @pify/autopilot
+
+[![CI](https://github.com/pifydev/autopilot/actions/workflows/ci.yml/badge.svg)](https://github.com/pifydev/autopilot/actions/workflows/ci.yml) [![npm version](https://img.shields.io/npm/v/@pify/autopilot)](https://www.npmjs.com/package/@pify/autopilot) [![npm downloads](https://img.shields.io/npm/dm/@pify/autopilot)](https://www.npmjs.com/package/@pify/autopilot)
+
+Let the main [pi](https://github.com/earendil-works/pi) agent keep going on its own between turns — **opt-in, hard-capped, and never over your head**. Arm it toward a goal and it drives the next turn itself until the work is done, the cap is hit, or it stops making progress.
+
+Part of the [Pify suite](https://github.com/pifydev). Install with [`pify install autopilot`](https://github.com/pifydev/cli) or `pi install npm:@pify/autopilot`.
+
+## Why
+
+The suite already loop-guards *child* agents (`@pify/subagent`, `@pify/swarm`), but the *primary* session still stops after every turn and waits for you. For a well-scoped task you'd rather set it going and step away. Autopilot does that — carefully.
+
+## Safety first
+
+An unbounded self-driving agent is the dangerous kind, so every default is a brake:
+
+- **Off by default.** It does nothing until you arm it with `/autopilot on`.
+- **A hard turn cap** it can never exceed, even via settings (ceiling 200).
+- **A no-progress breaker** — the same guard `@pify/subagent` uses — stops it the moment it repeats itself instead of working.
+- **Never over your head.** While a dialog is open (an `ask_question`, a confirm), it waits rather than driving a turn.
+- **A clean finish.** The agent ends its reply with `<autopilot-done>` when the task is complete, and autopilot stops.
+- **Always visible.** A `🅰 autopilot N/max` footer while armed, and a notification with the reason every time it stops.
+
+It drives each turn on `agent_settled` (fully idle) via a triggered message, so it never talks over a running turn. Arming is interactive-only, so a headless `pi -p` run never self-drives.
+
+## Use
+
+```
+/autopilot on refactor auth.ts to use the new session API and make the tests pass
+/autopilot status        # armed? turns used, goal
+/autopilot off           # stop now
+```
+
+Give a goal (recommended) and it works toward that, one concrete step per turn; without one it just continues the current task. It stops on any of: the done signal, the turn cap, no progress, an error, or `/autopilot off`.
+
+## Settings
+
+`.pi/autopilot.json` (project) or `<agentDir>/autopilot.json` (global):
+
+```json
+{
+  "maxTurns": 10,
+  "maxUnchangedTurns": 3
+}
+```
+
+`maxTurns` (1–200) is the hard cap per arming; `maxUnchangedTurns` (2–10) is how many turns with no real progress count as stuck. `PIFY_AUTOPILOT_MAX_TURNS` overrides the cap for one run. Bad values fall back to the defaults with a warning.
+
+## License
+
+MIT © [Pify maintainers](https://github.com/pifydev)

package/extensions/autopilot.ts

@@ -0,0 +1,181 @@
+/**
+ * @pify/autopilot — let the main agent keep going on its own, safely.
+ *
+ * The suite loop-guards CHILD agents (subagent/swarm) but nothing keeps the
+ * PRIMARY session moving without you pressing enter each turn. This does — and
+ * because an unbounded self-driving agent is the dangerous kind, every default
+ * here is a brake:
+ *
+ *   - OFF by default; you arm it explicitly with `/autopilot on [goal]`.
+ *   - a hard turn cap (maxTurns) it can never exceed, even via settings;
+ *   - a no-progress breaker (the same LoopGuard subagent uses) that stops it
+ *     the moment it repeats itself instead of working;
+ *   - it never drives a turn while a dialog is open (you are being asked
+ *     something), and it stops the instant the agent emits the done token;
+ *   - a visible footer while armed, and a notification with the reason whenever
+ *     it stops.
+ *
+ * It drives a turn on `agent_settled` (fully idle) via sendMessage triggerTurn,
+ * so it never talks over a running turn. Zero runtime dependencies.
+ */
+import { getAgentDir, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { decide, hasDoneSignal, DONE_TOKEN } from "../src/decide.ts";
+import { DEFAULT_SETTINGS, resolveSettings, type AutopilotSettings } from "../src/settings.ts";
+import { LoopGuard } from "../src/loop-guard.ts";
+
+type UiContext = ExtensionContext;
+const STATUS = "autopilot";
+const NUDGE_TYPE = "pify-autopilot-nudge";
+
+export default function autopilot(pi: ExtensionAPI) {
+  let settings: AutopilotSettings = DEFAULT_SETTINGS;
+  let armed = false;
+  let turns = 0;
+  let goal: string | null = null;
+  let blocked = false;
+  let done = false;
+  let stalled = false;
+  let guard = new LoopGuard();
+  let lastCtx: UiContext | null = null;
+
+  function loadSettings(cwd: string): string[] {
+    for (const file of [join(cwd, ".pi", "autopilot.json"), join(getAgentDir(), "autopilot.json")]) {
+      let raw: string;
+      try {
+        raw = readFileSync(file, "utf8");
+      } catch {
+        continue;
+      }
+      try {
+        const parsed = resolveSettings(JSON.parse(raw));
+        settings = parsed.settings;
+        return parsed.warnings;
+      } catch (err) {
+        settings = DEFAULT_SETTINGS;
+        return [`${file}: ${err instanceof Error ? err.message : String(err)}`];
+      }
+    }
+    settings = resolveSettings(undefined).settings;
+    return [];
+  }
+
+  function renderStatus(ctx: UiContext | null = lastCtx): void {
+    if (!ctx || !ctx.hasUI) return;
+    ctx.ui.setStatus(STATUS, armed ? `🅰 autopilot ${turns}/${settings.maxTurns}` : undefined);
+  }
+
+  function disarm(ctx: UiContext, reason: string): void {
+    if (!armed) return;
+    armed = false;
+    goal = null;
+    done = false;
+    stalled = false;
+    turns = 0;
+    if (ctx.hasUI) {
+      ctx.ui.notify(`Autopilot ${reason}.`, "info");
+      renderStatus(ctx);
+    }
+  }
+
+  function nudgeText(): string {
+    const close = `When the task is fully complete, end your reply with ${DONE_TOKEN} and stop.`;
+    return goal
+      ? `Keep working toward this goal, one concrete step at a time:\n${goal}\n\n${close}`
+      : `Continue the current task, one concrete step at a time. ${close}`;
+  }
+
+  async function drive(ctx: UiContext): Promise<void> {
+    turns++;
+    renderStatus(ctx);
+    try {
+      await pi.sendMessage(
+        { customType: NUDGE_TYPE, content: nudgeText(), display: false },
+        { triggerTurn: true, deliverAs: "nextTurn" },
+      );
+    } catch {
+      // A /reload or a busy session makes the captured handle throw; stop
+      // rather than leave a half-armed loop that never advances.
+      disarm(ctx, "stopped: could not drive the next turn");
+    }
+  }
+
+  // ── the loop ─────────────────────────────────────────────────────────
+
+  pi.on("session_start", async (_event, ctx) => {
+    lastCtx = ctx;
+    const warnings = loadSettings(ctx.cwd);
+    if (warnings.length > 0 && ctx.hasUI) ctx.ui.notify(`autopilot settings: ${warnings.join("; ")}`, "warning");
+  });
+
+  pi.on("ui_prompt_start", async () => {
+    blocked = true;
+  });
+  pi.on("ui_prompt_end", async () => {
+    blocked = false;
+  });
+
+  pi.on("agent_end", async (event, ctx) => {
+    lastCtx = ctx;
+    if (!armed) return;
+    const messages = (event as { messages?: Array<{ role?: string; content?: unknown }> }).messages ?? [];
+    const last = [...messages].reverse().find((m) => m.role === "assistant");
+    const content = Array.isArray(last?.content) ? (last!.content as Array<Record<string, unknown>>) : [];
+    const usedTool = content.some((b) => b.type === "toolCall");
+    const text = content
+      .filter((b) => b.type === "text" && typeof b.text === "string")
+      .map((b) => b.text as string)
+      .join("\n");
+    if (hasDoneSignal(text)) done = true;
+    // Feed the no-progress breaker; a stall stops autopilot at the next settle.
+    stalled = guard.observe({ text, usedTool }).stalled;
+  });
+
+  pi.on("agent_settled", async (_event, ctx) => {
+    lastCtx = ctx;
+    if (!armed) return;
+    const decision = decide({ armed, turns, maxTurns: settings.maxTurns, blocked, stalled, done });
+    if (decision.action === "continue") await drive(ctx);
+    else if (decision.action === "stop") disarm(ctx, decision.reason);
+    // "wait": stay armed, do nothing this settle
+  });
+
+  pi.registerCommand("autopilot", {
+    description: "Keep the agent going on its own: /autopilot [on [goal] | off | status]",
+    handler: async (args, ctx: UiContext) => {
+      if (!ctx.hasUI) return; // arming is interactive-only; headless never self-drives
+      lastCtx = ctx;
+      const [verb, ...rest] = (args ?? "").trim().split(/\s+/);
+      const v = (verb ?? "").toLowerCase();
+
+      if (v === "off") {
+        if (armed) disarm(ctx, "off");
+        else ctx.ui.notify("Autopilot is already off.", "info");
+        return;
+      }
+      if (v === "" || v === "status") {
+        ctx.ui.notify(
+          armed
+            ? `Autopilot on: ${turns}/${settings.maxTurns} turns used${goal ? `, goal: ${goal}` : ""}.`
+            : `Autopilot off. Arm with /autopilot on [goal]. Caps: ${settings.maxTurns} turns, stop after ${settings.maxUnchangedTurns} unchanged.`,
+          "info",
+        );
+        return;
+      }
+      if (v === "on") {
+        armed = true;
+        turns = 0;
+        done = false;
+        stalled = false;
+        guard = new LoopGuard({ repeat: settings.maxUnchangedTurns });
+        goal = rest.join(" ").trim() || null;
+        ctx.ui.notify(`Autopilot on (cap ${settings.maxTurns} turns)${goal ? `, working toward: ${goal}` : ""}.`, "info");
+        await drive(ctx); // start working immediately
+        return;
+      }
+      ctx.ui.notify("Usage: /autopilot [on [goal] | off | status]", "warning");
+    },
+  });
+}

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@pify/autopilot",
+  "version": "0.1.0",
+  "description": "Let the main agent keep going on its own between turns — opt-in, hard-capped by turn count and a no-progress breaker, and it never runs while you are being asked something",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi",
+    "pify",
+    "autopilot",
+    "autonomous",
+    "agent"
+  ],
+  "homepage": "https://github.com/pifydev/autopilot#readme",
+  "bugs": {
+    "url": "https://github.com/pifydev/autopilot/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pifydev/autopilot.git"
+  },
+  "license": "MIT",
+  "author": "Pify maintainers",
+  "type": "module",
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "files": [
+    "extensions",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./extensions/autopilot.ts"
+    ]
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "prepublishOnly": "npm run typecheck && npm test"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "@earendil-works/pi-tui": {
+      "optional": true
+    },
+    "typebox": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "^0.85.1",
+    "@earendil-works/pi-coding-agent": "^0.85.1",
+    "@earendil-works/pi-tui": "^0.85.1",
+    "@types/node": "^22.10.2",
+    "typebox": "^1.1.38",
+    "typescript": "^5.7.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/decide.ts

@@ -0,0 +1,49 @@
+/**
+ * The one decision that matters, pure and testable: after a turn settles,
+ * should autopilot drive another turn, stop, or just wait?
+ *
+ * The ordering encodes the safety priorities. Not armed → do nothing. The
+ * agent said it is done → stop. Blocked on a human question → wait (never talk
+ * over the user). No progress across recent turns → stop (it is spinning). Turn
+ * budget spent → stop. Only then: continue.
+ */
+
+export interface AutopilotState {
+  /** Explicitly turned on by the user this session. Off by default. */
+  armed: boolean;
+  /** Auto-continuations driven so far this run. */
+  turns: number;
+  /** Hard ceiling on auto-continuations. */
+  maxTurns: number;
+  /** A user-facing dialog is open — do not drive a turn over it. */
+  blocked: boolean;
+  /** The no-progress breaker flagged a stall (see loop-guard.ts). */
+  stalled: boolean;
+  /** The agent emitted the completion token. */
+  done: boolean;
+}
+
+export type AutopilotAction = "continue" | "stop" | "wait";
+
+export interface AutopilotDecision {
+  action: AutopilotAction;
+  reason: string;
+}
+
+export function decide(state: AutopilotState): AutopilotDecision {
+  if (!state.armed) return { action: "wait", reason: "not armed" };
+  if (state.done) return { action: "stop", reason: "the agent reported the task complete" };
+  if (state.blocked) return { action: "wait", reason: "waiting on your answer" };
+  if (state.stalled) return { action: "stop", reason: "stopped: no progress across recent turns" };
+  if (state.turns >= state.maxTurns) {
+    return { action: "stop", reason: `stopped: reached the ${state.maxTurns}-turn limit` };
+  }
+  return { action: "continue", reason: `continuing (turn ${state.turns + 1}/${state.maxTurns})` };
+}
+
+/** The token the agent ends its reply with to end autopilot cleanly. */
+export const DONE_TOKEN = "<autopilot-done>";
+
+export function hasDoneSignal(text: string): boolean {
+  return text.toLowerCase().includes(DONE_TOKEN);
+}

package/src/loop-guard.ts

@@ -0,0 +1,90 @@
+/**
+ * Stop a child that has stopped making progress.
+ *
+ * A turn cap bounds what a runaway child can cost; it does not notice the
+ * characteristic autonomous-agent failure, which is cheaper per turn and just
+ * as stuck: restating the same plan every turn without calling a tool, or
+ * oscillating between two states forever. pi's own loop will happily let that
+ * run to the cap.
+ *
+ * So fingerprint each assistant turn and watch for two shapes. A turn that
+ * called a tool is progress and clears the history — the guard only fires on
+ * turns that did nothing but talk. `repeat` identical tool-free turns is a
+ * child spinning in place; an A-B-A-B… run of `cycle` cycles is one bouncing
+ * between two dead ends. Both are advisory signals the caller acts on (a
+ * spawned child is unattended, so acting means aborting it).
+ *
+ * Zero dependencies — node:crypto for the hash. Deterministic and pure given
+ * the sequence of turns, so it is unit-testable without a live child.
+ */
+import { createHash } from "node:crypto";
+
+export interface LoopGuardConfig {
+  /** Consecutive identical tool-free turns before flagging a stall (min 2, default 3). */
+  repeat?: number;
+  /** Repeats of a two-turn A-B cycle before flagging (min 2, default 3). */
+  cycle?: number;
+}
+
+export interface Turn {
+  /** The visible assistant text of the turn. */
+  text: string;
+  /** Did the turn invoke at least one tool? A tool call is progress. */
+  usedTool: boolean;
+}
+
+export interface LoopVerdict {
+  stalled: boolean;
+  reason?: string;
+}
+
+/** Fold away cosmetic differences so "the same thought" hashes the same. */
+function fingerprint(text: string): string {
+  const norm = text.normalize("NFKC").toLowerCase().replace(/\s+/g, " ").trim();
+  return createHash("sha256").update(norm).digest("hex");
+}
+
+export class LoopGuard {
+  private readonly repeat: number;
+  private readonly cycle: number;
+  /** Recent tool-free fingerprints; a tool call clears this. */
+  private readonly recent: string[] = [];
+  private static readonly MAX = 16;
+
+  constructor(cfg: LoopGuardConfig = {}) {
+    this.repeat = Math.max(2, cfg.repeat ?? 3);
+    this.cycle = Math.max(2, cfg.cycle ?? 3);
+  }
+
+  observe(turn: Turn): LoopVerdict {
+    // A tool call is forward motion: forget the stall history entirely.
+    if (turn.usedTool) {
+      this.recent.length = 0;
+      return { stalled: false };
+    }
+    // A silent turn (no text, no tool) is not evidence of a loop by itself.
+    if (turn.text.trim() === "") return { stalled: false };
+
+    const fp = fingerprint(turn.text);
+    this.recent.push(fp);
+    if (this.recent.length > LoopGuard.MAX) this.recent.shift();
+
+    // Spinning in place: the last `repeat` tool-free turns are identical.
+    if (this.recent.length >= this.repeat && this.recent.slice(-this.repeat).every((f) => f === fp)) {
+      return { stalled: true, reason: `repeated the same output for ${this.repeat} turns without acting` };
+    }
+
+    // Oscillating: the last 2×cycle turns are a strict A-B-A-B… alternation.
+    const need = 2 * this.cycle;
+    if (this.recent.length >= need) {
+      const tail = this.recent.slice(-need);
+      const a = tail[0]!;
+      const b = tail[1]!;
+      if (a !== b && tail.every((f, i) => f === (i % 2 === 0 ? a : b))) {
+        return { stalled: true, reason: `oscillated between two states for ${this.cycle} cycles without acting` };
+      }
+    }
+
+    return { stalled: false };
+  }
+}

package/src/settings.ts

@@ -0,0 +1,67 @@
+/**
+ * Settings for @pify/autopilot. Autonomy is opt-in per session (armed with a
+ * command), so there is no "on by default" switch — only the safety bounds:
+ * how many turns it may drive, and how many unchanged turns count as stuck.
+ * `.pi/autopilot.json` (project) or `<agentDir>/autopilot.json` (global).
+ */
+
+export interface AutopilotSettings {
+  /** Hard cap on auto-continuations per arming (1..MAX). */
+  maxTurns: number;
+  /** Identical/no-tool turns in a row that count as no progress → stop. */
+  maxUnchangedTurns: number;
+}
+
+export const DEFAULT_SETTINGS: AutopilotSettings = {
+  maxTurns: 10,
+  maxUnchangedTurns: 3,
+};
+
+const LIMITS: Record<keyof AutopilotSettings, { min: number; max: number }> = {
+  // A ceiling even the setting can't exceed: autopilot must never be unbounded.
+  maxTurns: { min: 1, max: 200 },
+  maxUnchangedTurns: { min: 2, max: 10 },
+};
+
+export function resolveSettings(
+  raw: unknown,
+  env: NodeJS.ProcessEnv = process.env,
+): { settings: AutopilotSettings; warnings: string[] } {
+  const settings: AutopilotSettings = { ...DEFAULT_SETTINGS };
+  const warnings: string[] = [];
+
+  if (raw !== undefined && raw !== null) {
+    if (typeof raw !== "object" || Array.isArray(raw)) {
+      warnings.push("settings file is not an object — ignored");
+    } else {
+      for (const [key, value] of Object.entries(raw as Record<string, unknown>)) {
+        if (!(key in DEFAULT_SETTINGS)) {
+          warnings.push(`unknown setting "${key}"`);
+          continue;
+        }
+        const name = key as keyof AutopilotSettings;
+        if (typeof value !== "number" || !Number.isFinite(value)) {
+          warnings.push(`"${key}" must be a number — using ${DEFAULT_SETTINGS[name]}`);
+          continue;
+        }
+        settings[name] = clamp(name, value, warnings);
+      }
+    }
+  }
+
+  const envMax = env.PIFY_AUTOPILOT_MAX_TURNS;
+  if (envMax !== undefined && envMax !== "") {
+    const n = Number(envMax);
+    if (Number.isFinite(n)) settings.maxTurns = clamp("maxTurns", n, warnings);
+    else warnings.push(`PIFY_AUTOPILOT_MAX_TURNS="${envMax}" is not a number — ignored`);
+  }
+
+  return { settings, warnings };
+}
+
+function clamp(name: keyof AutopilotSettings, value: number, warnings: string[]): number {
+  const { min, max } = LIMITS[name];
+  const c = Math.round(Math.min(max, Math.max(min, value)));
+  if (c !== value) warnings.push(`"${name}" clamped to ${c} (allowed ${min}–${max})`);
+  return c;
+}