feat(agent-platform): parse kagent session tasks into a timeline

[marians]

What does this PR do?

Turns kagent's A2A task payloads into a renderable timeline. Groundwork for the session detail page — nothing renders these yet, so there is no visible change.

Stacked on #2002. Base is agent-platform-session-detail-proxy so the diff stays clean; GitHub will retarget to main when #2002 merges.

A session is a list of A2A tasks (turns) → history of messages → parts. kagent discriminates a part's meaning via prefixed keys in metadata rather than by wire type, so the new files split along that seam:

File	Responsibility
lib/kagentMetadata.ts	the adk_ / kagent_ prefix reader
lib/kagentParts.ts	part predicates (function_call, function_response, thought, agent-tool)
lib/kagentTimeline.ts	buildTimeline(tasks, timestamps) → flat TimelineItem[] + token totals
lib/kagentSessionState.ts	A2A TaskState → label/tone
lib/kagentEventTimestamps.ts	recovers per-message times from the doubly-encoded events
lib/kagentTaskSchema.ts, lib/kagentSessionDetail.ts	permissive zod + normalizers

Any background context you can provide?

Decisions I'd most like a second opinion on:

Metadata is read adk_<key> first, then kagent_<key>. Not a guess — it's kagent's own interop mechanism (getMetadataValue, ui/src/lib/messageHandlers.ts:479): upstream ADK writes one prefix, kagent writes the other, and a single session can contain both. There are two fixtures with identical content under different prefixes, and a test asserting they normalize identically.

A tool call and its result are one item, matched on the function-call id, with open calls scoped per task so a repeatedly-used tool can't get a result attached to the wrong call. An orphan response (call in a task we don't have, or no id) still renders — hiding a result seemed worse than showing one without its request.

