agent-scenario-loop 0.1.1 → 0.1.3

package/README.md

@@ -14,12 +14,14 @@ Execution tools can change. The scenario and evidence contract should not.
 | --- | --- |
 | Understand the idea in plain language | [Concepts](docs/concepts.md) |
 | Understand the project doctrine | [Principles](docs/principles.md) |
-| Write your first scenario | [Scenario Authoring](docs/authoring.md) |
-| Rehearse adoption in an existing app | [Consumer App Rehearsal](docs/consumer-rehearsal.md) |
+| Understand why ASL is a protocol, not a TypeScript-only library | [Architecture](docs/architecture.md) |
+| Implement or evaluate an out-of-process adapter in any language | [External Adapter Protocol](docs/external-adapter-protocol.md) |
 | Inspect artifacts, schemas, and supported surfaces | [Contracts](docs/contracts.md) |
-| Use the package from code | [Public API](docs/api.md) |
+| Write your first scenario | [Scenario Authoring](docs/authoring.md) |
 | Add a runner or evidence provider | [Adapter Onboarding](docs/adapters.md) |
+| Rehearse adoption in an existing app | [Consumer App Rehearsal](docs/consumer-rehearsal.md) |
 | Run fixture, Android, or iOS proofs | [Live Proofs](docs/live-proofs.md) |
+| Use the package from code | [Public API](docs/api.md) |
 | Inspect runner behavior and limits | [Runner docs](runner/README.md) |
 | Explore the neutral dogfood app | [examples/mobile-app](examples/mobile-app/README.md) |
 | See runner and provider fixtures | [examples/runners](examples/runners/README.md) |
@@ -43,6 +45,12 @@ Install or use the package, then scaffold a first scenario inside an app:
 asl-init --out . --scenario first-journey
 ```
 
+Add the optional repository-scoped agent skill when you want Codex to load ASL operating guidance from the consuming app:
+
+```bash
+asl-init --out . --scenario first-journey --with-agent-skill
+```
+
 Wire the generated app helper, emit truth events around one real journey, merge the generated `asl:*` scripts intentionally, then validate the project:
 
 ```bash
@@ -67,12 +75,6 @@ No simulator or device available yet? Run the fixture loop:
 pnpm demo:loop -- --out artifacts/demo-loop
 ```
 
-Read next:
-
-- [Scenario Authoring](docs/authoring.md) for scenario shape and truth events
-- [Consumer App Rehearsal](docs/consumer-rehearsal.md) for adoption in an existing app
-- [Live Proofs](docs/live-proofs.md) for Android, iOS, comparison, and release-proof paths
-
 ## Package Surface
 
 The root package exports stable core contracts:
@@ -117,3 +119,7 @@ pnpm release:check
 ```
 
 The package should remain product-neutral. Product-specific selectors, routes, auth assumptions, accounts, and scenario data belong in the consuming app, not in this repository.
+
+## Read next
+
+- [Concepts](docs/concepts.md) for the plain-language model

package/app/profile-session.ts

