notilens 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4f4a0ebf4c82fabed926e4c1f823449339cb5e9318a43b571ed9e0d7e5d959e4
-  data.tar.gz: 31adaa715cc3936496b80561cde5f7f1f08a551007325802b9bdcd8d9fa25c66
+  metadata.gz: 4d1f583f7aad9d8eef202acff467f3a52636763ab184f3a90c5f70f1533bec7b
+  data.tar.gz: 22ac7f6f6e05a57a61a79014efa9b4bf97f0d206734e8182b32c8f56995dc100
 SHA512:
-  metadata.gz: 24439ee3122debf3bbd68b3d4b6af2aa4d6970ae8addfbbabcef7345692e98d8b693872bdbf5d9ab6466977e2432db0f09d9caab9e589c3aa91a0e13347c7f8a
-  data.tar.gz: 165602c07940bcae4cf2843d5089b23316b31be68735a4a092fdd2d927470b8c4136d85010f72985495a2b4201546253dc34fc0805e1abf77138c3a86324e538
+  metadata.gz: ef22530fea5eb20fe5f40c307c2149da05f3e48892bded59dc42ef5499df89465d5eefdd77fb700f8c390c7d5d5eb9c0b53261ff64a15a62efeacd47b86f56b0
+  data.tar.gz: 791d08cfab8d4ea4824431150a9692ad8f1646131c4fad8d15b71b12cb1b5a857a7b9aaa9a8fa513028a11b8bc79ee2e0b60167873ce55ebe807269f6efeef9c

data/README.md

@@ -19,11 +19,11 @@ gem "notilens"
 ```ruby
 require "notilens"
 
-nl = NotiLens.init("my-agent")
-
-task_id = nl.task_start
-nl.task_progress("Processing...", task_id)
-nl.task_complete("Done!", task_id)
+nl  = NotiLens.init("my-agent")
+run = nl.task("report")
+run.start
+run.progress("Processing...")
+run.complete("Done!")
 ```
 
 ## Credentials
@@ -34,38 +34,50 @@ Resolved in order:
 3. Saved CLI config (`notilens init --agent ...`)
 
 ```ruby
-nl = NotiLens.init("my-agent", token: "your-token", secret: "your-secret")
+nl = NotiLens.init("my-agent",
+  token:     "your-token",
+  secret:    "your-secret",
+  state_ttl: 86400  # optional — orphaned state TTL in seconds (default: 86400)
+)
 ```
 
 ## SDK Reference
 
 ### Task Lifecycle
 
+`nl.task(label)` creates a `Run` — an isolated execution context. Multiple concurrent runs of the same label never conflict.
+
 ```ruby
-task_id = nl.task_start                          # auto-generated ID
-task_id = nl.task_start("my-task-123")           # custom ID
-
-nl.task_progress("Fetching data...", task_id)
-nl.task_loop("Processing item 42", task_id)
-nl.task_retry(task_id)
-nl.task_stop(task_id)
-nl.task_error("Quota exceeded", task_id)         # non-fatal
-nl.task_complete("All done!", task_id)           # terminal
-nl.task_fail("Unrecoverable error", task_id)     # terminal
-nl.task_timeout("Timed out after 5m", task_id)   # terminal
-nl.task_cancel("Cancelled by user", task_id)     # terminal
-nl.task_terminate("Force-killed", task_id)       # terminal
+run = nl.task("email")   # create a run for the "email" task
+run.queue                # optional — pre-start signal
+run.start                # begin the run
+
+run.progress("Fetching data...")
+run.loop("Processing item 42")
+run.retry
+run.pause("Waiting for rate limit")
+run.resume("Resuming work")
+run.wait("Waiting for tool response")
+run.stop
+run.error("Quota exceeded")  # non-fatal, run continues
+
+# Terminal — pick one
+run.complete("All done!")
+run.fail("Unrecoverable error")
+run.timeout("Timed out after 5m")
+run.cancel("Cancelled by user")
+run.terminate("Force-killed")
 ```
 
 ### Output & Input Events
 
 ```ruby
-nl.output_generated("Report ready", task_id)
-nl.output_failed("Rendering failed", task_id)
+run.output_generated("Report ready")
+run.output_failed("Rendering failed")
 
-nl.input_required("Approve deployment?", task_id)
-nl.input_approved("Approved", task_id)
-nl.input_rejected("Rejected", task_id)
+run.input_required("Approve deployment?")
+run.input_approved("Approved")
+run.input_rejected("Rejected")
 ```
 
 ### Metrics
@@ -73,18 +85,53 @@ nl.input_rejected("Rejected", task_id)
 Numeric values accumulate; strings are replaced.
 
 ```ruby
-nl.metric("tokens", 512)
-nl.metric("tokens", 128)    # now 640
+run.metric("tokens", 512)
+run.metric("tokens", 128)    # now 640
+run.metric("cost", 0.003)
 
-nl.reset_metrics("tokens")  # reset one key
-nl.reset_metrics            # reset all
+run.reset_metrics("tokens")  # reset one key
+run.reset_metrics            # reset all
 ```
 
+### Automatic Timing
+
+NotiLens automatically tracks task timing. These fields are included in every notification's `meta` payload when non-zero:
+
+| Field | Description |
+|-------|-------------|
+| `total_duration_ms` | Wall-clock time since `start` |
+| `queue_ms` | Time between `queue` and `start` |
+| `pause_ms` | Cumulative time spent paused |
+| `wait_ms` | Cumulative time spent waiting |
+| `active_ms` | Active time (`total − pause − wait`) |
+
 ### Generic Events
 
 ```ruby
-nl.emit("custom.event", "Something happened")
-nl.emit("custom.event", "With meta", meta: { "key" => "value" })
+nl.track("custom.event", "Something happened")
+nl.track("custom.event", "With meta", meta: { "key" => "value" })
+
+run.track("custom.event", "Run-level event")
+run.track("custom.event", "With meta", meta: { "key" => "value" })
+```
+
+### Full Example
+
+```ruby
+require "notilens"
+
+nl  = NotiLens.init("summarizer", token: "TOKEN", secret: "SECRET")
+run = nl.task("report")
+run.start
+
+begin
+  result = llm.complete(prompt)
+  run.metric("tokens", result.usage.total_tokens)
+  run.output_generated("Summary ready")
+  run.complete("All done!")
+rescue => e
+  run.fail(e.message)
+end
 ```
 
 ## CLI
@@ -105,24 +152,41 @@ notilens remove-agent my-agent
 
 ### Commands
 
