openclacky 1.3.6 → 1.3.7

data/lib/clacky/{default_agents/_panels/time_machine/panel.js → default_extensions/time_machine/panels/time_machine/view.js}

@@ -607,55 +607,66 @@
              confirmRow, confirmYes, confirmNo, files: filesEl, diff: diffEl, diffPath: diffPathEl };
   }
 
-  Clacky.ext.ui.mount("session.aside", (ctx) => {
-    if (!ctx || !ctx.sessionId) return null;
-
-    const list = el("div", { class: "tm-list" });
-    const foot = el("div", { class: "tm-foot", text: t("tm.foot", "每完成一步会自动存档。点击想回到的版本即可恢复。") });
-    const root = el("div", { class: "tm-panel", "data-panel": "tm" }, list, foot);
-
-    const d = buildDrawer();
-
-    const state = {
-      sessionId: ctx.sessionId,
-      tasks: [],
-      selected: null,
-      expanded: null,
-      panelEl: root, listEl: list, footEl: foot,
-      maskEl: d.mask, drawerEl: d.drawer,
-      drawerTitleEl: d.title, drawerTimeEl: d.time,
-      restoreBtn: d.restore, filesEl: d.files, diffEl: d.diff, diffPathEl: d.diffPath, confirmRow: d.confirmRow,
-    };
+  Clacky.ext.ui.mount("session.aside", {
+    create(ctx) {
+      const list = el("div", { class: "tm-list" });
+      const foot = el("div", { class: "tm-foot", text: t("tm.foot", "每完成一步会自动存档。点击想回到的版本即可恢复。") });
+      const root = el("div", { class: "tm-panel", "data-panel": "tm" }, list, foot);
+
+      const d = buildDrawer();
+
+      const state = {
+        sessionId: ctx.sessionId,
+        tasks: [],
+        selected: null,
+        expanded: null,
+        panelEl: root, listEl: list, footEl: foot,
+        maskEl: d.mask, drawerEl: d.drawer,
+        drawerTitleEl: d.title, drawerTimeEl: d.time,
+        restoreBtn: d.restore, filesEl: d.files, diffEl: d.diff, diffPathEl: d.diffPath, confirmRow: d.confirmRow,
+      };
 
-    // Re-bind the global drawer's controls to this mount's state. (The drawer
-    // is shared across mounts but only one is interactive at a time.)
-    const onClose = () => closeDrawer(state);
-    const onRestoreClick = () => {
-      d.confirmRow.style.display = "flex";
-      d.restore.disabled = true;
-    };
-    const onCancelClick = () => {
-      d.confirmRow.style.display = "none";
-      d.restore.disabled = false;
-    };
-    const onGoClick = () => performRestore(state);
-    const onMaskClick = () => closeDrawer(state);
-    const onKey = (e) => { if (e.key === "Escape" && d.drawer.classList.contains("open")) closeDrawer(state); };
-
-    d.close.onclick = onClose;
-    d.restore.onclick = onRestoreClick;
-    d.confirmNo.onclick = onCancelClick;
-    d.confirmYes.onclick = onGoClick;
-    d.mask.onclick = onMaskClick;
-    document.addEventListener("keydown", onKey);
-
-    _activeState = state;
-    _hookWs();
-
-    loadHistory(state);
-    return root;
+      const onClose = () => closeDrawer(state);
+      const onRestoreClick = () => {
+        d.confirmRow.style.display = "flex";
+        d.restore.disabled = true;
+      };
+      const onCancelClick = () => {
+        d.confirmRow.style.display = "none";
+        d.restore.disabled = false;
+      };
+      const onGoClick = () => performRestore(state);
+      const onMaskClick = () => closeDrawer(state);
+      const onKey = (e) => { if (e.key === "Escape" && d.drawer.classList.contains("open")) closeDrawer(state); };
+
+      d.close.onclick = onClose;
+      d.restore.onclick = onRestoreClick;
+      d.confirmNo.onclick = onCancelClick;
+      d.confirmYes.onclick = onGoClick;
+      d.mask.onclick = onMaskClick;
+      document.addEventListener("keydown", onKey);
+
+      _activeState = state;
+      _hookWs();
+
+      loadHistory(state);
+
+      return {
+        state,
+        root,
+        dispose() {
+          document.removeEventListener("keydown", onKey);
+          try { d.mask.remove(); } catch (_) {}
+          try { d.drawer.remove(); } catch (_) {}
+          if (_activeState === state) _activeState = null;
+        },
+      };
+    },
+    render(container, ctx, runtime) {
+      container.appendChild(runtime.root);
+      _activeState = runtime.state;
+    },
   }, {
-    panel: "time_machine",
     order: 20,
     tab: { id: "tm", label: () => t("tm.tab") },
   });

data/lib/clacky/default_skills/channel-manager/discord_setup.rb

@@ -85,7 +85,7 @@ end
 def saved_bot_token
   yml_path = File.expand_path("~/.clacky/channels.yml")
   return nil unless File.exist?(yml_path)
-  data = YAML.safe_load_file(yml_path, permitted_classes: [Symbol], aliases: true) rescue nil
+  data = YAML.safe_load(File.read(yml_path), permitted_classes: [Symbol], aliases: true) rescue nil
   data&.dig("channels", "discord", "bot_token") || data&.dig(:channels, :discord, :bot_token)
 end
 

data/lib/clacky/default_skills/extend-openclacky/SKILL.md

@@ -5,37 +5,102 @@ description: Customize, fix, override or extend openclacky itself — change a b
 
 # Extending Openclacky
 
-Openclacky ships four official extension mechanisms that survive `gem update` and never require editing the gem source.
-**Never tell the user to `bundle show openclacky` and edit the gem — always use one of these.**
+Openclacky ships one unified extension mechanism — an **extension container**
+declared by a single `ext.yml`. It survives `gem update` and never requires
+editing the gem source.
 
-## Pick the right mechanism
+**Never tell the user to `bundle show openclacky` and edit the gem.**
 
-| User wants to… | Use | Scaffold | Verify |
-|---|---|---|---|
-| Change behavior of an **existing method** in openclacky (e.g. `WebSearch#execute` timeout, fix a bug in a built-in tool) | **Patch** | `clacky patch_new <id> "Const#method" -d "<desc>"` | `clacky patch_verify` |
-| **Audit / block / observe** tool calls (block `rm -rf /`, log every shell command) — no Ruby needed | **Shell Hook** | `clacky hook_new <id> -e <event>` | `clacky hook_verify` |
-| Plug openclacky into a **new IM platform** (Slack, in-house IM, custom webhook…) | **Channel Adapter** | `clacky channel_new <platform_id>` | `clacky channel_verify` |
-| Add UI to the **Web UI** (custom panel, header button, settings tab, visualize data) | **Web UI Extension** | drop a `.js` file in `~/.clacky/webui_ext/` | reload page; `Clacky.ext.slots()` in console; `?pure=true` to escape |
+## The one entry point
+
+Every extension lives in a container directory:
+
+```
+~/.clacky/ext/local/<id>/
+  ext.yml         # single manifest — declares everything the container contributes
+  panels/…        # WebUI panels (JS)
+  api/handler.rb  # HTTP API backend
+  skills/…        # AI skills
+  agents/…        # agent profiles + prompts
+  channels/…      # IM adapters
+  patches/…       # runtime method patches
+  hooks/…         # shell hooks
+```
+
+Scaffold with:
+```bash
+clacky ext new <id>            # minimal hello-panel starter
+clacky ext new <id> --full     # kitchen-sink example with every contributes type
+```
+
+The ext.yml `contributes:` map declares which of these 7 types the container
+provides. A container may use one, several, or all.
+
+## Pick what to add to `contributes:`
+
+| User wants to… | contributes: field |
+|---|---|
+| Add a **WebUI panel / button / settings tab / data visualisation** | `panels:` |
+| Add an **HTTP API backend** (routes under `/api/ext/<id>/…`) | `api:` (a single `handler.rb`) |
+| **Change behavior of a built-in method** in openclacky (e.g. `WebSearch#execute` timeout) | `patches:` |
+| **Audit / block / observe** tool calls (block `rm -rf /`, log every shell command) | `hooks:` |
+| Plug openclacky into a **new IM platform** (Slack, in-house IM, custom webhook) | `channels:` |
+| Add a **new AI skill** (SKILL.md) | `skills:` |
+| Bundle a **custom agent profile** with its own panels + skills | `agents:` |
 
 ## Authoritative documentation
 
-Each mechanism has a full reference doc — read the relevant one with `web_fetch` before writing code:
+Read the relevant reference doc with `web_fetch` before writing code —
+don't guess field names, hook events, adapter methods, or the `Clacky.ext`
+WebUI contract.
 
+- Extension containers (ext.yml overview) → https://www.openclacky.com/docs/extend
+- Panels (WebUI) → https://www.openclacky.com/docs/extend-webui
+- API backends → https://www.openclacky.com/docs/extend-api
 - Patches → https://www.openclacky.com/docs/extend-patches
 - Shell Hooks → https://www.openclacky.com/docs/extend-shell-hooks
 - Channel Adapters → https://www.openclacky.com/docs/extend-channel-adapter
-- Web UI Extensions → https://www.openclacky.com/docs/extend-webui
+
+## WebUI host services live under `Clacky.*`
+
+The single public API surface for WebUI extensions is `window.Clacky`.
+All host services are exposed as properties on it — reach for them there,
+not through bare globals or `window.Xxx`:
+
+```js
+Clacky.Sessions.on("switched", handler);   // active session store
+Clacky.Router.go("session");                // top-level view routing
+Clacky.I18n.t("some.key");                  // translations
+Clacky.Modal.confirm("Delete?");            // dialogs
+Clacky.Notify.info("Saved");                // toasts
+Clacky.Auth.passed;                          // auth state
+Clacky.Workspace.list(dir);                 // working-directory files
+Clacky.Skills.list();                       // skill catalog
+Clacky.Backup.load();                       // backup/restore state
+Clacky.WS.send({ type: "..." });            // send a WebSocket message to the agent
+```
+
+Rules:
+
+- Prefer `Clacky.Xxx.method(...)` — this is the recommended, forward-stable form.
+- `window.Clacky.Xxx.method(...)` works too and is fine in defensive code.
+- **Never** write `window.Sessions` / `typeof window.Sessions` / `"Sessions" in window`
+  — bare host names are `const` bindings, not `window` properties, so those checks
+  return `undefined` / `false` even though the module is loaded.
+- The bare form (`Sessions.on(...)`) still works for backwards compatibility
+  but is not the pattern to teach or generate.
 
 ## Execution playbook
 
-1. **Identify** which mechanism fits (use the table above; ask if genuinely ambiguous).
-2. **Read the doc** for that mechanism with `web_fetch`. Don't guess fields, hook events, or required methods — the doc is the contract.
-3. **Run the scaffold** CLI command. It generates the file(s) in `~/.clacky/...` with correct meta. *(Web UI Extensions have no scaffold — just create a `.js` file under `~/.clacky/webui_ext/`; the doc shows the `Clacky.ext` contract.)*
-4. **Edit** the generated file to implement the user's intent. Keep generated meta fields (`target`, `event`, `platform_id`, the `Clacky::ChannelRegistry.register(...)` line, etc.) intact unless the doc says otherwise.
-5. **Verify** with the matching `*_verify` command. Surface any `[FAIL]` lines to the user verbatim. *(Web UI Extensions have no verify command — reload the page and confirm the slot rendered; if anything breaks, `?pure=true` disables all extensions instantly.)*
+1. **Identify** which `contributes:` fields the user's intent needs (use the table above; ask if genuinely ambiguous).
+2. **Read the doc(s)** for those fields. The doc is the contract.
+3. **Scaffold** with `clacky ext new <id>` (or `--full` if the user wants every type wired up as a reference).
+4. **Edit** `ext.yml` to declare the fields, and fill in the referenced files (panel view.js, api handler.rb, patches/xxx.rb, etc.).
+5. **Verify** with `clacky ext verify`. Surface any error/skip lines to the user verbatim.
+6. **Reload** the WebUI page (for panel/api changes take effect on next request — no restart needed).
 
 ## When NOT to use this skill
 
-- The user is building features in their own application that just *use* openclacky — that's normal coding, no patch/hook/channel needed.
-- The user wants a brand-new tool/skill for *their* project — use `.clacky/skills/` or `.clacky/tools/`, not these gem-level mechanisms.
+- The user is building features in their own application that just *use* openclacky — that's normal coding, no extension container needed.
+- The user wants a brand-new tool/skill for *their* project — use `.clacky/skills/` or `.clacky/tools/` in their project, not a gem-level container.
 - The change can be made via `clacky config set ...` — prefer config over patches.

data/lib/clacky/{api_extension.rb → extension/api_extension.rb}

@@ -4,16 +4,16 @@ require "json"
 require "fileutils"
 
 module Clacky
-  # Base class for user-defined HTTP API extensions loaded from
-  # ~/.clacky/api_ext/<name>/handler.rb. Subclasses use a tiny route DSL
+  # Base class for HTTP API extensions declared in an ext.yml container as
+  # `contributes.api: <path/to/handler.rb>`. Subclasses use a tiny route DSL
   # (get/post/put/patch/delete) to expose endpoints under
-  #   /api/ext/<name>/<sub-path>
+  #   /api/ext/<ext_id>/<sub-path>
   #
   # The framework wires up access-key auth, timeouts, JSON error envelopes,
   # path-parameter parsing, and a curated handler context — extension authors
   # only fill in business logic.
   #
-  # Minimal example (~/.clacky/api_ext/my-dashboard/handler.rb):
+  # Minimal example (~/.clacky/ext/local/my-dashboard/api/handler.rb):
   #
   #   class MyDashboardExt < Clacky::ApiExtension
   #     get "/summary" do
@@ -41,8 +41,8 @@ module Clacky
     end
 
     class << self
-      # Registry of all loaded ApiExtension subclasses, keyed by extension id
-      # (== directory name == mount prefix segment).
+      # Keyed by ext_id — every extension contributes at most one API unit
+      # (declared as `contributes.api: <path>` in ext.yml).
       def registry
         @registry ||= {}
       end
@@ -81,6 +81,14 @@ module Clacky
         @public_paths ||= []
       end
 
+      # Clears accumulated route/public-path state so a force-reload (`load`) of
+      # a named-constant handler re-registers its routes from scratch instead of
+      # appending duplicates onto the reopened class.
+      def reset_routes!
+        @routes = []
+        @public_paths = []
+      end
+
       def ext_id
         @ext_id
       end
@@ -115,7 +123,7 @@ module Clacky
       end
 
       # Mark a route as not requiring access-key auth. Caller must also
-      # declare `public: true` in meta.yml for the framework to honor this.
+      # declare `public: true` at ext.yml top level for the framework to honor this.
       def public_endpoint(pattern)
         public_paths << normalize_pattern(pattern)
       end
@@ -264,9 +272,11 @@ module Clacky
     end
 
     # Submit a prompt to an existing session for execution.
-    # The session must be idle; returns the session_id on success.
-    # Raises Halt (409) if the session is already running.
-    def submit_task(session_id, prompt, display_message: nil)
+    # Returns the session_id on success.
+    # Raises Halt (409) if the session is already running and `interrupt: false`.
+    # When `interrupt: true`, supersedes the current turn (raises AgentInterrupted
+    # on the running thread, waits up to 2s for it to exit) then runs the new task.
+    def submit_task(session_id, prompt, display_message: nil, interrupt: false)
       reg = registry
       error!("server not ready", status: 503) unless reg
 
@@ -276,7 +286,13 @@ module Clacky
       end
 
       session = reg.get(session_id)
-      error!("session is busy", status: 409) if session[:status] == :running
+      if session[:status] == :running
+        error!("session is busy", status: 409) unless interrupt
+        @http_server.send(:interrupt_session, session_id)
+        old_thread = nil
+        reg.with_session(session_id) { |s| old_thread = s[:thread] }
+        old_thread&.join(2)
+      end
 
       @http_server.send(:run_session_task, session_id, prompt, display_message: display_message)
       session_id

data/lib/clacky/extension/api_loader.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Clacky
+  # Loads HTTP API extensions from ext.yml containers into the shared
+  # Clacky::ApiExtension registry, keyed by ext_id. Every ext contributes
+  # at most one api unit (`contributes.api: <path>` in ext.yml), so the
+  # registry key is simply the ext id.
+  #
+  # A broken extension (syntax error, missing base class, no routes) is
+  # isolated: skipped with a logged warning, never aborts sibling loads.
+  module ApiExtensionLoader
+    class << self
+      def load_all(reload: false)
+        result = Result.new(loaded: [], skipped: [])
+        Clacky::ApiExtension.reset_registry!
+        handler_mtime_cache.clear
+
+        loader_result = Clacky::ExtensionLoader.load_all
+        loader_result.api.each do |unit|
+          container = loader_result.containers[unit.ext_id]
+          load_one(unit.ext_id, unit.spec["handler_abs"], unit.dir, container, result, reload: reload)
+        end
+
+        @last_result = result
+        log_summary(result)
+        result
+      end
+
+      Result = Struct.new(:loaded, :skipped, keyword_init: true)
+
+      def last_result
+        @last_result || load_all
+      end
+
+      # Per-request hot path used by the dispatcher. Re-loads the handler
+      # only when its file mtime has changed since the last load.
+      def ensure_fresh(ext_id)
+        loader_result = Clacky::ExtensionLoader.load_all
+        unit = loader_result.api.find { |u| u.ext_id == ext_id.to_s }
+        return unless unit
+
+        path = unit.spec["handler_abs"]
+        current_mtime = File.mtime(path).to_f
+        cache = handler_mtime_cache
+        return if cache[ext_id.to_s] == current_mtime
+
+        container = loader_result.containers[unit.ext_id]
+        r = Result.new(loaded: [], skipped: [])
+        load_one(unit.ext_id, path, unit.dir, container, r, reload: true)
+        r.skipped.each { |(id, reason)| log_skip(id, reason) }
+        cache[ext_id.to_s] = current_mtime
+      rescue StandardError => e
+        Clacky::Logger.warn("[ApiExtensionLoader] ensure_fresh(#{ext_id}) failed: #{e.message}")
+      end
+
+      private def handler_mtime_cache
+        @handler_mtime_cache ||= {}
+      end
+
+      def load_one(ext_id, handler_path, ext_dir, container, result, reload: false)
+        before = Clacky::ApiExtension.pending_subclasses.size
+
+        existing = reload ? Clacky::ApiExtension.registry[ext_id] : nil
+        existing&.reset_routes!
+
+        if reload
+          old_verbose = $VERBOSE
+          $VERBOSE = nil
+          begin
+            load(handler_path)
+          ensure
+            $VERBOSE = old_verbose
+          end
+        else
+          require(handler_path)
+        end
+
+        new_subclasses = Clacky::ApiExtension.pending_subclasses[before..] || []
+        klass = new_subclasses.last || existing
+
+        unless klass
+          result.skipped << [ext_id, "no Clacky::ApiExtension subclass defined in handler.rb"]
+          log_skip(ext_id, result.skipped.last[1])
+          return
+        end
+
+        klass.ext_id  = ext_id
+        klass.ext_dir = ext_dir
+        klass.meta    = (container && container[:raw]) || {}
+
+        if klass.routes.empty?
+          result.skipped << [ext_id, "no routes declared (use get/post/... DSL)"]
+          log_skip(ext_id, result.skipped.last[1])
+          Clacky::ApiExtension.registry.delete(ext_id)
+          return
+        end
+
+        if (gap = validate_public_endpoints(klass, container))
+          result.skipped << [ext_id, gap]
+          log_skip(ext_id, gap)
+          return
+        end
+
+        Clacky::ApiExtension.register(ext_id, klass)
+        result.loaded << ext_id
+        handler_mtime_cache[ext_id] = File.mtime(handler_path).to_f rescue nil
+        public_count = klass.public_paths.size
+        suffix = public_count > 0 ? " (#{public_count} public)" : ""
+        Clacky::Logger.info("[ApiExtensionLoader] Loaded '#{ext_id}' — #{klass.routes.size} route(s)#{suffix}")
+      rescue StandardError, ScriptError => e
+        result.skipped << [ext_id, e.message]
+        log_skip(ext_id, e.message)
+      end
+
+      private def validate_public_endpoints(klass, container)
+        return nil if klass.public_paths.empty?
+        return nil if container && container[:public] == true
+
+        "uses public_endpoint but ext.yml is missing 'public: true' at top level"
+      end
+
+      private def log_skip(ext_id, reason)
+        Clacky::Logger.warn("[ApiExtensionLoader] Skipped '#{ext_id}': #{reason}")
+      end
+
+      private def log_summary(result)
+        return if result.loaded.empty? && result.skipped.empty?
+
+        total_routes = result.loaded.sum { |id| Clacky::ApiExtension.registry[id]&.routes&.size || 0 }
+        Clacky::Logger.info("[ApiExtensionLoader] #{result.loaded.size} extension(s), #{total_routes} route(s); #{result.skipped.size} skipped")
+      end
+    end
+  end
+end