chat: separate create operation identity

Use an explicit chat_create operation_id as the durable bootstrap key while retaining envelope IDs for reply correlation. Legacy requests receive fresh server-scoped identities, so independent cli-1/android-1 requests do not collide; clients that retry retain one operation_id.

Update Android creation state and repository calls to preserve an operation identity across retries, and cover durable reconnect retries, duplicate barriers, changed input, legacy correlation reuse, and protocol serialization.

Checked packaged templates: none describe chat_create. Checked packaged authoring-skill references: the existing description is stale, but shared references and README must not be edited by an item; docs/notes/bootstrap-create-identity.md records the required docs-fold update and rollout compatibility.
This commit is contained in:
2026-10-18 16:50:12 +01:00
parent 134bd0611a
commit 5946f1abc8
14 changed files with 203 additions and 46 deletions
@@ -287,11 +287,15 @@ class PipelinesRepository(
* The server reports its own error when it does not broker creation; the
* caller surfaces that message rather than guessing at a session id.
*/
suspend fun chatCreate(title: String, directory: String): ChatSession {
suspend fun chatCreate(
title: String,
directory: String,
operationId: String = newChatCreateOperationId(),
): ChatSession {
val response = client.call(
Message(
type = Protocol.CHAT_CREATE,
chatCreate = ChatCreateRequest(title = title, directory = directory),
chatCreate = ChatCreateRequest(title = title, directory = directory, operationId = operationId),
),
)
return response.chatSession
@@ -383,5 +387,8 @@ class PipelinesRepository(
* the same start intent so the server can dedupe idempotent repeats.
*/
fun newRequestKey(): String = "android-" + UUID.randomUUID().toString()
/** A durable key for one chat-create intent; retain it when retrying. */
fun newChatCreateOperationId(): String = "android-chat-" + UUID.randomUUID().toString()
}
}
@@ -59,6 +59,7 @@ data class ChatCloseResult(
data class ChatCreateRequest(
val title: String = "",
val directory: String = "",
@SerialName("operation_id") val operationId: String = "",
)
/** The session-scoped request body for chat_messages and chat_interrupt. */
@@ -1055,7 +1055,7 @@ class AppViewModel(
* create a session wherever the server happens to be.
*/
fun startNewChat() {
chatStore.createOpened()
chatStore.createOpened(PipelinesRepository.newChatCreateOperationId())
refreshChatDirectories()
}
@@ -1076,7 +1076,11 @@ class AppViewModel(
chatStore.creating()
viewModelScope.launch {
try {
val created = repository.chatCreate(title = "New chat", directory = create.directory)
val created = repository.chatCreate(
title = "New chat",
directory = create.directory,
operationId = create.operationId,
)
chatStore.createSucceeded(created)
chatStore.history(created.id, emptyList())
} catch (t: Throwable) {
@@ -224,6 +224,8 @@ data class ChatThread(
*/
data class ChatCreateState(
val directory: String = HOME_DIRECTORY,
/** Durable identity for this one create intent; retained when the request is retried. */
val operationId: String,
val creating: Boolean = false,
val error: String? = null,
)
@@ -461,8 +463,8 @@ class ChatStore(
}
/** Opens the directory picker on its default (the operator's home). */
fun createOpened() {
_state.value = _state.value.copy(create = ChatCreateState())
fun createOpened(operationId: String) {
_state.value = _state.value.copy(create = ChatCreateState(operationId = operationId))
}
/** Picks a directory in the picker; the home stays the default until this is called. */
@@ -0,0 +1,26 @@
package net.awan.pipelines.data
import net.awan.pipelines.data.protocol.ChatCreateRequest
import net.awan.pipelines.data.protocol.Message
import net.awan.pipelines.data.protocol.PipelinesJson
import net.awan.pipelines.data.protocol.Protocol
import org.junit.Assert.assertEquals
import org.junit.Assert.assertNotEquals
import org.junit.Test
class ChatCreateIdentityTest {
@Test
fun aRetriedCreateKeepsItsDurableIdentityWhileNewCreatesDoNotReuseIt() {
val operationId = PipelinesRepository.newChatCreateOperationId()
val retry = Message(
type = Protocol.CHAT_CREATE,
id = "android-2", // Transport correlation may change after reconnect.
chatCreate = ChatCreateRequest(title = "New chat", directory = "/work", operationId = operationId),
)
val decoded = PipelinesJson.decodeFromString(Message.serializer(), PipelinesJson.encodeToString(Message.serializer(), retry))
assertEquals(operationId, decoded.chatCreate!!.operationId)
assertNotEquals(operationId, PipelinesRepository.newChatCreateOperationId())
}
}
@@ -218,12 +218,13 @@ class ChatProtocolTest {
val create = Message(
type = Protocol.CHAT_CREATE,
id = "android-1",
chatCreate = ChatCreateRequest(title = "New chat", directory = "/work"),
chatCreate = ChatCreateRequest(title = "New chat", directory = "/work", operationId = "create-1"),
)
val createJson = PipelinesJson.encodeToString(Message.serializer(), create)
assertTrue(createJson.contains("\"chat_create\""))
val decodedCreate = PipelinesJson.decodeFromString(Message.serializer(), createJson)
assertEquals("New chat", decodedCreate.chatCreate!!.title)
assertEquals("create-1", decodedCreate.chatCreate!!.operationId)
val prompt = Message(
type = Protocol.CHAT_PROMPT,
@@ -33,8 +33,9 @@ class ChatSessionManagementTest {
@Test
fun theCreateFlowDefaultsToHomeAndCreatesInTheChosenDirectory() {
val store = ChatStore()
store.createOpened()
store.createOpened("create-1")
assertEquals(HOME_DIRECTORY, store.value.create!!.directory)
assertEquals("create-1", store.value.create!!.operationId)
store.createDirectoryChosen("/home/op/work")
assertEquals("/home/op/work", store.value.create!!.directory)
@@ -50,12 +51,23 @@ class ChatSessionManagementTest {
fun cancellingTheCreateFlowLeavesTheListUntouched() {
val store = ChatStore()
store.sessionsLoaded(listOf(session("a")))
store.createOpened()
store.createOpened("create-2")
store.createCancelled()
assertNull(store.value.create)
assertEquals(listOf("a"), store.value.visibleSessions.map { it.id })
}
@Test
fun aFailedCreateKeepsItsOperationIdentityForRetry() {
val store = ChatStore()
store.createOpened("create-retry")
store.creating()
store.createFailed("connection lost")
assertEquals("create-retry", store.value.create!!.operationId)
assertTrue(!store.value.create!!.creating)
}
@Test
fun renameWinsOverTheServersTitleAndSurvivesARefresh() {
val store = ChatStore()
+18
View File
@@ -0,0 +1,18 @@
# Chat-create operation identity
`chat_create` now carries `chat_create.operation_id` as its durable create-intent
key. The envelope `id` remains only response correlation and may restart at
`cli-1` or `android-1` in a fresh process. Clients that need exactly-once retry
after reconnect or a lost response must retain and resend `operation_id`; legacy
clients receive a server-generated per-request scope and therefore have no
cross-reconnect retry guarantee.
`docs/cli.md` and the packaged OpenCode skill references that describe
`chat_create` are stale: they should document this additive field, the legacy
compatibility behavior, and rollout requirement that retry-capable clients send a
stable operation identity.
Compatibility rollout: deploy the additive server support before a client that
sends `operation_id`; old clients remain able to create chats but cannot safely
retry across reconnects. Once clients send a stable key per create intent, they
must keep that key for every retry and allocate a new key for each new chat.
+8 -7
View File
@@ -33,7 +33,7 @@ type OperatorSession struct {
}
// ChatCreateBootstrap is the durable progress record for one chat_create
// request. It lets a retried request resume after endpoint activation or a
// operation. It lets a retried operation resume after endpoint activation or a
// registry write failed, without creating or activating another session.
type ChatCreateBootstrap struct {
RequestID string
@@ -72,23 +72,24 @@ directory TEXT NOT NULL, state TEXT NOT NULL, created_at INTEGER NOT NULL, updat
return s.migrateOperatorSessions()
}
// BeginChatCreate reserves a request id or returns its prior progress. The
// request id is the client retry key and is never reused for different input.
func (s *Store) BeginChatCreate(ctx context.Context, requestID, title, directory string) (ChatCreateBootstrap, error) {
// BeginChatCreate reserves an operation id or returns its prior progress. The
// operation id is the client retry key and is never reused for different input.
// It remains stored in request_id for compatibility with existing bootstrap rows.
func (s *Store) BeginChatCreate(ctx context.Context, operationID, title, directory string) (ChatCreateBootstrap, error) {
now := time.Now().UnixMilli()
_, err := s.db.ExecContext(ctx, `INSERT INTO chat_create_bootstraps(request_id,title,directory,state,created_at,updated_at)
VALUES(?,?,?,?,?,?) ON CONFLICT(request_id) DO NOTHING`, requestID, title, directory, "created", now, now)
VALUES(?,?,?,?,?,?) ON CONFLICT(request_id) DO NOTHING`, operationID, title, directory, "created", now, now)
if err != nil {
return ChatCreateBootstrap{}, err
}
var b ChatCreateBootstrap
err = s.db.QueryRowContext(ctx, `SELECT request_id,session_id,title,directory,state FROM chat_create_bootstraps WHERE request_id=?`, requestID).
err = s.db.QueryRowContext(ctx, `SELECT request_id,session_id,title,directory,state FROM chat_create_bootstraps WHERE request_id=?`, operationID).
Scan(&b.RequestID, &b.SessionID, &b.Title, &b.Directory, &b.State)
if err != nil {
return ChatCreateBootstrap{}, err
}
if b.Title != title || b.Directory != directory {
return ChatCreateBootstrap{}, errors.New("chat_create request id was reused with different input")
return ChatCreateBootstrap{}, errors.New("chat_create operation id was reused with different input")
}
return b, nil
}
+8 -4
View File
@@ -172,11 +172,15 @@ type ChatCloseResult struct {
}
// ChatCreateRequest is the chat_create request body: a title and an optional
// working directory (the server's configured location when empty). The response
// carries the created session in Message.ChatSession.
// working directory (the server's configured location when empty). OperationID
// is the durable idempotency key for this create intent; it is deliberately
// separate from Message.ID, which remains connection-local response
// correlation. Clients retrying a create across reconnects must retain it. The
// response carries the created session in Message.ChatSession.
type ChatCreateRequest struct {
Title string `json:"title,omitempty"`
Directory string `json:"directory,omitempty"`
Title string `json:"title,omitempty"`
Directory string `json:"directory,omitempty"`
OperationID string `json:"operation_id,omitempty"`
}
// ChatAdoptRequest is the chat_adopt request body: the id of a session that
+1 -1
View File
@@ -24,7 +24,7 @@ func chatSamples() []struct {
{"session_busy", ChatSession{ID: "ses_2", Title: "held", Busy: true}},
{"session_closed", ChatSession{ID: "ses_3", Title: "done", Closed: true, ClosedAt: 1792112367999}},
{"close_result", ChatCloseResult{SessionID: "ses_3", ClosedAt: 1792112367999, Interrupted: true}},
{"create", ChatCreateRequest{Title: "demo", Directory: "/work"}},
{"create", ChatCreateRequest{Title: "demo", Directory: "/work", OperationID: "create-1"}},
{"adopt", ChatAdoptRequest{SessionID: "ses_1"}},
{"query", ChatQuery{SessionID: "ses_1", Limit: 50}},
{"prompt", ChatPromptRequest{SessionID: "ses_1", Text: "hello", Model: "m", Agent: "build", Files: []string{"file:///tmp/a.png"}, Client: "Pixel 9 Pro XL"}},
+5 -1
View File
@@ -4,6 +4,8 @@ import (
"context"
"crypto/rand"
"encoding/hex"
"strconv"
"sync/atomic"
"git.a-wan.net/alan/pipelines/internal/pipeline"
"git.a-wan.net/alan/pipelines/internal/protocol"
@@ -72,6 +74,8 @@ type operatorRegistry interface {
ReopenOperatorSession(ctx context.Context, sessionID string) error
}
var chatTokenSequence atomic.Uint64
// chatClientToken returns an unguessable per-connection identity. Its only role
// is to key a connection's chat-room subscriptions and to exclude the sender from
// its own fan-out; it carries no ownership. A fresh token per connection means a
@@ -79,7 +83,7 @@ type operatorRegistry interface {
func chatClientToken() string {
var b [8]byte
if _, err := rand.Read(b[:]); err != nil {
return "conn-unknown"
return "conn-fallback-" + strconv.FormatUint(chatTokenSequence.Add(1), 10)
}
return "conn-" + hex.EncodeToString(b[:])
}
+17 -12
View File
@@ -100,15 +100,20 @@ func handleChatCreate(ctx context.Context, request protocol.Message, broker chat
_ = write(protocol.Message{Type: protocol.Error, ID: request.ID, Error: "operator session registry is not configured on this server"})
return
}
if strings.TrimSpace(request.ID) == "" {
_ = write(protocol.Message{Type: protocol.Error, ID: request.ID, Error: "chat_create requires a non-empty request id for retry-safe creation"})
return
}
title := ""
directory := ""
operationID := ""
if request.ChatCreate != nil {
title = strings.TrimSpace(request.ChatCreate.Title)
directory = strings.TrimSpace(request.ChatCreate.Directory)
operationID = strings.TrimSpace(request.ChatCreate.OperationID)
}
// Legacy clients did not carry a durable create identity. Give each received
// request its own server-generated scope so their connection-local envelope
// IDs (for example cli-1) cannot collide globally. Such requests cannot be
// retried exactly once across reconnects because they supplied no key.
if operationID == "" {
operationID = chatClientToken()
}
if title == "" {
title = "New chat"
@@ -118,7 +123,7 @@ func handleChatCreate(ctx context.Context, request protocol.Message, broker chat
_ = write(protocol.Message{Type: protocol.Error, ID: request.ID, Error: err.Error()})
return
}
bootstrap, err := registry.BeginChatCreate(ctx, request.ID, title, resolved)
bootstrap, err := registry.BeginChatCreate(ctx, operationID, title, resolved)
if err != nil {
_ = write(protocol.Message{Type: protocol.Error, ID: request.ID, Error: err.Error()})
return
@@ -131,7 +136,7 @@ func handleChatCreate(ctx context.Context, request protocol.Message, broker chat
}
// The conditional transition is the durable reservation for the external
// Create call. A duplicate request that lost it must not create an orphan.
if err := registry.AdvanceChatCreate(ctx, request.ID, "created", "creating"); err != nil {
if err := registry.AdvanceChatCreate(ctx, operationID, "created", "creating"); err != nil {
chatCreateConflictError(request, err, write)
return
}
@@ -140,11 +145,11 @@ func handleChatCreate(ctx context.Context, request protocol.Message, broker chat
_ = write(protocol.Message{Type: protocol.Error, ID: request.ID, Error: err.Error()})
return
}
if err := registry.SetChatCreateSession(ctx, request.ID, session.ID); err != nil {
if err := registry.SetChatCreateSession(ctx, operationID, session.ID); err != nil {
_ = write(protocol.Message{Type: protocol.Error, ID: request.ID, Error: "session " + session.ID + " was created but durable bootstrap state could not be saved: " + err.Error()})
return
}
if err := registry.AdvanceChatCreate(ctx, request.ID, "creating", "created"); err != nil {
if err := registry.AdvanceChatCreate(ctx, operationID, "creating", "created"); err != nil {
_ = write(protocol.Message{Type: protocol.Error, ID: request.ID, Error: "session " + session.ID + " was created but durable bootstrap state could not advance: " + err.Error()})
return
}
@@ -154,7 +159,7 @@ func handleChatCreate(ctx context.Context, request protocol.Message, broker chat
// Reserve the activation before calling the external service. If the
// process dies after the call but before the success checkpoint, a retry
// must report the ambiguous operation rather than append the skill twice.
if err := registry.AdvanceChatCreate(ctx, request.ID, "created", "activating"); err != nil {
if err := registry.AdvanceChatCreate(ctx, operationID, "created", "activating"); err != nil {
chatCreateConflictError(request, err, write)
return
}
@@ -162,7 +167,7 @@ func handleChatCreate(ctx context.Context, request protocol.Message, broker chat
_ = write(protocol.Message{Type: protocol.Error, ID: request.ID, Error: "session " + session.ID + " was created but manager bootstrap failed while activating pipelines-manager: " + err.Error()})
return
}
if err := registry.AdvanceChatCreate(ctx, request.ID, "activating", "activated"); err != nil {
if err := registry.AdvanceChatCreate(ctx, operationID, "activating", "activated"); err != nil {
_ = write(protocol.Message{Type: protocol.Error, ID: request.ID, Error: "session " + session.ID + " activated but durable bootstrap state could not be saved: " + err.Error()})
return
}
@@ -173,7 +178,7 @@ func handleChatCreate(ctx context.Context, request protocol.Message, broker chat
return
}
if bootstrap.State == "activated" {
if err := registry.AdvanceChatCreate(ctx, request.ID, "activated", "recording"); err != nil {
if err := registry.AdvanceChatCreate(ctx, operationID, "activated", "recording"); err != nil {
chatCreateConflictError(request, err, write)
return
}
@@ -181,7 +186,7 @@ func handleChatCreate(ctx context.Context, request protocol.Message, broker chat
_ = write(protocol.Message{Type: protocol.Error, ID: request.ID, Error: "session " + session.ID + " was created but could not be recorded: " + err.Error()})
return
}
if err := registry.AdvanceChatCreate(ctx, request.ID, "recording", "recorded"); err != nil {
if err := registry.AdvanceChatCreate(ctx, operationID, "recording", "recorded"); err != nil {
_ = write(protocol.Message{Type: protocol.Error, ID: request.ID, Error: "session " + session.ID + " was recorded but durable bootstrap state could not be saved: " + err.Error()})
return
}
+84 -12
View File
@@ -1373,7 +1373,7 @@ func TestChatCreateReportsManagerBootstrapFailure(t *testing.T) {
func TestChatCreateRetryReusesDurableBootstrap(t *testing.T) {
broker := &fakeChat{created: protocol.ChatSession{ID: "ses_once"}}
store := newOperatorStore(t)
request := protocol.Message{ID: "create-once", Type: protocol.ChatCreate, ChatCreate: &protocol.ChatCreateRequest{Title: "demo"}}
request := protocol.Message{ID: "create-once", Type: protocol.ChatCreate, ChatCreate: &protocol.ChatCreateRequest{Title: "demo", OperationID: "operation-once"}}
for i := 0; i < 2; i++ {
var response protocol.Message
handleChatCreate(context.Background(), request, broker, store, func(message protocol.Message) error { response = message; return nil })
@@ -1389,6 +1389,51 @@ func TestChatCreateRetryReusesDurableBootstrap(t *testing.T) {
}
}
// TestChatCreateOperationSurvivesLostResponseAndStoreReopen verifies that the
// durable create identity, rather than the connection-local reply ID, resumes a
// completed create after a client lost its reply and the server reopened its DB.
func TestChatCreateOperationSurvivesLostResponseAndStoreReopen(t *testing.T) {
ctx := context.Background()
path := filepath.Join(t.TempDir(), "operator.db")
store, err := pipeline.Open(path)
if err != nil {
t.Fatal(err)
}
broker := &fakeChat{created: protocol.ChatSession{ID: "ses_once"}}
handleChatCreate(ctx, protocol.Message{
ID: "cli-1", Type: protocol.ChatCreate,
ChatCreate: &protocol.ChatCreateRequest{Title: "demo", OperationID: "operation-once"},
}, broker, store, func(protocol.Message) error {
return nil // Simulate a reply lost after all durable checkpoints completed.
})
if err := store.Close(); err != nil {
t.Fatal(err)
}
reopened, err := pipeline.Open(path)
if err != nil {
t.Fatal(err)
}
defer reopened.Close()
var response protocol.Message
handleChatCreate(ctx, protocol.Message{
ID: "cli-2", Type: protocol.ChatCreate,
ChatCreate: &protocol.ChatCreateRequest{Title: "demo", OperationID: "operation-once"},
}, broker, reopened, func(message protocol.Message) error {
response = message
return nil
})
if response.Type != protocol.ChatCreate || response.ID != "cli-2" || response.ChatSession == nil || response.ChatSession.ID != "ses_once" {
t.Fatalf("reopened retry response = %#v", response)
}
broker.mu.Lock()
creates, activations := broker.createCalls, broker.activateCalls
broker.mu.Unlock()
if creates != 1 || activations != 1 {
t.Fatalf("reopened retry repeated external work: creates=%d activations=%d", creates, activations)
}
}
// TestChatCreateDuplicateRequestReservesExternalWork proves the conditional
// durable transition, rather than timing or the race detector, elects exactly
// one request to call the external Create and ActivateSkill operations.
@@ -1400,7 +1445,7 @@ func TestChatCreateDuplicateRequestReservesExternalWork(t *testing.T) {
createGate: createGate,
createStarted: make(chan struct{}),
}
request := protocol.Message{ID: "same-request", Type: protocol.ChatCreate, ChatCreate: &protocol.ChatCreateRequest{Title: "demo"}}
request := protocol.Message{ID: "same-request", Type: protocol.ChatCreate, ChatCreate: &protocol.ChatCreateRequest{Title: "demo", OperationID: "operation-once"}}
responses := make(chan protocol.Message, 2)
run := func() {
handleChatCreate(context.Background(), request, broker, store, func(message protocol.Message) error {
@@ -1440,21 +1485,48 @@ func TestChatCreateDuplicateRequestReservesExternalWork(t *testing.T) {
}
}
func TestChatCreateRequiresRequestID(t *testing.T) {
func TestChatCreateLegacyRequestWithoutOperationIDUsesFreshScope(t *testing.T) {
broker := &fakeChat{created: protocol.ChatSession{ID: "ses_new"}}
var response protocol.Message
handleChatCreate(context.Background(), protocol.Message{Type: protocol.ChatCreate, ChatCreate: &protocol.ChatCreateRequest{Title: "demo"}}, broker, newOperatorStore(t), func(message protocol.Message) error {
response = message
return nil
})
if response.Type != protocol.Error || !strings.Contains(response.Error, "non-empty request id") {
t.Fatalf("empty chat_create response = %+v", response)
store := newOperatorStore(t)
for _, request := range []protocol.Message{
{ID: "cli-1", Type: protocol.ChatCreate, ChatCreate: &protocol.ChatCreateRequest{Title: "first"}},
{ID: "cli-1", Type: protocol.ChatCreate, ChatCreate: &protocol.ChatCreateRequest{Title: "second"}},
} {
var response protocol.Message
handleChatCreate(context.Background(), request, broker, store, func(message protocol.Message) error {
response = message
return nil
})
if response.Type != protocol.ChatCreate || response.ChatSession == nil {
t.Fatalf("legacy chat_create response = %+v", response)
}
}
broker.mu.Lock()
creates := broker.createCalls
broker.mu.Unlock()
if creates != 0 {
t.Fatalf("empty chat_create called broker.Create %d times", creates)
if creates != 2 {
t.Fatalf("legacy creates = %d, want 2", creates)
}
}
func TestChatCreateOperationIDRejectsChangedInputBeforeExternalWork(t *testing.T) {
broker := &fakeChat{created: protocol.ChatSession{ID: "ses_new"}}
store := newOperatorStore(t)
first := protocol.Message{ID: "cli-1", Type: protocol.ChatCreate, ChatCreate: &protocol.ChatCreateRequest{Title: "first", OperationID: "operation"}}
handleChatCreate(context.Background(), first, broker, store, func(protocol.Message) error { return nil })
var response protocol.Message
handleChatCreate(context.Background(), protocol.Message{ID: "cli-1", Type: protocol.ChatCreate, ChatCreate: &protocol.ChatCreateRequest{Title: "second", OperationID: "operation"}}, broker, store, func(message protocol.Message) error {
response = message
return nil
})
if response.Type != protocol.Error || !strings.Contains(response.Error, "operation id was reused with different input") {
t.Fatalf("changed operation response = %+v", response)
}
broker.mu.Lock()
creates, activations := broker.createCalls, broker.activateCalls
broker.mu.Unlock()
if creates != 1 || activations != 1 {
t.Fatalf("changed operation repeated external work: creates=%d activations=%d", creates, activations)
}
}