the reference

read the light.

A spectroscope tells you what light is made of without touching the source. This reference works the same way: every section below is extracted straight from the source tree, and each one names the file it came from. The RunEvents are the spectral lines, a run is the light they add up to, and the JSONL file on disk is the plate it is recorded on.

the facade

Extracted from Spectro.java; the example is the owner-frozen wording from SPECTRO-API.md.

var agent = Spectro.agent()
    .model(Anthropic.opus())
    .tools(Tools.readFile(), Tools.runCommand())
    .workspace(Path.of("/tmp/scratch"));

for (RunEvent event : agent.run("Write hello.py and run it")) {
    System.out.println(event);   // the stream IS the observability
}

from spectroscope import Spectro, Anthropic, Tools

agent = Spectro.agent(
    model=Anthropic.opus(),
    tools=[Tools.read_file, Tools.run_command, Tools.spawn_agents],
    workspace="/tmp/scratch",
)

for event in agent.run("Write hello.py and run it"):
    print(event)   # the stream IS the observability

the Python port is in design. The JSONL wire is the contract, so a stream recorded by either edition replays in the other.

`agent()`	`Agent`	The five-lines facade — spectroscope's front door.
`panel()`	`FleetPanel`	The fleet path — several agents, one merged spectrum — in exactly the facade's shape.
`model(LlmProvider provider)`	`Agent`	One configured agent: setters chain, #run streams.
`tools(Tool... tools)`	`Agent`	The tool belt the model may call.
`workspace(Path workspace)`	`Agent`	The directory the file tools resolve and sandbox against.
`systemPrompt(String systemPrompt)`	`Agent`	Replaces the default unattended system prompt entirely.
`run(String prompt)`	`EventStream`	Runs one prompt against the agent and hands back the live stream.

RunEvents (35)

The wire contract. Extracted verbatim from spectro-web/src/events.ts — the same union the TypeScript edition and the JSONL files share. The server additionally announces workspace_info on the socket (SessionConnection.java); consumers skip unknown types by contract.

`run_start`

`runId`	`string`
`agentId`	`string`
`parentId`optional	`string`
`prompt`	`string`
`provider`optional	`string`
`model`optional	`string`
`trigger`optional	`string`
`attachments`optional	`AttachmentRef[]`
`workspace`optional	`string`
`llmWire`optional	`string`
`browserWire`optional	`string`
`children`optional	`string[]`
`contextWindow`optional	`number`
`windowSource`optional	`ThresholdSource`
`origin`optional	`string`
`ts`	`number`

`turn_start`

`agentId`	`string`
`turn`	`number`
`ts`	`number`

`text_delta`

`agentId`	`string`
`text`	`string`
`ts`	`number`

`thinking_delta`

`agentId`	`string`
`text`	`string`
`ts`	`number`

`tool_call`

`agentId`	`string`
`callId`	`string`
`name`	`string`
`input`	`unknown`
`ts`	`number`

`permission_request`

`agentId`	`string`
`callId`	`string`
`name`	`string`
`input`	`unknown`
`decidedBy`optional	`string \| null`
`ts`	`number`

`permission_decision`

`callId`	`string`
`allowed`	`boolean`
`ts`	`number`

`tool_result`

`agentId`	`string`
`callId`	`string`
`output`	`string`
`isError`	`boolean`
`durationMs`	`number`
`fileChange`optional	`string`
`ts`	`number`

`agent_spawn`

`agentId`	`string`
`parentId`	`string`
`task`	`string`
`ts`	`number`

`compaction`

`agentId`	`string`
`removedTurns`	`number`
`summaryChars`	`number`
`ts`	`number`

`context_cleared`

`agentId`	`string`
`removedMessages`	`number`
`ts`	`number`

`playbook_progress`

`agentId`	`string`
`runId`	`string`
`phase`	`"start" \| "step" \| "end"`
`playbook`optional	`string`
`task`optional	`string`
`node`optional	`string`
`name`optional	`string`
`provider`optional	`string`
`model`optional	`string`
`stopReason`optional	`string`
`result`optional	`string`
`detail`optional	`string`
`ts`	`number`

`playbook_picked`

`dir`optional	`string`
`name`optional	`string`
`none`optional	`boolean`
`ts`	`number`

`run_step`

