@marver-design/marver 0.27.2 → 0.28.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.
Files changed (64) hide show
  1. package/CHANGELOG.md +101 -0
  2. package/README.md +4 -2
  3. package/dist/{anchor-check-gkxkPAIv.mjs → anchor-check-PHUOFj1N.mjs} +1 -1
  4. package/dist/{audio-Dw1lfMdb.mjs → audio-DX4POHAj.mjs} +39 -4
  5. package/dist/{boards-BqUqKNW8.mjs → boards-BeWtjGUM.mjs} +49 -4
  6. package/dist/boards-EH2onUXM.mjs +995 -0
  7. package/dist/{build-VgNg4rr8.mjs → build-BsAyLMT1.mjs} +7 -5
  8. package/dist/{capture-vadKjuCo.mjs → capture-DdZ6xgoz.mjs} +92 -30
  9. package/dist/cli.mjs +37 -16
  10. package/dist/{comments-YEU1Zhv9.mjs → comments-CrBHPEQl.mjs} +2 -2
  11. package/dist/config-BezZTiov.mjs +182 -0
  12. package/dist/conn-BMiHS42T.mjs +222 -0
  13. package/dist/connectors-MR9d-EBP.mjs +290 -0
  14. package/dist/{context-Ccjrhr1J.mjs → context-BUnFiyA3.mjs} +2 -2
  15. package/dist/{daemon-Dc9AH0M3.mjs → daemon-C5dg2R-V.mjs} +2187 -182
  16. package/dist/{dev-ri6nAlRp.mjs → dev-D7YS7iT2.mjs} +22 -11
  17. package/dist/{init-W0nxR1OY.mjs → init-WE5lQkQL.mjs} +7 -2
  18. package/dist/jam-Cj5gBvwD.mjs +373 -0
  19. package/dist/{link-CdTgn94Y.mjs → link-BFFRgrMt.mjs} +3 -3
  20. package/dist/listener-DdLEM79A.mjs +80 -0
  21. package/dist/{manifest-aFyDmL8C.mjs → manifest-DPZ3WNg_.mjs} +1 -1
  22. package/dist/{marks-BF9pNEgH.mjs → marks-Dyn6tmjp.mjs} +3 -3
  23. package/dist/{marks-CnCCfAbD.mjs → marks-Kmdab_5w.mjs} +2 -2
  24. package/dist/{perf-DkAUFT6W.mjs → perf-Cn5LiRaY.mjs} +3 -3
  25. package/dist/{perf-jam-BaH3Lg0m.mjs → perf-jam-QxD_UnzN.mjs} +1 -1
  26. package/dist/permit-DDa6wqOs.mjs +187 -0
  27. package/dist/{plugin-B8UghYuF.mjs → plugin-C_0yb-Fq.mjs} +365 -518
  28. package/dist/{poster-BNgafWMK.mjs → poster-DHi6I1fO.mjs} +1 -1
  29. package/dist/{publish-bakes-38Nja78p.mjs → publish-bakes-r4PEZuPl.mjs} +2 -2
  30. package/dist/{queue-CAM_vNmX.mjs → queue-c-6aTHEz.mjs} +164 -25
  31. package/dist/{recover-B8AiI29B.mjs → recover-nrLEVLyJ.mjs} +1 -1
  32. package/dist/{session-BAaJsK5c.mjs → session-DyVE7cCk.mjs} +1 -1
  33. package/dist/{shot-Ch24tiMO.mjs → shot-BrRtqaiS.mjs} +7 -6
  34. package/dist/{shot-CMQgMVZm.mjs → shot-DBWN8hPP.mjs} +1 -1
  35. package/dist/sizes-wjXDev3b.mjs +139 -0
  36. package/dist/speech-worker.mjs +23 -3
  37. package/dist/transport-C5FnY9ni.mjs +203 -0
  38. package/dist/{work-Bxz-ObF3.mjs → work-BYWD_1Zf.mjs} +3 -3
  39. package/dist/{work-CNhFF9pU.mjs → work-DJxH7cCX.mjs} +1 -1
  40. package/docs/jam-session.md +39 -14
  41. package/docs/live-jam.md +92 -10
  42. package/package.json +1 -1
  43. package/src/client/shell/JamSurface.tsx +56 -21
  44. package/src/client/shell/icons.tsx +1 -0
  45. package/src/client/shell/jam-capture.ts +97 -22
  46. package/src/client/shell/jam-keys.ts +32 -6
  47. package/src/client/shell/jam-lane.tsx +14 -5
  48. package/src/client/shell/jam-lines.ts +66 -9
  49. package/src/client/shell/jam-panel.tsx +55 -3
  50. package/src/client/shell/jam-queue.ts +50 -8
  51. package/src/client/shell/jam-session.tsx +53 -4
  52. package/src/client/shell/jam-surface-parts.tsx +6 -3
  53. package/src/client/shell/jam-ui.tsx +6 -1
  54. package/src/client/shell/jam-voice-wait.ts +21 -0
  55. package/src/client/shell/jam-voice.ts +14 -5
  56. package/src/client/shell/styles.css +27 -11
  57. package/src/client/shell/tidy.ts +3 -2
  58. package/src/shared/approval.ts +20 -0
  59. package/src/shared/events.ts +1 -1
  60. package/templates/AGENTS-embedded.md +28 -1
  61. package/templates/AGENTS-studio.md +28 -1
  62. package/templates/instructions/boards.md +7 -1
  63. package/templates/instructions/jam.md +90 -0
  64. package/dist/boards-BHKP5yhI.mjs +0 -342
@@ -8,15 +8,53 @@ import type { Bundle, CaptureRecord } from '../../server/jam/types.ts'
8
8
  const ordinal = (n: number) => `${n}${n % 100 >= 11 && n % 100 <= 13 ? 'th' : ['th', 'st', 'nd', 'rd'][n % 10] ?? 'th'}`
9
9
  const clock = (ms: number) => { const s = Math.max(0, Math.floor(ms / 1000)); return `${Math.floor(s / 60)}:${String(s % 60).padStart(2, '0')}` }
10
10
 
