agent-timelines 0.2.0__py3-none-any.whl

agent_timelines/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+main()

agent_timelines/actors.js

@@ -0,0 +1,202 @@
+/* Characters for the dungeon: the guild master in the hall, one hero + enemy per agent room, a chest per workflow.
+ * Sprites follow the timeline viewer exactly (same HERO map and rules; tests/test_actors.js compares them).
+ * place() is pure (seed + dungeon + nodes -> actors); stamp() remembers when each state began; draw() runs per frame.
+ * Actors not working (idle guild master, a hero after its victory) wander their room's free cells: never onto props,
+ * doors, corridors or the fallen enemy. walk() holds that motion and is canvas-free so it can be tested.
+ * Node fields are the viewer's: {id, tier, kind, running, flags, wf:{state}}. Plain ES5; window.Actors / module.exports. */
+(function (root) {
+  'use strict';
+  var D = root.Dungeon || (typeof require !== 'undefined' && require('./dungeon.js'));
+  // [sheet, col, row]: keep identical to HERO in viewer.html
+  var HERO = {main:["td",0,7],executor:["td",0,8],scanner:["td",1,7],plan:["td",4,8],writer:["td",3,8],runner:["td",4,7],other:["td",3,7],workflow:["td",5,7],wfrun:["td",8,7],ghost:["td",1,10]};
+  var FOES = [108, 109, 110, 111, 120, 122, 123, 124]; // td slime, cyclops, crab, hooded cultist, bat, spider, rat, grey rat
+  var OPEN_CHEST = 91;  // td open chest: a finished workflow
+  var OB_BONES = 721;   // ob bone pile under a fallen enemy
+  var RUG = { 629: 1, 630: 1, 631: 1 }; // ob carpet pieces: the only props that may be walked on
+  var STEP_MS = 220;    // one cell of running
+  var OB_TROPHY = 808;  // ob trophy raised on victory (tinted gold when drawn)
+
+  function cls(n) { return n.id === 'main' ? 'main' : n.kind === 'wf' ? 'workflow' : HERO[n.tier] ? n.tier : 'other'; }
+  function sprite(n) { // the viewer's sprite(): a berserk hero (ignored the tool limit) is a ghost, a running workflow a mimic
+    var berserk = n.id !== 'main' && n.kind !== 'wf' && !n.running && (n.flags || []).indexOf('ignored-limit') >= 0;
+    var s = berserk ? HERO.ghost : n.kind === 'wf' && n.running ? HERO.wfrun : HERO[cls(n)];
+    return s[2] * 12 + s[1];
+  }
+
+  function place(seed, d, nodes) {
+    var solid = {}, path = {}, rooms = {}, out = [];
+    d.deco.forEach(function (e) { if (!(e.sheet === 'ob' && RUG[e.idx])) solid[e.x + ',' + e.y] = 1; });
+    d.paths.forEach(function (p) { p.cells.forEach(function (c) { path[c[0] + ',' + c[1]] = 1; }); });
+    d.rooms.forEach(function (q) { rooms[q.id] = q; });
+    function free(q, x, y) { return x >= q.x && x < q.x + q.w && y >= q.y && y < q.y + q.h && !solid[x + ',' + y] && !path[x + ',' + y]; }
+    function near(q, x, y, two) { // closest free cell to (x, y) in rings outward; `two` also needs its right neighbour free
+      for (var r = 0; r < q.w + q.h; r++) for (var dy = -r; dy <= r; dy++) for (var dx = -r; dx <= r; dx++) {
+        if (Math.max(Math.abs(dx), Math.abs(dy)) === r && free(q, x + dx, y + dy) && (!two || free(q, x + dx + 1, y + dy))) return [x + dx, y + dy];
+      }
+      return [q.cx, q.cy];
+    }
+    function room(q, skip) { // free cells of q, minus `skip`, as {"x,y": 1}
+      var f = {}, x, y;
+      for (y = q.y; y < q.y + q.h; y++) for (x = q.x; x < q.x + q.w; x++) if (free(q, x, y) && x + ',' + y !== skip) f[x + ',' + y] = 1;
+      return f;
+    }
+    nodes.forEach(function (n) {
+      var q = rooms[n.id], a;
+      if (!q) return;
+      if (q.hall) { a = near(q, q.x + 2, q.y); out.push({ id: n.id, kind: 'gm', idx: sprite(n), x: a[0], y: a[1], state: n.running ? 'cast' : 'idle', free: room(q) }); return; }
+      if (n.kind === 'wf') {
+        a = near(q, q.cx, q.cy);
+        out.push({ id: n.id, kind: 'wf', idx: n.running ? sprite(n) : n.wf && n.wf.state === 'failed' ? sprite(n) : OPEN_CHEST, x: a[0], y: a[1],
+          state: n.running ? 'fight' : 'win', failed: !n.running && !!n.wf && n.wf.state === 'failed' });
+        return;
+      }
+      a = near(q, q.cx - 1, q.cy, true);
+      out.push({ id: n.id, kind: 'hero', idx: sprite(n), x: a[0], y: a[1], state: n.running ? 'fight' : 'win',
+        foe: FOES[D.prng(seed + '/foe/' + n.id)() * FOES.length | 0], fx: a[0] + 1, fy: a[1], free: room(q, (a[0] + 1) + ',' + a[1]) });
+    });
+    return out;
+  }
+
+  // mem: {id: {state, since}} kept by the caller. An actor first seen gets since = -Infinity, so a page opened on a
+  // finished session shows the resting pose instead of replaying every victory.
+  function stamp(actors, mem, now) {
+    actors.forEach(function (a) {
+      var m = mem[a.id];
+      // A hero's new state starts a fresh walk from its home cell; the guild master keeps walking through idle <-> cast.
+      if (!m || m.state !== a.state) mem[a.id] = { state: a.state, since: m ? now : -Infinity,
+        walk: m && a.kind === 'gm' ? m.walk : { r: D.prng('walk/' + a.id + '/' + now) } };
+      a.since = mem[a.id].since; a.walk = mem[a.id].walk;
+    });
+  }
+
+  function route(free, from, to) { // BFS over free cells; the cells after `from`, ending at `to` ([] if unreachable)
+    var prev = {}, q = [from], k = from + '', i, c;
+    prev[k] = null;
+    while (q.length) {
+      c = q.shift();
+      if (c[0] === to[0] && c[1] === to[1]) { var out = []; for (; prev[c + ''] !== null; c = prev[c + '']) out.unshift(c); return out; }
+      for (i = 0; i < 4; i++) {
+        var n = [c[0] + [1, -1, 0, 0][i], c[1] + [0, 0, 1, -1][i]];
+        if (free[n[0] + ',' + n[1]] && !(n + '' in prev)) { prev[n + ''] = c; q.push(n); }
+      }
+    }
+    return [];
+  }
+
+  // Position of a resting actor at `now`, in fractional cells: run to a random free cell, pause 1-3 s, repeat.
+  // The loop replays whole steps, so a late frame (hidden tab) catches up instead of skipping cells.
+  function walk(a, now) {
+    var w = a.walk, cells = Object.keys(a.free);
+    if (!w.at) { w.at = [a.x, a.y]; w.path = []; w.until = now + 400 + w.r() * 1500; w.face = 1; }
+    for (;;) {
+      if (!w.path.length) {
+        if (now < w.until || !cells.length) return { x: w.at[0], y: w.at[1], moving: false, face: w.face };
+        var t = cells[w.r() * cells.length | 0].split(',');
+        w.path = route(a.free, w.at, [+t[0], +t[1]]); w.t0 = w.until;
+        if (!w.path.length) { w.until += 1000; continue; }
+      }
+      var n = w.path[0], f = (now - w.t0) / STEP_MS;
+      if (n[0] !== w.at[0]) w.face = n[0] > w.at[0] ? 1 : -1;
+      if (f < 1) return { x: w.at[0] + (n[0] - w.at[0]) * f, y: w.at[1] + (n[1] - w.at[1]) * f, moving: true, face: w.face };
+      w.at = w.path.shift(); w.t0 += STEP_MS;
+      if (!w.path.length) w.until = w.t0 + 1000 + w.r() * 2000;
+    }
+  }
+
+  var tints = {};
+  function tinted(img, cols, idx, color, mix) { // cached recolour of one sprite: mix 1 = solid silhouette (hit flash), <1 keeps shading
+    var k = cols + '/' + idx + color + mix;
+    if (tints[k]) return tints[k];
+    var c = document.createElement('canvas'), x = c.getContext('2d');
+    c.width = c.height = 16;
+    x.drawImage(img, idx % cols * 16, (idx / cols | 0) * 16, 16, 16, 0, 0, 16, 16);
+    x.globalCompositeOperation = 'source-atop'; x.globalAlpha = mix; x.fillStyle = color; x.fillRect(0, 0, 16, 16);
+    return (tints[k] = c);
+  }
+
+  // Every offset is a whole number of sprite pixels and every animation steps (no tweening), so it stays pixel art.
+  // still = true (reduced motion) draws each state's resting pose.
+  function draw(ctx, d, actors, sheets, scale, now, still) {
+    var S = 16 * scale, p = scale, td = sheets.td, i;
+    ctx.imageSmoothingEnabled = false;
+    function spr(idx, x, y, o) {
+      o = o || {};
+      ctx.save(); ctx.globalAlpha = o.alpha == null ? 1 : o.alpha;
+      ctx.translate(x + S / 2, y + S / 2); if (o.flip) ctx.scale(-1, 1); if (o.rot) ctx.rotate(o.rot);
+      if (o.flash) ctx.drawImage(tinted(td, 12, idx, '#fff', 1), -S / 2, -S / 2, S, S);
+      else ctx.drawImage(td, idx % 12 * 16, (idx / 12 | 0) * 16, 16, 16, -S / 2, -S / 2, S, S);
+      ctx.restore();
+    }
+    function ob(idx, x, y, alpha, gold) {
+      ctx.save(); ctx.globalAlpha = alpha;
+      if (gold) ctx.drawImage(tinted(sheets.ob, 48, idx, '#ffc21a', 0.75), x, y, S, S);
+      else ctx.drawImage(sheets.ob, idx % 48 * 16, (idx / 48 | 0) * 16, 16, 16, x, y, S, S);
+      ctx.restore();
+    }
+    function dot(color, x, y, n) { ctx.fillStyle = color; ctx.fillRect(Math.round(x / p) * p, Math.round(y / p) * p, (n || 1) * p, (n || 1) * p); }
+    function step(period, n, off) { return still ? 0 : Math.floor((now + off) % period / period * n); }
+
+    actors.forEach(function (a) {
+      var X = (a.x - d.ox) * S, Y = (a.y - d.oy) * S, off = D.prng('t/' + a.id)() * 5000 | 0, k;
+      if (a.kind === 'gm') return rest(a, a.idx); // always roams the hall; casts at each stop while work is going on
+      if (a.kind === 'wf') return spr(a.idx, X + (a.state === 'fight' ? (step(300, 2, off) ? p : -p) : 0), Y, { alpha: a.failed ? 0.5 : 1 });
+
+      var FX = (a.fx - d.ox) * S, el = now - a.since;
+      if (a.state === 'fight') { // 6 beats: wind-up, lunge, hit (enemy flashes, slash, sparks), recoil, counter-attack, reset
+        k = step(900, 6, off);
+        var hx = [0, 2, 4, 1, 0, 0][k] * p, ex = [0, 0, 2, 1, -3, 0][k] * p;
+        spr(a.idx, X + hx, Y);
+        if (k === 4) spr(a.idx, X + hx, Y, { flash: true, alpha: 0.6 });
+        spr(a.foe, FX + ex, Y, { flip: true, flash: k === 2 });
+        if (k === 2) {
+          for (i = 0; i < 4; i++) dot('#ffffff', X + S + i * p, Y + (2 + i * 3) * p, 2);
+          dot('#ffd23f', FX + 2 * p, Y + 2 * p); dot('#ffd23f', FX + 12 * p, Y + 5 * p); dot('#ff5a5a', FX + 7 * p, Y);
+        }
+        return;
+      }
+      // Finished: for 1.6 s after the change the enemy blinks and falls, the hero hops twice under a raised trophy
+      // with a burst of gold; after that the hero rests and cheers (a hop and a sparkle) every few seconds.
+      var v = still ? 1 : Math.min(1, el / 1600), fell = v > 0.3;
+      if (fell) { ob(OB_BONES, FX, Y + 2 * p, 0.9); spr(a.foe, FX, Y + 3 * p, { flip: true, rot: Math.PI / 2, alpha: 0.55 }); }
+      else spr(a.foe, FX, Y, { flip: true, flash: step(200, 2, 0) === 1 });
+      if (v < 1) {
+        var hop = Math.round(Math.abs(Math.sin(v * 2 * Math.PI)) * 6) * p;
+        spr(a.idx, X, Y - hop);
+        ob(OB_TROPHY, X, Y - S - 3 * p - Math.round(v * 6) * p, v < 0.7 ? 1 : (1 - v) / 0.3, true); // above the hop's peak
+        for (i = 0; i < 8; i++) {
+          var g = i / 8 * 6.2832;
+          dot(i % 2 ? '#ffd23f' : '#fff3b0', X + S / 2 + Math.cos(g) * v * 14 * p, Y + S / 2 - hop + Math.sin(g) * v * 14 * p);
+        }
+        return;
+      }
+      rest(a, a.idx);
+    });
+    // Not working: wander (hop while running, face the way it runs); while paused, bob and now and then cheer.
+    function rest(a, idx) {
+      var o = still ? { x: a.x, y: a.y, moving: false, face: 1 } : walk(a, now), off = D.prng('t/' + a.id)() * 5000 | 0;
+      var X = Math.round((o.x - d.ox) * 16) * p, Y = Math.round((o.y - d.oy) * 16) * p;
+      if (o.moving) return spr(idx, X, Y - step(220, 2, off) * p, { flip: o.face < 0 });
+      if (a.state === 'cast') return cast(idx, X, Y, o.face, off);
+      var k = step(4000, 10, off);
+      spr(idx, X, Y - (k === 0 && a.kind === 'hero' ? 3 : step(1600, 2, off)) * p, { flip: o.face < 0 });
+      if (k === 0 && a.kind === 'hero') { dot('#ffd23f', X + 2 * p, Y - 2 * p); dot('#fff3b0', X + 13 * p, Y - p); }
+    }
+    function cast(idx, X, Y, face, off) { // magic circle on the floor, sparks round the hand, a rune rising off the staff
+      var k = step(800, 8, off), j;
+      for (j = 0; j < 4; j++) {
+        var c = (j / 4 + k / 8) * 6.2832;
+        dot(j % 2 ? '#b48cff' : '#5ab4ff', X + S / 2 + Math.cos(c) * 9 * p, Y + S - p + Math.sin(c) * 3 * p, 2);
+      }
+      for (j = 0; j < 3; j++) {
+        var b = (j / 3 + k / 8) * 6.2832;
+        dot(['#ffffff', '#ffd23f', '#b48cff'][j], X + S / 2 + Math.cos(b) * 7 * p, Y + 4 * p + Math.sin(b) * 4 * p, 2);
+      }
+      dot('#b48cff', face < 0 ? X + p : X + 13 * p, Y - (k % 4) * 3 * p, 2);
+      spr(idx, X, Y - (k % 2) * p, { flip: face < 0 });
+    }
+  }
+
+  var Actors = { place: place, stamp: stamp, draw: draw, walk: walk, sprite: sprite, HERO: HERO, FOES: FOES, OPEN_CHEST: OPEN_CHEST };
+  if (typeof module !== 'undefined' && module.exports) module.exports = Actors;
+  root.Actors = Actors;
+})(typeof window !== 'undefined' ? window : this);

