superkick 0.1.0

data/lib/superkick/team/log.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module Superkick
+  module Team
+    # Log — append-only shared log for a team of agents.
+    #
+    # Each team has its own log stored at ~/.superkick/teams/<team_id>.log as
+    # newline-delimited JSON (same framing pattern as IPC). Teammates append
+    # status updates, decisions, blockers, messages, lifecycle events, and
+    # artifact publications. Any teammate can read the log.
+    #
+    # Entry schema:
+    #   timestamp       — ISO 8601 UTC with microseconds
+    #   category        — :update, :message, :lifecycle, :system, :artifact
+    #   agent_id        — the agent that created this entry
+    #   agent_role      — team role of the agent (lead, worker, member)
+    #   role            — human-readable role label (optional)
+    #   message         — free-text content
+    #   kind            — sub-type within the category (e.g. :blocker, :decision, :spawned)
+    #   target_agent_id — recipient agent for messages (optional)
+    #   artifact_name   — name of published artifact (optional)
+    class Log
+      Entry = Data.define(
+        :timestamp, :category, :agent_id, :agent_role,
+        :role, :message, :kind, :target_agent_id, :artifact_name
+      ) do
+        # Build an Entry from a parsed hash, filling nil defaults for optional
+        # fields that were compacted away during persistence.
+        def self.from_hash(raw)
+          raw[:category] = raw[:category].to_sym if raw[:category]
+          raw[:kind] = raw[:kind].to_sym if raw[:kind]
+          defaults = members.each_with_object({}) { |m, h| h[m] = nil }
+          new(**defaults.merge(raw))
+        end
+      end
+
+      CATEGORIES = %i[update message lifecycle system artifact].freeze
+
+      attr_reader :team_id
+
+      def initialize(team_id, teams_dir: Superkick.config.teams_dir)
+        @team_id = team_id
+        @entries = []
+        @mutex = Mutex.new
+        @file_path = File.join(teams_dir, "#{team_id}.log")
+        FileUtils.mkdir_p(File.dirname(@file_path))
+        load_from_disk
+      end
+
+      def append(agent_id:, agent_role:, category:, message:,
+        role: nil, kind: nil, target_agent_id: nil, artifact_name: nil)
+        cat = category.to_sym
+        unless CATEGORIES.include?(cat)
+          raise ArgumentError, "Invalid category: #{category}. Must be one of: #{CATEGORIES.join(", ")}"
+        end
+
+        entry = Entry.new(
+          timestamp: Time.now.utc.strftime("%Y-%m-%dT%H:%M:%S.%6NZ"),
+          category: cat,
+          agent_id: agent_id.to_s,
+          agent_role: agent_role.to_s,
+          role: role,
+          message: message.to_s,
+          kind: kind&.to_sym,
+          target_agent_id: target_agent_id,
+          artifact_name: artifact_name
+        )
+
+        @mutex.synchronize do
+          @entries << entry
+          persist_entry(entry)
+        end
+
+        entry
+      end
+
+      def entries(since: nil, category: nil)
+        @mutex.synchronize do
+          result = @entries.dup
+          result = result.select { it.timestamp > since } if since
+          result = result.select { it.category == category.to_sym } if category
+          result
+        end
+      end
+
+      # Condensed view: latest entry per agent + any unresolved blockers.
+      def summary
+        @mutex.synchronize do
+          latest_by_agent = {}
+          blockers = []
+
+          @entries.each do |entry|
+            latest_by_agent[entry.agent_id] = entry
+            blockers << entry if entry.category == :update && entry.kind == :blocker
+          end
+
+          # Remove resolved blockers (if same agent posted a non-blocker after)
+          unresolved = blockers.select do |b|
+            latest = latest_by_agent[b.agent_id]
+            latest == b || (latest.category == :update && latest.kind == :blocker)
+          end
+
+          {latest_by_agent: latest_by_agent.values, unresolved_blockers: unresolved}
+        end
+      end
+
+      def size
+        @mutex.synchronize { @entries.size }
+      end
+
+      private
+
+      def persist_entry(entry)
+        # Only persist non-nil fields to keep the NDJSON compact
+        h = entry.to_h.compact
+        File.open(@file_path, "a") do |f|
+          f.puts(JSON.generate(h))
+          f.flush
+        end
+      rescue => e
+        Superkick.logger.warn("team_log") { "Failed to persist entry: #{e.message}" }
+      end
+
+      def load_from_disk
+        return unless File.exist?(@file_path)
+
+        File.readlines(@file_path).each do |line|
+          raw = JSON.parse(line.strip, symbolize_names: true)
+          @entries << Entry.from_hash(raw)
+        rescue JSON::ParserError, ArgumentError
+          next
+        end
+      rescue => e
+        Superkick.logger.warn("team_log") { "Failed to load team log: #{e.message}" }
+      end
+    end
+  end
+
+  # Backwards-compatible alias
+end

