@pi-ohm/subagents 0.6.4-dev.22132543465.1.e4e3071 → 0.6.4-dev.22169815567.1.cdde4e8

package/README.md

@@ -27,7 +27,8 @@ from profile IDs with deterministic collision handling.
 - direct-tool execution and task-routed execution share the same runtime/result envelope
 
 The orchestration tool name is **`task`**. Async orchestration lifecycle
-operations (`start/status/wait/send/cancel`) are exposed through this tool.
+operations (`start/status/wait/send/cancel`) are exposed through this tool, but
+default execution is sync (`async:false`). Use `async:true` only for background/long tasks.
 
 ## Task tool (current)
 
@@ -36,8 +37,38 @@ Current behavior:
 - supports `op: "start"` for a single task payload (sync + `async:true`)
 - supports batched `op: "start"` payloads via `tasks[]` with optional `parallel:true`
 - supports lifecycle operations: `status`, `wait`, `send`, `cancel`
-- compatibility aliases: `status`/`wait` accept `id` or `ids`; `op:"result"` is normalized to `status`
+- input normalization: `status`/`wait` accept `id` or `ids`; `op:"result"` is normalized to `status`
+- non-debug result text renders Amp-style inline message trees (prompt -> tool calls -> result)
+- running background updates use minimal inline progress lines
 - returns `task_id`, status, and deterministic task details
+- includes explicit wait/cancel ergonomics fields:
+  - `wait_status` (`completed|timeout|aborted`)
+  - `done` (boolean completion flag for `wait`)
+  - `cancel_applied`
+  - `prior_status`
+- includes batch acceptance accounting for `start` with `tasks[]`:
+  - `total_count`
+  - `accepted_count`
+  - `rejected_count`
+  - `batch_status` (`accepted|partial|completed|rejected`)
+- includes structured output metadata in details/items:
+  - `output_available`
+  - `output_truncated`
+  - `output_total_chars`
+  - `output_returned_chars`
+- includes structured SDK-derived tool transcript rows in details/items when available:
+  - `tool_rows` (deterministic per-tool lifecycle rows)
+  - `event_count` (captured structured event count)
+  - `assistant_text` (event-derived assistant transcript tail)
+- includes machine marker on every tool details payload:
+  - `contract_version: "task.v1"`
+- includes observability fields on details/items:
+  - `provider`
+  - `model`
+  - `runtime`
+  - `route`
+- collection lifecycle ops (`status`/`wait`) aggregate observability from task items
+  (so top-level `runtime`/`route` align with per-item metadata when present)
 - persists task registry snapshots to disk for resume/reload behavior
 - enforces terminal-task retention expiry with explicit `task_expired` lookup errors
 - validates all payloads with TypeBox boundary schema + typed Result errors
@@ -48,11 +79,34 @@ Runtime backend is selected from `subagentBackend` config:
 
 - `interactive-shell` (default): executes a real nested `pi` run for subagent prompts
   using built-in tools (`read,bash,edit,write,grep,find,ls`)
+- `interactive-sdk` (opt-in): executes subagent prompts through in-process Pi SDK
+  sessions with in-memory session/settings managers
 - `none`: uses deterministic scaffold backend (echo-style debug output)
 - `custom-plugin`: currently returns `unsupported_subagent_backend`
 
+Optional safety fallback:
+
+- set `OHM_SUBAGENTS_SDK_FALLBACK_TO_CLI=true` to fallback from `interactive-sdk` to
+  `interactive-shell` when SDK bootstrap/execution fails (`task_backend_execution_failed`)
+
 If output appears like prompt regurgitation, verify `subagentBackend` is not set to `none`.
 
