@robota-sdk/agent-transport 3.0.0-beta.100

package/src/message-decoders.ts

@@ -0,0 +1,485 @@
+/**
+ * Owner-side runtime decoders for the wire message unions (issue #2045 / TRANS-005 adjacent).
+ *
+ * `wire-messages.ts` owns the TypeScript unions; this file owns turning `JSON.parse` output into one
+ * of them. Before it, the server did `JSON.parse(data) as TClientMessage` and each client did the
+ * same for `TServerMessage`, so valid JSON with an invalid shape crossed the boundary wearing a
+ * protocol type. Carriers now implement `raw string → owner decoder → typed message` and answer a
+ * refusal with the protocol's own `protocol_error` (server side) or client error (client side).
+ *
+ * `decodeClientMessage` is TOTAL: every variant and every nested field it carries is validated.
+ * `decodeServerMessage` validates every variant's discriminator and declared top-level fields; a
+ * payload OWNED BY ANOTHER PACKAGE (`IToolState`, `IExecutionResult`, background events, …) is
+ * checked as a non-array record (or array of records) here — its own total decoding belongs to its
+ * owner and is tracked there, not duplicated in a transport package.
+ */
+
+import {
+  SESSION_CHANGE_REFUSAL_CODES,
+  SESSION_DELETE_REFUSAL_CODES,
+} from '@robota-sdk/agent-interface-session';
+
+import type { TBackgroundControlAction, TClientMessage, TServerMessage } from './wire-messages.js';
+
+export type TMessageDecodeResult<TMessage> =
+  | { readonly ok: true; readonly message: TMessage }
+  | { readonly ok: false; readonly reason: string };
+
+/** Serialized frames larger than this are refused before any parse (a bounded inbound budget). */
+export const MAX_INBOUND_FRAME_BYTES = 4 * 1024 * 1024;
+
+type TRecord = Record<string, unknown>;
+
+function isRecord(value: unknown): value is TRecord {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+const isString = (v: unknown): v is string => typeof v === 'string';
+const isNonEmptyString = (v: unknown): v is string => typeof v === 'string' && v.length > 0;
+const isBoolean = (v: unknown): v is boolean => typeof v === 'boolean';
+const isFiniteNumber = (v: unknown): v is number => typeof v === 'number' && Number.isFinite(v);
+const isCount = (v: unknown): v is number => Number.isSafeInteger(v) && (v as number) >= 0;
+const isOptional =
+  (check: (v: unknown) => boolean) =>
+  (v: unknown): boolean =>
+    v === undefined || check(v);
+const isRecordArray = (v: unknown): boolean => Array.isArray(v) && v.every(isRecord);
+const isNullableRecord = (v: unknown): boolean => v === null || isRecord(v);
+const oneOf =
+  (members: readonly string[]) =>
+  (v: unknown): boolean =>
+    typeof v === 'string' && members.includes(v);
+/** A record, not an array, so a turn source added to the union without one here fails to compile. */
+const TURN_SOURCES: Readonly<
+  Record<Extract<TServerMessage, { type: 'turn_source' }>['source'], true>
+> = { user: true, 'agent-wakeup': true, peer: true, external: true };
+/** A history entry's envelope is this package's (`IWireHistoryEntry`); its `data` is the recorder's. */
+const isWireHistoryEntry = (v: unknown): boolean =>
+  isRecord(v) &&
+  isString(v['id']) &&
+  isString(v['timestamp']) &&
+  isString(v['category']) &&
+  isString(v['type']);
+const isWireHistoryEntries = (v: unknown): boolean =>
+  Array.isArray(v) && v.every(isWireHistoryEntry);
+/** #3282 §4: one row of `agent_definitions` — name, one-line description, plain-words location. */
+const isWireAgentDefinition = (v: unknown): boolean =>
+  isRecord(v) && isString(v['name']) && isString(v['description']) && isString(v['definedIn']);
+const isWireAgentDefinitions = (v: unknown): boolean =>
+  Array.isArray(v) && v.every(isWireAgentDefinition);
+
+type TFieldCheck = (value: unknown) => boolean;
+type TVariantShape = Readonly<Record<string, TFieldCheck>>;
+
+const BACKGROUND_TASK_KINDS = ['agent', 'process', 'scheduled'] as const;
+const BACKGROUND_TASK_MODES = ['foreground', 'background'] as const;
+const BACKGROUND_TASK_STATUSES = [
+  'queued',
+  'running',
+  'waiting_permission',
+  'sleeping',
+  'paused',
+  'completed',
+  'failed',
+  'cancelled',
+] as const;
+const BACKGROUND_CONTROL_ACTIONS: readonly TBackgroundControlAction[] = ['cancel', 'close', 'send'];
+
+const isBackgroundTaskListFilter: TFieldCheck = (v) =>
+  isRecord(v) &&
+  isOptional(oneOf(BACKGROUND_TASK_KINDS))(v['kind']) &&
+  isOptional(oneOf(BACKGROUND_TASK_STATUSES))(v['status']) &&
+  isOptional(oneOf(BACKGROUND_TASK_MODES))(v['mode']) &&
+  isOptional(isBoolean)(v['includeClosed']);
+const isBackgroundTaskInput: TFieldCheck = (v) =>
+  isRecord(v) && isOptional(isString)(v['prompt']) && isOptional(isString)(v['stdin']);
+const isBackgroundTaskLogCursor: TFieldCheck = (v) => isRecord(v) && isFiniteNumber(v['offset']);
+const isExecutionDetailCursor: TFieldCheck = (v) => isRecord(v) && isCount(v['offset']);
+const isPermissionResultValue: TFieldCheck = (v) =>
+  isBoolean(v) || v === 'allow-session' || v === 'allow-project';
+const isActionResponse: TFieldCheck = (v) =>
+  isRecord(v) &&
+  ((v['type'] === 'answer' &&
+    Array.isArray(v['values']) &&
+    v['values'].every(isString) &&
+    isOptional(isString)(v['text'])) ||
+    (v['type'] === 'cancelled' && v['values'] === undefined && v['text'] === undefined));
+
+type TSettingsPatch = Extract<TClientMessage, { type: 'update-settings' }>['patch'];
+/** Keyed by `field`, so a patch variant added to the union without a shape here fails to compile. */
+const SETTINGS_PATCH_SHAPES: Readonly<Record<TSettingsPatch['field'], TVariantShape>> = {
+  language: { language: isNonEmptyString },
+  outputStyle: { styleId: isNonEmptyString },
+  preset: { presetId: isNonEmptyString },
+  permissionMode: { mode: isNonEmptyString },
+  sandbox: { enabled: isBoolean },
+  removePermissionRule: {
+    scope: isNonEmptyString,
+    kind: oneOf(['allow', 'deny', 'ask']),
+    pattern: isNonEmptyString,
+  },
+  mcpServerEnabled: { serverId: isNonEmptyString, enabled: isBoolean },
+  reloadMcpServers: {},
+  pluginEnabled: { pluginId: isNonEmptyString, enabled: isBoolean },
+  reloadPlugins: {},
+  installPlugin: { pluginId: isNonEmptyString },
+  uninstallPlugin: { pluginId: isNonEmptyString },
+  // #3282 §4b: "Providers & Models" — Use, Model, Delete.
+  providerProfile: { profileName: isNonEmptyString },
+  providerModel: { profileName: isNonEmptyString, modelId: isNonEmptyString },
+  deleteProviderProfile: { profileName: isNonEmptyString },
+};
+const isSettingsPatch: TFieldCheck = (v) => {
+  if (!isRecord(v) || !isString(v['field'])) return false;
+  const field = v['field'];
+  if (!Object.prototype.hasOwnProperty.call(SETTINGS_PATCH_SHAPES, field)) return false;
+  const shape = SETTINGS_PATCH_SHAPES[field as TSettingsPatch['field']];
+  return Object.entries(shape).every(([key, check]) => check(v[key]));
+};
+
+type TWaitingLoopStopOutcome = Extract<TServerMessage, { type: 'waiting_loop_stop' }>['outcome'];
+/** Keyed by `kind`, so an outcome added to the union without a shape here fails to compile. */
+const WAITING_LOOP_STOP_OUTCOME_SHAPES: Readonly<
+  Record<TWaitingLoopStopOutcome['kind'], TVariantShape>
+> = {
+  none: {},
+  several: { message: isString },
+  stopped: { loopId: isNonEmptyString, message: isOptional(isString) },
+  failed: { loopId: isOptional(isNonEmptyString), message: isString },
+};
+const isWaitingLoopStopOutcome: TFieldCheck = (v) => {
+  if (!isRecord(v) || !isString(v['kind'])) return false;
+  const kind = v['kind'];
+  if (!Object.prototype.hasOwnProperty.call(WAITING_LOOP_STOP_OUTCOME_SHAPES, kind)) return false;
+  const shape = WAITING_LOOP_STOP_OUTCOME_SHAPES[kind as TWaitingLoopStopOutcome['kind']];
+  return Object.entries(shape).every(([field, check]) => check(v[field]));
+};
+
+/** Decode a `kind`-discriminated result union (the `TWaitingLoopStopOutcome` convention) from a shape
+ *  map keyed by `kind`. */
+function isKindDiscriminated(shapes: Readonly<Record<string, TVariantShape>>): TFieldCheck {
+  return (v) => {
+    if (!isRecord(v) || !isString(v['kind'])) return false;
+    const shape = Object.prototype.hasOwnProperty.call(shapes, v['kind']) ? shapes[v['kind']] : undefined;
+    if (shape === undefined) return false;
+    return Object.entries(shape).every(([field, check]) => check(v[field]));
+  };
+}
+
+// #3282 §4c: the Project panel's reads. Each result is the session method's own return value, crossing
+// the wire unchanged (the `TWaitingLoopStopOutcome` convention above) — decoded from a `kind`-keyed
+// shape map the same way.
+const PROJECT_FILE_STATUSES = [
+  'Added',
+  'Modified',
+  'Deleted',
+  'Renamed',
+  'Copied',
+  'Untracked',
+  'Conflicted',
+] as const;
+const isProjectStatusFile: TFieldCheck = (v) =>
+  isRecord(v) &&
+  isNonEmptyString(v['path']) &&
+  oneOf(PROJECT_FILE_STATUSES)(v['status']) &&
+  isOptional(isNonEmptyString)(v['renamedFrom']) &&
+  isOptional(isFiniteNumber)(v['added']) &&
+  isOptional(isFiniteNumber)(v['removed']);
+const isProjectStatusFiles: TFieldCheck = (v) => Array.isArray(v) && v.every(isProjectStatusFile);
+
+type TProjectStatusReadResult = Extract<TServerMessage, { type: 'project_status' }>['result'];
+const PROJECT_STATUS_READ_SHAPES: Readonly<Record<TProjectStatusReadResult['kind'], TVariantShape>> = {
+  status: {
+    branch: isOptional(isString),
+    unborn: isBoolean,
+    files: isProjectStatusFiles,
+    truncated: isBoolean,
+  },
+  'not-a-repository': {},
+  failed: { message: isString },
+};
+const isProjectStatusRead = isKindDiscriminated(PROJECT_STATUS_READ_SHAPES);
+
+const DIFF_LINE_TYPES = ['add', 'remove', 'context', 'hunk'] as const;
+const isDiffLine: TFieldCheck = (v) =>
+  isRecord(v) && oneOf(DIFF_LINE_TYPES)(v['type']) && isString(v['text']) && isFiniteNumber(v['lineNumber']);
+const isDiffLines: TFieldCheck = (v) => Array.isArray(v) && v.every(isDiffLine);
+
+type TProjectDiffReadResult = Extract<TServerMessage, { type: 'project_diff' }>['result'];
+const PROJECT_DIFF_READ_SHAPES: Readonly<Record<TProjectDiffReadResult['kind'], TVariantShape>> = {
+  diff: { diffLines: isDiffLines, truncated: isBoolean },
+  'not-a-repository': {},
+  'outside-workspace': {},
+  failed: { message: isString },
+};
+const isProjectDiffRead = isKindDiscriminated(PROJECT_DIFF_READ_SHAPES);
+
+type TProjectMemoryReadResult = Extract<TServerMessage, { type: 'project_memory' }>['result'];
+const PROJECT_MEMORY_READ_SHAPES: Readonly<Record<TProjectMemoryReadResult['kind'], TVariantShape>> = {
+  memory: { content: isString, path: isNonEmptyString, truncated: isBoolean },
+  unavailable: { message: isString },
+};
+const isProjectMemoryRead = isKindDiscriminated(PROJECT_MEMORY_READ_SHAPES);
+
+/** One entry per `TClientMessage` variant — a variant added to the union without one fails the test. */
+export const CLIENT_MESSAGE_SHAPES: Readonly<Record<TClientMessage['type'], TVariantShape>> = {
+  submit: { prompt: isNonEmptyString },
+  command: {
+    name: isNonEmptyString,
+    args: isOptional(isString),
+    requestId: isOptional(isNonEmptyString),
+  },
+  abort: {},
+  'cancel-queue': {},
+  'get-messages': {},
+  'get-history': { fromIndex: isOptional(isCount) },
+  'get-prompts': {},
+  'get-context': {},
+  'get-commands': {},
+  'get-status': {},
+  'list-models': { requestId: isNonEmptyString },
+  'get-agent-definitions': { requestId: isNonEmptyString },
+  'list-sessions': { requestId: isNonEmptyString },
+  'new-session': { requestId: isOptional(isNonEmptyString) },
+  'switch-session': { sessionId: isNonEmptyString, requestId: isOptional(isNonEmptyString) },
+  'rename-session': {
+    sessionId: isNonEmptyString,
+    name: isNonEmptyString,
+    requestId: isNonEmptyString,
+  },
+  'delete-session': { sessionId: isNonEmptyString, requestId: isNonEmptyString },
+  'get-usage-report': {},
+  'get-personal-usage-report': {
+    requestId: isNonEmptyString,
+    period: oneOf(['7d', '30d']),
+    timezone: isNonEmptyString,
+  },
+  'get-stored-session-usage-report': {
+    requestId: isNonEmptyString,
+    sessionId: isNonEmptyString,
+  },
+  'get-executing': {},
+  'get-pending': {},
+  'get-execution-workspace': {},
+  'read-execution-detail': {
+    requestId: isNonEmptyString,
+    entryId: isNonEmptyString,
+    cursor: isOptional(isExecutionDetailCursor),
+  },
+  'stop-waiting-loop': { requestId: isNonEmptyString },
+  'project-status': { requestId: isNonEmptyString },
+  'project-diff': { requestId: isNonEmptyString, path: isNonEmptyString },
+  'project-memory': { requestId: isNonEmptyString },
+  'call-app-tool': {
+    requestId: isNonEmptyString,
+    viewId: isNonEmptyString,
+    name: isNonEmptyString,
+    arguments: isRecord,
+  },
+  'read-app-view': { requestId: isNonEmptyString, viewId: isNonEmptyString },
+  'get-background-tasks': { filter: isOptional(isBackgroundTaskListFilter) },
+  'get-background-task': { taskId: isNonEmptyString },
+  'get-background-job-groups': {},
+  'get-background-job-group': { groupId: isNonEmptyString },
+  'wait-background-job-group': { groupId: isNonEmptyString },
+  'cancel-background-task': { taskId: isNonEmptyString, reason: isOptional(isString) },
+  'close-background-task': { taskId: isNonEmptyString },
+  'send-background-task': { taskId: isNonEmptyString, input: isBackgroundTaskInput },
+  'read-background-task-log': {
+    taskId: isNonEmptyString,
+    cursor: isOptional(isBackgroundTaskLogCursor),
+  },
+  'permission-response': { id: isNonEmptyString, result: isPermissionResultValue },
+  'ask-response': { id: isNonEmptyString, response: isActionResponse },
+  resume: { lastSeq: isFiniteNumber },
+  ack: { seq: isFiniteNumber },
+  'get-settings': { requestId: isNonEmptyString },
+  'update-settings': { requestId: isNonEmptyString, patch: isSettingsPatch },
+};
+
+const authored: TVariantShape = { driverId: isOptional(isString) };
+
+/** One entry per `TServerMessage` variant. Foreign-owned payloads are checked as records (see header). */
+export const SERVER_MESSAGE_SHAPES: Readonly<Record<TServerMessage['type'], TVariantShape>> = {
+  text_delta: { delta: isString, ...authored },
+  user_message: { content: isString, ...authored },
+  tool_start: { state: isRecord, ...authored },
+  tool_end: { state: isRecord, ...authored },
+  thinking: { isThinking: isBoolean, ...authored },
+  complete: { result: isRecord, ...authored },
+  interrupted: { result: isRecord, ...authored },
+  error: {
+    message: isString,
+    code: isOptional(oneOf(['auth', 'rate_limit', 'model_unavailable', 'network', 'provider'])),
+    provider: isOptional(isString),
+    retryAfterSeconds: isOptional(isFiniteNumber),
+    model: isOptional(isString),
+    ...authored,
+  },
+  command_result: {
+    name: isString,
+    message: isString,
+    success: isBoolean,
+    requestId: isOptional(isString),
+  },
+  messages: { messages: isRecordArray, display: isOptional(isRecordArray), ...authored },
+  history: { startIndex: isCount, total: isCount, entries: isWireHistoryEntries },
+  context: { state: isRecord },
+  history_changed: {
+    compact: isOptional(
+      (value) =>
+        isRecord(value) &&
+        oneOf(['auto', 'manual'])(value['trigger']) &&
+        isFiniteNumber(value['beforeUsedPercentage']) &&
+        isFiniteNumber(value['afterUsedPercentage']),
+    ),
+  },
+  turn_source: { source: oneOf(Object.keys(TURN_SOURCES)) },
+  commands: { commands: isRecordArray, skills: isRecordArray },
+  session_status: { status: isRecord },
+  model_list: {
+    requestId: isNonEmptyString,
+    groups: isRecordArray,
+    currentProfile: isOptional(isString),
+    currentModel: isString,
+  },
+  agent_definitions: {
+    requestId: isNonEmptyString,
+    agents: isWireAgentDefinitions,
+    current: isNonEmptyString,
+  },
+  sessions: { requestId: isNonEmptyString, listing: isRecord },
+  sessions_error: {
+    requestId: isNonEmptyString,
+    code: oneOf(['not_available', 'list_failed']),
+    message: isString,
+  },
+  session_switched: { event: isRecord },
+  session_change_failed: {
+    code: oneOf(SESSION_CHANGE_REFUSAL_CODES),
+    message: isString,
+    requestId: isOptional(isString),
+  },
+  session_renamed_in_list: { requestId: isNonEmptyString, sessionId: isString, name: isString },
+  session_rename_failed: { requestId: isNonEmptyString, message: isString },
+  session_deleted: { requestId: isNonEmptyString, sessionId: isString },
+  session_delete_failed: {
+    requestId: isNonEmptyString,
+    code: oneOf(SESSION_DELETE_REFUSAL_CODES),
+    message: isString,
+  },
+  usage_report: { report: isRecord },
+  personal_usage_report: { requestId: isNonEmptyString, report: isRecord },
+  personal_usage_report_error: {
+    requestId: isNonEmptyString,
+    code: oneOf(['not_available', 'report_failed']),
+    message: isString,
+  },
+  stored_session_usage_report: {
+    requestId: isNonEmptyString,
+    sessionId: isNonEmptyString,
+    report: isRecord,
+  },
+  stored_session_usage_report_error: {
+    requestId: isNonEmptyString,
+    sessionId: isNonEmptyString,
+    code: oneOf(['not_available', 'report_failed']),
+    message: isString,
+  },
+  executing: { executing: isBoolean },
+  // An older host sends no count; a client then counts the one prompt it can see.
+  pending: { pending: (v) => v === null || isString(v), pendingCount: isOptional(isCount) },
+  execution_workspace_event: { snapshot: isRecord },
+  execution_detail: { requestId: isNonEmptyString, page: isRecord },
+  execution_detail_error: { requestId: isNonEmptyString, message: isString },
+  waiting_loop_stop: { requestId: isNonEmptyString, outcome: isWaitingLoopStopOutcome },
+  project_status: { requestId: isNonEmptyString, result: isProjectStatusRead },
+  project_diff: { requestId: isNonEmptyString, result: isProjectDiffRead },
+  project_memory: { requestId: isNonEmptyString, result: isProjectMemoryRead },
+  // `data` is whatever JSON the tool returned, so any value passes, null included; absent is fine.
+  app_tool_result: {
+    requestId: isNonEmptyString,
+    success: isBoolean,
+    data: () => true,
+    parts: isOptional(isRecordArray),
+    error: isOptional(isString),
+  },
+  app_view: { requestId: isNonEmptyString, view: isRecord },
+  background_task_event: { event: isRecord },
+  background_job_group_event: { event: isRecord },
+  plan_event: { event: isRecord },
+  context_file_refreshed: { event: isRecord },
+  branch_event: { event: isRecord },
+  background_tasks: { tasks: isRecordArray },
+  background_task: { taskId: isString, task: isNullableRecord },
+  background_job_groups: { groups: isRecordArray },
+  background_job_group: { groupId: isString, group: isNullableRecord },
+  background_task_log: { taskId: isString, page: isRecord },
+  permission_request: { event: isRecord },
+  ask_request: { event: isRecord },
+  prompt_resolved: { event: isRecord },
+  ui_intent: { event: isRecord },
+  session_renamed: { event: isRecord },
+  history_cleared: {},
+  background_task_control_result: {
+    action: oneOf(BACKGROUND_CONTROL_ACTIONS),
+    taskId: isString,
+    success: isBoolean,
+    message: isOptional(isString),
+  },
+  protocol_error: { message: isString, requestId: isOptional(isString) },
+  resume_gap: {},
+  settings: { requestId: isNonEmptyString, settings: isRecord },
+  settings_error: {
+    requestId: isNonEmptyString,
+    code: oneOf(['not_available', 'invalid', 'refused', 'update_failed']),
+    message: isString,
+  },
+};
+
+function decodeVariant<TMessage extends { type: string }>(
+  value: unknown,
+  shapes: Readonly<Record<string, TVariantShape>>,
+  reasonFor: (field: string) => string,
+): TMessageDecodeResult<TMessage> {
+  if (!isRecord(value)) return { ok: false, reason: 'message must be a JSON object' };
+  const type = value['type'];
+  if (!isString(type)) return { ok: false, reason: 'message type must be a string' };
+  const shape = Object.prototype.hasOwnProperty.call(shapes, type) ? shapes[type] : undefined;
+  if (shape === undefined) return { ok: false, reason: `Unknown message type: ${type}` };
+  for (const [field, check] of Object.entries(shape)) {
+    if (!check(value[field])) return { ok: false, reason: reasonFor(field) };
+  }
+  return { ok: true, message: value as unknown as TMessage };
+}
+
+/** Total decode of a parsed client frame. */
+export function decodeClientMessage(value: unknown): TMessageDecodeResult<TClientMessage> {
+  return decodeVariant<TClientMessage>(value, CLIENT_MESSAGE_SHAPES, (field) =>
+    field === 'prompt' ? 'prompt must be a non-empty string' : `${field} has an invalid shape`,
+  );
+}
+
+/** Variant-level decode of a parsed server frame (foreign-owned payloads as records, see header). */
+export function decodeServerMessage(value: unknown): TMessageDecodeResult<TServerMessage> {
+  return decodeVariant<TServerMessage>(
+    value,
+    SERVER_MESSAGE_SHAPES,
+    (field) => `${field} has an invalid shape`,
+  );
+}
+
+/** `raw string → JSON → owner decoder`, the one path a carrier implements. */
+export function decodeFrame<TMessage>(
+  data: string,
+  decode: (value: unknown) => TMessageDecodeResult<TMessage>,
+): TMessageDecodeResult<TMessage> {
+  if (data.length > MAX_INBOUND_FRAME_BYTES) return { ok: false, reason: 'Frame too large' };
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(data);
+    // allow-fallback: the parse failure is returned as a typed refusal the carrier answers on the wire
+  } catch {
+    return { ok: false, reason: 'Invalid JSON' };
+  }
+  return decode(parsed);
+}

