Replay your coding agent sessions as a map and a timeline
Python agent-observabilityai-agentsclaudeclaude-codecodexcoding-agentscursordeveloper-toolsdevtoolsgithub-copilotkirollmobservabilityopencodeprivacypythonsession-replaytypescriptvisualization
import { z } from 'zod';
/**
* Session Explorer API boundary.
*
* The three data endpoints (`status`, `sessions`, `map`) answer in camelCase,
* and the map document itself is `agentplay/v1` (the older
* `entelligence.session-map/v1` name is the same document shape and is
* accepted too), fetched from whatever URL the data source's `map` batch hands back.
*
* The map schema is validated loosely: every object is `passthrough` and
* optional fields default, so a CLI that adds a field never breaks the page.
* Only the `schema` discriminator is strict, because a v2 map is not something
* this renderer can draw.
*/
export const SESSION_MAP_SCHEMA_V1 = 'agentplay/v1';
/** The same v1 document under its original name; readers accept both. */
export const SESSION_MAP_SCHEMA_V1_LEGACY = 'entelligence.session-map/v1';
export const sessionExplorerStatusSchema = z
.object({
success: z.boolean().optional(),
available: z.boolean().catch(false).default(false),
mapCount: z.number().catch(0).default(0),
latestSessionDate: z.string().nullable().catch(null).default(null),
/** the local server is still scanning for sessions, so more may land */
scanning: z.boolean().catch(false).default(false),
})
.passthrough();
export type SessionExplorerStatus = z.infer<typeof sessionExplorerStatusSchema>;
/** Session-list `repos`: a server sends either plain names or
* `{name, remote}` objects reduced from the commit summary. Normalize both
* to the display name `SessionList` renders. */
const sessionRepoNameSchema = z
.union([
z.string(),
z
.object({ name: z.string().optional(), remote: z.string().optional() })
.passthrough(),
])
.transform((repo) =>
(typeof repo === 'string' ? repo : (repo.name ?? repo.remote ?? '')).trim()
)
.catch('');
export const sessionExplorerSessionSchema = z
.object({
sessionId: z.string(),
sessionDate: z.string().nullable().default(null),
startedAt: z.string(),
endedAt: z.string().nullable().default(null),
durationMs: z.number().default(0),
agentTool: z.string().default('claude-code'),
models: z.array(z.string()).default([]),
repos: z
.array(sessionRepoNameSchema)
.default([])
.transform((repos) => repos.filter((r) => r.length > 0)),
calls: z.number().default(0),
requests: z.number().default(0),
subagents: z.number().default(0),
errors: z.number().default(0),
filesTouched: z.number().default(0),
costUsd: z.number().default(0),
tokens: z.number().default(0),
userTurns: z.number().default(0),
sessionTitle: z.string().nullable().default(null),
contentHash: z.string().nullable().default(null),
bytesGz: z.number().nullable().default(null),
updatedAt: z.string().nullable().default(null),
// optional signal summary (render when present)
errorsBySource: z
.record(z.string(), z.number())
.optional()
.catch(undefined),
retries: z.number().optional().catch(undefined),
delays: z.number().optional().catch(undefined),
maxContext: z.number().optional().catch(undefined),
compactions: z.number().optional().catch(undefined),
// All optional: an older server omits them.
role: z.string().nullable().optional().catch(undefined),
parentSessionId: z.string().nullable().optional().catch(undefined),
tasks: z.number().optional().catch(undefined),
outputs: z.record(z.string(), z.number()).optional().catch(undefined),
prs: z
.array(
z
.object({
repo: z.string().optional(),
number: z.number().optional(),
url: z.string().optional(),
state: z.string().optional(),
})
.passthrough()
)
.optional()
.catch(undefined),
// Present when the list was searched and this session matched on what it
// touched (files, commands, MCP servers...), not only on its title.
search: z
.object({
count: z.number().default(0),
seqs: z.array(z.number()).default([]),
chips: z
.array(
z.object({
label: z.string(),
touch: z.string(),
seq: z.number().nullable().default(null),
n: z.number().default(1),
})
)
.default([]),
})
.optional()
.catch(undefined),
})
.passthrough();
export type SessionExplorerSession = z.infer<
typeof sessionExplorerSessionSchema
>;
export const sessionExplorerSessionsSchema = z
.object({
success: z.boolean().optional(),
sessions: z.array(sessionExplorerSessionSchema).default([]),
nextCursor: z.string().nullable().default(null),
hasMore: z.boolean().default(false),
// Set when a search named command arguments, which are never stored, and
// the results are for the command alone.
searchNote: z
.object({ code: z.string(), command: z.string().optional() })
.nullable()
.optional()
.catch(undefined),
})
.passthrough();
export type SessionExplorerSessionsPage = z.infer<
typeof sessionExplorerSessionsSchema
>;
/** One map entry in the batch answer: where to fetch it and its hash. */
export const sessionExplorerMapMetaSchema = z
.object({
sessionId: z.string(),
url: z.string().min(1),
schemaVersion: z.number().default(1),
contentHash: z.string().min(1),
bytesGz: z.number().nullable().default(null),
})
.passthrough();
export type SessionExplorerMapMeta = z.infer<
typeof sessionExplorerMapMetaSchema
>;
/** An id the server has no map for (unknown or removed row). */
export const sessionExplorerMapMissingSchema = z
.object({ sessionId: z.string(), status: z.literal('not_found') })
.passthrough();
/** `map/?session_id=A&session_id=B…` (1-20 ids). */
export const sessionExplorerMapBatchSchema = z
.object({
success: z.boolean().optional(),
expiresIn: z.number().default(300),
maps: z
.array(
z.union([sessionExplorerMapMetaSchema, sessionExplorerMapMissingSchema])
)
.default([]),
})
.passthrough();
export type SessionExplorerMapBatch = z.infer<
typeof sessionExplorerMapBatchSchema
>;
export type SessionExplorerMapItem = SessionExplorerMapBatch['maps'][number];
/** `GET /api/prompt-images`: the images pasted into each user turn. `turn` is
* 1-based over the session's main-agent user events (see `promptImageTurns`). */
export const promptImagesResponseSchema = z
.object({
success: z.boolean().optional(),
turns: z
.array(
z
.object({
turn: z.number().int(),
images: z
.array(
z
.object({
i: z.number().int(),
pasteId: z.number().nullable().catch(null).default(null),
mediaType: z.string().catch('').default(''),
available: z.boolean().catch(false).default(false),
})
.passthrough()
)
.default([]),
})
.passthrough()
)
.default([]),
})
.passthrough();
export type PromptImagesResponse = z.infer<typeof promptImagesResponseSchema>;
/** `GET /api/hook-detail`: what one failed hook said and ran. Free text that
* a map never carries; the server reads it from the transcript on demand. */
export const hookDetailResponseSchema = z
.object({
success: z.boolean().optional(),
message: z.string().nullable().catch(null).default(null),
command: z.string().nullable().catch(null).default(null),
})
.passthrough();
export type HookDetailResponse = z.infer<typeof hookDetailResponseSchema>;
export const isMapFound = (
item: SessionExplorerMapItem
): item is SessionExplorerMapMeta =>
'url' in item && typeof item.url === 'string';
// --- map document ---------------------------------------------------------
const touchSchema = z.enum(['hit', 'read', 'edit']).catch('hit');
/** `targets[].op` / `files[].op`: closed vocabulary, but optional and
* `.catch(undefined)` since most tool events touch no file at all. */
const fileOpSchema = z
.enum(['create', 'modify', 'delete', 'rename-from', 'rename-to'])
.optional()
.catch(undefined);
const targetSchema = z
.object({
file: z.number().optional(),
scope: z.string().optional(),
label: z.string().optional(),
touch: touchSchema,
op: fileOpSchema,
})
.passthrough();
// The CLI writes JSON, where an absent value is `null` (`"name": null`), not a
// missing key. `.optional()` alone rejects null, which took whole blocks down:
// `tasks` is wrapped in `.catch(undefined)`, so one null name silently discarded
// every task in the map and the viewer fell back to "Task 1", "Task 2", ...
const optNum = z.number().nullish();
const optStr = z.string().nullish();
/** `events[].vcs`: a VCS/PR-hosting operation. `action` is an open
* vocabulary (git subcommands, `<noun>_<verb>` for gh/glab) except the three
* closed PR-creation states (`pr_create`, `pr_create_attempt`,
* `pr_create_failed`), so it stays `z.string()` rather than an enum. */
const vcsSchema = z
.object({
provider: z.string(),
action: z.string(),
repo: optStr,
number: optNum,
})
.passthrough()
.optional();
export const sessionMapEventSchema = z
.object({
seq: optNum,
t: z.number().default(0),
kind: z.string(),
agent: z.string().default('main'),
err: z.boolean().default(false),
tool: optStr,
verb: optStr,
targets: z.array(targetSchema).optional(),
// PR creation, tool categories
vcs: vcsSchema,
cat: optStr,
outBytes: optNum,
dur: optNum,
server: optStr,
skill: optStr,
subagentType: optStr,
model: optStr,
child: optStr,
host: optStr,
in: optNum,
cw: optNum,
cr: optNum,
out: optNum,
cost: optNum,
chars: optNum,
// signals: tool/MCP/subagent failures and retries
errClass: optStr,
exitCode: optNum,
retryOf: optNum,
attempt: optNum,
// llm response metadata (never text)
latency: optNum,
stop: optStr,
thinking: z.boolean().optional(),
toolCalls: optNum,
textChars: optNum,
// error events
source: optStr,
hook: optStr,
hookEvent: optStr,
srcUuid: optStr,
retry: z.boolean().optional(),
// delay events
cause: optStr,
ms: optNum,
ref: optNum,
// compaction events
trigger: optStr,
preTokens: optNum,
postTokens: optNum,
// Additive in v1: task number + driving model on
// every event, prompt shape on user turns (counts only, never content),
// and the fields of the output kinds (commit / pr_merge / pr_close /
// pr_comment / ticket / artifact / skill_write / model_switch).
task: optNum,
images: optNum,
urls: optNum,
repo: optStr,
sha: optStr,
files: optNum,
ins: optNum,
del: optNum,
number: optNum,
url: optStr,
tracker: optStr,
action: optStr,
id: optStr,
title: optStr,
bytes: optNum,
version: optNum,
name: optStr,
from: optStr,
to: optStr,
})
.passthrough();
/** `tasks[]`: the CLI's own segmentation (`source: "segments"`) or
* one task per user-turn window (`"turns"`). `startSeq`/`endSeq` are
* inclusive event sequence numbers (seq === index). */
export const sessionMapTaskSchema = z
.object({
n: z.number(),
id: optStr,
name: optStr,
source: optStr,
startSeq: optNum,
endSeq: optNum,
startT: optNum,
endT: optNum,
firstTurn: optNum,
lastTurn: optNum,
})
.passthrough();
export const sessionMapSchema = z
.object({
schema: z.union([
z.literal(SESSION_MAP_SCHEMA_V1),
z.literal(SESSION_MAP_SCHEMA_V1_LEGACY),
]),
session: z
.object({
id: z.string(),
agentTool: z.string().default('claude-code'),
cliVersion: optStr,
startedAt: z.string(),
durationMs: z.number().default(0),
models: z.array(z.string()).default([]),
pathMode: optStr,
truncated: z.boolean().default(false),
// one of pr_created | verified | blocked | interrupted |
// unresolved_errors | completed | incomplete; open string so an
// unrecognized value degrades to its own label instead of failing.
outcome: optStr,
role: z.string().nullable().optional(),
parentSessionId: z.string().nullable().optional(),
})
.passthrough(),
totals: z
.object({
calls: z.number().default(0),
requests: z.number().default(0),
userTurns: z.number().default(0),
subagents: z.number().default(0),
errors: z.number().default(0),
tokens: z.number().default(0),
costUsd: z.number().default(0),
filesTouched: z.number().default(0),
errorsBySource: z.record(z.string(), z.number()).default({}),
errorsByClass: z.record(z.string(), z.number()).default({}),
retries: optNum,
delays: optNum,
delayMs: optNum,
maxContext: optNum,
compactions: optNum,
llmLatencyP50: optNum,
llmLatencyP95: optNum,
outputTokens: optNum,
// PR creation, file ops
prsCreated: optNum,
filesCreated: optNum,
filesDeleted: optNum,
})
.passthrough(),
repos: z
.array(
z
.object({ id: z.string(), name: z.string(), remote: optStr })
.passthrough()
)
.default([]),
files: z
.array(
z
.object({
id: z.number(),
repo: z.string(),
path: z.string(),
reads: z.number().default(0),
edits: z.number().default(0),
hits: z.number().default(0),
first: optNum,
// last op seen for this file across the whole doc; a lens must
// not read this for its own scope (see fileCoverage/recomputeTotals)
op: fileOpSchema,
})
.passthrough()
)
.default([]),
// Confirmed PR/MRs; `seq` points at the creating event.
// `totals.prsCreated` = length, kept separately since the producer
// writes both.
prs: z
.array(
z
.object({
provider: z.string(),
repo: optStr,
number: z.number(),
url: z.string(),
seq: z.number(),
state: optStr,
})
.passthrough()
)
.default([]),
agents: z
.array(
z
.object({
id: z.string(),
parent: z.string().nullable().default(null),
kind: z.string().default('main'),
subagentType: optStr,
launchSeq: optNum,
start: z.number().default(0),
end: z.number().default(0),
calls: z.number().default(0),
requests: z.number().default(0),
tokens: z.number().default(0),
cost: z.number().default(0),
outcome: optStr,
})
.passthrough()
)
.default([]),
events: z.array(sessionMapEventSchema).default([]),
// A malformed tasks block must never fail the whole map: drop it and
// fall back to per-user-turn windows.
tasks: z.array(sessionMapTaskSchema).optional().catch(undefined),
})
.passthrough();
export type SessionMap = z.infer<typeof sessionMapSchema>;
export type SessionMapEvent = SessionMap['events'][number];
export type SessionMapTarget = NonNullable<SessionMapEvent['targets']>[number];
export type SessionMapFile = SessionMap['files'][number];
export type SessionMapAgent = SessionMap['agents'][number];
export type SessionMapPr = SessionMap['prs'][number];
export type SessionMapTask = z.infer<typeof sessionMapTaskSchema>;
export type FileOp = NonNullable<SessionMapFile['op']>;