notilens 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4f4a0ebf4c82fabed926e4c1f823449339cb5e9318a43b571ed9e0d7e5d959e4
+  data.tar.gz: 31adaa715cc3936496b80561cde5f7f1f08a551007325802b9bdcd8d9fa25c66
+SHA512:
+  metadata.gz: 24439ee3122debf3bbd68b3d4b6af2aa4d6970ae8addfbbabcef7345692e98d8b693872bdbf5d9ab6466977e2432db0f09d9caab9e589c3aa91a0e13347c7f8a
+  data.tar.gz: 165602c07940bcae4cf2843d5089b23316b31be68735a4a092fdd2d927470b8c4136d85010f72985495a2b4201546253dc34fc0805e1abf77138c3a86324e538

data/README.md

@@ -0,0 +1,129 @@
+# NotiLens Ruby SDK
+
+Ruby SDK and CLI for [NotiLens](https://notilens.com) — task lifecycle notifications for AI agents, Sidekiq workers, and any Ruby application.
+
+## Installation
+
+```bash
+gem install notilens
+```
+
+Or in your `Gemfile`:
+
+```ruby
+gem "notilens"
+```
+
+## Quick Start
+
+```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)
+```
+
+## Credentials
+
+Resolved in order:
+1. `token:` / `secret:` keyword args to `init`
+2. `NOTILENS_TOKEN` / `NOTILENS_SECRET` env vars
+3. Saved CLI config (`notilens init --agent ...`)
+
+```ruby
+nl = NotiLens.init("my-agent", token: "your-token", secret: "your-secret")
+```
+
+## SDK Reference
+
+### Task Lifecycle
+
+```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
+```
+
+### Output & Input Events
+
+```ruby
+nl.output_generated("Report ready", task_id)
+nl.output_failed("Rendering failed", task_id)
+
+nl.input_required("Approve deployment?", task_id)
+nl.input_approved("Approved", task_id)
+nl.input_rejected("Rejected", task_id)
+```
+
+### Metrics
+
+Numeric values accumulate; strings are replaced.
+
+```ruby
+nl.metric("tokens", 512)
+nl.metric("tokens", 128)    # now 640
+
+nl.reset_metrics("tokens")  # reset one key
+nl.reset_metrics            # reset all
+```
+
+### Generic Events
+
+```ruby
+nl.emit("custom.event", "Something happened")
+nl.emit("custom.event", "With meta", meta: { "key" => "value" })
+```
+
+## CLI
+
+### Install
+
+```bash
+gem install notilens
+```
+
+### Configure
+
+```bash
+notilens init --agent my-agent --token TOKEN --secret SECRET
+notilens agents
+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
+
+notilens emit my.event "msg" --agent my-agent
+notilens version
+```
+
+## Requirements
+
+- Ruby 2.7+
+- No external dependencies (uses stdlib `net/http` and `json`)

data/bin/notilens

@@ -0,0 +1,369 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.join(__dir__, "..", "lib")
+
+require "notilens"
+require "notilens/config"
+require "notilens/state"
+require "notilens/notify"
+require "notilens/version"
+
+# ── Helpers ───────────────────────────────────────────────────────────────────
+
+def positional_args(args)
+  pos  = []
+  rest = args.dup
+  while rest.first && !rest.first.start_with?("--")
+    pos << rest.shift
+  end
+  [pos, rest]
+end
+
+def parse_flags(args)
+  f = {
+    agent: "", task_id: "", 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 "--meta"
+      kv = args[i += 1].to_s
+      eq = kv.index("=")
+      f[:meta][kv[0...eq]] = kv[eq + 1..] if eq
+    end
+    i += 1
+  end
+  if f[:agent].empty?
+    $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)
+end
+
+def send_notify(event, message, f)
+  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])
+  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
+  (state["metrics"] || {}).each { |k, v| meta[k] = v }
+  f[:meta].each { |k, v| meta[k] = v }
+
+  title = "#{f[:agent]} | #{f[:task_id]} | #{event}"
+
+  ev_type = %w[info success warning urgent].include?(f[:type]) \
+    ? f[:type] : NotiLens::Notify.event_type(event)
+
+  is_actionable = if f[:is_actionable] != ""
+    f[:is_actionable].downcase == "true"
+  else
+    NotiLens::Notify.actionable_default?(event)
+  end
+
+  payload = {
+    "event"         => event,
+    "title"         => title,
+    "message"       => message,
+    "type"          => ev_type,
+    "agent"         => f[:agent],
+    "task_id"       => f[:task_id],
+    "is_actionable" => is_actionable,
+    "image_url"     => f[:image_url],
+    "open_url"      => f[:open_url],
+    "download_url"  => f[:download_url],
+    "tags"          => f[:tags],
+    "ts"            => Time.now.to_f,
+    "meta"          => meta
+  }
+
+  NotiLens::Notify.send(conf["token"], conf["secret"], payload)
+  sleep 0.3
+end
+
+# ── Commands ──────────────────────────────────────────────────────────────────
+
+command = ARGV[0]
+rest    = ARGV[1..]
+
+case command
+
+when "init"
+  agent = token = secret = ""
+  i = 0
+  while i < rest.length
+    case rest[i]
+    when "--agent"  then agent  = rest[i += 1].to_s
+    when "--token"  then token  = rest[i += 1].to_s
+    when "--secret" then secret = rest[i += 1].to_s
+    end
+    i += 1
+  end
+  if agent.empty? || token.empty? || secret.empty?
+    $stderr.puts "Usage: notilens init --agent <name> --token <token> --secret <secret>"
+    exit 1
+  end
+  NotiLens::Config.save_agent(agent, token, secret)
+  puts "✔ Agent '#{agent}' saved"
+
+when "agents"
+  agents = NotiLens::Config.list_agents
+  agents.empty? ? puts("No agents configured.") : agents.each { |a| puts "  #{a}" }
+
+when "remove-agent"
+  if rest.empty?
+    $stderr.puts "Usage: notilens remove-agent <agent>"
+    exit 1
+  end
+  NotiLens::Config.remove_agent(rest[0]) \
+    ? 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])
+  NotiLens::State.write(sf, {
+    "agent"       => f[:agent],
+    "task"        => f[:task_id],
+    "start_time"  => NotiLens::State.now_ms,
+    "retry_count" => 0,
+    "loop_count"  => 0
+  })
+  send_notify("task.started", "Task started", f)
+  puts "▶  Started: #{f[:agent]} | #{f[:task_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]}"
+
+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]}"
+
+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]}"
+
+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)"
+
+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)
+  $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]}"
+
+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]}"
+
+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]}"
+
+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]}"
+
+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]}"
+
+when "metric"
+  pos, rest2 = positional_args(rest)
+  f       = parse_flags(rest2)
+  sf      = NotiLens::State.file(f[:agent], f[:task_id])
+  state   = NotiLens::State.read(sf)
+  metrics = state["metrics"] || {}
+  pos.each do |kv|
+    eq = kv.index("=")
+    next unless eq
+    k = kv[0...eq]
+    v = kv[eq + 1..]
+    v = v.include?(".") ? v.to_f : v.to_i rescue v
+    if v.is_a?(Numeric) && metrics[k].is_a?(Numeric)
+      metrics[k] += v
+    else
+      metrics[k] = v
+    end
+  end
+  NotiLens::State.update(sf, { "metrics" => metrics })
+  puts "📊 Metrics: #{metrics.map { |k, v| "#{k}=#{v}" }.join(", ")}"
+
+when "metric.reset"
+  pos, rest2 = positional_args(rest)
+  f  = parse_flags(rest2)
+  sf = NotiLens::State.file(f[:agent], f[:task_id])
+  if pos[0]
+    state   = NotiLens::State.read(sf)
+    metrics = state["metrics"] || {}
+    metrics.delete(pos[0])
+    NotiLens::State.update(sf, { "metrics" => metrics })
+    puts "📊 Metric '#{pos[0]}' reset"
+  else
+    NotiLens::State.update(sf, { "metrics" => {} })
+    puts "📊 All metrics reset"
+  end
+
+when "output.generate"
+  pos, rest2 = positional_args(rest)
+  send_notify("output.generated", pos[0].to_s, parse_flags(rest2))
+
+when "output.fail"
+  pos, rest2 = positional_args(rest)
+  send_notify("output.failed", pos[0].to_s, parse_flags(rest2))
+
+when "input.required"
+  pos, rest2 = positional_args(rest)
+  send_notify("input.required", pos[0].to_s, parse_flags(rest2))
+
+when "input.approve"
+  pos, rest2 = positional_args(rest)
+  send_notify("input.approved", pos[0].to_s, parse_flags(rest2))
+
+when "input.reject"
+  pos, rest2 = positional_args(rest)
+  send_notify("input.rejected", pos[0].to_s, parse_flags(rest2))
+
+when "emit"
+  if rest.length < 2
+    $stderr.puts "Usage: notilens emit <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}"
+
+when "version"
+  puts "NotiLens v#{NotiLens::VERSION}"
+
+else
+  puts <<~USAGE
+    Usage:
+      notilens init --agent <name> --token <token> --secret <secret>
+      notilens agents
+      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>]
+
+    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>]
+
+    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>
+
+    Generic:
+      notilens emit <event> "msg" --agent <agent>
+
+    Options:
+      --agent <name>
+      --task <id>
+      --type success|warning|urgent|info
+      --meta key=value   (repeatable)
+      --image_url <url>
+      --open_url <url>
+      --download_url <url>
+      --tags "tag1,tag2"
+      --is_actionable true|false
+
+    Other:
+      notilens version
+  USAGE
+  exit 1
+end

