aiwcli 0.11.1 → 0.12.1

package/dist/templates/cc-native/_cc-native/lib-ts/reviewers/providers/codex-agent.ts

@@ -0,0 +1,185 @@
+/**
+ * Codex CLI agent reviewer implementation.
+ * Uses codex exec with temp files for schema and output.
+ */
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+import { logDebug, logWarn } from "../../../../_shared/lib-ts/base/logger.js";
+import { getInternalSubprocessEnv, execFileAsync } from "../../../../_shared/lib-ts/base/subprocess-utils.js";
+import { debugLog, debugRaw } from "../../debug.js";
+import { parseJsonMaybe, coerceToReview } from "../../json-parser.js";
+import type { ReviewerResult } from "../../types.js";
+import { BaseCliAgent, type ExecResult } from "../base/base-agent.js";
+import { AGENT_REVIEW_PROMPT_PREFIX } from "../schemas.js";
+import { makeResult } from "../types.js";
+
+/** Temp directory for Codex schema/output files */
+const tmpDir: string | null = null;
+
+/**
+ * Codex CLI-based agent reviewer.
+ * Codex has no --system-prompt flag, so we embed schema and persona in stdin.
+ * Uses temp files for schema and output.
+ */
+export class CodexAgent extends BaseCliAgent<ReviewerResult> {
+  private tempDir: string | null = null;
+
+  protected buildCliArgs(): string[] {
+    // Create temp directory for schema and output files
+    this.tempDir = fs.mkdtempSync(path.join(os.tmpdir(), `codex-agent-${this.agent.name}-`));
+
+    const schemaPath = path.join(this.tempDir, "schema.json");
+    const outPath = path.join(this.tempDir, "output.json");
+    fs.writeFileSync(schemaPath, JSON.stringify(this.schema, null, 2), "utf-8");
+
+    const cmdArgs = ["exec", "--sandbox", "read-only"];
+    if (this.agent.model) cmdArgs.push("--model", this.agent.model);
+    cmdArgs.push("--output-schema", schemaPath, "-o", outPath, "-");
+
+    return cmdArgs;
+  }
+
+  protected buildPrompt(plan: string): string {
+    // Codex has no --system-prompt flag, so we prepend the agent persona to stdin.
+    return [
+      AGENT_REVIEW_PROMPT_PREFIX,
+      "---",
+      this.agent.system_prompt || "",
+      "---",
+      `Return ONLY a JSON object matching this schema:\n${JSON.stringify(this.schema)}`,
+      "",
+      "PLAN:",
+      "<<<",
+      plan,
+      ">>>",
+    ].join("\n\n");
+  }
+
+  protected async cleanup(): Promise<void> {
+    if (this.tempDir) {
+      try {
+        fs.rmSync(this.tempDir, { recursive: true, force: true });
+      } catch (error) {
+        logDebug(this.agent.name, `Failed to cleanup temp dir ${this.tempDir}: ${error}`);
+      }
+      this.tempDir = null;
+    }
+  }
+
+  protected coerceResult(obj: Record<string, unknown> | null, raw: string, err: string): ReviewerResult {
+    const [ok, verdict, norm] = coerceToReview(obj, this.getDefaultErrorMessage());
+    return makeResult(this.agent.name, ok, verdict, norm, raw, err);
+  }
+
+  protected extractOutput(result: ExecResult): { raw: string; err: string } {
+    const outPath = this.getOutputPath();
+    let raw = "";
+    const outExists = fs.existsSync(outPath);
+
+    if (outExists) {
+      raw = fs.readFileSync(outPath, "utf-8");
+    }
+
+    logDebug(this.agent.name, `Codex output: exit=${result.exitCode}, outFile=${outExists} (${raw.length} chars), stdout=${result.stdout.length} chars`);
+
+    // Debug logging (override to include out_file_exists)
+    if (this.contextPath) {
+      debugRaw(this.contextPath, this.sessionName, `agent:${this.agent.name}`, "stdout", raw || result.stdout);
+      if (result.stderr) {
+        debugRaw(this.contextPath, this.sessionName, `agent:${this.agent.name}`, "stderr", result.stderr);
+      }
+      debugLog(this.contextPath, this.sessionName, `agent:${this.agent.name}`, "subprocess_info", {
+        exit_code: result.exitCode,
+        stdout_len: (raw || result.stdout).length,
+        stderr_len: result.stderr.length,
+        out_file_exists: outExists,
+        model: this.agent.model,
+        provider: "codex",
+        timeout: this.timeout,
+      });
+    }
+
+    return {
+      raw: raw || result.stdout,
+      err: result.stderr.trim(),
+    };
+  }
+
+  protected getCliName(): string {
+    return "codex";
+  }
+
+  protected makeErrorResult(type: "skip" | "error", message: string): ReviewerResult {
+    return makeResult(this.agent.name, false, type, {}, "", message);
+  }
+
+  protected parseOutput(raw: string, result: ExecResult): Record<string, unknown> | null {
+    return parseJsonMaybe(raw) ?? parseJsonMaybe(result.stdout);
+  }
+
+  /**
+   * Override review() to handle temp file creation in try block.
+   * Codex writes output to a temp file instead of stdout.
+   */
+  async review(plan: string): Promise<ReviewerResult> {
+    const cliPath = this.findCli();
+    if (!cliPath) {
+      return this.makeSkipResult(`${this.getCliName()} CLI not found on PATH`);
+    }
+
+    logDebug(this.agent.name, `Found ${this.getCliName()} CLI at: ${cliPath}`);
+
+    const prompt = this.buildPrompt(plan);
+    const args = this.buildCliArgs();
+
+    logDebug(this.agent.name, `Running ${this.getCliName()} with model: ${this.agent.model}, timeout: ${this.timeout}s`);
+
+    try {
+      const env = getInternalSubprocessEnv();
+      const result = await execFileAsync(cliPath, args, {
+        input: prompt,
+        timeout: this.timeout * 1000,
+        env: env as Record<string, string>,
+        maxBuffer: 10 * 1024 * 1024,
+        shell: process.platform === "win32",
+      });
+
+      if (result.killed || result.signal === "SIGTERM") {
+        return this.handleTimeout();
+      }
+
+      // Extract from temp file if exists, fallback to stdout
+      const { raw, err } = this.extractOutput(result);
+
+      // Log exit code and stderr tail for ALL non-zero exits
+      if (result.exitCode !== 0) {
+        const stderrTail = err.slice(-500);
+        logWarn(this.agent.name, `Codex exited with code ${result.exitCode}, stderr_len=${err.length}, stderr_tail: ${stderrTail}`);
+      }
+
+      if (!raw && !err && !this.outputFileExists() && result.exitCode !== 0) {
+        return this.handleExitError(result);
+      }
+
+      this.logSubprocessResult(result, raw, err);
+
+      const obj = this.parseOutput(raw, result);
+      this.logParsedResult(obj);
+
+      return this.coerceResult(obj, raw, err);
+    } finally {
+      await this.cleanup();
+    }
+  }
+
+  private getOutputPath(): string {
+    return path.join(this.tempDir!, "output.json");
+  }
+
+  private outputFileExists(): boolean {
+    return this.tempDir ? fs.existsSync(this.getOutputPath()) : false;
+  }
+}