@@ -12,11 +12,16 @@ export type ProfileSessionState = {
 
 export type ProfileSessionCommand = {
   id: string;
+  commandId?: string;
   scenario?: string;
   runId?: string;
   command: string;
+  queueId?: string;
+  sequence?: number;
   source?: 'deeplink' | 'storage';
   timestamp: number;
+  waitForMilestone?: string;
+  waitTimeoutMs?: number;
 };
 
 export type ProfileSignalKind = 'js' | 'memory' | 'network';
@@ -65,7 +70,16 @@ type StoredProfileSessionEntry = {
   startedAt?: number;
   stoppedAt?: number;
   command?: string;
+  commandId?: string;
   id?: string;
+  queueId?: string;
+  reason?: string;
+  result?: string;
+  sequence?: number;
+  source?: 'deeplink' | 'storage';
+  status?: 'received' | 'queued' | 'delivered' | 'completed' | 'skipped';
+  waitForMilestone?: string;
+  waitTimeoutMs?: number;
 };
 
 type StoredProfileSignals = Record<ProfileSignalKind, Record<string, unknown>>;
@@ -316,6 +330,41 @@ function logProfileSession(kind: 'start' | 'stop' | 'command', payload: Record<s
     if (typeof payload.id === 'string') {
       entry.id = payload.id;
     }
+    if (typeof payload.commandId === 'string') {
+      entry.commandId = payload.commandId;
+    } else if (typeof payload.id === 'string') {
+      entry.commandId = payload.id;
+    }
+    if (typeof payload.queueId === 'string') {
+      entry.queueId = payload.queueId;
+    }
+    if (typeof payload.sequence === 'number') {
+      entry.sequence = payload.sequence;
+    }
+    if (payload.source === 'deeplink' || payload.source === 'storage') {
+      entry.source = payload.source;
+    }
+    if (
+      payload.status === 'received' ||
+      payload.status === 'queued' ||
+      payload.status === 'delivered' ||
+      payload.status === 'completed' ||
+      payload.status === 'skipped'
+    ) {
+      entry.status = payload.status;
+    }
+    if (typeof payload.reason === 'string') {
+      entry.reason = payload.reason;
+    }
+    if (typeof payload.result === 'string') {
+      entry.result = payload.result;
+    }
+    if (typeof payload.waitForMilestone === 'string') {
+      entry.waitForMilestone = payload.waitForMilestone;
+    }
+    if (typeof payload.waitTimeoutMs === 'number') {
+      entry.waitTimeoutMs = payload.waitTimeoutMs;
+    }
   }
 
   appendStoredProfileSessionEntry(entry);
@@ -326,6 +375,11 @@ function getProfileSessionRoute(url: string): {
   scenario?: string;
   runId?: string;
   command?: string;
+  commandId?: string;
+  queueId?: string;
+  sequence?: number;
+  waitForMilestone?: string;
+  waitTimeoutMs?: number;
 } | null {
   const parsed = ExpoLinking.parse(url);
   const segments = [parsed.hostname, parsed.path]
@@ -347,8 +401,22 @@ function getProfileSessionRoute(url: string): {
     typeof parsed.queryParams?.runId === 'string' ? parsed.queryParams.runId : undefined;
   const command =
     typeof parsed.queryParams?.command === 'string' ? parsed.queryParams.command : undefined;
-
-  return { action, scenario, runId, command };
+  const commandId =
+    typeof parsed.queryParams?.commandId === 'string' ? parsed.queryParams.commandId : undefined;
+  const sequence =
+    typeof parsed.queryParams?.sequence === 'string' && Number.isInteger(Number(parsed.queryParams.sequence))
+      ? Number(parsed.queryParams.sequence)
+      : undefined;
+  const queueId =
+    typeof parsed.queryParams?.queueId === 'string' ? parsed.queryParams.queueId : undefined;
+  const waitForMilestone =
+    typeof parsed.queryParams?.waitForMilestone === 'string' ? parsed.queryParams.waitForMilestone : undefined;
+  const waitTimeoutMs =
+    typeof parsed.queryParams?.waitTimeoutMs === 'string' && Number.isInteger(Number(parsed.queryParams.waitTimeoutMs))
+      ? Number(parsed.queryParams.waitTimeoutMs)
+      : undefined;
+
+  return { action, scenario, runId, command, commandId, queueId, sequence, waitForMilestone, waitTimeoutMs };
 }
 
 function queuePendingProfileCommand(command: ProfileSessionCommand) {
@@ -456,17 +524,32 @@ function notifyProfileCommandListeners(command: ProfileSessionCommand) {
 
   const targetDispatched = dispatchProfileCommandTarget(command);
   if (targetDispatched) {
+    logProfileSession('command', {
+      ...command,
+      status: 'completed',
+      result: 'target-dispatched',
+    });
     return;
   }
 
   if (profileCommandListeners.size === 0) {
     queuePendingProfileCommand(command);
+    logProfileSession('command', {
+      ...command,
+      status: 'queued',
+      reason: 'no-command-listener',
+    });
     return;
   }
 
   for (const listener of profileCommandListeners) {
     listener(command);
   }
+  logProfileSession('command', {
+    ...command,
+    status: 'delivered',
+    result: 'listener-notified',
+  });
 }
 
 function flushPendingProfileCommands(listener: (command: ProfileSessionCommand) => void) {
@@ -560,10 +643,18 @@ export function applyProfileSessionUrl(url: string | null | undefined): boolean
       scenario: route.scenario,
       runId: route.runId,
       command: route.command,
+      ...(route.commandId ? { commandId: route.commandId } : {}),
+      ...(route.queueId ? { queueId: route.queueId } : {}),
+      ...(typeof route.sequence === 'number' ? { sequence: route.sequence } : {}),
       source: 'deeplink' as const,
       timestamp,
+      ...(route.waitForMilestone ? { waitForMilestone: route.waitForMilestone } : {}),
+      ...(typeof route.waitTimeoutMs === 'number' ? { waitTimeoutMs: route.waitTimeoutMs } : {}),
     };
-    logProfileSession('command', command);
+    logProfileSession('command', {
+      ...command,
+      status: 'received',
+    });
     notifyProfileCommandListeners(command);
     return true;
   }
@@ -776,7 +867,10 @@ export function useProfileSessionBootstrap(): void {
         }
 
         markProfileCommandIdProcessed(storageCommand);
-        logProfileSession('command', storageCommand);
+        logProfileSession('command', {
+          ...storageCommand,
+          status: 'received',
+        });
         notifyProfileCommandListeners(storageCommand);
       }
     };

