@rol1n/subagent 0.0.0-stage → 0.1.0

package/extensions/subagent/session.ts

@@ -0,0 +1,166 @@
+import { openSync, readFileSync, readSync, closeSync } from "node:fs";
+
+export interface SessionEntry {
+  type: string;
+  id: string;
+  parentId?: string | null;
+  [key: string]: unknown;
+}
+
+export interface AssistantMessage {
+  role: "assistant";
+  content?: unknown;
+  stopReason?: string;
+  errorMessage?: string;
+  model?: string;
+  usage?: Record<string, unknown>;
+}
+
+export interface SessionUsage {
+  model?: string;
+  toolCount: number;
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+  contextTokens: number;
+  cost: number;
+}
+
+export function readEntries(sessionFile: string): SessionEntry[] {
+  let content: string;
+  try {
+    content = readFileSync(sessionFile, "utf8");
+  } catch {
+    return [];
+  }
+  const entries: SessionEntry[] = [];
+  for (const line of content.split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      entries.push(JSON.parse(line));
+    } catch {
+      // ignore malformed or mid-append lines
+    }
+  }
+  return entries;
+}
+
+export function getSessionId(sessionFile: string): string | null {
+  let fd: number | undefined;
+  try {
+    fd = openSync(sessionFile, "r");
+    const buf = Buffer.allocUnsafe(4096);
+    const bytes = readSync(fd, buf, 0, 4096, 0);
+    if (bytes <= 0) return null;
+    const nl = buf.indexOf(0x0a);
+    const end = nl === -1 || nl >= bytes ? bytes : nl;
+    const firstLine = buf.toString("utf8", 0, end).trim();
+    if (!firstLine) return null;
+    const parsed = JSON.parse(firstLine);
+    return parsed.type === "session" && typeof parsed.id === "string" ? parsed.id : null;
+  } catch {
+    return null;
+  } finally {
+    if (fd !== undefined) {
+      try {
+        closeSync(fd);
+      } catch {}
+    }
+  }
+}
+
+/**
+ * Extracts the last assistant response text from a session JSONL file.
+ * Handles auto-retry error messages as fallback.
+ */
+export function findLastAssistantMessage(sessionFile: string): string | null {
+  const entries = readEntries(sessionFile);
+  for (let i = entries.length - 1; i >= 0; i--) {
+    const entry = entries[i];
+    if (entry.type !== "message" || typeof entry.message !== "object" || entry.message === null) continue;
+    const msg = entry.message as AssistantMessage;
+    if (msg.role !== "assistant") continue;
+
+    if (Array.isArray(msg.content)) {
+      const texts: string[] = [];
+      for (const block of msg.content) {
+        if (typeof block === "object" && block !== null && (block as any).type === "text" && typeof (block as any).text === "string") {
+          texts.push((block as any).text);
+        }
+      }
+      const combined = texts.join("\n").trim();
+      if (combined) return combined;
+    }
+
+    if (msg.stopReason === "error" && typeof msg.errorMessage === "string" && msg.errorMessage.trim()) {
+      return `Worker error: ${msg.errorMessage.trim()}`;
+    }
+  }
+  return null;
+}
+
+/**
+ * Summarize token usage and cost across all assistant turns.
+ */
+export function readSessionUsage(sessionFile: string): SessionUsage | undefined {
+  let content: string;
+  try {
+    content = readFileSync(sessionFile, "utf8");
+  } catch {
+    return undefined;
+  }
+
+  const usage: SessionUsage = {
+    toolCount: 0,
+    input: 0,
+    output: 0,
+    cacheRead: 0,
+    cacheWrite: 0,
+    contextTokens: 0,
+    cost: 0,
+  };
+
+  const num = (value: unknown): number =>
+    typeof value === "number" && Number.isFinite(value) ? value : 0;
+
+  for (const line of content.split("\n")) {
+    if (!line.trim()) continue;
+    let entry: Record<string, unknown>;
+    try {
+      entry = JSON.parse(line);
+    } catch {
+      continue;
+    }
+
+    if (entry.type === "model_change" && typeof entry.modelId === "string" && entry.modelId) {
+      usage.model = entry.modelId;
+      continue;
+    }
+    if (entry.type !== "message") continue;
+    const message = entry.message as AssistantMessage | undefined;
+    if (!message || message.role !== "assistant") continue;
+
+    if (typeof message.model === "string" && message.model) usage.model = message.model;
+    if (Array.isArray(message.content)) {
+      for (const block of message.content) {
+        if (typeof block === "object" && block !== null && (block as any).type === "toolCall") {
+          usage.toolCount++;
+        }
+      }
+    }
+
+    const record = message.usage as Record<string, unknown> | undefined;
+    if (!record || typeof record !== "object") continue;
+    usage.input += num(record.input);
+    usage.output += num(record.output);
+    usage.cacheRead += num(record.cacheRead);
+    usage.cacheWrite += num(record.cacheWrite);
+    const total = num(record.totalTokens);
+    if (total > 0) usage.contextTokens = total;
+    const cost = record.cost as Record<string, unknown> | undefined;
+    if (cost && typeof cost === "object") usage.cost += num(cost.total);
+  }
+
+  return usage;
+}

