workboard Plugin

workboard is the clearest HTTP-injection-style plugin in the current built-in set.

Unlike skill, web, asr, and tts, it is not mainly action-driven. It is more about:

• runtime state exposure
• structured snapshot output
• control-plane and UI consumption

What it does

Its responsibility can be summarized in one sentence:

• expose the agent's current and recent work state as a structured snapshot for external surfaces

Its core capability today is one runtime HTTP route:

• GET /api/workboard/snapshot

Why it matters

Because it shows a very important point:

• a plugin does not have to be “used” mainly through runAction(...)

Some plugins are not mainly consumed by the agent itself. Their main consumers are:

• Console
• UI
• status dashboards
• control-plane proxies

workboard is exactly that shape.

Which plugin capabilities it uses

workboard currently uses:

• actions
• http.server

It does not use:

• setup
• usage
• system
• hooks

That tells you its job is extremely focused: provide one controlled, authenticated, observable snapshot surface.

Typical runtime flow

A normal workboard request usually flows like this:

1. an external surface issues GET /api/workboard/snapshot
2. runtime checks the plugin-declared auth policy first
3. workboard reads the current snapshot from the snapshot store
4. it returns structured JSON

The important part is not only the route itself. It is that:

• the route belongs to a plugin
• auth policy is declared by the plugin
• plugin presence comes from registration

Auth requirement

The current snapshot endpoint requires:

• authenticated access
• permission agent.read

That tells you it is not a public anonymous status page. It is a controlled runtime observability surface.

Typical scenarios

Scenario 1: Console wants to show “what is the agent doing right now”

The most common approach is to poll or fetch on demand:

• GET /api/workboard/snapshot

Then render the returned structure as a workboard or activity panel.

Scenario 2: you are building a control-plane proxy that needs agent runtime snapshots

workboard returns structured JSON instead of raw freeform logs, which makes it a strong control-plane data source.

Scenario 3: you are documenting or designing HTTP-style plugins

workboard is the most direct current reference.

How to think about it in the SDK

For workboard, the important question is not “how do I runAction it?”

The important question is “how does it safely contribute runtime HTTP routes?”

That means its main consumption path is closer to:

• external HTTP clients

not:

• local explicit SDK action calls

The interface it exposes

The main interface today is:

GET /api/workboard/snapshot

On success, it returns a structured snapshot response.

If an internal snapshot read fails, it usually returns:

• 500

Why it does not need actions

This is the key to understanding workboard.

Its goal is not to provide a “user clicks and runs one business operation” interface.

Its goal is to provide a state surface that other interfaces can read continuously.

In that shape:

• an HTTP route is more natural than an action

because:

• the consumer is already a UI, proxy, or console
• those consumers naturally prefer HTTP JSON endpoints

How it relates to plugin HTTP docs

If you want to fully understand workboard, read it alongside:

• Plugin HTTP injection

because workboard is the standard current example of that mechanism.

Its boundary relative to runtime ownership

workboard is not a background worker runtime owner.

It is a:

• runtime snapshot exposure plugin

Its job is not to do the work. Its job is to expose what work is being done.

That kind of need naturally fits plugin HTTP injection better than a separate custom communication surface.

Important boundaries

It is an observability surface, not a business execution surface

Do not treat it like an action center.

It depends on controlled permissions

If the caller does not have agent.read, the endpoint should not be exposed to that caller.

Registration decides whether it exists

workboard no longer reads project config for a second enable/disable switch. If the plugin is registered, this observability surface exists; if it is not registered, the action and HTTP route are not mounted.

When to use it as a reference

Use workboard as a reference for:

• plugin HTTP injection
• runtime state snapshots
• UI and Console observability surfaces
• permission-controlled status endpoints

Related docs

• Built-in Plugin Overview
• Plugin HTTP injection
• Custom plugin