stagent 0.9.2 → 0.9.5

package/src/lib/db/schema.ts

@@ -1,4 +1,4 @@
-import { sqliteTable, text, integer, index, uniqueIndex } from "drizzle-orm/sqlite-core";
+import { sqliteTable, text, integer, real, index, uniqueIndex } from "drizzle-orm/sqlite-core";
 import type { InferSelectModel } from "drizzle-orm";
 
 export const projects = sqliteTable("projects", {
@@ -38,6 +38,8 @@ export const tasks = sqliteTable(
       enum: ["manual", "scheduled", "heartbeat", "workflow"],
     }),
     workflowRunNumber: integer("workflow_run_number"),
+    /** Resolved per-task budget cap in USD — set by workflow engine for child tasks */
+    maxBudgetUsd: real("max_budget_usd"),
     createdAt: integer("created_at", { mode: "timestamp" }).notNull(),
     updatedAt: integer("updated_at", { mode: "timestamp" }).notNull(),
   },
@@ -61,6 +63,8 @@ export const workflows = sqliteTable("workflows", {
     .default("draft")
     .notNull(),
   runNumber: integer("run_number").default(0).notNull(),
+  /** Runtime to use for all steps (nullable — falls back to system default) */
+  runtimeId: text("runtime_id"),
   createdAt: integer("created_at", { mode: "timestamp" }).notNull(),
   updatedAt: integer("updated_at", { mode: "timestamp" }).notNull(),
 });
@@ -198,6 +202,14 @@ export const schedules = sqliteTable(
     }),
     /** JSON array of channel config IDs for delivery after firing */
     deliveryChannels: text("delivery_channels"),
+    /** Exponential moving average of turns used per child task firing */
+    avgTurnsPerFiring: integer("avg_turns_per_firing"),
+    /** Turns used by the most recent firing */
+    lastTurnCount: integer("last_turn_count"),
+    /** Consecutive failed firings (reset to 0 on success). Auto-pause at 3. */
+    failureStreak: integer("failure_streak").default(0).notNull(),
+    /** Detected reason for the most recent failure (turn_limit_exceeded, timeout, etc.) */
+    lastFailureReason: text("last_failure_reason"),
     createdAt: integer("created_at", { mode: "timestamp" }).notNull(),
     updatedAt: integer("updated_at", { mode: "timestamp" }).notNull(),
   },
@@ -1172,3 +1184,31 @@ export const license = sqliteTable("license", {
 });
 
 export type LicenseRow = InferSelectModel<typeof license>;
+
+// ── Workflow Execution Stats ─────────────────────────────────────────
+
+export const workflowExecutionStats = sqliteTable("workflow_execution_stats", {
+  id: text("id").primaryKey(),
+  /** Workflow pattern: sequence, parallel, swarm, etc. */
+  pattern: text("pattern").notNull(),
+  /** Number of steps in the workflow */
+  stepCount: integer("step_count").notNull(),
+  /** Average documents injected per step */
+  avgDocsPerStep: real("avg_docs_per_step"),
+  /** Average cost per step in microdollars */
+  avgCostPerStepMicros: integer("avg_cost_per_step_micros"),
+  /** Average duration per step in milliseconds */
+  avgDurationPerStepMs: integer("avg_duration_per_step_ms"),
+  /** Success rate (0.0 to 1.0) */
+  successRate: real("success_rate"),
+  /** JSON: common failure types and counts, e.g., {"budget_exceeded": 4, "timeout": 1} */
+  commonFailures: text("common_failures"),
+  /** JSON: per-runtime success rates, e.g., {"claude-code": 0.92, "openai-direct": 0.71} */
+  runtimeBreakdown: text("runtime_breakdown"),
+  /** Number of workflow runs included in these stats */
+  sampleCount: integer("sample_count").notNull().default(0),
+  lastUpdated: text("last_updated").notNull(),
+  createdAt: text("created_at").notNull(),
+});
+
+export type WorkflowExecutionStatsRow = InferSelectModel<typeof workflowExecutionStats>;

