eve 0.89.0 → 0.91.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (247) hide show
  1. package/CHANGELOG.md +39 -9
  2. package/dist/src/channel/adapter.d.ts +12 -3
  3. package/dist/src/channel/adapter.js +1 -1
  4. package/dist/src/channel/auth/definitions.d.ts +7 -20
  5. package/dist/src/channel/auth/definitions.js +1 -1
  6. package/dist/src/channel/auth/http-basic.js +1 -1
  7. package/dist/src/channel/auth/jwt-ecdsa.js +1 -1
  8. package/dist/src/channel/auth/jwt-hmac.js +1 -1
  9. package/dist/src/channel/auth/oidc.js +1 -1
  10. package/dist/src/channel/auth/result.d.ts +2 -3
  11. package/dist/src/channel/auth/result.js +1 -1
  12. package/dist/src/channel/channel-address.d.ts +1 -1
  13. package/dist/src/channel/channel-address.js +1 -1
  14. package/dist/src/channel/channel-operations.d.ts +1 -1
  15. package/dist/src/channel/schedule.js +1 -1
  16. package/dist/src/channel/types.d.ts +2 -0
  17. package/dist/src/chunks/{use-eve-agent-Bbl4H5aA.js → use-eve-agent-Bwloorf8.js} +77 -63
  18. package/dist/src/chunks/{use-eve-agent-CNpxgKEH.js → use-eve-agent-XCB0-tLX.js} +77 -63
  19. package/dist/src/cli/dev/environment.js +1 -1
  20. package/dist/src/cli/dev/tui/prompt-commands.d.ts +1 -1
  21. package/dist/src/cli/dev/tui/remote-connection-probe.js +1 -1
  22. package/dist/src/cli/dev/tui/remote-connection-types.d.ts +1 -0
  23. package/dist/src/cli/dev/tui/runner.js +2 -2
  24. package/dist/src/cli/dev/tui/status-line.d.ts +2 -2
  25. package/dist/src/cli/dev/tui/status-line.js +1 -1
  26. package/dist/src/client/agent-info-schema.d.ts +341 -326
  27. package/dist/src/client/agent-info-schema.js +1 -1
  28. package/dist/src/client/agent-info-types.d.ts +13 -10
  29. package/dist/src/client/client-error.d.ts +1 -1
  30. package/dist/src/client/client.d.ts +5 -3
  31. package/dist/src/client/client.js +1 -1
  32. package/dist/src/client/session.d.ts +1 -1
  33. package/dist/src/compiled/.vendor-stamp.json +1 -1
  34. package/dist/src/evals/target.js +1 -1
  35. package/dist/src/eve-channel/auth.d.ts +19 -0
  36. package/dist/src/eve-channel/auth.js +1 -0
  37. package/dist/src/eve-channel/index.d.ts +1 -0
  38. package/dist/src/eve-channel/index.js +1 -1
  39. package/dist/src/eve-channel/types.d.ts +23 -4
  40. package/dist/src/execution/catalog/connection-entry.js +1 -1
  41. package/dist/src/execution/coordination-dispatch-shared.js +1 -1
  42. package/dist/src/execution/dynamic-workflow/tool.js +1 -1
  43. package/dist/src/execution/proxied-deliver-step.js +1 -1
  44. package/dist/src/execution/sandbox/bash.js +2 -2
  45. package/dist/src/execution/session/active-turn.js +1 -1
  46. package/dist/src/execution/session/admission.d.ts +6 -0
  47. package/dist/src/execution/session/admission.js +1 -1
  48. package/dist/src/execution/session/delivery-facts.js +1 -1
  49. package/dist/src/execution/session/next-input.d.ts +2 -2
  50. package/dist/src/execution/session/next-input.js +1 -1
  51. package/dist/src/execution/session/program.js +1 -1
  52. package/dist/src/execution/session-inbox/inbox.d.ts +2 -2
  53. package/dist/src/execution/session-inbox/inbox.js +1 -1
  54. package/dist/src/execution/session-inbox/protocol.js +1 -1
  55. package/dist/src/execution/tools/agent-router-workflow.js +1 -1
  56. package/dist/src/harness/compaction/engine.js +2 -2
  57. package/dist/src/harness/current-messages.js +1 -1
  58. package/dist/src/harness/emission.d.ts +3 -0
  59. package/dist/src/harness/emission.js +1 -1
  60. package/dist/src/harness/facts.d.ts +5 -2
  61. package/dist/src/harness/facts.js +1 -1
  62. package/dist/src/harness/model-call/call.d.ts +7 -1
  63. package/dist/src/harness/model-call/call.js +3 -1
  64. package/dist/src/harness/provider-tool-history.d.ts +8 -0
  65. package/dist/src/harness/provider-tool-history.js +1 -1
  66. package/dist/src/harness/session-machine/transitions.d.ts +3 -2
  67. package/dist/src/harness/step/after-model.js +1 -1
  68. package/dist/src/harness/step/context.js +1 -1
  69. package/dist/src/harness/step/intake.js +1 -1
  70. package/dist/src/harness/step/prompt.js +1 -1
  71. package/dist/src/harness/tool-history-repair.d.ts +2 -0
  72. package/dist/src/harness/tool-history-repair.js +1 -1
  73. package/dist/src/harness/tool-loop.js +1 -1
  74. package/dist/src/internal/application/stamped-package-version.js +1 -1
  75. package/dist/src/internal/authored-module-graph.js +1 -1
  76. package/dist/src/internal/nitro/routes/agent-info/build-agent-info-response.d.ts +2 -2
  77. package/dist/src/protocol/routes.d.ts +7 -1
  78. package/dist/src/protocol/routes.js +1 -1
  79. package/dist/src/protocol/session-events/families/delivery.d.ts +5 -3
  80. package/dist/src/protocol/session-events/families/delivery.js +1 -1
  81. package/dist/src/protocol/session-projection/fold.js +1 -1
  82. package/dist/src/public/channels/discord/hitl.js +1 -1
  83. package/dist/src/public/channels/github/githubChannel.js +1 -1
  84. package/dist/src/public/channels/github/state.d.ts +7 -0
  85. package/dist/src/public/channels/github/state.js +1 -1
  86. package/dist/src/public/channels/mcp.js +1 -1
  87. package/dist/src/public/channels/slack/hitl.d.ts +2 -1
  88. package/dist/src/public/channels/slack/hitl.js +3 -3
  89. package/dist/src/public/channels/slack/interaction-cards.js +1 -1
  90. package/dist/src/public/channels/slack/request-card-render.js +1 -1
  91. package/dist/src/public/channels/teams/hitl.js +1 -1
  92. package/dist/src/public/channels/teams/verify.js +1 -1
  93. package/dist/src/public/channels/telegram/telegramChannel.js +1 -1
  94. package/dist/src/public/connections/index.d.ts +1 -1
  95. package/dist/src/public/definitions/channel.js +1 -1
  96. package/dist/src/public/definitions/connections/tool-call.d.ts +2 -2
  97. package/dist/src/public/definitions/hook.d.ts +90 -7
  98. package/dist/src/public/definitions/hook.js +1 -1
  99. package/dist/src/public/hooks/index.d.ts +3 -2
  100. package/dist/src/reactions/continuation.d.ts +19 -0
  101. package/dist/src/reactions/continuation.js +1 -0
  102. package/dist/src/reactions/frame.js +1 -1
  103. package/dist/src/reactions/intents.d.ts +10 -4
  104. package/dist/src/reactions/intents.js +1 -1
  105. package/dist/src/reactions/kinds/hook.js +1 -1
  106. package/dist/src/reactions/runner.js +1 -1
  107. package/dist/src/reactions/state.d.ts +15 -2
  108. package/dist/src/reactions/state.js +1 -1
  109. package/dist/src/runtime/channels/registry.d.ts +2 -2
  110. package/dist/src/runtime/channels/registry.js +1 -1
  111. package/dist/src/runtime/connections/approval-scope.d.ts +9 -0
  112. package/dist/src/runtime/connections/approval-scope.js +1 -0
  113. package/dist/src/runtime/connections/mcp-client.d.ts +1 -1
  114. package/dist/src/runtime/connections/mcp-client.js +1 -1
  115. package/dist/src/runtime/connections/provided-arguments.js +1 -1
  116. package/dist/src/runtime/resolve-connection.js +1 -1
  117. package/dist/src/runtime/subagents/workflow.js +1 -1
  118. package/dist/src/setup/primitives/open-url.js +1 -1
  119. package/dist/src/setup/scaffold/create/project.js +1 -1
  120. package/dist/src/shared/agent-info-access.d.ts +5 -0
  121. package/dist/src/shared/agent-info-access.js +1 -0
  122. package/dist/src/shared/connection-types.d.ts +21 -4
  123. package/dist/src/shared/value-delta.d.ts +5 -4
  124. package/dist/src/shared/value-delta.js +1 -1
  125. package/dist/src/svelte/index.js +1 -1
  126. package/dist/src/svelte/use-eve-agent.js +1 -1
  127. package/dist/src/tools/provided/ask-question-workflow.js +1 -1
  128. package/dist/src/tools/provided/sleep-workflow.js +1 -1
  129. package/dist/src/tools/provided/web-fetch.js +1 -1
  130. package/dist/src/vue/index.js +1 -1
  131. package/dist/src/vue/use-eve-agent.js +1 -1
  132. package/docs/agent-config.md +199 -222
  133. package/docs/channels/chat-sdk.mdx +60 -64
  134. package/docs/channels/custom.mdx +265 -280
  135. package/docs/channels/discord.mdx +176 -123
  136. package/docs/channels/eve.mdx +136 -204
  137. package/docs/channels/github.mdx +24 -22
  138. package/docs/channels/linear.mdx +30 -30
  139. package/docs/channels/linq.mdx +25 -13
  140. package/docs/channels/mcp.mdx +154 -116
  141. package/docs/channels/overview.mdx +31 -32
  142. package/docs/channels/photon.mdx +32 -56
  143. package/docs/channels/slack.mdx +538 -375
  144. package/docs/channels/teams.mdx +40 -26
  145. package/docs/channels/telegram.mdx +13 -13
  146. package/docs/channels/twilio.mdx +11 -11
  147. package/docs/code-extension.mdx +40 -42
  148. package/docs/concepts/built-in-tools.md +89 -57
  149. package/docs/concepts/context-control.md +20 -20
  150. package/docs/concepts/default-harness.md +20 -36
  151. package/docs/concepts/execution-model-and-durability.mdx +96 -160
  152. package/docs/concepts/project-structure.mdx +21 -14
  153. package/docs/concepts/security-model.md +27 -27
  154. package/docs/concepts/sessions-runs-and-streaming.md +184 -194
  155. package/docs/concepts/state.md +7 -15
  156. package/docs/connections/mcp.mdx +109 -93
  157. package/docs/connections/openapi.mdx +57 -59
  158. package/docs/connections/overview.mdx +205 -170
  159. package/docs/evals/assertions.mdx +36 -29
  160. package/docs/evals/cases.mdx +38 -42
  161. package/docs/evals/judge.mdx +21 -29
  162. package/docs/evals/overview.mdx +42 -38
  163. package/docs/evals/reporters.mdx +54 -27
  164. package/docs/evals/running.mdx +15 -8
  165. package/docs/evals/targets.mdx +17 -18
  166. package/docs/evals/tool-stubs.mdx +111 -97
  167. package/docs/experimental/dynamic-schedules.mdx +118 -63
  168. package/docs/extensions.md +58 -65
  169. package/docs/getting-started.mdx +4 -6
  170. package/docs/guides/auth-and-route-protection.md +100 -70
  171. package/docs/guides/client/continuations.mdx +23 -26
  172. package/docs/guides/client/messages.mdx +47 -66
  173. package/docs/guides/client/output-schema.mdx +8 -8
  174. package/docs/guides/client/overview.mdx +47 -41
  175. package/docs/guides/client/streaming.mdx +62 -71
  176. package/docs/guides/decide.md +24 -79
  177. package/docs/guides/deployment/meta.json +1 -1
  178. package/docs/guides/deployment/overview.md +27 -18
  179. package/docs/guides/deployment/self-hosted-operations.md +99 -0
  180. package/docs/guides/deployment/self-hosting.md +63 -80
  181. package/docs/guides/deployment/vercel.mdx +31 -27
  182. package/docs/guides/deployment/workflow-worlds.md +100 -0
  183. package/docs/guides/dev-tui.md +48 -41
  184. package/docs/guides/dynamic-capabilities.md +49 -50
  185. package/docs/guides/frontend/nextjs.mdx +2 -2
  186. package/docs/guides/frontend/nuxt.mdx +11 -11
  187. package/docs/guides/frontend/overview.mdx +1 -1
  188. package/docs/guides/frontend/sveltekit.mdx +11 -11
  189. package/docs/guides/frontend/tanstack.mdx +16 -16
  190. package/docs/guides/frontend/use-eve-agent-svelte.mdx +21 -21
  191. package/docs/guides/frontend/use-eve-agent-vue.mdx +22 -22
  192. package/docs/guides/frontend/use-eve-agent.mdx +25 -25
  193. package/docs/guides/hooks.md +152 -106
  194. package/docs/guides/instrumentation/agent-runs.mdx +26 -30
  195. package/docs/guides/instrumentation/instrumentation.mdx +49 -76
  196. package/docs/guides/instrumentation/meta.json +1 -1
  197. package/docs/guides/instrumentation/otel.mdx +113 -179
  198. package/docs/guides/prepare-for-1-0.md +23 -1
  199. package/docs/guides/remote-agents.md +125 -187
  200. package/docs/guides/self-modification.md +18 -18
  201. package/docs/guides/session-context.md +16 -16
  202. package/docs/install-integrations.mdx +26 -24
  203. package/docs/instructions.mdx +37 -42
  204. package/docs/memory/custom-provider.md +35 -41
  205. package/docs/memory/file.md +93 -76
  206. package/docs/memory/overview.mdx +145 -156
  207. package/docs/patterns/durable-cross-channel-notifications.md +15 -19
  208. package/docs/patterns/dynamic-scheduling.md +19 -23
  209. package/docs/patterns/multi-tenant-approvals.md +17 -22
  210. package/docs/patterns/multi-tenant-auth.md +43 -42
  211. package/docs/patterns/multi-tenant-memory.md +39 -36
  212. package/docs/patterns/voice-notes.md +3 -3
  213. package/docs/protocols/acp.md +13 -13
  214. package/docs/protocols/ucp.mdx +7 -7
  215. package/docs/reference/agent-files.md +6 -6
  216. package/docs/reference/cli.md +99 -98
  217. package/docs/reference/telemetry.md +1 -1
  218. package/docs/reference/typescript-api.md +52 -53
  219. package/docs/responsible-use.md +2 -2
  220. package/docs/sandbox/custom-providers.mdx +60 -56
  221. package/docs/sandbox/default.mdx +23 -24
  222. package/docs/sandbox/docker.mdx +16 -10
  223. package/docs/sandbox/index.mdx +93 -61
  224. package/docs/sandbox/just-bash.mdx +17 -11
  225. package/docs/sandbox/troubleshooting.mdx +29 -23
  226. package/docs/sandbox/vercel.mdx +45 -52
  227. package/docs/schedules.mdx +65 -54
  228. package/docs/skills.mdx +74 -49
  229. package/docs/subagents/index.mdx +97 -136
  230. package/docs/tools/human-in-the-loop.md +160 -90
  231. package/docs/tools/meta.json +1 -1
  232. package/docs/tools/overview.mdx +229 -237
  233. package/docs/tools/tasks.md +118 -117
  234. package/docs/tools/workflows.mdx +447 -543
  235. package/docs/tutorial/connect-a-warehouse.mdx +11 -13
  236. package/docs/tutorial/first-agent.mdx +14 -16
  237. package/docs/tutorial/guard-the-spend.mdx +6 -8
  238. package/docs/tutorial/how-it-runs.mdx +8 -8
  239. package/docs/tutorial/query-sample-data.mdx +8 -8
  240. package/docs/tutorial/remember-definitions.mdx +4 -4
  241. package/docs/tutorial/run-analysis.mdx +20 -22
  242. package/docs/tutorial/ship-it.mdx +19 -19
  243. package/docs/tutorial/team-playbooks.mdx +9 -9
  244. package/docs/use-cases.mdx +13 -11
  245. package/package.json +1 -1
  246. package/docs/guides/instrumentation/migration.md +0 -96
  247. package/docs/tools/tasks-upgrade.md +0 -218
