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

package/src/extension.ts

@@ -1,8 +1,20 @@
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
-import { loadOhmRuntimeConfig, registerOhmSettings } from "@pi-ohm/config";
+import { loadOhmRuntimeConfig, registerOhmSettings, type OhmRuntimeConfig } from "@pi-ohm/config";
 import { getSubagentById, OHM_SUBAGENT_CATALOG } from "./catalog";
+import { isSubagentVisibleInTaskRoster } from "./policy";
+import { registerPrimarySubagentTools } from "./tools/primary";
+import { createDefaultTaskToolDependencies, registerTaskTool } from "./tools/task";
 
-function normalizeCommandArgs(args: unknown): string[] {
+interface CommandArgsEnvelope {
+  args?: unknown;
+  raw?: unknown;
+}
+
+function isCommandArgsEnvelope(value: unknown): value is CommandArgsEnvelope {
+  return typeof value === "object" && value !== null;
+}
+
+export function normalizeCommandArgs(args: unknown): string[] {
   if (Array.isArray(args)) {
     return args.filter((value): value is string => typeof value === "string");
   }
@@ -14,15 +26,13 @@ function normalizeCommandArgs(args: unknown): string[] {
       .filter((part) => part.length > 0);
   }
 
-  if (args && typeof args === "object") {
-    const asRecord = args as { args?: unknown; raw?: unknown };
-
-    if (Array.isArray(asRecord.args)) {
-      return asRecord.args.filter((value): value is string => typeof value === "string");
+  if (isCommandArgsEnvelope(args)) {
+    if (Array.isArray(args.args)) {
+      return args.args.filter((value): value is string => typeof value === "string");
     }
 
-    if (typeof asRecord.raw === "string") {
-      return asRecord.raw
+    if (typeof args.raw === "string") {
+      return args.raw
         .split(/\s+/)
         .map((part) => part.trim())
         .filter((part) => part.length > 0);
@@ -32,42 +42,109 @@ function normalizeCommandArgs(args: unknown): string[] {
   return [];
 }
 
+export type SubagentInvocationMode = "primary-tool" | "task-routed";
+
+export function getSubagentInvocationMode(primary: boolean | undefined): SubagentInvocationMode {
+  return primary ? "primary-tool" : "task-routed";
+}
+
+function listSubagentIds(): string {
+  return OHM_SUBAGENT_CATALOG.map((agent) => agent.id).join("|");
+}
+
+function getVisibleSubagents(config: OhmRuntimeConfig) {
+  return OHM_SUBAGENT_CATALOG.filter((agent) => isSubagentVisibleInTaskRoster(agent, config));
+}
+
+export function buildSubagentsOverviewText(input: {
+  readonly config: OhmRuntimeConfig;
+  readonly loadedFrom: readonly string[];
+}): string {
+  const visibleSubagents = getVisibleSubagents(input.config);
+
+  const lines = visibleSubagents.map((agent) => {
+    const needsPainterPackage = agent.id === "painter";
+    const available = !needsPainterPackage || input.config.features.painterImagegen;
+    const availability = available ? "available" : "requires painter feature/package";
+    const invocation = getSubagentInvocationMode(agent.primary);
+    return `- ${agent.name} (${agent.id}): ${agent.summary} [${availability} · ${invocation}]`;
+  });
+
+  return [
+    "Pi OHM: subagents",
+    "",
+    `enabled: ${input.config.features.subagents ? "yes" : "no"}`,
+    `backend: ${input.config.subagentBackend}`,
+    "",
+    "Scaffolded subagents:",
+    ...lines,
+    "",
+    "Use /ohm-subagent <id> to inspect one profile.",
+    `loadedFrom: ${input.loadedFrom.length > 0 ? input.loadedFrom.join(", ") : "defaults + extension settings"}`,
+  ].join("\n");
+}
+
+export function buildSubagentDetailText(input: {
+  readonly config: OhmRuntimeConfig;
+  readonly subagent: (typeof OHM_SUBAGENT_CATALOG)[number];
+}): string {
+  const isAvailable = input.subagent.id !== "painter" || input.config.features.painterImagegen;
+
+  return [
+    `Subagent: ${input.subagent.name}`,
+    `id: ${input.subagent.id}`,
+    `available: ${isAvailable ? "yes" : "no"}`,
+    `invocation: ${getSubagentInvocationMode(input.subagent.primary)}`,
+    input.subagent.requiresPackage
+      ? `requiresPackage: ${input.subagent.requiresPackage}`
+      : "requiresPackage: none",
+    "",
+    "When to use:",
+    ...input.subagent.whenToUse.map((line) => `- ${line}`),
+    "",
+    "Scaffold prompt:",
+    input.subagent.scaffoldPrompt,
+  ].join("\n");
+}
+
+export function registerSubagentTools(pi: Pick<ExtensionAPI, "registerTool">): {
+  readonly primaryToolCount: number;
+  readonly diagnosticsCount: number;
+} {
+  const taskDeps = createDefaultTaskToolDependencies();
+  registerTaskTool(pi, taskDeps);
+  const primaryToolRegistration = registerPrimarySubagentTools(pi, {
+    taskDeps,
+  });
+
+  return {
+    primaryToolCount: primaryToolRegistration.registeredTools.length,
+    diagnosticsCount: primaryToolRegistration.diagnostics.length,
+  };
+}
+
 export default function registerSubagentsExtension(pi: ExtensionAPI): void {
   registerOhmSettings(pi);
+  const toolRegistration = registerSubagentTools(pi);
 
   pi.on("session_start", async (_event, ctx) => {
     const { config } = await loadOhmRuntimeConfig(ctx.cwd);
     if (!ctx.hasUI) return;
 
     const enabled = config.features.subagents ? "on" : "off";
-    ctx.ui.setStatus("ohm-subagents", `subagents:${enabled} · backend:${config.subagentBackend}`);
+    const primaryTools = toolRegistration.primaryToolCount;
+    const diagnostics = toolRegistration.diagnosticsCount;
+    ctx.ui.setStatus(
+      "ohm-subagents",
+      `subagents:${enabled} · backend:${config.subagentBackend} · primary:${primaryTools} · diag:${diagnostics}`,
+    );
   });
 
   pi.registerCommand("ohm-subagents", {
     description: "Show scaffolded subagents and backend status",
     handler: async (_args, ctx) => {
       const { config, loadedFrom } = await loadOhmRuntimeConfig(ctx.cwd);
-
-      const lines = OHM_SUBAGENT_CATALOG.map((agent) => {
-        const needsPainterPackage = agent.id === "painter";
-        const available = !needsPainterPackage || config.features.painterImagegen;
-        const availability = available ? "available" : "requires painter feature/package";
-        const invocation = agent.primary ? "primary-tool" : "delegated";
-        return `- ${agent.name} (${agent.id}): ${agent.summary} [${availability} · ${invocation}]`;
-      });
-
-      const text = [
-        "Pi OHM: subagents",
-        "",
-        `enabled: ${config.features.subagents ? "yes" : "no"}`,
-        `backend: ${config.subagentBackend}`,
-        "",
-        "Scaffolded subagents:",
-        ...lines,
-        "",
-        "Use /ohm-subagent <id> to inspect one profile.",
-        `loadedFrom: ${loadedFrom.length > 0 ? loadedFrom.join(", ") : "defaults + extension settings"}`,
-      ].join("\n");
+      const text = buildSubagentsOverviewText({ config, loadedFrom });
 
       if (!ctx.hasUI) {
         console.log(text);
@@ -79,18 +156,19 @@ export default function registerSubagentsExtension(pi: ExtensionAPI): void {
   });
 
   pi.registerCommand("ohm-subagent", {
-    description: "Inspect one subagent scaffold (librarian|oracle|finder|task|painter)",
+    description: `Inspect one subagent scaffold (${listSubagentIds()})`,
     handler: async (args, ctx) => {
       const { config } = await loadOhmRuntimeConfig(ctx.cwd);
       const [requested = ""] = normalizeCommandArgs(args);
       const match = getSubagentById(requested);
 
-      if (!match) {
-        const usage = [
-          "Usage: /ohm-subagent <id>",
-          "",
-          `Valid ids: ${OHM_SUBAGENT_CATALOG.map((agent) => agent.id).join(", ")}`,
-        ].join("\n");
+      const visibleSubagents = getVisibleSubagents(config);
+      const visibleIds = visibleSubagents.map((agent) => agent.id);
+
+      if (!match || !visibleIds.includes(match.id)) {
+        const usage = ["Usage: /ohm-subagent <id>", "", `Valid ids: ${visibleIds.join(", ")}`].join(
+          "\n",
+        );
 
         if (!ctx.hasUI) {
           console.log(usage);
@@ -101,23 +179,7 @@ export default function registerSubagentsExtension(pi: ExtensionAPI): void {
         return;
       }
 
-      const isAvailable = match.id !== "painter" || config.features.painterImagegen;
-
-      const text = [
-        `Subagent: ${match.name}`,
-        `id: ${match.id}`,
-        `available: ${isAvailable ? "yes" : "no"}`,
-        `invocation: ${match.primary ? "primary-tool" : "delegated"}`,
-        match.requiresPackage
-          ? `requiresPackage: ${match.requiresPackage}`
-          : "requiresPackage: none",
-        "",
-        "When to use:",
-        ...match.whenToUse.map((line) => `- ${line}`),
-        "",
-        "Scaffold prompt:",
-        match.scaffoldPrompt,
-      ].join("\n");
+      const text = buildSubagentDetailText({ config, subagent: match });
 
       if (!ctx.hasUI) {
         console.log(text);

package/src/policy.test.ts

@@ -0,0 +1,173 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import type { OhmRuntimeConfig } from "@pi-ohm/config";
+import { Result } from "better-result";
+import type { OhmSubagentDefinition } from "./catalog";
+import {
+  evaluateTaskPermission,
+  getTaskPermissionDecision,
+  getTaskPermissionPolicy,
+  isSubagentVisibleInTaskRoster,
+} from "./policy";
+
+function defineTest(name: string, run: () => void | Promise<void>): void {
+  void test(name, run);
+}
+
+const baseSubagentRuntimeConfig = {
+  taskMaxConcurrency: 3,
+  taskRetentionMs: 1000 * 60,
+  permissions: {
+    default: "allow",
+    subagents: {},
+    allowInternalRouting: false,
+  },
+} as const;
+
+const baseConfig: OhmRuntimeConfig = {
+  defaultMode: "smart",
+  subagentBackend: "none",
+  features: {
+    handoff: true,
+    subagents: true,
+    sessionThreadSearch: true,
+    handoffVisualizer: true,
+    painterImagegen: true,
+  },
+  painter: {
+    googleNanoBanana: {
+      enabled: false,
+      model: "",
+    },
+    openai: {
+      enabled: false,
+      model: "",
+    },
+    azureOpenai: {
+      enabled: false,
+      deployment: "",
+      endpoint: "",
+      apiVersion: "",
+    },
+  },
+  subagents: baseSubagentRuntimeConfig,
+};
+
+const finder: OhmSubagentDefinition = {
+  id: "finder",
+  name: "Finder",
+  summary: "Search specialist",
+  whenToUse: ["Search behavior paths"],
+  scaffoldPrompt: "Search code",
+};
+
+const internalFinder: OhmSubagentDefinition = {
+  ...finder,
+  internal: true,
+};
+
+defineTest("getTaskPermissionPolicy normalizes defaults", () => {
+  const normalized = getTaskPermissionPolicy(baseConfig);
+  assert.equal(normalized.defaultDecision, "allow");
+  assert.equal(normalized.allowInternalRouting, false);
+  assert.deepEqual(normalized.perSubagent, {});
+});
+
+defineTest("getTaskPermissionDecision resolves explicit override first", () => {
+  const config: OhmRuntimeConfig = {
+    ...baseConfig,
+    subagents: {
+      ...baseSubagentRuntimeConfig,
+      permissions: {
+        default: "allow",
+        subagents: {
+          finder: "deny",
+        },
+        allowInternalRouting: false,
+      },
+    },
+  };
+
+  assert.equal(getTaskPermissionDecision(finder, config), "deny");
+});
+
+defineTest("evaluateTaskPermission returns deny policy errors", () => {
+  const denyConfig: OhmRuntimeConfig = {
+    ...baseConfig,
+    subagents: {
+      ...baseSubagentRuntimeConfig,
+      permissions: {
+        default: "deny",
+        subagents: {},
+        allowInternalRouting: true,
+      },
+    },
+  };
+
+  const denied = evaluateTaskPermission(finder, denyConfig);
+  assert.equal(Result.isError(denied), true);
+  if (Result.isOk(denied)) {
+    assert.fail("Expected denied policy error");
+  }
+  assert.equal(denied.error.code, "task_permission_denied");
+});
+
+defineTest("deprecated ask policy is treated as deny-safe behavior", () => {
+  const legacyAskConfig: OhmRuntimeConfig = {
+    ...baseConfig,
+    subagents: {
+      ...baseSubagentRuntimeConfig,
+      permissions: {
+        default: "allow",
+        subagents: {},
+        allowInternalRouting: false,
+      },
+    },
+  };
+
+  if (!legacyAskConfig.subagents) {
+    assert.fail("Expected subagent config");
+  }
+
+  void Reflect.set(legacyAskConfig.subagents.permissions, "default", "ask");
+  void Reflect.set(legacyAskConfig.subagents.permissions.subagents, "finder", "ask");
+
+  const normalized = getTaskPermissionPolicy(legacyAskConfig);
+  assert.equal(normalized.defaultDecision, "deny");
+  assert.equal(normalized.perSubagent.finder, "deny");
+});
+
+defineTest(
+  "internal subagents are hidden from roster unless policy allows internal routing",
+  () => {
+    assert.equal(isSubagentVisibleInTaskRoster(internalFinder, baseConfig), false);
+
+    const internalAllowedConfig: OhmRuntimeConfig = {
+      ...baseConfig,
+      subagents: {
+        ...baseSubagentRuntimeConfig,
+        permissions: {
+          default: "allow",
+          subagents: {},
+          allowInternalRouting: true,
+        },
+      },
+    };
+
+    assert.equal(isSubagentVisibleInTaskRoster(internalFinder, internalAllowedConfig), true);
+  },
+);
+
+defineTest(
+  "evaluateTaskPermission blocks internal subagent when policy disallows internal routing",
+  () => {
+    const blocked = evaluateTaskPermission(internalFinder, baseConfig);
+
+    assert.equal(Result.isError(blocked), true);
+    if (Result.isOk(blocked)) {
+      assert.fail("Expected internal routing policy error");
+    }
+
+    assert.equal(blocked.error.code, "task_internal_subagent_hidden");
+  },
+);

package/src/policy.ts

@@ -0,0 +1,114 @@
+import type { OhmRuntimeConfig } from "@pi-ohm/config";
+import { Result } from "better-result";
+import type { OhmSubagentDefinition } from "./catalog";
+import { SubagentPolicyError } from "./errors";
+
+export type TaskPermissionDecision = "allow" | "deny";
+
+export interface TaskPermissionPolicySnapshot {
+  readonly defaultDecision: TaskPermissionDecision;
+  readonly perSubagent: Readonly<Record<string, TaskPermissionDecision>>;
+  readonly allowInternalRouting: boolean;
+}
+
+function normalizeDecision(value: unknown): TaskPermissionDecision | undefined {
+  if (value === "allow" || value === "deny") return value;
+
+  // Legacy compatibility: treat deprecated "ask" policy as deny-safe behavior.
+  if (value === "ask") return "deny";
+
+  return undefined;
+}
+
+function normalizePermissionMap(value: unknown): Readonly<Record<string, TaskPermissionDecision>> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return {};
+  }
+
+  const entries: Array<readonly [string, TaskPermissionDecision]> = [];
+
+  for (const [key, rawDecision] of Object.entries(value)) {
+    const normalizedKey = key.trim().toLowerCase();
+    if (normalizedKey.length === 0) continue;
+
+    const normalizedDecision = normalizeDecision(rawDecision);
+    if (!normalizedDecision) continue;
+
+    entries.push([normalizedKey, normalizedDecision]);
+  }
+
+  return Object.fromEntries(entries);
+}
+
+export function getTaskPermissionPolicy(config: OhmRuntimeConfig): TaskPermissionPolicySnapshot {
+  const permissions = config.subagents?.permissions;
+
+  const defaultDecision = normalizeDecision(permissions?.default) ?? "allow";
+  const perSubagent = normalizePermissionMap(permissions?.subagents);
+  const allowInternalRouting =
+    typeof permissions?.allowInternalRouting === "boolean"
+      ? permissions.allowInternalRouting
+      : false;
+
+  return {
+    defaultDecision,
+    perSubagent,
+    allowInternalRouting,
+  };
+}
+
+export function getTaskPermissionDecision(
+  subagent: OhmSubagentDefinition,
+  config: OhmRuntimeConfig,
+): TaskPermissionDecision {
+  const policy = getTaskPermissionPolicy(config);
+  const explicit = policy.perSubagent[subagent.id];
+  if (explicit) return explicit;
+  return policy.defaultDecision;
+}
+
+export function isSubagentVisibleInTaskRoster(
+  subagent: OhmSubagentDefinition,
+  config: OhmRuntimeConfig,
+): boolean {
+  if (!subagent.internal) return true;
+  const policy = getTaskPermissionPolicy(config);
+  return policy.allowInternalRouting;
+}
+
+export function evaluateTaskPermission(
+  subagent: OhmSubagentDefinition,
+  config: OhmRuntimeConfig,
+): Result<true, SubagentPolicyError> {
+  const policy = getTaskPermissionPolicy(config);
+
+  if (subagent.internal && !policy.allowInternalRouting) {
+    return Result.err(
+      new SubagentPolicyError({
+        code: "task_internal_subagent_hidden",
+        action: "task.invoke",
+        message: `Subagent '${subagent.id}' is internal and unavailable by current policy`,
+        meta: {
+          subagentId: subagent.id,
+          allowInternalRouting: policy.allowInternalRouting,
+        },
+      }),
+    );
+  }
+
+  const decision = getTaskPermissionDecision(subagent, config);
+
+  if (decision === "allow") return Result.ok(true);
+
+  return Result.err(
+    new SubagentPolicyError({
+      code: "task_permission_denied",
+      action: "task.invoke",
+      message: `Subagent '${subagent.id}' is denied by task permission policy`,
+      meta: {
+        subagentId: subagent.id,
+        decision,
+      },
+    }),
+  );
+}