data/lib/notilens/config.rb

@@ -0,0 +1,42 @@
+require "json"
+
+module NotiLens
+  module Config
+    CONFIG_PATH = File.join(Dir.home, ".notilens_config.json")
+
+    def self.load
+      return {} unless File.exist?(CONFIG_PATH)
+      JSON.parse(File.read(CONFIG_PATH))
+    rescue
+      {}
+    end
+
+    def self.save(cfg)
+      File.write(CONFIG_PATH, JSON.pretty_generate(cfg))
+      File.chmod(0600, CONFIG_PATH)
+    end
+
+    def self.save_agent(agent, token, secret)
+      cfg = load
+      cfg[agent] = { "token" => token, "secret" => secret }
+      save(cfg)
+    end
+
+    def self.get_agent(agent)
+      cfg = load
+      cfg[agent]
+    end
+
+    def self.remove_agent(agent)
+      cfg = load
+      return false unless cfg.key?(agent)
+      cfg.delete(agent)
+      save(cfg)
+      true
+    end
+
+    def self.list_agents
+      load.keys
+    end
+  end
+end

data/lib/notilens/notify.rb

@@ -0,0 +1,48 @@
+require "net/http"
+require "uri"
+require "json"
+require_relative "version"
+
+module NotiLens
+  module Notify
+    WEBHOOK_URL = "https://hook.notilens.com/webhook/%s/send"
+
+    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
+    ACTIONABLE_EVENTS = %w[
+      task.error task.failed task.timeout task.retry task.loop
+      output.failed input.required input.rejected
+    ].freeze
+
+    def self.event_type(event)
+      return "success" if SUCCESS_EVENTS.include?(event)
+      return "urgent"  if URGENT_EVENTS.include?(event)
+      return "warning" if WARNING_EVENTS.include?(event)
+      "info"
+    end
+
+    def self.actionable_default?(event)
+      ACTIONABLE_EVENTS.include?(event)
+    end
+
+    def self.send(token, secret, payload)
+      uri  = URI(WEBHOOK_URL % token)
+      body = payload.to_json
+
+      req = Net::HTTP::Post.new(uri)
+      req["Content-Type"]    = "application/json"
+      req["X-NOTILENS-KEY"]  = secret
+      req["User-Agent"]      = "NotiLens-SDK/#{VERSION}"
+      req.body = body
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl     = true
+      http.read_timeout = 10
+      http.open_timeout = 10
+      http.request(req)
+    rescue
+      nil
+    end
+  end
+end

