agent-scenario-loop 0.1.0

package/examples/mobile-app/src/example-screen.tsx

@@ -0,0 +1,322 @@
+import React, { useCallback, useEffect, useRef, useState } from 'react';
+import { Pressable, ScrollView, StyleSheet, Text, View } from 'react-native';
+import { useSafeAreaInsets } from 'react-native-safe-area-context';
+
+import {
+  emitProfileEvent,
+  registerProfileCommandTargetHandler,
+  useProfileSession,
+  useProfileSessionBootstrap,
+} from './devtools/profile-session';
+
+const CARDS = [
+  'Profile session control',
+  'Portable scenario manifests',
+  'Stable evidence artifacts',
+  'Before and after comparisons',
+  'Agent-readable summaries',
+];
+
+/**
+ * Emits one app-owned profile event for the active example scenario.
+ *
+ * @param {string} event
+ * @param {number} iteration
+ * @returns {void}
+ */
+function mark(event: string, iteration = 1): void {
+  emitProfileEvent(event, {
+    flowId: 'example-mobile-app',
+    iteration,
+    owner: 'example-mobile-app',
+    route: 'home',
+  });
+}
+
+/**
+ * Neutral Expo screen used to dogfood Agent Scenario Loop contracts.
+ *
+ * @returns {React.ReactElement}
+ */
+export function ExampleScreen(): React.ReactElement {
+  useProfileSessionBootstrap();
+
+  const insets = useSafeAreaInsets();
+  const profileSession = useProfileSession();
+  const [selectedCard, setSelectedCard] = useState<string | null>(null);
+  const [scrollSettled, setScrollSettled] = useState(false);
+  const scrollViewRef = useRef<ScrollView | null>(null);
+  const commandIterationRef = useRef(1);
+  const ignoredMomentumEndsRef = useRef(0);
+  const selectedIterationRef = useRef(1);
+  const startupRunKeyRef = useRef<string | null>(null);
+
+  const openCard = useCallback((index: number, iterationOverride?: number) => {
+    const card = CARDS[index] ?? CARDS[0];
+    const iteration = iterationOverride ?? index + 1;
+    mark('card_open_requested', iteration);
+    selectedIterationRef.current = iteration;
+    setSelectedCard(card);
+    requestAnimationFrame(() => {
+      mark('card_opened', iteration);
+    });
+  }, []);
+
+  const closeCard = useCallback(() => {
+    const iteration = selectedIterationRef.current;
+    mark('card_close_requested', iteration);
+    setSelectedCard(null);
+    requestAnimationFrame(() => {
+      mark('card_dismissed', iteration);
+    });
+  }, []);
+
+  const runScrollSettle = useCallback((iteration = 1) => {
+    setScrollSettled(false);
+    mark('feed_scroll_started', iteration);
+    ignoredMomentumEndsRef.current += 1;
+    scrollViewRef.current?.scrollTo({ animated: true, y: 360 });
+    requestAnimationFrame(() => {
+      mark('feed_first_content_visible', iteration);
+      mark('feed_scroll_settle_requested', iteration);
+      mark('feed_scroll_settled', iteration);
+      setScrollSettled(true);
+    });
+  }, []);
+
+  useEffect(() => {
+    if (profileSession.runId && profileSession.startedAt) {
+      commandIterationRef.current = 1;
+    }
+  }, [profileSession.runId, profileSession.startedAt]);
+
+  useEffect(() => {
+    const startupRunKey = `${profileSession.runId ?? 'unknown'}:${profileSession.startedAt ?? 0}`;
+    if (
+      !profileSession.active ||
+      profileSession.scenario !== 'app-startup' ||
+      !profileSession.runId ||
+      !profileSession.startedAt ||
+      startupRunKeyRef.current === startupRunKey
+    ) {
+      return;
+    }
+
+    startupRunKeyRef.current = startupRunKey;
+    mark('app_launch_requested');
+    requestAnimationFrame(() => {
+      mark('home_ready');
+      mark('startup_idle_observed');
+      mark('startup_complete');
+    });
+  }, [
+    profileSession.active,
+    profileSession.runId,
+    profileSession.scenario,
+    profileSession.startedAt,
+  ]);
+
+  useEffect(() => {
+    const unregisterOpen = registerProfileCommandTargetHandler('example-card-1', () => {
+      openCard(0, commandIterationRef.current);
+    });
+    const unregisterClose = registerProfileCommandTargetHandler('close-card', () => {
+      closeCard();
+      commandIterationRef.current += 1;
+    });
+    const unregisterScroll = registerProfileCommandTargetHandler('scroll-feed', () => {
+      runScrollSettle(commandIterationRef.current);
+      commandIterationRef.current += 1;
+    });
+
+    return () => {
+      unregisterOpen();
+      unregisterClose();
+      unregisterScroll();
+    };
+  }, [closeCard, openCard, runScrollSettle]);
+
+  return (
+    <View style={styles.root}>
+      <ScrollView
+        ref={scrollViewRef}
+        contentContainerStyle={[
+          styles.content,
+          {
+            paddingBottom: Math.max(insets.bottom + 120, 144),
+            paddingTop: insets.top + 18,
+          },
+        ]}
+        contentInsetAdjustmentBehavior="automatic"
+        onScrollBeginDrag={() => {
+          setScrollSettled(false);
+          mark('feed_scroll_started');
+        }}
+        onMomentumScrollEnd={() => {
+          if (ignoredMomentumEndsRef.current > 0) {
+            ignoredMomentumEndsRef.current -= 1;
+            return;
+          }
+
+          mark('feed_first_content_visible');
+          mark('feed_scroll_settle_requested');
+          mark('feed_scroll_settled');
+          setScrollSettled(true);
+        }}
+        scrollEventThrottle={16}
+      >
+        <View style={styles.header}>
+          <Text selectable style={styles.eyebrow}>
+            agent scenario loop
+          </Text>
+          <Text selectable style={styles.title} testID="asl-example-title">
+            Example Mobile App
+          </Text>
+          <Text selectable style={styles.subtitle}>
+            A neutral app surface for startup, open-close, and scroll-settle evidence.
+          </Text>
+        </View>
+
+        {CARDS.map((card, index) => (
+          <Pressable
+            accessibilityRole="button"
+            key={card}
+            onPress={() => {
+              openCard(index);
+            }}
+            style={styles.card}
+          >
+            <Text selectable style={styles.cardTitle}>
+              {card}
+            </Text>
+            <Text selectable style={styles.cardBody}>
+              Tap to emit an open milestone and show a dismissible detail surface.
+            </Text>
+          </Pressable>
+        ))}
+
+        <Text selectable style={styles.scrollState}>
+          {scrollSettled ? 'scroll evidence settled' : 'ready for scroll evidence'}
+        </Text>
+      </ScrollView>
+
+      {selectedCard ? (
+        <View
+          style={[
+            styles.sheet,
+            {
+              bottom: Math.max(insets.bottom, 18),
+            },
+          ]}
+        >
+          <Text selectable style={styles.sheetTitle}>
+            {selectedCard}
+          </Text>
+          <Text selectable style={styles.sheetBody}>
+            This surface is intentionally boring so repeated open-close evidence is stable.
+          </Text>
+          <Pressable
+            accessibilityRole="button"
+            onPress={() => {
+              closeCard();
+            }}
+            style={styles.closeButton}
+          >
+            <Text style={styles.closeButtonText}>Close</Text>
+          </Pressable>
+        </View>
+      ) : null}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  root: {
+    backgroundColor: '#f7f8fa',
+    flex: 1,
+  },
+  content: {
+    gap: 12,
+    paddingHorizontal: 16,
+  },
+  header: {
+    borderBottomColor: '#d9dde5',
+    borderBottomWidth: StyleSheet.hairlineWidth,
+    gap: 8,
+    paddingBottom: 18,
+  },
+  eyebrow: {
+    color: '#4f6b9a',
+    fontSize: 12,
+    fontWeight: '700',
+    letterSpacing: 0,
+    textTransform: 'uppercase',
+  },
+  title: {
+    color: '#151922',
+    fontSize: 28,
+    fontWeight: '800',
+  },
+  subtitle: {
+    color: '#5b6472',
+    fontSize: 15,
+    lineHeight: 21,
+  },
+  card: {
+    backgroundColor: '#ffffff',
+    borderColor: '#d9dde5',
+    borderRadius: 8,
+    borderWidth: 1,
+    padding: 16,
+  },
+  cardTitle: {
+    color: '#151922',
+    fontSize: 17,
+    fontWeight: '700',
+  },
+  cardBody: {
+    color: '#5b6472',
+    fontSize: 14,
+    lineHeight: 20,
+    marginTop: 6,
+  },
+  scrollState: {
+    color: '#4f6b9a',
+    fontSize: 13,
+    fontVariant: ['tabular-nums'],
+    fontWeight: '700',
+  },
+  sheet: {
+    backgroundColor: '#ffffff',
+    borderColor: '#d9dde5',
+    borderRadius: 8,
+    borderWidth: 1,
+    left: 16,
+    padding: 16,
+    position: 'absolute',
+    right: 16,
+  },
+  sheetTitle: {
+    color: '#151922',
+    fontSize: 20,
+    fontWeight: '800',
+  },
+  sheetBody: {
+    color: '#5b6472',
+    fontSize: 14,
+    lineHeight: 20,
+    marginTop: 8,
+  },
+  closeButton: {
+    alignItems: 'center',
+    backgroundColor: '#151922',
+    borderRadius: 8,
+    marginTop: 14,
+    padding: 12,
+  },
+  closeButtonText: {
+    color: '#ffffff',
+    fontSize: 15,
+    fontWeight: '700',
+  },
+});

