supipowers 1.5.3 → 2.0.0

package/src/ai/structured-output.ts

@@ -0,0 +1,274 @@
+// src/ai/structured-output.ts
+//
+// Canonical schema-backed AI output path. Every AI-heavy workflow (review,
+// planning, commit, docs-drift, AI review gate, fix-pr, release) must flow
+// through this module for:
+//   - final assistant message extraction (via ./final-message.ts)
+//   - JSON-fence stripping + schema-checked parsing
+//   - retry with a validator-feedback prompt until maxAttempts exhausts
+//   - explicit blocked result when parsing never succeeds
+//
+// One canonical retry template lives in `./prompts/invalid-output-retry.md`.
+// One canonical renderer lives in `./template.ts`. Neither has a review-
+// specific name any more.
+
+import type { TSchema } from "@sinclair/typebox";
+import { Value } from "@sinclair/typebox/value";
+import invalidOutputRetryPrompt from "./prompts/invalid-output-retry.md" with { type: "text" };
+import { runStructuredAgentSession } from "./final-message.js";
+import { renderTemplate } from "./template.js";
+import { stripMarkdownCodeFence } from "../text.js";
+import type { GateExecutionContext, ReliabilityOutcome, ValidationError } from "../types.js";
+import type { PlatformPaths } from "../platform/types.js";
+import { appendReliabilityRecord } from "../storage/reliability-metrics.js";
+
+export interface StructuredParseResult<T> {
+  output: T | null;
+  error: string | null;
+}
+
+export interface StructuredOutputRunOptions<T> {
+  cwd: string;
+  prompt: string;
+  /**
+   * Prompt-visible schema text, produced by schema-text.ts. Injected into
+   * the retry prompt so the model can self-correct on invalid output.
+   */
+  schema: string;
+  /**
+   * Parse raw model text into T. Implementations typically delegate to
+   * `parseStructuredOutput(raw, SomeSchema)`.
+   */
+  parse: (raw: string) => StructuredParseResult<T>;
+  model?: string;
+  thinkingLevel?: string | null;
+  agentId?: string;
+  agentDisplayName?: string;
+  timeoutMs?: number;
+  /** Default: 3. Clamped to >=1 at runtime. */
+  maxAttempts?: number;
+  /**
+   * Optional reliability reporter. When supplied, the runner appends one
+   * ReliabilityRecord per final outcome (ok / retry-exhausted / agent-error)
+   * to the cwd-local reliability events log. No-op when omitted.
+   */
+  reliability?: ReliabilityReporter;
+}
+
+/**
+ * Describes how to report the outcome of a runWithOutputValidation call to
+ * the per-cwd reliability log. Every AI-heavy production call site supplies
+ * one of these; the helper itself emits exactly one record per final outcome.
+ *
+ * Emission is best-effort: failures are swallowed (metrics must never crash
+ * the workflow they observe).
+ */
+export interface ReliabilityReporter {
+  paths: PlatformPaths;
+  cwd: string;
+  /** Logical command name (e.g. "plan", "commit", "review"). */
+  command: string;
+  /** Optional sub-operation (e.g. "commit-plan", "note-polish"). */
+  operation?: string;
+}
+
+export type StructuredOutputResult<T> =
+  | {
+      status: "ok";
+      output: T;
+      rawOutput: string;
+      attempts: number;
+    }
+  | {
+      status: "blocked";
+      error: string;
+      rawOutputs: string[];
+      attempts: number;
+    };
+
+function truncateForPrompt(text: string, maxLength = 1200): string {
+  const normalized = text.trim();
+  if (normalized.length <= maxLength) {
+    return normalized;
+  }
+  return `${normalized.slice(0, maxLength - 1)}…`;
+}
+
+function normalizeErrorPath(path: string): string {
+  return path.replace(/^\//, "").replace(/\//g, ".") || "(root)";
+}
+
+/**
+ * Collect schema validation errors for a TypeBox schema in a stable
+ * {path, message} shape. Used by parseStructuredOutput and by any code that
+ * needs to format schema-check failures for humans or prompts.
+ */
+export function collectValidationErrors(schema: TSchema, data: unknown): ValidationError[] {
+  return [...Value.Errors(schema, data)].map((error) => ({
+    path: normalizeErrorPath(error.path),
+    message: error.message,
+  }));
+}
+
+/**
+ * Render validation errors as `path: message` lines.
+ */
+export function formatValidationErrors(errors: ValidationError[]): string[] {
+  return errors.map((error) => `${error.path}: ${error.message}`);
+}
+
+/**
+ * Strip markdown fences, JSON-parse, and schema-check against a TypeBox.
+ * Returns {output: T, error: null} on success; {output: null, error: string}
+ * on failure with a human-readable error suitable for retry prompts.
+ */
+export function parseStructuredOutput<T>(raw: string, schema: TSchema): StructuredParseResult<T> {
+  let parsed: unknown;
+
+  try {
+    parsed = JSON.parse(stripMarkdownCodeFence(raw));
+  } catch (error) {
+    return {
+      output: null,
+      error: error instanceof Error ? `Invalid JSON: ${error.message}` : "Invalid JSON.",
+    };
+  }
+
+  if (!Value.Check(schema, parsed)) {
+    const errors = formatValidationErrors(collectValidationErrors(schema, parsed));
+    return {
+      output: null,
+      error: errors.length > 0 ? errors.join("; ") : "Output does not match the required schema.",
+    };
+  }
+
+  return {
+    output: parsed as T,
+    error: null,
+  };
+}
+
+/**
+ * Run a schema-backed AI session with retry-on-invalid-output. On every
+ * retry, the original prompt is wrapped with the invalid-output-retry
+ * template so the model sees the validation error and its previous output.
+ *
+ * Returns `status: "ok"` on first successful schema-valid parse. Returns
+ * `status: "blocked"` when maxAttempts exhausts, when the underlying agent
+ * session errors, or when no final assistant text is produced.
+ */
+export async function runWithOutputValidation<T>(
+  createAgentSession: GateExecutionContext["createAgentSession"],
+  options: StructuredOutputRunOptions<T>,
+): Promise<StructuredOutputResult<T>> {
+  const maxAttempts = Math.max(1, options.maxAttempts ?? 3);
+  const rawOutputs: string[] = [];
+  let prompt = options.prompt;
+  let attempt = 0;
+
+  try {
+    for (attempt = 1; attempt <= maxAttempts; attempt += 1) {
+      const result = await runStructuredAgentSession(createAgentSession, {
+        cwd: options.cwd,
+        prompt,
+        model: options.model,
+        thinkingLevel: options.thinkingLevel ?? null,
+        agentId: options.agentId,
+        agentDisplayName: options.agentDisplayName,
+        timeoutMs: options.timeoutMs,
+      });
+
+      if (result.status !== "ok") {
+        emitReliabilityOutcome(options.reliability, "agent-error", attempt, result.error);
+        return {
+          status: "blocked",
+          error: result.error,
+          rawOutputs,
+          attempts: attempt,
+        };
+      }
+
+      rawOutputs.push(result.finalText);
+      const parsed = options.parse(result.finalText);
+      if (parsed.output) {
+        emitReliabilityOutcome(options.reliability, "ok", attempt);
+        return {
+          status: "ok",
+          output: parsed.output,
+          rawOutput: result.finalText,
+          attempts: attempt,
+        };
+      }
+
+      if (attempt === maxAttempts) {
+        const reason = parsed.error ?? "Agent output was invalid.";
+        emitReliabilityOutcome(options.reliability, "retry-exhausted", attempt, reason);
+        return {
+          status: "blocked",
+          error: reason,
+          rawOutputs,
+          attempts: attempt,
+        };
+      }
+
+      prompt = renderTemplate(invalidOutputRetryPrompt, {
+        prompt: options.prompt,
+        error: parsed.error ?? "Agent output was invalid.",
+        previousOutput: truncateForPrompt(result.finalText),
+        schema: options.schema,
+      });
+    }
+  } catch (error) {
+    // createAgentSession (or anything else) threw before completing a final
+    // outcome — record as agent-error and re-raise so callers keep their
+    // existing error semantics.
+    const reason = error instanceof Error ? error.message : String(error);
+    emitReliabilityOutcome(
+      options.reliability,
+      "agent-error",
+      Math.max(1, attempt),
+      reason,
+    );
+    throw error;
+  }
+
+  // Fallthrough: loop exhausted without a final outcome. Treat as retry-
+  // exhausted for the record, and return blocked so callers see the same
+  // shape they used to.
+  emitReliabilityOutcome(
+    options.reliability,
+    "retry-exhausted",
+    maxAttempts,
+    "Output validation exhausted without producing a valid result.",
+  );
+  return {
+    status: "blocked",
+    error: "Output validation exhausted without producing a valid result.",
+    rawOutputs,
+    attempts: maxAttempts,
+  };
+}
+
+function emitReliabilityOutcome(
+  reporter: ReliabilityReporter | undefined,
+  outcome: ReliabilityOutcome,
+  attempts: number,
+  reason?: string,
+): void {
+  if (!reporter) return;
+  try {
+    appendReliabilityRecord(reporter.paths, reporter.cwd, {
+      ts: new Date().toISOString(),
+      command: reporter.command,
+      operation: reporter.operation,
+      outcome,
+      attempts,
+      reason,
+      cwd: reporter.cwd,
+    });
+  } catch {
+    // Defensive: appendReliabilityRecord already swallows its own errors,
+    // but we double-guard so a reporter misconfiguration never crashes the
+    // workflow it observes.
+  }
+}

package/src/ai/template.ts

@@ -0,0 +1,27 @@
+// src/ai/template.ts
+//
+// Generic Handlebars-based template renderer. Used by every AI prompt that
+// needs structured interpolation. Lives under src/ai/ because it is generic
+// and was previously duplicated under src/review/template.ts.
+//
+// Helpers:
+//   - {{json value}}       → JSON.stringify(value, null, 2)
+//   - {{joinLines lines}}  → array joined by newline
+//
+// Add new helpers here only when at least two unrelated callers need them.
+
+import Handlebars from "handlebars";
+
+const handlebars = Handlebars.create();
+
+handlebars.registerHelper("json", (value: unknown): string => JSON.stringify(value, null, 2));
+handlebars.registerHelper("joinLines", (value: unknown): string => {
+  if (!Array.isArray(value)) {
+    return "";
+  }
+  return value.join("\n");
+});
+
+export function renderTemplate(template: string, context: Record<string, unknown> = {}): string {
+  return handlebars.compile(template, { noEscape: true })(context);
+}

package/src/bootstrap.ts

@@ -19,18 +19,37 @@ import { executeManagerAction } from "./mcp/manager-tool.js";
 import { registerFixPrCommand } from "./commands/fix-pr.js";
 import { registerContextCommand, handleContext } from "./commands/context.js";
 import { registerOptimizeContextCommand, handleOptimizeContext } from "./commands/optimize-context.js";
+import { registerClearCommand, handleClear } from "./commands/clear.js";
 import { registerCommitCommand, handleCommit } from "./commands/commit.js";
 import { registerGenerateCommand } from "./commands/generate.js";
 import { registerAgentsCommand, handleAgents } from "./commands/agents.js";
+import { registerMemoryCommand, handleMemory } from "./commands/memory.js";
+import { registerUltraplanCommand, handleUltraplan } from "./commands/ultraplan.js";
+import { registerHarnessCommand, handleHarness } from "./harness/command.js";
+import { registerHarnessPipelineTools } from "./harness/tools.js";
+import { registerHarnessHooks } from "./harness/hooks/register.js";
 import { loadConfig } from "./config/loader.js";
 import { registerContextModeHooks } from "./context-mode/hooks.js";
 import { loadMcpRegistry } from "./mcp/config.js";
 import { McpcClient } from "./mcp/mcpc.js";
-import { parseTags, computeActiveServers } from "./mcp/activation.js";
+import { parseTags } from "./mcp/activation.js";
 import { initializeMcpServers, shutdownMcpServers } from "./mcp/lifecycle.js";
 import { registerPlanApprovalHook } from "./planning/approval-flow.js";
 import { registerPlanningSystemPromptHook } from "./planning/system-prompt.js";
-import { registerPlanningAskTool } from "./planning/planning-ask-tool.js";
+import { registerPlanningAskTool, registerPlanningAskToolGuard } from "./planning/planning-ask-tool.js";
+import { registerUiDesignCommand } from "./commands/ui-design.js";
+import { registerUiDesignSystemPromptHook } from "./ui-design/system-prompt.js";
+import {
+  registerUiDesignApprovalHook,
+  registerUiDesignToolGuard,
+  stopActiveUiDesignSession,
+} from "./ui-design/session.js";
+import { registerUltraPlanRuntimeTools } from "./ultraplan/execution/runtime-tools.js";
+import { registerUltraPlanAuthoringTool } from "./ultraplan/authoring-tool.js";
+import { registerUltraPlanAuthoringPipelineTools } from "./ultraplan/authoring/authoring-tools.js";
+import { registerActiveToolController } from "./tool-catalog/active-tool-controller.js";
+import { registerMempalaceHooks } from "./mempalace/hooks.js";
+import { registerMempalaceTool } from "./mempalace/tool.js";
 
 // TUI-only commands — intercepted at the input level to prevent
 // message submission and "Working..." indicator
@@ -38,17 +57,21 @@ const TUI_COMMANDS: Record<string, (platform: Platform, ctx: any, args?: string)
   "supi": (platform, ctx) => handleSupi(platform, ctx),
   "supi:config": (platform, ctx) => handleConfig(platform, ctx),
   "supi:status": (platform, ctx) => handleStatus(platform, ctx),
-  "supi:review": (platform, ctx) => handleAiReview(platform, ctx),
+  "supi:review": (platform, ctx, args) => handleAiReview(platform, ctx, args),
   "supi:update": (platform, ctx) => handleUpdate(platform, ctx),
   "supi:doctor": (platform, ctx) => handleDoctor(platform, ctx),
   "supi:mcp": (platform, ctx) => handleMcp(platform, ctx),
   "supi:model": (platform, ctx) => handleModel(platform, ctx),
   "supi:context": (platform, ctx) => handleContext(platform, ctx),
-  "supi:optimize-context": (platform, ctx) => handleOptimizeContext(platform, ctx),
+  "supi:optimize-context": (platform, ctx, args) => handleOptimizeContext(platform, ctx, args),
+  "supi:clear": (platform, ctx, args) => handleClear(platform, ctx, args),
   "supi:commit": (platform, ctx, args) => handleCommit(platform, ctx, args),
   "supi:release": (platform, ctx, args) => handleRelease(platform, ctx, args),
   "supi:checks": (platform, ctx, args) => handleChecksCommand(platform, ctx, args),
   "supi:agents": (platform, ctx, args) => handleAgents(platform, ctx, args),
+  "supi:ultraplan": (platform, ctx, args) => handleUltraplan(platform, ctx, args),
+  "supi:harness": (platform, ctx, args) => { void handleHarness(platform, ctx, args); },
+  "supi:memory": (platform, ctx, args) => handleMemory(platform, ctx, args),
 };
 
 let pendingTags: string[] = [];
