Skip to content

Add an interactive Agent Workbench with local host discovery and lifecycle replay #105

Description

@ScriptedAlchemy

Summary

Evolve the existing dev Workbench into the browser half of Agent Bundle's
meta-framework. It should derive its UI from the same compiled route, event,
target, and capability manifests as production; discover installed target hosts
and their real exposed tools/components on the local machine; execute or replay
those surfaces; and render the real Agent Document output as formatted
Markdown, structured data, rich content, progress, and boundary updates.

agent-bundle dev --open should provide an app-like development loop instead
of requiring authors to reason through raw MCP Inspector forms and JSON traces.

Existing foundation

The Workbench already has meaningful pieces to preserve:

  • a build-scoped capability catalog derived from artifact inspection;
  • Hooks pages that execute generated wrappers from canonical inputs and show
    canonical/native mapping;
  • an MCP page with real client sessions and MCP App rendering;
  • a Runtime Playground that creates and replays runs, reads Flight, and renders
    a runtime stage;
  • last-good build behavior and dev rebuild events.

The missing feature is one compiler-derived application model that joins the
new filesystem routes, real Agent Document renderer, semantic event lifecycle,
and locally observed host/tool catalogs into one usable authoring experience.

Product model

agent-bundle dev --open
  -> compile project route/capability manifests
  -> discover selected installed local hosts and exposed components/tools
  -> open Workbench
       |- route catalog and generated input editors
       |- host/target selector
       |- event lifecycle timeline and replay
       |- live Agent Document stage
       |- formatted Markdown/rich-content view
       |- target projection and protocol/native trace
       `- rebuild diagnostics and last-good output

The Workbench reads authoritative framework and host adapter catalogs. It does
not keep a second handwritten list of routes, event payloads, or output
components.

Local host discovery

Each target adapter may implement a read-only local discovery probe that finds
the host installations/config roots it understands and returns actually
observable components:

interface ObservedLocalHost {
  target: AgentTarget;
  installation: Observed<HostInstallation>;
  components: readonly ObservedHostComponent[];
  tools: readonly ObservedTool[];
  events: Readonly<Record<AgentEventKind, CapabilityState>>;
}

The probe uses the same native paths, schemas, host CLIs, and MCP handshakes as
the target adapter. It may discover generated plugins, skills, commands, rules,
hooks/events, configured MCP servers/tools, Apps, or native extensions where
the host exposes them. If a proprietary built-in tool catalog is not observable,
the Workbench reports that boundary instead of inventing tools.

This is direct discovery, not a separate sanitized-profile architecture. The
feature does not add a general security or credentials subsystem.

Authoring journeys

Tool and route preview

  1. Select a compiled tool, prompt, resource, CLI command, script, or event route.
  2. Generate an input editor from the compiled schema and route config.
  3. Run the real development route with the same request context and providers
    used by production.
  4. Apply shell/progress/replace/error/complete events to the browser stage.
  5. Show formatted Markdown by default, with Agent Document and projection data
    available for inspection.

Host-aware lifecycle replay

  1. Select an installed target host and one supported semantic lifecycle.
  2. Use a real observed native fixture/receipt or a checked-in adapter fixture as
    the replay source, clearly identifying which one it is.
  3. Decode native input through the target adapter.
  4. execute the generated semantic event route and renderer;
  5. encode the resulting native response or delivery route;
  6. show canonical input, request context, render timeline, final document,
    native projection, and diagnostics in one correlated view.

Replay exercises the real generated wrapper and adapter codecs. A deterministic
replay is not labeled as proof that the external host dispatched the event.

Installed MCP/tool use

For an observed configured MCP server, reuse the Workbench's real MCP client
session to initialize, list, call, read, or retrieve prompts according to the
negotiated protocol. Do not replace a failed connection with a fixture and do
not write non-protocol output to the server's stdout.

Browser rendering

  • The browser consumes the renderer's versioned AgentDocumentSnapshot and
    ordered event stream.
  • Agent.Markdown renders with an audited Markdown projector such as TanStack
    Markdown.
  • Image, audio, resources, errors, and structured values have explicit visual
    components and capability status.
  • Suspense fallbacks are replaced rather than left beside final content.
  • Progress updates are shown as mutable invocation status.
  • A target-projection switch shows what MCP, CLI, or a native event response
    actually receives without changing the canonical document.

Development lifecycle

  • agent-bundle dev --open opens the Workbench after the first valid build.
  • Adding/removing/renaming a route updates navigation from the new compiler
    manifest without a browser reload.
  • Source errors retain and label the last-good route catalog and rendered run.
  • Rebuilds cancel stale runs and prevent old events from updating a new build.
  • Saved replays remain bound to their original build, target contract, and
    artifact identity.

Non-goals

  • A replacement for native host acceptance tests.
  • Guessing proprietary built-in host tools that expose no catalog.
  • A second route/capability registry owned by the browser.
  • Implementing collision detection or TraceDecay domain behavior in Workbench.
  • Presenting adapter fixtures as live host activity.

Acceptance criteria

  • A framework-mode project opens a populated browser Workbench from one dev
    command with no manually authored Workbench catalog.
  • The Workbench renders real Agent Document Markdown, structured output, rich
    content, progress, Suspense replacement, and final status from one invocation.
  • A compiled MCP tool can be invoked through a real MCP client session and its
    final output appears through the same Agent Document stage.
  • At least two materially different installed target hosts are discovered
    through their real adapter probes, with observable tools/components listed.
  • A semantic lifecycle replay crosses native decode, generated route execution,
    RSC rendering, and native encode, and identifies fixture versus observed
    receipt provenance.
  • Unobservable host tools/events appear unavailable rather than fabricated.
  • Route changes, invalid source, last-good output, cancellation, and stale replay
    identity have browser and framework Rstest coverage.

Design references

Stack position

Full meta-framework stack

Activity

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or requesthost-integrationAgent host capabilities, projection, discovery, and lifecyclemeta-frameworkAgent Bundle compiler-coupled meta-frameworkrscReact Server Components and Agent Document renderingruntimeRuntime context, state, rendering, or executiontestingFramework test harnesses and integration evidence

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions