refactor(daemon): move interaction and find routes behind facade (#2178)

Author: thymikee

.fallowrc.json

@@ -182,18 +182,31 @@
     },
     {
       "comment": "Daemon route handlers are reached only through the dynamic `import()` table in request-handler-chain.ts, which --production analysis cannot follow to a consumer.",
-      "file": "src/daemon/handlers/{human-control,lease,session,snapshot,react-native,record-trace,find,interaction}.ts",
+      "file": "src/daemon/handlers/{human-control,lease,session,snapshot,react-native,record-trace}.ts",
       "exports": [
         "handleHumanControlCommand",
         "handleLeaseCommands",
         "handleSessionCommands",
         "handleSnapshotCommands",
         "handleReactNativeCommands",
-        "handleRecordTraceCommands",
+        "handleRecordTraceCommands"
+      ]
+    },
+    {
+      "comment": "The interaction facade exposes #2178's named route inputs and deferred handlers, plus the existing ref mutation response consumed by help conformance. Fallow's production graph cannot follow the request-handler-chain dynamic imports, so this exact list is the facade contract.",
+      "file": "src/daemon/interaction/index.ts",
+      "exports": [
+        "FindRouteInput",
+        "refMutationAdmissionResponse",
         "handleFindCommands",
         "handleInteractionCommands"
       ]
     },
