@mastra/code-sdk 0.0.0-fix-workflow-step-timing-and-parallel-status-20260715180716

package/dist/evals/scorers/outcome.js

@@ -0,0 +1,238 @@
+import { createScorer, filterRun } from "@mastra/core/evals";
+import { isBuildCommand, isTestCommand, getExitCode } from "./classify-command.js";
+import { extractToolCalls } from "./extract-tools.js";
+const WEIGHTS = {
+  build: 0.3,
+  tests: 0.25,
+  toolErrors: 0.2,
+  loops: 0.1,
+  regression: 0.1,
+  autonomy: 0.05
+};
+const THRESHOLDS = {
+  /** Multiplier for tool error rate penalty. Score = max(0, 1 - rate × this). */
+  toolErrorPenaltyMultiplier: 1,
+  /** How many consecutive identical calls (or same-error repeats) before it's a "loop". */
+  loopMinRepetitions: 3,
+  /** Score penalty per detected loop. */
+  loopPenaltyPerOccurrence: 0.3,
+  /** Score deducted per ask_user call. */
+  autonomyPenaltyPerAsk: 0.25,
+  /** Score when a command ran but exit code is ambiguous. */
+  ambiguousExitScore: 0.75,
+  /** Minimum tool calls required to produce a meaningful score. */
+  minToolCalls: 1,
+  /** Tool names whose errors are expected/benign (not penalized). */
+  benignErrorTools: ["search_content", "find_files", "lsp_inspect"]
+};
+function isBuildArgs(args) {
+  return isBuildCommand(String(args.command ?? ""));
+}
+function isTestArgs(args) {
+  return isTestCommand(String(args.command ?? ""));
+}
+function scoreBuild(execResults) {
+  const builds = execResults.filter((r) => r.toolName === "execute_command" && isBuildArgs(r.args));
+  if (builds.length === 0) return { score: 0, detail: "No build/typecheck ran", applicable: false };
+  const last = builds[builds.length - 1];
+  if (last.isError) return { score: 0, detail: "Build/typecheck tool errored", applicable: true };
+  const exitCode = getExitCode(last.result);
+  if (exitCode === 0) return { score: 1, detail: "Build/typecheck passed", applicable: true };
+  if (exitCode !== null && exitCode !== 0)
+    return { score: 0, detail: `Build failed (exit ${exitCode})`, applicable: true };
+  const text = typeof last.result === "string" ? last.result : JSON.stringify(last.result ?? "");
+  if (/error TS\d+|Cannot find module|is not assignable/i.test(text)) {
+    return { score: 0, detail: "Build failed (TypeScript errors in output)", applicable: true };
+  }
+  return { score: THRESHOLDS.ambiguousExitScore, detail: "Build ran, outcome unclear", applicable: true };
+}
+function scoreTests(execResults) {
+  const tests = execResults.filter((r) => r.toolName === "execute_command" && isTestArgs(r.args));
+  if (tests.length === 0) return { score: 0, detail: "No tests ran", applicable: false };
+  const last = tests[tests.length - 1];
+  if (last.isError) return { score: 0, detail: "Test command errored", applicable: true };
+  const exitCode = getExitCode(last.result);
+  if (exitCode === 0) return { score: 1, detail: "Tests passed", applicable: true };
+  if (exitCode !== null && exitCode !== 0)
+    return { score: 0, detail: `Tests failed (exit ${exitCode})`, applicable: true };
+  const text = typeof last.result === "string" ? last.result : JSON.stringify(last.result ?? "");
+  if (/\d+ (?:tests? )?passed|✓|PASS/i.test(text) && !/\bfail(?:ed|ure)?\b|\berror\b/i.test(text)) {
+    return { score: 1, detail: "Tests passed (inferred)", applicable: true };
+  }
+  if (/\bFAIL\b|failed|✗|✘/i.test(text)) {
+    return { score: 0, detail: "Tests failed (inferred)", applicable: true };
+  }
+  return { score: THRESHOLDS.ambiguousExitScore, detail: "Tests ran, outcome unclear", applicable: true };
+}
+function scoreToolErrors(results) {
+  if (results.length === 0) return { score: 1, detail: "No tool calls", applicable: false };
+  const nonBenign = results.filter((r) => !THRESHOLDS.benignErrorTools.includes(r.toolName));
+  if (nonBenign.length === 0) return { score: 1, detail: "All tool calls are benign-error tools", applicable: true };
+  const errors = nonBenign.filter((r) => r.isError);
+  const rate = errors.length / nonBenign.length;
+  if (rate === 0) return { score: 1, detail: "No tool errors", applicable: true };
+  const score = Math.max(0, 1 - rate * THRESHOLDS.toolErrorPenaltyMultiplier);
+  return {
+    score,
+    detail: `${errors.length}/${nonBenign.length} tools errored (${(rate * 100).toFixed(0)}%)`,
+    applicable: true
+  };
+}
+function scoreStuckLoops(results) {
+  if (results.length < 3) return { score: 1, detail: "Too few calls for loop detection", applicable: true };
+  const fingerprint = (r) => `${r.toolName}:${JSON.stringify(r.args)}`;
+  let maxConsecutive = 1;
+  let currentRun = 1;
+  for (let i = 1; i < results.length; i++) {
+    if (fingerprint(results[i]) === fingerprint(results[i - 1])) {
+      currentRun++;
+      maxConsecutive = Math.max(maxConsecutive, currentRun);
+    } else {
+      currentRun = 1;
+    }
+  }
+  const errorCounts = /* @__PURE__ */ new Map();
+  for (const r of results) {
+    if (!r.isError) continue;
+    const fp = fingerprint(r);
+    errorCounts.set(fp, (errorCounts.get(fp) ?? 0) + 1);
+  }
+  const maxErrorRepeat = Math.max(0, ...[...errorCounts.values()]);
+  const minReps = THRESHOLDS.loopMinRepetitions;
+  const loopSeverity = Math.max(
+    maxConsecutive >= minReps ? maxConsecutive - (minReps - 1) : 0,
+    maxErrorRepeat >= minReps ? maxErrorRepeat - (minReps - 1) : 0
+  );
+  if (loopSeverity === 0) return { score: 1, detail: "No stuck loops", applicable: true };
+  const score = Math.max(0, 1 - loopSeverity * THRESHOLDS.loopPenaltyPerOccurrence);
+  const details = [];
+  if (maxConsecutive >= minReps) details.push(`${maxConsecutive} consecutive identical calls`);
+  if (maxErrorRepeat >= minReps) details.push(`same error repeated ${maxErrorRepeat}x`);
+  return { score, detail: details.join("; "), applicable: true };
+}
+function scoreRegression(execResults) {
+  const regressions = [];
+  for (const [label, filter] of [
+    ["Build", isBuildArgs],
+    ["Tests", isTestArgs]
+  ]) {
+    const cmds = execResults.filter((r) => r.toolName === "execute_command" && filter(r.args));
+    if (cmds.length < 2) continue;
+    let sawPass = false;
+    let sawRegression = false;
+    for (const cmd of cmds) {
+      const exit = getExitCode(cmd.result);
+      if (exit === 0) {
+        if (sawRegression) {
+          regressions.push({ label, recovered: true });
+          sawRegression = false;
+        }
+        sawPass = true;
+      }
+      if (sawPass && exit !== null && exit !== 0) {
+        sawRegression = true;
+      }
+    }
+    if (sawRegression) {
+      regressions.push({ label, recovered: false });
+    }
+  }
+  if (regressions.length === 0) return { score: 1, detail: "No regressions", applicable: true };
+  const persistentCount = regressions.filter((r) => !r.recovered).length;
+  const recoveredCount = regressions.filter((r) => r.recovered).length;
+  const score = Math.max(0, 1 - persistentCount * 0.5 - recoveredCount * 0.1);
+  const details = regressions.map(
+    (r) => `${r.label} ${r.recovered ? "regressed then recovered" : "regressed (persisted)"}`
+  );
+  return { score, detail: details.join("; "), applicable: true };
+}
+function scoreAutonomy(results) {
+  const askUserCalls = results.filter((r) => r.toolName === "ask_user");
+  const count = askUserCalls.length;
+  if (count === 0) return { score: 1, detail: "No ask_user calls (fully autonomous)", applicable: true };
+  const score = Math.max(0, 1 - count * THRESHOLDS.autonomyPenaltyPerAsk);
+  return { score, detail: `${count} ask_user call${count > 1 ? "s" : ""}`, applicable: true };
+}
+function weightedAverage(dimensions, weights) {
+  let totalWeight = 0;
+  let weightedSum = 0;
+  for (const [key, result] of Object.entries(dimensions)) {
+    if (!result.applicable) continue;
+    const weight = weights[key] ?? 0;
+    totalWeight += weight;
+    weightedSum += result.score * weight;
+  }
+  if (totalWeight === 0) return null;
+  return weightedSum / totalWeight;
+}
+function createOutcomeScorer() {
+  return createScorer({
+    id: "mastracode-outcome",
+    name: "MastraCode Outcome",
+    description: "Grades coding session outcomes: build/test pass, tool errors, stuck loops, regressions, autonomy. Always-on.",
+    type: "agent",
+    prepareRun: filterRun({ partTypes: ["tool-invocation", "text"] })
+  }).preprocess(async ({ run }) => {
+    const messages = run.output ?? [];
+    const allResults = extractToolCalls(messages);
+    const totalCalls = allResults.length;
+    if (totalCalls < THRESHOLDS.minToolCalls) {
+      const empty = { score: 0, detail: "No tool calls", applicable: false };
+      return {
+        empty: true,
+        build: empty,
+        tests: empty,
+        toolErrors: empty,
+        loops: empty,
+        regression: empty,
+        autonomy: empty,
+        totalCalls
+      };
+    }
+    const execResults = allResults.filter((r) => r.toolName === "execute_command");
+    return {
+      empty: false,
+      build: scoreBuild(execResults),
+      tests: scoreTests(execResults),
+      toolErrors: scoreToolErrors(allResults),
+      loops: scoreStuckLoops(allResults),
+      regression: scoreRegression(execResults),
+      autonomy: scoreAutonomy(allResults),
+      totalCalls
+    };
+  }).generateScore(({ results }) => {
+    const p = results.preprocessStepResult;
+    if (p.empty) return 0;
+    const score = weightedAverage(
+      {
+        build: p.build,
+        tests: p.tests,
+        toolErrors: p.toolErrors,
+        loops: p.loops,
+        regression: p.regression,
+        autonomy: p.autonomy
+      },
+      WEIGHTS
+    );
+    return score === null ? 0 : Math.round(score * 100) / 100;
+  }).generateReason(({ results, score }) => {
+    const p = results.preprocessStepResult;
+    if (p.empty) {
+      return `Score: 0 (${p.totalCalls} tool calls \u2014 below minimum threshold for scoring)`;
+    }
+    const pct = (w) => `${(w * 100).toFixed(0)}%`;
+    const dimLine = (name, weight, r) => r.applicable ? `${name} (${pct(weight)}): ${r.detail} [${r.score}]` : `${name}: ${r.detail} [N/A \u2014 excluded from average]`;
+    const parts = [`Score: ${score} (${p.totalCalls} tool calls total)`];
+    parts.push(dimLine("Build", WEIGHTS.build, p.build));
+    parts.push(dimLine("Tests", WEIGHTS.tests, p.tests));
+    parts.push(dimLine("Tool errors", WEIGHTS.toolErrors, p.toolErrors));
+    parts.push(dimLine("Loops", WEIGHTS.loops, p.loops));
+    parts.push(dimLine("Regression", WEIGHTS.regression, p.regression));
+    parts.push(dimLine("Autonomy", WEIGHTS.autonomy, p.autonomy));
+    return parts.join("\n");
+  });
+}
+export {
+  createOutcomeScorer
+};
+//# sourceMappingURL=outcome.js.map

