openclacky 1.5.21 → 1.5.23

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (110) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +119 -0
  3. data/docs/secretary-prototype.md +286 -0
  4. data/lib/clacky/agent/session_serializer.rb +15 -11
  5. data/lib/clacky/agent.rb +58 -15
  6. data/lib/clacky/agent_config.rb +3 -1
  7. data/lib/clacky/agent_profile.rb +33 -6
  8. data/lib/clacky/billing/platform_billing.rb +9 -0
  9. data/lib/clacky/default_extensions/advisor/README.md +25 -0
  10. data/lib/clacky/default_extensions/advisor/README.zh.md +25 -0
  11. data/lib/clacky/default_extensions/advisor/ext.yml +1 -1
  12. data/lib/clacky/default_extensions/advisor/icon.svg +14 -0
  13. data/lib/clacky/default_extensions/coding/ext.yml +0 -1
  14. data/lib/clacky/default_extensions/computer-use/README.md +48 -0
  15. data/lib/clacky/default_extensions/computer-use/README.zh.md +48 -0
  16. data/lib/clacky/default_extensions/computer-use/ext.yml +1 -1
  17. data/lib/clacky/default_extensions/computer-use/icon.svg +16 -0
  18. data/lib/clacky/default_extensions/ext-studio/ext.yml +0 -1
  19. data/lib/clacky/default_extensions/general/ext.yml +0 -1
  20. data/lib/clacky/default_extensions/git/README.md +41 -0
  21. data/lib/clacky/default_extensions/git/README.zh.md +41 -0
  22. data/lib/clacky/default_extensions/git/ext.yml +1 -1
  23. data/lib/clacky/default_extensions/git/icon.svg +15 -0
  24. data/lib/clacky/default_extensions/git/panels/git/view.js +1960 -399
  25. data/lib/clacky/default_extensions/meeting/README.md +46 -0
  26. data/lib/clacky/default_extensions/meeting/README.zh.md +47 -0
  27. data/lib/clacky/default_extensions/meeting/ext.yml +1 -1
  28. data/lib/clacky/default_extensions/meeting/icon.svg +13 -0
  29. data/lib/clacky/default_extensions/preview/README.md +29 -0
  30. data/lib/clacky/default_extensions/preview/README.zh.md +29 -0
  31. data/lib/clacky/default_extensions/preview/ext.yml +1 -1
  32. data/lib/clacky/default_extensions/preview/icon.svg +13 -0
  33. data/lib/clacky/default_extensions/preview/panels/preview/view.js +199 -34
  34. data/lib/clacky/default_extensions/secretary/agents/secretary.md +41 -0
  35. data/lib/clacky/default_extensions/secretary/agents/worker.md +35 -0
  36. data/lib/clacky/default_extensions/secretary/api/handler.rb +8 -0
  37. data/lib/clacky/default_extensions/secretary/ext.yml +39 -0
  38. data/lib/clacky/default_extensions/secretary/panels/work/view.js +344 -0
  39. data/lib/clacky/default_extensions/secretary/tools/delegate_work.rb +37 -0
  40. data/lib/clacky/default_extensions/secretary/tools/manage_work.rb +22 -0
  41. data/lib/clacky/default_extensions/secretary/tools/yield_work.rb +35 -0
  42. data/lib/clacky/default_extensions/time_machine/README.md +32 -0
  43. data/lib/clacky/default_extensions/time_machine/README.zh.md +32 -0
  44. data/lib/clacky/default_extensions/time_machine/ext.yml +1 -1
  45. data/lib/clacky/default_extensions/time_machine/icon.svg +14 -0
  46. data/lib/clacky/default_skills/channel-manager/SKILL.md +79 -8
  47. data/lib/clacky/default_skills/channel-manager/discord_setup.rb +5 -1
  48. data/lib/clacky/default_skills/channel-manager/weixin_setup.rb +8 -1
  49. data/lib/clacky/default_skills/cron-task-creator/SKILL.md +183 -206
  50. data/lib/clacky/default_skills/cron-task-creator/evals/evals.json +45 -0
  51. data/lib/clacky/default_skills/media-gen/SKILL.md +17 -8
  52. data/lib/clacky/extension/api_extension.rb +10 -2
  53. data/lib/clacky/extension/loader.rb +2 -0
  54. data/lib/clacky/extension/verifier.rb +2 -2
  55. data/lib/clacky/locales/en.rb +14 -0
  56. data/lib/clacky/locales/zh.rb +14 -0
  57. data/lib/clacky/prompts/base.md +1 -1
  58. data/lib/clacky/providers.rb +68 -31
  59. data/lib/clacky/search_config.rb +33 -11
  60. data/lib/clacky/server/channel/adapters/base.rb +18 -0
  61. data/lib/clacky/server/channel/adapters/feishu/message_parser.rb +1 -0
  62. data/lib/clacky/server/channel/adapters/telegram/adapter.rb +1 -0
  63. data/lib/clacky/server/channel/channel_config.rb +185 -48
  64. data/lib/clacky/server/channel/channel_manager.rb +179 -66
  65. data/lib/clacky/server/git_panel.rb +362 -35
  66. data/lib/clacky/server/http_server.rb +530 -181
  67. data/lib/clacky/server/preview.rb +118 -17
  68. data/lib/clacky/server/scheduler.rb +211 -51
  69. data/lib/clacky/server/web_ui_controller.rb +35 -27
  70. data/lib/clacky/session_manager.rb +56 -6
  71. data/lib/clacky/tools/base.rb +7 -1
  72. data/lib/clacky/utils/file_processor.rb +20 -10
  73. data/lib/clacky/utils/mac_app_detector.rb +8 -7
  74. data/lib/clacky/utils/model_pricing.rb +60 -2
  75. data/lib/clacky/utils/windows_app_detector.rb +3 -1
  76. data/lib/clacky/version.rb +1 -1
  77. data/lib/clacky/web/app.css +1114 -205
  78. data/lib/clacky/web/app.js +143 -8
  79. data/lib/clacky/web/auth.js +1 -1
  80. data/lib/clacky/web/components/code-editor.js +73 -4
  81. data/lib/clacky/web/components/composer.js +107 -8
  82. data/lib/clacky/web/components/image-zoom.js +165 -0
  83. data/lib/clacky/web/components/model-picker.js +7 -5
  84. data/lib/clacky/web/components/notify.js +39 -12
  85. data/lib/clacky/web/components/onboard.js +1 -1
  86. data/lib/clacky/web/core/aside.js +60 -3
  87. data/lib/clacky/web/features/billing/view.js +2 -2
  88. data/lib/clacky/web/features/channels/store.js +19 -4
  89. data/lib/clacky/web/features/channels/view.js +92 -28
  90. data/lib/clacky/web/features/extensions/view.js +17 -10
  91. data/lib/clacky/web/features/new-session/store.js +79 -2
  92. data/lib/clacky/web/features/new-session/view.js +516 -75
  93. data/lib/clacky/web/features/skills/store.js +1 -1
  94. data/lib/clacky/web/features/tasks/store.js +5 -3
  95. data/lib/clacky/web/features/tasks/view.js +249 -66
  96. data/lib/clacky/web/features/workspace/store.js +13 -6
  97. data/lib/clacky/web/features/workspace/view.js +340 -214
  98. data/lib/clacky/web/i18n.js +366 -68
  99. data/lib/clacky/web/index.html +196 -165
  100. data/lib/clacky/web/projects.js +37 -4
  101. data/lib/clacky/web/sessions.js +263 -146
  102. data/lib/clacky/web/settings.js +241 -53
  103. data/lib/clacky/web/skills.js +2 -2
  104. data/lib/clacky/web/theme.js +17 -2
  105. data/lib/clacky/web/utils.js +234 -2
  106. data/lib/clacky/web/weixin-qr.html +2 -1
  107. data/lib/clacky/web/ws-dispatcher.js +14 -31
  108. data/lib/clacky/work/service.rb +542 -0
  109. data/lib/clacky/work/store.rb +57 -0
  110. metadata +31 -1
@@ -24,6 +24,7 @@ require_relative "preview"
24
24
  require_relative "web_ui_controller"
25
25
  require_relative "model_prices"
26
26
  require_relative "scheduler"
27
+ require_relative "../work/service"
27
28
  require_relative "../brand_config"
28
29
  require_relative "channel"
29
30
  require_relative "../banner"
@@ -75,26 +76,38 @@ module Clacky
75
76
  ev[:skill_command_display] = skill_command_display if skill_command_display
76
77
  ev[:editable] = false unless editable
77
78
  ev[:references] = references unless Array(references).empty?
78
- rendered = Array(files).filter_map do |f|
79
+ rendered_images = []
80
+ rendered_attachments = []
81
+ Array(files).each do |f|
82
+ next if f[:reference] || f["reference"]
83
+
79
84
  url = f[:data_url] || f["data_url"]
80
85
  name = f[:name] || f["name"]
81
86
  path = f[:path] || f["path"]
82
87
  type = f[:type] || f["type"] || ""
88
+ mime = f[:mime_type] || f["mime_type"]
89
+ image = type.to_s == "image" || mime.to_s.start_with?("image/")
83
90
 
84
91
  if url
85
- url
86
- elsif type.to_s == "image" && path && File.exist?(path.to_s)
92
+ rendered_images << url
93
+ elsif image && path && File.exist?(path.to_s)
87
94
  # Serve via the /api/local-image proxy instead of inlining a base64
88
95
  # data URL. Inlining forced a synchronous disk-read + full base64
89
96
  # encode + downscale on every history replay (2-3s lag for sessions
90
97
  # with downgraded text-model images). The proxy lets the browser
91
98
  # lazy-load + cache the image, keeping the replay response tiny.
92
- "/api/local-image?path=#{CGI.escape(path.to_s)}&v=#{File.mtime(path.to_s).to_i}"
99
+ rendered_images << "/api/local-image?path=#{CGI.escape(path.to_s)}&v=#{File.mtime(path.to_s).to_i}"
100
+ elsif image && name
101
+ rendered_images << "expired:#{name}"
93
102
  elsif name
