aiwcli 0.13.8 → 0.15.1

package/dist/templates/_shared/lib-ts/agent-exec/execution-backend.ts

@@ -0,0 +1,50 @@
+/**
+ * Execution backend interfaces for CLI agent subprocess invocations.
+ * Decouples agent logic (prompt building, output parsing) from execution
+ * strategy (headless subprocess vs tmux pane).
+ */
+
+// ---------------------------------------------------------------------------
+// Execution Request / Result
+// ---------------------------------------------------------------------------
+
+/** Request to execute a CLI subprocess. */
+export interface ExecutionRequest {
+  cliPath: string;
+  args: string[];
+  input: string;
+  env: Record<string, string | undefined>;
+  timeoutMs: number;
+  /** If set, read output from this file instead of stdout (Codex pattern). */
+  outputFilePath?: string;
+  maxBuffer?: number;
+  shell?: boolean;
+}
+
+/** Result from a CLI subprocess execution. */
+export interface ExecutionResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+  killed: boolean;
+  signal: string | null;
+}
+
+// ---------------------------------------------------------------------------
+// Execution Backend
+// ---------------------------------------------------------------------------
+
+/** Strategy interface for running CLI agent subprocesses. */
+export interface ExecutionBackend {
+  execute(request: ExecutionRequest): Promise<ExecutionResult>;
+}
+
+// ---------------------------------------------------------------------------
+// Debug Logger
+// ---------------------------------------------------------------------------
+
+/** Injectable debug logger for agents running in _shared context. */
+export interface AgentDebugLogger {
+  log(contextPath: string, sessionName: string, component: string, message: string, data?: unknown): void;
+  raw(contextPath: string, sessionName: string, component: string, label: string, raw: string): void;
+}

package/dist/templates/_shared/lib-ts/agent-exec/index.ts

@@ -0,0 +1,6 @@
+export { BaseCliAgent, type AgentExecutionConfig } from "./base-agent.js";
+export type { ExecutionBackend, ExecutionRequest, ExecutionResult, AgentDebugLogger } from "./execution-backend.js";
+export { HeadlessBackend } from "./backends/headless.js";
+export { TmuxBackend } from "./backends/tmux.js";
+export { parseJsonObjectMaybe, parseStructuredOutput } from "./structured-output.js";
+export type { StructuredOutputParseOptions } from "./structured-output.js";

package/dist/templates/_shared/lib-ts/agent-exec/structured-output.ts