11
+ /** Why a copy (or a fresh agent) runs it, in a few words, by the reason the canvas gave (daemon.ts, runs.ts): the one that
12
+ * matches, never a near one - any other reason as it was given. */
13
+ const whyShort = (w: string) => w.endsWith('it let it go') ? 'yours let it go' : w.startsWith('your session didn') ? 'yours was busy'
14
+ : w.startsWith('your session was idle') ? 'yours was idle' : w.startsWith('the Jam session had ended') ? 'the Jam session had ended' : w
15
+
16
+ /** Who runs a working card, in words (spec 29b): the tool at work, as its tile says it ("Claude Code is working · 0:42" -
17
+ * Nic, 29 Oct: "Your session" said nothing), then whose run it is - your session, a copy of it and why a copy took it, or
18
+ * a background run - and, for your session, where the run stands. `name` is the agent's name ("Claude Code"); unknown,
19
+ * "Agent". The detail is the working tile's tooltip too (laneTip), so the tile and the icon never disagree. */
20
+ export function runnerLine(c: JamCard, name: (agent: string) => string | undefined, now = Date.now()): { head: string; detail?: string } | null {
21
+ const r = c.runner
22
+ if (c.state !== 'working' || !r) return null
23
+ const tool = (r.agent && name(r.agent)) || undefined
24
+ const yours = tool ? `your ${tool} session` : 'your session'
25
+ const working = `${tool ?? 'Agent'} is working · ${clock(now - c.at)}`
26
+ if (r.kind === 'session') {
27
+ if (r.state === 'offered') return { head: `Dispatching · ${clock(now - c.at)}`, detail: `Offered to ${yours} - it takes the run when it is free` }
28
+ if (r.state === 'waiting') return { head: 'Waiting for your session', detail: 'Open Claude Code, Codex or Cursor in this repo - it takes the run' }
29
+ if (r.state === 'stalled') return { head: `No word from ${yours} for a while`, detail: 'Give it back, run it in the background, or drop it' }
30
+ if (r.state === 'stopping') return { head: `Stopping - waiting for ${yours} to let go`, detail: 'Its frames stay reserved until it does' }
31
+ return { head: working, detail: `In ${yours}${r.agent === 'claude' ? ' - a background subagent of it does the work' : ''}` }
32
+ }
33
+ const why = r.why ? ` (${whyShort(r.why)})` : ''
34
+ if (r.kind === 'fork') return { head: working, detail: `In a copy of ${yours}${why} - with your conversation, tools, MCP servers and skills` }
35
+ return { head: working, detail: `A background ${tool ?? 'agent'} run${why}` }
36
+ }
37
+
11
38
  /** What the icon's tooltip says: the state, then the detail - position, clock and agent, the reason
12
39
  * a held card waits, why a card failed. */
