@pi-ohm/subagents 0.6.3 → 0.6.4-dev.22132458683.1.8646f56

package/README.md

@@ -17,9 +17,110 @@ Scaffolded subagents:
 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.
 
+Primary profiles are registered as direct tools automatically. Tool names are derived
+from profile IDs with deterministic collision handling.
+
+`primary: true` is additive:
+
+- profile gets a direct top-level tool
+- profile stays available in `task` subagent roster (`subagent_type`)
+- 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.
 
+## Task tool (current)
+
+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`
+- returns `task_id`, status, and deterministic task details
+- 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
+
+## Subagent backend behavior
+
+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`)
+- `none`: uses deterministic scaffold backend (echo-style debug output)
+- `custom-plugin`: currently returns `unsupported_subagent_backend`
+
+If output appears like prompt regurgitation, verify `subagentBackend` is not set to `none`.
+
+Example payload:
+
+```jsonc
+{
+  "op": "start",
+  "subagent_type": "finder",
+  "description": "Auth flow scan",
+  "prompt": "Trace token validation + refresh paths",
+}
+```
+
+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
+
+## Task permission policy
+
+Task orchestration enforces policy decisions from runtime config:
+
+- `allow` — task execution proceeds
+- `deny` — execution is blocked with `task_permission_denied`
+
+Config shape:
+
+```jsonc
+{
+  "subagents": {
+    "permissions": {
+      "default": "allow",
+      "subagents": {
+        "finder": "deny",
+      },
+      "allowInternalRouting": false,
+    },
+  },
+}
+```
+
+Additional hardening behaviors:
+
+- internal profiles (`internal:true`) are hidden from task roster exposure unless
+  `allowInternalRouting` is enabled
+- wait timeout/abort are explicit (`task_wait_timeout`, `task_wait_aborted`)
+- tool error payloads include stable `error_category`
+
+Persistence details:
+
+- default snapshot path: `${PI_CONFIG_DIR|PI_CODING_AGENT_DIR|PI_AGENT_DIR|~/.pi/agent}/ohm.subagents.tasks.json`
+- retention window is configurable via `OHM_SUBAGENTS_TASK_RETENTION_MS` (positive integer ms)
+- corrupt snapshot files are auto-recovered to `*.corrupt-<epoch>` and runtime falls back to empty state
+
+## Migration notes
+
+Behavior has moved from scaffold-only single start calls to a lifecycle runtime,
+with real backend execution as the default:
+
+- orchestration now supports `start/status/wait/send/cancel`
+- batched `start` supports deterministic ordering and bounded concurrency
+- primary tools and task-routed calls share one execution/runtime contract
+- policy-denied calls now fail deterministically instead of silently proceeding
+
+Existing slash commands remain unchanged:
+
+- `/ohm-subagents`
+- `/ohm-subagent <id>`
+
 ## Live TUI feedback
 
 `@pi-ohm/subagents` uses `@mariozechner/pi-tui` for task runtime visuals.
@@ -31,6 +132,12 @@ Baseline running-task display includes:
 - in-flight tool call count
 - elapsed time (`mm:ss`)
 