package/dist/evals/scorers/outcome.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/evals/scorers/outcome.ts"],"sourcesContent":["/**\n * MastraCode Outcome Scorer (Code-based, Agent type, always-on)\n *\n * Grades the objective outcome of a coding session by checking hard facts:\n * - Did the build/typecheck pass?\n * - Did tests pass?\n * - What was the tool error rate?\n * - Did the agent get stuck in a loop?\n * - Was there a regression (build passed earlier, failed later)?\n * - Did the agent use ask_user unnecessarily? (autonomy)\n *\n * This scorer is always-on (no sampling) because it's cheap — it only\n * reads exit codes and error states from tool results already in the messages.\n *\n * Scoring philosophy (from Anthropic's eval guidance):\n * \"Grade outcomes, not paths\" — we check what happened, not how.\n * Partial credit: a session that passes build but fails tests scores\n * higher than one that fails build entirely.\n *\n * Dimensions that don't apply to a session (e.g. build for a docs-only task)\n * are excluded from the weighted average, so sessions aren't penalized for\n * irrelevant criteria.\n */\n\nimport type { MastraDBMessage } from '@mastra/core/agent';\nimport { createScorer, filterRun } from '@mastra/core/evals';\n\nimport { isBuildCommand, isTestCommand, getExitCode } from './classify-command.js';\nimport type { ExtractedToolCall } from './extract-tools.js';\nimport { extractToolCalls } from './extract-tools.js';\n\n// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n// CONFIGURATION — Adjust weights and thresholds here\n// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\n/**\n * Dimension weights. Used to compute the weighted average of applicable dimensions.\n * Dimensions that don't apply (e.g. no build ran) are excluded from the average.\n */\nconst WEIGHTS = {\n  build: 0.3,\n  tests: 0.25,\n  toolErrors: 0.2,\n  loops: 0.1,\n  regression: 0.1,\n  autonomy: 0.05,\n} as const;\n\n/**\n * Scoring thresholds and multipliers.\n */\nconst THRESHOLDS = {\n  /** Multiplier for tool error rate penalty. Score = max(0, 1 - rate × this). */\n  toolErrorPenaltyMultiplier: 1.0,\n\n  /** How many consecutive identical calls (or same-error repeats) before it's a \"loop\". */\n  loopMinRepetitions: 3,\n\n  /** Score penalty per detected loop. */\n  loopPenaltyPerOccurrence: 0.3,\n\n  /** Score deducted per ask_user call. */\n  autonomyPenaltyPerAsk: 0.25,\n\n  /** Score when a command ran but exit code is ambiguous. */\n  ambiguousExitScore: 0.75,\n\n  /** Minimum tool calls required to produce a meaningful score. */\n  minToolCalls: 1,\n\n  /** Tool names whose errors are expected/benign (not penalized). */\n  benignErrorTools: ['search_content', 'find_files', 'lsp_inspect'] as string[],\n} as const;\n\n// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\ntype DimensionResult = { score: number; detail: string; applicable: boolean };\n\n/**\n * Check if the primary verb of an execute_command is a build/typecheck command.\n * Splits compound commands (&&, ;) and checks the first segment.\n */\n/** Extract command string from tool call args, then delegate to shared classifier. */\nfunction isBuildArgs(args: Record<string, unknown>): boolean {\n  return isBuildCommand(String(args.command ?? ''));\n}\n\nfunction isTestArgs(args: Record<string, unknown>): boolean {\n  return isTestCommand(String(args.command ?? ''));\n}\n\n/**\n * Score build/typecheck outcome (final state).\n */\nfunction scoreBuild(execResults: ExtractedToolCall[]): DimensionResult {\n  const builds = execResults.filter(r => r.toolName === 'execute_command' && isBuildArgs(r.args));\n  if (builds.length === 0) return { score: 0, detail: 'No build/typecheck ran', applicable: false };\n\n  const last = builds[builds.length - 1]!;\n  if (last.isError) return { score: 0, detail: 'Build/typecheck tool errored', applicable: true };\n\n  const exitCode = getExitCode(last.result);\n  if (exitCode === 0) return { score: 1, detail: 'Build/typecheck passed', applicable: true };\n  if (exitCode !== null && exitCode !== 0)\n    return { score: 0, detail: `Build failed (exit ${exitCode})`, applicable: true };\n\n  // Fallback: check result text for TS errors\n  const text = typeof last.result === 'string' ? last.result : JSON.stringify(last.result ?? '');\n  if (/error TS\\d+|Cannot find module|is not assignable/i.test(text)) {\n    return { score: 0, detail: 'Build failed (TypeScript errors in output)', applicable: true };\n  }\n\n  return { score: THRESHOLDS.ambiguousExitScore, detail: 'Build ran, outcome unclear', applicable: true };\n}\n\n/**\n * Score test outcome (final state).\n */\nfunction scoreTests(execResults: ExtractedToolCall[]): DimensionResult {\n  const tests = execResults.filter(r => r.toolName === 'execute_command' && isTestArgs(r.args));\n  if (tests.length === 0) return { score: 0, detail: 'No tests ran', applicable: false };\n\n  const last = tests[tests.length - 1]!;\n  if (last.isError) return { score: 0, detail: 'Test command errored', applicable: true };\n\n  const exitCode = getExitCode(last.result);\n  if (exitCode === 0) return { score: 1, detail: 'Tests passed', applicable: true };\n  if (exitCode !== null && exitCode !== 0)\n    return { score: 0, detail: `Tests failed (exit ${exitCode})`, applicable: true };\n\n  const text = typeof last.result === 'string' ? last.result : JSON.stringify(last.result ?? '');\n  if (/\\d+ (?:tests? )?passed|✓|PASS/i.test(text) && !/\\bfail(?:ed|ure)?\\b|\\berror\\b/i.test(text)) {\n    return { score: 1, detail: 'Tests passed (inferred)', applicable: true };\n  }\n  if (/\\bFAIL\\b|failed|✗|✘/i.test(text)) {\n    return { score: 0, detail: 'Tests failed (inferred)', applicable: true };\n  }\n\n  return { score: THRESHOLDS.ambiguousExitScore, detail: 'Tests ran, outcome unclear', applicable: true };\n}\n\n/**\n * Score tool error rate, excluding benign errors from expected-to-fail tools.\n */\nfunction scoreToolErrors(results: ExtractedToolCall[]): DimensionResult {\n  if (results.length === 0) return { score: 1, detail: 'No tool calls', applicable: false };\n\n  // Only count errors from non-benign tools\n  const nonBenign = results.filter(r => !THRESHOLDS.benignErrorTools.includes(r.toolName));\n  if (nonBenign.length === 0) return { score: 1, detail: 'All tool calls are benign-error tools', applicable: true };\n\n  const errors = nonBenign.filter(r => r.isError);\n  const rate = errors.length / nonBenign.length;\n\n  if (rate === 0) return { score: 1, detail: 'No tool errors', applicable: true };\n\n  const score = Math.max(0, 1 - rate * THRESHOLDS.toolErrorPenaltyMultiplier);\n  return {\n    score,\n    detail: `${errors.length}/${nonBenign.length} tools errored (${(rate * 100).toFixed(0)}%)`,\n    applicable: true,\n  };\n}\n\n/**\n * Detect stuck loops: same tool + same args appearing 3+ times consecutively,\n * or same tool + same args erroring 3+ times total.\n */\nfunction scoreStuckLoops(results: ExtractedToolCall[]): DimensionResult {\n  if (results.length < 3) return { score: 1, detail: 'Too few calls for loop detection', applicable: true };\n\n  const fingerprint = (r: ExtractedToolCall) => `${r.toolName}:${JSON.stringify(r.args)}`;\n\n  // Check consecutive identical calls\n  let maxConsecutive = 1;\n  let currentRun = 1;\n  for (let i = 1; i < results.length; i++) {\n    if (fingerprint(results[i]!) === fingerprint(results[i - 1]!)) {\n      currentRun++;\n      maxConsecutive = Math.max(maxConsecutive, currentRun);\n    } else {\n      currentRun = 1;\n    }\n  }\n\n  // Check repeated error fingerprints\n  const errorCounts = new Map<string, number>();\n  for (const r of results) {\n    if (!r.isError) continue;\n    const fp = fingerprint(r);\n    errorCounts.set(fp, (errorCounts.get(fp) ?? 0) + 1);\n  }\n  const maxErrorRepeat = Math.max(0, ...[...errorCounts.values()]);\n\n  const minReps = THRESHOLDS.loopMinRepetitions;\n  const loopSeverity = Math.max(\n    maxConsecutive >= minReps ? maxConsecutive - (minReps - 1) : 0,\n    maxErrorRepeat >= minReps ? maxErrorRepeat - (minReps - 1) : 0,\n  );\n\n  if (loopSeverity === 0) return { score: 1, detail: 'No stuck loops', applicable: true };\n\n  const score = Math.max(0, 1 - loopSeverity * THRESHOLDS.loopPenaltyPerOccurrence);\n  const details: string[] = [];\n  if (maxConsecutive >= minReps) details.push(`${maxConsecutive} consecutive identical calls`);\n  if (maxErrorRepeat >= minReps) details.push(`same error repeated ${maxErrorRepeat}x`);\n  return { score, detail: details.join('; '), applicable: true };\n}\n\n/**\n * Detect regressions: build/test passed at some point, then failed later.\n * Gives partial credit if the agent recovered (final state passes).\n */\nfunction scoreRegression(execResults: ExtractedToolCall[]): DimensionResult {\n  const regressions: { label: string; recovered: boolean }[] = [];\n\n  for (const [label, filter] of [\n    ['Build', isBuildArgs],\n    ['Tests', isTestArgs],\n  ] as const) {\n    const cmds = execResults.filter(r => r.toolName === 'execute_command' && filter(r.args));\n    if (cmds.length < 2) continue;\n\n    let sawPass = false;\n    let sawRegression = false;\n    for (const cmd of cmds) {\n      const exit = getExitCode(cmd.result);\n      if (exit === 0) {\n        if (sawRegression) {\n          // Recovered from regression\n          regressions.push({ label, recovered: true });\n          sawRegression = false;\n        }\n        sawPass = true;\n      }\n      if (sawPass && exit !== null && exit !== 0) {\n        sawRegression = true;\n      }\n    }\n\n    if (sawRegression) {\n      // Regression persisted at end of session\n      regressions.push({ label, recovered: false });\n    }\n  }\n\n  if (regressions.length === 0) return { score: 1, detail: 'No regressions', applicable: true };\n\n  // Persistent regressions are severe (0), recovered regressions get partial credit (0.5)\n  const persistentCount = regressions.filter(r => !r.recovered).length;\n  const recoveredCount = regressions.filter(r => r.recovered).length;\n  const score = Math.max(0, 1 - persistentCount * 0.5 - recoveredCount * 0.1);\n  const details = regressions.map(\n    r => `${r.label} ${r.recovered ? 'regressed then recovered' : 'regressed (persisted)'}`,\n  );\n  return { score, detail: details.join('; '), applicable: true };\n}\n\n/**\n * Score autonomy: penalize ask_user calls.\n * 0 calls = 1.0, each call reduces by 0.25 (up to a floor of 0).\n */\nfunction scoreAutonomy(results: ExtractedToolCall[]): DimensionResult {\n  const askUserCalls = results.filter(r => r.toolName === 'ask_user');\n  const count = askUserCalls.length;\n\n  if (count === 0) return { score: 1, detail: 'No ask_user calls (fully autonomous)', applicable: true };\n\n  const score = Math.max(0, 1 - count * THRESHOLDS.autonomyPenaltyPerAsk);\n  return { score, detail: `${count} ask_user call${count > 1 ? 's' : ''}`, applicable: true };\n}\n\n/**\n * Compute weighted average of only applicable dimensions.\n * Returns null if no dimensions are applicable.\n */\nfunction weightedAverage(dimensions: Record<string, DimensionResult>, weights: Record<string, number>): number | null {\n  let totalWeight = 0;\n  let weightedSum = 0;\n\n  for (const [key, result] of Object.entries(dimensions)) {\n    if (!result.applicable) continue;\n    const weight = weights[key] ?? 0;\n    totalWeight += weight;\n    weightedSum += result.score * weight;\n  }\n\n  if (totalWeight === 0) return null;\n  return weightedSum / totalWeight;\n}\n\nexport function createOutcomeScorer() {\n  return createScorer({\n    id: 'mastracode-outcome',\n    name: 'MastraCode Outcome',\n    description:\n      'Grades coding session outcomes: build/test pass, tool errors, stuck loops, regressions, autonomy. Always-on.',\n    type: 'agent',\n    prepareRun: filterRun({ partTypes: ['tool-invocation', 'text'] }),\n  })\n    .preprocess(async ({ run }) => {\n      const messages = (run.output ?? []) as MastraDBMessage[];\n      const allResults = extractToolCalls(messages);\n      const totalCalls = allResults.length;\n\n      // H1: Empty sessions or sessions with no tool calls → score 0\n      if (totalCalls < THRESHOLDS.minToolCalls) {\n        const empty: DimensionResult = { score: 0, detail: 'No tool calls', applicable: false };\n        return {\n          empty: true as const,\n          build: empty,\n          tests: empty,\n          toolErrors: empty,\n          loops: empty,\n          regression: empty,\n          autonomy: empty,\n          totalCalls,\n        };\n      }\n\n      const execResults = allResults.filter(r => r.toolName === 'execute_command');\n\n      return {\n        empty: false as const,\n        build: scoreBuild(execResults),\n        tests: scoreTests(execResults),\n        toolErrors: scoreToolErrors(allResults),\n        loops: scoreStuckLoops(allResults),\n        regression: scoreRegression(execResults),\n        autonomy: scoreAutonomy(allResults),\n        totalCalls,\n      };\n    })\n    .generateScore(({ results }) => {\n      const p = results.preprocessStepResult;\n      if (p.empty) return 0;\n\n      const score = weightedAverage(\n        {\n          build: p.build,\n          tests: p.tests,\n          toolErrors: p.toolErrors,\n          loops: p.loops,\n          regression: p.regression,\n          autonomy: p.autonomy,\n        },\n        WEIGHTS,\n      );\n\n      return score === null ? 0 : Math.round(score * 100) / 100;\n    })\n    .generateReason(({ results, score }) => {\n      const p = results.preprocessStepResult;\n      if (p.empty) {\n        return `Score: 0 (${p.totalCalls} tool calls — below minimum threshold for scoring)`;\n      }\n\n      const pct = (w: number) => `${(w * 100).toFixed(0)}%`;\n      const dimLine = (name: string, weight: number, r: DimensionResult) =>\n        r.applicable\n          ? `${name} (${pct(weight)}): ${r.detail} [${r.score}]`\n          : `${name}: ${r.detail} [N/A — excluded from average]`;\n\n      const parts: string[] = [`Score: ${score} (${p.totalCalls} tool calls total)`];\n      parts.push(dimLine('Build', WEIGHTS.build, p.build));\n      parts.push(dimLine('Tests', WEIGHTS.tests, p.tests));\n      parts.push(dimLine('Tool errors', WEIGHTS.toolErrors, p.toolErrors));\n      parts.push(dimLine('Loops', WEIGHTS.loops, p.loops));\n      parts.push(dimLine('Regression', WEIGHTS.regression, p.regression));\n      parts.push(dimLine('Autonomy', WEIGHTS.autonomy, p.autonomy));\n\n      return parts.join('\\n');\n    });\n}\n"],"mappings":"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","names":[]}

