kyo-experiment: a Kyo session with real interrupt, and the SDK verdict (slice 02-kyo-session) #88

Merged

mph merged 28 commits from kyo-experiment into main 2026-10-16 09:18:51 +00:00

Conversation 0 Commits 28 Files changed 39 +3127 -92

claude commented 2026-10-13 09:35:28 +00:00

Member

Copy link

Slice 02-kyo-session (kyo-experiment, step 1: the SDK)

Goal. Hold a live, multi-turn conversation with the real Claude CLI through a Kyo session (send while a turn runs, interrupt a turn for real and keep talking, see completion as state), then read the Kyo code beside zio's session and write the SDK verdict.

Fit test. Michal chats and interrupts in the terminal runner (./mill -i kyo.runMain works.iterative.claude.kyo.ChatRunner), reads Kyo beside zio, and writes the verdict with file:line on both sides. Fit called by Michal on 2026-10-01.

Verdict (Michal). Hold the adoption of Kyo for now. Watch Kyo for updates in the areas where it is missing (a live stdin write, a sliding fan-out, an exact wait on a Signal), and possibly contribute. Go on to the Kyo UI slice. The evidence is the reading index at the top of project-management/efforts/kyo-experiment/slices/02-kyo-session/friction.md.

Done

• Kyo Session: send, interrupt over the control protocol, state / resultsSeen, awaitResultAfter / sendAndAwait, info, terminated, events, stateChanges, death with the stderr tail, and the process tree ended with the scope. Spawn and tree kill are shared with the query path (CliProcess).
• LossyBroadcast: each events subscriber has its own buffer and drops its oldest messages. Kyo's back-pressured Hub stalled every reader behind one slow reader.
• SignalAwait: one wait on a Signal with a repair interval, used by the session and the chat. The chat waits on changes, with no sleep loops.
• Terminal chat runner (Chat, ChatCommand, ChatRunner) with /interrupt and /quit.
• Tests: SessionIntegrationTest (18), SessionErrorIntegrationTest (2), SessionInterruptIntegrationTest (6) and ChatIntegrationTest (12) against bash stand-ins. Real-CLI SessionE2ETest (4) and StopAndKeepTalkingE2ETest (1), each in an isolated config directory that is deleted after the test. New unit suites for LossyBroadcast, SignalAwait, SessionRules, ChatCommand and SessionDisplay.
• core: SessionState and InterruptOutcome derive CanEqual (approved, no change in behaviour).

Review

Seven skills: style, testing, security, scala3, composition, architecture and error-handling. They found no critical issues and 11 warnings. Five were fixed in 0bbc81d:

• A reader panic was read as the end of input.
• The E2E tests left a copy of the login in /tmp.
• Three itests are now exact.
• The resumed query must stay in the stopped session.

The other warnings are filed as issues. Report: project-management/efforts/kyo-experiment/slices/02-kyo-session/review-slice-20261001-1525.md.

Follow-ups

• #81 Session and stream itests: timing-dependent and always-true assertions
• #82 Session errors do not say what happened (a refused interrupt reads as success). Affects zio.
• #83 A session whose stdout reader fails while the CLI lives can wait for ever on its end (related to #75)
• #84 CLI output reaches the terminal and the logs uncleaned
• #85 Kyo adapter boundaries

Parked (moved to the effort map)

• Conversation archive → kyo-archive
• Sessions host registry, and the "is the CLI working?" activity state → kyo-ui-chat
• Extract the control-request protocol out of SessionProcess (large refactor)
• direct session parity bar, effectful baseline, publication, full zio unit-suite port

Gates