@@ -0,0 +1,166 @@
+/**
+ * Shared structured output parsing utilities for CLI-based agents.
+ * Supports Claude/Codex-style envelopes and heuristic JSON extraction.
+ */
+
+import { logDebug, logError, logWarn } from "../base/logger.js";
+
+export interface StructuredOutputParseOptions {
+  requireFields?: string[];
+  loggerTag?: string;
+}
+
+const DEFAULT_LOG_TAG = "structured_output";
+
+function getTag(options?: StructuredOutputParseOptions): string {
+  return options?.loggerTag ?? DEFAULT_LOG_TAG;
+}
+
+function validateRequiredFields(
+  obj: Record<string, unknown>,
+  parseMethod: "strict" | "heuristic",
+  options?: StructuredOutputParseOptions,
+): Record<string, unknown> | null {
+  const required = options?.requireFields;
+  if (!required || required.length === 0) return obj;
+
+  const missing = required.filter((field) => !(field in obj) || obj[field] === undefined || obj[field] === null);
+  if (missing.length === 0) return obj;
+
+  const tag = getTag(options);
+  logWarn(tag, `Parsed JSON (${parseMethod}) missing required fields: ${JSON.stringify(missing)}`);
+  logDebug(tag, `Parsed keys: ${JSON.stringify(Object.keys(obj))}`);
+
+  // Heuristic extraction often grabs the wrong JSON blob. Reject in that case.
+  if (parseMethod === "heuristic") {
+    return null;
+  }
+  return obj;
+}
+
+/**
+ * Parse a JSON object from text using strict parse first, then heuristic
+ * extraction of the first object-like block.
+ */
+export function parseJsonObjectMaybe(
+  text: string,
+  options?: StructuredOutputParseOptions,
+): Record<string, unknown> | null {
+  const tag = getTag(options);
+  const trimmed = text.trim();
+  if (!trimmed) return null;
+
+  // Strict parse first.
+  try {
+    const parsed: unknown = JSON.parse(trimmed);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      return validateRequiredFields(parsed as Record<string, unknown>, "strict", options);
+    }
+  } catch {
+    // Fall through to heuristic extraction.
+  }
+
+  // Heuristic parse: extract the first object-like block.
+  const start = trimmed.indexOf("{");
+  const end = trimmed.lastIndexOf("}");
+  if (start === -1 || end === -1 || end <= start) return null;
+
+  const candidate = trimmed.slice(start, end + 1);
+  try {
+    const parsed: unknown = JSON.parse(candidate);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      logDebug(tag, `Used heuristic JSON extraction (chars ${start}-${end})`);
+      return validateRequiredFields(parsed as Record<string, unknown>, "heuristic", options);
+    }
+  } catch {
+    logDebug(tag, `Heuristic JSON extraction failed (chars ${start}-${end})`);
+  }
+
+  return null;
+}
+
+function parseAssistantEnvelope(
+  envelope: Record<string, unknown>,
+  options?: StructuredOutputParseOptions,
+): Record<string, unknown> | null {
+  const tag = getTag(options);
+  const message = envelope.message;
+  if (!message || typeof message !== "object") return null;
+
+  const content = (message as Record<string, unknown>).content;
+  if (!Array.isArray(content)) return null;
+
+  for (const item of content) {
+    if (!item || typeof item !== "object") continue;
+    const toolUse = item as Record<string, unknown>;
+    if (toolUse.name !== "StructuredOutput") continue;
+    if (toolUse.input && typeof toolUse.input === "object" && !Array.isArray(toolUse.input)) {
+      logDebug(tag, "Found StructuredOutput in assistant envelope");
+      return toolUse.input as Record<string, unknown>;
+    }
+  }
+  return null;
+}
+
+/**
+ * Parse structured output across known CLI envelope formats.
+ * Falls back to generic JSON extraction when no recognized envelope exists.
+ */
+export function parseStructuredOutput(
+  raw: string,
+  options?: StructuredOutputParseOptions,
+): Record<string, unknown> | null {
+  const tag = getTag(options);
+
+  try {
+    const parsed: unknown = JSON.parse(raw);
+
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      const obj = parsed as Record<string, unknown>;
+
+      if (obj.structured_output && typeof obj.structured_output === "object" && !Array.isArray(obj.structured_output)) {
+        logDebug(tag, "Found structured_output in root object");
+        return validateRequiredFields(obj.structured_output as Record<string, unknown>, "strict", options);
+      }
+
+      const assistantResult = parseAssistantEnvelope(obj, options);
+      if (assistantResult) return assistantResult;
+
+      // Session result envelope (no structured output tool call).
+      if (obj.type === "result" || ("duration_ms" in obj && "session_id" in obj)) {
+        if (obj.is_error === true || (Array.isArray(obj.errors) && obj.errors.length > 0)) {
+          logWarn(tag, `CLI returned error envelope: ${JSON.stringify(obj.errors ?? "is_error=true")}`);
+          return null;
+        }
+
+        if (typeof obj.result === "string" && obj.result.trim().length > 0) {
+          logDebug(tag, "Found text result in session envelope, attempting JSON extraction");
+          const extracted = parseJsonObjectMaybe(obj.result, options);
+          if (extracted) return extracted;
+          logWarn(tag, "Session envelope result contained no extractable JSON object");
+        }
+        return null;
+      }
+    } else if (Array.isArray(parsed)) {
+      for (let i = 0; i < parsed.length; i++) {
+        const event = parsed[i];
+        if (!event || typeof event !== "object") continue;
+        const eventObj = event as Record<string, unknown>;
+        const assistantResult = parseAssistantEnvelope(eventObj, options);
+        if (assistantResult) {
+          logDebug(tag, `Found StructuredOutput in event[${i}]`);
+          return assistantResult;
+        }
+      }
+    }
+  } catch (error: unknown) {
+    if (error instanceof SyntaxError) {
+      logWarn(tag, `JSON decode error: ${error.message}`);
+    } else {
+      logError(tag, `Unexpected parse error: ${error}`);
+    }
+  }
+
+  logDebug(tag, "No structured envelope found, falling back to generic JSON extraction");
+  return parseJsonObjectMaybe(raw, options);
+}

