Skip to content

feat(runtime,harness): grouped help for the large-option commands - #2296

Open
jariy17 wants to merge 1 commit into
refactorfrom
feat/runtime-harness-grouped-help
Open

feat(runtime,harness): grouped help for the large-option commands#2296
jariy17 wants to merge 1 commit into
refactorfrom
feat/runtime-harness-grouped-help

Conversation

@jariy17

@jariy17 jariy17 commented Sep 14, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Applied help Groups to all commands of agentcore runtime and agentcore harness. We didn't add helpGroups to either get/list commands because they are simple.

Before / after --help

agentcore harness create --help

Before

Usage: agentcore harness create [options]

create a harness

Options:
  --name <name>                                          the name of the harness
  --execution-role-arn <execution-role-arn>              IAM role the harness assumes; a default role is created when omitted
  --system-prompt <system-prompt>                        the agent's system prompt
  --model <model>                                        model configuration (JSON HarnessModelConfiguration)
  --tools <tools>                                        tools available to the agent (JSON HarnessTool[])
  --skills <skills>                                      skills available to the agent (JSON HarnessSkill[])
  --allowed-tools <allowed-tools...>                     tool allowlist patterns (e.g. * or @serverName/toolName)
  --memory <memory>                                      memory configuration (JSON HarnessMemoryConfiguration)
  --truncation <truncation>                              context truncation configuration (JSON HarnessTruncationConfiguration)
  --environment <environment>                            compute environment configuration (JSON HarnessEnvironmentProviderRequest)
  --environment-artifact <environment-artifact>          environment artifact, e.g. a container image (JSON HarnessEnvironmentArtifact)
  --environment-variables <environment-variables>        environment variables (JSON object of key/value strings)
  --authorizer-configuration <authorizer-configuration>  inbound authorizer configuration (JSON AuthorizerConfiguration)
  --max-iterations <max-iterations>                      max agent loop iterations per invocation
  --max-tokens <max-tokens>                              max total output tokens per invocation
  --timeout-seconds <timeout-seconds>                    max duration in seconds per invocation
  --tags <tags>                                          tags to apply (JSON object of key/value strings)
  -h, --help                                             display help for command

Global Options:
  --region <region>                                      AWS region
  --debug                                                debug logging (default: false)
  --json                                                 JSON output (default: false)
  --endpoint-url <endpoint-url>                          endpoint URL override


  [Parameter details section unchanged — omitted for brevity]

After

Usage: agentcore harness create [options]

create a harness

Configuration:
  --name <name>                                          the name of the harness
  --execution-role-arn <execution-role-arn>              IAM role the harness assumes; a default role is created when omitted
  --tags <tags>                                          tags to apply (JSON object of key/value strings)

Agent:
  --system-prompt <system-prompt>                        the agent's system prompt
  --model <model>                                        model configuration (JSON HarnessModelConfiguration)
  --tools <tools>                                        tools available to the agent (JSON HarnessTool[])
  --skills <skills>                                      skills available to the agent (JSON HarnessSkill[])
  --allowed-tools <allowed-tools...>                     tool allowlist patterns (e.g. * or @serverName/toolName)
  --memory <memory>                                      memory configuration (JSON HarnessMemoryConfiguration)
  --truncation <truncation>                              context truncation configuration (JSON HarnessTruncationConfiguration)

Compute environment:
  --environment <environment>                            compute environment configuration (JSON HarnessEnvironmentProviderRequest)
  --environment-artifact <environment-artifact>          environment artifact, e.g. a container image (JSON HarnessEnvironmentArtifact)
  --environment-variables <environment-variables>        environment variables (JSON object of key/value strings)

Access:
  --authorizer-configuration <authorizer-configuration>  inbound authorizer configuration (JSON AuthorizerConfiguration)

Limits:
  --max-iterations <max-iterations>                      max agent loop iterations per invocation
  --max-tokens <max-tokens>                              max total output tokens per invocation
  --timeout-seconds <timeout-seconds>                    max duration in seconds per invocation

Other options:
  -h, --help                                             display help for command