• __.compile, __.test and kyo.itest (66/66, including the real-CLI E2E tests) pass with no warnings.
• In a parallel __.itest run, timing tests in effectful and direct fail under load and pass alone (#81). This branch does not change effectful or direct.

🤖 Generated with Claude Code

## Slice 02-kyo-session (kyo-experiment, step 1: the SDK) **Goal.** Hold a live, multi-turn conversation with the real Claude CLI through a Kyo session (send while a turn runs, interrupt a turn for real and keep talking, see completion as state), then read the Kyo code beside `zio`'s session and write the SDK verdict. **Fit test.** Michal chats and interrupts in the terminal runner (`./mill -i kyo.runMain works.iterative.claude.kyo.ChatRunner`), reads Kyo beside `zio`, and writes the verdict with file:line on both sides. Fit called by Michal on 2026-10-01. **Verdict (Michal).** Hold the adoption of Kyo for now. Watch Kyo for updates in the areas where it is missing (a live stdin write, a sliding fan-out, an exact wait on a `Signal`), and possibly contribute. Go on to the Kyo UI slice. The evidence is the reading index at the top of `project-management/efforts/kyo-experiment/slices/02-kyo-session/friction.md`. ## Done - Kyo `Session`: `send`, `interrupt` over the control protocol, `state` / `resultsSeen`, `awaitResultAfter` / `sendAndAwait`, `info`, `terminated`, `events`, `stateChanges`, death with the stderr tail, and the process tree ended with the scope. Spawn and tree kill are shared with the query path (`CliProcess`). - `LossyBroadcast`: each `events` subscriber has its own buffer and drops its oldest messages. Kyo's back-pressured `Hub` stalled every reader behind one slow reader. - `SignalAwait`: one wait on a `Signal` with a repair interval, used by the session and the chat. The chat waits on changes, with no sleep loops. - Terminal chat runner (`Chat`, `ChatCommand`, `ChatRunner`) with `/interrupt` and `/quit`. - Tests: `SessionIntegrationTest` (18), `SessionErrorIntegrationTest` (2), `SessionInterruptIntegrationTest` (6) and `ChatIntegrationTest` (12) against bash stand-ins. Real-CLI `SessionE2ETest` (4) and `StopAndKeepTalkingE2ETest` (1), each in an isolated config directory that is deleted after the test. New unit suites for `LossyBroadcast`, `SignalAwait`, `SessionRules`, `ChatCommand` and `SessionDisplay`. - `core`: `SessionState` and `InterruptOutcome` derive `CanEqual` (approved, no change in behaviour). ## Review Seven skills: style, testing, security, scala3, composition, architecture and error-handling. They found no critical issues and 11 warnings. Five were fixed in `0bbc81d`: - A reader panic was read as the end of input. - The E2E tests left a copy of the login in `/tmp`. - Three itests are now exact. - The resumed query must stay in the stopped session. The other warnings are filed as issues. Report: `project-management/efforts/kyo-experiment/slices/02-kyo-session/review-slice-20261001-1525.md`. ## Follow-ups - [ ] #81 Session and stream itests: timing-dependent and always-true assertions - [ ] #82 Session errors do not say what happened (a refused interrupt reads as success). Affects `zio`. - [ ] #83 A session whose stdout reader fails while the CLI lives can wait for ever on its end (related to #75) - [ ] #84 CLI output reaches the terminal and the logs uncleaned - [ ] #85 Kyo adapter boundaries ## Parked (moved to the effort map) - Conversation archive → `kyo-archive` - `Sessions` host registry, and the "is the CLI working?" activity state → `kyo-ui-chat` - Extract the control-request protocol out of `SessionProcess` (large refactor) - `direct` session parity bar, `effectful` baseline, publication, full `zio` unit-suite port ## Gates - `__.compile`, `__.test` and `kyo.itest` (66/66, including the real-CLI E2E tests) pass with no warnings. - In a parallel `__.itest` run, timing tests in `effectful` and `direct` fail under load and pass alone (#81). This branch does not change `effectful` or `direct`. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

claude added 27 commits 2026-10-13 09:35:28 +00:00

workflow(sl): define kyo-experiment/02-kyo-session ... ef5a9fa186

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

workflow(sl): review-state for kyo-experiment/02-kyo-session ... 85c3775cbb

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

kyo-experiment 02-kyo-session: inventory the zio session and map it to Kyo constructs ... e719895508

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

kyo-experiment 02-kyo-session: a Kyo Session over a long-lived CLI process ... 87d699682a

Session, SessionProcess (one stdout reader, state as a Signal, events over a Hub),
ClaudeCode.session in the caller's Scope, the process helpers shared with the
query path, and the session integration tests against stand-in CLIs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

kyo-experiment 02-kyo-session: a terminal chat runner over the Kyo Session ... e721b781fa

ChatRunner (KyoApp) reads lines from stdin, sends them as user input, prints each
message and state change as it arrives, and leaves on /quit or end of input once
what was said has been answered. Line parsing, state display and the conversation
loop are tested apart from the terminal.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

kyo-experiment 02-kyo-session: correct a citation in the friction log ... 5ee330298a

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

workflow(sl): checkpoint 02-kyo-session ... 3ea5169a90

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

workflow(sl): checkpoint 02-kyo-session (fit: chat runner) ... 215e82a5f4

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

kyo-experiment 02-kyo-session: Session.interrupt over the control protocol, and /interrupt in the chat ... adbd066f20

The interrupt registers a pending request, re-checks liveness, writes the control
request and awaits the response with a timeout; the reader routes control responses
and fails pending requests when the session ends. The chat's /interrupt shows the
outcome and keeps reading.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

workflow(sl): checkpoint 02-kyo-session ... a4c67b5df8

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

workflow(sl): checkpoint 02-kyo-session (fit: interrupt) ... 42975b30f8

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

kyo-experiment 02-kyo-session: events isolate their consumers and drop the oldest ... 4f2949164d

Kyo's Hub is back-pressured, so one consumer that stopped reading stalled
every other one, and its close discarded what each listener still held.
LossyBroadcast gives each subscriber its own Channel; a publish never waits
and a full buffer loses its oldest value. A stalled-subscriber itest and five
unit tests, all run red against the Hub first.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

workflow(sl): checkpoint 02-kyo-session ... 178c9c389f

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

kyo-experiment 02-kyo-session: one wait on a signal, and a chat that waits on change ... 5193d7e995

SignalAwait.until holds the read-then-wait loop with its repair interval,
the form Kyo's own Signal.observe uses, since the safe Signal API has no
exact wait. The session's changedFrom calls it. The chat drops its 50 ms
and 20 ms sleep loops: answered is a filter on stateChanges, quiet is a
timeout on the next change of one SignalRef, and shown uses SignalAwait.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

workflow(sl): checkpoint 02-kyo-session ... 33a63de276

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

kyo-experiment 02-kyo-session: SessionErrorIntegrationTest beside zio's ... 4d19ef33f9

The two death cases move out of SessionIntegrationTest into their own file
with zio's names. The mid-turn exit now also asserts that terminated resolves
and that the state records the end, as zio does. Both fail when the end is
recorded without its exit code.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

kyo-experiment 02-kyo-session: real-CLI E2E for the session and for Stop ... f4b9182af6

SessionE2ETest ports zio's four cases: one turn, info after a turn, context
across two turns, and a real interrupt the session survives.
StopAndKeepTalkingE2ETest stops a query as its first tool call opens, with
takeWhile ending the stream and its scope ending the CLI, then resumes the
session and gets an answer. All five pass against the real CLI.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

kyo-experiment 02-kyo-session: reading index for the SDK verdict ... b26c487a9e

The friction log opens with each session concern at file:line in zio and in
Kyo, the friction entry that holds the evidence, the sizes, and the test
suites side by side. Two entries record what the E2E ports showed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

workflow(sl): checkpoint 02-kyo-session ... 4c7efa5ddb

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

kyo-experiment 02-kyo-session: SessionState and InterruptOutcome derive CanEqual ... d9af14737e

Kyo's Signal compares values to notify only on a change, so the Kyo session
had to give SessionState a local CanEqual. core now derives it for both
session model types; behaviour is unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

kyo-experiment 02-kyo-session: correct a citation in the friction log ... 71941e1fbf

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

workflow(sl): checkpoint 02-kyo-session (fit: activity parked) ... 8fe4db5906

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

workflow(sl): checkpoint 02-kyo-session (fit called: SDK verdict) ... 5602cc49f4

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

kyo-experiment 02-kyo-session: review fixes at close ... 0bbc81d2ef

Chat.speak re-raises a panic from the reader instead of reading it as the
end of input (new itest, red without the fix). The E2E tests run in a config
directory of their own that is deleted with its scope and holds the login
copy owner-only; the resumed query must answer in the stopped session. Three
itests assert what their names promise: the exact error of an ended
session's interrupt, one result for two merged sends, and a blank line
checked against a real line answered after it. Findings shared with zio, or
needing core, are in the effort's FOLLOW-UPS.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

workflow(sl): review report for kyo-experiment batch ... 17c6b67de7

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

workflow(sl): lesson entry for the Mill compile worker ... 539956761a

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

workflow: Triage lessons for kyo-experiment ... ce8b521133

Follow-ups filed: 5 (CC-81, CC-82, CC-83, CC-84, CC-85; 12 lines grouped), commented: 1 (#75), struck: 0
Lessons: 0 approved, 1 rejected, 0 still pending

Rejected:
- A compile after an interactive Mill run fails with "Connection refused": cause not understood

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

mph added 1 commit 2026-10-13 09:42:02 +00:00

workflow(sl): close kyo-experiment batch (flush parked items) ... a91208ccda

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

mph merged commit 807cc2cd9b into main 2026-10-16 09:18:51 +00:00

mph referenced this pull request from a commit 2026-10-16 09:18:52 +00:00

Merge pull request 'kyo-experiment: a Kyo session with real interrupt, and the SDK verdict (slice 02-kyo-session)' (#88) from kyo-experiment into main

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels   

bug

Something isn't working

  

documentation

Improvements or additions to documentation

  

duplicate

This issue or pull request already exists

  

enhancement

New feature or request

  

good first issue

Good for newcomers

  

help wanted

Extra attention is needed

  

invalid

This doesn't seem right

  

question

Further information is requested

  

wontfix

This will not be worked on

No labels

bug

documentation

duplicate

enhancement

good first issue

help wanted

invalid

question

wontfix

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

2 participants

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

iterative-works/claude-code-query!88

No description provided.