@pi-ohm/subagents 0.6.4-dev.22211394450.1.e53c4ee → 0.6.4-dev.22232376962.1.01704bd

package/package.json

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

package/src/runtime/backend/factory.test.ts

@@ -0,0 +1,12 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createDefaultTaskExecutionBackend } from "./index";
+
+function defineTest(name: string, run: () => void | Promise<void>): void {
+  void test(name, run);
+}
+
+defineTest("backend factory defaults to interactive-sdk route", () => {
+  const backend = createDefaultTaskExecutionBackend();
+  assert.equal(backend.id, "interactive-sdk");
+});

package/src/runtime/backend/index.ts

@@ -0,0 +1,43 @@
+import { PiCliTaskExecutionBackend } from "./pi-cli-backend";
+import type { TaskExecutionBackend } from "./types";
+
+export type {
+  ParseSubagentModelSelectionResult,
+  ParsedSubagentModelSelection,
+  PiCliRunner,
+  PiCliRunnerInput,
+  PiCliRunnerResult,
+  PiSdkRunner,
+  PiSdkRunnerInput,
+  PiSdkRunnerResult,
+  TaskBackendSendInput,
+  TaskBackendSendOutput,
+  TaskBackendStartInput,
+  TaskBackendStartOutput,
+  TaskExecutionBackend,
+} from "./types";
+
+export { parseSubagentModelSelection } from "./model-selection";
+export {
+  applyPiSdkSessionEvent,
+  createPiSdkStreamCaptureState,
+  finalizePiSdkStreamCapture,
+} from "./sdk-stream-capture";
+export { buildSendPrompt, buildStartPrompt, truncate } from "./prompts";
+export {
+  CLI_BACKEND_ROUTE,
+  PI_CLI_TOOLS,
+  SDK_BACKEND_ROUTE,
+  SDK_BACKEND_RUNTIME,
+  normalizeOutput,
+  runPiCliPrompt,
+  runPiSdkPrompt,
+  sanitizeNestedOutput,
+} from "./runners";
+export { ScaffoldTaskExecutionBackend } from "./scaffold-backend";
+export { PiCliTaskExecutionBackend, resolveBackendTimeoutMs } from "./pi-cli-backend";
+export { PiSdkTaskExecutionBackend } from "./pi-sdk-backend";
+
+export function createDefaultTaskExecutionBackend(): TaskExecutionBackend {
+  return new PiCliTaskExecutionBackend();
+}

package/src/runtime/backend/model-selection.test.ts

@@ -0,0 +1,23 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { parseSubagentModelSelection } from "./model-selection";
+
+function defineTest(name: string, run: () => void | Promise<void>): void {
+  void test(name, run);
+}
+
+defineTest("model-selection parses provider/model with thinking suffix", () => {
+  const parsed = parseSubagentModelSelection({
+    modelPattern: "openai-codex/gpt-5.3-codex:medium",
+    hasModel: (provider, modelId) => provider === "openai-codex" && modelId === "gpt-5.3-codex",
+  });
+
+  assert.equal(parsed.ok, true);
+  if (!parsed.ok) {
+    assert.fail("Expected model parse success");
+  }
+
+  assert.equal(parsed.value.provider, "openai-codex");
+  assert.equal(parsed.value.modelId, "gpt-5.3-codex");
+  assert.equal(parsed.value.thinkingLevel, "medium");
+});

package/src/runtime/backend/model-selection.ts

