feat(agent): shipped rules and skills for every harness, with a user layer and tool health (#2682)

This commit is contained in:
Kurt Himebauch authored and GitHub committed 2026-11-15 16:40:45 -05:00
1 parent c7ff93ec19
commit b6391ed8c0
46 files changed
+478 -17

No files matched your search

@@ -35,6 +35,10 @@ interface AgentHarness {
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?
/** The folder, under the userland's root, where the CLI loads user skills (`<name>/SKILL.md`). */
val skills: String
/** The CLI's global instructions file under the userland's root, where DroidDeck keeps its rules in a marked block. */
val instructions: String
/** Sets the CLI's own defaults in the userland before it runs; [rootfs] is the userland's root. */
fun prepare(rootfs: File) {}
/** Context and plan limits the CLI keeps on disk rather than printing, read once a turn of [conversation] is done. */
@@ -83,6 +87,8 @@ object ClaudeCode : AgentHarness {
* Commits and pull requests the agent makes carry no Claude Code credit or co-author line by
* default. Only keys the user has not set are written, so their own choice stays.
*/
override val skills = "root/.claude/skills"
override val instructions = "root/.claude/CLAUDE.md"
override fun prepare(rootfs: File) {
val file = File(rootfs, "root/.claude/settings.json")
val settings = if (file.exists()) runCatching { JSONObject(file.readText()) }.getOrNull() ?: return else JSONObject()
@@ -254,6 +260,8 @@ object Codex : AgentHarness {
override val id = "codex"
override val name = "Codex"
override val binary = "/root/.local/bin/codex"
override val skills = "root/.codex/skills"
override val instructions = "root/.codex/AGENTS.md"
// Code mode runs in a helper that each release ships as its own download.
private const val HOST = "/root/.local/bin/codex-code-mode-host"
override val files get() = listOf(binary, HOST)
@@ -68,18 +68,10 @@ object AgentHost {
@VisibleForTesting
internal const val BRIEF = "You run inside DroidDeck on the user's handheld, in its Linux userland (Ubuntu under proot, aarch64), " +
"and the user talks to you from DroidDeck's Agent tab, often on a small screen, so keep replies short. " +
"droiddeckctl inspects and drives the app over loopback adb (\$ADB_SERIAL); its guide is ${AgentSetup.CTL}/agent-control.md. " +
"Steam, the desktop and games run in DroidDeck's session, a separate guest from yours: a program you start here is not in it and has no screen. " +
"Reach the session through droiddeckctl: state, start steam, stop, launch, quit, focus, screenshot, logs, and guest to run a command inside it. " +
"Starting, stopping or restarting a session leaves you running. " +
"DroidDeck's rules for working here are in your global instructions file (~/.claude/CLAUDE.md or ~/.codex/AGENTS.md); " +
"if they are not loaded, read ${AgentSetup.CTL}/AGENTS.md before acting on the device. " +
"Never kill by a command-line pattern (pkill -f, pgrep -f piped to kill): your own command line holds the user's message, so the pattern matches you. " +
"End a game with droiddeckctl quit, the session with droiddeckctl stop, anything else by its pid. " +
"dd-lab-build builds the checkout as a Lab build and restarts DroidDeck on it (docs/lab-builds.md). DroidDeck runs the build in a " +
"process of its own and shows the user its progress and time left; dd-lab-build follows that build's log until it is done. " +
"Run it with run_in_background and keep checking its output, so the user can talk to you meanwhile. " +
"The restart ends this process, and this conversation continues on the new build. " +
"Files the user attaches are listed at the end of their message, under /root/.cache/droiddeck/attachments. " +
"Commits and pull requests you make are the user's own: add no co-author line, AI credit or generated-by note. " +
"To have the user pick between options, end your reply with a fenced code block whose language is choices, one short option per line, " +
"and end your turn: DroidDeck shows them as buttons and sends the one picked as the next message."
@@ -4,6 +4,7 @@ import android.content.Context
import android.os.Handler
import android.os.Looper
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateListOf
import androidx.compose.runtime.mutableStateMapOf
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.setValue
@@ -40,7 +41,9 @@ object AgentSetup {
private val main = Handler(Looper.getMainLooper())
private const val REPO = "https://github.com/Droid-Deck/DroidDeck.git"
private const val CHECKOUT = "/root/DroidDeck"
private val HELPERS = listOf("android-open", "dd-gh-login", "droiddeckctl")
private val HELPERS = listOf("android-open", "dd-gh-login", "droiddeckctl", "droiddeck-scenario")
/** DroidDeck's own skills (tools/agent/skills), given to every harness. */
private const val SKILLS = "agent/skills"
internal const val CTL = "/root/.local/share/droiddeck/ctl"
private const val PROBE_TIMEOUT_S = 60L
@@ -187,11 +190,98 @@ object AgentSetup {
/** Written before every step, so the helpers a step relies on are there and match this DroidDeck version. */
internal fun installHelpers(app: Context) {
val root = LinuxRuntime.rootDir(app)
val failed = mutableListOf<String>()
fun attempt(what: String, block: () -> Unit) = runCatching(block).onFailure {
android.util.Log.w("AgentSetup", "could not install $what", it)
failed += what
}
val bin = File(root, "root/.local/bin").apply { mkdirs() }
for (name in HELPERS) copyAsset(app, "agent/$name", File(bin, name))
for (name in HELPERS) attempt(name) { copyAsset(app, "agent/$name", File(bin, name)) }
val ctl = File(root, CTL.removePrefix("/")).apply { mkdirs() }
for (name in app.assets.list("agent/ctl").orEmpty()) copyAsset(app, "agent/ctl/$name", File(ctl, name))
for (name in app.assets.list("agent/ctl").orEmpty()) attempt("ctl/$name") { copyAsset(app, "agent/ctl/$name", File(ctl, name)) }
val skills = app.assets.list(SKILLS).orEmpty().associateWith { app.assets.list("$SKILLS/$it").orEmpty().toList() }
failed += installSkills(root, skills) { app.assets.open("$SKILLS/$it") }
attempt("AGENTS.md") {
val rules = app.assets.open("agent/ctl/AGENTS.md").use { it.readBytes().decodeToString() }
failed += installInstructions(root, rules)
}
unpinAdbSerial(File(root, "root/.bashrc"))
main.post { problems.clear(); problems.addAll(failed.distinct()) }
}
/** What [installHelpers] could not install last time, shown in the Agent tab; empty when all is in place. */
val problems = mutableStateListOf<String>()
/**
* Writes each of DroidDeck's [skills] (name to its files) into every harness's skills folder, so
* Claude Code, Codex and any later harness load the same ones, as of this DroidDeck version.
* Skills the user added there are left alone. Returns the skills that could not be written.
*/
internal fun installSkills(root: File, skills: Map<String, List<String>>, open: (String) -> java.io.InputStream): List<String> {
val failed = mutableListOf<String>()
for (harness in AgentHarness.all) for ((name, files) in skills) runCatching {
val dir = File(root, "${harness.skills}/$name")
// A folder of that name without DroidDeck's mark is the user's own skill: keep it.
if (dir.exists() && !File(dir, SKILL_MARK).exists()) return@runCatching
dir.mkdirs()
// Marked before copying, so a copy that fails part way is retried next turn, not taken for the user's.
File(dir, SKILL_MARK).writeText("Installed by DroidDeck and replaced on every turn. Delete this file to keep your own edits.\n")
for (file in files) open("$name/$file").use { replaceFile(it, File(dir, file), executable = false) }
}.onFailure {
android.util.Log.w("AgentSetup", "could not install skill $name for ${harness.name}", it)
failed += "skill $name"
}
return failed
}
/** Marks a skill folder as DroidDeck's, so it may be replaced; one without it belongs to the user. */
internal const val SKILL_MARK = ".droiddeck"
/**
* Where [file] really is when it is a symlink, as the guest sees it: an absolute target is a
* userland path, so it is looked up under [root]. A dotfiles link keeps working that way.
*/
internal fun guestTarget(root: File, file: File): File {
var current = file
repeat(8) {
val path = current.toPath()
if (!java.nio.file.Files.isSymbolicLink(path)) return current
val target = java.nio.file.Files.readSymbolicLink(path).toString()
current = if (target.startsWith("/")) File(root, target.removePrefix("/")) else File(current.parentFile, target)
}
return current
}
internal const val BLOCK_BEGIN = "<!-- BEGIN DroidDeck: replaced on every turn. Write your own rules outside this block. -->"
internal const val BLOCK_END = "<!-- END DroidDeck -->"
/**
* Puts DroidDeck's [rules] in a marked block of every harness's global instructions file,
* keeping whatever the user wrote around it. Returns the files that could not be written.
*/
internal fun installInstructions(root: File, rules: String): List<String> {
val failed = mutableListOf<String>()
for (harness in AgentHarness.all) runCatching {
val file = guestTarget(root, File(root, harness.instructions)).apply { parentFile?.mkdirs() }
val existing = if (file.exists()) file.readText() else null
val merged = withBlock(existing, rules)
if (merged != existing) replaceFile(merged.byteInputStream(), file, executable = false)
}.onFailure {
android.util.Log.w("AgentSetup", "could not write ${harness.instructions}", it)
failed += harness.instructions.substringAfterLast("root/")
}
return failed
}
/** [existing] with DroidDeck's block set to [rules]: replaced in place, or put first when there is none yet. */
internal fun withBlock(existing: String?, rules: String): String {
val block = "$BLOCK_BEGIN\n${rules.trim()}\n$BLOCK_END\n"
if (existing.isNullOrBlank()) return block
val start = existing.indexOf(BLOCK_BEGIN)
val end = existing.indexOf(BLOCK_END, start.coerceAtLeast(0))
if (start < 0 || end < 0) return "$block\n$existing"
val after = existing.substring(end + BLOCK_END.length).removePrefix("\n")
return existing.substring(0, start) + block + after
}
/** Older tools/agent/setup pinned the adb port in .bashrc, which overrides the live port DroidDeck passes. */
@@ -201,8 +291,24 @@ object AgentSetup {
if (fixed != text) runCatching { bashrc.writeText(fixed) }
}
/**
* Written beside [target] and renamed over it, so a symlink left there by a hand-made setup is
* replaced rather than followed: its absolute target is a userland path the app cannot reach,
* and the failed write stopped every helper after it, the droiddeckctl guide included.
*/
private fun copyAsset(app: Context, asset: String, target: File) {
app.assets.open(asset).use { input -> target.outputStream().use { input.copyTo(it) } }
target.setExecutable(true, false)
app.assets.open(asset).use { replaceFile(it, target) }
}
/** Replaces [target], or the symlink at it, with [input]. */
internal fun replaceFile(input: java.io.InputStream, target: File, executable: Boolean = true) {
// A unique name, since an agent turn and a setup step can install at the same time.
val staged = File.createTempFile(".${target.name}.", ".part", target.parentFile)
staged.outputStream().use { input.copyTo(it) }
if (executable) staged.setExecutable(true, false)
if (!staged.renameTo(target)) {
staged.delete()
throw java.io.IOException("could not replace $target")
}
}
}
@@ -567,7 +567,8 @@ private fun labStage(lab: com.droiddeck.launcher.agent.LabProgress) = when (lab.
else -> stringResource(R.string.agent_lab_stage_starting)
}
private fun hasActivity() = AgentHost.lab != null || AgentHost.queue.isNotEmpty() || currentTodo() != null
private fun hasActivity() = AgentHost.lab != null || AgentHost.queue.isNotEmpty() || currentTodo() != null ||
com.droiddeck.launcher.agent.AgentSetup.problems.isNotEmpty()
/** The todo item in progress and how many are done, while the agent works through a list. */
private fun currentTodo(): String? {
@@ -594,6 +595,11 @@ private fun AgentActivity(labOpen: Boolean, onLab: () -> Unit) {
Text(todo, fontSize = 12.5.sp, color = pal.onSurfaceVariant, maxLines = 1, overflow = TextOverflow.Ellipsis, modifier = Modifier.widthIn(max = 220.dp))
}
}
val problems = com.droiddeck.launcher.agent.AgentSetup.problems
if (problems.isNotEmpty()) AgentChip(warn = true, tag = "agent-tools-missing") {
Text(stringResource(R.string.agent_tools_missing, problems.joinToString(", ")), fontSize = 12.5.sp, color = AttentionAmber,
maxLines = 2, overflow = TextOverflow.Ellipsis, modifier = Modifier.widthIn(max = 260.dp))
}
for (queued in AgentHost.queue) AgentChip(warn = true) {
Text(stringResource(R.string.agent_queued, queued.text), fontSize = 12.5.sp, color = AttentionAmber, maxLines = 1,
overflow = TextOverflow.Ellipsis, modifier = Modifier.widthIn(max = 180.dp))