package/extensions/subagent/skills/subagent/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: subagent
+description: Dispatch, message, and collaborate with parallel, full-powered Pi subagent workers running in split terminal panes or silent background processes.
+---
+
+# Subagent
+
+Use the native `subagent` tool to delegate tasks to independent, full-powered Pi instances ("workers"). Workers run in dedicated split terminal panes (inside tmux or Zellij) or run silently as background processes (in standard terminals, VSCode, CI/CD, or headless environments). Every worker inherits all standard tools, skills, and extensions, and operates completely asynchronously.
+
+## Spawning Workers
+
+Call the `subagent` tool directly. The tool returns **immediately** with an acknowledgement. You do **not** need to wait or poll:
+
+```json
+subagent({
+  "task": "Investigate the authentication middleware in src/auth.ts and propose fixes.",
+  "name": "auth-audit"
+})
+```
+
+- `task`: Clear, comprehensive instructions for the worker.
+- `name`: Short, descriptive identifier (e.g. `frontend`, `db-migration`, `tester`).
+- `model`: (Optional) Model override (e.g. a faster model for simple exploration).
+- `cwd`: (Optional) Working directory for the worker.
+
+### Parallel Workers
+
+You can dispatch **multiple workers in parallel in a single turn**:
+
+```json
+[
+  { "name": "subagent", "arguments": { "task": "Audit frontend router in src/routes/", "name": "frontend" } },
+  { "name": "subagent", "arguments": { "task": "Audit database models in src/db/", "name": "backend" } }
+]
+```
+
+All workers run concurrently in separate split panes. As each worker finishes, the system automatically injects its final result into your conversation as a **steer message**, waking you up to review the findings.
+
+## Non-Blocking Principle
+
+- **DO NOT** write bash scripts, `sleep` commands, `tail` logs, or polling loops to check on a worker.
+- **DO NOT** fabricate or assume worker results before receiving the steer message.
+- After calling `subagent`, either end your turn immediately or work on other independent tasks. The harness will wake you with the result as soon as it is ready.
+
+## Answering Worker Questions
+
+Workers have an `ask_question` tool. When a worker encounters ambiguity or needs a decision:
+1. The worker pauses its work and marks itself as `waiting: ask`.
+2. You receive a steer notification: `[Subagent "<name>" question] ...`.
+3. Answer the worker by targeting its name:
+
+```json
+subagent({
+  "target": "auth-audit",
+  "task": "Use the JWT verification method rather than session cookies."
+})
+```
+
+The worker absorbs your guidance, resumes execution, and reports back when done.
+
+## Stopping a Worker
+
+If a worker is no longer needed or is off-track, terminate it:
+
+```json
+subagent({
+  "target": "auth-audit",
+  "action": "stop"
+})
+```

package/extensions/subagent/ui.ts

