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
|
@@ -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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
53
|
+
### Options
|
|
49
54
|
|
|
50
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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
|
|
81
|
+
Set `tool` to choose how the model reaches these operations:
|
|
88
82
|
|
|
89
|
-
|
|
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
|
-
|
|
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.
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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.
|