package/examples/mobile-app/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "extends": "expo/tsconfig.base",
+  "compilerOptions": {
+    "baseUrl": ".",
+    "ignoreDeprecations": "6.0",
+    "paths": {
+      "@react-native-async-storage/async-storage": [
+        "node_modules/@react-native-async-storage/async-storage"
+      ],
+      "expo-linking": ["node_modules/expo-linking"],
+      "react-native": ["node_modules/react-native"]
+    },
+    "strict": true
+  },
+  "include": ["src", "*.ts", "*.tsx"]
+}

package/examples/mobile-app/tsconfig.typecheck.json

@@ -0,0 +1,13 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "paths": {
+      "@react-native-async-storage/async-storage": [
+        "node_modules/@react-native-async-storage/async-storage"
+      ],
+      "expo-linking": ["node_modules/expo-linking"],
+      "react": ["node_modules/@types/react"],
+      "react-native": ["node_modules/react-native"]
+    }
+  }
+}

package/examples/runners/README.md

@@ -0,0 +1,44 @@
+# Runner And Provider Targets
+
+These manifests are public contract fixtures. They are schema-checked, planner-tested, and shipped with the package so adapter authors can start from known capability shapes.
+
+They do not mean the package bundles every named tool. A fixture describes what a tool-specific adapter can provide behind the Agent Scenario Loop ports.
+
+## Primary Runner Targets
+
+| Manifest | Platforms | Contract role | Notes |
+| --- | --- | --- | --- |
+| `adb-android.json` | Android | Built-in adb runner target | Matches the bundled adb driver and Android profile capture path. |
+| `xcodebuildmcp-ios.json` | iOS | XcodeBuildMCP target | Models an iOS simulator driver with UI, screenshot, video, log, and accessibility evidence. |
+| `agent-device-android.json` | Android | agent-device target | Matches the bundled agent-device driver adapter's portable interaction subset. |
+| `agent-device-ios.json` | iOS | agent-device target | Same portable interaction contract on iOS. |
+| `argent-android.json` | Android | Argent target | Models Argent as an interaction runner paired with wrapper-owned log capture. |
+| `argent-ios.json` | iOS | Argent target | Models Argent as an interaction runner with native-devtools and restart-health expectations. |
+| `manual-log-ingest.json` | iOS, Android | fixture-only log ingest | Intentionally insufficient for live lifecycle ownership; useful for proving planner failures. |
+
+## Evidence Provider Targets
+
+| Manifest | Platforms | Contract role | Notes |
+| --- | --- | --- | --- |
+| `argent-react-profiler-provider.json` | Android | Argent profiler provider | Models profiler evidence as a provider lane separate from primary interaction control. |
+| `axe-accessibility-provider.json` | iOS, Android | axe accessibility provider | Demonstrates a command-backed accessibility provider output. |
+| `rozenite-profiler-provider.json` | iOS, Android | Rozenite profiler provider | Describes profiler evidence without bundling the runtime tool. |
+| `script-accessibility-provider.json` | iOS, Android | project-local script provider | Command wrapper pattern for accessibility evidence. |
+| `script-memory-provider.json` | iOS, Android | project-local script provider | Command wrapper pattern for memory evidence and signal attachment. |
+| `script-network-provider.json` | iOS, Android | project-local script provider | Command wrapper pattern for network capture evidence. |
+| `script-profiler-provider.json` | iOS, Android | project-local script provider | Command wrapper pattern for profiler evidence and JS signal attachment. |
+
+## Rules
+
+- Keep `capabilities` about lifecycle or evidence ownership.
+- Keep `driverActions` about concrete operations the adapter can perform.
+- Do not add a capability or driver action until a runner or provider can produce the corresponding evidence.
+- Keep `providerCommands` on evidence-provider manifests; primary runners should own lifecycle orchestration, not provider command wrappers.
+- When a tool writes files independently, attach them through `--signal`, `--capture`, or a `providerCommands` manifest so the run keeps stable artifact paths.
+- Treat these manifests as starting contracts; consuming apps can narrow them to match the exact adapter they install.
+
+## Tool Surface Notes
+
+The bundled `agent-device` driver adapter and `asl-agent-device` capture runner map the declared portable subset: app open/close, alert inspection, `tap`, `scroll`, `assertVisible`, `inspectTree`, `screenshot`, and `readLogs`. Planner compatibility validates the agent-device target metadata that must be known before runtime: `tap` needs a selector, `adapterOptions.agentDevice.ref`, or `adapterOptions.agentDevice.x/y`; `assertVisible` needs a portable selector; selector matching must be exact until the adapter maps richer match modes. The agent-device CLI may expose more commands than the fixture declares, including recording, performance, network, trace, batch, and React DevTools operations. Keep those out of the primary runner manifest until an adapter maps them into stable Agent Scenario Loop artifacts. For example, performance or React DevTools output should usually start as an evidence provider or signal attachment, while `record` should only be declared once video capture is wired into `captures.video`.
+
+The Argent fixtures are external-tool contracts, not bundled package dependencies. `@swmansion/argent` exposes a local MCP/CLI surface for iOS Simulator and Android Emulator control, so Agent Scenario Loop should keep two lanes distinct when an app adopts it: a primary interaction adapter for launch, gestures, screenshot requests, and UI descriptions, and a provider lane for profiler output such as React commit or CPU summaries. Android can pair fast adb interaction with an Argent profiler provider so profiling startup cost does not slow every tap or scroll. iOS adapters should treat native-devtools disconnects, restart-required statuses, required screenshot failures, and root-only UI descriptions as failed scenario health, because timing budgets are not trustworthy when required UI evidence is unverifiable. Optional screenshot failures should stay visible as warnings. When Argent can prove launch and accessibility but its iOS screenshot backend is unavailable, ASL may attach simctl as a screenshot fallback provider while keeping the Argent warning in health. Argent output files should enter ASL through `raw/`, `captures/`, `signals/js`, or provider-command attachments with stable manifest inventory; do not create Argent-specific top-level artifact folders.

