adb-ready 0.7.0 → 0.9.0

package/CHANGELOG.md

@@ -9,6 +9,28 @@ breaking changes.
 
 ## [Unreleased]
 
+## [0.9.0] - 2026-09-29
+
+### Added
+
+- Add a packaged JSON Schema for the stable JSON result and NDJSON event
+  envelopes, plus an explicit 1.x compatibility, deprecation, migration, and
+  support-claim policy for CLI, configuration, automation, and MCP consumers.
+
+### Changed
+
+- Strengthen package and release verification so the automation schema is
+  always shipped and generated agent contracts cannot drift from the package
+  version.
+
+## [0.8.0] - 2026-09-29
+
+### Added
+
+- Add deterministic, offline shell completion generation for Bash, zsh, fish,
+  PowerShell, and Nushell, covering both `adb-ready` and `adbr` without loading
+  project configuration or contacting ADB.
+
 ## [0.7.0] - 2026-09-27
 
 ### Added
@@ -499,7 +521,9 @@ breaking changes.
   explainable configuration precedence.
 - Human, plain, JSON, and NDJSON output across Node, Bun, and Deno entrypoints.
 
-[Unreleased]: https://github.com/Adam014/adb-ready/compare/v0.7.0...HEAD
+[Unreleased]: https://github.com/Adam014/adb-ready/compare/v0.9.0...HEAD
+[0.9.0]: https://github.com/Adam014/adb-ready/compare/v0.8.0...v0.9.0
+[0.8.0]: https://github.com/Adam014/adb-ready/compare/v0.7.0...v0.8.0
 [0.7.0]: https://github.com/Adam014/adb-ready/compare/v0.6.0...v0.7.0
 [0.6.0]: https://github.com/Adam014/adb-ready/compare/v0.5.1...v0.6.0
 [0.5.1]: https://github.com/Adam014/adb-ready/compare/v0.5.0...v0.5.1

package/README.md

@@ -284,6 +284,7 @@ Android transport backend.
 | Guide | Start here when you want to… |
 | --- | --- |
 | [Getting started](./docs/getting-started.md) | Reach the first ready development session. |
+| [Shell completion](./docs/completions.md) | Enable command discovery in Bash, zsh, fish, PowerShell, or Nushell. |
 | [Development sessions](./docs/dev-sessions.md) | Configure frameworks, commands, ports, readiness, and cleanup. |
 | [Targets and Wireless debugging](./docs/targets-and-wireless.md) | Pair, connect, recover, or explicitly select a target. |
 | [Apps and evidence](./docs/apps-and-evidence.md) | Control the app and capture screenshots or recordings. |
@@ -291,6 +292,7 @@ Android transport backend.
 | [Logs and AI context](./docs/logs-and-context.md) | Diagnose a failure with bounded, redacted evidence. |
 | [AI agent integration](./docs/agent-integration.md) | Connect an MCP-capable coding agent. |
 | [Automation](./docs/automation.md) | Use readiness, exit codes, JSON, NDJSON, JUnit, and CI artifacts. |
+| [Stability and versioning](./docs/stability.md) | Understand the 1.x API, schema, deprecation, and migration guarantees. |
 | [Gradle Managed Devices](./docs/gradle-managed-devices.md) | Run build-owned virtual-device and group tests with normalized evidence. |
 | [Firebase Test Lab](./docs/firebase-test-lab.md) | Run explicit remote instrumentation or Robo matrices with bounded evidence. |
 | [Target pools and fan-out](./docs/target-pools.md) | Bound parallel verification across an explicit target set. |

package/dist/cli.js