package/dist/headless/cli.d.ts

@@ -0,0 +1,42 @@
+import type { PermissionMode, RunMode, ThinkingLevel } from './types.js';
+/** Consolidated output mode (replaces the old `--format` + `--output-format`). */
+export type OutputMode = 'human' | 'json' | 'jsonl';
+export interface HeadlessArgs {
+    prompt?: string;
+    /** Timeout in seconds (CLI surface); converted to ms before `runMC`. */
+    timeout?: number;
+    output: OutputMode;
+    continue_: boolean;
+    model?: string;
+    mode?: RunMode;
+    thinkingLevel?: ThinkingLevel;
+    settings?: string;
+    thread?: string;
+    title?: string;
+    cloneThread: boolean;
+    resourceId?: string;
+    /** Max agentic turns before the run aborts with exit code 1. */
+    maxTurns?: number;
+    /** Named permission mode resolving to a built-in policy. Defaults to `auto`. */
+    permissionMode?: PermissionMode;
+}
+/**
+ * Returns true if `argv` selects headless mode. This must agree with what
+ * {@link parseHeadlessArgs} (and `runMCCli`) accept as a prompt: `--prompt`/`-p`
+ * or a bare positional prompt (e.g. `mastracode "Fix the bug"`). Note that a
+ * prompt piped via stdin without a flag is handled separately by the caller.
+ */
+export declare function hasHeadlessFlag(argv: string[]): boolean;
+/**
+ * Parse CLI arguments for headless mode. The flag table in `flags.ts` is the
+ * single source of truth: each flag carries its own coercion/validation, so this
+ * function just walks {@link FLAGS} and assembles the typed {@link HeadlessArgs}.
+ */
+export declare function parseHeadlessArgs(argv: string[]): HeadlessArgs;
+export declare function printHeadlessUsage(): void;
+/**
+ * Headless CLI entry point: parse arguments, read stdin, initialize MastraCode,
+ * run via `runMC`, render output, and exit with the mapped code.
+ */
+export declare function runMCCli(predrainedInput?: string | null): Promise<never>;
+//# sourceMappingURL=cli.d.ts.map