package/examples/runners/adb-android.json

@@ -0,0 +1,25 @@
+{
+  "schemaVersion": "1.0.0",
+  "runnerId": "adb-android",
+  "kind": "primary",
+  "platforms": ["android"],
+  "capabilities": [
+    "launch",
+    "sessionControl",
+    "command",
+    "logCapture",
+    "artifactWrite"
+  ],
+  "driverActions": ["tap", "scroll", "assertVisible", "inspectTree", "screenshot", "record", "readLogs"],
+  "artifactOutputs": ["logs", "signals", "screenshot", "video", "uiTree"],
+  "lifecycle": [
+    "prepare",
+    "launch",
+    "startSession",
+    "executeStep",
+    "waitForTruthEvent",
+    "captureEvidence",
+    "stopSession",
+    "finalize"
+  ]
+}

package/examples/runners/agent-device-android.json

@@ -0,0 +1,27 @@
+{
+  "schemaVersion": "1.0.0",
+  "runnerId": "agent-device-android",
+  "kind": "primary",
+  "platforms": ["android"],
+  "capabilities": [
+    "launch",
+    "sessionControl",
+    "command",
+    "logCapture",
+    "artifactWrite",
+    "screenshot",
+    "uiTree"
+  ],
+  "driverActions": ["tap", "scroll", "assertVisible", "inspectTree", "screenshot", "readLogs"],
+  "artifactOutputs": ["logs", "signals", "screenshot", "uiTree"],
+  "lifecycle": [
+    "prepare",
+    "launch",
+    "startSession",
+    "executeStep",
+    "waitForTruthEvent",
+    "captureEvidence",
+    "stopSession",
+    "finalize"
+  ]
+}