package/dist/templates/cc-native/_cc-native/lib-ts/reviewers/providers/gemini-agent.ts

@@ -0,0 +1,39 @@
+/**
+ * Gemini CLI agent reviewer implementation (stub).
+ * Placeholder for future implementation.
+ */
+
+import type { ReviewerResult } from "../../types.js";
+import { BaseCliAgent } from "../base/base-agent.js";
+import { makeResult } from "../types.js";
+
+/**
+ * Gemini CLI-based agent reviewer (NOT IMPLEMENTED).
+ * All methods throw "not implemented" errors.
+ * This is a placeholder for future development.
+ */
+export class GeminiAgent extends BaseCliAgent<ReviewerResult> {
+  protected buildCliArgs(): string[] {
+    throw new Error("GeminiAgent not implemented");
+  }
+
+  protected buildPrompt(_plan: string): string {
+    throw new Error("GeminiAgent not implemented");
+  }
+
+  protected coerceResult(_obj: Record<string, unknown> | null, _raw: string, _err: string): ReviewerResult {
+    throw new Error("GeminiAgent not implemented");
+  }
+
+  protected getCliName(): string {
+    throw new Error("GeminiAgent not implemented");
+  }
+
+  protected makeErrorResult(type: "skip" | "error", message: string): ReviewerResult {
+    return makeResult(this.agent.name, false, type, {}, "", message);
+  }
+
+  protected parseOutput(_raw: string, _result: unknown): Record<string, unknown> | null {
+    throw new Error("GeminiAgent not implemented");
+  }
+}

