feat(agent): keep Claude Code open between turns so background tasks can wake it (#2652)

This commit is contained in:
Kurt Himebauch authored and GitHub committed 2026-11-15 12:27:17 -05:00
1 parent 9a93f59fbf
commit 259d5d184b
5 files changed
+196 -30

No files matched your search

@@ -5,7 +5,7 @@ import org.json.JSONArray
import org.json.JSONObject
import java.io.File
/** One coding agent CLI in the Linux userland, run one process per turn. */
/** One coding agent CLI in the Linux userland, run one process per turn (or kept open, see [input]). */
interface AgentHarness {
val id: String
val name: String
@@ -27,6 +27,12 @@ interface AgentHarness {
fun models(rootfs: File): List<Model>
/** The guest command for one turn; [conversation] is null for the first one. */
fun turn(message: String, conversation: String?, options: Options): List<String>
/**
* The line that hands [message] to a [turn] process over stdin, or null when the message is already in the
* command. A process that takes its messages this way stays open between turns, so work it started in the
* background can wake it, as it does in the CLI's own terminal.
*/
fun input(message: String): String? = null
/** One line of the CLI's output, or null when it carries nothing to show. */
fun parse(line: String): AgentEvent?
/** Sets the CLI's own defaults in the userland before it runs; [rootfs] is the userland's root. */
@@ -56,9 +62,13 @@ data class AgentEvent(
val window: Long? = null,
val limits: List<AgentHost.Limit>? = null,
val usage: AgentHost.Usage? = null,
/** This ends a turn the CLI started itself, such as the answer to a finished background task. */
val background: Boolean = false,
/** The error a background turn ended with, if it failed. */
val backgroundError: String? = null,
)
/** Claude Code: `claude -p` with stream-json output, resumed by session id. */
/** Claude Code: `claude -p` with stream-json input and output, resumed by session id. */
object ClaudeCode : AgentHarness {
override val id = "claude"
override val name = "Claude Code"
@@ -97,7 +107,7 @@ object ClaudeCode : AgentHarness {
// DroidDeck runs the agent unattended on the user's own device; permission prompts have no one to answer them.
override fun turn(message: String, conversation: String?, options: AgentHarness.Options) = buildList {
addAll(listOf(binary, "-p", message, "--output-format", "stream-json", "--verbose", "--include-partial-messages"))
addAll(listOf(binary, "-p", "--input-format", "stream-json", "--output-format", "stream-json", "--verbose", "--include-partial-messages"))
addAll(listOf("--permission-mode", if (options.plan) "plan" else "bypassPermissions"))
options.model?.let { addAll(listOf("--model", it)) }
options.effort?.let { addAll(listOf("--effort", it)) }
@@ -105,6 +115,11 @@ object ClaudeCode : AgentHarness {
if (conversation != null) addAll(listOf("--resume", conversation))
}
override fun input(message: String): String? = JSONObject()
.put("type", "user")
.put("message", JSONObject().put("role", "user").put("content", JSONArray().put(JSONObject().put("type", "text").put("text", message))))
.toString()
override fun parse(line: String): AgentEvent? {
val o = runCatching { JSONObject(line) }.getOrNull() ?: return null
val conversation = o.optString("session_id").takeIf { it.isNotEmpty() }
@@ -130,7 +145,11 @@ object ClaudeCode : AgentHarness {
"thinking" -> if (parent != null) null else block.optString("thinking").trim().takeIf { it.isNotEmpty() }?.let { AgentHost.Entry.Thought(it) }
"tool_use" -> {
val input = block.optJSONObject("input")
AgentHost.Entry.Used(block.optString("id"), block.optString("name"), detail(input), fullInput(block.optString("name"), input), parent = parent.orEmpty())
AgentHost.Entry.Used(
block.optString("id"), block.optString("name"), detail(input), fullInput(block.optString("name"), input),
parent = parent.orEmpty(),
background = input?.optBoolean("run_in_background") == true || block.optString("name") == "Monitor",
)
}
else -> null
}
@@ -148,17 +167,25 @@ object ClaudeCode : AgentHarness {
AgentEvent(conversation, results)
}
"rate_limit_event" -> AgentEvent(conversation, limits = limits(o.optJSONObject("rate_limit_info")))
// A resumed session first answers background tasks the last run left behind; that result is not the turn's.
"result" -> if (o.optJSONObject("origin")?.optString("kind") == "task-notification") conversation?.let { AgentEvent(it) } else AgentEvent(
conversation,
listOf(AgentHost.Entry.Finished(if (o.optBoolean("is_error")) o.optString("result").ifEmpty { o.optString("subtype") } else null)),
window = window(o.optJSONObject("modelUsage")),
usage = AgentHost.Usage(
// The CLI starts turns of its own for background tasks (a resumed session first answers the ones the last
// run left behind). Such a result is not the end of the user's turn; the host decides what it ends.
"result" -> {
val usage = AgentHost.Usage(
o.optLong("duration_ms"), o.optDouble("total_cost_usd", 0.0),
o.optJSONObject("usage")?.let { it.optLong("input_tokens") + it.optLong("cache_read_input_tokens") + it.optLong("cache_creation_input_tokens") } ?: 0,
o.optJSONObject("usage")?.optLong("output_tokens") ?: 0,
),
)
)
if (o.optJSONObject("origin")?.optString("kind") == "task-notification") AgentEvent(
conversation, usage = usage, background = true,
backgroundError = if (o.optBoolean("is_error")) o.optString("result").ifEmpty { o.optString("subtype") } else null,
)
else AgentEvent(
conversation,
listOf(AgentHost.Entry.Finished(if (o.optBoolean("is_error")) o.optString("result").ifEmpty { o.optString("subtype") } else null)),
window = window(o.optJSONObject("modelUsage")),
usage = usage,
)
}
else -> conversation?.let { AgentEvent(it) }
}
}
@@ -21,7 +21,8 @@ import java.nio.file.Files
/**
* The launcher's agent: a coding agent CLI ([AgentHarness]) from the Linux userland, run headless
* one process per turn, outside any game or desktop session. Conversations are kept on disk
* outside any game or desktop session: one process per turn, or for a CLI that takes its messages over
* stdin one process kept open between turns, so background work can start a turn of its own. Conversations are kept on disk
* ([AgentChats]), so a restart (a Lab build, a crash) continues the same one.
*/
object AgentHost {
@@ -29,10 +30,13 @@ object AgentHost {
data class Asked(val text: String, val files: List<String> = emptyList()) : Entry
data class Said(val text: String) : Entry
data class Thought(val text: String) : Entry
/** A tool call; [output] stays null until its result arrives. [parent] is the subagent call it was made under, if any. */
/**
* A tool call; [output] stays null until its result arrives. [parent] is the subagent call it was made under, if any.
* [background]: the call starts work that can wake the CLI after its turn (run_in_background, Monitor).
*/
data class Used(
val id: String, val tool: String, val detail: String, val input: String = "", val output: String? = null, val failed: Boolean = false,
val parent: String = "",
val parent: String = "", val background: Boolean = false,
) : Entry
data class Result(val id: String, val output: String, val failed: Boolean) : Entry
/** [planned]: the turn ran in plan mode, so it ends on a plan that nothing has carried out yet. */
@@ -126,10 +130,19 @@ object AgentHost {
var lab by mutableStateOf<LabProgress?>(null)
private set
private class Turn(val process: Process, val pid: Int)
private class Turn(val process: Process, val pid: Int, val stdin: java.io.OutputStream? = null)
private val main = Handler(Looper.getMainLooper())
private var turn: Turn? = null
/**
* The CLI process when it takes its messages over stdin. It outlives a turn, so work it started in the
* background can wake it: the answer to a finished task then arrives without a message from the user.
*/
private var session: Turn? = null
private var sessionKey: String? = null
/** The running turn is one the CLI started itself, not an answer to the user. */
private var background = false
private val reap = Runnable { if (state != State.WORKING) dropSession() }
/** Counts turns, so a process that starts after its turn was stopped is not adopted by the next one. */
private var generation = 0
private var labProcess: Process? = null
@@ -142,6 +155,8 @@ object AgentHost {
private var turnPlanned = false
private var loaded = false
private var appContext: Context? = null
/** A tool call in this CLI process started work that can wake it after its turn (run_in_background). */
private var launchedBackground = false
val turnPid: Int get() = turn?.pid ?: 0
@@ -197,6 +212,7 @@ object AgentHost {
AgentSetup.forget()
refresh(app)
}
dropSession()
load(app, id)
prefs(app).edit().putString(CHAT_KEY, id).apply()
}
@@ -289,7 +305,33 @@ object AgentHost {
val current = harness
val prompt = AgentAttachments.prompt(message, attached)
turnPlanned = plan && current.plans
val command = current.turn(prompt, conversation, AgentHarness.Options(model, turnPlanned, BRIEF, effort))
val options = AgentHarness.Options(model, turnPlanned, BRIEF, effort)
val command = current.turn(prompt, conversation, options)
val line = current.input(prompt)
val key = "${current.id}|$id|$model|$turnPlanned|$effort"
background = false
val kept = session
if (kept != null && line != null && sessionKey == key && kept.process.isAlive) {
main.removeCallbacks(reap)
turn = kept
Thread({
val written = runCatching { synchronized(kept) { kept.stdin?.apply { write((line + "\n").toByteArray()); flush() } != null } }.getOrDefault(false)
// The process died between turns: the same message goes to a new one, which resumes the conversation.
if (!written) main.post {
if (generation == gen && session === kept) {
dropSession()
turn = null
spawn(app, gen, current, current.turn(prompt, conversation, options), line, key)
}
}
}, "agent-input").start()
return
}
dropSession()
spawn(app, gen, current, command, line, key)
}
private fun spawn(app: Context, gen: Int, current: AgentHarness, command: List<String>, line: String?, key: String) {
val workdir = workspace(app)
var threadConversation = conversation
Thread({
@@ -304,40 +346,77 @@ object AgentHost {
main.post { if (generation == gen) finish(app, e.message ?: "could not start") }
return@Thread
}
val started = Turn(child, AgentProcesses.pidOf(child))
val started = Turn(child, AgentProcesses.pidOf(child), if (line != null) child.outputStream else null)
OrphanReaper.keep(started.pid)
main.post { if (generation == gen && state == State.WORKING && turn == null) turn = started else AgentProcesses.killTree(started.pid) }
child.outputStream.close()
var ended = false
main.post {
if (generation == gen && state == State.WORKING && turn == null) {
turn = started
if (line != null) { session = started; sessionKey = key }
} else AgentProcesses.killTree(started.pid)
}
if (line != null) runCatching { child.outputStream.apply { write((line + "\n").toByteArray()); flush() } } else child.outputStream.close()
val raw = runCatching {
val log = File(app.filesDir, TURN_LOG).apply { parentFile?.mkdirs() }
log.renameTo(File(app.filesDir, "$TURN_LOG.1"))
log.bufferedWriter()
}.getOrNull()
runCatching {
child.inputStream.bufferedReader().forEachLine { line ->
runCatching { raw?.apply { write(line); newLine(); flush() } }
val parsed = current.parse(line) ?: return@forEachLine
child.inputStream.bufferedReader().forEachLine { output ->
runCatching { raw?.apply { write(output); newLine(); flush() } }
val parsed = current.parse(output) ?: return@forEachLine
parsed.conversation?.let { threadConversation = it }
val done = parsed.entries.any { it is Entry.Finished }
if (done) ended = true
val event = if (!done) parsed else runCatching { current.usage(LinuxRuntime.rootDir(app), threadConversation) }.getOrNull()
?.let { parsed.copy(context = it.context ?: parsed.context, window = it.window ?: parsed.window, limits = it.limits ?: parsed.limits) } ?: parsed
main.post { if (turn === started) apply(app, event) }
main.post { if (turn === started || session === started) handle(app, started, event) }
}
}
runCatching { raw?.close() }
val status = runCatching { child.waitFor() }.getOrDefault(-1)
OrphanReaper.release(started.pid)
main.post {
if (session === started) { session = null; main.removeCallbacks(reap) }
if (turn === started) {
turn = null
if (state == State.WORKING && !ended) finish(app, app.getString(R.string.agent_exited, current.name, status))
if (state == State.WORKING) finish(app, app.getString(R.string.agent_exited, current.name, status))
}
}
}, "agent-output").start()
}
/** One event from the CLI, which may belong to a turn it started on its own once the user's has ended. */
private fun handle(app: Context, from: Turn, event: AgentEvent) {
if (event.background) {
// A leftover task answered before the user's message is not the user's turn; one the CLI started is its own.
if (background && state == State.WORKING) finish(app, event.backgroundError, usage = event.usage)
return
}
val content = event.text != null || event.thinking != null || event.entries.any { it !is Entry.Finished }
if (content && state == State.IDLE && session === from) {
main.removeCallbacks(reap)
background = true
turn = from
turnPlanned = false
state = State.WORKING
live = ""
liveThinking = ""
turnStarted = SystemClock.elapsedRealtime()
AgentHostService.start(app)
}
apply(app, event)
}
/** Ends the CLI process kept between turns, and with it whatever it still runs in the background. */
private fun dropSession() {
main.removeCallbacks(reap)
launchedBackground = false
appContext?.let { AgentHostService.backgroundDone(it) }
val kept = session ?: return
session = null
AgentProcesses.killTree(kept.pid)
kept.process.destroy()
}
/** Ends the turn now: its process and everything it started, a build included. */
fun stop(context: Context) {
val app = context.applicationContext
@@ -349,6 +428,7 @@ object AgentHost {
AgentProcesses.killTree(running.pid)
running.process.destroy()
}
dropSession()
if (state == State.WORKING) finish(app, null, stopped = true)
}
@@ -443,6 +523,10 @@ object AgentHost {
private fun finish(app: Context, error: String?, stopped: Boolean = false, usage: Usage? = null) {
if (state != State.WORKING) return
turn = null
val answeredTask = background
background = false
main.removeCallbacks(reap)
if (session != null) main.postDelayed(reap, LINGER_MS)
if (!stopped) labFromTurn = false
live = ""
liveThinking = ""
@@ -451,11 +535,11 @@ object AgentHost {
state = State.IDLE
unseen = true
failed = error != null
AgentHostService.stop(app)
if (session != null && launchedBackground) AgentHostService.waitForBackground(app) else AgentHostService.stop(app)
// Claude Code now and then ends a resumed turn at once without reading the message; nothing
// happened, so the message is sent once more.
val asked = entries.lastOrNull { it is Entry.Asked } as? Entry.Asked
if (!stopped && error == null && asked != null && answerless(entries) && !retrying) {
if (!stopped && error == null && !answeredTask && asked != null && answerless(entries) && !retrying) {
retrying = true
val retryChat = chat
resend = Runnable {
@@ -493,6 +577,7 @@ object AgentHost {
private fun record(app: Context, entry: Entry) {
if (!AgentChats.merge(entries, entry)) return
if (entry is Entry.Used && entry.background) launchedBackground = true
chat?.let { AgentChats.append(AgentChats.file(app, it), entry) }
}
@@ -645,6 +730,8 @@ object AgentHost {
/** The raw output of the latest turn, for working out what a CLI did when the chat shows nothing. */
private const val TURN_LOG = "agent/turn.log"
private const val RETRY_MS = 3_000L
/** How long the CLI process stays open after a turn, waiting for background work to wake it. */
private const val LINGER_MS = 20 * 60_000L
private fun modelKey(harness: AgentHarness) = "model_${harness.id}"
private fun limitsKey(harness: AgentHarness) = "limits_${harness.id}"
@@ -55,6 +55,23 @@ class AgentHostService : Service() {
if (awaiting == 0) context.stopService(Intent(context, AgentHostService::class.java))
}
/**
* The turn has ended but its CLI process stays open with background work that can wake it; the app must stay
* alive to read that answer, so the service keeps running until the process is dropped.
*/
@Volatile private var waiting = false
fun waitForBackground(context: Context) {
waiting = true
if (started) update(context) else start(context)
}
fun backgroundDone(context: Context) {
if (!waiting) return
waiting = false
if (AgentHost.state != AgentHost.State.WORKING) stop(context)
}
fun setupStarted(context: Context) {
setupSteps++
start(context)
@@ -80,7 +97,8 @@ class AgentHostService : Service() {
AgentSetup.detail[AgentSetup.Step.GITHUB]?.takeIf {
AgentSetup.status[AgentSetup.Step.GITHUB] == AgentSetup.Status.WORKING && it.startsWith("GitHub device code:")
}?.let { return it }
if (AgentHost.state != AgentHost.State.WORKING) return context.getString(R.string.agent_setting_up)
if (AgentHost.state != AgentHost.State.WORKING)
return context.getString(if (waiting && setupSteps == 0) R.string.agent_waiting_background else R.string.agent_setting_up)
val tool = AgentHost.running()
val elapsed = minutes((SystemClock.elapsedRealtime() - AgentHost.turnStarted) / 1000)
return if (tool != null) "${tool.tool} · ${tool.detail}".take(120) + " · $elapsed" else context.getString(R.string.agent_thinking_for, elapsed)
+1
View File
@@ -1269,6 +1269,7 @@
<string name="agent_no_reply">Ended without a reply</string>
<string name="agent_retry">Retry</string>
<string name="agent_setting_up">Setting up the agent</string>
<string name="agent_waiting_background">Waiting for background work</string>
<string name="agent_rebuild_lab">Rebuild my Lab build %1$s for the installed version of DroidDeck and restart on it.</string>
<string name="agent_tokens">%1$s in · %2$s out</string>
<string name="agent_thinking">Thinking</string>
@@ -80,6 +80,39 @@ class AgentHostTest {
assertTrue(event == null || event.entries.none { it is Entry.Finished })
}
@Test fun claudeTakesItsMessagesOverStdinSoItStaysOpen() {
val command = ClaudeCode.turn("hello there", null, AgentHarness.Options())
assertEquals("stream-json", command[command.indexOf("--input-format") + 1])
assertFalse("hello there" in command)
val line = org.json.JSONObject(ClaudeCode.input("hello there")!!)
assertEquals("user", line.getString("type"))
assertEquals("hello there", line.getJSONObject("message").getJSONArray("content").getJSONObject(0).getString("text"))
assertNull(Codex.input("hi"))
}
@Test fun aTaskNotificationResultIsMarkedBackgroundAndCarriesItsUsage() {
val event = ClaudeCode.parse("""{"type":"result","is_error":false,"session_id":"s","duration_ms":900,"total_cost_usd":0.01,"usage":{"input_tokens":3,"output_tokens":4},"origin":{"kind":"task-notification"}}""")!!
assertTrue(event.background)
assertTrue(event.entries.isEmpty())
assertEquals(4L, event.usage?.outputTokens)
assertNull(event.backgroundError)
}
@Test fun aFailedTaskNotificationResultKeepsItsError() {
val event = ClaudeCode.parse("""{"type":"result","is_error":true,"result":"API Error: overloaded","session_id":"s","usage":{"input_tokens":0,"output_tokens":0},"origin":{"kind":"task-notification"}}""")!!
assertTrue(event.background)
assertEquals("API Error: overloaded", event.backgroundError)
}
@Test fun aToolCallThatRunsInTheBackgroundIsMarked() {
fun used(tool: String, input: String) = ClaudeCode.parse(
"""{"type":"assistant","session_id":"s","message":{"content":[{"type":"tool_use","id":"t","name":"$tool","input":$input}]}}"""
)!!.entries.single() as Entry.Used
assertTrue(used("Bash", """{"command":"./gradlew test","run_in_background":true}""").background)
assertFalse(used("Bash", """{"command":"ls"}""").background)
assertTrue(used("Monitor", """{"command":"tail -f log"}""").background)
}
@Test fun claudeTurnsBypassPermissionsOrPlanAndTakeAModel() {
val first = ClaudeCode.turn("hi", null, AgentHarness.Options())
assertTrue("bypassPermissions" in first && "--resume" !in first && "--model" !in first && "--include-partial-messages" in first)