`agentId`	`string`
`runId`	`string`
`runKind`	`"playbook" \| "workflow"`
`phase`	`"run_start" \| "step_start" \| "step_end" \| "run_end"`
`name`optional	`string`
`task`optional	`string`
`nodes`optional	`{ id: string; name?: string; kind: string }[]`
`node`optional	`string`
`kind`optional	`string`
`entry`optional	`number`
`performer`optional	`"chat" \| "child"`
`role`optional	`string`
`provider`optional	`string`
`model`optional	`string`
`picked`optional	`boolean`
`input`optional	`string`
`inputChars`optional	`number`
`reads`optional	`{ doc: string; path?: string }[]`
`round`optional	`number`
`maxRounds`optional	`number`
`status`optional	`"done" \| "failed" \| "stopped"`
`durationMs`optional	`number`
`childId`optional	`string`
`children`optional	`string[]`
`output`optional	`string`
`outputChars`optional	`number`
`documents`optional	`{ doc: string; path: string; change?: "created" \| "changed" }[]`
`label`optional	`string`
`error`optional	`string`
`stopReason`optional	`string`
`result`optional	`string`
`detail`optional	`string`
`ts`	`number`

`llm_exchange`

`xid`	`string`
`agentId`	`string`
`turn`optional	`number`
`kind`	`string`
`provider`	`string`
`model`	`string`
`transport`	`string`
`url`	`string`
`status`optional	`number`
`requestBytes`	`number`
`responseBytes`	`number`
`responseLines`	`number`
`aborted`	`boolean`
`fidelity`	`string`
`durationMs`	`number`
`ts`	`number`

`usage`

`agentId`	`string`
`inputTokens`	`number`
`outputTokens`	`number`
`cacheReadTokens`optional	`number`
`cacheCreationTokens`optional	`number`
`aiCredits`optional	`number`
`ts`	`number`

`run_end`

`runId`	`string`
`stopReason`	`string`
`ts`	`number`

`error`

`agentId`optional	`string`
`message`	`string`
`ts`	`number`

`image_generated`

`agentId`	`string`
`callId`	`string`
`prompt`	`string`
`provider`	`string`
`model`	`string`
`mediaType`	`string`
`blobPath`	`string`
`sha256`	`string`
`ts`	`number`

`context_info`

`agentId`	`string`
`turn`	`number`
`messages`	`number`
`estimatedTokens`	`number`
`threshold`	`number`
`thresholdSource`optional	`ThresholdSource`
`contextWindow`optional	`number`
`parts`	`{ label: string; chars: number; estTokens: number; text?: string }[]`
`ts`	`number`

`window_override`

`tokens`optional	`number`
`threshold`	`number`
`thresholdSource`optional	`ThresholdSource`
`contextWindow`optional	`number`
`ts`	`number`

`agent_message`

`from`	`string`
`to`	`string`
`role`	`string`
`state`	`string`
`text`	`string`
`label`optional	`string`
`ts`	`number`

`plan`

`agentId`	`string`
`steps`	`{ text: string; status: string }[]`
`ts`	`number`

`browser_action`

`agentId`	`string`
`callId`optional	`string`
`cid`	`string`
`epoch`	`number`
`tool`	`string`
`url`optional	`string`
`ok`	`boolean`
`resultBytes`	`number`
`durationMs`	`number`
`sha256`optional	`string`
`ts`	`number`

`hook_decision`

`agentId`	`string`
`callId`	`string`
`toolName`	`string`
`event`	`string`
`matcher`	`string`
`command`	`string`
`timeoutSeconds`	`number`
`verdict`	`string`
`reason`optional	`string`
`ts`	`number`

`settings_ignored`

`key`	`string`
`file`	`string`
`hint`	`string`
`inForce`optional	`boolean`
`inForceFrom`optional	`string`
`kept`optional	`string[]`
`ts`	`number`

`launch_outcome`

`name`	`string`
`ok`	`boolean`
`up`	`boolean`
`url`optional	`string`
`problem`optional	`string`
`durationMs`	`number`
`ts`	`number`

`no_progress`

`agentId`	`string`
`detector`	`string`
`count`	`number`
`details`optional	`string[]`
`evidence`	`string`
`callId`optional	`string`
`ts`	`number`

`progress_intervention`

`agentId`	`string`
`callId`	`string`
`detector`	`string`
`intervention`	`string`
`stoodDown`	`boolean`
`ts`	`number`

`continuation`

