@gotgenes/pi-subagents 4.0.0 → 4.1.1

package/src/tools/get-result-tool.ts

@@ -0,0 +1,99 @@
+import { Type } from "@sinclair/typebox";
+import type { AgentRecord } from "../types.js";
+import { formatDuration, getDisplayName } from "../ui/agent-widget.js";
+import { getSessionContextPercent } from "../usage.js";
+import { formatLifetimeTokens, textResult } from "./helpers.js";
+
+/** Narrow deps — only the methods this tool's execute callback calls. */
+export interface GetResultDeps {
+  getRecord: (id: string) => AgentRecord | undefined;
+  cancelNudge: (key: string) => void;
+  getConversation: (session: unknown) => string | undefined;
+}
+
+/** Create the get_subagent_result tool definition (without Pi SDK wrapper). */
+export function createGetResultTool(deps: GetResultDeps) {
+  return {
+    name: "get_subagent_result" as const,
+    label: "Get Agent Result",
+    description:
+      "Check status and retrieve results from a background agent. Use the agent ID returned by Agent with run_in_background.",
+    parameters: Type.Object({
+      agent_id: Type.String({
+        description: "The agent ID to check.",
+      }),
+      wait: Type.Optional(
+        Type.Boolean({
+          description: "If true, wait for the agent to complete before returning. Default: false.",
+        }),
+      ),
+      verbose: Type.Optional(
+        Type.Boolean({
+          description:
+            "If true, include the agent's full conversation (messages + tool calls). Default: false.",
+        }),
+      ),
+    }),
+    execute: async (
+      _toolCallId: string,
+      params: { agent_id: string; wait?: boolean; verbose?: boolean },
+      _signal: AbortSignal,
+      _onUpdate: unknown,
+      _ctx: unknown,
+    ) => {
+      const record = deps.getRecord(params.agent_id);
+      if (!record) {
+        return textResult(`Agent not found: "${params.agent_id}". It may have been cleaned up.`);
+      }
+
+      // Wait for completion if requested.
+      // Pre-mark resultConsumed BEFORE awaiting: onComplete fires inside .then()
+      // (attached earlier at spawn time) and always runs before this await resumes.
+      // Setting the flag here prevents a redundant follow-up notification.
+      if (params.wait && record.status === "running" && record.promise) {
+        record.resultConsumed = true;
+        deps.cancelNudge(params.agent_id);
+        await record.promise;
+      }
+
+      const displayName = getDisplayName(record.type);
+      const duration = formatDuration(record.startedAt, record.completedAt);
+      const tokens = formatLifetimeTokens(record);
+      const contextPercent = getSessionContextPercent(record.session);
+      const statsParts = [`Tool uses: ${record.toolUses}`];
+      if (tokens) statsParts.push(tokens);
+      if (contextPercent !== null) statsParts.push(`Context: ${Math.round(contextPercent)}%`);
+      if (record.compactionCount) statsParts.push(`Compactions: ${record.compactionCount}`);
+      statsParts.push(`Duration: ${duration}`);
+
+      let output =
+        `Agent: ${record.id}\n` +
+        `Type: ${displayName} | Status: ${record.status} | ${statsParts.join(" | ")}\n` +
+        `Description: ${record.description}\n\n`;
+
+      if (record.status === "running") {
+        output += "Agent is still running. Use wait: true or check back later.";
+      } else if (record.status === "error") {
+        output += `Error: ${record.error}`;
+      } else {
+        output += record.result?.trim() || "No output.";
+      }
+
+      // Mark result as consumed — suppresses the completion notification
+      if (record.status !== "running" && record.status !== "queued") {
+        record.resultConsumed = true;
+        deps.cancelNudge(params.agent_id);
+      }
+
+      // Verbose: include full conversation
+      if (params.verbose && record.session) {
+        const conversation = deps.getConversation(record.session);
+        if (conversation) {
+          output += `\n\n--- Agent Conversation ---\n${conversation}`;
+        }
+      }
+
+      return textResult(output);
+    },
+  };
+}

package/src/tools/helpers.ts