package/examples/runners/agent-device-ios.json

@@ -0,0 +1,27 @@
+{
+  "schemaVersion": "1.0.0",
+  "runnerId": "agent-device-ios",
+  "kind": "primary",
+  "platforms": ["ios"],
+  "capabilities": [
+    "launch",
+    "sessionControl",
+    "command",
+    "logCapture",
+    "artifactWrite",
+    "screenshot",
+    "uiTree"
+  ],
+  "driverActions": ["tap", "scroll", "assertVisible", "inspectTree", "screenshot", "readLogs"],
+  "artifactOutputs": ["logs", "signals", "screenshot", "uiTree"],
+  "lifecycle": [
+    "prepare",
+    "launch",
+    "startSession",
+    "executeStep",
+    "waitForTruthEvent",
+    "captureEvidence",
+    "stopSession",
+    "finalize"
+  ]
+}

package/examples/runners/argent-android.json

@@ -0,0 +1,32 @@
+{
+  "schemaVersion": "1.0.0",
+  "runnerId": "argent-android",
+  "kind": "primary",
+  "platforms": ["android"],
+  "capabilities": [
+    "launch",
+    "sessionControl",
+    "command",
+    "logCapture",
+    "artifactWrite",
+    "screenshot",
+    "uiTree"
+  ],
+  "driverActions": ["tap", "scroll", "assertVisible", "inspectTree", "screenshot"],
+  "artifactOutputs": ["logs", "signals", "screenshot", "uiTree"],
+  "lifecycle": [
+    "prepare",
+    "launch",
+    "startSession",
+    "executeStep",
+    "waitForTruthEvent",
+    "captureEvidence",
+    "stopSession",
+    "finalize"
+  ],
+  "adapterOptionsSchema": {
+    "fallbackUiTreeProvider": "adb-uiautomator",
+    "fallbackScreenshotProvider": "adb-screencap",
+    "failHealthOnRootOnlyTree": true
+  }
+}