94
- type.to_s == "image" ? "expired:#{name}" : "pdf:#{name}"
103
+ attachment_type = type.to_s.empty? ? (mime || "file") : type
104
+ attachment = { name: name, type: attachment_type }
105
+ attachment[:path] = path if path && File.exist?(path.to_s)
106
+ rendered_attachments << attachment
95
107
  end
96
108
  end
97
- ev[:images] = rendered unless rendered.empty?
109
+ ev[:images] = rendered_images unless rendered_images.empty?
110
+ ev[:attachments] = rendered_attachments unless rendered_attachments.empty?
98
111
  @events << ev
99
112
  end
100
113
 
@@ -257,14 +270,24 @@ module Clacky
257
270
  @ws_clients = {} # session_id => [WebSocketConnection, ...]
258
271
  @all_ws_conns = [] # every connected WS client, regardless of session subscription
259
272
  @ws_mutex = Mutex.new
273
+ @task_admission_mutex = Mutex.new
260
274
  # Version cache: { latest: "x.y.z", checked_at: Time }
261
275
  @version_cache = nil
262
276
  @version_mutex = Mutex.new
263
277
  @scheduler = Scheduler.new(
264
278
  session_registry: @registry,
265
279
  session_builder: method(:build_session),
266
- task_runner: method(:run_agent_task)
280
+ task_runner: method(:run_agent_task),
281
+ scheduled_dispatcher: ->(plan, prompt, due) { @work_service.dispatch_schedule(plan, prompt, due) }
282
+ )
283
+ @work_service = Clacky::Work::Service.new(
284
+ store: Clacky::Work::Store.new(File.join(sessions_dir || Clacky::SessionManager::SESSIONS_DIR, "work", "state.json")),
285
+ registry: @registry, build_session: method(:build_session), scheduler: @scheduler,
286
+ submit_task: method(:run_session_task), interrupt: method(:interrupt_session),
287
+ persist: ->(agent) { @session_manager.save(agent.to_session_data) },
288
+ publish: ->(sid, type) { broadcast(sid, { type: type, session_id: sid }) }
267
289
  )
290
+ @session_manager.protected_session_ids = -> { @work_service.protected_session_ids }
268
291
  @channel_manager = Clacky::Channel::ChannelManager.new(
269
292
  session_registry: @registry,
270
293
  session_builder: method(:build_session),
@@ -273,6 +296,7 @@ module Clacky
273
296
  # No updated_at: clearing a stale channel_info must not bump the session's
274
297
  # position in the newest-first list.
275
298
  persist_session: ->(agent) { @session_manager.save(agent.to_session_data) },
299
+ work_service: @work_service,
276
300
  channel_config: Clacky::ChannelConfig.load
277
301
  )
278
302
  @browser_manager = Clacky::BrowserManager.instance
@@ -297,6 +321,8 @@ module Clacky
297
321
  end
298
322
  end
299
323
 
324
+ attr_reader :work_service
325
+
300
326
  def start
301
327
  @start_time = Time.now
302
328
  # One-time migration: move legacy trash contents into file-trash/ subdirectory.
@@ -350,6 +376,7 @@ module Clacky
350
376
  next if shutdown_once
351
377
  shutdown_once = true
352
378
  @draining = true
379
+ @work_service.stop
353
380
  # Flip the process-wide cooperative shutdown flag FIRST so agent
354
381
  # threads poll it at safe points (stream chunk callbacks, retry
355
382
  # loops, main loop) and exit cleanly instead of spinning.
@@ -544,6 +571,7 @@ module Clacky
544
571
 
545
572
  # Start the background scheduler
546
573
  @scheduler.start
574
+ @work_service.start
547
575
  puts " Scheduler: #{@scheduler.schedules.size} task(s) loaded"
548
576
 
549
577
  # Reclaim orphaned Time Machine snapshots (sessions deleted earlier
@@ -565,6 +593,7 @@ module Clacky
565
593
 
566
594
  server.start unless @draining
567
595
  ensure
596
+ @work_service&.stop
568
597
  # close only this process's FD, never shutdown the shared kernel socket.
569
598
  @inherited_socket.close if @inherited_socket && !@inherited_socket.closed?
570
599
  end
@@ -785,14 +814,19 @@ module Clacky
785
814
  api_group_history(chat_id, res)
786
815
  elsif method == "GET" && path.match?(%r{^/api/channels/[^/]+/users$})
787
816
  platform = path.sub("/api/channels/", "").sub("/users", "")
788
- api_list_channel_users(platform, res)
817
+ api_list_channel_users(platform, req, res)
789
818
  elsif method == "POST" && path.match?(%r{^/api/channels/qq/qr/start$})
790
- api_qq_qr_start(res)
819
+ api_qq_qr_start(req, res)
791
820
  elsif method == "POST" && path.match?(%r{^/api/channels/qq/qr/poll$})
792
821
  api_qq_qr_poll(req, res)
793
822
  elsif method == "POST" && path.match?(%r{^/api/channels/[^/]+/test$})
794
823
  platform = path.sub("/api/channels/", "").sub("/test", "")
795
824
  api_test_channel(platform, req, res)
825
+ elsif method == "DELETE" && path.match?(%r{^/api/channels/[^/]+/instances/[^/]+$})
826
+ rest = path.sub("/api/channels/", "")
827
+ platform = rest.split("/").first
828
+ instance_id = URI.decode_www_form_component(rest.split("/").last)
829
+ api_delete_channel(platform, res, instance_id)
796
830
  elsif method == "PATCH" && path == "/api/channels/status_messages"
797
831
  api_channel_status_messages(req, res)
798
832
  elsif method == "PATCH" && path == "/api/channels/process_messages"
@@ -838,9 +872,6 @@ module Clacky
838
872
  session_id = path[%r{^/api/sessions/([^/]+)/git/}, 1]
839
873
  action = path[%r{/git/([a-z]+)$}, 1]
840
874
  api_session_git(session_id, action, req, res)
841
- elsif method == "POST" && path.match?(%r{^/api/sessions/[^/]+/git/commit$})
842
- session_id = path[%r{^/api/sessions/([^/]+)/git/}, 1]
843
- api_session_git_commit(session_id, req, res)
844
875
  elsif method == "POST" && path.match?(%r{^/api/sessions/[^/]+/git/restore$})
845
876
  session_id = path[%r{^/api/sessions/([^/]+)/git/}, 1]
846
877
  api_session_git_restore(session_id, req, res)
@@ -960,6 +991,12 @@ module Clacky
960
991
  elsif method == "DELETE" && path.match?(%r{^/api/memories/[^/]+$})
961
992
  filename = URI.decode_www_form_component(path.sub("/api/memories/", ""))
962
993
  api_memories_delete(filename, res)
994
+ elsif method == "GET" && path.match?(%r{^/api/projects/[^/]+/git$})
995
+ project_id = path.sub("/api/projects/", "").sub("/git", "")
996
+ api_project_git(project_id, req, res)
997
+ elsif method == "POST" && path.match?(%r{^/api/projects/[^/]+/git/checkout$})
998
+ project_id = path.sub("/api/projects/", "").sub("/git/checkout", "")
999
+ api_project_git_checkout(project_id, req, res)
963
1000
  elsif method == "PATCH" && path.match?(%r{^/api/projects/[^/]+$})
964
1001
  project_id = path.sub("/api/projects/", "")
965
1002
  api_update_project(project_id, req, res)
@@ -1428,6 +1465,12 @@ module Clacky
1428
1465
  agent_data = agent_profile_data
1429
1466
  agent_data.each do |name, data|
1430
1467
  ext_id = data["_ext_id"]
1468
+ # Base agent panels retain their extension-qualified IDs.
1469
+ base_unit = ext_result&.agents&.find { |unit| unit.id == data["base_agent"] }
1470
+ Array(base_unit&.spec&.dig("panels")).each do |panel|
1471
+ pid = panel.to_s
1472
+ add.call(pid.include?("/") ? pid : "#{base_unit.ext_id}/#{pid}", name)
1473
+ end
1431
1474
  Array(data["panels"]).each do |panel|
1432
1475
  pid = panel.to_s
1433
1476
  full = pid.include?("/") ? pid : (ext_id ? "#{ext_id}/#{pid}" : pid)
@@ -1446,7 +1489,9 @@ module Clacky
1446
1489
  if attach.include?("*")
1447
1490
  all_agent_ids.each { |a| add.call(full_id, a) }
1448
1491
  else
1449
- attach.each { |a| add.call(full_id, a) if all_agent_ids.include?(a) }
1492
+ all_agent_ids.each do |name|
1493
+ add.call(full_id, name) if attach.include?(name) || attach.include?(agent_data.dig(name, "base_agent"))
1494
+ end
1450
1495
  end
1451
1496
  end
1452
1497
  result
@@ -1460,6 +1505,7 @@ module Clacky
1460
1505
  Array(Clacky::ExtensionLoader.last_result&.agents).each do |unit|