+Nested interactive-shell outputs are sanitized to strip runtime metadata lines (`backend:`,
+`provider:`, `model:`) before surfacing task output.
+
+For unknown tasks/expired tasks, error categorization is explicit: `error_category: "not_found"`.
+
+### Output truncation policy
+
+Task output returned in tool payloads is capped to prevent oversized context injection.
+
+- env override: `OHM_SUBAGENTS_OUTPUT_MAX_CHARS`
+- default cap: `8000` chars
+- when truncation occurs, payloads include:
+  - `output_truncated: true`
+  - `output_total_chars`
+  - `output_returned_chars`
+
 Example payload:
 
 ```jsonc
@@ -69,6 +123,8 @@ Batch execution notes:
 - aggregate item order is deterministic (input order)
 - bounded parallelism is enforced by `subagents.taskMaxConcurrency` (default `3`)
 - task failures are isolated; one failed batch item does not abort siblings
+- async mixed-validity batch starts no longer collapse to top-level failure when tasks were accepted;
+  use acceptance counters + `batch_status` to decide polling behavior
 
 ## Task permission policy
 
@@ -121,38 +177,68 @@ Existing slash commands remain unchanged:
 - `/ohm-subagents`
 - `/ohm-subagent <id>`
 
+## Invocation mode behavior
+
+`task-routed` and `primary-tool` invocation paths share one runtime/result envelope.
+
+Current shared fields:
+
+- `contract_version`
+- `status`
+- `subagent_type`
+- `description`
+- `backend`
+- `provider`
+- `model`
+- `runtime`
+- `route`
+- `output_available`
+- `output` (subject to truncation policy)
+
+Invocation mode differences are intentional and explicit via `invocation`:
+
+- `task-routed` for non-primary profiles
+- `primary-tool` for direct primary profile calls
+
 ## Live TUI feedback
 
-`@pi-ohm/subagents` uses `@mariozechner/pi-tui` for task runtime visuals.
+`@pi-ohm/subagents` uses shared component `@pi-ohm/tui` (`SubagentTaskTreeComponent`) for task runtime visuals.
+Live bottom widget mode now defaults to `off`; inline tool-result updates are the primary UX.
 
 Baseline running-task display includes:
 
 - spinner
-- task description (from original `task` start payload)
-- in-flight tool call count
-- elapsed time (`mm:ss`)
+- prompt line from task start payload (main-agent instruction)
+- best-effort parsed tool-call rows
+- terminal/final result row
 
 Runtime UI surfaces are synchronized from one task snapshot model:
 
 - footer status (`setStatus`) with running/active counters
-- widget task list (`setWidget`) using two-line per-task renderer
+- widget task tree (`setWidget`) using Amp-style tree component
 - headless fallback `onUpdate` text with equivalent description/tool-count/elapsed info
 
 Example running block:
 
 ```bash
-⠋ [finder] Auth flow scan
-  Tools 3/3 · Elapsed 00:18
+  ⠋ Finder · Auth flow scan
+    ├── Trace auth validation
+    ├── ✓ Read packages/subagents/src
+    ├── ✓ Grep auth|token in packages/subagents/src
+    ╰── Working...
 ```
 
 Terminal examples:
 
 ```bash
