Ch11. Schedules, State, Hooks

Production agents do not only respond to users. They also run checks, remember session-scoped facts, and write audit trails.

Schedules

Schedules live under agent/schedules/ and are root-agent only.

Markdown Schedule

---
cron: "0 9 * * *"
---

Prepare the daily risk report for open incidents.

Markdown schedules are fire-and-forget task-mode runs. They cannot wait for human input or OAuth sign-in. Use them for read-only or already-authorized work.

Handler Schedule

import { defineSchedule } from "eve/schedules";

export default defineSchedule({
  cron: "*/15 * * * *",
  async run({ receive, appAuth }) {
    await receive({
      message: "Check stale incidents and summarize any that need attention.",
      auth: appAuth,
    });
  },
});

Handler schedules can route work through a channel and carry app-level auth context.

Schedule Standards

Durable State

defineState gives per-session durable memory.

import { defineState } from "eve/context";

export default defineState({
  default: () => ({ definitions: {} as Record<string, string> }),
});

Use state for small, session-scoped facts such as:

• user's selected project
• current investigation id
• glossary entries gathered during a session
• workflow progress markers

Do not use state for:

• large documents
• tenant-wide memory
• OAuth token storage
• data requiring complex queries

State Use Criteria

Hooks

Hooks subscribe to runtime stream events from agent/hooks/.

import { defineHook } from "eve/hooks";

export default defineHook({
  events: {
    "action.result": async (event, ctx) => {
      await writeAuditLog({
        sessionId: ctx.session.id,
        action: event.name,
        success: event.status === "success",
      });
    },
  },
});

Use hooks for:

• audit logs
• metrics
• alerting
• warehouse ingestion
• incident timelines

Hook Failure Is Real Failure

If a hook throws, the turn/session can fail. Make hook code reliable:

• isolate network calls behind retry/timeout
• avoid throwing for optional analytics
• use a dead-letter path for audit export failure
• do not put business side effects only in hooks

Hook vs Channel Event Handler

Tool Result Narrowing

Hook event payloads can include tool results. Apply the same data-minimization mindset as toModelOutput.

Operating Patterns

Checklist