stagent 0.9.6 → 0.11.0

package/src/lib/chat/system-prompt.ts

@@ -1,6 +1,28 @@
 /**
  * Enhanced system prompt for the Stagent chat LLM.
  * Provides identity, tool catalog, and intent routing guidance.
+ *
+ * ## Tier 0 vs CLAUDE.md partition (DD-CE-002)
+ *
+ * When the chat engine runs on the `claude-code` runtime, the Claude Agent
+ * SDK loads project-level `CLAUDE.md` and user-level `~/.claude/CLAUDE.md`
+ * via `settingSources: ["user", "project"]`. To avoid double-prompting,
+ * this system prompt MUST stay scoped to:
+ *
+ *   (a) Stagent identity
+ *   (b) Stagent tool catalog and routing
+ *   (c) Stagent domain semantics (delay steps, enrich_table, workflow dedup)
+ *   (d) LLM interaction style
+ *
+ * Content that is project-specific (coding conventions, testing rules,
+ * git workflow, repo-specific gotchas) belongs in `CLAUDE.md` — NOT here.
+ *
+ * Audit (2026-04-13): every current block in this prompt passes the rubric.
+ * No content migration was required for Stagent's current CLAUDE.md state.
+ * The worktree note on line 110 is borderline and flagged for revisit if
+ * CLAUDE.md gains an explicit worktree section.
+ *
+ * Reference: features/chat-claude-sdk-skills.md (§"Tier 0 vs CLAUDE.md").
  */
 
 export const STAGENT_SYSTEM_PROMPT = `You are Stagent, an AI workspace assistant for managing software projects, tasks, workflows, documents, and schedules. You are a full alternate UI for the Stagent app — users can do everything through chat that they can do in the GUI.
@@ -21,11 +43,12 @@ export const STAGENT_SYSTEM_PROMPT = `You are Stagent, an AI workspace assistant
 
 ### Workflows
 - list_workflows: List all workflows
-- create_workflow: Create a multi-step workflow with a definition
+- create_workflow: Create a multi-step workflow with a definition. Steps can be task steps (profile + prompt) or **delay steps** (delayDuration like '3d', '2h', '30m', '1w') that pause the workflow before the next step. Delay steps enable time-distributed sequences.
 - get_workflow: Get workflow details and definition
 - update_workflow: Update a draft workflow
 - delete_workflow: Delete a workflow and its children [requires approval]
 - execute_workflow: Start workflow execution [requires approval]
+- resume_workflow: Resume a paused (delayed) workflow immediately instead of waiting for its scheduled resume time [requires approval]
 - get_workflow_status: Get current execution status with step progress
 - find_related_documents: Search the project document pool for documents to attach as workflow context
 