1461
1506
  data[unit.id] = {
1462
1507
  "name" => unit.id,
1508
+ "base_agent" => unit.spec["base_agent"],
1463
1509
  "description" => unit.spec["description"],
1464
1510
  "panels" => unit.spec["panels"],
1465
1511
  "skills" => unit.spec["skills"],
@@ -1557,19 +1603,31 @@ module Clacky
1557
1603
 
1558
1604
  # Serve a file from a resolved extension container: /ext_ui/<ext_id>/<rel>.
1559
1605
  # The container dir is looked up via the loader (it may live in any layer),
1560
- # then strict path containment prevents escaping it. JS/CSS only, no-store.
1606
+ # then strict path containment prevents escaping it. Source files and the
1607
+ # icon set are allowed; everything else is refused.
1608
+ EXT_UI_TYPES = {
1609
+ ".js" => "application/javascript",
1610
+ ".css" => "text/css",
1611
+ ".png" => "image/png",
1612
+ ".jpg" => "image/jpeg",
1613
+ ".jpeg" => "image/jpeg",
1614
+ ".webp" => "image/webp",
1615
+ ".svg" => "image/svg+xml",
1616
+ ".gif" => "image/gif",
1617
+ }.freeze
1618
+
1561
1619
  private def serve_ext_ui(req, res)
1562
1620
  rel = req.path.delete_prefix("/ext_ui/")
1563
1621
  ext_id, _, sub = rel.partition("/")
1564
1622
 
1565
- unit = Clacky::ExtensionLoader.load_all.units.find { |u| u.ext_id == ext_id }
1566
- unless unit
1623
+ container = Clacky::ExtensionLoader.load_all.containers[ext_id]
1624
+ unless container
1567
1625
  res.status = 404
1568
1626
  res.body = "not found"
1569
1627
  return
1570
1628
  end
1571
1629
 
1572
- root = File.expand_path(unit.dir)
1630
+ root = File.expand_path(container[:dir].to_s)
1573
1631
  abs = File.expand_path(File.join(root, sub))
1574
1632
  unless abs.start_with?(root + File::SEPARATOR) && File.file?(abs)
1575
1633
  res.status = 404
@@ -1577,8 +1635,7 @@ module Clacky
1577
1635
  return
1578
1636
  end
1579
1637
 
1580
- ext = File.extname(abs)
1581
- ctype = { ".js" => "application/javascript", ".css" => "text/css" }[ext]
1638
+ ctype = EXT_UI_TYPES[File.extname(abs).downcase]
1582
1639
  unless ctype
1583
1640
  res.status = 415
1584
1641
  res.body = "unsupported media type"
@@ -1589,7 +1646,7 @@ module Clacky
1589
1646
  res["Content-Type"] = ctype
1590
1647
  res["Cache-Control"] = "no-store"
1591
1648
  res["Pragma"] = "no-cache"
1592
- res.body = File.read(abs)
1649
+ res.body = ctype.start_with?("image/") ? File.binread(abs) : File.read(abs)
1593
1650
  end
1594
1651
 
1595
1652
  # Serve agents/<name>/webui/<file> from built-in or user agent dir.
@@ -2321,7 +2378,7 @@ module Clacky
2321
2378
  json_response(res, 200, {
2322
2379
  ok: true,
2323
2380
  provider: config["provider"],
2324
- key_masked: config["key"].empty? ? nil : mask_api_key(config["key"]),
2381
+ keys_masked: masked_search_keys(config),
2325
2382
  available: Clacky::Utils::SearcherManager.available
2326
2383
  })
2327
2384
  end
@@ -2338,12 +2395,12 @@ module Clacky
2338
2395
  return json_response(res, 422, { error: "Unknown search provider: #{provider}" })
2339
2396
  end
2340
2397
 
2341
- key = body["key"].to_s
2342
- key = Clacky::SearchConfig.key if key.include?("****")
2343
-
2344
2398
  current = Clacky::SearchConfig.load
2345
2399
  final_provider = body.key?("provider") ? provider : current["provider"]
2346
- final_key = body.key?("key") ? key : current["key"]
2400
+ # A masked value only ever stands for the same provider's stored key.
2401
+ key = body["key"].to_s
2402
+ key = Clacky::SearchConfig.key_for(final_provider) if key.include?("****")
2403
+ final_key = body.key?("key") ? key : Clacky::SearchConfig.key_for(final_provider)
2347
2404
 
2348
2405
  # deepseek_web falls back to the configured model key, so it may be
2349
2406
  # saved without one. Every other searcher is a script that reads the
@@ -2361,11 +2418,15 @@ module Clacky
2361
2418
  key: body.key?("key") ? key : nil
2362
2419
  )
2363
2420
  config = Clacky::SearchConfig.load
2364
- json_response(res, 200, { ok: true, provider: config["provider"] })
2421
+ json_response(res, 200, { ok: true, provider: config["provider"], keys_masked: masked_search_keys(config) })
2365
2422
  rescue => e
2366
2423
  json_response(res, 422, { error: e.message })
2367
2424
  end
2368
2425
 
2426
+ private def masked_search_keys(config)
2427
+ config["keys"].transform_values { |key| mask_api_key(key) }
2428
+ end
2429
+
2369
2430
  private def search_provider_known?(provider)
2370
2431
  return true if provider.empty?
2371
2432
  return true if provider == Clacky::SearchConfig::DEEPSEEK_WEB
@@ -2382,7 +2443,7 @@ module Clacky
2382
2443
  return json_response(res, 200, { ok: false, message: "provider is required" }) if provider.empty?
2383
2444
 
2384
2445
  key = body["key"].to_s
2385
- key = Clacky::SearchConfig.key if key.empty? || key.include?("****")
2446
+ key = Clacky::SearchConfig.key_for(provider) if key.empty? || key.include?("****")
2386
2447
  return test_deepseek_web_search(res, key) if provider == Clacky::SearchConfig::DEEPSEEK_WEB
2387
2448
 
2388
2449
  script = Clacky::Utils::SearcherManager.path_for(provider)
@@ -2909,6 +2970,7 @@ module Clacky
2909
2970
  "description" => local_desc,
2910
2971
  "description_zh" => local_desc_zh,
2911
2972
  "author" => local_author,
2973
+ "icon_url" => extension_icon_url(container),
2912
2974
  "units" => local_units,
2913
2975
  "layer" => "builtin",
2914
2976
  "installed" => true,
@@ -2965,7 +3027,7 @@ module Clacky
2965
3027
  "description" => (label && label["description"]) || container.dig(:raw, "description").to_s,
2966
3028
  "description_zh" => (label && label["description_zh"]) || container.dig(:raw, "description_zh").to_s,
2967
3029
  "author" => (label && label["author"]) || container[:author].to_s,
2968
- "icon_url" => market&.dig("icon_url"),
3030
+ "icon_url" => builtin ? extension_icon_url(container) : (market&.dig("icon_url") || extension_icon_url(container)),
2969
3031
  "units" => (label && label["units"]) || units_from_container(container),
2970
3032
  "homepage" => (label && label["homepage"]) || container[:homepage].to_s,
2971
3033
  "origin" => (label && (label["origin"] || container[:origin])) || container[:origin],
@@ -3035,9 +3097,11 @@ module Clacky
3035
3097
 
3036
3098
  # GET /api/store/extension?id=<slug-or-id>[&source=brand]
3037
3099
  #
3038
- # Detail for a single extension. Pass source=brand to query brand-private
3039
- # extensions via the license-gated API; omit (or any other value) for the
3040
- # public marketplace API.
3100
+ # Detail for a single extension. A builtin ships with the gem and is not a
3101
+ # marketplace entry — its slug can collide with an unrelated published
3102
+ # extension, so it is answered from the local manifest without asking the
3103
+ # store. Pass source=brand to query brand-private extensions via the
3104
+ # license-gated API; omit (or any other value) for the public catalog.
3041
3105
  def api_store_extension_detail(req, res)
3042
3106
  id = req.query["id"].to_s
3043
3107
  if id.strip.empty?
@@ -3045,6 +3109,12 @@ module Clacky
3045
3109
  return
3046
3110
  end
3047
3111
 
3112
+ container = extension_container(id)
3113
+ if container && container[:layer] == :builtin
3114
+ json_response(res, 200, { ok: true, extension: local_extension_payload(container) })
3115
+ return
3116
+ end
3117
+
3048
3118
  brand = Clacky::BrandConfig.load
3049
3119
  result = if req.query["source"] == "brand"
3050
3120
  brand.brand_extension_detail!(id)
@@ -3062,44 +3132,85 @@ module Clacky
3062
3132
  "installed_version" => container&.dig(:version),
3063
3133
  "removable" => container && container[:layer] == :installed,
3064
3134
  "disabled" => container ? container[:disabled] == true : false,
3135
+ "icon_url" => ext["icon_url"] || (container && extension_icon_url(container)),
3065
3136
  )
3066
3137
  json_response(res, 200, { ok: true, extension: ext })
3138
+ elsif container && container[:layer] == :installed
3139
+ market = fetch_batch_market_data([id])[id]
3140
+ json_response(res, 200, { ok: true, extension: local_extension_payload(container, market: market) })
3067
3141
  else
3068
- container = extension_container(id)
3069
- if container && container[:layer] == :installed
3070
- market = fetch_batch_market_data([id])[id]
3071
- # Fall back to local ext.yml for self-authored extensions.
3072
- local_name = container[:name].to_s.then { |n| n.empty? ? id : n }
3073
- local_desc = container.dig(:raw, "description").to_s
3074
- local_author = container[:author].to_s
3075
- local_units = units_from_container(container)
3076
- ext = {
3077
- "id" => id,
3078
- "name" => market ? (market["name"] || id) : local_name,
3079
- "name_zh" => market&.dig("name_zh"),
3080
- "name_en" => market&.dig("name_en"),
3081
- "slug" => id,
3082
- "version" => market ? (market["version"] || container[:version]) : container[:version],
3083
- "installed_version" => container[:version],
3084
- "description" => market ? market["description"] : local_desc,
3085
- "author" => market ? market["author"] : local_author,
3086
- "icon_url" => market&.dig("icon_url"),
3087
- "units" => market ? market["units"] : local_units,
3088
- "homepage" => market ? (market["homepage"] || "") : container[:homepage].to_s,
3089
- "origin" => market ? (market["origin"] || container[:origin]) : container[:origin],
3090
- "hub_active" => market&.dig("hub_active"),
3091
- "unlisted" => market.nil? || market["unlisted"] == true,
3092
- "installed" => true,
3093
- "removable" => true,
3094
- "disabled" => container[:disabled] == true,
3095
- }
3096
- json_response(res, 200, { ok: true, extension: ext })
3097
- else
3098
- json_response(res, 404, { ok: false, error: result[:error] || "Not found" })
3099
- end
3142
+ json_response(res, 404, { ok: false, error: result[:error] || "Not found" })
3100
3143
  end
3101
3144
  end
3102
3145
 
