feat: extract readable messages from structured OTel and JSON logs

formatLogLine now parses structured log lines and extracts human-readable
content instead of dumping raw JSON. Handles plain text, simple JSON
(level + message), and OTel format (severityText + body) including
nested content arrays and input/output message pairs.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: jesseturner21

src/cli/commands/logs/__tests__/action.test.ts

@@ -1,4 +1,4 @@
-import { detectMode, formatLogLine, resolveAgentContext } from '../action';
+import { detectMode, extractReadableMessage, formatLogLine, resolveAgentContext } from '../action';
 import type { LogsContext } from '../action';
 import { describe, expect, it } from 'vitest';
 
@@ -20,21 +20,110 @@ describe('detectMode', () => {
   });
 });
 
-describe('formatLogLine', () => {
-  const event = { timestamp: 1709391000000, message: 'Hello world' };
+describe('extractReadableMessage', () => {
+  it('returns plain text as-is', () => {
+    const result = extractReadableMessage('WARNING:  Invalid HTTP request received.');
+    expect(result.message).toBe('WARNING:  Invalid HTTP request received.');
+    expect(result.level).toBeUndefined();
+  });
+
+  it('extracts level and message from simple JSON', () => {
+    const raw = JSON.stringify({
+      timestamp: '2026-03-03T21:49:11Z',
+      level: 'INFO',
+      message: 'Invoking Agent.....',
+      logger: 'bedrock_agentcore.app',
+    });
+    const result = extractReadableMessage(raw);
+    expect(result.level).toBe('INFO');
+    expect(result.message).toBe('Invoking Agent.....');
+  });
+
+  it('extracts string body from OTel JSON', () => {
+    const raw = JSON.stringify({
+      scope: { name: 'bedrock_agentcore.app' },
+      severityText: 'INFO',
+      body: 'Returning streaming response (generator) (0.000s)',
+      traceId: 'abc123',
+    });
+    const result = extractReadableMessage(raw);
+    expect(result.level).toBe('INFO');
+    expect(result.message).toBe('Returning streaming response (generator) (0.000s)');
+  });
 
-  it('formats human-readable line with timestamp', () => {
+  it('extracts text from OTel body.content array', () => {
+    const raw = JSON.stringify({ severityText: '', body: { content: [{ text: 'hello' }] }, traceId: 'abc' });
+    const result = extractReadableMessage(raw);
+    expect(result.message).toBe('hello');
+  });
+
+  it('extracts assistant response from OTel body.message.content', () => {
+    const raw = JSON.stringify({
+      severityText: '',
+      body: {
+        message: { content: [{ text: 'Hello! How can I help you today?' }], role: 'assistant' },
+        index: 0,
+        finish_reason: 'end_turn',
+      },
+    });
+    const result = extractReadableMessage(raw);
+    expect(result.message).toBe('[assistant] Hello! How can I help you today?');
+  });
+
+  it('extracts from OTel input/output messages', () => {
+    const raw = JSON.stringify({
+      severityText: '',
+      body: {
+        output: { messages: [{ content: { message: '[{"text": "Hi there!"}]' }, role: 'assistant' }] },
+        input: { messages: [{ content: { content: '[{"text": "hello"}]' }, role: 'user' }] },
+      },
+    });
+    const result = extractReadableMessage(raw);
+    expect(result.message).toContain('[user] hello');
+    expect(result.message).toContain('[assistant] Hi there!');
+  });
+
+  it('handles invalid JSON gracefully', () => {
+    const result = extractReadableMessage('{not valid json}');
+    expect(result.message).toBe('{not valid json}');
+  });
+});
+
+describe('formatLogLine', () => {
+  it('formats plain text with timestamp', () => {
+    const event = { timestamp: 1709391000000, message: 'Hello world' };
     const line = formatLogLine(event, false);
     expect(line).toContain('Hello world');
     expect(line).toContain('2024-03-02');
   });
 
-  it('formats JSON line', () => {
+  it('formats structured log with level tag', () => {
+    const event = {
+      timestamp: 1709391000000,
+      message: JSON.stringify({ level: 'WARN', message: 'something happened' }),
+    };
+    const line = formatLogLine(event, false);
+    expect(line).toContain('WARN');
+    expect(line).toContain('something happened');
+    expect(line).not.toContain('"level"');
+  });
+
+  it('formats JSON output with extracted fields', () => {
+    const event = { timestamp: 1709391000000, message: JSON.stringify({ level: 'INFO', message: 'test message' }) };
     const line = formatLogLine(event, true);
     const parsed = JSON.parse(line);
-    expect(parsed.message).toBe('Hello world');
+    expect(parsed.level).toBe('INFO');
+    expect(parsed.message).toBe('test message');
     expect(parsed.timestamp).toBeDefined();
   });
+
+  it('formats JSON output for plain text messages', () => {
+    const event = { timestamp: 1709391000000, message: 'plain text' };
+    const line = formatLogLine(event, true);
+    const parsed = JSON.parse(line);
+    expect(parsed.message).toBe('plain text');
+    expect(parsed.level).toBeUndefined();
+  });
 });
 
 describe('resolveAgentContext', () => {

src/cli/commands/logs/action.ts

@@ -46,15 +46,149 @@ export function detectMode(options: LogsOptions): 'stream' | 'search' {
   return 'stream';
 }
 
+interface TextEntry {
+  text?: string;
+}
+
+interface OTelMessage {
+  content?: { content?: string; message?: string };
+  role?: string;
+}
+
+interface OTelBody {
+  content?: TextEntry[];
+  message?: { content?: TextEntry[]; role?: string };
+  output?: { messages?: OTelMessage[] };
+  input?: { messages?: OTelMessage[] };
+}
+
+interface SimpleLogEntry {
+  level?: string;
+  message?: string;
+}
+
+interface OTelLogEntry {
+  severityText?: string;
+  body?: string | OTelBody;
+}
+
+function extractTexts(entries: TextEntry[]): string[] {
+  return entries.filter(c => typeof c.text === 'string').map(c => c.text!);
+}
+
+function extractFromIOMessages(messages: OTelMessage[], field: 'content' | 'message'): string[] {
+  const parts: string[] = [];
+  for (const msg of messages) {
+    const raw = field === 'content' ? msg.content?.content : msg.content?.message;
+    if (typeof raw !== 'string') continue;
+    const role = typeof msg.role === 'string' ? msg.role : 'unknown';
+    try {
+      const arr: unknown = JSON.parse(raw);
+      if (Array.isArray(arr)) {
+        const texts = extractTexts(arr as TextEntry[]);
+        if (texts.length) {
+          parts.push(`[${role}] ${texts.join(' ')}`);
+          continue;
+        }
+      }
+      parts.push(`[${role}] ${raw}`);
+    } catch {
+      parts.push(`[${role}] ${raw}`);
+    }
+  }
+  return parts;
+}
+
+/**
+ * Extract a human-readable message from a structured log line.
+ * Handles plain text, simple JSON ({"level","message"}), and OTel JSON ({"severityText","body"}).
+ */
+export function extractReadableMessage(raw: string): { level?: string; message: string } {
+  const trimmed = raw.trim();
+  if (!trimmed.startsWith('{')) {
+    return { message: trimmed };
+  }
+
+  try {
+    const parsed: unknown = JSON.parse(trimmed);
+    if (typeof parsed !== 'object' || parsed === null) {
+      return { message: trimmed };
+    }
+
+    const simple = parsed as SimpleLogEntry;
+
+    // Simple JSON format: {"level": "INFO", "message": "..."}
+    if (typeof simple.message === 'string' && typeof simple.level === 'string') {
+      return { level: simple.level, message: simple.message };
+    }
+
+    // OTel format: {"severityText": "INFO", "body": "..." | {...}}
+    const otel = parsed as OTelLogEntry;
+    if (otel.body !== undefined) {
+      const level = typeof otel.severityText === 'string' && otel.severityText ? otel.severityText : undefined;
+      const body = otel.body;
+
+      // String body
+      if (typeof body === 'string') {
+        return { level, message: body };
+      }
+
+      // Object body with content array: {"content": [{"text": "..."}]}
+      if (Array.isArray(body.content)) {
+        const texts = extractTexts(body.content);
+        if (texts.length > 0) {
+          return { level, message: texts.join(' ') };
+        }
+      }
+
+      // Object body with message.content: {"message": {"content": [{"text": "..."}]}}
+      if (body.message?.content && Array.isArray(body.message.content)) {
+        const texts = extractTexts(body.message.content);
+        if (texts.length > 0) {
+          const role = body.message.role ? `[${body.message.role}]` : '';
+          return { level, message: `${role} ${texts.join(' ')}`.trim() };
+        }
+      }
+
+      // Object body with stringified content in input/output messages
+      if (body.output?.messages ?? body.input?.messages) {
+        const parts: string[] = [
+          ...extractFromIOMessages(body.input?.messages ?? [], 'content'),
+          ...extractFromIOMessages(body.output?.messages ?? [], 'message'),
+        ];
+        if (parts.length > 0) {
+          return { level, message: parts.join(' | ') };
+        }
+      }
+
+      // Fallback: stringify the body
+      return { level, message: JSON.stringify(body) };
+    }
+
+    // Unrecognized JSON — return as-is
+    return { message: trimmed };
+  } catch {
+    return { message: trimmed };
+  }
+}
+
 /**
  * Format a log event for display
  */
 export function formatLogLine(event: { timestamp: number; message: string }, json: boolean): string {
   if (json) {
-    return JSON.stringify({ timestamp: new Date(event.timestamp).toISOString(), message: event.message });
+    const { level, message } = extractReadableMessage(event.message);
+    return JSON.stringify({
+      timestamp: new Date(event.timestamp).toISOString(),
+      ...(level ? { level } : {}),
+      message,
+    });
   }
+
   const ts = new Date(event.timestamp).toISOString();
-  return `${ts}  ${event.message}`;
+  const { level, message } = extractReadableMessage(event.message);
+  const levelTag = level ? `  ${level.padEnd(5)}` : '       ';
+  return `${ts}${levelTag}  ${message}`;
 }
 
 /**