package/dist/templates/cc-native/_cc-native/lib-ts/reviewers/providers/orchestrator-claude-agent.ts

@@ -0,0 +1,195 @@
+/**
+ * Orchestrator agent implementation using BaseCliAgent framework.
+ * Analyzes plan complexity and selects reviewer agents via Claude CLI.
+ */
+
+import { logDebug } from "../../../../_shared/lib-ts/base/logger.js";
+import { shellQuoteWin } from "../../../../_shared/lib-ts/base/subprocess-utils.js";
+import { parseCliOutput } from "../../cli-output-parser.js";
+import type { AgentConfig, OrchestratorResult, ComplexityCategory } from "../../types.js";
+import { BaseCliAgent } from "../base/base-agent.js";
+import { buildOrchestratorSchema, ORCHESTRATOR_SCHEMA } from "../schemas.js";
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const DEFAULT_COMPLEXITY_CATEGORIES = [
+  "code",
+  "infrastructure",
+  "documentation",
+  "life",
+  "business",
+  "design",
+  "research",
+];
+
+const DEFAULT_AGENT_SELECTION: Record<string, unknown> = {
+  simple: { min: 3, max: 3 },
+  medium: { min: 8, max: 8 },
+  high: { min: 12, max: 12 },
+  fallbackCount: 3,
+};
+
+/**
+ * Claude CLI-based orchestrator agent.
+ * Extends BaseCliAgent<OrchestratorResult> to reuse subprocess execution infrastructure.
+ */
+export class OrchestratorClaudeAgent extends BaseCliAgent<OrchestratorResult> {
+  private categories: string[];
+  private fallbackCount: number;
+  private mandatoryCount: number;
+  private nonMandatory: AgentConfig[];
+  private settings: Record<string, unknown>;
+  private validNames: string[];
+
+  constructor(
+    agent: AgentConfig,
+    agentLibrary: AgentConfig[],
+    mandatoryNames: Set<string>,
+    settings: Record<string, unknown>,
+    timeout: number,
+    contextPath?: string,
+    sessionName?: string,
+  ) {
+    // Build schema dynamically based on valid agent names
+    const nonMandatory = agentLibrary.filter(
+      (a) => a.enabled && !mandatoryNames.has(a.name),
+    );
+    const validNames = nonMandatory.map((a) => a.name);
+    const categories = (settings.complexityCategories as string[]) ?? DEFAULT_COMPLEXITY_CATEGORIES;
+
+    const schema = validNames.length > 0
+      ? buildOrchestratorSchema(validNames, categories)
+      : ORCHESTRATOR_SCHEMA;
+
+    super(agent, schema, timeout, contextPath, sessionName);
+
+    this.nonMandatory = nonMandatory;
+    this.validNames = validNames;
+    this.categories = categories;
+    this.settings = settings;
+
+    const selection = (settings.agentSelection as Record<string, unknown>) ?? DEFAULT_AGENT_SELECTION;
+    this.fallbackCount = (selection.fallbackCount as number) ?? 2;
+    this.mandatoryCount = agentLibrary.filter((a) => mandatoryNames.has(a.name)).length;
+
+    logDebug("orchestrator", `Mandatory agents (always run): ${[...mandatoryNames].sort().join(", ")}`);
+    logDebug("orchestrator", `Non-mandatory agents for selection: ${validNames.join(", ")}`);
+  }
+
+  protected buildCliArgs(): string[] {
+    const schemaJson = JSON.stringify(this.schema);
+
+    const systemPrompt = `You are a plan orchestrator for code review. Your job is to analyze plans and select appropriate reviewer agents.
+
+You MUST call StructuredOutput immediately with your analysis. Do NOT ask questions or use any other tools.
+
+When selecting agents:
+- Match agent expertise to plan requirements
+- Consider what each agent specializes in
+- Only select agents whose categories match the plan category
+- Fewer agents for simple plans, more for complex plans`;
+
+    return [
+      "--model", this.agent.model,
+      "--output-format", "json",
+      "--json-schema", shellQuoteWin(schemaJson),
+      "--max-turns", "3",
+      "--setting-sources", process.platform === "win32" ? '""' : "",
+      "--system-prompt", shellQuoteWin(systemPrompt),
+      "-p",
+    ];
+  }
+
+  protected buildPrompt(plan: string): string {
+    const selection = (this.settings.agentSelection as Record<string, unknown>) ?? DEFAULT_AGENT_SELECTION;
+
+    const agentList = this.nonMandatory
+      .map(
+        (a) =>
+          `- ${a.name} [${a.categories.join(", ")}]\n  Focus: ${a.focus}\n  Expertise: ${a.description}`,
+      )
+      .join("\n");
+    const categoryList = this.categories.join("/");
+
+    const simpleAdditional = Math.max(0, ((selection.simple as Record<string, number> | undefined)?.max ?? 3) - this.mandatoryCount);
+    const mediumAdditional = Math.max(0, ((selection.medium as Record<string, number> | undefined)?.max ?? 8) - this.mandatoryCount);
+    const highAdditional = Math.max(0, ((selection.high as Record<string, number> | undefined)?.max ?? 12) - this.mandatoryCount);
+
+    return `Analyze this plan and select appropriate reviewer agents.
+
+Available agents (select ONLY from this list):
+${agentList}
+
+Selection rules (number of ADDITIONAL agents to select from the list above):
+- simple complexity = ${simpleAdditional} agents
+- medium complexity = ${mediumAdditional} agents
+- high complexity = ${highAdditional} agents
+- Only select agents whose categories match the plan category (${categoryList})
+- Non-technical plans (life, business) typically need 0 code-focused agents
+- Note: mandatory agents run separately and are NOT listed above
+
+PLAN:
+<<<
+${plan}
+>>>
+
+Call StructuredOutput now with: complexity, category, selectedAgents, reasoning`;
+  }
+
+  protected coerceResult(obj: Record<string, unknown> | null, _raw: string, _err: string): OrchestratorResult {
+    if (!obj) {
+      return this.makeFallback("Orchestrator output could not be parsed", "Failed to parse orchestrator output");
+    }
+
+    // Extract and validate fields
+    const rawComplexity = String(obj.complexity ?? "medium");
+    const complexity: ComplexityCategory =
+      rawComplexity === "simple" || rawComplexity === "medium" || rawComplexity === "high"
+        ? rawComplexity
+        : "medium";
+
+    let category = (obj.category as string) ?? "code";
+    if (!this.categories.includes(category)) category = "code";
+
+    let {selectedAgents} = obj;
+    if (!Array.isArray(selectedAgents)) selectedAgents = [];
+
+    const reasoning = String(obj.reasoning ?? "").trim() || "No reasoning provided";
+    const skipReason = obj.skipReason as string | undefined;
+
+    return {
+      complexity,
+      category,
+      selected_agents: selectedAgents as string[],
+      reasoning,
+      skip_reason: skipReason || undefined,
+    };
+  }
+
+  protected getCliName(): string {
+    return "claude";
+  }
+
+  protected makeErrorResult(type: "skip" | "error", message: string): OrchestratorResult {
+    return this.makeFallback(
+      type === "skip" ? `Orchestrator skipped - ${message}` : message,
+      message,
+    );
+  }
+
+  protected parseOutput(raw: string, _result: unknown): Record<string, unknown> | null {
+    return parseCliOutput(raw);
+  }
+
+  private makeFallback(reasoning: string, error: string): OrchestratorResult {
+    return {
+      complexity: "medium",
+      category: "code",
+      selected_agents: this.nonMandatory.slice(0, this.fallbackCount).map((a) => a.name),
+      reasoning,
+      error,
+    };
+  }
+}