Delegations to other agents are their own kind. They look like tool calls on the wire (the tell is __NS__ in the name, same check kagent's UI makes), but a subagent runs in its own session, so its messages never appear here and the response is the only place its token usage surfaces. That usage is counted once toward the session total, keyed on the call rather than the response — responses don't always repeat the name, and keying on them would silently under-count.

An unrecognised approval verdict leaves the verdict unset rather than defaulting to "approved". The message is still recognised as a decision (so it doesn't render as user prose), but guessing would claim the user consented to an action they may have refused.

Session state comes from the last task. kagent returns tasks ORDER BY created_at ASC (verified in tasks.sql.go), so the array is chronological; an earlier turn having completed says nothing about whether the session is working now. An unknown A2A state renders as itself and counts as inactive, so it can't produce a spinner that never resolves. "No tasks at all" stays its own condition rather than being flattened into a state.

Per-message timestamps come from joining the session's stored events on messageId, because A2A messages carry no time of their own. I've treated that join as decoration everywhere: whether the two storage paths agree on ids isn't guaranteed anywhere, so a miss falls back to the task's timestamp and then to showing no time. Tests cover all three levels.

How does it look like?

Nothing visual yet. The shape it produces:

user-message   You: Which GitHub issues are assigned to me?
reasoning      (2 adjacent thought parts, merged into one item)
tool-call      github_search_issues  args + result, isPending: false
agent-message  issue-tracker: You have two open issues...
user-message   You: Ask the SRE agent to check cluster health.
agent-call     kagent__NS__sre_agent  tokens: {total: 3100, ...}

Do the docs need to be updated?

Not in this PR — the user-facing write-up in docs/agent-platform.md lands with the page, where there's something to describe.

One thing to flag: the fixtures here are hand-authored from kagent's Go/Python source and its own test payloads, not captured from production. PR 2 adds no UI, so nothing in the app would exercise the new endpoints yet. I'll capture a real gazelle payload and add it as the primary fixture in the UI PR, where the page actually calls them — same approach that caught the z.unknown().transform() bug in the sessions list. Until then, treat the parsing as verified against the source but not against the wire.

Should this change be mentioned in the release notes?

• A changeset describing the change and affected packages was added.

[marians]

Careful pass over the whole diff (parsing layer, timeline builder, client methods, fixtures). The parsing is genuinely defensive and the reasoning in the comments is easy to follow — the findings below are all in the "wire shape we haven't seen yet" category the PR description already flags, plus one observability regression.

Highest-value ones: the adk_request_confirmation response leaking through the orphan branch as a raw tool call, and the drift-dedup key now being shared by three endpoints (which makes the new listSessionTasks warning effectively unreachable — the test has to dodge it with a different installation).

Nothing here blocks the groundwork landing; most are cheap to close before the UI PR exercises these paths against a real payload.

One thing I could not verify statically and would check against the real gazelle capture: whether kagent repeats the same usage_metadata bag on several a2a messages derived from one LLM event. If it does, the message-level accumulation in buildTimeline over-counts the session total, and the messageId dedup only saves you when the ids actually repeat.

[marians]

Validated against a real payload — three corrections

Your curl let me run the parsers over a live gazelle session (4 tasks, 32 messages, 12 tool calls) before this merges. It produced 29 items, no drift, no skipped rows, and all 12 tool calls paired with their responses. But it also disproved something I'd built on, so the diff has grown:

1. Per-message timestamps are not obtainable — that code is deleted.

kagent's Go type says Data string // JSON-serialized protocol.Message, which is what made me think the session's stored events could supply the timestamps A2A messages lack. The comment is stale. The decoded value is an ADK event:

actions, author, avg_logprobs, branch, cache_metadata, citation_metadata,
content, custom_metadata, error_code, ..., invocation_id, partial,
timestamp, turn_complete, usage_metadata

No messageId anywhere — 36 events yielded zero joinable ids. invocation_id does correlate (4/4 against task history), but an invocation is a whole turn, so it's no finer than the task timestamp I already had. kagentEventTimestamps.ts is gone, buildTimeline lost its second parameter, and every item now takes its task's timestamp. Items within a turn share one by design — the UI should show it per turn rather than imply per-message precision.

This also had a knock-on effect worth its own commit on #2002: with events unread, GET /kagent/sessions/:id now asks for limit=1. On that session the events were 591 KB against 261 bytes of session metadata I actually needed.

2. kagent repeats each user message verbatim under the same messageId, on every single turn:

t0 #0 user text len=103 id=019f892c-1c1e-75e6-b54f-25ab49e3a1c8
t0 #1 user text len=103 id=019f892c-1c1e-75e6-b54f-25ab49e3a1c8   <- same id

So the session-wide dedupe is load-bearing on real data, not defensive as I'd written it. Without it every turn opens by saying the same thing twice. Now has its own test and the fixture reproduces it.

3. One message can carry prose and several tool calls, always text first — observed text(-) -> data(function_call) -> data(function_call). Walking parts in order and merging only runs of same-kind text is what keeps the narration ahead of the calls it introduces. Also tested now.

What the real data does not exercise

Worth knowing when reviewing the fixtures: that session had no thought parts and no __NS__ delegations, and every metadata key was kagent_-prefixed — no adk_ in sight. So reasoning, agent delegation and the adk_ fallback are covered only by hand-authored fixtures. They're justified by kagent's source (part_converter.py sets the thought key; getMetadataValue reads adk_ first), but they are not wire-verified. Please don't let the "validated against real data" framing above extend further than it should.

On the fixtures

The real payload is not committed. A /tasks body is the full conversation — prompts, tool arguments, tool results — which isn't ours to put in this repo. The hand-authored fixtures are now structurally faithful to the three findings above instead.

tasks.adk-prefixed.json is now generated from tasks.v0-9-9.json by swapping only the metadata key prefix (agent references like kagent__NS__sre_agent are values, not keys, and stay). That way the two can't drift in any other dimension, which is exactly what the prefix test asserts. I got this wrong on the first attempt — a naive "kagent_ → "adk_ also rewrote the agent reference.

One thing to flag for the UI PR

Token totals are large in a way that will need careful labelling: that 4-turn session sums to 1.5M prompt tokens across 14 model calls (min 3,854, max 144,379). That's not a bug — each call re-sends the whole context and muster's tool schemas are big, so it's genuine cumulative billed usage, and kagent's own UI sums it the same way. But "1.5M input tokens" on a short chat will read as alarming or broken unless the label says what it's counting.

[fiunchinho]

Code review

Found 4 issues:

1. Stale doc comment: a2aMessageWireSchema says per-item times "come from joining messageId against the session's events — see kagentEventTimestamps.ts", but that file was deleted by this PR's second commit and the shipped design does the opposite (events are ignored; every item takes its task's timestamp, per kagentTimeline.ts and the changeset).

backstage/plugins/agent-platform/src/lib/kagentTaskSchema.ts

Lines 40 to 47 in 232a271

	metadata: z.unknown().optional(),
	});
	export type A2aPartWire = z.infer<typeof a2aPartWireSchema>;
	/**
	* One message in a task's history.
	*

2. Stale JSDoc on the KagentApi interface: getSessionDetail claims to return "the message timestamps recovered from its stored events", and listSessionTasks claims timestamp combining "happens in the calling hook". KagentSessionDetail is just { session; readOnly? } — it carries no timestamps — and no such hook exists. This describes the abandoned event-timestamp join.

backstage/plugins/agent-platform/src/apis/types.ts

Lines 37 to 58 in 232a271

	/**
	* One session's metadata, plus the message timestamps recovered from its
	* stored events.
	*
	* kagent scopes this by the forwarded token's user id, so a session belonging
	* to someone else raises `NotFoundError` exactly as a deleted one does. That is
	* the expected outcome for a stale deep link, not a fault.
	*/
	getSessionDetail(
	installation: string,
	sessionId: string,
	): Promise<KagentSessionDetail | undefined>;
	/**
	* The session's A2A tasks, in kagent's chronological order.
	*
	* Returned in wire form on purpose: the only consumer is `buildTimeline`,
	* which needs the full nested structure. Combining these with the timestamps
	* from {@link getSessionDetail} happens in the calling hook, because neither
	* request can see the other's result.
	*/

