refactor(kernel): own the response-warnings field contract beside the message reader

Four call sites read the composable warnings field with their own
Array.isArray filters (the daemon append, the daemon attempt outcome, the
CLI success line, the CLI/MCP error text), and the PR had grown a fifth.
The field has one contract now: kernel/success-text readResponseWarnings,
next to readCommandMessage, with the daemon append, the attempt outcome,
messageWithWarningsText, and both error renderers as its named consumers.
The CLI-side reader the PR introduced is deleted, not wrapped.

Author: thymikee

packages/contracts/src/snapshot-capture-annotations.test.ts

@@ -0,0 +1,31 @@
+import assert from 'node:assert/strict';
+import { test } from 'vitest';
+import { readResponseWarnings } from '@agent-device/kernel/success-text';
+import { readSerializedSnapshotCaptureAnnotations } from './snapshot-capture-annotations.ts';
+
+test('the annotations filter and the shared warnings parser agree on adversarial arrays', () => {
+  for (const warnings of [
+    ['a note'],
+    ['a note', 42, { nested: true }, null],
+    ['', 'kept'],
+    ['a note', ''],
+  ]) {
+    assert.deepEqual(
+      readSerializedSnapshotCaptureAnnotations({ warnings }).warnings,
+      readResponseWarnings({ warnings }),
+      `drift for ${JSON.stringify(warnings)}`,
+    );
+  }
+});
+
+test('an empty warnings array serializes back to absent', () => {
+  assert.equal(readSerializedSnapshotCaptureAnnotations({ warnings: [] }).warnings, undefined);
+});
+
+test('absent or non-array warnings stay absent on the serialized annotations', () => {
+  assert.equal(readSerializedSnapshotCaptureAnnotations({}).warnings, undefined);
+  assert.equal(
+    readSerializedSnapshotCaptureAnnotations({ warnings: 'a note' }).warnings,
+    undefined,
+  );
+});

packages/contracts/src/snapshot-capture-annotations.ts