package/dist/headless/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/headless/cli.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEzE,kFAAkF;AAClF,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC;AAEpD,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wEAAwE;IACxE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,UAAU,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,OAAO,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gEAAgE;IAChE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gFAAgF;IAChF,cAAc,CAAC,EAAE,cAAc,CAAC;CACjC;AAID;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAcvD;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,YAAY,CAsC9D;AAED,wBAAgB,kBAAkB,IAAI,IAAI,CA+BzC;AAED;;;GAGG;AACH,wBAAsB,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,CA+G9E"}

package/dist/headless/cli.js

@@ -0,0 +1,196 @@
+import { existsSync } from "node:fs";
+import { parseArgs } from "node:util";
+import { createMastraCode } from "../index.js";
+import { setupDebugLogging } from "../utils/debug-log.js";
+import { releaseAllThreadLocks } from "../utils/thread-lock.js";
+import { buildParseArgsOptions, FLAGS, renderFlagUsage } from "./flags.js";
+import { createHumanFormatState, formatHuman, formatJsonl, renderJsonResult } from "./format.js";
+import { permissionModeToPolicy } from "./policy.js";
+import { runMC } from "./run-mc.js";
+const parseArgsOptions = buildParseArgsOptions();
+function hasHeadlessFlag(argv) {
+  if (argv.some((a) => a === "--prompt" || a === "-p")) return true;
+  try {
+    const { values, positionals } = parseArgs({
+      args: argv.slice(2),
+      options: parseArgsOptions,
+      strict: false,
+      allowPositionals: true
+    });
+    return positionals.length > 0 && !values.help;
+  } catch {
+    return false;
+  }
+}
+function parseHeadlessArgs(argv) {
+  const { values, positionals } = parseArgs({
+    args: argv.slice(2),
+    options: parseArgsOptions,
+    strict: false,
+    allowPositionals: true
+  });
+  const args = {
+    output: "human",
+    continue_: false,
+    cloneThread: false
+  };
+  const sink = args;
+  for (const flag of FLAGS) {
+    if (!flag.field) continue;
+    const raw = values[flag.key];
+    if (raw === void 0) continue;
+    if (flag.type === "boolean") {
+      sink[flag.field] = Boolean(raw);
+    } else if (typeof raw === "string") {
+      sink[flag.field] = flag.coerce ? flag.coerce(raw) : raw;
+    }
+  }
+  if (args.prompt === void 0 && positionals[0] !== void 0) {
+    args.prompt = positionals[0];
+  }
+  if (args.continue_ && args.thread) {
+    throw new Error("--continue and --thread cannot be used together");
+  }
+  return args;
+}
+function printHeadlessUsage() {
+  process.stdout.write(`
+Usage: mastracode --prompt <text> [options]
+
+Headless (non-interactive) mode options:
+${renderFlagUsage()}
+
+Thread behavior:
+  By default, a new thread is created for each run.
+  Use --continue to resume the most recent thread, or --thread to target a specific one.
+  Use --clone-thread to branch off a copy before running.
+
+Settings file:
+  Uses the same settings.json as the interactive TUI. Pass --settings to use
+  a custom settings file (e.g., settings-ci.json for CI). All model, pack,
+  subagent, and OM configuration is resolved from settings at startup.
+
+Exit codes:
+  0  Agent completed successfully
+  1  Error, aborted, or max turns reached
+  2  Timeout
+
+Examples:
+  mastracode --prompt "Fix the bug in auth.ts"
+  mastracode --prompt "Add tests" --timeout 300 --output json
+  mastracode --prompt "Refactor" --output jsonl
+  mastracode --prompt "Review this PR" --permission-mode deny --max-turns 10
+  mastracode --settings ./settings-ci.json --prompt "Run tests"
+  mastracode -c --prompt "Continue where you left off"
+  echo "Summarize the repo" | mastracode --prompt -
+`);
+}
+async function runMCCli(predrainedInput) {
+  if (process.argv.includes("--help") || process.argv.includes("-h")) {
+    printHeadlessUsage();
+    process.exit(0);
+  }
+  let args;
+  try {
+    args = parseHeadlessArgs(process.argv);
+  } catch (e) {
+    process.stderr.write(`Error: ${e.message}
+`);
+    process.exit(1);
+  }
+  let prompt = args.prompt;
+  if (predrainedInput !== void 0) {
+    prompt = predrainedInput ?? "";
+  } else if (prompt === "-" || !prompt && !process.stdin.isTTY) {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+      chunks.push(chunk);
+    }
+    prompt = Buffer.concat(chunks).toString("utf-8").trim();
+  }
+  if (!prompt) {
+    printHeadlessUsage();
+    process.stderr.write("Error: --prompt is required (or pipe via stdin)\n");
+    process.exit(1);
+  }
+  if (args.settings && !existsSync(args.settings)) {
+    process.stderr.write(`Error: Settings file not found: ${args.settings}
+`);
+    process.exit(1);
+  }
+  const boot = await createMastraCode({ settingsPath: args.settings });
+  const { controller, session, mcpManager, effectiveDefaults } = boot;
+  if (mcpManager?.hasServers()) {
+    try {
+      await mcpManager.initInBackground();
+    } catch (err) {
+      process.stderr.write(`Warning: MCP server initialization failed: ${err.message ?? err}
+`);
+    }
+  }
+  setupDebugLogging();
+  let exitCode = 1;
+  try {
+    const humanState = createHumanFormatState();
+    const run = runMC({
+      controller,
+      session,
+      prompt,
+      model: args.model,
+      mode: args.mode,
+      modeDefaults: effectiveDefaults,
+      thinkingLevel: args.thinkingLevel,
+      thread: { id: args.thread, continueLatest: args.continue_, clone: args.cloneThread },
+      resourceId: args.resourceId,
+      title: args.title,
+      timeoutMs: args.timeout ? args.timeout * 1e3 : void 0,
+      maxTurns: args.maxTurns,
+      policy: args.permissionMode ? permissionModeToPolicy(args.permissionMode) : void 0
+    });
+    for await (const event of run) {
+      if (args.output === "human") {
+        const out = formatHuman(event, humanState);
+        if (out.stdout) process.stdout.write(out.stdout);
+        if (out.stderr) process.stderr.write(out.stderr);
+      } else if (args.output === "jsonl") {
+        process.stdout.write(JSON.stringify(formatJsonl(event)) + "\n");
+      }
+    }
+    const result = await run.result;
+    exitCode = result.exitCode;
+    if (args.output === "json") {
+      process.stdout.write(renderJsonResult(result));
+    } else if (args.output === "jsonl") {
+      process.stdout.write(JSON.stringify({ type: "result", ...result }) + "\n");
+    }
+    if (result.status === "timeout") {
+      process.stderr.write(`
+Timeout elapsed. Aborted.
+`);
+    } else if (result.error && args.output === "human") {
+      process.stderr.write(`Error: ${result.error.message}
+`);
+    }
+  } catch (err) {
+    process.stderr.write(`Error: ${err.message ?? err}
+`);
+    exitCode = 1;
+  } finally {
+    releaseAllThreadLocks();
+    const closeSignalsPubSub = boot.signalsPubSub?.close;
+    await Promise.allSettled([
+      mcpManager?.disconnect(),
+      controller.getMastra()?.stopWorkers(),
+      controller?.stopIntervals(),
+      closeSignalsPubSub?.()
+    ]);
+  }
+  process.exit(exitCode);
+}
+export {
+  hasHeadlessFlag,
+  parseHeadlessArgs,
+  printHeadlessUsage,
+  runMCCli
+};
+//# sourceMappingURL=cli.js.map