@@ -3304,7 +3304,7 @@ import process15 from "node:process";
 // package.json
 var package_default = {
   name: "adb-ready",
-  version: "0.7.0",
+  version: "0.9.0",
   description: "Agent-ready Android CLI for reliable ADB sessions, app automation, and verified evidence.",
   private: false,
   type: "module",
@@ -3403,7 +3403,7 @@ var package_default = {
     "@yarnpkg/cli-dist": "4.18.0",
     npm: "12.0.2",
     publint: "0.3.24",
-    runpalette: "0.3.0",
+    runpalette: "0.5.0",
     tinyexec: "1.3.1",
     typescript: "7.0.2",
     yarn: "1.22.22"
@@ -57732,12 +57732,259 @@ function resolveTerminalCapabilities(preferences) {
   };
 }
 
+// src/cli/completion.ts
+var COMPLETION_SHELLS = ["bash", "zsh", "fish", "powershell", "nushell"];
+var COMMANDS = [
+  { name: "agent", description: "Configure a project-local AI agent bridge", values: ["setup"] },
+  {
+    name: "app",
+    description: "Resolve, inspect, install, or control one app",
+    values: ["resolve", "info", "install", "launch", "stop", "restart", "clear-data", "uninstall"]
+  },
+  { name: "apps", description: "List packages on one Android target", values: ["list"] },
+  {
+    name: "capture",
+    description: "Capture verified device evidence",
+    values: ["screenshot", "screen-record"]
+  },
+  { name: "completion", description: "Generate shell completion", values: COMPLETION_SHELLS },
+  {
+    name: "config",
+    description: "Validate or explain configuration",
+    values: ["validate", "explain"]
+  },
+  { name: "connect", description: "Connect a wireless Android target" },
+  { name: "context", description: "Export bounded AI-ready context" },
+  { name: "dev", description: "Start a target-bound development session" },
+  { name: "devices", description: "List visible Android targets" },
+  { name: "doctor", description: "Inspect the local ADB environment" },
+  { name: "help", description: "Show command help" },
+  { name: "init", description: "Create detected project configuration" },
+  {
+    name: "inspect",
+    description: "Build bounded device evidence",
+    values: ["app", "failures", "ui"]
+  },
+  { name: "logs", description: "Stream focused target logs" },
+  { name: "mcp", description: "Serve typed tools over local stdio" },
+  { name: "open", description: "Open a deep link or web URL" },
+  { name: "pair", description: "Pair through Wireless debugging" },
+  { name: "ports", description: "Manage verified TCP mappings", values: ["forward", "reverse"] },
+  { name: "problems", description: "Show saved session problems" },
+  { name: "run", description: "Run one bounded verification job" },
+  { name: "sessions", description: "Inspect saved sessions", values: ["list", "show", "events"] },
+  { name: "test", description: "Run managed Android tests", values: ["gradle", "firebase"] },
+  {
+    name: "ui",
+    description: "Perform a bounded verified UI action",
+    values: [
+      "audit",
+      "find",
+      "get",
+      "assert",
+      "compare",
+      "tap",
+      "long-press",
+      "scroll",
+      "swipe",
+      "fill",
+      "clear",
+      "type",
+      "press",
+      "keyboard",
+      "permission",
+      "wait"
+    ]
+  },
+  { name: "version", description: "Show version" }
+];
+var GLOBAL_OPTIONS = [
+  "--help",
+  "-h",
+  "--version",
+  "-V",
+  "--format",
+  "--json",
+  "--quiet",
+  "--verbose",
+  "--color",
+  "--no-color",
+  "--unicode",
+  "--no-unicode",
+  "--animation",
+  "--no-animation",
+  "--non-interactive",
+  "--timeout",
+  "--adb",
+  "--adb-host",
+  "--adb-port",
+  "--config",
+  "--profile",
+  "--select",
+  "--device",
+  "--serial",
+  "-s",
+  "--transport-id",
+  "--last",
+  "--dry-run"
+];
+var commandNames = () => COMMANDS.map(({ name }) => name).join(" ");
+var optionNames = () => GLOBAL_OPTIONS.join(" ");
+function bash() {
+  const cases = COMMANDS.filter(({ values: values2 }) => values2 !== undefined).map(({ name, values: values2 }) => `      ${name}) candidates="${values2?.join(" ")}" ;;`).join(`
+`);
+  return `# Generated by adb-ready. Source this file from ~/.bashrc.
+_adb_ready_complete() {
+  local current command candidates
+  COMPREPLY=()
+  current="\${COMP_WORDS[COMP_CWORD]}"
+  command="\${COMP_WORDS[1]}"
+  if [[ \${COMP_CWORD} -eq 1 ]]; then
+    candidates="${commandNames()} ${optionNames()}"
+  elif [[ \${COMP_CWORD} -eq 2 ]]; then
+    case "\${command}" in
+${cases}
+      help) candidates="${commandNames()}" ;;
+      *) candidates="${optionNames()}" ;;
+    esac
+  else
+    candidates="${optionNames()}"
+  fi
+  COMPREPLY=( $(compgen -W "\${candidates}" -- "\${current}") )
+}
+complete -F _adb_ready_complete adb-ready adbr
+`;
+}
+function zsh() {
+  const commands = COMMANDS.map(({ name, description }) => `    '${name}:${description.replaceAll("'", "'\\''")}'`).join(`
+`);
+  const cases = COMMANDS.filter(({ values: values2 }) => values2 !== undefined).map(({ name, values: values2 }) => `      ${name}) _values 'action' ${values2?.join(" ")} ;;`).join(`
+`);
+  return `#compdef adb-ready adbr
+# Generated by adb-ready. Add its directory to fpath, then run compinit.
+_adb_ready() {
+  local -a commands
+  commands=(
+${commands}
+  )
+  _arguments -C \\
+    '(-h --help)'{-h,--help}'[show help]' \\
+    '(-V --version)'{-V,--version}'[show version]' \\
+    '--format[select output format]:format:(human plain json ndjson)' \\
+    '--json[emit JSON]' \\
+    '--non-interactive[never prompt]' \\
+    '1:command:->command' \\
+    '*::argument:->argument'
+  case $state in
+    command) _describe 'command' commands ;;
+    argument)
+      case $words[2] in
+${cases}
+        help) _describe 'command' commands ;;
+      esac
+      ;;
+  esac
+}
+_adb_ready "$@"
+`;
+}
+function fish() {
+  const lines = [
+    "# Generated by adb-ready. Save as ~/.config/fish/completions/adb-ready.fish."
+  ];
+  for (const binary of ["adb-ready", "adbr"]) {
+    for (const { name, description } of COMMANDS) {
+      const safeDescription = description.replaceAll("'", "\\'");
+      lines.push(`complete -c ${binary} -f -n '__fish_use_subcommand' -a '${name}' -d '${safeDescription}'`);
+    }
+    for (const { name, values: values2 } of COMMANDS) {
+      if (values2 === undefined)
+        continue;
+      lines.push(`complete -c ${binary} -f -n '__fish_seen_subcommand_from ${name}' -a '${values2.join(" ")}'`);
+    }
+    lines.push(`complete -c ${binary} -s h -l help -d 'Show help'`, `complete -c ${binary} -s V -l version -d 'Show version'`, `complete -c ${binary} -l json -d 'Emit JSON'`, `complete -c ${binary} -l non-interactive -d 'Never prompt'`, `complete -c ${binary} -l dry-run -d 'Plan without mutation'`);
+  }
+  return `${lines.join(`
+`)}
+`;
+}
+function powershell() {
+  const map = COMMANDS.filter(({ values: values2 }) => values2 !== undefined).map(({ name, values: values2 }) => `  '${name}' = @('${values2?.join("','")}')`).join(`
+`);
+  return `# Generated by adb-ready. Add this script to your PowerShell profile.
+$AdbReadyCommands = @('${commandNames().replaceAll(" ", "','")}')
+$AdbReadyOptions = @('${optionNames().replaceAll(" ", "','")}')
+$AdbReadyActions = @{
+${map}
+}
+Register-ArgumentCompleter -Native -CommandName adb-ready,adbr -ScriptBlock {
+  param($wordToComplete, $commandAst, $cursorPosition)
+  $words = $commandAst.CommandElements | ForEach-Object { $_.Extent.Text }
+  $candidates = if ($words.Count -le 1) {
+    $AdbReadyCommands + $AdbReadyOptions
+  } elseif ($words.Count -eq 2 -and $AdbReadyActions.ContainsKey($words[1])) {
+    $AdbReadyActions[$words[1]] + $AdbReadyOptions
+  } elseif ($words[1] -eq 'help') {
+    $AdbReadyCommands
+  } else {
+    $AdbReadyOptions
+  }
+  $candidates | Where-Object { $_ -like "$wordToComplete*" } | ForEach-Object {
+    [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_)
+  }
+}
+`;
+}
+function nushellExtern(binary) {
+  return `export extern "${binary}" [
+  command?: string@"nu-complete adb-ready commands"
+  ...args: string
+  --help(-h)
+  --version(-V)
+  --json
+  --quiet
+  --verbose
+  --non-interactive
+  --dry-run
+]`;
+}
+function nushell() {
+  const records = COMMANDS.map(({ name, description }) => `  { value: "${name}", description: "${description}" }`).join(`
+`);
+  return `# Generated by adb-ready. Source this file from config.nu.
+def "nu-complete adb-ready commands" [] {
+[
+${records}
+]
+}
+
+${nushellExtern("adb-ready")}
+
+${nushellExtern("adbr")}
+`;
+}
+function generateCompletion(shell) {
+  switch (shell) {
+    case "bash":
+      return bash();
+    case "zsh":
+      return zsh();
+    case "fish":
+      return fish();
+    case "powershell":
+      return powershell();
+    case "nushell":
+      return nushell();
+  }
+}
+
 // src/cli/arguments.ts
-var COMMANDS = new Set([
+var COMMANDS2 = new Set([
   "agent",
   "app",
   "apps",
   "capture",
+  "completion",
   "config",
   "connect",
   "context",
@@ -57887,6 +58134,7 @@ function splitLongOption(argument) {
 function parseArguments(argv) {
   let command;
   let helpTarget;
+  let completionShell;
   let format = "human";
   let quiet = false;
   let verbose = false;
@@ -58024,17 +58272,17 @@ function parseArguments(argv) {
     }
     if (!argument.startsWith("-")) {
       if (command === undefined) {
-        if (!COMMANDS.has(argument)) {
-          const hint = suggestion(argument, COMMANDS);
+        if (!COMMANDS2.has(argument)) {
+          const hint = suggestion(argument, COMMANDS2);
           return failure4("CLI_USAGE", `Unknown command: ${argument}${hint === "" ? "" : `. ${hint}`}`);
         }
         const candidate = argument;
         command = candidate;
         continue;
       }
-      if (command === "help" && COMMANDS.has(argument)) {
+      if (command === "help" && COMMANDS2.has(argument)) {
         const candidate = argument;
-        if (candidate === "agent" || candidate === "app" || candidate === "apps" || candidate === "capture" || candidate === "connect" || candidate === "config" || candidate === "context" || candidate === "dev" || candidate === "devices" || candidate === "doctor" || candidate === "logs" || candidate === "mcp" || candidate === "open" || candidate === "init" || candidate === "inspect" || candidate === "pair" || candidate === "ports" || candidate === "problems" || candidate === "run" || candidate === "sessions" || candidate === "test" || candidate === "ui" || candidate === "version") {
+        if (candidate === "agent" || candidate === "app" || candidate === "apps" || candidate === "capture" || candidate === "completion" || candidate === "connect" || candidate === "config" || candidate === "context" || candidate === "dev" || candidate === "devices" || candidate === "doctor" || candidate === "logs" || candidate === "mcp" || candidate === "open" || candidate === "init" || candidate === "inspect" || candidate === "pair" || candidate === "ports" || candidate === "problems" || candidate === "run" || candidate === "sessions" || candidate === "test" || candidate === "ui" || candidate === "version") {
           helpTarget = candidate;
           continue;
         }
@@ -58043,6 +58291,13 @@ function parseArguments(argv) {
         endpoint = argument;
         continue;
       }
+      if (command === "completion" && completionShell === undefined) {
+        if (!COMPLETION_SHELLS.includes(argument)) {
+          return failure4("CLI_INVALID_VALUE", `Invalid completion shell: ${argument}. Expected bash, zsh, fish, powershell, or nushell.`);
+        }
+        completionShell = argument;
+        continue;
+      }
       if (command === "agent" && argument === "setup" && !agentSetupSeen) {
         agentSetupSeen = true;
         continue;
@@ -58927,6 +59182,12 @@ function parseArguments(argv) {
   if (command === "capture" && captureKind === undefined) {
     return failure4("CLI_USAGE", "capture requires screenshot or screen-record.");
   }
+  if (command === "completion" && completionShell === undefined) {
+    return failure4("CLI_USAGE", "completion requires bash, zsh, fish, powershell, or nushell.");
+  }
+  if (command === "completion" && argv.some((argument) => argument !== "completion" && argument !== completionShell)) {
+    return failure4("CLI_USAGE", "completion accepts only one shell name; redirect its exact script output to a file.");
+  }
   if (command === "inspect" && inspectKind === undefined) {
     return failure4("CLI_USAGE", "inspect requires app, failures, or ui.");
   }
@@ -59232,6 +59493,7 @@ function parseArguments(argv) {
     options: {
       command,
       ...helpTarget === undefined ? {} : { helpTarget },
+      ...completionShell === undefined ? {} : { completionShell },
       format,
       quiet,
       verbose,
@@ -59360,6 +59622,7 @@ Commands:
   app ACTION [APP_ID]   Resolve, inspect, install, or control one app
   apps list             List packages on one Android target
   capture ACTION         Save a verified screenshot or bounded screen recording
+  completion SHELL       Generate completion for bash, zsh, fish, PowerShell, or Nushell
   config ACTION          Validate or explain resolved configuration
   connect [HOST:PORT]    Connect and verify a wireless Android target
   context [SESSION]      Export bounded AI-ready diagnostic context
@@ -59466,6 +59729,12 @@ Writes verified binary evidence inside the current project. Existing files are
 never replaced unless --force is explicit. Recordings are bounded to 180s.
 Screenshot crops use source pixels. Dimension limits preserve aspect ratio and
 never upscale the image. The CLI keeps full resolution unless limits are set.
+`,
+  completion: `Usage: adb-ready completion bash|zsh|fish|powershell|nushell
+
+Prints a static completion script for both adb-ready and adbr. Generation is
+offline, deterministic, and never loads project configuration or contacts ADB.
+See docs/completions.md for one-time installation instructions.
 `,
   config: `Usage:
   adb-ready config validate [options]
@@ -60225,6 +60494,10 @@ async function runCliInternal(argv, io, dependencies = {}, signal) {
     });
     return 0 /* Success */;
   }
+  if (options.command === "completion") {
+    io.output.write(generateCompletion(options.completionShell ?? "bash"));
+    return 0 /* Success */;
+  }
   if (options.command === "mcp") {
     const explicitRoot = io.env.ADB_READY_MCP_PROJECT_ROOT?.trim();
     await runMcpStdio({
@@ -61355,4 +61628,4 @@ try {
   process16.removeListener("SIGTERM", abort);
 }
 
-//# debugId=8986C9014073E12364756E2164756E21
+//# debugId=24EB6A0CAE0CFFFC64756E2164756E21

package/docs/automation.md

@@ -62,12 +62,17 @@ JSON commands return this top-level shape:
 Consumers must ignore unknown additive fields and event types within the same
 schema version.
 
-The npm package includes two versioned public artifacts:
+The npm package includes three versioned public artifacts:
 
 - `schema/config-v1.schema.json` validates project configuration; and
+- `schema/automation-v1.schema.json` validates the common JSON result and
+  NDJSON event envelopes; and
 - `schema/agent-tools-v1.json` catalogs every MCP tool's generated input and
   output schemas plus safety annotations for the matching package version.
 
+See [Stability and versioning](./stability.md) for the 1.x compatibility,
+deprecation, and migration policy.
+
 ## Event envelope
 
 NDJSON events include:

package/docs/completions.md

@@ -0,0 +1,61 @@
+# Shell completion
+
+ADB Ready generates static tab-completion scripts for both `adb-ready` and its
+short alias, `adbr`. Generation is instant and offline: it does not load project
+configuration, start ADB, or inspect a device.
+
+## Bash
+
+```bash
+mkdir -p ~/.local/share/bash-completion/completions
+adb-ready completion bash > ~/.local/share/bash-completion/completions/adb-ready
+```
+
+Start a new shell. If the user completion directory is not loaded by your Bash
+installation, source the generated file from `~/.bashrc`.
+
+## zsh
+
+```zsh
+mkdir -p ~/.zfunc
+adb-ready completion zsh > ~/.zfunc/_adb-ready
+```
+
+Add the directory before `compinit` in `~/.zshrc`:
+
+```zsh
+fpath=(~/.zfunc $fpath)
+autoload -Uz compinit && compinit
+```
+
+## fish
+
+```fish
+mkdir -p ~/.config/fish/completions
+adb-ready completion fish > ~/.config/fish/completions/adb-ready.fish
+```
+
+fish loads the file automatically in new shell sessions.
+
+## PowerShell
+
+```powershell
+New-Item -ItemType Directory -Force (Split-Path $PROFILE) | Out-Null
+adb-ready completion powershell | Out-File -Append -Encoding utf8 $PROFILE
+```
+
+Reload the profile with `. $PROFILE` or open a new PowerShell session.
+
+## Nushell
+
+```nu
+mkdir ($nu.data-dir | path join "vendor" "autoload")
+adb-ready completion nushell | save --force ($nu.data-dir | path join "vendor" "autoload" "adb-ready.nu")
+```
+
+Nushell loads vendor autoload files in new sessions. The generated declarations
+complete public commands while preserving ordinary file completion for command
+arguments.
+
+Regenerate the script after upgrading ADB Ready so newly added commands become
+available to the shell.

package/docs/stability.md

@@ -0,0 +1,68 @@
+# Stability and versioning
+
+ADB Ready follows Semantic Versioning for the npm package and versions its
+machine contracts independently. Version `1.0.0` starts the compatibility
+policy below; pre-1.0 releases remain governed by their changelog.
+
+## Stable in 1.x
+
+Within the `1.x` package line, ADB Ready will not remove or rename a documented
+CLI command, option, configuration field, exit-code category, result-envelope
+field, event-envelope field, MCP tool, or MCP resource without a new major
+version. Existing documented meanings will not be silently reassigned.
+
+Backward-compatible additions may ship in a minor release. These include new
+commands, options, event types, problem codes, optional object fields, enum
+values, MCP tools, and target capabilities. Automation must ignore unknown
+additive fields and handle unknown event or problem types conservatively.
+
+Human terminal layout, animation, color, progress wording, and diagnostic prose
+are presentation rather than an automation API. Do not parse them. Use JSON,
+NDJSON, the packaged schemas, or MCP instead.
+
+## Versioned contracts
+
+The npm package contains three contract artifacts:
+
+- `schema/config-v1.schema.json` — declarative project configuration;
+- `schema/automation-v1.schema.json` — common JSON result and NDJSON event
+  envelopes; and
+- `schema/agent-tools-v1.json` — the exact MCP tool input/output surface for
+  the installed package version.
+
+`schemaVersion` identifies an envelope or configuration shape; it is not the
+npm package version. Additive changes retain the same schema version. An
+incompatible machine-shape change requires a new schema version and a new npm
+major release. ADB Ready 1.x continues to accept configuration schema v1.
+
+The generated agent contract records `packageVersion`. Clients should load the
+artifact from the same installed package that starts the MCP server instead of
+combining contracts from different releases.
+
+## Exit behavior
+
+The category exit codes documented in [Automation](./automation.md#exit-codes)
+are stable in 1.x. A bounded `dev` or `run` child may preserve its own non-zero
+exit code, so callers must not assume every non-zero value belongs to the ADB
+Ready category table. Read the structured `problems` array for classification.
+
+## Deprecation and migration
+
+A deprecated capability remains functional throughout the current major line
+unless retaining it would create a security or data-integrity risk. ADB Ready
+will mark the replacement in CLI help, public documentation, and the changelog
+before removal. Removal or an incompatible semantic change waits for the next
+major release and receives a migration section.
+
+Security fixes, upstream Android/ADB behavior, and hosted-provider changes can
+make an operation unavailable without changing its public shape. Such cases
+must fail explicitly with structured evidence; ADB Ready does not fabricate a
+successful result to preserve compatibility.
+
+## Support claims
+
+API stability does not turn every upstream-capable environment into a tested
+environment. [Compatibility](../COMPATIBILITY.md) distinguishes CI-tested,
+hardware-observed, and upstream-capable tiers. A new host, runtime, transport,
+or Android form factor is promoted only after its stated acceptance evidence
+exists.

package/llms.txt

@@ -45,6 +45,7 @@
 - Logs and diagnostic context: `docs/logs-and-context.md`
 - Configuration: `docs/configuration.md`
 - Automation contract: `docs/automation.md`
+- Stability and versioning: `docs/stability.md`
 - Compatibility: `COMPATIBILITY.md`
 - Security: `SECURITY.md`
 - Threat model: `docs/threat-model.md`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "adb-ready",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Agent-ready Android CLI for reliable ADB sessions, app automation, and verified evidence.",
   "private": false,
   "type": "module",
@@ -99,7 +99,7 @@
     "@yarnpkg/cli-dist": "4.18.0",
     "npm": "12.0.2",
     "publint": "0.3.24",
-    "runpalette": "0.3.0",
+    "runpalette": "0.5.0",
     "tinyexec": "1.3.1",
     "typescript": "7.0.2",
     "yarn": "1.22.22"

package/schema/agent-tools-v1.json

@@ -1,7 +1,7 @@
 {
   "title": "ADB Ready agent tool contract",
   "schemaVersion": 1,
-  "packageVersion": "0.7.0",
+  "packageVersion": "0.9.0",
   "protocolVersion": "2025-11-25",
   "transport": "stdio",
   "tools": [

package/schema/automation-v1.schema.json

@@ -0,0 +1,156 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/Adam014/adb-ready/blob/main/schema/automation-v1.schema.json",
+  "title": "ADB Ready automation envelope v1",
+  "description": "Common JSON result and NDJSON event envelopes emitted by ADB Ready.",
+  "oneOf": [{ "$ref": "#/$defs/result" }, { "$ref": "#/$defs/event" }],
+  "$defs": {
+    "jsonValue": {
+      "oneOf": [
+        { "type": "null" },
+        { "type": "boolean" },
+        { "type": "number" },
+        { "type": "string" },
+        { "type": "array", "items": { "$ref": "#/$defs/jsonValue" } },
+        {
+          "type": "object",
+          "additionalProperties": { "$ref": "#/$defs/jsonValue" }
+        }
+      ]
+    },
+    "correlation": {
+      "type": "object",
+      "required": ["commandId"],
+      "properties": {
+        "commandId": { "type": "string", "minLength": 1 },
+        "operationId": { "type": "string", "minLength": 1 },
+        "sessionId": { "type": "string", "minLength": 1 },
+        "targetId": { "type": "string", "minLength": 1 }
+      },
+      "additionalProperties": true
+    },
+    "evidence": {
+      "type": "object",
+      "required": ["source", "value"],
+      "properties": {
+        "source": { "type": "string", "minLength": 1 },
+        "field": { "type": "string", "minLength": 1 },
+        "value": { "$ref": "#/$defs/jsonValue" },
+        "redacted": { "type": "boolean" }
+      },
+      "additionalProperties": true
+    },
+    "action": {
+      "type": "object",
+      "required": ["id", "title", "kind", "risk", "automatic"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "title": { "type": "string", "minLength": 1 },
+        "kind": { "enum": ["command", "user", "documentation"] },
+        "risk": {
+          "enum": [
+            "none",
+            "read-only",
+            "local-additive",
+            "device-reversible",
+            "shared-global",
+            "destructive",
+            "open-world"
+          ]
+        },
+        "automatic": { "type": "boolean" },
+        "idempotent": { "type": "boolean" },
+        "command": {
+          "type": "object",
+          "required": ["executable", "args"],
+          "properties": {
+            "executable": { "type": "string", "minLength": 1 },
+            "args": { "type": "array", "items": { "type": "string" } }
+          },
+          "additionalProperties": true
+        }
+      },
+      "additionalProperties": true
+    },
+    "problem": {
+      "type": "object",
+      "required": [
+        "code",
+        "category",
+        "severity",
+        "summary",
+        "detail",
+        "retryable",
+        "evidence",
+        "actions",
+        "correlation"
+      ],
+      "properties": {
+        "code": { "type": "string", "minLength": 1 },
+        "category": { "type": "string", "minLength": 1 },
+        "severity": { "enum": ["warning", "error"] },
+        "summary": { "type": "string" },
+        "detail": { "type": "string" },
+        "retryable": { "type": "boolean" },
+        "evidence": { "type": "array", "items": { "$ref": "#/$defs/evidence" } },
+        "actions": { "type": "array", "items": { "$ref": "#/$defs/action" } },
+        "correlation": { "$ref": "#/$defs/correlation" }
+      },
+      "additionalProperties": true
+    },
+    "result": {
+      "type": "object",
+      "required": [
+        "schemaVersion",
+        "command",
+        "commandId",
+        "ok",
+        "startedAt",
+        "finishedAt",
+        "durationMs",
+        "data",
+        "problems"
+      ],
+      "properties": {
+        "schemaVersion": { "const": 1 },
+        "command": { "type": "string", "minLength": 1 },
+        "commandId": { "type": "string", "minLength": 1 },
+        "ok": { "type": "boolean" },
+        "startedAt": { "type": "string", "format": "date-time" },
+        "finishedAt": { "type": "string", "format": "date-time" },
+        "durationMs": { "type": "number", "minimum": 0 },
+        "data": { "$ref": "#/$defs/jsonValue" },
+        "problems": { "type": "array", "items": { "$ref": "#/$defs/problem" } }
+      },
+      "additionalProperties": true
+    },
+    "event": {
+      "type": "object",
+      "required": [
+        "schemaVersion",
+        "sequence",
+        "timestamp",
+        "type",
+        "source",
+        "severity",
+        "message",
+        "correlation"
+      ],
+      "properties": {
+        "schemaVersion": { "const": 1 },
+        "sequence": { "type": "integer", "minimum": 1 },
+        "timestamp": { "type": "string", "format": "date-time" },
+        "type": { "type": "string", "minLength": 1 },
+        "source": { "type": "string", "minLength": 1 },
+        "severity": { "enum": ["debug", "info", "warning", "error"] },
+        "message": { "type": "string" },
+        "correlation": { "$ref": "#/$defs/correlation" },
+        "data": {
+          "type": "object",
+          "additionalProperties": { "$ref": "#/$defs/jsonValue" }
+        }
+      },
+      "additionalProperties": true
+    }
+  }
+}

package/skills/adb-ready/SKILL.md

@@ -3,7 +3,7 @@ name: adb-ready
 description: Prepare, automate, debug, and verify one Android target through the ADB Ready MCP server. Use for Android development sessions, app lifecycle work, UI automation, failure evidence, screenshots, and agent-driven device checks.
 ---
 
-<!-- Generated by adb-ready 0.7.0; do not edit. -->
+<!-- Generated by adb-ready 0.9.0; do not edit. -->
 
 # ADB Ready
 
@@ -51,4 +51,4 @@ Use the typed `adb-ready` MCP tools. Do not replace them with generic shell or r
 - `session`: 12 tools
 - `ui`: 29 tools
 
-Contract: ADB Ready 0.7.0, agent schema v1.
+Contract: ADB Ready 0.9.0, agent schema v1.