Global Options:
  --region <region>                                      AWS region
  --debug                                                debug logging (default: false)
  --json                                                 JSON output (default: false)
  --endpoint-url <endpoint-url>                          endpoint URL override


  [Parameter details section unchanged — omitted for brevity]
agentcore harness update --help

Before

Usage: agentcore harness update [options]

update a harness (creates a new version)

Options:
  --id <id>                                                          the ID of the harness to update
  --execution-role-arn <execution-role-arn>                          IAM role the harness assumes
  --system-prompt <system-prompt>                                    the agent's system prompt
  --model <model>                                                    model configuration (JSON HarnessModelConfiguration)
  --tools <tools>                                                    tools available to the agent (JSON HarnessTool[])
  --skills <skills>                                                  skills available to the agent (JSON HarnessSkill[])
  --allowed-tools <allowed-tools...>                                 tool allowlist patterns (e.g. * or @serverName/toolName)
  --memory <memory>                                                  memory configuration (JSON HarnessMemoryConfiguration)
  --clear-memory <clear-memory>                                      clear the memory configuration (pass true)
  --truncation <truncation>                                          context truncation configuration (JSON HarnessTruncationConfiguration)
  --environment <environment>                                        compute environment configuration (JSON HarnessEnvironmentProviderRequest)
  --environment-artifact <environment-artifact>                      environment artifact, e.g. a container image (JSON HarnessEnvironmentArtifact)
  --clear-environment-artifact <clear-environment-artifact>          clear the environment artifact (pass true)
  --environment-variables <environment-variables>                    environment variables (JSON object; replaces all existing)
  --authorizer-configuration <authorizer-configuration>              inbound authorizer configuration (JSON AuthorizerConfiguration)
  --clear-authorizer-configuration <clear-authorizer-configuration>  clear the authorizer configuration (pass true)
  --max-iterations <max-iterations>                                  max agent loop iterations per invocation
  --max-tokens <max-tokens>                                          max total output tokens per invocation
  --timeout-seconds <timeout-seconds>                                max duration in seconds per invocation
  -h, --help                                                         display help for command

Global Options:
  --region <region>                                                  AWS region
  --debug                                                            debug logging (default: false)
  --json                                                             JSON output (default: false)
  --endpoint-url <endpoint-url>                                      endpoint URL override


  [Parameter details section unchanged — omitted for brevity]

After

Usage: agentcore harness update [options]

update a harness (creates a new version)

Target:
  --id <id>                                                          the ID of the harness to update

Configuration:
  --execution-role-arn <execution-role-arn>                          IAM role the harness assumes

Agent:
  --system-prompt <system-prompt>                                    the agent's system prompt
  --model <model>                                                    model configuration (JSON HarnessModelConfiguration)
  --tools <tools>                                                    tools available to the agent (JSON HarnessTool[])
  --skills <skills>                                                  skills available to the agent (JSON HarnessSkill[])
  --allowed-tools <allowed-tools...>                                 tool allowlist patterns (e.g. * or @serverName/toolName)
  --memory <memory>                                                  memory configuration (JSON HarnessMemoryConfiguration)
  --clear-memory <clear-memory>                                      clear the memory configuration (pass true)
  --truncation <truncation>                                          context truncation configuration (JSON HarnessTruncationConfiguration)

Compute environment:
  --environment <environment>                                        compute environment configuration (JSON HarnessEnvironmentProviderRequest)
  --environment-artifact <environment-artifact>                      environment artifact, e.g. a container image (JSON HarnessEnvironmentArtifact)
  --clear-environment-artifact <clear-environment-artifact>          clear the environment artifact (pass true)
  --environment-variables <environment-variables>                    environment variables (JSON object; replaces all existing)

Access:
  --authorizer-configuration <authorizer-configuration>              inbound authorizer configuration (JSON AuthorizerConfiguration)
  --clear-authorizer-configuration <clear-authorizer-configuration>  clear the authorizer configuration (pass true)