@@ -0,0 +1,21 @@
+import { formatTokens } from "../ui/agent-widget.js";
+import { getLifetimeTotal, type LifetimeUsage } from "../usage.js";
+
+/** Tool execute return value for a text response. */
+export function textResult(msg: string, details?: unknown) {
+  return { content: [{ type: "text" as const, text: msg }], details: details as any };
+}
+
+/** Format an agent's lifetime token total, or "" when zero. */
+export function formatLifetimeTokens(o: { lifetimeUsage: LifetimeUsage }): string {
+  const t = getLifetimeTotal(o.lifetimeUsage);
+  return t > 0 ? formatTokens(t) : "";
+}
+
+/** Derive a short model label from a model string. */
+export function getModelLabelFromConfig(model: string): string {
+  // Strip provider prefix (e.g. "anthropic/claude-sonnet-4-6" → "claude-sonnet-4-6")
+  const name = model.includes("/") ? model.split("/").pop()! : model;
+  // Strip trailing date suffix (e.g. "claude-haiku-4-5-20251001" → "claude-haiku-4-5")
+  return name.replace(/-\d{8}$/, "");
+}

package/src/tools/steer-tool.ts

@@ -0,0 +1,83 @@
+import { Type } from "@sinclair/typebox";
+import type { AgentRecord } from "../types.js";
+import { getSessionContextPercent } from "../usage.js";
+import { formatLifetimeTokens, textResult } from "./helpers.js";
+
+/** Narrow deps — only the methods this tool's execute callback calls. */
+export interface SteerToolDeps {
+  getRecord: (id: string) => AgentRecord | undefined;
+  emitEvent: (name: string, data: unknown) => void;
+  steerAgent: (session: unknown, message: string) => Promise<void>;
+}
+
+/** Create the steer_subagent tool definition (without Pi SDK wrapper). */
+export function createSteerTool(deps: SteerToolDeps) {
+  return {
+    name: "steer_subagent" as const,
+    label: "Steer Agent",
+    description:
+      "Send a steering message to a running agent. The message will interrupt the agent after its current tool execution " +
+      "and be injected into its conversation, allowing you to redirect its work mid-run. Only works on running agents.",
+    parameters: Type.Object({
+      agent_id: Type.String({
+        description: "The agent ID to steer (must be currently running).",
+      }),
+      message: Type.String({
+        description:
+          "The steering message to send. This will appear as a user message in the agent's conversation.",
+      }),
+    }),
+    execute: async (
+      _toolCallId: string,
+      params: { agent_id: string; message: string },
+      _signal: AbortSignal,
+      _onUpdate: unknown,
+      _ctx: unknown,
+    ) => {
+      const record = deps.getRecord(params.agent_id);
+      if (!record) {
+        return textResult(
+          `Agent not found: "${params.agent_id}". It may have been cleaned up.`,
+        );
+      }
+      if (record.status !== "running") {
+        return textResult(
+          `Agent "${params.agent_id}" is not running (status: ${record.status}). Cannot steer a non-running agent.`,
+        );
+      }
+      if (!record.session) {
+        // Session not ready yet — queue the steer for delivery once initialized
+        if (!record.pendingSteers) record.pendingSteers = [];
+        record.pendingSteers.push(params.message);
+        deps.emitEvent("subagents:steered", { id: record.id, message: params.message });
+        return textResult(
+          `Steering message queued for agent ${record.id}. It will be delivered once the session initializes.`,
+        );
+      }
+
+      try {
+        await deps.steerAgent(record.session, params.message);
+        deps.emitEvent("subagents:steered", { id: record.id, message: params.message });
+        const tokens = formatLifetimeTokens(record);
+        const contextPercent = getSessionContextPercent(record.session);
+        const stateParts: string[] = [];
+        if (tokens) stateParts.push(tokens);
+        stateParts.push(`${record.toolUses} tool ${record.toolUses === 1 ? "use" : "uses"}`);
+        if (contextPercent !== null)
+          stateParts.push(`context ${Math.round(contextPercent)}% full`);
+        if (record.compactionCount)
+          stateParts.push(
+            `${record.compactionCount} compaction${record.compactionCount === 1 ? "" : "s"}`,
+          );
+        return textResult(
+          `Steering message sent to agent ${record.id}. The agent will process it after its current tool execution.\n` +
+            `Current state: ${stateParts.join(" · ")}`,
+        );
+      } catch (err) {
+        return textResult(
+          `Failed to steer agent: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }
+    },
+  };
+}