data/lib/superkick/team/log_entry_drop.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Superkick
+  module Team
+    # Liquid Drop for team log entries. Wraps the symbol-keyed hash
+    # from Team::Log::Entry#to_h so the team_digest template can access
+    # properties via dot notation (e.g. {{ e.agent_id }}, {{ e.kind }}).
+    class LogEntryDrop < Superkick::Drop
+      def self.drop_type = "team_log_entry"
+
+      def timestamp = @data[:timestamp]
+
+      def category = @data[:category].to_s
+
+      def agent_id = @data[:agent_id]
+
+      def agent_role = @data[:agent_role]
+
+      def role = @data[:role]
+
+      def message = @data[:message]
+
+      def kind = @data[:kind].to_s
+
+      def target_agent_id = @data[:target_agent_id]
+
+      def artifact_name = @data[:artifact_name]
+    end
+  end
+
+  # Backwards-compatible alias
+end
+
+Superkick::Drop.register(Superkick::Team::LogEntryDrop)

data/lib/superkick/team/log_monitor.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Superkick
+  module Team
+    # LogMonitor — polls the team log and injects digest events.
+    #
+    # Registered as `:team_log` in the Monitor registry. Auto-added by the
+    # server for team leads and human team members (`:member`). Workers can
+    # opt in via superkick_add_monitor.
+    #
+    # On each tick, reads team log entries since the last injection, filters
+    # out self-entries, and dispatches a single `team_digest` event with
+    # batched entries grouped by category.
+    #
+    # Config:
+    #   team_id  — (required) the team to watch
+    class LogMonitor < Monitor
+      class << self
+        def type = :team_log
+
+        def description
+          "Polls the team log and injects digest summaries of teammate activity."
+        end
+
+        def required_config = %i[team_id]
+
+        def event_types = %w[team_digest]
+
+        def templates_dir
+          File.join(__dir__, "..", "templates", "team_log")
+        end
+      end
+
+      def on_start
+        @last_check_at = Time.now.utc.strftime("%Y-%m-%dT%H:%M:%S.%6NZ")
+      end
+
+      def tick
+        team_id = self[:team_id]
+        return unless team_id
+
+        log = team_log_store&.get(team_id)
+        return unless log
+
+        entries = log.entries(since: @last_check_at)
+
+        # Filter out entries from this agent (no self-echo)
+        agent_id = @agent&.id
+        entries = entries.reject { it.agent_id == agent_id }
+
+        return if entries.empty?
+
+        @last_check_at = entries.last.timestamp
+
+        # Group entries by category for the template
+        grouped = entries.group_by(&:category)
+
+        entry_drops = entries.map { Team::LogEntryDrop.new(it.to_h) }
+        grouped_drops = grouped.transform_keys(&:to_s).transform_values { |v| v.map { Team::LogEntryDrop.new(it.to_h) } }
+
+        has_blockers = entries.any? { it.category == :update && it.kind == :blocker }
+
+        dispatch(
+          event_type: :team_digest,
+          entries: entry_drops,
+          grouped: grouped_drops,
+          entry_count: entries.size,
+          has_blockers:,
+          agent_role: @agent&.team_role&.to_s || "unknown",
+          injection_ttl: 120,
+          **(has_blockers ? {injection_priority: :high} : {})
+        )
+      end
+
+      private
+
+      def team_log_store
+        server_context[:team_log_store]
+      end
+    end
+  end
+
+  Monitor.register(Team::LogMonitor)
+end

