Skip to content

Commit adb0053

Browse files
authored
feat(core): tag shell, tool and model-stream spans with session, agent and command (#62806)
1 parent 765d850 commit adb0053

8 files changed

Lines changed: 143 additions & 6 deletions

File tree

‎packages/core/src/session/runner/step.ts‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -76,9 +76,13 @@ export const make = Effect.gen(function* () {
7676
const pendingStartSnapshot = yield* snapshots.capture().pipe(Effect.forkScoped)
7777
const started = yield* Clock.currentTimeMillis
7878
let firstOutputAt: number | undefined
79-
yield* Effect.annotateCurrentSpan({
79+
const modelAttributes = {
8080
"gen_ai.provider.name": input.model.ref.providerID,
8181
"gen_ai.request.model": input.model.ref.id,
82+
}
83+
yield* Effect.annotateCurrentSpan({
84+
...modelAttributes,
85+
"gen_ai.agent.name": input.agent,
8286
...(input.retryAttempt === undefined ? {} : { "opencode.retry.attempt": input.retryAttempt }),
8387
})
8488
const publisher = createLLMEventPublisher(bus, {
@@ -110,7 +114,9 @@ export const make = Effect.gen(function* () {
110114
// Provider and tool fibers retain per-source order without a shared writer queue.
111115
// A local execution starts only after its Tool.Called publication completes.
112116
// Read to the end, not just the finish event, so the next request can reuse this response.
117+
// The span covers only the provider stream, so model time separates from tools, which run in this consumer.
113118
const providerStream = llm.stream(input.prepared.request, input.prepared.options).pipe(
119+
Stream.withSpan("LLM.stream", { attributes: modelAttributes }),
114120
Stream.runForEach((event) =>
115121
Effect.gen(function* () {
116122
if (publisher.record().providerFailed) return

‎packages/core/src/session/subagent-job.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,8 @@ const make: Effect.Effect<Interface, never, Session.Service | Job.Service | Scop
3636
if (info) yield* SubagentCompletion.deliver(sessions, jobs, { ...info, recovery })
3737
}).pipe(
3838
Effect.ensuring(Effect.sync(() => notifications.delete(key))),
39+
// The global context drops the caller's span annotations; delivery is the parent session's work.
40+
Effect.annotateSpans("session.id", recovery.parentSessionID),
3941
Effect.forkIn(scope, { startImmediately: true }),
4042
Effect.setContext(context),
4143
)

‎packages/core/src/shell.ts‎

Lines changed: 34 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,7 @@ export class NotFoundError extends Schema.TaggedError<NotFoundError>()("Shell.No
3232
const EXITED_LIMIT = 25
3333
export const RETENTION = Duration.days(7)
3434
export const DIRECTORY = "shell"
35+
const SPAN_COMMAND_LIMIT = 200
3536

3637
type Info = Shell.Info
3738
type CreateInput = Shell.CreateInput & {
@@ -182,7 +183,7 @@ const layer = () =>
182183
})
183184

184185
const remove = Effect.fn("Shell.remove")(function* (id: Shell.ID) {
185-
yield* require(id)
186+
yield* annotate((yield* require(id)).info)
186187
yield* removeCommand(id)
187188
})
188189

@@ -193,15 +194,22 @@ const layer = () =>
193194
})
194195

195196
const get = Effect.fn("Shell.get")(function* (id: Shell.ID) {
196-
return (yield* require(id)).info
197+
const { info } = yield* require(id)
198+
yield* annotate(info)
199+
return info
197200
})
198201

199202
const wait = Effect.fn("Shell.wait")(function* (id: Shell.ID) {
200-
return yield* Deferred.await((yield* require(id)).done)
203+
const command = yield* require(id)
204+
yield* annotate(command.info)
205+
const info = yield* Deferred.await(command.done)
206+
yield* annotate(info)
207+
return info
201208
})
202209

203210
const timeout = Effect.fn("Shell.timeout")(function* (id: Shell.ID, duration: number) {
204211
const command = yield* require(id)
212+
yield* annotate(command.info)
205213
if (command.info.status !== "running" || !command.timeout) return command.info
206214
yield* command.timeout(duration)
207215
return command.info
@@ -242,11 +250,13 @@ const layer = () =>
242250
})
243251

244252
const result = Effect.fn("Shell.result")(function* (started: Shell.Info) {
253+
yield* annotate(started)
245254
const info = yield* wait(started.id).pipe(
246255
Effect.catchTag("Shell.NotFoundError", () =>
247256
Effect.succeed({ ...started, status: "killed" as const, time: { ...started.time, completed: Date.now() } }),
248257
),
249258
)
259+
yield* annotate(info)
250260
const capture = yield* Effect.gen(function* () {
251261
const limits = Config.latest(yield* config.entries(), "tool_output")
252262
const maxLines = limits?.max_lines ?? ToolOutput.MAX_LINES
@@ -322,6 +332,7 @@ const layer = () =>
322332
metadata: input.metadata ?? {},
323333
time: { started: Date.now() },
324334
}
335+
yield* annotate(info)
325336

326337
// Spawn through the Environment and stream combined output to the file. The handle is scope-bound, so
327338
// the managing fiber keeps its scope open until the command terminates (it awaits `done` at the
@@ -486,6 +497,26 @@ const layer = () =>
486497
}),
487498
)
488499

500+
// Spans carry only the command text, truncated; never env, stdin or output. Shells outlive the turn that started
501+
// them, so the session comes from the shell's own metadata rather than the caller's span annotations.
502+
function annotate(info: Info) {
503+
const sessionID = info.metadata.sessionID
504+
return Effect.annotateCurrentSpan({
505+
"opencode.shell.id": info.id,
506+
"opencode.shell.command": spanCommand(info.command),
507+
...(typeof sessionID === "string" ? { "session.id": sessionID } : {}),
508+
...(info.metadata.background === true ? { "opencode.shell.background": true } : {}),
509+
...(info.status === "running" ? {} : { "opencode.shell.status": info.status }),
510+
...(info.exit === undefined ? {} : { "process.exit.code": info.exit }),
511+
})
512+
}
513+
514+
// Strict OTLP JSON parsers reject a lone surrogate, which a cut through an emoji would leave.
515+
function spanCommand(command: string) {
516+
if (command.length <= SPAN_COMMAND_LIMIT) return command.toWellFormed()
517+
return `${command.slice(0, SPAN_COMMAND_LIMIT).toWellFormed()}…`
518+
}
519+
489520
// Moves past UTF-8 continuation bytes (at most 3) so a byte cut never splits a character.
490521
function charBoundary(bytes: Buffer, offset: number) {
491522
const limit = Math.min(bytes.length, offset + 3)

‎packages/core/src/tool.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -140,6 +140,7 @@ const layer = Layer.effect(
140140
"gen_ai.tool.name": name,
141141
"gen_ai.tool.call.id": context.id,
142142
"session.id": context.sessionID,
143+
"gen_ai.agent.name": context.agent,
143144
})
144145
const execution = yield* execute(tool, input, context).pipe(
145146
Effect.map((value) => ({ value })),

‎packages/core/src/tool/plugin/shell.ts‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -252,6 +252,11 @@ export const Plugin = {
252252

253253
return yield* Deferred.await(settled)
254254
}).pipe(
255+
// Shell spans, including the job that waits for a backgrounded command, name the call that started them.
256+
Effect.annotateSpans({
257+
"gen_ai.tool.call.id": context.id,
258+
...(input.background === true ? { "opencode.shell.background": true } : {}),
259+
}),
255260
Effect.map((output) => toolResult(output, finalTimeout)),
256261
Effect.mapError(
257262
(error) => new ToolFailure({ message: `Unable to execute command: ${input.command}`, error }),

‎packages/core/test/session-runner-recorded.test.ts‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -263,6 +263,7 @@ describe("SessionRunnerLLM recorded", () => {
263263
)
264264
const attempt = turn.find((span) => span.name === "SessionStep.attempt")
265265
expect(Object.fromEntries(attempt?.attributes ?? [])).toMatchObject({
266+
"gen_ai.agent.name": "build",
266267
"gen_ai.provider.name": "openai",
267268
"gen_ai.request.model": "gpt-4o-mini",
268269
"gen_ai.response.finish_reasons": ["stop"],
@@ -271,6 +272,14 @@ describe("SessionRunnerLLM recorded", () => {
271272
"opencode.usage.cost_usd": 0,
272273
})
273274
expect(attempt?.attributes.get("opencode.llm.first_output_ms")).toBeNumber()
275+
// The provider stream has its own span under the attempt, so model time splits from tool time.
276+
const stream = turn.find((span) => span.name === "LLM.stream")
277+
expect(Option.getOrUndefined(stream!.parent)?.spanId).toBe(attempt!.spanId)
278+
expect(Object.fromEntries(stream!.attributes)).toMatchObject({
279+
"gen_ai.provider.name": "openai",
280+
"gen_ai.request.model": "gpt-4o-mini",
281+
})
282+
expect(stream!.status._tag).toBe("Ended")
274283
}).pipe(Effect.withSpan("fixture.request")),
275284
)
276285
})

‎packages/core/test/session-shell.test.ts‎

Lines changed: 44 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
import { describe, expect, setDefaultTimeout } from "bun:test"
22
import fs from "fs/promises"
33
import path from "path"
4-
import { Cause, Context, Deferred, Effect, Exit, Fiber, Layer, Option, Schedule, Stream } from "effect"
4+
import { Cause, Context, Deferred, Effect, Exit, Fiber, Layer, Option, Schedule, Stream, Tracer } from "effect"
55
import { Bus } from "@opencode/core/bus"
66
import { AppNodeBuilder } from "@opencode/core/effect/app-node-builder"
77
import { Location } from "@opencode/core/location"
@@ -75,6 +75,18 @@ const setup = Effect.gen(function* () {
7575
return { tmp, session, created, shell, control, execution }
7676
})
7777

78+
const recordSpans = () => {
79+
const spans: Tracer.NativeSpan[] = []
80+
const tracer = Tracer.make({
81+
span(options) {
82+
const span = new Tracer.NativeSpan(options)
83+
spans.push(span)
84+
return span
85+
},
86+
})
87+
return { spans, tracer }
88+
}
89+
7890
const log = (session: Session.Interface, sessionID: Session.ID, follow = false) =>
7991
session.log({ sessionID, follow }).pipe(Stream.filter((event) => !Bus.isSynced(event)))
8092

@@ -327,6 +339,37 @@ describe("Session.shell", () => {
327339
)
328340
}
329341

342+
it.live("names the session, a truncated command and the exit on shell spans outside any turn", () =>
343+
Effect.gen(function* () {
344+
const { spans, tracer } = recordSpans()
345+
const fixture = yield* setup
346+
// The emoji's two UTF-16 units sit at indexes 199 and 200, across the 200-unit cut.
347+
const command = `exit 3 # ${"x".repeat(190)}😀${"x".repeat(100)}`
348+
const truncated = `exit 3 # ${"x".repeat(190)}\uFFFD…`
349+
yield* fixture.session.shell({ sessionID: fixture.created.id, command }).pipe(Effect.withTracer(tracer))
350+
351+
const create = spans.find((span) => span.name === "Shell.create")
352+
const result = spans.find((span) => span.name === "Shell.result")
353+
const shellID = create?.attributes.get("opencode.shell.id")
354+
expect(shellID).toBeString()
355+
expect(truncated.isWellFormed()).toBe(true)
356+
expect(Object.fromEntries(create?.attributes ?? [])).toEqual({
357+
"opencode.shell.id": shellID,
358+
"opencode.shell.command": truncated,
359+
"session.id": fixture.created.id,
360+
"opencode.shell.background": true,
361+
})
362+
expect(Object.fromEntries(result?.attributes ?? [])).toEqual({
363+
"opencode.shell.id": shellID,
364+
"opencode.shell.command": truncated,
365+
"session.id": fixture.created.id,
366+
"opencode.shell.background": true,
367+
"opencode.shell.status": "exited",
368+
"process.exit.code": 3,
369+
})
370+
}),
371+
)
372+
330373
it.live("admits a spawn failure without waking the model before failing the caller", () =>
331374
Effect.gen(function* () {
332375
const fixture = yield* setup

‎packages/core/test/tool-shell.test.ts‎

Lines changed: 41 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ import { realpathSync, watch } from "node:fs"
33
import os from "os"
44
import path from "path"
55
import { describe, expect } from "bun:test"
6-
import { Cause, Deferred, Duration, Effect, Exit, Fiber, Layer, Queue, Scope, Stream } from "effect"
6+
import { Cause, Deferred, Duration, Effect, Exit, Fiber, Layer, Queue, Scope, Stream, Tracer } from "effect"
77
import { Money } from "@opencode/schema/money"
88
import { AppNodeBuilder } from "@opencode/core/effect/app-node-builder"
99
import { LayerNode } from "@opencode/util/effect/layer-node"
@@ -1503,6 +1503,46 @@ describe("ShellTool", () => {
15031503
{ timeout: 15_000 },
15041504
)
15051505

1506+
it.live("names the tool call and background on the spans of the shell it starts", () =>
1507+
withTempDir((tmp) => {
1508+
reset()
1509+
const spans: Tracer.NativeSpan[] = []
1510+
const tracer = Tracer.make({
1511+
span(options) {
1512+
const span = new Tracer.NativeSpan(options)
1513+
spans.push(span)
1514+
return span
1515+
},
1516+
})
1517+
return withSession(tmp.path, (registry) =>
1518+
Effect.gen(function* () {
1519+
yield* executeTool(registry, call({ command: bodyExitCommand }, "call-traced"))
1520+
yield* executeTool(registry, call({ command: helloCommand, background: true }, "call-traced-background"))
1521+
}),
1522+
).pipe(
1523+
Effect.withTracer(tracer),
1524+
Effect.andThen(
1525+
Effect.sync(() => {
1526+
const attributes = (name: string, callID: string) =>
1527+
spans
1528+
.filter((span) => span.name === name && span.attributes.get("gen_ai.tool.call.id") === callID)
1529+
.map((span) => Object.fromEntries(span.attributes))
1530+
expect(attributes("Shell.create", "call-traced")).toEqual([
1531+
expect.objectContaining({ "session.id": sessionID, "opencode.shell.command": bodyExitCommand }),
1532+
])
1533+
expect(attributes("Shell.create", "call-traced")[0]).not.toHaveProperty("opencode.shell.background")
1534+
expect(attributes("Shell.result", "call-traced")).toEqual([
1535+
expect.objectContaining({ "session.id": sessionID, "process.exit.code": 7 }),
1536+
])
1537+
expect(attributes("Shell.create", "call-traced-background")).toEqual([
1538+
expect.objectContaining({ "session.id": sessionID, "opencode.shell.background": true }),
1539+
])
1540+
}),
1541+
),
1542+
)
1543+
}),
1544+
)
1545+
15061546
it.live("returns the shell id for a background command", () =>
15071547
withTempDir((tmp) => {
15081548
reset()

0 commit comments

Comments
 (0)