package/dist/templates/_shared/lib-ts/base/cli-args.ts

@@ -0,0 +1,287 @@
+/**
+ * Centralized CLI argument construction for agent subprocesses.
+ * Single source of truth for Claude CLI and Codex CLI flag patterns,
+ * platform quoting, model tier resolution, and env setup.
+ */
+
+import type { PreflightCommandConfig } from "./preflight.js";
+import { getInternalSubprocessEnv, shellQuoteWin } from "./subprocess-utils.js";
+import { CLAUDE_MODELS, CODEX_MODELS } from "./models.js";
+
+export { CLAUDE_MODELS, CODEX_MODELS };
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type InvocationMode = "structured" | "print" | "preflight";
+export type CliProvider = "claude" | "codex";
+export type ModelTier = "fast" | "standard" | "smart";
+
+const VALID_SANDBOXES = ["read-only", "workspace-write", "danger-full-access"] as const;
+export type CodexSandbox = (typeof VALID_SANDBOXES)[number];
+
+export function isCodexSandbox(value: string): value is CodexSandbox {
+  return (VALID_SANDBOXES as readonly string[]).includes(value);
+}
+
+export interface CliArgSpec {
+  provider: CliProvider;
+  model: string | ModelTier;
+  mode: InvocationMode;
+  jsonSchema?: Record<string, unknown>;
+  maxTurns?: number;
+  systemPrompt?: string;
+  sandbox?: CodexSandbox;
+  outputSchemaPath?: string;
+  outputFilePath?: string;
+  extraArgs?: string[];
+}
+
+/** Codex REPL spec — model optional (Codex uses its default when omitted). */
+export interface CodexReplSpec {
+  provider: "codex";
+  mode: "repl";
+  model?: string | ModelTier;
+  sandbox?: CodexSandbox;
+  yolo?: boolean;
+  extraArgs?: string[];
+}
+
+export interface CliInvocation {
+  cliName: string;
+  args: string[];
+  needsShell: boolean;
+  env: Record<string, string | undefined>;
+}
+
+// ---------------------------------------------------------------------------
+// Model Tier Resolution
+// ---------------------------------------------------------------------------
+
+export const MODEL_TIERS: Record<ModelTier, string> = {
+  fast: CLAUDE_MODELS.haiku,
+  standard: CLAUDE_MODELS.sonnet,
+  smart: CLAUDE_MODELS.opus,
+};
+
+export const CODEX_MODEL_TIERS: Record<ModelTier, string> = {
+  fast: CODEX_MODELS.spark,
+  standard: CODEX_MODELS.codex,
+  smart: CODEX_MODELS.codex,
+};
+
+export const TIER_TIMEOUTS: Record<ModelTier, number> = {
+  fast: 15,
+  standard: 30,
+  smart: 90,
+};
+
+export function isModelTier(value: string): value is ModelTier {
+  return value in MODEL_TIERS;
+}
+
+export function resolveModel(model: string | ModelTier): string {
+  if (isModelTier(model)) return MODEL_TIERS[model];
+  return model;
+}
+
+export function resolveModelForProvider(
+  model: string | ModelTier,
+  provider: CliProvider,
+): string {
+  if (!isModelTier(model)) return model;
+  return provider === "codex" ? CODEX_MODEL_TIERS[model] : MODEL_TIERS[model];
+}
+
+export function getTierTimeout(tier: ModelTier): number {
+  return TIER_TIMEOUTS[tier];
+}
+
+/** Resolve a Codex model: tier resolution + pass-through. No aliases (those are skill-specific). */
+export function resolveCodexModel(input: string): string {
+  if (isModelTier(input)) return CODEX_MODEL_TIERS[input as ModelTier];
+  return input;
+}
+
+// ---------------------------------------------------------------------------
+// Core Builder
+// ---------------------------------------------------------------------------
+
+export function buildCliInvocation(spec: CliArgSpec | CodexReplSpec): CliInvocation {
+  const env = getInternalSubprocessEnv();
+  delete env.ANTHROPIC_API_KEY;
+
+  if (spec.mode === "repl") {
+    const resolvedModel = spec.model ? resolveModelForProvider(spec.model, spec.provider) : undefined;
+    return buildCodexReplInvocation(spec, resolvedModel, env);
+  }
+
+  const resolvedModel = resolveModelForProvider((spec as CliArgSpec).model, spec.provider);
+  const isWin = process.platform === "win32";
+  const empty = isWin ? '""' : "";
+
+  if (spec.provider === "claude") {
+    return buildClaudeInvocation(spec as CliArgSpec, resolvedModel, isWin, empty, env);
+  }
+
+  return buildCodexInvocation(spec as CliArgSpec, resolvedModel, env);
+}
+
+function buildClaudeInvocation(
+  spec: CliArgSpec,
+  model: string,
+  isWin: boolean,
+  empty: string,
+  env: Record<string, string | undefined>,
+): CliInvocation {
+  const args: string[] = [];
+
+  args.push("--model", model);
+
+  if (spec.mode === "print") {
+    args.push("--print");
+  } else {
+    // structured and preflight both use json output
+    args.push("--output-format", "json");
+
+    if (spec.jsonSchema) {
+      args.push("--json-schema", shellQuoteWin(JSON.stringify(spec.jsonSchema)));
+    }
+
+    const maxTurns = spec.mode === "preflight" ? 1 : (spec.maxTurns ?? 3);
+    args.push("--max-turns", String(maxTurns));
+  }
+
+  args.push("--setting-sources", empty);
+  args.push("-p");
+  args.push("--no-session-persistence");
+
+  if (spec.systemPrompt) {
+    args.push("--system-prompt", shellQuoteWin(spec.systemPrompt));
+  }
+
+  if (spec.extraArgs) {
+    args.push(...spec.extraArgs);
+  }
+
+  return { cliName: "claude", args, needsShell: isWin, env };
+}
+
+function buildCodexInvocation(
+  spec: CliArgSpec,
+  model: string,
+  env: Record<string, string | undefined>,
+): CliInvocation {
+  const args: string[] = ["exec"];
+
+  if (spec.sandbox) {
+    args.push("--sandbox", spec.sandbox);
+  }
+
+  args.push("--model", model);
+
+  if (spec.outputSchemaPath) {
+    args.push("--output-schema", spec.outputSchemaPath);
+  }
+
+  if (spec.outputFilePath) {
+    args.push("-o", spec.outputFilePath);
+  }
+
+  args.push("-");
+
+  if (spec.extraArgs) {
+    args.push(...spec.extraArgs);
+  }
+
+  return { cliName: "codex", args, needsShell: false, env };
+}
+
+function buildCodexReplInvocation(
+  spec: CodexReplSpec,
+  model: string | undefined,
+  env: Record<string, string | undefined>,
+): CliInvocation {
+  const args: string[] = [];
+  if (spec.yolo) args.push("--dangerously-bypass-approvals-and-sandbox");
+  if (spec.sandbox) args.push("--sandbox", spec.sandbox);
+  if (model) args.push("--model", model);
+  if (spec.extraArgs) args.push(...spec.extraArgs);
+  return { cliName: "codex", args, needsShell: false, env };
+}
+
+// ---------------------------------------------------------------------------
+// Convenience Presets
+// ---------------------------------------------------------------------------
+
+export function preflightSpec(provider: CliProvider, model: string): CliArgSpec {
+  if (provider === "codex") {
+    return {
+      provider: "codex",
+      model,
+      mode: "preflight",
+      sandbox: "read-only",
+    };
+  }
+  return {
+    provider: "claude",
+    model,
+    mode: "preflight",
+  };
+}
+
+export function inferenceSpec(model: string | ModelTier): CliArgSpec {
+  return {
+    provider: "claude",
+    model,
+    mode: "print",
+  };
+}
+
+export function reviewSpec(
+  provider: CliProvider,
+  model: string,
+  schema: Record<string, unknown>,
+  systemPrompt?: string,
+): CliArgSpec {
+  if (provider === "codex") {
+    return {
+      provider: "codex",
+      model,
+      mode: "structured",
+      sandbox: "read-only",
+    };
+  }
+  return {
+    provider: "claude",
+    model,
+    mode: "structured",
+    jsonSchema: schema,
+    systemPrompt,
+  };
+}
+
+export function codexReplSpec(
+  model?: string,
+  sandbox?: CodexSandbox,
+  yolo?: boolean,
+): CodexReplSpec {
+  return {
+    provider: "codex",
+    mode: "repl",
+    model,
+    sandbox,
+    yolo,
+  };
+}
+
+export function preflightCommandConfig(provider: CliProvider): PreflightCommandConfig {
+  const input = "Respond with exactly: ok";
+
+  return {
+    cliName: provider === "claude" ? "claude" : "codex",
+    buildArgs: (model: string) => buildCliInvocation(preflightSpec(provider, model)).args,
+    input,
+  };
+}