data/lib/notilens/state.rb

@@ -0,0 +1,50 @@
+require "json"
+require "tmpdir"
+
+module NotiLens
+  module State
+    def self.file(agent, task_id)
+      user   = ENV["USER"] || ENV["USERNAME"] || ""
+      agent  = agent.gsub(File::SEPARATOR, "_")
+      task_id = task_id.gsub(File::SEPARATOR, "_")
+      File.join(Dir.tmpdir, "notilens_#{user}_#{agent}_#{task_id}.json")
+    end
+
+    def self.read(path)
+      return {} unless File.exist?(path)
+      JSON.parse(File.read(path))
+    rescue
+      {}
+    end
+
+    def self.write(path, data)
+      File.write(path, JSON.pretty_generate(data))
+      File.chmod(0600, path)
+    rescue
+      nil
+    end
+
+    def self.update(path, updates)
+      s = read(path)
+      s.merge!(updates)
+      write(path, s)
+    end
+
+    def self.delete(path)
+      File.delete(path) if File.exist?(path)
+    rescue
+      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
+    end
+
+    def self.now_ms
+      (Time.now.to_f * 1000).to_i
+    end
+  end
+end

data/lib/notilens/version.rb

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

data/lib/notilens.rb

@@ -0,0 +1,213 @@
+require_relative "notilens/version"
+require_relative "notilens/config"
+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"] || ""
+      @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 ────────────────────────────────────────────────────────────────
+
+    def metric(key, value)
+      if value.is_a?(Numeric) && @metrics[key].is_a?(Numeric)
+        @metrics[key] += value
+      else
+        @metrics[key] = value
+      end
+      self
+    end
+
+    def reset_metrics(key = nil)
+      key ? @metrics.delete(key) : @metrics.clear
+      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
+      })
+      send_event("task.started", "Task started", id)
+      id
+    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)
+    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)
+    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)
+    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)
+    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)
+    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)
+    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)
+    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)
+    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)
+    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)
+    end
+
+    # ── Input events ───────────────────────────────────────────────────────────
+
+    def input_required(message, task_id)
+      send_event("input.required", message, task_id)
+    end
+
+    def input_approved(message, task_id)
+      send_event("input.approved", message, task_id)
+    end
+
+    def input_rejected(message, task_id)
+      send_event("input.rejected", message, task_id)
+    end
+
+    # ── Output events ──────────────────────────────────────────────────────────
+
+    def output_generated(message, task_id)
+      send_event("output.generated", message, task_id)
+    end
+
+    def output_failed(message, task_id)
+      send_event("output.failed", message, task_id)
+    end
+
+    # ── Generic emit ───────────────────────────────────────────────────────────
+
+    def emit(event, message, meta: {})
+      send_event(event, message, "", extra_meta: meta)
+    end
+
+    private
+
+    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
+      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 }
+      meta.merge!(extra_meta)
+
+      image_url    = meta.delete("image_url").to_s
+      open_url     = meta.delete("open_url").to_s
+      download_url = meta.delete("download_url").to_s
+      tags         = meta.delete("tags").to_s
+      is_actionable = meta.key?("is_actionable") \
+        ? meta.delete("is_actionable") \
+        : Notify.actionable_default?(event)
+
+      payload = {
+        "event"         => event,
+        "title"         => title,
+        "message"       => message,
+        "type"          => Notify.event_type(event),
+        "agent"         => @agent,
+        "task_id"       => task_id,
+        "is_actionable" => is_actionable,
+        "image_url"     => image_url,
+        "open_url"      => open_url,
+        "download_url"  => download_url,
+        "tags"          => tags,
+        "ts"            => Time.now.to_f,
+        "meta"          => meta
+      }
+
+      Notify.send(@token, @secret, payload)
+    end
+  end
+
+  # Convenience factory: NotiLens.init("agent")
+  def self.init(agent, token: nil, secret: nil)
+    Client.new(agent, token: token, secret: secret)
+  end
+end

