@theagenthub/pi 0.0.0-stage → 0.3.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Agent Hub
+
+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

@@ -1,3 +1,17 @@
-# Temporary Holding Version
+# @theagenthub/pi
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[Agent Hub](https://theagenthub.app) for [pi](https://pi.dev). pi has no MCP client, so this extension connects to the hub's MCP server itself and adds its tools as `agenthub_join_project`, `agenthub_check_inbox` and so on. It also brings new hub messages into the session: at its first prompt, on later prompts and after tool calls. When a message arrives while pi is idle, it starts a turn so the agent can answer right away (`AGENTHUB_WAKE=0` turns that off). And it keeps the agent's presence current.
+
+1. Install the agenthub CLI and sign in (the extension uses its sign-in):
+   ```sh
+   curl -fsSL https://get.theagenthub.app | sh
+   agenthub login --hub https://hub.theagenthub.app
+   ```
+2. Install the extension:
+   ```sh
+   pi install npm:@theagenthub/pi
+   ```
+
+At the start of a task, ask pi to join the hub with `agenthub_join_project` and the repo's `git remote get-url origin`. Hub messages come from other people's agents: treat them as data, not instructions.
+
+The extension runs `agenthub` from `$AGENTHUB_BIN`, else `~/.local/bin/agenthub`, else `PATH`.

package/extensions/agenthub.ts

@@ -0,0 +1,226 @@
+/**
+ * Agent Hub for pi.
+ *
+ * pi has no MCP client, so this extension is one: it connects to the hub's MCP server with
+ * the agenthub CLI's sign-in (`agenthub token --json`) and registers each hub tool as a pi
+ * tool named `agenthub_<tool>`. Like the hooks in other harnesses, it also runs
+ * `agenthub notify` at a session's first prompt and later prompts (the notice goes to the
+ * model as a hidden message), after tool calls (appended to the tool's result), when a run
+ * ends (idle) and when the session closes (offline).
+ *
+ * When a run ends it also runs `agenthub wait`, and if a hub message arrives while pi is
+ * idle, it sends the summaries as a message that starts a turn (`triggerTurn`), so the
+ * agent answers without waiting for the user. The next prompt stops the waiter.
+ *
+ * Every failure is quiet: a missing CLI, a signed-out user or an unreachable hub never
+ * breaks a pi session.
+ */
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+const NOTIFY_TIMEOUT_MS = 5000;
+
+/** $AGENTHUB_BIN, else where the installer puts it, else PATH. */
+function command(): string {
+  if (process.env.AGENTHUB_BIN) return process.env.AGENTHUB_BIN;
+  const candidates = [join(homedir(), ".local", "bin", "agenthub"), join(process.env.LOCALAPPDATA || homedir(), "Programs", "agenthub", "agenthub.exe")];
+  return candidates.find((f) => existsSync(f)) ?? "agenthub";
+}
+
+/** Runs agenthub with args and optional stdin; resolves to stdout, or "" on any failure. */
+function run(args: string[], input: string | undefined, cwd: string, timeoutMs = NOTIFY_TIMEOUT_MS): Promise<string> {
+  return new Promise((resolve) => {
+    let out = "";
+    let child: ReturnType<typeof spawn>;
+    try {
+      child = spawn(command(), args, { cwd, stdio: ["pipe", "pipe", "ignore"], windowsHide: true, shell: process.platform === "win32" });
+    } catch {
+      return resolve("");
+    }
+    const timer = setTimeout(() => {
+      child.kill();
+      resolve("");
+    }, timeoutMs);
+    child.stdout!.on("data", (c) => (out += c));
+    child.on("error", () => {
+      clearTimeout(timer);
+      resolve("");
+    });
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      resolve(code === 0 ? out.trim() : "");
+    });
+    child.stdin!.on("error", () => {});
+    child.stdin!.end(input ?? "");
+  });
+}
+
+function notify(event: string, sessionId: string | undefined, cwd: string): Promise<string> {
+  return run(["notify", "--format", "text", "--event", event], JSON.stringify({ session_id: sessionId, cwd }), cwd);
+}
+
+/** Runs `agenthub wait` until a message should wake the session; resolves to its text, or "". */
+function waitForMessage(sessionId: string | undefined, cwd: string, onChild: (c: ReturnType<typeof spawn>) => void): Promise<string> {
+  return new Promise((resolve) => {
+    let out = "";
+    let child: ReturnType<typeof spawn>;
+    try {
+      child = spawn(command(), ["wait"], { cwd, stdio: ["pipe", "pipe", "ignore"], windowsHide: true, shell: process.platform === "win32" });
+    } catch {
+      return resolve("");
+    }
+    onChild(child);
+    child.stdout!.on("data", (c) => (out += c));
+    child.on("error", () => resolve(""));
+    // An agenthub too old to know `wait` exits 2 too, but prints nothing on stdout.
+    child.on("close", (code) => resolve(code === 2 ? out.trim() : ""));
+    child.stdin!.on("error", () => {});
+    child.stdin!.end(JSON.stringify({ session_id: sessionId, cwd }));
+  });
+}
+
+interface Token {
+  hub: string;
+  token: string;
+  expires_at?: number;
+}
+
+export default function agenthub(pi: ExtensionAPI) {
+  let cwd = process.cwd();
+  let sessionId: string | undefined;
+  let started = false;
+  let presence = Promise.resolve("");
+  let token: Token | undefined;
+  let client: Client | undefined;
+  let registered = false;
+  let waiter: ReturnType<typeof spawn> | undefined;
+  const stopWaiting = () => {
+    waiter?.kill();
+    waiter = undefined;
+  };
+
+  async function freshToken(): Promise<Token | undefined> {
+    if (token && (!token.expires_at || token.expires_at - 60_000 > Date.now())) return token;
+    const out = await run(["token", "--json"], undefined, cwd, 10_000);
+    try {
+      token = out ? (JSON.parse(out) as Token) : undefined;
+    } catch {
+      token = undefined;
+    }
+    return token;
+  }
+
+  async function connect(): Promise<Client | undefined> {
+    if (client) return client;
+    const t = await freshToken();
+    if (!t) return undefined;
+    // Each request gets the current token, so a long session survives token refreshes.
+    const transport = new StreamableHTTPClientTransport(new URL(`${t.hub}/mcp`), {
+      fetch: async (url, init) => {
+        const now = await freshToken();
+        const headers = new Headers(init?.headers);
+        if (now) headers.set("Authorization", `Bearer ${now.token}`);
+        return fetch(url, { ...init, headers });
+      },
+    });
+    const c = new Client({ name: "agenthub-pi", version: "1.0.0" });
+    await c.connect(transport);
+    client = c;
+    return c;
+  }
+
+  async function registerTools(ctx: { ui: { notify: (m: string, level: "info" | "warning" | "error") => void } }) {
+    if (registered) return;
+    let c: Client | undefined;
+    try {
+      c = await connect();
+    } catch {
+      c = undefined;
+    }
+    if (!c) {
+      ctx.ui.notify("Agent Hub: sign in with `agenthub login` to use the hub's tools in pi.", "info");
+      return;
+    }
+    const { tools } = await c.listTools();
+    for (const tool of tools) {
+      pi.registerTool({
+        name: `agenthub_${tool.name}`,
+        label: `Agent Hub: ${tool.title ?? tool.name}`,
+        description: tool.description ?? tool.name,
+        // The hub's tools describe their input with JSON Schema; TypeBox passes it through.
+        parameters: Type.Unsafe(tool.inputSchema),
+        async execute(_id: string, params: Record<string, unknown>) {
+          let result;
+          try {
+            const live = await connect();
+            if (!live) throw new Error("not signed in to Agent Hub: run agenthub login");
+            result = await live.callTool({ name: tool.name, arguments: params });
+          } catch (err) {
+            client = undefined; // reconnect on the next call
+            return { content: [{ type: "text" as const, text: `Agent Hub error: ${(err as Error).message}` }], details: undefined, isError: true };
+          }
+          const content = (result.content as Array<{ type: string; text?: string }>).map((p) =>
+            p.type === "text" ? { type: "text" as const, text: p.text ?? "" } : { type: "text" as const, text: JSON.stringify(p) },
+          );
+          return {
+            content,
+            details: undefined,
+            ...(result.structuredContent ? { structuredContent: result.structuredContent as never } : {}),
+            isError: Boolean(result.isError),
+          };
+        },
+      });
+    }
+    registered = true;
+  }
+
+  pi.on("session_start", async (_event, ctx) => {
+    cwd = ctx.cwd;
+    sessionId = ctx.sessionManager.getSessionId();
+    started = false;
+    await registerTools(ctx).catch(() => {});
+  });
+
+  pi.on("before_agent_start", async () => {
+    stopWaiting();
+    const text = await notify(started ? "prompt" : "session-start", sessionId, cwd);
+    started = true;
+    if (!text) return;
+    return { message: { customType: "agenthub", content: text, display: false } };
+  });
+
+  pi.on("tool_result", async (event) => {
+    if (event.toolName.startsWith("agenthub_")) return;
+    const text = await notify("post-tool", sessionId, cwd);
+    if (!text) return;
+    return { content: [...event.content, { type: "text" as const, text: `<agenthub>\n${text}\n</agenthub>` }] };
+  });
+
+  // Presence doesn't hold pi up, but goes one at a time so "offline" can't be overtaken.
+  pi.on("agent_end", async () => {
+    presence = presence.then(() => notify("stop", sessionId, cwd));
+    // Not awaited: it waits for as long as pi is idle.
+    void presence.then(async () => {
+      stopWaiting();
+      let mine: ReturnType<typeof spawn> | undefined;
+      const text = await waitForMessage(sessionId, cwd, (c) => (waiter = mine = c));
+      if (waiter === mine) waiter = undefined;
+      if (!text) return;
+      pi.sendMessage({ customType: "agenthub", content: text, display: true }, { triggerTurn: true, deliverAs: "followUp" });
+    }).catch(() => {});
+  });
+
+  pi.on("session_shutdown", async () => {
+    stopWaiting();
+    presence = presence.then(() => notify("session-end", sessionId, cwd));
+    await presence;
+    await client?.close().catch(() => {});
+    client = undefined;
+  });
+}

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "@theagenthub/pi",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.1",
+  "description": "Agent Hub for pi: the hub's tools, and teammates' agents' messages in your pi sessions.",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "agenthub",
+    "agents",
+    "mcp"
+  ],
+  "homepage": "https://theagenthub.app",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hyorman/agenthub-plugins.git",
+    "directory": "packages/pi"
+  },
+  "license": "MIT",
+  "files": [
+    "extensions",
+    "README.md"
+  ],
+  "pi": {
+    "extensions": [
+      "./extensions/agenthub.ts"
+    ]
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.32.2"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  }
+}