Skip to content

feat(agents): add human-readable streaming display for agent steps (F082)#312

Merged
pocky merged 1 commit intomainfrom
feature/F082-display-matrix-for-cli-agent-providers--
Apr 13, 2026
Merged

feat(agents): add human-readable streaming display for agent steps (F082)#312
pocky merged 1 commit intomainfrom
feature/F082-display-matrix-for-cli-agent-providers--

Conversation

@pocky
Copy link
Copy Markdown
Contributor

@pocky pocky commented Apr 13, 2026

Summary

  • Add human-readable streaming display for agent steps (F082): when running with --output streaming or --output buffered, agent NDJSON responses are filtered to plain text instead of showing raw wire format
  • The output_format field now serves dual purpose — post-processing (code fence stripping) AND terminal display routing: text/omitted filters to readable output, json passes raw NDJSON through
  • DisplayOutput field propagates from AgentResult through ConversationResultStepState → CLI summary; state.Output retains raw NDJSON for template interpolation unchanged
  • cloneAndInjectOutputFormat now normalizes OutputFormatNonetext so the display-matrix pipeline always receives an explicit format value, and is applied consistently to both executeAgentStep and ExecuteConversation paths

Changes

Infrastructure — Agent Providers

  • internal/infrastructure/agents/base_cli_provider.go: Wire parseStreamLine hook into streaming I/O path; apply streamFilterWriter when output_format is not json; populate DisplayOutput in returned AgentResult
  • internal/infrastructure/agents/stream_filter.go: Simplify streamFilterWriter — remove redundant buffering logic, tighten LineExtractor contract
  • internal/infrastructure/agents/opencode_provider.go: Add stub parseStreamLine hook to satisfy updated cliProviderHooks struct

Application Layer

  • internal/application/execution_service.go: Normalize OutputFormatNoneOutputFormatText in cloneAndInjectOutputFormat so downstream always sees an explicit value
  • internal/application/conversation_manager.go: Replace inline options map construction with cloneAndInjectOutputFormat to apply identical display routing to conversation turns (F082 cross-path consistency)

Tests

  • internal/application/execution_service_display_output_test.go: Add table-driven tests for output_format injection (text/json/none→text), nil-options handling, and option map immutability (FR-009)
  • internal/infrastructure/agents/claude_provider_display_output_unit_test.go: Refocus tests on parseClaudeStreamLine extraction; remove obsolete streaming-path tests superseded by base provider
  • internal/infrastructure/agents/opencode_provider_display_output_unit_test.go: Update to reflect stub extractor behavior after OpenCode gains parseStreamLine hook
  • internal/infrastructure/agents/stream_filter_unit_test.go: Align with simplified streamFilterWriter contract; add benchmark for throughput and 1 MB buffer constraint
  • internal/domain/workflow/context_json_test.go: Assert DisplayOutput is NOT resolvable in template interpolation context (prevents accidental exposure)
  • internal/interfaces/cli/run.go: Remove unused import/variable introduced during earlier wiring
  • pkg/interpolation/resolver_data_test.go: Add DisplayOutput to excluded-fields coverage
  • tests/integration/agents/f082_display_matrix_test.go: New integration test matrix covering all provider × output-mode × output-format combinations

Documentation

  • docs/user-guide/agent-steps.md: Add Streaming Output Display section with mode/format matrix table and examples for streaming, buffered, and silent modes
  • docs/user-guide/commands.md: Update --output flag table to document agent-step display filtering behavior
  • docs/README.md: Add link to new Streaming Output Display subsection
  • README.md: Update feature bullet to mention human-readable streaming display
  • CHANGELOG.md: Add F082 entry under Added

Project Config

  • CLAUDE.md: Add architecture rules for cross-path hook wiring and test conventions for DisplayOutput field isolation and benchmark requirements; remove stale rules