+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
+- headless fallback `onUpdate` text with equivalent description/tool-count/elapsed info
+
 Example running block:
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-ohm/subagents",
-  "version": "0.6.3",
+  "version": "0.6.4-dev.22132458683.1.8646f56",
   "homepage": "https://github.com/pi-ohm/pi-ohm/tree/dev/packages/subagents#readme",
   "repository": {
     "type": "git",
@@ -20,10 +20,22 @@
   },
   "dependencies": {
     "@mariozechner/pi-coding-agent": "catalog:pi",
-    "@pi-ohm/config": "^0.6.3"
+    "@pi-ohm/config": "0.6.4-dev.22132458683.1.8646f56",
+    "better-result": "catalog:",
+    "zod": "catalog:"
   },
   "peerDependencies": {
-    "@mariozechner/pi-coding-agent": "*"
+    "@mariozechner/pi-coding-agent": "*",
+    "@mariozechner/pi-tui": "*",
+    "@sinclair/typebox": "*"
+  },
+  "peerDependenciesMeta": {
+    "@mariozechner/pi-tui": {
+      "optional": true
+    },
+    "@sinclair/typebox": {
+      "optional": true
+    }
   },
   "pi": {
     "extensions": [

package/src/catalog.test.ts

@@ -0,0 +1,71 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { getSubagentById, OHM_SUBAGENT_CATALOG } from "./catalog";
+
+function defineTest(name: string, run: () => void | Promise<void>): void {
+  void test(name, run);
+}
+
+defineTest("catalog ids are unique", () => {
+  const ids = OHM_SUBAGENT_CATALOG.map((agent) => agent.id);
+  const uniqueIds = new Set(ids);
+
+  assert.equal(uniqueIds.size, ids.length);
+});
+
+defineTest("catalog includes expected default subagents", () => {
+  const ids = OHM_SUBAGENT_CATALOG.map((agent) => agent.id);
+  assert.deepEqual(ids, ["librarian", "oracle", "finder"]);
+});
+
+defineTest("librarian is primary by default", () => {
+  const librarian = getSubagentById("librarian");
+  assert.notEqual(librarian, undefined);
+  if (!librarian) {
+    assert.fail("Expected librarian profile in catalog");
+  }
+
+  assert.equal(librarian.primary, true);
+});
+
+defineTest("finder and oracle are task-routed by default", () => {
+  const finder = getSubagentById("finder");
+  const oracle = getSubagentById("oracle");
+
+  assert.notEqual(finder, undefined);
+  assert.notEqual(oracle, undefined);
+
+  if (!finder || !oracle) {
+    assert.fail("Expected finder and oracle profiles in catalog");
+  }
+
+  assert.equal(finder.primary, undefined);
+  assert.equal(oracle.primary, undefined);
+});
+
+defineTest("getSubagentById is case-insensitive and trims input", () => {
+  const match = getSubagentById("  LiBrArIaN ");
+  assert.notEqual(match, undefined);
+  if (!match) {
+    assert.fail("Expected to find librarian profile");
+  }
+
+  assert.equal(match.id, "librarian");
+});
+
+defineTest("getSubagentById returns undefined for unknown ids", () => {
+  const match = getSubagentById("does-not-exist");
+  assert.equal(match, undefined);
+});
+
+defineTest("catalog entries contain required non-empty scaffold fields", () => {
+  for (const agent of OHM_SUBAGENT_CATALOG) {
+    assert.ok(agent.name.trim().length > 0);
+    assert.ok(agent.summary.trim().length > 0);
+    assert.ok(agent.scaffoldPrompt.trim().length > 0);
+    assert.ok(agent.whenToUse.length > 0);
+    for (const condition of agent.whenToUse) {
+      assert.ok(condition.trim().length > 0);
+    }
+  }
+});

package/src/catalog.ts

@@ -9,6 +9,11 @@ export interface OhmSubagentDefinition {
    * instead of requiring delegated Task-style invocation.
    */
   primary?: boolean;
+  /**
+   * Internal profiles are hidden from model-facing task roster exposure unless
+   * policy explicitly allows internal routing.
+   */
+  internal?: boolean;
   whenToUse: string[];
   scaffoldPrompt: string;
   requiresPackage?: string;

package/src/errors.test.ts

@@ -0,0 +1,72 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+  SubagentPersistenceError,
+  SubagentPolicyError,
+  SubagentRuntimeError,
+  SubagentValidationError,
+  isSubagentError,
+} from "./errors";
+
+function defineTest(name: string, run: () => void | Promise<void>): void {
+  void test(name, run);
+}
+
+defineTest("SubagentValidationError derives message from cause when omitted", () => {
+  const error = new SubagentValidationError({
+    code: "invalid_payload",
+    cause: new Error("bad shape"),
+  });
+
+  assert.equal(error._tag, "SubagentValidationError");
+  assert.equal(error.code, "invalid_payload");
+  assert.match(error.message, /Validation failed/);
+  assert.match(error.message, /bad shape/);
+});
+
+defineTest("SubagentPolicyError keeps explicit message", () => {
+  const error = new SubagentPolicyError({
+    code: "policy_denied",
+    action: "start",
+    message: "Policy blocked task start",
+  });
+
+  assert.equal(error._tag, "SubagentPolicyError");
+  assert.equal(error.action, "start");
+  assert.equal(error.message, "Policy blocked task start");
+});
+
+defineTest("SubagentRuntimeError and SubagentPersistenceError expose typed tags", () => {
+  const runtimeError = new SubagentRuntimeError({
+    code: "runtime_unavailable",
+    stage: "execute",
+  });
+
+  const persistenceError = new SubagentPersistenceError({
+    code: "state_write_failed",
+    resource: "task-registry",
+  });
+
+  assert.equal(runtimeError._tag, "SubagentRuntimeError");
+  assert.equal(runtimeError.stage, "execute");
+  assert.equal(persistenceError._tag, "SubagentPersistenceError");
+  assert.equal(persistenceError.resource, "task-registry");
+});
+
+defineTest("isSubagentError narrows tagged errors", () => {
+  const validationError = new SubagentValidationError({
+    code: "invalid_id",
+    message: "id required",
+  });
+
+  const runtimeError = new SubagentRuntimeError({
+    code: "runtime_failure",
+    message: "executor unavailable",
+  });
+
+  const notError = { ok: true };
+
+  assert.equal(isSubagentError(validationError), true);
+  assert.equal(isSubagentError(runtimeError), true);
+  assert.equal(isSubagentError(notError), false);
+});

package/src/errors.ts

@@ -0,0 +1,146 @@
+import { TaggedError, type Result } from "better-result";
+
+export type SubagentErrorMeta = Record<string, unknown>;
+
+function messageFromCause(cause: unknown): string {
+  if (cause instanceof Error && cause.message.trim().length > 0) return cause.message;
+  if (typeof cause === "string" && cause.trim().length > 0) return cause;
+  return String(cause);
+}
+
+export class SubagentValidationError extends TaggedError("SubagentValidationError")<{
+  code: string;
+  message: string;
+  path?: string;
+  cause?: unknown;
+  meta?: SubagentErrorMeta;
+}>() {
+  constructor(args: {
+    code: string;
+    path?: string;
+    message?: string;
+    cause?: unknown;
+    meta?: SubagentErrorMeta;
+  }) {
+    const derivedMessage =
+      args.message ??
+      (args.cause
+        ? `Validation failed (${args.code}): ${messageFromCause(args.cause)}`
+        : `Validation failed (${args.code})`);
+
+    super({
+      code: args.code,
+      path: args.path,
+      cause: args.cause,
+      meta: args.meta,
+      message: derivedMessage,
+    });
+  }
+}
+
+export class SubagentPolicyError extends TaggedError("SubagentPolicyError")<{
+  code: string;
+  message: string;
+  action?: string;
+  cause?: unknown;
+  meta?: SubagentErrorMeta;
+}>() {
+  constructor(args: {
+    code: string;
+    action?: string;
+    message?: string;
+    cause?: unknown;
+    meta?: SubagentErrorMeta;
+  }) {
+    const derivedMessage =
+      args.message ??
+      (args.cause
+        ? `Policy denied (${args.code}): ${messageFromCause(args.cause)}`
+        : `Policy denied (${args.code})`);
+
+    super({
+      code: args.code,
+      action: args.action,
+      cause: args.cause,
+      meta: args.meta,
+      message: derivedMessage,
+    });
+  }
+}
+
+export class SubagentRuntimeError extends TaggedError("SubagentRuntimeError")<{
+  code: string;
+  message: string;
+  stage?: string;
+  cause?: unknown;
+  meta?: SubagentErrorMeta;
+}>() {
+  constructor(args: {
+    code: string;
+    stage?: string;
+    message?: string;
+    cause?: unknown;
+    meta?: SubagentErrorMeta;
+  }) {
+    const derivedMessage =
+      args.message ??
+      (args.cause
+        ? `Runtime failure (${args.code}): ${messageFromCause(args.cause)}`
+        : `Runtime failure (${args.code})`);
+
+    super({
+      code: args.code,
+      stage: args.stage,
+      cause: args.cause,
+      meta: args.meta,
+      message: derivedMessage,
+    });
+  }
+}
+
+export class SubagentPersistenceError extends TaggedError("SubagentPersistenceError")<{
+  code: string;
+  message: string;
+  resource?: string;
+  cause?: unknown;
+  meta?: SubagentErrorMeta;
+}>() {
+  constructor(args: {
+    code: string;
+    resource?: string;
+    message?: string;
+    cause?: unknown;
+    meta?: SubagentErrorMeta;
+  }) {
+    const derivedMessage =
+      args.message ??
+      (args.cause
+        ? `Persistence failure (${args.code}): ${messageFromCause(args.cause)}`
+        : `Persistence failure (${args.code})`);
+
+    super({
+      code: args.code,
+      resource: args.resource,
+      cause: args.cause,
+      meta: args.meta,
+      message: derivedMessage,
+    });
+  }
+}
+
+export type SubagentError =
+  | SubagentValidationError
+  | SubagentPolicyError
+  | SubagentRuntimeError
+  | SubagentPersistenceError;
+
+export type SubagentResult<T, E extends SubagentError = SubagentError> = Result<T, E>;
+
+export function isSubagentError(value: unknown): value is SubagentError {
+  return (
+    SubagentValidationError.is(value) ||
+    SubagentPolicyError.is(value) ||
+    SubagentRuntimeError.is(value) ||
+    SubagentPersistenceError.is(value)
+  );
+}

package/src/extension.test.ts

@@ -0,0 +1,137 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import type { OhmRuntimeConfig } from "@pi-ohm/config";
+import { getSubagentById } from "./catalog";
+import {
+  buildSubagentDetailText,
+  buildSubagentsOverviewText,
+  getSubagentInvocationMode,
+  normalizeCommandArgs,
+  registerSubagentTools,
+} from "./extension";
+
+function defineTest(name: string, run: () => void | Promise<void>): void {
+  void test(name, run);
+}
+
+const configFixture: OhmRuntimeConfig = {
+  defaultMode: "smart",
+  subagentBackend: "none",
+  features: {
+    handoff: true,
+    subagents: true,
+    sessionThreadSearch: true,
+    handoffVisualizer: true,
+    painterImagegen: false,
+  },
+  painter: {
+    googleNanoBanana: {
+      enabled: false,
+      model: "",
+    },
+    openai: {
+      enabled: false,
+      model: "",
+    },
+    azureOpenai: {
+      enabled: false,
+      deployment: "",
+      endpoint: "",
+      apiVersion: "",
+    },
+  },
+  subagents: {
+    taskMaxConcurrency: 2,
+    taskRetentionMs: 1000,
+    permissions: {
+      default: "allow",
+      subagents: {},
+      allowInternalRouting: false,
+    },
+  },
+};
+
+defineTest("normalizeCommandArgs supports array input", () => {
+  const parsed = normalizeCommandArgs(["finder", 42, "oracle", null]);
+  assert.deepEqual(parsed, ["finder", "oracle"]);
+});
+
+defineTest("normalizeCommandArgs splits raw string input", () => {
+  const parsed = normalizeCommandArgs(" finder   oracle   librarian ");
+  assert.deepEqual(parsed, ["finder", "oracle", "librarian"]);
+});
+
+defineTest("normalizeCommandArgs supports envelope args array", () => {
+  const parsed = normalizeCommandArgs({
+    args: ["finder", 1, "oracle"],
+  });
+
+  assert.deepEqual(parsed, ["finder", "oracle"]);
+});
+
+defineTest("normalizeCommandArgs supports envelope raw string", () => {
+  const parsed = normalizeCommandArgs({
+    raw: "finder   oracle",
+  });
+
+  assert.deepEqual(parsed, ["finder", "oracle"]);
+});
+
+defineTest("normalizeCommandArgs returns empty list for unsupported payloads", () => {
+  assert.deepEqual(normalizeCommandArgs(undefined), []);
+  assert.deepEqual(normalizeCommandArgs(123), []);
+  assert.deepEqual(normalizeCommandArgs({}), []);
+});
+
+defineTest("getSubagentInvocationMode returns primary-tool for primary profiles", () => {
+  assert.equal(getSubagentInvocationMode(true), "primary-tool");
+});
+
+defineTest("getSubagentInvocationMode returns task-routed for non-primary profiles", () => {
+  assert.equal(getSubagentInvocationMode(false), "task-routed");
+  assert.equal(getSubagentInvocationMode(undefined), "task-routed");
+});
+
+defineTest("registerSubagentTools registers task tool + primary tools", () => {
+  const registeredTools: string[] = [];
+
+  registerSubagentTools({
+    registerTool(definition) {
+      registeredTools.push(definition.name);
+    },
+  });
+
+  assert.equal(registeredTools.includes("task"), true);
+  assert.equal(registeredTools.includes("librarian"), true);
+  assert.equal(registeredTools.includes("finder"), false);
+  assert.equal(registeredTools.includes("oracle"), false);
+});
+
+defineTest("buildSubagentsOverviewText preserves command compatibility output", () => {
+  const text = buildSubagentsOverviewText({
+    config: configFixture,
+    loadedFrom: ["/tmp/global/ohm.json"],
+  });
+
+  assert.match(text, /Pi OHM: subagents/);
+  assert.match(text, /Scaffolded subagents:/);
+  assert.match(text, /Use \/ohm-subagent <id> to inspect one profile\./);
+  assert.match(text, /loadedFrom: \/tmp\/global\/ohm.json/);
+});
+
+defineTest("buildSubagentDetailText preserves detailed subagent view", () => {
+  const librarian = getSubagentById("librarian");
+  assert.notEqual(librarian, undefined);
+  if (!librarian) {
+    assert.fail("Expected librarian profile");
+  }
+
+  const text = buildSubagentDetailText({
+    config: configFixture,
+    subagent: librarian,
+  });
+
+  assert.match(text, /Subagent: Librarian/);
+  assert.match(text, /When to use:/);
+  assert.match(text, /Scaffold prompt:/);
+});