eve 0.78.0 → 0.79.1

package/dist/src/vue/use-eve-agent.d.ts

@@ -104,6 +104,12 @@ export interface UseEveAgentOptions<TData> extends EveAgentStoreCallbacks<TData>
     readonly optimistic?: boolean;
     /** Follow each subagent call's session into `conversation.agents` while mounted. @default false */
     readonly followSubagents?: boolean;
+    /**
+     * Keep the session stream open between turns to show events that arrive from schedules,
+     * channels, or other clients. Set to false to close it once the session is idle and reopen it
+     * on the next send, answer, or resume. @default true
+     */
+    readonly followIdle?: boolean;
     /** Prewarm an owned session on mount and after reset. @default false */
     readonly prewarm?: boolean;
     /**

package/dist/src/vue/use-eve-agent.js

@@ -1,3 +1,3 @@
-import { t as useEveAgent } from "../chunks/use-eve-agent-B8brxCk-.js";
+import { t as useEveAgent } from "../chunks/use-eve-agent-Vsl-S0yI.js";
 
 export { useEveAgent };

package/docs/agent-config.md

@@ -75,6 +75,54 @@ prefix. Each subagent session gets its own key. An authored
 in the `session-id` header, which the Codex backend uses for cache routing.
 Gateway-routed calls do not receive the option.
 
+### Use a local model
+
+To test against a model running on your own machine, point the AI SDK
+[OpenAI-compatible provider](https://ai-sdk.dev/providers/openai-compatible-providers)
+at a local server. This works with any server that implements the OpenAI Chat
+Completions API, such as Ollama, LM Studio, llama.cpp, or vLLM. With
+[Ollama](https://docs.ollama.com/api/openai-compatibility):
+
+```bash
+pnpm add @ai-sdk/openai-compatible
+ollama pull gpt-oss:20b
+OLLAMA_CONTEXT_LENGTH=64000 ollama serve
+```
+
+```ts title="agent/agent.ts"
+import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
+import { defineAgent } from "eve";
+
+const ollama = createOpenAICompatible({
+  name: "ollama",
+  baseURL: "http://localhost:11434/v1",
+  includeUsage: true, // report token usage while streaming
+});
+
+export default defineAgent({
+  model: ollama("gpt-oss:20b"),
+  modelContextWindowTokens: 64_000,
+});
+```
+
+- **Context window.** AI Gateway has no metadata for local models, so set
+  `modelContextWindowTokens` to the context length your server allocates, not
+  the model's maximum. eve uses it to decide when to compact. Ollama allocates
+  as little as 4K tokens by default; raise it to at least 64K for agents, as
+  above.
+- **Tool calling.** eve agents call tools on most turns, so pick a model with
+  native tool-calling support. `gpt-oss:20b`, `qwen3`, and `gemma4` are good
+  starting points on Ollama.
+- **Usage.** `includeUsage: true` lets token usage reach eve's
+  [session limits](#runtime-limits). Local models report no cost, so
+  `maxTokenCostUsdPerSession` does not apply.
+- **Other servers.** Change `baseURL`, for example to
+  `http://localhost:1234/v1` for LM Studio. Pass `apiKey` for a remote
+  OpenAI-compatible server that requires one.
+
+A deployment cannot reach a server on your machine, so use a Gateway or hosted
+provider model when you deploy.
+
 ### Choose the model dynamically
 
 To select a model from the incoming prompt with an AI SDK decision model, use

package/docs/channels/eve.mdx

@@ -203,6 +203,8 @@ Stream a session as newline-delimited JSON from `GET /eve/v1/session/:sessionId/
 
 Following a stranded session's stream returns `409 session_stranded`, just like a send. The TypeScript client reports `ClientSessionStrandedError` without retrying. Pass `follow=false` to read the recorded history instead: the response ends at the durable tail, carries the `x-eve-stream-tail-index` header, and never inspects or changes the session, so it works before a reset. A reset attempts to append `session.failed` with code `session_stranded` and close the stream. Existing readers finish when they receive that terminal event.
 
+After a session ends, the World keeps its stream only for its retention period. Reading a stream past that point returns `410 session_expired`. The history is gone, so the TypeScript client fails on the first response with a `ClientError` whose `code` is `"session_expired"`, without retrying.
+
 ### Cancel a turn
 
 Post to `/eve/v1/session/:sessionId/cancel` to request cancellation of the active turn. You can include the observed `turnId` to keep a late request from cancelling a newer turn. Cancellation is asynchronous; confirm the turn boundary on the stream as `turn.cancelled` followed by `session.waiting`.

package/docs/connections/mcp.mdx

@@ -115,7 +115,7 @@ Use the shared `approval` option to gate every tool served by an MCP connection.
 
 ### Gate specific tools by name or input
 
-A remote MCP server usually mixes read tools with destructive or publishing ones, so a blanket `always()` would prompt on every harmless call. Pass a custom policy instead — the same [`Approval`](/docs/human-in-the-loop#approvals) shape authored tools use — to gate only the calls that matter. The policy receives `{ session, toolName, toolInput, approvedTools, callId, abortSignal }` and returns an approval status, synchronously or as a promise.
+A remote MCP server usually mixes read tools with destructive or publishing ones, so a blanket `always()` would prompt on every harmless call. Pass a custom policy instead — the same [`Approval`](/docs/human-in-the-loop#approvals) shape authored tools use — to gate only the calls that matter. The policy receives `{ session, toolName, toolInput, toolAnnotations, approvedTools, callId, abortSignal }` and returns an approval status, synchronously or as a promise.
 
 This connection always gates deletes, gates a publish only when the call actually schedules a post, and lets everything else through:
 
@@ -157,6 +157,27 @@ Two details are specific to connection tools:
 
 Return `"user-approval"` (or `true`) to pause for a person and `"not-applicable"` (or `false`) to run without a prompt; return `"approved"` or `"denied"` to decide automatically without involving anyone.
 
+### Gate by the server's tool annotations
+
+Many MCP servers declare [tool annotations](https://modelcontextprotocol.io/specification/2025-06-18/server/tools#tool) such as `readOnlyHint` and `destructiveHint` for each tool. eve passes what the server declared for the called tool as `toolAnnotations`, typed as `ConnectionToolAnnotations` from `eve/tools/approval`. It is `undefined` when the server declares none, so keep a fallback:
+
+```ts title="agent/connections/linear.ts"
+import { connect } from "@vercel/connect/eve";
+import { defineMcpClientConnection } from "eve/connections";
+
+export default defineMcpClientConnection({
+  url: "https://mcp.linear.app/mcp",
+  description: "Linear issues and projects.",
+  auth: connect("mcp.linear.app/linear"),
+  approval: ({ toolAnnotations }) => {
+    if (toolAnnotations?.readOnlyHint === true) return "not-applicable";
+    return "user-approval";
+  },
+});
+```
+
+Annotations are hints from the server, not guarantees. Trust them only as far as you trust the server that sent them.
+
 [Human-in-the-loop](/docs/human-in-the-loop#approvals) covers the full set of statuses, how `approvedTools` and `session.auth` factor in, and how a gated call pauses and resumes durably.
 
 ## Forward the caller to an eve agent

package/docs/connections/overview.mdx

@@ -254,12 +254,13 @@ App-scoped Connect auth is non-interactive. eve asks Vercel Connect for an app t
 
 ### Troubleshooting Vercel Connect auth
 
-| Symptom                                      | What it means                                                                                                                     | Fix                                                                                                                                                             |
-| -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `reason: "principal_required"`               | A user-scoped connection ran without an authenticated user on the active session.                                                 | Return `principalType: "user"` from the channel's route auth, or use `connect({ connector, principalType: "app" })` if the Connect credential should be shared. |
-| `authorization.required` appears but no UI   | eve parked the turn for OAuth, but the channel or frontend is not rendering the challenge.                                        | Render the challenge from the stream event and continue the same session after the callback.                                                                    |
-| OAuth works locally but fails after deploy   | The project may not be linked to the Connect client, or the deployed runtime may not have the expected Vercel OIDC/project scope. | Run Connect setup from the consuming project directory, link the project, deploy again, and verify the connector UID in `connect("...")`.                       |
-| A scheduled or internal run needs user OAuth | Schedules and runtime callers do not automatically carry an end-user principal.                                                   | Dispatch through a user-authenticated channel when work is user-owned, or use app-scoped auth for agent-owned background work.                                  |
+| Symptom                                           | What it means                                                                                                                     | Fix                                                                                                                                                             |
+| ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `reason: "principal_required"`                    | A user-scoped connection ran without an authenticated user on the active session.                                                 | Return `principalType: "user"` from the channel's route auth, or use `connect({ connector, principalType: "app" })` if the Connect credential should be shared. |
+| `authorization.required` appears but no UI        | eve parked the turn for OAuth, but the channel or frontend is not rendering the challenge.                                        | Render the challenge from the stream event and continue the same session after the callback.                                                                    |
+| OAuth works locally but fails after deploy        | The project may not be linked to the Connect client, or the deployed runtime may not have the expected Vercel OIDC/project scope. | Run Connect setup from the consuming project directory, link the project, deploy again, and verify the connector UID in `connect("...")`.                       |
+| A scheduled or internal run needs user OAuth      | Schedules and runtime callers do not automatically carry an end-user principal.                                                   | Dispatch through a user-authenticated channel when work is user-owned, or use app-scoped auth for agent-owned background work.                                  |
+| Sign-in ends on a Vercel login or protection page | The deployment is behind Deployment Protection, and sign-in callback URLs never carry the automation bypass secret.               | Have the user sign in to Vercel with access to the project, or add a Deployment Protection Exception for the domain.                                            |
 
 ## Self-hosted interactive OAuth
 
@@ -316,6 +317,8 @@ export default defineMcpClientConnection({
 
 Drop `resume` when the provider keeps flow state server-side, so nothing has to cross the step boundary.
 
+The callback URL never carries `VERCEL_AUTOMATION_BYPASS_SECRET`, because the user's browser and the provider both see it. On a deployment behind [Deployment Protection](https://vercel.com/docs/deployment-protection), the person signing in must pass protection on their own, for example through Vercel Authentication or a [Deployment Protection Exception](https://vercel.com/docs/deployment-protection/methods-to-bypass-deployment-protection/deployment-protection-exceptions).
+
 `displayName` is presentation-only. The connection's resolved name still keys
 the callback URL, while eve scopes token caching and authorization completion
 to the opaque resolved instance identity. You can also set `displayName` on the

package/docs/evals/assertions.mdx

@@ -3,7 +3,7 @@ title: "Assertions"
 description: "Scoped methods, value assertions, the matcher mini-language, and gate vs soft severity."
 ---
 
-Assertions are how an eval grades what its `test(t)` function produced. Each one records a result and returns a chainable handle. The runner reads every recorded result to compute the verdict, so a single run reports every failing assertion rather than dying on the first. There are two deterministic surfaces: scoped methods and `t.check` for grading a specific value. For model-graded assertions, see [Judge](./judge).
+Assertions are how an eval grades what its `test(t)` function produced. Each one records a result and returns a chainable handle. The runner reads every recorded result to compute the verdict, so a single run reports every failing assertion rather than dying on the first. There are three deterministic surfaces: scoped methods, `t.check` for grading a specific value, and `t.score` for recording a measurement you computed yourself. For model-graded assertions, see [Judge](./judge).
 
 ## Scoped assertions
 
@@ -83,6 +83,53 @@ For example, a failed labeled equality check prints:
 
 Pick the cheapest builder that captures what "correct" means. When exact match is too strict but a judge model is overkill, `similarity` is the middle ground. For nuanced grading, reach for the [judge](./judge).
 
+## Scores with `t.score`
+
+`t.score(evaluation)` records a score from 0 to 1. The evaluation is the number or `{ score, message?, metadata? }`, or a promise of either. Chain `.label(key)` to name it; reporters and artifacts expose the label as `key`. Without a label the score reports as `score`, and several unlabeled scores share that name.
+
+```ts
+const reply = turn.message ?? "";
+t.score({
+  score: Math.max(0, 1 - reply.length / 400),
+  metadata: { length: reply.length },
+}).label("reply-brevity");
+t.score(gradeFaithfulness(reply, reference)).label("faithfulness"); // async
+```
+
+On its own a score has no verdict and does not affect the eval's outcome. Chain a rule when it should:
+
+```ts
+t.score(gradeFaithfulness(reply, reference)).label("faithfulness").gate(0.9); // fails below 0.9
+t.score(brevity).label("reply-brevity").atLeast(0.5); // marks the eval `scored`, fatal under --strict
+```
+
+The score is reported as measured. A `0.82` gated at `0.9` is reported as `score: 0.82`, `threshold: 0.9`, `passed: false`. An evaluator that throws or returns a score outside 0 to 1 records an errored outcome with the error message and no score, and fails the eval.
+
+Every [reporter](./reporters#custom-reporters) receives the entries in `onEvalComplete` and can read them by `key`:
+
+```ts
+onEvalComplete(result) {
+  for (const { key, score, threshold, passed } of result.assertions) {
+    if (key === undefined) continue;
+    store.write({ evalId: result.id, key, score, threshold, passed });
+  }
+}
+```
+
+The same entries land in the [run artifacts](./running#artifacts) under `.eve/evals/`, in `summary.json` and one line per eval in `results.jsonl`:
+
+```json
+{
+  "name": "score [reply-brevity]",
+  "key": "reply-brevity",
+  "score": 0.84,
+  "severity": "soft",
+  "errored": false
+}
+```
+
+`threshold` and `passed` are present only when a rule was chained.
+
 ## The matcher mini-language
 
 `t.calledTool` and `t.calledSubagent` take matcher objects. Tools accept `{ input, output, status, count }`; subagents accept `{ callId, childSessionId, remoteUrl, output, status, count }`. Calls match `status: "completed"` by default. Tool lifecycle checks also accept `"pending"`, `"failed"`, and `"rejected"`. Subagent checks accept `"working"`, `"completed"`, `"failed"`, and `"cancelled"`. A numeric `count` requires an exact number of calls matching every supplied constraint. Use a predicate for ranges or other custom count requirements; it receives the observed number of matching calls.
@@ -164,9 +211,9 @@ const request = session.requireInputRequest({ toolName: "guarded" });
 Every assertion returns a chainable handle. Severity rides on the assertion, so there is no separate thresholds map to keep in sync.
 
 - `.gate(threshold?)` is hard. A miss marks the eval `failed` and `eve eval` exits non-zero.
-- `.soft(threshold?)` is tracked data. A below-threshold miss marks the eval `scored`, fatal only under `--strict`. With no threshold, it is tracked-only and never fails.
+- `.soft(threshold?)` is tracked data. A below-threshold miss marks the eval `scored`, fatal only under `--strict`. With no threshold it records no verdict and never fails.
 - `.atLeast(threshold)` is soft with a bar (equivalent to `.soft(threshold)`).
-- `.label(name)` adds a stable name when an eval records several assertions from the same family.
+- `.label(key)` adds a stable name when an eval records several assertions from the same family. Reporters and artifacts expose it as `key`. Braintrust and Datadog keep one score per name, so `eve eval` warns when soft assertions in one eval share a name with different scores.
 
 The defaults are chosen so you rarely set severity. Run-level methods and `includes`/`equals`/`matches` are gates; `similarity` and every `t.judge(...)` assertion are soft. Annotate only when you deviate:
 

package/docs/evals/overview.mdx

@@ -154,6 +154,7 @@ Each surface matches a genuinely different kind of judgment:
 
 - **Scoped methods** read the final whole run on `t`, snapshot one independent session when invoked there, or inspect one immutable `EveEvalTurn`. See [Assertions](./assertions).
 - **`t.check(value, assertion)`** grades an explicit value with a deterministic builder from `eve/evals/expect`, such as `t.check(turn.message, includes("sunny"))`. Grade `turn.message`, an intermediate draft, parsed JSON, or anything else. See [Assertions](./assertions).
+- **`t.score(evaluation)`** records a score, such as a length ratio or an evaluator's result. Chain `.label(key)` to name it, and `.gate(threshold)` or `.atLeast(threshold)` to let it decide the eval. See [Assertions](./assertions#scores-with-tscore).
 - **`t.judge(...)`** is the LLM-as-judge surface, like `t.judge("cites a source")`. It grades the most recently settled turn’s assistant message by default; pass `{ on: turn.session.transcript }` to grade a multi-turn conversation. The judge uses the configured judge model, never the agent under test. See [Judge](./judge).
 
 ## Gate vs soft
@@ -161,7 +162,7 @@ Each surface matches a genuinely different kind of judgment:
 Every assertion returns a chainable handle, so severity rides on the assertion itself. There is no separate thresholds map.
 
 - **Gates** are hard. A failed gate marks the eval `failed` and `eve eval` exits non-zero. Run-level methods, `includes`, `equals`, and `matches` are gates by default.
-- **Soft** assertions are tracked data. They land in reports and artifacts, and a below-threshold soft assertion marks the eval `scored` (visible but not fatal, unless you pass `--strict`). `similarity` and every `t.judge(...)` assertion are soft by default. A soft assertion with no threshold is tracked-only and never fails.
+- **Soft** assertions are tracked data. They land in reports and artifacts, and a below-threshold soft assertion marks the eval `scored` (visible but not fatal, unless you pass `--strict`). `similarity`, every `t.judge(...)` assertion, and every `t.score(...)` are soft by default. A soft assertion with no threshold records no verdict and never fails.
 
 Override per assertion: `.gate(threshold?)` promotes to a hard gate, `.soft(threshold?)` demotes to tracked, and `.atLeast(threshold)` is a soft assertion with a bar.
 

package/docs/evals/reporters.mdx

@@ -38,7 +38,7 @@ export default defineEval({
 });
 ```
 
-The reporter config takes an optional `projectName` and `experimentName`, plus a base experiment (by name or id) to diff against. Gate assertions log as binary scores under a `gate:` prefix so experiments diff gate regressions the same way they diff soft-score regressions. Assertions that share a name, such as several unlabeled judges, log one score: the lowest. Use `.label(name)` to group or separate them. Each assertion's score is stored in the Braintrust metadata under `eveAssertionScores` and failed assertion details under `eveFailedAssertions`; observed traces are stored under `eveTraceIds` and `eveTraceContexts`.
+The reporter config takes an optional `projectName` and `experimentName`, plus a base experiment (by name or id) to diff against. Gate assertions log as binary scores under a `gate:` prefix so experiments diff gate regressions the same way they diff soft-score regressions. Assertions that share a name, such as several unlabeled judges, log one score: the lowest. The console warns under the eval when merged soft scores differ; use `.label(name)` to group or separate them. Errored assertions log no score. Each assertion's score is stored in the Braintrust metadata under `eveAssertionScores` and failed assertion details under `eveFailedAssertions`; observed traces are stored under `eveTraceIds` and `eveTraceContexts`.
 
 A reporter instance observes the evals that reference it. Share one instance across several evals (the config, a `shared.ts` export, or every entry of a dataset array) and their results land in a single experiment. Listing the same config reporter on an eval too does not double-report it.
 
@@ -97,6 +97,8 @@ interface EvalReporter {
 - `onSessionStart` fires once for each session after eve receives its first trace context. It includes `sessionId`, `primary`, and `traceContext` with `traceId`, `spanId`, and `traceFlags`.
 - `onEvalComplete` fires with the checks, scores, and verdict. The runner also supplies `context`, including every distinct trace context collected across the eval's sessions. The same list is available as `result.result.traceContexts`.
 
+Each entry in `result.assertions` is an `AssertionResult`. `name` is the display label, `key` the identifier set by `.label(key)`, and `score` the measurement. `threshold` and `passed` describe the rule and are absent when no rule applies. When a scorer threw, `errored` is `true`, `message` carries the error, and `score` is absent. The `.eve/evals/` artifacts write the same fields.
+
 An eval can create several sessions, and a long session can produce several traces, so completion exposes a list instead of a single trace id. `onEvalStart` does not include a trace because the agent session has not started yet. If the target has no tracing configured, `onSessionStart` does not fire and the completed trace list is empty.
 
 `result.result.derived` holds the facts the runner derived from the eval's sessions, such as tool calls and `models`: the distinct ids of the models the steps started with, in session order. Each entry in `result.result.sessions` holds the same facts for one session, in first-use order, so a reporter can tell the primary session's models from those of the other sessions the eval created or attached. A delegated subagent runs in its own session, so its models appear only when the eval attaches that session with `t.target.attachSession`. Compaction and `auto` routing calls are not included.

package/docs/guides/frontend/overview.mdx

@@ -165,6 +165,15 @@ its cursor after a disconnect or the
 server's renewable 60-second lease; lease renewal does not start a turn or clear UI state.
 Unmounting or resetting closes the local stream without cancelling the old durable session.
 
+An open stream reconnects for as long as the chat stays mounted, even when nothing happens. If
+your UI only shows replies to its own messages, such as a help sidebar that stays mounted across
+pages, pass `followIdle: false`. The binding then closes the stream once the session is idle: no
+turn is running or parked, no task is working, and no sign-in is pending. A prewarmed session
+opens no stream until its first message. The next `send()`, `respond()`, or `resume()` reopens
+the stream from the session cursor, so events that arrived in between are applied then. Leave
+`followIdle` on when other sources, such as schedules, channels, or another tab, can start turns
+in the session while your UI is idle.
+
 `reset()` reuses the hook instance and clears the conversation. When `prewarm` is true after
 the reset, it prepares the next owned session; otherwise, the next send creates it. An explicitly
 supplied `session` remains externally owned and is never replaced by prewarming or reset. Use
@@ -399,7 +408,7 @@ then save a final snapshot in `onFinish`.
 
 `initialEvents` must be an ordered prefix of the same session's stream, but its endpoint does not have to line up exactly with where the stream resumes. When the event count matches `initialSession.streamIndex`, catch-up continues from that cursor. A partial or overlapping saved log falls back to index `0`. Every event carries a stable [`meta.id`](/docs/concepts/sessions-runs-and-streaming#the-event-envelope), and the store drops any event whose id it has already applied, so an overlapping replay renders once and `onEvent` only fires for events your UI has not seen.
 
-For multiple chat threads, keep one saved event log and session cursor per thread. `agent`, `host`, `reducer`, `session`, `initialEvents`, `initialSession`, `auth`, `headers`, `optimistic`, and `resume` are read when the hook creates its store, so remount the chat component when switching threads, for example with `key={chat.id}`. React reads `prewarm` on every render.
+For multiple chat threads, keep one saved event log and session cursor per thread. `agent`, `host`, `reducer`, `session`, `initialEvents`, `initialSession`, `auth`, `headers`, `optimistic`, `followIdle`, and `resume` are read when the hook creates its store, so remount the chat component when switching threads, for example with `key={chat.id}`. React reads `prewarm` on every render.
 
 Pass `resume: true` with `initialSession` to rebuild the projection from the durable stream after mount. While `status` is `"resuming"`, render hydrated `data` but disable message and HITL submission; do not present cancellation or active-turn progress controls. If catch-up finds an in-flight turn, `status` changes to `"streaming"` before the binding follows it to a boundary. The stream reports its initial durable tail so catch-up can finish without closing the connection or waiting for an idle timeout. A settled tail changes directly to `"ready"`; a newer turn or pending authorization remains `"streaming"`. The connection stays open to receive later events. A terminal session failure changes to `"error"`.
 

package/docs/guides/hooks.md

@@ -97,7 +97,7 @@ when the parent's current model step ends if one is running.
 
 ### Narrowing tool results
 
-`toolResultFrom` narrows an `action.result` event to a specific authored tool or MCP connection and returns typed output. Import it from `eve/tools`:
+`toolResultFrom` narrows an `action.result` event to a specific authored tool or connection (MCP or OpenAPI) and returns typed output. Import it from `eve/tools`:
 
 ```ts
 import { defineHook } from "eve/hooks";
@@ -114,7 +114,7 @@ export default defineHook({
         console.log(weather.output.temperature);
       }
 
-      // MCP connection: output is unknown, toolName is qualified
+      // Connection: output is unknown, toolName is qualified
       const linearResult = toolResultFrom(event.data.result, linear);
       if (linearResult) {
         console.log(linearResult.connectionToolName, linearResult.output);

package/docs/guides/instrumentation/otel.mdx

@@ -174,6 +174,9 @@ each turn. Remote requests carry the conversation ID in W3C Baggage.
 `trustedForwarders` controls whether the receiver accepts parent session data
 and the trace-content policy. See
 [Remote agents](../guides/remote-agents#preserving-trace-content).
+Gateway-routed model calls propagate the configured OpenTelemetry context at
+each provider request. Eve-owned baggage is removed before forwarding. Gateway
+controls whether its spans are sampled and which destinations receive them.
 
 ## Local traces
 

package/docs/reference/cli.md

@@ -403,7 +403,7 @@ Each root agent turn starts a new trace. With local caller trace context, that t
 
 Every span carries a real duration. A turn's root `invoke_agent` span is written when the turn settles, so a running turn shows only its steps.
 
-Model, `execute_tool`, and memory spans retain their content by default. Set `EVE_TRACES_CONTENT=off` to omit system prompts, prompt messages, and response text for models; call arguments and results for tools; and recalled memory records. Each captured value is capped at 32 KB.
+Model, `execute_tool`, and memory spans retain their content by default. Set `EVE_TRACES_CONTENT=off` to omit system prompts, prompt messages, and response text for models; call arguments and results for tools; and recalled memory records. Each captured value is capped at 32 KB. When a model call's prompt messages exceed the cap, the oldest are dropped first and `agent.input.messages.omitted` records how many.
 
 Step spans carry token counts under `agent.usage.*`, and cost when Vercel AI Gateway served the call. Model spans also expose `gen_ai.usage.*` token counters. The CLI sums step-level counters only, so model and delegated-call totals are not counted twice.
 

package/docs/reference/typescript-api.md

@@ -103,12 +103,13 @@ import template from "../../prompts/template.txt?raw";
 
 `ctx` is passed to your tool `execute`, hook handlers, channel event handlers, and connection auth/header resolvers. It is live only while authored code is running, so reaching for it at module top level throws. See [Session context](../guides/session-context) for the full model.
 
-| Member                      | Use                                                                          |
-| --------------------------- | ---------------------------------------------------------------------------- |
-| `ctx.session`               | Current session, turn, auth, and optional parent lineage (read-only)         |
-| `ctx.getSandbox()`          | Live sandbox handle; `stop()` releases compute but preserves durable state   |
-| `ctx.getToken(provider)`    | Resolve a bearer token for an inline auth provider such as `connect("...")`  |
-| `ctx.requireAuth(provider)` | Evict and re-authorize an inline provider, commonly after a downstream `401` |
+| Member                      | Use                                                                                                                                                                                                                                                    |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `ctx.session`               | Current session, turn, auth, and optional parent lineage (read-only)                                                                                                                                                                                   |
+| `ctx.getSandbox()`          | Live sandbox handle; `stop()` releases compute but preserves durable state                                                                                                                                                                             |
+| `ctx.getToken(provider)`    | Resolve a bearer token for an inline auth provider such as `connect("...")`                                                                                                                                                                            |
+| `ctx.requireAuth(provider)` | Evict and re-authorize an inline provider, commonly after a downstream `401`                                                                                                                                                                           |
+| `ctx.approval`              | Present only while a call runs after a person approved it: `responder` is who approved it and `responder.getToken(provider)` resolves their token. The call still runs as `ctx.session.auth.current`; see [Human-in-the-loop](/docs/human-in-the-loop) |
 
 Tool definitions accept `availableInSubagents: false` to restrict the tool to top-level root sessions, and `deferred: true` to keep the tool out of the model's tool list so the model finds it with `eve__search` and calls it with `eve__tool`; see [Tools](../tools#keep-a-tool-out-of-the-tool-list). `defineTool` definitions accept `endsTurn: true`, or a function that receives the `execute` output, to end the turn without a reply after a successful call; see [Tools](../tools#end-the-turn-after-a-tool-call). Authored workflow bodies also receive `ctx.agents`, a replay-stable map of callable-agent metadata, and `ctx.agent(name)`, which returns an `AgentSession` whose `send(message, options?)` resolves to a response with `result()`. A `"use step"` helper that receives the context directly should type it as `WorkflowStepToolContext`, which excludes `agents`, `agent`, and `ask`. The root-copy `agent` entry has an empty description when the root omits `description`. See [Workflows as tools](../tools/workflows#delegate-work-ctxagent) for the workflow-only context.
 

package/docs/sandbox/vercel.mdx

@@ -95,6 +95,15 @@ await sandbox.setNetworkPolicy("deny-all");
 return sandbox;
 ```
 
+## Live sandbox name
+
+Sessions returned by `environment.open()` and `ctx.getSandbox(environment)` expose a read-only `name` property. The name identifies the live Vercel Sandbox and stays stable across stop/resume for the session. Use it as `sandboxName` when creating Vercel git-credential-broker grants scoped to that sandbox:
+
+```ts
+const sandbox = await ctx.getSandbox(environment);
+const sandboxName = sandbox.name;
+```
+
 ## Live sandbox options
 
 `open()` also accepts Vercel compute resources, timeout, and Drive mounts. Configure project credentials and custom fetch behavior on the environment, not in `open()`, because resume does not reconstruct start-only options.

package/docs/skills.mdx

@@ -44,7 +44,7 @@ A skill's name comes from its path and must use only ASCII letters, digits, unde
 
 A flat markdown skill can skip the `description` frontmatter. When it does, eve advertises the first non-empty, non-code-fence line of the body with any leading `#`, `>`, `*`, or `-` marker stripped. If the body has no such line, eve falls back to the literal `Instructions for the <name> skill.`, which is a weak routing hint, so add a `description` when you want the model to route on intent.
 
-A packaged skill is a directory with a `SKILL.md` plus sibling files like `references/`, `assets/`, and `scripts/`. The packaged `SKILL.md` must carry `description` frontmatter; it has no filename slug to fall back on.
+A packaged skill is a directory with a `SKILL.md` plus sibling files like `references/`, `assets/`, and `scripts/`. The packaged `SKILL.md` must carry `description` frontmatter; it has no filename slug to fall back on. eve ignores frontmatter it does not use so skills authored for other Agent Skills clients remain importable.
 
 ```md title="agent/skills/research/SKILL.md"
 ---

package/docs/tools/human-in-the-loop.md

@@ -64,7 +64,29 @@ approval: auto({
 
 A reusable approval grant applies only after every matching request that is already pending has been resolved. If several calls to a `once()`-gated tool have each produced an approval prompt, approving one does not authorize the others; each visible prompt remains an independent decision. After those pending requests are resolved, later calls in the session are allowed automatically.
 
-When the decision depends on the input, pass your own policy instead of a helper. It receives the same session context as tool execution, plus `{ toolName, toolInput, approvedTools, callId, abortSignal }`, and returns an AI SDK 7 approval status synchronously or as a promise. Use `abortSignal` for asynchronous policy work so cancellation stops it with the turn. Use `ctx.session.auth.current` to guard by the caller of the current turn and `ctx.session.auth.initiator` to guard by the caller that created the session. Return `"user-approval"` to pause for a person or `"not-applicable"` to continue without a prompt. `toolInput` can be undefined, so guard the access. This policy denies cross-tenant calls, then requires approval only when an amount crosses a threshold:
+Use the object form of `approval` to replace the default `Approve <tool label>?` text with a tool-specific summary. The `prompt` callback receives the validated `input`, final `toolName`, and `callId`:
+
+```ts title="agent/tools/refund_charge.ts"
+import { defineTool } from "eve/tools";
+import { always } from "eve/tools/approval";
+import { z } from "zod";
+
+export default defineTool({
+  description: "Refund a charge.",
+  inputSchema: z.object({ chargeId: z.string(), amount: z.number() }),
+  approval: {
+    request: always(),
+    prompt: ({ input }) => `Refund $${input.amount.toFixed(2)} for charge ${input.chargeId}?`,
+  },
+  async execute(input) {
+    return refund(input);
+  },
+});
+```
+
+Channels render this prompt in their approval UI. Slack also includes the complete tool input in a collapsed **Tool input** block so an approver can inspect the original structured value.
+
+When the decision depends on the input, pass your own policy instead of a helper. It receives the same session context as tool execution, plus `{ toolName, toolInput, approvedTools, callId, abortSignal }` (connection tools also get `toolAnnotations`), and returns an AI SDK 7 approval status synchronously or as a promise. Use `abortSignal` for asynchronous policy work so cancellation stops it with the turn. Use `ctx.session.auth.current` to guard by the caller of the current turn and `ctx.session.auth.initiator` to guard by the caller that created the session. Return `"user-approval"` to pause for a person or `"not-applicable"` to continue without a prompt. `toolInput` can be undefined, so guard the access. This policy denies cross-tenant calls, then requires approval only when an amount crosses a threshold:
 
 ```ts
 approval: ({ session, toolInput }) => {
@@ -234,6 +256,27 @@ When a subagent requests input, eve emits the same `input.requested` event on it
 
 Approval is consent only. An approved tool call runs with the requesting user's identity, connections, and credentials, including its policy recheck. The approver's access is never lent to the call. Subsequent tool calls in the turn also stay with the original owner.
 
+A `defineTool` tool can still act on the approver's behalf when it chooses to. While an approved `defineTool` call runs, `ctx.approval.responder` is the principal who approved it, and `ctx.approval.responder.getToken(provider)` resolves that person's token for an inline provider, as `ctx.getToken(provider)` does for the requester. `ctx.session.auth.current` stays the requester. `ctx.approval` is absent for calls that needed no approval, and workflow tools don't receive it. `ctx.approval.responder.getToken(provider)` never starts a sign-in: when the approver has no token, it throws a `ConnectionAuthorizationFailedError` with `reason: "approver_authorization_required"`.
+
+```ts
+export default defineTool({
+  description: "Grant the requester access to a repository.",
+  inputSchema: z.object({ repo: z.string() }),
+  approval: {
+    request: always(),
+    response: ({ response }) =>
+      itAdmins.includes(response.principal.principalId)
+        ? { status: "allowed" }
+        : { status: "rejected" },
+  },
+  async execute({ repo }, ctx) {
+    const admin = await ctx.approval?.responder.getToken(github);
+    if (admin === undefined) throw new Error("An IT admin must approve this grant.");
+    return await grantAccess(repo, ctx.session.auth.current, admin.token);
+  },
+});
+```
+
 For approval requests, a follow-up message that doesn't match an option steers the turn instead of answering it. eve cancels the turn's pending approval, so the call doesn't run and `input.resolved` reports `outcome: "ignored"`, and the model reads the message next. This happens even when the message is sent with `turnPolicy: "queue"`, because a turn held on a person can't end until they act. Calls the person already approved in the same batch still run. A message from someone other than the person the turn serves waits until the turn ends. Cancelling the turn withdraws its approval: the call doesn't run, `input.resolved` reports `outcome: "cancelled"`, and a later answer to it approves nothing.
 
 ### Several requests at once

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eve",
-  "version": "0.78.0",
+  "version": "0.79.1",
   "private": false,
   "description": "Filesystem-first framework for durable backend AI agents that run anywhere.",
   "keywords": [
@@ -574,6 +574,7 @@
     "@chat-adapter/twilio": "4.41.0",
     "@clack/core": "1.3.1",
     "@eve/catalog": "0.0.1",
+    "@eve/tracing": "0.0.0",
     "@linqapp/chat-sdk-adapter": "^0.5.1",
     "@modelcontextprotocol/server": "2.0.0",
     "@nuxt/kit": "^4.0.0",

package/dist/src/harness/proxy-input-requests.js

@@ -1 +0,0 @@
-import{isSessionInboxAddress}from"#execution/session-inbox/address.js";import{inputOptionSchema}from"#shared/input.js";const PROXY_INPUT_REQUESTS_KEY=`eve.runtime.proxyInputRequests`,PROXY_INPUT_REQUEST_KINDS={question:!0,"session-limit":!0,"tool-approval":!0};function resolvedByChild(e){return e===`tool-approval`}function resolvedForParent(e){let t=e.resolutions.filter(({kind:e})=>resolvedByChild(e));return t.length===0?void 0:{...e,resolutions:t}}function getProxyInputRequests(e){return new Map(Object.entries(readMap(e)))}function hasProxyInputRequests(e){for(let t of Object.keys(readMap(e)))return!0;return!1}function upsertProxyInputRequests(e){return{...e.session,state:upsertProxyInputRequestState({entries:e.entries,forChildContinuationToken:e.forChildContinuationToken,inputSource:e.inputSource,state:e.session.state})}}function upsertProxyInputRequestState(e){let t={};for(let[n,r]of Object.entries(readMap(e.state)))(r.childContinuationToken!==e.forChildContinuationToken||r.inputSource!==e.inputSource)&&(t[n]=r);for(let[n,r]of e.entries)t[n]=r;let n={...e.state};return Object.keys(t).length===0?delete n[PROXY_INPUT_REQUESTS_KEY]:n[PROXY_INPUT_REQUESTS_KEY]=t,Object.keys(n).length>0?n:void 0}function clearProxyInputRequestsWhere(e,t){return retireProxyInputRequests(e,Object.entries(readMap(e.state)).filter(([e,n])=>t(n,e)).map(([e])=>e))}function retireProxyInputRequests(e,t){let n={...readMap(e.state)},r=!1;for(let e of t)Object.hasOwn(n,e)&&(delete n[e],r=!0);return r?writeMap(e,n):e}function toProxyInputRequestEntries(e){let t={approvalRequestIds:e.event.requests.flatMap(e=>e.kind===`tool-approval`?[e.requestId]:[]),requestIds:e.event.requests.map(e=>e.requestId)},n={sequence:e.event.sequence,stepIndex:e.event.stepIndex,turnId:e.event.turnId};return e.event.requests.map(r=>{let i={batch:t,childContinuationToken:e.childContinuationToken,...e.inputSource!==void 0&&{inputSource:e.inputSource},...e.remote!==void 0&&{remote:e.remote},event:n,kind:r.kind,reply:{...r.allowFreeform!==void 0&&{allowFreeform:r.allowFreeform},...r.options!==void 0&&{options:[...r.options]}}};return e.childSessionInbox?.sessionId===e.childSessionId&&(i.childSessionInbox=e.childSessionInbox),[r.requestId,i]})}function readMap(e){let t=e?.[PROXY_INPUT_REQUESTS_KEY];if(typeof t!=`object`||!t||Array.isArray(t))return{};let n={};for(let[e,r]of Object.entries(t)){let t=parseProxyInputRequest(r,e);t!==void 0&&(n[e]=t)}return n}function writeMap(e,t){let n={...e.state};return Object.keys(t).length===0?(delete n[PROXY_INPUT_REQUESTS_KEY],{...e,state:Object.keys(n).length>0?n:void 0}):(n[PROXY_INPUT_REQUESTS_KEY]=t,{...e,state:n})}function parseProxyInputRequest(e,t){if(typeof e!=`object`||!e||Array.isArray(e)||!(`childContinuationToken`in e)||!(`kind`in e)||typeof e.childContinuationToken!=`string`||!isInputRequestKind(e.kind))return;let n=`remote`in e?parseRemoteAgentBinding(e.remote):void 0;if(`remote`in e&&n===void 0)return;let r=`inputSource`in e?e.inputSource:void 0;if(r!==void 0&&(typeof r!=`string`||r.length===0))return;let i=`event`in e?parseInputRequestEvent(e.event):void 0;if(i===void 0)return;let a=`batch`in e?parseProxyInputRequestBatch(e.batch):void 0,o=`workflowAsk`in e?parseWorkflowAskRoute(e.workflowAsk):void 0;if(`workflowAsk`in e&&o===void 0)return;let s=`runId`in e?e.runId:void 0;if(s!==void 0&&(typeof s!=`string`||s.length===0))return;let c=`reply`in e?parseProxyInputReply(e.reply):void 0;if(`reply`in e&&c===void 0)return;let l=`childSessionInbox`in e?e.childSessionInbox:void 0;if(l!==void 0&&!isSessionInboxAddress(l))return;let u={childContinuationToken:e.childContinuationToken,event:i,kind:e.kind};return typeof r==`string`&&(u.inputSource=r),n!==void 0&&(u.remote=n),o!==void 0&&(u.workflowAsk=o),typeof s==`string`&&(u.runId=s),l!==void 0&&(u.childSessionInbox=l),a!==void 0&&a.requestIds.includes(t)&&(u.batch=a),c!==void 0&&(u.reply=c),u}function parseInputRequestEvent(e){if(typeof e!=`object`||!e||Array.isArray(e))return;let t=Reflect.get(e,`sequence`),n=Reflect.get(e,`stepIndex`),r=Reflect.get(e,`turnId`);if(typeof t==`number`&&typeof n==`number`&&typeof r==`string`)return{sequence:t,stepIndex:n,turnId:r}}function parseWorkflowAskRoute(e){if(typeof e!=`object`||!e)return;let t=Reflect.get(e,`control`);if(typeof t==`string`&&t.length!==0)return{control:t}}function parseRemoteAgentBinding(e){if(typeof e!=`object`||!e||Array.isArray(e))return;let t=Reflect.get(e,`name`),n=Reflect.get(e,`url`),r=Reflect.get(e,`resolverId`),i=Reflect.get(e,`forwardPrincipal`),a=Reflect.get(e,`sessionId`);if(typeof t==`string`&&t&&typeof n==`string`&&n&&typeof a==`string`&&a&&(r===void 0||typeof r==`string`&&r)&&(i===void 0||typeof i==`boolean`))return{name:t,url:n,sessionId:a,...r!==void 0&&{resolverId:r},...i!==void 0&&{forwardPrincipal:i}}}function parseProxyInputReply(e){if(typeof e!=`object`||!e||Array.isArray(e))return;let t={},n=Reflect.get(e,`allowFreeform`);if(n!==void 0){if(typeof n!=`boolean`)return;t.allowFreeform=n}let r=Reflect.get(e,`options`);if(r!==void 0){let e=inputOptionSchema.array().safeParse(r);if(!e.success)return;t.options=e.data}return t}function parseProxyInputRequestBatch(e){if(typeof e!=`object`||!e||Array.isArray(e)||!(`approvalRequestIds`in e)||!(`requestIds`in e)||!isStringArray(e.approvalRequestIds)||!isStringArray(e.requestIds))return;let t=new Set(e.requestIds);if(!(t.size!==e.requestIds.length||e.approvalRequestIds.some(e=>!t.has(e))))return{approvalRequestIds:e.approvalRequestIds,requestIds:e.requestIds}}function isStringArray(e){return Array.isArray(e)&&e.every(e=>typeof e==`string`)}function isInputRequestKind(e){return typeof e==`string`&&Object.hasOwn(PROXY_INPUT_REQUEST_KINDS,e)}export{clearProxyInputRequestsWhere,getProxyInputRequests,hasProxyInputRequests,resolvedByChild,resolvedForParent,retireProxyInputRequests,toProxyInputRequestEntries,upsertProxyInputRequestState,upsertProxyInputRequests};

package/dist/src/tracing/agent-approval-instrumentation.d.ts

@@ -1,11 +0,0 @@
-import { type Tracer } from "#compiled/@opentelemetry/api/index.js";
-import type { InstrumentationProviderDefinition } from "#instrumentation/lifecycle.js";
-import type { AgentToolContext } from "#tracing/agent-tool-instrumentation.js";
-import type { AgentSpanIdGenerator } from "#tracing/agent-span-id-generator.js";
-/** Builds durable approval wait spans under their originating runtime action. */
-export declare function createAgentApprovalInstrumentation(input: {
-    readonly actionContextFor: (sessionId: string, turnId: string, callId: string) => Promise<AgentToolContext | undefined>;
-    readonly frameworkVersion: string;
-    readonly idGenerator: AgentSpanIdGenerator;
-    readonly tracer: Tracer;
-}): Pick<NonNullable<InstrumentationProviderDefinition["events"]>, "input.requested" | "input.resolved">;