-✓ [finder] Auth flow scan
-  Tools 5/5 · Elapsed 00:42
-
-✕ [finder] Auth flow scan
-  Tools 2/3 · Elapsed 00:11
+  ✓ Finder · Auth flow scan
+    ├── Trace auth validation
+    ├── ✓ Read packages/subagents/src
+    ╰── Auth validation path uses task permission policy + runtime store transitions.
+
+  ✕ Finder · Auth flow scan
+    ├── Trace auth validation
+    ╰── Task failed: backend timeout while reading repository files.
 ```
 
 ## Error handling
@@ -167,3 +253,23 @@ Commands:
 
 - `/ohm-subagents`
 - `/ohm-subagent <id>`
+
+## Primary tool input schemas
+
+For profiles marked `primary:true`, direct tool input schema is subagent-specific:
+
+- `librarian`
+  - required: `query`
+  - optional: `context`, `async`, `description`
+- `oracle`
+  - required: `task`
+  - optional: `context`, `files[]`, `async`, `description`
+- `finder`
+  - required: `query`
+  - optional: `async`, `description`
+
+Normalization behavior:
+
+- `context` is forwarded in a dedicated prompt section (`Context:`)
+- oracle `files[]` is forwarded in a dedicated prompt block (`Files:` + bullet paths)
+- task lifecycle/result payload remains the same shape after primary normalization

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-ohm/subagents",
-  "version": "0.6.4-dev.22132543465.1.e4e3071",
+  "version": "0.6.4-dev.22169815567.1.cdde4e8",
   "homepage": "https://github.com/pi-ohm/pi-ohm/tree/dev/packages/subagents#readme",
   "repository": {
     "type": "git",
@@ -20,7 +20,8 @@
   },
   "dependencies": {
     "@mariozechner/pi-coding-agent": "catalog:pi",
-    "@pi-ohm/config": "0.6.4-dev.22132543465.1.e4e3071",
+    "@pi-ohm/config": "0.6.4-dev.22169815567.1.cdde4e8",
+    "@pi-ohm/tui": "0.6.4-dev.22169815567.1.cdde4e8",
     "better-result": "catalog:",
     "zod": "catalog:"
   },

package/src/extension.test.ts

@@ -2,8 +2,10 @@ import assert from "node:assert/strict";
 import test from "node:test";
 import type { OhmRuntimeConfig } from "@pi-ohm/config";
 import { getSubagentById } from "./catalog";
+import { getTaskLiveUiMode, setTaskLiveUiMode } from "./runtime/live-ui";
 import {
   buildSubagentDetailText,
+  resolveSubagentsLiveUiModeCommand,
   buildSubagentsOverviewText,
   getSubagentInvocationMode,
   normalizeCommandArgs,
@@ -135,3 +137,23 @@ defineTest("buildSubagentDetailText preserves detailed subagent view", () => {
   assert.match(text, /When to use:/);
   assert.match(text, /Scaffold prompt:/);
 });
+
+defineTest("resolveSubagentsLiveUiModeCommand sets requested mode", () => {
+  setTaskLiveUiMode("compact");
+
+  const result = resolveSubagentsLiveUiModeCommand(["verbose"]);
+
+  assert.equal(result.ok, true);
+  assert.equal(result.mode, "verbose");
+  assert.equal(getTaskLiveUiMode(), "verbose");
+});
+
+defineTest("resolveSubagentsLiveUiModeCommand rejects invalid mode values", () => {
+  setTaskLiveUiMode("compact");
+
+  const result = resolveSubagentsLiveUiModeCommand(["loud"]);
+
+  assert.equal(result.ok, false);
+  assert.match(result.message, /off\|compact\|verbose/);
+  assert.equal(getTaskLiveUiMode(), "compact");
+});

package/src/extension.ts

@@ -2,6 +2,12 @@ import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import { loadOhmRuntimeConfig, registerOhmSettings, type OhmRuntimeConfig } from "@pi-ohm/config";
 import { getSubagentById, OHM_SUBAGENT_CATALOG } from "./catalog";
 import { isSubagentVisibleInTaskRoster } from "./policy";
+import {
+  getTaskLiveUiMode,
+  parseTaskLiveUiModeInput,
+  setTaskLiveUiMode,
+  type TaskLiveUiMode,
+} from "./runtime/live-ui";
 import { registerPrimarySubagentTools } from "./tools/primary";
 import { createDefaultTaskToolDependencies, registerTaskTool } from "./tools/task";
 
@@ -107,6 +113,47 @@ export function buildSubagentDetailText(input: {
   ].join("\n");
 }
 
+export interface ResolveSubagentsLiveUiModeResult {
+  readonly ok: boolean;
+  readonly mode: TaskLiveUiMode;
+  readonly message: string;
+}
+
+export function resolveSubagentsLiveUiModeCommand(args: unknown): ResolveSubagentsLiveUiModeResult {
+  const [requestedModeRaw] = normalizeCommandArgs(args);
+  const currentMode = getTaskLiveUiMode();
+
+  if (!requestedModeRaw) {
+    return {
+      ok: true,
+      mode: currentMode,
+      message: [
+        `subagents live ui mode: ${currentMode}`,
+        "Usage: /ohm-subagents-live <off|compact|verbose>",
+      ].join("\n"),
+    };
+  }
+
+  const parsedMode = parseTaskLiveUiModeInput(requestedModeRaw);
+  if (!parsedMode) {
+    return {
+      ok: false,
+      mode: currentMode,
+      message: [`Invalid mode '${requestedModeRaw}'.`, "Use one of: off|compact|verbose"].join(
+        "\n",
+      ),
+    };
+  }
+
+  setTaskLiveUiMode(parsedMode);
+
+  return {
+    ok: true,
+    mode: parsedMode,
+    message: `subagents live ui mode set to '${parsedMode}'`,
+  };
+}
+
 export function registerSubagentTools(pi: Pick<ExtensionAPI, "registerTool">): {
   readonly primaryToolCount: number;
   readonly diagnosticsCount: number;
@@ -189,4 +236,25 @@ export default function registerSubagentsExtension(pi: ExtensionAPI): void {
       await ctx.ui.editor(`pi-ohm ${match.id} subagent`, text);
     },
   });
+
+  pi.registerCommand("ohm-subagents-live", {
+    description: "Set subagents live UI mode (off|compact|verbose)",
+    handler: async (args, ctx) => {
+      const result = resolveSubagentsLiveUiModeCommand(args);
+
+      if (!ctx.hasUI) {
+        console.log(result.message);
+        return;
+      }
+
+      if (result.mode === "off") {
+        ctx.ui.setStatus("ohm-subagents", undefined);
+        ctx.ui.setWidget("ohm-subagents", undefined, { placement: "belowEditor" });
+      } else {
+        ctx.ui.setStatus("ohm-subagents", `subagents live ui: ${result.mode}`);
+      }
+
+      await ctx.ui.editor("pi-ohm subagents live", result.message);
+    },
+  });
 }