1jehuang / 1jehuang/jcode

Harness API: `detach_session` should detach without aborting/crashing an in-flight turn

Open
#977 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

autonomous: no bug triage: needs-decision
Dominant language
Rust
Stars
19.9k
Forks
2.3k
Avg merge
2d 7h
Merged PRs (30d)
30

Description

Summary

In JCode v0.76.0 (bbef1f6a8), the harness API exposes detach_session, but the api-bridge currently replies ok locally without forwarding any detach operation to the daemon.

For an external orchestrator, this means there is no supported way to say:

this client is done observing the session, but let the already-started turn continue normally.

Closing the last attached client connection instead enters the normal disconnect cleanup path, which can mark/remove the session as crashed and, for the connection that owns the in-flight processing task, abort that task.

Observed behavior

From the v0.76.0 source:

  • crates/jcode-harness-api-server/src/translate.rs handles detach_session by returning ApiEvent::Ok locally.
  • No corresponding detach request is sent to the daemon.
  • jcode-protocol::wire::Request has no detach variant to translate to.
  • Daemon disconnect cleanup uses session_has_live_successor(...) to avoid destructive cleanup only while another connection is still attached to the same session.
  • Therefore a second/keeper connection can keep a turn alive, but only while a client connection remains continuously retained. There is no bounded/eager handoff that allows all external clients to disconnect safely.

This is especially awkward for request/response integrations: an HTTP request can start a turn, but returning the HTTP response should not require retaining an unbounded client socket merely to keep the turn alive.

Expected behavior

detach_session should have real daemon semantics:

  1. an attached client can explicitly detach from the current session;
  2. voluntary detach is non-destructive to an already-running turn;
  3. the session is not marked crashed merely because the detaching client was the last attached client;
  4. the in-flight processing task is not aborted solely because of that voluntary detach;
  5. later attach/cancel/session observation remains consistent with the existing session model;
  6. ordinary unexpected socket loss may keep its current fail-safe semantics.

In short: detach should mean "client leaves, session/turn keeps running", not "return ok while remaining attached".

Smallest implementation boundary I found

A minimal implementation appears to require changes around:

  • crates/jcode-protocol/src/wire.rs — add an explicit detach request/intent;
  • crates/jcode-app-core/src/server/client_lifecycle.rs — carry voluntary-detach intent into cleanup;
  • crates/jcode-app-core/src/server/client_disconnect_cleanup.rs — treat voluntary detach as non-destructive while processing;
  • crates/jcode-harness-api-server/src/translate.rs — forward detach_session to the daemon instead of replying ok locally;
  • focused unit/e2e coverage proving: start turn → detach last client → turn continues → session is not marked crashed.

I am not assuming the exact storage/lifetime policy for an unattached live session; that likely belongs to the JCode maintainers' existing session model. The key semantic requirement is only that a deliberate detach not be treated as an accidental/destructive client disconnect.

Why this matters

JCode already has the pieces needed by external harnesses — create/attach, streaming events, cancel, session inventory — but without a real detach semantic, a client that starts a long-running turn must either:

  • keep a connection open for the entire turn, or
  • risk destructive disconnect behavior when it returns control to its own caller.

A real detach would make the existing daemon/api-bridge usable as a clean execution boundary for external orchestrators without requiring them to invent a separate long-lived keeper runtime.

Environment

  • JCode: v0.76.0
  • commit reported by the installed binary/source: bbef1f6a8
  • Linux

I searched the existing issue tracker for detach_session before filing and did not find a matching issue.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Read the detach_session handling in crates/jcode-harness-api-server/src/translate.rs, then trace Request in crates/jcode-protocol/src/wire.rs and cleanup in client_lifecycle.rs and client_disconnect_cleanup.rs. Add focused unit or end-to-end coverage for starting a turn, detaching the last client, and confirming the turn continues without the session being marked crashed.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
api, backend-api-design
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
52/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.