@@ -57,6 +57,9 @@ export function readSerializedSnapshotCaptureAnnotations(
   data: Record<string, unknown>,
 ): PublicSnapshotCaptureAnnotations {
   const androidSnapshot = readObject(data.androidSnapshot);
+  // Declared exception to kernel's shared `readResponseWarnings` (see its doc): this facade
+  // pins its eager module closure, and absent-or-non-array keeps the serialized tri-state.
+  // `snapshot-capture-annotations.test.ts` cross-checks this filter against the shared parser.
   const warnings = Array.isArray(data.warnings)
     ? data.warnings.filter((entry): entry is string => typeof entry === 'string')
     : undefined;

packages/kernel/src/success-text.test.ts

@@ -0,0 +1,12 @@
+import assert from 'node:assert/strict';
+import { describe, test } from 'vitest';
+import { readCommandMessage } from './success-text.ts';
+
+describe('readCommandMessage', () => {
+  test('an empty message is absent, not an empty success line', () => {
+    assert.equal(readCommandMessage({ message: '' }), null);
+    assert.equal(readCommandMessage({ message: 42 }), null);
+    assert.equal(readCommandMessage(undefined), null);
+    assert.equal(readCommandMessage({ message: 'Replayed 7 steps' }), 'Replayed 7 steps');
+  });
+});

packages/kernel/src/success-text.ts

@@ -12,3 +12,24 @@ export function withSuccessText<T extends Record<string, unknown>>(
 export function readCommandMessage(data: Record<string, unknown> | undefined): string | null {
   return typeof data?.message === 'string' && data.message.length > 0 ? data.message : null;
 }
+
+/**
+ * The composable response-warnings channel (skipped `optional` steps, capture
+ * degradations): readers that project a response or error record onto note
+ * strings go through here — daemon append and attempt outcome, CLI success
+ * line, CLI/MCP error text, SDK client (open and screenshot result), and the
+ * snapshot text renderer — so one field contract has one parser. Consumers may
+ * add rendering rules on top (snapshot text and screenshot result drop empty
+ * notes; screenshot result keeps absent-means-undefined). The one declared
+ * exception is contracts' `readSerializedSnapshotCaptureAnnotations`, which
+ * keeps a local copy of the filter: contracts facades pin their eager module
+ * closure (`scripts/__tests__/eager-closure-budgets.test.ts`) and this module
+ * is outside it; its test cross-checks both parses so the contract cannot
+ * drift. Non-string entries are other producers' bugs.
+ */
+export function readResponseWarnings(data: Record<string, unknown> | undefined): string[] {
+  const warnings = data?.warnings;
+  return Array.isArray(warnings)
+    ? warnings.filter((warning): warning is string => typeof warning === 'string')
+    : [];
+}

src/agent-device-client.ts

@@ -72,6 +72,7 @@ import {
   type MetroSessionHints,
 } from './metro/metro-session-hints.ts';
 import { isRecord } from '@agent-device/kernel/record';
+import { readResponseWarnings } from '@agent-device/kernel/success-text';
 import { createLeaseClient } from './client/lease-client.ts';
 import { normalizeScreenshotCaptureResult } from './client/screenshot-result.ts';
 
@@ -266,9 +267,7 @@ export function createAgentDeviceClient(
         const device = normalizeOpenDevice(data);
         const appBundleId = readOptionalString(data, 'appBundleId');
         const appId = appBundleId;
-        const warnings = Array.isArray(data.warnings)
-          ? data.warnings.filter((warning): warning is string => typeof warning === 'string')
-          : [];
+        const warnings = readResponseWarnings(data);
         return {
           session,
           ...(warnings.length > 0 ? { warnings } : {}),

src/client/screenshot-result.ts

@@ -1,6 +1,7 @@
 import type { ScreenshotResultData } from '@agent-device/contracts/capture';
 import type { CaptureScreenshotResult } from '@agent-device/contracts/client';
 import { isRecord, parsePoint, parseRect, readRequiredString } from '@agent-device/kernel/record';
+import { readResponseWarnings } from '@agent-device/kernel/success-text';
 import type { ScreenshotOverlayRef } from '@agent-device/kernel/snapshot';
 
 export function pickScreenshotResultData(value: ScreenshotResultData): ScreenshotResultData {
@@ -45,7 +46,7 @@ type ScreenshotOverlayRefData = {
 
 function readScreenshotResultData(value: unknown): ScreenshotResultData | undefined {
   if (!isRecord(value)) return undefined;
-  const warnings = readScreenshotWarnings(value.warnings);
+  const warnings = readScreenshotWarnings(value);
   return pickScreenshotResultData({
     path: readStringField(value, 'path'),
     width: readNumberField(value, 'width'),
@@ -76,9 +77,11 @@ function readScreenshotOverlayRefs(value: unknown): ScreenshotOverlayRef[] | und
   });
 }
 
-function readScreenshotWarnings(value: unknown): string[] | undefined {
-  if (!Array.isArray(value)) return undefined;
-  return value.filter((entry): entry is string => typeof entry === 'string' && entry.length > 0);
+function readScreenshotWarnings(data: Record<string, unknown>): string[] | undefined {
+  // An absent or non-array field is "no warnings channel on this result";
+  // the field contract itself is the shared parser's.
+  if (!Array.isArray(data.warnings)) return undefined;
+  return readResponseWarnings(data).filter((warning) => warning.length > 0);
 }
 
 function readScreenshotOverlayRef(

src/commands/output-common.ts

@@ -1,4 +1,4 @@
-import { readCommandMessage } from '@agent-device/kernel/success-text';
+import { readCommandMessage, readResponseWarnings } from '@agent-device/kernel/success-text';
 import type { CommandProgressState } from './command-progress.ts';
 import type { CliOutput } from './command-contract.ts';
 
@@ -37,9 +37,7 @@ export function messageCliOutput(result: Record<string, unknown>): CliOutput {
  */
 export function messageWithWarningsText(result: Record<string, unknown>): string | null {
   const message = readCommandMessage(result);
-  const warnings = Array.isArray(result.warnings)
-    ? result.warnings.filter((warning): warning is string => typeof warning === 'string')
-    : [];
+  const warnings = readResponseWarnings(result);
   if (warnings.length === 0) return message;
   return [message, ...warnings.map((warning) => `Warning: ${collapseWarningText(warning)}`)]
     .filter(Boolean)

src/commands/output/error.ts

@@ -5,6 +5,7 @@ import {
   type ErrorCandidateView,
   type NormalizedError,
 } from '@agent-device/kernel/errors';
+import { readResponseWarnings } from '@agent-device/kernel/success-text';
 import { formatReplayDivergenceReport } from '@agent-device/ad-replay/divergence';
 import { collapseWarningText } from '../output-common.ts';
 
@@ -54,13 +55,6 @@ export function printHumanError(
   }
 }
 
-export function readResponseWarnings(details: Record<string, unknown> | undefined): string[] {
-  const warnings = details?.warnings;
-  return Array.isArray(warnings)
-    ? warnings.filter((warning): warning is string => typeof warning === 'string')
-    : [];
-}
-
 export function formatErrorCandidateViews(views: ErrorCandidateView[]): string[] {
   return views.flatMap((view) => {
     if (view.kind === 'element-match') {

src/commands/output/snapshot.ts

@@ -14,6 +14,7 @@ import {
   type SnapshotUnchanged,
   type SnapshotVisibility,
 } from '@agent-device/kernel/snapshot';
+import { readResponseWarnings } from '@agent-device/kernel/success-text';
 import { buildMobileSnapshotPresentation } from '@agent-device/capture-kit/mobile-snapshot-semantics';
 
 type SnapshotTextOptions = {
@@ -281,13 +282,8 @@ function formatSparseSnapshotHint(
 }
 
 export function readSnapshotWarnings(data: Record<string, unknown>): string[] {
-  const rawWarnings = data.warnings;
-  if (!Array.isArray(rawWarnings)) {
-    return [];
-  }
-  return rawWarnings.filter(
-    (entry): entry is string => typeof entry === 'string' && entry.length > 0,
-  );
+  // Snapshot text additionally drops empty notes; the field contract is the shared parser's.
+  return readResponseWarnings(data).filter((warning) => warning.length > 0);
 }
 
 type SnapshotDisplayLine = ReturnType<typeof buildSnapshotDisplayLines>[number];

src/daemon/replay/internal/session-test-outcome.ts

@@ -1,4 +1,5 @@
 import { readSnapshotDiagnosticsSummary } from '@agent-device/contracts/capture';
+import { readResponseWarnings } from '@agent-device/kernel/success-text';
 import type { DaemonResponse } from '../../daemon-request.ts';
 import { isReplayInfrastructureFailure } from './session-test-infrastructure.ts';
 import type { ReplayTestAttemptFailed, ReplayTestAttemptOutcome } from '@agent-device/replay-test';
@@ -18,7 +19,7 @@ export function toReplayTestAttemptOutcome(response: DaemonResponse): ReplayTest
       status: 'failed',
       error: response.error,
       artifactPaths: readArtifactPaths(response.error.details?.artifactPaths),
-      warnings: readStringArray(response.error.details?.warnings),
+      warnings: readResponseWarnings(response.error.details),
       infrastructure: isReplayInfrastructureFailure(response),
       ...snapshotDiagnostics(response.error.details?.snapshotDiagnostics),
     };
@@ -28,7 +29,7 @@ export function toReplayTestAttemptOutcome(response: DaemonResponse): ReplayTest
     status: 'passed',
     replayed: typeof data?.replayed === 'number' ? data.replayed : 0,
     healed: typeof data?.healed === 'number' ? data.healed : 0,
-    warnings: readStringArray(data?.warnings),
+    warnings: readResponseWarnings(data),
     artifactPaths: readArtifactPaths(data?.artifactPaths),
     ...snapshotDiagnostics(data?.snapshotDiagnostics),
   };