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

+3 -1
View File
@@ -278,8 +278,10 @@ def stageRuntimeAssets = tasks.register('stageRuntimeAssets', Sync) {
dependsOn(stageSessionScripts)
from(layout.projectDirectory.dir('src/main/assets')) { exclude 'pulseaudio.tzst' }
from(rootProject.file('tools/linuxfs/innoextract'))
from(rootProject.file('tools')) { include 'droiddeckctl', 'adb_device.py', 'proot_profile.py'; into('agent/ctl') }
from(rootProject.file('tools')) { include 'droiddeckctl', 'droiddeck-scenario', 'adb_device.py', 'proot_profile.py'; into('agent/ctl') }
from(rootProject.file('tools/agent/AGENTS.md')) { into('agent/ctl') }
from(rootProject.file('docs/agent-control.md')) { into('agent/ctl') }
from(rootProject.file('tools/agent/skills')) { into('agent/skills') }
from(layout.buildDirectory.dir('prepared-assets'))
into(runtimeAssetsDir)
}
+2
View File
@@ -0,0 +1,2 @@
#!/bin/sh
exec python3 /root/.local/share/droiddeck/ctl/droiddeck-scenario "$@"
@@ -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))
+1
View File
@@ -1195,6 +1195,7 @@
<string name="agent_hint_working">اكتب لإضافة الرسالة التالية إلى الانتظار</string>
<string name="agent_queue">إضافة إلى الانتظار</string>
<string name="agent_queued">التالي: %1$s</string>
<string name="agent_tools_missing">أدوات الوكيل غير مثبتة: %1$s</string>
<string name="agent_unqueue">لا تُرسل</string>
<string name="agent_attach">إرفاق</string>
<string name="agent_remove_attachment">إزالة</string>
@@ -1213,6 +1213,7 @@
<string name="agent_hint_working">Escribe para encolar el siguiente mensaje</string>
<string name="agent_queue">Encolar</string>
<string name="agent_queued">Siguiente: %1$s</string>
<string name="agent_tools_missing">Herramientas del agente sin instalar: %1$s</string>
<string name="agent_unqueue">No enviar</string>
<string name="agent_attach">Adjuntar</string>
<string name="agent_remove_attachment">Quitar</string>
+1
View File
@@ -1183,6 +1183,7 @@
<string name="agent_hint_working">Въведете, за да наредите следващото съобщение</string>
<string name="agent_queue">В опашката</string>
<string name="agent_queued">Следващо: %1$s</string>
<string name="agent_tools_missing">Инструментите на агента не са инсталирани: %1$s</string>
<string name="agent_unqueue">Не изпращай</string>
<string name="agent_attach">Прикачи</string>
<string name="agent_remove_attachment">Премахни</string>
+1
View File
@@ -1189,6 +1189,7 @@
<string name="agent_hint_working">Psaním zařadíte další zprávu do fronty</string>
<string name="agent_queue">Zařadit do fronty</string>
<string name="agent_queued">Další: %1$s</string>
<string name="agent_tools_missing">Nástroje agenta nejsou nainstalované: %1$s</string>
<string name="agent_unqueue">Neposílat</string>
<string name="agent_attach">Přiložit</string>
<string name="agent_remove_attachment">Odebrat</string>
+1
View File
@@ -1183,6 +1183,7 @@
<string name="agent_hint_working">Skriv for at sætte den næste besked i kø</string>
<string name="agent_queue">Sæt i kø</string>
<string name="agent_queued">Næste: %1$s</string>
<string name="agent_tools_missing">Agentens værktøjer er ikke installeret: %1$s</string>
<string name="agent_unqueue">Send ikke</string>
<string name="agent_attach">Vedhæft</string>
<string name="agent_remove_attachment">Fjern</string>
+1
View File
@@ -1175,6 +1175,7 @@
<string name="agent_hint_working">Tippen, um die nächste Nachricht einzureihen</string>
<string name="agent_queue">Einreihen</string>
<string name="agent_queued">Als Nächstes: %1$s</string>
<string name="agent_tools_missing">Agent-Werkzeuge nicht installiert: %1$s</string>
<string name="agent_unqueue">Nicht senden</string>
<string name="agent_attach">Anhängen</string>
<string name="agent_remove_attachment">Entfernen</string>
+1
View File
@@ -1183,6 +1183,7 @@
<string name="agent_hint_working">Γράψτε για να προσθέσετε το επόμενο μήνυμα στην ουρά</string>
<string name="agent_queue">Στην ουρά</string>
<string name="agent_queued">Επόμενο: %1$s</string>
<string name="agent_tools_missing">Τα εργαλεία του πράκτορα δεν εγκαταστάθηκαν: %1$s</string>
<string name="agent_unqueue">Να μην σταλεί</string>
<string name="agent_attach">Επισύναψη</string>
<string name="agent_remove_attachment">Αφαίρεση</string>
+1
View File
@@ -1186,6 +1186,7 @@
<string name="agent_hint_working">Escribe para encolar el siguiente mensaje</string>
<string name="agent_queue">Encolar</string>
<string name="agent_queued">Siguiente: %1$s</string>
<string name="agent_tools_missing">Herramientas del agente sin instalar: %1$s</string>
<string name="agent_unqueue">No enviar</string>
<string name="agent_attach">Adjuntar</string>
<string name="agent_remove_attachment">Quitar</string>
+1
View File
@@ -1183,6 +1183,7 @@
<string name="agent_hint_working">Kirjoita lisätäksesi seuraavan viestin jonoon</string>
<string name="agent_queue">Jono</string>
<string name="agent_queued">Seuraava: %1$s</string>
<string name="agent_tools_missing">Agentin työkaluja ei ole asennettu: %1$s</string>
<string name="agent_unqueue">Älä lähetä</string>
<string name="agent_attach">Liitä</string>
<string name="agent_remove_attachment">Poista</string>
+1
View File
@@ -1186,6 +1186,7 @@
<string name="agent_hint_working">Tapez pour mettre le prochain message en attente</string>
<string name="agent_queue">Mettre en attente</string>
<string name="agent_queued">Suivant : %1$s</string>
<string name="agent_tools_missing">Outils de l’agent non installés : %1$s</string>
<string name="agent_unqueue">Ne pas envoyer</string>
<string name="agent_attach">Joindre</string>
<string name="agent_remove_attachment">Supprimer</string>
+1
View File
@@ -1183,6 +1183,7 @@
<string name="agent_hint_working">अगला संदेश कतार में जोड़ने के लिए टाइप करें</string>
<string name="agent_queue">कतार में जोड़ें</string>
<string name="agent_queued">अगला: %1$s</string>
<string name="agent_tools_missing">एजेंट टूल इंस्टॉल नहीं हुए: %1$s</string>
<string name="agent_unqueue">न भेजें</string>
<string name="agent_attach">संलग्न करें</string>
<string name="agent_remove_attachment">हटाएँ</string>
+1
View File
@@ -1183,6 +1183,7 @@
<string name="agent_hint_working">Gépelj a következő üzenet sorba állításához</string>
<string name="agent_queue">Sorba állítás</string>
<string name="agent_queued">Következő: %1$s</string>
<string name="agent_tools_missing">Az ügynök eszközei nincsenek telepítve: %1$s</string>
<string name="agent_unqueue">Ne küldd el</string>
<string name="agent_attach">Csatolás</string>
<string name="agent_remove_attachment">Eltávolítás</string>
+1
View File
@@ -1180,6 +1180,7 @@
<string name="agent_hint_working">Ketik untuk mengantrekan pesan berikutnya</string>
<string name="agent_queue">Antrekan</string>
<string name="agent_queued">Berikutnya: %1$s</string>
<string name="agent_tools_missing">Alat agen tidak terpasang: %1$s</string>
<string name="agent_unqueue">Jangan kirim</string>
<string name="agent_attach">Lampirkan</string>
<string name="agent_remove_attachment">Hapus</string>
+1
View File
@@ -1178,6 +1178,7 @@
<string name="agent_hint_working">Digita per mettere in coda il messaggio successivo</string>
<string name="agent_queue">Metti in coda</string>
<string name="agent_queued">Prossimo: %1$s</string>
<string name="agent_tools_missing">Strumenti dell’agente non installati: %1$s</string>
<string name="agent_unqueue">Non inviare</string>
<string name="agent_attach">Allega</string>
<string name="agent_remove_attachment">Rimuovi</string>
+1
View File
@@ -1180,6 +1180,7 @@
<string name="agent_hint_working">入力すると次のメッセージをキューに追加できます</string>
<string name="agent_queue">キューに追加</string>
<string name="agent_queued">次: %1$s</string>
<string name="agent_tools_missing">エージェントのツールが未インストール: %1$s</string>
<string name="agent_unqueue">送信しない</string>
<string name="agent_attach">添付</string>
<string name="agent_remove_attachment">削除</string>
+1
View File
@@ -1180,6 +1180,7 @@
<string name="agent_hint_working">입력하면 다음 메시지가 대기열에 추가됩니다</string>
<string name="agent_queue">대기열에 추가</string>
<string name="agent_queued">다음: %1$s</string>
<string name="agent_tools_missing">에이전트 도구가 설치되지 않음: %1$s</string>
<string name="agent_unqueue">보내지 않기</string>
<string name="agent_attach">첨부</string>
<string name="agent_remove_attachment">제거</string>
+1
View File
@@ -1180,6 +1180,7 @@
<string name="agent_hint_working">Taip untuk membariskan mesej seterusnya</string>
<string name="agent_queue">Baris gilir</string>
<string name="agent_queued">Seterusnya: %1$s</string>
<string name="agent_tools_missing">Alat ejen tidak dipasang: %1$s</string>
<string name="agent_unqueue">Jangan hantar</string>
<string name="agent_attach">Lampirkan</string>
<string name="agent_remove_attachment">Alih keluar</string>
+1
View File
@@ -1183,6 +1183,7 @@
<string name="agent_hint_working">Skriv for å legge neste melding i kø</string>
<string name="agent_queue">Legg i kø</string>
<string name="agent_queued">Neste: %1$s</string>
<string name="agent_tools_missing">Agentverktøy er ikke installert: %1$s</string>
<string name="agent_unqueue">Ikke send</string>
<string name="agent_attach">Legg ved</string>
<string name="agent_remove_attachment">Fjern</string>
+1
View File
@@ -1183,6 +1183,7 @@
<string name="agent_hint_working">Typ om het volgende bericht in de wachtrij te zetten</string>
<string name="agent_queue">In wachtrij</string>
<string name="agent_queued">Volgende: %1$s</string>
<string name="agent_tools_missing">Agenttools niet geïnstalleerd: %1$s</string>
<string name="agent_unqueue">Niet verzenden</string>
<string name="agent_attach">Bijvoegen</string>
<string name="agent_remove_attachment">Verwijderen</string>
+1
View File
@@ -1189,6 +1189,7 @@
<string name="agent_hint_working">Wpisz, aby zakolejkować następną wiadomość</string>
<string name="agent_queue">Zakolejkuj</string>
<string name="agent_queued">Następna: %1$s</string>
<string name="agent_tools_missing">Narzędzia agenta nie są zainstalowane: %1$s</string>
<string name="agent_unqueue">Nie wysyłaj</string>
<string name="agent_attach">Załącz</string>
<string name="agent_remove_attachment">Usuń</string>
@@ -1178,6 +1178,7 @@
<string name="agent_hint_working">Escreva para pôr a mensagem seguinte na fila</string>
<string name="agent_queue">Pôr na fila</string>
<string name="agent_queued">Seguinte: %1$s</string>
<string name="agent_tools_missing">Ferramentas do agente não instaladas: %1$s</string>
<string name="agent_unqueue">Não enviar</string>
<string name="agent_attach">Anexar</string>
<string name="agent_remove_attachment">Remover</string>
+1
View File
@@ -1185,6 +1185,7 @@
<string name="agent_hint_working">Digite para enfileirar a próxima mensagem</string>
<string name="agent_queue">Enfileirar</string>
<string name="agent_queued">Próxima: %1$s</string>
<string name="agent_tools_missing">Ferramentas do agente não instaladas: %1$s</string>
<string name="agent_unqueue">Não enviar</string>
<string name="agent_attach">Anexar</string>
<string name="agent_remove_attachment">Remover</string>
+1
View File
@@ -1186,6 +1186,7 @@
<string name="agent_hint_working">Scrie pentru a pune următorul mesaj în coadă</string>
<string name="agent_queue">Pune în coadă</string>
<string name="agent_queued">Următorul: %1$s</string>
<string name="agent_tools_missing">Instrumentele agentului nu sunt instalate: %1$s</string>
<string name="agent_unqueue">Nu trimite</string>
<string name="agent_attach">Atașează</string>
<string name="agent_remove_attachment">Elimină</string>
+1
View File
@@ -1189,6 +1189,7 @@
<string name="agent_hint_working">Введите текст, чтобы поставить следующее сообщение в очередь</string>
<string name="agent_queue">В очередь</string>
<string name="agent_queued">Далее: %1$s</string>
<string name="agent_tools_missing">Инструменты агента не установлены: %1$s</string>
<string name="agent_unqueue">Не отправлять</string>
<string name="agent_attach">Прикрепить</string>
<string name="agent_remove_attachment">Удалить</string>
+1
View File
@@ -1183,6 +1183,7 @@
<string name="agent_hint_working">Skriv för att köa nästa meddelande</string>
<string name="agent_queue">Köa</string>
<string name="agent_queued">Nästa: %1$s</string>
<string name="agent_tools_missing">Agentens verktyg är inte installerade: %1$s</string>
<string name="agent_unqueue">Skicka inte</string>
<string name="agent_attach">Bifoga</string>
<string name="agent_remove_attachment">Ta bort</string>
+1
View File
@@ -1180,6 +1180,7 @@
<string name="agent_hint_working">พิมพ์เพื่อเข้าคิวข้อความถัดไป</string>
<string name="agent_queue">เข้าคิว</string>
<string name="agent_queued">ถัดไป: %1$s</string>
<string name="agent_tools_missing">ยังไม่ได้ติดตั้งเครื่องมือของเอเจนต์: %1$s</string>
<string name="agent_unqueue">ไม่ต้องส่ง</string>
<string name="agent_attach">แนบ</string>
<string name="agent_remove_attachment">นำออก</string>
+1
View File
@@ -1175,6 +1175,7 @@
<string name="agent_hint_working">Sonraki mesajı sıraya almak için yazın</string>
<string name="agent_queue">Sıraya ekle</string>
<string name="agent_queued">Sıradaki: %1$s</string>
<string name="agent_tools_missing">Ajan araçları yüklenmedi: %1$s</string>
<string name="agent_unqueue">Gönderme</string>
<string name="agent_attach">Ekle</string>
<string name="agent_remove_attachment">Kaldır</string>
+1
View File
@@ -1189,6 +1189,7 @@
<string name="agent_hint_working">Введіть текст, щоб поставити наступне повідомлення в чергу</string>
<string name="agent_queue">Поставити в чергу</string>
<string name="agent_queued">Далі: %1$s</string>
<string name="agent_tools_missing">Інструменти агента не встановлено: %1$s</string>
<string name="agent_unqueue">Не надсилати</string>
<string name="agent_attach">Прикріпити</string>
<string name="agent_remove_attachment">Видалити</string>
+1
View File
@@ -1180,6 +1180,7 @@
<string name="agent_hint_working">Nhập để xếp tin nhắn tiếp theo vào hàng đợi</string>
<string name="agent_queue">Xếp hàng</string>
<string name="agent_queued">Tiếp theo: %1$s</string>
<string name="agent_tools_missing">Chưa cài công cụ của tác tử: %1$s</string>
<string name="agent_unqueue">Không gửi</string>
<string name="agent_attach">Đính kèm</string>
<string name="agent_remove_attachment">Xóa</string>
@@ -1263,6 +1263,7 @@
<string name="agent_hint_working">输入以排队下一条消息</string>
<string name="agent_queue">排队</string>
<string name="agent_queued">下一条:%1$s</string>
<string name="agent_tools_missing">智能体工具未安装:%1$s</string>
<string name="agent_unqueue">不发送</string>
<string name="agent_attach">添加附件</string>
<string name="agent_remove_attachment">移除</string>
@@ -1179,6 +1179,7 @@
<string name="agent_hint_working">輸入即可排入下一則訊息</string>
<string name="agent_queue">排入</string>
<string name="agent_queued">下一則:%1$s</string>
<string name="agent_tools_missing">智能體工具未安裝:%1$s</string>
<string name="agent_unqueue">不要傳送</string>
<string name="agent_attach">附加</string>
<string name="agent_remove_attachment">移除</string>
@@ -1179,6 +1179,7 @@
<string name="agent_hint_working">輸入以排入下一則訊息</string>
<string name="agent_queue">排入佇列</string>
<string name="agent_queued">下一則:%1$s</string>
<string name="agent_tools_missing">智慧代理工具未安裝:%1$s</string>
<string name="agent_unqueue">不要傳送</string>
<string name="agent_attach">附加</string>
<string name="agent_remove_attachment">移除</string>
+1
View File
@@ -1284,6 +1284,7 @@
<string name="agent_hint_working">Type to queue the next message</string>
<string name="agent_queue">Queue</string>
<string name="agent_queued">Next: %1$s</string>
<string name="agent_tools_missing">Agent tools not installed: %1$s</string>
<string name="agent_unqueue">Don\'t send</string>
<string name="agent_attach">Attach</string>
<string name="agent_remove_attachment">Remove</string>
@@ -0,0 +1,117 @@
package com.droiddeck.launcher.agent
import org.junit.Assert.assertEquals
import org.junit.Assert.assertFalse
import org.junit.Assert.assertTrue
import org.junit.Rule
import org.junit.Test
import org.junit.rules.TemporaryFolder
import java.io.File
import java.nio.file.Files
class AgentHelpersTest {
@get:Rule val tmp = TemporaryFolder()
@Test fun aSymlinkLeftByAHandMadeSetupIsReplacedNotFollowed() {
val bin = tmp.newFolder("bin")
val old = tmp.newFile("old-droiddeckctl").apply { writeText("old") }
val target = File(bin, "droiddeckctl")
Files.createSymbolicLink(target.toPath(), old.toPath())
AgentSetup.replaceFile("new".byteInputStream(), target)
assertFalse(Files.isSymbolicLink(target.toPath()))
assertEquals("new", target.readText())
assertEquals("old", old.readText())
assertTrue(target.canExecute())
}
@Test fun aDanglingSymlinkIsReplaced() {
val bin = tmp.newFolder("bin")
val target = File(bin, "droiddeckctl")
Files.createSymbolicLink(target.toPath(), File("/no/such/userland/path").toPath())
AgentSetup.replaceFile("new".byteInputStream(), target)
assertEquals("new", target.readText())
assertEquals(listOf("droiddeckctl"), bin.list()!!.toList())
}
@Test fun skillsGoToEveryHarnessAndLeaveTheUsersOwnAlone() {
val root = tmp.newFolder("rootfs")
val mine = File(root, "root/.claude/skills/my-skill/SKILL.md").apply { parentFile!!.mkdirs(); writeText("mine") }
val stale = File(root, "root/.codex/skills/diagnose-game/SKILL.md").apply { parentFile!!.mkdirs(); writeText("old") }
File(stale.parentFile, AgentSetup.SKILL_MARK).writeText("")
val failed = AgentSetup.installSkills(root, mapOf("diagnose-game" to listOf("SKILL.md"))) { "new $it".byteInputStream() }
assertEquals(emptyList<String>(), failed)
for (harness in AgentHarness.all) {
assertEquals("new diagnose-game/SKILL.md", File(root, "${harness.skills}/diagnose-game/SKILL.md").readText())
}
assertEquals("mine", mine.readText())
assertFalse(File(root, "${ClaudeCode.skills}/diagnose-game/SKILL.md").canExecute())
}
@Test fun aSkillTheUserMadeWithTheSameNameIsKept() {
val root = tmp.newFolder("rootfs3")
val own = File(root, "${ClaudeCode.skills}/diagnose-game/SKILL.md").apply { parentFile!!.mkdirs(); writeText("my version") }
AgentSetup.installSkills(root, mapOf("diagnose-game" to listOf("SKILL.md"))) { "new".byteInputStream() }
assertEquals("my version", own.readText())
assertFalse(File(own.parentFile, AgentSetup.SKILL_MARK).exists())
assertEquals("new", File(root, "${Codex.skills}/diagnose-game/SKILL.md").readText())
}
@Test fun aSkillThatFailedPartWayIsRetriedNextTurn() {
val root = tmp.newFolder("rootfs5")
val skills = mapOf("diagnose-game" to listOf("SKILL.md"))
val failed = AgentSetup.installSkills(root, skills) { throw java.io.IOException("asset unreadable") }
assertEquals(AgentHarness.all.size, failed.size)
assertEquals(emptyList<String>(), AgentSetup.installSkills(root, skills) { "new".byteInputStream() })
for (harness in AgentHarness.all) assertEquals("new", File(root, "${harness.skills}/diagnose-game/SKILL.md").readText())
}
@Test fun instructionsBehindAGuestSymlinkAreWrittenWhereItPoints() {
val root = tmp.newFolder("rootfs4")
val dotfile = File(root, "root/dotfiles/CLAUDE.md").apply { parentFile!!.mkdirs(); writeText("my rule\n") }
val link = File(root, ClaudeCode.instructions).apply { parentFile!!.mkdirs() }
Files.createSymbolicLink(link.toPath(), File("/root/dotfiles/CLAUDE.md").toPath())
AgentSetup.installInstructions(root, "rules")
assertTrue(Files.isSymbolicLink(link.toPath()))
assertTrue(dotfile.readText().contains("rules"))
assertTrue(dotfile.readText().endsWith("\nmy rule\n"))
}
@Test fun theRulesGoFirstInAFileThatHasNoBlockYetAndKeepTheUsersOwn() {
val text = AgentSetup.withBlock("# Mine\nAlways answer in French.\n", "rules v1")
assertEquals("${AgentSetup.BLOCK_BEGIN}\nrules v1\n${AgentSetup.BLOCK_END}\n\n# Mine\nAlways answer in French.\n", text)
}
@Test fun onlyTheBlockIsReplacedOnTheNextTurn() {
val first = AgentSetup.withBlock("before\n", "rules v1") + "after\n"
val second = AgentSetup.withBlock(first, "rules v2")
assertEquals(first.replace("rules v1", "rules v2"), second)
assertEquals(second, AgentSetup.withBlock(second, "rules v2"))
}
@Test fun anEmptyOrMissingFileGetsJustTheBlock() {
assertEquals("${AgentSetup.BLOCK_BEGIN}\nrules\n${AgentSetup.BLOCK_END}\n", AgentSetup.withBlock(null, "rules\n"))
assertEquals(AgentSetup.withBlock(null, "rules"), AgentSetup.withBlock(" \n", "rules"))
}
@Test fun everyHarnessGetsTheRules() {
val root = tmp.newFolder("rootfs2")
val claude = File(root, ClaudeCode.instructions).apply { parentFile!!.mkdirs(); writeText("my rule\n") }
assertEquals(emptyList<String>(), AgentSetup.installInstructions(root, "rules"))
for (harness in AgentHarness.all) assertTrue(File(root, harness.instructions).readText().contains("rules"))
assertTrue(claude.readText().endsWith("\nmy rule\n"))
}
}
+12
View File
@@ -22,6 +22,18 @@ and reports every run.
works on every display and window. UI Automator, by contrast, dumps whichever window has focus,
which on a dual-screen device is often another app's.
## On the device
The agent in DroidDeck's Agent tab gets its working rules from `tools/agent/AGENTS.md` and its
skills from `tools/agent/skills`. Both ship in the APK; before every turn the app writes the rules
as a marked block into each harness's global instructions (`~/.claude/CLAUDE.md`,
`~/.codex/AGENTS.md`) and the skills into its skills folder (`~/.claude/skills`, `~/.codex/skills`).
Only DroidDeck's own block and skills (folders holding a `.droiddeck` file) are replaced: rules
the user writes outside the block, and skills they add, stay. A symlinked instructions file is
followed, so the block lands in the file it points to. `droiddeckctl`, `droiddeck-scenario` and this guide are installed in
`~/.local/share/droiddeck/ctl` (with `droiddeckctl` and `droiddeck-scenario` on PATH). If any of
these cannot be installed, the Agent tab shows which.
## Access
Player controls and observations work over authorized ADB on any build: `state`, `start`, `stop`,
+74
View File
@@ -0,0 +1,74 @@
# DroidDeck on-device agent
You run in DroidDeck's Agent tab, on the user's handheld, in DroidDeck's Linux userland (Ubuntu
under proot, aarch64). The user is often on a small screen: keep replies short. These notes come
from what tripped agents up on real devices.
## Where you run
- 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 it with `droiddeckctl` (guide:
`/root/.local/share/droiddeck/ctl/agent-control.md`): `state`, `start steam`, `stop`, `launch`,
`quit`, `focus`, `screenshot`, `logs`, `pacing`, `thermal`, and `guest` to run a command in it.
- `droiddeckctl stop`, `start steam` and `resume` end or restart only the session. You keep
running, so restart it yourself when a change needs a new session.
- The session shares your filesystem. Steam is in `/root/.local/share/Steam` (its logs in
`logs/`), and the session's live logs are in the folder `state` gives as `session.logDir`.
`logs latest` makes a redacted, partial copy: read the live folder yourself. X properties,
gamescope and the session's processes are only reachable through `guest`.
## Commands
- `guest` runs one program, not a shell line: `droiddeckctl guest -- sh -c '...'` for pipes,
`$(...)` or `DISPLAY=:0 xprop ...`. Its answer is JSON; the output is in `stdout.text`.
- `screenshot` takes the path as an argument (`screenshot /tmp/top.png --display 0`); on a
dual-screen device see `droiddeckctl displays`. `prefs get` takes a file (`prefs get session`).
- `input` drives a game session that has drawn a frame. For the launcher's own screens use
`adb -s $ADB_SERIAL shell input keyevent KEYCODE_BACK` and similar.
- `droiddeck-scenario` replays a scripted test through `droiddeckctl` (`--help` for the format).
- 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 after checking what it is
(`ps -o pid,args -p <pid>`): a pid near a game can be the Steam client.
- `DEVICE_RESOLUTION_FAILED`: run `adb devices` and use the serial it lists.
- Do not chain `sleep` before a check. Start long work in the background. In Claude Code, its end
starts you again; other harnesses are not woken, so check it before ending your turn or tell the
user it is still running.
## What applies when
- Many session settings (black frame insertion, environment, Proton) are read when a session or
game starts. After changing one, restart the game or the session before judging it.
- With "Return after game" on (the default), quitting a game DroidDeck launched ends the whole
session; `start steam --wait --reuse` before the next launch. Launching a game that is already
running makes Steam show "Game already running" and `launch` time out.
- Session scripts are APK assets, copied into the rootfs at every session start over any local
edit. A Lab build (`dd-lab-build`, see `docs/lab-builds.md`) carries app code and resources only:
session scripts, native code and assets need a new APK, such as the pull request's CI test build
(DroidDeck > Updates > Test builds).
## Changing DroidDeck
The source is checked out at `/root/DroidDeck` once the Agent tab's build tools are set up.
- It often holds the user's uncommitted work and a stale local `main`. Branch from `origin/main`
in a worktree (`git worktree add -b <branch> ../<dir> origin/main`).
- `dd-lab-build` builds the checkout as a Lab build and restarts DroidDeck on it. DroidDeck runs the
build in a process of its own and shows its progress; `dd-lab-build` follows its log. Run it in
the background and keep checking, so the user can talk to you meanwhile. The restart ends your
process, and the conversation continues on the new build.
- Python tests run from the repository root: `python3 -m unittest tools.tests.test_x`. Some fail on
the device on `origin/main` too; run them on a worktree of `origin/main` before blaming a change.
- Gradle unit tests rarely run on the device. Leave them to CI and say so rather than retrying.
- If `git push` asks for credentials, run `gh auth setup-git` once.
- Commits and pull requests you make are the user's own: no co-author line, AI credit or
generated-by note.
## This file
DroidDeck writes this block into your global instructions (`~/.claude/CLAUDE.md`,
`~/.codex/AGENTS.md`) before every turn, and its skills into `~/.claude/skills` and
`~/.codex/skills`. It replaces only its own block and its own skills (folders holding a `.droiddeck` file): the
user's rules go outside the block, and their skills stay, even one with the same name. Deleting a
skill's `.droiddeck` file keeps local edits to it. To change DroidDeck's, edit `tools/agent/AGENTS.md` and
`tools/agent/skills` in the source.
+3
View File
@@ -19,6 +19,9 @@ for arg in "$@"; do
--no-restart) mode=no-restart ;;
--prepare) mode=prepare ;;
--explain) explain=(--info -Pkotlin.build.report.output=file) ;;
# Anything else used to start a full build and restart the app, --help included.
-h|--help) sed -n '2,6s/^# \{0,1\}//p' "$0"; exit 0 ;;
*) echo "dd-lab-build: unknown option $arg (see --help)" >&2; exit 2 ;;
esac
done
started=$(date +%s)
+41
View File
@@ -0,0 +1,41 @@
---
name: diagnose-game
description: Find why a game crashed, hung or ran badly in DroidDeck, from session state and logs
---
1. `droiddeckctl state`: `session.phase`, `session.failure`, `session.focus.focusedApp` (769 is
Steam's own UI) and `session.logDir`.
2. Read that log folder directly; it is on your filesystem. Earlier sessions are its siblings:
`ls -t "$(dirname <logDir>)"`; the crash may be in the one before a restart. `logs latest`
makes a redacted, partial copy with renamed files: use it only to hand logs to someone.
- `games/<time>-<id>-<appid>/`, one folder per launch: `launch.txt` (exe, Proton, environment)
and `steam-<appid>.log` (Proton and Wine).
- `session.log` (the session script, `== ` lines), `wayland.log` (compositor), `app.log`,
`events.jsonl`, `crash.log` (Android's crash buffer at session end), `memory-pressure.log`
(low-memory kills), `graphics-report.txt`, `vulkan-summary.txt`, `steam/` (client logs).
- The game's own log is in its prefix,
`/root/.local/share/Steam/steamapps/compatdata/<appid>/pfx/drive_c/users/steamuser/`:
Unity writes `AppData/LocalLow/<company>/<game>/Player.log`, Unreal
`AppData/Local/<game>/Saved/Logs/`.
3. Find the fatal error, not the first `err:`. Every run logs harmless ones (`err:nsi` bind
errno 13, `err:hid`, `winebth`, `tabtip`, `overriding CPU configuration`), and `trace:seh`
first-chance exceptions are often handled. Look for the last exception before the process ends:
`grep -nE "EXCEPTION_ACCESS_VIOLATION|Unhandled exception|virtual_setup_exception|DEVICE_LOST|VK_ERROR" steam-<appid>.log`.
Same address in every launch means a deterministic fault; compare with an older launch that
worked before blaming a line.
4. For performance, `droiddeckctl pacing --seconds 20` (`fpsOnScreen`, `offCadencePercent`) and
`droiddeckctl thermal`: at `SEVERE` or worse the device is throttling, so say that first.
5. Explain the cause in plain words with the lines that show it (file and line number). Propose
the smallest reversible change and ask before applying it:
- Proton for one game: list `/root/.local/share/Steam/compatibilitytools.d` and
`steamapps/common/Proton*`, then
`droiddeckctl cdp eval 'SteamClient.Apps.SpecifyCompatTool(<appid>, "<tool dir name>")'`;
check `CompatToolMapping` in `config/config.vdf`.
- Launch options for one game: read them first,
`droiddeckctl cdp eval 'appDetailsStore.GetAppDetails(<appid>)?.strLaunchOptions'`, keep
them, then `SteamClient.Apps.SetAppLaunchOptions(<appid>, "VAR=1 %command%")`.
- For every game: `droiddeckctl env set KEY=VALUE` applies to the next session only
(`--persistent` keeps it); restart the session with `droiddeckctl stop` and `start steam`.
6. Relaunch and read the new launch folder before saying it is fixed. If Steam stays on
"Stopping", `droiddeckctl quit <appid>`, then look for leftover Wine processes with
`droiddeckctl guest -- sh -c 'ps -eo pid,args | grep -i wine'`; never kill the Steam client.
@@ -0,0 +1,41 @@
---
name: reproduce-with-input
description: Reproduce a reported game problem by launching the game and driving controller input
---
1. `droiddeckctl state` first. If the game already has focus, do not launch it again: Steam shows
"Game already running" and `launch` times out. With no session, `droiddeckctl start steam --wait`.
Then `droiddeckctl launch <appid> --wait` and `droiddeckctl wait focused <appid> --timeout 180`.
Check `droiddeckctl thermal` too: at `SEVERE` or worse, performance results mean little.
2. Look before acting: `droiddeckctl screenshot ./shot.png --display 0`, then read the image. On the
Retroid Pocket Duo the top screen is display 0 and the bottom is 2 (`droiddeckctl displays`).
A game shows black or loading frames for a while after it takes focus; take another shot a few
seconds later before calling it a black screen.
3. Drive it with `droiddeckctl input`: `pad a` (also `b x y lb rb start select l3 r3 guide qam`
and the D-pad `up down left right`; `--hold` in ms), `stick left 0 -1 --hold 800`,
`trigger right 1.0`, `key ENTER`, `text 'hello'`. Input goes to the game window that has
focus once the session has drawn a frame. The launcher's own screens need
`adb -s $ADB_SERIAL shell input keyevent ...` instead. Take a screenshot after each step that
should change the screen.
4. Measure: `droiddeckctl pacing --seconds 20` (`fpsOnScreen`, `offCadencePercent`). For flicker
or stutter a still cannot show, `droiddeckctl record ./clip.mp4 --seconds 8 --display 0`.
5. Make it replayable: write the steps as a scenario and run it with `droiddeck-scenario`
(installed beside `droiddeckctl`); `--help` documents the format. Give screenshot steps a display:
```json
{"name": "nfs-menu", "vars": {"appId": 47870}, "repeat": 1,
"before": [["start", "steam", "--wait", "--reuse", "--timeout", "240"]],
"steps": [["launch", "${appId}", "--wait"],
["wait", "focused", "${appId}", "--timeout", "180"],
{"sleep": 20}, ["input", "pad", "a"], {"sleep": 3},
{"screenshot": "after-a", "display": 0},
["pacing", "--seconds", "10"], {"assert": "fpsOnScreen", "exists": true}],
"after": [["quit", "${appId}"]]}
```
`droiddeck-scenario nfs-menu.json --out ./runs` writes `report.json` and, for a failed
run, a screenshot, focus and logs.
6. Report the steps that reproduce it and what you saw at each. Quit the game with
`droiddeckctl quit <appid>` unless the user is playing it. With "Return after game" on (the
default), quitting a game DroidDeck launched also ends the session, so `start steam` again
before the next launch.
+24
View File
@@ -10,6 +10,30 @@ import unittest
SCRIPT = Path(__file__).resolve().parents[1] / 'agent/dd-lab-build'
class LabBuildOptionsTest(unittest.TestCase):
def run_script(self, *args):
with tempfile.TemporaryDirectory() as tmp:
inbox = Path(tmp) / 'agent'
inbox.mkdir()
env = {**os.environ, 'HOME': tmp, 'DD_AGENT': '1', 'DD_AGENT_INBOX': str(inbox)}
env.pop('DD_LAB_DETACHED', None)
result = subprocess.run(['bash', str(SCRIPT), *args], env=env,
capture_output=True, text=True, timeout=10)
return result, (inbox / 'lab-request').exists()
def test_help_prints_usage_without_starting_a_build(self):
result, requested = self.run_script('--help')
self.assertEqual(0, result.returncode, result.stderr)
self.assertIn('Usage: dd-lab-build', result.stdout)
self.assertFalse(requested)
def test_unknown_options_are_refused_without_starting_a_build(self):
result, requested = self.run_script('--bogus')
self.assertEqual(2, result.returncode)
self.assertIn('unknown option --bogus', result.stderr)
self.assertFalse(requested)
class LabBuildPackageTest(unittest.TestCase):
def test_package_override_survives_app_handoff_without_its_environment(self):
with tempfile.TemporaryDirectory() as tmp: