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 (19)

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[]`
`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`
`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`

`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`
`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	`"override" \| "window" \| "model" \| "fallback"`
`contextWindow`optional	`number`
`parts`	`{ label: string; chars: number; estTokens: number; text?: string }[]`
`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`

socket frames (10)

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`

`set_workspace`

`mode`optional	`"random" \| "default" \| "set"`
`path`optional	`string`

`set_permission_mode`

mode string

`question_response`

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

REST endpoints (73)

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}`

GET /api/bundles/{id}?build=gradle — the rendered file set (copy-paste).

BundleController.java

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

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

BundleController.java