eve 0.90.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 (185) hide show
  1. package/CHANGELOG.md +34 -23
  2. package/dist/src/channel/auth/http-basic.js +1 -1
  3. package/dist/src/channel/channel-operations.d.ts +1 -1
  4. package/dist/src/channel/types.d.ts +2 -0
  5. package/dist/src/cli/dev/tui/prompt-commands.d.ts +1 -1
  6. package/dist/src/client/session.d.ts +1 -1
  7. package/dist/src/compiled/.vendor-stamp.json +1 -1
  8. package/dist/src/execution/dynamic-workflow/tool.js +1 -1
  9. package/dist/src/execution/proxied-deliver-step.js +1 -1
  10. package/dist/src/execution/sandbox/bash.js +2 -2
  11. package/dist/src/execution/session/active-turn.js +1 -1
  12. package/dist/src/execution/session/admission.d.ts +6 -0
  13. package/dist/src/execution/session/admission.js +1 -1
  14. package/dist/src/execution/session/delivery-facts.js +1 -1
  15. package/dist/src/execution/session/next-input.d.ts +2 -2
  16. package/dist/src/execution/session/next-input.js +1 -1
  17. package/dist/src/execution/session/program.js +1 -1
  18. package/dist/src/execution/session-inbox/inbox.d.ts +2 -2
  19. package/dist/src/execution/session-inbox/inbox.js +1 -1
  20. package/dist/src/execution/session-inbox/protocol.js +1 -1
  21. package/dist/src/execution/tools/agent-router-workflow.js +1 -1
  22. package/dist/src/harness/compaction/engine.js +2 -2
  23. package/dist/src/harness/current-messages.js +1 -1
  24. package/dist/src/harness/emission.d.ts +3 -0
  25. package/dist/src/harness/emission.js +1 -1
  26. package/dist/src/harness/facts.d.ts +5 -2
  27. package/dist/src/harness/facts.js +1 -1
  28. package/dist/src/harness/model-call/call.d.ts +7 -1
  29. package/dist/src/harness/model-call/call.js +3 -1
  30. package/dist/src/harness/provider-tool-history.d.ts +8 -0
  31. package/dist/src/harness/provider-tool-history.js +1 -1
  32. package/dist/src/harness/session-machine/transitions.d.ts +3 -2
  33. package/dist/src/harness/step/after-model.js +1 -1
  34. package/dist/src/harness/step/context.js +1 -1
  35. package/dist/src/harness/step/intake.js +1 -1
  36. package/dist/src/harness/step/prompt.js +1 -1
  37. package/dist/src/harness/tool-history-repair.d.ts +2 -0
  38. package/dist/src/harness/tool-history-repair.js +1 -1
  39. package/dist/src/harness/tool-loop.js +1 -1
  40. package/dist/src/internal/application/stamped-package-version.js +1 -1
  41. package/dist/src/protocol/session-events/families/delivery.d.ts +5 -3
  42. package/dist/src/protocol/session-events/families/delivery.js +1 -1
  43. package/dist/src/protocol/session-projection/fold.js +1 -1
  44. package/dist/src/public/channels/discord/hitl.js +1 -1
  45. package/dist/src/public/channels/slack/hitl.d.ts +2 -1
  46. package/dist/src/public/channels/slack/hitl.js +3 -3
  47. package/dist/src/public/channels/slack/interaction-cards.js +1 -1
  48. package/dist/src/public/channels/slack/request-card-render.js +1 -1
  49. package/dist/src/public/channels/teams/hitl.js +1 -1
  50. package/dist/src/public/channels/teams/verify.js +1 -1
  51. package/dist/src/public/definitions/hook.d.ts +90 -7
  52. package/dist/src/public/definitions/hook.js +1 -1
  53. package/dist/src/public/hooks/index.d.ts +3 -2
  54. package/dist/src/reactions/continuation.d.ts +19 -0
  55. package/dist/src/reactions/continuation.js +1 -0
  56. package/dist/src/reactions/intents.d.ts +10 -4
  57. package/dist/src/reactions/intents.js +1 -1
  58. package/dist/src/reactions/kinds/hook.js +1 -1
  59. package/dist/src/reactions/runner.js +1 -1
  60. package/dist/src/reactions/state.d.ts +15 -2
  61. package/dist/src/reactions/state.js +1 -1
  62. package/dist/src/runtime/resolve-connection.js +1 -1
  63. package/dist/src/runtime/subagents/workflow.js +1 -1
  64. package/dist/src/setup/primitives/open-url.js +1 -1
  65. package/dist/src/setup/scaffold/create/project.js +1 -1
  66. package/dist/src/shared/value-delta.d.ts +5 -4
  67. package/dist/src/shared/value-delta.js +1 -1
  68. package/dist/src/tools/provided/ask-question-workflow.js +1 -1
  69. package/dist/src/tools/provided/sleep-workflow.js +1 -1
  70. package/dist/src/tools/provided/web-fetch.js +1 -1
  71. package/docs/agent-config.md +199 -222
  72. package/docs/channels/chat-sdk.mdx +60 -64
  73. package/docs/channels/custom.mdx +264 -281
  74. package/docs/channels/discord.mdx +176 -123
  75. package/docs/channels/eve.mdx +136 -206
  76. package/docs/channels/github.mdx +24 -22
  77. package/docs/channels/linear.mdx +30 -30
  78. package/docs/channels/linq.mdx +25 -13
  79. package/docs/channels/mcp.mdx +154 -116
  80. package/docs/channels/overview.mdx +31 -32
  81. package/docs/channels/photon.mdx +32 -56
  82. package/docs/channels/slack.mdx +538 -375
  83. package/docs/channels/teams.mdx +40 -26
  84. package/docs/channels/telegram.mdx +13 -13
  85. package/docs/channels/twilio.mdx +11 -11
  86. package/docs/code-extension.mdx +40 -42
  87. package/docs/concepts/built-in-tools.md +89 -57
  88. package/docs/concepts/context-control.md +20 -20
  89. package/docs/concepts/default-harness.md +20 -36
  90. package/docs/concepts/execution-model-and-durability.mdx +96 -160
  91. package/docs/concepts/project-structure.mdx +21 -14
  92. package/docs/concepts/security-model.md +27 -27
  93. package/docs/concepts/sessions-runs-and-streaming.md +184 -198
  94. package/docs/concepts/state.md +7 -15
  95. package/docs/connections/mcp.mdx +109 -93
  96. package/docs/connections/openapi.mdx +57 -59
  97. package/docs/connections/overview.mdx +175 -170
  98. package/docs/evals/assertions.mdx +36 -29
  99. package/docs/evals/cases.mdx +38 -42
  100. package/docs/evals/judge.mdx +21 -29
  101. package/docs/evals/overview.mdx +42 -38
  102. package/docs/evals/reporters.mdx +54 -27
  103. package/docs/evals/running.mdx +15 -8
  104. package/docs/evals/targets.mdx +16 -19
  105. package/docs/evals/tool-stubs.mdx +111 -97
  106. package/docs/experimental/dynamic-schedules.mdx +118 -63
  107. package/docs/extensions.md +58 -65
  108. package/docs/getting-started.mdx +4 -6
  109. package/docs/guides/auth-and-route-protection.md +87 -70
  110. package/docs/guides/client/continuations.mdx +23 -26
  111. package/docs/guides/client/messages.mdx +47 -66
  112. package/docs/guides/client/output-schema.mdx +8 -8
  113. package/docs/guides/client/overview.mdx +45 -43
  114. package/docs/guides/client/streaming.mdx +62 -71
  115. package/docs/guides/decide.md +24 -79
  116. package/docs/guides/deployment/meta.json +1 -1
  117. package/docs/guides/deployment/overview.md +27 -18
  118. package/docs/guides/deployment/self-hosted-operations.md +99 -0
  119. package/docs/guides/deployment/self-hosting.md +63 -80
  120. package/docs/guides/deployment/vercel.mdx +31 -27
  121. package/docs/guides/deployment/workflow-worlds.md +100 -0
  122. package/docs/guides/dev-tui.md +48 -41
  123. package/docs/guides/dynamic-capabilities.md +49 -50
  124. package/docs/guides/frontend/nextjs.mdx +2 -2
  125. package/docs/guides/frontend/nuxt.mdx +11 -11
  126. package/docs/guides/frontend/overview.mdx +1 -1
  127. package/docs/guides/frontend/sveltekit.mdx +11 -11
  128. package/docs/guides/frontend/tanstack.mdx +16 -16
  129. package/docs/guides/frontend/use-eve-agent-svelte.mdx +21 -21
  130. package/docs/guides/frontend/use-eve-agent-vue.mdx +22 -22
  131. package/docs/guides/frontend/use-eve-agent.mdx +25 -25
  132. package/docs/guides/hooks.md +152 -106
  133. package/docs/guides/instrumentation/agent-runs.mdx +26 -30
  134. package/docs/guides/instrumentation/instrumentation.mdx +49 -76
  135. package/docs/guides/instrumentation/meta.json +1 -1
  136. package/docs/guides/instrumentation/otel.mdx +113 -179
  137. package/docs/guides/remote-agents.md +125 -187
  138. package/docs/guides/self-modification.md +18 -18
  139. package/docs/guides/session-context.md +16 -16
  140. package/docs/install-integrations.mdx +26 -24
  141. package/docs/instructions.mdx +37 -42
  142. package/docs/memory/custom-provider.md +35 -41
  143. package/docs/memory/file.md +93 -76
  144. package/docs/memory/overview.mdx +145 -156
  145. package/docs/patterns/durable-cross-channel-notifications.md +15 -19
  146. package/docs/patterns/dynamic-scheduling.md +19 -23
  147. package/docs/patterns/multi-tenant-approvals.md +17 -22
  148. package/docs/patterns/multi-tenant-auth.md +43 -42
  149. package/docs/patterns/multi-tenant-memory.md +39 -36
  150. package/docs/patterns/voice-notes.md +3 -3
  151. package/docs/protocols/acp.md +13 -13
  152. package/docs/protocols/ucp.mdx +7 -7
  153. package/docs/reference/agent-files.md +6 -6
  154. package/docs/reference/cli.md +99 -98
  155. package/docs/reference/telemetry.md +1 -1
  156. package/docs/reference/typescript-api.md +52 -53
  157. package/docs/responsible-use.md +2 -2
  158. package/docs/sandbox/custom-providers.mdx +60 -56
  159. package/docs/sandbox/default.mdx +23 -24
  160. package/docs/sandbox/docker.mdx +16 -10
  161. package/docs/sandbox/index.mdx +93 -61
  162. package/docs/sandbox/just-bash.mdx +17 -11
  163. package/docs/sandbox/troubleshooting.mdx +29 -23
  164. package/docs/sandbox/vercel.mdx +45 -52
  165. package/docs/schedules.mdx +65 -54
  166. package/docs/skills.mdx +74 -49
  167. package/docs/subagents/index.mdx +97 -136
  168. package/docs/tools/human-in-the-loop.md +160 -90
  169. package/docs/tools/meta.json +1 -1
  170. package/docs/tools/overview.mdx +229 -237
  171. package/docs/tools/tasks.md +118 -117
  172. package/docs/tools/workflows.mdx +447 -543
  173. package/docs/tutorial/connect-a-warehouse.mdx +11 -13
  174. package/docs/tutorial/first-agent.mdx +14 -16
  175. package/docs/tutorial/guard-the-spend.mdx +6 -8
  176. package/docs/tutorial/how-it-runs.mdx +8 -8
  177. package/docs/tutorial/query-sample-data.mdx +8 -8
  178. package/docs/tutorial/remember-definitions.mdx +4 -4
  179. package/docs/tutorial/run-analysis.mdx +20 -22
  180. package/docs/tutorial/ship-it.mdx +19 -19
  181. package/docs/tutorial/team-playbooks.mdx +9 -9
  182. package/docs/use-cases.mdx +13 -11
  183. package/package.json +1 -1
  184. package/docs/guides/instrumentation/migration.md +0 -96
  185. package/docs/tools/tasks-upgrade.md +0 -218