data/lib/superkick/team/log_notifier.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Superkick
+  module Team
+    # Writes team log entries as a notification side-effect.
+    #
+    # This notifier is automatically wired into the NotificationDispatcher
+    # when a team_log_store is available.  It converts notification payloads
+    # into Team::Log entries for any agent that belongs to a team.
+    #
+    # Not user-configurable — it's an internal notifier.
+    class LogNotifier < Superkick::Notifier
+      def self.type = :team_log
+
+      # Event type → { category:, kind: } mapping.
+      # Events not listed here are ignored (no team log entry).
+      EVENT_MAP = {
+        "agent_update" => {category: :update},
+        "teammate_message" => {category: :message},
+        "teammate_blocker" => {category: :update, kind: :blocker},
+        "agent_spawned" => {category: :lifecycle},
+        "worker_spawned" => {category: :lifecycle, kind: :spawned},
+        "agent_completed" => {category: :lifecycle, kind: :completed},
+        "agent_failed" => {category: :lifecycle, kind: :failed},
+        "agent_timed_out" => {category: :lifecycle, kind: :timed_out},
+        "agent_blocked" => {category: :lifecycle, kind: :blocked},
+        "agent_terminated" => {category: :lifecycle, kind: :terminated},
+        "agent_claimed" => {category: :lifecycle, kind: :claimed},
+        "agent_unclaimed" => {category: :lifecycle, kind: :unclaimed},
+        "artifact_published" => {category: :artifact}
+      }.freeze
+
+      def initialize(team_log_store:, **kwargs)
+        super(**kwargs)
+        @team_log_store = team_log_store
+      end
+
+      def stateful? = true
+
+      def notify(payload)
+        team_id = payload.dig(:context, :team)&.id
+        return unless team_id
+
+        mapping = EVENT_MAP[payload[:event_type]]
+        return unless mapping
+
+        entry = build_entry(payload, mapping)
+        log = @team_log_store.get_or_create(team_id)
+        log.append(**entry)
+      rescue => e
+        Superkick.logger.warn("notifier:team_log") { "Failed to write team log: #{e.message}" }
+      end
+
+      def agent_finished(agent_id:)
+        # No cleanup needed — team log entries are persistent
+      end
+
+      private
+
+      def build_entry(payload, mapping)
+        agent = payload.dig(:context, :agent)
+        event_kind = payload.dig(:context, :kind)
+
+        entry = {
+          agent_id: payload[:agent_id],
+          agent_role: agent&.team_role || "unknown",
+          role: agent&.role,
+          category: mapping[:category],
+          message: payload[:message]
+        }
+
+        # Kind: use mapping default, but allow event-level override (e.g. agent_update kinds)
+        # For agent_spawned, infer kind from team_role (member → joined, others → spawned)
+        kind = event_kind || mapping[:kind]
+        if payload[:event_type] == "agent_spawned" && !kind
+          kind = (agent&.team_role == "member") ? :joined : :spawned
+        end
+        entry[:kind] = kind
+
+        # Directed messages include target
+        if payload[:event_type] == "teammate_message"
+          target = payload.dig(:context, :target_agent_id) ||
+            payload[:monitor]&.name # fallback
+          entry[:target_agent_id] = target if target
+        end
+
+        # Artifact entries include the artifact name
+        if payload[:event_type] == "artifact_published"
+          entry[:artifact_name] = payload.dig(:context, :artifact_name)
+        end
+
+        entry
+      end
+    end
+  end
+end