Test plan

  • make test — all unit and integration tests pass including new f082_display_matrix_test.go
  • awf run <workflow-with-agent-step> --output streaming — terminal shows readable text, not raw {"type":"content_block_delta",...} NDJSON
  • awf run <workflow-with-agent-step> --output streaming with output_format: json — raw NDJSON appears unchanged on terminal
  • Template interpolation {{states.step.display_output}} returns empty/unresolved — DisplayOutput is not exposed to workflows

Closes #311


Generated with awf commit workflow

@pocky pocky force-pushed the feature/F082-display-matrix-for-cli-agent-providers-- branch 3 times, most recently from a722241 to fe976b5 Compare April 13, 2026 20:49
- `internal/infrastructure/agents/stream_filter.go`: Add `streamFilterWriter` io.Writer decorator and `LineExtractor` func type for NDJSON-to-text filtering
- `internal/infrastructure/agents/base_cli_provider.go`: Wire `parseStreamLine` hook and `DisplayOutput` extraction into shared execution flow
- `internal/infrastructure/agents/claude_provider.go`: Implement `parseClaudeStreamLine` extracting `content_block_delta` text events
- `internal/infrastructure/agents/gemini_provider.go`: Add stub `parseStreamLine` hook for future NDJSON extraction
- `internal/infrastructure/agents/codex_provider.go`: Add stub `parseStreamLine` hook for future NDJSON extraction
- `internal/infrastructure/agents/opencode_provider.go`: Add stub `parseStreamLine` hook for future NDJSON extraction
- `internal/domain/workflow/agent_config.go`: Add `DisplayOutput` field (json:"-") to `AgentResult`
- `internal/domain/workflow/context.go`: Add `DisplayOutput` field (json:"-") to `StepState`
- `internal/domain/workflow/conversation.go`: Add `DisplayOutput` field (json:"-") to `ConversationResult`
- `internal/application/execution_service.go`: Use `DisplayOutput` in `showStepOutputs`; clone options before injecting `output_format`
- `internal/application/conversation_manager.go`: Propagate `DisplayOutput` from conversation result
- `internal/interfaces/cli/run.go`: Pass output format context to execution service
- `internal/infrastructure/agents/base_cli_provider_display_output_unit_test.go`: Add 629-line unit test suite for stream filter and base provider display output
- `internal/infrastructure/agents/claude_provider_display_output_unit_test.go`: Add unit tests for Claude NDJSON parser
- `internal/infrastructure/agents/gemini_provider_display_output_unit_test.go`: Add unit tests for Gemini display output stub
- `internal/infrastructure/agents/codex_provider_display_output_unit_test.go`: Add unit tests for Codex display output stub
- `internal/infrastructure/agents/opencode_provider_display_output_unit_test.go`: Add unit tests for OpenCode display output stub
- `internal/infrastructure/agents/stream_filter_unit_test.go`: Add unit tests for `streamFilterWriter`
- `internal/application/execution_service_display_output_test.go`: Add 424-line tests for display output cross-layer wiring
- `internal/domain/workflow/context_json_test.go`: Verify `DisplayOutput` is excluded from JSON serialization
- `pkg/interpolation/resolver_data_test.go`: Verify `DisplayOutput` not resolvable in template context
- `tests/integration/agents/f082_display_matrix_test.go`: Add integration test matrix across all providers
- `docs/user-guide/agent-steps.md`: Document `output_format` field and streaming display behavior
- `docs/user-guide/commands.md`: Update run command docs with output mode behavior
- `CHANGELOG.md`: Add F082 entry
- `README.md`: Update feature list
- `docs/README.md`: Update docs index

Closes #311
@pocky pocky force-pushed the feature/F082-display-matrix-for-cli-agent-providers-- branch from fe976b5 to 242bea9 Compare April 13, 2026 20:54
@pocky pocky marked this pull request as ready for review April 13, 2026 20:56
@pocky pocky merged commit 3701f68 into main Apr 13, 2026
5 checks passed
@pocky pocky deleted the feature/F082-display-matrix-for-cli-agent-providers-- branch April 13, 2026 20:57
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

F082: Display Matrix for CLI Agent Providers (--output × output_format)

1 participant