Live agent collaboration: the event inbox, honest presence, and every way to wake an agent

app/admin/agent_events.rb

@@ -0,0 +1,28 @@
+ActiveAdmin.register CoPlan::AgentEvent, as: "AgentEvent" do
+  # Inbox rows are written by the platform and acked by agents; admin is
+  # for inspection only (a stuck inbox, a delivery question).
+  actions :index, :show
+
+  index do
+    id_column
+    column :event_type
+    column :plan
+    column :api_token
+    column :acked_at
+    column :created_at
+  end
+
+  show do
+    attributes_table do
+      row :id
+      row :event_type
+      row :plan
+      row :api_token
+      row :comment_thread_id
+      row :comment_id
+      row :payload
+      row :acked_at
+      row :created_at
+    end
+  end
+end

app/admin/agent_sessions.rb

@@ -0,0 +1,38 @@
+ActiveAdmin.register CoPlan::AgentSession, as: "AgentSession" do
+  # Read-mostly: sessions are claimed and updated over the API. Destroy
+  # stays available so an operator can clear a stuck row.
+  actions :index, :show, :destroy
+
+  index do
+    selectable_column
+    id_column
+    column :agent_name
+    column :plan
+    column :api_token
+    column :state
+    column :state_detail
+    column :last_activity_at
+    column :wakes_answered_count
+    column :wake_failures_count
+    actions
+  end
+
+  show do
+    attributes_table do
+      row :id
+      row :agent_name
+      row :plan
+      row :api_token
+      row :state
+      row :state_detail
+      row :last_activity_at
+      row :last_transport_at
+      # wake_secret is deliberately not rendered — it's a credential.
+      row :wake_url
+      row :wakes_answered_count
+      row :wake_failures_count
+      row :created_at
+      row :updated_at
+    end
+  end
+end

config/initializers/coplan.rb

@@ -40,6 +40,14 @@
   #   }
   # }
 