Limits:
  --max-iterations <max-iterations>                                  max agent loop iterations per invocation
  --max-tokens <max-tokens>                                          max total output tokens per invocation
  --timeout-seconds <timeout-seconds>                                max duration in seconds per invocation

Other options:
  -h, --help                                                         display help for command

Global Options:
  --region <region>                                                  AWS region
  --debug                                                            debug logging (default: false)
  --json                                                             JSON output (default: false)
  --endpoint-url <endpoint-url>                                      endpoint URL override


  [Parameter details section unchanged — omitted for brevity]
agentcore runtime invoke --help

Before

Usage: agentcore runtime invoke [options]

invoke a Runtime

Options:
  --id <id>                                      the ID of the Runtime
  --payload <payload>                            the inline payload to send
  --qualifier <qualifier>                        the Runtime endpoint qualifier
  --content-type <content-type>                  the payload content type
  --accept <accept>                              the accepted response content type
  --session-id <session-id>                      the Runtime session ID
  --user-id <user-id>                            the Runtime user ID (default "default")
  --header <header...>                           an ordered application header
  --bearer-token <bearer-token>                  the CUSTOM_JWT bearer token
  --mcp-session-id <mcp-session-id>              the MCP session ID
  --mcp-protocol-version <mcp-protocol-version>  the MCP protocol version
  --mcp-method <mcp-method>                      the MCP method
  --mcp-name <mcp-name>                          the MCP tool, resource, or prompt name
  --trace-id <trace-id>                          the X-Ray trace ID
  --trace-parent <trace-parent>                  the W3C trace parent
  --trace-state <trace-state>                    the W3C trace state
  --baggage <baggage>                            the W3C baggage
  --output-file <output-file>                    the response output file
  -h, --help                                     display help for command

Global Options:
  --region <region>                              AWS region
  --debug                                        debug logging (default: false)
  --json                                         JSON output (default: false)
  --endpoint-url <endpoint-url>                  endpoint URL override

After

Usage: agentcore runtime invoke [options]

invoke a Runtime

Target:
  --id <id>                                      the ID of the Runtime
  --qualifier <qualifier>                        the Runtime endpoint qualifier

Payload:
  --payload <payload>                            the inline payload to send
  --content-type <content-type>                  the payload content type
  --accept <accept>                              the accepted response content type
  --output-file <output-file>                    the response output file

Session:
  --session-id <session-id>                      the Runtime session ID
  --user-id <user-id>                            the Runtime user ID (default "default")

Authentication:
  --bearer-token <bearer-token>                  the CUSTOM_JWT bearer token

Application headers:
  --header <header...>                           an ordered application header

MCP:
  --mcp-session-id <mcp-session-id>              the MCP session ID
  --mcp-protocol-version <mcp-protocol-version>  the MCP protocol version
  --mcp-method <mcp-method>                      the MCP method
  --mcp-name <mcp-name>                          the MCP tool, resource, or prompt name

Tracing:
  --trace-id <trace-id>                          the X-Ray trace ID
  --trace-parent <trace-parent>                  the W3C trace parent
  --trace-state <trace-state>                    the W3C trace state
  --baggage <baggage>                            the W3C baggage

Other options:
  -h, --help                                     display help for command

Global Options:
  --region <region>                              AWS region
  --debug                                        debug logging (default: false)
  --json                                         JSON output (default: false)
  --endpoint-url <endpoint-url>                  endpoint URL override

Parameter details:

  --trace-id (string)
      The AWS X-Ray trace ID to associate this invocation with, sent as the
      X-Amzn-Trace-Id header. Format: 1-<8 hex digits>-<24 hex digits>.

      Example:
        --trace-id 1-5759e988-bd862e3fe1be46a994272793

  --trace-parent (string)
      The W3C Trace Context traceparent header identifying the parent span.
      Format: <version>-<trace-id>-<parent-id>-<trace-flags>.

      Example:
        --trace-parent 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01

  --trace-state (string)
      The W3C Trace Context tracestate header carrying vendor-specific trace
      data. Format: a comma-separated list of key=value pairs.

      Example:
        --trace-state vendor1=opaqueValue1,vendor2=opaqueValue2

  --baggage (string)
      The W3C Baggage header carrying application-defined key=value context
      propagated across the request. Format: a comma-separated list of key=value
      pairs.

      Example:
        --baggage userId=alice,sessionId=abc123