@@ -0,0 +1,117 @@
+import type { ThinkingLevel } from "@mariozechner/pi-agent-core";
+
+export interface ParsedSubagentModelSelection {
+  readonly provider: string;
+  readonly modelId: string;
+  readonly thinkingLevel?: ThinkingLevel;
+}
+
+export type ParseSubagentModelSelectionResult =
+  | {
+      readonly ok: true;
+      readonly value: ParsedSubagentModelSelection;
+    }
+  | {
+      readonly ok: false;
+      readonly reason: "invalid_format" | "invalid_thinking_level" | "model_not_found";
+      readonly message: string;
+    };
+
+function parseProviderModelPattern(
+  modelPattern: string,
+): { readonly provider: string; readonly modelId: string } | undefined {
+  const trimmed = modelPattern.trim();
+  if (trimmed.length === 0) return undefined;
+
+  const slashIndex = trimmed.indexOf("/");
+  if (slashIndex <= 0 || slashIndex >= trimmed.length - 1) return undefined;
+
+  const provider = trimmed.slice(0, slashIndex).trim().toLowerCase();
+  const modelId = trimmed.slice(slashIndex + 1).trim();
+  if (provider.length === 0 || modelId.length === 0) return undefined;
+
+  return { provider, modelId };
+}
+
+function isThinkingLevel(value: string): value is ThinkingLevel {
+  return (
+    value === "off" ||
+    value === "minimal" ||
+    value === "low" ||
+    value === "medium" ||
+    value === "high" ||
+    value === "xhigh"
+  );
+}
+
+export function parseSubagentModelSelection(input: {
+  readonly modelPattern: string;
+  readonly hasModel: (provider: string, modelId: string) => boolean;
+}): ParseSubagentModelSelectionResult {
+  const parsedBase = parseProviderModelPattern(input.modelPattern);
+  if (!parsedBase) {
+    return {
+      ok: false,
+      reason: "invalid_format",
+      message: `Invalid subagent model '${input.modelPattern}'. Expected '<provider>/<model>' or '<provider>/<model>:<thinking>'.`,
+    };
+  }
+
+  const fullModelId = parsedBase.modelId;
+  if (input.hasModel(parsedBase.provider, fullModelId)) {
+    return {
+      ok: true,
+      value: {
+        provider: parsedBase.provider,
+        modelId: fullModelId,
+      },
+    };
+  }
+
+  const colonIndex = fullModelId.lastIndexOf(":");
+  if (colonIndex <= 0 || colonIndex >= fullModelId.length - 1) {
+    return {
+      ok: false,
+      reason: "model_not_found",
+      message: `Configured subagent model '${input.modelPattern}' was not found.`,
+    };
+  }
+
+  const thinkingRaw = fullModelId
+    .slice(colonIndex + 1)
+    .trim()
+    .toLowerCase();
+  if (!isThinkingLevel(thinkingRaw)) {
+    return {
+      ok: false,
+      reason: "invalid_thinking_level",
+      message: `Invalid subagent thinking level '${thinkingRaw}' in '${input.modelPattern}'.`,
+    };
+  }
+
+  const modelId = fullModelId.slice(0, colonIndex).trim();
+  if (modelId.length === 0) {
+    return {
+      ok: false,
+      reason: "invalid_format",
+      message: `Invalid subagent model '${input.modelPattern}'. Expected '<provider>/<model>' or '<provider>/<model>:<thinking>'.`,
+    };
+  }
+
+  if (!input.hasModel(parsedBase.provider, modelId)) {
+    return {
+      ok: false,
+      reason: "model_not_found",
+      message: `Configured subagent model '${input.modelPattern}' was not found.`,
+    };
+  }
+
+  return {
+    ok: true,
+    value: {
+      provider: parsedBase.provider,
+      modelId,
+      thinkingLevel: thinkingRaw,
+    },
+  };
+}

package/src/runtime/{backend.test.ts → backend/pi-cli-backend.test.ts}

@@ -2,8 +2,8 @@ import assert from "node:assert/strict";
 import test from "node:test";
 import type { OhmRuntimeConfig, OhmSubagentBackend } from "@pi-ohm/config";
 import { Result } from "better-result";
