@howarewoo/pi-subagents 0.1.1 → 0.2.0

package/src/subagent-widget.ts

@@ -0,0 +1,115 @@
+import {
+  sliceByColumn,
+  truncateToWidth,
+  visibleWidth,
+  type Component,
+} from "@earendil-works/pi-tui";
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import type { ChildSnapshot } from "./coordinator.ts";
+import { active, activity, assignmentHeadline, lineText, statuses } from "./task-presentation.ts";
+
+/** Event-driven, bounded current-agent tree; history and full metrics remain in the Hub. */
+export function createChildWidget(
+  snapshot: () => ChildSnapshot[],
+  theme: Pick<Theme, "fg"> & Partial<Pick<Theme, "bold">>,
+  availableRows = () => 30,
+): Component {
+  return {
+    render(width) {
+      width = Math.max(0, width);
+      const children = snapshot();
+      if (!children.length) return [];
+      const queued = children.filter((child) => child.status === "queued").length;
+      const priority = (child: ChildSnapshot) =>
+        child.status === "draining" || child.status === "pausing"
+          ? 0
+          : child.status === "running"
+            ? 1
+            : child.status === "setup"
+              ? 2
+              : 3;
+      const live = children
+        .filter(
+          (child) =>
+            !child.disposed &&
+            (child.status === "setup" ||
+              child.status === "running" ||
+              child.status === "draining" ||
+              child.status === "pausing"),
+        )
+        .sort((a, b) => priority(a) - priority(b));
+      const budget = Math.max(1, Math.min(5, Math.floor(availableRows() / 4)));
+      const counts =
+        width < 60
+          ? `${live.filter(active).length} active · ${children.filter((child) => child.status === "paused").length} paused · ${queued} queued`
+          : statuses
+              .flatMap((status) => {
+                const count = children.filter((child) => child.status === status).length;
+                return count ? [`${count} ${status}`] : [];
+              })
+              .join(" · ");
+      const rows = [
+        theme.fg("accent", `● Subagents ${children.length}`) + theme.fg("muted", ` · ${counts}`),
+      ];
+      const room = Math.max(0, budget - 1);
+      const activityRows = live.length && room >= (live.length > 1 ? 3 : 2) ? 1 : 0;
+      const slots = room - activityRows;
+      const overflow = live.length > slots;
+      const shown = live.slice(0, Math.max(0, slots - (overflow ? 1 : 0)));
+      shown.forEach((child, index) => {
+        const last = index === shown.length - 1 && shown.length === live.length;
+        const color =
+          child.status === "draining" || child.status === "pausing" ? "warning" : "accent";
+        const role = lineText(child.profile);
+        const indent = "  ".repeat(Math.min(3, Math.max(0, child.depth - 1)));
+        const prefix =
+          theme.fg("muted", `${indent}${last ? "└─" : "├─"} `) +
+          theme.fg(color, "● ") +
+          (theme.bold?.(role) ?? role) +
+          " ";
+        const elapsed = Math.max(
+          0,
+          Math.floor(((child.endedAt ?? Date.now()) - child.createdAt) / 1000),
+        );
+        const stats = [
+          child.status,
+          `${elapsed}s`,
+          `${child.toolCalls} tools`,
+          ...(child.telemetry.requests === null ? [] : [`${child.telemetry.requests} req`]),
+          ...(child.telemetry.tokens ? [`${child.telemetry.tokens.total} tok`] : []),
+          ...(child.telemetry.cost === null ? [] : [`$${child.telemetry.cost.toFixed(3)}`]),
+        ].join(" · ");
+        const metric = truncateToWidth(stats, Math.max(8, Math.floor(width / 2)));
+        const headline = assignmentHeadline(child);
+        rows.push(
+          prefix +
+            theme.fg(
+              "text",
+              truncateToWidth(
+                headline,
+                Math.max(4, width - visibleWidth(prefix) - visibleWidth(metric) - 3),
+              ),
+            ) +
+            theme.fg("muted", " · " + metric),
+        );
+        if (!index && activityRows) {
+          const prefix = `${indent}${last ? "   " : "│  "} └ `;
+          const text = lineText(activity(child));
+          const columns = Math.max(0, width - visibleWidth(prefix));
+          const length = visibleWidth(text);
+          // Progress is an accumulated tail; keep its newest text, not a frozen opening paragraph.
+          const preview =
+            length > columns
+              ? "…" +
+                sliceByColumn(text, length - Math.max(0, columns - 1), Math.max(0, columns - 1))
+              : text;
+          rows.push(theme.fg("muted", prefix + preview));
+        }
+      });
+      if (shown.length < live.length && room)
+        rows.push(theme.fg("muted", `└─ ${live.length - shown.length} more · /subagent-hub`));
+      return rows.slice(0, budget).map((line) => truncateToWidth(line, width));
+    },
+    invalidate() {},
+  };
+}