package/src/lib/license/__tests__/manager.test.ts

@@ -0,0 +1,64 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { eq } from "drizzle-orm";
+import { db } from "@/lib/db";
+import { license as licenseTable } from "@/lib/db/schema";
+import { licenseManager } from "../manager";
+
+const LICENSE_ROW_ID = "default";
+
+/**
+ * Regression: under Turbopack module instance separation, the singleton's
+ * in-memory cache could disagree with the DB. If another module instance
+ * (or another process) updates the license row, getTier() must reflect
+ * the new value — otherwise gated limits silently fall back to community
+ * tier rules even on paid tiers.
+ *
+ * The fix in manager.ts makes getTier() / getStatus() read from the DB.
+ * This test simulates the cross-instance scenario by mutating the DB row
+ * directly without going through licenseManager.activate().
+ */
+describe("LicenseManager — DB-direct tier reads", () => {
+  beforeEach(() => {
+    // Reset to a known community baseline.
+    db.delete(licenseTable).where(eq(licenseTable.id, LICENSE_ROW_ID)).run();
+    licenseManager.initialize();
+  });
+
+  afterEach(() => {
+    db.delete(licenseTable).where(eq(licenseTable.id, LICENSE_ROW_ID)).run();
+  });
+
+  it("getTier() reflects DB updates that bypassed activate()", () => {
+    expect(licenseManager.getTier()).toBe("community");
+
+    // Simulate "another module instance wrote scale to the DB".
+    db.update(licenseTable)
+      .set({ tier: "scale", status: "active", updatedAt: new Date() })
+      .where(eq(licenseTable.id, LICENSE_ROW_ID))
+      .run();
+
+    expect(licenseManager.getTier()).toBe("scale");
+    expect(licenseManager.getLimit("agentMemories")).toBe(Infinity);
+    expect(licenseManager.getLimit("activeSchedules")).toBe(Infinity);
+    expect(licenseManager.getLimit("parallelWorkflows")).toBe(Infinity);
+    expect(licenseManager.isPremium()).toBe(true);
+  });
+
+  it("getStatus() also reads from DB, not stale cache", () => {
+    expect(licenseManager.getStatus().tier).toBe("community");
+
+    db.update(licenseTable)
+      .set({
+        tier: "operator",
+        status: "active",
+        email: "ops@example.com",
+        updatedAt: new Date(),
+      })
+      .where(eq(licenseTable.id, LICENSE_ROW_ID))
+      .run();
+
+    const status = licenseManager.getStatus();
+    expect(status.tier).toBe("operator");
+    expect(status.email).toBe("ops@example.com");
+  });
+});

package/src/lib/license/manager.ts

@@ -93,9 +93,15 @@ class LicenseManager {
     }
   }
 