package/dist/src/tracing/agent-approval-instrumentation.js

@@ -1 +0,0 @@
-import{normalizeChannelAudience}from"#shared/channel-audience.js";import{AGENT_SPAN_NAMES}from"#tracing/agent-span-contract.js";import{ROOT_CONTEXT,trace}from"#compiled/@opentelemetry/api/index.js";import{agentSpanNamingAttributes}from"#tracing/agent-span-naming.js";import{contentAttribute}from"#tracing/agent-otel-content.js";import{recordAgentSpanError}from"#tracing/agent-span-error.js";import{agentTraceIdentityAttributes,traceSessionIdOf}from"#tracing/agent-otel-attributes.js";import{decodeTraceSessionId}from"#tracing/agent-trace-context-codec.js";import{withChannelAudience}from"#tracing/channel-audience-context.js";function createAgentApprovalInstrumentation(e){return{"input.requested":async(t,n)=>{if(t.kind!==`tool-approval`||readState(n.state.get())!==void 0)return;let r=await e.actionContextFor(t.scope.sessionId,t.scope.turnId,t.action.callId);if(r===void 0)return;let i={actionCallId:t.action.callId,actionName:t.action.name,attemptIndex:t.scope.attemptIndex,channelAudience:normalizeChannelAudience(t.scope.channelAudience),parent:{spanId:r.spanContext.spanId,traceFlags:r.spanContext.traceFlags,traceId:r.spanContext.traceId},requestId:t.requestId,rootSessionId:t.scope.rootSessionId??t.scope.sessionId,traceSessionId:traceSessionIdOf(t.scope),sessionId:t.scope.sessionId,startTimeMs:Date.now(),stepIndex:t.scope.stepIndex,turnId:t.scope.turnId},a=contentAttribute(t.request);a!==void 0&&(i.requestAttribute=a),n.state.set(i)},"input.resolved":(t,n)=>{let r=readState(n.state.get());if(r===void 0)return;let i=e.idGenerator.withSpanId(e.idGenerator.deriveSpanId(`approval:${t.idempotencyKey}`),()=>e.tracer.startSpan(AGENT_SPAN_NAMES.approval,{attributes:{"gen_ai.tool.call.id":r.actionCallId,"agent.action.name":r.actionName,"agent.approval.kind":`tool-approval`,"agent.approval.outcome":t.outcome,"agent.approval.request_id":r.requestId,"agent.framework.name":`eve`,"agent.framework.version":e.frameworkVersion,"agent.step.attempt":r.attemptIndex,"agent.step.index":r.stepIndex,"agent.turn.id":r.turnId,"gen_ai.operation.name":`workflow`,...agentSpanNamingAttributes(`agent.approval`,`workflow`),...agentTraceIdentityAttributes({rootSessionId:r.rootSessionId,traceSessionId:r.traceSessionId,sessionId:r.sessionId})},startTime:r.startTimeMs},withChannelAudience(trace.setSpan(ROOT_CONTEXT,trace.wrapSpanContext({...r.parent,isRemote:!1})),r.channelAudience)));if(r.requestAttribute!==void 0&&i.setAttribute(`agent.approval.request`,r.requestAttribute),t.response!==void 0){let e=contentAttribute(t.response);e!==void 0&&i.setAttribute(`agent.approval.response`,e)}t.outcome===`failed`&&recordAgentSpanError(i,t.error),i.end()}}}function readState(e){if(typeof e!=`object`||!e||Array.isArray(e))return;let t=e,n=t.parent;if(typeof n!=`object`||!n||Array.isArray(n))return;let r=n;if(typeof t.actionCallId!=`string`||typeof t.actionName!=`string`||typeof t.attemptIndex!=`number`||typeof r.spanId!=`string`||typeof r.traceFlags!=`number`||typeof r.traceId!=`string`||typeof t.requestId!=`string`||typeof t.rootSessionId!=`string`||typeof t.sessionId!=`string`||typeof t.startTimeMs!=`number`||typeof t.stepIndex!=`number`||typeof t.turnId!=`string`)return;let i=t.requestAttribute;if(i===void 0||typeof i==`string`)return{actionCallId:t.actionCallId,actionName:t.actionName,attemptIndex:t.attemptIndex,channelAudience:normalizeChannelAudience(t.channelAudience),parent:{isRemote:!1,spanId:r.spanId,traceFlags:r.traceFlags,traceId:r.traceId},requestAttribute:i,requestId:t.requestId,rootSessionId:t.rootSessionId,traceSessionId:decodeTraceSessionId(t),sessionId:t.sessionId,startTimeMs:t.startTimeMs,stepIndex:t.stepIndex,turnId:t.turnId}}export{createAgentApprovalInstrumentation};

