Function runHeadless

src/cli/modes/headless.ts:24–208

(opts: HeadlessOptions)

  config: QodexConfig;
  router: ModelRouter;
  registry: ToolRegistry;
  permissions: PermissionEngine;
  prompt: string;
  json: boolean;
  autoApproveAll?: boolean;
  explicitModel?: string;
  resumeSessionId?: string;
  /** Guardrailed autonomy contract (--budget-tokens/--budget-usd/--max-wall/--scope/
   *  --verify/--rollback-on-fail). When set: budgets override config.budget, journaled
   *  writes are scope-gated, and the run ends with enforcement (verify →
   *  rollback-on-fail → RUN REPORT). */
  contract?: AutonomyContract;
  /** `--receipt <path>`: write a signed, tamper-evident JSON receipt of the run there.
   *  Requires a contract (there is nothing to attest without one). */
  receiptPath?: string;
}

export async function runHeadless(opts: HeadlessOptions): Promise<number> {
  const startedAt = Date.now();
  const store = getSessionStore();

  // ── Autonomy contract: apply budgets BEFORE the loop is built ──
  // Budgets ride the existing BudgetTracker (fromConfig reads config.budget), so a
  // shallow clone with overridden limits is the whole wiring. (The write-scope gate
  // is armed further down, right before agent.run() — see the comment there.)
  let config = opts.config;
  if (opts.contract) {
    const c = opts.contract;
    if (c.budgetTokens !== undefined || c.budgetUsd !== undefined || c.maxWallSec !== undefined) {
      config = {
        ...config,
        budget: {
          ...config.budget,
          ...(c.budgetTokens !== undefined ? { perTaskMaxTokens: c.budgetTokens } : {}),
          ...(c.budgetUsd !== undefined ? { perTaskLimitUsd: c.budgetUsd } : {}),
          ...(c.maxWallSec !== undefined ? { perTaskMaxWallSeconds: c.maxWallSec } : {}),
        },
      };
    }
    // A USD budget on a model we cannot price would never fire: computeCost multiplies by a
    // placeholder 0, spend stays $0.00 forever, and the run is effectively unbounded. Say so
    // loudly rather than letting the user believe a cap is protecting them.
    if (c.budgetUsd !== undefined) {
      try {
        const routed = opts.router.route('main' as any, 0, {});
        if (routed?.modelInfo?.pricingSource === 'unknown') {
          process.stderr.write(
            `⚠  --budget-usd cannot be enforced for "${routed.modelInfo.id}": no pricing is known for this model, ` +
            `so spend always computes as $0.00. Use --budget-tokens or --max-wall instead, or set the price under ` +
            `providers.custom[].models[].inputCostPerMillion.\n`,
          );
        }
      } catch { /* routing probe is best-effort — never block the run on it */ }
    }
  }

  // Resolve a leading custom slash command into its template + one-shot overrides.
  let effectivePrompt = opts.prompt;