-  /** Current tier — synchronous, zero-latency (reads from cache) */
+  /**
+   * Current tier — reads directly from DB to avoid stale singleton cache
+   * under Turbopack module instance separation. SQLite primary-key lookup
+   * is sub-millisecond, so the previous cache shortcut is not worth the
+   * staleness risk that caused gated limits to fall back to community
+   * even on paid tiers.
+   */
   getTier(): LicenseTier {
-    return this.cache?.tier ?? "community";
+    return this.getTierFromDb();
   }
 
   /**
@@ -128,17 +134,40 @@ class LicenseManager {
     return TIER_LIMITS[this.getTier()][resource];
   }
 
-  /** Get the full cached license state */
+  /**
+   * Get the full license state — reads directly from DB for the same
+   * reason as getTier(): the in-memory cache can be stale across
+   * Turbopack module instances, causing tier/email/expiry to disagree
+   * with what activate() just wrote.
+   */
   getStatus(): CachedLicense & { tier: LicenseTier } {
-    return {
-      tier: this.getTier(),
-      status: this.cache?.status ?? "inactive",
-      email: this.cache?.email ?? null,
-      activatedAt: this.cache?.activatedAt ?? null,
-      expiresAt: this.cache?.expiresAt ?? null,
-      lastValidatedAt: this.cache?.lastValidatedAt ?? null,
-      gracePeriodExpiresAt: this.cache?.gracePeriodExpiresAt ?? null,
-    };
+    return this.getStatusFromDb();
+  }
+
+  /**
+   * Read full license state directly from DB — bypasses in-memory cache.
+   * Use in API routes to avoid stale Turbopack module singleton state.
+   */
+  getStatusFromDb(): CachedLicense & { tier: LicenseTier } {
+    const row = db
+      .select()
+      .from(licenseTable)
+      .where(eq(licenseTable.id, LICENSE_ROW_ID))
+      .get();
+
+    if (!row) {
+      return {
+        tier: "community",
+        status: "inactive",
+        email: null,
+        activatedAt: null,
+        expiresAt: null,
+        lastValidatedAt: null,
+        gracePeriodExpiresAt: null,
+      };
+    }
+
+    return this.rowToCache(row);
   }
 
   /**
@@ -151,20 +180,46 @@ class LicenseManager {
     encryptedToken?: string;
   }): void {
     const now = new Date();
-    db.update(licenseTable)
-      .set({
-        tier: params.tier,
-        status: "active",
-        email: params.email,
-        activatedAt: now,
-        expiresAt: params.expiresAt ?? null,
-        lastValidatedAt: now,
-        gracePeriodExpiresAt: null,
-        encryptedToken: params.encryptedToken ?? null,
-        updatedAt: now,
-      })
+
+    // Ensure the license row exists (may be missing if initialize() hasn't run)
+    const existing = db
+      .select({ id: licenseTable.id })
+      .from(licenseTable)
       .where(eq(licenseTable.id, LICENSE_ROW_ID))
-      .run();
+      .get();
+
+    if (existing) {
+      db.update(licenseTable)
+        .set({
+          tier: params.tier,
+          status: "active",
+          email: params.email,
+          activatedAt: now,
+          expiresAt: params.expiresAt ?? null,
+          lastValidatedAt: now,
+          gracePeriodExpiresAt: null,
+          encryptedToken: params.encryptedToken ?? null,
+          updatedAt: now,
+        })
+        .where(eq(licenseTable.id, LICENSE_ROW_ID))
+        .run();
+    } else {
+      db.insert(licenseTable)
+        .values({
+          id: LICENSE_ROW_ID,
+          tier: params.tier,
+          status: "active",
+          email: params.email,
+          activatedAt: now,
+          expiresAt: params.expiresAt ?? null,
+          lastValidatedAt: now,
+          gracePeriodExpiresAt: null,
+          encryptedToken: params.encryptedToken ?? null,
+          createdAt: now,
+          updatedAt: now,
+        })
+        .run();
+    }
 
     this.refreshCache();
   }

package/src/lib/schedules/__tests__/interval-parser.test.ts

@@ -0,0 +1,87 @@
+import { describe, it, expect } from "vitest";
+import {
+  expandCronMinutes,
+  computeStaggeredCron,
+} from "../interval-parser";
+
+describe("expandCronMinutes", () => {
+  it("expands */N step pattern", () => {
+    expect(expandCronMinutes("*/30 * * * *")).toEqual([0, 30]);
+    expect(expandCronMinutes("*/15 * * * *")).toEqual([0, 15, 30, 45]);
+  });
+
+  it("expands wildcard", () => {
+    const all = expandCronMinutes("* * * * *");
+    expect(all.length).toBe(60);
+    expect(all[0]).toBe(0);
+    expect(all[59]).toBe(59);
+  });
+
+  it("expands comma list", () => {
+    expect(expandCronMinutes("5,15,45 * * * *")).toEqual([5, 15, 45]);
+  });
+
+  it("expands ranges", () => {
+    expect(expandCronMinutes("10-13 * * * *")).toEqual([10, 11, 12, 13]);
+  });
+
+  it("expands stepped ranges", () => {
+    expect(expandCronMinutes("0-30/10 * * * *")).toEqual([0, 10, 20, 30]);
+  });
+
+  it("expands single value", () => {
+    expect(expandCronMinutes("7 * * * *")).toEqual([7]);
+  });
+
+  it("throws on invalid cron", () => {
+    expect(() => expandCronMinutes("not a cron")).toThrow();
+  });
+});
+
+describe("computeStaggeredCron", () => {
+  it("returns original cron when no existing schedules", () => {
+    const result = computeStaggeredCron("*/30 * * * *", []);
+    expect(result.collided).toBe(false);
+    expect(result.offsetApplied).toBe(0);
+    expect(result.cronExpression).toBe("*/30 * * * *");
+  });
+
+  it("returns original cron when no collision", () => {
+    const result = computeStaggeredCron("*/30 * * * *", ["7 * * * *"]);
+    expect(result.collided).toBe(false);
+    expect(result.cronExpression).toBe("*/30 * * * *");
+  });
+
+  it("staggers two */30 schedules", () => {
+    // First schedule fires at :00 and :30. Second should be offset by ≥5min.
+    const result = computeStaggeredCron("*/30 * * * *", ["*/30 * * * *"]);
+    expect(result.collided).toBe(true);
+    expect(result.offsetApplied).toBeGreaterThanOrEqual(5);
+    // Should produce a comma list reflecting the new fire times
+    const minutes = expandCronMinutes(result.cronExpression);
+    // Both fire minutes should be ≥5 away from {0,30}
+    for (const m of minutes) {
+      const distTo0 = Math.min(m, 60 - m);
+      const distTo30 = Math.abs(m - 30);
+      expect(distTo0).toBeGreaterThanOrEqual(5);
+      expect(distTo30).toBeGreaterThanOrEqual(5);
+    }
+  });
+
+  it("enforces 5-minute minimum gap", () => {
+    // Existing schedule at :00, new schedule wants :03 — should stagger.
+    const result = computeStaggeredCron("3 * * * *", ["0 * * * *"]);
+    expect(result.collided).toBe(true);
+    const minutes = expandCronMinutes(result.cronExpression);
+    expect(minutes.length).toBe(1);
+    const m = minutes[0];
+    const distTo0 = Math.min(m, 60 - m);
+    expect(distTo0).toBeGreaterThanOrEqual(5);
+  });
+
+  it("ignores unparseable existing crons gracefully", () => {
+    const result = computeStaggeredCron("*/30 * * * *", ["garbage"]);
+    expect(result.collided).toBe(false);
+    expect(result.cronExpression).toBe("*/30 * * * *");
+  });
+});