package/examples/runners/argent-ios.json

@@ -0,0 +1,32 @@
+{
+  "schemaVersion": "1.0.0",
+  "runnerId": "argent-ios",
+  "kind": "primary",
+  "platforms": ["ios"],
+  "capabilities": [
+    "launch",
+    "sessionControl",
+    "command",
+    "logCapture",
+    "artifactWrite",
+    "screenshot",
+    "uiTree"
+  ],
+  "driverActions": ["tap", "scroll", "assertVisible", "inspectTree", "screenshot"],
+  "artifactOutputs": ["logs", "signals", "screenshot", "uiTree"],
+  "lifecycle": [
+    "prepare",
+    "launch",
+    "startSession",
+    "executeStep",
+    "waitForTruthEvent",
+    "captureEvidence",
+    "stopSession",
+    "finalize"
+  ],
+  "adapterOptionsSchema": {
+    "nativeDevtoolsRequired": true,
+    "failHealthOnRestartRequired": true,
+    "failHealthOnRootOnlyTree": true
+  }
+}

package/examples/runners/argent-react-profiler-provider.json

@@ -0,0 +1,15 @@
+{
+  "schemaVersion": "1.0.0",
+  "runnerId": "argent-react-profiler-provider",
+  "kind": "evidenceProvider",
+  "platforms": ["android"],
+  "capabilities": ["profiler"],
+  "driverActions": ["collectPerfSignals"],
+  "artifactOutputs": ["profiler", "signals"],
+  "lifecycle": ["prepare", "startWindow", "capture", "stopWindow", "finalize"],
+  "adapterOptionsSchema": {
+    "connection": "mcp",
+    "warmup": "oncePerRun",
+    "signalPath": "signals/js"
+  }
+}

