fascicle 0.12.1 → 0.12.5

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 (47) hide show
  1. package/CHANGELOG.md +113 -38
  2. package/README.md +16 -15
  3. package/dist/{adapters-hmnJOOgf.js → adapters-CutexJd3.js} +12 -12
  4. package/dist/adapters-CutexJd3.js.map +1 -0
  5. package/dist/adapters.d.ts +10 -10
  6. package/dist/adapters.js +1 -1
  7. package/dist/agents.d.ts +13 -3
  8. package/dist/agents.js +12 -5
  9. package/dist/agents.js.map +1 -1
  10. package/dist/{core-DDRhHu5P.js → core-DdJEhyQc.js} +122 -488
  11. package/dist/core-DdJEhyQc.js.map +1 -0
  12. package/dist/{engine-b4ZH8esY.js → engine-CdXegeqC.js} +201 -380
  13. package/dist/engine-CdXegeqC.js.map +1 -0
  14. package/dist/index.d.ts +111 -25
  15. package/dist/index.js +446 -48
  16. package/dist/index.js.map +1 -1
  17. package/dist/{invoke-CyKNhvBw.js → invoke-CH_eJZeS.js} +8 -8
  18. package/dist/{invoke-CyKNhvBw.js.map → invoke-CH_eJZeS.js.map} +1 -1
  19. package/dist/leading_system-BUCT-PwD.js +330 -0
  20. package/dist/leading_system-BUCT-PwD.js.map +1 -0
  21. package/dist/mcp.d.ts +5 -5
  22. package/dist/mcp.js +10 -9
  23. package/dist/mcp.js.map +1 -1
  24. package/dist/otel.d.ts +21 -3
  25. package/dist/otel.js +232 -12
  26. package/dist/otel.js.map +1 -1
  27. package/dist/stdio.d.ts +2 -2
  28. package/dist/stdio.js +2 -2
  29. package/dist/testing.d.ts +1 -1
  30. package/dist/testing.js +3 -2
  31. package/dist/testing.js.map +1 -1
  32. package/dist/{trajectory-cSLNlHzh.d.ts → trajectory-ByoOQZ6T.d.ts} +10 -10
  33. package/dist/trajectory-D1eq9eue.js +81 -0
  34. package/dist/trajectory-D1eq9eue.js.map +1 -0
  35. package/dist/{types-BCtKsxrX.d.ts → types-BK0UW28o.d.ts} +3 -3
  36. package/dist/{types-CXBB4aIM.d.ts → types-CLigYA62.d.ts} +30 -4
  37. package/dist/{types-BqUY6nRX.d.ts → types-DBpU27sQ.d.ts} +7 -2
  38. package/dist/ui.d.ts +1 -1
  39. package/dist/ui.js +1 -1
  40. package/dist/ui.js.map +1 -1
  41. package/dist/viewer.d.ts +8 -8
  42. package/dist/viewer.js +16 -15
  43. package/dist/viewer.js.map +1 -1
  44. package/package.json +10 -5
  45. package/dist/adapters-hmnJOOgf.js.map +0 -1
  46. package/dist/core-DDRhHu5P.js.map +0 -1
  47. package/dist/engine-b4ZH8esY.js.map +0 -1
package/dist/viewer.js CHANGED
@@ -1,4 +1,5 @@
1
- import { s as parse_trajectory_event } from "./core-DDRhHu5P.js";
1
+ import "./core-DdJEhyQc.js";
2
+ import { s as parse_trajectory_event } from "./trajectory-D1eq9eue.js";
2
3
  import { open, stat } from "node:fs/promises";
3
4
  import { dirname, resolve } from "node:path";
4
5
  import { createReadStream, existsSync, statSync, watch } from "node:fs";
@@ -16,8 +17,8 @@ import { parseArgs } from "node:util";
16
17
  * that throws is unsubscribed, and the `on_subscriber_error` callback fires
17
18
  * once with the captured error so the server can log it.
18
19
  */