package/dist/src/tracing/agent-invocation-coordinator.js

@@ -1 +0,0 @@
-import{applyLiveDeliveryAudienceCeiling,readForwardedTraceAssertion}from"#shared/forwarded-trace-policy.js";import{ConversationIdKey}from"#context/keys.js";import{readConversationId}from"#shared/conversation-identity.js";import{readActionTraceContext,readTurnTraceContext}from"#tracing/agent-trace-context-store.js";function resolveToolCallAgentTrace(e){let{serializedContext:t,sessionId:n,turnId:r}=e;return toChildTraceDispatch({conversation:e.conversation,conversationId:readConversationId(t[ConversationIdKey.name]),stored:readActionTraceContext(t,n,r,e.callId)??readTurnTraceContext(t,n,r)})}function toChildTraceDispatch(e){let{stored:t}=e,n=e.conversation?.audience??`unknown`,r=e.conversation?.environment??`production`,i=readForwardedTraceAssertion(t?.forwardedTracePolicy),a=t?.decision===void 0?t:{...t,decision:applyLiveDeliveryAudienceCeiling(t.decision,n,i,r)};return{conversationId:e.conversationId,originAudience:i?.originAudience??n,parentTraceContext:a}}export{resolveToolCallAgentTrace};

package/dist/src/tracing/agent-memory-instrumentation.d.ts