package/examples/runners/axe-accessibility-provider.json

@@ -0,0 +1,24 @@
+{
+  "schemaVersion": "1.0.0",
+  "runnerId": "axe-accessibility-provider",
+  "kind": "evidenceProvider",
+  "platforms": ["ios", "android"],
+  "capabilities": ["accessibility"],
+  "artifactOutputs": ["accessibility"],
+  "lifecycle": ["prepare", "startWindow", "capture", "stopWindow", "finalize"],
+  "providerCommands": [
+    {
+      "id": "capture-accessibility",
+      "phase": "capture",
+      "command": "axe",
+      "args": ["--output", "{providerDir}/accessibility.json"],
+      "outputs": [
+        {
+          "channel": "provider",
+          "kind": "accessibility",
+          "path": "{providerDir}/accessibility.json"
+        }
+      ]
+    }
+  ]
+}

package/examples/runners/manual-log-ingest.json

@@ -0,0 +1,9 @@
+{
+  "schemaVersion": "1.0.0",
+  "runnerId": "manual-log-ingest",
+  "kind": "primary",
+  "platforms": ["ios", "android"],
+  "capabilities": ["logCapture", "artifactWrite"],
+  "artifactOutputs": ["logs", "signals"],
+  "lifecycle": ["prepare", "captureEvidence", "finalize"]
+}

package/examples/runners/rozenite-profiler-provider.json

@@ -0,0 +1,9 @@
+{
+  "schemaVersion": "1.0.0",
+  "runnerId": "rozenite-profiler-provider",
+  "kind": "evidenceProvider",
+  "platforms": ["ios", "android"],
+  "capabilities": ["profiler"],
+  "artifactOutputs": ["profiler"],
+  "lifecycle": ["prepare", "startWindow", "capture", "stopWindow", "finalize"]
+}

package/examples/runners/script-accessibility-provider.json

@@ -0,0 +1,24 @@
+{
+  "schemaVersion": "1.0.0",
+  "runnerId": "script-accessibility-provider",
+  "kind": "evidenceProvider",
+  "platforms": ["ios", "android"],
+  "capabilities": ["accessibility"],
+  "artifactOutputs": ["accessibility"],
+  "lifecycle": ["prepare", "startWindow", "capture", "stopWindow", "finalize"],
+  "providerCommands": [
+    {
+      "id": "capture-accessibility",
+      "phase": "capture",
+      "command": "capture-accessibility",
+      "args": ["--platform", "{platform}", "--out", "{providerDir}/accessibility.json"],
+      "outputs": [
+        {
+          "channel": "provider",
+          "kind": "accessibility",
+          "path": "{providerDir}/accessibility.json"
+        }
+      ]
+    }
+  ]
+}

package/examples/runners/script-memory-provider.json

@@ -0,0 +1,24 @@
+{
+  "schemaVersion": "1.0.0",
+  "runnerId": "script-memory-provider",
+  "kind": "evidenceProvider",
+  "platforms": ["ios", "android"],
+  "capabilities": ["memory"],
+  "artifactOutputs": ["memory", "signals"],
+  "lifecycle": ["prepare", "startWindow", "capture", "stopWindow", "finalize"],
+  "providerCommands": [
+    {
+      "id": "capture-memory",
+      "phase": "capture",
+      "command": "capture-memory",
+      "args": ["--platform", "{platform}", "--run-id", "{runId}", "--out", "{providerDir}/memory.json"],
+      "outputs": [
+        {
+          "channel": "signal",
+          "kind": "memory",
+          "path": "{providerDir}/memory.json"
+        }
+      ]
+    }
+  ]
+}