`agentId`	`string`
`decision`	`string`
`continuation`	`number`
`budget`	`number`
`openSteps`	`number`
`totalSteps`	`number`
`inputTokens`	`number`
`evidence`	`string`
`ts`	`number`

`goal_check`

`agentId`	`string`
`outcome`	`string`
`command`	`string`
`exitCode`optional	`number \| null`
`judge`	`string`
`output`	`string`
`durationMs`	`number`
`gateWaitMs`optional	`number \| null`
`evidence`	`string`
`ts`	`number`

`images_withheld`

`agentId`	`string`
`images`	`number`
`model`optional	`string`
`reason`	`string`
`ts`	`number`

`question_asked`

`agentId`	`string`
`callId`	`string`
`questions`	`AskedQuestionWire[]`
`ts`	`number`

`question_answered`

`callId`	`string`
`answers`	`string[]`
`cancelled`	`boolean`
`waitMs`optional	`number`
`ts`	`number`

`steering_message`

`agentId`	`string`
`text`	`string`
`taken`	`boolean`
`turn`	`number`
`ts`	`number`

socket frames (29)

Client → server messages on /ws. In the other direction the server sends RunEvent JSON plus socket-only UI frames: workspace_info, provider_info, permission_mode_info, and the fleet frames fleet_roster and fleet_event. Consumers skip unknown types by contract.

`user_message`

`text`	`string`
`attachments`optional	`{ mediaType: string; dataBase64: string }[]`

`permission_response`

`callId`	`string`
`allowed`	`boolean`
`remember`optional	`boolean`
`persist`optional	`boolean`

`abort`

`set_image_provider`

provider string

`set_thinking`

enabled boolean

`set_reasoning`

`mode`	`"on" \| "off" \| "default"`
`effort`optional	`string`

`set_provider`

`provider`	`string`
`model`optional	`string`
`ask`optional	`string`

`set_workspace`

`mode`optional	`ChooserOption`
`path`optional	`string`

`set_permission_mode`

mode string

`set_tool_groups_off`

`groups`	`string[]`
`save`optional	`boolean`

`set_local_mode`

`on`optional	`boolean`
`values`optional	`Record<string, unknown>`
`reset`optional	`string[]`

`set_window_override`

tokens number | null

`question_response`

`callId`	`string`
`answers`	`string[]`
`cancelled`optional	`boolean`

`steering_message`

text string

`compact_context`

`clear_context`

`start_playbook`

`dir`	`string`
`hash`	`string`
`prompt`	`string`
`picks`optional	`Record<string, { provider: string; model: string }>`
`ask`optional	`string`

`confirm_playbook`

`prompt`	`string`
`dir`optional	`string`

`set_playbook`

`dir`	`string \| null`
`none`optional	`true`

`start_workflow`

`dir`	`string`
`file`	`string`
`hash`	`string`
`input`	`string`
`lang`	`"en" \| "de"`

`start_workflow`

`name`	`string`
`input`	`string`
`lang`	`"en" \| "de"`
`dir`optional	`string`

`wake_session`

sessionId string

`peer_message_decision`

`msgId`	`string`
`deliver`	`boolean`

`send_peer_message`

`to`	`string`
`toSession`optional	`string`
`text`	`string`

`set_goal`

`outcome`	`string`
`check`	`string`

`set_loop`

`action`	`"start"`
`prompt`	`string`
`intervalSeconds`optional	`number`

`set_loop`

action "stop"

`get_session_items`

`graph_ask`

question string

REST endpoints (123)

Extracted from the @GetMapping/@PostMapping/@DeleteMapping annotations in spectro-server.

POST `/api/analyze`

One analysis call, streamed as NDJSON.

AnalyzeController.java

GET `/api/analyze/engine`

The opt-in run analysis (card 294): an imported run's compact digest goes to the configured provider ONCE, on an explicit click, and the model's reading comes back as a stream.

AnalyzeController.java

GET `/api/browser/status`

Where the browser pane goes, and whether one exists — the two things the web UI needs in order to draw the browser segment honestly.

BrowserViewportController.java

POST `/api/browser/viewport`

The rectangle the browser segment reserved, in window CSS pixels.

BrowserViewportController.java

GET `/api/bundles`

The starter-bundle endpoints.

BundleController.java

GET `/api/bundles/{id}`

The catalog for a given stamp.

BundleController.java

POST `/api/bundles/{id}/scaffold`

POST /api/bundles/{id}/scaffold {dir, build} — write the bundle's files into dir.

BundleController.java