13
40
  export function statusLines(c: JamCard, agent: string | null, harness: Record<string, string>, now = Date.now()): { head: string; detail?: string } {
14
41
  const tags = c.events.length > 1 ? ` · ${c.events.length} tags` : ''
42
+ // waiting for more than its place (one runs alone, your session is full): why, never a place in line it does not have -
43
+ // and before a frame another run holds, which it waits for too: that run ending is not enough (Codex's review)
44
+ const w = c.waitsFor
45
+ const also = w ? `; ${w.by === 'chat' ? 'your agent in chat' : w.by ? `"${w.by}"` : 'another run'} is working on ${w.frame}` : ''
46
+ if (c.state === 'queued' && c.waiting === 'alone') return { head: `Queued · waits to run alone${tags}`, detail: `It ${c.exclusive ? 'changes a shared file' : 'names no frame'} and runs on its own - it starts once the other work is done${also}` }
47
+ if (c.state === 'queued' && c.waiting === 'behind') return { head: `Queued · waits - a run goes alone first${tags}`, detail: `A request that runs on its own goes first - this one starts after it${also}` }
48
+ if (c.state === 'queued' && w) {
49
+ return { head: `Queued · waits for ${w.frame}${tags}`, detail: w.by === 'chat' ? 'Your agent in chat is working on it - this one starts when it is done'
50
+ : w.by ? `"${w.by}" is working on it - this one starts when it is done` : 'Another run is working on it - this one starts when it is done' }
51
+ }
52
+ if (c.state === 'queued' && c.waiting === 'session') return { head: `Queued · waits - your session is full${tags}`, detail: 'Your session holds all the runs it can - this one goes to it when one of them ends' }
15
53
  if (c.state === 'queued') {
16
54
  const p = c.position ?? 1
17
- return { head: p <= 1 ? `Queued · next${tags}` : `Queued · ${ordinal(p)}${tags} - runs after ${p - 1} other${p - 1 === 1 ? '' : 's'}`, ...(c.waiting ? { detail: c.waiting } : {}) }
55
+ return { head: p <= 1 ? `Queued · next${tags}` : `Queued · ${ordinal(p)}${tags} - runs after ${p - 1} other${p - 1 === 1 ? '' : 's'}` }
18
56
  }
19
- if (c.state === 'working') return { head: `Agent working · ${clock(now - c.at)}${agent ? ` - ${harness[agent] ?? agent}` : ''}` }
57
+ if (c.state === 'working') return runnerLine(c, (a) => harness[a], now) ?? { head: `${(agent && harness[agent]) || 'Agent'} is working · ${clock(now - c.at)}` }
20
58
  if (c.state === 'asks') return { head: 'Asks you - see the question below' }
21
59
  if (c.state === 'failed') return { head: `Failed - ${c.note ?? 'the agent could not finish'}`, detail: 'Retry here, or tag @marver again' }
22
60
  return { head: c.state }
@@ -27,15 +65,30 @@ export function statusLines(c: JamCard, agent: string | null, harness: Record<st
27
65
  /** A card as the lane reads it: the queue's card, with its last run's shots when the view has them. */
28
66
  export type LaneCard = JamCard & { shots?: { frame: string; before?: string; after?: string }[] }
29
67
 
30
- /** A tile's status line (spec 27 Part 1): "To confirm", "Queued · 2nd", "Queued · next", "Agent
31
- * working · 0:41", "Asks you", "Ready to review", "Done · 2 frames", "Kept, not sent", "Failed ·
32
- * Retry". A queue position counts every queued card, tags included - they share one queue. */
33
- export function laneLine(c: LaneCard, now = Date.now()): string {
68
+ /** A tile's status line (spec 27 Part 1): "To confirm", "Queued · 2nd", "Queued · next", "Claude Code
69
+ * is working · 0:41", "Dispatching", "Asks you", "Ready to review", "Done · 2 frames", "Kept, not sent", "Failed ·
70
+ * Retry". A queue position counts every queued card, tags included - they share one queue. `name` is the agent's
71
+ * name ("Claude Code"); unknown, "Agent". */
72
+ export function laneLine(c: LaneCard, now = Date.now(), name: (agent: string) => string | undefined = () => undefined): string {
34
73
  switch (c.state) {
35
- case 'draft': return 'To confirm'
74
+ // a draft the queue would not take (a conflicting comment under its id - an E capture, or a confirm): it says
75
+ // so, never "To confirm" - E's never asked you to confirm anything
76
+ case 'draft': return c.note ? 'Not queued' : 'To confirm'
36
77
  case 'confirming': return 'Confirming'
37
- case 'queued': { const p = c.position ?? 1; return p <= 1 ? 'Queued · next' : `Queued · ${ordinal(p)}` }
38
- case 'working': return `Agent working · ${clock(now - c.at)}`
78
+ // waiting for one that runs alone, or on a frame another run holds: why, never a place in line it does not have (the
79
+ // run alone first - a frame's run ending is not enough while it waits for that too; Codex's review)
80
+ case 'queued': {
81
+ if (c.waiting) return c.waiting === 'alone' ? 'Waits to run alone' : c.waiting === 'session' ? 'Waits · your session is full' : 'Waits · a run goes alone first'
82
+ if (c.waitsFor) return `Waits for ${c.waitsFor.frame.split('/').pop()}`
83
+ const p = c.position ?? 1; return p <= 1 ? 'Queued · next' : `Queued · ${ordinal(p)}`
84
+ }
85
+ case 'working': {
86
+ // the tool at work, whoever runs it (Nic, 29 Oct: "Your session" and "a copy of your session" said nothing) - whose
87
+ // run it is, and why a copy took it, is the tile's tooltip (laneTip); your session not holding it yet says so
88
+ const r = c.runner
89
+ if (r?.kind === 'session' && r.state && r.state !== 'claimed') return r.state === 'offered' ? 'Dispatching' : r.state === 'waiting' ? 'Waiting for a session' : r.state === 'stalled' ? 'Stalled · choose' : 'Stopping'
90
+ return `${(r?.agent && name(r.agent)) || 'Agent'} is working · ${clock(now - c.at)}`
91
+ }
39
92
  case 'asks': return 'Asks you'
40
93
  case 'review': return 'Ready to review'
41
94
  case 'done': { const n = c.shots?.length ?? 0; return n ? `Done · ${n} frame${n === 1 ? '' : 's'}` : 'Done' }
@@ -45,6 +98,10 @@ export function laneLine(c: LaneCard, now = Date.now()): string {
45
98
  }
46
99
  }
47
100
 
101
+ /** A working tile's tooltip (0.28.0): whose run it is - your session, a copy of it and why, a background run - the
102
+ * status icon's own detail (runnerLine), so the two never disagree. Other tiles have none. */
103
+ export const laneTip = (c: LaneCard, name: (agent: string) => string | undefined): string | undefined => runnerLine(c, name)?.detail
104
+
48
105
  // ---- the read-back ---------------------------------------------------------------------------------
49
106
 
50
107
  /** One line of a capture's detail: its time in the capture, the kind of step, the words, the element's
@@ -146,6 +146,21 @@ function AddedNotes({ added, onAdd }: { added: { at: number; text: string }[]; o
146
146
  )
147
147
  }
148
148
 
149
+ /** The review pictures' shapes (width / height) by URL, learned as one loads in a review or ahead of it (preloadShots):
150
+ * a review opens at its pictures' width and layout, never the default first (Nic, 29 Oct: it collapsed, then grew). */
151
+ const shapes = new Map<string, number>()
152
+ const preloaded = new Set<string>()
153
+ /** A card's review pictures loaded ahead, each URL once - as the card is ready to review, before its review opens. */
154
+ export function preloadShots(urls: (string | undefined)[]) {
155
+ for (const url of urls) {
156
+ if (!url || preloaded.has(url)) continue
157
+ preloaded.add(url)
158
+ const im = new Image()
159
+ im.onload = () => { if (im.naturalWidth > 0 && im.naturalHeight > 0) shapes.set(url, im.naturalWidth / im.naturalHeight) }
160
+ im.src = url
161
+ }
162
+ }
163
+
149
164
  /** A picture, or the dashed "No picture" where a shot failed. */
150
165
  export function Shot({ url, cap, alt, onSize }: { url?: string; cap?: ReactNode; alt?: string; onSize?: (w: number, h: number) => void }) {
151
166
  // a picture that cannot load (gone, refused) is "No picture" too - never a broken image
@@ -188,7 +203,7 @@ const Meta = ({ items }: { items: ReactNode[] }) => (
188
203
  * capture made during a review; `err` = a confirm that failed closed; `warn` = degraded content
189
204
  * ("words may be incomplete").
190
205
  */
191
- export function ReadBack({ title, head, of, onPrev, onNext, meta, lines, pictures, edited, pending, editing, onEdit, onRetry, onConfirm, onKeep, onDrop, onResume, agent, follows, readOnly, locked, onOpenThread, added, onAddNote, autoNamed, err, warn, style }: {
206
+ export function ReadBack({ title, head, of, onPrev, onNext, meta, lines, pictures, edited, pending, editing, onEdit, onRetry, onConfirm, onKeep, onDrop, onResume, agent, follows, readOnly, locked, onOpenThread, added, onAddNote, autoNamed, err, warn, asks, style }: {
192
207
  title: string
193
208
  /** beside the title: the Review | Capture switch (a capture under review) */
194
209
  head?: ReactNode
@@ -224,6 +239,9 @@ export function ReadBack({ title, head, of, onPrev, onNext, meta, lines, picture
224
239
  onAddNote?: (text: string, id: string) => Promise<boolean>
225
240
  err?: ReactNode
226
241
  warn?: ReactNode
242
+ /** a capture whose run asks you something, opened here because its thread cannot show on this board: the question,
243
+ * and a field whose answer goes to its thread with @marver (an answer with a tag is what carries the work on) */
244
+ asks?: { question: string; onAnswer(text: string): Promise<boolean> }
227
245
  style?: CSSProperties
228
246
  }) {
229
247
  const [open, setOpen] = useState(!!editing)
@@ -255,6 +273,7 @@ export function ReadBack({ title, head, of, onPrev, onNext, meta, lines, picture
255
273
  </div>
256
274
  <Meta items={meta} />
257
275
  <div className="jm-body">
276
+ {asks && <AsksAnswer question={asks.question} onAnswer={asks.onAnswer} />}
258
277
  {follows && <div className="note-line info"><ArrowBendUpLeftIcon size={14} /><span>Follows <b style={{ color: 'var(--glass-ink)' }}>{follows}</b> - confirming sends that review back as more work</span></div>}
259
278
  {err && <div className="note-line err"><WarningIcon size={14} /><span>{err}</span></div>}
260
279
  {warn && <div className="note-line warn"><WarningIcon size={14} /><span>{warn}</span></div>}
@@ -291,6 +310,36 @@ export function ReadBack({ title, head, of, onPrev, onNext, meta, lines, picture
291
310
  )
292
311
  }
293
312
 
313
+ /** What a capture's run asked you, and your answer - for a thread this board cannot show (its frame is on no node
314
+ * here). Sent with @marver in its thread: the answer goes back to the agent, as a tagged reply does. */
315
+ function AsksAnswer({ question, onAnswer }: { question: string; onAnswer(text: string): Promise<boolean> }) {
316
+ const [text, setText] = useState('')
317
+ const [sending, setSending] = useState(false)
318
+ const send = () => {
319
+ if (!text.trim() || sending) return
320
+ setSending(true)
321
+ void onAnswer(text.trim()).then((ok) => { setSending(false); if (ok) setText('') })
322
+ }
323
+ return (
324
+ <div className="jm-asks" data-jam-asks="" style={{ display: 'flex', flexDirection: 'column', gap: 7 }}>
325
+ <div className="jm-reply">
326
+ <Marver size={20} />
327
+ <p>{question || 'It asks you something - see its thread.'}</p>
328
+ </div>
329
+ <div className="jm-more">
330
+ <span className="at">@marver</span>
331
+ <textarea className="txt" rows={1} value={text} placeholder="Your answer" disabled={sending}
332
+ onChange={(e) => setText(e.target.value)}
333
+ onKeyDown={(e) => {
334
+ e.stopPropagation()
335
+ if (e.key === 'Enter' && !e.shiftKey && !(e.nativeEvent as unknown as { isComposing?: boolean }).isComposing) { e.preventDefault(); send() }
336
+ }} />
337
+ <button className="jm-send" disabled={!text.trim() || sending} onClick={send}>Send <kbd>⏎</kbd></button>
338
+ </div>
339
+ </div>
340
+ )
341
+ }
342
+
294
343
  // ---- the review --------------------------------------------------------------------------------------
295
344
 
296
345
  /**
@@ -338,9 +387,11 @@ export function ReviewDetail({ title, head, of, onPrev, onNext, frames, active,
338
387
  const isNew = (f: string) => !!shots.find((s) => s.frame === f)?.new
339
388
  // the frame's shape, from its pictures as they load (After's, else Before's): taller than wide (or square) side by
340
389
  // side, wider than tall stacked - and the panel as wide as that needs (0.26.1, the owner's first real session)
390
+ // - known before it loads when it was preloaded, or shown before
341
391
  const [sizes, setSizes] = useState<Record<string, number>>({})
342
- const sized = (url?: string) => (url ? (w: number, h: number) => { if (w > 0 && h > 0) setSizes((m) => (m[url] === w / h ? m : { ...m, [url]: w / h })) } : undefined)
343
- const aspect = (shot?.after && sizes[shot.after]) || (shot?.before && sizes[shot.before]) || undefined
392
+ const sized = (url?: string) => (url ? (w: number, h: number) => { if (w > 0 && h > 0) { shapes.set(url, w / h); setSizes((m) => (m[url] === w / h ? m : { ...m, [url]: w / h })) } } : undefined)
393
+ const shape = (url?: string) => (url ? sizes[url] ?? shapes.get(url) : undefined)
394
+ const aspect = shape(shot?.after) || shape(shot?.before) || undefined
344
395
  // both slots whenever the frame has a before at all (either may read "No picture") - a missing After never hides a Before
345
396
  const both = view === 'both' && !!shot && !shot.new && !!(shot.before || shot.after)
346
397
  const side = (aspect ?? 1.6) <= 1.1
@@ -379,6 +430,7 @@ export function ReviewDetail({ title, head, of, onPrev, onNext, frames, active,
379
430
  // left on purpose (Esc cleared its words from the map): the composer's words go too; closed by a click
380
431
  // elsewhere, the map still holds them
381
432
  useEffect(() => { if (more) field.current?.focus(); else if (draftKey && !moreDrafts.has(draftKey)) setTextState('') }, [more])
433
+ // sent as More work, always: the canvas settles a note that only approves ("looks good") as Looks good
382
434
  const send = () => { if (text.trim()) onMore(text.trim()) }
383
435
  return (
384
436
  <div className="jm-panel jm-review" data-jam-review="" style={style}>
@@ -13,7 +13,7 @@ export type JamCardState = 'draft' | 'confirming' | 'queued' | 'working' | 'asks
13
13
  export interface JamCard {
14
14
  id: string; kind: 'comment' | 'capture' | 'wrapup'; board: string; thread?: string; frames: string[]; events: string[]
15
15
  state: JamCardState; note?: string; rev: number; made: number; order: number; at: number
16
- follows?: string; reply?: string; position?: number; waiting?: string; exclusive?: boolean; batch?: string
16
+ follows?: string; reply?: string; position?: number; waiting?: 'alone' | 'behind' | 'session'; waitsFor?: { frame: string; by?: string }; exclusive?: boolean; batch?: string
17
17
  // captures: the lane and the review
18
18
  title?: string; inRun?: boolean; shots?: { frame: string; before?: string; after?: string; same?: boolean; new?: boolean }[]
19
19
  reviewing?: { card: string; batch: string; rev: number }; edited?: string; added?: { at: number; text: string }[]; notes?: number; capture?: string
@@ -25,7 +25,14 @@ export interface JamCard {
25
25
  session?: string
26
26
  /** a session record: the file it writes */
27
27
  file?: string
28
+ /** who runs it now (spec 29b): your session, a copy of it, or a fresh agent - and where it stands */
29
+ runner?: JamRunner
28
30
  }
31
+ export interface JamRunner { kind: 'session' | 'fork' | 'fresh'; agent: string; state?: 'offered' | 'claimed' | 'stalled' | 'stopping' | 'waiting'; why?: string; batch: string; gen?: number }
32
+ /** A coding-agent session connected to this repo (spec 29b): the selected one takes the work while a Jam session runs. */
33
+ export interface JamSession { id: string; agent: 'claude' | 'codex' | 'cursor'; busy: boolean; selected: boolean; since: number; mode?: string }
34
+ /** What Jam does on this machine: the config with the start sheet's switches over it. */
35
+ export interface JamSettings { runner: 'auto' | 'session' | 'background'; session: boolean; context: 'fork' | 'fresh'; mcp: boolean; skills: boolean; others: boolean; sessionMax: number }
29
36
  /** The review's frames: the ones the run changed (all of them when none did - there is still a before
30
37
  * and after to look at). */
31
38
  export const changedShots = (shots: JamCard['shots']) => { const all = shots ?? []; const changed = all.filter((x) => !x.same); return changed.length ? changed : all }
@@ -38,11 +45,20 @@ interface QueueState {
38
45
  run: { since: number } | null
39
46
  /** the Jam session running now (spec 27 Part 5) */
40
47
  session: { id: string; since: number } | null
41
- load(): Promise<void>
48
+ /** the coding-agent sessions connected to this repo, and Jam's settings here (spec 29b) */
49
+ sessions: JamSession[]
50
+ settings: JamSettings | null
51
+ /** resolves true once the canvas answered with a view (applied, or overtaken by a newer one) - one built after the call */
52
+ /** the view now; `signal` lets a caller that stopped waiting cancel the request */
53
+ load(opts?: { signal?: AbortSignal }): Promise<boolean>
42
54
  apply(view: unknown): void
43
55
  /** A session this page ended (the server said so): gone at once, and no view shows it again */
44
56
  forget(session: string): void
45
57
  act(card: JamCard, action: JamAction, body?: string): Promise<boolean>
58
+ /** a session run's choice (spec 29b): give it back, run it in the background, drop it - at its generation */
59
+ runAct(card: JamCard, action: 'again' | 'background' | 'drop'): Promise<boolean>
60
+ /** the start sheet's switches, and which session takes the work */
61
+ setPrefs(p: { mcp?: boolean; skills?: boolean; context?: 'fork' | 'fresh'; others?: boolean; pick?: string | null }): Promise<boolean>
46
62
  }
47
63
 
48
64
  const csrf = () => /(?:^|;\s*)mv_c=([\w-]+)/.exec(document.cookie)?.[1] ?? ''
@@ -69,12 +85,20 @@ export const useJamQueue = create<QueueState>((set, get) => {
69
85
  agent: null,
70
86
  run: null,
71
87
  session: null,
72
- async load() {
73
- if (PUBLISHED) return
88
+ sessions: [],
89
+ settings: null,
90
+ async load(opts) {
91
+ if (PUBLISHED) return false
74
92
  try {
75
- const res = await api('jam/queue', { headers: { 'x-mv-c': csrf() } })
76
- if (res.ok) get().apply(await res.json())
77
- } catch { /* no queue: no icons */ }
93
+ const res = await api('jam/queue', { headers: { 'x-mv-c': csrf() }, ...(opts?.signal ? { signal: opts.signal } : {}) })
94
+ if (!res.ok) return false
95
+ const v = await res.json()
96
+ // the canvas's stand-in while its queue is not up (a restart) is not a view of it: never applied - it would
97
+ // empty the lane and end the session here (its microphone too) over what a push just brought
98
+ if ((v as { unavailable?: unknown } | null)?.unavailable) return false
99
+ get().apply(v)
100
+ return Array.isArray((v as { cards?: unknown } | null)?.cards)
101
+ } catch { return false /* no queue: no icons */ }
78
102
  },
79
103
  apply(view) {
80
104
  const v = (view && typeof view === 'object' ? view : {}) as { cards?: unknown; agent?: unknown }
@@ -90,8 +114,12 @@ export const useJamQueue = create<QueueState>((set, get) => {
90
114
  loaded = true
91
115
  const run = (v as { run?: { since?: unknown } }).run
92
116
  const ses = (v as { session?: { id?: unknown; since?: unknown } }).session
117
+ const sessions = (v as { sessions?: unknown }).sessions
118
+ const settings = (v as { settings?: unknown }).settings
93
119
  set({ cards: next, agent: typeof v.agent === 'string' ? v.agent : null, run: run && typeof run.since === 'number' ? { since: run.since } : null,
94
- session: ses && typeof ses.id === 'string' && typeof ses.since === 'number' && !over.has(ses.id) ? { id: ses.id, since: ses.since } : null })
120
+ session: ses && typeof ses.id === 'string' && typeof ses.since === 'number' && !over.has(ses.id) ? { id: ses.id, since: ses.since } : null,
121
+ sessions: Array.isArray(sessions) ? sessions.filter((x): x is JamSession => !!x && typeof x === 'object' && typeof (x as JamSession).id === 'string') : [],
122
+ settings: settings && typeof settings === 'object' ? settings as JamSettings : null })
95
123
  if (first) return
96
124
  // something to review: a soft chime, once per batch that leaves a capture to review, if the page
97
125
  // has focus - never a notice (spec 27, Part 2)
@@ -120,6 +148,20 @@ export const useJamQueue = create<QueueState>((set, get) => {
120
148
  await get().load() // the card as it is now (its new rev) before the caller acts again
121
149
  return !!res?.ok
122
150
  },
151
+ async runAct(card, action) {
152
+ if (!card.runner || card.runner.gen === undefined) return false
153
+ const res = await api('jam/run', {
154
+ method: 'POST', headers: { 'content-type': 'application/json', 'x-mv-c': csrf() },
155
+ body: JSON.stringify({ batch: card.runner.batch, gen: card.runner.gen, action }),
156
+ }).catch(() => null)
157
+ await get().load()
158
+ return !!res?.ok
159
+ },
160
+ async setPrefs(p) {
161
+ const res = await api('jam/prefs', { method: 'POST', headers: { 'content-type': 'application/json', 'x-mv-c': csrf() }, body: JSON.stringify(p) }).catch(() => null)
162
+ await get().load()
163
+ return !!res?.ok
164
+ },
123
165
  }
124
166
  })
125
167
 
@@ -18,7 +18,7 @@ import { JamStateIcon } from './jam-ui.tsx'
18
18
  import { Marver, moreDraftOf, setMoreDraft } from './jam-panel.tsx'
19
19
  import { useJamVoice, voiceSession, voiceSessionEnd, voiceSessionId } from './jam-voice.ts'
20
20
  import { HARNESS } from './Comments.tsx'
21
- import { ArrowRightIcon, CaretIcon, KeyboardIcon, MicrophoneIcon, MicrophoneSlashIcon, WarningIcon, WaveformIcon } from './icons.tsx'
21
+ import { ArrowRightIcon, CaretIcon, CommentIcon, KeyboardIcon, LinkIcon, MicrophoneIcon, MicrophoneSlashIcon, NotebookIcon, UserIcon, WarningIcon, WaveformIcon } from './icons.tsx'
22
22
  import { Tip } from './Tip.tsx'
23
23
  import { useSessionClock } from './jam-lane.tsx'
24
24
  import { CONFIG, stoppedFor, useStore } from './store.ts'
@@ -117,7 +117,7 @@ export function pressJ() {
117
117
  if (!ui.sheet && stoppedFor('Jam needs the canvas running')) return
118
118
  if (!useJamQueue.getState().session) { ui.setSheet(ui.sheet === 'start' ? null : 'start'); return }
119
119
  if (ui.sheet === 'wrap' || ui.sheet === 'wrap-pending') { ui.setSheet(null); return }
120
- if (useJamCapture.getState().current) { useJamCapture.getState().end(); ui.setSheet('wrap-pending'); return }
120
+ if (useJamCapture.getState().current) { useJamCapture.getState().end(true); ui.setSheet('wrap-pending'); return }
121
121
  ui.setSheet('wrap')
122
122
  }
123
123
 
@@ -156,7 +156,7 @@ export function JamButton({ inPlay }: { inPlay?: boolean }) {
156
156
 
157
157
  /** Jam's keys, one list: the shortcuts tooltip (the key table in jam-keys.ts is the source of truth). */
158
158
  export const JAM_KEYS: [string, string][] = [
159
- ['Start a capture', 'S'], ['End it', 'E'], ['Drop it', 'esc'], ['Add a note', 'N'], ['Picture of the frame', 'I'],
159
+ ['Start a capture', 'S'], ['Stop and queue it', 'E'], ['Stop to review it', '⇧E'], ['Drop it', 'esc'], ['Add a note', 'N'], ['Picture of the frame', 'I'],
160
160
  ['Resume a capture', 'R'], ['The captures', 'Q'], ['Open a capture', '⏎'], ['Keep it, not sent', 'K'], ['Review the next', 'V'], ['End the session', 'J'],
161
161
  ]
162
162
 
@@ -178,6 +178,55 @@ function ShortcutsRow() {
178
178
  )
179
179
  }
180
180
 
181
+ /** Who does the work, and with what (spec 29b): your own coding-agent session while the Jam session runs, a copy of
182
+ * it, or a background agent - and the three switches over what the runs Marver spawns may use. Starting the
183
+ * session connects every Claude Code, Codex and Cursor session in the repo; nothing else to set up. */
184
+ function WhoWorks({ fallback }: { fallback: string }) {
185
+ const sessions = useJamQueue((s) => s.sessions)
186
+ const settings = useJamQueue((s) => s.settings)
187
+ const agent = useJamQueue((s) => s.agent)
188
+ const [info, setInfo] = useState<{ connectors?: { agent: string; state: string; note?: string }[] } | null>(null)
189
+ useEffect(() => { api('jam/prefs', { headers: { 'x-mv-c': csrf() } }).then((r) => (r.ok ? r.json() : null)).then(setInfo, () => {}) }, [])
190
+ if (!settings) return <div className="row"><ArrowRightIcon size={15} /><span>Hands work to</span><span className="v"><span className="jm-agent"><i />{fallback}</span></span></div>
191
+ const sel = sessions.find((x) => x.selected)
192
+ const context = settings.context !== 'fresh'
193
+ const name = (a: string) => HARNESS[a] ?? a
194
+ const forks = agent === 'claude' || agent === 'codex' || sel?.agent === 'claude' || sel?.agent === 'codex'
195
+ const who = !settings.session || !context || settings.runner === 'background'
196
+ ? { line: `A background agent - ${name(agent ?? '')}`, small: context ? 'With your last session\'s context' : 'Starting fresh' }
197
+ : sel
198
+ ? { line: `Your ${name(sel.agent)} session`, small: sel.agent === 'claude' ? 'With everything it has' : 'While it works; idle, a copy of it' }
199
+ : { line: forks ? 'A copy of your last session' : `A background agent - ${name(agent ?? '')}`, small: 'Open your agent here and it joins' }
200
+ // several sessions: the next one takes the work (one click), until it ends
201
+ const next = sessions.length > 1 ? sessions[(sessions.findIndex((x) => x.selected) + 1) % sessions.length] : undefined
202
+ // the Codex hint only for someone who is not working in another session now: it is noise to a Claude Code user
203
+ const trust = !sel && info?.connectors?.some((c) => c.agent === 'codex' && c.state === 'installed') && !sessions.some((x) => x.agent === 'codex')
204
+ const set = useJamQueue.getState().setPrefs
205
+ const sw = (on: boolean) => <span className="v">{on ? 'On' : 'Off'}<i className={`jm-switch${on ? ' on' : ''}`} /></span>
206
+ return (<>
207
+ {(() => {
208
+ const body = (<>
209
+ <UserIcon size={15} />
210
+ <span>{who.line}<br /><small title={next ? `${sessions.length} sessions open - click for the next` : undefined}>{next ? `${sessions.length} open · click for the next` : who.small}</small></span>
211
+ {sel && <span className="v"><span className="jm-agent"><i /></span></span>}
212
+ </>)
213
+ return next
214
+ ? <button className="row jm-two" data-jam-who={sel ? sel.agent : 'background'} onClick={() => void set({ pick: next.id })}>{body}</button>
215
+ : <div className="row jm-two" data-jam-who={sel ? sel.agent : 'background'}>{body}</div>
216
+ })()}
217
+ <button className="row jm-two" data-jam-switch="mcp" onClick={() => void set({ mcp: !settings.mcp, skills: !settings.mcp })}>
218
+ <LinkIcon size={15} /><span>MCP servers and skills<br /><small>Background runs use yours</small></span>{sw(settings.mcp)}
219
+ </button>
220
+ <button className="row jm-two" data-jam-switch="context" onClick={() => void set({ context: context ? 'fresh' : 'fork' })}>
221
+ <NotebookIcon size={15} /><span>Your session's context<br /><small>Your session or a copy works</small></span>{sw(context)}
222
+ </button>
223
+ <button className="row jm-two" data-jam-switch="others" onClick={() => void set({ others: !settings.others })}>
224
+ <CommentIcon size={15} /><span>Collaborators' comments<br /><small>Their words reach the agent</small></span>{sw(settings.others)}
225
+ </button>
226
+ {trust && <div className="note-line" style={{ margin: '4px 8px' }}><WarningIcon size={14} /><span>Codex runs go to a copy of your session. To let your open Codex session take them itself, type <code style={{ color: 'inherit' }}>/hooks</code> in Codex once and trust Marver's.</span></div>}
227
+ </>)
228
+ }
229
+
181
230
  export function StartSheet({ style }: { style?: CSSProperties }) {
182
231
  const agent = useJamQueue((s) => s.agent)
183
232
  const voice = useJamVoice()
@@ -196,7 +245,7 @@ export function StartSheet({ style }: { style?: CSSProperties }) {
196
245
  <span className="v">{mic ? 'On' : 'Off'}<i className={`jm-switch${mic ? ' on' : ''}`} /></span>
197
246
  </button>
198
247
  {name
199
- ? <div className="row"><ArrowRightIcon size={15} /><span>Hands work to</span><span className="v"><span className="jm-agent"><i />{name}</span></span></div>
248
+ ? <WhoWorks fallback={name} />
200
249
  : <div className="note-line warn" style={{ margin: '4px 0' }}><WarningIcon size={14} /><span>No coding agent found - work waits in the queue.<br /><code style={{ color: 'inherit', opacity: .8 }}>npx marver init</code> sets one up.</span></div>}
201
250
  </div>
202
251
  <ShortcutsRow />
@@ -67,15 +67,18 @@ export function FocusPanelView(p: {
67
67
  onPrev?: () => void; onNext?: () => void; pending?: string; onRetry?: () => void; locked?: boolean
68
68
  /** a note added in the read-back (a draft) */
69
69
  onAddNote?(text: string, id: string): Promise<boolean>
70
+ /** a card that asks, opened here (its thread cannot show on this board): its question and your answer */
71
+ asks?: { question: string; onAnswer(text: string): Promise<boolean> }
70
72
  }) {
71
73
  const c = p.card
72
74
  const title = c.title ?? 'Capture'
73
75
  // a capture under review: its review, or the capture itself as it was read back (its pictures, its timeline)
74
76
  const [pane, setPane] = useState<'review' | 'capture'>('review')
75
77
  useEffect(() => { setPane('review') }, [c.id])
76
- // the review asks for the width its pictures need (both at once, as big as the panel's height allows)
78
+ // the review asks for the width its pictures need (both at once, as big as the panel's height allows) - each card's
79
+ // review (keyed by it) asks as it mounts, before it paints: a reset here after that would undo a width its preloaded
80
+ // pictures gave it, and the panel would open narrow, then grow
77
81
  const [fit, setFit] = useState<number | undefined>(undefined)
78
- useEffect(() => { setFit(undefined) }, [c.id])
79
82
  const head = p.kind === 'review' ? (
80
83
  <div className="jm-ftabs jm-panes" role="tablist" data-jam-panes="">
81
84
  {(['review', 'capture'] as const).map((v) => <button key={v} role="tab" aria-selected={v === pane} className={v === pane ? 'on' : undefined} onClick={() => setPane(v)}>{v === 'review' ? 'Review' : 'Capture'}</button>)}
@@ -99,7 +102,7 @@ export function FocusPanelView(p: {
99
102
  readOnly={c.state !== 'draft'} locked={p.locked} agent={p.agent}
100
103
  follows={c.reviewing ? p.reviewedTitle ?? 'the review on screen' : undefined}
101
104
  onEdit={p.onEdit} onConfirm={p.onConfirm} onKeep={p.onKeep} onDrop={p.onDrop} onResume={c.state === 'draft' ? p.onResume : undefined} onOpenThread={c.thread ? p.onOpenThread : undefined}
102
- onRetry={c.state === 'failed' ? p.onRetry : undefined} />
105
+ onRetry={c.state === 'failed' ? p.onRetry : undefined} asks={c.state === 'asks' ? p.asks : undefined} />
103
106
  )}
104
107
  </FocusPanel>
105
108
  )
@@ -83,6 +83,8 @@ export function TagStatus({ board, eventId, harness }: { board?: string; eventId
83
83
  if (!card) return null
84
84
  const { head, detail } = statusLines(card, agent, harness)
85
85
  const move = card.state === 'queued' ? 'drop' : card.state === 'failed' ? 'retry' : null
86
+ // a run your session went quiet on (spec 29b): the owner's three choices, by the run and its generation
87
+ const stalled = card.state === 'working' && card.runner?.kind === 'session' && card.runner.state === 'stalled'
86
88
  const lines = <span className="sh-tip-lines"><b>{head}</b>{detail && <small>{detail}</small>}</span>
87
89
  return (
88
90
  <span className={`cm-tstat${open ? ' on' : ''}`} ref={ref} data-jam-card={card.id} data-jam-state={card.state}>
@@ -94,9 +96,12 @@ export function TagStatus({ board, eventId, harness }: { board?: string; eventId
94
96
  </Tip>
95
97
  )}
96
98
  {open && (
97
- <span className="cm-tstat-pop" role="dialog" aria-label={head} ref={popRef}>
99
+ <span className={`cm-tstat-pop${stalled ? ' many' : ''}`} role="dialog" aria-label={head} ref={popRef}>
98
100
  {lines}
99
101
  {move && <button className="cm-tstat-act" onClick={() => { void useJamQueue.getState().act(card, move); setOpen(false) }}>{move === 'drop' ? 'Drop' : 'Retry'}</button>}
102
+ {stalled && ([['again', 'Give it back'], ['background', 'Run in the background'], ['drop', 'Drop it']] as const).map(([a, label]) => (
103
+ <button key={a} className="cm-tstat-act" data-jam-run-act={a} onClick={() => { void useJamQueue.getState().runAct(card, a); setOpen(false) }}>{label}</button>
104
+ ))}
100
105
  </span>
101
106
  )}
102
107
  </span>
@@ -0,0 +1,21 @@
1
+ /**
2
+ * When a capture's words are whole, and how long its last words are waited for (jam-voice.ts) - pure, so a test
3
+ * holds them to it.
4
+ */
5
+
6
+ /** A segment's last words are waited for this long after it is cut - and as long again after the speech engine was
7
+ * last heard from (words or a final, for any segment: it is working through what it was given - a cold start of its
8
+ * process, a long last phrase, other phrases ahead of it) - never past FINAL_MAX. Past it the capture seals without
9
+ * them, and a capture stopped with E goes straight on (27 Oct: one reached the agent with no words; the wait was a
10
+ * flat 3 s). A lost engine or connection answers at once, never this late. */
11
+ export const FINAL_MS = 15_000
12
+ export const FINAL_MAX = 60_000
13
+
14
+ /** How much longer to wait for a final, cut at `cut`, with the engine last heard at `heard` (ms; <= 0: stop waiting). */
15
+ export const finalWait = (cut: number, heard: number, now: number): number => Math.min(Math.max(cut, heard) + FINAL_MS, cut + FINAL_MAX) - now
16
+
17
+ /** A capture's words are whole when every segment cut for it came back final and none was lost - and, when you said
18
+ * yes to the microphone, when it had one at all: the engine not available, the microphone still opening (or refused)
19
+ * hears nothing, and those words are missing, not complete. */
20
+ export const wordsWhole = (finals: boolean[], lost: boolean, expected: boolean): boolean =>
21
+ (finals.length > 0 || !expected) && finals.every(Boolean) && !lost
@@ -19,9 +19,10 @@ import { create } from 'zustand'
19
19
  import { ROUTE } from '../const.ts'
20
20
  import { CONFIG, useStore } from './store.ts'
21
21
  import { api } from './api.ts'
22
+ import { finalWait, FINAL_MS, wordsWhole } from './jam-voice-wait.ts'
22
23
 
23
24
  export const RATE = 16_000
24
- const FINAL_MS = 3_000
25
+ // how long a segment's last words are waited for: jam-voice-wait.ts (FINAL_MS, longer while the engine is heard from)
25
26
  const CHUNK = 1_600 // 100 ms
26
27
 
27
28
  const csrf = () => /(?:^|;\s*)mv_c=([\w-]+)/.exec(document.cookie)?.[1] ?? ''
@@ -164,6 +165,8 @@ let wsOpen: Promise<WebSocket | null> | null = null
164
165
  const finals = new Map<string, (complete: boolean) => void>() // segment -> its final
165
166
  let toldUnavailable = false
166
167
  let takenOver = false
168
+ /** when the speech engine last answered (words or a final): a final still to come is waited for longer while it works */
169
+ let engineAt = 0
167
170
 
168
171
  const setLive = () => useJamVoice.setState({ live: !!mic && !mic.closed, hearing: mic && !mic.closed && mic.seg?.owner.kind === 'capture' ? mic.seg.owner.id : null })
169
172
 
@@ -183,6 +186,7 @@ function socket(reclaim = false): Promise<WebSocket | null> {
183
186
  let m: any
184
187
  try { m = JSON.parse(String(e.data)) } catch { return }
185
188
  if (typeof m?.capture !== 'string') return
189
+ if (m.type === 'words' || m.type === 'final') engineAt = Date.now()
186
190
  const owner = owners.get(m.capture)
187
191
  if (m.type === 'words' && Array.isArray(m.words)) {
188
192
  if (!owner || owner.kind !== 'capture' || !accepting.has(owner.id)) return // talk goes to the transcript on the server
@@ -306,8 +310,12 @@ function endSegment(s: Segment, at: { start: number; pcm: Int16Array; mark: numb
306
310
  const clean = !!at && s.from >= 0
307
311
  if (clean) sendChunk(s, at!.start, at!.pcm)
308
312
  const lastSample = clean ? s.base + at!.mark - s.from : s.sent
313
+ const cut = Date.now()
309
314
  const done = !ws || ws.readyState !== WebSocket.OPEN ? Promise.resolve(false) : new Promise<boolean>((res) => {
310
- const t = setTimeout(() => { finals.delete(s.seg); res(false) }, FINAL_MS)
315
+ // FINAL_MS after the cut - longer while the engine keeps answering (it is working through what came before)
316
+ let t: ReturnType<typeof setTimeout>
317
+ const wait = () => { const ms = finalWait(cut, engineAt, Date.now()); if (ms > 0) t = setTimeout(wait, ms); else { finals.delete(s.seg); res(false) } }
318
+ t = setTimeout(wait, FINAL_MS)
311
319
  finals.set(s.seg, (complete) => { clearTimeout(t); res(complete && clean) })
312
320
  ws!.send(JSON.stringify({ type: 'end', capture: s.seg, lastSample }))
313
321
  })
@@ -448,12 +456,13 @@ async function begin() {
448
456
  await reconcile()
449
457
  }
450
458
 
451
- /** Every segment of an owner ended: true when all its words came back whole. */
459
+ /** Every segment of an owner ended: true when all its words came back whole - and, with the microphone on for this
460
+ * canvas, when it heard the owner at all (an engine not available, a microphone still opening or refused: none). */
452
461
  async function settled(owner: string): Promise<boolean> {
453
462
  const list = cuts.get(owner) ?? []
454
463
  cuts.delete(owner)
455
464
  const all = await Promise.all(list)
456
- const ok = all.every(Boolean) && !broken.has(owner)
465
+ const ok = wordsWhole(all, broken.has(owner), useJamVoice.getState().choice === 'yes')
457
466
  broken.delete(owner)
458
467
  return ok
459
468
  }
@@ -469,7 +478,7 @@ export async function voiceBegin(id: string, t0: number) {
469
478
  }
470
479
 
471
480
  /** A capture ends: its audio cut at this instant (in a session the talk goes on from it), its words awaited
472
- * (3 s at most). Resolves true when the words are complete, false when they may not be. */
481
+ * (jam-voice-wait.ts). Resolves true when the words are complete, false when they may not be. */
473
482
  export async function voiceEnd(id: string): Promise<boolean> {
474
483
  if (capture?.id === id) capture = null
475
484
  useJamVoice.setState((st) => ({ asking: st.asking && st.choice === null && !session ? false : st.asking }))