Events and Types

The events the backend emits and the TypeScript types the bridge uses.

On this page11 events and the bridge types

onTextDelta
onToolCall
onToolCallEnd
onNodeCreated
onAgentDone
onPlan
onPlanUnavailable
onPlanRejected
onMarkerChanged
onChatGptStatus
onMlModelProgress

Events

Subscribe with the unlisten pattern. Each handler returns an UnlistenFn — call it in useEffect cleanup.

const unlisten = await bridge.onTextDelta((chunk) => {
  appendText(chunk);
});
// cleanup:
return () => { unlisten(); };

Event	Payload	Description
`onTextDelta(cb)`	`string (text chunk)`	Each streamed text chunk from the LLM. Append to the current assistant message.
`onToolCall(cb)`	`{ name, id }`	Tool execution started. Use to show a tool badge in the chat UI.
`onToolCallEnd(cb)`	`{ id, ok: boolean, not_run: boolean, view? }`	Tool execution completed. ok = false if the tool returned an error. not_run = true (with ok = false) when the call was announced but never dispatched (declined, reworded, unanswered, or over the tool budget): show it as not run, not as a failure. view is set for the few tools that return something to draw or play: plot_spectrum's chart, and audition_effect's excerpt with a target caption (track 1, the master bus, or bus "Drums").
`onNodeCreated(cb)`	`nodeId: string`	An agent tool call moved the session's head: to a new node, or to one already in the graph (revert_to, fork_node). nodeId is the head the session is on after the call, not a node_id from the tool's result, and it is sent once per call that moved it, even one that then failed. A call that leaves the head where it was (name_node, a read) sends nothing. Refresh the graph view and track list.
`onAgentDone(cb)`	`none`	Agent turn fully complete — no more text or tool calls.
`onPlan(cb)`	`steps: { step, tool, description }[]`	Something needs approval before it runs: the agent's plan, or with Plan first on and no plan, its first edit shown as the exact tool calls and arguments. The turn waits for approvePlan() or rejectPlan().
`onPlanUnavailable(cb)`	`reason: string, firstEditHeld: boolean`	A plan was asked for and none arrived. firstEditHeld says whether the first edit will be held for approval (Plan first on) or the turn proceeds with no gate.
`onPlanRejected(cb)`	`none`	The user declined a plan or a held edit. The turn ends with no onAgentDone.
`onMarkerChanged(cb)`	`none`	Marker or region annotation added, renamed, moved or removed. Refresh the marker list.
`onChatGptStatus(cb)`	`status: ChatGptStatus`	The ChatGPT sign-in changed (event chatgpt://status), sent when the status differs from the last one sent: a sign-in begins, ends or is cancelled, a sign-out, a session that ended inside a turn or a refresh, a message kept or taken. Lets a card follow a sign-in that is happening in the browser. The payload is the object chatgptStatus answers with.
`onMlModelProgress(cb)`	`status: MlModelStatus`	A downloadable model changed state (event ml-model-progress): the start, progress at most every 100 ms, the end (ready, failed, or not_downloaded after a cancel) and a removal. The payload is the object the model commands answer with.

Key types

type NodeId = string;
type ProviderId = "anthropic" | "openrouter" | "openai" | "groq" | "gemini" | "ollama";

interface ProjectInfo  { path: string; head: NodeId | null }
interface SessionNode  { id: NodeId; parent: NodeId | null; created_at: string; label: string | null; reasoning: string | null; state: SessionState }
interface GraphSummary { nodes: GraphNode[]; head: NodeId | null }
interface GraphNode    { id: NodeId; parent: NodeId | null; label: string | null; tool: string | null; created_at: string }
interface TrackSummary { id: string; name: string; muted: boolean; gain_db: number; pan: number; soloed: boolean; audio_path: string | null; clips: ClipSummary[] }
interface ClipSummary  { start_sec: number; length_sec: number; source_path: string; volume_envelope: { time_sec: number; gain_db: number }[] }
interface RenderWarning { scope: { type: "track"; index: number; name: string } | { type: "bus"; name: string } | { type: "master" }; effect_index: number; kind: string; reason: "not_yet_streamable" | "unknown" }
interface ModelInfo    { id: string; display_name: string; context_length: number | null; provider_hint: string | null }
interface ModelCatalogue { models: ModelInfo[]; source: "live" | "fallback"; notice: string | null }
type MlRuntimeStatus =
  | { state: "found"; version: string; path: string; source: "bundled" | "environment" | "executable" }
  | { state: "missing"; searched: string[] }
  | { state: "unsupportedOs"; needs: string; running: string }
  | { state: "loadFailed"; path: string | null; reason: string };
type Marker           = { id: string; name: string; kind: "marker"; time_sec: number }
                      | { id: string; name: string; kind: "region"; start_sec: number; end_sec: number }