@miadi/companion-ui 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/thread.ts ADDED
@@ -0,0 +1,255 @@
1
+ /**
2
+ * The conversation a person holds with an episode's companion seat, as data.
3
+ *
4
+ * Three sources meet here and nowhere else:
5
+ *
6
+ * - **takes**: what the person said, a recorded take filed in the episode under
7
+ * `captures/<take>/` with its English transcript;
8
+ * - **replies**: what the seat answered, one record per reply as the companion's
9
+ * phone page keeps them (`replies/<episode>.jsonl` in its state directory);
10
+ * - **voices**: the voice ledger's records of those replies. A reply is voiced
11
+ * in parts of at most 900 characters, each its own record, so one reply can be
12
+ * several voices.
13
+ *
14
+ * A voice whose `source` is `phone-capture` is a companion reply. Those voices
15
+ * belong to the conversation, not to the episode's other recordings, and
16
+ * `isCompanionVoice` is the one place that says so.
17
+ *
18
+ * Pure: no React, no DOM, no Node. `./node` reads the files; the host reads the
19
+ * ledger; this module joins them.
20
+ */
21
+
22
+ export type CompanionFeedback = "up" | "down"
23
+
24
+ /** A card under a reply for something it names: a diagram, a review, an issue, a file. */
25
+ export interface CompanionRelated {
26
+ label: string
27
+ /** An absolute http(s) URL, as the phone page keeps it. */
28
+ href: string
29
+ kind?: string
30
+ }
31
+
32
+ /** One recorded take, as the episode files it. */
33
+ export interface CompanionTake {
34
+ /** The 12-digit take id, `yyMMddHHmmss`. */
35
+ id: string
36
+ /** When the take was stored, ISO 8601. */
37
+ at: string
38
+ /** The English transcript, `""` when the take has none yet. */
39
+ text: string
40
+ /** The take's audio, relative to the episode folder. */
41
+ audioPath?: string
42
+ /** What the take was for, when it said (`labelling` takes are not part of the conversation). */
43
+ purpose?: string
44
+ }
45
+
46
+ /** One reply from the seat, as the companion's phone page keeps it. */
47
+ export interface CompanionReply {
48
+ id: string
49
+ /** The take it answers, or null when the seat spoke first. */
50
+ take: string | null
51
+ text: string
52
+ /** Which seat wrote it, as the seat names itself (`claude-code@gaia`). */
53
+ seat: string
54
+ /** The tmux session the seat ran in, from the reply's origin. */
55
+ session?: string
56
+ at: string
57
+ related?: CompanionRelated[]
58
+ /** The person's ruling on the reply, when given. */
59
+ feedback?: CompanionFeedback
60
+ }
61
+
62
+ /** One voice-ledger record, reduced to what the conversation needs. */
63
+ export interface CompanionVoice {
64
+ id: string
65
+ at: string
66
+ text: string
67
+ persona: string
68
+ source?: string | null
69
+ /** A playable URL, or null when the record carries no audio. */
70
+ src: string | null
71
+ /** The tmux session of the voice's origin. */
72
+ session?: string
73
+ }
74
+
75
+ export interface CompanionTakeTurn extends CompanionTake {
76
+ kind: "take"
77
+ }
78
+
79
+ export interface CompanionReplyTurn extends CompanionReply {
80
+ kind: "reply"
81
+ /** Who speaks: the persona that voiced it, else the seat key in its session name. */
82
+ persona: string
83
+ /** Its voice, in the order of the text. Empty when it was never voiced. */
84
+ audio: CompanionVoice[]
85
+ /** True when no reply record was found and the turn was rebuilt from its voices. */
86
+ fromVoices?: boolean
87
+ }
88
+
89
+ export type CompanionTurn = CompanionTakeTurn | CompanionReplyTurn
90
+
91
+ export interface CompanionThread {
92
+ /** Takes and replies in the order they happened. */
93
+ turns: CompanionTurn[]
94
+ takes: number
95
+ replies: number
96
+ /** Sessions that wrote replies, newest last. */
97
+ sessions: string[]
98
+ }
99
+
100
+ /** The ledger `source` the companion's phone page voices its replies with. */
101
+ export const COMPANION_VOICE_SOURCE = "phone-capture"
102
+
103
+ /** True for a ledger voice that is a companion's reply, not another recording of the episode. */
104
+ export function isCompanionVoice(voice: { source?: string | null }): boolean {
105
+ return voice.source === COMPANION_VOICE_SOURCE
106
+ }
107
+
108
+ /** Take purposes that belong to something else than the conversation. */
109
+ const NOT_CONVERSATION = new Set(["labelling"])
110
+
111
+ /**
112
+ * What the phone page sends to the voice layer for a reply: the glyph labels,
113
+ * headings, list marks, emphasis, code ticks and link targets removed. Kept equal
114
+ * to `speakable` in jgwill/miadi-orchestration-kit
115
+ * `claude/mia-episode-companion/phone-capture/server.mjs`, so a voice can be found
116
+ * in the reply it was cut from.
117
+ */
118
+ export function speakable(text: string): string {
119
+ return text
120
+ .split("\n")
121
+ .map((line) => line.replace(/^\s*(🧠|🌸)\s*:?\s*/u, "").replace(/^#+\s*/, "").replace(/^\s*[-*]\s+/, ""))
122
+ .join("\n")
123
+ .replace(/\*\*|__|`/g, "")
124
+ .replace(/\[([^\]]+)\]\([^)]+\)/g, "$1")
125
+ .replace(/\n{3,}/g, "\n\n")
126
+ .trim()
127
+ }
128
+
129
+ /** Letters and digits only, lower case: what survives every joint between parts. */
130
+ function letters(text: string): string {
131
+ return text.toLowerCase().replace(/[^\p{L}\p{N}]+/gu, "")
132
+ }
133
+
134
+ const SESSION_SEAT = /^episode-\d+-([a-z][a-z0-9]*)-companion(?:-|$)/
135
+
136
+ /** The seat key a companion session name carries: `episode-120-mia-companion` → `mia`. */
137
+ export function seatOfSession(session: string | undefined): string | undefined {
138
+ return session ? SESSION_SEAT.exec(session)?.[1] : undefined
139
+ }
140
+
141
+ function time(at: string): number {
142
+ const t = Date.parse(at)
143
+ return Number.isFinite(t) ? t : 0
144
+ }
145
+
146
+ /** Voices close enough in time and from one session are one reply when no record names it. */
147
+ const VOICE_GAP_MS = 120_000
148
+
149
+ /**
150
+ * The conversation, in order. Every reply gets the voices cut from its text. A
151
+ * companion voice that no reply record holds becomes a reply of its own, so a
152
+ * host that cannot read the phone page's records still shows what the seat said.
153
+ */
154
+ export function buildCompanionThread(input: {
155
+ takes?: readonly CompanionTake[]
156
+ replies?: readonly CompanionReply[]
157
+ voices?: readonly CompanionVoice[]
158
+ }): CompanionThread {
159
+ const takes = (input.takes ?? []).filter((take) => !take.purpose || !NOT_CONVERSATION.has(take.purpose))
160
+ const replies = [...(input.replies ?? [])].sort((a, b) => time(a.at) - time(b.at))
161
+ const voices = (input.voices ?? []).filter(isCompanionVoice).sort((a, b) => time(a.at) - time(b.at))
162
+
163
+ const spoken = replies.map((reply) => letters(speakable(reply.text)))
164
+ const audio = new Map<string, { voice: CompanionVoice; offset: number }[]>()
165
+ const loose: CompanionVoice[] = []
166
+ for (const voice of voices) {
167
+ const said = letters(voice.text)
168
+ let found = -1
169
+ let offset = -1
170
+ if (said) {
171
+ // The latest reply posted before the voice was made that holds its words. A reply
172
+ // can be voiced long after it was posted (Hear Mia renders on demand), never before.
173
+ for (let i = replies.length - 1; i >= 0; i--) {
174
+ const at = spoken[i]!.indexOf(said)
175
+ if (at < 0) continue
176
+ if (found < 0) { found = i; offset = at }
177
+ if (time(replies[i]!.at) <= time(voice.at) + 60_000) { found = i; offset = at; break }
178
+ }
179
+ }
180
+ if (found < 0) { loose.push(voice); continue }
181
+ const id = replies[found]!.id
182
+ audio.set(id, [...(audio.get(id) ?? []), { voice, offset }])
183
+ }
184
+
185
+ const turns: CompanionTurn[] = takes.map((take) => ({ kind: "take", ...take }))
186
+ for (const reply of replies) {
187
+ const parts = (audio.get(reply.id) ?? []).sort((a, b) => a.offset - b.offset)
188
+ // A reply voiced twice keeps one voice per part: the first made.
189
+ const seen = new Set<number>()
190
+ const kept = parts.filter((p) => (seen.has(p.offset) ? false : (seen.add(p.offset), true))).map((p) => p.voice)
191
+ turns.push({
192
+ kind: "reply",
193
+ ...reply,
194
+ persona: kept[0]?.persona || seatOfSession(reply.session) || "companion",
195
+ audio: kept,
196
+ })
197
+ }
198
+ for (const group of groupVoices(loose)) {
199
+ const first = group[0]!
200
+ turns.push({
201
+ kind: "reply",
202
+ id: `voice:${first.id}`,
203
+ take: null,
204
+ text: group.map((v) => v.text).join("\n\n"),
205
+ seat: "",
206
+ ...(first.session ? { session: first.session } : {}),
207
+ at: first.at,
208
+ persona: first.persona || seatOfSession(first.session) || "companion",
209
+ audio: group,
210
+ fromVoices: true,
211
+ })
212
+ }
213
+ turns.sort((a, b) => time(a.at) - time(b.at))
214
+
215
+ const sessions: string[] = []
216
+ for (const turn of turns) {
217
+ if (turn.kind !== "reply" || !turn.session) continue
218
+ const at = sessions.indexOf(turn.session)
219
+ if (at >= 0) sessions.splice(at, 1)
220
+ sessions.push(turn.session)
221
+ }
222
+ return {
223
+ turns,
224
+ takes: turns.filter((t) => t.kind === "take").length,
225
+ replies: turns.filter((t) => t.kind === "reply").length,
226
+ sessions,
227
+ }
228
+ }
229
+
230
+ function groupVoices(voices: readonly CompanionVoice[]): CompanionVoice[][] {
231
+ const groups: CompanionVoice[][] = []
232
+ for (const voice of voices) {
233
+ const last = groups.at(-1)
234
+ const previous = last?.at(-1)
235
+ if (last && previous && previous.session === voice.session && time(voice.at) - time(previous.at) <= VOICE_GAP_MS) last.push(voice)
236
+ else groups.push([voice])
237
+ }
238
+ return groups
239
+ }
240
+
241
+ /** The take a reply answers, when it is in the thread. */
242
+ export function takeOf(thread: CompanionThread, reply: CompanionReplyTurn): CompanionTakeTurn | undefined {
243
+ return reply.take ? (thread.turns.find((t) => t.kind === "take" && t.id === reply.take) as CompanionTakeTurn | undefined) : undefined
244
+ }
245
+
246
+ /** `2026-10-12T15:32:05Z` → `2026-10-12 15:32 UTC`: the same on the server and in every browser. */
247
+ export function stampOf(at: string): string {
248
+ const m = /^(\d{4}-\d{2}-\d{2})T(\d{2}:\d{2})/.exec(at)
249
+ return m ? `${m[1]} ${m[2]} UTC` : at
250
+ }
251
+
252
+ /** `mia` → `Mia`. */
253
+ export function personaLabel(persona: string): string {
254
+ return persona ? persona[0]!.toUpperCase() + persona.slice(1) : persona
255
+ }