init claude-code

tools/ScheduleCronTool/CronCreateTool.ts

@@ -0,0 +1,157 @@
+import { z } from 'zod/v4'
+import { setScheduledTasksEnabled } from '../../bootstrap/state.js'
+import type { ValidationResult } from '../../Tool.js'
+import { buildTool, type ToolDef } from '../../Tool.js'
+import { cronToHuman, parseCronExpression } from '../../utils/cron.js'
+import {
+  addCronTask,
+  getCronFilePath,
+  listAllCronTasks,
+  nextCronRunMs,
+} from '../../utils/cronTasks.js'
+import { lazySchema } from '../../utils/lazySchema.js'
+import { semanticBoolean } from '../../utils/semanticBoolean.js'
+import { getTeammateContext } from '../../utils/teammateContext.js'
+import {
+  buildCronCreateDescription,
+  buildCronCreatePrompt,
+  CRON_CREATE_TOOL_NAME,
+  DEFAULT_MAX_AGE_DAYS,
+  isDurableCronEnabled,
+  isKairosCronEnabled,
+} from './prompt.js'
+import { renderCreateResultMessage, renderCreateToolUseMessage } from './UI.js'
+
+const MAX_JOBS = 50
+
+const inputSchema = lazySchema(() =>
+  z.strictObject({
+    cron: z
+      .string()
+      .describe(
+        'Standard 5-field cron expression in local time: "M H DoM Mon DoW" (e.g. "*/5 * * * *" = every 5 minutes, "30 14 28 2 *" = Feb 28 at 2:30pm local once).',
+      ),
+    prompt: z.string().describe('The prompt to enqueue at each fire time.'),
+    recurring: semanticBoolean(z.boolean().optional()).describe(
+      `true (default) = fire on every cron match until deleted or auto-expired after ${DEFAULT_MAX_AGE_DAYS} days. false = fire once at the next match, then auto-delete. Use false for "remind me at X" one-shot requests with pinned minute/hour/dom/month.`,
+    ),
+    durable: semanticBoolean(z.boolean().optional()).describe(
+      'true = persist to .claude/scheduled_tasks.json and survive restarts. false (default) = in-memory only, dies when this Claude session ends. Use true only when the user asks the task to survive across sessions.',
+    ),
+  }),
+)
+type InputSchema = ReturnType<typeof inputSchema>
+
+const outputSchema = lazySchema(() =>
+  z.object({
+    id: z.string(),
+    humanSchedule: z.string(),
+    recurring: z.boolean(),
+    durable: z.boolean().optional(),
+  }),
+)
+type OutputSchema = ReturnType<typeof outputSchema>
+export type CreateOutput = z.infer<OutputSchema>
+
+export const CronCreateTool = buildTool({
+  name: CRON_CREATE_TOOL_NAME,
+  searchHint: 'schedule a recurring or one-shot prompt',
+  maxResultSizeChars: 100_000,
+  shouldDefer: true,
+  get inputSchema(): InputSchema {
+    return inputSchema()
+  },
+  get outputSchema(): OutputSchema {
+    return outputSchema()
+  },
+  isEnabled() {
+    return isKairosCronEnabled()
+  },
+  toAutoClassifierInput(input) {
+    return `${input.cron}: ${input.prompt}`
+  },
+  async description() {
+    return buildCronCreateDescription(isDurableCronEnabled())
+  },
+  async prompt() {
+    return buildCronCreatePrompt(isDurableCronEnabled())
+  },
+  getPath() {
+    return getCronFilePath()
+  },
+  async validateInput(input): Promise<ValidationResult> {
+    if (!parseCronExpression(input.cron)) {
+      return {
+        result: false,
+        message: `Invalid cron expression '${input.cron}'. Expected 5 fields: M H DoM Mon DoW.`,
+        errorCode: 1,
+      }
+    }
+    if (nextCronRunMs(input.cron, Date.now()) === null) {
+      return {
+        result: false,
+        message: `Cron expression '${input.cron}' does not match any calendar date in the next year.`,
+        errorCode: 2,
+      }
+    }
+    const tasks = await listAllCronTasks()
+    if (tasks.length >= MAX_JOBS) {
+      return {
+        result: false,
+        message: `Too many scheduled jobs (max ${MAX_JOBS}). Cancel one first.`,
+        errorCode: 3,
+      }
+    }
+    // Teammates don't persist across sessions, so a durable teammate cron
+    // would orphan on restart (agentId would point to a nonexistent teammate).
+    if (input.durable && getTeammateContext()) {
+      return {
+        result: false,
+        message:
+          'durable crons are not supported for teammates (teammates do not persist across sessions)',
+        errorCode: 4,
+      }
+    }
+    return { result: true }
+  },
+  async call({ cron, prompt, recurring = true, durable = false }) {
+    // Kill switch forces session-only; schema stays stable so the model sees
+    // no validation errors when the gate flips mid-session.
+    const effectiveDurable = durable && isDurableCronEnabled()
+    const id = await addCronTask(
+      cron,
+      prompt,
+      recurring,
+      effectiveDurable,
+      getTeammateContext()?.agentId,
+    )
+    // Enable the scheduler so the task fires in this session. The
+    // useScheduledTasks hook polls this flag and will start watching
+    // on the next tick. For durable: false tasks the file never changes
+    // — check() reads the session store directly — but the enable flag
+    // is still what starts the tick loop.
+    setScheduledTasksEnabled(true)
+    return {
+      data: {
+        id,
+        humanSchedule: cronToHuman(cron),
+        recurring,
+        durable: effectiveDurable,
+      },
+    }
+  },
+  mapToolResultToToolResultBlockParam(output, toolUseID) {
+    const where = output.durable
+      ? 'Persisted to .claude/scheduled_tasks.json'
+      : 'Session-only (not written to disk, dies when Claude exits)'
+    return {
+      tool_use_id: toolUseID,
+      type: 'tool_result',
+      content: output.recurring
+        ? `Scheduled recurring job ${output.id} (${output.humanSchedule}). ${where}. Auto-expires after ${DEFAULT_MAX_AGE_DAYS} days. Use CronDelete to cancel sooner.`
+        : `Scheduled one-shot task ${output.id} (${output.humanSchedule}). ${where}. It will fire once then auto-delete.`,
+    }
+  },
+  renderToolUseMessage: renderCreateToolUseMessage,
+  renderToolResultMessage: renderCreateResultMessage,
+} satisfies ToolDef<InputSchema, CreateOutput>)

