Skip to content

Commit 14dd8b7

Browse files
committed
refactor(kernel): scope the refusal-reason map to what it declares
PRE_DISPATCH_REFUSAL_REASONS states the kernel-owned subset whose refusals always disclose dispatched:no, instead of a name that implies it holds every published reason (the WebDriver and other producer reasons live beside their own disclosures). The map's own doc names the versioned docs as the wire vocabulary and the disclosure table as the producer registry. The session-or-selector refusal gains its daemon.route row in contracts/fixtures/dispatch-disclosure.json, driven through the real router with an unopened session. That command declares no recording effect, so the dispatched:no the row asserts can only come from the producer rather than the read-only seam. The e2e cleanup fixture builds its refusal from sessionAppRequiredDetails() instead of re-typing the details shape, and the permission bullet stops implying a request can name an app for settings permission while #3179 is open.
1 parent da0a23f commit 14dd8b7

14 files changed

Lines changed: 67 additions & 45 deletions

File tree

‎contracts/fixtures/dispatch-disclosure.json‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -89,6 +89,12 @@
8989
"trigger": "get through the request router: the router, not only the interaction route, discloses no for a command the registry declares observes-app",
9090
"dispatched": "no"
9191
},
92+
{
93+
"id": "daemon.route.session-or-selector-refusal",
94+
"producer": "daemon",
95+
"trigger": "a device-bound command with no active session and no device selector: requireSessionOrExplicitSelector refuses before any target resolves, carrying details.reason session_or_device_selector_required",
96+
"dispatched": "no"
97+
},
9298
{
9399
"id": "daemon.route.find-type-refused-after-focus",
94100
"producer": "daemon",

‎packages/kernel/src/errors.test.ts‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ import {
66
discloseDispatch,
77
discloseDispatchAfterSteps,
88
normalizeError,
9-
PUBLISHED_ERROR_REASONS,
9+
PRE_DISPATCH_REFUSAL_REASONS,
1010
sessionAppRequiredDetails,
1111
sessionOrDeviceSelectorRequiredDetails,
1212
throwDaemonError,
@@ -15,8 +15,8 @@ import {
1515
summarizeCommandAttemptFailures,
1616
} from './errors.ts';
1717

18-
test('the published reasons are the values consumers branch on', () => {
19-
assert.deepEqual(PUBLISHED_ERROR_REASONS, {
18+
test('the pre-dispatch refusal reasons are the values consumers branch on', () => {
19+
assert.deepEqual(PRE_DISPATCH_REFUSAL_REASONS, {
2020
sessionAppRequired: 'session_app_required',
2121
sessionOrDeviceSelectorRequired: 'session_or_device_selector_required',
2222
});

‎packages/kernel/src/errors.ts‎

Lines changed: 19 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -252,18 +252,20 @@ export function throwDaemonError(error: DaemonError): never {
252252
}
253253

254254
/**
255-
* The `details.reason` values a refusal answers with when the caller must know *why* a request was
256-
* stopped rather than read the prose: what a caller does to recover is the reason's meaning, and it
257-
* is public surface. Every refusal that names a reason here states its `dispatched` disclosure too,
258-
* because a refusal that reached no device is exactly what makes a retry safe.
255+
* The `details.reason` values a pre-dispatch refusal answers with when the caller must know *why* a
256+
* request was stopped rather than read the prose: what a caller does to recover is the reason's
257+
* meaning, and the reason strings are wire vocabulary (documented in
258+
* `website/docs/docs/commands.md`). This map is the kernel-owned subset whose refusals always
259+
* state `dispatched: 'no'` too — a refusal that provably reached no device is exactly what makes a
260+
* retry safe. Other producers own their own reason strings beside their own disclosures.
259261
*/
260-
export const PUBLISHED_ERROR_REASONS = {
262+
export const PRE_DISPATCH_REFUSAL_REASONS = {
261263
/**
262-
* A per-app setting was asked for while the request carries no app — the session binds none and
263-
* none was named for this request. Recovery: `open` the app (or name it for the request), then
264-
* retry. The daemon's `clear-app-state` pre-check and the Apple, Android, and HarmonyOS owners
265-
* all answer with this one reason for every per-app setting, because the recovery is the same
266-
* whichever setting asked.
264+
* A per-app setting was asked for while the request carries no app — the session binds none and,
265+
* for a setting that takes an app id, none was named for this request. Recovery: `open` the app
266+
* (or name the app id on the request), then retry. The daemon's `clear-app-state` pre-check and
267+
* the Apple, Android, and HarmonyOS owners all answer with this one reason for every per-app
268+
* setting, because the recovery is the same whichever setting asked.
267269
*/
268270
sessionAppRequired: 'session_app_required',
269271
/**
@@ -275,31 +277,31 @@ export const PUBLISHED_ERROR_REASONS = {
275277
sessionOrDeviceSelectorRequired: 'session_or_device_selector_required',
276278
} as const;
277279

278-
export type PublishedErrorReason =
279-
(typeof PUBLISHED_ERROR_REASONS)[keyof typeof PUBLISHED_ERROR_REASONS];
280+
export type PreDispatchRefusalReason =
281+
(typeof PRE_DISPATCH_REFUSAL_REASONS)[keyof typeof PRE_DISPATCH_REFUSAL_REASONS];
280282

281283
/** The details of a refusal that stopped a request before anything could reach a device. */
282-
export type RefusalDetails<TReason extends PublishedErrorReason> = AppErrorDetails & {
284+
export type RefusalDetails<TReason extends PreDispatchRefusalReason> = AppErrorDetails & {
283285
reason: TReason;
284286
dispatched: 'no';
285287
};
286288

287289
/** The details of a per-app setting refused for want of an app. */
288290
export function sessionAppRequiredDetails(): RefusalDetails<
289-
(typeof PUBLISHED_ERROR_REASONS)['sessionAppRequired']
291+
(typeof PRE_DISPATCH_REFUSAL_REASONS)['sessionAppRequired']
290292
> {
291293
return {
292-
reason: PUBLISHED_ERROR_REASONS.sessionAppRequired,
294+
reason: PRE_DISPATCH_REFUSAL_REASONS.sessionAppRequired,
293295
dispatched: 'no',
294296
};
295297
}
296298

297299
/** The details of a command refused for want of a target to route to. */
298300
export function sessionOrDeviceSelectorRequiredDetails(): RefusalDetails<
299-
(typeof PUBLISHED_ERROR_REASONS)['sessionOrDeviceSelectorRequired']
301+
(typeof PRE_DISPATCH_REFUSAL_REASONS)['sessionOrDeviceSelectorRequired']
300302
> {
301303
return {
302-
reason: PUBLISHED_ERROR_REASONS.sessionOrDeviceSelectorRequired,
304+
reason: PRE_DISPATCH_REFUSAL_REASONS.sessionOrDeviceSelectorRequired,
303305
dispatched: 'no',
304306
};
305307
}

‎packages/platform-android/src/__tests__/settings-permission.test.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ import { androidRevokedPermissionWarning } from '../settings-permission.ts';
55
import { ANDROID_EMULATOR } from './test-utils/device-fixtures.ts';
66
import { assertRejectsAppError } from './test-utils/app-error.ts';
77
import { withFakeAdb } from './test-utils/fake-adb.ts';
8-
import { PUBLISHED_ERROR_REASONS } from '@agent-device/kernel/errors';
8+
import { PRE_DISPATCH_REFUSAL_REASONS } from '@agent-device/kernel/errors';
99

1010
// #1796. Two invariants decide every case here:
1111
// * `pm` defaults grant/revoke and the permission-flag operations to UserHandle.USER_SYSTEM,
@@ -324,7 +324,7 @@ test('setAndroidSetting permission requires an app in session with the published
324324
{
325325
code: 'INVALID_ARGS',
326326
message: /requires an active app in session/,
327-
reason: PUBLISHED_ERROR_REASONS.sessionAppRequired,
327+
reason: PRE_DISPATCH_REFUSAL_REASONS.sessionAppRequired,
328328
dispatched: 'no',
329329
},
330330
);

‎packages/platform-android/src/__tests__/settings.test.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
import { test } from 'vitest';
22
import assert from 'node:assert/strict';
33
import { TEXT_SIZE_CATEGORIES } from '@agent-device/contracts/settings';
4-
import { PUBLISHED_ERROR_REASONS } from '@agent-device/kernel/errors';
4+
import { PRE_DISPATCH_REFUSAL_REASONS } from '@agent-device/kernel/errors';
55
import { readAndroidSetting, setAndroidSetting } from '../settings.ts';
66
import { ANDROID_EMULATOR } from './test-utils/device-fixtures.ts';
77
import { assertRejectsAppError } from './test-utils/app-error.ts';
@@ -70,7 +70,7 @@ test('setAndroidSetting clear-app-state refuses an appless session with the publ
7070
async ({ device }) => {
7171
await assertRejectsAppError(() => setAndroidSetting(device, 'clear-app-state', 'clear'), {
7272
code: 'INVALID_ARGS',
73-
reason: PUBLISHED_ERROR_REASONS.sessionAppRequired,
73+
reason: PRE_DISPATCH_REFUSAL_REASONS.sessionAppRequired,
7474
dispatched: 'no',
7575
});
7676
},

‎packages/platform-apple/src/core/__tests__/app-settings.test.ts‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ const simulatorActual = await vi.importActual<typeof import('../simulator.ts')>(
2828
import { setIosSetting } from '../app-settings.ts';
2929
import { withMockedMacOsHelper } from './macos-helper-test-utils.ts';
3030
import { ensureBootedSimulator } from '../simulator.ts';
31-
import { AppError, PUBLISHED_ERROR_REASONS } from '@agent-device/kernel/errors';
31+
import { AppError, PRE_DISPATCH_REFUSAL_REASONS } from '@agent-device/kernel/errors';
3232
import { runCmd } from '@agent-device/host-kit/command';
3333
import { retryWithPolicy } from '@agent-device/host-kit/retry';
3434
import { assertRejectsAppError } from '../../__tests__/app-error.ts';
@@ -329,7 +329,7 @@ test('setIosSetting permission requires an app in session with the published rea
329329
}),
330330
{
331331
code: 'INVALID_ARGS',
332-
reason: PUBLISHED_ERROR_REASONS.sessionAppRequired,
332+
reason: PRE_DISPATCH_REFUSAL_REASONS.sessionAppRequired,
333333
dispatched: 'no',
334334
},
335335
);
@@ -345,7 +345,7 @@ test('setIosSetting location refuses an appless session with the published reaso
345345
async () => {
346346
await assertRejectsAppError(() => setIosSetting(IOS_TEST_SIMULATOR, 'location', 'on'), {
347347
code: 'INVALID_ARGS',
348-
reason: PUBLISHED_ERROR_REASONS.sessionAppRequired,
348+
reason: PRE_DISPATCH_REFUSAL_REASONS.sessionAppRequired,
349349
dispatched: 'no',
350350
});
351351
},
@@ -362,7 +362,7 @@ test('setIosSetting clear-app-state refuses an appless session with the publishe
362362
() => setIosSetting(IOS_TEST_SIMULATOR, 'clear-app-state', 'clear'),
363363
{
364364
code: 'INVALID_ARGS',
365-
reason: PUBLISHED_ERROR_REASONS.sessionAppRequired,
365+
reason: PRE_DISPATCH_REFUSAL_REASONS.sessionAppRequired,
366366
dispatched: 'no',
367367
},
368368
);

‎packages/platform-harmonyos/src/__tests__/settings.test.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ vi.mock('../hdc.ts', () => ({ runHarmonyShell: vi.fn() }));
66
import { runHarmonyShell } from '../hdc.ts';
77
import { setHarmonySetting } from '../settings.ts';
88
import type { DeviceInfo } from '@agent-device/kernel/device';
9-
import { AppError, PUBLISHED_ERROR_REASONS } from '@agent-device/kernel/errors';
9+
import { AppError, PRE_DISPATCH_REFUSAL_REASONS } from '@agent-device/kernel/errors';
1010

1111
const device: DeviceInfo = {
1212
platform: 'harmonyos',
@@ -50,7 +50,7 @@ test('HarmonyOS settings rejects unsupported setting and missing app bundle', as
5050
(error: unknown) =>
5151
error instanceof AppError &&
5252
error.message.includes('requires an app id') &&
53-
error.details?.reason === PUBLISHED_ERROR_REASONS.sessionAppRequired &&
53+
error.details?.reason === PRE_DISPATCH_REFUSAL_REASONS.sessionAppRequired &&
5454
error.details?.dispatched === 'no',
5555
);
5656
});

‎src/daemon/__tests__/request-dispatch-disclosure.test.ts‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -236,6 +236,20 @@ async function readOnlyGet(): Promise<unknown> {
236236
});
237237
}
238238

239+
/**
240+
* The named session is absent from the store, which is what "no active session" means for a
241+
* request: the CLI asks the daemon to find a device and none resolves. The row's command carries
242+
* no declared recording effect, so the `no` under test is the producer's own, not the seam's.
243+
*/
244+
async function sessionOrSelectorRefusedBeforeRouting(): Promise<unknown> {
245+
const failure = await route(makeSession(SESSION), {
246+
command: 'capabilities',
247+
positionals: [],
248+
session: 'session-never-opened',
249+
});
250+
assert.fail(`expected the routing refusal, got ${String(failure)}`);
251+
}
252+
239253
function captureNodes(nodes: readonly unknown[]): void {
240254
gestureRuntimeSpies.captureSnapshot.mockResolvedValue({
241255
backend: 'xctest',
@@ -336,6 +350,7 @@ const DRIVERS: Record<string, () => Promise<unknown>> = {
336350
'daemon.route.scroll-edge-third-pass-refused': () => scrollRefusedOnThirdPass({}, ['bottom']),
337351
'daemon.route.scroll-then-dialog-read-refused': androidScrollThenDialogReadRefused,
338352
'daemon.route.read-only-get': readOnlyGet,
353+
'daemon.route.session-or-selector-refusal': sessionOrSelectorRefusedBeforeRouting,
339354
};
340355

341356
const ROWS = dispatchDisclosureRowsOwnedBy(

‎src/daemon/__tests__/request-router-typed-error.test.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@ import type { DeviceInfo } from '@agent-device/kernel/device';
3232
import {
3333
AppError,
3434
defaultHintForCode,
35-
PUBLISHED_ERROR_REASONS,
35+
PRE_DISPATCH_REFUSAL_REASONS,
3636
retriableForErrorCode,
3737
} from '@agent-device/kernel/errors';
3838
import { mkdtempForTestSync } from '../../__tests__/test-utils/tmp-dir.ts';
@@ -259,7 +259,7 @@ test('#3181: the session-or-selector refusal reaches the caller with its reason
259259
'capabilities requires an active session or an explicit device selector (e.g. --platform ios).',
260260
);
261261
expect(response.error.details?.reason).toBe(
262-
PUBLISHED_ERROR_REASONS.sessionOrDeviceSelectorRequired,
262+
PRE_DISPATCH_REFUSAL_REASONS.sessionOrDeviceSelectorRequired,
263263
);
264264
expect(response.error.details?.dispatched).toBe('no');
265265
// The hint stays the INVALID_ARGS default: the reason, not the prose, is the new information.

‎src/daemon/__tests__/session-device-resolution.test.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ import { appleSessionObservation } from '../../platform-runtime-apple-resources.
1111
import { resolveTargetDevice } from '@agent-device/device-selection/dispatch-resolve';
1212
import { isActiveProviderDevice } from '../provider-device-admission.ts';
1313
import { ensureDeviceReady } from '../device/device-ready.ts';
14-
import { PUBLISHED_ERROR_REASONS } from '@agent-device/kernel/errors';
14+
import { PRE_DISPATCH_REFUSAL_REASONS } from '@agent-device/kernel/errors';
1515

1616
vi.mock('../../platform-runtime-apple-resources.ts', async (importOriginal) => ({
1717
...(await importOriginal<typeof import('../../platform-runtime-apple-resources.ts')>()),
@@ -166,7 +166,7 @@ test('requireSessionOrExplicitSelector refuses with the published reason and dis
166166
if (!refusal || refusal.ok) return;
167167
expect(refusal.error.code).toBe('INVALID_ARGS');
168168
expect(refusal.error.details?.reason).toBe(
169-
PUBLISHED_ERROR_REASONS.sessionOrDeviceSelectorRequired,
169+
PRE_DISPATCH_REFUSAL_REASONS.sessionOrDeviceSelectorRequired,
170170
);
171171
expect(refusal.error.details?.dispatched).toBe('no');
172172
});

0 commit comments

Comments
 (0)