@codecaine-ai/agent-kernel-viewer-core 0.0.0-stage → 0.0.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +82 -2
- package/package.json +35 -4
- package/src/api.ts +136 -0
- package/src/build-trace-spans.ts +347 -0
- package/src/catalog-types.ts +597 -0
- package/src/index.ts +69 -0
- package/src/prompt-diff.ts +241 -0
- package/src/trace-builder/containerGrouping.ts +238 -0
- package/src/trace-builder/eventOrder.ts +109 -0
- package/src/trace-builder/model-nodes.ts +450 -0
- package/src/trace-builder/nesting.ts +436 -0
- package/src/trace-builder/pairEvents.ts +162 -0
- package/src/trace-builder/phaseGrouping.ts +120 -0
- package/src/trace-builder/runBucketing.ts +68 -0
- package/src/trace-builder/spanAttributes.ts +919 -0
- package/src/trace-builder/spanFactories.ts +287 -0
- package/src/types.ts +249 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Codecaine AI
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,83 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Agent Kernel
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
- An opinionated system for building **problem-specific agent harnesses** on top of the Pi Agent SDK
|
|
4
|
+
- Designed for high-volume multi-agent systems that do one class of work extremely well
|
|
5
|
+
|
|
6
|
+
## Why this exists
|
|
7
|
+
|
|
8
|
+
- Mass multi-agent systems are the next step for agentic software:
|
|
9
|
+
- Dozens of workers
|
|
10
|
+
- Long pipelines
|
|
11
|
+
- Deep subagent trees
|
|
12
|
+
- At that scale, token spend becomes a commodity resource:
|
|
13
|
+
- Meter it like water.
|
|
14
|
+
- Map where it flows.
|
|
15
|
+
- Find the leaks.
|
|
16
|
+
- Cut or reroute work that does not earn its cost.
|
|
17
|
+
- General tools like Codex and Claude Code are useful execution environments, but they do not give a purpose-built harness deep observability into spawned agents, token budgets, trace lineage, and model effectiveness.
|
|
18
|
+
|
|
19
|
+
- Agent Kernel is opinionated about that layer:
|
|
20
|
+
|
|
21
|
+
- **Extreme observability.**
|
|
22
|
+
- Every prompt, context load, tool call, subagent spawn, and lifecycle event is captured as a durable, explicitly-linked trace.
|
|
23
|
+
- You can answer "where did the tokens go and what did they produce?" without guesswork or timestamp reconstruction.
|
|
24
|
+
- **Extreme control.**
|
|
25
|
+
- Per-kernel and per-agent concurrency, explicit boundaries, scoped run context, abort/stop semantics, and a spawn pipeline you can audit end to end.
|
|
26
|
+
- You decide how many workers run and how they're contained.
|
|
27
|
+
- **Any model, per agent.**
|
|
28
|
+
- Agents are declarative definitions, not hardcoded to one model.
|
|
29
|
+
- Route each agent in a harness to the model that earns its tokens
|
|
30
|
+
|
|
31
|
+
- The kernel stays deliberately neutral about *what problem your harness solves*.
|
|
32
|
+
- Workflow semantics, domain tools, and product rules belong to your harness.
|
|
33
|
+
- The kernel owns the runtime and observability foundation that makes a harness safe to scale — because scaling blindly is how agent projects get quietly expensive.
|
|
34
|
+
|
|
35
|
+
## Packages
|
|
36
|
+
|
|
37
|
+
- This is a platform monorepo while the contracts settle:
|
|
38
|
+
|
|
39
|
+
- `@codecaine-ai/agent-kernel-protocol` — trace/event envelopes, event factories, deterministic event ids, and turn usage
|
|
40
|
+
- `@codecaine-ai/agent-kernel-db` — per-kernel SQLite observability store, schema, kernel manifest, and query helpers
|
|
41
|
+
- `@codecaine-ai/agent-kernel` — `createKernel` runtime, container identity, registry, context assembly, spawn pipeline, in-process emitter, subagents, trace doctor, read API, and transcript recovery
|
|
42
|
+
- `@codecaine-ai/prompt-kit` — prompt document model, canonicalization/hashing, renderers, and editor primitives (sibling repo and Core workspace member)
|
|
43
|
+
- `@codecaine-ai/agent-kernel-viewer-core` — viewer DTOs, read/catalog API paths, trace transforms, and prompt diffing
|
|
44
|
+
- `@codecaine-ai/agent-kernel-viewer-ui` — trace tree and card system, the detail panel and its data-only renderer contract, prompt lab components
|
|
45
|
+
- `@codecaine-ai/agent-kernel-viewer-shell` — mountable trace workspace, the tree/detail viewer, and the shared style system
|
|
46
|
+
|
|
47
|
+
## Building a harness on it
|
|
48
|
+
|
|
49
|
+
- A harness is the problem-specific application layer that makes the kernel good at one task.
|
|
50
|
+
- A host application (the harness) consumes the kernel through a thin adapter.
|
|
51
|
+
- The harness owns workflow sessions, phase semantics, domain tools, app-specific loaders, app DB tables, and custom viewer panels.
|
|
52
|
+
- The kernel owns spawning, context assembly, observability storage, trace reading, and viewer primitives.
|
|
53
|
+
- The identity model behind all of this (containers, sessions, runs, turns, linkage invariants) is documented in [docs/10-system-design/15-identity-model/](docs/10-system-design/15-identity-model/); the overhaul plan that produced it lives in [docs/.drafts/agent-kernel-overhaul.plan.md](docs/.drafts/agent-kernel-overhaul.plan.md).
|
|
54
|
+
|
|
55
|
+
## Setup
|
|
56
|
+
|
|
57
|
+
- Install dependencies with `bun install`.
|
|
58
|
+
|
|
59
|
+
## Validation
|
|
60
|
+
|
|
61
|
+
- Run `bun run test:boundaries`.
|
|
62
|
+
- Run `bun run typecheck`.
|
|
63
|
+
- Run `bun run test`.
|
|
64
|
+
- The boundary check is the important portability gate: platform packages must not import the host application or reference host-app paths.
|
|
65
|
+
- Per-package typechecks exist as `bun run typecheck:<name>` for `protocol`, `db`, `kernel`, `tui`, `core-harness`, `viewer-core`, `viewer-ui`, `viewer-shell`, and `examples`.
|
|
66
|
+
- When changing package boundaries, also sweep manually: `rg -n "@spectre|\.spectre|Spectre|SPECTRE|apps/backend|apps/frontend|checkpoint-slice|SessionStateManager" packages docs` — app-specific names may appear in docs only when explaining adapter boundaries, never in package source.
|
|
67
|
+
- To check a kernel trace database against the linkage/usage invariants, run the trace doctor: `bun run packages/kernel/src/doctor-cli.ts <db-path>`. Without an argument it defaults to `.agent-kernel/trace.db` under the current directory; non-zero exit means violations.
|
|
68
|
+
|
|
69
|
+
## Running this repo's kernel
|
|
70
|
+
|
|
71
|
+
- This repo is itself a kernel; its service leg is the core harness: `bun run core-harness` serves health, the kernel read API, catalog routes, and prompt-edit sessions on `http://127.0.0.1:4860`.
|
|
72
|
+
- The terminal harness (`/kernel` inside pi) is [`packages/tui`](packages/tui/README.md) — setup, usage, and troubleshooting live in its README.
|
|
73
|
+
- To fold marked TUI sessions into the owning kernel's `trace.db`, run `bunx agent-kernel-tui-ingest` (batch, idempotent).
|
|
74
|
+
- To register a kernel with the Observatory, run `bun run registry:check` / `bun run registry:sync` in the observatory repo (Core's doctor warns on drift).
|
|
75
|
+
|
|
76
|
+
## Examples
|
|
77
|
+
|
|
78
|
+
- The Prompt Kit kernel host has moved to the sibling Prompt Kit repo at `../prompt-kit/packages/prompt-kit-agent`; from `../prompt-kit`, start it with `bun run dev:agent`.
|
|
79
|
+
- `examples/simple-research-kernel` is a runnable standalone Simple Research Kernel — run instructions in [its README](examples/simple-research-kernel/README.md).
|
|
80
|
+
- The example defines agents in a catalog (folder-form bundles: `agent.json` + `prompt/` + `context/` + `tools/`), loads context sidecars, spawns scout subagents, waits for their reports, reviews gaps, queues a report writer, writes working memory, persists kernel observability rows, and renders traces through the viewer shell.
|
|
81
|
+
- Start it with `bun run dev:simple-research` — SQLite only, no service processes.
|
|
82
|
+
- It runs against a single local SQLite file (`examples/simple-research-kernel/.agent-kernel/trace.db`, WAL mode) created on boot, alongside a local kernel manifest (`.agent-kernel/kernel.json`).
|
|
83
|
+
- The launcher starts the API on `http://127.0.0.1:8788` and the viewer on `http://127.0.0.1:5174`.
|
package/package.json
CHANGED
|
@@ -1,6 +1,37 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@codecaine-ai/agent-kernel-viewer-core",
|
|
3
|
-
"version": "0.0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.0.2",
|
|
4
|
+
"license": "MIT",
|
|
5
|
+
"repository": {
|
|
6
|
+
"type": "git",
|
|
7
|
+
"url": "git+https://github.com/Codecaine-AI/agent-kernel.git",
|
|
8
|
+
"directory": "packages/viewer-core"
|
|
9
|
+
},
|
|
10
|
+
"type": "module",
|
|
11
|
+
"main": "src/index.ts",
|
|
12
|
+
"types": "src/index.ts",
|
|
13
|
+
"exports": {
|
|
14
|
+
".": "./src/index.ts"
|
|
15
|
+
},
|
|
16
|
+
"dependencies": {
|
|
17
|
+
"@codecaine-ai/agent-kernel-protocol": "^0.0.2",
|
|
18
|
+
"@codecaine-ai/prompt-kit": "^0.0.2",
|
|
19
|
+
"@evilmartians/agent-prism-types": "^0.0.9",
|
|
20
|
+
"@tanstack/react-query": "^5.99.0"
|
|
21
|
+
},
|
|
22
|
+
"devDependencies": {
|
|
23
|
+
"@types/bun": "latest"
|
|
24
|
+
},
|
|
25
|
+
"files": [
|
|
26
|
+
"src",
|
|
27
|
+
"!src/**/*.test.ts",
|
|
28
|
+
"!src/**/*.test.tsx",
|
|
29
|
+
"!src/**/__tests__",
|
|
30
|
+
"!src/**/__fixtures__",
|
|
31
|
+
"!src/**/__snapshots__",
|
|
32
|
+
"README.md"
|
|
33
|
+
],
|
|
34
|
+
"publishConfig": {
|
|
35
|
+
"access": "public"
|
|
36
|
+
}
|
|
37
|
+
}
|
package/src/api.ts
ADDED
|
@@ -0,0 +1,136 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Routes owned by the kernel trace read API (see
|
|
3
|
+
* packages/kernel/src/read-api.ts). Trace sessions are container-backed —
|
|
4
|
+
* the detail route serves the container trace for a container of kind
|
|
5
|
+
* "session"; the container route is the primary read.
|
|
6
|
+
*/
|
|
7
|
+
export const KERNEL_TRACE_READ_PATHS = {
|
|
8
|
+
listTraceSessions: "/kernel/trace-sessions",
|
|
9
|
+
traceSessionDetail(id: string): string {
|
|
10
|
+
return `/kernel/trace-sessions/${encodeURIComponent(id)}`;
|
|
11
|
+
},
|
|
12
|
+
containerTrace(containerId: string): string {
|
|
13
|
+
return `/kernel/containers/${encodeURIComponent(containerId)}/trace`;
|
|
14
|
+
},
|
|
15
|
+
/** Content-addressed trace blob bytes (hash is "b1-<sha256hex>"). */
|
|
16
|
+
blob(hash: string): string {
|
|
17
|
+
return `/kernel/blobs/${encodeURIComponent(hash)}`;
|
|
18
|
+
},
|
|
19
|
+
/** Per-turn request snapshot context for one agent run. */
|
|
20
|
+
runTurnContext(runId: string, turnNumber: number): string {
|
|
21
|
+
return `/kernel/runs/${encodeURIComponent(runId)}/turns/${turnNumber}/context`;
|
|
22
|
+
},
|
|
23
|
+
} as const;
|
|
24
|
+
|
|
25
|
+
/**
|
|
26
|
+
* Routes owned by the kernel catalog API (Phase 5): registry listing, agent
|
|
27
|
+
* detail (manifest + prompt + validation), prompt writes, revision history,
|
|
28
|
+
* and per-revision run stats. The write route (`PUT .../prompt`) is always
|
|
29
|
+
* mounted and answers 403 unless the kernel allows catalog writes
|
|
30
|
+
* (`allowWrites`, i.e. dev mode); the paths are defined here so browser hosts
|
|
31
|
+
* and the server agree on the URL shape.
|
|
32
|
+
*/
|
|
33
|
+
export const KERNEL_CATALOG_PATHS = {
|
|
34
|
+
listAgents: "/kernel/catalog/agents",
|
|
35
|
+
agentDetail(name: string): string {
|
|
36
|
+
return `/kernel/catalog/agents/${encodeURIComponent(name)}`;
|
|
37
|
+
},
|
|
38
|
+
agentPrompt(name: string): string {
|
|
39
|
+
return `/kernel/catalog/agents/${encodeURIComponent(name)}/prompt`;
|
|
40
|
+
},
|
|
41
|
+
agentManifest(name: string): string {
|
|
42
|
+
return `/kernel/catalog/agents/${encodeURIComponent(name)}/manifest`;
|
|
43
|
+
},
|
|
44
|
+
agentRevisions(name: string): string {
|
|
45
|
+
return `/kernel/catalog/agents/${encodeURIComponent(name)}/revisions`;
|
|
46
|
+
},
|
|
47
|
+
revisionDocument(name: string, hash: string): string {
|
|
48
|
+
return `/kernel/catalog/agents/${encodeURIComponent(name)}/revisions/${encodeURIComponent(hash)}/document`;
|
|
49
|
+
},
|
|
50
|
+
revisionStats(name: string, hash: string): string {
|
|
51
|
+
return `/kernel/catalog/agents/${encodeURIComponent(name)}/revisions/${encodeURIComponent(hash)}/stats`;
|
|
52
|
+
},
|
|
53
|
+
/** Rendered state document for one named fixture (the lab's State view). */
|
|
54
|
+
agentFixtureStatePreview(name: string, fixtureId: string): string {
|
|
55
|
+
return `/kernel/catalog/agents/${encodeURIComponent(name)}/fixtures/${encodeURIComponent(fixtureId)}/state-preview`;
|
|
56
|
+
},
|
|
57
|
+
// -- Annotation sidecar routes (kernel catalog-annotations-api.ts). GET
|
|
58
|
+
// lists, POST adds; the :id mutations follow the 409 + { currentHash }
|
|
59
|
+
// optimistic-concurrency idiom via expectedHash in the body.
|
|
60
|
+
agentAnnotations(name: string): string {
|
|
61
|
+
return `/kernel/catalog/agents/${encodeURIComponent(name)}/annotations`;
|
|
62
|
+
},
|
|
63
|
+
agentAnnotation(name: string, annotationId: string): string {
|
|
64
|
+
return `/kernel/catalog/agents/${encodeURIComponent(name)}/annotations/${encodeURIComponent(annotationId)}`;
|
|
65
|
+
},
|
|
66
|
+
agentAnnotationReplies(name: string, annotationId: string): string {
|
|
67
|
+
return `/kernel/catalog/agents/${encodeURIComponent(name)}/annotations/${encodeURIComponent(annotationId)}/replies`;
|
|
68
|
+
},
|
|
69
|
+
agentAnnotationResolve(name: string, annotationId: string): string {
|
|
70
|
+
return `/kernel/catalog/agents/${encodeURIComponent(name)}/annotations/${encodeURIComponent(annotationId)}/resolve`;
|
|
71
|
+
},
|
|
72
|
+
agentAnnotationAgentRun(name: string, annotationId: string): string {
|
|
73
|
+
return `/kernel/catalog/agents/${encodeURIComponent(name)}/annotations/${encodeURIComponent(annotationId)}/agent-run`;
|
|
74
|
+
},
|
|
75
|
+
agentAnnotationsPrune(name: string): string {
|
|
76
|
+
return `/kernel/catalog/agents/${encodeURIComponent(name)}/annotations/prune`;
|
|
77
|
+
},
|
|
78
|
+
/** Creates a prompt-edit session for the agent (201 { state }). */
|
|
79
|
+
agentEditSessions(name: string): string {
|
|
80
|
+
return `/kernel/catalog/agents/${encodeURIComponent(name)}/edit-sessions`;
|
|
81
|
+
},
|
|
82
|
+
} as const;
|
|
83
|
+
|
|
84
|
+
/**
|
|
85
|
+
* Routes owned by the kernel prompt-edit session API (Phase 2 review loop —
|
|
86
|
+
* see packages/kernel/src/prompt-edit-session-api.ts). Session creation lives
|
|
87
|
+
* under the catalog agent (KERNEL_CATALOG_PATHS.agentEditSessions); everything
|
|
88
|
+
* after creation is keyed by session id here.
|
|
89
|
+
*/
|
|
90
|
+
export const KERNEL_PROMPT_EDIT_SESSION_PATHS = {
|
|
91
|
+
list: "/kernel/prompt-edit-sessions",
|
|
92
|
+
session(sessionId: string): string {
|
|
93
|
+
return `/kernel/prompt-edit-sessions/${encodeURIComponent(sessionId)}`;
|
|
94
|
+
},
|
|
95
|
+
/** SSE stream: `session-state` hello, then every service stream event. */
|
|
96
|
+
events(sessionId: string): string {
|
|
97
|
+
return `/kernel/prompt-edit-sessions/${encodeURIComponent(sessionId)}/events`;
|
|
98
|
+
},
|
|
99
|
+
/** POST: add a human request mid-session. */
|
|
100
|
+
requests(sessionId: string): string {
|
|
101
|
+
return `/kernel/prompt-edit-sessions/${encodeURIComponent(sessionId)}/requests`;
|
|
102
|
+
},
|
|
103
|
+
accept(sessionId: string, alias: string): string {
|
|
104
|
+
return `/kernel/prompt-edit-sessions/${encodeURIComponent(sessionId)}/requests/${encodeURIComponent(alias)}/accept`;
|
|
105
|
+
},
|
|
106
|
+
reject(sessionId: string, alias: string): string {
|
|
107
|
+
return `/kernel/prompt-edit-sessions/${encodeURIComponent(sessionId)}/requests/${encodeURIComponent(alias)}/reject`;
|
|
108
|
+
},
|
|
109
|
+
undo(sessionId: string, alias: string): string {
|
|
110
|
+
return `/kernel/prompt-edit-sessions/${encodeURIComponent(sessionId)}/requests/${encodeURIComponent(alias)}/undo`;
|
|
111
|
+
},
|
|
112
|
+
replies(sessionId: string, alias: string): string {
|
|
113
|
+
return `/kernel/prompt-edit-sessions/${encodeURIComponent(sessionId)}/requests/${encodeURIComponent(alias)}/replies`;
|
|
114
|
+
},
|
|
115
|
+
} as const;
|
|
116
|
+
|
|
117
|
+
/**
|
|
118
|
+
* Cross-kernel observer routes (a viewer plane over many kernel manifests).
|
|
119
|
+
* Container-first; the tailer-daemon routes are gone with D75 (transcript
|
|
120
|
+
* recovery is a backfill tool, not a service).
|
|
121
|
+
*/
|
|
122
|
+
export const KERNEL_OBSERVER_READ_PATHS = {
|
|
123
|
+
listKernels: "/kernels",
|
|
124
|
+
kernel(kernelId: string): string {
|
|
125
|
+
return `/kernels/${encodeURIComponent(kernelId)}`;
|
|
126
|
+
},
|
|
127
|
+
kernelContainers(kernelId: string): string {
|
|
128
|
+
return `/kernels/${encodeURIComponent(kernelId)}/containers`;
|
|
129
|
+
},
|
|
130
|
+
container(containerId: string): string {
|
|
131
|
+
return `/containers/${encodeURIComponent(containerId)}`;
|
|
132
|
+
},
|
|
133
|
+
containerTrace(containerId: string): string {
|
|
134
|
+
return `/containers/${encodeURIComponent(containerId)}/trace`;
|
|
135
|
+
},
|
|
136
|
+
} as const;
|
|
@@ -0,0 +1,347 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* buildTraceSpans.ts — Orchestrator that turns raw TraceEvents + PI session +
|
|
3
|
+
* AgentRun rows into a TraceSpan tree for trace-viewer TreeView.
|
|
4
|
+
*
|
|
5
|
+
* Pipeline (each stage lives in ./trace-builder/):
|
|
6
|
+
* pairEvents → fold start/end pairs into PairedEvent
|
|
7
|
+
* toEventSpans → PairedEvent → TraceSpan, bucketed per PI session
|
|
8
|
+
* nestPiSpans → context inputs → provisioning → per-turn grouping →
|
|
9
|
+
* nested tools under their parent tool span
|
|
10
|
+
* wrapSpansInRuns → drop each PI bucket's spans into agent_run wrappers
|
|
11
|
+
* buildAgentForest → PI spans hosted under their spawner's tool_call;
|
|
12
|
+
* call/decision sessions become node rows
|
|
13
|
+
* foldGateChildren → gate checks (steps, decisions) under their gate
|
|
14
|
+
* attachRunScopedSpans → node rows, steps and gates under their parent run
|
|
15
|
+
* collectContainerRanges → container events + summaries → ContainerRange map
|
|
16
|
+
* groupRoots → hoist roots under phase and/or container spans
|
|
17
|
+
*
|
|
18
|
+
* Debug: set localStorage.TRACE_BUILDER_DEBUG='1' to log stage-by-stage
|
|
19
|
+
* counts (paired events, pi buckets, runs matched vs orphaned, roots, phases).
|
|
20
|
+
*/
|
|
21
|
+
|
|
22
|
+
import type { TraceSpan } from "@evilmartians/agent-prism-types";
|
|
23
|
+
|
|
24
|
+
import { EventType, type AgentRun, type KernelContainerSummary, type TraceEvent } from "./types";
|
|
25
|
+
import type { PiAgentSession } from "./types";
|
|
26
|
+
|
|
27
|
+
import { sortByEmissionOrder } from "./trace-builder/eventOrder";
|
|
28
|
+
import { pairEvents, type PairedEvent } from "./trace-builder/pairEvents";
|
|
29
|
+
import { toAgentSpan, toEventSpan, toRunSpan } from "./trace-builder/spanFactories";
|
|
30
|
+
import { bucketSpansByRun, sortRunsByStart } from "./trace-builder/runBucketing";
|
|
31
|
+
import {
|
|
32
|
+
findToolCallSpanByToolUseId,
|
|
33
|
+
groupContextInputsByBuild,
|
|
34
|
+
groupProvisioningSpans,
|
|
35
|
+
groupSpansByTurn,
|
|
36
|
+
groupSpansByUserMessage,
|
|
37
|
+
} from "./trace-builder/nesting";
|
|
38
|
+
import {
|
|
39
|
+
attachRunScopedSpans,
|
|
40
|
+
foldGateChildren,
|
|
41
|
+
isNodeSession,
|
|
42
|
+
nestToolSpans,
|
|
43
|
+
NODE_LIFECYCLE_EVENT_TYPES,
|
|
44
|
+
toNodeSpans,
|
|
45
|
+
} from "./trace-builder/model-nodes";
|
|
46
|
+
import { extractPhaseSpans, groupAgentsByPhase, type PhaseRange } from "./trace-builder/phaseGrouping";
|
|
47
|
+
import {
|
|
48
|
+
containerSummariesToRanges,
|
|
49
|
+
extractContainerSpans,
|
|
50
|
+
groupAgentsByContainer,
|
|
51
|
+
type ContainerRange,
|
|
52
|
+
} from "./trace-builder/containerGrouping";
|
|
53
|
+
|
|
54
|
+
/** Rendered as phase/container grouping spans, never as event spans. */
|
|
55
|
+
const STRUCTURAL_EVENT_TYPES = new Set<string>([
|
|
56
|
+
EventType.PHASE_START,
|
|
57
|
+
EventType.PHASE_END,
|
|
58
|
+
EventType.CONTAINER_START,
|
|
59
|
+
EventType.CONTAINER_END,
|
|
60
|
+
]);
|
|
61
|
+
|
|
62
|
+
function debugEnabled(): boolean {
|
|
63
|
+
if (typeof window === "undefined") return false;
|
|
64
|
+
try {
|
|
65
|
+
return window.localStorage?.getItem("TRACE_BUILDER_DEBUG") === "1";
|
|
66
|
+
} catch {
|
|
67
|
+
return false;
|
|
68
|
+
}
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
function debugLog(label: string, payload: Record<string, unknown>): void {
|
|
72
|
+
if (!debugEnabled()) return;
|
|
73
|
+
console.log(`[trace-builder] ${label}`, payload);
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
/**
|
|
77
|
+
* Side tables the nesting/bucketing stages need about each event span,
|
|
78
|
+
* keyed by span id (nesting stages receive bare TraceSpans).
|
|
79
|
+
*/
|
|
80
|
+
interface EventSpanIndex {
|
|
81
|
+
/** span id → source event type. */
|
|
82
|
+
typeById: Map<string, string>;
|
|
83
|
+
/** span id → protocol spanId (spawn/run lifecycle correlation). */
|
|
84
|
+
protocolSpanIdById: Map<string, string>;
|
|
85
|
+
/** span id → envelope runId; explicit run linkage stamped at emit time,
|
|
86
|
+
* preferred over timestamp reconstruction wherever the emitter set it. */
|
|
87
|
+
runIdBySpanId: Map<string, string>;
|
|
88
|
+
/** span id → source events, for the model-node lifecycle spans node rows absorb. */
|
|
89
|
+
pairedBySpanId: Map<string, PairedEvent>;
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
interface EventSpanBuckets {
|
|
93
|
+
/** Event spans per PI session, sorted by startTime. */
|
|
94
|
+
spansByPi: Map<string, TraceSpan[]>;
|
|
95
|
+
/** Event spans with no piSessionId (app-level seed events). */
|
|
96
|
+
orphanSpans: TraceSpan[];
|
|
97
|
+
index: EventSpanIndex;
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
/** Stage: PairedEvent → TraceSpan, bucketed by piSessionId (structural events skipped). */
|
|
101
|
+
function toEventSpans(paired: PairedEvent[]): EventSpanBuckets {
|
|
102
|
+
const spansByPi = new Map<string, TraceSpan[]>();
|
|
103
|
+
const orphanSpans: TraceSpan[] = [];
|
|
104
|
+
const index: EventSpanIndex = {
|
|
105
|
+
typeById: new Map(),
|
|
106
|
+
protocolSpanIdById: new Map(),
|
|
107
|
+
runIdBySpanId: new Map(),
|
|
108
|
+
pairedBySpanId: new Map(),
|
|
109
|
+
};
|
|
110
|
+
|
|
111
|
+
for (const p of paired) {
|
|
112
|
+
const sourceEvent = p.kind === "pair" ? p.start : p.event;
|
|
113
|
+
if (STRUCTURAL_EVENT_TYPES.has(sourceEvent.type)) continue;
|
|
114
|
+
|
|
115
|
+
const span = toEventSpan(p);
|
|
116
|
+
index.typeById.set(span.id, sourceEvent.type);
|
|
117
|
+
if (sourceEvent.spanId) index.protocolSpanIdById.set(span.id, sourceEvent.spanId);
|
|
118
|
+
if (sourceEvent.runId) index.runIdBySpanId.set(span.id, sourceEvent.runId);
|
|
119
|
+
if (NODE_LIFECYCLE_EVENT_TYPES.has(sourceEvent.type)) index.pairedBySpanId.set(span.id, p);
|
|
120
|
+
|
|
121
|
+
if (!sourceEvent.piSessionId) {
|
|
122
|
+
orphanSpans.push(span);
|
|
123
|
+
continue;
|
|
124
|
+
}
|
|
125
|
+
const list = spansByPi.get(sourceEvent.piSessionId);
|
|
126
|
+
if (list) list.push(span);
|
|
127
|
+
else spansByPi.set(sourceEvent.piSessionId, [span]);
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
for (const list of spansByPi.values()) {
|
|
131
|
+
list.sort((a, b) => a.startTime.getTime() - b.startTime.getTime());
|
|
132
|
+
}
|
|
133
|
+
|
|
134
|
+
return { spansByPi, orphanSpans, index };
|
|
135
|
+
}
|
|
136
|
+
|
|
137
|
+
/** Stage: nest each PI bucket — context inputs under their build, provisioning wrapper, tools under their turn, one block per user turn, nested tools under their parent tool. */
|
|
138
|
+
function nestPiSpans(spansByPi: Map<string, TraceSpan[]>, index: EventSpanIndex): void {
|
|
139
|
+
for (const [piId, list] of spansByPi.entries()) {
|
|
140
|
+
const contextGrouped = groupContextInputsByBuild(list, index.typeById, index.protocolSpanIdById);
|
|
141
|
+
const provisioningGrouped = groupProvisioningSpans(
|
|
142
|
+
contextGrouped,
|
|
143
|
+
index.typeById,
|
|
144
|
+
index.protocolSpanIdById,
|
|
145
|
+
);
|
|
146
|
+
// Turn ownership first (tools/replies fold under their Turn N span),
|
|
147
|
+
// then the user-message fold wraps whole turns under the prompt that
|
|
148
|
+
// started them. Traces without snapshot spans skip the turn stage.
|
|
149
|
+
const turnGrouped = groupSpansByTurn(
|
|
150
|
+
provisioningGrouped,
|
|
151
|
+
index.typeById,
|
|
152
|
+
index.runIdBySpanId,
|
|
153
|
+
);
|
|
154
|
+
const userGrouped = groupSpansByUserMessage(turnGrouped, index.typeById);
|
|
155
|
+
spansByPi.set(piId, nestToolSpans(userGrouped, index.typeById));
|
|
156
|
+
}
|
|
157
|
+
}
|
|
158
|
+
|
|
159
|
+
/** Stage: wrap one PI session's spans into Run #n containers (skipped for single-run sessions). */
|
|
160
|
+
function wrapSpansInRuns(
|
|
161
|
+
piId: string,
|
|
162
|
+
children: TraceSpan[],
|
|
163
|
+
runsByPi: Map<string, AgentRun[]>,
|
|
164
|
+
runIdBySpanId: Map<string, string>,
|
|
165
|
+
): TraceSpan[] {
|
|
166
|
+
const runs = runsByPi.get(piId);
|
|
167
|
+
if (!runs || runs.length === 0) return children;
|
|
168
|
+
// CP3: single-run pi sessions (kickoff path) skip the Run wrapper — distinct sibling agents render at their own level instead of nested under Run #1.
|
|
169
|
+
if (runs.length === 1) {
|
|
170
|
+
debugLog("wrapSpansInRuns", { piId, runCount: 1, skipped: true });
|
|
171
|
+
return children;
|
|
172
|
+
}
|
|
173
|
+
const { runBuckets, orphans } = bucketSpansByRun(children, runs, runIdBySpanId);
|
|
174
|
+
const sorted = sortRunsByStart(runs);
|
|
175
|
+
const wrapped = sorted.map((r, index) =>
|
|
176
|
+
toRunSpan(r, runBuckets.get(r.id) ?? [], index + 1),
|
|
177
|
+
);
|
|
178
|
+
debugLog("wrapSpansInRuns", {
|
|
179
|
+
piId,
|
|
180
|
+
runCount: sorted.length,
|
|
181
|
+
skipped: false,
|
|
182
|
+
wrappedSizes: wrapped.map((w) => w.children?.length ?? 0),
|
|
183
|
+
intraPiOrphans: orphans.length,
|
|
184
|
+
});
|
|
185
|
+
return [...wrapped, ...orphans];
|
|
186
|
+
}
|
|
187
|
+
|
|
188
|
+
/**
|
|
189
|
+
* Stage: PI sessions → agent spans; sub-agents nest under their spawner's
|
|
190
|
+
* tool_call span (parentSessionId + parentToolUseId), the rest are roots.
|
|
191
|
+
* Call/decision sessions become node rows (roots here; attachRunScopedSpans
|
|
192
|
+
* places them under their parent run).
|
|
193
|
+
*/
|
|
194
|
+
function buildAgentForest(
|
|
195
|
+
piSessions: PiAgentSession[],
|
|
196
|
+
agentRuns: AgentRun[],
|
|
197
|
+
buckets: EventSpanBuckets,
|
|
198
|
+
): TraceSpan[] {
|
|
199
|
+
const runsByPi = new Map<string, AgentRun[]>();
|
|
200
|
+
for (const r of agentRuns) {
|
|
201
|
+
const list = runsByPi.get(r.piSessionId);
|
|
202
|
+
if (list) list.push(r);
|
|
203
|
+
else runsByPi.set(r.piSessionId, [r]);
|
|
204
|
+
}
|
|
205
|
+
|
|
206
|
+
const firstRunByPi = new Map<string, AgentRun>();
|
|
207
|
+
for (const [piId, runs] of runsByPi.entries()) {
|
|
208
|
+
const first = sortRunsByStart(runs)[0] ?? null;
|
|
209
|
+
if (first) firstRunByPi.set(piId, first);
|
|
210
|
+
}
|
|
211
|
+
|
|
212
|
+
debugLog("bucketing", {
|
|
213
|
+
piBuckets: Array.from(buckets.spansByPi.entries()).map(([piId, spans]) => ({
|
|
214
|
+
piId,
|
|
215
|
+
spans: spans.length,
|
|
216
|
+
runs: runsByPi.get(piId)?.length ?? 0,
|
|
217
|
+
})),
|
|
218
|
+
orphanSpans: buckets.orphanSpans.length,
|
|
219
|
+
});
|
|
220
|
+
|
|
221
|
+
const agentSpansById = new Map<string, TraceSpan>();
|
|
222
|
+
const nodeRows: TraceSpan[] = [];
|
|
223
|
+
for (const pi of piSessions) {
|
|
224
|
+
if (isNodeSession(pi)) {
|
|
225
|
+
const runs = runsByPi.get(pi.id) ?? [];
|
|
226
|
+
const spans = buckets.spansByPi.get(pi.id) ?? [];
|
|
227
|
+
nodeRows.push(...toNodeSpans(pi, runs, spans, buckets.index));
|
|
228
|
+
continue;
|
|
229
|
+
}
|
|
230
|
+
const children = wrapSpansInRuns(
|
|
231
|
+
pi.id,
|
|
232
|
+
buckets.spansByPi.get(pi.id) ?? [],
|
|
233
|
+
runsByPi,
|
|
234
|
+
buckets.index.runIdBySpanId,
|
|
235
|
+
);
|
|
236
|
+
agentSpansById.set(pi.id, toAgentSpan(pi, children));
|
|
237
|
+
}
|
|
238
|
+
|
|
239
|
+
const roots: TraceSpan[] = [];
|
|
240
|
+
for (const pi of piSessions) {
|
|
241
|
+
const span = agentSpansById.get(pi.id);
|
|
242
|
+
if (!span) continue;
|
|
243
|
+
if (pi.parentSessionId && agentSpansById.has(pi.parentSessionId)) {
|
|
244
|
+
const parentSpan = agentSpansById.get(pi.parentSessionId)!;
|
|
245
|
+
// Explicit linkage: the session row carries parent_tool_use_id; the
|
|
246
|
+
// first run's parent_tool_use_id remains as a fallback for older rows.
|
|
247
|
+
const parentToolUseId =
|
|
248
|
+
pi.parentToolUseId ?? firstRunByPi.get(pi.id)?.parentToolUseId ?? null;
|
|
249
|
+
const host = parentToolUseId
|
|
250
|
+
? (findToolCallSpanByToolUseId(parentSpan, parentToolUseId, buckets.index.typeById) ?? parentSpan)
|
|
251
|
+
: parentSpan;
|
|
252
|
+
host.children = host.children ?? [];
|
|
253
|
+
host.children.push(span);
|
|
254
|
+
} else {
|
|
255
|
+
roots.push(span);
|
|
256
|
+
}
|
|
257
|
+
}
|
|
258
|
+
|
|
259
|
+
roots.push(...nodeRows);
|
|
260
|
+
roots.push(...buckets.orphanSpans);
|
|
261
|
+
roots.sort((a, b) => a.startTime.getTime() - b.startTime.getTime());
|
|
262
|
+
return roots;
|
|
263
|
+
}
|
|
264
|
+
|
|
265
|
+
/**
|
|
266
|
+
* Stage: container ranges from container_start/end events, backfilled with
|
|
267
|
+
* persisted container summaries (event-derived start/end/phase win).
|
|
268
|
+
*/
|
|
269
|
+
function collectContainerRanges(
|
|
270
|
+
events: TraceEvent[],
|
|
271
|
+
containers: KernelContainerSummary[],
|
|
272
|
+
): Map<string, ContainerRange> {
|
|
273
|
+
const containerMap = extractContainerSpans(events);
|
|
274
|
+
for (const [id, range] of containerSummariesToRanges(containers)) {
|
|
275
|
+
if (!containerMap.has(id)) {
|
|
276
|
+
containerMap.set(id, range);
|
|
277
|
+
continue;
|
|
278
|
+
}
|
|
279
|
+
const existing = containerMap.get(id)!;
|
|
280
|
+
containerMap.set(id, {
|
|
281
|
+
...range,
|
|
282
|
+
start: existing.start,
|
|
283
|
+
end: existing.end ?? range.end,
|
|
284
|
+
phase: existing.phase ?? range.phase,
|
|
285
|
+
});
|
|
286
|
+
}
|
|
287
|
+
return containerMap;
|
|
288
|
+
}
|
|
289
|
+
|
|
290
|
+
/** Stage: hoist root spans under phase containers, then nest each phase's roots by container. */
|
|
291
|
+
function groupRoots(
|
|
292
|
+
roots: TraceSpan[],
|
|
293
|
+
phaseMap: Map<string, PhaseRange>,
|
|
294
|
+
containerMap: Map<string, ContainerRange>,
|
|
295
|
+
): TraceSpan[] {
|
|
296
|
+
const grouped = phaseMap.size > 0 ? groupAgentsByPhase(roots, phaseMap) : roots;
|
|
297
|
+
if (containerMap.size === 0) return grouped;
|
|
298
|
+
if (phaseMap.size === 0) return groupAgentsByContainer(grouped, containerMap);
|
|
299
|
+
|
|
300
|
+
return grouped.map((span) => {
|
|
301
|
+
if (!span.id.startsWith("phase:")) return span;
|
|
302
|
+
const phaseName = span.id.replace("phase:", "");
|
|
303
|
+
const phaseContainerMap = new Map(
|
|
304
|
+
[...containerMap].filter(([, r]) => r.phase === phaseName || r.phase === null),
|
|
305
|
+
);
|
|
306
|
+
return { ...span, children: groupAgentsByContainer(span.children ?? [], phaseContainerMap) };
|
|
307
|
+
});
|
|
308
|
+
}
|
|
309
|
+
|
|
310
|
+
export function buildTraceSpans(
|
|
311
|
+
rawEvents: TraceEvent[],
|
|
312
|
+
piSessions: PiAgentSession[],
|
|
313
|
+
agentRuns: AgentRun[] = [],
|
|
314
|
+
containers: KernelContainerSummary[] = [],
|
|
315
|
+
): TraceSpan[] {
|
|
316
|
+
// Canonical emission order first: the API's (timestamp, eventId) ordering
|
|
317
|
+
// breaks same-millisecond ties by arbitrary id, which can put a reply
|
|
318
|
+
// before the request snapshot that produced it. Every later sort is a
|
|
319
|
+
// stable startTime sort, so this order survives the pipeline for ties.
|
|
320
|
+
const events = sortByEmissionOrder(rawEvents);
|
|
321
|
+
|
|
322
|
+
debugLog("inputs", {
|
|
323
|
+
events: events.length,
|
|
324
|
+
piSessions: piSessions.length,
|
|
325
|
+
agentRuns: agentRuns.length,
|
|
326
|
+
containers: containers.length,
|
|
327
|
+
eventsWithNullPi: events.reduce((n, e) => n + (e.piSessionId ? 0 : 1), 0),
|
|
328
|
+
});
|
|
329
|
+
|
|
330
|
+
const buckets = toEventSpans(pairEvents(events));
|
|
331
|
+
nestPiSpans(buckets.spansByPi, buckets.index);
|
|
332
|
+
const forest = buildAgentForest(piSessions, agentRuns, buckets);
|
|
333
|
+
const roots = attachRunScopedSpans(foldGateChildren(forest), agentRuns);
|
|
334
|
+
|
|
335
|
+
const phaseMap = extractPhaseSpans(events);
|
|
336
|
+
const containerMap = collectContainerRanges(events, containers);
|
|
337
|
+
const final = groupRoots(roots, phaseMap, containerMap);
|
|
338
|
+
|
|
339
|
+
debugLog("output", {
|
|
340
|
+
phases: phaseMap.size,
|
|
341
|
+
containers: containerMap.size,
|
|
342
|
+
rootsBeforePhases: roots.length,
|
|
343
|
+
finalTopLevel: final.length,
|
|
344
|
+
});
|
|
345
|
+
|
|
346
|
+
return final;
|
|
347
|
+
}
|