tools/ScheduleCronTool/CronDeleteTool.ts

@@ -0,0 +1,95 @@
+import { z } from 'zod/v4'
+import type { ValidationResult } from '../../Tool.js'
+import { buildTool, type ToolDef } from '../../Tool.js'
+import {
+  getCronFilePath,
+  listAllCronTasks,
+  removeCronTasks,
+} from '../../utils/cronTasks.js'
+import { lazySchema } from '../../utils/lazySchema.js'
+import { getTeammateContext } from '../../utils/teammateContext.js'
+import {
+  buildCronDeletePrompt,
+  CRON_DELETE_DESCRIPTION,
+  CRON_DELETE_TOOL_NAME,
+  isDurableCronEnabled,
+  isKairosCronEnabled,
+} from './prompt.js'
+import { renderDeleteResultMessage, renderDeleteToolUseMessage } from './UI.js'
+
+const inputSchema = lazySchema(() =>
+  z.strictObject({
+    id: z.string().describe('Job ID returned by CronCreate.'),
+  }),
+)
+type InputSchema = ReturnType<typeof inputSchema>
+
+const outputSchema = lazySchema(() =>
+  z.object({
+    id: z.string(),
+  }),
+)
+type OutputSchema = ReturnType<typeof outputSchema>
+export type DeleteOutput = z.infer<OutputSchema>
+
+export const CronDeleteTool = buildTool({
+  name: CRON_DELETE_TOOL_NAME,
+  searchHint: 'cancel a scheduled cron job',
+  maxResultSizeChars: 100_000,
+  shouldDefer: true,
+  get inputSchema(): InputSchema {
+    return inputSchema()
+  },
+  get outputSchema(): OutputSchema {
+    return outputSchema()
+  },
+  isEnabled() {
+    return isKairosCronEnabled()
+  },
+  toAutoClassifierInput(input) {
+    return input.id
+  },
+  async description() {
+    return CRON_DELETE_DESCRIPTION
+  },
+  async prompt() {
+    return buildCronDeletePrompt(isDurableCronEnabled())
+  },
+  getPath() {
+    return getCronFilePath()
+  },
+  async validateInput(input): Promise<ValidationResult> {
+    const tasks = await listAllCronTasks()
+    const task = tasks.find(t => t.id === input.id)
+    if (!task) {
+      return {
+        result: false,
+        message: `No scheduled job with id '${input.id}'`,
+        errorCode: 1,
+      }
+    }
+    // Teammates may only delete their own crons.
+    const ctx = getTeammateContext()
+    if (ctx && task.agentId !== ctx.agentId) {
+      return {
+        result: false,
+        message: `Cannot delete cron job '${input.id}': owned by another agent`,
+        errorCode: 2,
+      }
+    }
+    return { result: true }
+  },
+  async call({ id }) {
+    await removeCronTasks([id])
+    return { data: { id } }
+  },
+  mapToolResultToToolResultBlockParam(output, toolUseID) {
+    return {
+      tool_use_id: toolUseID,
+      type: 'tool_result',
+      content: `Cancelled job ${output.id}.`,
+    }
+  },
+  renderToolUseMessage: renderDeleteToolUseMessage,
+  renderToolResultMessage: renderDeleteResultMessage,
+} satisfies ToolDef<InputSchema, DeleteOutput>)

