fascicle 0.3.3 → 0.3.8

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.
@@ -0,0 +1,374 @@
1
+ <!doctype html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="utf-8" />
5
+ <meta name="viewport" content="width=device-width,initial-scale=1" />
6
+ <title>fascicle viewer</title>
7
+ <style>
8
+ :root {
9
+ color-scheme: light;
10
+ --fg: #1f2328;
11
+ --muted: #57606a;
12
+ --bg: #f6f7f8;
13
+ --panel: #ffffff;
14
+ --border: #d0d7de;
15
+ --accent: #b08900;
16
+ --accent-soft: #fff4c2;
17
+ --error: #a53a2c;
18
+ --error-soft: #fbe1dc;
19
+ --pulse: #cce4ff;
20
+ }
21
+ * { box-sizing: border-box }
22
+ html, body { margin: 0; height: 100% }
23
+ body {
24
+ font: 13px/1.4 ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
25
+ color: var(--fg);
26
+ background: var(--bg);
27
+ }
28
+ header {
29
+ display: flex; align-items: center; gap: 12px;
30
+ padding: 8px 12px;
31
+ background: var(--panel);
32
+ border-bottom: 1px solid var(--border);
33
+ }
34
+ header h1 { margin: 0; font: inherit; font-weight: 600 }
35
+ header .conn { color: var(--muted) }
36
+ header .conn.ok { color: #1a7f37 }
37
+ header .conn.err { color: var(--error) }
38
+ header label { color: var(--muted) }
39
+ header select { font: inherit; padding: 2px 4px; border: 1px solid var(--border); background: #fff }
40
+ main {
41
+ display: grid;
42
+ grid-template-columns: minmax(0, 1fr) minmax(0, 1fr);
43
+ gap: 0;
44
+ height: calc(100vh - 38px);
45
+ }
46
+ section { overflow: auto; padding: 8px 12px; background: var(--panel); }
47
+ section + section { border-left: 1px solid var(--border) }
48
+ h2 { margin: 0 0 8px 0; font: inherit; font-weight: 600; color: var(--muted); text-transform: uppercase; letter-spacing: 0.05em }
49
+ ul.tree { list-style: none; margin: 0; padding-left: 0 }
50
+ ul.tree ul { list-style: none; margin: 0; padding-left: 16px; border-left: 1px dotted var(--border) }
51
+ .node {
52
+ display: flex; gap: 8px; align-items: baseline;
53
+ padding: 2px 6px; border-radius: 4px;
54
+ }
55
+ .node .label { font-weight: 600 }
56
+ .node .kind { color: var(--muted); font-size: 11px; padding: 0 4px; border: 1px solid var(--border); border-radius: 3px }
57
+ .node .id { color: var(--muted); font-size: 11px }
58
+ .node .elapsed { margin-left: auto; color: var(--muted); font-size: 11px }
59
+ .node .cost { color: var(--accent); font-size: 11px; padding-left: 6px; font-variant-numeric: tabular-nums }
60
+ .node.running { background: var(--accent-soft); animation: pulse 1.6s ease-in-out infinite }
61
+ .node.errored { background: var(--error-soft); color: var(--error) }
62
+ .node.suspended { background: #ececec; font-style: italic }
63
+ .node.emit-flash { background: var(--pulse); transition: background 200ms }
64
+ @keyframes pulse {
65
+ 0%, 100% { background: var(--accent-soft) }
66
+ 50% { background: #ffe690 }
67
+ }
68
+ .log {
69
+ font-size: 12px;
70
+ }
71
+ .log .row {
72
+ display: grid; grid-template-columns: 80px 90px 130px 1fr;
73
+ gap: 8px; padding: 2px 0; border-bottom: 1px solid var(--border);
74
+ cursor: pointer;
75
+ }
76
+ .log .row:hover { background: var(--bg) }
77
+ .log .row .ts { color: var(--muted) }
78
+ .log .row .kind { font-weight: 600 }
79
+ .log .row .span { color: var(--muted); white-space: nowrap; overflow: hidden; text-overflow: ellipsis }
80
+ .log .row .payload { white-space: nowrap; overflow: hidden; text-overflow: ellipsis; color: var(--muted) }
81
+ .log .row.err .kind { color: var(--error) }
82
+ details { margin: 6px 0 }
83
+ details > pre { background: var(--bg); padding: 8px; overflow: auto; margin: 4px 0 0 0; border: 1px solid var(--border); border-radius: 4px }
84
+ .empty { color: var(--muted); padding: 16px 0 }
85
+ footer { color: var(--muted); padding: 4px 12px; border-top: 1px solid var(--border); background: var(--panel); font-size: 11px }
86
+ </style>
87
+ </head>
88
+ <body>
89
+ <header>
90
+ <h1>fascicle viewer</h1>
91
+ <span class="conn" id="conn">connecting…</span>
92
+ <label>run:
93
+ <select id="run-filter"><option value="">all</option></select>
94
+ </label>
95
+ <span style="margin-left:auto" id="counts"></span>
96
+ </header>
97
+ <main>
98
+ <section>
99
+ <h2>spans</h2>
100
+ <div id="tree"></div>
101
+ </section>
102
+ <section>
103
+ <h2>events</h2>
104
+ <div class="log" id="log"></div>
105
+ </section>
106
+ </main>
107
+ <footer id="footer">localhost dev tool — no auth, no persistence</footer>
108
+ <script>
109
+ (() => {
110
+ const $tree = document.getElementById('tree')
111
+ const $log = document.getElementById('log')
112
+ const $conn = document.getElementById('conn')
113
+ const $filter = document.getElementById('run-filter')
114
+ const $counts = document.getElementById('counts')
115
+
116
+ const spans = new Map()
117
+ const roots = []
118
+ const log_rows = []
119
+ const run_ids = new Set()
120
+ const open_stacks = new Map() // run_id -> [span_id...] (deepest last)
121
+ const cost_by_run = new Map() // run_id -> total cost in usd
122
+ let unattributed_cost = 0 // cost events with no matching run / open span
123
+ let active_run = ''
124
+ let total = 0
125
+ let errors = 0
126
+
127
+ function empty_message(text) {
128
+ const div = document.createElement('div')
129
+ div.className = 'empty'
130
+ div.textContent = text
131
+ return div
132
+ }
133
+
134
+ $tree.replaceChildren(empty_message('waiting for events…'))
135
+
136
+ $filter.addEventListener('change', () => {
137
+ active_run = $filter.value
138
+ render_tree()
139
+ render_log()
140
+ })
141
+
142
+ function set_conn(state, label) {
143
+ $conn.className = 'conn ' + state
144
+ $conn.textContent = label
145
+ }
146
+
147
+ function ensure_run(id) {
148
+ if (!id || run_ids.has(id)) return
149
+ run_ids.add(id)
150
+ const opt = document.createElement('option')
151
+ opt.value = id
152
+ opt.textContent = id
153
+ $filter.appendChild(opt)
154
+ }
155
+
156
+ function span_visible(span) {
157
+ if (!active_run) return true
158
+ return span.run_id === active_run
159
+ }
160
+
161
+ function format_elapsed(span) {
162
+ if (!span.started_at) return ''
163
+ const end = span.ended_at ?? Date.now()
164
+ const ms = Math.max(0, end - span.started_at)
165
+ if (ms < 1000) return ms + 'ms'
166
+ return (ms / 1000).toFixed(2) + 's'
167
+ }
168
+
169
+ function format_cost(usd) {
170
+ // < 1¢ shown to 4 decimals, otherwise to 2 decimals (per spec/eval.md §5)
171
+ if (usd < 0.01) return '$' + usd.toFixed(4)
172
+ return '$' + usd.toFixed(2)
173
+ }
174
+
175
+ function span_cost_total(span) {
176
+ // Direct cost on this span plus the rolled-up cost of every descendant.
177
+ let sum = span.cost_self
178
+ for (const cid of span.children) {
179
+ const child = spans.get(cid)
180
+ if (child) sum += span_cost_total(child)
181
+ }
182
+ return sum
183
+ }
184
+
185
+ function render_tree() {
186
+ if (spans.size === 0) {
187
+ $tree.replaceChildren(empty_message('waiting for events…'))
188
+ return
189
+ }
190
+ const ul = document.createElement('ul')
191
+ ul.className = 'tree'
192
+ for (const id of roots) {
193
+ const span = spans.get(id)
194
+ if (!span || !span_visible(span)) continue
195
+ ul.appendChild(render_node(span))
196
+ }
197
+ $tree.replaceChildren(ul)
198
+ }
199
+
200
+ function render_node(span) {
201
+ const li = document.createElement('li')
202
+ const node = document.createElement('div')
203
+ node.className = 'node ' + span.state
204
+ if (span.flash_until && span.flash_until > Date.now()) node.classList.add('emit-flash')
205
+ const label = document.createElement('span')
206
+ label.className = 'label'
207
+ label.textContent = span.label
208
+ node.appendChild(label)
209
+ if (span.kind && span.kind !== span.label) {
210
+ const kind = document.createElement('span')
211
+ kind.className = 'kind'
212
+ kind.textContent = span.kind
213
+ node.appendChild(kind)
214
+ }
215
+ const sid = document.createElement('span')
216
+ sid.className = 'id'
217
+ sid.textContent = span.span_id
218
+ const elapsed = document.createElement('span')
219
+ elapsed.className = 'elapsed'
220
+ elapsed.textContent = format_elapsed(span)
221
+ node.appendChild(sid)
222
+ node.appendChild(elapsed)
223
+ const cost = span_cost_total(span)
224
+ if (cost > 0) {
225
+ const cost_el = document.createElement('span')
226
+ cost_el.className = 'cost'
227
+ cost_el.textContent = format_cost(cost)
228
+ node.appendChild(cost_el)
229
+ }
230
+ li.appendChild(node)
231
+ if (span.children.length) {
232
+ const ul = document.createElement('ul')
233
+ for (const cid of span.children) {
234
+ const child = spans.get(cid)
235
+ if (child) ul.appendChild(render_node(child))
236
+ }
237
+ li.appendChild(ul)
238
+ }
239
+ return li
240
+ }
241
+
242
+ function render_log() {
243
+ const visible = log_rows.filter((r) => !active_run || r.run_id === active_run)
244
+ const slice = visible.slice(-200)
245
+ $log.replaceChildren()
246
+ for (const row of slice) {
247
+ const div = document.createElement('div')
248
+ div.className = 'row' + (row.kind === 'error' ? ' err' : '')
249
+ const ts = document.createElement('span'); ts.className = 'ts'
250
+ ts.textContent = new Date(row.ts).toLocaleTimeString()
251
+ const kind = document.createElement('span'); kind.className = 'kind'; kind.textContent = row.kind
252
+ const span = document.createElement('span'); span.className = 'span'; span.textContent = row.span_id ?? ''
253
+ const payload = document.createElement('span'); payload.className = 'payload'
254
+ payload.textContent = row.preview
255
+ div.appendChild(ts); div.appendChild(kind); div.appendChild(span); div.appendChild(payload)
256
+ div.addEventListener('click', () => {
257
+ const open = div.nextSibling
258
+ if (open && open.tagName === 'DETAILS') { open.remove(); return }
259
+ const det = document.createElement('details')
260
+ det.open = true
261
+ const pre = document.createElement('pre')
262
+ pre.textContent = JSON.stringify(row.event, null, 2)
263
+ det.appendChild(pre)
264
+ div.after(det)
265
+ })
266
+ $log.appendChild(div)
267
+ }
268
+ let cost_total
269
+ if (active_run) {
270
+ cost_total = cost_by_run.get(active_run) ?? 0
271
+ } else {
272
+ cost_total = unattributed_cost
273
+ for (const v of cost_by_run.values()) cost_total += v
274
+ }
275
+ const cost_label = cost_total > 0 ? ' · ' + format_cost(cost_total) : ''
276
+ $counts.textContent = total + ' events · ' + errors + ' errors' + cost_label
277
+ }
278
+
279
+ function preview(event) {
280
+ const { kind, span_id, run_id, parent_span_id, name, ...rest } = event
281
+ const txt = JSON.stringify(rest)
282
+ return txt.length > 100 ? txt.slice(0, 100) + '…' : txt
283
+ }
284
+
285
+ function ingest(event) {
286
+ total++
287
+ ensure_run(event.run_id)
288
+ const ts = Date.now()
289
+ if (event.kind === 'span_start') {
290
+ const span = {
291
+ span_id: event.span_id,
292
+ label: event.id ?? event.name,
293
+ kind: event.name,
294
+ run_id: event.run_id,
295
+ parent_span_id: event.parent_span_id,
296
+ state: 'running',
297
+ children: [],
298
+ started_at: ts,
299
+ ended_at: null,
300
+ flash_until: 0,
301
+ cost_self: 0,
302
+ }
303
+ spans.set(event.span_id, span)
304
+ if (event.parent_span_id && spans.has(event.parent_span_id)) {
305
+ spans.get(event.parent_span_id).children.push(event.span_id)
306
+ } else {
307
+ roots.push(event.span_id)
308
+ }
309
+ const stack_key = event.run_id ?? ''
310
+ if (!open_stacks.has(stack_key)) open_stacks.set(stack_key, [])
311
+ open_stacks.get(stack_key).push(event.span_id)
312
+ } else if (event.kind === 'span_end') {
313
+ const span = spans.get(event.span_id)
314
+ if (span) {
315
+ span.ended_at = ts
316
+ const has_error = event.error !== undefined
317
+ span.state = has_error ? 'errored' : 'done'
318
+ if (has_error) errors++
319
+ }
320
+ const stack_key = event.run_id ?? ''
321
+ const stack = open_stacks.get(stack_key)
322
+ if (stack) {
323
+ const idx = stack.lastIndexOf(event.span_id)
324
+ if (idx !== -1) stack.splice(idx, 1)
325
+ }
326
+ } else if (event.kind === 'cost') {
327
+ const usd = typeof event.total_usd === 'number' ? event.total_usd : 0
328
+ const run_key = event.run_id ?? ''
329
+ cost_by_run.set(run_key, (cost_by_run.get(run_key) ?? 0) + usd)
330
+ const stack = open_stacks.get(run_key)
331
+ const target_id = stack && stack.length > 0 ? stack[stack.length - 1] : null
332
+ const target = target_id ? spans.get(target_id) : null
333
+ if (target) target.cost_self += usd
334
+ else unattributed_cost += usd
335
+ } else if (event.kind === 'emit') {
336
+ const span = spans.get(event.span_id)
337
+ if (span) span.flash_until = ts + 200
338
+ } else if (event.kind === 'error') {
339
+ errors++
340
+ const span = spans.get(event.span_id)
341
+ if (span) span.state = 'errored'
342
+ } else if (event.kind === 'suspend') {
343
+ const span = spans.get(event.span_id)
344
+ if (span) span.state = 'suspended'
345
+ }
346
+ log_rows.push({
347
+ ts,
348
+ kind: event.kind,
349
+ span_id: event.span_id,
350
+ run_id: event.run_id,
351
+ event,
352
+ preview: preview(event),
353
+ })
354
+ if (log_rows.length > 5000) log_rows.splice(0, log_rows.length - 5000)
355
+ render_tree()
356
+ render_log()
357
+ }
358
+
359
+ function connect() {
360
+ const es = new EventSource('/api/events')
361
+ es.addEventListener('open', () => set_conn('ok', 'live'))
362
+ es.addEventListener('error', () => set_conn('err', 'reconnecting…'))
363
+ es.addEventListener('trajectory', (e) => {
364
+ try { ingest(JSON.parse(e.data)) } catch {}
365
+ })
366
+ es.addEventListener('close', () => { es.close(); set_conn('err', 'closed') })
367
+ }
368
+
369
+ connect()
370
+ setInterval(render_tree, 250)
371
+ })()
372
+ </script>
373
+ </body>
374
+ </html>
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "fascicle",
3
- "version": "0.3.3",
3
+ "version": "0.3.8",
4
4
  "description": "Composable TypeScript toolkit for agentic workflows. Plain values, no framework, no ambient state.",
5
5
  "license": "Apache-2.0",
6
6
  "author": {
@@ -22,6 +22,9 @@
22
22
  "import": "./dist/index.js"
23
23
  }
24
24
  },
25
+ "bin": {
26
+ "fascicle-viewer": "./dist/bin/fascicle-viewer.js"
27
+ },
25
28
  "files": [
26
29
  "dist",
27
30
  "README.md",
@@ -45,14 +48,15 @@
45
48
  "check:all": "node scripts/check.mjs --all",
46
49
  "check:json": "node scripts/check.mjs --json",
47
50
  "check:bail": "node scripts/check.mjs --bail",
48
- "check:fix": "pnpm exec oxlint --type-aware --fix && pnpm exec fallow fix",
51
+ "check:fix": "pnpm exec oxlint --type-aware --fix && node scripts/strip-semicolons.mjs && pnpm exec fallow fix",
49
52
  "check:mutation": "stryker run",
50
53
  "check:publish": "node scripts/check-publish.mjs",
51
54
  "check:security": "pnpm audit --audit-level=high",
52
55
  "prepublishOnly": "pnpm check && pnpm build && pnpm check:publish",
53
56
  "test": "vitest run",
54
57
  "test:watch": "vitest",
55
- "types": "tsc --noEmit"
58
+ "types": "tsc --noEmit",
59
+ "fascicle-viewer": "tsx packages/viewer/src/cli.ts"
56
60
  },
57
61
  "peerDependencies": {
58
62
  "@ai-sdk/anthropic": "^3.0.0",
@@ -91,6 +95,7 @@
91
95
  "@repo/fascicle": "workspace:*",
92
96
  "@repo/observability": "workspace:*",
93
97
  "@repo/stores": "workspace:*",
98
+ "@repo/viewer": "workspace:*",
94
99
  "@stryker-mutator/core": "9.6.1",
95
100
  "@stryker-mutator/vitest-runner": "9.6.1",
96
101
  "@types/node": "24.12.2",