@celestea/core 2.7.1

package/contracts/session-event.schema.json

@@ -0,0 +1,441 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://celestea.top/contracts/session-event.schema.json",
+  "title": "Celestea engine SessionEvent (cli-main.jsonl v1, one JSON object per line)",
+  "generatedAt": "2026-09-10T01:20:00Z",
+  "source": {
+    "legacy": "frozen from the retired implementation (original source file deleted 2026-09-15): /src/celestea_harness/crates/core/src/session_log.rs:44-85 (serde tag=\"type\", rename_all=snake_case)",
+    "doc": "docs/data-files.md §4"
+  },
+  "encoding": {
+    "file": "<session-dir>/cli-main.jsonl",
+    "format": "JSONL: one SessionEvent per line, UTF-8, no trailing comma",
+    "parse": "skip blank lines; STOP at the first unparsable line (a torn tail is never treated as content) - src/api.rs:141-153"
+  },
+  "turnId": {
+    "pattern": "^turn-\\d+$",
+    "monotonic": true,
+    "rule": "next_turn_number only recognises the 'turn-<n>' prefix and restores its counter from the max replayed id, so ids never repeat across restarts (session_log.rs:94-98)",
+    "compactRewrites": "/compact renumbers the kept turns as turn-1..turn-(K+1); the next live turn is turn-(K+2)"
+  },
+  "$defs": {
+    "AttachmentRef": {
+      "title": "AttachmentRef (W804 multimodal P0)",
+      "type": "object",
+      "required": [
+        "attachment_id",
+        "media_type",
+        "width",
+        "height"
+      ],
+      "properties": {
+        "attachment_id": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{64}$"
+        },
+        "media_type": {
+          "type": "string",
+          "enum": [
+            "image/png",
+            "image/jpeg",
+            "image/webp",
+            "image/gif"
+          ]
+        },
+        "width": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "height": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "name": {
+          "type": "string"
+        },
+        "original": {
+          "type": "object",
+          "description": "present only when the stored bytes are a downscaled/re-encoded variant (P0 never writes it)"
+        }
+      },
+      "additionalProperties": false,
+      "note": "A CONTENT-ADDRESSED REFERENCE, never bytes: the object lives at <session-dir>/attachments/<attachment_id>.<ext> and the log stores only this shape (no base64 is ever written to cli-main.jsonl)."
+    },
+    "TurnOutcome": {
+      "title": "TurnOutcome (5 terminal states)",
+      "oneOf": [
+        {
+          "const": "completed",
+          "description": "normal end: the model answered without further tool calls"
+        },
+        {
+          "const": "cancelled",
+          "description": "cooperative cancel fired; partial output/tool results stay in the log"
+        },
+        {
+          "type": "object",
+          "required": [
+            "error"
+          ],
+          "properties": {
+            "error": {
+              "type": "object",
+              "required": [
+                "kind",
+                "message"
+              ],
+              "properties": {
+                "kind": {
+                  "type": "string",
+                  "enum": [
+                    "generate",
+                    "stream"
+                  ]
+                },
+                "message": {
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
+            }
+          },
+          "additionalProperties": false,
+          "description": "LLM stream or generation failure"
+        },
+        {
+          "const": "step_limit",
+          "description": "max_steps exhausted without a final assistant answer (NOT completion)"
+        },
+        {
+          "const": "interrupted",
+          "description": "the stream ended without a terminal frame"
+        }
+      ],
+      "serdeShape": {
+        "completed": "\"completed\"",
+        "cancelled": "\"cancelled\"",
+        "error": "{\"error\":{\"kind\":\"generate\",\"message\":\"...\"}}",
+        "step_limit": "\"step_limit\"",
+        "interrupted": "\"interrupted\""
+      },
+      "legacyDefault": "a turn_end row WITHOUT an outcome field deserializes as \"completed\" (#[serde(default)])"
+    },
+    "SessionEvent": {
+      "oneOf": [
+        {
+          "title": "turn_start",
+          "type": "object",
+          "required": [
+            "type",
+            "id"
+          ],
+          "properties": {
+            "type": {
+              "const": "turn_start"
+            },
+            "id": {
+              "type": "string",
+              "pattern": "^turn-\\d+$"
+            }
+          },
+          "additionalProperties": true
+        },
+        {
+          "title": "turn_end",
+          "type": "object",
+          "required": [
+            "type",
+            "id"
+          ],
+          "properties": {
+            "type": {
+              "const": "turn_end"
+            },
+            "id": {
+              "type": "string",
+              "pattern": "^turn-\\d+$"
+            },
+            "outcome": {
+              "$ref": "#/$defs/TurnOutcome"
+            }
+          },
+          "additionalProperties": true
+        },
+        {
+          "title": "user_message",
+          "type": "object",
+          "required": [
+            "type",
+            "text"
+          ],
+          "properties": {
+            "type": {
+              "const": "user_message"
+            },
+            "text": {
+              "type": "string"
+            },
+            "attachments": {
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/AttachmentRef"
+              },
+              "description": "W804: optional image references; omitted entirely when there are none (a legacy row is byte-identical)"
+            }
+          },
+          "additionalProperties": true
+        },
+        {
+          "title": "assistant_message",
+          "type": "object",
+          "required": [
+            "type",
+            "text"
+          ],
+          "properties": {
+            "type": {
+              "const": "assistant_message"
+            },
+            "text": {
+              "type": "string"
+            }
+          },
+          "additionalProperties": true
+        },
+        {
+          "title": "thinking_delta",
+          "type": "object",
+          "required": [
+            "type",
+            "text"
+          ],
+          "properties": {
+            "type": {
+              "const": "thinking_delta"
+            },
+            "text": {
+              "type": "string"
+            }
+          },
+          "additionalProperties": true
+        },
+        {
+          "title": "tool_call",
+          "type": "object",
+          "required": [
+            "type",
+            "id",
+            "name",
+            "args"
+          ],
+          "properties": {
+            "type": {
+              "const": "tool_call"
+            },
+            "id": {
+              "type": "string"
+            },
+            "name": {
+              "type": "string"
+            },
+            "args": {},
+            "parent_id": {
+              "type": "string",
+              "description": "W255 run_code sub-call: Some(<parent call id>); the row is logged for audit/replay but derive_messages skips it"
+            }
+          },
+          "additionalProperties": true
+        },
+        {
+          "title": "tool_result",
+          "type": "object",
+          "required": [
+            "type",
+            "id",
+            "value",
+            "error"
+          ],
+          "properties": {
+            "type": {
+              "const": "tool_result"
+            },
+            "id": {
+              "type": "string"
+            },
+            "value": {},
+            "error": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "parent_id": {
+              "type": "string",
+              "description": "same contract as tool_call.parent_id"
+            }
+          },
+          "additionalProperties": true
+        },
+        {
+          "title": "user_question",
+          "type": "object",
+          "required": [
+            "type",
+            "id",
+            "questions"
+          ],
+          "properties": {
+            "type": {
+              "const": "user_question"
+            },
+            "id": {
+              "type": "string",
+              "description": "W783: the request id ('q-<n>'), echoed by the matching user_answer row."
+            },
+            "questions": {
+              "type": "array",
+              "description": "The question batch as the model asked it (the same shape the tool received).",
+              "items": {
+                "type": "object",
+                "additionalProperties": true
+              }
+            },
+            "expires_at": {
+              "type": "integer",
+              "description": "W783: absolute deadline in ms; judged at READ time so a replay still knows whether the question expired."
+            },
+            "timeout_ms": {
+              "type": "integer",
+              "description": "W783: the resolved maximum wait in ms."
+            }
+          },
+          "additionalProperties": true
+        },
+        {
+          "title": "user_answer",
+          "type": "object",
+          "required": [
+            "type",
+            "id",
+            "answers"
+          ],
+          "properties": {
+            "type": {
+              "const": "user_answer"
+            },
+            "id": {
+              "type": "string",
+              "description": "W783: the request id this row answers."
+            },
+            "answers": {
+              "type": "array",
+              "description": "selected holds option LABELS, never indices; custom is the optional free-text answer.",
+              "items": {
+                "type": "object",
+                "additionalProperties": true
+              }
+            },
+            "timed_out": {
+              "type": "boolean",
+              "description": "W783: true = the deadline expired and NO answer exists; the system decided nothing for the model."
+            }
+          },
+          "additionalProperties": true
+        }
+      ],
+      "note": "W783 added user_question/user_answer (7 -> 9 variants). They are ADDITIVE rows: the engine never emits them, the host does, and a reader that does not know them treats the row as a torn tail exactly as before."
+    }
+  },
+  "type": "object",
+  "required": [
+    "type"
+  ],
+  "oneOf": [
+    {
+      "$ref": "#/$defs/SessionEvent/oneOf/0"
+    },
+    {
+      "$ref": "#/$defs/SessionEvent/oneOf/1"
+    },
+    {
+      "$ref": "#/$defs/SessionEvent/oneOf/2"
+    },
+    {
+      "$ref": "#/$defs/SessionEvent/oneOf/3"
+    },
+    {
+      "$ref": "#/$defs/SessionEvent/oneOf/4"
+    },
+    {
+      "$ref": "#/$defs/SessionEvent/oneOf/5"
+    },
+    {
+      "$ref": "#/$defs/SessionEvent/oneOf/6"
+    },
+    {
+      "$ref": "#/$defs/SessionEvent/oneOf/7"
+    },
+    {
+      "$ref": "#/$defs/SessionEvent/oneOf/8"
+    }
+  ],
+  "projections": {
+    "studioMessages": "GET /api/sessions/{id}/messages -> session_event_to_message (src/api.rs:94-135). Independent per event, NO pairing/dropping.",
+    "studioMapping": {
+      "turn_start": "(omitted)",
+      "turn_end": "(omitted)",
+      "user_message": {
+        "role": "user",
+        "content": "<text>",
+        "attachments": "[AttachmentRef] (omitted when absent; W804)"
+      },
+      "assistant_message": {
+        "role": "assistant",
+        "content": "<text>"
+      },
+      "thinking_delta": {
+        "role": "thinking",
+        "content": "<text>"
+      },
+      "tool_call": {
+        "role": "tool",
+        "kind": "call",
+        "tool_call_id": "<id>",
+        "tool_name": "<name>",
+        "tool_args": "<args>",
+        "tool_parent_id": "<parent_id> (only when present)",
+        "content": "ABSENT"
+      },
+      "tool_result": {
+        "role": "tool",
+        "kind": "result",
+        "tool_call_id": "<id>",
+        "tool_value": "<value>",
+        "tool_error": "<error>",
+        "tool_parent_id": "<parent_id> (only when present)",
+        "content": "ABSENT"
+      },
+      "user_question": {
+        "role": "question",
+        "kind": "question",
+        "content": "<questions>",
+        "question_id": "<id>",
+        "expires_at": "<expires_at> (when present)"
+      },
+      "user_answer": {
+        "role": "question",
+        "kind": "answer",
+        "content": "<answers>",
+        "question_id": "<id>",
+        "timed_out": "<timed_out> (when present)"
+      }
+    },
+    "engineDeriveMessages": "model-visible history: turn_start/turn_end/thinking_delta are SKIPPED; tool rows carrying parent_id are SKIPPED (run_code sub-calls); everything else is projected in log order. W783: user_question/user_answer are host-side audit rows about a PAUSED turn — they are SKIPPED too (the answer reaches the model as the ordinary tool_result of ask_user_question, never as invented history).",
+    "orphanRule": "an orphan tool_result (no preceding tool_call) is still emitted by the Studio projection; nothing is paired or filtered.",
+    "questionRecovery": "W783 §7: user_question/user_answer exist so a client that reconnects can rebuild the card and so a replay shows how a parked turn ended. The pending TABLE is in-memory: after a restart a question is unanswerable, and the row reads as an unanswered/expired question instead of blocking the model."
+  },
+  "serialization": {
+    "fieldOrder": "serde struct order",
+    "parentIdOmitted": "parent_id is omitted (skip_serializing_if=Option::is_none) when absent, so pre-W255 byte shape is unchanged"
+  }
+}