data/lib/superkick/team/log_store.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Superkick
+  module Team
+    # LogStore — server-level registry of active team logs.
+    #
+    # Thread-safe. Lazily creates Team::Log instances on first access.
+    class LogStore
+      def initialize(teams_dir: Superkick.config.teams_dir)
+        @teams_dir = teams_dir
+        @logs = {}
+        @mutex = Mutex.new
+      end
+
+      # Get or create the team log for the given team_id.
+      def get_or_create(team_id)
+        @mutex.synchronize do
+          @logs[team_id.to_s] ||= Team::Log.new(team_id, teams_dir: @teams_dir)
+        end
+      end
+
+      # Get the team log if it exists, nil otherwise.
+      def get(team_id)
+        @mutex.synchronize { @logs[team_id.to_s] }
+      end
+
+      # List all active team IDs.
+      def team_ids
+        @mutex.synchronize { @logs.keys.dup }
+      end
+
+      # Remove the team log entry (does not delete the file).
+      def cleanup(team_id)
+        @mutex.synchronize { @logs.delete(team_id.to_s) }
+      end
+    end
+  end
+
+  # Backwards-compatible alias
+end

data/lib/superkick/template_filters.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Superkick
+  # Core Liquid filters available in all templates.
+  #
+  # These are registered globally on every Liquid::Environment.
+  # Integration-specific filters are declared inline via the `liquid do`
+  # DSL on each monitor/spawner class.
+  module TemplateFilters
+    def time(input = nil)
+      t = input.is_a?(Time) ? input : Time.now
+      t.strftime("%H:%M")
+    end
+
+    def short_sha(sha)
+      sha.to_s[0, 7]
+    end
+
+    def truncate(str, max = 72)
+      str = str.to_s
+      (str.length <= max) ? str : "#{str[0, max - 1]}…"
+    end
+  end
+end

data/lib/superkick/template_renderer.rb

