agent-scenario-loop 0.1.0

package/examples/mobile-app/scenarios/mobile/open-close-cycle.json

@@ -0,0 +1,160 @@
+{
+  "schemaVersion": "1.0.0",
+  "id": "open-close-cycle",
+  "flowId": "example-card-open-close",
+  "description": "Open and dismiss the example app detail card repeatedly from one portable scenario.",
+  "journey": {
+    "name": "Example card open and close",
+    "intent": "Open a stable example card, prove it rendered, dismiss it, and prove the app returned to the list.",
+    "actor": "mobile app user",
+    "startState": "example app home screen ready",
+    "endState": "example card dismissed"
+  },
+  "platforms": ["ios", "android"],
+  "requiredCapabilities": ["launch", "sessionControl", "command", "logCapture", "artifactWrite"],
+  "optionalCapabilities": ["screenshot", "video", "uiTree"],
+  "truthEvents": {
+    "openRequested": {
+      "event": "card_open_requested",
+      "required": true,
+      "phase": "intent"
+    },
+    "opened": {
+      "event": "card_opened",
+      "required": true,
+      "timeoutMs": 2500,
+      "phase": "visual"
+    },
+    "closeRequested": {
+      "event": "card_close_requested",
+      "required": true,
+      "phase": "intent"
+    },
+    "dismissed": {
+      "event": "card_dismissed",
+      "required": true,
+      "timeoutMs": 2500,
+      "phase": "completion"
+    }
+  },
+  "milestones": [
+    {
+      "id": "openRequested",
+      "event": "card_open_requested",
+      "description": "The app received the command to open the first example card.",
+      "required": true,
+      "phase": "intent"
+    },
+    {
+      "id": "opened",
+      "event": "card_opened",
+      "description": "The first example card became visible.",
+      "required": true,
+      "timeoutMs": 2500,
+      "phase": "visual"
+    },
+    {
+      "id": "closeRequested",
+      "event": "card_close_requested",
+      "description": "The app received the command to close the example card.",
+      "required": true,
+      "phase": "intent"
+    },
+    {
+      "id": "dismissed",
+      "event": "card_dismissed",
+      "description": "The example card was dismissed cleanly.",
+      "required": true,
+      "timeoutMs": 2500,
+      "phase": "completion"
+    }
+  ],
+  "expectedEvents": [
+    "card_open_requested",
+    "card_opened",
+    "card_close_requested",
+    "card_dismissed"
+  ],
+  "cycles": {
+    "iterations": 3,
+    "warmupIterations": 0,
+    "stopOnFailure": true
+  },
+  "budgets": [
+    {
+      "name": "open close cycle p95",
+      "source": "milestone",
+      "metric": "p95",
+      "unit": "ms",
+      "limit": 1350,
+      "fromMilestone": "openRequested",
+      "toMilestone": "dismissed"
+    },
+    {
+      "name": "open p95",
+      "source": "milestone",
+      "metric": "p95",
+      "unit": "ms",
+      "limit": 650,
+      "fromMilestone": "openRequested",
+      "toMilestone": "opened"
+    },
+    {
+      "name": "close p95",
+      "source": "milestone",
+      "metric": "p95",
+      "unit": "ms",
+      "limit": 500,
+      "fromMilestone": "closeRequested",
+      "toMilestone": "dismissed"
+    }
+  ],
+  "steps": [
+    {
+      "id": "launch",
+      "kind": "launch"
+    },
+    {
+      "id": "open-example-card",
+      "kind": "command",
+      "command": "activate-target:example-card-1",
+      "adapterOptions": {
+        "androidAdb": {
+          "waitMs": 300
+        },
+        "iosSimctl": {
+          "waitMs": 300
+        }
+      }
+    },
+    {
+      "id": "wait-card-opened",
+      "kind": "waitForMilestone",
+      "milestone": "opened",
+      "timeoutMs": 2500
+    },
+    {
+      "id": "close-example-card",
+      "kind": "command",
+      "command": "activate-target:close-card",
+      "adapterOptions": {
+        "androidAdb": {
+          "waitMs": 300
+        },
+        "iosSimctl": {
+          "waitMs": 300
+        }
+      }
+    },
+    {
+      "id": "wait-card-dismissed",
+      "kind": "waitForMilestone",
+      "milestone": "dismissed",
+      "timeoutMs": 2500
+    }
+  ],
+  "artifacts": {
+    "required": ["logs", "signals"],
+    "optional": ["screenshot", "video", "uiTree"]
+  }
+}

package/examples/mobile-app/scenarios/mobile/scroll-settle.json