agentcore runtime logs --help

Before

Usage: agentcore runtime logs [options]

stream or search a Runtime's logs

Options:
  --id <id>                      the ID of the Runtime
  --qualifier <qualifier>        the Runtime endpoint qualifier
  --since <since>                search window start: "5m", "1h", ISO 8601,
                                 epoch ms, or "now"
  --until <until>                search window end: "5m", "1h", ISO 8601, epoch
                                 ms, or "now"
  --tail                         tail new log records (default: false)
  --level <level>                filter by log level (error, warn, info, debug)
  --query <query>                CloudWatch Logs filter pattern
  --limit <limit>                maximum number of log records to return in
                                 search mode
  -h, --help                     display help for command

Global Options:
  --region <region>              AWS region
  --debug                        debug logging (default: false)
  --json                         JSON output (default: false)
  --endpoint-url <endpoint-url>  endpoint URL override

After

Usage: agentcore runtime logs [options]

stream or search a Runtime's logs

Log source:
  --id <id>                      the ID of the Runtime
  --qualifier <qualifier>        the Runtime endpoint qualifier

Time window:
  --since <since>                search window start: "5m", "1h", ISO 8601,
                                 epoch ms, or "now"
  --until <until>                search window end: "5m", "1h", ISO 8601, epoch
                                 ms, or "now"
  --tail                         tail new log records (default: false)

Filtering:
  --level <level>                filter by log level (error, warn, info, debug)
  --query <query>                CloudWatch Logs filter pattern
  --limit <limit>                maximum number of log records to return in
                                 search mode

Other options:
  -h, --help                     display help for command

Global Options:
  --region <region>              AWS region
  --debug                        debug logging (default: false)
  --json                         JSON output (default: false)
  --endpoint-url <endpoint-url>  endpoint URL override
agentcore harness logs --help

Before

Usage: agentcore harness logs [options]

stream or search a harness's logs

Options:
  --id <id>                      the ID of the harness
  --qualifier <qualifier>        the harness endpoint qualifier
  --since <since>                search window start: "5m", "1h", ISO 8601,
                                 epoch ms, or "now"
  --until <until>                search window end: "5m", "1h", ISO 8601, epoch
                                 ms, or "now"
  --tail                         tail new log records (default: false)
  --level <level>                filter by log level (error, warn, info, debug)
  --query <query>                CloudWatch Logs filter pattern
  --limit <limit>                maximum number of log records to return in
                                 search mode
  -h, --help                     display help for command

Global Options:
  --region <region>              AWS region
  --debug                        debug logging (default: false)
  --json                         JSON output (default: false)
  --endpoint-url <endpoint-url>  endpoint URL override

After

Usage: agentcore harness logs [options]

stream or search a harness's logs

Log source:
  --id <id>                      the ID of the harness
  --qualifier <qualifier>        the harness endpoint qualifier

Time window:
  --since <since>                search window start: "5m", "1h", ISO 8601,
                                 epoch ms, or "now"
  --until <until>                search window end: "5m", "1h", ISO 8601, epoch
                                 ms, or "now"
  --tail                         tail new log records (default: false)

Filtering:
  --level <level>                filter by log level (error, warn, info, debug)
  --query <query>                CloudWatch Logs filter pattern
  --limit <limit>                maximum number of log records to return in
                                 search mode

Other options:
  -h, --help                     display help for command

Global Options:
  --region <region>              AWS region
  --debug                        debug logging (default: false)
  --json                         JSON output (default: false)
  --endpoint-url <endpoint-url>  endpoint URL override

jariy17
feat(runtime,harness): grouped help for the large-option commands
e8964e0 
Applies the router's help-group mechanism (PR #2262) to the runtime and
harness commands whose flat option lists had grown past skimming. Presentation
only — no flag is added, removed, or renamed, and no request changes.