@@ -0,0 +1,223 @@
+# frozen_string_literal: true
+
+require "liquid"
+require "time"
+
+module Superkick
+  # Resolves and renders Liquid templates for injected events.
+  #
+  # Resolution order:
+  #   1. ~/.superkick/templates/<monitor_name>/<event_type>.liquid  (user per-instance)
+  #   2. ~/.superkick/templates/<monitor_type>/<event_type>.liquid  (user per-type)
+  #   3. <Monitor.templates_dir>/<event_type>.liquid            (monitor bundled)
+  #
+  # Templates are rendered with Liquid. All event keys are available as
+  # template variables. Built-in filters: time, truncate, short_sha.
+  # Integration-specific filters are resolved via the monitor/spawner class.
+  module TemplateRenderer
+    FALLBACK_TEMPLATE = "SUPERKICK [{{ \"now\" | time }}]: {{ event_type }} — {{ monitor_name | truncate: 40 }}"
+
+    # Render an event hash to a string.
+    # @param event [Hash] must include :monitor_type and :event_type
+    # @return [String]
+    def self.render(event)
+      template_path = resolve(event)
+      source = template_path ? File.read(template_path, encoding: "utf-8") : FALLBACK_TEMPLATE
+      render_source(source, event, monitor_type: event[:monitor_type])
+    end
+
+    # Render a Liquid source string against an event hash.
+    # Useful for testing and for callers that have already resolved a template.
+    # @param source       [String]      Liquid template source
+    # @param event        [Hash]        event data; all keys become template variables
+    # @param monitor_type [String, nil] monitor type key; used to look up template filters
+    # @return [String]
+    def self.render_source(source, event, monitor_type: nil)
+      env = environment_for_type(monitor_type)
+      template = ::Liquid::Template.parse(source, environment: env)
+      assigns = build_assigns(event)
+      template.render(assigns).strip
+    rescue => e
+      Superkick.logger.error("renderer") { "Template render error: #{e.message}\n#{e.backtrace.first(5).join("\n")}" }
+      "SUPERKICK: #{event[:event_type]} in #{event[:repo]}"
+    end
+
+    # Copy all built-in monitor templates to ~/.superkick/templates/ for user customisation.
+    # Iterates every registered monitor and copies its bundled templates,
+    # namespaced under <type>/ within the user templates directory.
+    # @param force [Boolean] overwrite existing files
+    def self.install_defaults(force: false)
+      Monitor.registered.each do |type, monitor_class|
+        next unless (templates_dir = monitor_class.templates_dir) && File.directory?(templates_dir)
+
+        install_from(templates_dir, File.join(Superkick.config.templates_dir, type.to_s), force:)
+      end
+    end
+
+    # Copy all built-in spawner templates to ~/.superkick/templates/spawners/ for
+    # user customisation.  Iterates every registered Spawner and copies
+    # its bundled spawn templates, namespaced under spawners/<type>/.
+    # @param force [Boolean] overwrite existing files
+    def self.install_spawner_defaults(force: false)
+      Spawner.registered.each do |type, spawner_class|
+        next unless (templates_dir = spawner_class.spawn_templates_dir) && File.directory?(templates_dir)
+
+        install_from(templates_dir, File.join(Superkick.config.templates_dir, "spawners", type.to_s), force:)
+      end
+    end
+
+    def self.install_from(source_dir, dest_dir, force: false)
+      Dir.glob("#{source_dir}/**/*.liquid").each do |source_path|
+        rel = source_path.sub("#{source_dir}/", "")
+        dest = File.join(dest_dir, rel)
+
+        if File.exist?(dest) && !force
+          Superkick.logger.info("installer") { "Skipping (exists): #{dest}" }
+          next
+        end
+
+        FileUtils.mkdir_p(File.dirname(dest))
+        FileUtils.cp(source_path, dest)
+        Superkick.logger.info("installer") { "Installed: #{dest}" }
+      end
+    end
+    private_class_method :install_from
+
+    # Build a Liquid::Environment for a class that includes Superkick::Liquid.
+    # Combines global TemplateFilters + inline filters and block tags from the
+    # liquid_config DSL. Cached per class.
+    # @param klass [Class] monitor or spawner class
+    # @return [Liquid::Environment]
+    def self.environment_for(klass)
+      @environment_cache ||= {}
+      @environment_cache[klass] ||= build_environment(klass)
+    end
+
+    # Look up the monitor/spawner class for a type key and return its environment.
+    # Falls back to a global-filters-only environment for unknown types.
+    private_class_method def self.environment_for_type(monitor_type)
+      return global_environment unless monitor_type
+
+      key = monitor_type.to_sym
+      klass = Monitor.registered[key] || Spawner.registered[key]
+      return global_environment unless klass
+
+      environment_for(klass)
+    end
+
+    # Environment with only global TemplateFilters — used when no class-specific
+    # customizations are needed.
+    private_class_method def self.global_environment
+      @global_environment ||= ::Liquid::Environment.build do |env|
+        env.register_filter(TemplateFilters)
+      end
+    end
+
+    private_class_method def self.build_environment(klass)
+      config = klass.respond_to?(:liquid_config) ? klass.liquid_config : nil
+
+      ::Liquid::Environment.build do |env|
+        # Global filters — always present
+        env.register_filter(TemplateFilters)
+
+        # Inline filters from liquid_config DSL
+        if config && !config.filters.empty?
+          mod = Module.new
+          config.filters.each do |name, handler|
+            mod.define_method(name, &handler)
+          end
+          env.register_filter(mod)
+        end
+
+        # Block tags from liquid_config DSL
+        if config
+          config.blocks.each do |name, handler|
+            env.register_tag(name.to_s, NotifierTemplate.create_block_class(handler))
+          end
+
+          # Bodyless tags from liquid_config DSL
+          config.tags.each do |name, handler|
+            env.register_tag(name.to_s, NotifierTemplate.create_tag_class(handler))
+          end
+        end
+      end
+    end
+    private_class_method :build_environment
+
+    # Clear cached environments. Called from tests via reset_config!.
+    def self.reset_environments!
+      @environment_cache = nil
+      @global_environment = nil
+    end
+
+    # Build Liquid assigns from event hash.
+    # Liquid requires string keys.
+    private_class_method def self.build_assigns(event)
+      event.transform_keys(&:to_s)
+    end
+
+    # Resolve a notification template for a notifier class and event type.
+    # Returns the template source string, or nil if no template is found.
+    #
+    # Resolution order:
+    #   1. ~/.superkick/templates/notifications/<type>/<event_type>.liquid  (user override)
+    #   2. <Notifier.templates_dir>/<event_type>.liquid                    (bundled per-event)
+    #   3. ~/.superkick/templates/notifications/<type>/default.liquid       (user catch-all)
+    #   4. <Notifier.templates_dir>/default.liquid                         (bundled catch-all)
+    def self.resolve_notification(notifier_class, event_type)
+      type = notifier_class.type.to_s
+      event_type = event_type.to_s
+      user_dir = File.join(Superkick.config.templates_dir, "notifications", type)
+      bundled_dir = notifier_class.templates_dir
+
+      # 1. User per-event override
+      user_event = File.join(user_dir, "#{event_type}.liquid")
+      return File.read(user_event, encoding: "utf-8") if File.exist?(user_event)
+
+      # 2. Bundled per-event
+      if bundled_dir
+        bundled_event = File.join(bundled_dir, "#{event_type}.liquid")
+        return File.read(bundled_event, encoding: "utf-8") if File.exist?(bundled_event)
+      end
+
+      # 3. User default catch-all
+      user_default = File.join(user_dir, "default.liquid")
+      return File.read(user_default, encoding: "utf-8") if File.exist?(user_default)
+
+      # 4. Bundled default catch-all
+      if bundled_dir
+        bundled_default = File.join(bundled_dir, "default.liquid")
+        return File.read(bundled_default, encoding: "utf-8") if File.exist?(bundled_default)
+      end
+
+      nil
+    end
+
+    private_class_method def self.resolve(event)
+      monitor_type = event[:monitor_type]&.to_s
+      monitor_name = event[:monitor_name]&.to_s
+      event_type = event[:event_type]&.to_s  # Symbol from dispatch, needs String for path
+
+      return nil unless monitor_type && event_type
+
+      # 1. User per-instance override (by monitor name)
+      if monitor_name && monitor_name != monitor_type
+        name_path = File.join(Superkick.config.templates_dir, monitor_name, "#{event_type}.liquid")
+        return name_path if File.exist?(name_path)
+      end
+
+      # 2. User per-type override
+      user_path = File.join(Superkick.config.templates_dir, monitor_type, "#{event_type}.liquid")
+      return user_path if File.exist?(user_path)
+
+      # 3. Monitor bundled templates
+      monitor_class = Monitor.registered[monitor_type.to_sym]
+      if monitor_class&.templates_dir
+        bundled = File.join(monitor_class.templates_dir, "#{event_type}.liquid")
+        return bundled if File.exist?(bundled)
+      end
+
+      nil
+    end
+  end
+end