@@ -8,31 +8,36 @@ description: "Create and manage creator-owned recurring or one-time schedules at
8
8
  representative to have the feature enabled for your organization.
9
9
  </Callout>
10
10
 
11
- Use `defineDynamicSchedules` when users or agents need to create recurring or one-time schedules at runtime. Export the definition from `agent/schedules/`; eve derives its identity from the file path. The definition configures management tools and an occurrence callback. It does not create a schedule or set its timing.
11
+ `defineDynamicSchedules` lets users and agents create recurring or one-time schedules while the agent runs. Export the definition from a file in `agent/schedules/`; the file path names it. Use it when a user or the model picks the timing. For fixed cron jobs written in code, use [`defineSchedule`](../schedules) instead.
12
12
 
13
- This API is experimental and may change. Import it from `eve/experimental/schedules`. For fixed, code-authored cron jobs, use [`defineSchedule`](../schedules) instead. For a self-hosted alternative with application-owned storage, see [Dynamic scheduling](../patterns/dynamic-scheduling).
13
+ The definition gives the model tools to manage schedules, and gives you a `run` callback that runs each time a schedule fires. Each firing is an occurrence. This API is experimental and may change. Import it from `eve/experimental/schedules`.
14
14
 
15
15
  ## Define scheduled work
16
16
 
