Skip to content

Commit 4565eba

Browse files
strzhaoclaude
andcommitted
feat(harmonyos): opt the trajectory carrier in through a CLI flag
--trajectory-transport carrier replaces the ambient AGENT_DEVICE_HARMONY_CARRIER read: the platform package takes the transport choice as plan data from the contracts seam, which the layering rules require (no ambient host authority below the process entry), and a flag is the operator interface the CLI surface already documents. The example's standalone hvigor project joins the fallow ignore list beside examples/test-app, and the bridge's internal script and verdict helpers drop their exports now that no production consumer imports them. Co-Authored-By: Claude Code <[email protected]>
1 parent 3eacac5 commit 4565eba

18 files changed

Lines changed: 81 additions & 17 deletions

File tree

‎.fallowrc.json‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,8 @@
6363
],
6464
"ignorePatterns": [
6565
"examples/test-app/**",
66+
// Standalone debug-signed hvigor project: built by its own toolchain, not the workspace graph.
67+
"examples/harmony-trajectory-driver/**",
6668
// The social card template: scripts/og.mjs serves it with generated /og/* files.
6769
"website/og/og.html",
6870
"scripts/perf/**",

‎examples/harmony-trajectory-driver/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -76,7 +76,7 @@ mis-judged fail at 200 px/s - both prove the gesture fired), while the carrier i
7676
across shapes (2-point line, 41-point fine steps, 51-point burst at 40000 px/s).
7777

7878
agent-device therefore treats this carrier as an **experimental, explicit opt-in**: the CLI takes
79-
the raw evdev sendevent transport first, and only `AGENT_DEVICE_HARMONY_CARRIER=1` selects this
79+
the raw evdev sendevent transport first, and only `--trajectory-transport carrier` selects this
8080
carrier when evdev is denied. Without either, `--trajectory human` refuses with
8181
`trajectory-channel-unavailable` instead of reporting a green injection that moves nothing.
8282

‎packages/command-registry/src/flag-definitions-action.ts‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,17 @@ export const ACTION_FLAG_DEFINITIONS: readonly FlagDefinition[] = [
4747
projectConfig: true,
4848
recorded: true,
4949
},
50+
{
51+
key: 'trajectoryTransport',
52+
names: ['--trajectory-transport'],
53+
type: 'enum',
54+
enumValues: ['carrier'],
55+
usageLabel: '--trajectory-transport <carrier>',
56+
usageDescription:
57+
'Gesture pan: opt the sampled stroke into the experimental HarmonyOS test-HAP carrier transport',
58+
projectConfig: true,
59+
recorded: true,
60+
},
5061
{
5162
key: 'fps',
5263
names: ['--fps'],

‎packages/command-surface/src/interaction/gesture.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@ function gestureInputFromCli(positionals: string[], flags: CliFlags): Record<str
2626
count: flags.count,
2727
pauseMs: flags.pauseMs,
2828
trajectory: flags.trajectory,
29+
trajectoryTransport: flags.trajectoryTransport,
2930
}),
3031
};
3132
}