data/lib/superkick/templates/team_log/planning_agent.liquid

@@ -0,0 +1,38 @@
+You are a planning agent coordinating a team of AI coding agents.
+
+## Task
+{{ event_type }}: {{ title }}
+{{ description }}
+
+## Available repositories
+{{ repository_context }}
+
+## Your responsibilities
+1. Analyze the task and determine which repositories need changes.
+2. For each affected repository, define a clear sub-task with specific instructions.
+3. Spawn a worker agent for each repository using the superkick_spawn_worker tool.
+4. Monitor team progress using superkick_team_status.
+5. Coordinate between agents if one depends on another's work.
+6. Use superkick_post_update to share your planning decisions with the team.
+7. Read worker artifacts (implementation plans, summaries) to track detailed progress.
+
+## Available tools
+- superkick_spawn_worker: Create a worker agent for a specific repository
+- superkick_discover_repositories: List available repositories with descriptions and tags
+- superkick_team_status: Check what all teammates are doing
+- superkick_post_update: Broadcast a status update to the team
+- superkick_post_update (with target_agent_id): Send a message to a specific teammate
+- superkick_list_teammates: List all agents on your team
+- superkick_publish_artifact: Share structured data (plans, contracts) with the team
+- superkick_read_artifact: Read an artifact published by a teammate
+- superkick_list_artifacts: List all published artifacts
+- superkick_signal_goal: Signal when the team's work is complete
+
+## Guidelines
+- Spawn workers in parallel when their work is independent.
+- If repository B depends on repository A's changes, note this in repository B's
+  instructions and tell its worker to check team status before starting dependent work.
+- Keep sub-tasks focused — each worker should have a clear, achievable goal.
+- Give each worker a descriptive role label (e.g. "API migration", "Test writer").
+- Use superkick_post_update with category "decision" to explain your decomposition.
+- Read worker artifacts periodically to review their implementation plans.