-```bash
-notilens task.start     --agent my-agent --task job-123
-notilens task.progress  "Fetching" --agent my-agent --task job-123
-notilens task.loop      "Item 5"   --agent my-agent --task job-123
-notilens task.retry                --agent my-agent --task job-123
-notilens task.complete  "Done!"    --agent my-agent --task job-123
-notilens task.fail      "Error"    --agent my-agent --task job-123
-
-notilens output.generate "Report ready" --agent my-agent --task job-123
-notilens input.required  "Approve?"     --agent my-agent --task job-123
-
-notilens metric       tokens=512 cost=0.003 --agent my-agent --task job-123
-notilens metric.reset                       --agent my-agent --task job-123
+`--task` is a semantic label (e.g. `email`, `report`). Each `task.start` creates an isolated run internally — concurrent executions of the same label never conflict.
 
-notilens emit my.event "msg" --agent my-agent
+```bash
+notilens task.queue                      --agent my-agent --task email
+notilens task.start                      --agent my-agent --task email
+notilens task.progress  "Fetching data"  --agent my-agent --task email
+notilens task.loop      "Item 5/100"     --agent my-agent --task email
+notilens task.retry                      --agent my-agent --task email
+notilens task.pause     "Rate limited"   --agent my-agent --task email
+notilens task.resume    "Resuming"       --agent my-agent --task email
+notilens task.wait      "Awaiting tool"  --agent my-agent --task email
+notilens task.stop                       --agent my-agent --task email
+notilens task.error     "Quota hit"      --agent my-agent --task email
+notilens task.fail      "Fatal error"    --agent my-agent --task email
+notilens task.timeout   "Timed out"      --agent my-agent --task email
+notilens task.cancel    "Cancelled"      --agent my-agent --task email
+notilens task.terminate "Force stop"     --agent my-agent --task email
+notilens task.complete  "Done!"          --agent my-agent --task email
+
+notilens output.generate "Report ready"  --agent my-agent --task email
+notilens output.fail     "Render failed" --agent my-agent --task email
+notilens input.required  "Approve?"      --agent my-agent --task email
+notilens input.approve   "Approved"      --agent my-agent --task email
+notilens input.reject    "Rejected"      --agent my-agent --task email
+
+notilens metric       tokens=512 cost=0.003 --agent my-agent --task email
+notilens metric.reset tokens               --agent my-agent --task email
+notilens metric.reset                      --agent my-agent --task email
+
+notilens track my.event "Something happened" --agent my-agent
 notilens version
 ```
 
+`task.start` prints the internal `run_id` to stdout.
+
 ## Requirements
 
 - Ruby 2.7+

data/bin/notilens

@@ -8,6 +8,7 @@ require "notilens/config"
 require "notilens/state"
 require "notilens/notify"
 require "notilens/version"
+require "securerandom"
 
 # ── Helpers ───────────────────────────────────────────────────────────────────
 
@@ -22,21 +23,21 @@ end
 
 def parse_flags(args)
   f = {
-    agent: "", task_id: "", type: "", meta: {},
+    agent: "", task_label: "", type: "", meta: {},
     image_url: "", open_url: "", download_url: "",
     tags: "", is_actionable: ""
   }
   i = 0
   while i < args.length
     case args[i]
-    when "--agent"        then f[:agent]        = args[i += 1].to_s
-    when "--task"         then f[:task_id]       = args[i += 1].to_s
-    when "--type"         then f[:type]          = args[i += 1].to_s
-    when "--image_url"    then f[:image_url]     = args[i += 1].to_s
-    when "--open_url"     then f[:open_url]      = args[i += 1].to_s
-    when "--download_url" then f[:download_url]  = args[i += 1].to_s
-    when "--tags"         then f[:tags]          = args[i += 1].to_s
-    when "--is_actionable"then f[:is_actionable] = args[i += 1].to_s
+    when "--agent"         then f[:agent]        = args[i += 1].to_s
+    when "--task"          then f[:task_label]   = args[i += 1].to_s
+    when "--type"          then f[:type]          = args[i += 1].to_s
+    when "--image_url"     then f[:image_url]     = args[i += 1].to_s
+    when "--open_url"      then f[:open_url]      = args[i += 1].to_s
+    when "--download_url"  then f[:download_url]  = args[i += 1].to_s
+    when "--tags"          then f[:tags]          = args[i += 1].to_s
+    when "--is_actionable" then f[:is_actionable] = args[i += 1].to_s
     when "--meta"
       kv = args[i += 1].to_s
       eq = kv.index("=")
@@ -48,35 +49,70 @@ def parse_flags(args)
     $stderr.puts "❌ --agent is required"
     exit 1
   end
-  f[:task_id] = "task_#{NotiLens::State.now_ms}" if f[:task_id].empty?
   f
 end
 
-def calc_duration(sf)
-  NotiLens::State.calc_duration(sf)
+def resolve_run_id(f)
+  if f[:task_label].empty?
+    $stderr.puts "❌ --task is required"
+    exit 1
+  end
+  run_id = NotiLens::State.read_pointer(f[:agent], f[:task_label])
+  if run_id.empty?
+    $stderr.puts "❌ No active run for task '#{f[:task_label]}' on agent '#{f[:agent]}'. Run task.start first."
+    exit 1
+  end
+  run_id
 end
 
-def send_notify(event, message, f)
+def gen_run_id
+  "run_#{NotiLens::State.now_ms}_#{SecureRandom.hex(4)}"
+end
+
+def send_notify(event, message, f, run_id)
   conf = NotiLens::Config.get_agent(f[:agent])
   if conf.nil? || conf["token"].to_s.empty? || conf["secret"].to_s.empty?
     $stderr.puts "❌ Agent '#{f[:agent]}' not configured. Run: notilens init --agent #{f[:agent]} --token TOKEN --secret SECRET"
     exit 1
   end
 
-  sf    = NotiLens::State.file(f[:agent], f[:task_id])
+  sf    = NotiLens::State.file(f[:agent], run_id)
   state = NotiLens::State.read(sf)
 
   meta = { "agent" => f[:agent] }
-  dur = state["duration_ms"].to_i
-  rc  = state["retry_count"].to_i
-  lc  = state["loop_count"].to_i
-  meta["duration_ms"]  = dur if dur > 0
-  meta["retry_count"]  = rc  if rc  > 0
-  meta["loop_count"]   = lc  if lc  > 0
+  meta["run_id"] = run_id unless run_id.to_s.empty?
+
+  unless f[:task_label].empty?
+    meta["task"]   = f[:task_label]
+    now         = NotiLens::State.now_ms
+    start_time  = state["start_time"].to_i
+    queued_at   = state["queued_at"].to_i
+    pause_total = state["pause_total_ms"].to_i
+    wait_total  = state["wait_total_ms"].to_i
+    pause_total += now - state["paused_at"].to_i if state["paused_at"].to_i > 0
+    wait_total  += now - state["wait_at"].to_i   if state["wait_at"].to_i > 0
+    total_ms  = start_time > 0 ? now - start_time : 0
+    queue_ms  = (start_time > 0 && queued_at > 0) ? start_time - queued_at : 0
+    active_ms = [0, total_ms - pause_total - wait_total].max
+
+    meta["total_duration_ms"] = total_ms   if total_ms   > 0
+    meta["queue_ms"]          = queue_ms   if queue_ms   > 0
+    meta["pause_ms"]          = pause_total if pause_total > 0
+    meta["wait_ms"]           = wait_total  if wait_total  > 0
+    meta["active_ms"]         = active_ms  if active_ms  > 0
+    rc = state["retry_count"].to_i; meta["retry_count"] = rc if rc > 0
+    lc = state["loop_count"].to_i;  meta["loop_count"]  = lc if lc > 0
+    ec = state["error_count"].to_i; meta["error_count"] = ec if ec > 0
+    pc = state["pause_count"].to_i; meta["pause_count"] = pc if pc > 0
+    wc = state["wait_count"].to_i;  meta["wait_count"]  = wc if wc > 0
+  end
+
   (state["metrics"] || {}).each { |k, v| meta[k] = v }
   f[:meta].each { |k, v| meta[k] = v }
 
-  title = "#{f[:agent]} | #{f[:task_id]} | #{event}"
+  title = f[:task_label].empty? \
+    ? "#{f[:agent]} | #{event}" \
+    : "#{f[:agent]} | #{f[:task_label]} | #{event}"
 
   ev_type = %w[info success warning urgent].include?(f[:type]) \
     ? f[:type] : NotiLens::Notify.event_type(event)
@@ -93,7 +129,7 @@ def send_notify(event, message, f)
     "message"       => message,
     "type"          => ev_type,
     "agent"         => f[:agent],
-    "task_id"       => f[:task_id],
+    "task_id"       => f[:task_label],
     "is_actionable" => is_actionable,
     "image_url"     => f[:image_url],
     "open_url"      => f[:open_url],
@@ -145,109 +181,181 @@ when "remove-agent"
     ? puts("✔ Agent '#{rest[0]}' removed") \
     : $stderr.puts("Agent '#{rest[0]}' not found")
 
-when "task.start"
-  f  = parse_flags(rest)
-  sf = NotiLens::State.file(f[:agent], f[:task_id])
+when "task.queue"
+  f      = parse_flags(rest)
+  run_id = gen_run_id
+  sf     = NotiLens::State.file(f[:agent], run_id)
   NotiLens::State.write(sf, {
-    "agent"       => f[:agent],
-    "task"        => f[:task_id],
-    "start_time"  => NotiLens::State.now_ms,
-    "retry_count" => 0,
-    "loop_count"  => 0
+    "agent"          => f[:agent],
+    "task"           => f[:task_label],
+    "run_id"         => run_id,
+    "queued_at"      => NotiLens::State.now_ms,
+    "retry_count"    => 0,
+    "loop_count"     => 0,
+    "error_count"    => 0,
+    "pause_count"    => 0,
+    "wait_count"     => 0,
+    "pause_total_ms" => 0,
+    "wait_total_ms"  => 0
   })
-  send_notify("task.started", "Task started", f)
-  puts "▶  Started: #{f[:agent]} | #{f[:task_id]}"
+  NotiLens::State.write_pointer(f[:agent], f[:task_label], run_id)
+  send_notify("task.queued", "Task queued", f, run_id)
+  puts run_id
+
+when "task.start"
+  f = parse_flags(rest)
+  # Reuse run_id from a prior task.queue if available
+  run_id   = NotiLens::State.read_pointer(f[:agent], f[:task_label])
+  run_id   = gen_run_id if run_id.empty?
+  sf       = NotiLens::State.file(f[:agent], run_id)
+  existing = NotiLens::State.read(sf)
+  if existing.key?("queued_at")
+    NotiLens::State.update(sf, { "start_time" => NotiLens::State.now_ms })
+  else
+    NotiLens::State.write(sf, {
+      "agent"          => f[:agent],
+      "task"           => f[:task_label],
+      "run_id"         => run_id,
+      "start_time"     => NotiLens::State.now_ms,
+      "retry_count"    => 0,
+      "loop_count"     => 0,
+      "error_count"    => 0,
+      "pause_count"    => 0,
+      "wait_count"     => 0,
+      "pause_total_ms" => 0,
+      "wait_total_ms"  => 0
+    })
+  end
+  NotiLens::State.write_pointer(f[:agent], f[:task_label], run_id)
+  send_notify("task.started", "Task started", f, run_id)
+  puts run_id
 
 when "task.progress"
   pos, rest2 = positional_args(rest)
-  f = parse_flags(rest2)
-  sf = NotiLens::State.file(f[:agent], f[:task_id])
-  NotiLens::State.update(sf, { "duration_ms" => calc_duration(sf) })
-  send_notify("task.progress", pos[0].to_s, f)
-  puts "⏳ Progress: #{f[:agent]} | #{f[:task_id]}"
+  f      = parse_flags(rest2)
+  run_id = resolve_run_id(f)
+  send_notify("task.progress", pos[0].to_s, f, run_id)
 
 when "task.loop"
   pos, rest2 = positional_args(rest)
-  f     = parse_flags(rest2)
-  sf    = NotiLens::State.file(f[:agent], f[:task_id])
-  count = NotiLens::State.read(sf)["loop_count"].to_i + 1
-  NotiLens::State.update(sf, { "duration_ms" => calc_duration(sf), "loop_count" => count })
-  send_notify("task.loop", pos[0].to_s, f)
-  puts "🔄 Loop (#{count}): #{f[:agent]} | #{f[:task_id]}"
+  f      = parse_flags(rest2)
+  run_id = resolve_run_id(f)
+  sf     = NotiLens::State.file(f[:agent], run_id)
+  count  = NotiLens::State.read(sf)["loop_count"].to_i + 1
+  NotiLens::State.update(sf, { "loop_count" => count })
+  send_notify("task.loop", pos[0].to_s, f, run_id)
 
 when "task.retry"
-  f     = parse_flags(rest)
-  sf    = NotiLens::State.file(f[:agent], f[:task_id])
-  count = NotiLens::State.read(sf)["retry_count"].to_i + 1
-  NotiLens::State.update(sf, { "duration_ms" => calc_duration(sf), "retry_count" => count })
-  send_notify("task.retry", "Retrying task", f)
-  puts "🔁 Retry: #{f[:agent]} | #{f[:task_id]}"
+  f      = parse_flags(rest)
+  run_id = resolve_run_id(f)
+  sf     = NotiLens::State.file(f[:agent], run_id)
+  count  = NotiLens::State.read(sf)["retry_count"].to_i + 1
+  NotiLens::State.update(sf, { "retry_count" => count })
+  send_notify("task.retry", "Retrying task", f, run_id)
 
 when "task.stop"
-  f   = parse_flags(rest)
-  sf  = NotiLens::State.file(f[:agent], f[:task_id])
-  dur = calc_duration(sf)
-  NotiLens::State.update(sf, { "duration_ms" => dur })
-  send_notify("task.stopped", "Task stopped", f)
-  puts "⏹  Stopped: #{f[:agent]} | #{f[:task_id]} (#{dur} ms)"
+  f      = parse_flags(rest)
+  run_id = resolve_run_id(f)
+  send_notify("task.stopped", "Task stopped", f, run_id)
+
+when "task.pause"
+  pos, rest2 = positional_args(rest)
+  f      = parse_flags(rest2)
+  run_id = resolve_run_id(f)
+  sf     = NotiLens::State.file(f[:agent], run_id)
+  state  = NotiLens::State.read(sf)
+  NotiLens::State.update(sf, {
+    "paused_at"   => NotiLens::State.now_ms,
+    "pause_count" => state["pause_count"].to_i + 1
+  })
+  send_notify("task.paused", pos[0].to_s, f, run_id)
+
+when "task.resume"
+  pos, rest2 = positional_args(rest)
+  f       = parse_flags(rest2)
+  run_id  = resolve_run_id(f)
+  sf      = NotiLens::State.file(f[:agent], run_id)
+  state   = NotiLens::State.read(sf)
+  now     = NotiLens::State.now_ms
+  updates = {}
+  if state["paused_at"].to_i > 0
+    updates["pause_total_ms"] = state["pause_total_ms"].to_i + (now - state["paused_at"].to_i)
+    updates["paused_at"]      = nil
+  end
+  if state["wait_at"].to_i > 0
+    updates["wait_total_ms"] = state["wait_total_ms"].to_i + (now - state["wait_at"].to_i)
+    updates["wait_at"]       = nil
+  end
+  NotiLens::State.update(sf, updates) unless updates.empty?
+  send_notify("task.resumed", pos[0].to_s, f, run_id)
+
+when "task.wait"
+  pos, rest2 = positional_args(rest)
+  f      = parse_flags(rest2)
+  run_id = resolve_run_id(f)
+  sf     = NotiLens::State.file(f[:agent], run_id)
+  state  = NotiLens::State.read(sf)
+  NotiLens::State.update(sf, {
+    "wait_at"    => NotiLens::State.now_ms,
+    "wait_count" => state["wait_count"].to_i + 1
+  })
+  send_notify("task.waiting", pos[0].to_s, f, run_id)
 
 when "task.error"
   pos, rest2 = positional_args(rest)
-  f  = parse_flags(rest2)
-  sf = NotiLens::State.file(f[:agent], f[:task_id])
-  NotiLens::State.update(sf, { "duration_ms" => calc_duration(sf), "last_error" => pos[0].to_s })
-  send_notify("task.error", pos[0].to_s, f)
+  f      = parse_flags(rest2)
+  run_id = resolve_run_id(f)
+  sf     = NotiLens::State.file(f[:agent], run_id)
+  state  = NotiLens::State.read(sf)
+  NotiLens::State.update(sf, { "last_error" => pos[0].to_s, "error_count" => state["error_count"].to_i + 1 })
+  send_notify("task.error", pos[0].to_s, f, run_id)
   $stderr.puts "❌ Error: #{pos[0]}"
 
 when "task.fail"
   pos, rest2 = positional_args(rest)
-  f  = parse_flags(rest2)
-  sf = NotiLens::State.file(f[:agent], f[:task_id])
-  NotiLens::State.update(sf, { "duration_ms" => calc_duration(sf) })
-  send_notify("task.failed", pos[0].to_s, f)
-  NotiLens::State.delete(sf)
-  puts "💥 Failed: #{f[:agent]} | #{f[:task_id]}"
+  f      = parse_flags(rest2)
+  run_id = resolve_run_id(f)
+  send_notify("task.failed", pos[0].to_s, f, run_id)
+  NotiLens::State.delete(NotiLens::State.file(f[:agent], run_id))
+  NotiLens::State.delete_pointer(f[:agent], f[:task_label])
 
 when "task.timeout"
   pos, rest2 = positional_args(rest)
-  f  = parse_flags(rest2)
-  sf = NotiLens::State.file(f[:agent], f[:task_id])
-  NotiLens::State.update(sf, { "duration_ms" => calc_duration(sf) })
-  send_notify("task.timeout", pos[0].to_s, f)
-  NotiLens::State.delete(sf)
-  puts "⏰ Timeout: #{f[:agent]} | #{f[:task_id]}"
+  f      = parse_flags(rest2)
+  run_id = resolve_run_id(f)
+  send_notify("task.timeout", pos[0].to_s, f, run_id)
+  NotiLens::State.delete(NotiLens::State.file(f[:agent], run_id))
+  NotiLens::State.delete_pointer(f[:agent], f[:task_label])
 
 when "task.cancel"
   pos, rest2 = positional_args(rest)
-  f  = parse_flags(rest2)
-  sf = NotiLens::State.file(f[:agent], f[:task_id])
-  NotiLens::State.update(sf, { "duration_ms" => calc_duration(sf) })
-  send_notify("task.cancelled", pos[0].to_s, f)
-  NotiLens::State.delete(sf)
-  puts "🚫 Cancelled: #{f[:agent]} | #{f[:task_id]}"
+  f      = parse_flags(rest2)
+  run_id = resolve_run_id(f)
+  send_notify("task.cancelled", pos[0].to_s, f, run_id)
+  NotiLens::State.delete(NotiLens::State.file(f[:agent], run_id))
+  NotiLens::State.delete_pointer(f[:agent], f[:task_label])
 
 when "task.terminate"
   pos, rest2 = positional_args(rest)
-  f  = parse_flags(rest2)
-  sf = NotiLens::State.file(f[:agent], f[:task_id])
-  NotiLens::State.update(sf, { "duration_ms" => calc_duration(sf) })
-  send_notify("task.terminated", pos[0].to_s, f)
-  NotiLens::State.delete(sf)
-  puts "⚠  Terminated: #{f[:agent]} | #{f[:task_id]}"
+  f      = parse_flags(rest2)
+  run_id = resolve_run_id(f)
+  send_notify("task.terminated", pos[0].to_s, f, run_id)
+  NotiLens::State.delete(NotiLens::State.file(f[:agent], run_id))
+  NotiLens::State.delete_pointer(f[:agent], f[:task_label])
 
 when "task.complete"
   pos, rest2 = positional_args(rest)
-  f  = parse_flags(rest2)
-  sf = NotiLens::State.file(f[:agent], f[:task_id])
-  NotiLens::State.update(sf, { "duration_ms" => calc_duration(sf) })
-  send_notify("task.completed", pos[0].to_s, f)
-  NotiLens::State.delete(sf)
-  puts "✅ Completed: #{f[:agent]} | #{f[:task_id]}"
+  f      = parse_flags(rest2)
+  run_id = resolve_run_id(f)
+  send_notify("task.completed", pos[0].to_s, f, run_id)
+  NotiLens::State.delete(NotiLens::State.file(f[:agent], run_id))
+  NotiLens::State.delete_pointer(f[:agent], f[:task_label])
 
 when "metric"
   pos, rest2 = positional_args(rest)
   f       = parse_flags(rest2)
-  sf      = NotiLens::State.file(f[:agent], f[:task_id])
+  run_id  = resolve_run_id(f)
+  sf      = NotiLens::State.file(f[:agent], run_id)
   state   = NotiLens::State.read(sf)
   metrics = state["metrics"] || {}
   pos.each do |kv|
@@ -267,8 +375,9 @@ when "metric"
 
 when "metric.reset"
   pos, rest2 = positional_args(rest)
-  f  = parse_flags(rest2)
-  sf = NotiLens::State.file(f[:agent], f[:task_id])
+  f      = parse_flags(rest2)
+  run_id = resolve_run_id(f)
+  sf     = NotiLens::State.file(f[:agent], run_id)
   if pos[0]
     state   = NotiLens::State.read(sf)
     metrics = state["metrics"] || {}
@@ -282,36 +391,46 @@ when "metric.reset"
 
 when "output.generate"
   pos, rest2 = positional_args(rest)
-  send_notify("output.generated", pos[0].to_s, parse_flags(rest2))
+  f      = parse_flags(rest2)
+  run_id = resolve_run_id(f)
+  send_notify("output.generated", pos[0].to_s, f, run_id)
 
 when "output.fail"
   pos, rest2 = positional_args(rest)
-  send_notify("output.failed", pos[0].to_s, parse_flags(rest2))
+  f      = parse_flags(rest2)
+  run_id = resolve_run_id(f)
+  send_notify("output.failed", pos[0].to_s, f, run_id)
 
 when "input.required"
   pos, rest2 = positional_args(rest)
-  send_notify("input.required", pos[0].to_s, parse_flags(rest2))
+  f      = parse_flags(rest2)
+  run_id = resolve_run_id(f)
+  send_notify("input.required", pos[0].to_s, f, run_id)
 
 when "input.approve"
   pos, rest2 = positional_args(rest)
-  send_notify("input.approved", pos[0].to_s, parse_flags(rest2))
+  f      = parse_flags(rest2)
+  run_id = resolve_run_id(f)
+  send_notify("input.approved", pos[0].to_s, f, run_id)
 
 when "input.reject"
   pos, rest2 = positional_args(rest)
-  send_notify("input.rejected", pos[0].to_s, parse_flags(rest2))
+  f      = parse_flags(rest2)
+  run_id = resolve_run_id(f)
+  send_notify("input.rejected", pos[0].to_s, f, run_id)
 
-when "emit"
+when "track"
   if rest.length < 2
-    $stderr.puts "Usage: notilens emit <event> <message> --agent <agent>"
+    $stderr.puts "Usage: notilens track <event> <message> --agent <agent>"
     exit 1
   end
-  event = rest[0]
-  msg   = rest[1]
-  f     = parse_flags(rest[2..])
-  sf    = NotiLens::State.file(f[:agent], f[:task_id])
-  NotiLens::State.update(sf, { "duration_ms" => calc_duration(sf) })
-  send_notify(event, msg, f)
-  puts "📡 Event emitted: #{event}"
+  event  = rest[0]
+  msg    = rest[1]
+  f      = parse_flags(rest[2..])
+  # track is agent-level; use pointer if available but don't error if absent
+  run_id = NotiLens::State.read_pointer(f[:agent], f[:task_label])
+  send_notify(event, msg, f, run_id)
+  puts "📡 Tracked: #{event}"
 
 when "version"
   puts "NotiLens v#{NotiLens::VERSION}"
@@ -324,36 +443,40 @@ else
       notilens remove-agent <agent>
 
     Task Lifecycle:
-      notilens task.start     --agent <agent> [--task <id>]
-      notilens task.progress  "msg" --agent <agent> [--task <id>]
-      notilens task.loop      "msg" --agent <agent> [--task <id>]
-      notilens task.retry           --agent <agent> [--task <id>]
-      notilens task.stop            --agent <agent> [--task <id>]
-      notilens task.error     "msg" --agent <agent> [--task <id>]
-      notilens task.fail      "msg" --agent <agent> [--task <id>]
-      notilens task.timeout   "msg" --agent <agent> [--task <id>]
-      notilens task.cancel    "msg" --agent <agent> [--task <id>]
-      notilens task.terminate "msg" --agent <agent> [--task <id>]
-      notilens task.complete  "msg" --agent <agent> [--task <id>]
+      notilens task.queue           --agent <agent> --task <label>
+      notilens task.start           --agent <agent> --task <label>
+      notilens task.progress  "msg" --agent <agent> --task <label>
+      notilens task.loop      "msg" --agent <agent> --task <label>
+      notilens task.retry           --agent <agent> --task <label>
+      notilens task.stop            --agent <agent> --task <label>
+      notilens task.pause     "msg" --agent <agent> --task <label>
+      notilens task.resume    "msg" --agent <agent> --task <label>
+      notilens task.wait      "msg" --agent <agent> --task <label>
+      notilens task.error     "msg" --agent <agent> --task <label>
+      notilens task.fail      "msg" --agent <agent> --task <label>
+      notilens task.timeout   "msg" --agent <agent> --task <label>
+      notilens task.cancel    "msg" --agent <agent> --task <label>
+      notilens task.terminate "msg" --agent <agent> --task <label>
+      notilens task.complete  "msg" --agent <agent> --task <label>
 
     Output / Input:
-      notilens output.generate "msg" --agent <agent> [--task <id>]
-      notilens output.fail     "msg" --agent <agent> [--task <id>]
-      notilens input.required  "msg" --agent <agent> [--task <id>]
-      notilens input.approve   "msg" --agent <agent> [--task <id>]
-      notilens input.reject    "msg" --agent <agent> [--task <id>]
+      notilens output.generate "msg" --agent <agent> --task <label>
+      notilens output.fail     "msg" --agent <agent> --task <label>
+      notilens input.required  "msg" --agent <agent> --task <label>
+      notilens input.approve   "msg" --agent <agent> --task <label>
+      notilens input.reject    "msg" --agent <agent> --task <label>
 
     Metrics:
-      notilens metric       tokens=512 cost=0.003 --agent <agent> --task <id>
-      notilens metric.reset tokens               --agent <agent> --task <id>
-      notilens metric.reset                      --agent <agent> --task <id>
+      notilens metric       tokens=512 cost=0.003 --agent <agent> --task <label>
+      notilens metric.reset tokens               --agent <agent> --task <label>
+      notilens metric.reset                      --agent <agent> --task <label>
 
     Generic:
-      notilens emit <event> "msg" --agent <agent>
+      notilens track <event> "msg" --agent <agent>
 
     Options:
       --agent <name>
-      --task <id>
+      --task <label>
       --type success|warning|urgent|info
       --meta key=value   (repeatable)
       --image_url <url>

data/lib/notilens/notify.rb

@@ -9,7 +9,7 @@ module NotiLens
 
     SUCCESS_EVENTS  = %w[task.completed output.generated input.approved].freeze
     URGENT_EVENTS   = %w[task.failed task.timeout task.error task.terminated output.failed].freeze
-    WARNING_EVENTS  = %w[task.retry task.cancelled input.required input.rejected].freeze
+    WARNING_EVENTS  = %w[task.retry task.cancelled task.paused task.waiting input.required input.rejected].freeze
     ACTIONABLE_EVENTS = %w[
       task.error task.failed task.timeout task.retry task.loop
       output.failed input.required input.rejected
@@ -37,11 +37,12 @@ module NotiLens
       req.body = body
 
       http = Net::HTTP.new(uri.host, uri.port)
-      http.use_ssl     = true
+      http.use_ssl      = true
       http.read_timeout = 10
       http.open_timeout = 10
+
       http.request(req)
-    rescue
+    rescue StandardError
       nil
     end
   end

data/lib/notilens/state.rb

@@ -3,11 +3,21 @@ require "tmpdir"
 
 module NotiLens
   module State
-    def self.file(agent, task_id)
-      user   = ENV["USER"] || ENV["USERNAME"] || ""
+    def self.os_user
+      ENV["USER"] || ENV["USERNAME"] || ""
+    end
+
+    def self.file(agent, run_id)
+      user   = os_user
       agent  = agent.gsub(File::SEPARATOR, "_")
-      task_id = task_id.gsub(File::SEPARATOR, "_")
-      File.join(Dir.tmpdir, "notilens_#{user}_#{agent}_#{task_id}.json")
+      run_id = run_id.gsub(File::SEPARATOR, "_")
+      File.join(Dir.tmpdir, "notilens_#{user}_#{agent}_#{run_id}.json")
+    end
+
+    def self.pointer_file(agent, label)
+      user       = os_user
+      safe_label = label.gsub("/", "_").gsub("\\", "_")
+      File.join(Dir.tmpdir, "notilens_#{user}_#{agent}_#{safe_label}.ptr")
     end
 
     def self.read(path)
@@ -18,8 +28,10 @@ module NotiLens
     end
 
     def self.write(path, data)
-      File.write(path, JSON.pretty_generate(data))
-      File.chmod(0600, path)
+      tmp = path + ".tmp"
+      File.write(tmp, JSON.pretty_generate(data))
+      File.chmod(0600, tmp)
+      File.rename(tmp, path)
     rescue
       nil
     end
@@ -36,11 +48,38 @@ module NotiLens
       nil
     end
 
-    def self.calc_duration(path)
-      s = read(path)
-      start = s["start_time"].to_i
-      return 0 if start == 0
-      (Time.now.to_f * 1000).to_i - start
+    def self.read_pointer(agent, label)
+      path = pointer_file(agent, label)
+      return "" unless File.exist?(path)
+      File.read(path).strip
+    rescue
+      ""
+    end
+
+    def self.write_pointer(agent, label, run_id)
+      File.write(pointer_file(agent, label), run_id)
+    rescue
+      nil
+    end
+
+    def self.delete_pointer(agent, label)
+      path = pointer_file(agent, label)
+      File.delete(path) if File.exist?(path)
+    rescue
+      nil
+    end
+
+    def self.cleanup_stale(agent, state_ttl_seconds)
+      user   = os_user
+      tmp    = Dir.tmpdir
+      cutoff = Time.now.to_f - state_ttl_seconds
+      prefix = "notilens_#{user}_#{agent}_"
+      Dir.entries(tmp).each do |name|
+        next unless name.start_with?(prefix)
+        next unless name.end_with?(".json") || name.end_with?(".ptr")
+        path = File.join(tmp, name)
+        File.delete(path) if File.mtime(path).to_f < cutoff rescue nil
+      end
     end
 
     def self.now_ms

data/lib/notilens/version.rb

@@ -1,3 +1,3 @@
 module NotiLens
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/lib/notilens.rb

@@ -4,24 +4,15 @@ require_relative "notilens/state"
 require_relative "notilens/notify"
 
 module NotiLens
-  class Client
-    def initialize(agent, token: nil, secret: nil)
-      @agent   = agent
-      @token   = token  || ENV["NOTILENS_TOKEN"]  || ""
-      @secret  = secret || ENV["NOTILENS_SECRET"] || ""
+  class Run
+    attr_reader :run_id, :label
+
+    def initialize(agent_obj, label, run_id)
+      @agent   = agent_obj
+      @label   = label
+      @run_id  = run_id
+      @sf      = State.file(agent_obj.agent_name, run_id)
       @metrics = {}
-
-      if @token.empty? || @secret.empty?
-        conf = Config.get_agent(agent) || {}
-        @token  = conf["token"]  if @token.empty?
-        @secret = conf["secret"] if @secret.empty?
-      end
-
-      if @token.to_s.empty? || @secret.to_s.empty?
-        raise "NotiLens: token and secret are required. Pass them directly, " \
-              "set NOTILENS_TOKEN/NOTILENS_SECRET env vars, or run: " \
-              "notilens init --agent #{agent} --token TOKEN --secret SECRET"
-      end
     end
 
     # ── Metrics ────────────────────────────────────────────────────────────────
@@ -40,142 +31,259 @@ module NotiLens
       self
     end
 
-    # ── Task lifecycle ─────────────────────────────────────────────────────────
-
-    def task_start(task_id = nil)
-      id = task_id.to_s.empty? ? "task_#{State.now_ms}" : task_id
-      sf = State.file(@agent, id)
-      State.write(sf, {
-        "agent"       => @agent,
-        "task"        => id,
-        "start_time"  => State.now_ms,
-        "retry_count" => 0,
-        "loop_count"  => 0
+    # ── Lifecycle ──────────────────────────────────────────────────────────────
+
+    def queue
+      State.write(@sf, {
+        "agent"          => @agent.agent_name,
+        "task"           => @label,
+        "run_id"         => @run_id,
+        "queued_at"      => State.now_ms,
+        "retry_count"    => 0,
+        "loop_count"     => 0,
+        "error_count"    => 0,
+        "pause_count"    => 0,
+        "wait_count"     => 0,
+        "pause_total_ms" => 0,
+        "wait_total_ms"  => 0
       })
-      send_event("task.started", "Task started", id)
-      id
+      send_event("task.queued", "Task queued")
+      self
+    end
+
+    def start
+      now      = State.now_ms
+      existing = State.read(@sf)
+      if existing.key?("queued_at")
+        State.update(@sf, { "start_time" => now })
+      else
+        State.write(@sf, {
+          "agent"          => @agent.agent_name,
+          "task"           => @label,
+          "run_id"         => @run_id,
+          "start_time"     => now,
+          "retry_count"    => 0,
+          "loop_count"     => 0,
+          "error_count"    => 0,
+          "pause_count"    => 0,
+          "wait_count"     => 0,
+          "pause_total_ms" => 0,
+          "wait_total_ms"  => 0
+        })
+      end
+      send_event("task.started", "Task started")
+      self
     end
 
-    def task_progress(message, task_id)
-      sf = State.file(@agent, task_id)
-      State.update(sf, { "duration_ms" => State.calc_duration(sf) })
-      send_event("task.progress", message, task_id)
+    def progress(message) = send_event("task.progress", message)
+
+    def loop(message)
+      s = State.read(@sf)
+      State.update(@sf, { "loop_count" => s["loop_count"].to_i + 1 })
+      send_event("task.loop", message)
     end
 
-    def task_loop(message, task_id)
-      sf    = State.file(@agent, task_id)
-      s     = State.read(sf)
-      count = s["loop_count"].to_i + 1
-      State.update(sf, { "duration_ms" => State.calc_duration(sf), "loop_count" => count })
-      send_event("task.loop", message, task_id)
+    def retry
+      s = State.read(@sf)
+      State.update(@sf, { "retry_count" => s["retry_count"].to_i + 1 })
+      send_event("task.retry", "Retrying task")
     end
 
-    def task_retry(task_id)
-      sf    = State.file(@agent, task_id)
-      s     = State.read(sf)
-      count = s["retry_count"].to_i + 1
-      State.update(sf, { "duration_ms" => State.calc_duration(sf), "retry_count" => count })
-      send_event("task.retry", "Retrying task", task_id)
+    def pause(message)
+      s = State.read(@sf)
+      State.update(@sf, {
+        "paused_at"   => State.now_ms,
+        "pause_count" => s["pause_count"].to_i + 1
+      })
+      send_event("task.paused", message)
     end
 
-    def task_error(message, task_id)
-      sf = State.file(@agent, task_id)
-      State.update(sf, { "duration_ms" => State.calc_duration(sf), "last_error" => message })
-      send_event("task.error", message, task_id)
+    def resume(message)
+      s       = State.read(@sf)
+      now     = State.now_ms
+      updates = {}
+      if s["paused_at"].to_i > 0
+        updates["pause_total_ms"] = s["pause_total_ms"].to_i + (now - s["paused_at"].to_i)
+        updates["paused_at"]      = nil
+      end
+      if s["wait_at"].to_i > 0
+        updates["wait_total_ms"] = s["wait_total_ms"].to_i + (now - s["wait_at"].to_i)
+        updates["wait_at"]       = nil
+      end
+      State.update(@sf, updates) unless updates.empty?
+      send_event("task.resumed", message)
     end
 
-    def task_complete(message, task_id)
-      sf = State.file(@agent, task_id)
-      State.update(sf, { "duration_ms" => State.calc_duration(sf) })
-      send_event("task.completed", message, task_id)
-      State.delete(sf)
+    def wait(message)
+      s = State.read(@sf)
+      State.update(@sf, {
+        "wait_at"    => State.now_ms,
+        "wait_count" => s["wait_count"].to_i + 1
+      })
+      send_event("task.waiting", message)
     end
 
-    def task_fail(message, task_id)
-      sf = State.file(@agent, task_id)
-      State.update(sf, { "duration_ms" => State.calc_duration(sf) })
-      send_event("task.failed", message, task_id)
-      State.delete(sf)
+    def stop = send_event("task.stopped", "Task stopped")
+
+    def error(message)
+      s = State.read(@sf)
+      State.update(@sf, { "last_error" => message, "error_count" => s["error_count"].to_i + 1 })
+      send_event("task.error", message)
     end
 
-    def task_timeout(message, task_id)
-      sf = State.file(@agent, task_id)
-      State.update(sf, { "duration_ms" => State.calc_duration(sf) })
-      send_event("task.timeout", message, task_id)
-      State.delete(sf)
+    def complete(message)
+      send_event("task.completed", message)
+      terminal
     end
 
-    def task_cancel(message, task_id)
-      sf = State.file(@agent, task_id)
-      State.update(sf, { "duration_ms" => State.calc_duration(sf) })
-      send_event("task.cancelled", message, task_id)
-      State.delete(sf)
+    def fail(message)
+      send_event("task.failed", message)
+      terminal
     end
 
-    def task_stop(task_id)
-      sf = State.file(@agent, task_id)
-      State.update(sf, { "duration_ms" => State.calc_duration(sf) })
-      send_event("task.stopped", "Task stopped", task_id)
+    def timeout(message)
+      send_event("task.timeout", message)
+      terminal
     end
 
-    def task_terminate(message, task_id)
-      sf = State.file(@agent, task_id)
-      State.update(sf, { "duration_ms" => State.calc_duration(sf) })
-      send_event("task.terminated", message, task_id)
-      State.delete(sf)
+    def cancel(message)
+      send_event("task.cancelled", message)
+      terminal
     end
 
-    # ── Input events ───────────────────────────────────────────────────────────
+    def terminate(message)
+      send_event("task.terminated", message)
+      terminal
+    end
 
-    def input_required(message, task_id)
-      send_event("input.required", message, task_id)
+    # ── Input / Output ─────────────────────────────────────────────────────────
+
+    def input_required(message)  = send_event("input.required",  message)
+    def input_approved(message)  = send_event("input.approved",  message)
+    def input_rejected(message)  = send_event("input.rejected",  message)
+    def output_generated(message) = send_event("output.generated", message)
+    def output_failed(message)   = send_event("output.failed",   message)
+
+    def track(event, message, meta: {})
+      send_event(event, message, extra_meta: meta)
     end
 
-    def input_approved(message, task_id)
-      send_event("input.approved", message, task_id)
+    private
+
+    def send_event(event, message, extra_meta: {})
+      @agent.send_payload(event, message, @run_id, @label, @sf, @metrics, extra_meta)
     end
 
-    def input_rejected(message, task_id)
-      send_event("input.rejected", message, task_id)
+    def terminal
+      State.delete(@sf)
+      State.delete_pointer(@agent.agent_name, @label)
     end
+  end
+
+  class Client
+    attr_reader :agent_name
 
-    # ── Output events ──────────────────────────────────────────────────────────
+    def initialize(agent, token: nil, secret: nil, state_ttl: 86400)
+      @agent_name = agent
+      @token      = token  || ENV["NOTILENS_TOKEN"]  || ""
+      @secret     = secret || ENV["NOTILENS_SECRET"] || ""
+      @state_ttl  = state_ttl
+      @metrics    = {}
 
-    def output_generated(message, task_id)
-      send_event("output.generated", message, task_id)
+      if @token.empty? || @secret.empty?
+        conf    = Config.get_agent(agent) || {}
+        @token  = conf["token"]  if @token.empty?
+        @secret = conf["secret"] if @secret.empty?
+      end
+
+      if @token.to_s.empty? || @secret.to_s.empty?
+        raise "NotiLens: token and secret are required. Pass them directly, " \
+              "set NOTILENS_TOKEN/NOTILENS_SECRET env vars, or run: " \
+              "notilens init --agent #{agent} --token TOKEN --secret SECRET"
+      end
+
+      State.cleanup_stale(agent, state_ttl)
+
+      # Single background worker — one thread shared across all sends
+      @_queue = SizedQueue.new(256)
+      token_w  = @token
+      secret_w = @secret
+      @_worker = Thread.new do
+        while (job = @_queue.pop)
+          Notify.send(token_w, secret_w, job) rescue nil
+        end
+      end
     end
 
-    def output_failed(message, task_id)
-      send_event("output.failed", message, task_id)
+    # ── Task factory ───────────────────────────────────────────────────────────
+
+    def task(label)
+      State.cleanup_stale(@agent_name, @state_ttl)
+      Run.new(self, label, gen_run_id)
     end
 
-    # ── Generic emit ───────────────────────────────────────────────────────────
+    # ── Agent-level metrics ────────────────────────────────────────────────────
 
-    def emit(event, message, meta: {})
-      send_event(event, message, "", extra_meta: meta)
+    def metric(key, value)
+      if value.is_a?(Numeric) && @metrics[key].is_a?(Numeric)
+        @metrics[key] += value
+      else
+        @metrics[key] = value
+      end
+      self
     end
 
-    private
+    def reset_metrics(key = nil)
+      key ? @metrics.delete(key) : @metrics.clear
+      self
+    end
 
-    def send_event(event, message, task_id, extra_meta: {})
-      title = task_id.to_s.empty? \
-        ? "#{@agent} | #{event}" \
-        : "#{@agent} | #{task_id} | #{event}"
-
-      duration = retry_count = loop_count = 0
-      unless task_id.to_s.empty?
-        sf = State.file(@agent, task_id)
-        s  = State.read(sf)
-        duration    = s["duration_ms"].to_i
-        retry_count = s["retry_count"].to_i
-        loop_count  = s["loop_count"].to_i
+    # ── Generic track ──────────────────────────────────────────────────────────
+
+    def track(event, message, meta: {})
+      send_payload(event, message, "", "", "", @metrics, meta)
+    end
+
+    # ── Internal (called by Run) ───────────────────────────────────────────────
+
+    def send_payload(event, message, run_id, label, state_file, run_metrics, extra_meta = {})
+      title = label.to_s.empty? \
+        ? "#{@agent_name} | #{event}" \
+        : "#{@agent_name} | #{label} | #{event}"
+
+      meta = { "agent" => @agent_name }
+      meta["run_id"] = run_id unless run_id.to_s.empty?
+      meta["task"]   = label  unless label.to_s.empty?
+
+      unless state_file.to_s.empty?
+        state = State.read(state_file)
+        now         = State.now_ms
+        start_time  = state["start_time"].to_i
+        queued_at   = state["queued_at"].to_i
+        pause_total = state["pause_total_ms"].to_i
+        wait_total  = state["wait_total_ms"].to_i
+        pause_total += now - state["paused_at"].to_i if state["paused_at"].to_i > 0
+        wait_total  += now - state["wait_at"].to_i   if state["wait_at"].to_i > 0
+
+        total_ms  = start_time > 0 ? now - start_time : 0
+        queue_ms  = (start_time > 0 && queued_at > 0) ? start_time - queued_at : 0
+        active_ms = [0, total_ms - pause_total - wait_total].max
+
+        meta["total_duration_ms"] = total_ms   if total_ms   > 0
+        meta["queue_ms"]          = queue_ms   if queue_ms   > 0
+        meta["pause_ms"]          = pause_total if pause_total > 0
+        meta["wait_ms"]           = wait_total  if wait_total  > 0
+        meta["active_ms"]         = active_ms  if active_ms  > 0
+
+        rc = state["retry_count"].to_i; meta["retry_count"] = rc if rc > 0
+        lc = state["loop_count"].to_i;  meta["loop_count"]  = lc if lc > 0
+        ec = state["error_count"].to_i; meta["error_count"] = ec if ec > 0
+        pc = state["pause_count"].to_i; meta["pause_count"] = pc if pc > 0
+        wc = state["wait_count"].to_i;  meta["wait_count"]  = wc if wc > 0
+        (state["metrics"] || {}).each { |k, v| meta[k] = v }
       end
 
-      meta = { "agent" => @agent }
-      meta["duration_ms"]  = duration    if duration    > 0
-      meta["retry_count"]  = retry_count if retry_count > 0
-      meta["loop_count"]   = loop_count  if loop_count  > 0
-      @metrics.each { |k, v| meta[k] = v }
+      run_metrics.each { |k, v| meta[k] = v }
       meta.merge!(extra_meta)
 
       image_url    = meta.delete("image_url").to_s
@@ -191,8 +299,8 @@ module NotiLens
         "title"         => title,
         "message"       => message,
         "type"          => Notify.event_type(event),
-        "agent"         => @agent,
-        "task_id"       => task_id,
+        "agent"         => @agent_name,
+        "task_id"       => label,
         "is_actionable" => is_actionable,
         "image_url"     => image_url,
         "open_url"      => open_url,
@@ -202,12 +310,21 @@ module NotiLens
         "meta"          => meta
       }
 
-      Notify.send(@token, @secret, payload)
+      # Fire-and-forget — push to background worker queue, never blocks the caller
+      @_queue.push(payload)
+    end
+
+    private
+
+    def gen_run_id
+      "run_#{State.now_ms}_#{SecureRandom.hex(4)}"
     end
   end
 
-  # Convenience factory: NotiLens.init("agent")
-  def self.init(agent, token: nil, secret: nil)
-    Client.new(agent, token: token, secret: secret)
+  # Convenience factory
+  def self.init(agent, token: nil, secret: nil, state_ttl: 86400)
+    Client.new(agent, token: token, secret: secret, state_ttl: state_ttl)
   end
 end
+
+require "securerandom"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: notilens
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - NotiLens
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-26 00:00:00.000000000 Z
+date: 2026-03-27 00:00:00.000000000 Z
 dependencies: []
 description: Send task started/progress/complete/failed notifications from AI agents,
   Sidekiq workers, and any Ruby application.