Grouped commands:
- harness create: Configuration, Agent, Compute environment, Access, Limits
- harness update: Target, Configuration, Agent, Compute environment, Access, Limits
- runtime invoke: Target, Payload, Session, Authentication, Application headers,
  MCP, Tracing (flags reordered so each heading's flags declare contiguously)
- runtime logs / harness logs: Log source, Time window, Filtering (the shared
  observability/logs flags carry the last two headings; only these two commands
  consume that handler)

Headings reuse the eval vocabulary where the concept matches: Configuration
holds name/execution-role-arn/tags, and update's Target is the same heading eval
already uses. A command that groups its flags gets its generated -h/--help moved
to "Other options:".

Also trims the Parameter details section: the long-form blocks for --name,
--system-prompt, and --execution-role-arn are removed (self-explanatory), and
--trace-parent/--trace-state/--baggage/--trace-id gain the W3C/X-Ray format and
an example they previously lacked.
@github-actions github-actions Bot added the size/m PR size: M label Sep 14, 2026
@agentcore-devx-automation agentcore-devx-automation Bot added agentcore-harness-reviewing AgentCore Harness review in progress claude-security-reviewing Claude Code /security-review in progress labels Sep 14, 2026
@agentcore-devx-automation

agentcore-devx-automation Bot commented Sep 14, 2026

Copy link
Copy Markdown
Contributor

Claude Security Review: no high-confidence findings. (run)

@agentcore-devx-automation agentcore-devx-automation Bot removed the claude-security-reviewing Claude Code /security-review in progress label Sep 14, 2026
@github-actions github-actions Bot added size/m PR size: M and removed size/m PR size: M labels Sep 14, 2026
@jariy17
jariy17 marked this pull request as ready for review September 14, 2026 20:55
agentcore-devx-automation[bot]
agentcore-devx-automation Bot reviewed Sep 14, 2026
View reviewed changes

@agentcore-devx-automation agentcore-devx-automation Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

AgentCore Harness Review

Verdict: Looks good

Cosmetic PR that adds helpGroup labels to flags for the large-option commands (harness create/update/logs, runtime invoke/logs, and shared observability logs). The flag() helper already supports group, and Commander renders it via Option.helpGroup, so this is straightforward metadata.

One thing worth confirming, not blocking:

  • Dropped parameterHelp entries in src/handlers/harness/parameterHelp.tsx — the name, executionRoleArn, and systemPrompt long-form help strings were removed and not replaced. harness create --help no longer surfaces the --name pattern ([a-zA-Z][a-zA-Z0-9_]{0,39}) or the "when omitted, a default AgentCoreHarness-<name> role is provisioned" behavior for --execution-role-arn. If that was intentional (deemed self-explanatory), no action needed; otherwise please restore them or move the key details into the short description string.

No new tests are needed for this change (no help-output snapshots exist), and no telemetry is warranted since this is a --help presentation change. parameterHelp.name/executionRoleArn/systemPrompt are not referenced anywhere else, so removing them doesn't break other call sites.

Minor style-level inconsistencies (some group labels use const while a few are inlined literals; execution-role-arn sits alone in a "Configuration:" group in update) are not blockers.

@agentcore-devx-automation agentcore-devx-automation Bot removed the agentcore-harness-reviewing AgentCore Harness review in progress label Sep 14, 2026
@github-actions github-actions Bot added size/m PR size: M and removed size/m PR size: M labels Sep 14, 2026
@codecov-commenter

codecov-commenter commented Sep 14, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.09%. Comparing base (f8e1495) to head (e8964e0).

Additional details and impacted files 
@@            Coverage Diff            @@
##           refactor    #2296   +/-   ##
=========================================
  Coverage     97.09%   97.09%           
=========================================
  Files           578      578           
  Lines         39639    39715   +76     
=========================================
+ Hits          38486    38562   +76     
  Misses         1153     1153

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@agentcore-devx-automation agentcore-devx-automation[bot] agentcore-devx-automation[bot] left review comments

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

size/m PR size: M

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@jariy17 @codecov-commenter