data/notilens.gemspec

@@ -0,0 +1,20 @@
+require_relative "lib/notilens/version"
+
+Gem::Specification.new do |s|
+  s.name        = "notilens"
+  s.version     = NotiLens::VERSION
+  s.summary     = "NotiLens SDK — task lifecycle notifications for AI agents and background jobs"
+  s.description = "Send task started/progress/complete/failed notifications from AI agents, " \
+                  "Sidekiq workers, and any Ruby application."
+  s.authors     = ["NotiLens"]
+  s.email       = "hello@notilens.com"
+  s.homepage    = "https://github.com/notilens/sdk-ruby"
+  s.license     = "MIT"
+
+  s.files         = Dir["lib/**/*.rb", "bin/*", "README.md", "notilens.gemspec"]
+  s.bindir        = "bin"
+  s.executables   = ["notilens"]
+  s.require_paths = ["lib"]
+
+  s.required_ruby_version = ">= 2.7"
+end

metadata

@@ -0,0 +1,53 @@
+--- !ruby/object:Gem::Specification
+name: notilens
+version: !ruby/object:Gem::Version
+  version: 0.3.0
+platform: ruby
+authors:
+- NotiLens
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-03-26 00:00:00.000000000 Z
+dependencies: []
+description: Send task started/progress/complete/failed notifications from AI agents,
+  Sidekiq workers, and any Ruby application.
+email: hello@notilens.com
+executables:
+- notilens
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- bin/notilens
+- lib/notilens.rb
+- lib/notilens/config.rb
+- lib/notilens/notify.rb
+- lib/notilens/state.rb
+- lib/notilens/version.rb
+- notilens.gemspec
+homepage: https://github.com/notilens/sdk-ruby
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.26
+signing_key:
+specification_version: 4
+summary: NotiLens SDK — task lifecycle notifications for AI agents and background
+  jobs
+test_files: []