package/src/lib/schedules/__tests__/prompt-analyzer.test.ts

@@ -0,0 +1,51 @@
+import { describe, it, expect } from "vitest";
+import { analyzePromptEfficiency } from "../prompt-analyzer";
+
+describe("analyzePromptEfficiency", () => {
+  it("returns no warnings for a clean batched prompt", () => {
+    const warnings = analyzePromptEfficiency(
+      "Search for stock prices AMZN GOOGL NVDA AAPL today and write a summary."
+    );
+    expect(warnings).toEqual([]);
+  });
+
+  it("flags 'for each' loop pattern", () => {
+    const warnings = analyzePromptEfficiency(
+      "For each stock in my portfolio, search the latest price."
+    );
+    expect(warnings.some((w) => w.type === "loop_pattern")).toBe(true);
+  });
+
+  it("flags 'for every' loop pattern", () => {
+    const warnings = analyzePromptEfficiency(
+      "For every market, fetch the current odds."
+    );
+    expect(warnings.some((w) => w.type === "loop_pattern")).toBe(true);
+  });
+
+  it("flags 'individually' loop pattern", () => {
+    const warnings = analyzePromptEfficiency(
+      "Look up each ticker individually and report results."
+    );
+    expect(warnings.some((w) => w.type === "loop_pattern")).toBe(true);
+  });
+
+  it("flags large list pattern", () => {
+    const warnings = analyzePromptEfficiency(
+      "Check all 32 markets and write a report."
+    );
+    expect(warnings.some((w) => w.type === "large_list")).toBe(true);
+  });
+
+  it("flags high turn estimate", () => {
+    // Many search verbs should trip the >30 estimate
+    const verbs = Array(35).fill("search").join(" ");
+    const warnings = analyzePromptEfficiency(verbs);
+    expect(warnings.some((w) => w.type === "high_turn_estimate")).toBe(true);
+  });
+
+  it("does not flag a single quick action", () => {
+    const warnings = analyzePromptEfficiency("Send me a daily news digest.");
+    expect(warnings).toEqual([]);
+  });
+});

