Overview

pinocchio/pkg/chatapp is the reusable chat application layer on top of sessionstream. It owns the base chat command, event, UI-event, and timeline schemas, while application packages can add more behavior through ChatPlugin implementations.

The current chatapp contract is protobuf-first:

• source schema: proto/pinocchio/chatapp/v1/chat.proto
• generated Go package: pkg/chatapp/pb/proto/pinocchio/chatapp/v1
• generator config: buf.chatapp.gen.yaml
• runtime registration: chatapp.RegisterSchemas(reg, plugins...)

Sessionstream still delivers browser frames as JSON over WebSocket, but those frames are the JSON form of registered protobuf messages. Backend code should publish concrete, feature-owned proto.Message payloads, not ad-hoc maps or generic google.protobuf.Struct objects.

Schema policy: concrete protobuf for every durable contract

Every chatapp/sessionstream command, backend event, UI event, and timeline entity payload must have its own concrete protobuf message, including app-specific features. Treat the protobuf type as the durable API contract between:

• runtime event producers;
• sessionstream projection code;
• persisted timeline snapshots;
• WebSocket JSON frames;
• frontend renderers and generated TypeScript types.

Do not register google.protobuf.Struct for event/UI/timeline payloads just because a feature is app-local. App-local still means durable once it is persisted, hydrated, or rendered after reload.

Good:

reg.RegisterUIEvent("ChatAgentModeCommitted", &chatappv1.AgentModeCommittedUpdate{})
reg.RegisterTimelineEntity("AgentMode", &chatappv1.AgentModeEntity{})

Avoid:

reg.RegisterUIEvent("ChatAgentModeCommitted", &structpb.Struct{})
reg.RegisterTimelineEntity("AgentMode", &structpb.Struct{})

Use google.protobuf.Struct only inside a typed message field when the field is intentionally open-ended metadata, for example provider-specific debug details or arbitrary tool input/output. The outer payload registered with sessionstream should still be a named protobuf message.

A repository-level architecture test (pkg/chatapp/schema_policy_test.go) and vet analyzer (pkg/analysis/sessionstreamschema, runnable with make schema-vet) reject RegisterEvent, RegisterUIEvent, and RegisterTimelineEntity registrations that use &structpb.Struct{}.

Base chatapp schema

The base chatapp registers these command messages:

StartInferenceCommand carries the prompt text plus repeated ChatAttachment attachments (images referenced by URL, never bytes). A submission may consist of attachments only; Service.SubmitPromptRequest rejects a request only when both the prompt and the attachments are empty. Attachments are echoed in ChatUserMessageAccepted and projected into ChatMessageEntity.attachments, and image attachments are appended to the geppetto user block via session.AppendNewTurnFromUserMessage (see chatapp.AttachmentsToTurnImages). Applications that own an upload endpoint resolve serverkit.SubmitMessageRequest.Attachments (ids) into chatapp.Attachment values; Attachment.Metadata["turn_url"] may override the URL placed into the turn when the runtime resolves images itself.

It registers these backend events and UI events with ChatMessageUpdate payloads:

It registers one base timeline entity kind:

Segment-aware transcript rows

ChatMessageUpdate and ChatMessageEntity include segment metadata:

This is important for tool loops. A single assistant run can produce:

chat-msg-1:thinking:1
chat-msg-1:text:2
ChatToolCall / ChatToolResult rows
chat-msg-1:thinking:3
chat-msg-1:text:4

Timeline stores and Redux reducers upsert by entity ID. Therefore every distinct transcript row must have a distinct messageId. Do not reuse the parent assistant ID for multiple thinking blocks or for multiple interleaved assistant text blocks.

Shared ReasoningPlugin

pkg/chatapp/plugins.NewReasoningPlugin() translates Geppetto reasoning events into chatapp/sessionstream events.

It handles:

• *events.EventThinkingPartial
• *events.EventInfo with thinking-started
• *events.EventInfo with thinking-ended
• reasoning summary info payloads when available

It registers concrete ReasoningUpdate protobuf payloads:

The payload contains chat-message-shaped fields such as messageId, parentMessageId, segment, role: "thinking", chunk, content, status, and streaming. Each contiguous thinking phase gets a segment ID such as chat-msg-5:thinking:1.

Use this shared plugin instead of defining app-local runtime-debug/reasoning projection code.

Shared ToolCallPlugin

pkg/chatapp/plugins.NewToolCallPlugin() translates Geppetto tool lifecycle events into typed protobuf payloads.

It handles:

• *events.EventToolCall
• *events.EventToolCallExecute
• *events.EventToolResult
• *events.EventToolCallExecutionResult

It registers:

It also registers timeline entity kinds:

Use this shared plugin for apps that want durable, hydrated tool-call and tool-result rows. Product-specific tools can still add their own widgets, but they should not duplicate the generic Geppetto tool lifecycle projection.

Wiring pattern

A web-chat style application wires the base schemas and plugins at server assembly time:

import (
    chatapp "github.com/go-go-golems/pinocchio/pkg/chatapp"
    chatplugins "github.com/go-go-golems/pinocchio/pkg/chatapp/plugins"
    sessionstream "github.com/go-go-golems/sessionstream/pkg/sessionstream"
)

reg := sessionstream.NewSchemaRegistry()
chatPlugins := []chatapp.ChatPlugin{
    myAppSpecificPlugin(),
    chatplugins.NewReasoningPlugin(),
    chatplugins.NewToolCallPlugin(),
}

if err := chatapp.RegisterSchemas(reg, chatPlugins...); err != nil {
    return err
}

engine := chatapp.NewEngine(chatapp.WithPlugins(chatPlugins...))

The reference app uses this pattern from cmd/web-chat/main.go and cmd/web-chat/app/server.go. agentmode remains app-owned under cmd/web-chat; reasoning and tool calls are reusable chatapp plugins under pkg/chatapp/plugins.

Frontend implications

The Pinocchio web frontend receives canonical sessionstream frames from /api/chat/ws and maps them into local renderer keys:

• ChatMessage snapshot entities become local message entities.
• thinking rows are represented as message entities with role: "thinking".
• app-specific entities such as AgentMode keep their own renderer path.

Downstream applications may choose different frontend mappings. The stable contract is the sessionstream event/entity name plus the protobuf payload, not the local React component name.

Troubleshooting

See Also

• Webchat Frontend Integration
• Webchat Frontend Architecture
• Building Sessionstream React Chat Apps