pi-subagentura 1.0.4 → 1.0.6

package/README.md

@@ -4,19 +4,24 @@
 
 > **Note:** The `docs/` folder is managed by the [`pi-docs`](https://github.com/lmn451/pi-docs) package.
 
-A public [Pi](https://pi.dev) package that adds two in-process sub-agent tools:
+A public [Pi](https://pi.dev) package that adds in-process sub-agent tools:
 
 - `subagent_with_context` — spawn a sub-agent that inherits the full conversation history
 - `subagent_isolated` — spawn a sub-agent with a fresh, empty context window
-
-The sub-agents run inside the current Pi process, stream live progress back to the UI, and inherit the active model by default.
+- `get_subagent_status` — poll an async subagent job for live progress
+- `get_subagent_result` — block until an async job completes and return the final output
+- `cancel_subagent` — abort a running async job
+- `prune_subagent_jobs` — remove all completed and failed jobs from the registry
+The sub-agents run inside the current Pi process, stream live progress back to the UI, and inherit the active model by default. Async sub-agents run in the background — the main agent continues immediately while you poll for progress and collect results when ready.
 
 ## Why use it?
 
 - Delegate focused side-tasks without leaving the current session
 - Compare context-aware vs isolated reasoning
 - Keep tool feedback lightweight with live status updates
-- Avoid subprocess overhead for sub-agent execution
+- Run sub-agents in the background while continuing the main conversation
+- Poll, collect, or cancel background jobs on demand
+- Get live previews of running sub-agents (current turn, active tool, usage)
 
 ![Sub-agent demo](working.png)
 
@@ -58,12 +63,16 @@ Parameters:
 - `persona` — optional system-style persona
 - `model` — optional model override like `anthropic/claude-sonnet-4-5`
 - `cwd` — optional working directory override
+- `async` — run in background; returns a jobId immediately instead of blocking
+- `notifyOnComplete` — `"notify"` or `"inject"`; auto-deliver completion notification (async only)
+- `maxAge` — optional TTL in ms for completed job retention (async only)
 
 Best for:
 
 - review tasks that depend on prior discussion
 - continuing a line of reasoning in parallel
 - focused implementation or research using the current context
+- background side-quests that report results later
 
 ### `subagent_isolated`
 
@@ -75,18 +84,64 @@ Parameters:
 - `persona` — optional system-style persona
 - `model` — optional model override like `anthropic/claude-sonnet-4-5`
 - `cwd` — optional working directory override
+- `async` — run in background; returns a jobId immediately instead of blocking
+- `notifyOnComplete` — `"notify"` or `"inject"`; auto-deliver completion notification (async only)
+- `maxAge` — optional TTL in ms for completed job retention (async only)
 
 Best for:
 
 - second opinions
 - clean-room summaries
 - avoiding context contamination from the parent session
+- background analysis without polluting the main conversation
+
+### Async Workflow Tools
+
+When you spawn a sub-agent with `async: true`, it returns a **jobId** immediately and runs in the background. Use these tools to manage async jobs:
+
+#### `get_subagent_status`
+
+Poll an async subagent job by jobId. Returns a live preview of the subagent's current turn, active tool, and partial output.
+
+Parameters:
+
+- `jobId` — required job ID returned by the async spawn
+
+#### `get_subagent_result`
+
+Block until an async subagent job completes, then return the final output and usage summary. If the job is already done, it returns immediately.
+
+Parameters:
+
+- `jobId` — required job ID returned by the async spawn
+
+#### `cancel_subagent`
+
+Abort a running async subagent job by jobId.
+
+Parameters:
+
+- `jobId` — required job ID returned by the async spawn
+
+#### `prune_subagent_jobs`
+
+Remove all completed and failed subagent jobs from the registry. Running and cancelled jobs are preserved.
+
+### `list_available_models`
+
+List all available AI models with auth status. Use this to validate model identifiers before passing them to subagent tools — prevents silent fallback to the parent session model.
+
+Parameters:
 
+- `filter` — optional substring filter for provider or model name
+- `authOnly` — if true (default), only return models with configured auth
 ## Example prompts
 
 - “Use a sub-agent to review this change and list risks.”
 - “Use an isolated sub-agent to propose a README outline for this repo.”
 - “Spawn a context-aware sub-agent to continue debugging while we keep planning here.”
+- “Run a sub-agent in the background to run the test suite, then notify me when done.”
+- “Spawn two isolated async sub-agents to review this code from different angles, then collect both results.”
 
 ## Development
 

package/helpers.ts

@@ -177,18 +177,35 @@ export function generateJobId(): string {
  * The caller (LLM agent) is responsible for providing the correct model id.
  * This function does NOT guess — it only does exact lookups:
  *   1. undefined → defaultModel
- *   2. "provider/id" format → exact getModel lookup
- *   3. Bare id → exact getModel scan across all providers
- *   4. Falls back to defaultModel when nothing matches
+ *   2. Use parent modelRegistry (has extension-added models like minimax)
+ *   3. "provider/id" format → exact getModel lookup (global static registry)
+ *   4. Bare id → exact getModel scan across all providers (global static registry)
+ *   5. Falls back to defaultModel when nothing matches
  */
 export function resolveModel(
   modelId: string | undefined,
-  // @ts-expect-error — Model<TApi> requires type arg; unknown is a safe placeholder here
+  // @ts-expect-error — Model<TApi> requires type arg; unknown is a safe placeholder
   defaultModel: Model | undefined,
+  parentModelRegistry?: ModelRegistry,
 ) {
   if (!modelId) return defaultModel;
 
-  // "provider/id" format — exact lookup only
+  // Only exact matching — no fuzzy/substring guessing.
+  // The AI should call list_available_models and pick from the list.
+  if (parentModelRegistry) {
+    if (modelId.includes("/")) {
+      const [provider, id] = modelId.split("/", 2);
+      const exact = parentModelRegistry.find(provider, id);
+      if (exact) return exact as any;
+    } else {
+      // Bare id — search all models in parent registry
+      for (const m of parentModelRegistry.getAll()) {
+        if (m.id === modelId) return m as any;
+      }
+    }
+  }
+
+  // Fall back to global static registry (built-in models only)
   if (modelId.includes("/")) {
     const [provider, id] = modelId.split("/", 2);
     // @ts-expect-error — getModel requires KnownProvider union; we trust the caller
@@ -255,6 +272,8 @@ export interface StartSubagentJobParams {
   // @ts-expect-error — Model<TApi> requires type arg
   defaultModel: Model | undefined;
   maxAge?: number;
+  /** Parent session's model registry for resolving extension-added models (e.g. minimax) */
+  parentModelRegistry?: ModelRegistry;
 }
 
 export interface StartSubagentJobResult {
@@ -263,6 +282,8 @@ export interface StartSubagentJobResult {
   session: AgentSession;
   liveStatus: SubagentLiveStatus;
   modelLabel?: string;
+  /** Warning when modelOverride was specified but not found — lists available models */
+  modelWarning?: string;
 }
 
 /**
@@ -286,6 +307,7 @@ export async function startSubagentJob(
     signal,
     onUpdate,
     defaultModel,
+    parentModelRegistry,
   } = params;
 
   // Enforce registry size cap before adding a new job
@@ -298,11 +320,25 @@ export async function startSubagentJob(
   const modelRegistry = ModelRegistry.create(authStorage);
 
   // Resolve model: exact match only, fallback to default
-  const targetModel = resolveModel(modelOverride, defaultModel);
+  // Uses parent's modelRegistry to find extension-added models (e.g. minimax)
+  const targetModel = resolveModel(modelOverride, defaultModel, parentModelRegistry);
   const modelLabel = targetModel
     ? `${targetModel.provider}/${targetModel.id}`
     : undefined;
 
+  // Build model warning when override was specified (helps AI discover valid models)
+  let modelWarning: string | undefined;
+  if (modelOverride && parentModelRegistry) {
+    const available = parentModelRegistry.getAvailable();
+    const modelList = available
+      .map((m) => `  ${m.provider}/${m.id}${m.name ? ` (${m.name})` : ""}`)
+      .join("\n");
+    modelWarning =
+      `Requested model "${modelOverride}" resolved to ${modelLabel ?? "none"}. ` +
+      `Available models:\n${modelList || "  (none)"}\n` +
+      `Use list_available_models to discover more.`;
+  }
+
   let handleAbort: (() => void) | undefined;
   let unsubscribe: (() => void) | undefined;
 
@@ -505,5 +541,5 @@ export async function startSubagentJob(
     return result;
   })();
 
-  return { jobId, jobPromise, session, liveStatus, modelLabel };
+  return { jobId, jobPromise, session, liveStatus, modelLabel, modelWarning };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-subagentura",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "Public Pi package that adds in-process sub-agents via the SDK",
   "main": "subagent.ts",
   "type": "module",

package/subagent.ts

@@ -23,6 +23,7 @@ import {
   type Theme,
   convertToLlm,
   serializeConversation,
+  ModelRegistry,
 } from "@mariozechner/pi-coding-agent";
 import type { AgentToolResult } from "@mariozechner/pi-agent-core";
 import type { Model } from "@mariozechner/pi-ai";
@@ -64,9 +65,10 @@ async function runSubagent(
   onUpdate: ((partial: AgentToolResult) => void) | undefined,
   // @ts-expect-error — Model<TApi> requires type arg; unknown is a safe placeholder
   defaultModel: Model | undefined,
+  parentModelRegistry: ModelRegistry | undefined,
 ): Promise<SubagentResult> {
   try {
-    const { jobPromise } = await startSubagentJob({
+    const { jobPromise, modelWarning } = await startSubagentJob({
       task,
       persona,
       modelOverride,
@@ -75,8 +77,14 @@ async function runSubagent(
       signal,
       onUpdate,
       defaultModel,
+      parentModelRegistry,
     });
-    return await jobPromise;
+    const result = await jobPromise;
+    // Surface model resolution info so the AI sees what model was used
+    if (modelWarning && !result.isError) {
+      result.output = `${modelWarning}\n---\n${result.output}`;
+    }
+    return result;
   } catch (err) {
     // Preserve original error formatting: if startSubagentJob throws
     // (e.g., createAgentSession auth failure), return clean SubagentResult
@@ -475,8 +483,18 @@ export default function (pi: ExtensionAPI) {
     label: "Sub-Agent (with context)",
     description: [
       "Spawn an in-process sub-agent that inherits the full conversation history.",
+      "WARNING: Each call serializes the entire conversation into memory. Spawning many",
+      "subagents with context in parallel can cause heap exhaustion (OOM).",
+      "",
+      "MEMORY-SAVING ALTERNATIVES:",
+      "1. Use subagent_isolated for tasks that don't need full history",
+      "2. Run few parallel subagents (1-3 at a time) instead of batching many",
+      "3. Consider summarizing the context before passing to subagent",
+      "",
       "The sub-agent sees everything discussed so far plus the new task.",
-      "Model is inherited by default. Streams output in real-time when sync.",
+      "Model is inherited by default. Use the model param to override (e.g. 'minimax/MiniMax-M2.7').",
+      "Use list_available_models to see which models have configured auth before setting model.",
+      "Streams output in real-time when sync.",
       "",
       "Examples:",
       '  - task: "Review this PR for security issues", persona: "You are a senior security auditor"',
@@ -513,7 +531,7 @@ export default function (pi: ExtensionAPI) {
         const conversationText = serializeConversation(llmMessages);
         const targetCwd = params.cwd ?? ctx.cwd;
 
-        const { jobId, jobPromise, session, liveStatus, modelLabel } =
+        const { jobId, jobPromise, session, liveStatus, modelLabel, modelWarning } =
           await startSubagentJob({
             task: params.task,
             persona: params.persona,
@@ -524,6 +542,7 @@ export default function (pi: ExtensionAPI) {
             onUpdate: undefined,
             defaultModel: ctx.model,
             maxAge: params.maxAge,
+            parentModelRegistry: ctx.modelRegistry,
           });
         const jobState: JobState = {
           id: jobId,
@@ -620,7 +639,8 @@ export default function (pi: ExtensionAPI) {
           content: [
             {
               type: "text",
-              text: `Job ${jobId} started. The main agent continues — use get_subagent_status to check progress and get_subagent_result to collect output when ready.`,
+              text: `Job ${jobId} started. The main agent continues — use get_subagent_status to check progress and get_subagent_result to collect output when ready.` +
+                (modelWarning ? `\n\n${modelWarning}` : ""),
             },
           ],
           details: {
@@ -654,6 +674,7 @@ export default function (pi: ExtensionAPI) {
         signal,
         onUpdate,
         ctx.model,
+        ctx.modelRegistry,
       );
 
       const usageStr = formatUsage(result.usage, result.model);
@@ -694,7 +715,9 @@ export default function (pi: ExtensionAPI) {
     description: [
       "Spawn an in-process sub-agent with a fresh, empty context window.",
       "Only receives the task and optional persona. No conversation history.",
-      "Model is inherited by default. Streams output in real-time when sync.",
+      "Model is inherited by default. Use the model param to override (e.g. 'minimax/MiniMax-M2.7').",
+      "Use list_available_models to see which models have configured auth before setting model.",
+      "Streams output in real-time when sync.",
       "",
       "Examples:",
       '  - task: "Propose a README outline for this repo", persona: "You are a technical writer"',
@@ -711,7 +734,7 @@ export default function (pi: ExtensionAPI) {
       if (params.async === true) {
         const targetCwd = params.cwd ?? ctx.cwd;
 
-        const { jobId, jobPromise, session, liveStatus, modelLabel } =
+        const { jobId, jobPromise, session, liveStatus, modelLabel, modelWarning } =
           await startSubagentJob({
             task: params.task,
             persona: params.persona,
@@ -722,6 +745,7 @@ export default function (pi: ExtensionAPI) {
             onUpdate: undefined,
             defaultModel: ctx.model,
             maxAge: params.maxAge,
+            parentModelRegistry: ctx.modelRegistry,
           });
         const jobState: JobState = {
           id: jobId,
@@ -821,7 +845,8 @@ export default function (pi: ExtensionAPI) {
           content: [
             {
               type: "text",
-              text: `Job ${jobId} started. The main agent continues — use get_subagent_status to check progress and get_subagent_result to collect output when ready.`,
+              text: `Job ${jobId} started. The main agent continues — use get_subagent_status to check progress and get_subagent_result to collect output when ready.` +
+                (modelWarning ? `\n\n${modelWarning}` : ""),
             },
           ],
           details: { jobId, status: "started" },
@@ -840,6 +865,7 @@ export default function (pi: ExtensionAPI) {
         signal,
         onUpdate,
         ctx.model,
+        ctx.modelRegistry,
       );
 
       const usageStr = formatUsage(result.usage, result.model);
@@ -876,8 +902,7 @@ export default function (pi: ExtensionAPI) {
   pi.registerTool({
     name: "get_subagent_status",
     label: "Get Subagent Status",
-    description:
-      "Poll an async subagent job by jobId. Returns live preview of the subagent's current turn, active tool, and output.",
+    description: "Poll an async subagent job by jobId. Returns live preview of the subagent's current turn, active tool, and output.",
     parameters: StatusParams,
 
     async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
@@ -891,7 +916,7 @@ export default function (pi: ExtensionAPI) {
               text: `Job ${params.jobId} not found. It may have been cancelled.`,
             },
           ],
-          details: { jobId: params.jobId },
+           details: { jobId: params.jobId, status: "not_found" },
           isError: true,
         };
       }