package/src/supported-host.ts

@@ -0,0 +1,26 @@
+import { VERSION } from "@earendil-works/pi-coding-agent";
+
+const MINIMUM_PI_VERSION = "1.5.2";
+const minimum = MINIMUM_PI_VERSION.split(".").map(BigInt);
+
+/** Gate execution, not registration: root diagnostics and cleanup must remain usable. */
+export function requireSupportedHost(): void {
+  // Only stable SemVer, with optional build metadata (which has no precedence).
+  const stable =
+    typeof VERSION === "string"
+      ? /^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/.exec(
+          VERSION,
+        )
+      : null;
+  if (stable && stable[0] === VERSION) {
+    // BigInt keeps numeric comparison exact without a version-component size limit.
+    const difference = stable
+      .slice(1, 4)
+      .map((part, index) => BigInt(part) - minimum[index]!)
+      .find((part) => part !== 0n);
+    if (difference === undefined || difference > 0n) return;
+  }
+  throw new Error(
+    `Delegated execution requires supported stable Pi >=${MINIMUM_PI_VERSION}; detected ${VERSION || "unknown"}. Install stable Pi ${MINIMUM_PI_VERSION} or newer and restart Pi after draining active tasks.`,
+  );
+}

package/src/task-input.ts

@@ -11,7 +11,7 @@ export async function readTaskInput(
   path: string,
   ctx: ExtensionToolContext,
   signal?: AbortSignal,
-  beforeRead?: () => void,
+  beforeRead?: () => void | Promise<void>,
   cwd = ctx.cwd,
 ): Promise<string> {
   if (!path || isAbsolute(path) || path.includes("\0") || hasDeniedTaskComponent(path))
@@ -32,7 +32,8 @@ export async function readTaskInput(
   if (!before.isFile() || before.size === 0 || before.size > 50000)
     throw new Error("taskFile must be a nonempty regular text file of at most 50000 bytes");
   signal?.throwIfAborted();
-  beforeRead?.();
+  await beforeRead?.();
+  signal?.throwIfAborted();
   const outcome = await ctx.executeTool("read", { path: target }, { signal });
   if (outcome.isError)
     throw new Error(

package/src/task-presentation.ts

@@ -0,0 +1,165 @@
+import { truncateToWidth } from "@earendil-works/pi-tui";
+import type { ChildSnapshot, DelegationCoordinator } from "./coordinator.ts";
+import { safe } from "./thread.ts";
+
+export const lineText = (text: string) => safe(text).replaceAll("\n", " ");
+export const assignmentHeadline = (child: ChildSnapshot) =>
+  safe(child.assignment)
+    .split("\n")
+    .map((line) => line.trim())
+    .find(Boolean)
+    ?.replace(/^#{1,6}\s+/, "") || "Assignment";
+export const agentLabel = (child: ChildSnapshot) =>
+  `${assignmentHeadline(child)} · ${lineText(child.profile)}`;
+export const active = (child: ChildSnapshot) => !child.disposed && child.status !== "paused";
+export const activity = (child: ChildSnapshot) =>
+  (child.status === "paused"
+    ? `Paused: ${child.pauseReason ?? "deadline"} · context ${child.retainedContext ? "retained" : "not yet available"} · resume via model or stop in Hub`
+    : child.error) ||
+  (active(child) ? child.activity || child.progress : child.result) ||
+  child.progress ||
+  "Waiting for SDK activity";
+export const writerWarning = "Model-tool writer only: no conflicting manual !/!! or external edits";
+export const statuses = [
+  "queued",
+  "setup",
+  "running",
+  "draining",
+  "pausing",
+  "paused",
+  "settled",
+  "failed",
+  "cancelled",
+] as const;
+export function fleetSummary(children: ChildSnapshot[]): string {
+  return children.length
+    ? statuses
+        .map((status) => `${status} ${children.filter((child) => child.status === status).length}`)
+        .join(" · ")
+    : "No tasks · ask the model to delegate_task";
+}
+
+export function taskCard(child: ChildSnapshot | undefined, expanded = false): string[] {
+  if (!child)
+    return [
+      "Task identity unavailable",
+      "See tool error; /subagent-hub lists current runtime tasks",
+    ];
+  const headline = `${truncateToWidth(assignmentHeadline(child), 240, "… [preview truncated]")} · ${lineText(child.profile)} #${child.generation} · ${child.status}`;
+  if (!expanded)
+    return [
+      headline,
+      ...(child.status === "paused"
+        ? [
+            `Pause: ${truncateToWidth(lineText(child.pauseReason ?? "deadline"), 240, "… [preview truncated]")}`,
+          ]
+        : child.error
+          ? [`Error: ${truncateToWidth(lineText(child.error), 240, "… [preview truncated]")}`]
+          : []),
+    ].map(lineText);
+  return [
+    headline,
+    `Identity ${child.id} #${child.generation}`,
+    `${child.model.provider}/${child.model.id} · effort ${child.effort ?? "unavailable"}`,
+    truncateToWidth(lineText(activity(child)), 240, "… [preview truncated]"),
+    `Prewalk ${child.prewalk ? JSON.stringify(child.prewalk) : "off"} · advisor unavailable`,
+    `Parent ${child.parentId}${child.parentGeneration ? ` #${child.parentGeneration}` : ""} · depth ${child.depth} · writer lease ${child.writerLease}`,
+    ...(child.outcome
+      ? [
+          `Structured ${child.outcome.validation} · ${child.outcome.finalized ? "finalized" : "provisional"} · attempts ${child.outcome.attempts}`,
+        ]
+      : []),
+    ...(child.limitReason ? [`Limit: ${child.limitReason}`] : []),
+    ...(child.pauseReason
+      ? [
+          `Pause: ${child.pauseReason} · context ${child.retainedContext ? "retained" : "not yet available"} · resume via model control after drain`,
+        ]
+      : []),
+    `Window ${child.window ?? 1} · cumulative requests ${child.telemetry.requests ?? 0}/${child.limits.requests} · tools ${child.toolCalls}/${child.limits.tools} · spawns ${child.spawned ?? 0}/${child.limits.spawns}`,
+    ...(child.artifacts ? [`Artifacts: ${JSON.stringify(child.artifacts)}`] : []),
+    "Assignment: " + truncateToWidth(lineText(child.assignment), 480, "… [preview truncated]"),
+    "Result: " +
+      truncateToWidth(
+        lineText(child.result || child.error || "Not available yet"),
+        480,
+        "… [preview truncated]",
+      ),
+    child.transcript
+      ? `Full transcript: ${child.transcript} · /subagent-hub`
+      : "Transcript unavailable (setup) · /subagent-hub",
+  ].map(lineText);
+}
+
+/** Read-only content projection: never dumps provider/auth objects, image payloads or opaque signatures. */
+export function transcriptLines(
+  messages: ReturnType<DelegationCoordinator["messages"]>,
+  toolsOnly = false,
+): string[] {
+  const lines: string[] = [];
+  for (const message of messages) {
+    if (message.role === "system") continue;
+    const start = lines.length;
+    const blocks = "content" in message ? message.content : undefined;
+    if (!toolsOnly || message.role === "toolResult") {
+      lines.push(
+        `[${message.role}${message.role === "toolResult" ? ` ${message.toolName} ${message.toolCallId} ${message.isError ? "ERROR" : "result"}` : ""}]`,
+      );
+      if (typeof blocks === "string") lines.push(safe(blocks));
+    }
+    if (Array.isArray(blocks))
+      for (const block of blocks) {
+        if (block.type === "toolCall")
+          lines.push(
+            `Tool ${block.name} ${block.id}\nArguments: ${safe(JSON.stringify(block.arguments, null, 2))}`,
+          );
+        else if (!toolsOnly || message.role === "toolResult") {
+          if (block.type === "text") lines.push(safe(block.text));
+          else if (block.type === "thinking") lines.push("Thinking: " + safe(block.thinking));
+          else if (block.type === "image")
+            lines.push(`[image ${safe(block.mimeType)}; payload omitted]`);
+        }
+      }
+    if (message.role === "assistant" && message.errorMessage)
+      lines.push("Error: " + safe(message.errorMessage));
+    if (start && lines.length > start) lines.splice(start, 0, "");
+  }
+  return lines.length
+    ? lines.map(safe)
+    : [toolsOnly ? "No tool calls yet" : "Waiting for SDK messages"];
+}
+
+export function taskDetails(
+  child: ChildSnapshot,
+  presence: ReturnType<DelegationCoordinator["agents"]>[number]["presence"],
+): string[] {
+  const metric = (value: unknown) =>
+    value === null || value === undefined ? "unavailable" : JSON.stringify(value);
+  return [
+    `Identity ${child.id} #${child.generation}`,
+    "",
+    "Assignment",
+    safe(child.assignment),
+    "",
+    "Result",
+    safe(child.result || "Not available yet"),
+    "",
+    ...(child.error ? ["Error", safe(child.error), ""] : []),
+    ...(child.outcome ? ["Structured outcome", JSON.stringify(child.outcome, null, 2), ""] : []),
+    ...(child.artifacts ? ["Saved artifacts", JSON.stringify(child.artifacts, null, 2), ""] : []),
+    `Workspace: ${safe(child.cwd ?? "parent workspace")}`,
+    `Effective builtin tools: ${child.tools.join(", ")}`,
+    `${child.model.provider}/${child.model.id} · effort ${child.effort ?? "unavailable"}`,
+    `Prewalk ${child.prewalk ? JSON.stringify(child.prewalk) : "off"} · advisor unavailable`,
+    `Presence ${presence ?? "historical"} · resources ${child.disposed ? "disposed" : child.status === "paused" ? "idle SDK; context retained; model resume required" : "live"}`,
+    `Elapsed ${Math.max(0, Math.floor(((child.endedAt ?? Date.now()) - child.createdAt) / 1000))}s`,
+    `Direct requests ${metric(child.telemetry.requests)} · cost ${metric(child.telemetry.cost)}`,
+    `Direct tokens ${metric(child.telemetry.tokens)}`,
+    `Context ${metric(child.telemetry.context)}`,
+    `Parent ${child.parentId} #${child.parentGeneration ?? "root"} · depth ${child.depth} · direct generation only`,
+    `Limits ${JSON.stringify(child.limits)} · calls ${child.toolCalls} · reason ${child.limitReason ?? "none"}`,
+    "Activity: " + safe(activity(child)),
+    "Full transcript: " + safe(child.transcript ?? "unavailable (queued/setup)"),
+    "Followup/revive: native delegate_coordinate only (Hub has no tool dispatcher)",
+    ...(child.writerLease ? [writerWarning] : []),
+  ];
+}

package/src/tool-schemas.ts

@@ -0,0 +1,165 @@
+import { Type } from "typebox";
+import { EFFORTS } from "./model-policy.ts";
+import { COORDINATION_ACTIONS } from "./profiles.ts";
+
+const role = Type.Union([
+  Type.Literal("general"),
+  Type.Literal("scout"),
+  Type.Literal("review"),
+  Type.Literal("implementation"),
+]);
+const limits = Type.Object(
+  {
+    depth: Type.Optional(Type.Integer({ minimum: 0 })),
+    spawns: Type.Optional(Type.Integer({ minimum: 0 })),
+    deadlineMs: Type.Optional(Type.Integer({ minimum: 1 })),
+    requests: Type.Optional(Type.Integer({ minimum: 1 })),
+    tools: Type.Optional(Type.Integer({ minimum: 1 })),
+  },
+  { additionalProperties: false },
+);
+const modelSelection = Type.Object(
+  {
+    provider: Type.String({ minLength: 1 }),
+    id: Type.String({ minLength: 1 }),
+    effort: Type.Enum(EFFORTS),
+  },
+  { additionalProperties: false },
+);
+const assignment = {
+  cwd: Type.Optional(
+    Type.String({
+      minLength: 1,
+      description:
+        "Existing workspace; absolute or relative to root parent cwd. No new permissions or sandbox.",
+    }),
+  ),
+  models: Type.Optional(Type.Array(modelSelection, { maxItems: 64 })),
+  model: Type.Optional(modelSelection),
+  assignment: Type.Optional(Type.String({ minLength: 1 })),
+  taskFile: Type.Optional(Type.String({ minLength: 1 })),
+  resultSchema: Type.Optional(Type.Unknown()),
+  profile: role,
+  spawn: Type.Optional(Type.Array(role)),
+  coordination: Type.Optional(
+    Type.Array(Type.Union(COORDINATION_ACTIONS.map((action) => Type.Literal(action)))),
+  ),
+  limits: Type.Optional(limits),
+};
+const item = Type.Object(assignment, { additionalProperties: false });
+export const parameters = Type.Union([
+  Type.Object(
+    { ...assignment, background: Type.Optional(Type.Boolean()) },
+    { additionalProperties: false },
+  ),
+  Type.Object(
+    {
+      tasks: Type.Array(item, { minItems: 1, maxItems: 64 }),
+      background: Type.Optional(Type.Boolean()),
+    },
+    { additionalProperties: false },
+  ),
+]);
+
+const identity = Type.Object(
+  { id: Type.String({ minLength: 1 }), generation: Type.Integer({ minimum: 1 }) },
+  { additionalProperties: false },
+);
+export const coordinationParameters = Type.Union([
+  Type.Object(
+    {
+      action: Type.Literal("message"),
+      target: Type.Optional(identity),
+      text: Type.String({ minLength: 1, maxLength: 4096 }),
+      mode: Type.Optional(
+        Type.Union([Type.Literal("inbox"), Type.Literal("steer"), Type.Literal("followUp")]),
+      ),
+    },
+    { additionalProperties: false },
+  ),
+  Type.Object({ action: Type.Literal("inbox") }, { additionalProperties: false }),
+  Type.Object(
+    {
+      action: Type.Literal("wait"),
+      target: Type.Optional(identity),
+      messageId: Type.Optional(Type.String({ minLength: 1 })),
+      timeoutMs: Type.Integer({ minimum: 1, maximum: 60000 }),
+    },
+    { additionalProperties: false },
+  ),
+  Type.Object(
+    {
+      action: Type.Union([Type.Literal("park"), Type.Literal("stop"), Type.Literal("status")]),
+      target: identity,
+    },
+    { additionalProperties: false },
+  ),
+  Type.Object(
+    {
+      action: Type.Union([Type.Literal("followup"), Type.Literal("revive")]),
+      target: identity,
+      assignment: Type.String({ minLength: 1 }),
+      resultSchema: Type.Optional(Type.Unknown()),
+    },
+    { additionalProperties: false },
+  ),
+  Type.Object(
+    {
+      action: Type.Literal("resume"),
+      target: identity,
+      assignment: Type.String({ minLength: 1 }),
+    },
+    { additionalProperties: false },
+  ),
+]);
+
+const worker = Type.Union([role, Type.Literal("worker")]);
+const compatibleItem = Type.Object(
+  {
+    agent: worker,
+    task: Type.String({ minLength: 1 }),
+    cwd: Type.Optional(
+      Type.String({
+        minLength: 1,
+        description:
+          "Existing workspace; absolute or relative to root parent cwd. Omit to inherit the call default.",
+      }),
+    ),
+    model: Type.Optional(Type.Union([modelSelection, Type.String({ minLength: 1 })])),
+    limits: Type.Optional(limits),
+  },
+  { additionalProperties: false },
+);
+export const compatibleParameters = Type.Union([
+  Type.Object(
+    { ...compatibleItem.properties, async: Type.Optional(Type.Boolean()) },
+    { additionalProperties: false },
+  ),
+  Type.Object(
+    {
+      tasks: Type.Array(compatibleItem, { minItems: 1, maxItems: 64 }),
+      async: Type.Optional(Type.Boolean()),
+      cwd: Type.Optional(Type.String({ minLength: 1 })),
+    },
+    { additionalProperties: false },
+  ),
+  Type.Object(
+    { action: Type.Union([Type.Literal("list"), Type.Literal("agents")]) },
+    { additionalProperties: false },
+  ),
+  Type.Object(
+    {
+      action: Type.Union([Type.Literal("status"), Type.Literal("stop")]),
+      id: Type.String({ minLength: 1 }),
+    },
+    { additionalProperties: false },
+  ),
+  Type.Object(
+    {
+      action: Type.Union([Type.Literal("steer"), Type.Literal("resume")]),
+      id: Type.String({ minLength: 1 }),
+      message: Type.String({ minLength: 1 }),
+    },
+    { additionalProperties: false },
+  ),
+]);