@@ -58,9 +81,30 @@ export const STAGENT_SYSTEM_PROMPT = `You are Stagent, an AI workspace assistant
 - get_usage_summary: Get token and cost statistics over a time period
 - get_settings: Read current configuration (auth method, budgets, runtime)
 
+### Tables
+Structured user data lives in Stagent tables (separate from Stagent's own internal records). Every table tool takes a tableId; use list_tables or search_table to find them first.
+- list_tables: List all user tables in a project
+- get_table_schema: Get a table's columns, types, and metadata
+- query_table: Filter, sort, and paginate rows with operators (eq, neq, gt, gte, lt, lte, contains, starts_with, in, is_empty, is_not_empty)
+- search_table: Full-text search across row cell values
+- aggregate_table: Compute count/sum/avg/min/max over a column with optional group-by
+- add_rows: Insert one or more rows
+- update_row: Update a single row's cell values
+- delete_rows: Delete rows matching a filter [requires approval]
+- create_table: Create a new empty table with specified columns
+- import_document_as_table: Parse an uploaded document into a new table
+- export_table: Export rows as CSV/JSON
+- add_column / update_column / delete_column / reorder_columns: Schema edits
+- list_triggers / create_trigger / update_trigger / delete_trigger: Per-row trigger evaluation
+- get_table_history: Read change history for a table
+- save_as_template: Save a table's shape as a reusable template
+- **enrich_table**: Run an agent task for every row in a table matching a filter, writing results to a target column. Use for bulk research, classification, content generation, or any table-row fan-out pattern. Generates the optimal loop workflow, binds each row as context, skips already-populated rows for idempotency [requires approval]
+
 ## When to Use Which Tools
 - CRUD operations ("create a task", "list workflows", "update the schedule") → Use the appropriate Stagent tool
 - Execution ("run this task", "execute the workflow") → Use execute_task / execute_workflow
+- Time-distributed multi-step sequences ("send email, wait 3 days, follow up", "drip campaign", "onboarding flow") → Use create_workflow with delay steps in a sequence pattern. Do NOT create separate workflows and schedules for each touch — a single workflow with inline delay steps is the idiomatic pattern.
+- Bulk per-row operations ("research every contact", "classify all tickets", "enrich rows missing X", "for each row do Y") → Use enrich_table. Do NOT hand-roll a loop workflow for this — enrich_table already generates the optimal loop, handles row-data binding, wires up the postAction writeback, and skips already-populated rows for idempotency.
 - Approvals ("approve that", "allow it", "deny the request") → Use respond_notification
 - Monitoring ("what's pending?", "any approval requests?") → Use list_notifications
 - Usage ("how much have I spent?", "token usage this week") → Use get_usage_summary
@@ -82,6 +126,9 @@ Be proactive with tools. If the user asks about project status, use list_tasks t
 - If a project context is active, scope operations to it unless the user specifies otherwise.
 - Tools marked [requires approval] will prompt the user before executing.
 - For workflows, valid patterns are: sequence, parallel, checkpoint, planner-executor, swarm, loop.
+- **Delay steps** (sequence pattern only): a step with \`delayDuration\` (format: Nm|Nh|Nd|Nw, bounds 1m..30d) pauses the workflow between task steps. Format examples: "30m", "2h", "3d", "1w". Delay steps must have NO profile or prompt — they are pure waits. Use them for outreach sequences, drip campaigns, cooling periods, staged rollouts. A paused workflow resumes automatically when its scheduled time arrives, or immediately when the user clicks "Resume Now".
+- **enrich_table idempotency:** \`enrich_table\` skips rows where the target column already has a non-empty value. If the user wants to overwrite existing values, explain that force re-enrichment is not supported in v1 — they must manually clear the target column first (e.g. via update_row) before re-running.
+- **create_workflow dedup:** Before calling \`create_workflow\`, call \`list_workflows\` (filtered by the current project) to check whether a similar workflow already exists. If the user asks to "redesign", "redo", or "update" an existing workflow, call \`update_workflow\` on the matching row instead of creating a new one. \`create_workflow\` performs its own near-duplicate check and will return \`{status: "similar-found", matches: [...]}\` instead of inserting when it finds one — when that happens, surface the matches to the user and confirm intent. Only pass \`force: true\` to \`create_workflow\` when the user has explicitly confirmed they want a second workflow alongside a similar one (e.g., "v2", "alternate approach").
 - When a working directory is specified, always create files relative to it. Never assume the git root is the working directory — they may differ in worktree environments.
 
 ## Document Pool Awareness

package/src/lib/chat/tool-catalog.ts

@@ -11,9 +11,9 @@ import {
   Clock,
   Globe,
   Sun,
-  CheckCheck,
   Sparkles,
   Table2,
+  Zap,
 } from "lucide-react";
 import type { LucideIcon } from "lucide-react";
 
@@ -33,7 +33,8 @@ export type ToolGroup =
   | "Settings"
   | "Chat"
   | "Browser"
-  | "Utility";
+  | "Utility"
+  | "Session";
 
 export interface ToolCatalogEntry {
   /** MCP tool name, e.g. "list_tasks" */
@@ -51,6 +52,7 @@ export interface ToolCatalogEntry {
 // ── Group → Icon mapping ─────────────────────────────────────────────────
 
 export const TOOL_GROUP_ICONS: Record<ToolGroup, LucideIcon> = {
+  Session: Zap,
   Tasks: ListTodo,
   Projects: FolderKanban,
   Workflows: GitBranch,
@@ -69,6 +71,7 @@ export const TOOL_GROUP_ICONS: Record<ToolGroup, LucideIcon> = {
 
 /** Display order for groups in the popover */
 export const TOOL_GROUP_ORDER: ToolGroup[] = [
+  "Session",
   "Tasks",
   "Projects",
   "Workflows",
@@ -110,6 +113,11 @@ const STAGENT_TOOLS: ToolCatalogEntry[] = [
   { name: "execute_workflow", description: "Start executing a workflow", group: "Workflows", paramHint: "workflowId" },
   { name: "delete_workflow", description: "Delete a workflow", group: "Workflows", paramHint: "workflowId" },
   { name: "get_workflow_status", description: "Get workflow execution progress", group: "Workflows", paramHint: "workflowId" },
+  { name: "list_blueprints", description: "List available workflow blueprints", group: "Workflows", paramHint: "domain, search" },
+  { name: "get_blueprint", description: "Get blueprint details and variables", group: "Workflows", paramHint: "blueprintId" },
+  { name: "instantiate_blueprint", description: "Create a workflow from a blueprint", group: "Workflows", paramHint: "blueprintId, variables" },
+  { name: "create_blueprint", description: "Create a custom workflow blueprint", group: "Workflows", paramHint: "yaml" },
+  { name: "delete_blueprint", description: "Delete a custom blueprint", group: "Workflows", paramHint: "blueprintId" },
 
   // ── Schedules ──
   { name: "list_schedules", description: "List scheduled prompt loops", group: "Schedules", paramHint: "status" },
@@ -134,6 +142,9 @@ const STAGENT_TOOLS: ToolCatalogEntry[] = [
   // ── Profiles ──
   { name: "list_profiles", description: "List available agent profiles", group: "Profiles" },
   { name: "get_profile", description: "Get agent profile configuration", group: "Profiles", paramHint: "profileId" },
+  { name: "create_profile", description: "Create a new agent profile", group: "Profiles", paramHint: "config, skillMd" },
+  { name: "update_profile", description: "Update a custom agent profile", group: "Profiles", paramHint: "profileId, config, skillMd" },
+  { name: "delete_profile", description: "Delete a custom agent profile", group: "Profiles", paramHint: "profileId" },
 
   // ── Usage ──
   { name: "get_usage_summary", description: "Get spending and token usage stats", group: "Usage", paramHint: "days" },
@@ -142,6 +153,12 @@ const STAGENT_TOOLS: ToolCatalogEntry[] = [
   { name: "get_settings", description: "Get current Stagent settings", group: "Settings", paramHint: "key" },
   { name: "set_settings", description: "Update a Stagent setting (approval required)", group: "Settings", paramHint: "key, value" },
 
+  // ── Skills ──
+  { name: "list_skills", description: "List all discoverable skills (user + project scopes)", group: "Skills" },
+  { name: "get_skill", description: "Get full SKILL.md content + metadata for one skill", group: "Skills", paramHint: "id" },
+  { name: "activate_skill", description: "Bind a skill to a conversation — SKILL.md is injected into every turn's system prompt. Pass mode='add' to compose (runtime-gated).", group: "Skills", paramHint: "conversationId, skillId, mode?" },
+  { name: "deactivate_skill", description: "Clear the active skill from a conversation", group: "Skills", paramHint: "conversationId" },
+
   // ── Tables ──
   { name: "list_tables", description: "List tables, filter by project or source", group: "Tables", paramHint: "projectId, source" },
   { name: "get_table_schema", description: "Get column definitions for a table", group: "Tables", paramHint: "tableId" },
@@ -171,11 +188,13 @@ const STAGENT_TOOLS: ToolCatalogEntry[] = [
   { name: "delete_trigger", description: "Delete a trigger", group: "Tables", paramHint: "tableId, triggerId" },
   { name: "get_table_history", description: "Get row change history for a table", group: "Tables", paramHint: "tableId, limit" },
   { name: "save_as_template", description: "Save a table as a reusable template", group: "Tables", paramHint: "tableId, name, category" },
+  { name: "enrich_table", description: "Bulk-enrich rows by running an agent task per row, writing results to a target column", group: "Tables", paramHint: "tableId, prompt, targetColumn, filter" },
 
   // ── Chat History ──
   { name: "list_conversations", description: "List recent chat conversations", group: "Chat", paramHint: "search, limit" },
   { name: "get_conversation_messages", description: "Get messages from a past conversation", group: "Chat", paramHint: "conversationId, limit" },
   { name: "search_messages", description: "Search across all conversations", group: "Chat", paramHint: "query" },
+
 ];
 
 const BROWSER_TOOLS: ToolCatalogEntry[] = [
@@ -187,6 +206,18 @@ const BROWSER_TOOLS: ToolCatalogEntry[] = [
   { name: "take_snapshot", description: "Take an accessibility snapshot", group: "Browser" },
 ];
 
+const SESSION_ENTRIES: ToolCatalogEntry[] = [
+  { name: "clear", description: "Start a new conversation", group: "Session", behavior: "execute_immediately" },
+  { name: "compact", description: "Summarize and compact conversation history", group: "Session", behavior: "execute_immediately" },
+  { name: "export", description: "Save current conversation as a document", group: "Session", behavior: "execute_immediately" },
+  { name: "help", description: "Show chat shortcuts and commands", group: "Session", behavior: "execute_immediately" },
+  { name: "settings", description: "Open Stagent settings", group: "Session", behavior: "execute_immediately" },
+  { name: "new-task", description: "Create a new task", group: "Session", paramHint: "title" },
+  { name: "new-workflow", description: "Create a new workflow", group: "Session", paramHint: "name" },
+  { name: "new-schedule", description: "Create a new schedule", group: "Session", paramHint: "name, interval" },
+  { name: "new-from-template", description: "Start a conversation from a workflow blueprint", group: "Session", behavior: "execute_immediately" },
+];
+
 const UTILITY_ENTRIES: ToolCatalogEntry[] = [
   { name: "toggle_theme", description: "Switch dark/light mode", group: "Utility", behavior: "execute_immediately" },
   { name: "mark_all_read", description: "Mark all notifications as read", group: "Utility", behavior: "execute_immediately" },
@@ -202,13 +233,13 @@ export function getToolCatalog(opts?: { includeBrowser?: boolean }): ToolCatalog
 
   if (withBrowser) {
     if (!cachedWithBrowser) {
-      cachedWithBrowser = [...STAGENT_TOOLS, ...BROWSER_TOOLS, ...UTILITY_ENTRIES];
+      cachedWithBrowser = [...SESSION_ENTRIES, ...STAGENT_TOOLS, ...BROWSER_TOOLS, ...UTILITY_ENTRIES];
     }
     return cachedWithBrowser;
   }
 
   if (!cachedCatalog) {
-    cachedCatalog = [...STAGENT_TOOLS, ...UTILITY_ENTRIES];
+    cachedCatalog = [...SESSION_ENTRIES, ...STAGENT_TOOLS, ...UTILITY_ENTRIES];
   }
   return cachedCatalog;
 }

package/src/lib/chat/tools/__tests__/enrich-table-tool.test.ts

@@ -0,0 +1,127 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+const { mockCreateEnrichmentWorkflow } = vi.hoisted(() => ({
+  mockCreateEnrichmentWorkflow: vi.fn(),
+}));
+
+vi.mock("@/lib/tables/enrichment", () => ({
+  createEnrichmentWorkflow: mockCreateEnrichmentWorkflow,
+}));
+
+// Stub the rest of @/lib/data/tables so importing table-tools doesn't drag in DB.
+vi.mock("@/lib/data/tables", () => ({
+  listTables: vi.fn(),
+  getTable: vi.fn(),
+  createTable: vi.fn(),
+  updateTable: vi.fn(),
+  deleteTable: vi.fn(),
+  listRows: vi.fn(),
+  addRows: vi.fn(),
+  updateRow: vi.fn(),
+  deleteRows: vi.fn(),
+  listTemplates: vi.fn(),
+  cloneFromTemplate: vi.fn(),
+  addColumn: vi.fn(),
+  updateColumn: vi.fn(),
+  deleteColumn: vi.fn(),
+  reorderColumns: vi.fn(),
+}));
+
+vi.mock("@/lib/tables/history", () => ({ getTableHistory: vi.fn() }));
+vi.mock("@/lib/tables/import", () => ({
+  extractStructuredData: vi.fn(),
+  inferColumnTypes: vi.fn(),
+  importRows: vi.fn(),
+  createImportRecord: vi.fn(),
+}));
+
+import { tableTools } from "../table-tools";
+
+function findEnrichTool() {
+  const tools = tableTools({ projectId: "proj_test" });
+  const tool = tools.find((t) => t.name === "enrich_table");
+  if (!tool) throw new Error("enrich_table tool not registered");
+  return tool;
+}
+
+describe("enrich_table tool", () => {
+  beforeEach(() => {
+    mockCreateEnrichmentWorkflow.mockReset();
+  });
+
+  it("is registered in tableTools", () => {
+    const tools = tableTools({ projectId: "proj_test" });
+    const names = tools.map((t) => t.name);
+    expect(names).toContain("enrich_table");
+  });
+
+  it("delegates to createEnrichmentWorkflow with the supplied params", async () => {
+    mockCreateEnrichmentWorkflow.mockResolvedValueOnce({
+      workflowId: "wf_xyz",
+      rowCount: 4,
+    });
+
+    const tool = findEnrichTool();
+    const result = await tool.handler({
+      tableId: "tbl_contacts",
+      prompt: "Find LinkedIn for {{row.name}}",
+      targetColumn: "linkedin",
+      filter: { column: "linkedin", operator: "is_empty" },
+      agentProfile: "sales-researcher",
+    });
+
+    expect(mockCreateEnrichmentWorkflow).toHaveBeenCalledWith(
+      "tbl_contacts",
+      expect.objectContaining({
+        prompt: "Find LinkedIn for {{row.name}}",
+        targetColumn: "linkedin",
+        filter: { column: "linkedin", operator: "is_empty" },
+        agentProfile: "sales-researcher",
+      })
+    );
+
+    expect(result.isError).toBeFalsy();
+    const payload = JSON.parse(result.content[0].text) as {
+      workflowId: string;
+      rowCount: number;
+    };
+    expect(payload.workflowId).toBe("wf_xyz");
+    expect(payload.rowCount).toBe(4);
+  });
+
+  it("falls back to ctx.projectId when projectId is not supplied", async () => {
+    mockCreateEnrichmentWorkflow.mockResolvedValueOnce({
+      workflowId: "wf_a",
+      rowCount: 1,
+    });
+
+    const tool = findEnrichTool();
+    await tool.handler({
+      tableId: "tbl_x",
+      prompt: "x",
+      targetColumn: "linkedin",
+    });
+
+    const callArg = mockCreateEnrichmentWorkflow.mock.calls[0][1] as {
+      projectId?: string;
+    };
+    expect(callArg.projectId).toBe("proj_test");
+  });
+
+  it("returns an error result when createEnrichmentWorkflow throws", async () => {
+    mockCreateEnrichmentWorkflow.mockRejectedValueOnce(
+      new Error("Table tbl_missing not found")
+    );
+
+    const tool = findEnrichTool();
+    const result = await tool.handler({
+      tableId: "tbl_missing",
+      prompt: "x",
+      targetColumn: "linkedin",
+    });
+
+    expect(result.isError).toBe(true);
+    const payload = JSON.parse(result.content[0].text) as { error: string };
+    expect(payload.error).toContain("not found");
+  });
+});

package/src/lib/chat/tools/__tests__/profile-tools.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, it, vi, beforeEach } from "vitest";
+
+vi.mock("@/lib/agents/profiles/list-fused-profiles", () => ({
+  listFusedProfiles: vi.fn(async (projectDir: string | null) =>
+    [
+      {
+        id: "general",
+        name: "General",
+        description: "Reg",
+        domain: "general",
+        tags: [],
+      },
+      projectDir
+        ? {
+            id: "project-only",
+            name: "Project Only",
+            description: "Proj",
+            domain: "skill",
+            tags: [],
+            origin: "filesystem-project",
+          }
+        : null,
+    ].filter(Boolean)
+  ),
+}));
+
+describe("list_profiles chat tool", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("returns fused profiles when called with a projectDir", async () => {
+    const { getListProfilesTool } = await import("@/lib/chat/tools/profile-tools");
+    const tool = getListProfilesTool("/fake/project");
+    const result = await tool.handler({});
+    // ok() wraps data as MCP content — parse the JSON text back out
+    const text = result.content[0].text;
+    const list = JSON.parse(text) as { id: string }[];
+    expect(Array.isArray(list)).toBe(true);
+    expect(list.some((p) => p.id === "project-only")).toBe(true);
+  });
+
+  it("returns registry-only profiles when projectDir is null", async () => {
+    const { getListProfilesTool } = await import("@/lib/chat/tools/profile-tools");
+    const tool = getListProfilesTool(null);
+    const result = await tool.handler({});
+    const text = result.content[0].text;
+    const list = JSON.parse(text) as { id: string }[];
+    expect(list.every((p) => p.id !== "project-only")).toBe(true);
+  });
+});

package/src/lib/chat/tools/__tests__/schedule-tools.test.ts

@@ -0,0 +1,261 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { z } from "zod";
+
+interface ScheduleRow {
+  id: string;
+  maxTurns: number | null;
+  [key: string]: unknown;
+}
+
+const { mockState } = vi.hoisted(() => ({
+  mockState: {
+    rows: [] as ScheduleRow[],
+    lastInsertValues: null as Record<string, unknown> | null,
+    lastUpdateValues: null as Record<string, unknown> | null,
+  },
+}));
+
+vi.mock("@/lib/db", () => {
+  const selectBuilder = {
+    from() { return this; },
+    where() { return this; },
+    orderBy() { return this; },
+    limit() { return this; },
+    get() { return Promise.resolve(mockState.rows[0]); },
+    then<TResolve>(resolve: (rows: ScheduleRow[]) => TResolve) {
+      return Promise.resolve(mockState.rows).then(resolve);
+    },
+  };
+  return {
+    db: {
+      select: () => selectBuilder,
+      insert: () => ({
+        values: (v: Record<string, unknown>) => {
+          mockState.lastInsertValues = v;
+          mockState.rows = [{ id: "sched-1", maxTurns: null, ...v } as ScheduleRow];
+          return Promise.resolve();
+        },
+      }),
+      update: () => ({
+        set: (v: Record<string, unknown>) => {
+          mockState.lastUpdateValues = v;
+          mockState.rows[0] = { ...mockState.rows[0], ...v } as ScheduleRow;
+          return { where: () => Promise.resolve() };
+        },
+      }),
+      delete: () => ({ where: () => Promise.resolve() }),
+    },
+  };
+});
+
+vi.mock("@/lib/db/schema", () => ({
+  schedules: {
+    id: "id",
+    status: "status",
+    projectId: "projectId",
+    updatedAt: "updatedAt",
+    cronExpression: "cronExpression",
+  },
+}));
+
+vi.mock("drizzle-orm", () => ({
+  eq: () => ({}),
+  and: () => ({}),
+  desc: () => ({}),
+  like: () => ({}),
+}));
+
+vi.mock("@/lib/schedules/interval-parser", () => ({
+  parseInterval: () => "*/30 * * * *",
+  computeNextFireTime: () => new Date("2026-04-11T10:00:00Z"),
+  computeStaggeredCron: (cron: string) => ({
+    cronExpression: cron,
+    offsetApplied: 0,
+    collided: false,
+  }),
+}));
+
+vi.mock("@/lib/schedules/nlp-parser", () => ({
+  parseNaturalLanguage: () => null,
+}));
+
+vi.mock("@/lib/schedules/prompt-analyzer", () => ({
+  analyzePromptEfficiency: () => [],
+}));
+
+import { scheduleTools } from "../schedule-tools";
+
+function getTool(name: string) {
+  const tools = scheduleTools({ projectId: "proj-1" } as never);
+  const tool = tools.find((t) => t.name === name);
+  if (!tool) throw new Error(`Tool not found: ${name}`);
+  return tool;
+}
+
+function parseArgs(toolName: string, args: unknown) {
+  const tool = getTool(toolName);
+  return z.object(tool.zodShape).safeParse(args);
+}
+
+beforeEach(() => {
+  mockState.rows = [];
+  mockState.lastInsertValues = null;
+  mockState.lastUpdateValues = null;
+});
+
+describe("create_schedule maxTurns Zod validation", () => {
+  const base = {
+    name: "test",
+    prompt: "hello",
+    interval: "every 30 minutes",
+  };
+
+  it("accepts a valid maxTurns value", () => {
+    const result = parseArgs("create_schedule", { ...base, maxTurns: 50 });
+    expect(result.success).toBe(true);
+  });
+
+  it("accepts omitted maxTurns (inherit default)", () => {
+    const result = parseArgs("create_schedule", base);
+    expect(result.success).toBe(true);
+  });
+
+  it("rejects maxTurns below 10", () => {
+    const result = parseArgs("create_schedule", { ...base, maxTurns: 9 });
+    expect(result.success).toBe(false);
+  });
+
+  it("rejects maxTurns above 500", () => {
+    const result = parseArgs("create_schedule", { ...base, maxTurns: 501 });
+    expect(result.success).toBe(false);
+  });
+
+  it("rejects non-integer maxTurns", () => {
+    const result = parseArgs("create_schedule", { ...base, maxTurns: 50.5 });
+    expect(result.success).toBe(false);
+  });
+
+  it("rejects explicit null on create (only update supports clear-to-null)", () => {
+    const result = parseArgs("create_schedule", { ...base, maxTurns: null });
+    expect(result.success).toBe(false);
+  });
+});
+
+describe("update_schedule maxTurns Zod validation", () => {
+  const base = { scheduleId: "sched-1" };
+
+  it("accepts a valid maxTurns value", () => {
+    const result = parseArgs("update_schedule", { ...base, maxTurns: 100 });
+    expect(result.success).toBe(true);
+  });
+
+  it("accepts explicit null to clear an override", () => {
+    const result = parseArgs("update_schedule", { ...base, maxTurns: null });
+    expect(result.success).toBe(true);
+  });
+
+  it("accepts omitted maxTurns (unchanged)", () => {
+    const result = parseArgs("update_schedule", base);
+    expect(result.success).toBe(true);
+  });
+
+  it("rejects out-of-range maxTurns on update", () => {
+    const result = parseArgs("update_schedule", { ...base, maxTurns: 9 });
+    expect(result.success).toBe(false);
+  });
+});
+
+describe("create_schedule maxTurns persistence", () => {
+  it("writes maxTurns to the insert payload when provided", async () => {
+    const tool = getTool("create_schedule");
+    await tool.handler({
+      name: "test",
+      prompt: "hello",
+      interval: "every 30 minutes",
+      maxTurns: 75,
+    });
+    expect(mockState.lastInsertValues).not.toBeNull();
+    expect(mockState.lastInsertValues?.maxTurns).toBe(75);
+  });
+
+  it("writes null to maxTurns when omitted (inherit default)", async () => {
+    const tool = getTool("create_schedule");
+    await tool.handler({
+      name: "test",
+      prompt: "hello",
+      interval: "every 30 minutes",
+    });
+    expect(mockState.lastInsertValues?.maxTurns).toBe(null);
+  });
+
+  it("sets maxTurnsSetAt to a Date when maxTurns is provided", async () => {
+    const tool = getTool("create_schedule");
+    await tool.handler({
+      name: "test",
+      prompt: "hello",
+      interval: "every 30 minutes",
+      maxTurns: 75,
+    });
+    expect(mockState.lastInsertValues?.maxTurnsSetAt).toBeInstanceOf(Date);
+  });
+
+  it("sets maxTurnsSetAt to null when maxTurns is omitted", async () => {
+    const tool = getTool("create_schedule");
+    await tool.handler({
+      name: "test",
+      prompt: "hello",
+      interval: "every 30 minutes",
+    });
+    expect(mockState.lastInsertValues?.maxTurnsSetAt).toBe(null);
+  });
+});
+
+describe("update_schedule maxTurns persistence", () => {
+  beforeEach(() => {
+    mockState.rows = [{
+      id: "sched-1",
+      name: "existing",
+      status: "active",
+      maxTurns: 50,
+    } as ScheduleRow];
+  });
+
+  it("writes the new maxTurns value when provided", async () => {
+    const tool = getTool("update_schedule");
+    await tool.handler({ scheduleId: "sched-1", maxTurns: 120 });
+    expect(mockState.lastUpdateValues?.maxTurns).toBe(120);
+  });
+
+  it("writes null when explicitly clearing the override", async () => {
+    const tool = getTool("update_schedule");
+    await tool.handler({ scheduleId: "sched-1", maxTurns: null });
+    expect(mockState.lastUpdateValues).not.toBeNull();
+    expect("maxTurns" in (mockState.lastUpdateValues ?? {})).toBe(true);
+    expect(mockState.lastUpdateValues?.maxTurns).toBe(null);
+  });
+
+  it("does not touch maxTurns when the field is omitted", async () => {
+    const tool = getTool("update_schedule");
+    await tool.handler({ scheduleId: "sched-1", name: "renamed" });
+    expect("maxTurns" in (mockState.lastUpdateValues ?? {})).toBe(false);
+  });
+
+  it("sets maxTurnsSetAt to a Date when maxTurns is set to a number", async () => {
+    const tool = getTool("update_schedule");
+    await tool.handler({ scheduleId: "sched-1", maxTurns: 120 });
+    expect(mockState.lastUpdateValues?.maxTurnsSetAt).toBeInstanceOf(Date);
+  });
+
+  it("sets maxTurnsSetAt to null when maxTurns is cleared", async () => {
+    const tool = getTool("update_schedule");
+    await tool.handler({ scheduleId: "sched-1", maxTurns: null });
+    expect("maxTurnsSetAt" in (mockState.lastUpdateValues ?? {})).toBe(true);
+    expect(mockState.lastUpdateValues?.maxTurnsSetAt).toBe(null);
+  });
+
+  it("does not touch maxTurnsSetAt when maxTurns is omitted", async () => {
+    const tool = getTool("update_schedule");
+    await tool.handler({ scheduleId: "sched-1", name: "renamed" });
+    expect("maxTurnsSetAt" in (mockState.lastUpdateValues ?? {})).toBe(false);
+  });
+});