feat: add Runtime read-only TUI by aidandaly24 · Pull Request #1802 · aws/agentcore-cli

aidandaly24 · 2026-07-22T03:13:14Z

Description

Adds an interactive, read-only TUI for the Runtime control-plane commands introduced in #1797.

The Runtime TUI provides route-based flows for:

Listing and inspecting Runtimes
Listing and inspecting immutable Runtime versions
Listing and inspecting Runtime endpoints

Runtime follows the established Harness interaction model. Bare Runtime groups and leaves open their corresponding TUI routes, operation flags keep commands headless, and --json suppresses interactive rendering. Nested endpoint and version flows preserve route history so Escape returns through the selectors and command menus in order.

This change also introduces a shared token-paged table picker used by Runtime and Harness. It centralizes loading, empty, error, retry, filtering, responsive columns, transition locking, pagination, resize resets, and Escape behavior while keeping each resource's API calls, columns, row mapping, sorting, labels, and destinations in its adapter.

Runtime detail and headless output omit SDK $metadata. The shared table filter accepts pasted text delivered as a single terminal input event.

Runtime invocation, mutations, deployment or project resolution, logs, traces, and other resource families remain outside this change.

Related Issue

N/A

Documentation PR

N/A. README command and interaction documentation is included in this PR.

Type of Change

Testing

Verified from current HEAD 023f2af:

bun test (319 passed, 0 failed)
bun run typecheck
bun run lint:check
bun run format:check
Manual terminal and TUI-harness verification of Runtime, version, and endpoint navigation

Checklist

I have read the CONTRIBUTING document
I have added necessary tests that prove the feature works
I have updated the documentation accordingly
I have added appropriate examples to the documentation
My changes generate no new warnings
No dependent changes are required

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

aidandaly24 · 2026-07-22T05:01:33Z

@@ -0,0 +1,103 @@
+import { useNavigate } from "react-router";


I wouldn't be against sorting these into folders since I could picture this getting unwieldy as time goes on. The reason I held off was because I didn't know if maybe we just sort the primitive ones or if maybe we just want to sort into a folder called "pickers".

I actually prefer a flat directory of components! I tend to think a flat directory is easier to maintain over time and that it makes it easier to find what you're looking for.

aidandaly24 · 2026-07-22T05:26:42Z

