Files
pipelines/internal/opencode/chat.go
T
alan 2307d45417 Release native chat runtimes on lifecycle changes
Ensure /new and chat close stop native foreground and background work before changing registry state. Preserve transcripts while surfacing release and recovery cleanup failures instead of reporting false success, with focused adapter and server regressions.
2026-11-11 17:11:40 +00:00

2017 lines
73 KiB
Go

package opencode
import (
"bufio"
"bytes"
"context"
"encoding/json"
"errors"
"fmt"
"io"
"net/url"
"sort"
"strings"
"sync"
"time"
"git.a-wan.net/alan/pipelines/internal/protocol"
)
// ErrPermissionUnsupported reports that the connected OpenCode backend does not
// expose the brokered approval surface. The native v1 serve translation returns
// it; callers treat it as a documented limitation rather than an operational
// failure, so a chat prompt does not emit a permission error frame on a backend
// that cannot answer one.
var ErrPermissionUnsupported = errors.New("OpenCode permission approval is not implemented for the native serve backend")
// Chat is the brokered OpenCode chat adapter (route B in the research): the
// Pipelines server owns the OpenCode endpoint and credentials and turns the v2
// HTTP API into protocol.ChatEventFrame frames. It reuses the owned-endpoint
// semantics and session-id shape of Connection, with its normal 64 KiB / 1 MiB
// call guards. History alone streams/project tool details before decoding; it
// does not introduce a total-history cap or a second credential path.
type Chat struct {
conn *Connection
shellMu sync.Mutex
shells map[string]*ChatStreamState
// shellOwners retains ownership from the last authoritative global shell
// listing so a shell known to belong to another session is rejected before
// its detail or output endpoint is queried.
shellOwners map[string]string
// mu serializes the adapter's HTTP calls. Connection records its last
// operation and status on the shared connection, so two calls must not
// overlap; the permission poller runs alongside the read loop's
// prompt/interrupt/reply calls.
mu sync.Mutex
usageMu sync.Mutex
usageModels map[string]usageModelCache
modeMu sync.Mutex
agents map[string]string
modelMu sync.Mutex
sessionModels map[string]sessionModelCache
// catalog caches /api/model for thinking levels (efforts.go).
catalogMu sync.Mutex
catalog []protocol.ChatModel
catalogAt time.Time
}
// NewChat brokers chat for one owned OpenCode endpoint. The connection must be
// able to reach the /api HTTP surface: an owned serve connection (translated by
// Connection.Call) or a connection that already carries the v2 API URL.
func NewChat(conn *Connection) *Chat { return &Chat{conn: conn} }
// ValidSessionID reports whether id has the OpenCode session-id shape the
// native adapter already accepts. It is the single validation shared by the
// chat adapter and callers that must reject a request before any OpenCode call.
func ValidSessionID(id string) bool { return sessionID.MatchString(id) }
// ValidShellID accepts only the provider's opaque shell-id alphabet. Keeping
// this check shared by the websocket boundary and provider adapter ensures an
// invalid id is rejected before either network call or path construction.
func ValidShellID(id string) bool {
if len(id) <= 3 || len(id) > 128 || !strings.HasPrefix(id, "sh_") {
return false
}
for _, c := range id[3:] {
if (c < 'a' || c > 'z') && (c < 'A' || c > 'Z') && (c < '0' || c > '9') && c != '_' && c != '-' {
return false
}
}
return true
}
// call serializes the adapter's HTTP calls and forwards them through the shared
// Connection, so no second transport is introduced and Connection's recorded
// last operation/status is never written by two goroutines at once.
func (c *Chat) call(ctx context.Context, method, path string, body any) ([]byte, error) {
c.mu.Lock()
defer c.mu.Unlock()
return c.conn.Call(ctx, method, path, body)
}
// Prompt forwards one chat prompt through the existing Call translation
// (authenticated, bounded, directory-scoped). The endpoint returns the inbox
// envelope immediately; the reply arrives on Stream.
func (c *Chat) Prompt(ctx context.Context, id, text string) error {
return c.PromptWithMessageID(ctx, id, text, "")
}
// PromptFile is one local file handed to OpenCode with a prompt. URI is the
// file:// URL the server wrote; Name is the browser's display name.
type PromptFile struct {
URI string
Name string
preparedURI string
}
// NewPreparedPromptFile marks a file written by the server attachment store.
// Only trusted server-side upload preparation should call this constructor;
// browser-provided paths must never be marked as prepared.
func NewPreparedPromptFile(uri, name string) PromptFile {
return PromptFile{URI: uri, Name: name, preparedURI: uri}
}
// ServerPrepared reports whether URI is the unchanged server-prepared reference.
func (f PromptFile) ServerPrepared() bool { return f.URI != "" && f.URI == f.preparedURI }
// PromptWithMessageID forwards the caller's canonical message id to OpenCode.
// OpenCode persists this id in history, which is the only safe bridge between
// the live user echo and an authoritative history page.
func (c *Chat) PromptWithMessageID(ctx context.Context, id, text, messageID string) error {
return c.PromptWithMessageIDFiles(ctx, id, text, messageID, nil)
}
// PromptWithMessageIDFiles is PromptWithMessageID with local file attachments.
// The V2 prompt body accepts a `files` array of {uri,name}; the server writes
// browser bytes to a private temporary file first, because a browser's own file
// reference is not readable by an OpenCode service on another machine.
func (c *Chat) PromptWithMessageIDFiles(ctx context.Context, id, text, messageID string, files []PromptFile) error {
if !sessionID.MatchString(id) {
return fmt.Errorf("invalid OpenCode session id")
}
if strings.TrimSpace(text) == "" {
return fmt.Errorf("empty chat prompt")
}
// The V2 prompt body is {"text": ...}; the native serve translation accepts
// the same "text" field, so one shape works on both backends without a
// second request format.
body := map[string]any{"text": text}
if messageID != "" {
body["id"] = messageID
}
if agent := c.agentFor(id); agent != "" {
body["agent"] = agent
}
if len(files) > 0 {
attachments := make([]map[string]string, 0, len(files))
for _, file := range files {
if strings.TrimSpace(file.URI) == "" {
continue
}
item := map[string]string{"uri": file.URI}
if name := strings.TrimSpace(file.Name); name != "" {
item["name"] = name
}
attachments = append(attachments, item)
}
if len(attachments) > 0 {
body["files"] = attachments
}
}
if evidence, err := c.call(ctx, "post", "/api/session/"+id+"/prompt", body); err != nil {
if reason := strings.TrimSpace(string(evidence)); reason != "" {
if len(reason) > 300 {
reason = reason[:300]
}
return fmt.Errorf("%w: %s", err, reason)
}
return err
}
return nil
}
// Models lists the models the connected endpoint offers for this chat. The
// endpoint returns providers/models for the connection's directory; only enabled,
// non-deprecated entries are exposed, because the picker is a choice the operator
// can actually apply.
func (c *Chat) Models(ctx context.Context, _ string) ([]protocol.ChatModel, error) {
data, err := c.call(ctx, "get", "/api/model", nil)
if err != nil {
return nil, err
}
var envelope struct {
Data []struct {
ModelID string `json:"modelID"`
ProviderID string `json:"providerID"`
Name string `json:"name"`
Enabled bool `json:"enabled"`
Status string `json:"status"`
Variants []struct {
ID string `json:"id"`
} `json:"variants"`
} `json:"data"`
}
if err := json.Unmarshal(data, &envelope); err != nil {
return nil, fmt.Errorf("invalid OpenCode model response")
}
models := make([]protocol.ChatModel, 0, len(envelope.Data))
seen := map[string]bool{}
for _, item := range envelope.Data {
id := strings.TrimSpace(item.ModelID)
provider := strings.TrimSpace(item.ProviderID)
if id == "" || provider == "" || !item.Enabled || strings.EqualFold(item.Status, "deprecated") {
continue
}
key := provider + "\x00" + id
if seen[key] {
continue
}
seen[key] = true
name := strings.TrimSpace(item.Name)
if name == "" {
name = id
}
model := protocol.ChatModel{ID: id, Provider: provider, Name: name}
for _, variant := range item.Variants {
if variant.ID != "" && !protocol.HasChatEffort(model.Efforts, variant.ID) {
model.Efforts = append(model.Efforts, protocol.ChatEffort{ID: variant.ID, Name: protocol.ChatEffortName(variant.ID)})
}
}
models = append(models, model)
}
sort.Slice(models, func(i, j int) bool {
if models[i].Provider != models[j].Provider {
return models[i].Provider < models[j].Provider
}
return strings.ToLower(models[i].Name) < strings.ToLower(models[j].Name)
})
return models, nil
}
// SwitchModel changes the model used by subsequent provider turns. A running
// turn keeps the model it started with; the next prompt uses the new one.
func (c *Chat) SwitchModel(ctx context.Context, id, provider, model string) error {
if !sessionID.MatchString(id) {
return fmt.Errorf("invalid OpenCode session id")
}
provider = strings.TrimSpace(provider)
model = strings.TrimSpace(model)
if provider == "" || model == "" {
return fmt.Errorf("a model and provider are required")
}
body := map[string]any{"model": map[string]string{"id": model, "providerID": provider}}
if evidence, err := c.call(ctx, "post", "/api/session/"+id+"/model", body); err != nil {
if reason := strings.TrimSpace(string(evidence)); reason != "" {
if len(reason) > 300 {
reason = reason[:300]
}
return fmt.Errorf("%w: %s", err, reason)
}
return err
}
c.modelMu.Lock()
delete(c.sessionModels, id)
c.modelMu.Unlock()
return nil
}
// SetInstruction attaches or replaces one durable session instruction entry.
// The experimental instruction surface announces changes at the next step
// boundary, which is exactly what a preloaded behavior brief needs.
func (c *Chat) SetInstruction(ctx context.Context, id, key string, value any) error {
if !sessionID.MatchString(id) {
return fmt.Errorf("invalid OpenCode session id")
}
if key == "" || len(key) > 64 {
return fmt.Errorf("an instruction key is required")
}
for _, r := range key {
if (r < 'a' || r > 'z') && (r < '0' || r > '9') && r != '.' && r != '_' && r != '-' {
return fmt.Errorf("invalid instruction key")
}
}
path := "/api/experimental/session/" + id + "/instructions/entries/" + url.PathEscape(key)
body := map[string]any{"value": value}
if evidence, err := c.call(ctx, "put", path, body); err != nil {
if reason := strings.TrimSpace(string(evidence)); reason != "" {
if len(reason) > 300 {
reason = reason[:300]
}
return fmt.Errorf("%w: %s", err, reason)
}
return err
}
return nil
}
// Answer replies to one OpenCode form. The agent's question tool pauses inside a
// form.created event; replying lets the same turn continue. The answer object is
// keyed by the form field keys, exactly as the OpenCode CLI sends it.
func (c *Chat) Answer(ctx context.Context, request protocol.ChatAnswerRequest) error {
if !sessionID.MatchString(request.SessionID) {
return fmt.Errorf("invalid OpenCode session id")
}
if strings.TrimSpace(request.FormID) == "" {
return fmt.Errorf("a form id is required")
}
if request.Action == "cancel" {
_, err := c.call(ctx, "delete", "/api/session/"+request.SessionID+"/form/"+url.PathEscape(request.FormID), nil)
return err
}
if request.Action != "" && request.Action != "accept" {
return fmt.Errorf("unsupported OpenCode form action")
}
body := map[string]any{"answer": request.Answers}
if request.Answers == nil {
body["answer"] = map[string]any{}
}
if _, err := c.call(ctx, "post", "/api/session/"+request.SessionID+"/form/"+url.PathEscape(request.FormID)+"/reply", body); err != nil {
return err
}
return nil
}
// Interrupt aborts the session's active run, reusing the same translated surface.
func (c *Chat) Interrupt(ctx context.Context, id string) error {
if !sessionID.MatchString(id) {
return fmt.Errorf("invalid OpenCode session id")
}
if _, err := c.call(ctx, "post", "/api/session/"+id+"/interrupt", map[string]any{}); err != nil {
return err
}
return nil
}
// ReleaseSession stops active and background work for an explicit operator
// close or /new without deleting the persisted native conversation. OpenCode
// interrupt only stops the foreground drain; running shells are separate native
// operations and must be terminated individually.
func (c *Chat) ReleaseSession(ctx context.Context, id string) error {
if err := c.Interrupt(ctx, id); err != nil {
return err
}
shells, err := c.Shells(ctx, id)
if err != nil {
return err
}
for _, shell := range shells {
if shell.Status != protocol.ChatShellRunning {
continue
}
if _, err := c.call(ctx, "delete", "/api/shell/"+url.PathEscape(shell.ID), nil); err != nil {
return fmt.Errorf("stop shell %s: %w", shell.ID, err)
}
}
c.ReleaseShells(id)
return nil
}
// Detach is the server-restart shutdown (chatShutdownDetacher). Sessions, turns, questions,
// permissions and shells live in the OpenCode service, not in this adapter, so
// there is nothing to stop: the connection's owner decides whether the service
// itself outlives the server (an attached endpoint and the detached owned chat
// service do; a V1 serve child does not).
func (c *Chat) Detach() {}
// Messages reads one session's stored turns. On the owned serve backend it
// reuses Connection.Messages, including its read-only OutputFormat readback
// fallback, instead of duplicating that path. It maps the verified assistant
// content parts (text | reasoning | tool) onto protocol.ChatMessage.
func (c *Chat) Messages(ctx context.Context, id string, limit int, cursor string) (protocol.ChatHistoryPage, error) {
if !sessionID.MatchString(id) {
return protocol.ChatHistoryPage{}, fmt.Errorf("invalid OpenCode session id")
}
var data []byte
var err error
c.mu.Lock()
defer c.mu.Unlock()
var reader io.Reader
if c.conn.Backend == "v1" {
var body io.ReadCloser
body, err = c.conn.HistoryNative(ctx, "/session/"+id+"/message")
if err == nil {
defer body.Close()
reader = body
} else if c.conn.LastHTTPStatus == 400 {
// Preserve the existing OutputFormat/read-only export recovery on
// native serve. Ordinary history is streamed, never Call-buffered.
data, err = c.conn.Messages(ctx, id)
reader = bytes.NewReader(data)
}
} else {
if limit <= 0 {
limit = 100 // bounded newest-page request, including legacy clients
}
path := "/api/session/" + id + "/message"
values := make([]string, 0, 2)
if limit > 0 {
values = append(values, fmt.Sprintf("limit=%d", limit))
}
if cursor != "" {
values = append(values, "cursor="+url.QueryEscape(cursor))
}
if len(values) > 0 {
path += "?" + strings.Join(values, "&")
}
var body io.ReadCloser
body, err = c.conn.HistoryNative(ctx, path)
if err == nil {
defer body.Close()
reader = body
}
}
if err != nil {
return protocol.ChatHistoryPage{}, err
}
messages, next, descending, err := decodeChatHistoryPage(ctx, id, reader)
if err != nil {
return protocol.ChatHistoryPage{}, err
}
// The verified API returns newest first. The transcript is chronological.
if descending {
for left, right := 0, len(messages)-1; left < right; left, right = left+1, right-1 {
messages[left], messages[right] = messages[right], messages[left]
}
}
return protocol.ChatHistoryPage{Messages: messages, NextCursor: next, HasMore: next != ""}, nil
}
// Sessions lists the OpenCode sessions on the endpoint. On the V2 HTTP API that
// is GET /api/session; the native v1 serve translation maps it to GET /session.
// It reads the list unscoped by the connection's directory (see
// Connection.SessionList): the V2 list is otherwise restricted to the
// connection's own directory, while an operator session may live in any
// directory, and the caller is responsible for restricting the result to the
// operator's recorded sessions. It decodes the verified {"data":[...]} envelope
// (tolerating a bare array like chatMessageRecords), lifts the nested
// location.directory and time{created,updated} into protocol.ChatSession, drops
// records without a valid session id, and orders newest-updated first so the list
// is deterministic.
func (c *Chat) Sessions(ctx context.Context) ([]protocol.ChatSession, error) {
c.mu.Lock()
data, err := c.conn.SessionList(ctx)
c.mu.Unlock()
if err != nil {
return nil, err
}
return decodeChatSessions(data)
}
// Automations reads the documented OpenCode experimental schedule surface. The
// endpoint is session-scoped by query parameter; the decoder still requires an
// exact sessionID match before counting anything. The older serve backend has
// no schedule API, so it reports unavailable without making a guessed request.
func (c *Chat) Automations(ctx context.Context, sessionID string) (protocol.ChatAutomationInfo, error) {
info := protocol.ChatAutomationInfo{SessionID: sessionID, Provider: "opencode"}
if !ValidSessionID(sessionID) {
return info, fmt.Errorf("invalid OpenCode session id")
}
if c == nil || c.conn == nil || c.conn.Backend == "v1" {
info.Status = protocol.ChatAutomationUnavailable
info.Reason = "this OpenCode backend does not expose the experimental schedule read API"
return info, nil
}
readCtx, cancel := context.WithTimeout(ctx, 3*time.Second)
defer cancel()
data, err := c.call(readCtx, "get", "/api/experimental/schedule?sessionID="+url.QueryEscape(sessionID), nil)
if err != nil {
if strings.Contains(err.Error(), "HTTP 404") || strings.Contains(err.Error(), "HTTP 405") {
info.Status = protocol.ChatAutomationUnavailable
info.Reason = "this OpenCode endpoint does not expose the experimental schedule read API"
return info, nil
}
return info, err
}
entries, err := decodeScheduleInfos(data)
if err != nil {
return info, err
}
count := 0
for _, entry := range entries {
if entry.SessionID == sessionID && entry.Status == "active" {
count++
}
}
info.Status = protocol.ChatAutomationSupported
info.ActiveCount = &count
return info, nil
}
type scheduleInfo struct {
SessionID string `json:"sessionID"`
Status string `json:"status"`
}
// decodeScheduleInfos accepts the documented array and the API's common data
// envelope, but rejects null/malformed bodies so a bad response never becomes a
// false empty count.
func decodeScheduleInfos(data []byte) ([]scheduleInfo, error) {
var entries []scheduleInfo
if err := json.Unmarshal(data, &entries); err == nil && entries != nil {
if err := validateScheduleInfos(entries); err != nil {
return nil, err
}
return entries, nil
}
var envelope struct {
Data []scheduleInfo `json:"data"`
}
if err := json.Unmarshal(data, &envelope); err != nil || envelope.Data == nil {
return nil, fmt.Errorf("invalid OpenCode schedule response")
}
if err := validateScheduleInfos(envelope.Data); err != nil {
return nil, err
}
return envelope.Data, nil
}
func validateScheduleInfos(entries []scheduleInfo) error {
for _, entry := range entries {
if entry.SessionID == "" || entry.Status == "" {
return fmt.Errorf("invalid OpenCode schedule response")
}
}
return nil
}
// Create creates one OpenCode session in the given directory, mirroring the
// verified V2 shape POST /api/session {"title":...,"location":{"directory":...}}.
// It deliberately sends no model or permission override here: the endpoint's own
// defaults apply, exactly as the live check creates a session. The created
// session is returned with its directory lifted from location.directory.
// ActivateSkill uses the V2 experimental session skill endpoint. resume=false
// records the skill without starting an artificial turn; the first operator prompt
// is therefore the first model turn and receives the manager instructions.
func (c *Chat) ActivateSkill(ctx context.Context, id, skill string) error {
if !sessionID.MatchString(id) {
return fmt.Errorf("invalid OpenCode session id")
}
if strings.TrimSpace(skill) == "" {
return fmt.Errorf("empty OpenCode skill id")
}
_, err := c.call(ctx, "post", "/api/experimental/session/"+id+"/skill", map[string]any{"id": skill, "resume": false})
return err
}
func (c *Chat) Create(ctx context.Context, title, directory string) (protocol.ChatSession, error) {
body := struct {
Title string `json:"title"`
Location struct {
Directory string `json:"directory"`
} `json:"location"`
}{Title: title}
body.Location.Directory = directory
data, err := c.call(ctx, "post", "/api/session", body)
if err != nil {
return protocol.ChatSession{}, err
}
return decodeChatSession(data)
}
// Session returns the endpoint's own record of one session so a caller can adopt
// an existing session with the directory and title the endpoint reports, never a
// guessed directory. found is false when the endpoint does not list id. It
// reuses Sessions/decodeChatSessions, so no second session decoder or endpoint is
// introduced; it performs at most one bounded endpoint read.
func (c *Chat) Session(ctx context.Context, id string) (protocol.ChatSession, bool, error) {
if !ValidSessionID(id) {
return protocol.ChatSession{}, false, fmt.Errorf("invalid OpenCode session id")
}
sessions, err := c.Sessions(ctx)
if err != nil {
return protocol.ChatSession{}, false, err
}
for _, session := range sessions {
if session.ID == id {
return session, true, nil
}
}
return protocol.ChatSession{}, false, nil
}
// Reply posts a permission decision, mirroring the documented endpoint.
func (c *Chat) Reply(ctx context.Context, request protocol.ChatReplyRequest) error {
if !sessionID.MatchString(request.SessionID) {
return fmt.Errorf("invalid OpenCode session id")
}
if request.RequestID == "" {
return fmt.Errorf("missing permission request id")
}
decision := request.Decision
if decision != protocol.ChatDecisionOnce && decision != protocol.ChatDecisionAlways && decision != protocol.ChatDecisionReject {
return fmt.Errorf("invalid permission decision %q", decision)
}
body := map[string]any{"decision": decision}
if request.Message != "" {
body["message"] = request.Message
}
path := "/api/session/" + request.SessionID + "/permission/" + request.RequestID + "/reply"
if _, err := c.call(ctx, "post", path, body); err != nil {
return err
}
return nil
}
// Permissions lists the session's pending OpenCode approval requests, mirroring
// GET /api/session/{id}/permission. The location-wide endpoint can silently
// miss chats in another directory. Results are still filtered to sessionID;
// a malformed response is an error, never an empty
// success. It reuses Connection.Call so the request keeps the shared bounds,
// auth and translation, and reuses ValidSessionID for the same rejection the
// other chat calls apply.
func (c *Chat) Permissions(ctx context.Context, id string) ([]protocol.ChatPermissionFrame, error) {
if !sessionID.MatchString(id) {
return nil, fmt.Errorf("invalid OpenCode session id")
}
data, err := c.call(ctx, "get", "/api/session/"+id+"/permission", nil)
if err != nil {
return nil, err
}
return decodeChatPermissions(id, data)
}
// nativeChatPermission is one pending approval request matching the V2
// Permission.Request schema verified against the service's /openapi.json: id,
// sessionID, action and resources are required; save, metadata, source and
// message are optional, so the decoder tolerates any of them being absent.
type nativeChatPermission struct {
ID string `json:"id"`
SessionID string `json:"sessionID"`
Action string `json:"action"`
Resources []string `json:"resources"`
Save []string `json:"save"`
Metadata map[string]any `json:"metadata"`
Source *nativeChatPermissionSource `json:"source"`
Message string `json:"message"`
}
// nativeChatPermissionSource is the incoming Permission.Source union; its single
// (tool) member carries type plus the message id and call id (the protocol frame
// renames messageID to message_id).
type nativeChatPermissionSource struct {
Type string `json:"type"`
MessageID string `json:"messageID"`
ID string `json:"id"`
}
// chatEnvelope unwraps the {"data":[...]} envelope the V2 HTTP API returns and
// reports whether the body was that envelope with a non-nil data array; a bare
// array or a malformed body returns ok=false. It is the single envelope rule the
// message and permission decoders share instead of each re-deriving it.
func chatEnvelope[T any](data []byte) ([]T, bool) {
var response struct {
Data []T `json:"data"`
}
if err := json.Unmarshal(data, &response); err != nil || response.Data == nil {
return nil, false
}
return response.Data, true
}
// chatPermissionRecords reads the {"data":[...]} envelope the V2 endpoint
// returns. An unparseable body or a missing data array is an error, never an
// empty list.
func chatPermissionRecords(data []byte) ([]nativeChatPermission, error) {
records, ok := chatEnvelope[nativeChatPermission](data)
if !ok {
return nil, fmt.Errorf("invalid OpenCode permission response")
}
return records, nil
}
// decodeChatPermissions maps the pending-request list onto protocol frames,
// keeping only the requested session's requests (a request with no id cannot be
// answered and is dropped).
func decodeChatPermissions(sessionID string, data []byte) ([]protocol.ChatPermissionFrame, error) {
records, err := chatPermissionRecords(data)
if err != nil {
return nil, err
}
frames := make([]protocol.ChatPermissionFrame, 0, len(records))
for _, record := range records {
if record.SessionID != sessionID || record.ID == "" {
continue
}
frame := protocol.ChatPermissionFrame{
SessionID: sessionID,
RequestID: record.ID,
Action: record.Action,
Resources: record.Resources,
Save: record.Save,
Metadata: record.Metadata,
Message: record.Message,
}
if record.Source != nil {
frame.Source = &protocol.ChatPermissionSource{Type: record.Source.Type, MessageID: record.Source.MessageID, ID: record.Source.ID}
}
frames = append(frames, frame)
}
return frames, nil
}
// Shells reads the endpoint's authoritative shell list and returns only running
// operations whose metadata explicitly names sessionID. The shell API is global;
// filtering locally avoids guessing an unsupported query filter and never assigns
// ownership from a shared working directory. A successful read also seeds the
// stream state used to attribute later shell.exited events, which carry no session.
func (c *Chat) Shells(ctx context.Context, sessionID string) ([]protocol.ChatShell, error) {
if !ValidSessionID(sessionID) {
return nil, fmt.Errorf("invalid OpenCode session id")
}
state, err := c.streamStateContext(ctx, sessionID)
if err != nil {
return nil, err
}
// One read per state; waiting and I/O never hold the event-state mutex.
state.mu.Lock()
if state.readGate == nil {
state.readGate = make(chan struct{}, 1)
}
gate := state.readGate
state.mu.Unlock()
select {
case gate <- struct{}{}:
case <-ctx.Done():
return nil, ctx.Err()
}
defer func() { <-gate }()
state.mu.Lock()
state.readback = &ShellSnapshot{}
state.mu.Unlock()
defer func() { state.mu.Lock(); state.readback = nil; state.mu.Unlock() }()
data, err := c.call(ctx, "get", "/api/shell", nil)
if err != nil {
return nil, err
}
var response struct {
Data []chatShellInfo `json:"data"`
}
if err := json.Unmarshal(data, &response); err != nil || response.Data == nil {
if err := json.Unmarshal(data, &response.Data); err != nil {
return nil, fmt.Errorf("invalid OpenCode shell response")
}
}
c.shellMu.Lock()
if c.shellOwners == nil {
c.shellOwners = make(map[string]string)
}
for _, info := range response.Data {
if ValidShellID(info.ID) && ValidSessionID(info.shellSessionID()) {
c.shellOwners[info.ID] = info.shellSessionID()
}
}
c.shellMu.Unlock()
out := make([]protocol.ChatShell, 0, len(response.Data))
for _, info := range response.Data {
if info.ID == "" || info.shellSessionID() != sessionID || (info.Status != "" && info.Status != protocol.ChatShellRunning && info.Status != protocol.ChatShellExited) {
continue
}
status := info.Status
if status == "" {
status = protocol.ChatShellRunning
}
out = append(out, protocol.ChatShell{ID: info.ID, Status: status, Command: info.Command})
}
state.mu.Lock()
defer state.mu.Unlock()
out, err = state.readback.Merge(out)
if err != nil {
return nil, err
}
if err := ctx.Err(); err != nil {
return nil, err
}
ids := make([]string, 0, len(out))
for _, shell := range out {
ids = append(ids, shell.ID)
}
state.replaceShellsLocked(ids)
return out, nil
}
// ShellOutput validates explicit session metadata from the authoritative detail
// record before reading the selected bounded output page. A shared directory is
// never ownership evidence.
func (c *Chat) ShellOutput(ctx context.Context, query protocol.ChatShellOutputQuery) (protocol.ChatShellOutputPage, error) {
if !ValidSessionID(query.SessionID) || !ValidShellID(query.ShellID) || query.Cursor < 0 || query.Cursor > protocol.ChatShellOutputMaxCursor || query.Limit <= 0 || query.Limit > protocol.ChatShellOutputLimit {
return protocol.ChatShellOutputPage{}, fmt.Errorf("invalid shell output query")
}
c.shellMu.Lock()
owner := c.shellOwners[query.ShellID]
c.shellMu.Unlock()
if owner != "" && owner != query.SessionID {
return protocol.ChatShellOutputPage{}, fmt.Errorf("shell is not available for this session")
}
data, err := c.call(ctx, "get", "/api/shell/"+query.ShellID, nil)
if err != nil {
if c.conn.LastHTTPStatus == 404 {
return protocol.ChatShellOutputPage{Unavailable: true}, nil
}
return protocol.ChatShellOutputPage{}, err
}
var detail struct {
Data chatShellInfo `json:"data"`
}
if err := json.Unmarshal(data, &detail); err != nil || detail.Data.ID != query.ShellID || detail.Data.shellSessionID() != query.SessionID || (detail.Data.Status != "" && detail.Data.Status != protocol.ChatShellRunning && detail.Data.Status != protocol.ChatShellExited) {
return protocol.ChatShellOutputPage{}, fmt.Errorf("shell is not available for this session")
}
shell := protocol.ChatShell{ID: detail.Data.ID, Status: detail.Data.Status, Command: detail.Data.Command, Exit: detail.Data.Exit}
if shell.Status == "" {
shell.Status = protocol.ChatShellRunning
}
path := fmt.Sprintf("/api/shell/%s/output?cursor=%d&limit=%d", query.ShellID, query.Cursor, query.Limit)
data, err = c.call(ctx, "get", path, nil)
if err != nil {
if c.conn.LastHTTPStatus == 404 {
return protocol.ChatShellOutputPage{Shell: shell, Unavailable: true}, nil
}
return protocol.ChatShellOutputPage{}, err
}
var response struct {
Data *struct {
Output *string `json:"output"`
Cursor *int64 `json:"cursor"`
Size *int64 `json:"size"`
Truncated *bool `json:"truncated"`
} `json:"data"`
}
if err := json.Unmarshal(data, &response); err != nil || response.Data == nil || response.Data.Output == nil || response.Data.Cursor == nil || response.Data.Size == nil || response.Data.Truncated == nil || len(*response.Data.Output) > query.Limit || *response.Data.Cursor < query.Cursor || *response.Data.Cursor > protocol.ChatShellOutputMaxCursor || *response.Data.Size < *response.Data.Cursor || *response.Data.Size > protocol.ChatShellOutputMaxCursor || *response.Data.Cursor-query.Cursor != int64(len(*response.Data.Output)) {
return protocol.ChatShellOutputPage{}, fmt.Errorf("invalid OpenCode shell output response")
}
return protocol.ChatShellOutputPage{Shell: shell, Output: *response.Data.Output, Cursor: *response.Data.Cursor, Size: *response.Data.Size, Truncated: *response.Data.Truncated}, nil
}
// streamState returns the session's retained, verified shell identities. It is
// deliberately kept across stream replacement so an exit after reconnect remains
// attributable; Shells reconciles its contents from authoritative readback on
// each attach rather than replacing the pointer a live scanner is using.
func (c *Chat) streamState(sessionID string) *ChatStreamState {
state, _ := c.streamStateContext(context.Background(), sessionID)
return state
}
func (c *Chat) streamStateContext(ctx context.Context, sessionID string) (*ChatStreamState, error) {
c.shellMu.Lock()
defer c.shellMu.Unlock()
if err := ctx.Err(); err != nil {
return nil, err
}
if c.shells == nil {
c.shells = map[string]*ChatStreamState{}
}
state := c.shells[sessionID]
if state == nil {
state = &ChatStreamState{}
c.shells[sessionID] = state
}
return state, nil
}
// ReleaseShells discards verified shell identities after the last room observer
// disconnects. A future attach calls Shells for a fresh authoritative snapshot,
// so this bounds state without attributing a foreign shell during the gap.
func (c *Chat) ReleaseShells(sessionID string) {
if sessionID == "" {
return
}
c.shellMu.Lock()
delete(c.shells, sessionID)
c.shellMu.Unlock()
}
// Stream subscribes to the OpenCode event firehose and invokes emit for every
// frame belonging to sessionID. It reads one bounded SSE frame at a time and
// never polls the per-session message log; the global firehose is the only
// source of token-level deltas on this build. ready, when non-nil, is called
// once the subscription is attached and before the first frame is read, so a
// caller can post its prompt only after the stream is listening (the firehose
// has no replay cursor). Canceling ctx cancels the subscription and returns
// without leaking a connection.
func (c *Chat) Stream(ctx context.Context, id string, ready func(), emit func(protocol.ChatEventFrame) error) error {
if !sessionID.MatchString(id) {
return fmt.Errorf("invalid OpenCode session id")
}
// Pin state before opening/announcing the stream so a canceled scanner
// cannot acquire a replacement room's identity map.
state, err := c.streamStateContext(ctx, id)
if err != nil {
return err
}
body, err := c.conn.EventStream(ctx)
if err != nil {
return err
}
defer body.Close()
defer func() {
state.mu.Lock()
state.Compaction = nil
state.mu.Unlock()
}()
ctx, cancel := context.WithCancel(ctx)
defer cancel()
var delivery sync.Mutex
usageReadbackAvailable := false // protected by delivery, fallback for older API builds
var pendingUsage *protocol.ChatUsage // latest cumulative event, never a sum
state.mu.Lock()
busy := state.Active
state.mu.Unlock()
setBusy := func(value bool) {
busy = value
state.mu.Lock()
state.Active = value
state.usageDirty = true
if !value {
state.Compaction = nil
}
state.mu.Unlock()
}
deliver := func(frame protocol.ChatEventFrame) error {
// Native usage is cumulative but lacks context/model/timing. Coalesce it
// into one complete readback; never erase richer metrics with a partial
// usage event or issue HTTP reads for every token delta.
if frame.Kind == protocol.ChatEventUsage {
state.mu.Lock()
state.usageDirty = true
state.mu.Unlock()
delivery.Lock()
defer delivery.Unlock()
if usageReadbackAvailable {
pendingUsage = frame.Usage
return nil
}
return emit(frame)
}
delivery.Lock()
defer delivery.Unlock()
if frame.Kind == protocol.ChatEventStep || frame.Kind == protocol.ChatEventText || frame.Kind == protocol.ChatEventTool || frame.Kind == protocol.ChatEventReasoning || (frame.Compaction != nil && frame.Compaction.Status == "running") {
setBusy(true)
}
return emit(frame)
}
// Recover a compaction already underway before this SSE attachment. The
// event body is already open, so any concurrent terminal event follows this
// snapshot in the scanner, rather than being lost between read and subscribe.
if compaction := c.readCompaction(ctx, id); compaction != nil {
state.mu.Lock()
state.Compaction = compaction
state.mu.Unlock()
if err := deliver(protocol.ChatEventFrame{SessionID: id, Kind: protocol.ChatEventCompaction, Compaction: compaction}); err != nil {
return err
}
}
// V2 /api/session/active describes foreground drains, not individual
// provider steps. Poll it even after reconnect: a busy drain may have
// started before this SSE subscription. Failed readbacks never imply idle.
watchDone := make(chan struct{})
go func() {
defer close(watchDone)
ticker := time.NewTicker(500 * time.Millisecond)
defer ticker.Stop()
for {
select {
case <-ctx.Done():
return
case <-ticker.C:
}
delivery.Lock()
readCtx, readCancel := context.WithTimeout(ctx, 5*time.Second)
data, err := c.call(readCtx, "get", "/api/session/active", nil)
readCancel()
var emitErr error
var response struct {
Data *map[string]json.RawMessage `json:"data"`
}
if err == nil && json.Unmarshal(data, &response) == nil && response.Data != nil {
_, active := (*response.Data)[id]
if active && !busy {
setBusy(true)
emitErr = emit(protocol.ChatEventFrame{SessionID: id, Kind: protocol.ChatEventStep, Step: &protocol.ChatStep{Status: protocol.ChatStepStarted}})
} else if !active && busy {
setBusy(false)
emitErr = emit(protocol.ChatEventFrame{SessionID: id, Kind: protocol.ChatEventStep, Step: &protocol.ChatStep{Status: protocol.ChatStepEnded}})
}
}
delivery.Unlock()
if emitErr != nil {
cancel()
_ = body.Close()
return
}
}
}()
defer func() { cancel(); <-watchDone }()
usageRefreshGate := make(chan struct{}, 1)
refreshUsage := func() error {
if c.conn.Backend == "v1" {
return nil
}
select {
case usageRefreshGate <- struct{}{}:
defer func() { <-usageRefreshGate }()
default:
return nil
}
readCtx, readCancel := context.WithTimeout(ctx, 5*time.Second)
usage, err := c.Usage(readCtx, id)
readCancel()
if err != nil {
// A failed enrichment read must not lose authoritative native totals.
delivery.Lock()
defer delivery.Unlock()
usageReadbackAvailable = false
if pendingUsage != nil {
usage := pendingUsage
pendingUsage = nil
return emit(protocol.ChatEventFrame{SessionID: id, Kind: protocol.ChatEventUsage, Usage: usage})
}
return nil // unavailable metrics must not break chat
}
delivery.Lock()
defer delivery.Unlock()
usageReadbackAvailable = true
pendingUsage = nil
return emit(protocol.ChatEventFrame{SessionID: id, Kind: protocol.ChatEventUsage, Usage: usage})
}
if err := refreshUsage(); err != nil {
return err
}
usageDone := make(chan struct{})
go func() {
defer close(usageDone)
ticker := time.NewTicker(2 * time.Second)
defer ticker.Stop()
for {
select {
case <-ctx.Done():
return
case <-ticker.C:
}
state.mu.Lock()
refresh := state.usageDirty || state.Active
state.usageDirty = false
state.mu.Unlock()
if refresh {
if err := refreshUsage(); err != nil {
cancel()
_ = body.Close()
return
}
}
}
}()
defer func() { cancel(); <-usageDone }()
if ready != nil {
ready()
}
err = c.scanChatEventsWithState(ctx, body, id, state, deliver)
if ctx.Err() == nil {
state.mu.Lock()
dirty := state.usageDirty
state.mu.Unlock()
if dirty {
if refreshErr := refreshUsage(); refreshErr != nil {
return refreshErr
}
}
}
return err
}
// scanChatEvents turns an SSE body into protocol frames, one bounded frame at a
// time. Heartbeat comments, blank lines and unrelated event types are ignored;
// malformed JSON fails the stream instead of producing a malformed frame. The
// last assistant message id is retained so a later tool/step event that omits it
// still attributes every frame to a stable message.
func (c *Chat) scanChatEvents(ctx context.Context, body io.Reader, sessionID string, emit func(protocol.ChatEventFrame) error) error {
return c.scanChatEventsWithState(ctx, body, sessionID, c.streamState(sessionID), emit)
}
func (c *Chat) scanChatEventsWithState(ctx context.Context, body io.Reader, sessionID string, state *ChatStreamState, emit func(protocol.ChatEventFrame) error) error {
scanner := bufio.NewScanner(body)
scanner.Buffer(make([]byte, 0, 64<<10), MaxResponse)
for scanner.Scan() {
if err := ctx.Err(); err != nil {
return err
}
line := bytes.TrimSpace(scanner.Bytes())
if !bytes.HasPrefix(line, []byte("data:")) {
continue
}
payload := bytes.TrimSpace(line[len("data:"):])
if len(payload) == 0 {
continue
}
var usageTrigger struct {
Type string `json:"type"`
Data struct {
SessionID string `json:"sessionID"`
} `json:"data"`
}
if json.Unmarshal(payload, &usageTrigger) == nil && usageTrigger.Data.SessionID == sessionID {
switch usageTrigger.Type {
case "session.usage.updated", "session.step.ended", "session.step.failed", "session.compaction.ended", "session.compaction.failed", "session.model.selected", "session.moved", "session.execution.succeeded", "session.execution.failed", "session.execution.interrupted":
state.mu.Lock()
state.usageDirty = true
state.mu.Unlock()
}
}
frame, ok, err := NormalizeChatEvent(payload, sessionID, state)
if err != nil {
return err
}
if !ok {
continue
}
if frame.MessageID != "" {
state.setLastMessageID(frame.MessageID)
}
if err := emit(frame); err != nil {
return err
}
}
if err := scanner.Err(); err != nil {
if ctx.Err() != nil {
return ctx.Err()
}
return fmt.Errorf("OpenCode event stream read failed")
}
return ctx.Err()
}
// isChatEventType reports whether t is an event type NormalizeChatEvent
// surfaces. Unknown types are skipped before their data is decoded, so an
// unrelated event whose fields share a name with chatEvent but carry a different
// JSON shape cannot fail the stream.
func isChatEventType(t string) bool {
switch t {
case "session.text.delta", "session.reasoning.delta",
"session.step.started", "session.step.streamed", "session.step.ended",
"session.usage.updated",
"session.compaction.started", "session.compaction.ended", "session.compaction.failed",
"session.tool.input.started", "session.tool.input.ended",
"session.tool.called", "session.tool.progress",
"session.tool.success", "session.tool.failed",
"form.created", "form.replied", "form.cancelled",
"shell.created", "shell.exited":
return true
}
return false
}
// chatFormPayload is the form object nested under form.created. The question
// tool uses metadata.kind == "question"; other forms are surfaced with their own
// kind so the client can decide whether to render them as a question.
type chatFormPayload struct {
ID string `json:"id"`
SessionID string `json:"sessionID"`
Title string `json:"title"`
Metadata map[string]any `json:"metadata"`
Fields []chatFormField `json:"fields"`
}
// Forms recovers pending questions even when their creation event preceded the
// browser connection or the Pipelines process. Session ownership is explicit.
func (c *Chat) Forms(ctx context.Context, id string) ([]protocol.ChatForm, error) {
if !ValidSessionID(id) {
return nil, fmt.Errorf("invalid OpenCode session id")
}
data, err := c.call(ctx, "get", "/api/session/"+id+"/form", nil)
if err != nil {
return nil, err
}
forms, ok := chatEnvelope[chatFormPayload](data)
if !ok {
return nil, fmt.Errorf("invalid OpenCode form response")
}
result := make([]protocol.ChatForm, 0, len(forms))
for _, form := range forms {
if form.ID == "" || form.SessionID != id {
continue
}
frame, valid, err := normalizeFormEvent("form.created", chatEvent{Form: &form}, id, nil)
if err != nil {
return nil, err
}
if valid {
result = append(result, *frame.Form)
}
}
return result, nil
}
type chatFormField struct {
Key string `json:"key"`
Title string `json:"title"`
Description string `json:"description"`
Type string `json:"type"`
Options []chatFormOption `json:"options"`
Custom bool `json:"custom"`
Required bool `json:"required"`
URL string `json:"url"`
Default any `json:"default"`
Minimum any `json:"minimum"`
Maximum any `json:"maximum"`
MinLength *int `json:"minLength"`
MaxLength *int `json:"maxLength"`
MinItems *int `json:"minItems"`
MaxItems *int `json:"maxItems"`
Format string `json:"format"`
Pattern string `json:"pattern"`
Placeholder string `json:"placeholder"`
Hidden bool `json:"hidden"`
When []protocol.ChatFormWhen `json:"when"`
}
type chatFormOption struct {
Value string `json:"value"`
Label string `json:"label"`
Description string `json:"description"`
}
// chatEvent is the subset of the verified firehose envelope this adapter reads:
// {"type":"session.text.delta","data":{...}}. Fields absent from a given event
// stay zero so one struct covers every type.
type chatEvent struct {
SessionID string `json:"sessionID"`
MessageID string `json:"assistantMessageID"`
MessageIDAlt string `json:"messageID"`
Delta string `json:"delta"`
ID string `json:"id"`
Name string `json:"name"`
Text string `json:"text"`
Input json.RawMessage `json:"input"`
Content []protocol.ChatToolContent `json:"content"`
Metadata map[string]any `json:"metadata"`
Error *protocol.ChatError `json:"error"`
Ordinal int `json:"ordinal"`
Index int `json:"index"`
Step int `json:"step"`
InputTokens int `json:"inputTokens"`
OutputTokens int `json:"outputTokens"`
Cost float64 `json:"cost"`
Tokens struct {
Input int `json:"input"`
Output int `json:"output"`
} `json:"tokens"`
// The shell family. shell.created nests the started command under info;
// shell.exited carries the id, the final status and the exit code at the top
// level. Exit is a pointer so an exit of 0 is distinguishable from absent.
Status string `json:"status"`
Exit *int `json:"exit"`
Info *chatShellInfo `json:"info"`
// Form is the nested form.created payload; FormID is the bare id on
// form.replied/form.cancelled.
Form *chatFormPayload `json:"form"`
}
// chatShellInfo is the Shell.Info envelope a shell.created event nests under
// "info". The session that started the shell is reported in metadata.sessionID
// (the agent's shell tool sets it); only the fields the protocol surfaces are
// read, and the shell's cwd/file are deliberately not carried so no path or
// credential leaks into a frame.
type chatShellInfo struct {
ID string `json:"id"`
Status string `json:"status"`
Command string `json:"command"`
Exit *int `json:"exit"`
Metadata map[string]any `json:"metadata"`
}
// shellSessionID reads the session that started a shell from the created event's
// metadata, or "" when the event carries none. The agent's shell tool sets
// metadata.sessionID; a shell started by anything else is unattributed and is
// ignored, so a shell that cannot be shown to belong to this session never
// becomes one of its frames.
func (i *chatShellInfo) shellSessionID() string {
if i == nil || i.Metadata == nil {
return ""
}
id, _ := i.Metadata["sessionID"].(string)
return id
}
// ChatStreamState is the per-session memory one event stream folds across its
// frames, so a frame that omits context can still be attributed. It is the
// single state NormalizeChatEvent reads and writes; a caller that maps a lone
// event passes an empty state (or nil when it needs no attribution).
//
// - LastMessageID is the most recent assistant message id, so a later tool or
// step event that omits it still attributes every frame to a stable message.
// - Shells holds the ids of the shells this session has started and not yet
// seen exit. shell.exited carries no session id, so the id remembered here is
// what attributes the exit to its session: another session's shell is an
// unknown id and is ignored.
// - Forms maps a pending form id to its session, so form.replied/cancelled
// (which carry no session) can be attributed to the right chat.
type ChatStreamState struct {
Compaction *protocol.ChatCompaction
mu sync.Mutex
Active bool // last observed foreground drain, retained across SSE reconnects
LastMessageID string
Shells map[string]struct{}
Forms map[string]string
readGate chan struct{}
readback *ShellSnapshot
usageDirty bool
}
func (s *ChatStreamState) lastMessageID() string {
if s == nil {
return ""
}
s.mu.Lock()
defer s.mu.Unlock()
return s.LastMessageID
}
func (s *ChatStreamState) setLastMessageID(id string) {
if s == nil || id == "" {
return
}
s.mu.Lock()
s.LastMessageID = id
s.mu.Unlock()
}
// knowsShell reports whether id is a shell this stream has already surfaced for
// the session, and so is one this stream may now report the exit of.
func (s *ChatStreamState) knowsShell(id string) bool {
if s == nil || id == "" {
return false
}
s.mu.Lock()
defer s.mu.Unlock()
_, ok := s.Shells[id]
return ok
}
// markShell remembers id as a shell of this session.
func (s *ChatStreamState) markShell(id string) {
if s == nil || id == "" {
return
}
s.mu.Lock()
defer s.mu.Unlock()
if s.Shells == nil {
s.Shells = map[string]struct{}{}
}
s.Shells[id] = struct{}{}
}
// forgetShell drops id once its exit has been surfaced.
func (s *ChatStreamState) forgetShell(id string) {
if s == nil {
return
}
s.mu.Lock()
defer s.mu.Unlock()
if s.Shells == nil {
return
}
delete(s.Shells, id)
}
// replaceShells applies one authoritative running-shell snapshot without
// replacing the state object an already attached event scanner owns.
func (s *ChatStreamState) replaceShells(ids []string) {
if s == nil {
return
}
s.mu.Lock()
defer s.mu.Unlock()
s.replaceShellsLocked(ids)
}
func (s *ChatStreamState) replaceShellsLocked(ids []string) {
s.Shells = make(map[string]struct{}, len(ids))
for _, id := range ids {
if id != "" {
s.Shells[id] = struct{}{}
}
}
}
// NormalizeChatEvent maps one OpenCode firehose `data:` payload to a
// protocol.ChatEventFrame, folding the small per-session context ([stream]) it
// needs across frames. ok is false for an event type this adapter does not
// surface or one belonging to a different session, so the caller can skip it
// without emitting a frame. Malformed JSON returns an error and never a frame.
// stream may be nil when the caller maps a lone event and needs no attribution;
// a nil stream simply means no inherited message id and no remembered shell.
func NormalizeChatEvent(payload []byte, sessionID string, stream *ChatStreamState) (protocol.ChatEventFrame, bool, error) {
var outer struct {
Type string `json:"type"`
Data json.RawMessage `json:"data"`
}
if err := json.Unmarshal(payload, &outer); err != nil {
return protocol.ChatEventFrame{}, false, fmt.Errorf("malformed OpenCode event: %w", err)
}
if outer.Type == "" || len(outer.Data) == 0 {
return protocol.ChatEventFrame{}, false, nil
}
// Only decode the data of event types this adapter surfaces. The firehose
// also carries unrelated session events whose fields collide with chatEvent
// but have a different JSON shape (session.instructions.updated carries
// "delta" as an object), so decoding every event would fail the stream on an
// event that is not a chat frame at all.
if !isChatEventType(outer.Type) {
return protocol.ChatEventFrame{}, false, nil
}
var data chatEvent
if err := json.Unmarshal(outer.Data, &data); err != nil {
return protocol.ChatEventFrame{}, false, fmt.Errorf("malformed OpenCode event data: %w", err)
}
// The shell events are location-scoped, not session-scoped: the session that
// started a shell is reported in the created event's metadata, and the exit
// names no session at all, so it is attributed through the ids this stream
// already surfaced. They are mapped before the session check the other events
// use, which their absent data.sessionID could never pass.
if outer.Type == "shell.created" || outer.Type == "shell.exited" {
return normalizeShellEvent(outer.Type, data, sessionID, stream)
}
if strings.HasPrefix(outer.Type, "form.") {
return normalizeFormEvent(outer.Type, data, sessionID, stream)
}
if data.SessionID != sessionID {
return protocol.ChatEventFrame{}, false, nil
}
// Verified V2 SessionEvent.Compaction schema (upstream 3fdb13bc):
// only sessionID is shared across started/ended/failed; no message id.
if strings.HasPrefix(outer.Type, "session.compaction.") {
status := "running"
if outer.Type == "session.compaction.ended" {
status = "completed"
}
if outer.Type == "session.compaction.failed" {
status = "failed"
}
compaction := &protocol.ChatCompaction{Status: status}
if stream != nil {
stream.mu.Lock()
stream.Compaction = nil
if status == "running" {
stream.Compaction = compaction
}
stream.mu.Unlock()
}
return protocol.ChatEventFrame{SessionID: sessionID, Kind: protocol.ChatEventCompaction, Compaction: compaction}, true, nil
}
messageID := data.MessageID
if messageID == "" {
messageID = data.MessageIDAlt
}
if messageID == "" && stream != nil {
messageID = stream.lastMessageID()
}
// Usage is session state; native V2 UsageUpdated has no message id. Other
// message frames still require a stable id for transcript attribution.
if messageID == "" && outer.Type != "session.usage.updated" {
return protocol.ChatEventFrame{}, false, nil
}
frame := protocol.ChatEventFrame{SessionID: sessionID, MessageID: messageID}
switch {
case outer.Type == "session.text.delta":
frame.Kind = protocol.ChatEventText
frame.Delta = data.Delta
frame.Part = &protocol.ChatPart{Type: protocol.ChatPartText, ID: protocol.ChatDeltaPartID(messageID, protocol.ChatPartText, data.Ordinal)}
case outer.Type == "session.reasoning.delta":
frame.Kind = protocol.ChatEventReasoning
frame.Delta = data.Delta
frame.Part = &protocol.ChatPart{Type: protocol.ChatPartReasoning, ID: protocol.ChatDeltaPartID(messageID, protocol.ChatPartReasoning, data.Ordinal)}
case outer.Type == "session.step.started" || outer.Type == "session.step.streamed" || outer.Type == "session.step.ended":
frame.Kind = protocol.ChatEventStep
frame.Step = &protocol.ChatStep{Status: strings.TrimPrefix(outer.Type, "session.step."), Index: stepIndex(data), Intermediate: outer.Type == "session.step.ended"}
case strings.HasPrefix(outer.Type, "session.tool."):
status, ok := toolStatus(outer.Type)
if !ok {
return protocol.ChatEventFrame{}, false, nil
}
frame.Kind = protocol.ChatEventTool
state := &protocol.ChatToolState{Status: status, Input: toolInput(data), Content: data.Content, Metadata: data.Metadata, Error: data.Error}
frame.Part = &protocol.ChatPart{Type: protocol.ChatPartTool, ID: data.ID, Name: data.Name, State: state}
case outer.Type == "session.usage.updated":
frame.Kind = protocol.ChatEventUsage
frame.Usage = decodeUsageSnapshot(outer.Data)
default:
return protocol.ChatEventFrame{}, false, nil
}
return frame, true, nil
}
// normalizeFormEvent maps one form.created / form.replied / form.cancelled
// payload onto a ChatEventForm frame. Form.created carries its own session; the
// terminal events carry only an id, so the stream remembers which session owns
// each pending form. A form from another session is ignored, and an unknown
// terminal id is another session's form rather than a malformed frame.
func normalizeFormEvent(eventType string, data chatEvent, sessionID string, stream *ChatStreamState) (protocol.ChatEventFrame, bool, error) {
if eventType == "form.created" {
form := data.Form
if form == nil || form.ID == "" {
return protocol.ChatEventFrame{}, false, fmt.Errorf("malformed OpenCode form.created event")
}
if form.SessionID != "" && form.SessionID != sessionID {
return protocol.ChatEventFrame{}, false, nil
}
kind := ""
if form.Metadata != nil {
kind, _ = form.Metadata["kind"].(string)
}
frame := protocol.ChatForm{
ID: form.ID,
SessionID: sessionID,
Title: form.Title,
Kind: kind,
Actions: []string{"accept", "cancel"},
}
for _, field := range form.Fields {
out := protocol.ChatFormField{
Key: field.Key,
Title: field.Title,
Description: field.Description,
Type: field.Type,
Custom: field.Custom,
Required: field.Required,
URL: field.URL, Default: field.Default, Minimum: field.Minimum, Maximum: field.Maximum,
MinLength: field.MinLength, MaxLength: field.MaxLength, MinItems: field.MinItems, MaxItems: field.MaxItems,
Format: field.Format, Pattern: field.Pattern, Placeholder: field.Placeholder, Hidden: field.Hidden, When: field.When,
}
for _, option := range field.Options {
value := option.Value
if value == "" {
value = option.Label
}
out.Options = append(out.Options, protocol.ChatFormOption{
Value: value, Label: option.Label, Description: option.Description,
})
}
frame.Fields = append(frame.Fields, out)
}
if stream != nil {
stream.mu.Lock()
if stream.Forms == nil {
stream.Forms = map[string]string{}
}
stream.Forms[form.ID] = sessionID
stream.mu.Unlock()
}
return protocol.ChatEventFrame{SessionID: sessionID, Kind: protocol.ChatEventForm, Form: &frame}, true, nil
}
id := data.ID
if id == "" && data.Form != nil {
id = data.Form.ID
}
if id == "" {
return protocol.ChatEventFrame{}, false, fmt.Errorf("malformed OpenCode %s event", eventType)
}
if stream == nil {
return protocol.ChatEventFrame{}, false, nil
}
stream.mu.Lock()
owner, known := stream.Forms[id]
if known && owner == sessionID {
delete(stream.Forms, id)
}
stream.mu.Unlock()
if !known || owner != sessionID {
return protocol.ChatEventFrame{}, false, nil
}
form := &protocol.ChatForm{ID: id, SessionID: sessionID}
if eventType == "form.cancelled" {
form.Cancelled = true
} else {
form.Resolved = true
}
return protocol.ChatEventFrame{SessionID: sessionID, Kind: protocol.ChatEventForm, Form: form}, true, nil
}
// normalizeShellEvent maps one shell.created/shell.exited payload onto a
// protocol.ChatEventShell frame. A shell belongs to the session whose id the
// created event carries in info.metadata.sessionID, so a shell started by any
// other session is ignored (ok=false) rather than shown in this session. The
// exit event carries no session at all, so it is emitted only for a shell id
// this stream already surfaced for the session; any other id is another
// session's and is ignored. An event that carries no shell id at all cannot be
// keyed by the client and is malformed, so it fails the stream instead of
// producing a frame the client cannot attribute.
func normalizeShellEvent(eventType string, data chatEvent, sessionID string, stream *ChatStreamState) (protocol.ChatEventFrame, bool, error) {
if eventType == "shell.created" {
if data.Info == nil || data.Info.ID == "" {
return protocol.ChatEventFrame{}, false, fmt.Errorf("malformed OpenCode shell.created event")
}
if data.Info.shellSessionID() != sessionID {
return protocol.ChatEventFrame{}, false, nil
}
status := data.Info.Status
if status == "" {
status = protocol.ChatShellRunning
}
shell := &protocol.ChatShell{ID: data.Info.ID, Status: status, Command: data.Info.Command}
if stream != nil {
stream.mu.Lock()
stream.readback.Record(shell)
if stream.Shells == nil {
stream.Shells = map[string]struct{}{}
}
if status == protocol.ChatShellRunning && len(stream.Shells) < chatShellIdentityLimit {
stream.Shells[shell.ID] = struct{}{}
}
stream.mu.Unlock()
}
return protocol.ChatEventFrame{
SessionID: sessionID,
Kind: protocol.ChatEventShell,
Shell: shell,
}, true, nil
}
if data.ID == "" {
return protocol.ChatEventFrame{}, false, fmt.Errorf("malformed OpenCode shell.exited event")
}
if stream == nil {
return protocol.ChatEventFrame{}, false, nil
}
stream.mu.Lock()
stream.readback.Record(&protocol.ChatShell{ID: data.ID, Status: protocol.ChatShellExited})
_, known := stream.Shells[data.ID]
delete(stream.Shells, data.ID)
stream.mu.Unlock()
if !known {
return protocol.ChatEventFrame{}, false, nil
}
status := data.Status
if status == "" {
status = protocol.ChatShellExited
}
return protocol.ChatEventFrame{
SessionID: sessionID,
Kind: protocol.ChatEventShell,
Shell: &protocol.ChatShell{ID: data.ID, Status: status, Exit: data.Exit},
}, true, nil
}
// toolInput picks a tool call's arguments from whichever frame carries them:
// session.tool.called carries the parsed `input` object, session.tool.input.ended
// carries the same arguments as a `text` JSON string, and progress/success carry
// neither. Text that already parses as JSON is kept as that value (so an object
// pretty-prints); a partial string is carried as a JSON string so the frame stays
// valid and the client can show it while streaming. It returns nil when the frame
// carries no arguments, so the consumer retains what it already learned.
func toolInput(data chatEvent) json.RawMessage {
if len(data.Input) > 0 && string(data.Input) != "null" {
return data.Input
}
text := strings.TrimSpace(data.Text)
if text == "" {
return nil
}
if json.Valid([]byte(text)) {
return json.RawMessage(text)
}
encoded, err := json.Marshal(text)
if err != nil {
return nil
}
return encoded
}
// toolStatus maps the verified tool event types onto the ToolState lifecycle.
func toolStatus(eventType string) (string, bool) {
switch eventType {
case "session.tool.input.started", "session.tool.input.ended":
return protocol.ChatToolStreaming, true
case "session.tool.called", "session.tool.progress":
return protocol.ChatToolRunning, true
case "session.tool.success":
return protocol.ChatToolCompleted, true
case "session.tool.failed":
return protocol.ChatToolError, true
}
return "", false
}
func stepIndex(data chatEvent) int {
if data.Step > 0 {
return data.Step
}
return data.Index
}
// nativeChatMessage is one stored turn. The two surfaces return different
// envelopes for the same session and both decode into this one struct, so the
// mapping below reads whichever fields a record populated:
//
// - the V2 HTTP API (GET /api/session/{id}/message) puts id/type/agent/model,
// the timing and the parts array at the message top level, with the parts
// under "content" and a user turn's text as a bare string;
// - the native serve readback nests the same fields under "info" (role as
// "role", model as "modelID", timing as "created") with the parts under
// "parts".
type nativeChatMessage struct {
Raw json.RawMessage `json:"-"`
ID string `json:"id"`
Type string `json:"type"`
Agent string `json:"agent"`
Model nativeChatModel `json:"model"`
Time *protocol.ChatTime `json:"time"`
Text string `json:"text"`
Content []nativeChatPart `json:"content"`
Info struct {
ID string `json:"id"`
Role string `json:"role"`
ModelID string `json:"modelID"`
Agent string `json:"agent"`
CreatedAt int64 `json:"created"`
} `json:"info"`
Parts []nativeChatPart `json:"parts"`
// Files are the V2 user turn's attached files. They live on the message
// envelope (not in Parts), with an inline data field the history mapper must
// not expose.
Files []nativeChatFile `json:"files"`
}
type nativeChatFile struct {
Data string `json:"data"`
Mime string `json:"mime"`
Name string `json:"name"`
Source struct {
Type string `json:"type"`
URI string `json:"uri"`
} `json:"source"`
}
// nativeChatModel is the nested Model.Ref a V2 turn carries ({id, providerID,
// variant}); only the model id is surfaced in the protocol message.
type nativeChatModel struct {
ID string `json:"id"`
ProviderID string `json:"providerID"`
// Variant is the session model's chosen variant (its thinking level).
Variant string `json:"variant"`
}
// nativeChatPart is one content element shared by both message envelopes. Raw
// keeps the element's original JSON so the session exporter can render an
// unrecognised part type (file, patch, step, ...) instead of dropping it; it is
// ignored when a part is re-encoded.
type nativeChatPart struct {
Type string `json:"type"`
ID string `json:"id"`
Text string `json:"text"`
Name string `json:"name"`
URI string `json:"uri"`
Mime string `json:"mime"`
Executed bool `json:"executed"`
State *protocol.ChatToolState `json:"state"`
Time *protocol.ChatTime `json:"time"`
Raw json.RawMessage `json:"-"`
}
// UnmarshalJSON decodes one content part and retains its raw JSON alongside the
// decoded fields, so a part type the decoder does not model is still available
// verbatim to the session exporter.
func (p *nativeChatPart) UnmarshalJSON(data []byte) error {
type part nativeChatPart
var decoded part
if err := json.Unmarshal(data, &decoded); err != nil {
return err
}
*p = nativeChatPart(decoded)
p.Raw = append(p.Raw[:0], data...)
return nil
}
// role, parts and the accessor methods below read the V2 top-level fields first
// and fall back to the native serve "info"/"parts" fields, so one record maps
// regardless of which surface produced it.
func (m nativeChatMessage) role() string {
if m.Info.Role != "" {
return m.Info.Role
}
return m.Type
}
func (m nativeChatMessage) messageID() string {
if m.Info.ID != "" {
return m.Info.ID
}
return m.ID
}
func (m nativeChatMessage) modelID() string {
if m.Info.ModelID != "" {
return m.Info.ModelID
}
return m.Model.ID
}
func (m nativeChatMessage) agent() string {
if m.Info.Agent != "" {
return m.Info.Agent
}
return m.Agent
}
func (m nativeChatMessage) createdAt() int64 {
if m.Info.CreatedAt != 0 {
return m.Info.CreatedAt
}
if m.Time != nil {
return m.Time.Created
}
return 0
}
func (m nativeChatMessage) contentParts() []nativeChatPart {
if m.Parts != nil {
return m.Parts
}
return m.Content
}
// chatMessageRecords accepts both message envelopes the two surfaces return:
// the V2 HTTP API wraps them in {"data":[...]} while the native serve readback
// returns a bare array. An unrecognised body is an error, never empty history.
func chatMessageRecords(data []byte) ([]nativeChatMessage, error) {
if records, ok := chatEnvelope[nativeChatMessage](data); ok {
return records, nil
}
var records []nativeChatMessage
if err := json.Unmarshal(data, &records); err != nil {
return nil, fmt.Errorf("invalid OpenCode message response")
}
return records, nil
}
func decodeChatMessages(sessionID string, data []byte) ([]protocol.ChatMessage, error) {
records, err := chatMessageRecords(data)
if err != nil {
return nil, err
}
return mapChatMessages(sessionID, records), nil
}
func mapChatMessages(sessionID string, records []nativeChatMessage) []protocol.ChatMessage {
messages := make([]protocol.ChatMessage, 0, len(records))
for _, record := range records {
role := record.role()
if role != protocol.ChatRoleUser && role != protocol.ChatRoleAssistant {
continue
}
out := protocol.ChatMessage{ID: record.messageID(), SessionID: sessionID, Role: role, Model: record.modelID(), Agent: record.agent(), CreatedAt: record.createdAt()}
for _, part := range record.contentParts() {
switch part.Type {
case protocol.ChatPartText, protocol.ChatPartReasoning:
out.Parts = append(out.Parts, protocol.ChatPart{Type: part.Type, ID: part.ID, Text: part.Text})
case protocol.ChatPartTool:
out.Parts = append(out.Parts, protocol.ChatPart{Type: protocol.ChatPartTool, ID: part.ID, Name: part.Name, Executed: part.Executed, State: part.State, Time: part.Time})
case protocol.ChatPartFile:
if part.URI == "" && part.Name == "" {
continue
}
out.Parts = append(out.Parts, protocol.ChatPart{Type: protocol.ChatPartFile, Name: part.Name, URI: part.URI, Mime: part.Mime})
}
}
// A V2 user turn carries its prompt text as a message-level string rather
// than a content array, so surface it as the turn's single text part.
if len(out.Parts) == 0 && role == protocol.ChatRoleUser && record.Text != "" {
out.Parts = append(out.Parts, protocol.ChatPart{Type: protocol.ChatPartText, Text: record.Text})
}
// Attached files are top-level on the user envelope. Keep their name,
// MIME and file URI for the transcript; never copy the base64 data into
// history.
for _, file := range record.Files {
uri := file.Source.URI
if uri == "" {
continue
}
out.Parts = append(out.Parts, protocol.ChatPart{
Type: protocol.ChatPartFile,
Name: file.Name,
URI: uri,
Mime: file.Mime,
})
}
messages = append(messages, out)
}
return messages
}
// decodeChatHistoryPage reads the V2 cursor envelope while retaining the older
// bare-array decoder for native serve. Tool output is intentionally previewed:
// one command's unbounded stdout must not make the entire transcript or its final
// answer unavailable over the websocket.
func decodeChatHistoryPage(ctx context.Context, sessionID string, reader io.Reader) ([]protocol.ChatMessage, string, bool, error) {
return readHistoryPage(ctx, sessionID, reader)
}
const historyToolPreviewBytes = 64 << 10
// nativeChatSession is one listed session in the verified V2 shape
// ({id,title,agent,model,cost,tokens,outcome,time,title,location.directory,
// parentID,permissions}); only the fields the protocol surfaces are read. The
// native v1 serve readback of the same list is not covered by the research, so
// its records decode through the same tolerant envelope but any additional
// nesting is not asserted.
type nativeChatSession struct {
ID string `json:"id"`
Title string `json:"title"`
Agent string `json:"agent"`
Model nativeChatModel `json:"model"`
ParentID string `json:"parentID"`
Location struct {
Directory string `json:"directory"`
} `json:"location"`
Time struct {
Created int64 `json:"created"`
Updated int64 `json:"updated"`
} `json:"time"`
}
// chatSessionRecords accepts both session-list envelopes: the V2 HTTP API wraps
// them in {"data":[...]} while the native serve readback returns a bare array.
// An unrecognised body is an error, never an empty list.
func chatSessionRecords(data []byte) ([]nativeChatSession, error) {
if records, ok := chatEnvelope[nativeChatSession](data); ok {
return records, nil
}
var records []nativeChatSession
if err := json.Unmarshal(data, &records); err != nil {
return nil, fmt.Errorf("invalid OpenCode session response")
}
return records, nil
}
// chatSessionRecord reads one created session, accepting the {"data":{...}}
// envelope the V2 API returns and tolerating a bare object. An unrecognised body
// is an error, never an empty session.
func chatSessionRecord(data []byte) (nativeChatSession, error) {
var response struct {
Data *nativeChatSession `json:"data"`
}
if err := json.Unmarshal(data, &response); err == nil && response.Data != nil {
return *response.Data, nil
}
var record nativeChatSession
if err := json.Unmarshal(data, &record); err != nil || record.ID == "" {
return nativeChatSession{}, fmt.Errorf("invalid OpenCode session response")
}
return record, nil
}
// chatSessionFields lifts the nested location.directory and time{created,updated}
// of one native session record onto protocol.ChatSession. It is the single field
// mapping shared by the list decoder and Create, so the two cannot drift.
func chatSessionFields(record nativeChatSession) protocol.ChatSession {
return protocol.ChatSession{
ID: record.ID,
Title: record.Title,
Agent: record.Agent,
Model: record.Model.ID,
ModelProvider: record.Model.ProviderID,
Effort: record.Model.Variant,
Directory: record.Location.Directory,
ParentID: record.ParentID,
CreatedAt: record.Time.Created,
UpdatedAt: record.Time.Updated,
}
}
// decodeChatSessions maps the listed sessions onto protocol.ChatSession, dropping
// every record whose id is not a valid OpenCode session id (an empty or foreign
// id cannot be addressed) and ordering by UpdatedAt then id so the result is
// deterministic.
func decodeChatSessions(data []byte) ([]protocol.ChatSession, error) {
records, err := chatSessionRecords(data)
if err != nil {
return nil, err
}
sessions := make([]protocol.ChatSession, 0, len(records))
for _, record := range records {
if !sessionID.MatchString(record.ID) {
continue
}
sessions = append(sessions, chatSessionFields(record))
}
sort.SliceStable(sessions, func(i, j int) bool {
if sessions[i].UpdatedAt != sessions[j].UpdatedAt {
return sessions[i].UpdatedAt > sessions[j].UpdatedAt
}
return sessions[i].ID < sessions[j].ID
})
return sessions, nil
}
// decodeChatSession maps one created session, rejecting an empty or foreign id
// (an unaddressable session is an error, never a silent success).
func decodeChatSession(data []byte) (protocol.ChatSession, error) {
record, err := chatSessionRecord(data)
if err != nil {
return protocol.ChatSession{}, err
}
if !sessionID.MatchString(record.ID) {
return protocol.ChatSession{}, fmt.Errorf("invalid OpenCode session response")
}
return chatSessionFields(record), nil
}
// ProbeTurn reports whether OpenCode is running a turn for the session, read
// from the same /api/session/active list Stream polls. The server uses it once
// at start to resume observing turns a previous process left running. A failed
// read is an error, never "idle".
func (c *Chat) ProbeTurn(ctx context.Context, id string) (bool, error) {
if !sessionID.MatchString(id) {
return false, fmt.Errorf("invalid OpenCode session id")
}
data, err := c.call(ctx, "get", "/api/session/active", nil)
if err != nil {
return false, err
}
var response struct {
Data *map[string]json.RawMessage `json:"data"`
}
if err := json.Unmarshal(data, &response); err != nil || response.Data == nil {
return false, fmt.Errorf("invalid OpenCode active-session readback")
}
_, active := (*response.Data)[id]
return active, nil
}