Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

fix(eve): separate root session and agent run identity (#3316)

Chad Hietala871332a22aee
diff --git a/.changeset/root-session-run-identity.md b/.changeset/root-session-run-identity.md
new file mode 100644
index 000000000..e28ec1a77
--- /dev/null
+++ b/.changeset/root-session-run-identity.md
@@ -0,0 +1,5 @@
+---
+"eve": patch
+---
+
+Keep Vercel Agent Runs spans indexed under the root session while recording each activation's run ID and immediate parent lineage separately. Remote-created sessions retain that root when the receiver trusts the authenticated forwarder.
diff --git a/docs/guides/instrumentation-providers.md b/docs/guides/instrumentation-providers.md
index 5219fb00d..5ea12a02a 100644
--- a/docs/guides/instrumentation-providers.md
+++ b/docs/guides/instrumentation-providers.md
@@ -153,7 +153,7 @@ export default otelIntegration({
});
```
-Custom destinations receive the schema v4 agent trace contract. Follow [Query exported traces](./instrumentation#query-exported-traces) to find activations and join sessions across traces.
+Custom destinations receive the schema v4 agent trace contract. Follow [Query exported traces](./instrumentation#query-exported-traces) to find activations and sessions across traces.
Add `agent/instrumentation/otel.ts` when you need process-wide settings or want to control which content eve writes to OpenTelemetry spans:
diff --git a/docs/guides/instrumentation.md b/docs/guides/instrumentation.md
index 97056051a..32ab928d5 100644
--- a/docs/guides/instrumentation.md
+++ b/docs/guides/instrumentation.md
@@ -56,7 +56,7 @@ Three more fields control what eve and the AI SDK record inside those spans (see
eve records metadata without model, tool, or memory-record content by default. Enable either content category only after reviewing the exporter and its data-retention path.
-In the provider layout, eve stamps each span with `gen_ai.conversation.id`, which stays fixed across local and remote activations, including independent remote root workflows. Query this attribute to find the conversation's exported, retained traces; it does not grant access or control trace parenting. On Vercel, `vercel.session_id` additionally identifies the current Workflow run. See [Query exported traces](#query-exported-traces) for the cross-backend workflow.
+In the provider layout, eve stamps each span with `gen_ai.conversation.id`, which stays fixed across local and remote activations, including independent remote root workflows. Query this attribute to find the conversation's exported, retained traces; it does not grant access or control trace parenting. On Vercel, `vercel.session_id` identifies the verified root session, while `agent.run.id` identifies the current agent run. See [Query exported traces](#query-exported-traces) for the cross-backend workflow.
You are responsible for ensuring any observability or eval provider is approved for the data exported to it.
@@ -193,7 +193,14 @@ the failure outcome, error status, and error type. The initiating turn can
finish or be cancelled while the action remains open. Ending the session closes
an action whose task never reported a terminal result.
-Schema v4 removes the session-long `agent.session` root and duplicate agent session and lineage attributes. Every eve span carries `agent.trace.schema.version=4` and `gen_ai.conversation.id`; Vercel deployments additionally carry `vercel.session_id`.
+Schema v4 removes the session-long `agent.session` root. Every run-associated
+eve span carries `agent.trace.schema.version=4`, `agent.run.id`, and
+`gen_ai.conversation.id`; the pre-session `agent.channel.request` span is the
+exception. Vercel deployments additionally carry
+`vercel.session_id`, which stays fixed to the root session across local and
+trusted remote subagents. Remote lineage is accepted only when the receiver's
+`trustedForwarders` predicate approves the authenticated caller. Child
+activation roots carry `agent.parent_run.id` and `agent.parent_call.id`.
Only activations use the `invoke_agent` operation. A workflow tool invocation
that coordinates at least one nested agent uses `invoke_workflow`, with its
path-derived tool name in `gen_ai.workflow.name`. Durable workflow tools without
@@ -261,7 +268,8 @@ This workflow applies to schema v4 from the [instrumentation provider layout](./
| Agent activations | `agent.trace.schema.version=4` and `gen_ai.operation.name=invoke_agent` |
| One logical conversation | `gen_ai.conversation.id=<conversation ID>` |
| One turn | Both `gen_ai.conversation.id` and `agent.turn.id` |
-| One Vercel Workflow run | `vercel.session_id=<session ID>` |
+| One Vercel root session | `vercel.session_id=<root session ID>` |
+| One agent run | `agent.run.id=<run ID>` |
| Delegated dispatches | `agent.invocation.role=caller` |
Start with an activation filter for latency, failure, or turn-count dashboards. Every activation is a trace root. Within a conversation, group by trace ID, order activations by `agent.turn.sequence` or start time, and open the selected trace ID. Child activations link to their caller with `eve.link.type=agent.dispatch`; remote workflows keep their own execution lineage, so use conversation IDs and caller links for cross-deployment correlation.
diff --git a/packages/eve/src/eve-channel/index.ts b/packages/eve/src/eve-channel/index.ts
index 68af40935..9108d2d23 100644
--- a/packages/eve/src/eve-channel/index.ts
+++ b/packages/eve/src/eve-channel/index.ts
@@ -1,4 +1,4 @@
-import type { SessionAuthContext, SessionTraceContext } from "#channel/types.js";
+import type { SessionAuthContext, SessionParent, SessionTraceContext } from "#channel/types.js";
import type { Session } from "#channel/session.js";
import { resolveForwardedPrincipal } from "#channel/forwarded-principal.js";
import {
@@ -49,7 +49,10 @@ import type { ClearResponse } from "#protocol/clear-session.js";
import type { CompactResponse } from "#protocol/compact-session.js";
import type { ResetResponse } from "#protocol/reset-session.js";
import { parseTraceparent, readAgentDispatchTraceContext } from "#protocol/traceparent.js";
-import { readForwardedAudienceBaggage } from "#protocol/baggage.js";
+import {
+ readForwardedAudienceBaggage,
+ readForwardedParentSessionBaggage,
+} from "#protocol/baggage.js";
import { readConversationBaggage } from "#tracing/conversation-context.js";
import {
FAIL_CLOSED_FORWARDED_TRACE_ASSERTION,
@@ -151,6 +154,44 @@ export function eveChannel(input: EveChannelInput): EveChannel {
const body = parseCreateBody(payload);
if (body instanceof Response) return body;
+ const forwardedParentSession =
+ body.callback === undefined
+ ? "absent"
+ : readForwardedParentSessionBaggage(req.headers.get("baggage"));
+ let parent: SessionParent | undefined;
+ if (typeof forwardedParentSession === "object") {
+ if (forwardedParentSession.callId !== body.callback?.callId) {
+ log.warn("ignoring remote parent lineage with a mismatched callback", {
+ forwarder: authResult.principalId,
+ });
+ } else {
+ let accepted = forwarded.accepted;
+ if (!accepted && input.trustedForwarders !== undefined) {
+ try {
+ accepted = await input.trustedForwarders(authResult);
+ } catch (error) {
+ const errorId = logError(log, "trustedForwarders handler failed", error, {
+ forwarder: authResult.principalId,
+ });
+ return Response.json(
+ { error: "trustedForwarders handler failed.", errorId, ok: false },
+ { status: 500 },
+ );
+ }
+ }
+ if (accepted) {
+ parent = forwardedParentSession;
+ } else {
+ log.warn("ignoring remote parent lineage from an untrusted forwarder", {
+ forwarder: authResult.principalId,
+ });
+ }
+ }
+ } else if (forwardedParentSession === "malformed") {
+ log.warn("ignoring malformed remote parent lineage", {
+ forwarder: authResult.principalId,
+ });
+ }
const transportParentTraceContext =
body.callback === undefined
? undefined
@@ -273,6 +314,7 @@ export function eveChannel(input: EveChannelInput): EveChannel {
body.callback === undefined
? undefined
: readConversationBaggage(req.headers.get("baggage")),
+ parent,
parentTraceContext,
title: messageResult.title,
});
diff --git a/packages/eve/src/eve-channel/types.ts b/packages/eve/src/eve-channel/types.ts
index 7d6e8f7f5..3e54c1042 100644
--- a/packages/eve/src/eve-channel/types.ts
+++ b/packages/eve/src/eve-channel/types.ts
@@ -96,12 +96,13 @@ export interface EveChannelInput {
readonly auth: AuthFn<Request> | readonly AuthFn<Request>[];
/**
* The trusted-forwarders policy: which transport-authenticated callers may
- * assert a forwarded principal or callback-marked public trace audience. The predicate
- * receives the *verified* route-auth principal of the forwarder — who is
- * asserting, never what is asserted — and must match it precisely (for example
- * `(forwarder) => forwarder.subject === vercelSubject({ teamSlug, projectName })`).
- * A permissive predicate lets any authenticated forwarder assert any
- * principal and public trace audience.
+ * assert a forwarded principal, callback-marked public trace audience, or
+ * remote parent lineage. The predicate receives the *verified* route-auth
+ * principal of the forwarder — who is asserting, never what is asserted —
+ * and must match it precisely (for example `(forwarder) =>
+ * forwarder.subject === vercelSubject({ teamSlug, projectName })`). A
+ * permissive predicate lets any authenticated forwarder assert any principal,
+ * public trace audience, or remote lineage.
*
* When a trusted forwarder's assertion is accepted on session creation, the
* forwarded principal replaces `session.auth.current` and
@@ -110,7 +111,8 @@ export interface EveChannelInput {
* forwarder is recorded on accepted contexts as the `eve:forwarded-by`
* attribute. An accepted public audience is evaluated by this deployment's
* trace policies; the default records model and tool content. Omit the option
- * to reject forwarded principals with 403 and ignore forwarded audience.
+ * to reject forwarded principals with 403 and ignore forwarded audience and
+ * remote lineage.
*/
readonly trustedForwarders?: TrustedForwarders;
/**
diff --git a/packages/eve/src/execution/eve-workflow-attributes.ts b/packages/eve/src/execution/eve-workflow-attributes.ts
index 6ba727a5e..cf845d3cd 100644
--- a/packages/eve/src/execution/eve-workflow-attributes.ts
+++ b/packages/eve/src/execution/eve-workflow-attributes.ts
@@ -163,7 +163,7 @@ export function readParentSessionId(
* site (see {@link "#channel/types.js".SessionParent}) so a subagent
* five levels deep can still attribute itself to the top user-facing
* session without walking the chain. Returns `undefined` for top-level
- * runs, which carry no `eve.parentSession`.
+ * runs, which carry no verified `eve.parentSession`.
*/
export function readRootSessionId(serializedContext: Record<string, unknown>): string | undefined {
return readParentLineage(serializedContext).rootSessionId;
diff --git a/packages/eve/src/execution/run-session-limits.ts b/packages/eve/src/execution/run-session-limits.ts
index 9969af03e..3d99288e3 100644
--- a/packages/eve/src/execution/run-session-limits.ts
+++ b/packages/eve/src/execution/run-session-limits.ts
@@ -14,9 +14,8 @@ export function resolveInheritedTokenLimit(input: {
readonly configured: UsageLimit | undefined;
readonly inherited: UsageLimit | undefined;
}): UsageLimit | undefined {
- if (input.inherited === undefined || input.inherited === false) {
- return input.configured;
- }
+ if (input.inherited === undefined) return input.configured;
+ if (input.inherited === false) return input.configured ?? false;
if (input.configured === undefined || input.configured === false) {
return input.inherited;
}
diff --git a/packages/eve/src/execution/session.test.ts b/packages/eve/src/execution/session.test.ts
index beaf04650..1f915a44c 100644
--- a/packages/eve/src/execution/session.test.ts
+++ b/packages/eve/src/execution/session.test.ts
@@ -255,7 +255,7 @@ describe("createSession", () => {
);
});
- it("leaves delegated subagent sessions uncapped by default", () => {
+ it("keeps the default cap when remote lineage has no inherited budget", () => {
const session = createSession({
continuationToken: "subagent-token",
rootSessionId: "sess-root",
@@ -263,7 +263,9 @@ describe("createSession", () => {
turnAgent: createTestTurnAgent(),
});
- expect(session.limits).toEqual({});
+ expect(session.limits?.maxInputTokensPerSession).toBe(
+ DEFAULT_ROOT_MAX_INPUT_TOKENS_PER_SESSION,
+ );
});
it("uncaps a root session when the authored limit is false", () => {
diff --git a/packages/eve/src/execution/session.ts b/packages/eve/src/execution/session.ts
index 41cb5889c..a32a627ee 100644
--- a/packages/eve/src/execution/session.ts
+++ b/packages/eve/src/execution/session.ts
@@ -308,17 +308,12 @@ function createSessionToolDefinitions(turnAgent: RuntimeTurnAgent): SessionToolD
}));
}
-function resolveSessionLimits(input: {
- readonly limits?: AuthoredSessionLimits;
- readonly rootSessionId?: string;
-}): SessionLimits {
- const isSubagent = input.rootSessionId !== undefined;
-
+function resolveSessionLimits(input: { readonly limits?: AuthoredSessionLimits }): SessionLimits {
const maxInputTokensPerSession = resolveSessionTokenLimit({
authored: input.limits?.maxInputTokensPerSession,
- // Subagents have no fixed default: uncapped parents delegate uncapped
- // children, capped parents delegate their remaining quota (inherited).
- fallback: isSubagent ? undefined : DEFAULT_ROOT_MAX_INPUT_TOKENS_PER_SESSION,
+ // Local children carry an explicit inherited value, including `false` for
+ // an uncapped parent. Remote lineage alone must not remove this default.
+ fallback: DEFAULT_ROOT_MAX_INPUT_TOKENS_PER_SESSION,
});
const maxOutputTokensPerSession = resolveSessionTokenLimit({
authored: input.limits?.maxOutputTokensPerSession,
diff --git a/packages/eve/src/instrumentation/parent-lineage.test.ts b/packages/eve/src/instrumentation/parent-lineage.test.ts
index 6415ea145..391a143b6 100644
--- a/packages/eve/src/instrumentation/parent-lineage.test.ts
+++ b/packages/eve/src/instrumentation/parent-lineage.test.ts
@@ -28,14 +28,14 @@ describe("parent trace lineage", () => {
});
it("uses the current callback for remote continuations", () => {
- expect(
- resolveParentLineage(parent, undefined, {
- callId: "continued-remote-call",
- subagentName: "research",
- token: "callback-token",
- url: "https://parent.example/callback",
- })?.callId,
- ).toBe("continued-remote-call");
+ const lineage = resolveParentLineage(parent, undefined, {
+ callId: "continued-remote-call",
+ subagentName: "research",
+ token: "callback-token",
+ url: "https://parent.example/callback",
+ });
+ expect(lineage?.callId).toBe("continued-remote-call");
+ expect(lineage?.subagentName).toBe("research");
});
it("does not invent delegated lineage from callback metadata", () => {
diff --git a/packages/eve/src/instrumentation/parent-lineage.ts b/packages/eve/src/instrumentation/parent-lineage.ts
index 334d68928..5b23ff3f3 100644
--- a/packages/eve/src/instrumentation/parent-lineage.ts
+++ b/packages/eve/src/instrumentation/parent-lineage.ts
@@ -19,7 +19,7 @@ export function resolveParentLineage(
return {
callId: callback?.callId ?? subagent?.callId ?? parent.callId,
sessionId: parent.sessionId,
- subagentName: subagent?.subagentName,
+ subagentName: callback?.subagentName ?? subagent?.subagentName,
turnId: parent.turn.id,
};
}
diff --git a/packages/eve/src/protocol/baggage.test.ts b/packages/eve/src/protocol/baggage.test.ts
index bb9c5f8ba..13f75ae0a 100644
--- a/packages/eve/src/protocol/baggage.test.ts
+++ b/packages/eve/src/protocol/baggage.test.ts
@@ -3,13 +3,21 @@ import { describe, expect, it } from "vitest";
import {
readBaggageMember,
readForwardedAudienceBaggage,
+ readForwardedParentSessionBaggage,
writeForwardedAudienceBaggage,
+ writeForwardedParentSessionBaggage,
} from "#protocol/baggage.js";
const PUBLIC_OUTPUTS = {
ceiling: { recordInputs: false, recordOutputs: true },
originAudience: "public",
} as const;
+const PARENT = {
+ callId: "call-1",
+ rootSessionId: "root-session",
+ sessionId: "parent-session",
+ turn: { id: "turn-1", sequence: 2 },
+} as const;
describe("baggage member parsing", () => {
it.each(["eve.audience", "eve.conversation.id"])("uses the same wire rules for %s", (key) => {
@@ -136,3 +144,24 @@ describe("writeForwardedAudienceBaggage", () => {
).toBeUndefined();
});
});
+
+describe("forwarded parent session baggage", () => {
+ it("round-trips lineage while preserving unrelated members", () => {
+ const baggage = writeForwardedParentSessionBaggage("vendor=value", PARENT);
+ expect(baggage).toContain("vendor=value");
+ expect(readForwardedParentSessionBaggage(baggage!)).toEqual(PARENT);
+ });
+
+ it.each([null, "vendor=value"])("returns absent for %s", (value) => {
+ expect(readForwardedParentSessionBaggage(value)).toBe("absent");
+ });
+
+ it.each([
+ "eve.parent_session=not-json",
+ `eve.parent_session=${encodeURIComponent(JSON.stringify({ ...PARENT, callId: "" }))}`,
+ `eve.parent_session=${encodeURIComponent(JSON.stringify({ ...PARENT, turn: { id: "turn-1" } }))}`,
+ `eve.parent_session=${encodeURIComponent(JSON.stringify(PARENT))};extra=yes`,
+ ])("rejects malformed lineage %s", (value) => {
+ expect(readForwardedParentSessionBaggage(value)).toBe("malformed");
+ });
+});
diff --git a/packages/eve/src/protocol/baggage.ts b/packages/eve/src/protocol/baggage.ts
index 0f68f7718..22493c4c6 100644
--- a/packages/eve/src/protocol/baggage.ts
+++ b/packages/eve/src/protocol/baggage.ts
@@ -3,8 +3,10 @@ import type {
TraceContentCeiling,
} from "#shared/forwarded-trace-policy.js";
import { formatTraceContentCeiling } from "#shared/forwarded-trace-policy.js";
+import type { SessionParent } from "#channel/types.js";
const EVE_AUDIENCE_KEY = "eve.audience";
+const EVE_PARENT_SESSION_KEY = "eve.parent_session";
const CEILING_PROPERTY_KEY = "ceiling";
const MAX_BAGGAGE_BYTES = 8192;
const encoder = new TextEncoder();
@@ -21,6 +23,58 @@ interface BaggageMember {
}
export type ForwardedTraceBaggage = "absent" | "malformed" | ForwardedTraceAssertion;
+export type ForwardedParentSessionBaggage = "absent" | "malformed" | SessionParent;
+
+/** Reads remote parent lineage without trusting the caller that supplied it. */
+export function readForwardedParentSessionBaggage(
+ value: string | null,
+): ForwardedParentSessionBaggage {
+ const member = readBaggageMember(value, EVE_PARENT_SESSION_KEY);
+ if (typeof member === "string") return member;
+ if (member.properties.length !== 0) return "malformed";
+ let parsed: unknown;
+ try {
+ parsed = JSON.parse(member.value);
+ } catch {
+ return "malformed";
+ }
+ if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return "malformed";
+ const parent = parsed as Partial<SessionParent>;
+ const turn = parent.turn;
+ if (
+ typeof parent.callId !== "string" ||
+ parent.callId.length === 0 ||
+ typeof parent.rootSessionId !== "string" ||
+ parent.rootSessionId.length === 0 ||
+ typeof parent.sessionId !== "string" ||
+ parent.sessionId.length === 0 ||
+ turn === undefined ||
+ typeof turn.id !== "string" ||
+ turn.id.length === 0 ||
+ !Number.isSafeInteger(turn.sequence) ||
+ turn.sequence < 0
+ ) {
+ return "malformed";
+ }
+ return {
+ callId: parent.callId,
+ rootSessionId: parent.rootSessionId,
+ sessionId: parent.sessionId,
+ turn: { id: turn.id, sequence: turn.sequence },
+ };
+}
+
+/** Replaces Eve's remote parent lineage while preserving unrelated baggage. */
+export function writeForwardedParentSessionBaggage(
+ value: string | undefined,
+ parent: SessionParent | undefined,
+): string | undefined {
+ return replaceBaggageMember(
+ value,
+ EVE_PARENT_SESSION_KEY,
+ parent === undefined ? undefined : encodeURIComponent(JSON.stringify(parent)),
+ );
+}
/** Reads eve's audience member without interpreting unrelated baggage. */
export function readForwardedAudienceBaggage(value: string | null): ForwardedTraceBaggage {
diff --git a/packages/eve/src/public/channels/eve-session-routes.test.ts b/packages/eve/src/public/channels/eve-session-routes.test.ts
index c001a5e24..a355415fb 100644
--- a/packages/eve/src/public/channels/eve-session-routes.test.ts
+++ b/packages/eve/src/public/channels/eve-session-routes.test.ts
@@ -4,6 +4,7 @@ import type { RouteHandlerArgs } from "#channel/routes.js";
import type { Session } from "#channel/session.js";
import { attachRouteSessionCreator } from "#internal/nitro/routes/channel-route-context.js";
import { mockChannelContext } from "#internal/testing/mocks/mock-channel-operations.js";
+import { writeForwardedParentSessionBaggage } from "#protocol/baggage.js";
import { none } from "#public/channels/auth.js";
import { eveChannel } from "#public/channels/eve.js";
@@ -276,6 +277,55 @@ describe("eve ID-addressed session routes", () => {
},
);
+ it.each([true, false])(
+ "promotes remote parent lineage only from a trusted forwarder (%s)",
+ async (trusted) => {
+ const createSession = vi.fn().mockResolvedValue({
+ events: new ReadableStream(),
+ sessionId: "wrun_A",
+ });
+ const args = attachRouteSessionCreator(createArgs(), createSession);
+ const trustedForwarders = vi.fn(() => trusted);
+ const parent = {
+ callId: "call-1",
+ rootSessionId: "root-session",
+ sessionId: "parent-session",
+ turn: { id: "turn-1", sequence: 2 },
+ } as const;
+
+ const response = await route("POST", "/eve/v1/session", {
+ auth: none(),
+ trustedForwarders,
+ })(
+ new Request("https://eve.test/eve/v1/session", {
+ body: JSON.stringify({
+ callback: {
+ callId: "call-1",
+ subagentName: "research",
+ token: "tok123",
+ url: "https://caller.example.com/eve/v1/callback/tok123",
+ },
+ message: "hello",
+ }),
+ headers: {
+ "content-type": "application/json",
+ baggage: writeForwardedParentSessionBaggage(undefined, parent)!,
+ },
+ method: "POST",
+ }),
+ args,
+ );
+
+ expect(response.status).toBe(202);
+ expect(trustedForwarders).toHaveBeenCalledTimes(1);
+ expect(createSession).toHaveBeenCalledWith(
+ expect.objectContaining({
+ parent: trusted ? parent : undefined,
+ }),
+ );
+ },
+ );
+
it("rejects input responses on session creation", async () => {
const createSession = vi.fn();
const args = attachRouteSessionCreator(createArgs(), createSession);
diff --git a/packages/eve/src/subagents/remote-dispatch.test.ts b/packages/eve/src/subagents/remote-dispatch.test.ts
index 7438f0bae..060044494 100644
--- a/packages/eve/src/subagents/remote-dispatch.test.ts
+++ b/packages/eve/src/subagents/remote-dispatch.test.ts
@@ -1,6 +1,7 @@
import { afterEach, describe, expect, it, vi } from "vitest";
import type { SessionAuthContext } from "#channel/types.js";
+import { readForwardedParentSessionBaggage } from "#protocol/baggage.js";
import {
cancelRemoteAgentTurn,
continueRemoteAgentSession,
@@ -300,6 +301,12 @@ describe("startRemoteAgentSession", () => {
state: {},
},
parent: {
+ lineage: {
+ callId: "call-remote",
+ rootSessionId: "root-session",
+ sessionId: "parent-session",
+ turn: { id: "parent-turn", sequence: 0 },
+ },
traceContext: {
spanId: "2".repeat(16),
traceFlags: 1,
@@ -313,6 +320,7 @@ describe("startRemoteAgentSession", () => {
body: expect.any(String),
headers: {
authorization: "Bearer remote-token",
+ baggage: expect.any(String),
"content-type": "application/json",
tracestate: `eve=${"2".repeat(16)}`,
traceparent: `00-${"1".repeat(32)}-${"2".repeat(16)}-01`,
@@ -339,6 +347,16 @@ describe("startRemoteAgentSession", () => {
capabilities: {},
mode: "conversation",
});
+ expect(
+ readForwardedParentSessionBaggage(
+ new Headers(fetchMock.mock.calls[0]?.[1]?.headers).get("baggage"),
+ ),
+ ).toEqual({
+ callId: "call-remote",
+ rootSessionId: "root-session",
+ sessionId: "parent-session",
+ turn: { id: "parent-turn", sequence: 0 },
+ });
});
it("binds a task id to an opaque invocation callback token", async () => {
diff --git a/packages/eve/src/subagents/remote-dispatch.ts b/packages/eve/src/subagents/remote-dispatch.ts
index 77a606430..34e2bd536 100644
--- a/packages/eve/src/subagents/remote-dispatch.ts
+++ b/packages/eve/src/subagents/remote-dispatch.ts
@@ -34,7 +34,10 @@ import type { ResolvedRuntimeRemoteAgentNode } from "#runtime/types.js";
import { expectFunction, expectObjectRecord } from "#internal/authored-module.js";
import type { JsonObject } from "#shared/json.js";
import { readTaskIdFromInboxToken } from "#tasks/task-inbox-token.js";
-import { writeForwardedAudienceBaggage } from "#protocol/baggage.js";
+import {
+ writeForwardedAudienceBaggage,
+ writeForwardedParentSessionBaggage,
+} from "#protocol/baggage.js";
import { decisionToTraceContentCeiling } from "#shared/forwarded-trace-policy.js";
import { writeConversationBaggage } from "#tracing/conversation-context.js";
@@ -73,7 +76,9 @@ export async function startRemoteAgentSession(input: {
* created instead of starting a second one.
*/
readonly operationId?: string;
- readonly parent?: Omit<SubagentParentContext, "lineage">;
+ readonly parent?: Omit<SubagentParentContext, "lineage"> & {
+ readonly lineage?: SubagentParentContext["lineage"];
+ };
readonly remote: ResolvedRuntimeRemoteAgentNode;
readonly session: HarnessSession;
readonly taskId?: string;
@@ -147,7 +152,12 @@ export async function startRemoteAgentSession(input: {
traceparent,
}),
);
- setHeader(headers, "baggage", writeConversationBaggage(baggage, input.parent?.conversationId));
+ const conversationBaggage = writeConversationBaggage(baggage, input.parent?.conversationId);
+ setHeader(
+ headers,
+ "baggage",
+ writeForwardedParentSessionBaggage(conversationBaggage, input.parent?.lineage),
+ );
const response = await fetch(createRemoteAgentSessionUrl(input.remote), {
body: JSON.stringify(requestBody),
headers: {
diff --git a/packages/eve/src/tracing/agent-otel-attributes.test.ts b/packages/eve/src/tracing/agent-otel-attributes.test.ts
index f067940b3..29234205e 100644
--- a/packages/eve/src/tracing/agent-otel-attributes.test.ts
+++ b/packages/eve/src/tracing/agent-otel-attributes.test.ts
@@ -1,5 +1,7 @@
import { afterEach, describe, expect, it, vi } from "vitest";
+import { ContextContainer, contextStorage } from "#context/container.js";
+import { ConversationIdKey } from "#context/keys.js";
import { agentTraceIdentityAttributes } from "#tracing/agent-otel-attributes.js";
afterEach(() => {
@@ -7,24 +9,30 @@ afterEach(() => {
});
describe("agentTraceIdentityAttributes", () => {
- const input = { rootSessionId: "conversation-1", sessionId: "session-1" };
+ const input = { rootSessionId: "root-session", sessionId: "session-1" };
it("uses the GenAI conversation identifier outside Vercel", () => {
vi.stubEnv("VERCEL_ENV", undefined);
expect(agentTraceIdentityAttributes(input)).toEqual({
+ "agent.run.id": "session-1",
"agent.trace.schema.version": 4,
- "gen_ai.conversation.id": "conversation-1",
+ "gen_ai.conversation.id": "root-session",
});
});
it("adds the Vercel session identifier on Vercel", () => {
vi.stubEnv("VERCEL_ENV", "preview");
+ const context = new ContextContainer();
+ context.set(ConversationIdKey, "caller-conversation");
- expect(agentTraceIdentityAttributes(input)).toEqual({
- "agent.trace.schema.version": 4,
- "gen_ai.conversation.id": "conversation-1",
- "vercel.session_id": "session-1",
+ contextStorage.run(context, () => {
+ expect(agentTraceIdentityAttributes(input)).toEqual({
+ "agent.run.id": "session-1",
+ "agent.trace.schema.version": 4,
+ "gen_ai.conversation.id": "caller-conversation",
+ "vercel.session_id": "root-session",
+ });
});
});
});
diff --git a/packages/eve/src/tracing/agent-otel-attributes.ts b/packages/eve/src/tracing/agent-otel-attributes.ts
index 8444862f1..bd2086bac 100644
--- a/packages/eve/src/tracing/agent-otel-attributes.ts
+++ b/packages/eve/src/tracing/agent-otel-attributes.ts
@@ -5,11 +5,14 @@ export function agentTraceIdentityAttributes(input: {
readonly rootSessionId: string;
readonly sessionId: string;
}): Record<string, string | number> {
- return {
+ const conversationId = resolveConversationId(input.rootSessionId);
+ const attributes: Record<string, string | number> = {
+ "agent.run.id": input.sessionId,
"agent.trace.schema.version": AGENT_TRACE_SCHEMA_VERSION,
- "gen_ai.conversation.id": resolveConversationId(input.rootSessionId),
- ...(process.env.VERCEL_ENV === undefined
- ? undefined
- : { "vercel.session_id": input.sessionId }),
+ "gen_ai.conversation.id": conversationId,
};
+ if (process.env.VERCEL_ENV !== undefined) {
+ attributes["vercel.session_id"] = input.rootSessionId;
+ }
+ return attributes;
}
diff --git a/packages/eve/src/tracing/agent-otel-provider.test.ts b/packages/eve/src/tracing/agent-otel-provider.test.ts
index 57a1a6f1c..7b0a5c27f 100644
--- a/packages/eve/src/tracing/agent-otel-provider.test.ts
+++ b/packages/eve/src/tracing/agent-otel-provider.test.ts
@@ -751,15 +751,16 @@ describe("createAgentOtelInstrumentation", () => {
},
]);
expect(invocation.attributes).toMatchObject({
+ "agent.parent_call.id": "call-child",
+ "agent.parent_run.id": "parent-session",
"agent.principal.current.id": "user-123",
"agent.principal.current.type": "user",
"agent.principal.initiator.type": "none",
+ "agent.run.id": "child-session",
"gen_ai.conversation.id": "root-session",
"gen_ai.operation.name": "invoke_agent",
});
expect(invocation.attributes).not.toHaveProperty("agent.principal.initiator.id");
- expect(invocation.attributes).not.toHaveProperty("agent.parent_call.id");
- expect(invocation.attributes).not.toHaveProperty("agent.parent_run.id");
expect(invocation.attributes).not.toHaveProperty("agent.root_run.id");
expect(invocation.attributes).not.toHaveProperty("agent.session.id");
expect(invocation.attributes).not.toHaveProperty("vercel.session_id");
@@ -3066,9 +3067,10 @@ describe("createAgentOtelInstrumentation", () => {
},
]);
expect(childTurn.attributes["agent.subagent.name"]).toBe("researcher");
+ expect(childTurn.attributes["agent.parent_call.id"]).toBe("call-1");
+ expect(childTurn.attributes["agent.parent_run.id"]).toBe("session-1");
+ expect(childTurn.attributes["agent.run.id"]).toBe("child-1");
expect(childTurn.attributes["gen_ai.conversation.id"]).toBe("session-1");
- expect(childTurn.attributes).not.toHaveProperty("agent.parent_call.id");
- expect(childTurn.attributes).not.toHaveProperty("agent.parent_run.id");
expect(childTurn.attributes).not.toHaveProperty("agent.root_run.id");
expect(childTurn.attributes).not.toHaveProperty("agent.session.id");
expect(childTurn.attributes).not.toHaveProperty("vercel.session_id");
@@ -3120,6 +3122,7 @@ describe("createAgentOtelInstrumentation", () => {
const turn = byName(runtime.exporter.getFinishedSpans(), "invoke_agent weather")[0]!;
expect(byName(runtime.exporter.getFinishedSpans(), "agent.session")).toHaveLength(0);
expect(turn.attributes).toMatchObject({
+ "agent.run.id": "child-1",
"gen_ai.conversation.id": "session-1",
});
expect(turn.attributes).not.toHaveProperty("agent.session.id");
diff --git a/packages/eve/src/tracing/agent-otel-runtime-context.ts b/packages/eve/src/tracing/agent-otel-runtime-context.ts
index e654247b3..d73b56778 100644
--- a/packages/eve/src/tracing/agent-otel-runtime-context.ts
+++ b/packages/eve/src/tracing/agent-otel-runtime-context.ts
@@ -23,6 +23,8 @@ export function agentActivationAttributes(input: {
"agent.channel.kind": input.turn.channelDelivery?.channelKind,
"agent.channel.name": input.turn.channelDelivery?.channelName,
"agent.channel.request.id": input.turn.channelDelivery?.requestId,
+ "agent.parent_call.id": input.turn.parentLineage?.callId,
+ "agent.parent_run.id": input.turn.parentLineage?.sessionId,
"agent.subagent.name": input.turn.subagentName,
"agent.turn.id": input.turnId,
"agent.turn.sequence": input.turn.sequence,
diff --git a/packages/eve/src/tracing/agent-telemetry-contract.integration.test.ts b/packages/eve/src/tracing/agent-telemetry-contract.integration.test.ts
index 139e3d73e..e64480ad8 100644
--- a/packages/eve/src/tracing/agent-telemetry-contract.integration.test.ts
+++ b/packages/eve/src/tracing/agent-telemetry-contract.integration.test.ts
@@ -589,12 +589,7 @@ describe("exported agent telemetry contract", () => {
expect(span.attributes["operation.name"]).toBe(
span.attributes["gen_ai.operation.name"] ?? span.name,
);
- for (const legacy of [
- "agent.parent_call.id",
- "agent.parent_run.id",
- "agent.root_run.id",
- "agent.session.id",
- ]) {
+ for (const legacy of ["agent.root_run.id", "agent.session.id"]) {
expect(span.attributes).not.toHaveProperty(legacy);
}
expect(span.attributes).not.toHaveProperty("vercel.session_id");
@@ -626,6 +621,9 @@ describe("exported agent telemetry contract", () => {
"agent.channel.name": "web",
});
expect(activation.attributes).toMatchObject({
+ "agent.parent_call.id": "nested",
+ "agent.parent_run.id": "parent",
+ "agent.run.id": "child",
"gen_ai.usage.input_tokens": 10,
"gen_ai.usage.output_tokens": 5,
"agent.usage.input_tokens": 10,