@ego-z/contracts 0.14.2 → 0.14.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ego-z/contracts",
-  "version": "0.14.2",
+  "version": "0.14.4",
   "description": "Wire-format type contracts shared between EgoZ backend, SDK, MCP and console. Type-only — no runtime artifacts.",
   "types": "./src/index.d.ts",
   "exports": {

package/src/stream.d.ts

@@ -97,8 +97,37 @@ export interface AskStreamDeltaEvent {
  * deltas it produced. **Live mode only** — buffered streams never emit it,
  * so a consumer that does not opt in sees a byte-identical wire.
  *
- * Emitted at iteration end, *before* any `tool.calling` for that iteration,
- * so a consumer's timeline always settles before the next thing moves.
+ * ## Ordering guarantees
+ *
+ * 1. **Before any `tool.calling` for that iteration** — so a consumer's
+ *    timeline always settles before the next thing moves.
+ * 2. **Before `done`, for every block that produced text.** Structural, not
+ *    conventional: every `iteration.end` is emitted inside the orchestrator's
+ *    tool loop, and `done` is emitted only after that loop returns. So a
+ *    terminal block — which by definition has no following `tool.calling` and
+ *    is therefore not covered by (1) — is still guaranteed resolved before the
+ *    stream completes normally.
+ *
+ * ⚠️ **Neither guarantee covers the `error` path.** A turn that fails
+ * mid-iteration terminates with an `error` event, and a block that was
+ * streaming `'pending'` at that moment is never resolved.
+ *
+ * **An unresolved block at `error` is expected, not a defect.** It means
+ * what it looks like: the model was mid-thought when the turn died, and
+ * nothing — here or downstream — knows which channel that text would have
+ * belonged to. Render it as the partial thought it is. Do NOT synthesise a
+ * phase for it, and in particular do not "fix" it by promoting it to
+ * `'final'` at the error site: that presents a half-finished thought as the
+ * answer with the error hidden, which is precisely the failure this channel
+ * exists to prevent.
+ *
+ * The two terminal frames are therefore asymmetric, and anything monitoring
+ * the stream should treat them as different signals:
+ *
+ *   - unresolved at `done`  → **invariant violation.** (2) says this cannot
+ *                             happen; if it does, the loop was restructured.
+ *   - unresolved at `error` → **expected.** Tells you how much text was
+ *                             stranded, and nothing more.
  *
  * `phase` is authoritative: it reports whether the orchestrator is actually
  * going on to dispatch tools (`'thinking'`) or this was the terminal answer

package/src/thread.d.ts

@@ -40,6 +40,26 @@ export type MessageFailureReason =
     | 'max_calls_per_turn'
     | 'unrecoverable_error';
 
+/**
+ * Conversation lifecycle state. Mirrors the CHECK constraint on
+ * `egoz_threads.status` (migration 054).
+ *
+ * - `'draft'`  — minted by the ghosted start (`POST /egoz/conversations/draft`)
+ *                before the user has typed anything. Carries the caller's
+ *                init context, holds a conversation id the caller can keep,
+ *                and is swept after the draft TTL if it never promotes.
+ * - `'active'` — a real conversation. Every thread created by `/ask` is born
+ *                active, and a draft becomes active on its first user
+ *                message. An active thread is never swept.
+ *
+ * ORTHOGONAL TO `isActive`, which means *archived* and predates this field.
+ * A draft is not an archived thread and an archived thread was never a draft;
+ * the two were deliberately not collapsed into one boolean, because the
+ * draft sweeper's delete predicate would then also match archived user
+ * conversations.
+ */
+export type ThreadStatus = 'draft' | 'active';
+
 // ============================================================================
 // Supporting shapes
 // ============================================================================
@@ -89,6 +109,13 @@ export interface ThreadWire {
     title: string | null;
     metadata: Record<string, unknown>;
     isActive: boolean;
+    /**
+     * Conversation lifecycle — `'draft'` (ghosted start, not yet spoken to)
+     * or `'active'`. See `ThreadStatus`; distinct from `isActive`, which
+     * means archived. Rows created before migration 054 read as `'active'`,
+     * which is what they are.
+     */
+    status: ThreadStatus;
     /** ISO 8601 timestamp. */
     createdAt: string;
     /** ISO 8601 timestamp. */