Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
121 changes: 121 additions & 0 deletions docs/evidence/harmonyos-launch-args-2026-11-23.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,121 @@
# HarmonyOS open --launch-args forwarding, 2026-11-23

Evidence for #4287 (forward `open --launch-args` to `aa start` verbatim), re-run at the
rebased head. The option forwards each entry as one argument of the `aa start` argv. The
CLI adds no `--ps`/`--pi` words of its own: every parameter word in this run is one the
caller chose.

## Build under test

- Source SHA `306a2f397`, branch `forge/launch-args-harmony`, commit
`feat(harmonyos): forward open --launch-args to aa start verbatim`
- Build: `pnpm install --frozen-lockfile && pnpm build` in the branch worktree. The CLI
and the daemon ran from that dist.
- The daemon ran under an isolated `AGENT_DEVICE_HOME`, so no other build served these
commands.

## Device

- HUAWEI 畅享 90 Plus, model `JDY-AL50`, HarmonyOS 7.0.0.111 (SP10C00E111R4P3), API 26, USB
- Serial `<serial>`. The app is a personal data-carrying user app, driven read-only and
named `<bundle>` below.

The app is force-stopped before cases (a), (b) and (c), so the recorded foreground state
belongs to that launch.

## (a) `--activity` route with parameter words

```sh
$ agent-device open <bundle> --platform harmonyos --serial <serial> --activity EntryAbility \
--launch-args --ps --launch-args k --launch-args v
Opened: <bundle>
$ hdc -t <serial> shell "aa dump -l"
Mission ID #102 mission name #[#<bundle>:entry:EntryAbility] lockedState #0 mission affinity #[]
AbilityRecord ID #21149
app name [<bundle>]
main name [EntryAbility]
bundle name [<bundle>]
ability type [PAGE]
state #FOREGROUND start time [1444191858]
app state #FOREGROUND
ready #1 window attached #0 launcher #0
```

## (b) no `--activity`, the `bm dump` route

```sh
$ agent-device open <bundle> --platform harmonyos --serial <serial> \
--launch-args --ps --launch-args k --launch-args v
Opened: <bundle>
```

The `aa dump -l` mission block matches case (a). The unit test
`openHarmonyApp keeps the module flag ahead of launch args on the bm dump route` pins the
argv: `-m <module>` precedes the forwarded entries.

## (c) a value with shell-live characters: the launch fails, and that is the finding

