@alexanderbianchi/herdr-aside 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexander Bianchi
+
+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,59 @@
+# herdr-aside
+
+A focused Pi extension for opening independent side conversations in [Herdr](https://herdr.dev).
+
+`/aside` forks the current persisted Pi session into a new Herdr location. The child starts with the current conversation context and then evolves independently. Every invocation creates a new fork; it never reuses or routes to an existing agent.
+
+## Install
+
+```bash
+pi install npm:@alexanderbianchi/herdr-aside
+```
+
+Until the npm package is published:
+
+```bash
+pi install git:github.com/alexanderbianchi/herdr-aside
+```
+
+Then run `/reload` in an existing Pi session.
+
+## Usage
+
+```text
+/aside explain this RFC while the main agent keeps working
+/aside h compare these APIs
+/aside v --focus investigate this failure
+/aside t draft an alternative design
+/aside w explore this independently
+```
+
+The optional first argument controls where the fork opens:
+
+| Argument | Herdr location |
+|---|---|
+| `h`, `horizontal` | Horizontal divider; new pane below |
+| `v`, `vertical` | Vertical divider; new pane to the right |
+| `t`, `tab` | New tab in the current workspace |
+| `w`, `workspace` | New workspace |
+
+Without a topology argument, `/aside` uses a horizontal split and treats all input as the prompt.
+
+A prompted aside stays in the background by default. An aside without a prompt receives focus so you can type into it. Put `--focus` or `--no-focus` after the topology to override that behavior.
+
+## Requirements
+
+- Pi running in interactive TUI mode
+- Pi's current session must be persisted
+- Pi must be running inside a Herdr-managed pane
+- `herdr` must be available on `PATH`
+
+The extension uses Herdr's `agent start` command and Pi's native `--fork` option. It does not provide general Herdr orchestration tools; [`@andrewjacop/pi-herdr`](https://pi.dev/packages/@andrewjacop/pi-herdr) is complementary and can be installed alongside it.
+
+## Development
+
+```bash
+npm install
+npm run check
+pi -ne -e ./src/index.ts
+```

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@alexanderbianchi/herdr-aside",
+  "version": "0.1.0",
+  "description": "Fork the current Pi session into a new Herdr split, tab, or workspace with /aside",
+  "type": "module",
+  "license": "MIT",
+  "author": "Alexander Bianchi",
+  "homepage": "https://github.com/alexanderbianchi/herdr-aside#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alexanderbianchi/herdr-aside.git"
+  },
+  "bugs": {
+    "url": "https://github.com/alexanderbianchi/herdr-aside/issues"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-coding-agent",
+    "herdr",
+    "aside",
+    "session",
+    "fork"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "pi": {
+    "extensions": ["./src/index.ts"]
+  },
+  "files": ["src/index.ts", "README.md", "LICENSE"],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest --run",
+    "check": "npm run typecheck && npm test"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "0.82.1",
+    "@types/node": "^24.5.2",
+    "typescript": "^5.9.2",
+    "vitest": "^4.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.ts

@@ -0,0 +1,266 @@
+import type {
+  ExecResult,
+  ExtensionAPI,
+  ExtensionCommandContext,
+} from "@earendil-works/pi-coding-agent";
+
+export type HerdrTopology = "horizontal" | "vertical" | "tab" | "workspace";
+
+type SpawnOptions = {
+  focus: boolean;
+  prompt: string;
+};
+
+type HerdrTarget = {
+  paneId: string;
+  cleanup: { command: "pane" | "tab" | "workspace"; id: string };
+};
+
+const ASIDE_SYSTEM_PROMPT = [
+  "You are in a side conversation forked from the user's main Pi session.",
+  "Treat inherited messages as context; another agent may still be handling the main task.",
+  "Focus on the user's side question and continue independently in this Herdr location.",
+].join(" ");
+
+const TOPOLOGY_ALIASES: Readonly<Record<string, HerdrTopology>> = {
+  h: "horizontal",
+  horizontal: "horizontal",
+  v: "vertical",
+  vertical: "vertical",
+  t: "tab",
+  tab: "tab",
+  w: "workspace",
+  workspace: "workspace",
+};
+
+function notify(
+  ctx: ExtensionCommandContext,
+  message: string,
+  level: "info" | "warning" | "error",
+): void {
+  if (ctx.hasUI) ctx.ui.notify(message, level);
+}
+
+function resultError(result: ExecResult, fallback: string): Error {
+  return new Error(result.stderr.trim() || result.stdout.trim() || fallback);
+}
+
+function parseJsonResult(result: ExecResult, fallback: string): Record<string, unknown> {
+  if (result.code !== 0) throw resultError(result, fallback);
+
+  try {
+    return JSON.parse(result.stdout) as Record<string, unknown>;
+  } catch {
+    throw new Error(`${fallback}: Herdr returned invalid JSON`);
+  }
+}
+
+function objectAt(value: unknown, key: string): Record<string, unknown> | undefined {
+  if (!value || typeof value !== "object") return undefined;
+  const nested = (value as Record<string, unknown>)[key];
+  return nested && typeof nested === "object" ? (nested as Record<string, unknown>) : undefined;
+}
+
+function stringAt(value: unknown, key: string): string | undefined {
+  if (!value || typeof value !== "object") return undefined;
+  const nested = (value as Record<string, unknown>)[key];
+  return typeof nested === "string" && nested.length > 0 ? nested : undefined;
+}
+
+export function parseSpawnOptions(args: string): SpawnOptions {
+  let remaining = args.trim();
+  let focus: boolean | undefined;
+
+  while (true) {
+    const match = remaining.match(/^(--focus|--no-focus)(?:\s+|$)/);
+    if (!match) break;
+    focus = match[1] === "--focus";
+    remaining = remaining.slice(match[0].length).trimStart();
+  }
+
+  return { focus: focus ?? remaining.length === 0, prompt: remaining };
+}
+
+export function parseAsideArgs(args: string): {
+  topology: HerdrTopology;
+  options: SpawnOptions;
+} {
+  const trimmed = args.trim();
+  const match = trimmed.match(/^(\S+)(?:\s+([\s\S]*))?$/);
+  if (!match) {
+    return { topology: "horizontal", options: parseSpawnOptions("") };
+  }
+
+  const topology = TOPOLOGY_ALIASES[match[1].toLowerCase()];
+  if (topology) {
+    return { topology, options: parseSpawnOptions(match[2] ?? "") };
+  }
+
+  return { topology: "horizontal", options: parseSpawnOptions(trimmed) };
+}
+
+async function createTarget(
+  pi: ExtensionAPI,
+  ctx: ExtensionCommandContext,
+  topology: HerdrTopology,
+  focus: boolean,
+): Promise<HerdrTarget> {
+  const focusArg = focus ? "--focus" : "--no-focus";
+  let result: ExecResult;
+
+  if (topology === "horizontal" || topology === "vertical") {
+    result = await pi.exec("herdr", [
+      "pane",
+      "split",
+      "--pane",
+      process.env.HERDR_PANE_ID!,
+      "--direction",
+      topology === "horizontal" ? "down" : "right",
+      "--cwd",
+      ctx.cwd,
+      focusArg,
+    ]);
+    const json = parseJsonResult(result, `Could not create the ${topology} Herdr split`);
+    const pane = objectAt(objectAt(json, "result"), "pane");
+    const paneId = stringAt(pane, "pane_id");
+    if (!paneId) throw new Error("Herdr did not return the new pane ID");
+    return { paneId, cleanup: { command: "pane", id: paneId } };
+  }
+
+  if (topology === "tab") {
+    result = await pi.exec("herdr", [
+      "tab",
+      "create",
+      "--workspace",
+      process.env.HERDR_WORKSPACE_ID!,
+      "--cwd",
+      ctx.cwd,
+      "--label",
+      "Aside",
+      focusArg,
+    ]);
+    const json = parseJsonResult(result, "Could not create the Herdr tab");
+    const payload = objectAt(json, "result");
+    const pane = objectAt(payload, "root_pane");
+    const tab = objectAt(payload, "tab");
+    const paneId = stringAt(pane, "pane_id");
+    const tabId = stringAt(tab, "tab_id");
+    if (!paneId || !tabId) throw new Error("Herdr did not return the new tab and pane IDs");
+    return { paneId, cleanup: { command: "tab", id: tabId } };
+  }
+
+  result = await pi.exec("herdr", [
+    "workspace",
+    "create",
+    "--cwd",
+    ctx.cwd,
+    "--label",
+    "Aside",
+    focusArg,
+  ]);
+  const json = parseJsonResult(result, "Could not create the Herdr workspace");
+  const payload = objectAt(json, "result");
+  const pane = objectAt(payload, "root_pane");
+  const workspace = objectAt(payload, "workspace");
+  const paneId = stringAt(pane, "pane_id");
+  const workspaceId = stringAt(workspace, "workspace_id");
+  if (!paneId || !workspaceId) {
+    throw new Error("Herdr did not return the new workspace and pane IDs");
+  }
+  return { paneId, cleanup: { command: "workspace", id: workspaceId } };
+}
+
+async function cleanupTarget(pi: ExtensionAPI, target: HerdrTarget): Promise<void> {
+  await pi.exec("herdr", [target.cleanup.command, "close", target.cleanup.id]);
+}
+
+function agentName(topology: HerdrTopology): string {
+  const short = topology === "horizontal" ? "h" : topology === "vertical" ? "v" : topology[0];
+  const unique = `${Date.now().toString(36).slice(-6)}${Math.random().toString(36).slice(2, 6)}`;
+  return `aside-${short}-${unique}`;
+}
+
+export async function spawnAsideFork(
+  pi: ExtensionAPI,
+  ctx: ExtensionCommandContext,
+  topology: HerdrTopology,
+  options: SpawnOptions,
+): Promise<void> {
+  if (ctx.mode !== "tui" || process.env.HERDR_ENV !== "1" || !process.env.HERDR_PANE_ID) {
+    notify(ctx, "/aside must run from Pi inside a Herdr-managed pane.", "error");
+    return;
+  }
+  if ((topology === "tab" || topology === "workspace") && !process.env.HERDR_WORKSPACE_ID) {
+    notify(ctx, "Herdr did not provide the current workspace ID.", "error");
+    return;
+  }
+
+  const sessionFile = ctx.sessionManager.getSessionFile();
+  if (!sessionFile) {
+    notify(ctx, "The current Pi session is ephemeral and cannot be used for an aside fork.", "error");
+    return;
+  }
+
+  let target: HerdrTarget | undefined;
+  try {
+    target = await createTarget(pi, ctx, topology, options.focus);
+    const name = agentName(topology);
+    const start = await pi.exec("herdr", [
+      "agent",
+      "start",
+      name,
+      "--kind",
+      "pi",
+      "--pane",
+      target.paneId,
+      "--",
+      "--fork",
+      sessionFile,
+      "--name",
+      `Aside ${topology}`,
+      "--append-system-prompt",
+      ASIDE_SYSTEM_PROMPT,
+    ], { timeout: 45_000 });
+    if (start.code !== 0) throw resultError(start, "Could not start the aside Pi fork");
+
+    if (options.prompt) {
+      const prompt = await pi.exec("herdr", ["agent", "prompt", name, options.prompt]);
+      if (prompt.code !== 0) throw resultError(prompt, "Could not send the initial aside prompt");
+    }
+
+    notify(
+      ctx,
+      `Created a new ${topology} aside in ${target.paneId}${options.prompt ? " and sent its prompt" : ""}.`,
+      "info",
+    );
+  } catch (error) {
+    if (target) {
+      try {
+        await cleanupTarget(pi, target);
+      } catch {
+        // The original failure is more useful than best-effort cleanup failure.
+      }
+    }
+    notify(ctx, error instanceof Error ? error.message : String(error), "error");
+  }
+}
+
+export default function herdrAside(pi: ExtensionAPI): void {
+  pi.registerCommand("aside", {
+    description: "Fork the current Pi session into a new Herdr split, tab, or workspace.",
+    getArgumentCompletions: (prefix) => {
+      const items = [
+        { value: "h", label: "h", description: "horizontal split" },
+        { value: "v", label: "v", description: "vertical split" },
+        { value: "t", label: "t", description: "new tab" },
+        { value: "w", label: "w", description: "new workspace" },
+      ];
+      const token = prefix.trim();
+      return token.includes(" ") ? null : items.filter((item) => item.value.startsWith(token));
+    },
+    handler: async (args, ctx) => {
+      const parsed = parseAsideArgs(args);
+      await spawnAsideFork(pi, ctx, parsed.topology, parsed.options);
+    },
+  });
+}