aiwcli 0.13.7 → 0.14.0

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,4 @@
+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";

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

@@ -0,0 +1,283 @@
+/**
+ * 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;
+  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.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,
+): CodexReplSpec {
+  return {
+    provider: "codex",
+    mode: "repl",
+    model,
+    sandbox,
+  };
+}
+
+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;

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

@@ -0,0 +1,98 @@
+/**
+ * Shared preflight health check for provider+model availability.
+ * Extracted from plan-review/lib/preflight.ts for reuse by any hook.
+ *
+ * Validates that a CLI tool + model combo works by running a minimal "ping" request.
+ */
+
+import { logDebug, logWarn } from "./logger.js";
+import { findExecutable, execFileAsync, getInternalSubprocessEnv } from "./subprocess-utils.js";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface PreflightCommandConfig {
+  cliName: string;
+  buildArgs: (model: string) => string[];
+  input: string;
+}
+
+export interface PreflightCheckResult {
+  provider: string;
+  model: string;
+  available: boolean;
+  latencyMs: number;
+  error?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Error Classification
+// ---------------------------------------------------------------------------
+
+export function classifyError(
+  stderr: string,
+  exitCode: number | null,
+  killed: boolean,
+  signal: string | null,
+): string {
+  if (killed || signal === "SIGTERM") return "Preflight timed out";
+  if (/model.*not found|not available/i.test(stderr)) return "Model not available for this account";
+  if (/rate limit|429/i.test(stderr)) return "Rate limited";
+  if (/auth|api key|401/i.test(stderr)) return "Authentication failed";
+  if (/quota|billing/i.test(stderr)) return "Quota/billing issue";
+  return `Exit code ${exitCode}`;
+}
+
+// ---------------------------------------------------------------------------
+// Single Provider+Model Check
+// ---------------------------------------------------------------------------
+
+/**
+ * Check if a single provider:model combo is available.
+ * Takes a PreflightCommandConfig so callers define their own CLI args.
+ */
+export async function checkProviderModel(
+  provider: string,
+  model: string,
+  config: PreflightCommandConfig,
+  timeoutMs: number,
+  hook = "preflight",
+): Promise<PreflightCheckResult> {
+  const cliPath = findExecutable(config.cliName);
+  if (!cliPath) {
+    return { provider, model, available: false, latencyMs: 0, error: `CLI '${config.cliName}' not found on PATH` };
+  }
+
+  const start = Date.now();
+  try {
+    const env = getInternalSubprocessEnv();
+    const result = await execFileAsync(cliPath, config.buildArgs(model), {
+      input: config.input,
+      timeout: timeoutMs,
+      env: env as Record<string, string>,
+      maxBuffer: 1 * 1024 * 1024,
+      shell: process.platform === "win32",
+    });
+
+    const latencyMs = Date.now() - start;
+
+    if (result.killed || result.signal === "SIGTERM") {
+      return { provider, model, available: false, latencyMs, error: "Preflight timed out" };
+    }
+
+    if (result.exitCode !== 0) {
+      const error = classifyError(result.stderr, result.exitCode, result.killed, result.signal);
+      logWarn(hook, `${provider}:${model} failed: ${error} (stderr: ${result.stderr.slice(-200)})`);
+      return { provider, model, available: false, latencyMs, error };
+    }
+
+    logDebug(hook, `${provider}:${model} passed (${latencyMs}ms)`);
+    return { provider, model, available: true, latencyMs };
+  } catch (err) {
+    const latencyMs = Date.now() - start;
+    const error = err instanceof Error ? err.message : String(err);
+    logWarn(hook, `${provider}:${model} exception: ${error}`);
+    return { provider, model, available: false, latencyMs, error };
+  }
+}