@@ -3,39 +3,29 @@ title: "Schedules"
3
3
  description: "Run an agent on a cron cadence, either a fire-and-forget prompt or a handler that hands work off to a channel."
4
4
  ---
5
5
 
6
- A schedule starts the agent on its own clock instead of waiting for an inbound message. Use one for daily digests, data syncs, cleanup sweeps, heartbeats, or anything that should fire on a cadence. Root-authored schedules are single files under `agent/schedules/`, and mounted extensions can contribute them from `extension/schedules/`. Declared subagents cannot have a `schedules/` directory.
6
+ A schedule starts the agent on a cron cadence instead of waiting for a message. Each schedule is one file under `agent/schedules/`. Use schedules for work such as daily digests, data syncs, cleanup sweeps, and heartbeats.
7
7
 
8
- The name comes from the path under `schedules/` (`agent/schedules/billing/sweep.ts` → `"billing/sweep"`), and nested directories are fine. An extension mount prefixes that name (`extension/schedules/sweep.ts` mounted as `crm` → `"crm__sweep"`) without changing its cron expression.
9
-
10
- For creator-owned schedules created and managed at runtime, see [Experimental dynamic schedules](./experimental/dynamic-schedules). `defineSchedule` remains the fixed, code-authored cron API.
11
-
12
- ## `defineSchedule`
13
-
14
- Every schedule provides a `cron` and exactly one of `content` or `run`:
8
+ ## Markdown form (fire-and-forget)
15
9
 
