eve 0.47.7 → 0.48.0

package/docs/guides/remote-agents.md

@@ -143,6 +143,31 @@ Forwarding is explicit on both sides. The receiver names which forwarders it tru
 
 A receiver on an eve version that predates all principal forwarding may instead drop the unknown field and run the session as your app's service identity; per-user connections there fail with `principal_required`. On remote requests where the dispatching turn has no auth, the field is omitted and the call proceeds on transport trust alone.
 
+## Preserving trace content
+
+With `forwardPrincipal: true`, a sampled trace carries its original audience and the maximum content the next hop may record. For example, `eve.audience=private;ceiling=i0o1` allows outputs but not inputs. eve sends this as [W3C Baggage](https://www.w3.org/TR/baggage/).
+
+The receiver uses it only after `trustedForwarders` accepts the authenticated calling deployment:
+
+```ts title="agent/channels/eve.ts"
+import { eveChannel } from "eve/channels/eve";
+import { vercelOidc, vercelSubject } from "eve/channels/auth";
+
+export default eveChannel({
+  auth: [vercelOidc()],
+  trustedForwarders: (forwarder) =>
+    forwarder.subject === vercelSubject({ teamSlug: "acme", projectName: "router" }),
+});
+```
+
+The request must also include a callback and a valid sampled `traceparent`. Those fields identify a remote call, but they do not establish trust. `trustedForwarders` is the authorization boundary.
+
+The receiver combines the incoming ceiling with its own trace policy. Each hop may narrow the result, but it cannot restore inputs or outputs removed earlier. The original audience stays the same across remote and local subagent hops. Public origins may include content by default; private and unknown origins stay metadata-only unless both deployments explicitly allow them.
+
+The live delivery audience still matters. An unknown callback delivery, or one matching the origin, uses the session decision. A different explicit audience applies its own hard ceiling, so a private delivery stays redacted even when the trace began in public.
+
+Missing, malformed, duplicate, unsampled, untrusted, and mixed-version assertions fall back to metadata-only tracing. Dropped traces use only the unsampled trace flag. The decision is fixed when the remote session starts and reused by continuations. Agent Runs shows Workflow content only when both inputs and outputs are allowed.
+
 ## How remote dispatch and callbacks work
 
 A local subagent runs inline. A remote one runs in its own deployment, so dispatch is asynchronous:

package/docs/reference/cli.md

@@ -210,7 +210,7 @@ Pass a bare URL and the UI connects to that server instead of booting a local on
 | `-H, --header <header>`             | string | none               | Request header for a URL target, in `Name: value` form; repeat for multiple headers       |
 | `--no-ui`                           | flag   | UI on              | Start the server without an interactive UI                                                |
 | `--name <name>`                     | string | app folder name    | Title shown in the terminal UI                                                            |
-| `--input <text>`                    | string | none               | Pre-fill the prompt input; bare local `/model` starts onboarding                          |
+| `--input <text>`                    | string | none               | Pre-fill the prompt input                                                                 |
 | `--tools <mode>`                    | enum   | `auto-collapsed`   | Tool-call rendering: `full` \| `collapsed` \| `auto-collapsed` \| `hidden`                |
 | `--reasoning <mode>`                | enum   | `full`             | Reasoning rendering: `full` \| `collapsed` \| `auto-collapsed` \| `hidden`                |
 | `--subagents <mode>`                | enum   | `auto-collapsed`   | Subagent-section rendering: `full` \| `collapsed` \| `auto-collapsed` \| `hidden`         |
@@ -221,7 +221,7 @@ Pass a bare URL and the UI connects to that server instead of booting a local on
 
 `eve acp` reserves stdin and stdout for newline-delimited JSON-RPC and sends diagnostics to stderr. Without a URL, it supervises an isolated local development server. With a URL, it bridges ACP to that server's existing eve HTTP API and accepts the same URL credentials and request headers as `eve dev <url>`. Pass `--scope <team>` when the active Vercel scope does not own the deployment; `EVE_VERCEL_SCOPE` provides the same value for managed harnesses. See [Agent Client Protocol (ACP)](../protocols/acp) for client configuration and capability limits.
 
-A fresh `eve init` passes `--input /model`. That bare local input starts onboarding: the TUI installs the Vercel CLI if needed, asks you to log in if needed, opens `/model`, then offers categorized registry next steps before the first prompt. Other input stays editable in the prompt.
+A fresh `eve init` starts onboarding before the first prompt: the TUI installs the Vercel CLI if needed, asks you to log in if needed, guides you through model configuration, then lets you choose channels and integrations. Other `--input` text stays editable in the prompt.
 
 For a URL target protected by HTTP Basic auth, put the credentials in the URL. eve sends them as a Basic `Authorization` header and strips them from the server URL before connecting:
 

package/docs/tools/meta.json

@@ -1,5 +1,5 @@
 {
   "title": "Tools",
   "defaultOpen": false,
-  "pages": ["overview", "human-in-the-loop"]
+  "pages": ["overview", "human-in-the-loop", "workflows"]
 }

package/docs/tools/overview.mdx

@@ -78,6 +78,13 @@ Later task-triggered parent turns receive fresh state for the same cohort. The m
 to keep related intermediate results silent while any task remains pending. Once every related
 task is terminal, the state includes their outputs so the model can combine the useful results.
 
+### Durable tools
+
+A tool whose `execute` starts with `"use workflow"` runs as a durable Workflow run instead of
+inside the model step. It can wait for a person, a webhook, or a timer for as long as it takes, with
+nothing running in between, and its return value still settles the tool call. See
+[Durable tools](/docs/tools/workflows).
+
 ### The `ctx` parameter
 
 `execute` gets a `ctx` carrying the runtime accessors:

package/docs/tools/workflows.mdx

@@ -0,0 +1,288 @@
+---
+title: "Durable Tools"
+description: "Write a tool as a workflow so it can wait for a person, a webhook, or a timer for as long as it takes, with nothing running in between."
+url: /tools/workflows
+---
+
+A tool's `execute` may be a workflow. eve starts one durable run per tool call and, by default,
+waits for it: the run's return value is the tool result, however long it takes. While the run waits
+on a person, a webhook, or a sleep, the turn is parked and nothing is running. Mark the same tool
+`execution: "background"` and the model gets a receipt instead; eve wakes the agent with the return
+value when the run ends.
+
+Inside the tool, everything is the [Workflow SDK](https://workflow-sdk.dev): `"use workflow"`,
+`"use step"`, `createHook`, `createWebhook`, `sleep`, retries, replay. eve adds `ask` from
+`eve/workflow` — a question the human on the session's channel answers — and treats each `yield` as
+a durable progress report.
+
+## Write one
+
+```ts title="agent/tools/deploy.ts"
+import { defineTool } from "eve/tools";
+import { ask } from "eve/workflow";
+import { z } from "zod";
+
+export default defineTool({
+  description: "Deploy a service to production. Pauses for a human to approve the plan.",
+  inputSchema: z.object({ service: z.string() }),
+  async execute({ service }, ctx) {
+    "use workflow";
+
+    const plan = await planDeploy(service);
+    const answer = await ask(ctx, {
+      prompt: `Deploy ${service}?\n\n${plan.summary}`,
+      display: "confirmation",
+      options: [
+        { id: "approve", label: "Deploy", style: "primary" },
+        { id: "cancel", label: "Cancel" },
+      ],
+    });
+
+    if (answer.optionId !== "approve") {
+      return { deployed: false, reason: "rejected" };
+    }
+    return { deployed: true, url: await applyDeploy(plan) };
+  },
+});
+
+async function planDeploy(service: string) {
+  "use step";
+  return computePlan(service);
+}
+
+async function applyDeploy(plan: DeployPlan) {
+  "use step";
+  return runDeploy(plan);
+}
+```
+
+The model calls `deploy`. The turn parks while the human reads the plan. When they answer, minutes
+or days later, the run resumes, deploys, and returns. The model sees one tool result.
+
+### Rules
+
+- `"use workflow"` goes on its own line as the first statement of `execute`, or of a top-level
+  `async function` you reference as `execute: deploy`.
+- `"use step"` marks a top-level `async function` in the tool module, or any module it imports, as a
+  step. Side effects, clocks, randomness, `process.env`, and Node.js APIs belong in steps; the body
+  is replayed and must stay deterministic.
+- Import `createHook`, `createWebhook`, `sleep`, and `FatalError` from `workflow` in the body.
+  `start`, `getRun`, and `resumeHook` from `workflow/api` belong in steps. Your app does not install
+  the SDK; for types, new projects list `eve/workflow-modules` in the tsconfig `types`.
+- In the body, `ctx` has `session`, `callId`, `toolName`, and `abortSignal`. `getSandbox`,
+  `getSkill`, `getToken`, and `requireAuth` throw there; read credentials in a step instead.
+- The tool's input must be a JSON object. Workflow bodies are for static tools under `agent/tools/`,
+  not tools returned from `defineDynamic` resolvers.
+
+## Wait or run in the background
+
+|                          | default                             | `execution: "background"`                   |
+| ------------------------ | ----------------------------------- | ------------------------------------------- |
+| tool result              | the run's return value              | `{ status: "working", taskId }`             |
+| turn while the run lives | parked                              | continues                                   |
+| when the run ends        | result lands in the tool call       | agent is woken with the result or the error |
+| progress (`yield`)       | `action.partial` on the turn        | wakes the agent with a note                 |
+| cancel                   | cancelling the turn cancels the run | `task_cancel`, or the session ending        |
+
+Wait when the model needs the answer to continue. Go background when the wait may outlive the
+conversation or the user should keep talking in the meantime. Background tools require
+`experimental.tasks` on the root agent, like every background tool.
+
+## Ask a human: `ask`
+
+```ts
+import { ask } from "eve/workflow";
+
+const answer = await ask(ctx, {
+  prompt: string,
+  display?: "confirmation" | "select" | "text",
+  options?: { id: string; label: string; description?: string; style?: "primary" | "danger" | "default" }[],
+  allowFreeform?: boolean,
+}); // { optionId?: string; text?: string }
+```
+
+`ask` publishes an `input.requested` event on the session — rendered the way channels render
+`ask_question` and tool approvals — and returns the hook the answer resumes, the way `createHook`
+returns one. Awaiting it suspends the run until a response arrives. Because it is a hook, it composes
+with the SDK's own constructs; race it against a deadline:
+
+```ts
+const pending = ask(ctx, { prompt: `Deploy ${service}?`, options: APPROVE_OR_CANCEL });
+const answer = await Promise.race([pending, sleep("4h")]);
+if (answer === undefined) return { deployed: false, reason: "timed out" };
+```
+
+- The request belongs to the run, not the turn. It stays answerable until it is answered or the run
+  ends. In a background tool that means long after the turn that started it.
+- A request is answered once. Ask again for the next answer.
+- Ending the run, by returning, throwing, or cancellation, withdraws its pending requests.
+- Several requests may be outstanding at once.
+- A response never steers. A new human message while a request is pending follows the session's
+  normal `turnPolicy`.
+
+Compare the [`approval`](/docs/human-in-the-loop) policy, which gates the call before `execute` runs
+and can only show the model's input. Both compose: `approval` before the run, `ask` inside it.
+
+## Report progress: `yield`
+
+A workflow body may be an async generator. Each `yield` is a durable progress snapshot; the return
+value is the result, or the last `yield` when the body returns nothing.
+
+```ts
+async *execute({ service }, ctx) {
+  "use workflow";
+  yield { status: "planning" };
+  const plan = await planDeploy(service);
+  yield { status: "deploying" };
+  return { deployed: true, url: await applyDeploy(plan) };
+}
+```
+
+For a waiting tool each `yield` streams as an `action.partial` event, last-write-wins by tool call
+id, and never enters model history — the same contract as an in-process generator tool. For a
+background tool each `yield` wakes the owning agent with a note. Returning ends the run with the
+result; throwing ends it with the failure.
+
+## Cancel and clean up: `ctx.abortSignal`
+
+`ctx.abortSignal` aborts when the run is cancelled: a steered turn for a waiting tool, `task_cancel`
+or the session ending for a background one. It is durable — it survives replay, and a step that
+receives it observes the abort. Pass it into the steps that should stop, and clean up in
+`try/finally`:
+
+```ts
+async execute({ projectId }, ctx) {
+  "use workflow";
+  const jobId = await submitRender(projectId);
+  try {
+    return await waitForRender(jobId, ctx.abortSignal);
+  } finally {
+    if (ctx.abortSignal.aborted) await abortRender(jobId);
+  }
+}
+```
+
+After the signal fires, the run waits up to 30 seconds for the body to finish unwinding, then ends
+as cancelled whether or not it did. A body parked on a hook or a `sleep` does not observe the signal;
+it is abandoned when the grace period ends. Steps that received the signal are how you clean up
+first.
+
+## Flows
+
+### Approve with a deadline and an escalation
+
+```ts
+async execute({ service }, ctx) {
+  "use workflow";
+
+  const plan = await planDeploy(service);
+  const pending = ask(ctx, { prompt: `Deploy ${service}?`, display: "confirmation", options: APPROVE_OR_CANCEL });
+
+  let answer = await Promise.race([pending, sleep("4h")]);
+  if (answer === undefined) {
+    await pageOnCall(service);
+    answer = await Promise.race([pending, sleep("20h")]);
+  }
+
+  if (answer === undefined) return { deployed: false, reason: "timed out" };
+  if (answer.optionId !== "approve") return { deployed: false, reason: "rejected" };
+  return { deployed: true, url: await applyDeploy(plan) };
+}
+```
+
+One request stays on the channel the whole time. `sleep` is the deadline, `pageOnCall` is a step,
+and returning withdraws the request.
+
+### Wait for an external system to call back
+
+```ts
+import { createWebhook, FatalError } from "workflow";
+
+export default defineTool({
+  description: "Render a video. Returns the URL once the render farm finishes.",
+  inputSchema: z.object({ projectId: z.string() }),
+  async execute({ projectId }) {
+    "use workflow";
+
+    const done = createWebhook();
+    const jobId = await submitRender(projectId, done.url);
+    const callback = await done;
+    const { status, url } = await callback.json();
+
+    if (status !== "ok") throw new FatalError(`Render ${jobId} failed: ${status}`);
+    return { url };
+  },
+});
+```
+
+`createWebhook` mints a URL under `/.well-known/workflow/v1/webhook/` that eve serves. The external
+system posts to it when it is done. Nothing runs in between.
+
+### Ask now, act when answered
+
+```ts
+import { ask } from "eve/workflow";
+
+export default defineTool({
+  description: "Request approval to refund an order, then issue the refund once approved.",
+  inputSchema: z.object({ orderId: z.string(), amount: z.number() }),
+  execution: "background",
+  async execute({ orderId, amount }, ctx) {
+    "use workflow";
+
+    const decision = await ask(ctx, {
+      prompt: `Refund $${amount} on order ${orderId}?`,
+      display: "confirmation",
+      options: [
+        { id: "approve", label: "Refund", style: "primary" },
+        { id: "deny", label: "Deny" },
+      ],
+    });
+
+    if (decision.optionId !== "approve") return { refunded: false };
+    return { refunded: true, receipt: await issueRefund(orderId, amount) };
+  },
+});
+```
+
+The model reports that approval is pending and the conversation continues. The approval card stays
+on the channel. When it is answered, the refund runs and the agent is woken with the outcome.
+
+### Remind me later
+
+```ts
+import { sleep } from "workflow";
+
+export default defineTool({
+  description: "Remind the user about something after a delay.",
+  inputSchema: z.object({ note: z.string(), delay: z.string() }),
+  execution: "background",
+  async execute({ note, delay }) {
+    "use workflow";
+    await sleep(delay);
+    return { reminder: note };
+  },
+});
+```
+
+The session parks between the receipt and the wake. The agent receives the return value and relays
+it.
+
+## Semantics
+
+One call, one result. A waiting tool's call resolves once, with the return value, the error, or a
+cancellation. A background tool's call resolves once, with the receipt; everything after arrives as
+separate session input.
+
+While a waiting tool runs, the turn is parked. A `queue` message waits for it. A `steer` message
+cancels the turn, which cancels the run, which withdraws its requests. Input responses never steer.
+
+Background runs belong to the session. They survive turn completion and cancellation, appear in the
+session's task index, can be cancelled with `task_cancel`, and are cancelled when the session ends.
+
+Errors follow the SDK. A thrown error in a step retries per the step's policy; `FatalError` does
+not. An error that escapes the body fails the run.
+
+Identity follows the tool. The workflow id derives from the tool's path, so renaming or moving the
+file creates a new workflow. Runs in flight finish on the deployment that started them; a run that
+resumes on a deployment without its tool fails with an error naming the missing workflow.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eve",
-  "version": "0.47.7",
+  "version": "0.48.0",
   "private": false,
   "description": "Filesystem-first framework for durable backend AI agents that run anywhere.",
   "keywords": [
@@ -181,6 +181,16 @@
       "import": "./dist/src/public/tools/workflow.js",
       "default": "./dist/src/public/tools/workflow.js"
     },
+    "./workflow": {
+      "eve-source": "./src/public/workflow/index.ts",
+      "types": "./dist/src/public/workflow/index.d.ts",
+      "import": "./dist/src/public/workflow/index.js",
+      "default": "./dist/src/public/workflow/index.js"
+    },
+    "./workflow-modules": {
+      "eve-source": "./src/public/workflow-modules.d.ts",
+      "types": "./dist/src/public/workflow-modules.d.ts"
+    },
     "./models/openai": {
       "types": "./dist/src/public/models/openai/index.d.ts",
       "import": "./dist/src/public/models/openai/index.js",
@@ -417,6 +427,7 @@
     "@vercel/sandbox-delete": "npm:@vercel/sandbox@3.2.0",
     "@vercel/sandbox-drives": "npm:@vercel/sandbox@2.10.0-beta.0",
     "@vercel/sdk": "1.28.8",
+    "@workflow/builders": "5.0.0-beta.44",
     "@workflow/core": "5.0.0-beta.43",
     "@workflow/errors": "5.0.0-beta.17",
     "@workflow/serde": "5.0.0-beta.2",

package/dist/src/internal/authored-directive-prologue.d.ts

@@ -1,4 +0,0 @@
-export declare function assertNoWorkflowDirectivePrologue(input: {
-    readonly filePath: string;
-    readonly source: string;
-}): Promise<void>;

package/dist/src/internal/authored-directive-prologue.js

@@ -1 +0,0 @@
-import{parseWithNitroRolldownAst}from"#internal/bundler/nitro-rolldown.js";const UNSUPPORTED_WORKFLOW_DIRECTIVES=new Set([`use step`,`use workflow`]);async function assertNoWorkflowDirectivePrologue(t){let n=await parseWithNitroRolldownAst(t.filePath,t.source);if(!Array.isArray(n.body))throw Error(`Failed to parse authored module "${t.filePath}".`);for(let e of n.body){if(typeof e.directive!=`string`)break;if(UNSUPPORTED_WORKFLOW_DIRECTIVES.has(e.directive))throw Error(`Authored module "${t.filePath}" contains an actual "${e.directive}" directive. Workflow directives are reserved for eve-generated workflow entrypoints.`)}}export{assertNoWorkflowDirectivePrologue};