@pi-ohm/subagents 0.6.2 → 0.6.3

package/README.md

@@ -1,6 +1,6 @@
 # @pi-ohm/subagents
 
-Install only subagent delegation support for Pi.
+Install only subagent support for Pi (task-routed + primary-tool profiles).
 
 ```bash
 pi install npm:@pi-ohm/subagents
@@ -8,12 +8,54 @@ pi install npm:@pi-ohm/subagents
 
 Scaffolded subagents:
 
-- `librarian` — multi-repo code understanding
+- `librarian` — multi-repo code understanding (default: primary-tool profile)
 - `oracle` — reasoning-heavy advisor/reviewer
 - `finder` — intelligent behavior-based search
 - `task` — isolated parallel execution worker
 - `painter` — explicit-request image generation/editing helper
 
+Profiles can be marked with `primary: true` in config/catalog to indicate direct
+invocation as a top-level tool entrypoint instead of task-tool-only invocation.
+
+The orchestration tool name is **`task`**. Async orchestration lifecycle
+operations (`start/status/wait/send/cancel`) are exposed through this tool.
+
+## Live TUI feedback
+
+`@pi-ohm/subagents` uses `@mariozechner/pi-tui` for task runtime visuals.
+
+Baseline running-task display includes:
+
+- spinner
+- task description (from original `task` start payload)
+- in-flight tool call count
+- elapsed time (`mm:ss`)
+
+Example running block:
+
+```bash
+⠋ [finder] Auth flow scan
+  Tools 3/3 · Elapsed 00:18
+```
+
+Terminal examples:
+
+```bash
+✓ [finder] Auth flow scan
+  Tools 5/5 · Elapsed 00:42
+
+✕ [finder] Auth flow scan
+  Tools 2/3 · Elapsed 00:11
+```
+
+## Error handling
+
+`@pi-ohm/subagents` uses `better-result` for recoverable errors:
+
+- runtime and orchestration paths should return `Result<T, E>`
+- typed error categories should use `TaggedError`
+- avoid broad try/catch error propagation for recoverable failures
+
 Commands:
 
 - `/ohm-subagents`

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@pi-ohm/subagents",
-  "version": "0.6.2",
+  "version": "0.6.3",
+  "homepage": "https://github.com/pi-ohm/pi-ohm/tree/dev/packages/subagents#readme",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/pi-ohm/pi-ohm.git",
@@ -18,8 +19,8 @@
     "provenance": true
   },
   "dependencies": {
-    "@mariozechner/pi-coding-agent": "^0.52.0",
-    "@pi-ohm/config": "^0.6.2"
+    "@mariozechner/pi-coding-agent": "catalog:pi",
+    "@pi-ohm/config": "^0.6.3"
   },
   "peerDependencies": {
     "@mariozechner/pi-coding-agent": "*"

package/src/catalog.ts

@@ -4,20 +4,33 @@ export interface OhmSubagentDefinition {
   id: OhmSubagentId;
   name: string;
   summary: string;
+  /**
+   * When true, this profile should be exposed as a directly invokable primary tool
+   * instead of requiring delegated Task-style invocation.
+   */
+  primary?: boolean;
   whenToUse: string[];
   scaffoldPrompt: string;
   requiresPackage?: string;
 }
 
+// should probably refactor these prompts... please don't sue me, Amp
+// imitation is the sincerest form of flattery
 export const OHM_SUBAGENT_CATALOG: readonly OhmSubagentDefinition[] = [
   {
     id: "librarian",
     name: "Librarian",
-    summary: "Multi-repo codebase understanding subagent (GitHub/Bitbucket architecture analysis).",
+    summary:
+      "A specialized codebase understanding agent that helps you answer questions about large, complex codebases. Works by reading from temporary local github checkouts. Works as your personal, multi-repository codebase expert, providing thorough analysis and comprehensive explanations across repositories",
+    primary: true,
     whenToUse: [
-      "Understand architecture across multiple repositories",
-      "Build implementation maps before migration/refactor",
-      "Trace ownership boundaries across services",
+      "Understanding complex multi-repository codebases and how they work",
+      "Exploring relationships between different repositories",
+      "Analyzing architectural patterns across large open-source projects",
+      "Finding specific implementations across multiple codebases",
+      "Understanding code evolution and commit history",
+      "Getting comprehensive explanations of how major features work",
+      "Exploring how systems are designed end-to-end across repositories",
     ],
     scaffoldPrompt:
       "Analyze this codebase (and linked repos if provided). Build an architecture map: boundaries, key modules, integration points, and risky coupling.",
@@ -28,9 +41,11 @@ export const OHM_SUBAGENT_CATALOG: readonly OhmSubagentDefinition[] = [
     summary:
       "Reasoning-heavy advisor for code review, architecture feedback, complex debugging, and planning.",
     whenToUse: [
-      "Get second-opinion architecture critique",
-      "Review risky design decisions before implementation",
-      "Debug ambiguous failures with hypothesis ranking",
+      "Code reviews and architecture feedback",
+      "Finding difficult bugs in codepaths that flow across many files",
+      "Planning complex implementations or refactors",
+      "Answering complex technical questions that require deep technical reasoning",
+      "Providing an alternative point of view when you are struggling to solve a problem",
     ],
     scaffoldPrompt:
       "Act as a critical reviewer. Challenge assumptions, rank risks, and provide a concrete implementation plan with trade-offs.",
@@ -38,40 +53,44 @@ export const OHM_SUBAGENT_CATALOG: readonly OhmSubagentDefinition[] = [
   {
     id: "finder",
     name: "Finder",
-    summary: "Concept/behavior-based search subagent for multi-step codebase discovery.",
+    summary:
+      "Intelligently search your codebase: Use it for complex, multi-step search tasks where you need to find code based on functionality or concepts rather than exact matches. Anytime you want to chain multiple grep calls you should use this tool.",
     whenToUse: [
-      "Find all call sites for a behavior, not just symbol references",
-      "Map data flow across modules",
-      "Locate implicit coupling and duplicated logic",
+      "You must locate code by behavior or concept",
+      "You need to run multiple greps in sequence",
+      "You must correlate or look for connection between several areas of the codebase",
+      `You must filter broad terms ("config", "logger", "cache") by context.`,
+      `You need answers to questions such as "Where do we validate JWT authentication headers?" or "Which module handles file-watcher retry logic"`,
     ],
     scaffoldPrompt:
       "Search this codebase for all implementations and call paths related to the requested behavior. Return files, rationale, and confidence.",
   },
-  {
-    id: "task",
-    name: "Task",
-    summary: "Independent execution subagent for parallelizable tasks with isolated tool context.",
-    whenToUse: [
-      "Parallelize work across unrelated app areas",
-      "Delegate focused implementation tasks",
-      "Run isolated experiments without polluting main context",
-    ],
-    scaffoldPrompt:
-      "Execute this focused implementation task independently. Return a concise summary of changes, validation, and follow-up risks.",
-  },
-  {
-    id: "painter",
-    name: "Painter",
-    summary: "Image generation/editing subagent used only on explicit request.",
-    whenToUse: [
-      "Generate concept/mock images",
-      "Edit existing images based on prompt instructions",
-      "Produce visual assets when user explicitly asks for image output",
-    ],
-    scaffoldPrompt:
-      "Generate or edit an image per user request. Confirm intent first, then return prompt + provider/model metadata with result notes.",
-    requiresPackage: "@pi-ohm/painter",
-  },
+  // {
+  //   id: "task",
+  //   name: "Task",
+  //   summary:
+  //     "Independent execution subagent for parallelizable tasks with isolated tool context.",
+  //   whenToUse: [
+  //     "Parallelize work across unrelated app areas",
+  //     "Delegate focused implementation tasks",
+  //     "Run isolated experiments without polluting main context",
+  //   ],
+  //   scaffoldPrompt:
+  //     "Execute this focused implementation task independently. Return a concise summary of changes, validation, and follow-up risks.",
+  // },
+  // {
+  //   id: "painter",
+  //   name: "Painter",
+  //   summary: "Image generation/editing subagent used only on explicit request.",
+  //   whenToUse: [
+  //     "Generate concept/mock images",
+  //     "Edit existing images based on prompt instructions",
+  //     "Produce visual assets when user explicitly asks for image output",
+  //   ],
+  //   scaffoldPrompt:
+  //     "Generate or edit an image per user request. Confirm intent first, then return prompt + provider/model metadata with result notes.",
+  //   requiresPackage: "@pi-ohm/painter",
+  // },
 ] as const;
 
 export function getSubagentById(id: string): OhmSubagentDefinition | undefined {

package/src/extension.ts

@@ -52,7 +52,8 @@ export default function registerSubagentsExtension(pi: ExtensionAPI): void {
         const needsPainterPackage = agent.id === "painter";
         const available = !needsPainterPackage || config.features.painterImagegen;
         const availability = available ? "available" : "requires painter feature/package";
-        return `- ${agent.name} (${agent.id}): ${agent.summary} [${availability}]`;
+        const invocation = agent.primary ? "primary-tool" : "delegated";
+        return `- ${agent.name} (${agent.id}): ${agent.summary} [${availability} · ${invocation}]`;
       });
 
       const text = [
@@ -106,6 +107,7 @@ export default function registerSubagentsExtension(pi: ExtensionAPI): void {
         `Subagent: ${match.name}`,
         `id: ${match.id}`,
         `available: ${isAvailable ? "yes" : "no"}`,
+        `invocation: ${match.primary ? "primary-tool" : "delegated"}`,
         match.requiresPackage
           ? `requiresPackage: ${match.requiresPackage}`
           : "requiresPackage: none",