@leing2021/super-pi 0.23.8 → 0.23.10

package/README.md

@@ -118,6 +118,7 @@ Super Pi is not a fork or wrapper. It extracts useful methods from the projects
 |---------|------------------------|
 | [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills) | "Use when" skill trigger conditions, source-driven verification, stop-the-line hard gate, anti-rationalization, and the five-axis review baseline. Adopted as embedded micro-patterns only — no new skills, tools, commands, or agents. |
 | [everything-claude-code](https://github.com/affaan-m/everything-claude-code) | Parallel subagent orchestration, checkpoint resume, continuous learning loops, and token-conscious agent workflow design. |
+| [humanlayer/12-factor-agents](https://github.com/humanlayer/12-factor-agents) | Context window ownership, compacting resolved errors, retry caps, and pre-fetching obvious prerequisites. Adopted as lightweight context hygiene rules inside the existing Phase 1 pipeline. |
 | [superpowers](https://github.com/obra/superpowers) | Strict TDD gates, design checklists, review discipline, and the idea that agents need hard gates instead of gentle suggestions. |
 | [compound-engineering-plugin](https://github.com/EveryInc/compound-engineering-plugin) | The five-step think → plan → build → review → learn loop and the knowledge-compounding backbone. |
 | [gstack](https://github.com/garrytan/gstack) | YC-style forcing questions, CEO Review cognitive frameworks, browser QA patterns, failure maps, and evidence-first validation. |

package/extensions/ce-core/index.ts

@@ -19,10 +19,12 @@ import { createContextHandoffTool } from "./tools/context-handoff"
 import { filterBashOutput } from "./tools/bash-output-filter"
 import { filterReadOutput } from "./tools/read-output-filter"
 import { COMPACTION_FOCUS_INSTRUCTIONS } from "./tools/compaction-optimizer"
-import { AsyncMutex } from "./tools/async-mutex"
-import type { SubagentExecOptions, SubagentRunner } from "./tools/subagent"
+import { createJsonRunner, type JsonRunConfig } from "./tools/subagent-json-runner"
+import { getFinalOutput, isFailedResult, type SingleResult } from "./tools/subagent-events"
+import { renderSubagentCall, renderSubagentResult } from "./tools/subagent-renderer"
+import type { SubagentLiveRunner, SubagentLiveExecOptions, SubagentLiveDetails } from "./tools/subagent"
+import type { ParallelSubagentLiveDetails } from "./tools/parallel-subagent"
 
-const _subagentEnvMutex = new AsyncMutex()
 const PIPELINE_STAGE_KEYS = new Set([
   "01-brainstorm",
   "02-plan",
@@ -115,43 +117,30 @@ function parseModelRef(
 }
 
 /**
- * Create a subagent runner that handles env injection with mutex protection
- * for concurrency safety when multiple parallel subagents share the process.
+ * Create a spawn-based subagent runner that uses pi --mode json
+ * with per-process env (no global process.env mutation).
  */
 function createSubagentRunner(
   pi: ExtensionAPI,
   signal?: AbortSignal,
-): SubagentRunner {
-  return async (prompt: string, options?: SubagentExecOptions) => {
-    const args = ["--no-session", ...(options?.extraFlags ?? []), "-p", prompt]
-    const release = await _subagentEnvMutex.acquire()
-    const savedEnv: Record<string, string | undefined> = {}
-    const extraEnv = options?.extraEnv ?? {}
-    for (const [key, value] of Object.entries(extraEnv)) {
-      savedEnv[key] = process.env[key]
-      process.env[key] = value
+): SubagentLiveRunner {
+  const jsonRunner = createJsonRunner()
+  return async (prompt: string, options?: SubagentLiveExecOptions) => {
+    const config: JsonRunConfig = {
+      prompt,
+      agent: "",
+      task: "",
+      cwd: pi.cwd ?? process.cwd(),
+      extraFlags: options?.extraFlags,
+      extraEnv: options?.extraEnv,
+      signal,
+      onUpdate: options?.onUpdate,
     }
-    try {
-      const execResult = await pi.exec("pi", args, {
-        signal,
-        timeout: 10 * 60 * 1000,
-      })
-
-      if (execResult.code !== 0) {
-        throw new Error(execResult.stderr || execResult.stdout || `Subagent failed for prompt: ${prompt}`)
-      }
-
-      return (execResult.stdout || "").trim()
-    } finally {
-      for (const [key, oldValue] of Object.entries(savedEnv)) {
-        if (oldValue === undefined) {
-          delete process.env[key]
-        } else {
-          process.env[key] = oldValue
-        }
-      }
-      release()
+    const result = await jsonRunner.run(config)
+    if (isFailedResult(result) || result.exitCode !== 0) {
+      throw new Error(result.errorMessage || result.stderr || `Subagent failed for prompt: ${prompt}`)
     }
+    return result
   }
 }
 
@@ -505,7 +494,7 @@ export default function ceCoreExtension(pi: ExtensionAPI) {
     label: "CE Subagent",
     description: "Run a single CE skill-based subagent or a serial chain in an isolated Pi process.",
     parameters: subagentParams,
-    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+    async execute(_toolCallId, params, signal, onUpdate, ctx) {
       const result = await subagent.execute(
         {
           agent: params.agent,
@@ -514,13 +503,26 @@ export default function ceCoreExtension(pi: ExtensionAPI) {
           inheritSkills: params.inheritSkills,
         },
         createSubagentRunner(pi, signal),
+        { onUpdate },
       )
 
+      // Build final content from results
+      const lastResult = result.results[result.results.length - 1]
+      const finalText = lastResult ? getFinalOutput(lastResult.messages) : ""
+      const isError = lastResult ? isFailedResult(lastResult) : false
+
       return {
-        content: [{ type: "text", text: result.outputs[result.outputs.length - 1] ?? "" }],
+        content: [{ type: "text", text: finalText || "(no output)" }],
         details: result,
+        isError: isError || undefined,
       }
     },
+    renderCall(args, theme, _context) {
+      return renderSubagentCall(args, theme)
+    },
+    renderResult(result, renderContext, theme, _context) {
+      return renderSubagentResult(result.details as SubagentLiveDetails, renderContext, theme)
+    },
   })
 
   pi.registerTool({
@@ -599,7 +601,7 @@ export default function ceCoreExtension(pi: ExtensionAPI) {
     label: "CE Parallel Subagent",
     description: "Run multiple CE skill-based subagent tasks concurrently. IMPORTANT: Provide 'tasks' as a clean JSON array object. If the environment forces a string, provide a valid JSON array string.",
     parameters: parallelSubagentParams,
-    async execute(_toolCallId, params, signal) {
+    async execute(_toolCallId, params, signal, onUpdate) {
       let tasks: any[]
       if (typeof params.tasks === "string") {
         try {
@@ -618,13 +620,32 @@ export default function ceCoreExtension(pi: ExtensionAPI) {
           inheritSkills: params.inheritSkills,
         },
         createSubagentRunner(pi, signal),
+        { onUpdate },
       )
 
+      // Build summary content
+      const successCount = result.results.filter(r => r.exitCode === 0).length
+      const failCount = result.results.filter(r => isFailedResult(r)).length
+      const summaries = result.results.map(r => {
+        const output = getFinalOutput(r.messages) || r.errorMessage || r.stderr || "(no output)"
+        const status = isFailedResult(r) ? "failed" : "completed"
+        return `### [${r.agent}] ${status}\n\n${output}`
+      })
+
       return {
-        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        content: [{
+          type: "text",
+          text: `Parallel: ${successCount}/${result.results.length} succeeded${failCount > 0 ? `, ${failCount} failed` : ""}\n\n${summaries.join("\n\n---\n\n")}`,
+        }],
         details: result,
       }
     },
+    renderCall(args, theme, _context) {
+      return renderSubagentCall(args, theme)
+    },
+    renderResult(result, renderContext, theme, _context) {
+      return renderSubagentResult(result.details as SubagentLiveDetails, renderContext, theme)
+    },
   })
 
   pi.registerTool({
@@ -873,6 +894,24 @@ export { createAskUserQuestionTool } from "./tools/ask-user-question"
 export { createSubagentTool } from "./tools/subagent"
 export { checkSubagentDepth, getChildDepthEnv, DEFAULT_MAX_SUBAGENT_DEPTH } from "./tools/subagent-depth-guard"
 export { AsyncMutex } from "./tools/async-mutex"
+export { createJsonRunner } from "./tools/subagent-json-runner"
+export {
+  parseJsonEvent,
+  applyEventToResult,
+  type SingleResult as SingleResultType,
+  type UsageStats,
+  type ParsedEvent,
+  isFailedResult as isFailedSingleResult,
+  formatUsageStats,
+  makeInitialResult,
+  getFinalOutput as getFinalOutputFromMessages,
+  getDisplayItems,
+} from "./tools/subagent-events"
+export {
+  formatToolCall,
+  renderSubagentCall,
+  renderSubagentResult,
+} from "./tools/subagent-renderer"
 export { createWorkflowStateTool } from "./tools/workflow-state"
 export { createWorktreeManagerTool } from "./tools/worktree-manager"
 export { createReviewRouterTool } from "./tools/review-router"

package/extensions/ce-core/tools/parallel-subagent.ts

@@ -4,13 +4,63 @@
  * Features:
  *   - Recursion depth guard (PI_SUBAGENT_DEPTH / PI_SUBAGENT_MAX_DEPTH)
  *   - Optional context slimming via --no-skills flag
+ *   - Concurrency limit via mapWithConcurrencyLimit (from pi official example)
+ *   - Live TUI updates with running placeholders and per-task status
+ *   - Promise.allSettled semantics: one failure does NOT cancel others
  */
 
 import {
   checkSubagentDepth,
   getChildDepthEnv,
 } from "./subagent-depth-guard"
-import { assertNonPipelineStageSkill, type SubagentExecOptions, type SubagentRunner } from "./subagent"
+import {
+  type SingleResult,
+  makeInitialResult,
+  isFailedResult,
+  getFinalOutput,
+  makeFailedResult,
+  invokeRunner,
+} from "./subagent-events"
+import {
+  assertNonPipelineStageSkill,
+  type SubagentLiveRunner,
+  type SubagentLiveExecOptions,
+} from "./subagent"
+
+// ---------------------------------------------------------------------------
+// Constants (from pi official example)
+// ---------------------------------------------------------------------------
+
+const MAX_PARALLEL_TASKS = 8
+const MAX_CONCURRENCY = 4
+
+// ---------------------------------------------------------------------------
+// mapWithConcurrencyLimit (directly from pi official subagent example)
+// ---------------------------------------------------------------------------
+
+async function mapWithConcurrencyLimit<TIn, TOut>(
+  items: TIn[],
+  concurrency: number,
+  fn: (item: TIn, index: number) => Promise<TOut>,
+): Promise<TOut[]> {
+  if (items.length === 0) return []
+  const limit = Math.max(1, Math.min(concurrency, items.length))
+  const results: TOut[] = new Array(items.length)
+  let nextIndex = 0
+  const workers = new Array(limit).fill(null).map(async () => {
+    while (true) {
+      const current = nextIndex++
+      if (current >= items.length) return
+      results[current] = await fn(items[current], current)
+    }
+  })
+  await Promise.all(workers)
+  return results
+}
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
 
 export interface ParallelSubagentTask {
   agent: string
@@ -23,25 +73,24 @@ export interface ParallelSubagentInput {
   inheritSkills?: boolean
 }
 
-export interface ParallelResultItem {
-  status: "fulfilled" | "rejected"
-  value?: string
-  reason?: string
-}
-
-export interface ParallelSubagentResult {
+export interface ParallelSubagentLiveDetails {
   mode: "parallel"
-  outputs: ParallelResultItem[]
+  results: SingleResult[]
 }
 
-function buildPrompt(agent: string, task: string): string {
-  return `/skill:${agent} ${task}`
-}
+// ---------------------------------------------------------------------------
+// Tool factory
+// ---------------------------------------------------------------------------
 
 export function createParallelSubagentTool() {
   return {
-    name: "ce_parallel_subagent",
-    async execute(input: ParallelSubagentInput, runner: SubagentRunner): Promise<ParallelSubagentResult> {
+    name: "ce_parallel_subagent" as const,
+
+    async execute(
+      input: ParallelSubagentInput,
+      runner: SubagentLiveRunner,
+      toolCtx?: { onUpdate?: (details: ParallelSubagentLiveDetails) => void },
+    ): Promise<ParallelSubagentLiveDetails> {
       // Recursion depth guard
       const depthCheck = checkSubagentDepth()
       if (!depthCheck.allowed) {
@@ -52,49 +101,73 @@ export function createParallelSubagentTool() {
         throw new Error("ce_parallel_subagent requires at least one task")
       }
 
+      if (input.tasks.length > MAX_PARALLEL_TASKS) {
+        throw new Error(
+          `Too many parallel tasks (${input.tasks.length}). Max is ${MAX_PARALLEL_TASKS}.`,
+        )
+      }
+
       for (const task of input.tasks) {
         assertNonPipelineStageSkill(task.agent, "ce_parallel_subagent")
       }
 
-      // Default: parallel workers get a slim context (no inherited skills)
-      const inheritSkills = input.inheritSkills ?? false
-      const execOptions = buildParallelExecOptions(inheritSkills)
+      const execOptions = buildParallelExecOptions(input.inheritSkills)
 
-      const promises = input.tasks.map(({ agent, task }) =>
-        runner(buildPrompt(agent, task), execOptions),
+      // Initialize all results as running placeholders
+      const allResults: SingleResult[] = input.tasks.map(({ agent, task }) =>
+        makeInitialResult(agent, task),
       )
 
-      const settled = await Promise.allSettled(promises)
+      // Emit initial state (all running)
+      emitParallelUpdate(allResults, toolCtx)
+
+      // Run tasks with concurrency limit
+      await mapWithConcurrencyLimit(input.tasks, MAX_CONCURRENCY, async (t, index) => {
+        const liveOptions: SubagentLiveExecOptions = {
+          ...execOptions,
+          onUpdate: (partial: SingleResult) => {
+            allResults[index] = partial
+            emitParallelUpdate(allResults, toolCtx)
+          },
+        }
 
-      const outputs: ParallelResultItem[] = settled.map((result) => {
-        if (result.status === "fulfilled") {
-          return { status: "fulfilled", value: result.value }
+        try {
+          const result = await invokeRunner(runner, `/skill:${t.agent} ${t.task}`, liveOptions)
+          allResults[index] = result
+        } catch (e) {
+          // Preserve allSettled semantics: one failure does not cancel others
+          allResults[index] = makeFailedResult(t.agent, t.task, e instanceof Error ? e.message : String(e))
         }
-        return { status: "rejected", reason: result.reason?.message || String(result.reason) }
+        emitParallelUpdate(allResults, toolCtx)
+        return allResults[index]
       })
 
-      return {
-        mode: "parallel",
-        outputs,
-      }
+      return { mode: "parallel", results: allResults }
     },
   }
 }
 
-/**
- * Build exec options for parallel subagent workers.
- * Defaults to slim context (no inherited skills).
- */
-function buildParallelExecOptions(inheritSkills: boolean): SubagentExecOptions {
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function emitParallelUpdate(
+  results: SingleResult[],
+  toolCtx?: { onUpdate?: (details: ParallelSubagentLiveDetails) => void },
+) {
+  if (toolCtx?.onUpdate) {
+    toolCtx.onUpdate({ mode: "parallel", results: [...results] })
+  }
+}
+
+function buildParallelExecOptions(inheritSkills?: boolean): { extraFlags?: string[]; extraEnv: Record<string, string> } {
   const flags: string[] = []
   const env: Record<string, string> = {}
 
-  // Context slimming
-  if (!inheritSkills) {
+  if (inheritSkills !== true) {
     flags.push("--no-skills")
   }
 
-  // Recursion depth
   Object.assign(env, getChildDepthEnv())
 
   return {
@@ -102,3 +175,20 @@ function buildParallelExecOptions(inheritSkills: boolean): SubagentExecOptions {
     extraEnv: env,
   }
 }
+
+// ---------------------------------------------------------------------------
+// Legacy backward-compat types and exports
+// ---------------------------------------------------------------------------
+
+/** @deprecated Use ParallelSubagentLiveDetails instead */
+export interface ParallelResultItem {
+  status: "fulfilled" | "rejected"
+  value?: string
+  reason?: string
+}
+
+/** @deprecated Use ParallelSubagentLiveDetails instead */
+export interface ParallelSubagentResult {
+  mode: "parallel"
+  outputs: ParallelResultItem[]
+}