-import type { OhmSubagentDefinition } from "../catalog";
-import { SubagentRuntimeError } from "../errors";
+import type { OhmSubagentDefinition } from "../../catalog";
+import { SubagentRuntimeError } from "../../errors";
 import {
   applyPiSdkSessionEvent,
   createDefaultTaskExecutionBackend,
@@ -16,7 +16,7 @@ import {
   type PiCliRunner,
   type PiSdkRunner,
   type TaskExecutionBackend,
-} from "./backend";
+} from "./index";
 
 function defineTest(name: string, run: () => void | Promise<void>): void {
   void test(name, run);

package/src/runtime/backend/pi-cli-backend.ts

@@ -0,0 +1,359 @@
+import { Result } from "better-result";
+import { getSubagentConfiguredModel, type OhmRuntimeConfig } from "@pi-ohm/config";
+import type { OhmSubagentDefinition } from "../../catalog";
+import { SubagentRuntimeError, type SubagentResult } from "../../errors";
+import { buildSendPrompt, buildStartPrompt, truncate } from "./prompts";
+import {
+  CLI_BACKEND_ROUTE,
+  normalizeOutput,
+  runPiCliPrompt,
+  sanitizeNestedOutput,
+  SDK_BACKEND_ROUTE,
+} from "./runners";
+import { PiSdkTaskExecutionBackend } from "./pi-sdk-backend";
+import { ScaffoldTaskExecutionBackend } from "./scaffold-backend";
+import type {
+  PiCliRunner,
+  TaskBackendSendInput,
+  TaskBackendSendOutput,
+  TaskBackendStartInput,
+  TaskBackendStartOutput,
+  TaskExecutionBackend,
+} from "./types";
+
+const DEFAULT_BACKEND_TIMEOUT_MS = 180_000;
+const DEFAULT_LIBRARIAN_TIMEOUT_MS = 300_000;
+const DEFAULT_ORACLE_TIMEOUT_MS = 3_600_000;
+
+function parsePositiveInteger(raw: string | undefined): number | undefined {
+  if (!raw) return undefined;
+  const parsed = Number.parseInt(raw, 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) return undefined;
+  return parsed;
+}
+
+function getTimeoutMsFromEnv(): number {
+  return (
+    parsePositiveInteger(process.env.OHM_SUBAGENTS_BACKEND_TIMEOUT_MS) ?? DEFAULT_BACKEND_TIMEOUT_MS
+  );
+}
+
+function getSubagentTimeoutMsFromEnv(subagentId: string): number | undefined {
+  const key = `OHM_SUBAGENTS_BACKEND_TIMEOUT_MS_${subagentId.trim().toUpperCase()}`;
+  return parsePositiveInteger(process.env[key]);
+}
+
+export function resolveBackendTimeoutMs(input: {
+  readonly fallbackTimeoutMs: number;
+  readonly subagent: OhmSubagentDefinition;
+}): number {
+  const fromSubagentEnv = getSubagentTimeoutMsFromEnv(input.subagent.id);
+  if (fromSubagentEnv !== undefined) return fromSubagentEnv;
+
+  const fromGlobalEnv = getTimeoutMsFromEnv();
+  const base = fromGlobalEnv > 0 ? fromGlobalEnv : input.fallbackTimeoutMs;
+
+  if (input.subagent.id === "librarian") {
+    return Math.max(base, DEFAULT_LIBRARIAN_TIMEOUT_MS);
+  }
+
+  if (input.subagent.id === "oracle") {
+    return Math.max(base, DEFAULT_ORACLE_TIMEOUT_MS);
+  }
+
+  return base;
+}
+
+function isSdkFallbackToCliEnabled(): boolean {
+  const raw = process.env.OHM_SUBAGENTS_SDK_FALLBACK_TO_CLI;
+  if (!raw) return false;
+
+  const normalized = raw.trim().toLowerCase();
+  return normalized === "1" || normalized === "true" || normalized === "yes" || normalized === "on";
+}
+
+function toAbortedError(
+  taskId: string,
+  stage: "execute_start" | "execute_send",
+): SubagentRuntimeError {
+  return new SubagentRuntimeError({
+    code: "task_aborted",
+    stage,
+    message: `Task ${taskId} was aborted before execution`,
+    meta: { taskId },
+  });
+}
+
+function toUnsupportedBackendError(
+  taskId: string,
+  stage: "execute_start" | "execute_send",
+): SubagentRuntimeError {
+  return new SubagentRuntimeError({
+    code: "unsupported_subagent_backend",
+    stage,
+    message: "Configured subagent backend is not implemented in @pi-ohm/subagents",
+    meta: { taskId, backend: "custom-plugin" },
+  });
+}
+
+function toBackendTimeoutError(input: {
+  readonly taskId: string;
+  readonly stage: "execute_start" | "execute_send";
+  readonly timeoutMs: number;
+  readonly subagentId: string;
+  readonly modelPattern: string | undefined;
+}): SubagentRuntimeError {
+  const timeoutSeconds = Math.max(1, Math.round(input.timeoutMs / 1000));
+  const modelHint = input.modelPattern ? ` (model: ${input.modelPattern})` : "";
+  const guidance =
+    input.subagentId === "oracle"
+      ? "Narrow oracle task scope/context/files or raise OHM_SUBAGENTS_BACKEND_TIMEOUT_MS_ORACLE."
+      : `Narrow task scope or raise OHM_SUBAGENTS_BACKEND_TIMEOUT_MS_${input.subagentId.toUpperCase()} (or OHM_SUBAGENTS_BACKEND_TIMEOUT_MS).`;
+
+  return new SubagentRuntimeError({
+    code: "task_backend_timeout",
+    stage: input.stage,
+    message: `Task ${input.taskId} timed out after ${timeoutSeconds}s while waiting for '${input.subagentId}' backend response${modelHint}. ${guidance}`,
+    meta: {
+      taskId: input.taskId,
+      timeoutMs: input.timeoutMs,
+      timeoutSeconds,
+      subagentId: input.subagentId,
+      modelPattern: input.modelPattern,
+    },
+  });
+}
+
+function toBackendExecutionError(input: {
+  readonly taskId: string;
+  readonly stage: "execute_start" | "execute_send";
+  readonly exitCode: number;
+  readonly stderr: string;
+}): SubagentRuntimeError {
+  const errorText = input.stderr.trim();
+  const summary =
+    errorText.length > 0 ? truncate(errorText, 260) : "subagent backend exited non-zero";
+
+  return new SubagentRuntimeError({
+    code: "task_backend_execution_failed",
+    stage: input.stage,
+    message: `Task ${input.taskId} backend failed: ${summary}`,
+    meta: {
+      taskId: input.taskId,
+      exitCode: input.exitCode,
+      stderr: errorText,
+    },
+  });
+}
+
+function resolveSubagentModelPattern(input: {
+  readonly config: OhmRuntimeConfig;
+  readonly subagent: OhmSubagentDefinition;
+}): string | undefined {
+  return getSubagentConfiguredModel(input.config, input.subagent.id);
+}
+
+export class PiCliTaskExecutionBackend implements TaskExecutionBackend {
+  readonly id = SDK_BACKEND_ROUTE;
+  private readonly scaffoldBackend = new ScaffoldTaskExecutionBackend();
+
+  constructor(
+    private readonly runner: PiCliRunner = runPiCliPrompt,
+    private readonly timeoutMs: number = getTimeoutMsFromEnv(),
+    private readonly sdkBackend: TaskExecutionBackend = new PiSdkTaskExecutionBackend(),
+  ) {}
+
+  resolveBackendId(config: OhmRuntimeConfig): string {
+    if (config.subagentBackend === "none") return this.scaffoldBackend.id;
+    if (config.subagentBackend === "interactive-shell") return CLI_BACKEND_ROUTE;
+    if (config.subagentBackend === "interactive-sdk") return SDK_BACKEND_ROUTE;
+    if (config.subagentBackend === "custom-plugin") return "custom-plugin";
+    return this.id;
+  }
+
+  private shouldFallbackToCli(error: SubagentRuntimeError): boolean {
+    if (!isSdkFallbackToCliEnabled()) return false;
+    if (error.code !== "task_backend_execution_failed") return false;
+    return true;
+  }
+
+  private async executeCliStart(
+    input: TaskBackendStartInput,
+  ): Promise<SubagentResult<TaskBackendStartOutput, SubagentRuntimeError>> {
+    const modelPattern = resolveSubagentModelPattern({
+      config: input.config,
+      subagent: input.subagent,
+    });
+    const timeoutMs = resolveBackendTimeoutMs({
+      fallbackTimeoutMs: this.timeoutMs,
+      subagent: input.subagent,
+    });
+    const run = await this.runner({
+      cwd: input.cwd,
+      prompt: buildStartPrompt(input),
+      modelPattern,
+      signal: input.signal,
+      timeoutMs,
+    });
+
+    if (run.aborted || input.signal?.aborted) {
+      return Result.err(toAbortedError(input.taskId, "execute_start"));
+    }
+
+    if (run.timedOut) {
+      return Result.err(
+        toBackendTimeoutError({
+          taskId: input.taskId,
+          stage: "execute_start",
+          timeoutMs,
+          subagentId: input.subagent.id,
+          modelPattern,
+        }),
+      );
+    }
+
+    if (run.exitCode !== 0) {
+      return Result.err(
+        toBackendExecutionError({
+          taskId: input.taskId,
+          stage: "execute_start",
+          exitCode: run.exitCode,
+          stderr: run.stderr,
+        }),
+      );
+    }
+
+    const normalized = sanitizeNestedOutput(normalizeOutput(run.stdout, run.stderr));
+    const summary = `${input.subagent.name}: ${truncate(input.description, 72)}`;
+    return Result.ok({
+      summary,
+      output: normalized.output,
+      provider: normalized.provider,
+      model: normalized.model,
+      runtime: normalized.runtime,
+      route: CLI_BACKEND_ROUTE,
+    });
+  }
+
+  private async executeCliSend(
+    input: TaskBackendSendInput,
+  ): Promise<SubagentResult<TaskBackendSendOutput, SubagentRuntimeError>> {
+    const modelPattern = resolveSubagentModelPattern({
+      config: input.config,
+      subagent: input.subagent,
+    });
+    const timeoutMs = resolveBackendTimeoutMs({
+      fallbackTimeoutMs: this.timeoutMs,
+      subagent: input.subagent,
+    });
+    const run = await this.runner({
+      cwd: input.cwd,
+      prompt: buildSendPrompt(input),
+      modelPattern,
+      signal: input.signal,
+      timeoutMs,
+    });
+
+    if (run.aborted || input.signal?.aborted) {
+      return Result.err(toAbortedError(input.taskId, "execute_send"));
+    }
+
+    if (run.timedOut) {
+      return Result.err(
+        toBackendTimeoutError({
+          taskId: input.taskId,
+          stage: "execute_send",
+          timeoutMs,
+          subagentId: input.subagent.id,
+          modelPattern,
+        }),
+      );
+    }
+
+    if (run.exitCode !== 0) {
+      return Result.err(
+        toBackendExecutionError({
+          taskId: input.taskId,
+          stage: "execute_send",
+          exitCode: run.exitCode,
+          stderr: run.stderr,
+        }),
+      );
+    }
+
+    const normalized = sanitizeNestedOutput(normalizeOutput(run.stdout, run.stderr));
+    const summary = `${input.subagent.name} follow-up: ${truncate(input.prompt, 72)}`;
+    return Result.ok({
+      summary,
+      output: normalized.output,
+      provider: normalized.provider,
+      model: normalized.model,
+      runtime: normalized.runtime,
+      route: CLI_BACKEND_ROUTE,
+    });
+  }
+
+  async executeStart(
+    input: TaskBackendStartInput,
+  ): Promise<SubagentResult<TaskBackendStartOutput, SubagentRuntimeError>> {
+    if (input.signal?.aborted) {
+      return Result.err(toAbortedError(input.taskId, "execute_start"));
+    }
+
+    if (input.config.subagentBackend === "none") {
+      return this.scaffoldBackend.executeStart(input);
+    }
+
+    if (input.config.subagentBackend === "custom-plugin") {
+      return Result.err(toUnsupportedBackendError(input.taskId, "execute_start"));
+    }
+
+    if (input.config.subagentBackend === "interactive-shell") {
+      return this.executeCliStart(input);
+    }
+
+    if (input.config.subagentBackend === "interactive-sdk") {
+      const sdkResult = await this.sdkBackend.executeStart(input);
+      if (Result.isOk(sdkResult)) return sdkResult;
+      if (!this.shouldFallbackToCli(sdkResult.error)) return sdkResult;
+      return this.executeCliStart(input);
+    }
+
+    const sdkResult = await this.sdkBackend.executeStart(input);
+    if (Result.isOk(sdkResult)) return sdkResult;
+    if (!this.shouldFallbackToCli(sdkResult.error)) return sdkResult;
+    return this.executeCliStart(input);
+  }
+
+  async executeSend(
+    input: TaskBackendSendInput,
+  ): Promise<SubagentResult<TaskBackendSendOutput, SubagentRuntimeError>> {
+    if (input.signal?.aborted) {
+      return Result.err(toAbortedError(input.taskId, "execute_send"));
+    }
+
+    if (input.config.subagentBackend === "none") {
+      return this.scaffoldBackend.executeSend(input);
+    }
+
+    if (input.config.subagentBackend === "custom-plugin") {
+      return Result.err(toUnsupportedBackendError(input.taskId, "execute_send"));
+    }
+
+    if (input.config.subagentBackend === "interactive-shell") {
+      return this.executeCliSend(input);
+    }
+
+    if (input.config.subagentBackend === "interactive-sdk") {
+      const sdkResult = await this.sdkBackend.executeSend(input);
+      if (Result.isOk(sdkResult)) return sdkResult;
+      if (!this.shouldFallbackToCli(sdkResult.error)) return sdkResult;
+      return this.executeCliSend(input);
+    }
+
+    const sdkResult = await this.sdkBackend.executeSend(input);
+    if (Result.isOk(sdkResult)) return sdkResult;
+    if (!this.shouldFallbackToCli(sdkResult.error)) return sdkResult;
+    return this.executeCliSend(input);
+  }
+}

package/src/runtime/backend/pi-sdk-backend.test.ts

@@ -0,0 +1,73 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import type { OhmRuntimeConfig } from "@pi-ohm/config";
+import { Result } from "better-result";
+import { PiSdkTaskExecutionBackend } from "./pi-sdk-backend";
+
+function defineTest(name: string, run: () => void | Promise<void>): void {
+  void test(name, run);
+}
+
+const config: OhmRuntimeConfig = {
+  defaultMode: "smart",
+  subagentBackend: "interactive-sdk",
+  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: 60_000,
+    permissions: {
+      default: "allow",
+      subagents: {},
+      allowInternalRouting: false,
+    },
+    profiles: {},
+  },
+};
+
+defineTest("pi-sdk-backend executes start with runner", async () => {
+  const backend = new PiSdkTaskExecutionBackend(async () => {
+    return {
+      output: "sdk output",
+      events: [],
+      timedOut: false,
+      aborted: false,
+      runtime: "pi-sdk",
+    };
+  });
+
+  const result = await backend.executeStart({
+    taskId: "task_sdk_1",
+    subagent: {
+      id: "finder",
+      name: "Finder",
+      summary: "Search specialist",
+      whenToUse: ["search"],
+      scaffoldPrompt: "search prompt",
+      primary: false,
+    },
+    description: "sdk smoke",
+    prompt: "find auth",
+    cwd: "/tmp/project",
+    config,
+    signal: undefined,
+  });
+
+  assert.equal(Result.isOk(result), true);
+  if (Result.isError(result)) {
+    assert.fail("Expected sdk backend success");
+  }
+
+  assert.equal(result.value.runtime, "pi-sdk");
+  assert.equal(result.value.route, "interactive-sdk");
+});