package/dist/templates/cc-native/_cc-native/lib-ts/reviewers/schemas.ts

@@ -0,0 +1,201 @@
+/**
+ * JSON schemas and prompt constants for plan reviewers.
+ * Centralized schema definitions used by Claude/Codex/Gemini agents and orchestrator.
+ * See cc-native-plan-review-spec.md §4.10
+ */
+
+// ---------------------------------------------------------------------------
+// Prompt Constants
+// ---------------------------------------------------------------------------
+
+/** Prefix for agent review prompts (embedded in stdin or --system-prompt) */
+export const AGENT_REVIEW_PROMPT_PREFIX = `# SINGLE-TURN PLAN REVIEW
+
+## CRITICAL: ONE TURN ONLY
+You have exactly ONE response to complete this review. Do NOT attempt multi-step workflows, context queries, or phased analysis. Analyze the plan and output your review immediately.
+
+## YOUR TASK
+Review the plan below from your area of expertise. Then call StructuredOutput with your assessment.
+
+## REQUIRED OUTPUT (all fields must have content)
+Call StructuredOutput with:
+- **verdict**: "pass" (no concerns), "warn" (some concerns), or "fail" (critical issues)
+- **summary**: 2-3 sentences with your overall assessment and key findings (REQUIRED)
+- **issues**: Array of concerns found. Format each as:
+  {"severity": "high/medium/low", "category": "...", "issue": "...", "suggested_fix": "...", "dimension": "..."}
+- **dimension**: Classify each issue into exactly one dimension:
+  completeness, simplicity, security, performance, reliability,
+  maintainability, testability, scope, feasibility, or clarity.
+  Examples: "missing error handling" → reliability, "excessive abstraction" → simplicity,
+  "no test strategy" → testability, "missing deployment steps" → completeness,
+  "unclear interaction between components" → clarity.
+- **missing_sections**: Topics the plan should address but doesn't
+- **questions**: Things that need clarification before implementation
+
+## IMPORTANT RULES
+1. A "warn" verdict MUST include at least one issue explaining why
+2. Summary MUST explain your reasoning, not just "looks good" or empty
+3. Focus on your expertise area (architecture, security, performance, etc.)
+4. Output StructuredOutput NOW - no other tools, no questions, no delays
+5. Return ONLY your top 3 most critical issues. Prioritize high-severity over medium/low. Quality over quantity.
+`;
+
+/** Prefix for Codex/Gemini review prompts (legacy, may be deprecated) */
+export const REVIEW_PROMPT_PREFIX = `You are a senior staff software engineer acting as a strict plan reviewer.
+
+Review the PLAN below. Focus on:
+- missing steps, unclear assumptions, edge cases
+- security/privacy concerns
+- testing/rollout/rollback completeness
+- operational concerns (observability, failure modes)
+`;
+
+// ---------------------------------------------------------------------------
+// JSON Schemas
+// ---------------------------------------------------------------------------
+
+/** JSON schema for review structured output (agents: Claude, Codex, Gemini) */
+export const REVIEW_SCHEMA: Record<string, unknown> = {
+  type: "object",
+  properties: {
+    verdict: { type: "string", enum: ["pass", "warn", "fail"] },
+    summary: { type: "string", minLength: 20 },
+    issues: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          severity: { type: "string", enum: ["high", "medium", "low"] },
+          category: { type: "string" },
+          issue: { type: "string" },
+          suggested_fix: { type: "string" },
+          dimension: {
+            type: "string",
+            enum: [
+              "completeness", "simplicity", "security", "performance",
+              "reliability", "maintainability", "testability", "scope",
+              "feasibility", "clarity",
+            ],
+          },
+        },
+        required: ["severity", "category", "issue", "suggested_fix", "dimension"],
+        additionalProperties: false,
+      },
+    },
+    missing_sections: { type: "array", items: { type: "string" } },
+    questions: { type: "array", items: { type: "string" } },
+  },
+  required: ["verdict", "summary", "issues", "missing_sections", "questions"],
+  additionalProperties: false,
+};
+
+/**
+ * Build orchestrator JSON schema with enum-constrained agent names.
+ * Dynamic schema that restricts selectedAgents to valid agent names.
+ */
+export function buildOrchestratorSchema(
+  validAgentNames: string[],
+  categories: string[],
+): Record<string, unknown> {
+  const itemsSchema: Record<string, unknown> = { type: "string" };
+  if (validAgentNames.length > 0) {
+    itemsSchema.enum = validAgentNames;
+  }
+
+  return {
+    type: "object",
+    properties: {
+      complexity: { type: "string", enum: ["simple", "medium", "high"] },
+      category: { type: "string", enum: categories },
+      selectedAgents: {
+        type: "array",
+        items: itemsSchema,
+      },
+      reasoning: { type: "string" },
+      skipReason: { type: "string" },
+    },
+    required: ["complexity", "category", "selectedAgents", "reasoning"],
+    additionalProperties: false,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Plan Questions Schema
+// ---------------------------------------------------------------------------
+
+/** Prefix for plan question generation prompts */
+export const QUESTIONS_PROMPT_PREFIX = `# PLAN QUESTION GENERATION
+
+## CRITICAL: ONE TURN ONLY
+You have exactly ONE response. Do NOT attempt multi-step workflows or tool use beyond StructuredOutput.
+
+## YOUR TASK
+You are reviewing a plan that was written by another agent. You have NO access to the codebase, NO session history, and NO exploration context. You see ONLY the plan text.
+
+This is intentional. Plans must be executable by a fresh agent in a new session. If the plan assumes knowledge that isn't written down, that's a gap.
+
+## WHAT TO LOOK FOR
+- Questions the plan doesn't answer but should
+- Assumptions the plan makes without stating them
+- Ambiguities where a reader could interpret something two ways
+- Missing context that would be obvious to the author but not a new reader
+
+## IMPORTANT
+- Focus on questions that would change the implementation approach if answered differently
+- Don't ask about things clearly stated in the plan
+- Don't generate generic questions — every question should be specific to THIS plan
+- Aim for 3-6 high-value questions
+`;
+
+/** JSON schema for plan question generation output */
+export const QUESTIONS_SCHEMA: Record<string, unknown> = {
+  type: "object",
+  properties: {
+    questions: {
+      type: "array",
+      items: { type: "string" },
+      description: "Questions the user should answer before this plan is implemented",
+    },
+    assumptions: {
+      type: "array",
+      items: { type: "string" },
+      description: "Assumptions the plan makes that are not explicitly stated",
+    },
+    ambiguities: {
+      type: "array",
+      items: { type: "string" },
+      description: "Parts of the plan that could be interpreted multiple ways",
+    },
+  },
+  required: ["questions", "assumptions", "ambiguities"],
+  additionalProperties: false,
+};
+
+// ---------------------------------------------------------------------------
+// Orchestrator Schemas
+// ---------------------------------------------------------------------------
+
+/** JSON schema for orchestrator structured output (static fallback) */
+export const ORCHESTRATOR_SCHEMA: Record<string, unknown> = {
+  type: "object",
+  properties: {
+    complexity: { type: "string", enum: ["simple", "medium", "high"] },
+    category: {
+      type: "string",
+      enum: [
+        "code",
+        "infrastructure",
+        "documentation",
+        "life",
+        "business",
+        "design",
+        "research",
+      ],
+    },
+    selectedAgents: { type: "array", items: { type: "string" } },
+    reasoning: { type: "string" },
+    skipReason: { type: "string" },
+  },
+  required: ["complexity", "category", "selectedAgents", "reasoning"],
+  additionalProperties: false,
+};

package/dist/templates/cc-native/_cc-native/lib-ts/reviewers/types.ts

@@ -3,7 +3,7 @@
  * See cc-native-plan-review-spec.md §4.9
  */
 
-import type { ReviewData,  ReviewerResult,  Verdict } from "../types.js";
+import type { ReviewerResult,   Verdict, ReviewData } from "../types.js";
 
 // Re-export for convenience
 
@@ -13,7 +13,7 @@ export function makeResult(
   name: string,
   ok: boolean,
   verdict: Verdict,
-  data: Record<string, unknown> | ReviewData,
+  data: ReviewData | Record<string, unknown>,
   raw: string,
   err: string,
 ): ReviewerResult {