@@ -1,16 +0,0 @@
-import { type Tracer } from "#compiled/@opentelemetry/api/index.js";
-import type { InstrumentationProviderDefinition } from "#instrumentation/lifecycle.js";
-import type { InstrumentationMemoryExecutionOperation } from "#instrumentation/memory.js";
-import type { AgentTraceStateStore } from "#tracing/agent-trace-state.js";
-import type { ConversationEnvironment } from "#shared/conversation-context.js";
-interface AgentMemoryInstrumentation {
-    readonly events: Pick<NonNullable<InstrumentationProviderDefinition["events"]>, "memory.operation.completed" | "memory.operation.failed" | "memory.operation.started">;
-    runInContext<T>(operation: InstrumentationMemoryExecutionOperation, execute: () => PromiseLike<T>): Promise<T>;
-}
-export declare function createAgentMemoryInstrumentation(input: {
-    readonly environment: ConversationEnvironment;
-    readonly recordOutputs?: boolean;
-    readonly stateStore: AgentTraceStateStore;
-    readonly tracer: Tracer;
-}): AgentMemoryInstrumentation;
-export {};

package/dist/src/tracing/agent-memory-instrumentation.js

@@ -1 +0,0 @@
-import{normalizeChannelAudience}from"#shared/channel-audience.js";import{applyLiveDeliveryAudienceCeiling,resolveForwardedTraceSeed}from"#shared/forwarded-trace-policy.js";import{contextStorage}from"#context/container.js";import{SessionTraceSeedKey}from"#context/keys.js";import{withOperationConversation}from"#tracing/conversation-context.js";import{isSampledTrace}from"#tracing/sampled-trace.js";import{ROOT_CONTEXT,SpanKind,context,trace}from"#compiled/@opentelemetry/api/index.js";import{isAgentTraceContext,markAgentTraceContext}from"#tracing/agent-trace-context.js";import{withErrorContent}from"#tracing/error-content-context.js";import{agentSpanNamingAttributes}from"#tracing/agent-span-naming.js";import{genAiMemoryRecordsAttribute}from"#tracing/agent-otel-content.js";import{recordAgentSpanError}from"#tracing/agent-span-error.js";import{agentTraceIdentityAttributes,traceSessionIdOf}from"#tracing/agent-otel-attributes.js";import{withChannelAudience}from"#tracing/channel-audience-context.js";import{suppressTracing}from"#tracing/suppress-tracing.js";function createAgentMemoryInstrumentation(e){let t=e.recordOutputs??!1,n=new Map,parentContext=async t=>{let n=context.active();if(isAgentTraceContext(n))return n;let r=await e.stateStore.getSession(t.sessionId);if(t.turnId!==void 0){let n=await e.stateStore.getTurn(t.sessionId,t.turnId);if(n!==void 0)return withChannelAudience(contextFromSpanContext(n.context),r?.channelAudience)}return r===void 0?void 0:withChannelAudience(contextFromSpanContext(r.context),r.channelAudience)},onStarted=async t=>{if(n.has(t.idempotencyKey))return;let r=await parentContext(t),i=r===void 0?void 0:trace.getSpan(r)?.spanContext();if(r===void 0||i===void 0||!isSampledTrace(i))return;let a=e.tracer.startSpan(t.operationName,{attributes:memorySpanAttributes(t),kind:SpanKind.CLIENT},r);n.set(t.idempotencyKey,{context:trace.setSpan(r,a),span:a})},onTerminal=e=>{let t=n.get(e.idempotencyKey);t!==void 0&&(n.delete(e.idempotencyKey),updateMemorySpan(t.span,e),t.span.end())};return{events:{"memory.operation.completed":onTerminal,"memory.operation.failed":onTerminal,"memory.operation.started":onStarted},async runInContext(r,i){let a=await e.stateStore.getSession(r.sessionId),o=n.get(r.idempotencyKey)?.context;if(o===void 0&&r.turnId!==void 0){let t=await e.stateStore.getTurn(r.sessionId,r.turnId);t!==void 0&&(o=withChannelAudience(contextFromSpanContext(t.context),a?.channelAudience),isSampledTrace(t.context)||(o=suppressTracing(o)))}o===void 0&&a!==void 0&&(o=withChannelAudience(contextFromSpanContext(a.context),a.channelAudience),isSampledTrace(a.context)||(o=suppressTracing(o)));let s=resolveForwardedTraceSeed(contextStorage.getStore()?.get(SessionTraceSeedKey)),c=s?.decision??a?.decision,l=c===void 0?void 0:applyLiveDeliveryAudienceCeiling(c,normalizeChannelAudience(a?.channelAudience),s?.forwardedTracePolicy,e.environment);return o===void 0?await i():await context.with(markAgentTraceContext(withErrorContent(withOperationConversation(o,{rootSessionId:a?.rootSessionId,sessionId:r.sessionId}),t&&l?.action===`record`&&l.recordOutputs)),i)}}}function memorySpanAttributes(e){let t={"agent.memory.phase":e.phase,"agent.memory.slot":e.slot,"gen_ai.memory.store.id":e.storeId,"gen_ai.operation.name":e.operationName,...agentSpanNamingAttributes(e.operationName,e.operationName),...agentTraceIdentityAttributes({rootSessionId:e.rootSessionId,traceSessionId:traceSessionIdOf(e),sessionId:e.sessionId})};return e.turnId!==void 0&&(t[`agent.turn.id`]=e.turnId),t}function updateMemorySpan(e,t){if(t.type===`memory.operation.failed`)recordAgentSpanError(e,t.error);else{t.recordCount!==void 0&&e.setAttribute(`gen_ai.memory.record.count`,t.recordCount);let n=genAiMemoryRecordsAttribute(t.outputRecords??[]);n!==void 0&&t.outputRecords!==void 0&&e.setAttribute(`gen_ai.memory.records`,n)}}function contextFromSpanContext(e){return trace.setSpan(ROOT_CONTEXT,trace.wrapSpanContext(e))}export{createAgentMemoryInstrumentation};

