Add minimal Runtime domain support for live inspection

[V3RON]

The CLI is strong for profiling, memory analysis, traces, console capture, and network inspection, but it does not yet expose the Chrome DevTools Protocol Runtime domain as a first-class workflow. That leaves a gap for interactive debugging: an LLM agent can record and analyze data, but it cannot directly evaluate expressions against the selected target, inspect returned remote objects, or explicitly release inspector-held object handles during a long-lived daemon session.

This matters most for agent-driven debugging on Chrome, Node.js, and React Native targets. The minimal missing primitives are live expression evaluation, follow-up object property inspection, and explicit release of preserved handles.

Observed Findings

• The current CLI command families in packages/agent-cdp/src/cli.ts are: daemon lifecycle, target selection, console, network, trace, raw memory capture, heap snapshot analysis, JS heap monitoring, JS allocation profiling, JS allocation timeline profiling, JS CPU profiling, and skills.
• The published help from pnpm run agent-cdp --help does not list a runtime command family.
• The tool already uses some Runtime-related CDP commands internally, but only for existing features:
  • packages/agent-cdp/src/console.ts sends Runtime.enable, Console.enable, and Log.enable to collect console output.
  • packages/agent-cdp/src/js-memory/capture.ts uses Runtime.getHeapUsage for heap usage sampling.
• There is no Runtime-specific module directory yet. Existing feature families with richer behavior are organized into their own folders such as src/network/, src/js-memory/, src/js-allocation/, src/js-allocation-timeline/, src/js-profiler/, and src/heap-snapshot/.
• The daemon currently routes feature work through typed IPC commands in packages/agent-cdp/src/types.ts and command handlers in packages/agent-cdp/src/daemon.ts.
• The README currently lists command groups and capabilities for console, network, traces, memory, heap snapshots, JS memory, JS allocation, allocation timeline, JS profiling, and skills, but not Runtime inspection.
• The packaged skills currently include core.md and network.md. There is no runtime.md skill yet.

Suggested Behavior

Add a minimal, cross-target Runtime command family that works with Chrome, Node.js, and React Native targets and is optimized for LLM-agent debugging workflows.

Initial command scope

Implement only these commands in the first pass:

• agent-cdp runtime eval --expr EXPR [--await] [--json]
• agent-cdp runtime props --id OBJECT_ID [--own] [--accessor-properties-only]
• agent-cdp runtime release --id OBJECT_ID
• agent-cdp runtime release-group --group NAME

Do not add lower-priority Runtime commands yet, including:

• Runtime.callFunctionOn
• Runtime.queryObjects
• object history or registry commands beyond CDP's own objectId and objectGroup
• Runtime event streaming or exception tracking
• Debugger domain commands

Required behavior details

runtime eval

• Back this command with Runtime.evaluate.
• Support --await by mapping it to awaitPromise: true.
• Use a stable object group for agent-created handles, for example agent-cdp-runtime.
• Preserve returned remote object handles by default so the caller can inspect them in follow-up commands.
• If the result is a primitive or is returned by value safely, print a concise agent-friendly summary.
• If the result is a remote object, print a compact summary that includes at least:
  • object type / subtype when available
  • a short preview or description when available
  • the objectId
  • the object group name if useful for cleanup guidance
• --json should prefer JSON-like output for by-value results, but it should not hide objectId information for remote objects.
• Keep default output compact and readable; do not use JSON as the default CLI output format.

runtime props

• Back this command with Runtime.getProperties.
• Accept an existing objectId via --id.
• Support only the following first-pass flags:
  • --own
  • --accessor-properties-only
• Return a concise property listing suitable for agent consumption.
• Each property row should include at least:
  • property name
  • property kind / type when determinable
  • a short value preview
  • nested objectId when the property value is itself a remote object
• Do not add deep recursion, prototype-chain browsing, pagination, or object navigation helpers in v1.

runtime release

• Back this command with Runtime.releaseObject.
• Release a single objectId and print a short confirmation.

runtime release-group

• Back this command with Runtime.releaseObjectGroup.
• Allow bulk cleanup of the stable Runtime object group or any other explicit group name.
• Print a short confirmation.

Encapsulation and file layout