3146
+ # Local manifest view of an installed extension, used when the marketplace
3147
+ # has nothing to say about it (or must not be asked at all).
3148
+ private def local_extension_payload(container, market: nil)
3149
+ builtin = container[:layer] == :builtin
3150
+ id = container[:ext_id].to_s
3151
+ # A builtin's manifest is the source of truth — plenty ship with the gem
3152
+ # and were never published.
3153
+ label = builtin ? nil : market
3154
+ local_name = container[:name].to_s.then { |n| n.empty? ? id : n }
3155
+ local_desc = container.dig(:raw, "description").to_s
3156
+
3157
+ {
3158
+ "id" => id,
3159
+ "name" => label ? (label["name"] || id) : local_name,
3160
+ "name_zh" => (label && label["name_zh"]) || container.dig(:raw, "name_zh"),
3161
+ "name_en" => (label && label["name_en"]) || container.dig(:raw, "name_en"),
3162
+ "display_name" => (label && label["display_name"]) || container.dig(:raw, "display_name") || local_name,
3163
+ "display_name_zh" => (label && label["display_name_zh"]) || container.dig(:raw, "display_name_zh"),
3164
+ "slug" => id,
3165
+ "version" => (label && label["version"]) || container[:version],
3166
+ "installed_version" => container[:version],
3167
+ "description" => (label && label["description"]) || local_desc,
3168
+ "description_zh" => (label && label["description_zh"]) || container.dig(:raw, "description_zh").to_s,
3169
+ "author" => (label && label["author"]) || container[:author].to_s,
3170
+ "icon_url" => builtin ? extension_icon_url(container) : ((label && label["icon_url"]) || extension_icon_url(container)),
3171
+ "units" => (label && label["units"]) || units_from_container(container),
3172
+ "homepage" => (label && label["homepage"]) || container[:homepage].to_s,
3173
+ "origin" => (label && label["origin"]) || container[:origin],
3174
+ "hub_active" => label && label["hub_active"],
3175
+ "download_count" => label ? label["download_count"].to_i : 0,
3176
+ "unlisted" => builtin ? false : (market.nil? || market["unlisted"] == true),
3177
+ "layer" => container[:layer].to_s,
3178
+ "installed" => true,
3179
+ "removable" => container[:layer] == :installed,
3180
+ "disabled" => container[:disabled] == true,
3181
+ "contributes" => container[:contributes] || {},
3182
+ "readme" => (label && label["readme"]).to_s.then { |r| r.strip.empty? ? local_extension_readme(container) : r },
3183
+ }
3184
+ end
3185
+
3186
+ # README.zh.md wins for Chinese clients; README.md is the fallback.
3187
+ private def local_extension_readme(container)
3188
+ dir = container[:dir].to_s
3189
+ return nil if dir.empty?
3190
+
3191
+ names = Thread.current[:lang].to_s.start_with?("zh") ? %w[README.zh.md README.md] : %w[README.md]
3192
+ path = names.map { |n| File.join(dir, n) }.find { |p| File.file?(p) }
3193
+ path && File.read(path, encoding: "UTF-8")
3194
+ end
3195
+
3196
+ # Public URL for an extension's local icon file, or nil when the manifest
3197
+ # names none (or the file is missing / outside the container). Served by
3198
+ # /ext_ui, so it works for every layer and while the extension is off.
3199
+ private def extension_icon_url(container)
3200
+ rel = container.dig(:raw, "icon").to_s.strip
3201
+ return nil if rel.empty?
3202
+
3203
+ ext_id = container[:ext_id].to_s
3204
+ dir = container[:dir].to_s
3205
+ return nil if ext_id.empty? || dir.empty?
3206
+
3207
+ root = File.expand_path(dir)
3208
+ abs = File.expand_path(File.join(root, rel))
3209
+ return nil unless abs.start_with?(root + File::SEPARATOR) && File.file?(abs)
3210
+
3211
+ "/ext_ui/#{ext_id}/#{rel}"
3212
+ end
3213
+
3103
3214
  # Locate an installed container by slug/id (nil when not installed).
3104
3215
  def extension_container(slug)
3105
3216
  return nil if slug.to_s.strip.empty?
@@ -4194,18 +4305,31 @@ module Clacky
4194
4305
  end
4195
4306
 
4196
4307
  def api_list_channels(res)
4197
- config = Clacky::ChannelConfig.load
4198
- running = @channel_manager.running_platforms
4308
+ config = Clacky::ChannelConfig.load
4309
+ running = @channel_manager.running_instances
4199
4310
 
4200
4311
  platforms = Clacky::Channel::Adapters.all.map do |klass|
4201
- platform = klass.platform_id
4202
- raw = config.instance_variable_get(:@channels)[platform.to_s] || {}
4312
+ platform = klass.platform_id
4313
+ instances = config.instances(platform).map do |inst|
4314
+ {
4315
+ id: inst["id"],
4316
+ name: inst["name"].to_s,
4317
+ enabled: !!inst["enabled"],
4318
+ running: running.any? { |r| r[:platform] == platform && r[:instance_id] == inst["id"] },
4319
+ has_config: !config.platform_config(platform, inst["id"]).nil?
4320
+ }.merge(platform_safe_fields(platform, config, inst["id"]))
4321
+ end
4322
+
4323
+ primary = instances.first || { id: Clacky::ChannelConfig::DEFAULT_INSTANCE_ID, name: "", enabled: false, running: false, has_config: false }
4203
4324
  {
4204
- platform: platform,
4205
- enabled: !!raw["enabled"],
4206
- running: running.include?(platform),
4207
- has_config: !config.platform_config(platform).nil?
4208
- }.merge(platform_safe_fields(platform, config))
4325
+ platform: platform,
4326
+ id: primary[:id],
4327
+ name: primary[:name],
4328
+ enabled: instances.any? { |inst| inst[:enabled] },
4329
+ running: running.any? { |r| r[:platform] == platform },
4330
+ has_config: !instances.empty?,
4331
+ instances: instances
4332
+ }.merge(platform_safe_fields(platform, config, primary[:id]))
4209
4333
  end
4210
4334
 
4211
4335
  json_response(res, 200, { channels: platforms, status_messages: config.status_messages_enabled?, process_messages: config.process_messages_enabled?, progress_cards: config.progress_cards_enabled? })
@@ -4500,6 +4624,7 @@ module Clacky
4500
4624
  platform = platform.to_sym
4501
4625
  body = parse_json_body(req)
4502
4626
  message = body["message"].to_s.strip
4627
+ instance_id = body["instance_id"].to_s.strip
4503
4628
 
4504
4629
  if message.empty?
4505
4630
  json_response(res, 400, { ok: false, error: "message is required" })
@@ -4510,7 +4635,7 @@ module Clacky
4510
4635
  user_id = body["user_id"].to_s.strip
4511
4636
  if user_id.empty?
4512
4637
  # Default to the most-recently active user for this platform
4513
- known = @channel_manager.known_users(platform)
4638
+ known = @channel_manager.known_users(platform, instance_id)
4514
4639
  if known.empty?