package/dist/src/tracing/agent-otel-attributes.d.ts

@@ -1,10 +0,0 @@
-export declare function traceSessionIdOf(scope: {
-    readonly traceSessionId?: string;
-    readonly rootSessionId?: string;
-    readonly sessionId: string;
-}): string;
-export declare function agentTraceIdentityAttributes(input: {
-    readonly rootSessionId: string;
-    readonly sessionId: string;
-    readonly traceSessionId: string;
-}): Record<string, string | number>;

package/dist/src/tracing/agent-otel-attributes.js

@@ -1 +0,0 @@
-import{AGENT_TRACE_SCHEMA_VERSION}from"#tracing/agent-span-contract.js";import{operationConversationId}from"#tracing/conversation-context.js";function traceSessionIdOf(e){return e.traceSessionId??e.rootSessionId??e.sessionId}function agentTraceIdentityAttributes(e){let t=operationConversationId(e),n={"agent.run.id":e.sessionId,"agent.trace.schema.version":AGENT_TRACE_SCHEMA_VERSION,"gen_ai.conversation.id":t};return process.env.VERCEL_ENV!==void 0&&(n[`vercel.session_id`]=e.traceSessionId),n}export{agentTraceIdentityAttributes,traceSessionIdOf};

package/dist/src/tracing/agent-otel-content.js

