@pi-unipi/subagents 2.6.1 → 2.6.2

package/src/output-limits.ts

@@ -0,0 +1,142 @@
+/**
+ * @pi-unipi/subagents — Output truncation + run/tool timeout defaults
+ *
+ * truncateOutput ported verbatim from pi-subagents src/shared/types.ts.
+ * Timeout resolution follows their precedence: call param > agent frontmatter >
+ * config > default (30min foreground; 5min for known-fast tools when
+ * toolTimeoutMs is unset). Exemptions use OUR tool names.
+ */
+
+import { DEFAULT_MAX_OUTPUT, type MaxOutputConfig } from "./parity-types.js";
+import { KNOWN_FAST_TOOLS, FAST_TOOL_TIMEOUT_MS, DEFAULT_RUN_TIMEOUT_MS } from "./parity-types.js";
+import type { AgentConfig } from "./types.js";
+import type { SubagentsConfig } from "./types.js";
+
+// ============================================================================
+// Output truncation
+// ============================================================================
+
+export interface TruncationResult {
+  text: string;
+  truncated: boolean;
+  originalBytes?: number;
+  originalLines?: number;
+  artifactPath?: string;
+}
+
+function formatBytes(bytes: number): string {
+  if (bytes < 1024) return `${bytes}B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+}
+
+export function truncateOutput(
+  output: string,
+  config: Required<MaxOutputConfig>,
+  artifactPath?: string,
+): TruncationResult {
+  const lines = output.split("\n");
+  const bytes = Buffer.byteLength(output, "utf-8");
+
+  if (bytes <= config.bytes && lines.length <= config.lines) {
+    return { text: output, truncated: false };
+  }
+
+  let truncatedLines = lines;
+  if (lines.length > config.lines) {
+    truncatedLines = lines.slice(0, config.lines);
+  }
+
+  let result = truncatedLines.join("\n");
+  if (Buffer.byteLength(result, "utf-8") > config.bytes) {
+    let low = 0;
+    let high = result.length;
+    while (low < high) {
+      const mid = Math.floor((low + high + 1) / 2);
+      if (Buffer.byteLength(result.slice(0, mid), "utf-8") <= config.bytes) {
+        low = mid;
+      } else {
+        high = mid - 1;
+      }
+    }
+    result = result.slice(0, low);
+  }
+
+  const keptLines = result.split("\n").length;
+  const marker = `[TRUNCATED: showing first ${keptLines} of ${lines.length} lines, ${formatBytes(Buffer.byteLength(result))} of ${formatBytes(bytes)}${artifactPath ? ` - full output at ${artifactPath}` : ""}]\n`;
+
+  return {
+    text: marker + result,
+    truncated: true,
+    originalBytes: bytes,
+    originalLines: lines.length,
+    artifactPath,
+  };
+}
+
+export function resolveMaxOutput(
+  callMaxOutput: MaxOutputConfig | undefined,
+  config: SubagentsConfig | undefined,
+): Required<MaxOutputConfig> {
+  const fromConfig = config?.maxOutput;
+  return {
+    bytes: callMaxOutput?.bytes ?? fromConfig?.bytes ?? DEFAULT_MAX_OUTPUT.bytes,
+    lines: callMaxOutput?.lines ?? fromConfig?.lines ?? DEFAULT_MAX_OUTPUT.lines,
+  };
+}
+
+// ============================================================================
+// Timeout resolution (reference precedence)
+// ============================================================================
+
+/**
+ * Run-level deadline: call param > agent frontmatter > config > 30-minute
+ * foreground backstop.
+ */
+export function resolveRunTimeoutMs(
+  callTimeoutMs: number | undefined,
+  agent: AgentConfig | undefined,
+  config: SubagentsConfig | undefined,
+): number {
+  return (
+    callTimeoutMs ??
+    agent?.timeoutMs ??
+    config?.timeoutMs ??
+    DEFAULT_RUN_TIMEOUT_MS
+  );
+}
+
+/**
+ * Per-tool-call hard deadline: call param > agent frontmatter > config >
+ * env (UNIPI_SUBAGENT_TOOL_TIMEOUT_MS) > 5-minute default for known-fast
+ * tools only (long-running tools get no hard default).
+ */
+export function resolveToolTimeoutMs(
+  callToolTimeoutMs: number | undefined,
+  agent: AgentConfig | undefined,
+  config: SubagentsConfig | undefined,
+  env: NodeJS.ProcessEnv = process.env,
+): number | undefined {
+  const envRaw = env.UNIPI_SUBAGENT_TOOL_TIMEOUT_MS;
+  const envParsed =
+    envRaw !== undefined && envRaw.trim() !== "" ? Number(envRaw) : undefined;
+  if (envParsed !== undefined && (!Number.isInteger(envParsed) || envParsed <= 0)) {
+    throw new Error("UNIPI_SUBAGENT_TOOL_TIMEOUT_MS must be a positive integer number of milliseconds.");
+  }
+  const configured = callToolTimeoutMs ?? agent?.toolTimeoutMs ?? config?.toolTimeoutMs ?? envParsed;
+  if (configured !== undefined) return configured;
+  // No configured value: hard timeout only for known-fast built-ins.
+  return undefined;
+}
+
+/** Whether a tool gets the 5-minute known-fast default when nothing is configured. */
+export function isKnownFastTool(toolName: string): boolean {
+  return (KNOWN_FAST_TOOLS as readonly string[]).includes(toolName);
+}
+
+export function effectiveToolDeadlineMs(toolName: string, configured: number | undefined): number | undefined {
+  return configured ?? (isKnownFastTool(toolName) ? FAST_TOOL_TIMEOUT_MS : undefined);
+}
+
+/** Tools exempt from hard tool timeouts (their legitimate purpose is waiting). */
+export const TOOL_TIMEOUT_EXEMPT = new Set(["contact_supervisor", "intercom", "get_helper_result", "ask_user"]);

package/src/parity-types.ts

@@ -0,0 +1,315 @@
+/**
+ * @pi-unipi/subagents — Parity types (pi-subagents v0.53.0 feature surface)
+ *
+ * Ported from nicobailon/pi-subagents src/shared/types.ts. Semantics follow
+ * the reference; naming and on-disk layout follow unipi conventions:
+ *   - runtime artifacts under os.tmpdir()/unipi-subagents-<scope>
+ *   - env overrides use UNIPI_SUBAGENT_* (not PI_SUBAGENT_*)
+ *   - tool surface stays spawn_helper / get_helper_result
+ */
+
+import { existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir, userInfo } from "node:os";
+
+// ============================================================================
+// Output / truncation
+// ============================================================================
+
+export interface MaxOutputConfig {
+  bytes?: number;
+  lines?: number;
+}
+
+export type OutputMode = "inline" | "file-only";
+
+export const DEFAULT_MAX_OUTPUT: Required<MaxOutputConfig> = {
+  bytes: 200 * 1024,
+  lines: 5000,
+};
+
+// ============================================================================
+// Budgets
+// ============================================================================
+
+export interface TurnBudgetConfig {
+  maxTurns?: number;
+  graceTurns?: number;
+}
+
+export interface ResolvedTurnBudget {
+  maxTurns: number;
+  graceTurns: number;
+}
+
+export type TurnBudgetOutcome =
+  | "within-budget"
+  | "wrap-up-requested"
+  | "termination-deferred"
+  | "exceeded";
+
+export interface TurnBudgetState extends ResolvedTurnBudget {
+  turns: number;
+  outcome: TurnBudgetOutcome;
+}
+
+export interface ToolBudgetConfig {
+  soft?: number;
+  hard: number;
+  block?: string[] | "*";
+}
+
+export interface ResolvedToolBudget {
+  soft?: number;
+  hard: number;
+  block: "*" | string[];
+}
+
+export type ToolBudgetOutcome = "within-budget" | "soft-reached" | "hard-blocked";
+
+export interface ToolBudgetState extends ResolvedToolBudget {
+  toolCalls: number;
+  outcome: ToolBudgetOutcome;
+}
+
+export interface UsageBudgetLimit {
+  soft?: number;
+  hard: number;
+}
+
+export interface UsageBudgetConfig {
+  tokens?: UsageBudgetLimit;
+  costUsd?: UsageBudgetLimit;
+}
+
+// ============================================================================
+// Run / result states
+// ============================================================================
+
+export type SubagentRunMode = "single" | "parallel" | "chain" | "workflow";
+
+export type SubagentResultStatus =
+  | "completed"
+  | "failed"
+  | "paused"
+  | "stopped"
+  | "detached";
+
+export type SubagentOutputState = "present" | "absent" | "unknown";
+
+export type WorkflowNodeStatus =
+  | "pending"
+  | "running"
+  | "completed"
+  | "failed"
+  | "paused"
+  | "stopped"
+  | "detached"
+  | "rejected";
+
+export type ProcessTerminalState = "pending" | "observed" | "unknown" | "not-started";
+
+export interface Usage {
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+  cost: number;
+  turns: number;
+}
+
+export type ContextMode = "fresh" | "fork";
+
+export type IsolationMode = "none" | "worktree";
+
+// ============================================================================
+// Config sub-objects (ExtensionConfig pieces we port into our subagents.json)
+// ============================================================================
+
+export type FleetViewPlacement = "belowEditor" | "aboveEditor";
+
+export type ToolDescriptionMode = "default" | "full" | "compact" | "custom";
+
+export type InlineToolDisplay = "rich" | "summary";
+
+export interface MainWindowRendererConfig {
+  horizontalSpacing?: number;
+  compactResultMaxLines?: number;
+}
+
+export interface WaitToolConfigObject {
+  enabled?: boolean;
+}
+
+export type WaitToolConfig = boolean | WaitToolConfigObject;
+
+export interface TopLevelParallelConfig {
+  maxTasks?: number;
+  concurrency?: number;
+}
+
+export interface ResultScanLoggingConfig {
+  mode: "all" | "activity" | "off";
+}
+
+// ============================================================================
+// Constants — artifact layout (temp-scoped like the reference, unipi-named)
+// ============================================================================
+
+function sanitizeScopeSegment(value: string): string {
+  const sanitized = value
+    .trim()
+    .replace(/[^A-Za-z0-9._-]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return sanitized || "unknown";
+}
+
+/** Stable per-user temp scope so concurrent users never share artifacts. */
+export function resolveTempScopeId(options?: {
+  env?: NodeJS.ProcessEnv;
+  getuid?: (() => number) | undefined;
+}): string {
+  const env = options?.env ?? process.env;
+  const getuid =
+    options && Object.hasOwn(options, "getuid") ? options.getuid : process.getuid?.bind(process);
+  if (typeof getuid === "function") return `uid-${getuid()}`;
+  for (const key of ["USERNAME", "USER", "LOGNAME"] as const) {
+    const value = env[key];
+    if (value) return `user-${sanitizeScopeSegment(value)}`;
+  }
+  try {
+    const username = userInfo().username;
+    if (username) return `user-${sanitizeScopeSegment(username)}`;
+  } catch {
+    // fall through
+  }
+  const home = env.USERPROFILE ?? env.HOME;
+  if (home) return `home-${sanitizeScopeSegment(home)}`;
+  return "shared";
+}
+
+const configuredTempRoot = process.env.UNIPI_SUBAGENTS_TEMP_ROOT?.trim();
+export const TEMP_ROOT_DIR = configuredTempRoot
+  ? join(configuredTempRoot)
+  : join(tmpdir(), `unipi-subagents-${resolveTempScopeId()}`);
+
+export const RESULTS_DIR = join(TEMP_ROOT_DIR, "async-subagent-results");
+export const ASYNC_DIR = join(TEMP_ROOT_DIR, "async-subagent-runs");
+export const CHAIN_RUNS_DIR = join(TEMP_ROOT_DIR, "chain-runs");
+export const TEMP_ARTIFACTS_DIR = join(TEMP_ROOT_DIR, "artifacts");
+
+export const DIRS = {
+  results: RESULTS_DIR,
+  async: ASYNC_DIR,
+  chain: CHAIN_RUNS_DIR,
+  artifacts: TEMP_ARTIFACTS_DIR,
+} as const;
+
+export function ensureDirs(): void {
+  for (const dir of Object.values(DIRS)) {
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  }
+}
+
+// ============================================================================
+// Widget / render constants
+// ============================================================================
+
+export const WIDGET_KEY_ASYNC = "unipi-agents-async";
+export const MAX_WIDGET_JOBS = 4;
+export const POLL_INTERVAL_MS = 250;
+export const DEFAULT_SUBAGENT_MAX_DEPTH = 2;
+export const DEFAULT_MAX_SUBAGENTS_PER_RUN = 64;
+export const MAX_PARALLEL_TASKS = 8;
+export const DEFAULT_CONCURRENCY = 4;
+export const DEFAULT_GLOBAL_CONCURRENCY_LIMIT = 20;
+
+/** Foreground backstop when nothing else configures a deadline. */
+export const DEFAULT_RUN_TIMEOUT_MS = 30 * 60 * 1000;
+/** Hard per-tool deadline for known-fast built-in tools when toolTimeoutMs unset. */
+export const FAST_TOOL_TIMEOUT_MS = 5 * 60 * 1000;
+export const KNOWN_FAST_TOOLS = ["read", "grep", "find", "ls", "edit", "write"] as const;
+
+// ============================================================================
+// Events (unipi event bus payloads for async lifecycle)
+// ============================================================================
+
+export const SUBAGENT_ASYNC_STARTED_EVENT = "subagent:async-started";
+export const SUBAGENT_ASYNC_COMPLETE_EVENT = "subagent:async-complete";
+export const SUBAGENT_PROCESS_TERMINAL_EVENT = "subagent:process-terminal";
+export const SUBAGENT_CONTROL_EVENT = "subagent:control";
+
+/**
+ * Actions accepted by spawn_helper. Ported from SUBAGENT_ACTIONS; names kept
+ * identical (they are parameter values, not tool names — no convention clash).
+ * Actions land phase by phase; unimplemented ones return a clear error.
+ */
+export const SUBAGENT_ACTIONS = [
+  "list",
+  "get",
+  "children.list",
+  "guide",
+  "create",
+  "update",
+  "delete",
+  "eject",
+  "disable",
+  "enable",
+  "reset",
+  "mission.create",
+  "mission.list",
+  "mission.show",
+  "mission.update",
+  "mission.resolve-decision",
+  "mission.attach-run",
+  "mission.close",
+  "worktree.discard",
+  "refine",
+  "refine.show",
+  "refine.rollback",
+  "inspector.open",
+  "inspector.status",
+  "inspector.close",
+  "project.open",
+  "project.status",
+  "project.close",
+  "status",
+  "debug.run",
+  "grant-spawn-budget",
+  "interrupt",
+  "resume",
+  "steer",
+  "stop",
+  "dismiss",
+  "doctor",
+  "watchdog.status",
+  "watchdog.check",
+  "watchdog.configure",
+  "watchdog.recommend-model",
+  "schedule.create",
+  "schedule.list",
+  "schedule.show",
+  "schedule.history",
+  "schedule.pause",
+  "schedule.resume",
+  "schedule.run",
+  "schedule.run-due",
+  "schedule.delete",
+] as const;
+
+export type SubagentAction = (typeof SUBAGENT_ACTIONS)[number];
+
+export const GUIDE_TOPICS = [
+  "overview",
+  "workflows",
+  "agents",
+  "missions",
+  "observability",
+  "tool-reference",
+  "configuration",
+  "models",
+  "watchdog",
+  "extension-api",
+] as const;
+
+export type GuideTopic = (typeof GUIDE_TOPICS)[number];

package/src/pi-args.ts

@@ -0,0 +1,161 @@
+/**
+ * @pi-unipi/subagents — Child pi CLI argument builder
+ *
+ * Ported from pi-subagents src/runs/shared/pi-args.ts (buildPiArgs core).
+ * Env overrides use OUR prefix: UNIPI_SUBAGENT_TASK_DELIVERY,
+ * UNIPI_SUBAGENT_CHILD, UNIPI_SUBAGENT_PARENT_SESSION. Task delivery follows
+ * the reference: 'auto' passes short tasks inline and writes tasks over
+ * 8000 chars to a temp task.md referenced as @<path> (EDR workaround); 'file'
+ * always uses the file. Zero-activity SIGKILL escalation to file delivery
+ * lives in the runner (Phase 3 next slice).
+ */
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+export const SUBAGENT_TASK_DELIVERY_ENV = "UNIPI_SUBAGENT_TASK_DELIVERY";
+export const SUBAGENT_CHILD_ENV = "UNIPI_SUBAGENT_CHILD";
+export const SUBAGENT_PARENT_SESSION_ENV = "UNIPI_SUBAGENT_PARENT_SESSION";
+export const SUBAGENT_CHILD_AGENT_ENV = "UNIPI_SUBAGENT_CHILD_AGENT";
+export const SUBAGENT_RUN_ID_ENV = "UNIPI_SUBAGENT_RUN_ID";
+
+const TASK_ARG_LIMIT = 8000;
+
+export type SubagentTaskDelivery = "auto" | "file";
+
+export function resolveSubagentTaskDelivery(
+  env: NodeJS.ProcessEnv = process.env,
+): SubagentTaskDelivery {
+  return env[SUBAGENT_TASK_DELIVERY_ENV]?.trim().toLowerCase() === "file" ? "file" : "auto";
+}
+
+function shouldDeliverTaskViaFile(task: string, delivery: SubagentTaskDelivery): boolean {
+  return delivery === "file" || task.length > TASK_ARG_LIMIT;
+}
+
+function escapeXmlAttr(value: string): string {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+
+export interface BuildPiArgsInput {
+  /** Extra CLI args before the task (e.g. ['--print', mode flags]). */
+  baseArgs: string[];
+  task: string;
+  /** pi flags */
+  sessionFile?: string;
+  sessionDir?: string;
+  noSession?: boolean;
+  model?: string;
+  thinking?: string | false;
+  tools?: string[];
+  extensions?: string[];
+  systemPrompt?: string;
+  systemPromptMode?: "replace" | "append";
+  promptFileStem?: string;
+  inheritProjectContext?: boolean;
+  inheritSkills?: boolean;
+  cwd?: string;
+  taskDelivery?: SubagentTaskDelivery;
+  /** Child identification env (parent session targeting for Phase 6 intercom). */
+  parentSessionId?: string;
+  childAgentName?: string;
+  runId?: string;
+}
+
+export interface BuildPiArgsResult {
+  args: string[];
+  env: Record<string, string | undefined>;
+  /** Temp dir holding prompt/task files; caller cleans up after exit. */
+  tempDir: string;
+}
+
+export function buildPiArgs(input: BuildPiArgsInput): BuildPiArgsResult {
+  const args = [...input.baseArgs];
+
+  // ---- Session ----
+  if (input.sessionFile) {
+    fs.mkdirSync(path.dirname(input.sessionFile), { recursive: true });
+    args.push("--session", input.sessionFile);
+  } else {
+    if (input.noSession) args.push("--no-session");
+    if (input.sessionDir) {
+      fs.mkdirSync(input.sessionDir, { recursive: true });
+      args.push("--session-dir", input.sessionDir);
+    }
+  }
+
+  // ---- Model (+ thinking suffix) ----
+  if (input.model) {
+    const thinking = input.thinking;
+    const modelArg =
+      thinking && thinking !== "false" && thinking !== "off"
+        ? `${input.model}--thinking=${thinking}`
+        : input.model;
+    args.push("--model", modelArg);
+  }
+
+  // ---- Tools ----
+  if (input.tools !== undefined) {
+    if (input.tools.length === 0) args.push("--no-tools");
+    else args.push("--tools", input.tools.join(","));
+  }
+
+  // ---- Extensions ----
+  if (input.extensions !== undefined) {
+    args.push("--no-extensions");
+    for (const extPath of input.extensions) args.push("--extension", extPath);
+  }
+
+  // ---- Project context / skills ----
+  if (!input.inheritProjectContext) args.push("--no-context-files");
+  if (!input.inheritSkills) args.push("--no-skills");
+
+  // ---- System prompt via temp file ----
+  let tempDir: string | undefined;
+  if (input.systemPrompt !== undefined && input.systemPrompt !== null) {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "unipi-subagent-"));
+    const stem = (input.promptFileStem ?? "prompt").replace(/[^\w.-]/g, "_");
+    const promptPath = path.join(tempDir, `${stem}.md`);
+    const taggedPrompt = input.childAgentName
+      ? `<active_agent name="${escapeXmlAttr(input.childAgentName)}"/>\n\n${input.systemPrompt}`
+      : input.systemPrompt;
+    fs.writeFileSync(promptPath, taggedPrompt, { mode: 0o600 });
+    args.push(
+      input.systemPromptMode === "replace" ? "--system-prompt" : "--append-system-prompt",
+      promptPath,
+    );
+  }
+
+  // ---- Task delivery (EDR-safe) ----
+  if (shouldDeliverTaskViaFile(input.task, input.taskDelivery ?? resolveSubagentTaskDelivery())) {
+    if (!tempDir) tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "unipi-subagent-"));
+    const taskFilePath = path.join(tempDir, "task.md");
+    fs.writeFileSync(taskFilePath, `Task: ${input.task}`, { mode: 0o600 });
+    args.push(`@${taskFilePath}`);
+  } else {
+    args.push(`Task: ${input.task}`);
+  }
+
+  // ---- Child env ----
+  const env: Record<string, string | undefined> = {};
+  env[SUBAGENT_CHILD_ENV] = "1";
+  if (input.parentSessionId) env[SUBAGENT_PARENT_SESSION_ENV] = input.parentSessionId;
+  if (input.childAgentName) env[SUBAGENT_CHILD_AGENT_ENV] = input.childAgentName;
+  if (input.runId) env[SUBAGENT_RUN_ID_ENV] = input.runId;
+
+  return { args, env, tempDir: tempDir ?? "" };
+}
+
+export function cleanupTempDir(tempDir: string | null | undefined): void {
+  if (!tempDir) return;
+  try {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  } catch {
+    // Best-effort cleanup.
+  }
+}