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/kernel/src/success-text.test.ts

@@ -0,0 +1,22 @@
+import assert from 'node:assert/strict';
+import { describe, test } from 'vitest';
+import { readCommandMessage, readResponseWarnings } 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');
+  });
+});
+
+describe('readResponseWarnings', () => {
+  test('the shared warnings parser ignores anything that is not a note', () => {
+    assert.deepEqual(readResponseWarnings({ warnings: ['a note', 42, { nested: true }, null] }), [
+      'a note',
+    ]);
+    assert.deepEqual(readResponseWarnings({}), []);
+    assert.deepEqual(readResponseWarnings(undefined), []);
+  });
+});

packages/kernel/src/success-text.ts

@@ -12,3 +12,16 @@ 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): every reader of a response or error record — daemon outcome,
+ * CLI success line, CLI/MCP error text — goes through here, so one field
+ * contract has one parser. 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/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/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),
   };

src/daemon/session-lifecycle/internal/__tests__/session-open-warnings.test.ts

@@ -1,6 +1,6 @@
 import assert from 'node:assert/strict';
 import { test } from 'vitest';
-import { appendResponseWarning, readResponseWarnings } from '../session-open-warnings.ts';
+import { appendResponseWarning } from '../session-open-warnings.ts';
 
 test('a producer adds its note without dropping the notes already on the response', () => {
   const responseData: Record<string, unknown> = { warnings: ['the session is already open'] };
@@ -21,10 +21,12 @@ test('a response that carries no warnings yet starts from an empty list', () =>
   assert.deepEqual(responseData.warnings, ['the device was taken over']);
 });
 
-test('reading warnings ignores anything that is not a note', () => {
-  assert.deepEqual(readResponseWarnings({ warnings: ['a note', 42, { nested: true }, null] }), [
-    'a note',
-  ]);
-  assert.deepEqual(readResponseWarnings({}), []);
-  assert.deepEqual(readResponseWarnings(undefined), []);
+test('accumulating onto non-note entries keeps only the notes and the new one', () => {
+  const responseData: Record<string, unknown> = {
+    warnings: ['a note', 42, { nested: true }, null],
+  };
+
+  appendResponseWarning(responseData, 'the device was taken over');
+
+  assert.deepEqual(responseData.warnings, ['a note', 'the device was taken over']);
 });

src/daemon/session-lifecycle/internal/session-open-foreground.ts

@@ -7,7 +7,7 @@ import type {
   InspectDeviceRuntimeFacts,
 } from '../../request-runtime-binding.ts';
 import { errorResponse } from '../../response.ts';
-import { readResponseWarnings } from './session-open-warnings.ts';
+import { readResponseWarnings } from '@agent-device/kernel/success-text';
 
 export type ForegroundOpenResolution =
   | { type: 'not-requested' }

src/daemon/session-lifecycle/internal/session-open-warnings.ts

@@ -1,3 +1,5 @@
+import { readResponseWarnings } from '@agent-device/kernel/success-text';
+
 /**
  * Response-level warnings accumulate: every `open` producer adds its own note and keeps the ones
  * already there, so a producer never has to know which other note ran first.
@@ -8,10 +10,3 @@ export function appendResponseWarning(
 ): void {
   responseData.warnings = [...readResponseWarnings(responseData), warning];
 }
-
-export function readResponseWarnings(responseData: Record<string, unknown> | undefined): string[] {
-  const warnings = responseData?.warnings;
-  return Array.isArray(warnings)
-    ? warnings.filter((warning): warning is string => typeof warning === 'string')
-    : [];
-}

src/mcp/tool-error.ts

@@ -4,7 +4,8 @@ import {
   type NormalizedError,
 } from '@agent-device/kernel/errors';
 import { formatReplayDivergenceReport } from '@agent-device/ad-replay/divergence';
-import { formatErrorCandidateViews, readResponseWarnings } from '../commands/output/error.ts';
+import { readResponseWarnings } from '@agent-device/kernel/success-text';
+import { formatErrorCandidateViews } from '../commands/output/error.ts';
 import { collapseWarningText } from '../commands/output-common.ts';
 
 export function normalizeToolError(error: unknown): NormalizedError {