4515
4640
  json_response(res, 503, {
4516
4641
  ok: false,
@@ -4521,21 +4646,21 @@ module Clacky
4521
4646
  user_id = known.last
4522
4647
  end
4523
4648
 
4524
- result = @channel_manager.send_to_user(platform, user_id, message)
4649
+ result = @channel_manager.send_to_user(platform, user_id, message, instance_id)
4525
4650
  if result.nil?
4526
4651
  json_response(res, 400, {
4527
4652
  ok: false,
4528
4653
  error: "Failed to send message. The :#{platform} adapter may not be running, or no context_token is available for user #{user_id}."
4529
4654
  })
4530
4655
  else
4531
- json_response(res, 200, { ok: true, platform: platform, user_id: user_id })
4656
+ json_response(res, 200, { ok: true, platform: platform, instance_id: instance_id, user_id: user_id })
4532
4657
  end
4533
4658
  rescue StandardError => e
4534
4659
  json_response(res, 500, { ok: false, error: e.message })
4535
4660
  end
4536
4661
 
4537
- # GET /api/channels/:platform/users
4538
- # Returns the list of known user IDs for the given platform.
4662
+ # GET /api/channels/:platform/users?instance_id=...
4663
+ # Returns the list of known user IDs for the given platform (or instance).
4539
4664
  # These are users who have sent at least one message to the bot in this server session.
4540
4665
  #
4541
4666
  # For Weixin: returns users with a cached context_token (required for proactive messaging).
@@ -4543,10 +4668,11 @@ module Clacky
4543
4668
  #
4544
4669
  # Response:
4545
4670
  # 200 { users: ["uid1", "uid2", ...] }
4546
- def api_list_channel_users(platform, res)
4547
- platform = platform.to_sym
4548
- users = @channel_manager.known_users(platform)
4549
- json_response(res, 200, { platform: platform, users: users })
4671
+ def api_list_channel_users(platform, req, res)
4672
+ platform = platform.to_sym
4673
+ instance_id = req.query["instance_id"].to_s.strip
4674
+ users = @channel_manager.known_users(platform, instance_id)
4675
+ json_response(res, 200, { platform: platform, instance_id: instance_id, users: users })
4550
4676
  rescue StandardError => e
4551
4677
  json_response(res, 500, { ok: false, error: e.message })
4552
4678
  end
@@ -4590,10 +4716,12 @@ module Clacky
4590
4716
 
4591
4717
  path = Utils::EnvironmentDetector.resolve_local_path(raw_path)
4592
4718
  ext = File.extname(path).downcase.sub(/\A\./, "")
4719
+ # Extension-less files (Dockerfile, Makefile, Gemfile) declare no
4720
+ # document type, so no app lists them. Plain text is the closest
4721
+ # approximation and keeps the picker useful.
4722
+ ext = "txt" if ext.empty?
4593
4723
 
4594
- apps = if ext.empty?
4595
- []
4596
- elsif Utils::EnvironmentDetector.os_type == :wsl
4724
+ apps = if Utils::EnvironmentDetector.os_type == :wsl
4597
4725
  Utils::WindowsAppDetector.apps_for_ext(ext)
4598
4726
  else
4599
4727
  Utils::MacAppDetector.apps_for_ext(ext)
@@ -4610,9 +4738,7 @@ module Clacky
4610
4738
  return json_response(res, 400, { error: "path is required" }) if raw_path.empty?
4611
4739
 
4612
4740
  path = Utils::EnvironmentDetector.resolve_local_path(raw_path)
4613
- app = if File.extname(path).empty?
4614
- nil
4615
- elsif Utils::EnvironmentDetector.os_type == :wsl
4741
+ app = if Utils::EnvironmentDetector.os_type == :wsl
4616
4742
  Utils::WindowsAppDetector.default_app_for(path)
4617
4743
  else
4618
4744
  Utils::MacAppDetector.default_app_for(path)
@@ -4682,6 +4808,9 @@ module Clacky
4682
4808
  when "open"
4683
4809
  result = Utils::EnvironmentDetector.open_file(linux_path)
4684
4810
  return json_response(res, 501, { error: "unsupported OS" }) if result.nil?
4811
+ # system() returns false when the launcher exits non-zero (broken app
4812
+ # association, no handler). Surface it instead of a silent 200.
4813
+ return json_response(res, 500, { error: "failed to open file" }) unless result
4685
4814
  json_response(res, 200, { ok: true })
4686
4815
  when "open_with"
4687
4816
  result = if Utils::EnvironmentDetector.os_type == :wsl
@@ -4812,13 +4941,24 @@ module Clacky
4812
4941
 
4813
4942
  # POST /api/channels/:platform
4814
4943
  # Body: { fields... } (platform-specific credential fields)
4944
+ # Optional: { instance_id, name } to target an additional instance of the
4945
+ # same platform. Without instance_id the default (first) instance is
4946
+ # updated, which keeps older clients and skill curls working unchanged.
4815
4947
  # Saves credentials and optionally (re)starts the adapter.
4816
4948
  def api_save_channel(platform, req, res)
4817
4949
  platform = platform.to_sym
4818
4950
  body = parse_json_body(req)
4819
4951
  config = Clacky::ChannelConfig.load
4820
4952
 
4821
- fields = body.transform_keys(&:to_sym).reject { |k, _| k == :platform }
4953
+ instance_id = body["instance_id"].to_s.strip
4954
+ name = body["name"].is_a?(String) ? body["name"].strip : nil
4955
+ if !instance_id.empty? && !valid_instance_id?(instance_id)
4956
+ json_response(res, 422, { ok: false, error: "instance_id may only contain letters, digits, '-' and '_'" })
4957
+ return
4958
+ end
4959
+ return json_response(res, 422, { ok: false, error: "name is too long" }) if name && name.length > 60
4960
+
4961
+ fields = body.transform_keys(&:to_sym).reject { |k, _| %i[platform instance_id name id].include?(k) }
4822
4962
  fields = fields.transform_values { |v| v.is_a?(String) ? v.strip : v }
4823
4963
 
4824
4964
  # Record when the token was last updated so clients can detect re-login
@@ -4826,10 +4966,12 @@ module Clacky
4826
4966
  fields[:token_updated_at] = Time.now.to_i if platform == :discord && fields.key?(:bot_token)
4827
4967
 
4828
4968
  # Validate credentials against live API before persisting.
4829
- # Merge with existing config so partial updates (e.g. allowed_users only) still validate correctly.
4969
+ # Merge with the target instance's existing config so partial updates
4970
+ # (e.g. allowed_users only) still validate correctly. A new instance
4971
+ # does not inherit the default instance's credentials.
4830
4972
  klass = Clacky::Channel::Adapters.find(platform)
4831
4973
  if klass && klass.respond_to?(:test_connection)
4832
- existing = config.platform_config(platform) || {}
4974
+ existing = config.platform_config(platform, instance_id) || {}
4833
4975
  merged = existing.merge(fields)
4834
4976
  result = klass.test_connection(merged)
4835
4977
  unless result[:ok]
@@ -4838,13 +4980,19 @@ module Clacky
4838
4980
  end
4839
4981
  end
4840
4982
 
4841
- config.set_platform(platform, **fields)
4983
+ resolved_id = config.set_platform(
4984
+ platform,
4985
+ instance_id: instance_id,
4986
+ name: name,
4987
+ enabled: body.key?("enabled") ? body["enabled"] == true : nil,
4988
+ **fields
4989
+ )
4842
4990
  config.save
4843
4991
 
4844
- # Hot-reload: stop existing adapter for this platform (if running) and restart
4845
- @channel_manager.reload_platform(platform, config)
4992
+ # Hot-reload only the affected instance.
4993
+ @channel_manager.reload_platform(platform, config, resolved_id)
4846
4994
 
4847
- json_response(res, 200, { ok: true })
4995
+ json_response(res, 200, { ok: true, instance_id: resolved_id })
4848
4996
  rescue StandardError => e
4849
4997
  json_response(res, 422, { ok: false, error: e.message })
4850
4998
  end
@@ -4853,13 +5001,14 @@ module Clacky
4853
5001
  # Creates a QQ "lite bind" task and returns the official connect URL
4854
5002
  # (Tencent renders the QR). The AES key is held server-side, keyed by
4855
5003
  # task_id, so the poll step can decrypt the returned AppSecret.
4856
- def api_qq_qr_start(res)
5004
+ def api_qq_qr_start(req, res)
5005
+ instance_id = parse_json_body(req)["instance_id"].to_s.strip
4857
5006
  binder = Clacky::Channel::Adapters::Qq::QrBinder.new
4858
5007
  task = binder.create_task
4859
- qr_bind_store[task[:task_id]] = { "key" => task[:key], "created_at" => Time.now.to_i }
5008
+ qr_bind_store[task[:task_id]] = { "key" => task[:key], "instance_id" => instance_id, "created_at" => Time.now.to_i }
4860
5009
  prune_qr_bind_store
4861
5010
 
4862
- json_response(res, 200, { ok: true, task_id: task[:task_id], connect_url: task[:connect_url] })
5011
+ json_response(res, 200, { ok: true, task_id: task[:task_id], connect_url: task[:connect_url], instance_id: instance_id })
4863
5012
  rescue StandardError => e
4864
5013
  json_response(res, 422, { ok: false, error: e.message })
4865
5014
  end
@@ -4888,9 +5037,9 @@ module Clacky
4888
5037
  user_openid: result[:user_openid],
4889
5038
  key: stored["key"]
4890
5039
  )
4891
- persist_qq_qr_credentials(creds)
5040
+ persist_qq_qr_credentials(creds, stored["instance_id"])
4892
5041
  qr_bind_store.delete(task_id)
4893
- json_response(res, 200, { ok: true, status: "completed", app_id: creds[:app_id] })
5042
+ json_response(res, 200, { ok: true, status: "completed", app_id: creds[:app_id], instance_id: stored["instance_id"].to_s })
4894
5043
  else
4895
5044
  json_response(res, 200, { ok: true, status: "pending" })
4896
5045
  end
@@ -4899,21 +5048,22 @@ module Clacky
4899
5048
  end
4900
5049
 
4901
5050
  # Persist scanned QQ credentials and ensure the scanning user can talk
4902
- # to the bot (merged with any existing whitelist).
4903
- def persist_qq_qr_credentials(creds)
5051
+ # to the bot (merged with that instance's existing whitelist).
5052
+ def persist_qq_qr_credentials(creds, instance_id = nil)
4904
5053
  config = Clacky::ChannelConfig.load
4905
- existing = config.platform_config(:qq) || {}
5054
+ existing = config.platform_config(:qq, instance_id) || {}
4906
5055
  whitelist = Array(existing[:allowed_users]).map(&:to_s)
4907
5056
  whitelist << creds[:user_openid] unless creds[:user_openid].to_s.empty?
4908
5057
 
4909
- config.set_platform(
5058
+ resolved_id = config.set_platform(
4910
5059
  :qq,
5060
+ instance_id: instance_id,
4911
5061
  app_id: creds[:app_id],
4912
5062
  app_secret: creds[:app_secret],
4913
5063
  allowed_users: whitelist.uniq
4914
5064
  )
4915
5065
  config.save
4916
- @channel_manager.reload_platform(:qq, config)
5066
+ @channel_manager.reload_platform(:qq, config, resolved_id)
4917
5067
  end
4918
5068
 
4919
5069
  def qr_bind_store
@@ -4929,16 +5079,20 @@ module Clacky
4929
5079
  end
4930
5080
 
4931
5081
  # DELETE /api/channels/:platform
4932
- # Disables the platform (keeps credentials, sets enabled: false).
4933
- def api_delete_channel(platform, res)
5082
+ # DELETE /api/channels/:platform/instances/:id
5083
+ # Removes the instance from channels.yml and stops its adapter.
5084
+ # Without an instance id the whole platform entry is removed.
5085
+ def api_delete_channel(platform, res, instance_id = nil)
4934
5086
  platform = platform.to_sym
4935
5087
  config = Clacky::ChannelConfig.load
4936
- config.disable_platform(platform)
5088
+ removed = config.remove_platform(platform, instance_id)
5089
+ return json_response(res, 404, { ok: false, error: "instance not found" }) unless removed
5090
+
4937
5091
  config.save
4938
5092
 
4939
- @channel_manager.reload_platform(platform, config)
5093
+ @channel_manager.reload_platform(platform, config, instance_id)
4940
5094
 
4941
- json_response(res, 200, { ok: true })
5095
+ json_response(res, 200, { ok: true, instance_id: instance_id })
4942
5096
  rescue StandardError => e
4943
5097
  json_response(res, 422, { ok: false, error: e.message })
4944
5098
  end
@@ -4997,29 +5151,34 @@ module Clacky
4997
5151
  end
4998
5152
 
4999
5153
  # PATCH /api/channels/:platform/enabled
5000
- # Body: { enabled: true|false }
5001
- # Toggles the platform on/off without touching credentials.
5002
- # Enabling requires the platform to already be configured.
5154
+ # Body: { enabled: true|false, instance_id?: "..." }
5155
+ # Toggles an instance on/off without touching credentials. Without an
5156
+ # instance_id the default (first) instance is toggled.
5157
+ # Enabling requires the instance to already be configured.
5003
5158
  def api_toggle_channel(platform, req, res)
5004
5159
  platform = platform.to_sym
5005
- enabled = parse_json_body(req)["enabled"] == true
5160
+ body = parse_json_body(req)
5161
+ enabled = body["enabled"] == true
5006
5162
 
5007
5163
  config = Clacky::ChannelConfig.load
5164
+ instance_id = body["instance_id"].to_s.strip
5165
+ instance_id = config.instances(platform).first&.fetch("id", nil) if instance_id.empty?
5166
+
5167
+ unless instance_id && config.instance(platform, instance_id)
5168
+ json_response(res, 422, { ok: false, error: "Platform is not configured yet" })
5169
+ return
5170
+ end
5008
5171
 
5009
5172
  if enabled
5010
- unless config.platform_config(platform)
5011
- json_response(res, 422, { ok: false, error: "Platform is not configured yet" })
5012
- return
5013
- end
5014
- config.enable_platform(platform)
5173
+ config.enable_platform(platform, instance_id)
5015
5174
  else
5016
- config.disable_platform(platform)
5175
+ config.disable_platform(platform, instance_id)
5017
5176
  end
5018
5177
 
5019
5178
  config.save
5020
- @channel_manager.reload_platform(platform, config)
5179
+ @channel_manager.reload_platform(platform, config, instance_id)
5021
5180
 
5022
- json_response(res, 200, { ok: true, enabled: config.enabled?(platform) })
5181
+ json_response(res, 200, { ok: true, instance_id: instance_id, enabled: config.enabled?(platform, instance_id) })
5023
5182
  rescue StandardError => e
5024
5183
  json_response(res, 422, { ok: false, error: e.message })
5025
5184
  end
@@ -5044,9 +5203,15 @@ module Clacky
5044
5203
  json_response(res, 200, { ok: false, error: e.message })
5045
5204
  end
5046
5205
 
5047
- # Returns non-secret fields for a platform (masked secrets).
5048
- private def platform_safe_fields(platform, config)
5049
- raw = config.instance_variable_get(:@channels)[platform.to_s] || {}
5206
+ # Instance ids are used in channel binding keys and thread names, so keep
5207
+ # them to a small, predictable character set.
5208
+ private def valid_instance_id?(id)
5209
+ id.to_s.match?(/\A[A-Za-z0-9][A-Za-z0-9_-]{0,39}\z/)
5210
+ end
5211
+
5212
+ # Returns non-secret fields for a platform instance (masked secrets).
5213
+ private def platform_safe_fields(platform, config, instance_id = nil)
5214
+ raw = config.instance(platform, instance_id) || {}
5050
5215
  case platform.to_sym
5051
5216
  when :feishu
5052
5217
  {
@@ -5175,10 +5340,11 @@ module Clacky
5175
5340
  end
5176
5341
 
5177
5342
  # POST /api/cron-tasks — create task file + schedule in one step
5178
- # Body: { name, content, cron, enabled? }
5343
+ # Body: { name, title?, content, cron, enabled? }
5179
5344
  def api_create_cron_task(req, res)
5180
5345
  body = parse_json_body(req)
5181
5346
  name = body["name"].to_s.strip
5347
+ title = body["title"].to_s.strip
5182
5348
  content = body["content"].to_s
5183
5349
  cron = body["cron"].to_s.strip
5184
5350
  enabled = body.key?("enabled") ? body["enabled"] : true
@@ -5192,24 +5358,36 @@ module Clacky
5192
5358
  return json_response(res, 422, { error: "cron must have 5 fields (min hour dom month dow)" })
5193
5359
  end
5194
5360
 
5195
- @scheduler.create_cron_task(name: name, content: content, cron: cron, enabled: enabled)
5361
+ target = nil
5362
+ if body.key?("owner_session_id")
5363
+ owner_id = body["owner_session_id"].to_s.strip
5364
+ return json_response(res, 422, { error: "owner_session_id is required for secretary plans" }) if owner_id.empty?
5365
+ target = @work_service.schedule_target(owner_id, title: title.empty? ? name : title)
5366
+ end
5367
+ @scheduler.create_cron_task(name: name, content: content, cron: cron, enabled: enabled,
5368
+ target: target, title: title.empty? ? nil : title)
5196
5369
  json_response(res, 201, { ok: true, name: name })
5370
+ rescue ArgumentError => e
5371
+ json_response(res, 422, { error: e.message })
5197
5372
  end
5198
5373
 
5199
- # PATCH /api/cron-tasks/:name — update content and/or cron/enabled
5200
- # Body: { content?, cron?, enabled? }
5374
+ # PATCH /api/cron-tasks/:name — update content and/or cron/enabled/title
5375
+ # Body: { content?, cron?, enabled?, title? }
5201
5376
  def api_update_cron_task(name, req, res)
5202
5377
  body = parse_json_body(req)
5203
5378
  content = body["content"]
5204
5379
  cron = body["cron"]&.to_s&.strip
5205
5380
  enabled = body["enabled"]
5381
+ title = body.key?("title") ? body["title"].to_s.strip : nil
5206
5382
 
5207
5383
  if cron && cron.split(/\s+/).size != 5
5208
5384
  return json_response(res, 422, { error: "cron must have 5 fields (min hour dom month dow)" })
5209
5385
  end
5210
5386
 
5211
- @scheduler.update_cron_task(name, content: content, cron: cron, enabled: enabled)
5387
+ @scheduler.update_cron_task(name, content: content, cron: cron, enabled: enabled, title: title)
5212
5388
  json_response(res, 200, { ok: true, name: name })
5389
+ rescue ArgumentError => e
5390
+ json_response(res, 422, { error: e.message })
5213
5391
  rescue => e
5214
5392
  json_response(res, 404, { error: e.message })
5215
5393
  end
@@ -5244,8 +5422,16 @@ module Clacky
5244
5422
  return json_response(res, 404, { error: "Cron task not found: #{name}" })
5245
5423
  end
5246
5424
 
5425
+ schedule = @scheduler.schedules.find { |plan| plan["task"] == name }
5426
+ if schedule && schedule["target"]
5427
+ card = @work_service.dispatch_schedule(schedule, @scheduler.read_task(name), Time.now)
5428
+ return json_response(res, 409, { error: "Previous work is unfinished or its owner is unavailable" }) unless card
5429
+ return json_response(res, 202, { ok: true, session: @registry.session_summary(card["session_id"]) })
5430
+ end
5431
+
5247
5432
  prompt = @scheduler.read_task(name)
5248
- session_name = "▶ #{name} #{Time.now.strftime("%H:%M")}"
5433
+ label = schedule && !schedule["title"].to_s.empty? ? schedule["title"] : name
5434
+ session_name = "▶ #{label} #{Time.now.strftime("%H:%M")}"
5249
5435
  working_dir = File.expand_path("~/clacky_workspace")
5250
5436
  FileUtils.mkdir_p(working_dir)
5251
5437
 
@@ -5414,9 +5600,22 @@ module Clacky
5414
5600
  when "status"
5415
5601
  json_response(res, 200, { repo: true }.merge(Clacky::Server::GitPanel.status(dir)))
5416
5602
  when "diff"
5417
- json_response(res, 200, { repo: true, diff: Clacky::Server::GitPanel.diff(dir, file: query["file"]) })
5603
+ json_response(res, 200, { repo: true, diff: Clacky::Server::GitPanel.diff(
5604
+ dir, file: query["file"], context: query["context"],
5605
+ scope: query["scope"], base: query["base"]
5606
+ ) })
5607
+ when "review"
5608
+ if query["scope"].to_s == "lastTurn"
5609
+ json_response(res, 200, Clacky::Server::GitPanel.last_turn_review(git_session_agent(session_id)))
5610
+ else
5611
+ json_response(res, 200, Clacky::Server::GitPanel.review(
5612
+ dir, scope: query["scope"], base: query["base"]
5613
+ ))
5614
+ end
5418
5615
  when "log"
5419
- json_response(res, 200, { repo: true, commits: Clacky::Server::GitPanel.log(dir, limit: query["limit"] || 50) })
5616
+ json_response(res, 200, { repo: true, commits: Clacky::Server::GitPanel.log(
5617
+ dir, limit: query["limit"] || 50, unpushed: query["unpushed"].to_s == "1"
5618
+ ) })
5420
5619
  when "branches"
5421
5620
  json_response(res, 200, { repo: true, branches: Clacky::Server::GitPanel.branches(dir) })
5422
5621
  else
@@ -5424,24 +5623,6 @@ module Clacky
5424
5623
  end
5425
5624
  end
5426
5625
 
5427
- # POST /api/sessions/:id/git/commit — body: { message:, files: [..] }.
5428
- def api_session_git_commit(session_id, req, res)
5429
- dir = git_session_dir(session_id, res)
5430
- return unless dir
5431
-
5432
- unless Clacky::Server::GitPanel.repo?(dir)
5433
- return json_response(res, 400, { error: "Not a git repository" })
5434
- end
5435
-
5436
- body = parse_json_body(req)
5437
- result = Clacky::Server::GitPanel.commit(dir, message: body["message"], files: body["files"])
5438
- if result[:ok]
5439
- json_response(res, 200, result)
5440
- else
5441
- json_response(res, 422, { error: result[:error] })
5442
- end
5443
- end
5444
-
5445
5626
  # POST /api/sessions/:id/git/restore - body: { file: }.
5446
5627
  # Discards uncommitted changes to one file, back to its HEAD state.
5447
5628
  def api_session_git_restore(session_id, req, res)
@@ -5545,8 +5726,7 @@ module Clacky
5545
5726
  json_response(res, 404, { error: "Session not found" })
5546
5727
  return nil
5547
5728
  end
5548
- session = @registry.get(session_id)
5549
- agent = session && session[:agent]
5729
+ agent = git_session_agent(session_id)
5550
5730
  unless agent
5551
5731
  json_response(res, 404, { error: "Session not found" })
5552
5732
  return nil
@@ -5558,6 +5738,11 @@ module Clacky
5558
5738
  end
5559
5739
  dir
5560
5740
  end
5741
+
5742
+ private def git_session_agent(session_id)
5743
+ session = @registry.get(session_id)
5744
+ session && session[:agent]
5745
+ end
5561
5746
  # Lists one directory level inside the session's working_dir (lazy, per-layer).
5562
5747
  # Path traversal outside working_dir is rejected. Noisy dirs are hidden.
5563
5748
  IGNORED_FILE_ENTRIES = %w[.git .svn .hg node_modules .DS_Store .bundle vendor/bundle tmp .sass-cache].freeze
@@ -5571,7 +5756,11 @@ module Clacky
5571
5756
  return json_response(res, 404, { error: "Session not found" }) unless agent
5572
5757
 
5573
5758
  root = File.expand_path(agent.working_dir.to_s)
5574
- return json_response(res, 404, { error: "Working directory not found" }) unless Dir.exist?(root)
5759
+ unless Dir.exist?(root)
5760
+ # `code` lets the client tell "the folder was deleted" apart from any
5761
+ # other failure and explain it, instead of showing a generic error.
5762
+ return json_response(res, 404, { error: "Working directory not found", code: "working_dir_missing", path: root })
5763
+ end
5575
5764
 
5576
5765
  query = URI.decode_www_form(req.query_string.to_s).to_h
5577
5766
  rel = query["path"].to_s
@@ -5596,7 +5785,9 @@ module Clacky
5596
5785
  end
5597
5786
  end
5598
5787
 
5599
- return json_response(res, 404, { error: "Directory not found" }) unless Dir.exist?(target)
5788
+ unless Dir.exist?(target)
5789
+ return json_response(res, 404, { error: "Directory not found", code: "directory_missing" })
5790
+ end
5600
5791
  entries = Dir.children(target).reject do |name|
5601
5792
  IGNORED_FILE_ENTRIES.include?(name) || (!show_hidden && name.start_with?("."))
5602
5793
  end
@@ -7166,6 +7357,14 @@ module Clacky
7166
7357
  client.test_connection(model: model)
7167
7358
  end
7168
7359
 
7360
+ private def preset_model_capabilities(id, preset)
7361
+ names = (preset["models"] || []) | (preset["model_capabilities"] || {}).keys
7362
+ names.each_with_object({}) do |name, out|
7363
+ caps = Clacky::Providers.capabilities(id, model_name: name)
7364
+ out[name] = caps unless caps.empty?
7365
+ end
7366
+ end
7367
+
7169
7368
  # GET /api/providers — return built-in provider presets for quick setup
7170
7369
  def api_list_providers(res)
7171
7370
  providers = Clacky::Providers::PRESETS.map do |id, preset|
@@ -7185,7 +7384,9 @@ module Clacky
7185
7384
  # billing-plan variants) when present. Absent for single-endpoint
7186
7385
  # providers — UI renders a plain text input in that case.
7187
7386
  endpoint_variants: preset["endpoint_variants"],
7188
- website_url: preset["website_url"]
7387
+ website_url: preset["website_url"],
7388
+ # Lets the custom-provider form infer capabilities from a typed model name.
7389
+ model_capabilities: preset_model_capabilities(id, preset)
7189
7390
  }
7190
7391
  end
7191
7392
  json_response(res, 200, { providers: providers })
@@ -7280,6 +7481,71 @@ module Clacky
7280
7481
  json_response(res, 500, { error: e.message })
7281
7482
  end
7282
7483
 
7484
+ # GET /api/projects/:id/git?dir= — branch state of a work tree, used by
7485
+ # the new-session branch picker. `dir` overrides the project's own
7486
+ # working dir, since a session may run in a different repo. `repo: false`
7487
+ # covers a missing working dir, a missing directory, and plain non-git
7488
+ # folders, so the picker can simply hide itself.
7489
+ def api_project_git(project_id, req, res)
7490
+ project = @project_manager.find(project_id)
7491
+ return json_response(res, 404, { error: "Project not found" }) unless project
7492
+
7493
+ dir = git_work_tree(project, git_dir_param(req))
7494
+ return json_response(res, 200, { repo: false }) unless dir
7495
+
7496
+ json_response(res, 200, {
7497
+ repo: true,
7498
+ branch: Clacky::Server::GitPanel.branch_name(dir),
7499
+ branches: Clacky::Server::GitPanel.branches(dir),
7500
+ })
7501
+ end
7502
+
7503
+ # POST /api/projects/:id/git/checkout — body: { branch:, create:?, from:?, dir:? }
7504
+ # Switches a work tree. `create: true` branches off `from`, which may be
7505
+ # a remote ref (origin/feature) to get a tracking branch.
7506
+ def api_project_git_checkout(project_id, req, res)
7507
+ project = @project_manager.find(project_id)
7508
+ return json_response(res, 404, { error: "Project not found" }) unless project
7509
+
7510
+ body = parse_json_body(req)
7511
+ dir = git_work_tree(project, body["dir"])
7512
+ return json_response(res, 400, { error: "Not a git repository" }) unless dir
7513
+
7514
+ result = Clacky::Server::GitPanel.checkout(
7515
+ dir,
7516
+ branch: body["branch"],
7517
+ create: body["create"] == true,
7518
+ from: body["from"]
7519
+ )
7520
+
7521
+ unless result[:ok]
7522
+ return json_response(res, 422, { error: result[:error] })
7523
+ end
7524
+
7525
+ json_response(res, 200, {
7526
+ ok: true,
7527
+ branch: Clacky::Server::GitPanel.branch_name(dir),
7528
+ branches: Clacky::Server::GitPanel.branches(dir),
7529
+ })
7530
+ end
7531
+
7532
+ def git_dir_param(req)
7533
+ URI.decode_www_form(req.query_string.to_s).to_h["dir"]
7534
+ rescue ArgumentError
7535
+ nil
7536
+ end
7537
+
7538
+ # Resolves the work tree a git request targets: the explicit `dir` when
7539
+ # given, otherwise the project's own working dir. Nil when the path is
7540
+ # not an existing git repository.
7541
+ def git_work_tree(project, dir_param)
7542
+ raw = dir_param.to_s.strip
7543
+ dir = raw.empty? ? project[:working_dir].to_s : File.expand_path(raw)
7544
+ return nil if dir.empty? || !Dir.exist?(dir)
7545
+ return nil unless Clacky::Server::GitPanel.repo?(dir)
7546
+ dir
7547
+ end
7548
+
7283
7549
  # PATCH /api/projects/:id - update a project
7284
7550
  # Body: { name:?, description:?, color:?, working_dir:?, pinned:? } - only provided fields are changed
7285
7551
  def api_update_project(project_id, req, res)
@@ -7816,6 +8082,8 @@ module Clacky
7816
8082
  zos.write(File.binread(chunk_path))
7817
8083
  end
7818
8084
 
8085
+ write_work_debug_bundle(zos, bundle[:session][:session_id])
8086
+
7819
8087
  log_path = Clacky::Logger.current_log_file
7820
8088
  if log_path && File.exist?(log_path)
7821
8089
  zos.put_next_entry("logs/#{File.basename(log_path)}")
@@ -7838,6 +8106,46 @@ module Clacky
7838
8106
  json_response(res, 500, { error: "Export failed: #{e.message}" })
7839
8107
  end
7840
8108
 
8109
+ private def write_work_debug_bundle(zos, session_id)
8110
+ snapshot = @work_service&.debug_snapshot(session_id)
8111
+ return if !snapshot || snapshot["cards"].empty?
8112
+
8113
+ sessions = snapshot["cards"].map { |card| card["session_id"] }.uniq.map do |worker_id|
8114
+ entry = { "session_id" => worker_id }
8115
+ if worker_id == session_id
8116
+ entry.merge("path" => "session.json", "status" => "included")
8117
+ else
8118
+ bundle = @session_manager.files_for(worker_id)
8119
+ # files_for accepts prefixes; debug associations must be exact.
8120
+ if bundle && bundle[:session][:session_id] == worker_id
8121
+ prefix = "work/sessions/#{URI.encode_www_form_component(worker_id)}/"
8122
+ begin
8123
+ files = [["session.json", File.binread(bundle[:json_path])]]
8124
+ bundle[:chunks].each { |path| files << [File.basename(path), File.binread(path)] }
8125
+ files.each do |name, content|
8126
+ zos.put_next_entry(prefix + name)
8127
+ zos.write(content)
8128
+ end
8129
+ entry.merge("path" => prefix + "session.json", "status" => "included")
8130
+ rescue Errno::ENOENT
8131
+ entry.merge("status" => "missing")
8132
+ end
8133
+ else
8134
+ entry.merge("status" => "missing")
8135
+ end
8136
+ end
8137
+ end
8138
+ manifest = {
8139
+ "session_id" => session_id,
8140
+ "work" => snapshot["cards"].map { |card| card.slice("id", "session_id", "owner_session_id", "revision") },
8141
+ "sessions" => sessions
8142
+ }
8143
+ { "manifest" => manifest, "cards" => snapshot["cards"], "events" => snapshot["events"] }.each do |name, data|
8144
+ zos.put_next_entry("work/#{name}.json")
8145
+ zos.write(JSON.pretty_generate(data))
8146
+ end
8147
+ end
8148
+
7841
8149
  # ── WebSocket ─────────────────────────────────────────────────────────────
7842
8150
 
7843
8151
  def websocket_upgrade?(req)
@@ -8107,8 +8415,7 @@ module Clacky
8107
8415
  @registry.with_session(session_id) do |s|
8108
8416
  if s[:status] == :running && %w[queue steer].include?(mode)
8109
8417
  queued_created_at = Time.now.to_f
8110
- s[:agent].enqueue_input(content, delivery: mode.to_sym, files: files, references_display: references,
8111
- reference_contexts: build_reference_contexts(references), created_at: queued_created_at)
8418
+ s[:agent].enqueue_input(content, delivery: mode.to_sym, files: files, reference_contexts: build_reference_contexts(references), created_at: queued_created_at)
8112
8419
  queued = true
8113
8420
  end
8114
8421
  end
@@ -8130,8 +8437,7 @@ module Clacky
8130
8437
  @registry.with_session(session_id) { |s| old_thread = s[:thread] }
8131
8438
  if old_thread && !old_thread.join(2)
8132
8439
  retained_created_at = Time.now.to_f
8133
- session[:agent].enqueue_input(content, files: files, references_display: references,
8134
- reference_contexts: build_reference_contexts(references), created_at: retained_created_at)
8440
+ session[:agent].enqueue_input(content, files: files, reference_contexts: build_reference_contexts(references), created_at: retained_created_at)
8135
8441
  broadcast(session_id, { type: "input_enqueued", session_id: session_id, created_at: retained_created_at })
8136
8442
  broadcast(session_id, { type: "input_queue_notice", session_id: session_id, key: "chat.input.stoppingDelayed" })
8137
8443
  return
@@ -8182,14 +8488,13 @@ module Clacky
8182
8488
 
8183
8489
  # File references are now handled inside agent.run — injected as a system_injected
8184
8490
  # message after the user message, so replay_history skips them automatically.
8185
- reference_contexts = build_reference_contexts(references)
8186
8491
  run_agent_task(session_id, agent) do
8187
8492
  # Start the progress card inside the task: run_agent_task returns early when
8188
8493
  # the concurrency cap is hit, and posting beforehand would strand the card at
8189
8494
  # "Thinking..." forever. A web-originated turn bound to an IM channel gets a
8190
8495
  # card too, so tools/narration render like a native IM turn (#603).
8191
8496
  @channel_manager.channel_ui_for_session(session_id)&.start_task(reply_to: nil)
8192
- agent.run(content, files: files, reference_contexts: reference_contexts, created_at: msg_created_at, references_display: references)
8497
+ agent.run(content, files: files, created_at: msg_created_at, reference_contexts: build_reference_contexts(references))
8193
8498
  end
8194
8499
  end
8195
8500
 
@@ -8198,21 +8503,24 @@ module Clacky
8198
8503
  # (e.g. branch diff, browser snapshot) only add a `when` branch here.
8199
8504
  private def build_reference_contexts(references)
8200
8505
  Array(references).filter_map do |ref|
8506
+ next ref if ref.is_a?(String)
8201
8507
  next unless ref.is_a?(Hash)
8202
- case ref["type"].to_s
8203
- when "session" then build_session_reference_context(ref)
8204
- when "quote" then build_quote_reference_context(ref)
8205
- end
8508
+ context = case (ref[:type] || ref["type"]).to_s
8509
+ when "session" then build_session_reference_context(ref)
8510
+ when "quote" then build_quote_reference_context(ref)
8511
+ end
8512
+ metadata = ref.reject { |key, _| key.to_s == "context" }
8513
+ context ? metadata.merge(context: context) : metadata
8206
8514
  end
8207
8515
  end
8208
8516
 
8209
8517
  # Resolve a past-chat reference into a lightweight pointer for the LLM:
8210
8518
  # the session name + ID + on-disk file path, no transcript inlined.
8211
8519
  private def build_session_reference_context(ref)
8212
- session_id = ref["session_id"].to_s
8520
+ session_id = (ref[:session_id] || ref["session_id"]).to_s
8213
8521
  return nil if session_id.empty?
8214
8522
 
8215
- name = ref["name"].to_s
8523
+ name = (ref[:name] || ref["name"]).to_s
8216
8524
  name = session_id if name.empty?
8217
8525
 
8218
8526
  lines = ["[Referenced conversation: #{name}]", "Session ID: #{session_id}"]
@@ -8226,10 +8534,10 @@ module Clacky
8226
8534
  # message. The excerpt is the whole point of the reference, so inline it
8227
8535
  # verbatim — no file pointer, nothing for the model to go fetch.
8228
8536
  private def build_quote_reference_context(ref)
8229
- text = ref["text"].to_s.strip
8537
+ text = (ref[:text] || ref["text"]).to_s.strip
8230
8538
  return nil if text.empty?
8231
8539
 
8232
- label = ref["label"].to_s.strip
8540
+ label = (ref[:label] || ref["label"]).to_s.strip
8233
8541
  header = label.empty? ? "[Quoted excerpt from this conversation]" :
8234
8542
  "[Quoted excerpt from this conversation: #{label}]"
8235
8543
  [header, text].join("\n")
@@ -8264,13 +8572,14 @@ module Clacky
8264
8572
  Clacky::Logger.warn("[interrupt] raise failed: #{e.message}")
8265
8573
  end
8266
8574
  end
8267
- end # Run a task in a session immediately in the background, without waiting
8268
- # for the client to subscribe. The user bubble is persisted via
8269
- # display_text (Agent#run → history → replay_history), so the frontend
8270
- # only needs to navigate over and load history — no realtime broadcast,
8271
- # no subscribe-timing race. This is the stable entry point for
8272
- # programmatic "create session + run now" flows (spawn, extensions).
8273
- def run_session_task(session_id, prompt, display_message: nil)
8575
+ end
8576
+
8577
+ # Shared submission path for host services and extensions. Execution and
8578
+ # presentation happen only after admission, on the session's owning thread.
8579
+ # display_message supplies the same friendly input for live display and replay.
8580
+ # around_execution, when supplied by a host service, wraps the admitted
8581
+ # execution on its owning thread (e.g. generation fencing and receipts).
8582
+ def run_session_task(session_id, prompt, display_message: nil, reference_contexts: nil, background: false, &around_execution)
8274
8583
  return unless @registry.exist?(session_id)
8275
8584
 
8276
8585
  agent = nil
@@ -8281,9 +8590,18 @@ module Clacky
8281
8590
  end
8282
8591
  return unless agent
8283
8592
 
8284
- web_ui&.show_user_message(display_message, source: :web) if display_message
8285
-
8286
- run_agent_task(session_id, agent) { agent.run(prompt, display_text: display_message) }
8593
+ run_agent_task(session_id, agent, background: background) do
8594
+ execute = lambda do
8595
+ display_options = { source: :web }
8596
+ visible_references = Array(reference_contexts).select { |ref| ref.is_a?(Hash) }.map { |ref| ref.reject { |key, _| key.to_s == "context" } }
8597
+ display_options[:references] = visible_references unless visible_references.empty?
8598
+ web_ui&.show_user_message(display_message, **display_options) if display_message
8599
+ options = { display_text: display_message }
8600
+ options[:reference_contexts] = build_reference_contexts(reference_contexts) if reference_contexts
8601
+ agent.run(prompt, **options)
8602
+ end
8603
+ around_execution ? around_execution.call(execute, agent) : execute.call
8604
+ end
8287
8605
  end
8288
8606
 
8289
8607
  # Start the pending task for a session.
@@ -8359,7 +8677,23 @@ module Clacky
8359
8677
  # Run an agent task in a background thread, handling status updates,
8360
8678
  # session persistence, and idle compression timer lifecycle.
8361
8679
  # Yields to the caller to perform the actual agent.run call.
8362
- private def run_agent_task(session_id, agent, &task)
8680
+ private def run_agent_task(session_id, agent, background: false, &task)
8681
+ # Admission must be atomic across user messages and coordinator wakeups.
8682
+ (@task_admission_mutex ||= Mutex.new).synchronize do
8683
+ session = @registry.get(session_id)
8684
+ return unless session
8685
+ if session[:status] == :running || (background && session[:thread]&.alive?)
8686
+ unless background
8687
+ broadcast(session_id, { type: "error", session_id: session_id,
8688
+ message: "Session is busy; please send your message again." })
8689
+ end
8690
+ return
8691
+ end
8692
+ launch_agent_task(session_id, agent, &task)
8693
+ end
8694
+ end
8695
+
8696
+ private def launch_agent_task(session_id, agent, &task)
8363
8697
  if @registry.running_full?
8364
8698
  broadcast(session_id, { type: "error", session_id: session_id,
8365
8699
  message: "Too many concurrent tasks (max #{@registry.max_running_agents}), please try again later" })
@@ -8403,6 +8737,7 @@ module Clacky
8403
8737
  Thread.current[:task_epoch] = epoch
8404
8738
  run_result = task.call
8405
8739
  awaiting = false
8740
+ web_ui = nil
8406
8741
  owns_epoch = true
8407
8742
  loop do
8408
8743
  owns_epoch = @registry.current_epoch(session_id).to_i == epoch.to_i
@@ -8412,6 +8747,7 @@ module Clacky
8412
8747
  @registry.with_session(session_id) do |s|
8413
8748
  owns_epoch = s[:epoch].to_i == epoch.to_i
8414
8749
  next unless owns_epoch
8750
+ web_ui = s[:ui]
8415
8751
  awaiting = run_result.is_a?(Hash) && run_result[:awaiting_user_feedback]
8416
8752
  pending = agent.take_pending_input if Agent.task_completed?(run_result)
8417
8753
  unless pending
@@ -8430,7 +8766,18 @@ module Clacky
8430
8766
  # session history: a chime is a live cue, never replayed on refresh.
8431
8767
  # Also fires when awaiting feedback — that is precisely when the user
8432
8768
  # most needs pulling back; the flag lets the client word it differently.
8433
- broadcast_all(type: "task_finished", session_id: session_id, awaiting_feedback: !!awaiting)
8769
+ finished = { type: "task_finished", session_id: session_id, awaiting_feedback: !!awaiting }
8770
+ # Carried inline because the client may not have this session in its
8771
+ # list yet (cron runs land in another project, and the sidebar is
8772
+ # paged), so a client-side lookup by id would come back empty and the
8773
+ # toast would lose the session name.
8774
+ name = @registry.with_session(session_id) { |s| s[:agent]&.name }
8775
+ finished[:session_name] = name unless name.to_s.strip.empty?
8776
+ finished[:notify_user] = false if run_result.is_a?(Hash) && run_result[:notify_user] == false
8777
+ # Lets clients not viewing this session keep the summary until it is first opened.
8778
+ complete = web_ui&.last_complete
8779
+ finished[:complete] = complete if complete&.dig(:task_id) && run_result.is_a?(Hash) && complete[:task_id] == run_result[:task_id]
8780
+ broadcast_all(finished)
8434
8781
  @session_manager.save(agent.to_session_data(status: :success, updated_at: Time.now))
8435
8782
  # Start idle compression timer now that the agent is idle
8436
8783
  idle_timer&.start
@@ -8611,6 +8958,7 @@ module Clacky
8611
8958
  ui = WebUIController.new(session_id, broadcaster)
8612
8959
  agent = Clacky::Agent.new(client, config, working_dir: working_dir, ui: ui, profile: profile,
8613
8960
  session_id: session_id, source: source)
8961
+ @work_service&.attach(agent)
8614
8962
  agent.rename(name) unless name.nil? || name.empty?
8615
8963
  idle_timer = build_idle_timer(session_id, agent)
8616
8964
 
@@ -8643,6 +8991,7 @@ module Clacky
8643
8991
  profile = session_data[:agent_profile].to_s
8644
8992
  profile = "general" if profile.empty?
8645
8993
  agent = Clacky::Agent.from_session(client, config, session_data, ui: ui, profile: profile)
8994
+ @work_service&.attach(agent)
8646
8995
  idle_timer = build_idle_timer(original_id, agent)
8647
8996
 
8648
8997
  # Register session atomically with a fully-built agent so no concurrent