+    {
+      "comment": "The #2178 route implementations are reached only through the interaction facade's deferred delegates; Fallow's production graph cannot follow those dynamic imports. Keep this exemption limited to the two route entrypoints.",
+      "file": "src/daemon/interaction/internal/{find,interaction}.ts",
+      "exports": ["handleFindCommands", "handleInteractionCommands"]
+    },
     {
       "comment": "Dedicated CLI command handlers are reached only through the dynamic `import()` table `dedicatedCliCommandHandlerLoaders` in src/cli/commands/router.ts, which --production analysis cannot follow to a consumer. Same shape as the daemon route-handler entry above; that table is what enumerates this list, so add/remove here whenever a loader is added/removed.",
       "file": "src/cli/commands/{auth,connection,daemon,device,proxy,replay,screenshot,takeover}.ts",

docs/adr/0012-interactive-replay.md

@@ -761,7 +761,7 @@ works" and "healed scripts are always valid":
   steps are re-executed during the repair replay; only if recording is armed from the start do they land
   in `session.actions` with fresh `target-v1` evidence. Arming late yields a hybrid healed script (an
   annotated corrective step glued to a bare, unannotated prefix) that re-diverges on its own next replay
-  (`src/daemon/handlers/interaction-common.ts:64-65` attaches evidence only when `recordSession` was
+  (`src/daemon/interaction/internal/interaction-common.ts:64-65` attaches evidence only when `recordSession` was
   true when the step ran).
 - **R2 — `--from` continuation only; never re-run the full replay on the same session.** After a
   divergence at step N and the corrective action, the agent must continue with `replay --from k
@@ -803,7 +803,7 @@ works" and "healed scripts are always valid":
   instead of leaving it to agent judgment.
 - **R4 — corrective actions must materialize to selector form; the writer fails loudly on a bare `@ref`
   cross-session export.** A `press @e12` normally resolves a `selectorChain` at runtime
-  (`src/daemon/handlers/interaction-touch-targets.ts`), which `buildOptimizedActions`
+  (`src/daemon/interaction/internal/interaction-touch-targets.ts`), which `buildOptimizedActions`
   (`src/daemon/session-script-writer.ts:69-83`) rewrites to a selector line. If no `selectorChain` was
   captured, the writer must refuse to emit a bare `@ref` line into a persisted `.ad` — a session-bound
   ref will not resolve in a fresh run. It **fails loudly**: an error surfaced to the user with a non-zero

docs/dependency-graph-findings.md

@@ -70,7 +70,7 @@ type-only inversions, R7 pins SessionState field ownership, and the shared selec
   gates for the next major.
 - The **ADR 0017 parameterization boundary is exactly where the ADR says it is**:
   `daemon/parameterized-recorded-fill.ts` has precisely two dependents — the response boundary
-  (`handlers/interaction-common.ts`, step 3) and the recorder boundary
+  (`daemon/interaction/internal/interaction-common.ts`, step 3) and the recorder boundary
   (`session-action-recorder.ts`, step 4). The two-pass structure is two call sites, not a scattered
   concern.
 - Still outside every rule: **dynamic** import direction (0 inversions today, nothing watching),
@@ -358,7 +358,7 @@ candidate facet, and each facet retired is a branch deleted in every command tha
 **This is not a defect list** — importing `kernel/errors.ts` directly is clearer than inheriting it
 through a sibling. It earns its keep per file: `daemon/server/daemon-runtime.ts` gets 18 of its 32
 imports from one neighbour, `handlers/session-open.ts` 17 of 30, `handlers/session.ts` 17 of 32,
-`handlers/find.ts` 16 of 20. A file whose neighbour already provides two-thirds of what it imports
+`daemon/interaction/internal/find.ts` 16 of 20. A file whose neighbour already provides two-thirds of what it imports
 is usually doing its neighbour's job too — the same orchestrator smell as §5, from the other side.
 
 ## 6. R2 is right, and the duplication it forces now has a home

fallow-baselines/health.json

@@ -138,22 +138,22 @@
         "count": 1
       }
     },
-    "src/daemon/handlers/__tests__/interaction-touch.test.ts": {
+    "src/daemon/interaction/internal/__tests__/interaction-touch.test.ts": {
       "crap_moderate": {
         "count": 2
       }
     },
-    "src/daemon/handlers/__tests__/interaction-touch-press.test.ts": {
+    "src/daemon/interaction/internal/__tests__/interaction-touch-press.test.ts": {
       "crap_moderate": {
         "count": 3
       }
     },
-    "src/daemon/handlers/__tests__/interaction-touch-press-admission.test.ts": {
+    "src/daemon/interaction/internal/__tests__/interaction-touch-press-admission.test.ts": {
       "crap_moderate": {
         "count": 2
       }
     },
-    "src/daemon/handlers/__tests__/interaction-touch-response.test.ts": {
+    "src/daemon/interaction/internal/__tests__/interaction-touch-response.test.ts": {
       "crap_moderate": {
         "count": 1
       }
@@ -207,15 +207,15 @@
         "count": 1
       }
     },
-    "src/daemon/handlers/find.ts": {
+    "src/daemon/interaction/internal/find.ts": {
       "complexity_moderate": {
         "count": 1
       },
       "crap_moderate": {
         "count": 1
       }
     },
-    "src/daemon/handlers/interaction-touch-reference-frame.ts": {
+    "src/daemon/interaction/internal/interaction-touch-reference-frame.ts": {
       "crap_moderate": {
         "count": 1
       }

packages/contracts/src/interaction-guarantees.ts

@@ -143,7 +143,7 @@ const PARENT_OWNED_TOUCH_POINT_GAP_ISSUE = 'https://github.com/callstack/agent-d
 // (interaction-response-construction-guard.test.ts) keeps new branches on it.
 const SHARED_RESPONSE_CONSTRUCTION: GuaranteeEnforcement = {
   kind: 'runtime',
-  via: 'src/daemon/handlers/interaction-touch-response.ts#buildInteractionResponseData',
+  via: 'src/daemon/interaction/internal/interaction-touch-response.ts#buildInteractionResponseData',
 };
 
 // The two runtime tree paths (selector and ref resolution) run the SAME shared
@@ -183,7 +183,7 @@ const RUNTIME_TREE_SHARED_GUARANTEES = {
   responseConstruction: SHARED_RESPONSE_CONSTRUCTION,
   responseIdentity: {
     kind: 'runtime',
-    via: 'src/daemon/handlers/interaction-touch-targets.ts#interactionResultExtra',
+    via: 'src/daemon/interaction/internal/interaction-touch-targets.ts#interactionResultExtra',
   },
   verifyEvidence: {
     kind: 'runtime',
@@ -271,7 +271,7 @@ export const INTERACTION_DISPATCH_PATHS: Record<InteractionPathId, InteractionPa
       },
       responseConstruction: {
         kind: 'runtime',
-        via: 'src/daemon/handlers/interaction-gesture-response.ts#gestureResponseData',
+        via: 'src/daemon/interaction/internal/interaction-gesture-response.ts#gestureResponseData',
       },
       responseIdentity: {
         kind: 'runtime',
@@ -340,7 +340,7 @@ export const INTERACTION_DISPATCH_PATHS: Record<InteractionPathId, InteractionPa
       responseConstruction: SHARED_RESPONSE_CONSTRUCTION,
       responseIdentity: {
         kind: 'runtime',
-        via: 'src/daemon/handlers/interaction-touch-targets.ts#interactionResultExtra',
+        via: 'src/daemon/interaction/internal/interaction-touch-targets.ts#interactionResultExtra',
       },
       verifyEvidence: {
         kind: 'delegated',
@@ -464,7 +464,7 @@ export const INTERACTION_DISPATCH_PATHS: Record<InteractionPathId, InteractionPa
       },
       resolutionDisclosure: {
         kind: 'runtime',
-        via: 'src/daemon/handlers/interaction-touch-response.ts#buildInteractionResponseData',
+        via: 'src/daemon/interaction/internal/interaction-touch-response.ts#buildInteractionResponseData',
       },
     },
   },

packages/contracts/src/interaction.ts

@@ -96,7 +96,7 @@ export type RecordingTargetOverride = {
  * captured itself, handed to the interaction leaf so the leaf does not resolve
  * the same `@ref` a second time.
  *
- * The sole producer is a mutating `find` (`src/daemon/handlers/find.ts`): it
+ * The sole producer is a mutating `find` (`src/daemon/interaction/internal/find.ts`): it
  * captures, matches by locator, promotes to a hittable ancestor, and mints
  * `@eN` off the node it chose — then re-enters the interaction leaf. Without
  * this channel the leaf repeated an in-memory `@eN` lookup after find had

…mon/handlers/__tests__/find-args.test.ts …selectors/src/internal/find-args.test.tssrc/daemon/handlers/__tests__/find-args.test.ts renamed to packages/selectors/src/internal/find-args.test.ts src/daemon/handlers/__tests__/find-args.test.ts renamed to packages/selectors/src/internal/find-args.test.ts

@@ -4,7 +4,7 @@ import {
   parseFindArgs,
   parseFindSelectorExpression,
   UNSUPPORTED_FIND_ACTION_HINT,
-} from '@agent-device/selectors';
+} from './find.ts';
 
 test('parseFindArgs defaults to click with any locator', () => {
   const parsed = parseFindArgs(['Login']);

scripts/__tests__/help-conformance-sample-producers.ts

@@ -19,7 +19,7 @@ import { interactionCliOutputFormatters } from '../../src/commands/interaction/o
 import { snapshotCliOutput } from '../../src/commands/capture/output.ts';
 import { openCliOutput } from '../../src/commands/management/output.ts';
 import { NEVER_SETTLED_HINT } from '../../src/commands/interaction/runtime/settle.ts';
-import { buildAmbiguousMatchError } from '../../src/daemon/handlers/find-match-resolution.ts';
+import { buildAmbiguousMatchError } from '../../src/daemon/selector-match-errors.ts';
 import { refMutationAdmissionResponse } from '../../src/daemon/interaction/index.ts';
 import { buildDeviceInUseBySessionError } from '../../src/daemon/session-recovery-hints.ts';
 import { buildDeviceClaimConflictError } from '../../src/daemon/device-claim-conflict.ts';

scripts/__tests__/test-file-size-ratchet.test.ts

@@ -47,7 +47,7 @@ const PINNED_TEST_FILE_LINES: Readonly<Record<string, number>> = Object.freeze({
   'packages/platform-apple/src/runner/__tests__/runner-command-retry.test.ts': 1280,
   'src/__tests__/cli-client-commands.test.ts': 1304,
   'src/__tests__/cli-config.test.ts': 1282,
-  'src/daemon/handlers/__tests__/find.test.ts': 1199,
+  'src/daemon/interaction/internal/__tests__/find.test.ts': 1199,
   'packages/platform-apple/src/core/__tests__/perf.test.ts': 1222,
   'src/mcp/__tests__/command-tools.test.ts': 1216,
   'src/daemon/replay/internal/__tests__/session-replay-divergence.test.ts': 1100,

scripts/depgraph/affected.test.ts

@@ -89,16 +89,16 @@ test('commandsReaching follows the dynamic import a route uses to load its handl
   const edges = edgesOf({
     'src/daemon/handlers/session.ts':
       "import { helper } from '../../utils/helper.ts';\nexport const h = helper;",
-    'src/daemon/handlers/find.ts': 'export const f = 1;',
+    'src/daemon/interaction/index.ts': 'export const f = 1;',
     'src/utils/helper.ts': 'export const helper = 1;',
     'src/daemon/chain.ts': [
       "export const routes = { session: () => import('./handlers/session.ts'),",
-      "  find: () => import('./handlers/find.ts') };",
+      "  find: () => import('./interaction/index.ts') };",
     ].join('\n'),
   });
   const chains = [
     { command: 'open', route: 'session', entry: 'src/daemon/handlers/session.ts' },
-    { command: 'find', route: 'find', entry: 'src/daemon/handlers/find.ts' },
+    { command: 'find', route: 'find', entry: 'src/daemon/interaction/index.ts' },
   ];
 
   assert.deepEqual(
@@ -107,7 +107,9 @@ test('commandsReaching follows the dynamic import a route uses to load its handl
   );
   // The entry module itself counts as part of its own chain.
   assert.deepEqual(
-    commandsReaching('src/daemon/handlers/find.ts', chains, edges).map((chain) => chain.command),
+    commandsReaching('src/daemon/interaction/index.ts', chains, edges).map(
+      (chain) => chain.command,
+    ),
     ['find'],
   );
 });