refactor: move utilities to owning modules

src/cli-schema/cli-config.ts

@@ -2,7 +2,7 @@ import type { CliFlags } from '@agent-device/contracts/command';
 import fs from 'node:fs';
 import path from 'node:path';
 import { AppError } from '@agent-device/kernel/errors';
-import { mergeDefinedFlags } from '../utils/merge-flags.ts';
+import { mergeDefinedFlags } from './merge-flags.ts';
 import { type FlagKey } from '../commands/cli-grammar/flag-types.ts';
 import { expandUserHomePath, resolveUserPath } from '@agent-device/host-kit/file';
 import {

src/cli.ts

@@ -34,7 +34,7 @@ import {
   withDiagnosticsScope,
 } from '@agent-device/host-kit/diagnostics';
 import { resolveDaemonPaths } from './daemon/config.ts';
-import { applyDefaultPlatformBinding, resolveBindingSettings } from './utils/session-binding.ts';
+import { applyDefaultPlatformBinding, resolveBindingSettings } from './cli/session-binding.ts';
 import { resolveCliOptions } from './cli/resolve-cli-options.ts';
 import { maybeRunUpgradeNotifier } from './cli/update-check.ts';
 import {

src/utils/__tests__/perf-args.test.ts → src/cli/parser/__tests__/perf-args.test.ts

@@ -1,6 +1,6 @@
 import { test } from 'vitest';
 import assert from 'node:assert/strict';
-import { parseArgs, usageForCommand } from '../../cli/parser/args.ts';
+import { parseArgs, usageForCommand } from '../args.ts';
 
 test('parseArgs accepts perf area subcommands', () => {
   const frames = parseArgs(['perf', 'frames'], { strictFlags: true });

src/cli/parser/args.ts

@@ -1,6 +1,6 @@
 import type { CliFlags } from '@agent-device/contracts/command';
 import { AppError } from '@agent-device/kernel/errors';
-import { mergeDefinedFlags } from '../../utils/merge-flags.ts';
+import { mergeDefinedFlags } from '../../cli-schema/merge-flags.ts';
 import {
   applyCommandDefaults,
   assertCommandPositionalArity,

src/cli/resolve-cli-options.ts

@@ -1,5 +1,5 @@
 import type { CliFlags } from '@agent-device/contracts/command';
-import { mergeDefinedFlags } from '../utils/merge-flags.ts';
+import { mergeDefinedFlags } from '../cli-schema/merge-flags.ts';
 import { finalizeParsedArgs, parseRawArgs } from './parser/args.ts';
 import { resolveConfigBackedFlagDefaults } from '../cli-schema/cli-config.ts';
 import { resolveRemoteConfigDefaults } from './remote-config-flags.ts';

src/commands/interaction/runtime/gestures.ts

@@ -28,7 +28,7 @@ import {
   type ScrollEdgeTarget,
 } from '../../../snapshot/scroll-edge-state.ts';
 import { successText } from '@agent-device/kernel/success-text';
-import { requireIntInRange } from '../../../utils/validation.ts';
+import { requireIntInRange } from '../../../core/validation.ts';
 import { toBackendContext } from '../../runtime-common.ts';
 import {
   toBackendResult,

src/commands/interaction/runtime/resolution.ts

@@ -33,7 +33,7 @@ import {
   classifyOffscreenScrollDirection,
   type OffscreenScrollDirection,
 } from '@agent-device/capture-kit/mobile-snapshot-semantics';
-import { truncateUtf8 } from '../../../utils/truncate-utf8.ts';
+import { truncateUtf8 } from './truncate-utf8.ts';
 import type {
   InteractionTarget,
   PointTarget,

src/utils/__tests__/truncate-utf8.test.ts → src/commands/interaction/runtime/truncate-utf8.test.ts

@@ -1,6 +1,6 @@
 import { test } from 'vitest';
 import assert from 'node:assert/strict';
-import { truncateUtf8 } from '../truncate-utf8.ts';
+import { truncateUtf8 } from './truncate-utf8.ts';
 
 test('truncateUtf8 leaves short strings untouched', () => {
   assert.equal(truncateUtf8('Save', 256), 'Save');

src/commands/observability/index.ts

@@ -6,7 +6,7 @@ import type {
 } from '@agent-device/contracts/client';
 import { NETWORK_INCLUDE_MODES, type NetworkIncludeMode } from '@agent-device/kernel/contracts';
 import { AppError } from '@agent-device/kernel/errors';
-import { parseStringMember } from '../../utils/string-enum.ts';
+import { parseStringMember } from './string-enum.ts';
 import type { CommandSchemaOverride } from '../../cli-schema/types.ts';
 import { defineCommandFacet, defineCommandFamilyFromFacets } from '../family/types.ts';
 import { booleanField, enumField, integerField, stringField } from '../command-input.ts';

src/commands/observability/runtime/diagnostics.ts

@@ -9,7 +9,7 @@ import type {
 } from '../../../backend.ts';
 import type { AgentDeviceRuntime, CommandContext } from '../../../runtime-contract.ts';
 import { AppError } from '@agent-device/kernel/errors';
-import { requireIntInRange } from '../../../utils/validation.ts';
+import { requireIntInRange } from '../../../core/validation.ts';
 import { formatLogsResult, formatNetworkResult, formatPerfResult } from './diagnostics-format.ts';
 import type {
   DiagnosticsLogsCommandResult,

src/commands/recording/runtime/recording.ts

@@ -8,7 +8,7 @@ import type { ArtifactDescriptor, FileOutputRef } from '../../../io.ts';
 import type { CommandContext } from '../../../runtime-contract.ts';
 import { AppError } from '@agent-device/kernel/errors';
 import { successText } from '@agent-device/kernel/success-text';
-import { requireIntInRange } from '../../../utils/validation.ts';
+import { requireIntInRange } from '../../../core/validation.ts';
 import {
   recordingQualityInputToExportQuality,
   type RecordingExportQuality,

src/commands/system/runtime/system.ts

@@ -11,8 +11,8 @@ import type { BackMode } from '@agent-device/contracts/back-mode';
 import { parseTvRemoteButton } from '@agent-device/contracts/tv-remote';
 import { AppError } from '@agent-device/kernel/errors';
 import { successText } from '@agent-device/kernel/success-text';
-import { requireIntInRange } from '../../../utils/validation.ts';
-import { isKeyboardAction } from '../../../utils/keyboard-actions.ts';
+import { isKeyboardAction } from '../../../core/keyboard-actions.ts';
+import { requireIntInRange } from '../../../core/validation.ts';
 import {
   toBackendResult,
   type BackendResultEnvelope,

src/utils/__tests__/interactors.test.ts → src/core/__tests__/interactors.test.ts

@@ -7,7 +7,7 @@ import type { Interactor, RunnerContext } from '@agent-device/contracts/interact
 import { setActiveProviderDeviceRuntimes } from '../../provider-device-runtime.ts';
 import type { ProviderDeviceRuntime } from '@agent-device/contracts/device';
 
-import { getInteractor, getLocalInteractor } from '../../core/interactors.ts';
+import { getInteractor, getLocalInteractor } from '../interactors.ts';
 
 const iosSimulator: DeviceInfo = {
   platform: 'apple',

src/core/dispatch-payload.ts

@@ -1,6 +1,6 @@
 import { promises as fs } from 'node:fs';
 import { AppError } from '@agent-device/kernel/errors';
-import { resolvePayloadInput } from '../utils/payload-input.ts';
+import { resolvePayloadInput } from './payload-input.ts';
 import type { JsonObject } from '@agent-device/contracts/client';
 
 export async function readNotificationPayload(payloadArg: string): Promise<JsonObject> {

src/core/wait-positionals.ts

@@ -1,4 +1,4 @@
-import { parseTimeout } from '../utils/parse-timeout.ts';
+import { parseTimeout } from './parse-timeout.ts';
 import {
   detectUnknownSelectorKeyToken,
   isRoleHintWord,

src/daemon/focus-runtime.ts

@@ -3,7 +3,7 @@ import { focusRuntimeUse } from '@agent-device/contracts/platform-runtime-operat
 import type { DeviceInfo } from '@agent-device/kernel/device';
 import type { Point } from '@agent-device/kernel/snapshot';
 import { successText } from '@agent-device/kernel/success-text';
-import { readPointPositionals } from '../utils/validation.ts';
+import { readPointPositionals } from '../core/validation.ts';
 import type { DaemonCommandContext } from './context.ts';
 import type { ResolvedGenericExecution } from './request-generic-dispatch.ts';
 import { resolveBoundGenericRuntime, type RuntimeAdmissionBindings } from './runtime-admission.ts';

src/daemon/handlers/__tests__/snapshot.test.ts

@@ -1,7 +1,7 @@
 import { test } from 'vitest';
 import assert from 'node:assert/strict';
 import { parseWaitPositionals as parseWaitArgs } from '../../../core/wait-positionals.ts';
-import { parseTimeout } from '../../../utils/parse-timeout.ts';
+import { parseTimeout } from '../../../core/parse-timeout.ts';
 
 // --- parseTimeout ---
 

src/daemon/handlers/session-app-deployment.ts

@@ -11,7 +11,7 @@ import { expireRefFrame } from '../ref-frame.ts';
 import type { BindDeviceRuntime, InspectDeviceRuntimeFacts } from '../request-runtime-binding.ts';
 import { SessionStore } from '../session-store.ts';
 import type { DaemonRequest, DaemonResponse, SessionState } from '../types.ts';
-import { resolvePayloadInput } from '../../utils/payload-input.ts';
+import { resolvePayloadInput } from '../../core/payload-input.ts';
 import { resolveDeployResultTarget } from '../result-serialization.ts';
 import { withSuccessText } from '@agent-device/kernel/success-text';
 import { recordSessionAction } from '../session-action-recorder.ts';

src/daemon/handlers/session-doctor-options.ts

@@ -1,4 +1,4 @@
-import { detectProjectRuntimeKind } from '../../utils/project-runtime.ts';
+import { detectProjectRuntimeKind } from '../../core/project-runtime.ts';
 import { publicPlatformString } from '@agent-device/kernel/device';
 import type { SessionStore } from '../session-store.ts';
 import type { DaemonRequest, SessionState } from '../types.ts';

src/daemon/handlers/snapshot-alert.ts

@@ -15,7 +15,7 @@ import { contextFromFlags } from '../context.ts';
 import type { DaemonRequest, DaemonResponse, SessionState } from '../types.ts';
 import { SessionStore } from '../session-store.ts';
 import { recordIfSession } from './snapshot-session.ts';
-import { parseTimeout } from '../../utils/parse-timeout.ts';
+import { parseTimeout } from '../../core/parse-timeout.ts';
 import { resolveRefFrameEffect } from '../daemon-command-registry.ts';
 import { expireRefFrame } from '../ref-frame.ts';
 import type { DaemonFailureResponse } from '../response.ts';

src/daemon/keyboard-runtime.ts

@@ -17,7 +17,7 @@ import type {
 } from '@agent-device/contracts/platform-runtime';
 import type { DeviceInfo } from '@agent-device/kernel/device';
 import { AppError } from '@agent-device/kernel/errors';
-import { isKeyboardAction, type KeyboardAction } from '../utils/keyboard-actions.ts';
+import { isKeyboardAction, type KeyboardAction } from '../core/keyboard-actions.ts';
 import { successText } from '@agent-device/kernel/success-text';
 import type { DaemonCommandContext } from './context.ts';
 import {

src/daemon/session-event-action-presentation.ts

@@ -3,7 +3,7 @@ import { DEVICE_ROTATIONS } from '@agent-device/contracts/device';
 import { BACK_MODES } from '@agent-device/contracts/back-mode';
 import { TV_REMOTE_BUTTONS } from '@agent-device/contracts/tv-remote';
 import { PUBLIC_COMMANDS } from '../command-catalog.ts';
-import { isKeyboardAction } from '../utils/keyboard-actions.ts';
+import { isKeyboardAction } from '../core/keyboard-actions.ts';
 import {
   compactSessionEventDetails as compactDetails,
   readSessionEventBoolean as readBoolean,

src/daemon/touch-runtime.ts

@@ -21,7 +21,7 @@ import { AppError } from '@agent-device/kernel/errors';
 import type { Point } from '@agent-device/kernel/snapshot';
 import { readFillBackendResult } from '../core/fill-backend-result.ts';
 import { successText } from '@agent-device/kernel/success-text';
-import { requireIntInRange } from '../utils/validation.ts';
+import { requireIntInRange } from '../core/validation.ts';
 import type { DaemonCommandContext } from './context.ts';
 import type { DirectIosSelectorTarget } from './direct-ios-selector.ts';
 import type { DaemonFailureResponse } from './response.ts';

src/daemon/tv-remote-runtime.ts

@@ -5,7 +5,7 @@ import { parseTvRemoteButton, type TvRemoteButton } from '@agent-device/contract
 import type { DeviceInfo } from '@agent-device/kernel/device';
 import { AppError } from '@agent-device/kernel/errors';
 import { successText } from '@agent-device/kernel/success-text';
-import { requireIntInRange } from '../utils/validation.ts';
+import { requireIntInRange } from '../core/validation.ts';
 import type { DaemonCommandContext } from './context.ts';
 import type { ResolvedGenericExecution } from './request-generic-dispatch.ts';
 import { resolveBoundGenericRuntime, type RuntimeAdmissionBindings } from './runtime-admission.ts';

src/daemon/type-text-runtime.ts

@@ -6,8 +6,8 @@ import type {
 import type { DeviceInfo } from '@agent-device/kernel/device';
 import { AppError } from '@agent-device/kernel/errors';
 import { successText } from '@agent-device/kernel/success-text';
-import { findMistargetedTypeRefToken } from '../utils/type-target-warning.ts';
-import { requireIntInRange } from '../utils/validation.ts';
+import { findMistargetedTypeRefToken } from './type-target-warning.ts';
+import { requireIntInRange } from '../core/validation.ts';
 import type { DaemonCommandContext } from './context.ts';
 import type { DaemonFailureResponse } from './response.ts';
 import { admitRuntimeUse, type RuntimeAdmissionBindings } from './runtime-admission.ts';

src/mcp/tool-input-config.ts

@@ -4,7 +4,7 @@ import type { CliFlags } from '@agent-device/contracts/command';
 import type { JsonSchema } from '../commands/command-contract.ts';
 import type { CommandName } from '../commands/command-metadata.ts';
 import { resolveConfigBackedFlagDefaults } from '../cli-schema/cli-config.ts';
-import { mergeDefinedFlags } from '../utils/merge-flags.ts';
+import { mergeDefinedFlags } from '../cli-schema/merge-flags.ts';
 
 export function resolveMcpConfigDefaults(
   name: CommandName,

src/metro/client-metro.ts

@@ -28,7 +28,7 @@ import {
   detectProjectRuntimeKindFromPackageJson,
   readProjectPackageJson,
   type PackageJsonShape,
-} from '../utils/project-runtime.ts';
+} from '../core/project-runtime.ts';
 import { normalizeBaseUrl } from '../client/base-url.ts';
 import { buildBundleUrl } from './bundle-url.ts';
 import {