3. Misleading field comment: verdict is documented as "Undefined while the request is still unanswered", but readDecision also leaves it undefined for an answered approval with unrecognised wording (tests "leaves the verdict unset for wording it does not recognise" and "leaves an unanswered approval pending" both assert verdict: undefined). A consumer relying on "undefined = pending" would mislabel answered approvals.

backstage/plugins/agent-platform/src/lib/kagentTimeline.ts

Lines 64 to 67 in 232a271

	args?: unknown;
	/** Undefined while the request is still unanswered. */
	verdict?: 'approved' | 'rejected';
	});

4. The changeset body is ~70 lines of design rationale ("Decisions worth knowing", validation history, internal file cross-references) that Changesets will emit verbatim into the published CHANGELOG (CLAUDE.md guidance: "CHANGELOG.md entries should say what the consumer gets, not the rationale that usually already lives in the PR body"). Consider keeping the one-line consumer summary and moving the narrative to the PR body.

backstage/.changeset/agent-platform-session-timeline.md

Lines 1 to 20 in 232a271

	---
	'@giantswarm/backstage-plugin-agent-platform': minor
	---
	Parse kagent session tasks into a renderable timeline. Groundwork for the session
	detail page — no visible change yet.
	A session is a list of A2A **tasks** (turns), each holding a `history` of
	**messages**, each holding **parts**. kagent discriminates a part's meaning via
	prefixed keys in its `metadata` rather than by wire type, so the new
	`lib/kagentParts.ts` holds those predicates and `lib/kagentTimeline.ts` turns the
	nesting into a flat list of items: user and agent messages, reasoning, tool calls,
	delegations to other agents, and approval requests.
	Decisions worth knowing:
	- **Metadata is read `adk_<key>` first, then `kagent_<key>`.** That is kagent's
	own interop mechanism (`getMetadataValue` in its UI), not a guess: upstream ADK
	writes one prefix, kagent writes the other, and a single session can contain
	both. One helper spells the prefixes out; nothing else does.

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[marians]

Correction: real data does use adk_ prefixes, and the fallback is load-bearing

I said above that the gazelle session I probed had "only kagent_-prefixed metadata — no adk_ in sight", and that the adk_ fallback was justified by kagent's source but not wire-verified. That was wrong, and it matters more than a footnote.

Opening a different gazelle session in the running app today, every message carries:

"adk_usage_metadata": { "candidatesTokenCount": 60, "promptTokenCount": 2909 }

The session I probed yesterday carried kagent_usage_metadata. So one installation genuinely serves both prefixes, presumably depending on which kagent/ADK version wrote each message. The dual-prefix reader is therefore load-bearing, not defensive: reading only kagent_ would silently zero this session's token totals.

Please read my earlier "what the real data does not exercise" paragraph with that removed. Reasoning (thought) parts and __NS__ delegations are still fixture-only.

And a real bug it surfaced

The same session rendered "Total 0" next to "Input tokens 1.4M". adk_usage_metadata has no totalTokenCount at all, so summing reported totals stayed at zero while the parts ran into millions. kagent's own UI has the identical hole (total: usage.totalTokenCount ?? 0) — I faithfully reproduced a kagent bug.

Fixed in c9b274e on the UI branch (#2005): the total is derived from prompt + completion when kagent reports none, while a reported total still wins when present — a model billing thinking tokens separately counts them in the total but in neither part, so it isn't always the sum. Both cases have tests.

Verified live afterwards: the strip now reads Turns 3 · Input 1.4M · Output 2.6k · Total 1.4M.