tools/ScheduleCronTool/CronListTool.ts

@@ -0,0 +1,97 @@
+import { z } from 'zod/v4'
+import { buildTool, type ToolDef } from '../../Tool.js'
+import { cronToHuman } from '../../utils/cron.js'
+import { listAllCronTasks } from '../../utils/cronTasks.js'
+import { truncate } from '../../utils/format.js'
+import { lazySchema } from '../../utils/lazySchema.js'
+import { getTeammateContext } from '../../utils/teammateContext.js'
+import {
+  buildCronListPrompt,
+  CRON_LIST_DESCRIPTION,
+  CRON_LIST_TOOL_NAME,
+  isDurableCronEnabled,
+  isKairosCronEnabled,
+} from './prompt.js'
+import { renderListResultMessage, renderListToolUseMessage } from './UI.js'
+
+const inputSchema = lazySchema(() => z.strictObject({}))
+type InputSchema = ReturnType<typeof inputSchema>
+
+const outputSchema = lazySchema(() =>
+  z.object({
+    jobs: z.array(
+      z.object({
+        id: z.string(),
+        cron: z.string(),
+        humanSchedule: z.string(),
+        prompt: z.string(),
+        recurring: z.boolean().optional(),
+        durable: z.boolean().optional(),
+      }),
+    ),
+  }),
+)
+type OutputSchema = ReturnType<typeof outputSchema>
+export type ListOutput = z.infer<OutputSchema>
+
+export const CronListTool = buildTool({
+  name: CRON_LIST_TOOL_NAME,
+  searchHint: 'list active cron jobs',
+  maxResultSizeChars: 100_000,
+  shouldDefer: true,
+  get inputSchema(): InputSchema {
+    return inputSchema()
+  },
+  get outputSchema(): OutputSchema {
+    return outputSchema()
+  },
+  isEnabled() {
+    return isKairosCronEnabled()
+  },
+  isConcurrencySafe() {
+    return true
+  },
+  isReadOnly() {
+    return true
+  },
+  async description() {
+    return CRON_LIST_DESCRIPTION
+  },
+  async prompt() {
+    return buildCronListPrompt(isDurableCronEnabled())
+  },
+  async call() {
+    const allTasks = await listAllCronTasks()
+    // Teammates only see their own crons; team lead (no ctx) sees all.
+    const ctx = getTeammateContext()
+    const tasks = ctx
+      ? allTasks.filter(t => t.agentId === ctx.agentId)
+      : allTasks
+    const jobs = tasks.map(t => ({
+      id: t.id,
+      cron: t.cron,
+      humanSchedule: cronToHuman(t.cron),
+      prompt: t.prompt,
+      ...(t.recurring ? { recurring: true } : {}),
+      ...(t.durable === false ? { durable: false } : {}),
+    }))
+    return { data: { jobs } }
+  },
+  mapToolResultToToolResultBlockParam(output, toolUseID) {
+    return {
+      tool_use_id: toolUseID,
+      type: 'tool_result',
+      content:
+        output.jobs.length > 0
+          ? output.jobs
+              .map(
+                j =>
+                  `${j.id} — ${j.humanSchedule}${j.recurring ? ' (recurring)' : ' (one-shot)'}${j.durable === false ? ' [session-only]' : ''}: ${truncate(j.prompt, 80, true)}`,
+              )
+              .join('\n')
+          : 'No scheduled jobs.',
+    }
+  },
+  renderToolUseMessage: renderListToolUseMessage,
+  renderToolResultMessage: renderListResultMessage,
+} satisfies ToolDef<InputSchema, ListOutput>)