package/contracts/sse-events.json

@@ -0,0 +1,202 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Celestea Studio SSE contract (GET /api/events)",
+  "generatedAt": "2026-09-10T01:20:00Z",
+  "source": {
+    "code": "frozen from the retired backend implementation (original source file deleted 2026-09-15): emit + loop_event_to_json, the SSE handler, and the bus capacity constant",
+    "doc": "docs/DEVELOPMENT.md §2.5",
+    "liveProbe": {
+      "endpoint": "http://127.0.0.1:3777/api/events",
+      "mode": "read-only passive connect",
+      "observedHeaders": {
+        "content-type": "text/event-stream",
+        "cache-control": "no-cache",
+        "transfer-encoding": "chunked"
+      },
+      "eventsObserved": 0,
+      "reason": "no turn was running; P0 forbids POST /api/turn because it appends to the production cli-main.jsonl"
+    }
+  },
+  "transport": {
+    "contentType": "text/event-stream",
+    "keepAlive": true,
+    "busCapacity": 512,
+    "envelope": {
+      "turn": "u64",
+      "seq": "u64 (global atomic counter, monotonic across the process)",
+      "payload": "object"
+    },
+    "envelopeExtensions": {
+      "note": "W513 per-session envelope: the TypeScript host adds these two keys to the frozen `{turn,seq,payload}` envelope (apps/studio/src/sse.ts: createStudioBus). The W744 parity test validates a real frame against `envelopeSchema` widened by exactly these keys, so an undeclared envelope key is a failure instead of an unnoticed drift.",
+      "v": {
+        "type": "integer",
+        "const": 2
+      },
+      "session": {
+        "type": [
+          "string",
+          "null"
+        ]
+      }
+    },
+    "envelopeSchema": {
+      "type": "object",
+      "required": [
+        "turn",
+        "seq",
+        "payload"
+      ],
+      "properties": {
+        "turn": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "seq": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "payload": {
+          "type": "object"
+        }
+      },
+      "additionalProperties": false
+    },
+    "frameFormat": "event: <name>\\ndata: <envelope JSON>\\n\\n"
+  },
+  "lagged": {
+    "trigger": "a slow client is dropped by the broadcast channel (capacity 512)",
+    "event": "status",
+    "payload": {
+      "phase": "lagged",
+      "hint": "slow client, skipped events",
+      "statusline": "<statusline object>"
+    },
+    "semantics": "the stream does NOT close; the client receives one lagged status and continues consuming. Skipped events are NOT replayed.",
+    "codeRef": "src/main.rs:883-892"
+  },
+  "payloadExtensions": {
+    "note": "Keys the TypeScript host adds to an event payload beyond the frozen legacy table above (W513 per-session frames + W515 injection placements). They are contract too: `payloadExtensions.<event>` is the ONLY place a host-only payload key may be declared, and the W744 parity test fails on any produced key that appears in neither the event's `payload` table nor here. W785 added the `phase:\"fallback\"` value (a payload VALUE, not a new event name) and its five companion keys under `payloadExtensions.status`; the 9 event names are untouched (K5/D8).",
+    "status": {
+      "session": "string|null (the session the frame belongs to; null = process-level)",
+      "dropped": "integer (per-session bucket overflow counter, lagged frames only)",
+      "hint": "string (the lagged hint, equal to `lagged.payload.hint`)",
+      "placement": "'queued'|'steering'|'context' (W515 injection placement)",
+      "boundary": "'turn-start'|'step'? (the boundary that consumed an injected message)",
+      "message": "object (the injected-message view {id,kind,from,lane,source,summary})",
+      "effective_model": "string (E §4.2.3 #4, W785: the model actually serving; present on a fallback frame and readable from /api/status.effective_model)",
+      "from": "string|null (W785: the target that just failed and is being left behind; `phase:\"fallback\"` frames only)",
+      "to": "string (W785: the target about to run; `phase:\"fallback\"` frames only)",
+      "reason": "string (W785: `http_503` / `timeout_idle` / `stream` / `network` / `generate`)",
+      "attempt": "integer (W785: index of the attempt ABOUT to run, §5.2 numbering)"
+    }
+  },
+  "count": 9,
+  "events": [
+    {
+      "name": "text",
+      "payload": {
+        "delta": "string"
+      },
+      "source": "LoopEvent::Text",
+      "codeRef": "src/main.rs:668",
+      "frontendListens": true
+    },
+    {
+      "name": "thinking",
+      "payload": {
+        "delta": "string"
+      },
+      "source": "LoopEvent::Thinking",
+      "codeRef": "src/main.rs:669",
+      "frontendListens": true
+    },
+    {
+      "name": "tool",
+      "payload": {
+        "id": "string",
+        "name": "string",
+        "args": "object"
+      },
+      "source": "LoopEvent::ToolCall",
+      "codeRef": "src/main.rs:670-672",
+      "frontendListens": true
+    },
+    {
+      "name": "tool_result",
+      "payload": {
+        "id": "string",
+        "ok": "boolean",
+        "value": "any|null",
+        "render": "any|null",
+        "error": "string|null",
+        "decision": "'allow'|'deny'|'ask'|null"
+      },
+      "source": "LoopEvent::ToolResult",
+      "codeRef": "src/main.rs:673-691",
+      "frontendListens": true
+    },
+    {
+      "name": "turn_end",
+      "payload": {
+        "outcome": "'completed'|'cancelled'|'error'|'step_limit'|'interrupted'",
+        "error": "string|null (only for outcome=error: '{kind}: {message}')"
+      },
+      "source": "LoopEvent::TurnEnd",
+      "codeRef": "src/main.rs:692-695,716-732",
+      "frontendListens": false
+    },
+    {
+      "name": "done",
+      "payload": {
+        "text": "string",
+        "tool_calls": "array<{id,name,args}>"
+      },
+      "source": "LoopEvent::Done",
+      "codeRef": "src/main.rs:696-710",
+      "frontendListens": true
+    },
+    {
+      "name": "status",
+      "payload": {
+        "phase": "'start'|'progress'|'completed'|'cancelled'|'error'|'step_limit'|'interrupted'|'lagged'|'fallback'",
+        "statusline": "object",
+        "error": "string?",
+        "source": "'autowake'?"
+      },
+      "source": "execute_turn / post_turn / slow-client degrade",
+      "codeRef": "src/main.rs:883-892,951-973,1005-1011,1172-1178 ; W785: phase 'fallback' (E §4.2.3 #2)",
+      "frontendListens": true
+    },
+    {
+      "name": "compact",
+      "payload": {
+        "session": "string",
+        "kept_turns": "integer",
+        "note": "string",
+        "rebound": "boolean"
+      },
+      "source": "compact handler",
+      "codeRef": "src/compact.rs:480-491",
+      "frontendListens": true,
+      "note": "envelope `turn` is ALWAYS 0 for compact events"
+    },
+    {
+      "name": "question",
+      "payload": {
+        "id": "string",
+        "questions": "array<{id,question}>",
+        "expires_at": "integer",
+        "timeout_ms": "integer",
+        "session": "string|null"
+      },
+      "source": "W783: the user-questions service, while a turn is parked (host-emitted)",
+      "codeRef": "apps/studio/src/user-questions.ts (publish)",
+      "frontendListens": true,
+      "note": "W783: emitted when the model calls ask_user_question, i.e. while the turn's slot is BUSY. The answer does NOT come back over POST /api/turn (that would be steering, and steering is only drained at step boundaries the parked call never reaches) -- it goes to POST /api/questions/{id}/answer. envelope `turn` is the SESSION-local turn number of the turn that parked."
+    }
+  ],
+  "frontendDeadListener": {
+    "name": "context",
+    "note": "frontend/src/sse.ts:34-43 subscribes to `context` but the backend never emits it"
+  }
+}