+  emptyPageMessage: string;
+}
+
+export function TokenPagedTablePicker<TItem, TRow extends Record<string, unknown>>({


TokenPagedTablePicker centralizes the interaction state shared by Runtime and Harness resource pickers like terminal-derived page sizing, continuation-token history, loading/retry/empty states, page transitions, resize resets, filtering, selection, and keyboard navigation.

Resource-specific adapters still own their API calls, query keys, row mapping, columns, sorting, labels, selectors, and navigation destinations. This removes duplicated pagination state machines without forcing different resources into one data model, and gives the shared behavior one focused test suite.

aidandaly24 · 2026-07-22T05:29:50Z

@@ -0,0 +1,7 @@
+export function withoutSdkMetadata(data: unknown): unknown {


This PR strips SDK $metadata at the Runtime handler boundary so both headless and TUI output remain resource-focused. I think we should decide whether transport metadata removal belongs in Core, JsonRenderer, or another shared normalization layer, then apply this contract consistently across resource families. What do you think, it could be done in this PR or a followup?

I agree that we shouldn't show $metadata. Let's handle globally in a follow up.

Makes sense. I’ll remove the Runtime-specific handling from this PR and address $metadata globally in a follow-up. I'll add a backlog item for it.

codecov-commenter · 2026-07-22T07:39:21Z

Codecov Report

❌ Patch coverage is 99.73154% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 94.84%. Comparing base (3bf082c) to head (4ffe40a).

Files with missing lines	Patch %	Lines
src/handlers/runtime/get/screen.tsx	98.41%	2 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##           refactor    #1802      +/-   ##
============================================
+ Coverage     94.08%   94.84%   +0.75%     
============================================
  Files           130      143      +13     
  Lines          6631     7120     +489     
============================================
+ Hits           6239     6753     +514     
+ Misses          392      367      -25

☔ 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.

AlexanderRichey

Looks good! Blocking things are:

Simplifying the column handling where TokenPagedTablePicker is used. We might want to do something similar to what you have here in a later PR, but for now let's try to keep things as simple as possible.
Cleaning up some of the tests, particularly the ones for the RouterScreen.

AlexanderRichey · 2026-07-22T18:18:56Z

  showFooter = true,
  emptyMessage = "No data",
  focus = true,
+  selectionResetKey,


What's this for?

This handles terminal-height resizes. When pageSize changes, pagination resets but DataTable would otherwise retain its selected row and internal page. This resets those states while preserving filter and sort state.

AlexanderRichey · 2026-07-22T18:20:01Z

            {searchMode ? (
              <Text>
-                <Text color={theme.colors.primary}>/ Filter: </Text>
+                <Text color={theme.colors.primary}>/ {searchPlaceholder}: </Text>


What makes changing this necessary?

AlexanderRichey · 2026-07-22T18:24:22Z

+  }
+
+  return keys.filter((_, index) => selected.has(index));
+}


These changes add a lot of complexity. I see the upshot, but I'm not sure that now is the time to add all this. Let me pull these changes down and test the behavior a bit.

AlexanderRichey · 2026-07-22T18:28:52Z

@@ -0,0 +1,103 @@
+import { useNavigate } from "react-router";


I actually prefer a flat directory of components! I tend to think a flat directory is easier to maintain over time and that it makes it easier to find what you're looking for.

AlexanderRichey · 2026-07-22T18:33:26Z

+        };
+      }}
+      toRow={toRow}
+      columns={(terminalColumns) => {


We're adding a whole lot of complexity here. I tend to think we shouldn't worry about this problem now. When we do take on this problem, we should solve it in a general way and not in a way that will require every user of DataTable to solve the problem again, as I think the current approach would.

AlexanderRichey · 2026-07-22T18:48:45Z

      breadcrumb={breadcrumb}
      keyHints={[
        { key: "↑↓/kj", label: "navigate" },
+        ...(error && onRetry ? [{ key: "r", label: "retry" }] : []),


Should this be "retry" or "reload"?

I intentionally used "retry" because this action only appears after a failed query and invokes refetch to retry that request. I could switch it to "reload" if that makes more sense or you think would be more consistent for other places where we may want to use the "r" letter.

AlexanderRichey · 2026-07-22T18:50:29Z

+        const showCreatedAt = terminalColumns >= 90;
+        const statusWidth = showStatus ? 20 : 0;
+        const createdAtWidth = showCreatedAt ? 30 : 0;
+        const versionWidth = Math.max(8, terminalColumns - 2 - statusWidth - createdAtWidth);


Same here. I like the idea of a component that handles this stuff, but I think we need to simplify the approach here a bit.

The version picker now passes static columns without terminal-specific width calculations.

AlexanderRichey · 2026-07-22T19:05:28Z

+    agentRuntimeVersion: "7",
+    createdAt: new Date("2026-07-19T01:02:03.000Z"),
+    lastUpdatedAt: new Date("2026-07-20T12:34:56.000Z"),
+    roleArn: "arn:aws:iam::123456789012:role/runtime-role",


All of this stuff seems out of scope for RouterScreen tests. We should be testing the behavior of the router screen and not all this other stuff here.

AlexanderRichey · 2026-07-22T19:13:21Z

@@ -0,0 +1,7 @@
+export function withoutSdkMetadata(data: unknown): unknown {


I agree that we shouldn't show $metadata. Let's handle globally in a follow up.

AlexanderRichey

This is looking good! Let's merge this one. We have one follow up to handle which is to get the column lengths right in the data tables. Let's discuss offline on a strategy for this.

Hweinstock · 2026-07-23T18:19:38Z

@@ -1,4 +1,4 @@
-import React, { useState } from "react";
+import React, { useEffect, useState } from "react";


unrelated to change here but noticed the path has data-table. Should we swap to dataTable to be consistent in another PR?

Hweinstock · 2026-07-23T18:31:03Z

+  onEscape?: () => void;
+}
+
+// HarnessEndpointPicker fetches a harness's endpoints and renders them as a navigable


Patrick had a nice comment a bit ago about standardizing on TSDoc format. Do we think its worth trying to follow that standard?

I would recommend using TSDoc format consistently so you can get auto generated docs. I've spotted some functions throughout that just use //.

AlexanderRichey/agentcore-cli#3 (comment)

Updated the exported Harness picker documentation to TSDoc for consistency. I left implementation-only comments as regular comments.

Hweinstock · 2026-07-23T18:33:24Z


  return (
-    <Layout
+    <TokenPagedTablePicker


I really like this abstraction btw. One nit is the name TokenPagedTablePicker feels kinda odd to me. What do we think of PaginatedTablePicker? (also open to original name if we think it makes more sense)

I agree the name is currently a mouthful. Updating to your suggestion it is better.

aidandaly24 · 2026-07-23T19:15:01Z

We have one follow up to handle which is to get the column lengths right in the data tables. Let's discuss offline on a strategy for this.

Sounds good. For the follow-up, my initial direction is to make DataTable own terminal-aware column sizing rather than having each picker calculate widths. Column definitions could declare sizing intent such as minimum/maximum width and priority, while DataTable allocates the available width, truncates predictably, and hides optional columns only when necessary. We can align offline on the exact format and validate it.

github-actions Bot added agentcore-harness-reviewing AgentCore Harness review in progress and removed agentcore-harness-reviewing AgentCore Harness review in progress labels Jul 22, 2026

aidandaly24 commented Jul 22, 2026

View reviewed changes

AlexanderRichey requested changes Jul 22, 2026

View reviewed changes

aidandaly24 force-pushed the feat/runtime-read-only-tui branch from f7c3938 to 8a45204 Compare July 23, 2026 04:42

AlexanderRichey previously approved these changes Jul 23, 2026

View reviewed changes

Hweinstock previously approved these changes Jul 23, 2026

View reviewed changes

aidandaly24 added 20 commits July 23, 2026 19:00

feat: add Runtime TUI route menus

2cd8593

test: add controllable Runtime screen client

b95036a

test: focus Runtime test helper coverage

410de77

feat: add Runtime TUI picker

2575049

test: stabilize screen resize synchronization

506fef3

feat: add Runtime TUI hub and detail

95bd4c1

feat: add Runtime version TUI

1a3bb94

feat: add Runtime endpoint TUI

79301bb

feat: add explicit Runtime TUI entry

801f608

refactor: keep test IO options local

739efc8

test: complete Runtime TUI coverage

6d34438

test: verify Runtime TUI exit and filtering

76cb020

fix: stabilize Runtime pagination resets

3028bbf

fix: keep TUI footer stable in narrow terminals

2735339

fix: clarify Runtime latest version column

5ec22d0

fix: align Runtime TUI navigation with Harness

451c27d

refactor: simplify Runtime TUI helpers

e81653c

fix: align Runtime TUI entry and detail output

dbbe455

test: simplify Runtime TUI integration coverage

a25dd75

refactor: share token-paged table picker

6b7e4a2

aidandaly24 added 17 commits July 23, 2026 19:00

fix: strip SDK metadata from Runtime output

b98fdac

fix: support pasted table filters

9f4bfa0

test: stabilize Runtime TUI exit readiness

07bee92

test: decouple Runtime exit readiness from rendering

35118b6

refactor: align Runtime picker component placement

e44e5e4

test: replace fixed TUI delays with state waits

06c39f0

refactor: align Runtime route registration with Harness

97f175c

refactor: clarify Harness picker names

eaf3a2f

refactor: keep table filter copy generic

b1f1dac

test: remove redundant DataTable copy test

0b36541

refactor: separate table reset responsibilities

4fed8f0

refactor: simplify key hint width calculation

70e8350

test: consolidate runtime TUI coverage

0b11c1f

refactor: simplify paged picker implementation

88834c4

fix: preserve Winston dependencies after rebase

8c9ec77

refactor: defer SDK metadata filtering

0b46082

docs: use TSDoc for Harness pickers

432a397

aidandaly24 dismissed stale reviews from Hweinstock and AlexanderRichey via 432a397 July 23, 2026 19:01

aidandaly24 force-pushed the feat/runtime-read-only-tui branch from 8394594 to 432a397 Compare July 23, 2026 19:01

refactor: rename paginated table picker

4ffe40a

AlexanderRichey approved these changes Jul 23, 2026

View reviewed changes

Hweinstock approved these changes Jul 23, 2026

View reviewed changes

aidandaly24 merged commit 272e50e into refactor Jul 23, 2026
8 checks passed

aidandaly24 deleted the feat/runtime-read-only-tui branch July 23, 2026 19:56

aidandaly24 mentioned this pull request Jul 23, 2026

feat(runtime): add Runtime invocation #1820

Open

18 tasks

		@@ -0,0 +1,103 @@
		import { useNavigate } from "react-router";

		@@ -0,0 +1,7 @@
		export function withoutSdkMetadata(data: unknown): unknown {

		@@ -1,4 +1,4 @@
		import React, { useState } from "react";
		import React, { useEffect, useState } from "react";

Uh oh!

Conversation

aidandaly24 commented Jul 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Related Issue

Documentation PR

Type of Change

Testing

Checklist

Uh oh!

aidandaly24 Jul 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

codecov-commenter commented Jul 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

AlexanderRichey left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AlexanderRichey left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aidandaly24 commented Jul 23, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

aidandaly24 commented Jul 22, 2026 •

edited

Loading

aidandaly24 Jul 22, 2026 •

edited

Loading

codecov-commenter commented Jul 22, 2026 •

edited

Loading