16
- ```ts
17
- interface ScheduleDefinition {
18
- cron: string;
19
- content?: string; // fire-and-forget prompt
20
- run?: (args: ScheduleHandlerArgs) => Promise<void> | void; // handler
21
- }
10
+ The smallest schedule is a markdown file. Its frontmatter takes `cron`, and the body is the prompt:
22
11
 
23
- interface ScheduleHandlerArgs {
24
- to: ScheduleToFn; // select a channel target, then send
25
- waitUntil: (task: Promise<unknown>) => void; // keep the cron task alive past return
26
- appAuth: SessionAuthContext; // pre-built app principal
27
- }
12
+ ```text
13
+ agent/schedules/
14
+ ├── cleanup.md # markdown form
15
+ ├── heartbeat.ts # markdown form, in TypeScript
16
+ └── billing/
17
+ └── sweep.ts # named "billing/sweep"
28
18
  ```
29
19
 
30
- `defineSchedule` is a type-level pass-through. The compiler is what enforces the one-of rule.
31
-
32
- A TypeScript schedule with `content` is compile-only because eve stores the prompt in the manifest. A schedule with `run` remains a runtime entry so the handler can execute. See [Authored module lifecycle](./reference/typescript-api#authored-module-lifecycle).
33
-
34
- `cron` is a standard 5-field string (`minute hour day-of-month month day-of-week`) with minute granularity. On Vercel, each schedule becomes a Vercel Cron Job, and Vercel evaluates the expression in UTC, so `"0 9 * * 1-5"` fires at 09:00 UTC on weekdays. `eve dev` never fires schedules on their cron cadence. A built app served with `eve start` does run production scheduled tasks. To trigger one while iterating in dev, use the dispatch route below.
20
+ ```md title="agent/schedules/cleanup.md"
21
+ ---
22
+ cron: "0 0 * * 0"
23
+ ---
35
24
 
36
- ## Markdown form (fire-and-forget)
25
+ Sweep stale workflow state.
26
+ ```
37
27
 
38
- This is the minimal schedule. eve runs the agent on the prompt and throws away the output, though the agent can still call tools, write to backends, and log along the way. The session has no channel, so it cannot ask a person for input, and nothing can send it a follow-up message. If the agent calls a tool that needs approval, the session fails instead of waiting for an answer. After its turn settles, the session parks like any other session until its [session timeout](./agent-config#runtime-limits) ends it.
28
+ The same schedule in TypeScript uses `content` for the prompt:
39
29
 
40
30
  ```ts title="agent/schedules/heartbeat.ts"
41
31
  import { defineSchedule } from "eve/schedules";
@@ -46,21 +36,35 @@ export default defineSchedule({
46
36
  });
47
37
  ```
48
38
 
49
- You can write the same thing as a plain `.md` file: its frontmatter takes `cron`, and the body is the prompt.
39
+ A markdown-form schedule runs the agent on the prompt and discards the reply. The agent can still call tools, write to backends, and log. The session has no channel, so it can't ask a person for input or receive a follow-up message. A tool that needs approval fails the session instead of waiting. After the turn ends, the session stays open until its [session timeout](./agent-config#runtime-limits) ends it.
50
40
 
51
- `agent/schedules/cleanup.md`:
41
+ ## `defineSchedule`
52
42
 
53
- ```md
54
- ---
55
- cron: "0 0 * * 0"
56
- ---
43
+ Every schedule provides a `cron` and exactly one of `content` or `run`. The build fails otherwise.
57
44
 
58
- Sweep stale workflow state.
45
+ ```ts
46
+ interface ScheduleDefinition {
47
+ cron: string;
48
+ content?: string; // fire-and-forget prompt
49
+ run?: (args: ScheduleHandlerArgs) => Promise<void> | void; // handler
50
+ }
51
+
52
+ interface ScheduleHandlerArgs {
53
+ to: ScheduleToFn; // select a channel target, then send
54
+ waitUntil: (task: Promise<unknown>) => void; // keep the cron task alive past return
55
+ appAuth: SessionAuthContext; // the app's own identity
56
+ }
59
57
  ```
60
58
 