@@ -80,15 +103,29 @@ export function bootstrap(platform: Platform): void {
   registerModelCommand(platform);
   registerContextCommand(platform);
   registerOptimizeContextCommand(platform);
+  registerClearCommand(platform);
   registerCommitCommand(platform);
   registerGenerateCommand(platform);
   registerAgentsCommand(platform);
+  registerUiDesignCommand(platform);
+  registerUltraplanCommand(platform);
+  registerHarnessCommand(platform);
+  registerMemoryCommand(platform);
 
 
+  registerUltraPlanRuntimeTools(platform);
+  registerUltraPlanAuthoringTool(platform);
+  registerUltraPlanAuthoringPipelineTools(platform);
+  registerHarnessPipelineTools(platform);
+
   // Register plan approval flow (agent_end hook for plan approval UI)
   registerPlanApprovalHook(platform);
   registerPlanningAskTool(platform);
+  registerPlanningAskToolGuard(platform);
 
+  // Register ui-design approval flow + runtime write-scope guard
+  registerUiDesignApprovalHook(platform);
+  registerUiDesignToolGuard(platform);
 
   // Intercept TUI-only commands at the input level — this runs BEFORE
   // message submission, so no chat message appears and no "Working..." indicator
@@ -120,35 +157,28 @@ export function bootstrap(platform: Platform): void {
 
   // Context-mode integration
   const config = loadConfig(platform.paths, process.cwd());
+  registerActiveToolController(platform, config, {
+    loadMcpRegistryForCwd: (cwd: string) => loadMcpRegistry(platform.paths, cwd),
+    consumePendingTags: () => {
+      const tags = pendingTags;
+      pendingTags = [];
+      return tags;
+    },
+  });
   registerContextModeHooks(platform, config);
+  registerMempalaceTool(platform, config);
+  registerMempalaceHooks(platform, config);
 
-
-  // Planning-mode prompt override — registered after context-mode so it wins
+  // Planning-mode prompt override — registered after context-mode and MemPalace so it wins
   // when /supi:plan is active and otherwise stays dormant.
   registerPlanningSystemPromptHook(platform);
+  registerUiDesignSystemPromptHook(platform);
 
-  // MCP per-turn activation
-  platform.on("before_agent_start", async (event, ctx) => {
-    const registry = loadMcpRegistry(platform.paths, ctx.cwd);
-    if (Object.keys(registry.servers).length === 0) {
-      pendingTags = [];
-      return;
-    }
+  // Register harness anti-slop hooks (gated by per-repo marker file at session start).
+  // Idempotent — safe to call once per process. The hooks themselves no-op on every
+  // event when the marker is missing, so other repos see no behavior change.
+  registerHarnessHooks(platform);
 
-    const message = typeof event.message?.content === "string" ? event.message.content : "";
-    const active = computeActiveServers(registry.servers, message, pendingTags);
-
-    const activeToolNames = active.map((name) => `mcpc_${name}`);
-    activeToolNames.push("mcpc_manager");
-
-    if (platform.setActiveTools) {
-      const currentTools = platform.getActiveTools();
-      const nonMcpTools = currentTools.filter((t: string) => !t.startsWith("mcpc_"));
-      platform.setActiveTools([...nonMcpTools, ...activeToolNames]);
-    }
-
-    pendingTags = [];
-  });
 
   // Session start
   platform.on("session_start", async (_event, ctx) => {
@@ -159,6 +189,9 @@ export function bootstrap(platform: Platform): void {
       setActiveVisualSessionDir(null);
     }
 
+    // Clean up any leftover ui-design companion from a previous session
+    await stopActiveUiDesignSession();
+
     // Clear leftover model-override status from a previous session.
     // OMP's StatusLine never clears hook statuses on /new, so extensions must do it.
     ctx.ui?.setStatus?.("supi-model", undefined);
@@ -200,8 +233,10 @@ export function bootstrap(platform: Platform): void {
       });
   });
 
-  // MCP session shutdown
+  // Session shutdown
   platform.on("session_shutdown", async (_event, ctx) => {
+    await stopActiveUiDesignSession();
+
     const mcpConfig = loadConfig(platform.paths, ctx.cwd ?? process.cwd());
     if (!mcpConfig.mcp?.closeSessionsOnExit) return;