package/dist/templates/_shared/lib-ts/base/inference.ts

@@ -9,20 +9,18 @@ import { execFileSync } from "node:child_process";
 import { logDebug, logWarn } from "./logger.js";
 import { STOP_WORDS } from "./stop-words.js";
 import type { InferenceResult } from "../types.js";
-import { execFileAsync, getInternalSubprocessEnv, shellQuoteWin } from "./subprocess-utils.js";
-
-// Model configurations §6.1
-const MODELS: Record<string, string> = {
-  fast: "claude-haiku-4-5-20251001",
-  standard: "claude-sonnet-4-6",
-  smart: "claude-opus-4-6",
-};
-
-const TIMEOUTS: Record<string, number> = {
-  fast: 15,
-  standard: 30,
-  smart: 90,
-};
+import { execFileAsync } from "./subprocess-utils.js";
+import {
+  buildCliInvocation,
+  inferenceSpec,
+  isModelTier,
+  resolveModel,
+  getTierTimeout,
+  TIER_TIMEOUTS,
+} from "./cli-args.js";
+import { CODEX_MODELS } from "./models.js";
+
+const CONTEXT_ID_PRIMARY_MODEL = CODEX_MODELS.spark;
 
 /**
  * Run inference using the claude CLI.
@@ -33,38 +31,33 @@ export function inference(
   userPrompt: string,
   level = "fast",
   timeout?: number,
+  options?: { model?: string },
 ): InferenceResult {
   const startTime = Date.now();
-  const model = MODELS[level] ?? MODELS.fast;
-  const timeoutSec = timeout ?? TIMEOUTS[level] ?? TIMEOUTS.fast;
+  const modelInput = options?.model ?? level;
+  const model = resolveModel(modelInput);
+  const timeoutSec = timeout ?? (isModelTier(modelInput) ? getTierTimeout(modelInput) : TIER_TIMEOUTS.fast);
   const fullPrompt = `${systemPrompt}\n\n${userPrompt}`;
 
-  // Remove ANTHROPIC_API_KEY to force subscription auth
-  const env = { ...process.env };
-  delete env.ANTHROPIC_API_KEY;
+  const invocation = buildCliInvocation(inferenceSpec(modelInput));
+  const isWin = invocation.needsShell;
 
-  try {
-    const isWin = process.platform === "win32";
-
-    // On Windows with shell:true, Node.js sets windowsVerbatimArguments —
-    // args are joined with spaces, NOT individually quoted. We must manually
-    // wrap multi-word/special-char args in "..." for cmd.exe parsing.
-    // Inside double quotes: "" = literal ", and |&<> are safe.
-    const empty = isWin ? '""' : "";
-    let promptArg = fullPrompt;
-    if (isWin) {
-      promptArg = '"' + fullPrompt.replaceAll(/\r?\n/g, " ").replaceAll('"', '""') + '"';
-    }
+  // Prompt arg needs Windows quoting when using shell mode
+  let promptArg = fullPrompt;
+  if (isWin) {
+    promptArg = '"' + fullPrompt.replaceAll(/\r?\n/g, " ").replaceAll('"', '""') + '"';
+  }
 
+  try {
     const stdout = execFileSync(
-      "claude",
-      ["--model", model, "--print", "--setting-sources", empty, "-p", "--no-session-persistence", promptArg],
+      invocation.cliName,
+      [...invocation.args, promptArg],
       {
         timeout: timeoutSec * 1000,
-        env,
+        env: invocation.env,
         encoding: "utf-8",
         stdio: ["pipe", "pipe", "pipe"],
-        shell: isWin, // Windows needs shell for .cmd resolution
+        shell: isWin,
       },
     );
 
@@ -189,7 +182,7 @@ Respond with ONLY a JSON object: {"slug": "your 8-12 word phrase here"}`;
 
 /**
  * Generate a 5-12 word context ID slug from a user prompt.
- * Uses Haiku (fast tier) for low latency.
+ * Uses 5.3 Codex Spark first, then falls back to current fast tier for resilience.
  * See SPEC.md §6.3
  */
 export function generateContextIdSlug(
@@ -198,7 +191,20 @@ export function generateContextIdSlug(
 ): string | null {
   const truncated = prompt.slice(0, 500);
 
-  const result = inference(CONTEXT_ID_SLUG_PROMPT, truncated, "fast", timeout);
+  const sparkResult = inference(
+    CONTEXT_ID_SLUG_PROMPT,
+    truncated,
+    "fast",
+    timeout,
+    { model: CONTEXT_ID_PRIMARY_MODEL },
+  );
+  if (!sparkResult.success || !sparkResult.output) {
+    logWarn(
+      "inference",
+      `Context ID slug Spark (${CONTEXT_ID_PRIMARY_MODEL}) failed or returned empty output. Falling back to ${resolveModel("fast")}`,
+    );
+  }
+  const result = sparkResult.success && sparkResult.output ? sparkResult : inference(CONTEXT_ID_SLUG_PROMPT, truncated, "fast", timeout);
 
   if (!result.success || !result.output) {
     logWarn("inference", `Context ID slug inference failed: ${result.error}`);
@@ -250,26 +256,26 @@ export async function inferenceAsync(
   userPrompt: string,
   level = "fast",
   timeout?: number,
+  options?: { model?: string },
 ): Promise<InferenceResult> {
   const startTime = Date.now();
-  const model = (level in MODELS ? MODELS[level] : undefined) ?? MODELS.fast;
-  const timeoutSec = timeout ?? (level in TIMEOUTS ? TIMEOUTS[level] : undefined) ?? TIMEOUTS.fast;
+  const modelInput = options?.model ?? level;
+  const timeoutSec = timeout ?? (isModelTier(modelInput) ? getTierTimeout(modelInput) : TIER_TIMEOUTS.fast);
   const timeoutMs = timeoutSec * 1000;
   const fullPrompt = `${systemPrompt}\n\n${userPrompt}`;
 
-  const env = getInternalSubprocessEnv();
-  delete env.ANTHROPIC_API_KEY;
+  const invocation = buildCliInvocation(inferenceSpec(modelInput));
+  const isWin = invocation.needsShell;
 
-  const isWin = process.platform === "win32";
-  const empty = isWin ? '""' : "";
+  // Prompt arg needs Windows quoting when using shell mode
   const promptArg = isWin
-    ? shellQuoteWin(fullPrompt.replaceAll(/\r?\n/g, " "))
+    ? ('"' + fullPrompt.replaceAll(/\r?\n/g, " ").replaceAll('"', '""') + '"')
     : fullPrompt;
 
   const result = await execFileAsync(
-    "claude",
-    ["--model", model, "--print", "--setting-sources", empty, "-p", "--no-session-persistence", promptArg],
-    { timeout: timeoutMs, env, shell: isWin },
+    invocation.cliName,
+    [...invocation.args, promptArg],
+    { timeout: timeoutMs, env: invocation.env, shell: isWin },
   );
 
   const latencyMs = Date.now() - startTime;

package/dist/templates/_shared/lib-ts/base/models.ts

@@ -0,0 +1,16 @@
+/**
+ * Canonical model ID constants — single source of truth.
+ * All model IDs used across the system should reference these constants.
+ */
+
+export const CLAUDE_MODELS = {
+  haiku: "claude-haiku-4-5-20251001",
+  sonnet: "claude-sonnet-4-6",
+  opus: "claude-opus-4-6",
+} as const;
+
+export const CODEX_MODELS = {
+  spark: "gpt-5.3-codex-spark",
+  codex: "gpt-5.3-codex",
+  gpt: "gpt-5.2",
+} as const;