tools/ScheduleCronTool/prompt.ts

@@ -0,0 +1,135 @@
+import { feature } from 'bun:bundle'
+import { getFeatureValue_CACHED_WITH_REFRESH } from '../../services/analytics/growthbook.js'
+import { DEFAULT_CRON_JITTER_CONFIG } from '../../utils/cronTasks.js'
+import { isEnvTruthy } from '../../utils/envUtils.js'
+
+const KAIROS_CRON_REFRESH_MS = 5 * 60 * 1000
+
+export const DEFAULT_MAX_AGE_DAYS =
+  DEFAULT_CRON_JITTER_CONFIG.recurringMaxAgeMs / (24 * 60 * 60 * 1000)
+
+/**
+ * Unified gate for the cron scheduling system. Combines the build-time
+ * `feature('AGENT_TRIGGERS')` flag (dead code elimination) with the runtime
+ * `tengu_kairos_cron` GrowthBook gate on a 5-minute refresh window.
+ *
+ * AGENT_TRIGGERS is independently shippable from KAIROS — the cron module
+ * graph (cronScheduler/cronTasks/cronTasksLock/cron.ts + the three tools +
+ * /loop skill) has zero imports into src/assistant/ and no feature('KAIROS')
+ * calls. The REPL.tsx kairosEnabled read is safe:
+ * kairosEnabled is unconditionally in AppStateStore with default false, so
+ * when KAIROS is off the scheduler just gets assistantMode: false.
+ *
+ * Called from Tool.isEnabled() (lazy, post-init) and inside useEffect /
+ * imperative setup, never at module scope — so the disk cache has had a
+ * chance to populate.
+ *
+ * The default is `true` — /loop is GA (announced in changelog). GrowthBook
+ * is disabled for Bedrock/Vertex/Foundry and when DISABLE_TELEMETRY /
+ * CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC are set; a `false` default would
+ * break /loop for those users (GH #31759). The GB gate now serves purely as
+ * a fleet-wide kill switch — flipping it to `false` stops already-running
+ * schedulers on their next isKilled poll tick, not just new ones.
+ *
+ * `CLAUDE_CODE_DISABLE_CRON` is a local override that wins over GB.
+ */
+export function isKairosCronEnabled(): boolean {
+  return feature('AGENT_TRIGGERS')
+    ? !isEnvTruthy(process.env.CLAUDE_CODE_DISABLE_CRON) &&
+        getFeatureValue_CACHED_WITH_REFRESH(
+          'tengu_kairos_cron',
+          true,
+          KAIROS_CRON_REFRESH_MS,
+        )
+    : false
+}
+
+/**
+ * Kill switch for disk-persistent (durable) cron tasks. Narrower than
+ * {@link isKairosCronEnabled} — flipping this off forces `durable: false` at
+ * the call() site, leaving session-only cron (in-memory, GA) untouched.
+ *
+ * Defaults to `true` so Bedrock/Vertex/Foundry and DISABLE_TELEMETRY users get
+ * durable cron. Does NOT consult CLAUDE_CODE_DISABLE_CRON (that kills the whole
+ * scheduler via isKairosCronEnabled).
+ */
+export function isDurableCronEnabled(): boolean {
+  return getFeatureValue_CACHED_WITH_REFRESH(
+    'tengu_kairos_cron_durable',
+    true,
+    KAIROS_CRON_REFRESH_MS,
+  )
+}
+
+export const CRON_CREATE_TOOL_NAME = 'CronCreate'
+export const CRON_DELETE_TOOL_NAME = 'CronDelete'
+export const CRON_LIST_TOOL_NAME = 'CronList'
+
+export function buildCronCreateDescription(durableEnabled: boolean): string {
+  return durableEnabled
+    ? 'Schedule a prompt to run at a future time — either recurring on a cron schedule, or once at a specific time. Pass durable: true to persist to .claude/scheduled_tasks.json; otherwise session-only.'
+    : 'Schedule a prompt to run at a future time within this Claude session — either recurring on a cron schedule, or once at a specific time.'
+}
+
+export function buildCronCreatePrompt(durableEnabled: boolean): string {
+  const durabilitySection = durableEnabled
+    ? `## Durability
+
+By default (durable: false) the job lives only in this Claude session — nothing is written to disk, and the job is gone when Claude exits. Pass durable: true to write to .claude/scheduled_tasks.json so the job survives restarts. Only use durable: true when the user explicitly asks for the task to persist ("keep doing this every day", "set this up permanently"). Most "remind me in 5 minutes" / "check back in an hour" requests should stay session-only.`
+    : `## Session-only
+
+Jobs live only in this Claude session — nothing is written to disk, and the job is gone when Claude exits.`
+
+  const durableRuntimeNote = durableEnabled
+    ? 'Durable jobs persist to .claude/scheduled_tasks.json and survive session restarts — on next launch they resume automatically. One-shot durable tasks that were missed while the REPL was closed are surfaced for catch-up. Session-only jobs die with the process. '
+    : ''
+
+  return `Schedule a prompt to be enqueued at a future time. Use for both recurring schedules and one-shot reminders.
+
+Uses standard 5-field cron in the user's local timezone: minute hour day-of-month month day-of-week. "0 9 * * *" means 9am local — no timezone conversion needed.
+
+## One-shot tasks (recurring: false)
+
+For "remind me at X" or "at <time>, do Y" requests — fire once then auto-delete.
+Pin minute/hour/day-of-month/month to specific values:
+  "remind me at 2:30pm today to check the deploy" → cron: "30 14 <today_dom> <today_month> *", recurring: false
+  "tomorrow morning, run the smoke test" → cron: "57 8 <tomorrow_dom> <tomorrow_month> *", recurring: false
+
+## Recurring jobs (recurring: true, the default)
+
+For "every N minutes" / "every hour" / "weekdays at 9am" requests:
+  "*/5 * * * *" (every 5 min), "0 * * * *" (hourly), "0 9 * * 1-5" (weekdays at 9am local)
+
+## Avoid the :00 and :30 minute marks when the task allows it
+
+Every user who asks for "9am" gets \`0 9\`, and every user who asks for "hourly" gets \`0 *\` — which means requests from across the planet land on the API at the same instant. When the user's request is approximate, pick a minute that is NOT 0 or 30:
+  "every morning around 9" → "57 8 * * *" or "3 9 * * *" (not "0 9 * * *")
+  "hourly" → "7 * * * *" (not "0 * * * *")
+  "in an hour or so, remind me to..." → pick whatever minute you land on, don't round
+
+Only use minute 0 or 30 when the user names that exact time and clearly means it ("at 9:00 sharp", "at half past", coordinating with a meeting). When in doubt, nudge a few minutes early or late — the user will not notice, and the fleet will.
+
+${durabilitySection}
+
+## Runtime behavior
+
+Jobs only fire while the REPL is idle (not mid-query). ${durableRuntimeNote}The scheduler adds a small deterministic jitter on top of whatever you pick: recurring tasks fire up to 10% of their period late (max 15 min); one-shot tasks landing on :00 or :30 fire up to 90 s early. Picking an off-minute is still the bigger lever.
+
+Recurring tasks auto-expire after ${DEFAULT_MAX_AGE_DAYS} days — they fire one final time, then are deleted. This bounds session lifetime. Tell the user about the ${DEFAULT_MAX_AGE_DAYS}-day limit when scheduling recurring jobs.
+
+Returns a job ID you can pass to ${CRON_DELETE_TOOL_NAME}.`
+}
+
+export const CRON_DELETE_DESCRIPTION = 'Cancel a scheduled cron job by ID'
+export function buildCronDeletePrompt(durableEnabled: boolean): string {
+  return durableEnabled
+    ? `Cancel a cron job previously scheduled with ${CRON_CREATE_TOOL_NAME}. Removes it from .claude/scheduled_tasks.json (durable jobs) or the in-memory session store (session-only jobs).`
+    : `Cancel a cron job previously scheduled with ${CRON_CREATE_TOOL_NAME}. Removes it from the in-memory session store.`
+}
+
+export const CRON_LIST_DESCRIPTION = 'List scheduled cron jobs'
+export function buildCronListPrompt(durableEnabled: boolean): string {
+  return durableEnabled
+    ? `List all cron jobs scheduled via ${CRON_CREATE_TOOL_NAME}, both durable (.claude/scheduled_tasks.json) and session-only.`
+    : `List all cron jobs scheduled via ${CRON_CREATE_TOOL_NAME} in this session.`
+}