‎packages/command-surface/src/interaction/metadata.ts‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@ import { CLICK_BUTTONS } from '@agent-device/contracts/click-button';
22
import {
33
GESTURE_KINDS,
44
HUMAN_TRAJECTORY_MODES,
5+
HUMAN_TRAJECTORY_TRANSPORTS,
56
type GesturePayload,
67
readGesturePayload,
78
} from '@agent-device/contracts/gesture-input';
@@ -235,6 +236,10 @@ const gestureFields = {
235236
HUMAN_TRAJECTORY_MODES,
236237
'Pan stroke transport path; human samples a hand-like curve.',
237238
),
239+
trajectoryTransport: enumField(
240+
HUMAN_TRAJECTORY_TRANSPORTS,
241+
'Opt the sampled stroke into the experimental HarmonyOS test-HAP carrier.',
242+
),
238243
points: pointArrayField('Tap contact points, held together for holdMs.', {
239244
min: GESTURE_TAP_MIN_CONTACTS,
240245
max: GESTURE_MAX_CONTACTS,

‎packages/contracts/src/cli-flags.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ import type { RecordingExportQuality } from './recording-export-quality.ts';
33
import type { BackMode } from './back-mode.ts';
44
import type { ClickButton } from './click-button.ts';
55
import type { SwipePattern } from './scroll-gesture.ts';
6-
import type { HumanTrajectoryMode } from './gesture-plan-types.ts';
6+
import type { HumanTrajectoryMode, HumanTrajectoryTransport } from './gesture-plan-types.ts';
77
import type { BootPickPolicy, DeviceTarget, PlatformSelector } from '@agent-device/kernel/device';
88
import type { SnapshotPreferredBackend } from '@agent-device/kernel/snapshot';
99
import type {
@@ -105,6 +105,7 @@ export type CliFlags = CloudProviderProfileFields &
105105
count?: number;
106106
pointerCount?: number;
107107
trajectory?: HumanTrajectoryMode;
108+
trajectoryTransport?: HumanTrajectoryTransport;
108109
fps?: number;
109110
quality?: RecordingExportQuality | string;
110111
hideTouches?: boolean;

‎packages/contracts/src/gesture-input.test.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -182,6 +182,7 @@ test('pan reads the human trajectory opt-in and every other kind refuses it', ()
182182
pointerCount: undefined,
183183
durationMs: undefined,
184184
trajectory: 'human',
185+
trajectoryTransport: undefined,
185186
},
186187
);
187188
assert.throws(

‎packages/contracts/src/gesture-input.ts‎

Lines changed: 24 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@ import {
2121
GESTURE_TAP_MIN_CONTACTS,
2222
type GesturePointerCount,
2323
type HumanTrajectoryMode,
24+
type HumanTrajectoryTransport,
2425
} from './gesture-plan-types.ts';
2526

2627
export const COORDINATE_GESTURE_KINDS = [
@@ -36,6 +37,7 @@ export const GESTURE_KINDS = [...COORDINATE_GESTURE_KINDS, 'drag'] as const;
3637

3738
/** The transport paths `gesture pan` can request for its stroke. */
3839
export const HUMAN_TRAJECTORY_MODES = ['human'] as const;
40+
export const HUMAN_TRAJECTORY_TRANSPORTS = ['carrier'] as const;
3941

4042
export type DragGesturePayload = {
4143
kind: 'drag';
@@ -54,6 +56,8 @@ export type PanGesturePayload = {
5456
durationMs?: number;
5557
/** Lowers the pan as a sampled human-hand stroke instead of one straight transport segment. */
5658
trajectory?: HumanTrajectoryMode;
59+
/** Opts the sampled stroke into the experimental test-HAP carrier transport. */
60+
trajectoryTransport?: HumanTrajectoryTransport;
5761
};
5862

5963
export type FlingGesturePayload = {
@@ -132,6 +136,7 @@ export function readGesturePayload(input: unknown): GesturePayload {
132136
| undefined,
133137
durationMs: readOptionalGestureDuration(record),
134138
trajectory: readOptionalPanTrajectory(record),
139+
trajectoryTransport: readOptionalPanTrajectoryTransport(record),
135140
};
136141
}
137142
if (kind === 'drag') {
@@ -324,11 +329,26 @@ function readOptionalPanTrajectory(
324329
: readEnum(record, 'trajectory', HUMAN_TRAJECTORY_MODES);
325330
}
326331

332+
function readOptionalPanTrajectoryTransport(
333+
record: Record<string, unknown>,
334+
): HumanTrajectoryTransport | undefined {
335+
return record.trajectoryTransport === undefined
336+
? undefined
337+
: readEnum(record, 'trajectoryTransport', HUMAN_TRAJECTORY_TRANSPORTS);
338+
}
339+
327340
function assertPanOnlyTrajectory(kind: string, record: Record<string, unknown>): void {
328-
if (kind === 'pan' || record.trajectory === undefined) return;
329-
throw new AppError('INVALID_ARGS', 'trajectory is supported only for gesture pan', {
330-
hint: 'A sampled human-hand path is a timed single-pointer motion.',
331-
});
341+
if (kind === 'pan') return;
342+
if (record.trajectory !== undefined) {
343+
throw new AppError('INVALID_ARGS', 'trajectory is supported only for gesture pan', {
344+
hint: 'A sampled human-hand path is a timed single-pointer motion.',
345+
});
346+
}
347+
if (record.trajectoryTransport !== undefined) {
348+
throw new AppError('INVALID_ARGS', 'trajectoryTransport is supported only for gesture pan', {
349+
hint: 'The carrier transport is a sampled human-hand stroke transport.',
350+
});
351+
}
332352
}
333353

334354
function readRecord(input: unknown): Record<string, unknown> {

‎packages/contracts/src/gesture-normalization.test.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@ test('CLI and .ad positionals normalize at one explicit syntax seam', () => {
2121
durationMs: 500,
2222
pointerCount: 2,
2323
trajectory: undefined,
24+
trajectoryTransport: undefined,
2425
},
2526
);
2627
});

‎packages/contracts/src/gesture-normalization.ts‎

Lines changed: 13 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ import type {
55
GestureCommandInput,
66
GestureSemanticInput,
77
HumanTrajectoryMode,
8+
HumanTrajectoryTransport,
89
} from './gesture-plan-types.ts';
910
import {
1011
DEFAULT_DRAG_DESTINATION_HOLD_MS,
@@ -24,14 +25,21 @@ export type SwipePayload = {
2425
pattern?: 'one-way' | 'ping-pong';
2526
};
2627

27-
type GestureFlagKey = 'pointerCount' | 'holdMs' | 'count' | 'pauseMs' | 'trajectory';
28+
type GestureFlagKey =
29+
| 'pointerCount'
30+
| 'holdMs'
31+
| 'count'
32+
| 'pauseMs'
33+
| 'trajectory'
34+
| 'trajectoryTransport';
2835

2936
const GESTURE_FLAG_NAMES: Record<GestureFlagKey, string> = {
3037
pointerCount: '--pointer-count',
3138
holdMs: '--hold-ms',
3239
count: '--count',
3340
pauseMs: '--pause-ms',
3441
trajectory: '--trajectory',
42+
trajectoryTransport: '--trajectory-transport',
3543
};
3644

3745
/**
@@ -40,7 +48,7 @@ const GESTURE_FLAG_NAMES: Record<GestureFlagKey, string> = {
4048
* CLI would reject and have it silently dropped.
4149
*/
4250
export const GESTURE_FLAGS_BY_KIND = {
43-
pan: ['pointerCount', 'trajectory'],
51+
pan: ['pointerCount', 'trajectory', 'trajectoryTransport'],
4452
tap: ['holdMs', 'count', 'pauseMs'],
4553
fling: [],
4654
swipe: [],
@@ -275,6 +283,7 @@ export type GesturePositionalFlags = {
275283
count?: number;
276284
pauseMs?: number;
277285
trajectory?: HumanTrajectoryMode;
286+
trajectoryTransport?: HumanTrajectoryTransport;
278287
};
279288

280289
/** The explicit parser for the public CLI and `.ad` gesture syntax. */
@@ -297,6 +306,7 @@ export function gesturePayloadFromPositionals(
297306
pointerCount,
298307
durationMs: optionalPositionNumber(args[4]),
299308
trajectory: flags.trajectory,
309+
trajectoryTransport: flags.trajectoryTransport,
300310
});
301311
}
302312
case 'fling': {
@@ -455,6 +465,7 @@ export function normalizePublicGesture(input: GesturePayload): NormalizedPublicG
455465
pointerCount: input.pointerCount,
456466
durationMs: input.durationMs,
457467
trajectory: input.trajectory,
468+
trajectoryTransport: input.trajectoryTransport,
458469
},
459470
};
460471
case 'fling':

0 commit comments

Comments
 (0)