17
- The model supplies schema-defined payload. eve captures the authenticated creator separately and resolves current execution auth whenever an occurrence fires.
17
+ The model supplies a payload that matches `inputSchema`. eve records who created the schedule separately, and checks that creator's current access each time the schedule fires.
18
18
 
19
19
  ```ts title="agent/schedules/requests.ts"
20
20
  import { byPrincipal, defineDynamicSchedules } from "eve/experimental/schedules";
21
21
  import { z } from "zod";
22
22
  import slack from "../channels/slack";
23
+ // Application code: look up users and destinations.
23
24
  import { resolveCurrentUser } from "../lib/identity";
24
25
  import { resolveCreatorDm, resolveAuthorizedTeamChannel } from "../lib/schedule-policy";
25
26
 
26
27
  export default defineDynamicSchedules({
27
28
  description: "Schedule Slack tasks for the creator's DM or authorized team channel.",
29
+ // Required: validates the payload the model or client supplies.
28
30
  inputSchema: z
29
31
  .object({
30
32
  task: z.string().min(1).max(2000),
31
33
  destination: z.enum(["my-dm", "team-channel"]),
32
34
  })
33
35
  .strict(),
36
+ // Optional: byPrincipal is the default.
34
37
  scope: byPrincipal,
38
+ // Required: resolve the creator's current access before each run.
35
39
  auth: ({ principal }) => resolveCurrentUser(principal),
40
+ // Required: runs each time the schedule fires.
36
41
  async run({ payload, occurrence, to, auth }) {
37
42
  const target =
38
43
  payload.destination === "my-dm"
@@ -45,58 +50,55 @@ export default defineDynamicSchedules({
45
50
  });
46
51
  ```