package/dist/headless/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/headless/cli.ts"],"sourcesContent":["/**\n * CLI adapter for headless MastraCode runs.\n *\n * This is the only headless layer that touches the process: it parses argv,\n * reads stdin, bootstraps MastraCode via `createMastraCode`, drives `runMC`,\n * renders events/results to stdout/stderr through the pure formatters, maps the\n * result to an exit code, and owns teardown + `process.exit`.\n */\nimport { existsSync } from 'node:fs';\nimport { parseArgs } from 'node:util';\n\nimport { createMastraCode } from '../index.js';\nimport { setupDebugLogging } from '../utils/debug-log.js';\nimport { releaseAllThreadLocks } from '../utils/thread-lock.js';\n\nimport { buildParseArgsOptions, FLAGS, renderFlagUsage } from './flags.js';\nimport { createHumanFormatState, formatHuman, formatJsonl, renderJsonResult } from './format.js';\nimport { permissionModeToPolicy } from './policy.js';\nimport { runMC } from './run-mc.js';\nimport type { PermissionMode, RunMode, ThinkingLevel } from './types.js';\n\n/** Consolidated output mode (replaces the old `--format` + `--output-format`). */\nexport type OutputMode = 'human' | 'json' | 'jsonl';\n\nexport interface HeadlessArgs {\n  prompt?: string;\n  /** Timeout in seconds (CLI surface); converted to ms before `runMC`. */\n  timeout?: number;\n  output: OutputMode;\n  continue_: boolean;\n  model?: string;\n  mode?: RunMode;\n  thinkingLevel?: ThinkingLevel;\n  settings?: string;\n  thread?: string;\n  title?: string;\n  cloneThread: boolean;\n  resourceId?: string;\n  /** Max agentic turns before the run aborts with exit code 1. */\n  maxTurns?: number;\n  /** Named permission mode resolving to a built-in policy. Defaults to `auto`. */\n  permissionMode?: PermissionMode;\n}\n\nconst parseArgsOptions = buildParseArgsOptions();\n\n/**\n * Returns true if `argv` selects headless mode. This must agree with what\n * {@link parseHeadlessArgs} (and `runMCCli`) accept as a prompt: `--prompt`/`-p`\n * or a bare positional prompt (e.g. `mastracode \"Fix the bug\"`). Note that a\n * prompt piped via stdin without a flag is handled separately by the caller.\n */\nexport function hasHeadlessFlag(argv: string[]): boolean {\n  if (argv.some(a => a === '--prompt' || a === '-p')) return true;\n  try {\n    const { values, positionals } = parseArgs({\n      args: argv.slice(2),\n      options: parseArgsOptions,\n      strict: false,\n      allowPositionals: true,\n    });\n    // A positional prompt only counts when not asking for help.\n    return positionals.length > 0 && !values.help;\n  } catch {\n    return false;\n  }\n}\n\n/**\n * Parse CLI arguments for headless mode. The flag table in `flags.ts` is the\n * single source of truth: each flag carries its own coercion/validation, so this\n * function just walks {@link FLAGS} and assembles the typed {@link HeadlessArgs}.\n */\nexport function parseHeadlessArgs(argv: string[]): HeadlessArgs {\n  const { values, positionals } = parseArgs({\n    args: argv.slice(2),\n    options: parseArgsOptions,\n    strict: false,\n    allowPositionals: true,\n  });\n\n  // Seed defaults; per-flag values below override these.\n  const args: HeadlessArgs = {\n    output: 'human',\n    continue_: false,\n    cloneThread: false,\n  };\n  const sink = args as unknown as Record<string, unknown>;\n\n  for (const flag of FLAGS) {\n    if (!flag.field) continue; // e.g. --help, handled by the caller\n    const raw = values[flag.key];\n    if (raw === undefined) continue;\n\n    if (flag.type === 'boolean') {\n      sink[flag.field] = Boolean(raw);\n    } else if (typeof raw === 'string') {\n      sink[flag.field] = flag.coerce ? flag.coerce(raw) : raw;\n    }\n  }\n\n  // A bare positional acts as the prompt when --prompt/-p is absent.\n  if (args.prompt === undefined && positionals[0] !== undefined) {\n    args.prompt = positionals[0];\n  }\n\n  if (args.continue_ && args.thread) {\n    throw new Error('--continue and --thread cannot be used together');\n  }\n\n  return args;\n}\n\nexport function printHeadlessUsage(): void {\n  process.stdout.write(`\nUsage: mastracode --prompt <text> [options]\n\nHeadless (non-interactive) mode options:\n${renderFlagUsage()}\n\nThread behavior:\n  By default, a new thread is created for each run.\n  Use --continue to resume the most recent thread, or --thread to target a specific one.\n  Use --clone-thread to branch off a copy before running.\n\nSettings file:\n  Uses the same settings.json as the interactive TUI. Pass --settings to use\n  a custom settings file (e.g., settings-ci.json for CI). All model, pack,\n  subagent, and OM configuration is resolved from settings at startup.\n\nExit codes:\n  0  Agent completed successfully\n  1  Error, aborted, or max turns reached\n  2  Timeout\n\nExamples:\n  mastracode --prompt \"Fix the bug in auth.ts\"\n  mastracode --prompt \"Add tests\" --timeout 300 --output json\n  mastracode --prompt \"Refactor\" --output jsonl\n  mastracode --prompt \"Review this PR\" --permission-mode deny --max-turns 10\n  mastracode --settings ./settings-ci.json --prompt \"Run tests\"\n  mastracode -c --prompt \"Continue where you left off\"\n  echo \"Summarize the repo\" | mastracode --prompt -\n`);\n}\n\n/**\n * Headless CLI entry point: parse arguments, read stdin, initialize MastraCode,\n * run via `runMC`, render output, and exit with the mapped code.\n */\nexport async function runMCCli(predrainedInput?: string | null): Promise<never> {\n  if (process.argv.includes('--help') || process.argv.includes('-h')) {\n    printHeadlessUsage();\n    process.exit(0);\n  }\n\n  let args: HeadlessArgs;\n  try {\n    args = parseHeadlessArgs(process.argv);\n  } catch (e) {\n    process.stderr.write(`Error: ${(e as Error).message}\\n`);\n    process.exit(1);\n  }\n\n  let prompt = args.prompt;\n  if (predrainedInput !== undefined) {\n    prompt = predrainedInput ?? '';\n  } else if (prompt === '-' || (!prompt && !process.stdin.isTTY)) {\n    const chunks: Buffer[] = [];\n    for await (const chunk of process.stdin) {\n      chunks.push(chunk as Buffer);\n    }\n    prompt = Buffer.concat(chunks).toString('utf-8').trim();\n  }\n\n  if (!prompt) {\n    printHeadlessUsage();\n    process.stderr.write('Error: --prompt is required (or pipe via stdin)\\n');\n    process.exit(1);\n  }\n\n  if (args.settings && !existsSync(args.settings)) {\n    process.stderr.write(`Error: Settings file not found: ${args.settings}\\n`);\n    process.exit(1);\n  }\n\n  const boot = await createMastraCode({ settingsPath: args.settings });\n  const { controller, session, mcpManager, effectiveDefaults } = boot;\n\n  if (mcpManager?.hasServers()) {\n    try {\n      await mcpManager.initInBackground();\n    } catch (err) {\n      process.stderr.write(`Warning: MCP server initialization failed: ${(err as Error).message ?? err}\\n`);\n    }\n  }\n\n  setupDebugLogging();\n\n  // Default to a non-zero exit so an unexpected throw before the run resolves\n  // still surfaces as a failure to the caller / CI.\n  let exitCode = 1;\n  try {\n    const humanState = createHumanFormatState();\n    const run = runMC({\n      controller,\n      session,\n      prompt,\n      model: args.model,\n      mode: args.mode,\n      modeDefaults: effectiveDefaults,\n      thinkingLevel: args.thinkingLevel,\n      thread: { id: args.thread, continueLatest: args.continue_, clone: args.cloneThread },\n      resourceId: args.resourceId,\n      title: args.title,\n      timeoutMs: args.timeout ? args.timeout * 1000 : undefined,\n      maxTurns: args.maxTurns,\n      policy: args.permissionMode ? permissionModeToPolicy(args.permissionMode) : undefined,\n    });\n\n    // Stream live events for human + jsonl modes. (json mode prints only the final object.)\n    for await (const event of run) {\n      if (args.output === 'human') {\n        const out = formatHuman(event, humanState);\n        if (out.stdout) process.stdout.write(out.stdout);\n        if (out.stderr) process.stderr.write(out.stderr);\n      } else if (args.output === 'jsonl') {\n        process.stdout.write(JSON.stringify(formatJsonl(event)) + '\\n');\n      }\n    }\n\n    const result = await run.result;\n    exitCode = result.exitCode;\n\n    if (args.output === 'json') {\n      process.stdout.write(renderJsonResult(result));\n    } else if (args.output === 'jsonl') {\n      process.stdout.write(JSON.stringify({ type: 'result', ...result }) + '\\n');\n    }\n\n    if (result.status === 'timeout') {\n      process.stderr.write(`\\nTimeout elapsed. Aborted.\\n`);\n    } else if (result.error && args.output === 'human') {\n      process.stderr.write(`Error: ${result.error.message}\\n`);\n    }\n  } catch (err) {\n    process.stderr.write(`Error: ${(err as Error).message ?? err}\\n`);\n    exitCode = 1;\n  } finally {\n    // --- Teardown (always runs, even on a thrown error) ---\n    releaseAllThreadLocks();\n    const closeSignalsPubSub = (boot.signalsPubSub as { close?: () => Promise<void> | void } | undefined)?.close;\n    await Promise.allSettled([\n      mcpManager?.disconnect(),\n      controller.getMastra()?.stopWorkers(),\n      controller?.stopIntervals(),\n      closeSignalsPubSub?.(),\n    ]);\n  }\n\n  process.exit(exitCode);\n}\n"],"mappings":"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","names":[]}

package/dist/headless/flags.d.ts

@@ -0,0 +1,33 @@
+export declare const VALID_OUTPUTS: readonly ["human", "json", "jsonl"];
+/**
+ * One CLI flag. `key` is the long name (e.g. `output`); `field` is the
+ * {@link import('./cli.js').HeadlessArgs} property it populates. `coerce`
+ * converts the raw string and validates it. Boolean flags omit `coerce` and set
+ * `field` to `true` when present.
+ */
+export interface FlagSpec {
+    /** Long flag name without the leading `--`. */
+    key: string;
+    /** Single-character alias (without the leading `-`), if any. */
+    short?: string;
+    /** Whether the flag takes a value (`string`) or is a switch (`boolean`). */
+    type: 'string' | 'boolean';
+    /** Target field on `HeadlessArgs`. Omit for flags handled out-of-band (e.g. help). */
+    field?: string;
+    /** Coerce/validate a string value. Required for `type: 'string'` flags that map to a field. */
+    coerce?: (raw: string) => unknown;
+    /** `<...>` value placeholder shown in usage, e.g. `<text>`. */
+    placeholder?: string;
+    /** One-line (or multi-line) help description shown in usage. */
+    help: string | string[];
+}
+export declare const FLAGS: FlagSpec[];
+/** `parseArgs` option config derived from {@link FLAGS}. */
+export declare function buildParseArgsOptions(): Record<string, {
+    type: "string" | "boolean";
+    short?: string;
+    default?: boolean;
+}>;
+/** Render the aligned `--flag  description` block of the usage text from {@link FLAGS}. */
+export declare function renderFlagUsage(): string;
+//# sourceMappingURL=flags.d.ts.map

package/dist/headless/flags.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flags.d.ts","sourceRoot":"","sources":["../../src/headless/flags.ts"],"names":[],"mappings":"AAgBA,eAAO,MAAM,aAAa,qCAAsC,CAAC;AA6BjE;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACvB,+CAA+C;IAC/C,GAAG,EAAE,MAAM,CAAC;IACZ,gEAAgE;IAChE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4EAA4E;IAC5E,IAAI,EAAE,QAAQ,GAAG,SAAS,CAAC;IAC3B,sFAAsF;IACtF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+FAA+F;IAC/F,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IAClC,+DAA+D;IAC/D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gEAAgE;IAChE,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;CACzB;AAED,eAAO,MAAM,KAAK,EAAE,QAAQ,EAiI3B,CAAC;AAEF,4DAA4D;AAC5D,wBAAgB,qBAAqB;UACG,QAAQ,GAAG,SAAS;YAAU,MAAM;cAAY,OAAO;GAM9F;AAED,2FAA2F;AAC3F,wBAAgB,eAAe,IAAI,MAAM,CAmBxC"}