[PR] Collect the sessions Kiro's V3 engine writes, for kiro-cli and Kiro Crew [skywalking-ai-sessionizer]

["wu-sheng (via GitHub)" <gi...@apache.org>]

wu-sheng opened a new pull request, #60:
URL: https://github.com/apache/skywalking-ai-sessionizer/pull/60

   A new adapter, `kiro-local`, collects the sessions Kiro's V3 agent engine writes under `~/.kiro`: kiro-cli started with `--v3` or with `chat.agentEngine` set to `v3`, and Kiro Crew on its `kas` backend. It is on by default and needs nothing from Kiro.
   
   ## Measured
   
   | Sample | Sessions | With records | Records |
   | --- | --- | --- | --- |
   | kiro-cli 2.28.0, engine `@kiro/agent` 0.66.26, and Kiro Crew 0.7.2 on it; tasks run for the purpose and real use | 86 | 56 | 3,101 |
   | Kiro Crew 0.8.0, which bundles kiro-cli 2.27.1 and engine 0.66.22; real use after it updated itself | 13 | 10 | 2,069 |
   
   All on one macOS machine. Every session with records lands and assembles into a verified conversation; a header-only session waits until it has a record. The six fixtures under `internal/adapters/kiro/testdata` come from these samples; the sessions from real use keep only their record structure, with every text a person, the agent or a tool wrote replaced.
   
   ## How Kiro's records become a conversation
   
   - **What is read.** `sessions/<workspace key>/sess_<id>/`: `session.json`, the header, lands as the main stream's `agent_meta`; `messages.jsonl` is the main stream; `sub-executions/<child id>.jsonl` are the subagents. A header must name `schemaVersion` `1.0.0`, the one measured. kiro-cli's V2 sessions and V3 sessions of another schema are counted in `asz sources` and once in `asz collect`, and not collected.
   - **Turns.** A prompt carries no turn id, nor does a message sent while a turn runs. Each belongs to the first turn named after it in the file, and waits to land until that turn is named, since a landed record is never written again. The lines after a window are read for it. A prompt whose turn never starts lands with no turn once its file has been still for five minutes.
   - **Ids.** A record's id is the engine's id followed by the first 12 hex digits of the record's SHA-256: the engine gives one id to an approval it asks twice, 46 ids in the measured records, and assembly would have removed the second as a copy.
   - **Subagents** are joined by the child's id, which the parent's start and end records and the child's own file share. A compaction is a context reset with its summary. A turn's `elapsedTime` is its measured duration.
   - **No provider call.** Kiro ties no record to a request, so model output whose record names no call is a step of its run and no `llm.call` is written. Grouping the records into calls by turn or by record would draw a boundary the runtime never recorded.
   - **Title.** Kiro keeps a session's title in its header, so a sidecar of the `main` stream names the conversation. A child's sidecar still names only its child.
   - **Not supplied.** Tokens (the engine records credits, not tokens), the model per record, permission decisions and interruptions as steps. The [Kiro adapter](docs/en/adapters/kiro.md) page lists them with the reason for each.
   - **Kiro Crew's task runs.** On `kas`, Crew deletes a task run's step sessions within seconds of each step: in one measured run they lasted 1.4 to 358 seconds, 68 at the median. A collection every few minutes misses most of them. kirodotdev/KiroCrew#18988 proposes a setting that keeps them for a while; the adapter page links it. Chats, scheduled jobs, subagents and `kirocrew chat -m` keep their records and are collected today.
   
   ## Changes beside the adapter
   
   - **A file that fails to land leaves nothing behind.** Its records entered the index while it was being written, and it kept the number it took. A failed rename therefore left index entries for records that never landed, and a gap in the landed numbers that every later round reported as a missing file. Claude Code's transcripts and workspace changes did both, as the new adapter did. Records now enter the index only once their file has landed (`index.Staged`), and a file that did not land gives its number back (`SessionState.GiveBack`). Provider bodies stopped the session's pass at the failed file before anything was saved, and land in the same order now.
   - **`control.notice` is in `model.Vocabulary`**, the list every glossary is checked against. It was the one kind the model emits that the list left out; the Kiro and LangSmith glossaries gain its entry.
   - **Scenarios.** An `error` step can name no call, `error: {text, unidentified: true}`, and an expectation can check the session's title, `session: {title}`. `output-without-call` holds a synthetic message with no call and checks the talk's reply; `all-kinds` checks that a child's meta file does not rename the conversation.
   - **Filters** match a Windows path in either spelling, on every host.
   
   ## Tests
   
   - `internal/adapters/kiro`: every fixture lands, parses to a verified conversation with the steps its records hold, and lands and parses again with nothing new; a re-landed record folds to the same conversation; tools, subagents, compaction, steering, a cancelled turn, image prompts, reasoning kept as `...`; a prompt waiting for its turn, a turn past the window, a turn line with no newline yet, an abandoned prompt; record ids unique and stable; the latest header naming the conversation; the measured schema only, and an empty transcript not a session; Windows filters; a file that fails to land, as a window and as a snapshot.
   - `internal/adapters/claudecode` and `internal/adapters/claudecodechanges`: a file that fails to land leaves no index entry and no gap.
   - Glossary tests cover the whole vocabulary for every adapter, with `control.notice` in it.
   - Every new guard was reverted once and its test failed.
   - `make check` passes, and so do `go test -race ./...` and the scenarios.
   - End to end, beside the change kirodotdev/KiroCrew#18988 proposes: a Kiro Crew built with it ran a two-step task with a 240-second delay, while asz collected every 60 seconds. All five step sessions (the planner, both steps, both reviews) landed and assembled into verified conversations, each with its final reply. After Crew's cleanup loop deleted the five records, `asz verify` still passed over the root.
   
   ## Docs
   
   The [Kiro](docs/en/setup/kiro.md) setup page, the [Kiro adapter](docs/en/adapters/kiro.md) page and its [glossary](docs/en/adapters/kiro-glossary.md), the configuration page, the scenario guide, the assembly page, the formats pages it touches, the menu, and the changes entries.
   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@skywalking.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] Collect the sessions Kiro's V3 engine writes, for kiro-cli and Kiro Crew [skywalking-ai-sessionizer]

["wu-sheng (via GitHub)" <gi...@apache.org>]

wu-sheng merged PR #60:
URL: https://github.com/apache/skywalking-ai-sessionizer/pull/60


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@skywalking.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org