47
52
 
48
- The identity and destination helpers are application code. `inputSchema`, `auth`, and `run` are required. `provider` is optional and defaults to `vercelScheduleProvider()`. Pass a provider explicitly to use another backend or configure the Vercel endpoint.
53
+ ### Options
49
54
 
50
- `scope` defaults to `byPrincipal`, isolating management by authenticated principal type, authenticator, issuer, and ID, plus application and path-derived definition identity. A custom scope resolver must authorize each operation before returning a namespace; return `null` to deny.
55
+ | Field | Default | Purpose |
56
+ | ---------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
57
+ | `inputSchema` | Required | Validates the payload from the model or client. |
58
+ | `auth` | Required | Resolves the creator to current access. See [Revalidate creator identity](#revalidate-creator-identity). |
59
+ | `run` | Required | Runs each time a schedule fires. See [Handle occurrences and retries](#handle-occurrences-and-retries). |
60
+ | `description` | None | Text added to each management tool's description. |
61
+ | `scope` | `byPrincipal` | Decides which caller can manage which schedules. |
62
+ | `provider` | `vercelScheduleProvider()` | Stores schedules and fires them. See [Choose a provider and test locally](#choose-a-provider-and-test-locally). |
63
+ | `preparePayload` | None | Checks and reshapes the payload before eve saves it. See [Prepare payloads and destinations](#prepare-payloads-and-destinations). |
64
+ | `tool` | `true` | How the model reaches the management tools. See [Expose management tools](#expose-management-tools). |
65
+ | `approval` | User approval for changes | Approval policy for each operation the model calls. |
66
+ | `events` | None | `occurrence.dispatched` and `occurrence.failed` handlers. |
51
67
 
52
- ## Revalidate creator identity
53
-
54
- `auth({ principal, payload, occurrence })` resolves the stored creator reference to current execution auth. Look up current account status and permissions rather than replaying credentials or roles captured at creation. Return `null` to deny; thrown errors remain eligible for provider retries.
55
-
56
- The returned principal type, authenticator, issuer, ID, and subject must match the creator reference. eve does not fall back to app identity. Manual invocation does not replace the creator with the invoker. Tool and connection authorization still applies during execution.
57
-
58
- ## Prepare payloads and destinations
59
-
60
- The generated creation and update tools validate their `payload` field with your `inputSchema`. Without `preparePayload`, eve validates payloads before persistence and again before dispatch. The complete provider envelope is limited to 64 KB; store JSON data and stable references, not credentials or sensitive recipient details.
61
-
62
- Optional `preparePayload(input, context)` validates application policy, resolves caller context, and returns the stored shape. It runs on creation and payload replacement, after input validation and scope authorization, before persistence. For model calls, eve prepares before asking for approval and provides the prepared payload to `approval.create` or `approval.update`. It prepares again before writing and rejects the call if the prepared result differs from the approved snapshot. Preparation errors reach the model before a person is asked. Authenticated code calling the client prepares once before writing, without model approval.
63
-
64
- `auth`, `run`, and occurrence events infer the prepared return type. Declare `preparePayload` before these callbacks or give it an explicit return type for TypeScript contextual inference. Without preparation, payload type comes from the schema.
65
-
66
- The input schema does not describe prepared output. eve bounds and JSON-validates the persisted envelope but does not structurally revalidate prepared application data against the input schema at execution. Authored code owns that persisted contract; validate it explicitly if needed. Preparation may repeat on write retries, so avoid irreversible effects. Reads, timing-only updates, state changes, and occurrences never rerun it.
67
-
68
- ```ts
69
- preparePayload(input, context) {
70
- const target = resolveDestination(input.destination, context);
71
- return { task: input.task, target };
72
- },
73
- ```
74
-
75
- `resolveDestination` is application code. For channel delivery, it can validate trusted caller context and capture channel/workspace references without exposing those fields in the model-facing schema. Reject callers that lack the required channel context, including delegated work when appropriate. Payload replacement recaptures the destination and creator from the updating caller.
76
-
77
- Destination IDs are optional. Conditional logic in `run` can derive a DM from creator identity, select an authorized configured channel, or look up a destination using another payload value. A schema may expose explicit IDs when the model can obtain them, but valid IDs do not prove access. Management scope does not authorize sending to every destination. Validate model-selected destinations against the creator's current permissions.
78
-
79
- The original creation conversation is not captured automatically. To support “reply in the exact thread where I created this,” persist an authorized thread reference through `preparePayload` or application code. Creator identity alone cannot recover that thread. Runtime lookups can follow changed configuration; persist a destination reference when the destination must stay fixed.
68
+ `scope` decides who can manage a schedule. `byPrincipal` limits each caller to their own schedules, keyed by identity type, authenticator, issuer, and ID, plus the application and definition. A custom `scope` function must authorize each operation before it returns a namespace. Return `null` to deny.
80
69
 
81
70
  ## Expose management tools
82
71
 
83
- Each definition contributes tools for `create`, `get`, `list`, `update`, `enable`, `disable`, `invoke`, and `delete`. Each has its own object-rooted schema, approval policy, and readable action label. For example, `agent/schedules/billing/requests.ts` generates `schedule__billing-requests__create`, `schedule__billing-requests__update`, and the other operation names. There is no combined manage tool or operation field.
72
+ Each definition adds one tool for each operation: `create`, `get`, `list`, `update`, `enable`, `disable`, `invoke`, and `delete`. Each tool has its own schema, approval policy, and action label. For example, `agent/schedules/billing/requests.ts` generates `schedule__billing-requests__create`, `schedule__billing-requests__update`, and so on.
84
73
 
85
- Creation takes `{ name, expression, payload }`. Updates take `{ name, expression?, payload? }` and require at least an expression or a complete replacement payload. Listing takes optional `{ cursor, limit }`, with limits from 1 through 100. The remaining tools take `{ name }` using the unique identifier from receipts or reads.
74
+ | Tool | Input |
75
+ | -------------------- | --------------------------------------------------------------------------- |
76
+ | `create` | `{ name, expression, payload }` |
77
+ | `update` | `{ name, expression?, payload? }`, with an expression or a complete payload |
78
+ | `list` | Optional `{ cursor, limit }`, with `limit` from 1 through 100 |
79
+ | All other operations | `{ name }`, the unique name from receipts or reads |
86
80
 
87
- Set `tool: true` (the default) for direct tools, `tool: "deferred"` for catalog-discovered tools, or `tool: false` for code-only scheduling. Deferred operations keep the same names, schemas, approval policies, and authorization checks; the model finds them with `eve__search` and calls them with `eve__tool`. See [Dynamic capabilities](../guides/dynamic-capabilities#dynamic-tools).
81
+ Set `tool` to choose how the model reaches these operations:
88
82
 
89
- Reads need no approval by default; mutations require user approval. Configure top-level `approval`, keyed by operation, with ordinary request/response policies. Separate tool identities keep `once()` grants independent. Create and payload-replacement update policies receive a typed `payload` containing prepared data; `toolInput.payload` also contains prepared rather than raw data. Timing-only update policies receive `payload: undefined`.
83
+ | `tool` | Behavior |
84
+ | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
85
+ | `true` (default) | Direct tools. |
86
+ | `"deferred"` | The same tools, names, schemas, approval policies, and authorization checks, discovered with `eve__search` and called with `eve__tool`. See [Dynamic capabilities](../guides/dynamic-capabilities#dynamic-tools). |
87
+ | `false` | No tools; code-only scheduling. |
88
+
89
+ By default, reads need no approval and changes need user approval. Set top-level `approval`, keyed by operation, with ordinary request and response policies. Each operation's `once()` grants are independent.
90
90
 
91
91
  ```ts
92
92
  approval: {
93
+ // `payload` is the prepared payload; `target.audience` is an application field.
93
94
  create: ({ payload }) => payload.target.audience === "private" ? "not-applicable" : "user-approval",
95
+ // `payload` is undefined for a timing-only update.
94
96
  update: ({ payload }) => payload?.target.audience === "private" ? "not-applicable" : "user-approval",
95
- delete: always(),
97
+ delete: always(), // from eve/tools/approval
96
98
  },
97
99
  ```
98
100
 
99
- Import `always` from `eve/tools/approval`; `target.audience` above is an application-owned prepared field. Combining `tool: false` with `approval` is rejected by TypeScript and runtime validation: these policies apply only to model calls, not code using `schedules(definition)`. Approvals do not bypass scope authorization or configure tools a future agent session uses.
101
+ `toolInput.payload` is also the prepared payload. Approval policies apply only to model calls, not to code that uses `schedules(definition)`. So eve rejects `approval` with `tool: false`, in TypeScript and at runtime. Approvals don't bypass `scope` checks.
100
102
 
101
103
  ## Use the authenticated client
102
104
 
@@ -115,19 +117,25 @@ export default defineTool({
115
117
  });
116
118
  ```
117
119
 
118
- Call the client inside an active eve context, not at module scope. Client creation accepts `{ name, expression, payload }`. The supplied `name` is a display label and may repeat; it must start with an ASCII letter or digit and contain only letters, digits, `.`, `_`, or `-`, up to 256 characters. eve truncates labels longer than 218 characters and appends `--` plus a UUID to allocate a unique management name.
120
+ Call the client inside an active eve context, not at module scope.
121
+
122
+ The `name` you pass is a display label, and several schedules can share it. It must start with an ASCII letter or digit, contain only letters, digits, `.`, `_`, or `-`, and have at most 256 characters. eve truncates it to 218 characters and appends `--` plus a UUID to make the unique management name.
119
123
 
120
- Receipts and reads include `name` (use this exact value for management) and `displayName`. Callbacks and events keep the unique identifier in `occurrence.name` and expose the readable label as `occurrence.displayName`. Approval applies to the supplied label, timing, and payload before the unique identifier is allocated.
124
+ Receipts and reads return that unique `name`, which management calls take, plus `displayName`. In callbacks and events, they are `occurrence.name` and `occurrence.displayName`. Approval covers the label, timing, and payload, before the unique name exists.
121
125
 
122
- Both generated tools and authored clients check scope authorization on every operation, including during scheduled turns and local delegated work. Scheduled sessions remain unattended: mutation tools that require human approval cannot wait for it. Authorize unattended operations explicitly with `approval` policies, or use an authenticated client in authored code; neither bypasses scope checks.
126
+ Generated tools and the client check `scope` on every operation, including in scheduled turns and local delegated work. Scheduled sessions have no one present, so tools that change schedules and need human approval can't wait for it. Authorize these operations with `approval` policies, or use the client in your own code. Neither one bypasses `scope` checks.
123
127
 
124
- Authored tools, hooks, and channel events can read `ctx.session.schedule`: `undefined` for ordinary work, or `{ definition, instance?, occurrenceId? }` for scheduled work. Static schedules that run as a user are included; this is framework provenance, not an auth attribute. Custom scope policies can inspect `context.session.schedule` to deny or restrict scheduled callers. A new ordinary inbound message clears scheduled-turn context; approval/input responses preserve it.
128
+ Your tools, hooks, and channel events can read `ctx.session.schedule`. It is `undefined` for ordinary work. Scheduled work, including static schedules that run as a user, gets `{ definition, instance?, occurrenceId? }`. It records where the work came from, not who is authorized. A custom `scope` function can read `context.session.schedule` to restrict scheduled callers. A new ordinary inbound message clears it; approval and input responses keep it.
125
129
 
126
130
  ## Set timing
127
131
 
128
- For “in one minute,” use `expression: { type: "delay", minutes: 1 }`. eve resolves the time when the approved write executes and rounds up to minute precision, adding up to 59 seconds before provider/execution latency. Delays accept whole minutes from 1 through 525,600. Approval time is not part of the delay. A separate client retry resolves a new time; this is not a mutation-idempotency guarantee.
132
+ | `expression.type` | Fields | Use for |
133
+ | ----------------- | ---------------------------------------------------------- | ------------------------------------------------ |
134
+ | `delay` | `minutes`, a whole number from 1 through 525,600 | “In one minute”: `{ type: "delay", minutes: 1 }` |
135
+ | `single` | `at`, a `YYYY-MM-DDTHH:mm` local datetime, IANA `timezone` | One absolute time |
136
+ | `cron` | `cron`, a five-field expression, IANA `timezone` | Recurring work |
129
137
 
130
- Use `single` with a `YYYY-MM-DDTHH:mm` local datetime and IANA timezone for absolute times, or `cron` with a five-field expression and timezone for recurring work. Omitted timezones mean UTC. Relative delays do not need a timezone.
138
+ Omit `timezone` to use UTC. A delay starts when the approved write runs, not when approval is requested. It rounds up to the next minute, which adds up to 59 seconds before provider and execution latency. A separate client retry computes a new time, so a delay isn't idempotent across retries.
131
139
 
132
140
  ```ts
133
141
  const client = await schedules(requests);
@@ -137,32 +145,23 @@ const created = await client.create({
137
145
  payload: { task: "Summarize open issues.", destination: "my-dm" },
138
146
  });
139
147
 
148
+ // A timing-only update keeps the payload and creator.
140
149
  await client.update(created.name, {
141
150
  expression: { type: "cron", cron: "0 10 * * 1-5", timezone: "America/New_York" },
142
151
  });
143
152
  ```
144
153
 
145
- Import `schedules` from `eve/experimental/schedules` and `requests` from your definition module. Run this code in an active eve context.
146
-
147
154
  ## Update and control schedules
148
155
 
149
- `get` and `list` return identity, timing, state, and timestamps, not payload or creator data. New schedules are active; creation has no state option. Use `disable` to pause future scheduling.
156
+ `get` and `list` return identity, timing, state, and timestamps, not payload or creator data. New schedules are always active. Use `disable` to pause future runs.
150
157
 
151
- `client.update(name, patch)` changes timing, replaces the complete payload, or does both. Timing-only updates preserve the stored payload and creator and do not call `preparePayload`. Payload replacement validates the complete new input, reruns preparation, and captures the updating caller as the new creator. It is not a partial merge. In a shared scope, authorizing payload replacement therefore also authorizes a change of execution identity.
158
+ `client.update(name, patch)` changes timing, replaces the whole payload, or both. Timing-only updates keep the stored payload and creator and skip `preparePayload`. Payload replacement isn't a merge. It validates the complete new input, reruns preparation, and makes the updating caller the new creator. In a shared `scope`, permission to replace the payload is also permission to change who the schedule runs as.
152
159
 
153
- Updates preserve the management name, schedule ID, state, and dispatch target. They cannot rename a schedule or change its state; use `enable` or `disable` for state changes. Updating an inactive or completed schedule does not activate it.
160
+ Updates keep the management name, schedule ID, state, and destination. An update doesn't activate an inactive or completed schedule; use `enable` or `disable` to change state.
154
161
 
155
- Updates, enable, disable, and delete affect future scheduling, not emitted callbacks or running sessions. Use delete-and-create only when you need a separate schedule identity; replacement is not atomic.
162
+ Updates, `enable`, `disable`, and `delete` affect future runs, not callbacks already started or running sessions. Delete-and-create gives a new schedule identity, but isn't atomic.
156
163
 
157
- `invoke(name)` requests an additional occurrence as the stored creator. Inactive schedules may be invoked; completed schedules cannot. Manual invocation does not consume a pending one-time fire. Enqueue acceptance does not prove callback or agent success.
158
-
159
- ## Handle occurrences and retries
160
-
161
- `run` receives `payload`, `occurrence`, `auth`, `to`, and `waitUntil`. It may start zero or several sessions or perform application work directly. `to(channel, target).send(message, options)` is bound to the resolved creator; no auth argument is needed or accepted. It starts fresh, unattended sessions through an authored channel, even when the target names an existing thread. It does not steer an existing conversation. `options` takes `context`, `history`, `idempotencyKey`, `outputSchema`, and `title`, as on a route handler's [`to().send()`](../channels/custom#cross-channel-hand-off). It takes no `turnPolicy`, because a send never reaches a session the schedule didn't start.
162
-
163
- eve awaits the callback and its registered `waitUntil` promises before reporting `occurrence.dispatched`. That event includes `sessionIds`; it means dispatch succeeded, not that the agent completed its task or delivered a successful result. Channels own output delivery and session-level failure reporting. Unattended sessions cannot wait for approvals or questions; configure tools accordingly.
164
-
165
- Provider retries may repeat the callback and start new sessions. This is an at-least-once callback contract, not exactly-once side effects. Use `occurrence.executionId` together with the schedule/resource identity to deduplicate application effects where the destination supports it. For sessions, pass it in the send's key, for example `` idempotencyKey: `${occurrence.executionId}:digest` ``. A retried callback's send with the same key and target then reaches the session the first attempt started instead of starting another. Keys are scoped to the schedule, and the [usual limits](../channels/custom#retried-deliveries) apply. An observer failure can also cause callback retry. `occurrence.failed` reports permanent provider failures or exhaustion of the provider retry budget.
164
+ `invoke(name)` requests an extra run as the stored creator. It works on inactive schedules but not completed ones, and doesn't use up a pending one-time run. An accepted invocation doesn't mean the callback or agent succeeded.
166
165
 
167
166
  ## Choose a provider and test locally
168
167
 
@@ -172,15 +171,71 @@ The default `vercelScheduleProvider()` supports these environments:
172
171
  | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
173
172
  | Vercel production | Requires feature-flag enablement for your organization. Hosted Vercel Schedules delivers occurrences through Vercel Queues. |
174
173
  | `eve dev` without local Vercel Schedules | Process-local storage, with no background clock. Call `invoke` through the client to dispatch an occurrence. |
175
- | `vc dev` with local Schedules and Queues support | Local Vercel Schedules stores timing, and eve polls local Queues to deliver due occurrences automatically. |
174
+ | `vc dev` with local Schedules and Queues support | Local Vercel Schedules stores timing, and eve delivers due occurrences automatically through local Queues. |
176
175
  | Vercel preview or self-hosted production | The default provider rejects operations. Use a different provider or the [application-managed scheduling pattern](../patterns/dynamic-scheduling). |
177
176
 
178
- For automatic local delivery, start eve through `vc dev` with a Vercel CLI that supports local Schedules and Queues. Plain `eve dev` still uses the in-memory fallback. Local queue-delivery errors appear in the dev server logs and retry after five seconds.
177
+ Under `vc dev`, local queue errors appear in the dev server logs and retry after five seconds.
178
+
179
+ Import `vercelScheduleProvider` from `eve/experimental/schedules/vercel` to configure the Vercel endpoint explicitly. Import the in-memory provider from `eve/experimental/schedules/testing` for code-driven tests.
180
+
181
+ ## Handle occurrences and retries
182
+
183
+ `run` receives `payload`, `occurrence`, `auth`, `to`, and `waitUntil`. It can start any number of sessions or do application work directly.
184
+
185
+ `to(channel, target).send(message, options)` runs as the resolved creator and takes no auth argument. `options` takes `context`, `history`, `idempotencyKey`, `outputSchema`, and `title`, as on a route handler's [`to().send()`](../channels/custom#cross-channel-hand-off). It takes no `turnPolicy`, because a send only reaches sessions the schedule started. It always starts a new session with no one present, through one of your channels, even when the target names an existing thread. Those sessions can't wait for approvals or questions, so configure tools to match.
186
+
187
+ After the callback and its `waitUntil` promises finish, eve calls `occurrence.dispatched` with `sessionIds`. That event means the callback succeeded, not that the agent finished its task. Channels send the output and report session failures.
188
+
189
+ Callbacks run at least once. Provider retries, including after an `events` handler fails, can repeat the callback and start new sessions. Deduplicate side effects with `occurrence.executionId` plus the schedule or resource identity. For sessions, put it in the send's key, as in `` idempotencyKey: `${occurrence.executionId}:digest` ``. A retried send with the same key and target then reaches the session the first attempt started. Keys are scoped to the schedule, and the [usual limits](../channels/custom#retried-deliveries) apply. `occurrence.failed` reports a permanent provider failure or a provider that ran out of retries.
190
+
191
+ ## Revalidate creator identity
192
+
193
+ `auth({ principal, payload, occurrence })` turns the stored creator reference into current access. `principal` identifies the creator; it holds no credentials or permissions. Look up current account status and permissions instead of replaying credentials or roles captured at creation. Return `null` to deny. A thrown error lets the provider retry.
194
+
195
+ The returned identity type, authenticator, issuer, ID, and subject must match the creator reference. eve never falls back to app identity. Manual `invoke` runs as the creator, not the caller. Tool and connection authorization still applies during the run.
196
+
197
+ ## Prepare payloads and destinations
198
+
199
+ Without `preparePayload`, eve validates payloads before saving and again before each run. Each saved write, including timing and payload, is limited to 64 KB. Store JSON data and stable references, not credentials or sensitive recipient details.
200
+
201
+ `preparePayload(input, context)` checks application policy, reads the caller's context, and returns the shape eve saves. It runs on creation and payload replacement, after input validation and `scope` authorization:
202
+
203
+ | Caller | When preparation runs |
204
+ | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
205
+ | Model tool call | Before approval, so errors reach the model before a person is asked, and again before writing. Approval policies receive the prepared payload. eve rejects the call if the second result differs. |
206
+ | Authenticated client code | Once, before writing, with no approval. |
207
+
208
+ Preparation can repeat when a write is retried, so avoid irreversible effects. Reads, timing-only updates, state changes, and runs never call it.
209
+
210
+ `auth`, `run`, and occurrence events infer the prepared return type. Declare `preparePayload` before them, or give it an explicit return type. Without preparation, the payload type comes from the schema.
211
+
212
+ Before each run, eve checks only the saved payload's size and JSON validity, not `inputSchema`. Validate the prepared shape yourself if needed.
213
+
214
+ ```ts
215
+ preparePayload(input, context) {
216
+ // resolveDestination is application code.
217
+ const target = resolveDestination(input.destination, context);
218
+ return { task: input.task, target };
219
+ },
220
+ ```
221
+
222
+ For channel messages, `preparePayload` can check trusted caller context and save channel and workspace references that the model-facing schema doesn't expose. Reject callers that lack the required channel context, including delegated work when appropriate. Payload replacement captures the destination and creator again from the updating caller.
223
+
224
+ Destination IDs are optional. `run` can derive a DM from the creator, pick an authorized configured channel, or look up a destination from another payload value. A schema may expose explicit IDs, but a valid ID doesn't prove access, and `scope` doesn't authorize sending everywhere. Check model-selected destinations against the creator's current permissions.
225
+
226
+ eve doesn't save the conversation that created a schedule. To reply in that thread, save an authorized thread reference through `preparePayload` or application code. Save a destination reference whenever the destination must stay fixed, because lookups at run time follow configuration changes.
227
+
228
+ ## Troubleshooting
179
229
 
180
- Import `vercelScheduleProvider` from `eve/experimental/schedules/vercel` to configure the Vercel endpoint explicitly. The in-memory provider is also available from `eve/experimental/schedules/testing` for code-driven tests.
230
+ | What you see | What to do |
231
+ | ------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
232
+ | `vercelScheduleProvider() requires a Vercel production deployment or eve dev.` | Run under `eve dev` or a Vercel production deployment, or pass a different `provider`. |
233
+ | ``Vercel Schedules currently supports production deployments only. Deploy with `vercel --prod`.`` | Deploy to production, because the default provider rejects preview deployments. |
234
+ | `Prepared schedule write exceeds the 64 KB limit, including timing and payload.` | Store stable references instead of large data in the payload. |
181
235
 
182
236
  ## What to read next
183
237
 
184
238
  - [Schedules](../schedules): author fixed cron jobs with `defineSchedule`.
239
+ - [Dynamic scheduling](../patterns/dynamic-scheduling): a self-hosted alternative with application-owned storage.
185
240
  - [Channels](../channels/overview): deliver schedule output to users.
186
241
  - [Sessions, runs & streaming](../concepts/sessions-runs-and-streaming): inspect a scheduled run.