The review asks that a value carrying `$`, `"` and `\` arrives literally with nothing
executed. At this head it does not arrive at all:

```sh
$ agent-device open <bundle> --platform harmonyos --serial <serial> --activity EntryAbility \
--launch-args '$(id)"q"\c'
Error (COMMAND_FAILED): Failed to start <bundle>
[exit=1]
```

The failure reproduced twice, with the app force-stopped before each attempt. A manual
`hdc shell aa start ... --ps <value>` with the unescaped value, run after the session as a
diagnostic, answers `invalid number of parameters for option --ps`. That repro bypasses
the branch's escaping, so it shows only how `aa` counts operands. The branch run's own
device-side stdout was not captured in the request log. What the two branch runs prove is
narrower: at this head, a value with shell-live characters fails the launch instead of
arriving verbatim. Whether the device shell expands anything before the grammar rejects
the word is not determinable from the captured output. Finding the reshaping layer (the
`hdc` argv join, or the device shell) needs one instrumented probe, and the transport
claim in this PR does not hold until that lands.

## (d) empty entry: typed refusal before any device call

```sh
$ agent-device open <bundle> --platform harmonyos --serial <serial> --activity EntryAbility \
--launch-args ""
Error (INVALID_ARGS): hdc drops an empty element instead of carrying it, so the device
command would lose an operand. May have reached the device. Next: Run snapshot to check
the screen before you retry. Pass a value the transport can carry, or use a device action
that needs no operand.
[exit=1]
```

## (e) lone `--ps` word: `aa` refuses the operand grammar

```sh
$ agent-device open <bundle> --platform harmonyos --serial <serial> --activity EntryAbility \
--launch-args --ps
Error (COMMAND_FAILED): Failed to start <bundle>
[exit=1]
```

A single `--ps` leaves `aa` without a value operand, and the CLI reports the start
failure as `COMMAND_FAILED`.

## Receipt is not observable at default levels, stated plainly

- `aa dump -l` and `aa dump -a` print no parameter lines for the mission.
- After a cleared hilog ring, a launch with `--ps evidence_key_4287 evidence_value_4287`
leaves zero grep hits in `hilog -x`.

This run proves an accepted dispatch with the forwarded argv and a clean foreground
launch. It does not prove in-app receipt. Proving receipt needs an instrumented build;
this session drove a user-built app and could not add one.

## Guard

`assertOpenDeviceSupport` refuses `--launch-args` on Linux
(`packages/contracts/src/application-lifecycle-interaction.ts`). macOS rejects the flag in
the Apple launch path.

## Cleanup

`close <bundle>` ran after the last case and answered `Closed: default`.
2 changes: 1 addition & 1 deletion packages/command-registry/src/flag-definitions-target.ts
Original file line number Diff line number Diff line change
Expand Up @@ -447,7 +447,7 @@ export const TARGET_FLAG_DEFINITIONS: readonly FlagDefinition[] = [
multiple: true,
usageLabel: '--launch-args <arg>',
usageDescription:
'open: repeatable launch argument forwarded verbatim to the platform launch command (iOS app process args; Android adb shell am start args). Linux and macOS reject the flag.',
'open: repeatable launch argument forwarded verbatim to the platform launch command (iOS app process args; Android adb shell am start args; HarmonyOS aa start args). Linux and macOS reject the flag.',
projectConfig: true,
recorded: false,
},
Expand Down
99 changes: 99 additions & 0 deletions packages/platform-harmonyos/src/__tests__/app-lifecycle.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -111,6 +111,105 @@ test('HarmonyOS lifecycle commands use HDC bundle and ability primitives', async
assert.deepEqual(invalidateHarmonyGestureViewport.mock.calls, [[DEVICE], [DEVICE]]);
});

test('openHarmonyApp appends launch args verbatim after the aa start target words', async () => {
mockRunCmd.mockResolvedValueOnce({
exitCode: 0,
stdout: 'start ability successfully',
stderr: '',
});

await openHarmonyApp(DEVICE, 'com.example.application', {
activity: 'EntryAbility',
Comment thread
cubic-dev-ai[bot] marked this conversation as resolved.
Resolved
launchArgs: ['--ps', 'configKey', 'debug', '--pi', 'retryCount', '3'],
});

assert.deepEqual(mockRunCmd.mock.calls[0]?.slice(0, 2), [
'hdc',
[
'-t',
'harmony-1',
'shell',
'aa',
'start',
'-a',
'EntryAbility',
'-b',
'com.example.application',
'--ps',
'configKey',
'debug',
'--pi',
'retryCount',
'3',
],
]);
});

test('openHarmonyApp forwards no extra aa start words when launch args are absent', async () => {
mockRunCmd.mockResolvedValueOnce({
exitCode: 0,
stdout: 'start ability successfully',
stderr: '',
});

await openHarmonyApp(DEVICE, 'com.example.application', { activity: 'EntryAbility' });

assert.deepEqual(mockRunCmd.mock.calls[0]?.slice(0, 2), [
'hdc',
[
'-t',
'harmony-1',
'shell',
'aa',
'start',
'-a',
'EntryAbility',
'-b',
'com.example.application',
],
]);
});

test('openHarmonyApp keeps the module flag ahead of launch args on the bm dump route', async () => {
mockRunCmd
.mockResolvedValueOnce({
exitCode: 0,
stdout: `com.example.application:\n${JSON.stringify({
hapModuleInfos: [{ moduleName: 'entry', mainElementName: 'EntryAbility' }],
})}`,
stderr: '',
})
.mockResolvedValueOnce({ exitCode: 0, stdout: 'start ability successfully', stderr: '' });

await openHarmonyApp(DEVICE, 'com.example.application', {
launchArgs: ['--ps', 'configKey', 'debug'],
});

assert.deepEqual(mockRunCmd.mock.calls[0]?.slice(0, 2), [
'hdc',
['-t', 'harmony-1', 'shell', 'bm', 'dump', '-n', 'com.example.application'],
]);
assert.deepEqual(mockRunCmd.mock.calls[1]?.slice(0, 2), [
'hdc',
[
'-t',
'harmony-1',
'shell',
'aa',
'start',
'-a',
'EntryAbility',
'-b',
'com.example.application',
'-m',
'entry',
'--ps',
'configKey',
'debug',
],
]);
});

test('openHarmonyApp refuses an ability name outside the module grammar before any hdc call', async () => {
for (const activity of ['Entry$(id)', 'Entry;reboot', 'Entry Ability', '1Entry', 'Entry"x', '']) {
await assert.rejects(
Expand Down
4 changes: 3 additions & 1 deletion packages/platform-harmonyos/src/app-lifecycle.ts
Original file line number Diff line number Diff line change
Expand Up @@ -186,10 +186,11 @@ function requireHarmonyAbilityName(ability: string): void {
});
}

/** Launches a bundle's ability; each `launchArgs` entry lands as one quoted `aa start` argument. */
export async function openHarmonyApp(
device: DeviceInfo,
bundleId: string,
options?: { activity?: string; signal?: AbortSignal },
options?: { activity?: string; launchArgs?: string[]; signal?: AbortSignal },
): Promise<void> {
if (options?.activity !== undefined) requireHarmonyAbilityName(options.activity);
const launchTarget = options?.activity
Expand All @@ -213,6 +214,7 @@ export async function openHarmonyApp(
}
const words: ShellWord[] = ['aa', 'start', '-a', launchTarget.ability, '-b', bundleId];
if (launchTarget.module) words.push('-m', launchTarget.module);
words.push(...(options?.launchArgs ?? []));

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P3: An empty --launch-args value is only rejected deep in the HDC transport, after the bm dump lookup when no --activity is given. The error text talks about a device action and never names the flag. Reject empty entries at the start of openHarmonyApp, before any HDC call, with a launch-args-specific error.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At packages/platform-harmonyos/src/app-lifecycle.ts, line 242:

<comment>An empty `--launch-args` value is only rejected deep in the HDC transport, after the `bm dump` lookup when no `--activity` is given. The error text talks about a device action and never names the flag. Reject empty entries at the start of `openHarmonyApp`, before any HDC call, with a launch-args-specific error.</comment>

<file context>
@@ -238,6 +239,7 @@ export async function openHarmonyApp(
   }
   const words: ShellWord[] = ['aa', 'start', '-a', launchTarget.ability, '-b', bundleId];
   if (launchTarget.module) words.push('-m', launchTarget.module);
+  words.push(...(options?.launchArgs ?? []));
   const result = await runHarmonyShell(device, words, { signal: options?.signal });
   if (!result.stdout.includes('start ability successfully')) {
</file context>

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Acknowledged. Case (d) in the evidence doc records the current typed refusal. Moving the check into openHarmonyApp with a launch-args-specific reason would change the pinned reason mid-round; happy to send it as a follow-up if you want the earlier refusal point.

const result = await runHarmonyShell(device, words, { signal: options?.signal });
if (!result.stdout.includes('start ability successfully')) {
throw new AppError('COMMAND_FAILED', `Failed to start ${bundleId}`, {
Expand Down
28 changes: 26 additions & 2 deletions packages/platform-harmonyos/src/interactor.test.ts
Original file line number Diff line number Diff line change
@@ -1,7 +1,8 @@
import { expect, test, vi } from 'vitest';
import type { DeviceInfo } from '@agent-device/kernel/device';

const { pressHarmonyKeyboardKey, snapshotHarmony } = vi.hoisted(() => ({
const { openHarmonyApp, pressHarmonyKeyboardKey, snapshotHarmony } = vi.hoisted(() => ({
openHarmonyApp: vi.fn(async () => undefined),
pressHarmonyKeyboardKey: vi.fn(async () => undefined),
snapshotHarmony: vi.fn(async () => ({
nodes: [{ index: 0, type: 'Button', label: 'Continue' }],
Expand All @@ -17,7 +18,7 @@ vi.mock('./index.ts', () => ({
fillHarmony: vi.fn(),
homeHarmony: vi.fn(),
longPressHarmony: vi.fn(),
openHarmonyApp: vi.fn(),
openHarmonyApp,
performHarmonyGesture: vi.fn(),
pressHarmony: vi.fn(),
pressHarmonyKeyboardKey,
Expand Down Expand Up @@ -56,3 +57,26 @@ test('harmonyos keyboard dismiss invalidates gesture viewport through the Back r

expect(pressHarmonyKeyboardKey).toHaveBeenCalledWith(device, 'Back');
});

test('harmonyos open forwards launch args with the activity to the app launcher', async () => {
await createHarmonyInteractor(device).open('com.example.application', {
activity: 'EntryAbility',
launchArgs: ['--ps', 'configKey', 'debug'],
});

expect(openHarmonyApp).toHaveBeenCalledWith(device, 'com.example.application', {
activity: 'EntryAbility',
launchArgs: ['--ps', 'configKey', 'debug'],
});
});

test('harmonyos open without launch args forwards none to the app launcher', async () => {
await createHarmonyInteractor(device).open('com.example.application', {
activity: 'EntryAbility',
});

expect(openHarmonyApp).toHaveBeenCalledWith(device, 'com.example.application', {
activity: 'EntryAbility',
launchArgs: undefined,
});
});
3 changes: 2 additions & 1 deletion packages/platform-harmonyos/src/interactor.ts
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,8 @@ export function createHarmonyInteractor(device: DeviceInfo, _runner?: RunnerCont
throw new AppError('UNSUPPORTED_OPERATION', `${name} is not supported on HarmonyOS`);
};
return {
open: (app, options) => openHarmonyApp(device, app, { activity: options?.activity }),
open: (app, options) =>
openHarmonyApp(device, app, { activity: options?.activity, launchArgs: options?.launchArgs }),
openDevice: () => homeHarmony(device),
close: (app) => closeHarmonyApp(device, app),
tap: (x, y) => pressHarmony(device, x, y),
Expand Down
3 changes: 2 additions & 1 deletion website/docs/docs/commands.md
Original file line number Diff line number Diff line change
Expand Up @@ -193,7 +193,7 @@ Aliases: `launch`, `relaunch`.
| `--no-test-ime` | open/test/replay: keep the real Android keyboard even on emulators (opt out of the headless test IME; on test/replay it applies to the sessions the flow opens) |
| `--activity <component>` | Android launch activity (package/Class, .Class, or Class) or HarmonyOS ability name; not for URL opens |
| `--launch-console <path>` | open: capture the initial local or Limrun iOS simulator launch console window to a file |
| `--launch-args <arg>` | open: repeatable launch argument forwarded verbatim to the platform launch command (iOS app process args; Android adb shell am start args). Linux and macOS reject the flag. |
| `--launch-args <arg>` | open: repeatable launch argument forwarded verbatim to the platform launch command (iOS app process args; Android adb shell am start args; HarmonyOS aa start args). Linux and macOS reject the flag. |
| `--no-post-gesture-stabilization` | Scroll, swipe, gesture swipe, open: skip the movement check and the stabilization wait that follow a gesture, and on a local iOS simulator the first-screen wait after an app launch; use it only when your own polling verifies the screen |
| `--save-script [path]` | Arm evidence capture on open, publish the armed recording on close; close --save-script alone (without an armed open) is rejected — start with open --save-script, or use session save-script mid-session. Optional custom output path. On Windows, absolute paths need a drive letter or ordinary UNC share. |
| `--relaunch` | open: terminate app process before launching it |
Expand Down Expand Up @@ -559,6 +559,7 @@ agent-device capabilities --session checkout --json
HarmonyOS support uses HDC and ArkUI `uitest`. On API 24 devices it supports lifecycle and HAP deployment, ArkUI snapshot/screenshot and selector reads, one-pointer touch and text actions, keyboard `enter`/`dismiss`, app logs, foreground app state, process RSS samples, and `settings clear-app-state`. Run `agent-device capabilities --platform harmonyos` for the command list of a selected device.

- Gestures use one pointer. Multi-touch gestures and `gesture drag` return `UNSUPPORTED_OPERATION`.
- `open --launch-args` appends each argument to the `aa start` command. Pass the `aa start` parameter pairs you need, such as `--launch-args --ps --launch-args configKey --launch-args debug` for a string extra.
- Physical devices support whole-screen recording with `record start <path> --scope device` or `--scope system`, without `--fps`, `--quality`, or `--hide-touches`. Emulator recording is refused.
- Not available: orientation, clipboard, alerts, network/audio capture, push and app-event delivery, React Native helpers, and trace capture. `settings` supports only `clear-app-state`. `perf memory sample` reports process RSS only.

Expand Down
Loading