@@ -0,0 +1,100 @@
+/**
+ * subagent/ui.ts — Status widget for active subagent workers above the editor.
+ *
+ * Compact, borderless, multi-worker friendly layout matching the SRP theme suite.
+ */
+
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { readSessionUsage, type SessionUsage } from "./session.ts";
+
+export type WorkerState = "running" | "waiting" | "done" | "error";
+
+export interface WorkerStatus {
+  name: string;
+  state: WorkerState;
+  startTime: number;
+  sessionFile: string;
+  question?: string;
+  error?: string;
+  backend?: string;
+}
+
+export function formatTokenCount(value: number): string {
+  if (value < 1000) return `${value}`;
+  if (value < 1_000_000) return `${(value / 1000).toFixed(1)}k`;
+  return `${(value / 1_000_000).toFixed(2)}M`;
+}
+
+export function formatElapsed(seconds: number): string {
+  const total = Math.max(0, Math.floor(seconds));
+  const m = Math.floor(total / 60);
+  const s = total % 60;
+  if (m > 0) return `${m}m${String(s).padStart(2, "0")}s`;
+  return `${s}s`;
+}
+
+function usageSegments(usage: SessionUsage): string[] {
+  const parts: string[] = [];
+  if (usage.toolCount > 0) parts.push(`${usage.toolCount} calls`);
+  if (usage.input > 0) parts.push(`↑${formatTokenCount(usage.input)}`);
+  if (usage.output > 0) parts.push(`↓${formatTokenCount(usage.output)}`);
+  if (usage.cost > 0) parts.push(`$${usage.cost < 0.1 ? usage.cost.toFixed(4) : usage.cost.toFixed(2)}`);
+  return parts;
+}
+
+function stateStyle(state: WorkerState, theme: Theme): { icon: string; label: string } {
+  switch (state) {
+    case "running":
+      return { icon: theme.fg("accent", "●"), label: theme.fg("accent", "running") };
+    case "waiting":
+      return { icon: theme.fg("warning", "◆"), label: theme.fg("warning", "waiting: ask") };
+    case "done":
+      return { icon: theme.fg("success", "✔"), label: theme.fg("success", "done") };
+    case "error":
+      return { icon: theme.fg("error", "✖"), label: theme.fg("error", "error") };
+  }
+}
+
+/**
+ * Render multi-worker status lines for ctx.ui.setWidget.
+ */
+export function renderWorkersWidget(workers: WorkerStatus[], theme: Theme, maxRows = 4): string[] {
+  if (workers.length === 0) return [];
+
+  const waitingCount = workers.filter((w) => w.state === "waiting").length;
+  const statusNote = waitingCount > 0 ? theme.fg("warning", ` · ${waitingCount} awaiting reply`) : "";
+  const header = `${theme.fg("accent", "◆")} ${theme.bold("Subagents")} ${theme.fg("dim", `· ${workers.length} active`)}${statusNote}`;
+
+  const visible = workers.slice(0, maxRows);
+  const overflow = workers.length - visible.length;
+
+  const rows = visible.map((worker) => {
+    const elapsed = formatElapsed((Date.now() - worker.startTime) / 1000);
+    const { icon, label } = stateStyle(worker.state, theme);
+
+    let detail = "";
+    if (worker.state === "waiting" && worker.question) {
+      const q = worker.question.length > 40 ? `${worker.question.slice(0, 37)}...` : worker.question;
+      detail = ` ${theme.fg("warning", `[Q: "${q}"]`)}`;
+    } else {
+      const usage = readSessionUsage(worker.sessionFile);
+      if (usage) {
+        const segments = usageSegments(usage).map((seg) => theme.fg("dim", seg));
+        if (segments.length > 0) detail = ` ${segments.join(theme.fg("dim", " · "))}`;
+      }
+    }
+
+    if (worker.state === "error" && worker.error) {
+      detail = ` ${theme.fg("error", worker.error.split("\n")[0])}`;
+    }
+
+    const backendTag = worker.backend === "process" ? theme.fg("dim", " [bg]") : "";
+    return `  ${icon} ${theme.bold(worker.name)}${backendTag} ${label} ${theme.fg("dim", elapsed)}${detail}`;
+  });
+
+  if (overflow > 0) {
+    rows.push(`  ${theme.fg("muted", `+${overflow} more workers running...`)}`);
+  }
+
+  return [header, ...rows];
+}

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "@rol1n/subagent",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "type": "module",
+  "description": "subagent extension from pi-kit",
+  "keywords": [
+    "pi-package"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/RolinShmily/pi-kit.git",
+    "directory": "extensions/subagent"
+  },
+  "homepage": "https://github.com/RolinShmily/pi-kit#readme",
+  "bugs": {
+    "url": "https://github.com/RolinShmily/pi-kit/issues"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "extensions/subagent",
+    "extensions/subagent/README.md"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-agent-core": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions/subagent/index.ts"
+    ],
+    "skills": [],
+    "prompts": [],
+    "themes": []
+  }
+}