package/dist/core/agent-summary.d.ts

@@ -1,10 +1,10 @@
 /**
  * Builds the minimum agent-facing markdown summary for a run.
  *
- * @param {{health: Record<string, unknown>, verdict: Record<string, unknown>, comparison?: Record<string, unknown> | null}} options
+ * @param {{health: Record<string, unknown>, verdict: Record<string, unknown>, comparison?: Record<string, unknown> | null, manifest?: Record<string, unknown> | null}} options
  * @returns {string}
  */
-declare function buildAgentSummaryMarkdown({ health, verdict, comparison }: AgentSummaryInput): string;
+declare function buildAgentSummaryMarkdown({ health, verdict, comparison, manifest }: AgentSummaryInput): string;
 export { buildAgentSummaryMarkdown, };
 export type { AgentSummaryInput, SummaryRecord, };
 type SummaryRecord = Record<string, unknown>;
@@ -12,4 +12,5 @@ type AgentSummaryInput = {
     health: SummaryRecord;
     verdict: SummaryRecord;
     comparison?: SummaryRecord | null;
+    manifest?: SummaryRecord | null;
 };

package/dist/core/agent-summary.js

@@ -122,13 +122,54 @@ function formatComparisonBasis(comparison) {
     }
     return lines;
 }
+/**
+ * Formats attempt terminal semantics for agent-readable summaries.
+ *
+ * @param {SummaryRecord | null | undefined} manifest
+ * @returns {string[]}
+ */
+function formatAttempt(manifest) {
+    const attempt = manifest?.attempt;
+    if (!attempt || typeof attempt !== 'object' || Array.isArray(attempt)) {
+        return [];
+    }
+    const attemptRecord = attempt;
+    const classification = attemptRecord.classification && typeof attemptRecord.classification === 'object' && !Array.isArray(attemptRecord.classification)
+        ? attemptRecord.classification
+        : {};
+    const cleanup = attemptRecord.cleanup && typeof attemptRecord.cleanup === 'object' && !Array.isArray(attemptRecord.cleanup)
+        ? attemptRecord.cleanup
+        : {};
+    const partialArtifacts = attemptRecord.partialArtifacts && typeof attemptRecord.partialArtifacts === 'object' && !Array.isArray(attemptRecord.partialArtifacts)
+        ? attemptRecord.partialArtifacts
+        : {};
+    const retryOfAttemptId = firstString([attemptRecord.retryOfAttemptId], '');
+    const retryReason = firstString([attemptRecord.retryReason], '');
+    const lines = [
+        '',
+        '## attempt',
+        '',
+        `- Attempt: ${code(firstString([attemptRecord.attemptId], 'unknown-attempt'))} (${attemptRecord.attemptNumber ?? 'unknown'}/${attemptRecord.maxAttempts ?? 'unknown'})`,
+        `- Terminal state: ${code(firstString([attemptRecord.terminalState], 'unknown'))}`,
+        `- Classification: ${code(firstString([classification.category], 'unknown'))}${classification.code ? ` ${code(classification.code)}` : ''}`,
+        `- Cleanup: ${code(firstString([cleanup.status], 'unknown'))}`,
+        `- Partial artifacts valid: ${partialArtifacts.valid === true ? 'true' : 'false'} - ${firstString([partialArtifacts.reason], 'no reason recorded')}`,
+    ];
+    if (retryOfAttemptId || retryReason) {
+        lines.push(`- Retry lineage: previous=${code(retryOfAttemptId || 'unknown')} reason=${retryReason || 'not recorded'}`);
+    }
+    if (Array.isArray(partialArtifacts.paths) && partialArtifacts.paths.length > 0) {
+        lines.push(`- Partial artifact paths: ${partialArtifacts.paths.map((item) => code(item)).join(', ')}`);
+    }
+    return lines;
+}
 /**
  * Builds the minimum agent-facing markdown summary for a run.
  *
- * @param {{health: Record<string, unknown>, verdict: Record<string, unknown>, comparison?: Record<string, unknown> | null}} options
+ * @param {{health: Record<string, unknown>, verdict: Record<string, unknown>, comparison?: Record<string, unknown> | null, manifest?: Record<string, unknown> | null}} options
  * @returns {string}
  */
