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
- Select a compiled tool, prompt, resource, CLI command, script, or event route.
- Generate an input editor from the compiled schema and route config.
- Run the real development route with the same request context and providers
used by production.
- Apply shell/progress/replace/error/complete events to the browser stage.
- Show formatted Markdown by default, with Agent Document and projection data
available for inspection.
Host-aware lifecycle replay
- Select an installed target host and one supported semantic lifecycle.
- Use a real observed native fixture/receipt or a checked-in adapter fixture as
the replay source, clearly identifying which one it is.
- Decode native input through the target adapter.
- execute the generated semantic event route and renderer;
- encode the resulting native response or delivery route;
- 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
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 --openshould provide an app-like development loop insteadof requiring authors to reason through raw MCP Inspector forms and JSON traces.
Existing foundation
The Workbench already has meaningful pieces to preserve:
canonical/native mapping;
a runtime stage;
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
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:
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
used by production.
available for inspection.
Host-aware lifecycle replay
the replay source, clearly identifying which one it is.
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
AgentDocumentSnapshotandordered event stream.
Agent.Markdownrenders with an audited Markdown projector such as TanStackMarkdown.
components and capability status.
actually receives without changing the canonical document.
Development lifecycle
agent-bundle dev --openopens the Workbench after the first valid build.manifest without a browser reload.
artifact identity.
Non-goals
Acceptance criteria
command with no manually authored Workbench catalog.
content, progress, Suspense replacement, and final status from one invocation.
final output appears through the same Agent Document stage.
through their real adapter probes, with observable tools/components listed.
RSC rendering, and native encode, and identifies fixture versus observed
receipt provenance.
identity have browser and framework Rstest coverage.
Design references
Stack position
rendered warnings inspectable in the browser.
Full meta-framework stack