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.
- package/CHANGELOG.md +39 -9
- package/dist/src/channel/adapter.d.ts +12 -3
- package/dist/src/channel/adapter.js +1 -1
- package/dist/src/channel/auth/definitions.d.ts +7 -20
- package/dist/src/channel/auth/definitions.js +1 -1
- package/dist/src/channel/auth/http-basic.js +1 -1
- package/dist/src/channel/auth/jwt-ecdsa.js +1 -1
- package/dist/src/channel/auth/jwt-hmac.js +1 -1
- package/dist/src/channel/auth/oidc.js +1 -1
- package/dist/src/channel/auth/result.d.ts +2 -3
- package/dist/src/channel/auth/result.js +1 -1
- package/dist/src/channel/channel-address.d.ts +1 -1
- package/dist/src/channel/channel-address.js +1 -1
- package/dist/src/channel/channel-operations.d.ts +1 -1
- package/dist/src/channel/schedule.js +1 -1
- package/dist/src/channel/types.d.ts +2 -0
- package/dist/src/chunks/{use-eve-agent-Bbl4H5aA.js → use-eve-agent-Bwloorf8.js} +77 -63
- package/dist/src/chunks/{use-eve-agent-CNpxgKEH.js → use-eve-agent-XCB0-tLX.js} +77 -63
- package/dist/src/cli/dev/environment.js +1 -1
- package/dist/src/cli/dev/tui/prompt-commands.d.ts +1 -1
- package/dist/src/cli/dev/tui/remote-connection-probe.js +1 -1
- package/dist/src/cli/dev/tui/remote-connection-types.d.ts +1 -0
- package/dist/src/cli/dev/tui/runner.js +2 -2
- package/dist/src/cli/dev/tui/status-line.d.ts +2 -2
- package/dist/src/cli/dev/tui/status-line.js +1 -1
- package/dist/src/client/agent-info-schema.d.ts +341 -326
- package/dist/src/client/agent-info-schema.js +1 -1
- package/dist/src/client/agent-info-types.d.ts +13 -10
- package/dist/src/client/client-error.d.ts +1 -1
- package/dist/src/client/client.d.ts +5 -3
- package/dist/src/client/client.js +1 -1
- package/dist/src/client/session.d.ts +1 -1
- package/dist/src/compiled/.vendor-stamp.json +1 -1
- package/dist/src/evals/target.js +1 -1
- package/dist/src/eve-channel/auth.d.ts +19 -0
- package/dist/src/eve-channel/auth.js +1 -0
- package/dist/src/eve-channel/index.d.ts +1 -0
- package/dist/src/eve-channel/index.js +1 -1
- package/dist/src/eve-channel/types.d.ts +23 -4
- package/dist/src/execution/catalog/connection-entry.js +1 -1
- package/dist/src/execution/coordination-dispatch-shared.js +1 -1
- package/dist/src/execution/dynamic-workflow/tool.js +1 -1
- package/dist/src/execution/proxied-deliver-step.js +1 -1
- package/dist/src/execution/sandbox/bash.js +2 -2
- package/dist/src/execution/session/active-turn.js +1 -1
- package/dist/src/execution/session/admission.d.ts +6 -0
- package/dist/src/execution/session/admission.js +1 -1
- package/dist/src/execution/session/delivery-facts.js +1 -1
- package/dist/src/execution/session/next-input.d.ts +2 -2
- package/dist/src/execution/session/next-input.js +1 -1
- package/dist/src/execution/session/program.js +1 -1
- package/dist/src/execution/session-inbox/inbox.d.ts +2 -2
- package/dist/src/execution/session-inbox/inbox.js +1 -1
- package/dist/src/execution/session-inbox/protocol.js +1 -1
- package/dist/src/execution/tools/agent-router-workflow.js +1 -1
- package/dist/src/harness/compaction/engine.js +2 -2
- package/dist/src/harness/current-messages.js +1 -1
- package/dist/src/harness/emission.d.ts +3 -0
- package/dist/src/harness/emission.js +1 -1
- package/dist/src/harness/facts.d.ts +5 -2
- package/dist/src/harness/facts.js +1 -1
- package/dist/src/harness/model-call/call.d.ts +7 -1
- package/dist/src/harness/model-call/call.js +3 -1
- package/dist/src/harness/provider-tool-history.d.ts +8 -0
- package/dist/src/harness/provider-tool-history.js +1 -1
- package/dist/src/harness/session-machine/transitions.d.ts +3 -2
- package/dist/src/harness/step/after-model.js +1 -1
- package/dist/src/harness/step/context.js +1 -1
- package/dist/src/harness/step/intake.js +1 -1
- package/dist/src/harness/step/prompt.js +1 -1
- package/dist/src/harness/tool-history-repair.d.ts +2 -0
- package/dist/src/harness/tool-history-repair.js +1 -1
- package/dist/src/harness/tool-loop.js +1 -1
- package/dist/src/internal/application/stamped-package-version.js +1 -1
- package/dist/src/internal/authored-module-graph.js +1 -1
- package/dist/src/internal/nitro/routes/agent-info/build-agent-info-response.d.ts +2 -2
- package/dist/src/protocol/routes.d.ts +7 -1
- package/dist/src/protocol/routes.js +1 -1
- package/dist/src/protocol/session-events/families/delivery.d.ts +5 -3
- package/dist/src/protocol/session-events/families/delivery.js +1 -1
- package/dist/src/protocol/session-projection/fold.js +1 -1
- package/dist/src/public/channels/discord/hitl.js +1 -1
- package/dist/src/public/channels/github/githubChannel.js +1 -1
- package/dist/src/public/channels/github/state.d.ts +7 -0
- package/dist/src/public/channels/github/state.js +1 -1
- package/dist/src/public/channels/mcp.js +1 -1
- package/dist/src/public/channels/slack/hitl.d.ts +2 -1
- package/dist/src/public/channels/slack/hitl.js +3 -3
- package/dist/src/public/channels/slack/interaction-cards.js +1 -1
- package/dist/src/public/channels/slack/request-card-render.js +1 -1
- package/dist/src/public/channels/teams/hitl.js +1 -1
- package/dist/src/public/channels/teams/verify.js +1 -1
- package/dist/src/public/channels/telegram/telegramChannel.js +1 -1
- package/dist/src/public/connections/index.d.ts +1 -1
- package/dist/src/public/definitions/channel.js +1 -1
- package/dist/src/public/definitions/connections/tool-call.d.ts +2 -2
- package/dist/src/public/definitions/hook.d.ts +90 -7
- package/dist/src/public/definitions/hook.js +1 -1
- package/dist/src/public/hooks/index.d.ts +3 -2
- package/dist/src/reactions/continuation.d.ts +19 -0
- package/dist/src/reactions/continuation.js +1 -0
- package/dist/src/reactions/frame.js +1 -1
- package/dist/src/reactions/intents.d.ts +10 -4
- package/dist/src/reactions/intents.js +1 -1
- package/dist/src/reactions/kinds/hook.js +1 -1
- package/dist/src/reactions/runner.js +1 -1
- package/dist/src/reactions/state.d.ts +15 -2
- package/dist/src/reactions/state.js +1 -1
- package/dist/src/runtime/channels/registry.d.ts +2 -2
- package/dist/src/runtime/channels/registry.js +1 -1
- package/dist/src/runtime/connections/approval-scope.d.ts +9 -0
- package/dist/src/runtime/connections/approval-scope.js +1 -0
- package/dist/src/runtime/connections/mcp-client.d.ts +1 -1
- package/dist/src/runtime/connections/mcp-client.js +1 -1
- package/dist/src/runtime/connections/provided-arguments.js +1 -1
- package/dist/src/runtime/resolve-connection.js +1 -1
- package/dist/src/runtime/subagents/workflow.js +1 -1
- package/dist/src/setup/primitives/open-url.js +1 -1
- package/dist/src/setup/scaffold/create/project.js +1 -1
- package/dist/src/shared/agent-info-access.d.ts +5 -0
- package/dist/src/shared/agent-info-access.js +1 -0
- package/dist/src/shared/connection-types.d.ts +21 -4
- package/dist/src/shared/value-delta.d.ts +5 -4
- package/dist/src/shared/value-delta.js +1 -1
- package/dist/src/svelte/index.js +1 -1
- package/dist/src/svelte/use-eve-agent.js +1 -1
- package/dist/src/tools/provided/ask-question-workflow.js +1 -1
- package/dist/src/tools/provided/sleep-workflow.js +1 -1
- package/dist/src/tools/provided/web-fetch.js +1 -1
- package/dist/src/vue/index.js +1 -1
- package/dist/src/vue/use-eve-agent.js +1 -1
- package/docs/agent-config.md +199 -222
- package/docs/channels/chat-sdk.mdx +60 -64
- package/docs/channels/custom.mdx +265 -280
- package/docs/channels/discord.mdx +176 -123
- package/docs/channels/eve.mdx +136 -204
- package/docs/channels/github.mdx +24 -22
- package/docs/channels/linear.mdx +30 -30
- package/docs/channels/linq.mdx +25 -13
- package/docs/channels/mcp.mdx +154 -116
- package/docs/channels/overview.mdx +31 -32
- package/docs/channels/photon.mdx +32 -56
- package/docs/channels/slack.mdx +538 -375
- package/docs/channels/teams.mdx +40 -26
- package/docs/channels/telegram.mdx +13 -13
- package/docs/channels/twilio.mdx +11 -11
- package/docs/code-extension.mdx +40 -42
- package/docs/concepts/built-in-tools.md +89 -57
- package/docs/concepts/context-control.md +20 -20
- package/docs/concepts/default-harness.md +20 -36
- package/docs/concepts/execution-model-and-durability.mdx +96 -160
- package/docs/concepts/project-structure.mdx +21 -14
- package/docs/concepts/security-model.md +27 -27
- package/docs/concepts/sessions-runs-and-streaming.md +184 -194
- package/docs/concepts/state.md +7 -15
- package/docs/connections/mcp.mdx +109 -93
- package/docs/connections/openapi.mdx +57 -59
- package/docs/connections/overview.mdx +205 -170
- package/docs/evals/assertions.mdx +36 -29
- package/docs/evals/cases.mdx +38 -42
- package/docs/evals/judge.mdx +21 -29
- package/docs/evals/overview.mdx +42 -38
- package/docs/evals/reporters.mdx +54 -27
- package/docs/evals/running.mdx +15 -8
- package/docs/evals/targets.mdx +17 -18
- package/docs/evals/tool-stubs.mdx +111 -97
- package/docs/experimental/dynamic-schedules.mdx +118 -63
- package/docs/extensions.md +58 -65
- package/docs/getting-started.mdx +4 -6
- package/docs/guides/auth-and-route-protection.md +100 -70
- package/docs/guides/client/continuations.mdx +23 -26
- package/docs/guides/client/messages.mdx +47 -66
- package/docs/guides/client/output-schema.mdx +8 -8
- package/docs/guides/client/overview.mdx +47 -41
- package/docs/guides/client/streaming.mdx +62 -71
- package/docs/guides/decide.md +24 -79
- package/docs/guides/deployment/meta.json +1 -1
- package/docs/guides/deployment/overview.md +27 -18
- package/docs/guides/deployment/self-hosted-operations.md +99 -0
- package/docs/guides/deployment/self-hosting.md +63 -80
- package/docs/guides/deployment/vercel.mdx +31 -27
- package/docs/guides/deployment/workflow-worlds.md +100 -0
- package/docs/guides/dev-tui.md +48 -41
- package/docs/guides/dynamic-capabilities.md +49 -50
- package/docs/guides/frontend/nextjs.mdx +2 -2
- package/docs/guides/frontend/nuxt.mdx +11 -11
- package/docs/guides/frontend/overview.mdx +1 -1
- package/docs/guides/frontend/sveltekit.mdx +11 -11
- package/docs/guides/frontend/tanstack.mdx +16 -16
- package/docs/guides/frontend/use-eve-agent-svelte.mdx +21 -21
- package/docs/guides/frontend/use-eve-agent-vue.mdx +22 -22
- package/docs/guides/frontend/use-eve-agent.mdx +25 -25
- package/docs/guides/hooks.md +152 -106
- package/docs/guides/instrumentation/agent-runs.mdx +26 -30
- package/docs/guides/instrumentation/instrumentation.mdx +49 -76
- package/docs/guides/instrumentation/meta.json +1 -1
- package/docs/guides/instrumentation/otel.mdx +113 -179
- package/docs/guides/prepare-for-1-0.md +23 -1
- package/docs/guides/remote-agents.md +125 -187
- package/docs/guides/self-modification.md +18 -18
- package/docs/guides/session-context.md +16 -16
- package/docs/install-integrations.mdx +26 -24
- package/docs/instructions.mdx +37 -42
- package/docs/memory/custom-provider.md +35 -41
- package/docs/memory/file.md +93 -76
- package/docs/memory/overview.mdx +145 -156
- package/docs/patterns/durable-cross-channel-notifications.md +15 -19
- package/docs/patterns/dynamic-scheduling.md +19 -23
- package/docs/patterns/multi-tenant-approvals.md +17 -22
- package/docs/patterns/multi-tenant-auth.md +43 -42
- package/docs/patterns/multi-tenant-memory.md +39 -36
- package/docs/patterns/voice-notes.md +3 -3
- package/docs/protocols/acp.md +13 -13
- package/docs/protocols/ucp.mdx +7 -7
- package/docs/reference/agent-files.md +6 -6
- package/docs/reference/cli.md +99 -98
- package/docs/reference/telemetry.md +1 -1
- package/docs/reference/typescript-api.md +52 -53
- package/docs/responsible-use.md +2 -2
- package/docs/sandbox/custom-providers.mdx +60 -56
- package/docs/sandbox/default.mdx +23 -24
- package/docs/sandbox/docker.mdx +16 -10
- package/docs/sandbox/index.mdx +93 -61
- package/docs/sandbox/just-bash.mdx +17 -11
- package/docs/sandbox/troubleshooting.mdx +29 -23
- package/docs/sandbox/vercel.mdx +45 -52
- package/docs/schedules.mdx +65 -54
- package/docs/skills.mdx +74 -49
- package/docs/subagents/index.mdx +97 -136
- package/docs/tools/human-in-the-loop.md +160 -90
- package/docs/tools/meta.json +1 -1
- package/docs/tools/overview.mdx +229 -237
- package/docs/tools/tasks.md +118 -117
- package/docs/tools/workflows.mdx +447 -543
- package/docs/tutorial/connect-a-warehouse.mdx +11 -13
- package/docs/tutorial/first-agent.mdx +14 -16
- package/docs/tutorial/guard-the-spend.mdx +6 -8
- package/docs/tutorial/how-it-runs.mdx +8 -8
- package/docs/tutorial/query-sample-data.mdx +8 -8
- package/docs/tutorial/remember-definitions.mdx +4 -4
- package/docs/tutorial/run-analysis.mdx +20 -22
- package/docs/tutorial/ship-it.mdx +19 -19
- package/docs/tutorial/team-playbooks.mdx +9 -9
- package/docs/use-cases.mdx +13 -11
- package/package.json +1 -1
- package/docs/guides/instrumentation/migration.md +0 -96
- package/docs/tools/tasks-upgrade.md +0 -218
package/docs/schedules.mdx
CHANGED
|
@@ -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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
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
|
-
|
|
31
|
-
|
|
32
|
-
|
|
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
|
-
|
|
25
|
+
Sweep stale workflow state.
|
|
26
|
+
```
|
|
37
27
|
|
|
38
|
-
|
|
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
|
-
|
|
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
|
-
`
|
|
41
|
+
## `defineSchedule`
|
|
52
42
|
|
|
53
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
103
|
+
// The turn runs as the app, not as a user.
|
|
99
104
|
}
|
|
100
105
|
```
|
|
101
106
|
|
|
102
|
-
`isScheduleAuth`
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
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.
|
|
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
|
-
|
|
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
|
|
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
|
-
##
|
|
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
|
-
|
|
10
|
+
The smallest skill is a flat markdown file whose content is the procedure:
|
|
25
11
|
|
|
26
|
-
```
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
65
|
+
eve ignores other frontmatter, so skills written for other Agent Skills clients import unchanged.
|
|
80
66
|
|
|
81
|
-
`eve
|
|
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
|
-
|
|
84
|
-
|
|
85
|
-
eve
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
##
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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
|