eve 0.5.4 → 0.6.0-beta.3

package/dist/docs/public/advanced/instrumentation.md

@@ -0,0 +1,165 @@
+---
+title: "instrumentation.ts"
+description: "Trace an agent with OpenTelemetry, read the workflow run tags Eve emits, and debug discovery with eve info and the error catalog."
+---
+
+`instrumentation.ts` is where you configure how an Eve agent is observed. The framework auto-discovers `agent/instrumentation.ts` and runs it at server startup before any agent code. Its presence implicitly enables telemetry, so there is no separate `isEnabled` toggle.
+
+## Three observability surfaces
+
+Eve observes an agent through three distinct surfaces. They do not all live in this file, and they write to different places, so it helps to keep them apart:
+
+| Surface                          | Configured in `instrumentation.ts`?                         | What it is                                                                                                                                                    |
+| -------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Workflow run tags** (`$eve.*`) | No (automatic)                                              | Framework-owned attributes on each Vercel Workflow run. Let dashboards stitch session, turn, and subagent runs into a tree and surface model and token usage. |
+| **OpenTelemetry export**         | Yes: `setup`, `recordInputs`, `recordOutputs`, `functionId` | Where AI SDK spans are exported and what they record.                                                                                                         |
+| **Runtime context events**       | Yes: `events["step.started"]`                               | Per-model-call values written into the AI SDK's runtime context, which the AI SDK carries onto its spans.                                                     |
+
+The two configurable surfaces send AI SDK spans to your OpenTelemetry backend. Workflow run tags are a separate system: they live on the Vercel Workflow run and are queryable in the Workflow dashboard, not on your OTel spans. The sections below cover what you configure here; [Workflow run tags](#workflow-run-tags) documents what Eve emits on its own.
+
+## Define instrumentation
+
+```ts title="agent/instrumentation.ts"
+import { BraintrustExporter } from "@braintrust/otel";
+import { defineInstrumentation } from "eve/instrumentation";
+import { registerOTel } from "@vercel/otel";
+
+export default defineInstrumentation({
+  setup: ({ agentName }) =>
+    registerOTel({
+      serviceName: agentName,
+      traceExporter: new BraintrustExporter({
+        parent: `project_name:${agentName}`,
+        filterAISpans: true,
+      }),
+    }),
+});
+```
+
+Export the result of `defineInstrumentation` as the default export.
+
+## OpenTelemetry
+
+The `setup` callback is invoked by the framework at server startup with the resolved agent name. Use it to register your OTel provider (for example `registerOTel` from `@vercel/otel`). The `context.agentName` is resolved at compile time from your project (the package's `name`, falling back to the app directory name), so you never need to hard-code a service name.
+
+Any OTel-compatible backend works (Braintrust, Honeycomb, Datadog, Jaeger). Install the exporter package you need and configure it in the callback.
+
+Three more fields control what the AI SDK records inside those spans (see the AI SDK's [telemetry reference](https://ai-sdk.dev/docs/ai-sdk-core/telemetry)):
+
+- `recordInputs` records full message history on each step span (defaults to `true`). Set it to `false` if inputs contain sensitive content or you want to reduce span payload size.
+- `recordOutputs` records model outputs on spans (defaults to `true`). Set it to `false` to disable output recording.
+- `functionId` overrides the function name on spans (defaults to the agent name).
+
+The third configurable surface, [runtime context events](#runtime-context), attaches per-model-call values to these spans.
+
+## Runtime context
+
+_Runtime context_ is an [AI SDK concept](https://ai-sdk.dev/docs/reference/ai-sdk-core/stream-text): a user-defined object that flows through a generation lifecycle. Eve exposes it through `events["step.started"]`, a callback that runs once Eve has assembled the model input for an attempt and returns `{ runtimeContext }`. Because Eve registers the AI SDK's OpenTelemetry integration with runtime context enabled, those returned values ride onto the model-call span and its children. That is the reason this surface exists. The returned field is named `runtimeContext`, not `metadata`, because AI SDK v7 carries per-call attributes on runtime context rather than a dedicated metadata field.
+
+Use it when the values depend on the current session, turn, step, channel, or model input:
+
+```ts
+import { defineInstrumentation, isChannel } from "eve/instrumentation";
+import supportChannel from "./channels/support.js";
+
+export default defineInstrumentation({
+  events: {
+    "step.started"(input) {
+      if (!isChannel(input.channel, supportChannel)) {
+        return undefined;
+      }
+
+      return {
+        runtimeContext: {
+          "support.channel_id": input.channel.metadata.channelId ?? "",
+          "support.user_id": input.channel.metadata.triggeringUserId ?? "",
+        },
+      };
+    },
+  },
+});
+```
+
+For authored channels, Eve emits compiler-owned typings keyed by the channel filename. A file at `agent/channels/support.ts` narrows as `channel:support`, either by checking `input.channel.kind === "channel:support"` or by using `isChannel(input.channel, supportChannel)`.
+
+The callback receives:
+
+- `session`: the session id, current and initiator auth, and parent session lineage when this is a child run
+- `turn`: the stream turn id and sequence, for example `turn_0`
+- `step`: the zero-based step index inside the turn
+- `channel`: the channel's `kind` and the metadata projected by the active channel
+- `modelInput`: the final instructions and messages passed to the model call
+
+A channel exposes its identity through `kind`, the discriminant you narrow on. For authored channels it is `channel:<name>`, where `<name>` is the channel's filename under `agent/channels/`, so `agent/channels/support.ts` is `channel:support`. Framework channels use `http`, `schedule`, or `subagent`; an unrecognized or absent kind normalizes to `unknown`. The kind is also emitted as the `eve.channel.kind` span attribute.
+
+Channel metadata is channel-owned. Built-in channels expose only the fields they choose to make observable; Slack, for example, projects `channelId`, `teamId`, `threadTs`, and `triggeringUserId` from its durable channel state. User-authored channels expose their own projection by returning `metadata(state)` from `defineChannel`. Runtime instrumentation never falls back to raw channel state.
+
+## Trace hierarchy
+
+When telemetry is enabled, each turn produces a trace like:
+
+```text
+ai.eve.turn  {eve.session.id}
+  +-- ai.streamText                           step 1
+  |     +-- ai.streamText.doStream            model call
+  |     +-- ai.toolCall  {toolName: search}   tool exec
+  +-- ai.streamText                           step 2
+  |     +-- ai.streamText.doStream
+  |     +-- ai.toolCall  {toolName: read}
+  +-- ai.streamText                           step 3 (final text)
+```
+
+Eve creates the `ai.eve.turn` parent span per turn and passes enriched telemetry to the AI SDK so model calls and tool executions are traced automatically. Session, turn, step, and channel context is injected as the framework half of the runtime context (`eve.version`, `eve.session.id`, `eve.environment`, `eve.turn.id`, `eve.turn.sequence`, `eve.step.index`, `eve.channel.kind`) and rides onto the spans alongside any values your `events["step.started"]` callback returns under `runtimeContext`.
+
+## Workflow run tags
+
+Separately from OpenTelemetry, Eve tags every workflow run with reserved `$eve.*` attributes. These live on the Vercel Workflow run, queryable in the Workflow dashboard, not on OTel spans, and you do not configure them: they are framework-owned and emitted automatically on every session, turn, and subagent run, whether or not an `instrumentation.ts` file is present. Authored code cannot set or override the `$eve.` namespace.
+
+Their job is to let a dashboard reconstruct the tree of runs behind a single agent invocation and surface model and token usage without reading run bodies.
+
+Structural tags describe each run's place in the tree:
+
+- `$eve.type`: `"session"`, `"turn"`, or `"subagent"`
+- `$eve.parent`: session id of the immediate parent
+- `$eve.root`: session id of the root session in the chain (group a whole tree with `$eve.root=<id>`)
+- `$eve.subagent`: compiled graph node id (subagent runs only)
+- `$eve.trigger`: the channel kind that started the run
+- `$eve.title`: truncated title derived from the first user message
+
+Per-turn usage tags are written on each step of a turn, accumulating cumulative totals (last write wins):
+
+- `$eve.model`: model id for the turn
+- `$eve.input_tokens`, `$eve.output_tokens`, `$eve.cache_read_tokens`: running token counts
+- `$eve.tool_count`: number of tools available to the turn
+
+Tag writes are best-effort: a failure is logged once per process and then swallowed, so a broken tag emit never breaks the agent.
+
+## Debugging
+
+`eve info` is the fastest way to see what Eve actually picked up: the active tools, skills, subagents, schedules, routes, and discovery diagnostics. Eve also writes inspectable artifacts under `.eve/`, kept even when discovery hits errors:
+
+| Artifact                        | Tells you                                   |
+| ------------------------------- | ------------------------------------------- |
+| `agent-discovery-manifest.json` | what Eve found on disk                      |
+| `diagnostics.json`              | authored-shape errors and warnings          |
+| `compiled-agent-manifest.json`  | the serialized surface Eve loads at runtime |
+| `module-map.mjs`                | compiled module entrypoints Eve imports     |
+
+When `eve build` fails on discovery errors, the CLI prints the full diagnostics report (severity, message, source path) and the path to the diagnostics artifact.
+
+### Common failures
+
+| Symptom                                       | Likely cause and fix                                                                                                                                                                                     |
+| --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Tool not discovered (the model never sees it) | Run `eve info`. Confirm the file is in the right slot (`agent/tools/<name>.ts`) and default-exports `defineTool(...)`, and check `.eve/diagnostics.json` for shape errors. `schedules/` are root-only.   |
+| Model won't call a tool it should             | Tighten the tool `description` and `inputSchema`; put procedural guidance in a [skill](../skills), not the description. Confirm it's in the active set with `eve info`.                                  |
+| Stuck on `session.waiting`                    | The turn is parked on an approval, a question, or a connection sign-in. Answer it, or POST a follow-up with the `continuationToken` (a stale token is rejected).                                         |
+| 401 on production routes                      | Expected: auth fails closed. Replace `placeholderAuth()`, and set `VERCEL_PROJECT_ID` and environment so `vercelOidc()` accepts user tokens. See [Auth & route protection](./auth-and-route-protection). |
+| Build fails with discovery errors             | Read the printed diagnostics and `.eve/diagnostics.json`; confirm the root-vs-subagent boundary is valid and secrets come from env vars.                                                                 |
+
+## What to read next
+
+- [`agent.ts`](../agent-config)
+- [Hooks](./hooks): observe the runtime event stream
+- [Dev TUI](./dev-tui): drive the agent locally
+- [Evals](./evals): repeatable scored checks

package/dist/docs/public/advanced/meta.json

@@ -0,0 +1,21 @@
+{
+  "title": "Advanced",
+  "pages": [
+    "default-harness",
+    "context-control",
+    "dynamic-capabilities",
+    "dynamic-workflows",
+    "hooks",
+    "session-context",
+    "state",
+    "remote-agents",
+    "auth-and-route-protection",
+    "security-model",
+    "deployment",
+    "instrumentation",
+    "dev-tui",
+    "evals",
+    "execution-model-and-durability",
+    "sessions-runs-and-streaming"
+  ]
+}

package/dist/docs/public/advanced/remote-agents.md

@@ -0,0 +1,60 @@
+---
+title: "Remote Agents"
+description: "Call another Eve deployment as a subagent with defineRemoteAgent: same lowered tool shape, outbound auth, durable callback dispatch."
+---
+
+Sometimes the specialist you want to delegate to isn't a directory in your repo, it's a separately owned agent living behind its own URL. `defineRemoteAgent` lets you call another Eve deployment as if it were a local subagent.
+
+The file lives under `agent/subagents/`, so its tool name is still derived from the path. There's no `name` field.
+
+```ts title="agent/subagents/weather.ts"
+import { defineRemoteAgent } from "eve";
+import { vercelOidc } from "eve/agents/auth";
+
+export default defineRemoteAgent({
+  url: "https://weather-agent.example.com",
+  description: "Answers weather, temperature, forecast, wind, rain, and snow questions.",
+  auth: vercelOidc(),
+});
+```
+
+`defineRemoteAgent` accepts:
+
+- `url`: the remote Eve deployment root. Required.
+- `description`: the model-visible delegation description. Required.
+- `auth`: optional outbound auth hook from `eve/agents/auth`.
+- `headers`: optional static or lazy request headers.
+- `path`: optional session-create path; defaults to `/eve/v1/session`.
+- `outputSchema`: optional structured return type the caller requires (lowered to JSON Schema at compile time and enforced by the remote like any task-mode output schema).
+
+## The lowered tool
+
+A remote agent lowers to the same `{ message, outputSchema? }` tool shape as a local subagent. The parent packs everything the remote needs into `message`; the remote never sees the parent's history. Set `outputSchema` (here or per call) and the remote runs in task mode, returning structured output as the tool result.
+
+## Outbound auth
+
+`auth` is an `OutboundAuthFn` from `eve/agents/auth`. It attaches request headers to the outbound dispatch:
+
+| Helper                          | Header                                                                       |
+| ------------------------------- | ---------------------------------------------------------------------------- |
+| `vercelOidc(opts?)`             | `Authorization: Bearer <Vercel OIDC token>` (deployment-to-deployment trust) |
+| `bearer(token)`                 | `Authorization: Bearer <token>` (static or lazily resolved)                  |
+| `basic({ username, password })` | `Authorization: Basic …`                                                     |
+
+If you're calling another Vercel-deployed Eve agent, reach for `vercelOidc()`: the remote verifies the OIDC token to authorize the caller. See [Auth & route protection](./auth-and-route-protection) for the receiving side.
+
+## Callback / park dispatch
+
+A local subagent runs inline. A remote one runs in its own deployment, so dispatch has to be asynchronous:
+
+1. The parent starts a task-mode session on the remote's `POST /eve/v1/session`, passing a framework callback URL.
+2. The parent turn parks durably until the remote posts a terminal callback, holding no compute while it waits.
+3. When the callback arrives, the parent resumes and surfaces the result.
+
+The parent stream carries the same `subagent.called`, `action.result`, and `subagent.completed` events as local delegation. For a remote call, `subagent.called.data.remote.url` records the target. A failed _start_ comes back as a failed tool result, so the caller can explain or recover within the same session. Terminal callback delivery runs as a durable Workflow step on the callee: a failed callback POST is rethrown rather than marking the task complete, which puts redelivery under Workflow retry policy.
+
+## What to read next
+
+- Local delegation and the isolation boundary → [Subagents](../subagents)
+- Have the model orchestrate remote agents programmatically → [Dynamic workflows](./dynamic-workflows)
+- Securing the receiving deployment → [Auth & route protection](./auth-and-route-protection)

package/dist/docs/public/advanced/security-model.md

@@ -0,0 +1,79 @@
+---
+title: "Security Model"
+description: "Trust boundaries, where secrets live, how credentials reach hosts, and what fails closed by default."
+---
+
+Your agent runs across two contexts, with a trust boundary drawn between them and every secret kept on the trusted side. This page is the mental model to use when you're deciding what an agent (and the model driving it) is allowed to reach.
+
+## Trust boundaries
+
+|                         | App runtime  | Sandbox               |
+| ----------------------- | ------------ | --------------------- |
+| `process.env` / secrets | Yes          | No                    |
+| Your Node.js code       | Yes          | No                    |
+| Network                 | Unrestricted | Controlled by policy  |
+| Filesystem              | App's own    | Isolated `/workspace` |
+
+The app runtime is the trusted side. Your tool implementations, model calls, connections, state, and durable execution all run here, with `process.env` and full Node.js available. (On Vercel, this is a Vercel Function.)
+
+The sandbox is the isolated side. The model runs shell commands there through the built-in `bash`, `read_file`, `write_file`, `glob`, and `grep` tools. It gets its own `/workspace` filesystem, but no `process.env`, no secrets, and no path back into the app runtime. (On Vercel, each sandbox is a [Vercel Sandbox](https://vercel.com/docs/sandbox) microVM with hardware-level isolation.) The only thing that actually executes in the sandbox is shell commands. Even the built-in `bash`/`read_file`/`write_file` tools live in the app runtime and _proxy_ into the sandbox. The model sees tool definitions and results, never your secrets.
+
+A concrete trace makes the boundary clear. When the model calls a custom `charge_card` tool, its `execute` runs in the app runtime, reads `process.env.STRIPE_KEY`, calls Stripe, and returns `{ ok: true }`. The model sees only `{ ok: true }`: the key never leaves the app runtime, and nothing about the call touches the sandbox. The built-in `write_file` is the mirror image, running in the app runtime and proxying the write into the sandbox `/workspace`. Either way the model drives the work through tool calls and their results, never by holding a credential or reaching the runtime directly.
+
+## Credential brokering
+
+Sometimes the model needs _authenticated_ network access from inside the sandbox, like a `git clone` of a private repo or an authenticated `curl`, and there's no [tool](../tools) or [connection](../connections) to route it through. That's what credential brokering is for. On the Vercel Sandbox backend, auth headers get injected at the sandbox's network firewall for matching domains. The secret stays in the app runtime; the sandbox process only ever sees the response. See [Vercel Sandbox Credential Brokering](https://vercel.com/docs/sandbox/concepts/firewall#credentials-brokering) for the platform mechanism, and [Sandbox](../sandbox) for the Eve policy API.
+
+## Connection credentials
+
+[Connection](../connections) tokens (MCP and OpenAPI) come from either `getToken()` or an interactive OAuth flow, and Eve injects the resolved token into every outbound request. The token is cached per step and never serialized to durable state.
+
+## Channel verification
+
+A [channel](../channels/overview) is your agent's front door, which makes authenticating inbound traffic its job. The built-in platform channels follow two rules here, and so must any channel you write yourself:
+
+- **Verify signatures in constant time.** Platform channels (Slack, GitHub,
+  Telegram, Twilio) verify the platform's HMAC signature over the raw request body
+  with a constant-time comparison, so timing the response can't reveal a forged
+  signature. Use a constant-time compare for any secret you check, never `===` on
+  a signature.
+- **Don't trust body-supplied identity.** Derive the caller from a _verified_
+  signature or token, never from a `principalId` (or similar) the request body
+  claims. A body field is attacker-controlled; treating it as identity is
+  cross-user impersonation.
+
+(The `support-agent` dashboard channel breaks both on purpose, with a timing-unsafe comparison and a body-supplied principal, as a _what-not-to-do_ example. Don't copy it.)
+
+## Authored markdown is data
+
+[Skill](../skills) and [schedule](../schedules) files are markdown with YAML frontmatter, and Eve treats that frontmatter strictly as data. The code-capable engines (`---js` / `---javascript`, which would `eval()` the frontmatter body the moment the file is parsed) are disabled. A fence like that throws rather than running. Frontmatter has to parse to a plain YAML object.
+
+## Auth fails closed
+
+Routes reject unauthenticated traffic by default: if no `AuthFn` in the walk accepts the request, it gets a `401`, and admitting anonymous callers takes an explicit `none()`. The scaffold's `placeholderAuth()` keeps a half-configured app closed in production until you replace it. See [Auth & route protection](../advanced/auth-and-route-protection) for the full walk and verifiers.
+
+## Pre-production checklist
+
+Before exposing an agent to real traffic:
+
+- [ ] Replace `placeholderAuth()` in `agent/channels/eve.ts` with a real
+      `AuthFn` (`vercelOidc()`, `httpBasic()`, `oidc()`, or your own). Verify an
+      unauthenticated production request gets `401`.
+- [ ] Verify channel signatures. Each platform channel needs its signing
+      secret set; custom channels must verify signatures in constant time and never
+      trust body-supplied identity.
+- [ ] Keep secrets in `process.env`, never in compiled artifacts, never
+      passed into the sandbox. Route privileged calls through tools or connections.
+- [ ] Scope connection tokens to the least privilege the agent needs; they
+      reach hosts but never the model.
+- [ ] Set a sandbox network policy tighter than `allow-all` if the model
+      shouldn't have open egress; use credential brokering for authenticated egress.
+- [ ] Don't surface untrusted text as markup. Model- or user-controlled
+      strings rendered into a channel UI should be escaped for that surface.
+
+## What to read next
+
+- [Auth & route protection](./auth-and-route-protection): the full auth walk and verifier helpers
+- [Sandbox](../sandbox): backends, network policy, and brokering config
+- [Execution model & durability](./execution-model-and-durability): how durable sessions run
+- [Connections](../connections): static-token and OAuth connections

package/dist/docs/public/advanced/session-context.md

@@ -0,0 +1,149 @@
+---
+title: "Session context"
+description: "Runtime helpers: ctx.session, ctx.getSandbox, ctx.getSkill, and defineState."
+---
+
+Eve exposes runtime state through the `ctx` parameter passed to tool `execute`, hook handlers, and channel event handlers:
+
+- `ctx.session`: session metadata, turn, auth, and parent lineage
+- `ctx.getSandbox()`: live sandbox handle for the current agent
+- `ctx.getSkill(identifier)`: handle for a named skill visible to the current agent
+- `defineState(name, initial)`: typed durable state with `get()` and `update()` (imported from `eve/context`)
+
+These APIs work only inside active authored runtime execution such as tools, channel event handlers, and authored hooks. They throw when called outside a managed context.
+
+## `ctx.session`
+
+Use `ctx.session` when you need durable runtime metadata about the current execution.
+
+```ts title="agent/tools/who_called_me.ts"
+import { defineTool } from "eve/tools";
+import { z } from "zod";
+
+export default defineTool({
+  description: "Return the active session metadata.",
+  inputSchema: z.object({}),
+  async execute(_input, ctx) {
+    return {
+      sessionId: ctx.session.id,
+      turnId: ctx.session.turn.id,
+      turnSequence: ctx.session.turn.sequence,
+      currentCaller: ctx.session.auth.current?.principalId,
+      initiator: ctx.session.auth.initiator?.principalId,
+      parentSessionId: ctx.session.parent?.sessionId,
+      parentCallId: ctx.session.parent?.callId,
+    };
+  },
+});
+```
+
+Public session fields:
+
+- `auth.current`
+- `auth.initiator`
+- `id`
+- `turn.id`
+- `turn.sequence`
+- optional `parent`
+
+Important behavior:
+
+- `auth.current` is the caller for the active inbound turn.
+- `auth.initiator` is the caller that started the durable session.
+- Unprotected agents expose both as `null`.
+- Top-level schedule sessions expose the framework app principal (`principalId: "eve:app"`, `principalType: "runtime"`).
+- `parent` is present for child subagent sessions and includes the parent `callId`, `sessionId`, `rootSessionId`, and `turn`.
+
+## `ctx.getSandbox()`
+
+`ctx.getSandbox()` returns a live handle for the current agent's sandbox.
+
+```ts
+const sandbox = await ctx.getSandbox();
+const result = await sandbox.run({ command: "pnpm test" });
+```
+
+Important behavior:
+
+- It takes no arguments: each agent has exactly one sandbox.
+- It is async because Eve binds or restores sandbox state lazily.
+- It only works when sandbox access is attached to the active runtime path.
+- Visibility is node-local: a subagent sees its own sandbox, not the parent's.
+
+`SandboxSession` also exposes `resolvePath(path)` for cases where authored code needs the live backend-native path for a logical `/workspace/...` location before passing it to shell code or a child process.
+
+See [Sandbox](../sandbox) for lifecycle details.
+
+## `ctx.getSkill(identifier)`
+
+`ctx.getSkill(identifier)` returns a handle for a named skill visible to the current agent.
+
+```ts
+const skill = ctx.getSkill("research");
+const notes = await skill.file("references/checklist.md").text();
+```
+
+Important behavior:
+
+- It is synchronous; file content is read lazily from the active sandbox.
+- It only works when sandbox access is attached to the active runtime path.
+- `identifier` is the path-derived skill id.
+- Visibility follows the current agent's sandbox.
+- Missing skills surface when a file accessor reads a missing sandbox path.
+- The returned handle exposes `name` and `file(relativePath)`.
+
+See [Skills](../skills) for the full authoring model.
+
+## Custom state with `defineState`
+
+Use `defineState` when your agent needs durable typed state that tools, hooks, and channel handlers can share. State survives across workflow step boundaries. Declare the handle at module scope so every importer shares it:
+
+```ts title="agent/lib/budget.ts"
+import { defineState } from "eve/context";
+
+interface BudgetState {
+  readonly count: number;
+  readonly cap: number;
+}
+
+export const budget = defineState<BudgetState>("myapp.budget", () => ({
+  count: 0,
+  cap: 25,
+}));
+```
+
+`get()` reads the current value (returning `initial()` on first access), and `update(fn)` applies a function to it. Both throw outside a managed scope. See [State](./state) for the full read/write model and examples from tools and hooks.
+
+## Where these APIs work
+
+Safe places:
+
+- inside `defineTool(...).execute(input, ctx)`
+- inside authored callbacks Eve runs inside the runtime
+- after asynchronous boundaries inside the same authored execution chain
+
+Unsafe places:
+
+- top-level module evaluation
+- build scripts
+- discovery-time code paths
+
+If you call them outside an active Eve runtime context, they throw immediately with a message explaining the required scope.
+
+## How it works
+
+The framework sets up a context container before invoking authored code:
+
+1. The runtime populates durable seed values (auth, session id, compiled bundle).
+2. Before each step, the framework derives step-local values (session metadata, sandbox access, skill access) from the durable state.
+3. Authored code runs inside the managed scope, so `ctx` and `defineState` accessors resolve automatically.
+4. After the step, the framework commits mutable state (for example sandbox changes) back to the durable session.
+
+This lifecycle is fully managed by the framework. Authored code only needs to use `ctx` and the public accessors.
+
+## What to read next
+
+- [State](./state)
+- [Sessions, runs & streaming](./sessions-runs-and-streaming)
+- [Subagents](../subagents)
+- [Skills](../skills)

package/dist/docs/public/advanced/sessions-runs-and-streaming.md

@@ -0,0 +1,127 @@
+---
+title: "Sessions, Runs & Streaming"
+description: "The session and run contract you touch: continuation tokens, stream handles, the NDJSON event stream, and reconnecting."
+---
+
+Every Eve app speaks the same stable HTTP API to a [durable session](./execution-model-and-durability). This page is the contract you hold: the handles you get back, the events you stream, and how to reconnect.
+
+## The two handles
+
+Two handles do two jobs here, and mixing them up is the most common mistake. One handle creates and resumes a session; a different one streams and inspects it.
+
+- **`continuationToken`**: the resume handle. Use it to send a follow-up message to the same conversation. Owned by the channel.
+- **`sessionId` / `runId`**: the stream-and-inspect handle. Use it to attach to the event stream and watch a run. Owned by the runtime.
+
+A session has one active continuation at a time: each follow-up uses the current `continuationToken`, and a stale one is rejected.
+
+React, Vue, and Svelte apps reach for [`useEveAgent()`](../frontend/overview) instead of calling these routes by hand. Next.js and Nuxt apps can proxy them to the Eve runtime from the same origin.
+
+## Start a session
+
+```bash
+curl -X POST http://127.0.0.1:3000/eve/v1/session \
+  -H 'content-type: application/json' \
+  -d '{"message":"Summarize the latest forecast."}'
+```
+
+Eve responds right away. The JSON body carries a `sessionId` and a `continuationToken`, and the `x-eve-session-id` header tells you which durable session to stream.
+
+## Stream a session
+
+```bash
+curl http://127.0.0.1:3000/eve/v1/session/<sessionId>/stream
+```
+
+The stream is newline-delimited JSON (NDJSON), one event per line:
+
+| Event                     | Meaning                                                                                        |
+| ------------------------- | ---------------------------------------------------------------------------------------------- |
+| `session.started`         | A durable session was created.                                                                 |
+| `turn.started`            | A new turn began.                                                                              |
+| `message.received`        | An inbound user message was accepted.                                                          |
+| `step.started`            | A model step began.                                                                            |
+| `actions.requested`       | The model requested tool calls.                                                                |
+| `action.result`           | A tool call returned.                                                                          |
+| `input.requested`         | The run paused for human input (HITL approval or `ask_question`); carries `requests`.          |
+| `subagent.called`         | A subagent was delegated; carries `childSessionId` to attach to.                               |
+| `subagent.completed`      | A delegated subagent finished.                                                                 |
+| `reasoning.appended`      | A reasoning delta (incremental, with cumulative text so far).                                  |
+| `reasoning.completed`     | The finalized reasoning block.                                                                 |
+| `message.appended`        | An assistant text delta (incremental, with cumulative text so far).                            |
+| `message.completed`       | A finalized assistant text block.                                                              |
+| `result.completed`        | The finalized structured result for a turn that requested an output schema; carries `result`.  |
+| `compaction.requested`    | Context-window compaction began; carries `modelId`, `sessionId`, `turnId`, `usageInputTokens`. |
+| `compaction.completed`    | A compaction checkpoint was written to durable history.                                        |
+| `authorization.required`  | A connection needs OAuth; carries `name`, `description`, and an `authorization` challenge.     |
+| `authorization.completed` | A connection's authorization resolved; carries `outcome`.                                      |
+| `step.completed`          | A model step finished; carries `finishReason` and usage.                                       |
+| `step.failed`             | A model step failed; carries `{ code, message, details? }`.                                    |
+| `turn.completed`          | The turn finished.                                                                             |
+| `turn.failed`             | The turn failed; carries `{ code, message, details? }`.                                        |
+| `session.waiting`         | The session parked, waiting for the next input (a message, an answer).                         |
+| `session.failed`          | The session failed.                                                                            |
+| `session.completed`       | The session reached a terminal end.                                                            |
+
+`reasoning.appended` and `message.appended` stream deltas as they arrive, and each one carries both the new delta and the cumulative text for the current block. The finalized block shows up on `message.completed` and `reasoning.completed`, which is the compatibility path for clients that don't render incremental streaming.
+
+`message.completed` can fire more than once in a turn: the agent often emits interim assistant text before a tool call. To tell tool-call narration from a terminal reply, check `message.completed.data.finishReason`. `step.completed.data.finishReason` mirrors the step outcome, and usage lives on `step.completed`.
+
+A delegated subagent publishes progress on its own child-session stream. The parent only emits `subagent.called` with a `childSessionId`, which a client uses to attach.
+
+`step.failed` and `turn.failed` carry `{ code, message, details? }` for the failed fragment or turn, and `session.failed` is the terminal session-level variant. When a turn requested an output schema, the finalized payload lands on `result.completed` as `data.result` before the turn boundary. `authorization.required` carries the sign-in challenge (`data.authorization` may include `url`, `userCode`, `expiresAt`, `instructions`), and `authorization.completed` carries `data.outcome` (`"authorized" | "declined" | "failed" | "timed-out"`).
+
+## Send a follow-up message
+
+Once the session is waiting (you'll see `session.waiting`), POST your follow-up to the session endpoint with the stored continuation token:
+
+```bash
+curl -X POST http://127.0.0.1:3000/eve/v1/session/<sessionId> \
+  -H 'content-type: application/json' \
+  -d '{"continuationToken":"<token>","message":"Now send the short version."}'
+```
+
+The follow-up reuses the same durable session: same history, same state.
+
+For deterministic ordering, send one follow-up at a time and wait for the next `session.waiting` event before sending another message to the same session. See [message delivery and queueing](./execution-model-and-durability#message-delivery-and-queueing) for the current runtime contract.
+
+## Reconnect and rewind
+
+The stream is durable. Every event is recorded before a step completes, so it's all replayable. Pass `startIndex` to reconnect by event count and pick up where you dropped off, or rewind to the start:
+
+```bash
+curl "http://127.0.0.1:3000/eve/v1/session/<sessionId>/stream?startIndex=<count>"
+```
+
+## Use the client from TypeScript
+
+For scripts, server-to-server calls, tests, evals, and custom UIs, `eve/client` wraps these routes in a typed client so you don't hand-roll the POST and NDJSON stream loop.
+
+Start with the [TypeScript Client](../client/overview) guide. It covers basic usage, sending messages, continuations, streaming, and per-turn `outputSchema` results.
+
+## Inspect the agent over HTTP
+
+`GET /eve/v1/info` returns a JSON inspection payload for the running agent: model id, instructions preview, skills, schedules, subagents, tools, sandbox, and the runtime's endpoint catalog. It's the `eve info` CLI, served over HTTP.
+
+```bash
+curl http://127.0.0.1:3000/eve/v1/info
+```
+
+The route uses the same default auth chain as the eve channel (`[localDev(), vercelOidc()]`). Locally it answers anonymously; a deployed Vercel target requires a valid OIDC bearer, with a same-project bypass for in-deployment callers. See [auth & route protection](../advanced/auth-and-route-protection).
+
+## Dispatch order
+
+Every stream event runs four steps, in this order:
+
+1. **Channel handler**: the channel's event handler runs and can mutate adapter state.
+2. **Metadata projection**: the framework re-evaluates the channel's `metadata(state)` and stores the result.
+3. **Hooks**: authored [hooks](../advanced/hooks) subscribed to the event fire.
+4. **Dynamic resolvers**: [dynamic](../advanced/dynamic-capabilities) tool, skill, and instruction resolvers fire, and `ctx.channel.metadata` already holds the freshly projected metadata from step 2.
+
+The order isn't incidental, it's structural. By the time a resolver or hook reads channel metadata, the channel has already updated its state and the projection is current.
+
+## What to read next
+
+- [Execution model & durability](./execution-model-and-durability): what makes a session durable and how parked work resumes.
+- [Channels](../channels/overview): what owns the continuation token and delivery.
+- [TypeScript Client](../client/overview): call these routes from scripts and server-side code.
+- [Frontend](../frontend/overview): `useEveAgent` instead of raw routes.