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:

• availability
• http.runtime

It does not use:

• actions
• setup
• usage
• system
• hooks

That tells you its job is extremely focused: provide one controlled, authenticated, observable HTTP 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 checks its own availability
4. if unavailable, it returns 503
5. if available, it reads the current snapshot from the snapshot store
6. 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
• availability is aligned with plugin lifecycle

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 the plugin is currently unavailable, it usually returns:

• 503

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 services

workboard is not a “background worker service.”

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

Availability still affects endpoint behavior

Even if the route exists, a disabled or unavailable plugin does not guarantee a successful response.

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
• Plugin vs service