59
+ A schedule with `content` needs no code at runtime. A schedule with `run` stays loaded at runtime so the handler can execute. See [Authored module lifecycle](./reference/typescript-api#authored-module-lifecycle).
60
+
61
+ `cron` is a standard 5-field string (`minute hour day-of-month month day-of-week`) with minute granularity. On Vercel, schedules run in UTC, so `"0 9 * * 1-5"` fires at 09:00 UTC on weekdays. `eve dev` never fires schedules on their cadence, but a built app served with `eve start` does. In development, use the [dispatch route](#trigger-a-schedule-while-iterating).
62
+
63
+ The name comes from the path under `schedules/`, so `agent/schedules/billing/sweep.ts` is `"billing/sweep"`. Mounted extensions can add schedules from `extension/schedules/`. The mount name becomes a prefix: `extension/schedules/sweep.ts` mounted as `crm` is `"crm__sweep"`, with the same cron expression. Declared subagents can't have a `schedules/` directory.
64
+
61
65
  ## Handler form (`run`)
62
66
 
63
- Use a handler when the schedule needs to deliver to a channel, branch on conditions, or compute its arguments at fire time. The handler is in full control. It has no channel of its own, so it selects a channel target with `to(...)` and sends through the returned handle.
67
+ Use a handler when the schedule sends to a channel, branches on conditions, or computes its message when it fires. A handler has no channel of its own. It selects a channel target with `to(...)` and sends through the returned handle:
64
68
 
65
69
  ```ts title="agent/schedules/critical-alerts.ts"
66
70
  import { defineSchedule } from "eve/schedules";
@@ -70,72 +74,79 @@ import slack from "../channels/slack";
70
74
  export default defineSchedule({
71
75
  cron: "* * * * *",
72
76
  async run({ to, waitUntil, appAuth }) {
77
+ // waitUntil keeps the cron task alive until the session and any open fetches finish.
73
78
  waitUntil(
74
79
  to(slack, { channelId: "C0123ABC" }).send("Summarize the new critical alerts.", {
75
- auth: appAuth,
80
+ auth: appAuth, // run as the app, not as a user
76
81
  }),
77
82
  );
78
83
  },
79
84
  });
80
85
  ```
81
86
 
82
- Every run delivers the agent's reply to the channel. To skip a run when there is nothing to report, check that condition in the handler before calling `send`. When only the agent can tell, add the opt-in [`no_reply`](/docs/concepts/built-in-tools#no_reply) tool and ask the agent to call it when there is nothing to report; the run then posts nothing.
87
+ `to(channel, target).send(message, { auth, ...options })` starts a session on that channel. It takes the same [options](./channels/custom#cross-channel-hand-off) as a route handler's `ctx.to(...)` handle.
83
88
 
84
- - `to(channel, target).send(message, { auth, ...options })`: starts a session on another channel. It has the same contract and [options](./channels/custom#cross-channel-hand-off) as a route handler's `ctx.to(...)` handle.
85
- - `waitUntil(promise)`: extends the cron task's lifetime so the parked session and any in-flight fetches settle before the task ends. Wrap the `send` call in it.
86
- - `appAuth`: the app principal (`{ authenticator: "app", principalId: "eve:app", principalType: "runtime" }`). Pass it as `to(...).send(..., { auth: appAuth })` for work the agent does on its own behalf.
89
+ The `auth` option sets which identity the session runs as. `appAuth` is the app's own identity (`{ authenticator: "app", principalId: "eve:app", principalType: "runtime" }`), for work the agent does for itself. When scheduled work needs a user's grants, pass that user's auth instead. The session still records that a schedule started it.
87
90
 
88
- The `auth` option controls which principal the session runs as. A handler may instead supply a user principal when scheduled work needs that user's grants; a session created by that dispatch still retains schedule provenance.
91
+ Every run sends the agent's reply to the channel. To skip a run with nothing to report, check in the handler before you call `send`. When only the agent can tell, add the opt-in [`no_reply`](/docs/concepts/built-in-tools#no_reply) tool and ask the agent to call it, so the run posts nothing.
92
+
93
+ A handler-form session can pause and wait like any other session, for example while a Slack thread waits for a reply.
89
94
 
90
95
  ### Detect the app principal
91
96
 
92
- `isScheduleAuth(auth)` returns `true` when `auth` is the app principal that schedules pass as `appAuth` and that markdown-form sessions run as. Use it in tools, hooks, or channel handlers to treat the agent's own work differently from a user's:
97
+ `isScheduleAuth(auth)` returns `true` when `auth` is the app identity that schedules pass as `appAuth`. Markdown-form sessions also run as that identity. Use it in tools, hooks, or channel handlers to treat the agent's own work differently from a user's:
93
98
 
94
99
  ```ts
95
100
  import { isScheduleAuth } from "eve/schedules";
96
101
 
97
102
  if (isScheduleAuth(ctx.session.auth.current)) {
98
- // The turn runs as the app principal, not as a user.
103
+ // The turn runs as the app, not as a user.
99
104
  }
100
105
  ```
101
106
 
102
- `isScheduleAuth` identifies the principal, not how the turn started. A turn from a schedule handler that sends with a user principal returns `false`, and any code that passes `appAuth` along returns `true`.
103
-
104
- A handler-form session runs on the same durable runtime engine as any other session, so it can park (durably suspend), for instance when the channel handoff is waiting for a Slack reply. Markdown-form sessions park too, but no channel is attached, so they cannot receive follow-up messages.
107
+ `isScheduleAuth` checks the identity, not how the turn started. It returns `false` when a schedule handler sends with a user's auth, and `true` for any code that passes `appAuth` along.
105
108
 
106
109
  ## Session continuity
107
110
 
108
- Markdown schedules start a new session on every fire. Handler schedules do too, unless they send to an existing conversation, such as a Slack thread. Store data that must survive across fires outside session state.
111
+ Markdown-form schedules start a new session each time they fire. Handler schedules do too, unless they send to an existing conversation, such as a Slack thread. Store data that must carry over between runs outside session state.
109
112
 
110
113
  ## Trigger a schedule while iterating
111
114
 
112
- The dev server mounts a one-shot dispatch route that fires a schedule by name, out of band, exactly once. Since `eve dev` never runs schedules on their cron cadence, this is how you trigger one without waiting for the next production tick.
115
+ `eve dev` never runs schedules on their cadence, so the dev server adds a route that fires a schedule by name once:
113
116
 
114
117
  ```sh
115
118
  curl -X POST http://localhost:2000/eve/v1/dev/schedules/heartbeat
116
119
  # -> { "scheduleId": "heartbeat", "sessionIds": ["..."] }
117
120
  ```
118
121
 
119
- `:scheduleId` is the path-derived schedule name (`agent/schedules/heartbeat.ts` → `heartbeat`; URL-encode the `/` in nested names). It runs the exact dispatch path the production cron handler uses and returns the started session ids as JSON, so you can subscribe to each one's [stream](./concepts/sessions-runs-and-streaming) at `GET /eve/v1/session/:sessionId/stream`. An unknown id comes back `404` with `availableScheduleIds`, listing the schedules the app actually defines.
122
+ `:scheduleId` is the schedule name from its path (`agent/schedules/heartbeat.ts` → `heartbeat`). URL-encode the `/` in nested names. The route fires the schedule as production cron does and returns the started session IDs. Subscribe to each session's [stream](./concepts/sessions-runs-and-streaming) at `GET /eve/v1/session/:sessionId/stream`.
123
+
124
+ An unknown name returns `404` with `availableScheduleIds`, which lists the app's schedules.
120
125
 
121
- The route is dev-only. Production builds never mount it, and it needs no auth since the dev server is local-only.
126
+ The route exists only in development. Production builds never include it. It needs no auth because the dev server is local-only.
122
127
 
123
128
  ## On Vercel
124
129
 
125
- Hosted Vercel builds turn every `defineSchedule(...)` into a Vercel Cron Job, with each `cron` written as an entry in `.vercel/output/config.json`. This also applies when [`withEve`](./guides/frontend/nextjs) embeds one or more agents in a Next.js deployment: Vercel assembles each generated eve service's schedules into the project Build Output config while preserving existing project cron entries. Named agents use their public `/eve/<name>` route prefix automatically.
130
+ Hosted Vercel builds turn every schedule into a Vercel Cron Job entry in `.vercel/output/config.json`. When [`withEve`](./guides/frontend/nextjs) adds agents to a Next.js deployment, Vercel adds each agent's schedules to the project's cron entries. Named agents use their `/eve/<name>` route prefix.
126
131
 
127
- When running `vercel build` locally, use Vercel CLI 56.4.0 or later so generated-service cron entries are included in the project output.
132
+ When you run `vercel build` locally, use Vercel CLI 56.4.0 or later so the project output includes these cron entries.
128
133
 
129
- Vercel evaluates cron expressions in UTC. Confirm discovery under **Settings → Cron Jobs** and watch execution history under **Observability → Cron Jobs**. Per-run logs land under **Observability → Logs**.
134
+ Confirm that Vercel found the schedules under **Settings → Cron Jobs**. Find run history under **Observability → Cron Jobs**, and per-run logs under **Observability → Logs**.
130
135
 
131
136
  ## Self-deployed hosts
132
137
 
133
- Production builds register schedules as Nitro scheduled tasks. On Vercel, Nitro's Vercel preset wires those task registrations into Vercel Cron for you. Outside Vercel, the standard `eve build && eve start` path serves Nitro's Node output and starts Nitro's schedule runner, so the tasks fire on their cron cadence while that process is running.
138
+ Production builds register schedules as Nitro scheduled tasks. Outside Vercel, `eve build && eve start` starts Nitro's schedule runner, so schedules fire while that process runs.
134
139
 
135
- The gotcha is custom hosting. If you adapt the generated output to a process manager, container platform, or Nitro preset that only serves HTTP and does not start Nitro's scheduled task runner, the schedule definitions still compile, but they will not fire automatically. In that case, run eve through `eve start`, use a host that supports Nitro scheduled tasks, or trigger the same work from your own scheduler through an authenticated route, channel handoff, or application-specific job runner. The dev dispatch route above is only for `eve dev`; production builds do not mount it.
140
+ A process manager, container platform, or Nitro preset that only serves HTTP doesn't start the schedule runner. Schedules build but never fire. In that case, choose one:
141
+
142
+ - Run eve through `eve start`.
143
+ - Use a host that supports Nitro scheduled tasks.
144
+ - Trigger the work from your own scheduler through an authenticated route, channel handoff, or job runner.
136
145
 
137
146
  ## What to read next
138
147
 
148
+ `defineSchedule` covers fixed schedules in code. For schedules that users or the agent create at runtime, see [Experimental dynamic schedules](./experimental/dynamic-schedules).
149
+
139
150
  - [Channels](./channels/overview): deliver schedule output to users.
140
151
  - [Sessions, runs & streaming](./concepts/sessions-runs-and-streaming): inspect a schedule run.
141
152
  - [Dynamic scheduling](./patterns/dynamic-scheduling): manage schedule rows in your own store behind one dispatcher schedule.
package/docs/skills.mdx CHANGED
@@ -3,48 +3,28 @@ title: "Skills"
3
3
  description: "Author load-on-demand procedures the model pulls into context with eve__skill."
4
4
  ---
5
5
 
6
- A skill is a model-loadable procedure that follows the `SKILL.md` convention. It is a markdown document, optionally a packaged directory with supporting files, that the model pulls into context on demand rather than carrying on every turn. eve advertises each skill's description, and the model loads the full body only when a turn calls for it. This is progressive disclosure, the same model the broader Agent Skills standard uses, so a skill authored against that standard ports over as-is.
6
+ A skill is a procedure the model reads only when a task needs it, instead of carrying it on every turn. Each skill lives under `agent/skills/` as a markdown file, or as a directory with a `SKILL.md` and supporting files. Skills follow the Agent Skills standard, so a skill written for another Agent Skills client works as-is.
7
7
 
8
- ## How loading works
9
-
10
- eve scans the files under `agent/skills/` and lists each one's name and description in the system prompt. When a request matches a skill's description (or you name the skill outright), the model loads it with `eve__skill({ name })`, and the skill's markdown becomes the call's result in the active turn. An agent with skills always has the [`eve__skill` tool](./concepts/built-in-tools#eve__search-eve__tool-and-eve__skill). A load reports a `load-skill` action named for the skill, and `t.calledSkill` asserts it in [evals](./evals/assertions).
11
-
12
- Listing skills and loading their instructions do not require a sandbox: loading returns static instructions from the compiled agent and dynamic instructions from session state. Only access to supporting package files requires a sandbox. Builds may also prewarm sandbox templates that contain static package files. Supporting files are available under `$HOME/.agents/skills/<skill>/`, with `skills/<skill>/` under the workspace root as the fallback when `$HOME` is unavailable. Sibling references inside `SKILL.md`, such as `references/checklist.md`, are relative to the directory containing that specific `SKILL.md`.
13
-
14
- The description is a routing hint, not a label. Write it as the task that should trigger activation:
15
-
16
- ```md
17
- Use when the user needs a release checklist or changelog workflow.
18
- ```
19
-
20
- Loading a skill adds instructions, never a new execution surface. Tools stay visible whether a skill is loaded or not. If you need typed runtime behavior, reach for a [tool](./tools) instead.
21
-
22
- ## Deferred skills
8
+ ## Markdown vs `defineSkill`
23
9
 
24
- An agent with many skills can keep most of them out of the system prompt. Set `deferred: true` in the frontmatter or on `defineSkill`:
10
+ The smallest skill is a flat markdown file whose content is the procedure:
25
11
 
26
- ```md title="agent/skills/pdf-forms/SKILL.md"
27
- ---
28
- description: Fill and validate PDF forms.
29
- deferred: true
30
- ---
12
+ ```text
13
+ agent/skills/
14
+ ├── forecast.md # flat skill: description is optional
15
+ └── research/
16
+ ├── SKILL.md # packaged skill: description is required
17
+ └── references/
18
+ └── checklist.md # supporting file
31
19
  ```
32
20
 
33
- A deferred skill isn't named in context; the catalog listing only says that deferred skills exist, and their namespaces. The model finds a deferred skill with `eve__search`, which ranks skills and tools together, and loads it with `eve__skill({ name })`. Its markdown, supporting files, and eval assertions work as they do for any other skill. Dynamic skills accept `deferred` too; see [Dynamic capabilities](./guides/dynamic-capabilities#dynamic-skills).
34
-
35
- ## Markdown vs `defineSkill`
36
-
37
- The smallest skill is a flat markdown file. The content is the procedure, and the name comes from the path.
38
-
39
21
  ```md title="agent/skills/forecast.md"
40
22
  Use the weather tool before answering forecast or temperature questions.
41
23
  ```
42
24
 
43
- A skill's name comes from its path and must use only ASCII letters, digits, underscores, and dashes, start with a letter or digit, and have at most 64 characters. The compiler rejects any other name.
25
+ A skill's name comes from its path: `agent/skills/forecast.md` is `forecast`, and `agent/skills/research/SKILL.md` is `research`. A name uses only ASCII letters, digits, underscores, and dashes. It starts with a letter or digit and has at most 64 characters. The build fails on any other name.
44
26
 
45
- A flat markdown skill can skip the `description` frontmatter. When it does, eve advertises the first non-empty, non-code-fence line of the body with any leading `#`, `>`, `*`, or `-` marker stripped. If the body has no such line, eve falls back to the literal `Instructions for the <name> skill.`, which is a weak routing hint, so add a `description` when you want the model to route on intent.
46
-
47
- A packaged skill is a directory with a `SKILL.md` plus sibling files like `references/`, `assets/`, and `scripts/`. The packaged `SKILL.md` must carry `description` frontmatter; it has no filename slug to fall back on. eve ignores frontmatter it does not use so skills authored for other Agent Skills clients remain importable.
27
+ A packaged skill is a directory with a `SKILL.md` and sibling files such as `references/`, `assets/`, and `scripts/`:
48
28
 
49
29
  ```md title="agent/skills/research/SKILL.md"
50
30
  ---
@@ -55,54 +35,99 @@ When the task is novel or ambiguous, gather evidence first, then answer with the
55
35
  key facts and the remaining uncertainty.
56
36
  ```
57
37
 
58
- eve reads `description`, optional `license`, string `metadata`, and `deferred`; other `SKILL.md` frontmatter is accepted as a no-op.
59
-
60
- When markdown can't express what you need (typed values, generated content, or inline sibling files), author the skill in TypeScript with `defineSkill` from `eve/skills`:
38
+ Use `defineSkill` from `eve/skills` when markdown can't express what you need, such as typed values, generated content, or inline sibling files:
61
39
 
62
40
  ```ts title="agent/skills/research.ts"
63
41
  import { defineSkill } from "eve/skills";
64
42
 
65
43
  export default defineSkill({
66
- description: "Research unfamiliar topics before answering with confidence.",
44
+ description: "Research unfamiliar topics before answering with confidence.", // required
67
45
  content:
68
46
  "When the task is novel or ambiguous, gather evidence first, then answer with the key facts and the remaining uncertainty.",
47
+ // optional: each key becomes a file next to the generated SKILL.md
69
48
  files: {
70
49
  "references/checklist.md": "# Checklist\n\n- Find primary sources.\n",
71
50
  },
72
51
  });
73
52
  ```
74
53
 
75
- eve generates `SKILL.md` from `content`, and each `files` entry becomes a package-relative sibling. Start with plain markdown and move to `defineSkill` only when you hit its limits.
54
+ eve generates `SKILL.md` from `content`. A static `defineSkill` module runs once at build time, and a dynamic skill module also runs at runtime. See [Authored module lifecycle](./reference/typescript-api#authored-module-lifecycle).
76
55
 
77
- A static `defineSkill` module is evaluated during compilation and its resolved definition is stored in the manifest; a dynamic skill module is also retained as a runtime entry. See [Authored module lifecycle](./reference/typescript-api#authored-module-lifecycle).
56
+ | Field | Where | Default |
57
+ | ------------- | ---------------------------- | ------------------------------------------------ |
58
+ | `description` | Frontmatter or `defineSkill` | Required, except in a flat markdown skill |
59
+ | `deferred` | Frontmatter or `defineSkill` | `false`; see [Deferred skills](#deferred-skills) |
60
+ | `license` | Frontmatter or `defineSkill` | Unset |
61
+ | `metadata` | Frontmatter or `defineSkill` | Unset; values must be strings |
62
+ | `content` | `defineSkill` | Required; the markdown body in a file |
63
+ | `files` | `defineSkill` | None |
78
64
 
79
- ## Find and install community skills
65
+ eve ignores other frontmatter, so skills written for other Agent Skills clients import unchanged.
80
66
 
81
- `eve registry search` includes [skills.sh](https://skills.sh) as the built-in `@skills` source. Search by task, review the source, then install the returned skill into your project:
67
+ A flat markdown skill without `description` uses the body's first non-empty line that isn't a code fence marker. eve strips any leading `#`, `>`, `*`, or `-` marker from that line. A body with no such line gives `Instructions for the <name> skill.`, which is a weak hint. Add a `description` when the model must choose the skill by intent.
82
68
 
83
- ```bash
84
- eve registry search react --registry @skills
85
- eve add @skills/vercel-labs/agent-skills/vercel-react-best-practices
69
+ ## How loading works
70
+
71
+ eve lists each skill's name and description in the system prompt. When a request matches a description, or names the skill, the model loads it with `eve__skill({ name })`. The skill's markdown becomes that call's result in the current turn.
72
+
73
+ An agent with skills always has the [`eve__skill` tool](./concepts/built-in-tools#eve__search-eve__tool-and-eve__skill). Each load reports a `load-skill` action named for the skill, and `t.calledSkill` asserts it in [evals](./evals/assertions).
74
+
75
+ The description tells the model when to load the skill. Write it as the task that should trigger it:
76
+
77
+ ```md
78
+ Use when the user needs a release checklist or changelog workflow.
86
79
  ```
87
80
 
88
- skills.sh skills are community-authored project files. Review their source and the resulting diff before running the agent. See [Install integrations](./install-integrations#add-a-skill) for registry configuration and install behavior.
81
+ Loading a skill adds instructions, never tools. Tools stay visible whether or not a skill is loaded.
82
+
83
+ ## Supporting files
84
+
85
+ Supporting files are for the model. It reads a loaded skill's references, assets, and scripts with sandbox tools such as `read_file` and `bash`.
86
+
87
+ The files are under `$HOME/.agents/skills/<skill>/` in the sandbox. When `$HOME` is unavailable, they are under `skills/<skill>/` in the workspace root. A relative path inside `SKILL.md`, such as `references/checklist.md`, starts from the directory that holds that `SKILL.md`.
88
+
89
+ Listing and loading skills don't need a sandbox. Only reading supporting files does.
90
+
91
+ Tools and hooks have no API to read skill files. When your code needs the same data, import it from a module in `lib/`.
89
92
 
90
93
  ## Skills are scoped per agent
91
94
 
92
- Skills are scoped to the agent that declares them. A [subagent](./subagents)'s `skills/` are invisible to the root agent, and the reverse holds too. To share one skill definition across agents, package it in a [workspace extension](./extensions#use-an-extension-in-a-workspace) and mount that extension in each agent. Put shared executable helpers in `lib/`.
95
+ A skill belongs to the agent that declares it. A [subagent](./subagents) and the root agent can't see each other's `skills/`. To share one skill across agents, package it in a [workspace extension](./extensions#use-an-extension-in-a-workspace) and mount that extension in each agent. Put shared executable helpers in `lib/`.
93
96
 
94
- ## Supporting files
97
+ ## Deferred skills
98
+
99
+ A deferred skill stays out of the system prompt, which helps an agent with many skills. Set `deferred: true` in the frontmatter or on `defineSkill`:
100
+
101
+ ```md title="agent/skills/pdf-forms/SKILL.md"
102
+ ---
103
+ description: Fill and validate PDF forms.
104
+ deferred: true
105
+ ---
106
+ ```
95
107
 
96
- Supporting files are for the model. After loading a skill, the model reads its references, assets, and scripts with sandbox filesystem tools such as `read_file` and `bash`. Tools and hooks have no skill file API; when your code needs the same data, import it from a module in `lib/` so it ships with the agent.
108
+ The system prompt says only that deferred skills exist, and lists their namespaces. The model finds a deferred skill with `eve__search`, which searches skills and tools together, and loads it with `eve__skill({ name })`. After that, the skill works like any other skill.
97
109
 
98
110
  ## Dynamic skills
99
111
 
100
- To serve a different skill per principal, tenant, or channel (the caller's own team playbook, say), wrap `defineSkill` in `defineDynamic` and select the attribute it depends on from `ctx.session.auth`. See [Dynamic capabilities](./guides/dynamic-capabilities#dynamic-skills).
112
+ To serve a different skill per user, tenant, or channel, wrap `defineSkill` in `defineDynamic`. Read the value it depends on, such as the caller's team, from `ctx.session.auth`. Dynamic skills accept `deferred` too. See [Dynamic capabilities](./guides/dynamic-capabilities#dynamic-skills).
113
+
114
+ A parent agent keeps its dynamic skills when it resumes after delegating to a subagent.
115
+
116
+ ## Find and install community skills
101
117
 
102
- Delegating to a subagent does not change the parent's dynamic skills. They remain available when the parent resumes after delegation.
118
+ `eve registry search` includes [skills.sh](https://skills.sh) as the built-in `@skills` source. Search by task, review the source, then install the skill into your project:
119
+
120
+ ```bash
121
+ eve registry search react --registry @skills
122
+ eve add @skills/vercel-labs/agent-skills/vercel-react-best-practices
123
+ ```
124
+
125
+ skills.sh skills are written by the community and become files in your project. Review their source and the resulting diff before you run the agent. See [Install integrations](./install-integrations#add-a-skill) for registry configuration and install behavior.
103
126
 
104
127
  ## What to read next
105
128
 
129
+ Use [instructions](./instructions) for rules the model needs on every turn, and a [tool](./tools) when the model needs typed code that runs.
130
+
106
131
  - [Connections](./connections): add tools from external MCP and OpenAPI servers
107
132
  - [Dynamic capabilities](./guides/dynamic-capabilities): choose skills per caller with `defineDynamic`
108
133
  - [Context control](./concepts/context-control): how skills fit the full context model