@@ -0,0 +1,148 @@
+{
+  "schemaVersion": "1.0.0",
+  "id": "scroll-settle",
+  "flowId": "example-feed-scroll",
+  "description": "Scroll the example feed and measure app-owned evidence until visible content settles.",
+  "journey": {
+    "name": "Example feed scroll settle",
+    "intent": "Trigger a deterministic feed scroll, prove content became visible, and prove the feed reached a settled state.",
+    "actor": "mobile app user",
+    "startState": "example app feed visible and idle",
+    "endState": "example app feed settled after scroll"
+  },
+  "platforms": ["ios", "android"],
+  "requiredCapabilities": ["launch", "sessionControl", "command", "logCapture", "artifactWrite"],
+  "optionalCapabilities": ["screenshot", "video", "uiTree", "profiler"],
+  "truthEvents": {
+    "openRequested": {
+      "event": "feed_scroll_started",
+      "required": true,
+      "phase": "intent"
+    },
+    "opened": {
+      "event": "feed_first_content_visible",
+      "required": true,
+      "timeoutMs": 2500,
+      "phase": "visual"
+    },
+    "closeRequested": {
+      "event": "feed_scroll_settle_requested",
+      "required": true,
+      "phase": "render"
+    },
+    "dismissed": {
+      "event": "feed_scroll_settled",
+      "required": true,
+      "timeoutMs": 2500,
+      "phase": "completion"
+    }
+  },
+  "milestones": [
+    {
+      "id": "openRequested",
+      "event": "feed_scroll_started",
+      "description": "The app started the deterministic feed scroll.",
+      "required": true,
+      "phase": "intent"
+    },
+    {
+      "id": "opened",
+      "event": "feed_first_content_visible",
+      "description": "The first target content became visible after scrolling.",
+      "required": true,
+      "timeoutMs": 2500,
+      "phase": "visual"
+    },
+    {
+      "id": "closeRequested",
+      "event": "feed_scroll_settle_requested",
+      "description": "The app requested a settled-state check for the feed.",
+      "required": true,
+      "phase": "render"
+    },
+    {
+      "id": "dismissed",
+      "event": "feed_scroll_settled",
+      "description": "The feed reached a stable settled state.",
+      "required": true,
+      "timeoutMs": 2500,
+      "phase": "completion"
+    }
+  ],
+  "expectedEvents": [
+    "feed_scroll_started",
+    "feed_first_content_visible",
+    "feed_scroll_settle_requested",
+    "feed_scroll_settled"
+  ],
+  "cycles": {
+    "iterations": 3,
+    "warmupIterations": 0,
+    "stopOnFailure": true
+  },
+  "budgets": [
+    {
+      "name": "scroll settle p95",
+      "source": "milestone",
+      "metric": "p95",
+      "unit": "ms",
+      "limit": 1050,
+      "fromMilestone": "openRequested",
+      "toMilestone": "dismissed"
+    },
+    {
+      "name": "first content visible p95",
+      "source": "milestone",
+      "metric": "p95",
+      "unit": "ms",
+      "limit": 500,
+      "fromMilestone": "openRequested",
+      "toMilestone": "opened"
+    },
+    {
+      "name": "settle completion p95",
+      "source": "milestone",
+      "metric": "p95",
+      "unit": "ms",
+      "limit": 350,
+      "fromMilestone": "closeRequested",
+      "toMilestone": "dismissed"
+    }
+  ],
+  "steps": [
+    {
+      "id": "launch",
+      "kind": "launch"
+    },
+    {
+      "id": "scroll-example-feed",
+      "kind": "command",
+      "command": "activate-target:scroll-feed",
+      "adapterOptions": {
+        "androidAdb": {
+          "waitMs": 300
+        },
+        "iosSimctl": {
+          "waitMs": 300
+        }
+      }
+    },
+    {
+      "id": "wait-feed-settled",
+      "kind": "waitForMilestone",
+      "milestone": "dismissed",
+      "timeoutMs": 2500
+    },
+    {
+      "id": "capture-final-screen",
+      "kind": "captureEvidence",
+      "artifact": "screenshot",
+      "driverAction": "screenshot",
+      "required": false
+    }
+  ],
+  "artifacts": {
+    "required": ["logs", "signals"],
+    "optional": ["screenshot", "video", "uiTree", "profiler"]
+  }
+}