package/src/message-parser.ts

@@ -0,0 +1,33 @@
+import { decodeClientMessage, decodeFrame } from './message-decoders.js';
+import { malformedUsageRequest } from './usage-messages.js';
+
+import type { TOutboundDeliver } from './outbound-delivery.js';
+import type { TClientMessage } from './wire-messages.js';
+
+/** Decode a client frame and preserve validated usage-request correlation on malformed payloads. */
+export function parseClientMessage(data: string, deliver: TOutboundDeliver): TClientMessage | null {
+  const decoded = decodeFrame(data, decodeClientMessage);
+  if (decoded.ok) return decoded.message;
+  const malformedUsage = malformedUsageRequest(data);
+  if (malformedUsage?.type === 'personal') {
+    deliver({
+      type: 'personal_usage_report_error',
+      requestId: malformedUsage.requestId,
+      code: 'report_failed',
+      message: 'Invalid personal usage report request.',
+    });
+    return null;
+  }
+  if (malformedUsage?.type === 'stored-session') {
+    deliver({
+      type: 'stored_session_usage_report_error',
+      requestId: malformedUsage.requestId,
+      sessionId: malformedUsage.sessionId,
+      code: 'report_failed',
+      message: 'Invalid stored-session usage report request.',
+    });
+    return null;
+  }
+  deliver({ type: 'protocol_error', message: decoded.reason });
+  return null;
+}