feat: add logs command for streaming and searching agent runtime logs

[jesseturner21]

Description

Add a new agentcore logs command that provides real-time streaming and historical search of agent runtime logs via CloudWatch Logs.

Stream mode (default): Uses StartLiveTail for real-time log streaming with auto-reconnect on 3-hour session timeout. Simply run agentcore logs to start streaming.

Search mode (--since/--until): Uses FilterLogEvents with pagination for bounded time-range queries. Supports relative durations (5m, 1h, 2d), ISO 8601 timestamps, and epoch ms.

Filtering: Server-side filtering via --level (error/warn/info/debug) and --query (free-text). These use CloudWatch filter patterns for efficient server-side filtering.

Output: Human-readable by default (ISO timestamp + message), or JSON Lines with --json for piping to other tools.

New files

• src/cli/commands/logs/ — Command registration, action handler, types, time parser, filter pattern builder, barrel export
• src/cli/aws/cloudwatch.ts — CloudWatch Logs client with streamLogs() and searchLogs() async generators
• src/cli/commands/logs/__tests__/ — 32 unit tests covering time parsing, filter patterns, mode detection, formatting, and agent resolution

Modified files

• src/cli/cli.ts — Register logs command
• src/cli/tui/copy.ts — Add command description
• src/cli/aws/index.ts — Export cloudwatch module
• package.json — Add @aws-sdk/client-cloudwatch-logs dependency
• .gitignore — Scope logs pattern to top-level only (was blocking src/cli/commands/logs/)

Related Issue

N/A — New feature
Closes #373

screenshots of experience

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update
• Other (please describe):

Testing

How have you tested the change?

• I ran npm run test:unit and npm run test:integ
• I ran npm run typecheck
• I ran npm run lint
• If I modified src/assets/, I ran npm run test:update-snapshots and committed the updated snapshots

Manual E2E testing performed with valid AWS credentials:

• Error handling: Verified all error paths — no project, no agents, agent not deployed, multiple agents without --agent, unknown agent name, invalid --level, invalid --since
• Search mode: Verified against real CloudWatch log groups with --since, --until, --level, --query, --json, -n (line limit), ISO 8601 timestamps
• Stream mode: Verified StartLiveTail connects and streams (tested with real log group, confirmed "Streaming logs..." message and clean Ctrl+C handling)
• ResourceNotFoundException: Verified friendly "No logs found. Has the agent been invoked?" message for non-existent log groups
• 32 unit tests pass covering time-parser, filter-pattern, and action logic
• 1788 existing unit tests pass with zero regressions

Checklist

• I have read the CONTRIBUTING document
• I have added any necessary tests that prove my fix is effective or my feature works
• I have updated the documentation accordingly
• I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
• My changes generate no new warnings
• Any dependent changes have been merged and published

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the
terms of your choice.

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	46.33%	3487 / 7526
🔵	Statements	45.95%	3673 / 7993
🔵	Functions	48.15%	691 / 1435
🔵	Branches	50.26%	2301 / 4578

Generated in workflow #830 for commit ef1e369 by the Vitest Coverage Report Action

[jesseturner21]

Discussion: I think we should go into the template agent experience and see the logs and otel logs we are providing. Currently the logs command just returns the logs from the runtime log group. This gives the developer the ability to configure logs in there agent how they want and the agentcore cli aligns with there configuration. Right now the otel logs are verbose and it would help to do a deep dive on how the default agent is outputting logs.