fix: default apps listing to user-installed

[thymikee]

Summary

• Default apps discovery to user-installed apps and keep --all as the explicit full-inventory mode.
• Add human output hints for default filtered discovery and all-apps mode.
• Align Android, Apple, daemon, CLI, and public Android ADB helper defaults, with focused tests and docs updates.

Validation

• /Users/thymikee/.nvm/versions/node/v24.13.0/bin/pnpm format
• PATH=/Users/thymikee/.nvm/versions/node/v24.13.0/bin:$PATH /Users/thymikee/.nvm/versions/node/v24.13.0/bin/pnpm check:quick
• /Users/thymikee/.nvm/versions/node/v24.13.0/bin/pnpm exec vitest run src/utils/__tests__/args.test.ts src/__tests__/cli-config.test.ts src/__tests__/cli-client-commands.test.ts src/platforms/android/__tests__/index.test.ts src/platforms/android/__tests__/app-helpers.test.ts src/platforms/ios/__tests__/index.test.ts src/daemon/handlers/__tests__/session.test.ts
• PATH=/Users/thymikee/.nvm/versions/node/v24.13.0/bin:$PATH /Users/thymikee/.nvm/versions/node/v24.13.0/bin/pnpm build
• Android emulator emulator-5554: ./bin/agent-device.mjs apps --platform android showed Dev (com.expensify.chat.dev) and hid system packages by default; ./bin/agent-device.mjs apps --platform android --all showed system apps such as Settings (com.android.settings).

Touched 18 files. Scope expanded from Android inventory to shared apps defaults so CLI, daemon, Android helper APIs, and Apple helper APIs do not disagree.

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://callstackincubator.github.io/agent-device/pr-preview/pr-541/
Built to branch gh-pages at 2026-05-15 08:45 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 3b407be931

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Keep apps hints out of stdout

When agent-device apps is used in non-JSON mode by scripts or agents that consume stdout as a newline-delimited app list, this appends a non-app hint as an extra stdout line, so downstream selection can treat Showing user-installed apps... or Showing all apps... as an app identifier. Other command metadata/hints in the CLI are written to stderr, so keep stdout to app rows and emit this guidance separately.

Useful? React with 👍 / 👎.

[thymikee]

Architecture Review

Small, focused PR (174/-20, 18 files). Read every patch in full.

Direction overall

Right call. Defaulting apps to user-installed across CLI, daemon, and public helpers fixes a real annoyance: an agent asking "what apps are on this device?" was previously drowning in com.android.providers.* system noise. Flipping the default is more useful and --all keeps the escape hatch.

What's well done

• Cross-layer consistency. Previously CLI, daemon, and Android/iOS helpers all defaulted to 'all'. Now CLI / daemon / listAndroidApps / listIosApps / listMacApps / listAndroidAppsWithAdb all agree.
• --all is documented in command schema, README, and commands.md.
• Tests cover default, override, and daemon's filter forwarding.
• session-inventory.ts already applies the default once at the boundary — the right place.

Concerns

1. Public-API breaking change without a changelog signal. listAndroidApps(device), listIosApps(device), listMacApps(), listAndroidAppsWithAdb(adb, {}) are exposed (the website docs show listAndroidAppsWithAdb). Anyone calling these to look up a system package (e.g., com.android.settings, com.apple.systempreferences) will silently get an empty result. Deserves a release-note line. The client-api.md change removes the explicit { filter: 'user-installed' } and comments "user-installed apps by default" — but doesn't flag the behavior change.

2. The default 'user-installed' is now hardcoded in 7 places:

   • command-schema.ts (CLI parser default)
   • cli/commands/apps.ts (CLI handler fallback)
   • daemon/handlers/session-inventory.ts (daemon fallback)
   • platforms/android/app-helpers.ts (options.filter ?? 'user-installed')
   • platforms/android/app-lifecycle.ts (parameter default)
   • platforms/ios/apps.ts (parameter default)
   • platforms/ios/macos-apps.ts (parameter default)

   Extract a single DEFAULT_APPS_FILTER = 'user-installed' as const. Better still: don't default at the platform layer at all — those are pure library functions; the policy belongs at the CLI/daemon boundary. Making filter required on the platform helpers would have surfaced this consistency bug at compile time instead of letting it drift in the first place.

3. session-inventory.ts switches listAndroidApps from dynamic to static import while iOS stays dynamic. That asymmetry is now silent. If the daemon handles iOS-only sessions, you've added Android-platform cold-start cost. Either both eager or both lazy — pick one and justify it briefly.

4. The discovery hint goes to stdout, not stderr. agent-device apps | grep com.foo now matches against "Showing user-installed apps. Use --all to include system apps." as part of the searchable text. Probably no real-world false positives, but the hint is guidance, not data — stderr is the right stream. --json already correctly omits it, so this only matters for the human path.

5. Empty-result UX leaves the hint without context. When apps is empty, output is just the hint with no "no apps found" line. The empty case is exactly when the hint matters most (the user filtered out the app they wanted), so consider:

   No user-installed apps found. Use --all to include system apps.

6. The hint is procedural, not informative. It says "use --all" without telling you what you'd gain. Since the daemon already computes the launchable set, it could cheaply return how many apps were hidden: { apps, filterApplied, hiddenCount }. Then the hint becomes:

   Showing 4 user-installed apps. 28 system apps hidden — use --all to include them.

   That helps the agent decide whether --all is worth the noise.

7. listMacApps('user-installed') semantics aren't documented. What defines "system" on macOS — /System/Applications? Apple-signed? Worth a one-line comment in macos-apps.ts so the contract isn't only in the implementation.

8. Tests assert exact hint wording. Fine, but couples wording to test maintenance. For evolvable wording, assert stdout.includes('--all') and stdout.includes('user-installed') and reserve exact-match for the data lines.

Forward-looking suggestion

The pattern "platform helper returns data + policy hint" will repeat (devices, sessions, filtered snapshots). Consider a richer envelope from the helpers:

type AppListResult = {
  apps: AppInfo[];
  filter: 'user-installed' | 'all';
  hiddenCount?: number;
};

Then the CLI is a renderer, not a policy decider, and programmatic SDK consumers get the same signal (right now the hint exists only in the CLI's human path).

Verdict

Ship it — the direction is good and the consistency win is real. The DRY-violating 7-place default and the eager-import asymmetry are the only items I'd touch before merge; the rest are nice-to-haves for a follow-up that adds the hiddenCount envelope.

---

Generated by Claude Code