@@ -1,4 +0,0 @@
-import{isUserMessageKind}from"#harness/messages.js";const CONTENT_ATTRIBUTE_LIMIT=32768;function contentAttribute(e){if(e===void 0)return;let t;try{t=JSON.stringify(e)}catch{return}if(t!==void 0)return textContentAttribute(t)}function genAiInputMessagesAttribute(e){if(!Array.isArray(e))return;let t=e.flatMap(e=>{if(!isRecord(e)||e.role===`system`||typeof e.role!=`string`)return[];let t=semanticParts(e.content);if(t.length===0)return[];let n=e.role===`user`&&isUserMessageKind(e.kind)?e.kind:void 0;return[n===void 0?{parts:t,role:e.role}:{kind:n,parts:t,role:e.role}]});for(let e=0;e<t.length;e+=1){let n=semanticJsonAttribute(t.slice(e));if(n!==void 0)return n}return truncateSingleSemanticMessage(t)??semanticJsonAttribute([])}function genAiSystemInstructionsAttribute(e){let t=systemPromptText(e);if(t!==void 0)return fitSemanticText(t,e=>[{content:e,type:`text`}])}function genAiToolDefinitionsAttribute(e){if(!Array.isArray(e))return;let t=e.flatMap(e=>{if(!isRecord(e)||typeof e.name!=`string`)return[];let t={name:e.name};return typeof e.description==`string`&&(t.description=e.description),e.inputSchema!==void 0&&(t.parameters=e.inputSchema),[t]});if(t.length===0)return;let n=[],r=2;for(let e of t){let t=stringifyContent(e);if(t===void 0)break;let i=r+(n.length===0?0:1)+t.length;if(i>32768)break;n.push(t),r=i}return`[${n.join(`,`)}]`}function genAiOutputMessagesAttribute(e,t){let n=semanticParts(e);return semanticJsonAttribute([{finish_reason:t===`tool-calls`?`tool_call`:t,parts:n,role:`assistant`}])}function genAiMemoryRecordsAttribute(e){return semanticJsonAttribute(e)}function toolResultsContentAttribute(e){if(e.length===0)return;let t=stringifyContent(e);if(t!==void 0&&t.length<=32768)return t;for(let t=CONTENT_ATTRIBUTE_LIMIT;t>=0;t=t>=256?Math.floor(t/2):-1){let n=stringifyContent(e.map(e=>cappedToolResult(e,t)));if(n!==void 0&&n.length<=32768)return n}}function cappedToolResult(e,t){let n={toolName:e.toolName};for(let r of[`input`,`output`,`error`]){if(!(r in e))continue;let i=e[r],a=typeof i==`string`?i:stringifyContent(i)??``;n[r]=a.length<=t?a:`${a.slice(0,t)}… [truncated]`}return n}function systemPromptText(e){if(typeof e==`string`)return e.length===0?void 0:e;if(!isRecord(e)&&!Array.isArray(e))return;let t=Array.isArray(e)?e:[e],n=[];for(let e of t)if(isRecord(e)){if(typeof e.content==`string`)n.push(e.content);else if(Array.isArray(e.content))for(let t of e.content)isRecord(t)&&t.type===`text`&&typeof t.text==`string`&&n.push(t.text)}let r=n.join(`
-
-`).trim();return r.length===0?void 0:r}function textContentAttribute(e){if(e.length!==0)return e.length<=32768?e:`${e.slice(0,CONTENT_ATTRIBUTE_LIMIT)}… [truncated]`}function stringifyContent(e){try{return JSON.stringify(e)}catch{return}}function semanticJsonAttribute(e){let t=stringifyContent(e);return t!==void 0&&t.length<=32768?t:void 0}function truncateSingleSemanticMessage(e){let t=e.at(-1);if(t===void 0||typeof t.role!=`string`)return;let n=semanticMessageText(t.parts),r=typeof t.kind==`string`?{kind:t.kind,role:t.role}:{role:t.role};return fitSemanticText(n,e=>[{...r,parts:[{content:e,type:`text`}]}],!0)}function fitSemanticText(e,t,n=!1){if(!n&&e.length<=32768){let n=semanticJsonAttribute(t(e));if(n!==void 0)return n}for(let n=Math.min(e.length,CONTENT_ATTRIBUTE_LIMIT);n>0;n-=256){let r=semanticJsonAttribute(t(`${e.slice(0,n)}… [truncated]`));if(r!==void 0)return r}return semanticJsonAttribute(t(`… [truncated]`))}function semanticMessageText(e){if(!Array.isArray(e))return``;let t=``;for(let n of e){if(!isRecord(n)||n.type!==`text`||typeof n.content!=`string`)continue;let e=t.length===0?``:`
-`,r=32769-t.length-e.length;if(r<=0)break;t+=e+n.content.slice(0,r)}return t}function semanticParts(e){if(typeof e==`string`)return[{content:e,type:`text`}];if(!Array.isArray(e))return[];let t=[];for(let n of e){let e=semanticPart(n);e!==void 0&&t.push(e)}return t}function semanticPart(e){if(isRecord(e)&&typeof e.type==`string`)switch(e.type){case`text`:case`reasoning`:{let t=typeof e.text==`string`?e.text:e.content;return typeof t==`string`?{content:t,type:e.type}:void 0}case`tool-call`:return{arguments:e.input,id:stringValue(e.toolCallId)??stringValue(e.callId)??null,name:e.toolName,type:`tool_call`};case`tool-result`:return{id:stringValue(e.toolCallId)??stringValue(e.callId)??null,response:toolResponse(e.output),type:`tool_call_response`};case`tool-error`:return{id:stringValue(e.toolCallId)??stringValue(e.callId)??null,response:e.error instanceof Error?e.error.message:e.error,type:`tool_call_response`};default:return{type:e.type}}}function toolResponse(e){return isRecord(e)?(e.type===`text`||e.type===`error-text`||e.type===`json`||e.type===`error-json`)&&`value`in e?e.value:e.type===`execution-denied`?{denied:!0,reason:e.reason}:e:e}function stringValue(e){return typeof e==`string`?e:void 0}function isRecord(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}export{CONTENT_ATTRIBUTE_LIMIT,contentAttribute,genAiInputMessagesAttribute,genAiMemoryRecordsAttribute,genAiOutputMessagesAttribute,genAiSystemInstructionsAttribute,genAiToolDefinitionsAttribute,textContentAttribute,toolResultsContentAttribute};