package/examples/mobile-app/scripts/asl-capture-accessibility-provider.mjs

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Parses simple `--key value` CLI arguments.
+ *
+ * @param {string[]} argv
+ * @returns {Record<string, string | boolean>}
+ */
+function parseArgs(argv) {
+  const args = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (!token?.startsWith('--')) {
+      continue;
+    }
+
+    const key = token.slice(2);
+    const value = argv[index + 1];
+    if (value && !value.startsWith('--')) {
+      args[key] = value;
+      index += 1;
+    } else {
+      args[key] = true;
+    }
+  }
+  return args;
+}
+
+/**
+ * Reads a required string CLI argument.
+ *
+ * @param {Record<string, string | boolean>} args
+ * @param {string} key
+ * @returns {string}
+ */
+function requireStringArg(args, key) {
+  const value = args[key];
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new Error(`Missing required --${key} value.`);
+  }
+  return value;
+}
+
+/**
+ * Writes a formatted JSON artifact.
+ *
+ * @param {string} outPath
+ * @param {Record<string, unknown>} payload
+ * @returns {void}
+ */
+function writeJsonArtifact(outPath, payload) {
+  fs.mkdirSync(path.dirname(outPath), { recursive: true });
+  fs.writeFileSync(outPath, `${JSON.stringify(payload, null, 2)}\n`, 'utf8');
+}
+
+/**
+ * Writes deterministic accessibility evidence for the example-app provider command.
+ *
+ * @param {{outPath: string, platform: string, runId: string, scenarioId: string}} options
+ * @returns {void}
+ */
+function writeAccessibilityEvidence({
+  outPath,
+  platform,
+  runId,
+  scenarioId,
+}) {
+  writeJsonArtifact(outPath, {
+    checks: [
+      {
+        id: 'app-title-visible',
+        selector: {
+          kind: 'testId',
+          value: 'asl-example-title',
+        },
+        status: 'passed',
+      },
+    ],
+    platform,
+    providerId: 'example-mobile-app-evidence-provider',
+    runId,
+    scenarioId,
+    schemaVersion: '1.0.0',
+    summary: 'Deterministic example accessibility evidence for package and consumer rehearsal.',
+    violations: [],
+  });
+}
+
+/**
+ * Runs the provider script.
+ *
+ * @returns {void}
+ */
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  writeAccessibilityEvidence({
+    outPath: requireStringArg(args, 'out'),
+    platform: requireStringArg(args, 'platform'),
+    runId: requireStringArg(args, 'run-id'),
+    scenarioId: requireStringArg(args, 'scenario'),
+  });
+}
+
+try {
+  main();
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+}

package/examples/mobile-app/scripts/asl-capture-profiler-provider.mjs

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Parses simple `--key value` CLI arguments.
+ *
+ * @param {string[]} argv
+ * @returns {Record<string, string | boolean>}
+ */
+function parseArgs(argv) {
+  const args = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (!token?.startsWith('--')) {
+      continue;
+    }
+
+    const key = token.slice(2);
+    const value = argv[index + 1];
+    if (value && !value.startsWith('--')) {
+      args[key] = value;
+      index += 1;
+    } else {
+      args[key] = true;
+    }
+  }
+  return args;
+}
+
+/**
+ * Reads a required string CLI argument.
+ *
+ * @param {Record<string, string | boolean>} args
+ * @param {string} key
+ * @returns {string}
+ */
+function requireStringArg(args, key) {
+  const value = args[key];
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new Error(`Missing required --${key} value.`);
+  }
+  return value;
+}
+
+/**
+ * Writes a formatted JSON artifact.
+ *
+ * @param {string} outPath
+ * @param {Record<string, unknown>} payload
+ * @returns {void}
+ */
+function writeJsonArtifact(outPath, payload) {
+  fs.mkdirSync(path.dirname(outPath), { recursive: true });
+  fs.writeFileSync(outPath, `${JSON.stringify(payload, null, 2)}\n`, 'utf8');
+}
+
+/**
+ * Writes deterministic evidence for the example-app provider command.
+ *
+ * @param {{memoryOutPath: string, networkOutPath: string, outPath: string, platform: string, runId: string, scenarioId: string}} options
+ * @returns {void}
+ */
+function writeProviderEvidence({
+  memoryOutPath,
+  networkOutPath,
+  outPath,
+  platform,
+  runId,
+  scenarioId,
+}) {
+  const shared = {
+    platform,
+    providerId: 'example-mobile-app-evidence-provider',
+    runId,
+    scenarioId,
+    schemaVersion: '1.0.0',
+  };
+
+  writeJsonArtifact(outPath, {
+    ...shared,
+    samples: [],
+    summary: 'Deterministic example profiler evidence for package and consumer rehearsal.',
+  });
+  writeJsonArtifact(memoryOutPath, {
+    ...shared,
+    jsHeapBytes: null,
+    nativeHeapBytes: null,
+    summary: 'Deterministic example memory signal for package and consumer rehearsal.',
+  });
+  writeJsonArtifact(networkOutPath, {
+    log: {
+      creator: {
+        name: 'agent-scenario-loop example provider',
+        version: '1.0.0',
+      },
+      entries: [],
+      version: '1.2',
+    },
+    ...shared,
+  });
+}
+
+/**
+ * Runs the provider script.
+ *
+ * @returns {void}
+ */
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  writeProviderEvidence({
+    memoryOutPath: requireStringArg(args, 'memory-out'),
+    networkOutPath: requireStringArg(args, 'network-out'),
+    outPath: requireStringArg(args, 'out'),
+    platform: requireStringArg(args, 'platform'),
+    runId: requireStringArg(args, 'run-id'),
+    scenarioId: requireStringArg(args, 'scenario'),
+  });
+}
+
+try {
+  main();
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+}

package/examples/mobile-app/src/devtools/profile-session.ts

@@ -0,0 +1,7 @@
+export {
+  emitProfileEvent,
+  registerProfileCommandTargetHandler,
+  storeProfileSignal,
+  useProfileSession,
+  useProfileSessionBootstrap,
+} from '../../../../app/profile-session';