package/src/lib/schedules/interval-parser.ts

@@ -75,6 +75,193 @@ export function computeNextFireTime(cronExpression: string, from?: Date): Date {
   return expr.next().toDate();
 }
 
+/**
+ * Expand a cron expression's minute field into the concrete set of minute
+ * values (0-59) it fires on.
+ *
+ * Used by the schedule auto-stagger logic to detect collisions between
+ * existing schedules and a newly requested cron. Only the minute field is
+ * expanded — collisions across hour/day/month boundaries are intentionally
+ * out of scope (a `*​/30 * * * *` schedule and a `*​/30 9 * * *` schedule are
+ * treated as overlapping at minute :00 even though they only collide once
+ * a day, because that single collision is still a starvation risk).
+ *
+ * Supported minute syntax: `*`, `*​/N`, comma lists (`5,15,45`), ranges
+ * (`10-30`), single values, and `step ranges` (`0-30/5`).
+ */
+export function expandCronMinutes(cronExpression: string): number[] {
+  const fields = cronExpression.trim().split(/\s+/);
+  if (fields.length !== 5) {
+    throw new Error(`Invalid cron expression (need 5 fields): ${cronExpression}`);
+  }
+  return expandMinuteField(fields[0]);
+}
+
+function expandMinuteField(field: string): number[] {
+  const result = new Set<number>();
+  for (const part of field.split(",")) {
+    const trimmed = part.trim();
+    if (!trimmed) continue;
+
+    // Handle step syntax: */N, M/N, or A-B/N
+    let stepBase = trimmed;
+    let step = 1;
+    const stepIdx = trimmed.indexOf("/");
+    if (stepIdx >= 0) {
+      stepBase = trimmed.slice(0, stepIdx);
+      step = parseInt(trimmed.slice(stepIdx + 1), 10);
+      if (!Number.isFinite(step) || step <= 0) {
+        throw new Error(`Invalid step in cron minute field: ${trimmed}`);
+      }
+    }
+
+    let from: number;
+    let to: number;
+    if (stepBase === "*") {
+      from = 0;
+      to = 59;
+    } else if (stepBase.includes("-")) {
+      const [a, b] = stepBase.split("-").map((n) => parseInt(n, 10));
+      if (!Number.isFinite(a) || !Number.isFinite(b)) {
+        throw new Error(`Invalid range in cron minute field: ${trimmed}`);
+      }
+      from = a;
+      to = b;
+    } else {
+      const single = parseInt(stepBase, 10);
+      if (!Number.isFinite(single)) {
+        throw new Error(`Invalid value in cron minute field: ${trimmed}`);
+      }
+      // Bare integer with no step: just that one minute.
+      // Bare integer with /N: from value to 59 by step (cron semantics).
+      from = single;
+      to = stepIdx >= 0 ? 59 : single;
+    }
+
+    for (let m = from; m <= to && m < 60; m += step) {
+      if (m >= 0) result.add(m);
+    }
+  }
+  return [...result].sort((a, b) => a - b);
+}
+
+const MIN_GAP_MINUTES = 5;
+
+export interface StaggerResult {
+  cronExpression: string;
+  offsetApplied: number;
+  collided: boolean;
+}
+
+/**
+ * Compute a non-colliding cron expression for a new schedule by offsetting
+ * its minute field if any of its fire minutes are within MIN_GAP_MINUTES of
+ * an already-occupied minute.
+ *
+ * Strategy:
+ *   1. Expand both the requested cron and all existing schedule crons into
+ *      minute sets.
+ *   2. Detect the "interval period" of the request (e.g. 30 for `*​/30`),
+ *      which bounds the offset search space.
+ *   3. Walk offsets [0..interval-1] looking for the smallest one that puts
+ *      all requested fire minutes ≥ MIN_GAP_MINUTES away from every
+ *      occupied minute.
+ *   4. Apply the offset by rewriting the minute field. For `*​/N` patterns
+ *      we rewrite to a comma list `(0+off, N+off, 2N+off, ...)`. For lists
+ *      we shift each element by the offset (mod 60).
+ *
+ * Returns the original cron when no offset is needed or when no
+ * collision-free offset exists in the search space (caller can decide
+ * whether to warn).
+ */
+export function computeStaggeredCron(
+  requestedCron: string,
+  existingCrons: string[]
+): StaggerResult {
+  const requestedMinutes = expandCronMinutes(requestedCron);
+  if (requestedMinutes.length === 0) {
+    return { cronExpression: requestedCron, offsetApplied: 0, collided: false };
+  }
+
+  const occupied = new Set<number>();
+  for (const cron of existingCrons) {
+    try {
+      for (const m of expandCronMinutes(cron)) occupied.add(m);
+    } catch {
+      // Skip cron expressions we cannot parse — better to allow the user's
+      // schedule than to block creation on a bad neighbor.
+    }
+  }
+
+  if (!hasCollision(requestedMinutes, occupied)) {
+    return { cronExpression: requestedCron, offsetApplied: 0, collided: false };
+  }
+
+  // Determine the interval period bounds offset search.
+  // For `*​/N * * * *` the period is N. For arbitrary lists fall back to 60.
+  const period = detectMinutePeriod(requestedCron) ?? 60;
+
+  for (let offset = 1; offset < period; offset++) {
+    const shifted = requestedMinutes.map((m) => (m + offset) % 60);
+    if (!hasCollision(shifted, occupied)) {
+      return {
+        cronExpression: applyMinuteOffset(requestedCron, offset),
+        offsetApplied: offset,
+        collided: true,
+      };
+    }
+  }
+
+  // No collision-free offset found in search space — return original and let
+  // the caller log a warning. The queue drain still prevents starvation.
+  return { cronExpression: requestedCron, offsetApplied: 0, collided: true };
+}
+
+function hasCollision(minutes: number[], occupied: Set<number>): boolean {
+  if (occupied.size === 0) return false;
+  for (const m of minutes) {
+    for (let delta = -MIN_GAP_MINUTES + 1; delta < MIN_GAP_MINUTES; delta++) {
+      const candidate = (m + delta + 60) % 60;
+      if (occupied.has(candidate)) return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Detect the minute period of a cron expression. Returns the step value for
+ * `*​/N` patterns, the gap for evenly-spaced lists like `0,30`, or null when
+ * the pattern is irregular.
+ */
+function detectMinutePeriod(cronExpression: string): number | null {
+  const minuteField = cronExpression.trim().split(/\s+/)[0];
+  const stepMatch = minuteField.match(/^\*\/(\d+)$/);
+  if (stepMatch) return parseInt(stepMatch[1], 10);
+
+  const minutes = expandCronMinutes(cronExpression);
+  if (minutes.length < 2) return null;
+  const gap = minutes[1] - minutes[0];
+  for (let i = 2; i < minutes.length; i++) {
+    if (minutes[i] - minutes[i - 1] !== gap) return null;
+  }
+  return gap;
+}
+
+/**
+ * Rewrite the minute field of a cron expression by shifting all minutes by
+ * the given offset. Replaces `*​/N` shorthand with an explicit comma list so
+ * the offset is visible to users inspecting the cron.
+ */
+function applyMinuteOffset(cronExpression: string, offset: number): string {
+  const fields = cronExpression.trim().split(/\s+/);
+  const minutes = expandCronMinutes(cronExpression);
+  const shifted = minutes
+    .map((m) => (m + offset) % 60)
+    .sort((a, b) => a - b);
+  fields[0] = shifted.join(",");
+  return fields.join(" ");
+}
+
 /**
  * Generate a human-readable description of a cron expression.
  */

package/src/lib/schedules/prompt-analyzer.ts

@@ -0,0 +1,87 @@
+/**
+ * Heuristic prompt-efficiency analyzer for scheduled prompts.
+ *
+ * Field deployments showed that scheduled tasks frequently exhausted their
+ * `maxTurns` budget because authors wrote prompts using per-item language
+ * ("for each holding, search the price"), which causes agents to issue N
+ * sequential tool calls instead of one batched call. This analyzer flags
+ * those patterns at schedule-creation time so the user can rewrite the
+ * prompt before it ever fires.
+ *
+ * The analyzer is intentionally conservative: it returns *warnings*, not
+ * errors. The chat tool surfaces them to the user but still creates the
+ * schedule. The runtime turn limit remains the hard backstop.
+ */
+
+export type WarningSeverity = "low" | "medium" | "high";
+
+export interface PromptWarning {
+  type: string;
+  severity: WarningSeverity;
+  message: string;
+}
+
+const LOOP_PATTERNS: RegExp[] = [
+  /\bfor each\b/i,
+  /\bfor every\b/i,
+  /\bone by one\b/i,
+  /\bindividually\b/i,
+  /\bper[\s-]?(symbol|stock|item|market|ticker|holding|row)\b/i,
+  /\bsearch for [^.]+ then search for\b/i,
+];
+
+const LARGE_LIST_PATTERNS: RegExp[] = [
+  /\ball \d{2,}\b/i, // "all 32 markets"
+  /\beach of the \d{2,}\b/i,
+];
+
+/**
+ * Analyze a scheduled prompt for known turn-exhaustion anti-patterns.
+ *
+ * The estimate uses a deliberately rough heuristic: count occurrences of
+ * search/fetch/lookup verbs and table operations, add 3 for orchestration
+ * overhead, and warn if the result exceeds 30. Tuned against the failures
+ * observed in production (97 / 84 / 69 turn cases all triggered).
+ */
+export function analyzePromptEfficiency(prompt: string): PromptWarning[] {
+  const warnings: PromptWarning[] = [];
+
+  for (const pattern of LOOP_PATTERNS) {
+    if (pattern.test(prompt)) {
+      warnings.push({
+        type: "loop_pattern",
+        severity: "high",
+        message:
+          "Prompt contains per-item processing language. Consider batching: instead of \"search for each stock price\", use \"search for all stock prices in one query: AMZN GOOGL NVDA...\".",
+      });
+      break;
+    }
+  }
+
+  for (const pattern of LARGE_LIST_PATTERNS) {
+    if (pattern.test(prompt)) {
+      warnings.push({
+        type: "large_list",
+        severity: "medium",
+        message:
+          "Prompt references a large number of items. Consider a bulk API call instead of iterating.",
+      });
+      break;
+    }
+  }
+
+  // Rough turn estimate. Each search-style verb ≈ 1 turn; each table op ≈ 1 turn.
+  const webSearchCount = (prompt.match(/\b(search|fetch|look up|check.*price)\b/gi) || []).length;
+  const tableOps = (prompt.match(/\b(read|query|update|insert|write).*(table|row)\b/gi) || []).length;
+  const estimatedTurns = webSearchCount + tableOps + 3;
+
+  if (estimatedTurns > 30) {
+    warnings.push({
+      type: "high_turn_estimate",
+      severity: "high",
+      message: `Estimated ${estimatedTurns}+ turns required. Consider splitting into a multi-step workflow or batching operations.`,
+    });
+  }
+
+  return warnings;
+}