19
- function create_broadcaster(options) {
20
- const max = Math.max(1, options.buffer | 0);
20
+ function create_broadcaster(config) {
21
+ const max = Math.max(1, config.buffer | 0);
21
22
  const ring = [];
22
23
  const subscribers = /* @__PURE__ */ new Set();
23
24
  let next_id = 1;
@@ -32,7 +33,7 @@ function create_broadcaster(options) {
32
33
  fn(entry);
33
34
  } catch (err) {
34
35
  subscribers.delete(fn);
35
- if (options.on_subscriber_error) options.on_subscriber_error(err);
36
+ if (config.on_subscriber_error) config.on_subscriber_error(err);
36
37
  }
37
38
  return entry;
38
39
  };
@@ -78,8 +79,8 @@ const STATIC_HTML = resolve(dirname(fileURLToPath(import.meta.url)), "static", "
78
79
  * single request handler and resolves with the bound URL and a `close`
79
80
  * that shuts the socket down.
80
81
  */
81
- function start_server(options) {
82
- const { broadcaster, host, port, on_parse_error } = options;
82
+ function start_server(config) {
83
+ const { broadcaster, host, port, on_parse_error } = config;
83
84
  const handler = (req, res) => {
84
85
  const route = resolve_route(req, host, port);
85
86
  if (route === "GET /" || route === "GET /index.html") {
@@ -306,8 +307,8 @@ function handle_ingest(req, res, broadcaster, on_parse_error) {
306
307
  * flight absorbs any events that fire while it runs instead of starting a
307
308
  * second concurrent read.
308
309
  */
309
- function start_tail(options) {
310
- const { path, on_event, on_parse_error, on_io_error } = options;
310
+ function start_tail(config) {
311
+ const { path, on_event, on_parse_error, on_io_error } = config;
311
312
  let offset = 0;
312
313
  let buffer = "";
313
314
  let busy = false;
@@ -474,7 +475,7 @@ function wrap_handle(server, tail, host) {
474
475
  /**
475
476
  * fascicle-viewer CLI.
476
477
  *
477
- * fascicle-viewer <path> # tail a JSONL file (primary)
478
+ * fascicle-viewer <path> # tail a JSONL file (primary)
478
479
  * fascicle-viewer --listen # accept HTTP push only
479
480
  * fascicle-viewer <path> --listen # both producers feed the same broadcaster
480
481
  *
@@ -495,7 +496,7 @@ Usage:
495
496
  Options:
496
497
  --port <n> port (default 4242)
497
498
  --host <h> bind host (default 127.0.0.1; --host 0.0.0.0 warns)
498
- --buffer <n> ring-buffer size (default 1000)
499
+ --buffer <n> ring-buffer size (default 1000)
499
500
  --no-open do not open the browser
500
501
  --help show this message
501
502
  `;
@@ -549,11 +550,11 @@ function parse(argv) {
549
550
  const port = Number.parseInt(port_raw, 10);
550
551
  const buffer = Number.parseInt(buffer_raw, 10);
551
552
  if (!Number.isFinite(port) || port <= 0) {
552
- process.stderr.write(`invalid --port: ${port_raw}\n`);
553
+ process.stderr.write(`fascicle-viewer: invalid --port '${port_raw}': expected a positive integer\n`);
553
554
  process.exit(2);
554
555
  }
555
556
  if (!Number.isFinite(buffer) || buffer <= 0) {
556
- process.stderr.write(`invalid --buffer: ${buffer_raw}\n`);
557
+ process.stderr.write(`fascicle-viewer: invalid --buffer '${buffer_raw}': expected a positive integer\n`);
557
558
  process.exit(2);
558
559
  }
559
560
  const path = positionals[0];
@@ -621,9 +622,9 @@ async function run_viewer_cli(argv) {
621
622
  process.stderr.write(`fascicle-viewer: io error: ${describe_error(err)}\n`);
622
623
  }
623
624
  });
624
- if (args.path !== void 0) process.stderr.write(`watching ${args.path}\n`);
625
- if (args.listen || args.path === void 0) process.stderr.write(`listening for HTTP push on ${handle.url}/api/ingest\n`);
626
- process.stderr.write(`viewer at ${handle.url}\n`);
625
+ if (args.path !== void 0) process.stderr.write(`fascicle-viewer: watching ${args.path}\n`);
626
+ if (args.listen || args.path === void 0) process.stderr.write(`fascicle-viewer: listening for HTTP push on ${handle.url}/api/ingest\n`);
627
+ process.stderr.write(`fascicle-viewer: viewer at ${handle.url}\n`);
627
628
  if (args.open) open_browser(handle.url);
628
629
  const shutdown = async () => {
629
630
  process.stderr.write("\nfascicle-viewer: shutting down\n");
@@ -1 +1 @@
1
- {"version":3,"file":"viewer.js","names":["fs_watch"],"sources":["../src/viewer/broadcast.ts","../src/viewer/server.ts","../src/viewer/tail.ts","../src/viewer/start_viewer.ts","../src/viewer/cli.ts"],"sourcesContent":["/**\n * In-process pub/sub for trajectory events.\n *\n * One ring buffer of the last N events plus a Set of subscriber callbacks.\n * Both producers (file tail and HTTP ingest) push into the same broadcaster;\n * SSE writers fan out via `subscribe`.\n */\n\nimport type { ParsedTrajectoryEvent } from '#core'\n\nexport type BroadcastEvent = {\n readonly id: number\n readonly event: ParsedTrajectoryEvent\n}\n\nexport type Subscriber = (entry: BroadcastEvent) => void\n\nexport type Broadcaster = {\n readonly emit: (event: ParsedTrajectoryEvent) => BroadcastEvent\n readonly subscribe: (fn: Subscriber) => () => void\n readonly snapshot: () => readonly BroadcastEvent[]\n readonly snapshot_after: (last_id: number) => readonly BroadcastEvent[]\n readonly size: () => number\n}\n\nexport type BroadcasterOptions = {\n readonly buffer: number\n readonly on_subscriber_error?: (err: unknown) => void\n}\n\n/**\n * Creates a broadcaster: a bounded ring buffer plus subscriber fan-out.\n *\n * Each event gets a monotonic `id` so SSE clients can replay from a known\n * cursor on reconnect (`snapshot_after`). `emit` does not await delivery, so\n * slow-client backpressure is the subscriber's responsibility. A subscriber\n * that throws is unsubscribed, and the `on_subscriber_error` callback fires\n * once with the captured error so the server can log it.\n */\nexport function create_broadcaster(options: BroadcasterOptions): Broadcaster {\n // `| 0` truncates fractional sizes; clamp so the ring keeps at least one\n // event.\n const max = Math.max(1, options.buffer | 0)\n const ring: BroadcastEvent[] = []\n const subscribers = new Set<Subscriber>()\n let next_id = 1\n\n const emit = (event: ParsedTrajectoryEvent): BroadcastEvent => {\n const entry: BroadcastEvent = { id: next_id++, event }\n ring.push(entry)\n if (ring.length > max) ring.splice(0, ring.length - max)\n // Iterate a copy so deleting a throwing subscriber (or an unsubscribe\n // triggered from inside a callback) cannot upset the live Set.\n for (const fn of Array.from(subscribers)) {\n try {\n fn(entry)\n } catch (err) {\n subscribers.delete(fn)\n if (options.on_subscriber_error) options.on_subscriber_error(err)\n }\n }\n return entry\n }\n\n const subscribe = (fn: Subscriber): (() => void) => {\n subscribers.add(fn)\n return () => { subscribers.delete(fn) }\n }\n\n const snapshot = (): readonly BroadcastEvent[] => [...ring]\n\n const snapshot_after = (last_id: number): readonly BroadcastEvent[] =>\n ring.filter((e) => e.id > last_id)\n\n const size = (): number => ring.length\n\n return { emit, subscribe, snapshot, snapshot_after, size }\n}\n","/**\n * Tiny HTTP server: 5 routes, SSE fan-out, NDJSON ingest.\n *\n * GET / -> static viewer.html\n * GET /api/events -> text/event-stream replaying the ring buffer\n * GET /api/snapshot -> JSON dump of the ring buffer\n * POST /api/ingest -> newline-delimited trajectory events (http_logger)\n * GET /api/health -> { ok: true }\n *\n * The server owns nothing but the socket. The broadcaster owns the event\n * history; the static html lives on disk. SSE clients reconnect with\n * `Last-Event-ID` and the server replays anything past their cursor from\n * the ring buffer; older events are gone (bounded memory by design).\n */\n\nimport { createReadStream, statSync } from 'node:fs'\nimport { createServer, type IncomingMessage, type Server, type ServerResponse } from 'node:http'\nimport { dirname, resolve } from 'node:path'\nimport { fileURLToPath } from 'node:url'\nimport { parse_trajectory_event, type ParsedTrajectoryEvent } from '#core'\nimport type { Broadcaster } from './broadcast.js'\n\nconst SSE_HEARTBEAT_MS = 15_000\nconst HERE = dirname(fileURLToPath(import.meta.url))\nconst STATIC_HTML = resolve(HERE, 'static', 'viewer.html')\n\nexport type ServerOptions = {\n readonly broadcaster: Broadcaster\n readonly host: string\n readonly port: number\n readonly on_parse_error?: (err: unknown, line: string) => void\n}\n\nexport type ViewerServer = {\n readonly url: string\n readonly close: () => Promise<void>\n}\n\n/**\n * Starts the HTTP server and resolves once it is listening.\n *\n * Wires the five routes (static HTML, health, snapshot, SSE, ingest) to a\n * single request handler and resolves with the bound URL and a `close`\n * that shuts the socket down.\n */\nexport function start_server(options: ServerOptions): Promise<ViewerServer> {\n const { broadcaster, host, port, on_parse_error } = options\n\n const handler = (req: IncomingMessage, res: ServerResponse): void => {\n const route = resolve_route(req, host, port)\n\n if (route === 'GET /' || route === 'GET /index.html') {\n serve_static_html(res)\n return\n }\n if (route === 'GET /api/health') {\n send_json(res, 200, { ok: true })\n return\n }\n if (route === 'GET /api/snapshot') {\n send_json(res, 200, { events: broadcaster.snapshot() })\n return\n }\n if (route === 'GET /api/events') {\n handle_sse(req, res, broadcaster)\n return\n }\n if (route === 'POST /api/ingest') {\n handle_ingest(req, res, broadcaster, on_parse_error)\n return\n }\n res.statusCode = 404\n res.setHeader('content-type', 'application/json')\n res.end(JSON.stringify({ error: 'not_found', route }))\n }\n\n const http_server = createServer(handler)\n\n return new Promise((res_ok, res_err) => {\n // `listen` can fail (e.g. port already in use); reject instead of\n // leaving the returned promise pending forever.\n http_server.once('error', res_err)\n http_server.listen(port, host, () => {\n http_server.removeListener('error', res_err)\n // `address().port` is the port actually bound. It only differs from\n // the requested `port` when the caller passed 0 and asked the OS to\n // pick a free port.\n const addr = http_server.address()\n const bound_port =\n addr !== null && typeof addr === 'object' && 'port' in addr ? addr.port : port\n const url = `http://${host}:${bound_port}`\n res_ok({\n url,\n close: () => close_server(http_server),\n })\n })\n })\n}\n\n/**\n * Builds a `\"METHOD /path\"` route key from a request.\n *\n * Falls back to the server's own `host`/`port` when the request has no\n * `Host` header, so a malformed or missing header never throws inside\n * `new URL`.\n */\nexport function resolve_route(\n req: {\n url?: string | undefined\n method?: string | undefined\n headers: { host?: string | undefined }\n },\n host: string,\n port: number,\n): string {\n const url = new URL(req.url ?? '/', `http://${req.headers.host ?? `${host}:${port}`}`)\n return `${req.method ?? 'GET'} ${url.pathname}`\n}\n\n/**\n * Closes the HTTP server and resolves once every connection is torn down.\n */\nfunction close_server(server: Server): Promise<void> {\n return new Promise((res_ok, res_err) => {\n server.close((err) => {\n if (err) res_err(err)\n else res_ok()\n })\n // `close` alone only stops new connections and waits for existing ones\n // (including open SSE streams) to end on their own, which can hang\n // indefinitely. Force them closed so shutdown actually completes.\n server.closeAllConnections?.()\n })\n}\n\n/**\n * Writes a JSON response with the given status code.\n */\nfunction send_json(res: ServerResponse, status: number, body: unknown): void {\n res.statusCode = status\n res.setHeader('content-type', 'application/json')\n res.end(JSON.stringify(body))\n}\n\n/**\n * Streams the bundled `viewer.html` as the response body.\n */\nfunction serve_static_html(res: ServerResponse): void {\n let size: number\n try {\n // Stat first so a missing file produces a clean 500 response instead\n // of a stream error after headers have already been sent.\n size = statSync(STATIC_HTML).size\n } catch {\n res.statusCode = 500\n res.setHeader('content-type', 'text/plain')\n res.end('viewer.html missing')\n return\n }\n res.statusCode = 200\n res.setHeader('content-type', 'text/html; charset=utf-8')\n res.setHeader('cache-control', 'no-store')\n res.setHeader('content-length', String(size))\n createReadStream(STATIC_HTML).pipe(res)\n}\n\n/**\n * Handles `GET /api/events` by turning the connection into an SSE stream.\n *\n * Replays whatever the client missed since its `Last-Event-ID` cursor,\n * subscribes it to the broadcaster for new events, and keeps the\n * connection alive with a periodic heartbeat comment.\n */\nfunction handle_sse(req: IncomingMessage, res: ServerResponse, broadcaster: Broadcaster): void {\n res.statusCode = 200\n res.setHeader('content-type', 'text/event-stream')\n res.setHeader('cache-control', 'no-store')\n res.setHeader('connection', 'keep-alive')\n // Disables response buffering in nginx so SSE frames reach the client as\n // soon as they are written instead of sitting in a proxy buffer.\n res.setHeader('x-accel-buffering', 'no')\n\n // Replay everything after the client's cursor before subscribing. Both\n // calls run synchronously back to back, so there is no window in which\n // an event could land between the replay and the live subscription.\n const last_event_id = parse_last_event_id(req.headers['last-event-id'])\n for (const entry of broadcaster.snapshot_after(last_event_id)) {\n write_event(res, entry.id, entry.event)\n }\n\n // Comment frames keep the connection alive through idle proxies and\n // load balancers that would otherwise time out a quiet SSE stream.\n const heartbeat = setInterval(() => {\n res.write(': heartbeat\\n\\n')\n }, SSE_HEARTBEAT_MS)\n\n const unsubscribe = broadcaster.subscribe((entry) => {\n write_event(res, entry.id, entry.event)\n })\n\n const close = (): void => {\n clearInterval(heartbeat)\n unsubscribe()\n if (!res.writableEnded) {\n res.write('event: close\\ndata: {}\\n\\n')\n res.end()\n }\n }\n\n // A clean disconnect and a socket error both need the same cleanup.\n req.on('close', close)\n req.on('error', close)\n}\n\n/**\n * Parses the `Last-Event-ID` header into a replay cursor, defaulting to 0.\n *\n * Treats a missing header or a non-numeric or non-positive value as \"no\n * cursor\", which makes `handle_sse` replay the full ring buffer.\n */\nfunction parse_last_event_id(value: string | string[] | undefined): number {\n if (typeof value !== 'string') return 0\n const n = Number.parseInt(value, 10)\n return Number.isFinite(n) && n > 0 ? n : 0\n}\n\n/**\n * Writes one SSE `trajectory` event frame to the response stream.\n */\nfunction write_event(res: ServerResponse, id: number, event: ParsedTrajectoryEvent): void {\n res.write(`id: ${id}\\nevent: trajectory\\ndata: ${JSON.stringify(event)}\\n\\n`)\n}\n\n/**\n * Handles `POST /api/ingest`: parses newline-delimited trajectory events\n * from the request body and feeds valid ones into the broadcaster.\n *\n * Reports how many lines were accepted vs rejected in the response body;\n * a malformed line is skipped and reported via `on_parse_error`, not\n * treated as a fatal request error.\n */\nfunction handle_ingest(\n req: IncomingMessage,\n res: ServerResponse,\n broadcaster: Broadcaster,\n on_parse_error?: (err: unknown, line: string) => void,\n): void {\n let buf = ''\n let accepted = 0\n let rejected = 0\n\n const consume_line = (line: string): void => {\n if (line.length === 0) return\n let parsed: unknown\n try {\n parsed = JSON.parse(line)\n } catch (err) {\n rejected++\n if (on_parse_error) on_parse_error(err, line)\n return\n }\n const result = parse_trajectory_event(parsed)\n if (!result.success) {\n rejected++\n if (on_parse_error) on_parse_error(result.error, line)\n return\n }\n broadcaster.emit(result.data)\n accepted++\n }\n\n req.setEncoding('utf8')\n req.on('data', (chunk: string) => {\n buf += chunk\n // Consume every complete line in the buffer so far; a trailing partial\n // line (no `\\n` yet) stays in `buf` until a later chunk completes it.\n let nl = buf.indexOf('\\n')\n while (nl !== -1) {\n consume_line(buf.slice(0, nl))\n buf = buf.slice(nl + 1)\n nl = buf.indexOf('\\n')\n }\n })\n req.on('end', () => {\n // Flush a final line that arrived without a trailing newline.\n if (buf.length > 0) consume_line(buf)\n send_json(res, 200, { accepted, rejected })\n })\n req.on('error', (err: unknown) => {\n if (on_parse_error) on_parse_error(err, '')\n send_json(res, 400, { error: 'bad_request' })\n })\n}\n\nexport const internals_for_test = { STATIC_HTML, SSE_HEARTBEAT_MS, parse_last_event_id }\n","/**\n * JSONL file tailer.\n *\n * Watches a file for appends and emits one parsed trajectory event per\n * complete line. Handles three pathological cases:\n *\n * - Truncation / rotation: a watcher event whose stat is shorter than the\n * current offset means the file shrunk. Reset offset to 0 and re-stream.\n * - Partial last line: if the trailing chunk has no `\\n`, buffer it and\n * wait. Never parse a half-written line.\n * - Schema failures: a line that fails `parse_trajectory_event` is\n * dropped and surfaced to `on_parse_error`. The stream keeps going.\n *\n * The watcher is fs.watch-based; reads are serialized and change events\n * that arrive mid-read are coalesced into one extra pass rather than\n * dropped, so a burst of appends never starts overlapping reads. Each pass\n * re-stats and re-reads from the saved offset, which also covers platforms\n * where fs.watch misses some append notifications: the next successful\n * change event catches the file up regardless.\n */\n\nimport { type FSWatcher, watch as fs_watch } from 'node:fs'\nimport { open, stat } from 'node:fs/promises'\nimport { parse_trajectory_event, type ParsedTrajectoryEvent } from '#core'\n\nexport type TailOptions = {\n readonly path: string\n readonly on_event: (event: ParsedTrajectoryEvent) => void\n readonly on_parse_error?: (err: unknown, line: string) => void\n readonly on_io_error?: (err: unknown) => void\n}\n\nexport type Tail = {\n readonly stop: () => void\n readonly drain: () => Promise<void>\n}\n\n/**\n * Starts tailing `path` and returns a handle to stop or drain it.\n *\n * Watches the file with `fs.watch` and re-reads from the last known offset\n * on every change, buffering an incomplete trailing line until the rest\n * arrives. Overlapping change events are coalesced: a read already in\n * flight absorbs any events that fire while it runs instead of starting a\n * second concurrent read.\n */\nexport function start_tail(options: TailOptions): Tail {\n const { path, on_event, on_parse_error, on_io_error } = options\n let offset = 0\n let buffer = ''\n let busy = false\n let pending = false\n let closed = false\n let watcher: FSWatcher | null = null\n let last_drain: Promise<void> = Promise.resolve()\n\n const handle_line = (line: string): void => {\n if (line.length === 0) return\n let parsed: unknown\n try {\n parsed = JSON.parse(line)\n } catch (err) {\n if (on_parse_error) on_parse_error(err, line)\n return\n }\n const result = parse_trajectory_event(parsed)\n if (!result.success) {\n if (on_parse_error) on_parse_error(result.error, line)\n return\n }\n on_event(result.data)\n }\n\n const read_more = async (): Promise<void> => {\n let st\n try {\n st = await stat(path)\n } catch (err) {\n if (on_io_error) on_io_error(err)\n return\n }\n if (st.size < offset) {\n // File is shorter than our offset: it was truncated or rotated.\n // Restart from the top instead of seeking to a now-invalid offset.\n offset = 0\n buffer = ''\n }\n if (st.size === offset) return\n\n const fh = await open(path, 'r').catch((err: unknown) => {\n if (on_io_error) on_io_error(err)\n return null\n })\n if (!fh) return\n try {\n const length = st.size - offset\n const buf = Buffer.alloc(length)\n const { bytesRead } = await fh.read(buf, 0, length, offset)\n offset += bytesRead\n buffer += buf.subarray(0, bytesRead).toString('utf8')\n } finally {\n await fh.close()\n }\n\n let nl = buffer.indexOf('\\n')\n while (nl !== -1) {\n const line = buffer.slice(0, nl)\n buffer = buffer.slice(nl + 1)\n handle_line(line)\n nl = buffer.indexOf('\\n')\n }\n // Anything left in `buffer` has no trailing newline yet; keep it for\n // the next read instead of parsing a half-written line.\n }\n\n // Coalesces watcher bursts: if `schedule` fires while a read is already\n // running, it just flags `pending` and returns. The running loop below\n // checks `pending` after each pass and does one more pass if it was set,\n // so a burst of change events never starts overlapping reads.\n const schedule = (): void => {\n if (closed) return\n if (busy) {\n pending = true\n return\n }\n busy = true\n last_drain = (async (): Promise<void> => {\n try {\n let keep_going = true\n while (keep_going) {\n pending = false\n await read_more()\n keep_going = pending && !closed\n }\n } finally {\n busy = false\n }\n })()\n }\n\n schedule()\n\n try {\n watcher = fs_watch(path, { persistent: true }, () => { schedule() })\n } catch (err) {\n if (on_io_error) on_io_error(err)\n }\n\n const stop = (): void => {\n closed = true\n if (watcher) {\n watcher.close()\n watcher = null\n }\n }\n\n const drain = async (): Promise<void> => {\n schedule()\n await last_drain\n }\n\n return { stop, drain }\n}\n","/**\n * `start_viewer` programmatic embed implementation.\n *\n * Spin up the server, optionally start tailing a JSONL file, and return a\n * handle that can stop both. `start_viewer` only depends on core's wire-format\n * schema; it never reaches into the engine, composites, or any provider.\n */\n\nimport { create_broadcaster } from './broadcast.js'\nimport { start_server, type ViewerServer } from './server.js'\nimport { start_tail, type Tail } from './tail.js'\n\nexport type StartViewerOptions = {\n readonly path?: string\n readonly host?: string\n readonly port?: number\n readonly buffer?: number\n readonly on_parse_error?: (err: unknown, line: string) => void\n readonly on_io_error?: (err: unknown) => void\n readonly on_subscriber_error?: (err: unknown) => void\n}\n\nexport type ViewerHandle = {\n readonly url: string\n readonly host: string\n readonly port: number\n readonly close: () => Promise<void>\n}\n\n/**\n * Starts the viewer: brings up the HTTP/SSE server and, if `options.path`\n * is set, a file tail that feeds the same broadcaster.\n *\n * Defaults to `127.0.0.1:4242` with a 1000-event ring buffer. HTTP ingest\n * and SSE are always available; tailing is opt-in via `path`.\n */\nexport async function start_viewer(options: StartViewerOptions = {}): Promise<ViewerHandle> {\n const host = options.host ?? '127.0.0.1'\n const port = options.port ?? 4242\n const buffer = options.buffer ?? 1000\n const broadcaster = create_broadcaster({\n buffer,\n ...(options.on_subscriber_error ? { on_subscriber_error: options.on_subscriber_error } : {}),\n })\n const server = await start_server({\n broadcaster,\n host,\n port,\n ...(options.on_parse_error ? { on_parse_error: options.on_parse_error } : {}),\n })\n\n let tail: Tail | null = null\n if (options.path !== undefined) {\n tail = start_tail({\n path: options.path,\n on_event: (event) => { broadcaster.emit(event) },\n ...(options.on_parse_error ? { on_parse_error: options.on_parse_error } : {}),\n ...(options.on_io_error ? { on_io_error: options.on_io_error } : {}),\n })\n }\n\n return wrap_handle(server, tail, host)\n}\n\n/**\n * Combines the server and optional tail into a single `ViewerHandle`.\n *\n * `close` stops the tail first, then closes the server, mirroring the\n * startup order (server first, tail second) in reverse. The port is read\n * back from `server.url` rather than the requested `port` option, since\n * a caller that passes `0` gets whatever port the OS actually bound.\n */\nfunction wrap_handle(server: ViewerServer, tail: Tail | null, host: string): ViewerHandle {\n return {\n url: server.url,\n host,\n port: Number(new URL(server.url).port),\n close: async () => {\n if (tail) tail.stop()\n await server.close()\n },\n }\n}\n","#!/usr/bin/env tsx\n/**\n * fascicle-viewer CLI.\n *\n * fascicle-viewer <path> # tail a JSONL file (primary)\n * fascicle-viewer --listen # accept HTTP push only\n * fascicle-viewer <path> --listen # both producers feed the same broadcaster\n *\n * Flags: --port <n> --host <h> --buffer <n> --no-open --help\n *\n * Defaults bind 127.0.0.1:4242 and open the user's default browser. SIGINT\n * shuts everything down cleanly. The CLI body is exposed as `run_viewer_cli`\n * so the umbrella's bin shim can drive it from a bundled `dist/index.js`.\n */\n\nimport { spawn } from 'node:child_process'\nimport { existsSync } from 'node:fs'\nimport { parseArgs } from 'node:util'\nimport { fileURLToPath } from 'node:url'\nimport { start_viewer } from './start_viewer.js'\n\ntype CliArgs = {\n readonly path?: string\n readonly host: string\n readonly port: number\n readonly buffer: number\n readonly listen: boolean\n readonly open: boolean\n}\n\nconst HELP = `\\\nfascicle-viewer — minimal in-repo dashboard for fascicle trajectory streams.\n\nUsage:\n fascicle-viewer <path> tail a JSONL file\n fascicle-viewer --listen accept HTTP push only\n fascicle-viewer <path> --listen both producers feed the same broadcaster\n\nOptions:\n --port <n> port (default 4242)\n --host <h> bind host (default 127.0.0.1; --host 0.0.0.0 warns)\n --buffer <n> ring-buffer size (default 1000)\n --no-open do not open the browser\n --help show this message\n`\n\n/**\n * Parses CLI argv into a validated `CliArgs`, exiting on bad input.\n *\n * `--help` prints usage and exits 0. Invalid numeric flags, or a missing\n * <path> without `--listen`, write to stderr and exit 2.\n */\nexport function parse(argv: readonly string[]): CliArgs {\n const { values, positionals } = parseArgs({\n args: [...argv],\n allowPositionals: true,\n options: {\n port: { type: 'string', default: '4242' },\n host: { type: 'string', default: '127.0.0.1' },\n buffer: { type: 'string', default: '1000' },\n listen: { type: 'boolean', default: false },\n open: { type: 'boolean', default: true },\n 'no-open': { type: 'boolean', default: false },\n help: { type: 'boolean', default: false },\n },\n })\n if (values.help) {\n process.stdout.write(HELP)\n process.exit(0)\n }\n const port_raw = values.port ?? '4242'\n const buffer_raw = values.buffer ?? '1000'\n const port = Number.parseInt(port_raw, 10)\n const buffer = Number.parseInt(buffer_raw, 10)\n if (!Number.isFinite(port) || port <= 0) {\n process.stderr.write(`invalid --port: ${port_raw}\\n`)\n process.exit(2)\n }\n if (!Number.isFinite(buffer) || buffer <= 0) {\n process.stderr.write(`invalid --buffer: ${buffer_raw}\\n`)\n process.exit(2)\n }\n const path = positionals[0]\n const listen = values.listen ?? false\n if (path === undefined && !listen) {\n process.stderr.write('fascicle-viewer: a <path> is required unless --listen is set\\n')\n process.stderr.write(HELP)\n process.exit(2)\n }\n return {\n ...(path !== undefined ? { path } : {}),\n host: values.host ?? '127.0.0.1',\n port,\n buffer,\n listen,\n open: !values['no-open'] && (values.open ?? true),\n }\n}\n\n/**\n * Opens `url` in the platform's default browser, best-effort.\n *\n * Spawns the platform opener (`open`, `cmd /c start`, or `xdg-open`)\n * detached and swallows failures; the CLI prints the URL either way.\n */\nexport function open_browser(url: string): void {\n const platform = process.platform\n const cmd = platform === 'darwin' ? 'open' : platform === 'win32' ? 'cmd' : 'xdg-open'\n const args = platform === 'win32' ? ['/c', 'start', '\"\"', url] : [url]\n try {\n const child = spawn(cmd, args, { stdio: 'ignore', detached: true })\n child.on('error', () => {})\n child.unref()\n } catch {\n // Best-effort. The CLI logs the URL anyway.\n }\n}\n\n/**\n * CLI entry point: parses argv, starts the viewer, and wires shutdown.\n *\n * Warns but proceeds when the tailed path does not exist yet or when the\n * bind host is 0.0.0.0 (the dashboard has no auth). Optionally opens the\n * browser, then installs SIGINT/SIGTERM handlers that close the viewer\n * before exiting.\n */\nexport async function run_viewer_cli(argv: readonly string[]): Promise<void> {\n const args = parse(argv)\n\n if (args.path !== undefined && !existsSync(args.path)) {\n process.stderr.write(\n `fascicle-viewer: warning: ${args.path} does not exist yet — will pick up events once it is created\\n`,\n )\n }\n if (args.host === '0.0.0.0') {\n process.stderr.write(\n 'fascicle-viewer: warning: binding 0.0.0.0 — this dashboard has no auth and exposes whatever is in your trajectory stream\\n',\n )\n }\n\n const handle = await start_viewer({\n ...(args.path !== undefined ? { path: args.path } : {}),\n host: args.host,\n port: args.port,\n buffer: args.buffer,\n on_parse_error: (err, line) => {\n const preview = line.length > 120 ? `${line.slice(0, 120)}…` : line\n process.stderr.write(\n `fascicle-viewer: skipped malformed line: ${preview}\\n ${describe_error(err)}\\n`,\n )\n },\n on_io_error: (err) => {\n process.stderr.write(`fascicle-viewer: io error: ${describe_error(err)}\\n`)\n },\n })\n\n if (args.path !== undefined) process.stderr.write(`watching ${args.path}\\n`)\n if (args.listen || args.path === undefined) process.stderr.write(`listening for HTTP push on ${handle.url}/api/ingest\\n`)\n process.stderr.write(`viewer at ${handle.url}\\n`)\n\n if (args.open) open_browser(handle.url)\n\n const shutdown = async (): Promise<void> => {\n process.stderr.write('\\nfascicle-viewer: shutting down\\n')\n await handle.close()\n process.exit(0)\n }\n process.on('SIGINT', () => { void shutdown() })\n process.on('SIGTERM', () => { void shutdown() })\n}\n\n/**\n * Renders an unknown thrown value as a human-readable message.\n */\nfunction describe_error(err: unknown): string {\n if (err instanceof Error) return err.message\n try {\n return JSON.stringify(err)\n } catch {\n return String(err)\n }\n}\n\n// ESM main-module detection. The bundler inlines this file into dist/index.js,\n// so a fragile suffix check (`endsWith('/cli.js')`) would fire whenever a\n// consumer's own entry script happened to be named cli.js, see\n// https://nodejs.org/api/esm.html#importmetaurl. Compare the resolved path of\n// this module against argv[1] so the auto-execute only fires when the file is\n// run directly (e.g. `tsx packages/viewer/src/cli.ts`), not when imported.\nconst invoked_directly =\n process.argv[1] !== undefined &&\n process.argv[1] === fileURLToPath(import.meta.url)\n\nif (invoked_directly) {\n void run_viewer_cli(process.argv.slice(2)).catch((err: unknown) => {\n process.stderr.write(`fascicle-viewer: ${describe_error(err)}\\n`)\n process.exit(1)\n })\n}\n"],"mappings":"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"}
1
+ {"version":3,"file":"viewer.js","names":["fs_watch"],"sources":["../src/viewer/broadcast.ts","../src/viewer/server.ts","../src/viewer/tail.ts","../src/viewer/start_viewer.ts","../src/viewer/cli.ts"],"sourcesContent":["/**\n * In-process pub/sub for trajectory events.\n *\n * One ring buffer of the last N events plus a Set of subscriber callbacks.\n * Both producers (file tail and HTTP ingest) push into the same broadcaster;\n * SSE writers fan out via `subscribe`.\n */\n\nimport type { ParsedTrajectoryEvent } from '#core'\n\nexport type BroadcastEvent = {\n readonly id: number\n readonly event: ParsedTrajectoryEvent\n}\n\nexport type Subscriber = (entry: BroadcastEvent) => void\n\nexport type Broadcaster = {\n readonly emit: (event: ParsedTrajectoryEvent) => BroadcastEvent\n readonly subscribe: (fn: Subscriber) => () => void\n readonly snapshot: () => readonly BroadcastEvent[]\n readonly snapshot_after: (last_id: number) => readonly BroadcastEvent[]\n readonly size: () => number\n}\n\nexport type BroadcasterConfig = {\n readonly buffer: number\n readonly on_subscriber_error?: (err: unknown) => void\n}\n\n/**\n * Creates a broadcaster: a bounded ring buffer plus subscriber fan-out.\n *\n * Each event gets a monotonic `id` so SSE clients can replay from a known\n * cursor on reconnect (`snapshot_after`). `emit` does not await delivery, so\n * slow-client backpressure is the subscriber's responsibility. A subscriber\n * that throws is unsubscribed, and the `on_subscriber_error` callback fires\n * once with the captured error so the server can log it.\n */\nexport function create_broadcaster(config: BroadcasterConfig): Broadcaster {\n // `| 0` truncates fractional sizes; clamp so the ring keeps at least one\n // event.\n const max = Math.max(1, config.buffer | 0)\n const ring: BroadcastEvent[] = []\n const subscribers = new Set<Subscriber>()\n let next_id = 1\n\n const emit = (event: ParsedTrajectoryEvent): BroadcastEvent => {\n const entry: BroadcastEvent = { id: next_id++, event }\n ring.push(entry)\n if (ring.length > max) ring.splice(0, ring.length - max)\n // Iterate a copy so deleting a throwing subscriber (or an unsubscribe\n // triggered from inside a callback) cannot upset the live Set.\n for (const fn of Array.from(subscribers)) {\n try {\n fn(entry)\n } catch (err) {\n subscribers.delete(fn)\n if (config.on_subscriber_error) config.on_subscriber_error(err)\n }\n }\n return entry\n }\n\n const subscribe = (fn: Subscriber): (() => void) => {\n subscribers.add(fn)\n return () => { subscribers.delete(fn) }\n }\n\n const snapshot = (): readonly BroadcastEvent[] => [...ring]\n\n const snapshot_after = (last_id: number): readonly BroadcastEvent[] =>\n ring.filter((e) => e.id > last_id)\n\n const size = (): number => ring.length\n\n return { emit, subscribe, snapshot, snapshot_after, size }\n}\n","/**\n * Tiny HTTP server: 5 routes, SSE fan-out, NDJSON ingest.\n *\n * GET / -> static viewer.html\n * GET /api/events -> text/event-stream replaying the ring buffer\n * GET /api/snapshot -> JSON dump of the ring buffer\n * POST /api/ingest -> newline-delimited trajectory events (http_logger)\n * GET /api/health -> { ok: true }\n *\n * The server owns nothing but the socket. The broadcaster owns the event\n * history; the static html lives on disk. SSE clients reconnect with\n * `Last-Event-ID` and the server replays anything past their cursor from\n * the ring buffer; older events are gone (bounded memory by design).\n */\n\nimport { createReadStream, statSync } from 'node:fs'\nimport { createServer, type IncomingMessage, type Server, type ServerResponse } from 'node:http'\nimport { dirname, resolve } from 'node:path'\nimport { fileURLToPath } from 'node:url'\nimport { parse_trajectory_event, type ParsedTrajectoryEvent } from '#core'\nimport type { Broadcaster } from './broadcast.js'\n\nconst SSE_HEARTBEAT_MS = 15_000\nconst HERE = dirname(fileURLToPath(import.meta.url))\nconst STATIC_HTML = resolve(HERE, 'static', 'viewer.html')\n\nexport type ServerConfig = {\n readonly broadcaster: Broadcaster\n readonly host: string\n readonly port: number\n readonly on_parse_error?: (err: unknown, line: string) => void\n}\n\nexport type ViewerServer = {\n readonly url: string\n readonly close: () => Promise<void>\n}\n\n/**\n * Starts the HTTP server and resolves once it is listening.\n *\n * Wires the five routes (static HTML, health, snapshot, SSE, ingest) to a\n * single request handler and resolves with the bound URL and a `close`\n * that shuts the socket down.\n */\nexport function start_server(config: ServerConfig): Promise<ViewerServer> {\n const { broadcaster, host, port, on_parse_error } = config\n\n const handler = (req: IncomingMessage, res: ServerResponse): void => {\n const route = resolve_route(req, host, port)\n\n if (route === 'GET /' || route === 'GET /index.html') {\n serve_static_html(res)\n return\n }\n if (route === 'GET /api/health') {\n send_json(res, 200, { ok: true })\n return\n }\n if (route === 'GET /api/snapshot') {\n send_json(res, 200, { events: broadcaster.snapshot() })\n return\n }\n if (route === 'GET /api/events') {\n handle_sse(req, res, broadcaster)\n return\n }\n if (route === 'POST /api/ingest') {\n handle_ingest(req, res, broadcaster, on_parse_error)\n return\n }\n res.statusCode = 404\n res.setHeader('content-type', 'application/json')\n res.end(JSON.stringify({ error: 'not_found', route }))\n }\n\n const http_server = createServer(handler)\n\n return new Promise((res_ok, res_err) => {\n // `listen` can fail (for example, port already in use); reject instead of\n // leaving the returned promise pending forever.\n http_server.once('error', res_err)\n http_server.listen(port, host, () => {\n http_server.removeListener('error', res_err)\n // `address().port` is the port actually bound. It only differs from\n // the requested `port` when the caller passed 0 and asked the OS to\n // pick a free port.\n const addr = http_server.address()\n const bound_port =\n addr !== null && typeof addr === 'object' && 'port' in addr ? addr.port : port\n const url = `http://${host}:${bound_port}`\n res_ok({\n url,\n close: () => close_server(http_server),\n })\n })\n })\n}\n\n/**\n * Builds a `\"METHOD /path\"` route key from a request.\n *\n * Falls back to the server's own `host`/`port` when the request has no\n * `Host` header, so a malformed or missing header never throws inside\n * `new URL`.\n */\nexport function resolve_route(\n req: {\n url?: string | undefined\n method?: string | undefined\n headers: { host?: string | undefined }\n },\n host: string,\n port: number,\n): string {\n const url = new URL(req.url ?? '/', `http://${req.headers.host ?? `${host}:${port}`}`)\n return `${req.method ?? 'GET'} ${url.pathname}`\n}\n\n/**\n * Closes the HTTP server and resolves once every connection is torn down.\n */\nfunction close_server(server: Server): Promise<void> {\n return new Promise((res_ok, res_err) => {\n server.close((err) => {\n if (err) res_err(err)\n else res_ok()\n })\n // `close` alone only stops new connections and waits for existing ones\n // (including open SSE streams) to end on their own, which can hang\n // indefinitely. Force them closed so shutdown actually completes.\n server.closeAllConnections?.()\n })\n}\n\n/**\n * Writes a JSON response with the given status code.\n */\nfunction send_json(res: ServerResponse, status: number, body: unknown): void {\n res.statusCode = status\n res.setHeader('content-type', 'application/json')\n res.end(JSON.stringify(body))\n}\n\n/**\n * Streams the bundled `viewer.html` as the response body.\n */\nfunction serve_static_html(res: ServerResponse): void {\n let size: number\n try {\n // Stat first so a missing file produces a clean 500 response instead\n // of a stream error after headers have already been sent.\n size = statSync(STATIC_HTML).size\n } catch {\n res.statusCode = 500\n res.setHeader('content-type', 'text/plain')\n res.end('viewer.html missing')\n return\n }\n res.statusCode = 200\n res.setHeader('content-type', 'text/html; charset=utf-8')\n res.setHeader('cache-control', 'no-store')\n res.setHeader('content-length', String(size))\n createReadStream(STATIC_HTML).pipe(res)\n}\n\n/**\n * Handles `GET /api/events` by turning the connection into an SSE stream.\n *\n * Replays whatever the client missed since its `Last-Event-ID` cursor,\n * subscribes it to the broadcaster for new events, and keeps the\n * connection alive with a periodic heartbeat comment.\n */\nfunction handle_sse(req: IncomingMessage, res: ServerResponse, broadcaster: Broadcaster): void {\n res.statusCode = 200\n res.setHeader('content-type', 'text/event-stream')\n res.setHeader('cache-control', 'no-store')\n res.setHeader('connection', 'keep-alive')\n // Disables response buffering in nginx so SSE frames reach the client as\n // soon as they are written instead of sitting in a proxy buffer.\n res.setHeader('x-accel-buffering', 'no')\n\n // Replay everything after the client's cursor before subscribing. Both\n // calls run synchronously back to back, so there is no window in which\n // an event could land between the replay and the live subscription.\n const last_event_id = parse_last_event_id(req.headers['last-event-id'])\n for (const entry of broadcaster.snapshot_after(last_event_id)) {\n write_event(res, entry.id, entry.event)\n }\n\n // Comment frames keep the connection alive through idle proxies and\n // load balancers that would otherwise time out a quiet SSE stream.\n const heartbeat = setInterval(() => {\n res.write(': heartbeat\\n\\n')\n }, SSE_HEARTBEAT_MS)\n\n const unsubscribe = broadcaster.subscribe((entry) => {\n write_event(res, entry.id, entry.event)\n })\n\n const close = (): void => {\n clearInterval(heartbeat)\n unsubscribe()\n if (!res.writableEnded) {\n res.write('event: close\\ndata: {}\\n\\n')\n res.end()\n }\n }\n\n // A clean disconnect and a socket error both need the same cleanup.\n req.on('close', close)\n req.on('error', close)\n}\n\n/**\n * Parses the `Last-Event-ID` header into a replay cursor, defaulting to 0.\n *\n * Treats a missing header or a non-numeric or non-positive value as \"no\n * cursor\", which makes `handle_sse` replay the full ring buffer.\n */\nfunction parse_last_event_id(value: string | string[] | undefined): number {\n if (typeof value !== 'string') return 0\n const n = Number.parseInt(value, 10)\n return Number.isFinite(n) && n > 0 ? n : 0\n}\n\n/**\n * Writes one SSE `trajectory` event frame to the response stream.\n */\nfunction write_event(res: ServerResponse, id: number, event: ParsedTrajectoryEvent): void {\n res.write(`id: ${id}\\nevent: trajectory\\ndata: ${JSON.stringify(event)}\\n\\n`)\n}\n\n/**\n * Handles `POST /api/ingest`: parses newline-delimited trajectory events\n * from the request body and feeds valid ones into the broadcaster.\n *\n * Reports how many lines were accepted vs rejected in the response body;\n * a malformed line is skipped and reported via `on_parse_error`, not\n * treated as a fatal request error.\n */\nfunction handle_ingest(\n req: IncomingMessage,\n res: ServerResponse,\n broadcaster: Broadcaster,\n on_parse_error?: (err: unknown, line: string) => void,\n): void {\n let buf = ''\n let accepted = 0\n let rejected = 0\n\n const consume_line = (line: string): void => {\n if (line.length === 0) return\n let parsed: unknown\n try {\n parsed = JSON.parse(line)\n } catch (err) {\n rejected++\n if (on_parse_error) on_parse_error(err, line)\n return\n }\n const result = parse_trajectory_event(parsed)\n if (!result.success) {\n rejected++\n if (on_parse_error) on_parse_error(result.error, line)\n return\n }\n broadcaster.emit(result.data)\n accepted++\n }\n\n req.setEncoding('utf8')\n req.on('data', (chunk: string) => {\n buf += chunk\n // Consume every complete line in the buffer so far; a trailing partial\n // line (no `\\n` yet) stays in `buf` until a later chunk completes it.\n let nl = buf.indexOf('\\n')\n while (nl !== -1) {\n consume_line(buf.slice(0, nl))\n buf = buf.slice(nl + 1)\n nl = buf.indexOf('\\n')\n }\n })\n req.on('end', () => {\n // Flush a final line that arrived without a trailing newline.\n if (buf.length > 0) consume_line(buf)\n send_json(res, 200, { accepted, rejected })\n })\n req.on('error', (err: unknown) => {\n if (on_parse_error) on_parse_error(err, '')\n send_json(res, 400, { error: 'bad_request' })\n })\n}\n\nexport const internals_for_test = { STATIC_HTML, SSE_HEARTBEAT_MS, parse_last_event_id }\n","/**\n * JSONL file tailer.\n *\n * Watches a file for appends and emits one parsed trajectory event per\n * complete line. Handles three pathological cases:\n *\n * - Truncation / rotation: a watcher event whose stat is shorter than the\n * current offset means the file shrunk. Reset offset to 0 and re-stream.\n * - Partial last line: if the trailing chunk has no `\\n`, buffer it and\n * wait. Never parse a half-written line.\n * - Schema failures: a line that fails `parse_trajectory_event` is\n * dropped and surfaced to `on_parse_error`. The stream keeps going.\n *\n * The watcher is fs.watch-based; reads are serialized and change events\n * that arrive mid-read are coalesced into one extra pass rather than\n * dropped, so a burst of appends never starts overlapping reads. Each pass\n * re-stats and re-reads from the saved offset, which also covers platforms\n * where fs.watch misses some append notifications: the next successful\n * change event catches the file up regardless.\n */\n\nimport { type FSWatcher, watch as fs_watch } from 'node:fs'\nimport { open, stat } from 'node:fs/promises'\nimport { parse_trajectory_event, type ParsedTrajectoryEvent } from '#core'\n\nexport type TailConfig = {\n readonly path: string\n readonly on_event: (event: ParsedTrajectoryEvent) => void\n readonly on_parse_error?: (err: unknown, line: string) => void\n readonly on_io_error?: (err: unknown) => void\n}\n\nexport type Tail = {\n readonly stop: () => void\n readonly drain: () => Promise<void>\n}\n\n/**\n * Starts tailing `path` and returns a handle to stop or drain it.\n *\n * Watches the file with `fs.watch` and re-reads from the last known offset\n * on every change, buffering an incomplete trailing line until the rest\n * arrives. Overlapping change events are coalesced: a read already in\n * flight absorbs any events that fire while it runs instead of starting a\n * second concurrent read.\n */\nexport function start_tail(config: TailConfig): Tail {\n const { path, on_event, on_parse_error, on_io_error } = config\n let offset = 0\n let buffer = ''\n let busy = false\n let pending = false\n let closed = false\n let watcher: FSWatcher | null = null\n let last_drain: Promise<void> = Promise.resolve()\n\n const handle_line = (line: string): void => {\n if (line.length === 0) return\n let parsed: unknown\n try {\n parsed = JSON.parse(line)\n } catch (err) {\n if (on_parse_error) on_parse_error(err, line)\n return\n }\n const result = parse_trajectory_event(parsed)\n if (!result.success) {\n if (on_parse_error) on_parse_error(result.error, line)\n return\n }\n on_event(result.data)\n }\n\n const read_more = async (): Promise<void> => {\n let st\n try {\n st = await stat(path)\n } catch (err) {\n if (on_io_error) on_io_error(err)\n return\n }\n if (st.size < offset) {\n // File is shorter than our offset: it was truncated or rotated.\n // Restart from the top instead of seeking to a now-invalid offset.\n offset = 0\n buffer = ''\n }\n if (st.size === offset) return\n\n const fh = await open(path, 'r').catch((err: unknown) => {\n if (on_io_error) on_io_error(err)\n return null\n })\n if (!fh) return\n try {\n const length = st.size - offset\n const buf = Buffer.alloc(length)\n const { bytesRead } = await fh.read(buf, 0, length, offset)\n offset += bytesRead\n buffer += buf.subarray(0, bytesRead).toString('utf8')\n } finally {\n await fh.close()\n }\n\n let nl = buffer.indexOf('\\n')\n while (nl !== -1) {\n const line = buffer.slice(0, nl)\n buffer = buffer.slice(nl + 1)\n handle_line(line)\n nl = buffer.indexOf('\\n')\n }\n // Anything left in `buffer` has no trailing newline yet; keep it for\n // the next read instead of parsing a half-written line.\n }\n\n // Coalesces watcher bursts: if `schedule` fires while a read is already\n // running, it just flags `pending` and returns. The running loop below\n // checks `pending` after each pass and does one more pass if it was set,\n // so a burst of change events never starts overlapping reads.\n const schedule = (): void => {\n if (closed) return\n if (busy) {\n pending = true\n return\n }\n busy = true\n last_drain = (async (): Promise<void> => {\n try {\n let keep_going = true\n while (keep_going) {\n pending = false\n await read_more()\n keep_going = pending && !closed\n }\n } finally {\n busy = false\n }\n })()\n }\n\n schedule()\n\n try {\n watcher = fs_watch(path, { persistent: true }, () => { schedule() })\n } catch (err) {\n if (on_io_error) on_io_error(err)\n }\n\n const stop = (): void => {\n closed = true\n if (watcher) {\n watcher.close()\n watcher = null\n }\n }\n\n const drain = async (): Promise<void> => {\n schedule()\n await last_drain\n }\n\n return { stop, drain }\n}\n","/**\n * `start_viewer` programmatic embed implementation.\n *\n * Spin up the server, optionally start tailing a JSONL file, and return a\n * handle that can stop both. `start_viewer` only depends on core's wire-format\n * schema; it never reaches into the engine, composites, or any provider.\n */\n\nimport { create_broadcaster } from './broadcast.js'\nimport { start_server, type ViewerServer } from './server.js'\nimport { start_tail, type Tail } from './tail.js'\n\nexport type StartViewerOptions = {\n readonly path?: string\n readonly host?: string\n readonly port?: number\n readonly buffer?: number\n readonly on_parse_error?: (err: unknown, line: string) => void\n readonly on_io_error?: (err: unknown) => void\n readonly on_subscriber_error?: (err: unknown) => void\n}\n\nexport type ViewerHandle = {\n readonly url: string\n readonly host: string\n readonly port: number\n readonly close: () => Promise<void>\n}\n\n/**\n * Starts the viewer: brings up the HTTP/SSE server and, if `options.path`\n * is set, a file tail that feeds the same broadcaster.\n *\n * Defaults to `127.0.0.1:4242` with a 1000-event ring buffer. HTTP ingest\n * and SSE are always available; tailing is opt-in via `path`.\n */\nexport async function start_viewer(options: StartViewerOptions = {}): Promise<ViewerHandle> {\n const host = options.host ?? '127.0.0.1'\n const port = options.port ?? 4242\n const buffer = options.buffer ?? 1000\n const broadcaster = create_broadcaster({\n buffer,\n ...(options.on_subscriber_error ? { on_subscriber_error: options.on_subscriber_error } : {}),\n })\n const server = await start_server({\n broadcaster,\n host,\n port,\n ...(options.on_parse_error ? { on_parse_error: options.on_parse_error } : {}),\n })\n\n let tail: Tail | null = null\n if (options.path !== undefined) {\n tail = start_tail({\n path: options.path,\n on_event: (event) => { broadcaster.emit(event) },\n ...(options.on_parse_error ? { on_parse_error: options.on_parse_error } : {}),\n ...(options.on_io_error ? { on_io_error: options.on_io_error } : {}),\n })\n }\n\n return wrap_handle(server, tail, host)\n}\n\n/**\n * Combines the server and optional tail into a single `ViewerHandle`.\n *\n * `close` stops the tail first, then closes the server, mirroring the\n * startup order (server first, tail second) in reverse. The port is read\n * back from `server.url` rather than the requested `port` option, since\n * a caller that passes `0` gets whatever port the OS actually bound.\n */\nfunction wrap_handle(server: ViewerServer, tail: Tail | null, host: string): ViewerHandle {\n return {\n url: server.url,\n host,\n port: Number(new URL(server.url).port),\n close: async () => {\n if (tail) tail.stop()\n await server.close()\n },\n }\n}\n","#!/usr/bin/env tsx\n/**\n * fascicle-viewer CLI.\n *\n * fascicle-viewer <path> # tail a JSONL file (primary)\n * fascicle-viewer --listen # accept HTTP push only\n * fascicle-viewer <path> --listen # both producers feed the same broadcaster\n *\n * Flags: --port <n> --host <h> --buffer <n> --no-open --help\n *\n * Defaults bind 127.0.0.1:4242 and open the user's default browser. SIGINT\n * shuts everything down cleanly. The CLI body is exposed as `run_viewer_cli`\n * so the umbrella's bin shim can drive it from a bundled `dist/index.js`.\n */\n\nimport { spawn } from 'node:child_process'\nimport { existsSync } from 'node:fs'\nimport { parseArgs } from 'node:util'\nimport { fileURLToPath } from 'node:url'\nimport { start_viewer } from './start_viewer.js'\n\ntype CliArgs = {\n readonly path?: string\n readonly host: string\n readonly port: number\n readonly buffer: number\n readonly listen: boolean\n readonly open: boolean\n}\n\nconst HELP = `\\\nfascicle-viewer — minimal in-repo dashboard for fascicle trajectory streams.\n\nUsage:\n fascicle-viewer <path> tail a JSONL file\n fascicle-viewer --listen accept HTTP push only\n fascicle-viewer <path> --listen both producers feed the same broadcaster\n\nOptions:\n --port <n> port (default 4242)\n --host <h> bind host (default 127.0.0.1; --host 0.0.0.0 warns)\n --buffer <n> ring-buffer size (default 1000)\n --no-open do not open the browser\n --help show this message\n`\n\n/**\n * Parses CLI argv into a validated `CliArgs`, exiting on bad input.\n *\n * `--help` prints usage and exits 0. Invalid numeric flags, or a missing\n * <path> without `--listen`, write to stderr and exit 2.\n */\nexport function parse(argv: readonly string[]): CliArgs {\n const { values, positionals } = parseArgs({\n args: [...argv],\n allowPositionals: true,\n options: {\n port: { type: 'string', default: '4242' },\n host: { type: 'string', default: '127.0.0.1' },\n buffer: { type: 'string', default: '1000' },\n listen: { type: 'boolean', default: false },\n open: { type: 'boolean', default: true },\n 'no-open': { type: 'boolean', default: false },\n help: { type: 'boolean', default: false },\n },\n })\n if (values.help) {\n process.stdout.write(HELP)\n process.exit(0)\n }\n const port_raw = values.port ?? '4242'\n const buffer_raw = values.buffer ?? '1000'\n const port = Number.parseInt(port_raw, 10)\n const buffer = Number.parseInt(buffer_raw, 10)\n if (!Number.isFinite(port) || port <= 0) {\n process.stderr.write(\n `fascicle-viewer: invalid --port '${port_raw}': expected a positive integer\\n`,\n )\n process.exit(2)\n }\n if (!Number.isFinite(buffer) || buffer <= 0) {\n process.stderr.write(\n `fascicle-viewer: invalid --buffer '${buffer_raw}': expected a positive integer\\n`,\n )\n process.exit(2)\n }\n const path = positionals[0]\n const listen = values.listen ?? false\n if (path === undefined && !listen) {\n process.stderr.write('fascicle-viewer: a <path> is required unless --listen is set\\n')\n process.stderr.write(HELP)\n process.exit(2)\n }\n return {\n ...(path !== undefined ? { path } : {}),\n host: values.host ?? '127.0.0.1',\n port,\n buffer,\n listen,\n open: !values['no-open'] && (values.open ?? true),\n }\n}\n\n/**\n * Opens `url` in the platform's default browser, best-effort.\n *\n * Spawns the platform opener (`open`, `cmd /c start`, or `xdg-open`)\n * detached and swallows failures; the CLI prints the URL either way.\n */\nexport function open_browser(url: string): void {\n const platform = process.platform\n const cmd = platform === 'darwin' ? 'open' : platform === 'win32' ? 'cmd' : 'xdg-open'\n const args = platform === 'win32' ? ['/c', 'start', '\"\"', url] : [url]\n try {\n const child = spawn(cmd, args, { stdio: 'ignore', detached: true })\n child.on('error', () => {})\n child.unref()\n } catch {\n // Best-effort. The CLI logs the URL anyway.\n }\n}\n\n/**\n * CLI entry point: parses argv, starts the viewer, and wires shutdown.\n *\n * Warns but proceeds when the tailed path does not exist yet or when the\n * bind host is 0.0.0.0 (the dashboard has no auth). Optionally opens the\n * browser, then installs SIGINT/SIGTERM handlers that close the viewer\n * before exiting.\n */\nexport async function run_viewer_cli(argv: readonly string[]): Promise<void> {\n const args = parse(argv)\n\n if (args.path !== undefined && !existsSync(args.path)) {\n process.stderr.write(\n `fascicle-viewer: warning: ${args.path} does not exist yet — will pick up events once it is created\\n`,\n )\n }\n if (args.host === '0.0.0.0') {\n process.stderr.write(\n 'fascicle-viewer: warning: binding 0.0.0.0 — this dashboard has no auth and exposes whatever is in your trajectory stream\\n',\n )\n }\n\n const handle = await start_viewer({\n ...(args.path !== undefined ? { path: args.path } : {}),\n host: args.host,\n port: args.port,\n buffer: args.buffer,\n on_parse_error: (err, line) => {\n const preview = line.length > 120 ? `${line.slice(0, 120)}…` : line\n process.stderr.write(\n `fascicle-viewer: skipped malformed line: ${preview}\\n ${describe_error(err)}\\n`,\n )\n },\n on_io_error: (err) => {\n process.stderr.write(`fascicle-viewer: io error: ${describe_error(err)}\\n`)\n },\n })\n\n if (args.path !== undefined) process.stderr.write(`fascicle-viewer: watching ${args.path}\\n`)\n if (args.listen || args.path === undefined) process.stderr.write(`fascicle-viewer: listening for HTTP push on ${handle.url}/api/ingest\\n`)\n process.stderr.write(`fascicle-viewer: viewer at ${handle.url}\\n`)\n\n if (args.open) open_browser(handle.url)\n\n const shutdown = async (): Promise<void> => {\n process.stderr.write('\\nfascicle-viewer: shutting down\\n')\n await handle.close()\n process.exit(0)\n }\n process.on('SIGINT', () => { void shutdown() })\n process.on('SIGTERM', () => { void shutdown() })\n}\n\n/**\n * Renders an unknown thrown value as a human-readable message.\n */\nfunction describe_error(err: unknown): string {\n if (err instanceof Error) return err.message\n try {\n return JSON.stringify(err)\n } catch {\n return String(err)\n }\n}\n\n// ESM main-module detection. The bundler inlines this file into dist/index.js,\n// so a fragile suffix check (`endsWith('/cli.js')`) would fire whenever a\n// consumer's own entry script happened to be named cli.js, see\n// https://nodejs.org/api/esm.html#importmetaurl. Compare the resolved path of\n// this module against argv[1] so the auto-execute only fires when the file is\n// run directly (for example, `tsx src/viewer/cli.ts`), not when imported.\nconst invoked_directly =\n process.argv[1] !== undefined &&\n process.argv[1] === fileURLToPath(import.meta.url)\n\nif (invoked_directly) {\n void run_viewer_cli(process.argv.slice(2)).catch((err: unknown) => {\n process.stderr.write(`fascicle-viewer: ${describe_error(err)}\\n`)\n process.exit(1)\n })\n}\n"],"mappings":"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"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "fascicle",
3
- "version": "0.12.1",
3
+ "version": "0.12.5",
4
4
  "description": "Compose agents like plain values. A TypeScript toolkit that wires LLM calls, tools, and functions into typed steps over eight providers. No framework, no ambient state.",
5
5
  "keywords": [
6
6
  "agents",
@@ -132,7 +132,7 @@
132
132
  "check:fix": "pnpm exec oxlint --type-aware --fix && node scripts/strip-semicolons.mjs && pnpm exec fallow fix",
133
133
  "check:mutation": "stryker run",
134
134
  "check:publish": "checkride --only publint,attw,pack,smoke,snippets",
135
- "check:security": "pnpm audit --audit-level=high",
135
+ "check:security": "checkride --only security",
136
136
  "prepublishOnly": "pnpm check && pnpm build && pnpm check:publish",
137
137
  "test": "vitest run",
138
138
  "test:watch": "vitest",
@@ -198,19 +198,24 @@
198
198
  "devDependencies": {
199
199
  "@arethetypeswrong/cli": "0.18.4",
200
200
  "@ast-grep/cli": "0.44.1",
201
- "@modelcontextprotocol/sdk": "1.29.0",
202
- "@opentelemetry/sdk-trace-base": "2.9.0",
201
+ "@modelcontextprotocol/sdk": "1.30.0",
202
+ "@opentelemetry/exporter-metrics-otlp-http": "^0.221.0",
203
+ "@opentelemetry/exporter-trace-otlp-http": "^0.221.0",
204
+ "@opentelemetry/resources": "^2.10.0",
205
+ "@opentelemetry/sdk-metrics": "2.10.0",
206
+ "@opentelemetry/sdk-trace-base": "2.10.0",
203
207
  "@standard-schema/spec": "1.1.0",
204
208
  "@stryker-mutator/core": "9.6.1",
205
209
  "@stryker-mutator/vitest-runner": "9.6.1",
206
210
  "@types/node": "26.1.0",
207
211
  "@vitest/coverage-v8": "4.1.10",
212
+ "@vvago/vale": "3.17.0",
208
213
  "ai": "7.0.17",
209
214
  "arktype": "2.2.3",
210
215
  "checkride": "0.12.1",
211
216
  "cspell": "10.0.1",
212
217
  "fallow": "3.6.0",
213
- "markdownlint-cli2": "0.23.0",
218
+ "markdownlint-cli2": "0.23.2",
214
219
  "oxlint": "1.73.0",
215
220
  "oxlint-tsgolint": "0.24.0",
216
221
  "publint": "0.3.21",
@@ -1 +0,0 @@
1
- {"version":3,"file":"adapters-hmnJOOgf.js","names":[],"sources":["../src/adapters/trajectory_recorder.ts","../src/adapters/line_logger.ts","../src/adapters/filesystem_logger.ts","../src/adapters/http_logger.ts","../src/adapters/noop_logger.ts","../src/adapters/stderr_logger.ts","../src/adapters/tee_logger.ts","../src/adapters/filesystem_store.ts"],"sourcesContent":["/**\n * Shared span/record core for trajectory loggers.\n *\n * Every fascicle trajectory logger emits the same wire format (one JSON object\n * per event) and differs only in where each event goes: `line_logger` writes a\n * line, `http_logger` POSTs NDJSON. This module holds the span bookkeeping they\n * share, parameterized by a single `emit` sink.\n *\n * `start_span` and `end_span` each emit one event; `record` emits the event as\n * written. When the caller supplies `parent_span_id` in the span meta (the\n * runner threads the true structural parent through `RunContext`), that value is\n * used verbatim, so span trees are correct even for concurrent children under\n * `parallel`/`map`. Only when no parent is supplied does the recorder fall back\n * to an in-memory stack of still-open spans, which is best-effort under\n * concurrency.\n */\n\nimport { randomUUID } from 'node:crypto'\nimport type { TrajectoryLogger } from '#core'\n\n/**\n * Build a `TrajectoryLogger` whose events are handed, one at a time, to `emit`.\n */\nexport function trajectory_recorder(\n emit: (event: Record<string, unknown>) => void,\n): TrajectoryLogger {\n const stack: string[] = []\n\n const start_span: TrajectoryLogger['start_span'] = (name, meta) => {\n const span_id = `${name}:${randomUUID().slice(0, 8)}`\n const event: Record<string, unknown> = { kind: 'span_start', span_id, name, ...meta }\n // Prefer the caller-threaded structural parent; fall back to the open-span\n // stack only when none was supplied (best-effort under concurrency).\n if (event['parent_span_id'] === undefined && stack.length > 0) {\n event['parent_span_id'] = stack[stack.length - 1]\n }\n emit(event)\n stack.push(span_id)\n return span_id\n }\n\n const end_span: TrajectoryLogger['end_span'] = (id, meta) => {\n emit({ kind: 'span_end', span_id: id, ...meta })\n const idx = stack.lastIndexOf(id)\n if (idx !== -1) stack.splice(idx, 1)\n }\n\n const record: TrajectoryLogger['record'] = (event) => {\n emit({ ...event })\n }\n\n return { record, start_span, end_span }\n}\n","/**\n * Line-oriented trajectory logger core.\n *\n * `filesystem_logger` and `stderr_logger` emit the same wire format (one JSON\n * object per line) and differ only in where the line goes. Both build on this:\n * `line_logger` adapts the shared span/record core (`trajectory_recorder`) to a\n * `write_line` sink, so the span bookkeeping and `parent_span_id` handling that\n * keep span trees correct under `parallel`/`map` live in exactly one place.\n */\n\nimport type { TrajectoryLogger } from '#core'\nimport { trajectory_recorder } from './trajectory_recorder.js'\n\n/**\n * Create a `TrajectoryLogger` that writes one JSON object per line via\n * `write_line`.\n */\nexport function line_logger(write_line: (event: Record<string, unknown>) => void): TrajectoryLogger {\n return trajectory_recorder(write_line)\n}\n","/**\n * Filesystem JSONL trajectory logger.\n *\n * Appends one JSON object per line to a configured output file. Span\n * bookkeeping (including the `parent_span_id` handling that keeps span trees\n * correct for concurrent children under `parallel`/`map`) lives in\n * `line_logger`. Two concurrent `run(...)` calls that pass distinct logger\n * instances (constructed with distinct `output_path`s) share nothing.\n *\n * Paths are accepted at construction; the logger never reads `process.env`.\n */\n\nimport { appendFileSync, mkdirSync } from 'node:fs'\nimport { dirname } from 'node:path'\nimport type { TrajectoryLogger } from '#core'\nimport { line_logger } from './line_logger.js'\n\nexport type FilesystemLoggerOptions = {\n readonly output_path: string\n}\n\n/**\n * Create a `TrajectoryLogger` that appends one JSON object per line to\n * `output_path`, creating the parent directory if needed.\n */\nexport function filesystem_logger(options: FilesystemLoggerOptions): TrajectoryLogger {\n const { output_path } = options\n mkdirSync(dirname(output_path), { recursive: true })\n\n return line_logger((event) => {\n appendFileSync(output_path, `${JSON.stringify(event)}\\n`)\n })\n}\n","/**\n * HTTP push trajectory logger.\n *\n * Conforms to `TrajectoryLogger`. POSTs each event as a single line of\n * newline-delimited JSON to a configured URL. Pairs naturally with the\n * fascicle viewer's `/api/ingest` endpoint, but is a generic adapter: the\n * receiver can be anything that accepts NDJSON over HTTP.\n *\n * Failure policy: drop on transport error and invoke the optional `on_error`\n * callback. Never throws, never blocks the user's flow on a dev tool being\n * up. The flow always wins; the viewer is best-effort.\n *\n * Span bookkeeping (including the `parent_span_id` handling that mirrors\n * `filesystem_logger` so the wire format is identical) lives in the shared\n * `trajectory_recorder`; this adapter only supplies the emit sink.\n */\n\nimport type { TrajectoryLogger } from '#core'\nimport { trajectory_recorder } from './trajectory_recorder.js'\n\nexport type HttpLoggerFetch = (\n url: string,\n init: { method: 'POST'; headers: Record<string, string>; body: string },\n) => Promise<{ ok: boolean; status: number }>\n\nexport type HttpLoggerOptions = {\n readonly url: string\n readonly fetch?: HttpLoggerFetch\n readonly on_error?: (err: unknown) => void\n}\n\n/**\n * Default `HttpLoggerFetch`, backed by the global `fetch`.\n */\nconst default_fetch: HttpLoggerFetch = async (url, init) => {\n const res = await fetch(url, init)\n return { ok: res.ok, status: res.status }\n}\n\n/**\n * Create a `TrajectoryLogger` that POSTs each event as NDJSON to\n * `options.url`.\n *\n * Never throws: a transport failure is dropped and reported through the\n * optional `on_error` callback, so a dev viewer being unreachable never\n * blocks the flow.\n */\nexport function http_logger(options: HttpLoggerOptions): TrajectoryLogger {\n const { url, on_error } = options\n const send = options.fetch ?? default_fetch\n\n const post = (event: Record<string, unknown>): void => {\n const body = `${JSON.stringify(event)}\\n`\n void send(url, {\n method: 'POST',\n headers: { 'content-type': 'application/x-ndjson' },\n body,\n })\n .then((res) => {\n if (!res.ok && on_error) on_error(new Error(`http_logger: POST ${url} -> ${res.status}`))\n })\n .catch((err: unknown) => {\n if (on_error) on_error(err)\n })\n }\n\n return trajectory_recorder(post)\n}\n","/**\n * No-op trajectory logger.\n *\n * Satisfies `TrajectoryLogger` from `core` without emitting any\n * output. Used as the default when no logger is supplied to `run(...)` and as\n * a cheap fallback in tests that do not care about trajectory output.\n */\n\nimport { randomUUID } from 'node:crypto'\nimport type { TrajectoryLogger } from '#core'\n\n/**\n * Create a `TrajectoryLogger` whose methods do nothing.\n */\nexport function noop_logger(): TrajectoryLogger {\n return {\n record: () => {},\n start_span: (name) => `${name}:${randomUUID().slice(0, 8)}`,\n end_span: () => {},\n }\n}\n","/**\n * Stderr JSONL trajectory logger.\n *\n * Writes one JSON object per line to stderr (or an injected stream), leaving\n * stdout untouched. This is the blessed console logger for agents that run as\n * somebody's child process: under the stdio agent contract, stdout carries the\n * result envelope and belongs to the parent, so trajectory must go elsewhere.\n * The wire format is identical to `filesystem_logger`, so captured stderr is a\n * valid trajectory JSONL file (`2>events.jsonl`) the viewer parses unchanged.\n *\n * Writes never throw: a broken pipe or closed stream drops the event rather\n * than failing the flow.\n */\n\nimport type { TrajectoryLogger } from '#core'\nimport { line_logger } from './line_logger.js'\n\nexport type StderrLoggerOptions = {\n readonly stream?: { write(chunk: string): unknown }\n}\n\n/**\n * Create a `TrajectoryLogger` that writes one JSON object per line to\n * stderr, or to `options.stream` when supplied.\n */\nexport function stderr_logger(options: StderrLoggerOptions = {}): TrajectoryLogger {\n const stream = options.stream ?? process.stderr\n return line_logger((event) => {\n try {\n stream.write(`${JSON.stringify(event)}\\n`)\n } catch {\n // Never throw from a logger; the flow always wins.\n }\n })\n}\n","/**\n * tee_logger: fan one TrajectoryLogger contract out to many sinks.\n *\n * Each sink receives every record/start_span/end_span call. Sinks are called\n * in registration order and exceptions in one sink do not prevent the others\n * from receiving the event.\n *\n * The first sink's `start_span` return value is treated as canonical and\n * returned to the caller; the tee remembers each sink's per-sink id so that\n * `end_span(canonical_id, ...)` translates back to the right id for each sink.\n * Within any one sink the wire format stays internally consistent; only the\n * across-sink ids may differ.\n */\n\nimport type { TrajectoryLogger } from '#core'\n\n/**\n * Create a `TrajectoryLogger` that fans every call out to `loggers`.\n */\nexport function tee_logger(...loggers: ReadonlyArray<TrajectoryLogger>): TrajectoryLogger {\n if (loggers.length === 0) {\n throw new Error('tee_logger: at least one logger required')\n }\n\n const id_map = new Map<string, ReadonlyArray<string>>()\n\n const safe_each = (fn: (l: TrajectoryLogger, idx: number) => void): void => {\n for (let i = 0; i < loggers.length; i += 1) {\n const l = loggers[i]\n if (l === undefined) continue\n try {\n fn(l, i)\n } catch {\n // best-effort fan-out: a misbehaving sink must not derail the others\n }\n }\n }\n\n return {\n record: (event) => {\n safe_each((l) => l.record(event))\n },\n start_span: (name, meta) => {\n const ids: string[] = []\n safe_each((l) => {\n ids.push(l.start_span(name, meta))\n })\n const canonical = ids[0] ?? `${name}:tee`\n if (loggers.length > 1) id_map.set(canonical, ids)\n return canonical\n },\n end_span: (id, meta) => {\n const ids = id_map.get(id)\n if (ids === undefined) {\n safe_each((l) => l.end_span(id, meta))\n return\n }\n id_map.delete(id)\n safe_each((l, idx) => l.end_span(ids[idx] ?? id, meta))\n },\n }\n}\n","/**\n * Filesystem-backed checkpoint store.\n *\n * Satisfies `CheckpointStore` from `core`. Each key is stored as\n * a JSON file under the configured root directory. Writes are all-or-nothing:\n * values are written to a temporary sibling file and then atomically renamed\n * into place, so an interrupted write never leaves a partially-written file\n * at the target key. On `get`, a missing file, a partial temp file that was\n * never atomically renamed, or a JSON parse failure each read as a cache\n * miss (returning `null`) rather than an error.\n *\n * Paths are accepted at construction; the store never reads `process.env`.\n */\n\nimport { createHash, randomUUID } from 'node:crypto'\nimport { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises'\nimport { join } from 'node:path'\nimport type { CheckpointStore } from '#core'\n\nexport type FilesystemStoreOptions = {\n readonly root_dir: string\n}\n\n/**\n * Turn a checkpoint key into a filesystem-safe filename.\n *\n * Slugs the key down to `[a-zA-Z0-9._-]` and appends a short hash of the\n * full key, so two keys that slug to the same string still land on distinct\n * files.\n */\nfunction safe_filename(key: string): string {\n const hash = createHash('sha256').update(key).digest('hex').slice(0, 12)\n const slug = key.replace(/[^a-zA-Z0-9._-]/g, '_').slice(0, 64)\n return `${slug}.${hash}.json`\n}\n\n/**\n * Create a `CheckpointStore` backed by JSON files under `options.root_dir`.\n */\nexport function filesystem_store(options: FilesystemStoreOptions): CheckpointStore {\n const { root_dir } = options\n\n const ensure_root = async (): Promise<void> => {\n await mkdir(root_dir, { recursive: true })\n }\n\n const path_for = (key: string): string => join(root_dir, safe_filename(key))\n\n const get = async (key: string): Promise<unknown> => {\n const path = path_for(key)\n let raw: string\n try {\n raw = await readFile(path, 'utf8')\n } catch {\n return null\n }\n try {\n return JSON.parse(raw) as unknown\n } catch {\n return null\n }\n }\n\n const set = async (key: string, value: unknown): Promise<void> => {\n await ensure_root()\n const target = path_for(key)\n const tmp = `${target}.${randomUUID().slice(0, 8)}.tmp`\n await writeFile(tmp, JSON.stringify(value), 'utf8')\n await rename(tmp, target)\n }\n\n const delete_key = async (key: string): Promise<void> => {\n const target = path_for(key)\n await rm(target, { force: true })\n }\n\n return { get, set, delete: delete_key }\n}\n"],"mappings":"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"}