-function buildAgentSummaryMarkdown({ health, verdict, comparison = null }) {
+function buildAgentSummaryMarkdown({ health, verdict, comparison = null, manifest = null }) {
     const scenarioId = firstString([health?.scenarioId, verdict?.scenarioId], 'unknown-scenario');
     const runId = firstString([health?.runId, verdict?.runId], 'unknown-run');
     const healthStatus = firstString([health?.healthStatus], 'failed');
@@ -169,6 +210,7 @@ function buildAgentSummaryMarkdown({ health, verdict, comparison = null }) {
     if (failedBudgets.length > 0) {
         lines.push('', '## failed budgets', '', ...failedBudgets);
     }
+    lines.push(...formatAttempt(manifest));
     if (comparison) {
         lines.push('', '## comparison', '', firstString([comparison.summary], 'No comparison summary provided.'));
         lines.push(...formatComparisonBasis(comparison));

package/dist/core/artifact-contract.d.ts

@@ -8,6 +8,12 @@ type ProfileEvent = ArtifactRecord & {
     atMs?: number;
     timestamp?: number | string;
 };
+type ProfileSessionEntry = ArtifactRecord & {
+    kind?: string;
+    scenario?: string;
+    runId?: string;
+    timestamp?: number | string;
+};
 type BudgetCheck = {
     name: string;
     actual: unknown;
@@ -36,6 +42,17 @@ declare function extractProfileEvents(logText: string, filters?: {
     runId?: string;
     scenario?: string;
 }): ProfileEvent[];
+/**
+ * Extracts structured profile-session entries from device logs.
+ *
+ * @param {string} logText
+ * @param {{runId?: string, scenario?: string}} [filters]
+ * @returns {Record<string, unknown>[]}
+ */
+declare function extractProfileSessionEntries(logText: string, filters?: {
+    runId?: string;
+    scenario?: string;
+}): ProfileSessionEntry[];
 /**
  * Builds timing metrics from app-emitted profile events.
  *
@@ -75,8 +92,9 @@ declare function sortValue(value: any): any;
  * @param {{events: Record<string, unknown>[], startedAt?: string, phaseMap?: Record<string, string> | null, owner?: string | null}} options
  * @returns {Record<string, unknown>[]}
  */
-declare function buildCausalTimeline({ events, startedAt, phaseMap, owner, }: {
+declare function buildCausalTimeline({ events, sessionEntries, startedAt, phaseMap, owner, }: {
     events: ProfileEvent[];
+    sessionEntries?: ProfileSessionEntry[];
     startedAt?: string;
     phaseMap?: ArtifactRecord | null;
     owner?: string | null;
@@ -107,7 +125,7 @@ declare function buildCausalRun({ scenario, flowId, runId, platform, buildFlavor
  * @param {Record<string, unknown>} options
  * @returns {Record<string, unknown>}
  */
-declare function buildManifest({ scenario, scenarioHash, runId, platform, status, startedAt, endedAt, interactionDriver, comparisonLane, simulator, bundleId, gitSha, toolVersions, artifacts, failureReason, }: ArtifactRecord): ArtifactRecord;
+declare function buildManifest({ scenario, scenarioHash, runId, attemptId, attemptNumber, maxAttempts, retryOfAttemptId, retryReason, platform, status, terminalState, startedAt, endedAt, interactionDriver, comparisonLane, classification, cleanup, partialArtifacts, preconditions, postconditions, simulator, bundleId, gitSha, toolVersions, cohort, artifacts, failureReason, }: ArtifactRecord): ArtifactRecord;
 /**
  * Builds the human-readable profile summary.
  *
@@ -147,5 +165,5 @@ declare function evaluateUiContract({ rawDescription, requiredIdentifierPatterns
     checks: ArtifactRecord[];
     missingPatterns: string[];
 };
-export { PROFILE_EVENT_PREFIX, buildBudgetVerdict, buildCausalRun, buildCausalTimeline, buildManifest, buildMetricsFromProfileEvents, buildSummaryMarkdown, evaluateUiContract, evaluateProfileBudgets, extractCandidateIdentifiers, extractProfileEvents, findMatchingIdentifier, percentile, sortValue, };
-export type { ArtifactRecord, BudgetCheck, ProfileEvent, };
+export { PROFILE_EVENT_PREFIX, buildBudgetVerdict, buildCausalRun, buildCausalTimeline, buildManifest, buildMetricsFromProfileEvents, buildSummaryMarkdown, evaluateUiContract, evaluateProfileBudgets, extractCandidateIdentifiers, extractProfileEvents, extractProfileSessionEntries, findMatchingIdentifier, percentile, sortValue, };
+export type { ArtifactRecord, BudgetCheck, ProfileEvent, ProfileSessionEntry, };