agent_timelines/assets/LICENSES.txt

@@ -0,0 +1,98 @@
+tiny-dungeon.png  Kenney "Tiny Dungeon" 1.0 (www.kenney.nl), CC0 1.0. Source: https://opengameart.org/content/tiny-dungeon
+one-bit.png       Kenney "1-Bit Pack" 1.1 (www.kenney.nl), CC0 1.0. Source: https://opengameart.org/content/1-bit-pack
+PressStart2P-Regular.ttf  Copyright 2012 The Press Start 2P Project Authors, SIL Open Font License 1.1 (text below).
+Source: https://github.com/google/fonts/tree/main/ofl/pressstart2p
+
+Copyright 2012 The Press Start 2P Project Authors (cody@zone38.net), with Reserved Font Name "Press Start 2P".
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

agent_timelines/cli.py

@@ -0,0 +1,197 @@
+"""agent-timelines: install the Claude Code hooks, build session data, serve the dashboard."""
+import argparse, functools, glob, http.server, json, os, shlex, shutil, subprocess, sys, tempfile, time, urllib.parse, webbrowser
+from datetime import datetime
+
+from . import timeline as tl
+
+EVENTS = {"UserPromptSubmit": "", "PostToolUse": "*", "SubagentStart": "", "SubagentStop": "", "Stop": "", "SessionEnd": ""}  # event -> matcher
+MARK = "agent_timelines hook"  # every hook command this tool writes contains it
+OLD = "agent-timeline.py"  # hooks of the pre-package script, replaced on install
+THROTTLE = 3  # s between PostToolUse rebuilds of one session
+
+
+def detach(*args):
+    subprocess.Popen(list(args), stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, start_new_session=True)
+
+
+def strip(hooks):
+    """Remove this tool's (and the old script's) hook commands; drop groups and events left empty."""
+    for ev in list(hooks):
+        for g in hooks[ev]:
+            g["hooks"] = [h for h in g.get("hooks", []) if not any(m in str(h.get("command", "")) for m in (MARK, OLD))]
+        hooks[ev] = [g for g in hooks[ev] if g["hooks"]]
+        if not hooks[ev]:
+            del hooks[ev]
+
+
+def edit_settings(path, edit):
+    path = os.path.expanduser(path or os.path.join(tl.CLAUDE_DIR, "settings.json"))
+    try:
+        with open(path, encoding="utf-8") as f:
+            cfg = json.load(f)
+        bak = "%s.bak-agent-timelines-%s" % (path, time.strftime("%Y%m%d-%H%M%S"))
+        shutil.copy2(path, bak)
+        print("backup:", bak)
+    except FileNotFoundError:
+        cfg = {}
+        os.makedirs(os.path.dirname(path), exist_ok=True)
+    edit(cfg.setdefault("hooks", {}))
+    if not cfg["hooks"]:
+        del cfg["hooks"]
+    tl.write_atomic(path, json.dumps(cfg, indent=2, ensure_ascii=False) + "\n")
+    return path
+
+
+def install(a):
+    cmd = "%s -m %s" % (shlex.quote(sys.executable), MARK)  # absolute python: hooks do not get the login PATH
+
+    def edit(hooks):
+        strip(hooks)
+        for ev, matcher in EVENTS.items():
+            hooks.setdefault(ev, []).append(dict({"matcher": matcher} if matcher else {}, hooks=[{"type": "command", "command": cmd}]))
+    print("installed %d hooks in %s\nfill the lobby with past sessions: agent-timelines rebuild\nopen the dashboard: agent-timelines serve\n(using the Claude Code plugin instead? then skip this command)" % (len(EVENTS), edit_settings(a.settings, edit)))
+
+
+def uninstall(a):
+    print("removed agent-timelines hooks from", edit_settings(a.settings, strip))
+
+
+def plugin_duplicate():
+    """True when settings.json already holds this tool's hooks, so the plugin's copy stays quiet."""
+    try:
+        with open(os.path.join(tl.CLAUDE_DIR, "settings.json"), encoding="utf-8") as f:
+            return MARK in f.read()
+    except OSError:
+        return False
+
+
+def hook(a):
+    """Claude Code passes the event JSON on stdin. Never fail the hook, never block it: the rebuild runs detached."""
+    try:
+        if a.via == "plugin" and plugin_duplicate():
+            return
+        d = json.load(sys.stdin)
+        sid, tp, ev = d.get("session_id"), d.get("transcript_path"), d.get("hook_event_name") or ""
+        data = os.path.join(tl.OUT_DIR, "%s.data.js" % sid)
+        if not sid or not tp or ev == "PostToolUse" and os.path.exists(data) and time.time() - os.path.getmtime(data) < THROTTLE:
+            return  # shortcut: the last tool call of a burst may be skipped; Stop/SubagentStop catch up
+        detach(sys.executable, "-m", "agent_timelines", "build", tp, "--event", ev, "--closed", d.get("agent_id") or "")
+    except Exception:
+        pass
+
+
+def build(a):
+    tp = a.transcript.split("/subagents/")[0] + ".jsonl" if "/subagents/" in a.transcript else a.transcript  # subagent events may name their own file
+    sid = os.path.basename(tp)[:-6]
+    closed = tl.closed_ids(tl.OUT_DIR, sid, a.event, a.closed)
+    d = tl.load(tp, closed=closed, ended=a.event == "SessionEnd", event=a.event)
+    page = tl.publish(d, closed=closed)
+    # No hook fires when a Workflow ends, so while one looks live this re-runs itself every 20s.
+    # shortcut: gives up after 30 re-runs (10 min); upgrade if Claude Code adds a workflow-end hook event.
+    if a.event and a.recheck < 30 and any(n.get("kind") == "wf" and n["running"] for n in d["agents"]):
+        mark = os.path.join(tempfile.gettempdir(), "agent-timeline-%s.recheck" % sid)
+        if a.recheck or not os.path.exists(mark) or time.time() - os.path.getmtime(mark) >= 25:  # else another chain is polling
+            open(mark, "w").close()
+            detach("sh", "-c", 'sleep 20; exec "$@"', "sh", sys.executable, "-m", "agent_timelines", "build", tp, "--event", "Recheck",
+                   "--recheck", str(a.recheck + 1))
+    return page
+
+
+def open_(a):
+    files = tl.find(a.session)
+    if not files:
+        sys.exit("no session found")
+    page = build(argparse.Namespace(transcript=files[0], event=None, closed=None, recheck=0))
+    print(page)
+    webbrowser.open("file://" + page)
+
+
+def rebuild(a):
+    """Regenerate data for every transcript touched in the last `days` (fills the lobby on a first install)."""
+    files = [f for f in tl.find() if time.time() - os.path.getmtime(f) < a.days * 86400]
+    for i, f in enumerate(files, 1):
+        try:
+            build(argparse.Namespace(transcript=f, event=None, closed=None, recheck=0))
+        except Exception as e:  # one unreadable transcript must not stop the rest
+            print("skipped %s: %s" % (os.path.basename(f), e))
+        if sys.stdout.isatty():  # a live counter in a terminal; captured output gets only the summary
+            print("\r%d/%d" % (i, len(files)), end="", flush=True)
+    print("\r" if sys.stdout.isatty() else "", end="")
+    print("rebuilt %d sessions into %s" % (len(files), tl.OUT_DIR))
+
+
+def list_(a):
+    for p in tl.find()[:20]:
+        n = len(glob.glob(os.path.join(p[:-6], "subagents", "*.meta.json")))
+        print(os.path.basename(p)[:-6], datetime.fromtimestamp(os.path.getmtime(p)).strftime("%Y-%m-%d %H:%M"), n, "subagents")
+
+
+class Quiet(http.server.SimpleHTTPRequestHandler):
+    def log_message(self, *args):
+        pass
+
+    def send_head(self):
+        """Serve only same-origin requests: the files hold prompt text and are scripts any other site could include."""
+        port = self.server.server_address[1]
+        ours = ("127.0.0.1:%d" % port, "localhost:%d" % port)
+        ref = self.headers.get("Referer") or ""
+        # a top-level page load (typed URL, link from another site, tool-driven browser) exposes nothing: only scripts and fetches could read the data
+        nav = self.headers.get("Sec-Fetch-Mode") == "navigate" and self.headers.get("Sec-Fetch-Dest") == "document"
+        if self.headers.get("Host") not in ours or not nav and (self.headers.get("Sec-Fetch-Site") not in (None, "same-origin", "none")
+                                                                or ref and urllib.parse.urlsplit(ref).netloc not in ours):
+            self.send_error(403, "cross-site request refused")
+            return None
+        return super().send_head()
+
+    def end_headers(self):
+        self.send_header("Cross-Origin-Resource-Policy", "same-origin")
+        super().end_headers()
+
+
+def make_server(port, directory=None):
+    # 127.0.0.1 only: the pages hold prompt text from your sessions
+    return http.server.ThreadingHTTPServer(("127.0.0.1", port), functools.partial(Quiet, directory=directory or tl.OUT_DIR))
+
+
+def serve(a):
+    tl.build_index()
+    srv = make_server(a.port)
+    url = "http://127.0.0.1:%d/index.html" % srv.server_address[1]
+    print("serving", tl.OUT_DIR, "at", url, "(ctrl-c to stop)")
+    if not a.no_browser:
+        webbrowser.open(url)
+    try:
+        srv.serve_forever()
+    except KeyboardInterrupt:
+        pass
+
+
+def main(argv=None):
+    p = argparse.ArgumentParser(prog="agent-timelines", description="Live delegation graph of Claude Code sessions and subagents.")
+    sub = p.add_subparsers(dest="cmd", required=True)
+    for name, fn, help_ in (("install", install, "add the hooks to Claude Code settings"), ("uninstall", uninstall, "remove the hooks")):
+        sp = sub.add_parser(name, help=help_)
+        sp.add_argument("--settings", help="settings.json to edit (default: $CLAUDE_CONFIG_DIR or ~/.claude)")
+        sp.set_defaults(fn=fn)
+    sp = sub.add_parser("serve", help="serve the dashboard on localhost and open it")
+    sp.add_argument("--port", type=int, default=8765)
+    sp.add_argument("--no-browser", action="store_true")
+    sp.set_defaults(fn=serve)
+    sp = sub.add_parser("open", help="rebuild one session (newest, or by id prefix) and open it")
+    sp.add_argument("session", nargs="?")
+    sp.set_defaults(fn=open_)
+    sub.add_parser("list", help="list recent sessions").set_defaults(fn=list_)
+    sp = sub.add_parser("rebuild", help="regenerate data for recent sessions from their transcripts")
+    sp.add_argument("--days", type=float, default=tl.RETAIN_DAYS)
+    sp.set_defaults(fn=rebuild)
+    sp = sub.add_parser("hook", help="(called by Claude Code) handle one hook event from stdin")
+    sp.add_argument("--via", help="'plugin' when the Claude Code plugin calls it")
+    sp.set_defaults(fn=hook)
+    sp = sub.add_parser("build", help="(called by the hook) rebuild one session's data")
+    sp.add_argument("transcript")
+    sp.add_argument("--event")
+    sp.add_argument("--closed")
+    sp.add_argument("--recheck", type=int, default=0)
+    sp.set_defaults(fn=build)
+    a = p.parse_args(argv)
+    a.fn(a)