+  # Wake webhook egress: the engine default refuses URLs whose hosts
+  # resolve to private/loopback/link-local space (SSRF). Locally that's
+  # exactly where agents live, and specs use non-resolving example hosts,
+  # so dev and test allow any well-formed http(s) URL.
+  if Rails.env.development? || Rails.env.test?
+    config.wake_url_policy = ->(uri) { true }
+  end
+
   config.notification_handler = ->(event, payload) {
     case event
     when :comment_created

db/cable_schema.rb

@@ -4,8 +4,8 @@
     t.binary "payload", limit: 536870912, null: false
     t.datetime "created_at", null: false
     t.integer "channel_hash", limit: 8, null: false
-    t.index ["channel"], name: "index_solid_cable_messages_on_channel"
-    t.index ["channel_hash"], name: "index_solid_cable_messages_on_channel_hash"
-    t.index ["created_at"], name: "index_solid_cable_messages_on_created_at"
+    t.index [ "channel" ], name: "index_solid_cable_messages_on_channel"
+    t.index [ "channel_hash" ], name: "index_solid_cable_messages_on_channel_hash"
+    t.index [ "created_at" ], name: "index_solid_cable_messages_on_created_at"
   end
 end

db/cache_schema.rb

@@ -5,8 +5,8 @@
     t.datetime "created_at", null: false
     t.integer "key_hash", limit: 8, null: false
     t.integer "byte_size", limit: 4, null: false
-    t.index ["byte_size"], name: "index_solid_cache_entries_on_byte_size"
-    t.index ["key_hash", "byte_size"], name: "index_solid_cache_entries_on_key_hash_and_byte_size"
-    t.index ["key_hash"], name: "index_solid_cache_entries_on_key_hash", unique: true
+    t.index [ "byte_size" ], name: "index_solid_cache_entries_on_byte_size"
+    t.index [ "key_hash", "byte_size" ], name: "index_solid_cache_entries_on_key_hash_and_byte_size"
+    t.index [ "key_hash" ], name: "index_solid_cache_entries_on_key_hash", unique: true
   end
 end

db/migrate/20260807215107_create_agent_collaboration_tables.co_plan.rb

@@ -0,0 +1,59 @@
+# This migration comes from co_plan (originally 20260807000000)
+class CreateAgentCollaborationTables < ActiveRecord::Migration[8.1]
+  # Guarded because these objects may already exist on both sides of the
+  # split this migration heals: databases loaded from schema.rb carry the
+  # tables (they leaked into the schema via #175's regeneration against a
+  # dev database), and api_tokens.agent_name ships with the identity
+  # migration (20260815000000), which runs first on hosts that install
+  # this one later.
+  def change
+    # Durable per-agent event inbox. IDs are UUIDv7 (time-ordered), so the
+    # id doubles as the pagination cursor: "give me events after <id>".
+    unless table_exists?(:coplan_agent_events)
+      create_table :coplan_agent_events, id: { type: :string, limit: 36 } do |t|
+        t.string :api_token_id, limit: 36, null: false
+        t.string :plan_id, limit: 36, null: false
+        t.string :comment_thread_id, limit: 36
+        t.string :comment_id, limit: 36
+        t.string :event_type, null: false
+        t.json :payload
+        t.datetime :acked_at
+        t.datetime :created_at, null: false
+
+        t.index [ :api_token_id, :id ]
+        t.index [ :api_token_id, :acked_at ]
+        t.index :plan_id
+      end
+
+      add_foreign_key :coplan_agent_events, :coplan_api_tokens, column: :api_token_id
+      add_foreign_key :coplan_agent_events, :coplan_plans, column: :plan_id
+    end
+
+    # One session per (plan, agent token) — Linear-style delegation state
+    # machine driving the presence pill: pending / active / awaiting_input /
+    # complete / stale.
+    unless table_exists?(:coplan_agent_sessions)
+      create_table :coplan_agent_sessions, id: { type: :string, limit: 36 } do |t|
+        t.string :plan_id, limit: 36, null: false
+        t.string :api_token_id, limit: 36, null: false
+        t.string :agent_name, null: false
+        t.string :state, null: false, default: "pending"
+        t.string :state_detail
+        t.datetime :last_activity_at
+        t.timestamps
+
+        t.index [ :plan_id, :api_token_id ], unique: true
+        t.index :api_token_id
+      end
+
+      add_foreign_key :coplan_agent_sessions, :coplan_api_tokens, column: :api_token_id
+      add_foreign_key :coplan_agent_sessions, :coplan_plans, column: :plan_id
+    end
+
+    # Stable display identity for an agent token, instead of the free-text
+    # per-comment agent_name. Normally added by 20260815000000 already.
+    unless column_exists?(:coplan_api_tokens, :agent_name)
+      add_column :coplan_api_tokens, :agent_name, :string
+    end
+  end
+end

db/migrate/20260820193542_add_wake_plumbing_to_agent_sessions.co_plan.rb

@@ -0,0 +1,34 @@
+# This migration comes from co_plan (originally 20260820000000)
+class AddWakePlumbingToAgentSessions < ActiveRecord::Migration[8.0]
+  # Guarded like 20260807000000: main's schema.rb has carried leaked
+  # agent-collab structure before, so never assume a clean slate.
+  def change
+    return unless table_exists?(:coplan_agent_sessions)
+
+    # Evidence a connection is actually parked on this session's token —
+    # SSE heartbeats and long-poll parks touch it. Distinct from
+    # last_activity_at, which tracks the agent/state machine: a held
+    # socket must not keep a `pending` promise alive forever.
+    unless column_exists?(:coplan_agent_sessions, :last_transport_at)
+      add_column :coplan_agent_sessions, :last_transport_at, :datetime
+    end
+
+    # How many wakes this session has demonstrably answered (pending →
+    # an agent-driven state). Zero means the loop is unproven and the
+    # pill makes no wake promise.
+    unless column_exists?(:coplan_agent_sessions, :wakes_answered_count)
+      add_column :coplan_agent_sessions, :wakes_answered_count, :integer, default: 0, null: false
+    end
+
+    # Webhook wake: a session may register a URL CoPlan POSTs a signed
+    # "you have inbox items" ping to — the wake path for hosted agents
+    # that can receive HTTP but can't hold a connection or be resumed.
+    unless column_exists?(:coplan_agent_sessions, :wake_url)
+      add_column :coplan_agent_sessions, :wake_url, :string
+    end
+
+    unless column_exists?(:coplan_agent_sessions, :wake_secret)
+      add_column :coplan_agent_sessions, :wake_secret, :string
+    end
+  end
+end

db/migrate/20260820201255_add_wake_failures_count_to_agent_sessions.co_plan.rb

@@ -0,0 +1,11 @@
+# This migration comes from co_plan (originally 20260821000000)
+class AddWakeFailuresCountToAgentSessions < ActiveRecord::Migration[8.0]
+  def change
+    return unless table_exists?(:coplan_agent_sessions)
+    return if column_exists?(:coplan_agent_sessions, :wake_failures_count)
+
+    # Exhausted wake-webhook delivery runs since the last success; the
+    # URL is unregistered once this crosses WakeWebhookJob::MAX_EXHAUSTIONS.
+    add_column :coplan_agent_sessions, :wake_failures_count, :integer, default: 0, null: false
+  end
+end