Keep Runtime fully encapsulated under a dedicated directory named after the domain:

• packages/agent-cdp/src/runtime/

Suggested internal file layout:

• packages/agent-cdp/src/runtime/index.ts
• packages/agent-cdp/src/runtime/types.ts
• packages/agent-cdp/src/runtime/formatters.ts

Export only what the top-level CLI and daemon wiring need, such as:

• RuntimeManager
• any public Runtime result types actually consumed outside the folder

Keep helper functions private to the Runtime folder.

IPC and daemon integration

Add the smallest IPC surface necessary in packages/agent-cdp/src/types.ts:

• runtime-eval
• runtime-get-properties
• runtime-release-object
• runtime-release-object-group

In packages/agent-cdp/src/daemon.ts:

• instantiate a RuntimeManager
• route the four Runtime IPC commands to it
• use the existing connected-session flow, not a new session lifecycle
• avoid broader daemon changes

CLI and formatting integration

Update packages/agent-cdp/src/cli.ts to:

• add a new Runtime: section to the usage text
• parse and dispatch the four Runtime subcommands
• preserve the current CLI style and error messages

Add compact Runtime formatters that optimize for token-efficient output. Favor concise summaries over raw protocol dumps in default output.

Documentation and skill updates

Update README.md to make Runtime a listed command family and capability.

At minimum:

• mention Runtime inspection in the top-level description
• add Runtime to the quick-start feature list
• add Runtime to the command overview list
• add a short Runtime inspection section with examples

Add a new packaged skill file:

• packages/agent-cdp/skills/runtime.md

The Runtime skill should be explicit that Runtime handles are preserved by default. It should explain:

• when to use Runtime versus Console
• a safe probing workflow for LLM agents
• what objectId means
• what an object group is
• that preserved handles should be released when no longer needed in long-lived sessions
• that releasing a handle drops the inspector reference, not the app's own references
• that Runtime.evaluate can have side effects if the expression mutates state
• examples for Chrome, Node.js, and React Native usage

Also update packages/agent-cdp/skills/core.md so Runtime appears in the feature overview and the core skill points users to agent-cdp skills get runtime for domain-specific guidance.

Tests

Add only the minimum targeted test coverage needed for this feature:

• update packages/agent-cdp/src/__tests__/cli.test.ts so usage coverage includes the new Runtime commands
• add a focused Runtime test file, for example packages/agent-cdp/src/__tests__/runtime.test.ts

The Runtime tests should cover at least:

• normalization / formatting of a primitive eval result
• normalization / formatting of a string eval result
• normalization / formatting of a remote object eval result that includes objectId
• normalization / formatting of getProperties results with both primitive properties and nested remote object handles
• manager-level release behavior if that is easy to unit test

Avoid large daemon-level integration tests unless they are very cheap in the existing test structure.

Implementation Plan

1. Add a new src/runtime/ module with minimal Runtime types, result normalization, and compact formatters.
2. Implement a RuntimeManager that wraps Runtime.evaluate, Runtime.getProperties, Runtime.releaseObject, and Runtime.releaseObjectGroup against the active session transport.
3. Add the four Runtime IPC command types to packages/agent-cdp/src/types.ts.
4. Wire a single RuntimeManager instance into packages/agent-cdp/src/daemon.ts and route the new Runtime IPC commands through the existing connected-session flow.
5. Extend packages/agent-cdp/src/cli.ts usage text and command dispatch to support the new runtime subcommands.
6. Add concise Runtime-specific formatters and keep default output non-JSON and token-efficient.
7. Add packages/agent-cdp/skills/runtime.md, update packages/agent-cdp/skills/core.md, and update README.md so Runtime becomes a documented command family.
8. Add the minimum focused tests for CLI usage text and Runtime result normalization / formatting.

Resolution Summary

agent-cdp should gain a minimal Runtime domain focused on live inspection for LLM agents: expression evaluation, object property inspection, and explicit release of preserved inspector handles. The implementation should stay cross-target for Chrome, Node.js, and React Native, remain encapsulated under src/runtime/, and include the necessary CLI, daemon, README, and skill updates so another engineer can implement and ship it without expanding scope into lower-priority Runtime or Debugger work.