openclacky 1.3.6 → 1.3.7

data/lib/clacky/default_extensions/ext-studio/skills/ext-debug/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: ext-debug
+description: Debug an OpenClacky extension that won't load, throws errors, or whose panel/api/skill/agent isn't showing up. Use when the user reports something broken with their extension, when `clacky ext verify` reports issues, or when a change didn't take effect. Reads structured verify errors and fixes manifest and file problems.
+---
+
+# Extension Debug
+
+Diagnose and fix a broken extension. Your primary instrument is `clacky ext verify` —
+it's a compiler for extensions: every issue is structured with a `code`, `message`,
+the offending `file`, and a `hint` telling you how to fix it.
+
+## Step 1 — Run verify
+
+```
+clacky ext verify
+```
+
+Read the output line by line. `[OK]` lines confirm resolved units. `[ERR]` blocks a
+load; `[WARN]` is advisory. Each issue looks like:
+
+```
+[ERR] <ext> <unit> (<code>) — <message> [<file>]
+         hint: <how to fix>
+```
+
+## Step 2 — Fix by error code
+
+- **`loader.error`** — a file the manifest points at is missing or the container
+  couldn't be parsed. Check the `file` path exists and `ext.yml` is valid YAML. A skill
+  needs `SKILL.md` under `skills/<id>/`; an agent needs its `prompt` file; a panel needs
+  its `view` file; api needs `api/handler.rb`.
+- **`schema.unknown_contributes`** — a top-level key under `contributes:` isn't one of
+  `panels api skills agents channels patches hooks`. Fix the spelling.
+- **`schema.unknown_field` / `schema.unknown_key`** — a unit has a field that isn't
+  allowed for its type. Remove or rename it. Allowed fields:
+  - panel: `id title title_zh description description_zh view order attach`
+  - api: `id handler`
+  - skill: `id dir protected`
+  - agent: `id title title_zh description description_zh order prompt panels skills`
+  - channel: `id platform adapter`
+- **`schema.bad_attach`** — a panel `attach:` entry isn't a valid token. Use agent ids
+  or `"*"` for all.
+- **`ref.missing_panel`** — an agent references `panels: [id]` that no panel provides.
+  Fix the id, or use `<ext_id>/<panel_id>` to reference a panel in another extension.
+- **`ref.missing_skill`** — an agent references `skills: [id]` that no skill provides.
+  Fix the id or add the skill.
+- **`ref.missing_attach_agent`** — a panel's `attach:` names an agent that doesn't
+  exist. Fix the agent id.
+- **`override`** (warning) — a unit in a higher layer is shadowing a lower one
+  (`local > installed > builtin`). Usually intentional; confirm with the user if not.
+
+Fix one issue, re-run verify, repeat until clean.
+
+## Step 3 — "It verifies but doesn't show up"
+
+If verify is clean but a change isn't visible:
+- **Hot reload is per-request.** After editing `view.js`, `handler.rb`, or a `SKILL.md`,
+  the user must **reload the WebUI page** — there's no restart, but a stale tab won't
+  update on its own. Editing `ext.yml` also applies on the next load.
+- **Panel not appearing?** Check the panel's `attach:` (or the agent that references it
+  via `panels: [id]`). A panel with no `attach` and no referencing agent has nothing to
+  mount onto.
+- **API 404?** Routes are relative to `/api/ext/<ext_id>/`. Confirm the handler subclasses
+  `Clacky::ApiExtension` and the route pattern matches what `view.js` fetches.
+- **Skill not triggering?** The AI selects skills by their `description`. Make the
+  description concrete about WHEN to use it.
+
+## Step 4 — Confirm the fix
+
+End with a clean `clacky ext verify` and have the user reload to confirm the behavior
+actually works — don't declare success on "should work."

data/lib/clacky/default_extensions/ext-studio/skills/ext-publish/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: ext-publish
+description: Pack and publish an OpenClacky extension to the marketplace, publish a new version, list published extensions, or unpublish one. Use when the user wants to ship, release, publish, update, or take down an extension. Handles packing, the license requirement, versioning, and the already-published case.
+---
+
+# Extension Publish
+
+Take a finished local extension and ship it to the OpenClacky marketplace, then confirm
+it's live.
+
+## Before publishing
+
+- The extension must live in the **local** layer (`~/.clacky/ext/local/<id>/`). Only
+  local containers can be packed. Marketplace-origin and encrypted (`SKILL.md.enc`)
+  containers are rejected.
+- Publishing requires an **activated user license** — it proves creator identity, and
+  the platform attributes the extension to that account. If activation is missing, tell
+  the user to activate first; don't try to work around it.
+- Run `clacky ext verify` one last time and confirm no errors before shipping.
+
+## Publish (first time)
+
+```
+clacky ext publish <id>
+```
+
+This packs the local container into a zip and uploads it. On success you'll see:
+
+```
+Published <id> v<version> → status=<status>
+```
+
+Options:
+- `--status draft` — publish as a draft (not yet visible on the public marketplace).
+  Omit or use `--status published` to go live.
+- `--changelog "..."` — release notes for this version.
+
+## Publish a new version
+
+If the extension is already published, a plain `publish` fails with:
+
+```
+Error: <id> already published. Re-run with --force to publish a new version.
+```
+
+Re-run with `--force` (and ideally a `--changelog`) to publish a new version. The patch
+version auto-increments on the platform side.
+
+```
+clacky ext publish <id> --force --changelog "Fixed the weather refresh bug"
+```
+
+## List your published extensions
+
+```
+clacky ext published
+```
+
+Shows each extension with its latest version, status, and unit summary.
+
+## Unpublish
+
+```
+clacky ext unpublish <id>
+```
+
+Soft-deletes (takes down) one of your published extensions. Confirm with the user
+before doing this — it removes it from the marketplace.
+
+## Wrap up
+
+After a successful publish, tell the user the version and status in plain terms, and
+mention they can run `clacky ext published` to see it in their list, or bump a new
+version anytime with `--force`.

data/lib/clacky/default_extensions/ext-studio/skills/ext-scaffold/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: ext-scaffold
+description: Scaffold a new OpenClacky extension from an idea. Use when the user wants to create, start, or bootstrap a new extension, plugin, panel, agent, or skill container. Maps the idea to the right contributes types and generates a working skeleton in the local layer.
+---
+
+# Extension Scaffold
+
+Turn a plain-language idea into a working extension skeleton, then read the generated
+files so you know what you're working with.
+
+## Step 1 — Understand the idea
+
+Figure out what the extension should DO and which contributes types it needs. Ask one
+clarifying question only if it's genuinely ambiguous. Common mappings:
+
+- "Show me X in a side panel / add a button / dashboard" → **panel** (+ **api** if it
+  needs a backend or to call an external service).
+- "A capability the AI can invoke" (summarize, translate, format) → **skill**.
+- "A specialized assistant with its own personality/tools" → **agent** (usually
+  bundling its own panels/skills).
+- "Connect to Slack / an in-house IM" → **channel**.
+
+Keep it minimal. Most useful extensions are one panel + one handler, or one skill.
+Do NOT add `patches` or `hooks` unless the user explicitly asks — they run arbitrary
+Ruby and carry supply-chain risk.
+
+## Step 2 — Generate the skeleton
+
+Pick a lowercase, hyphenated id derived from the idea (e.g. `weather-panel`).
+
+```
+clacky ext new <id>
+```
+
+This creates `~/.clacky/ext/local/<id>/` with a working hello panel + handler:
+- `ext.yml` — the manifest
+- `panels/hello/view.js` — a panel that pings the backend
+- `api/handler.rb` — a `Clacky::ApiExtension` subclass mounted at `/api/ext/<id>/`
+
+Use `--full` only if the user needs the kitchen-sink reference exercising all seven
+contributes types — it's a lot to read, so prefer the plain scaffold otherwise.
+
+## Step 3 — Read what was generated
+
+Always read the generated `ext.yml`, `view.js`, and `handler.rb` before editing. This
+is your starting point; you'll reshape it to match the idea.
+
+## Step 4 — Reshape to the idea
+
+Edit the files into real, working code:
+- Rename the panel id and `view.js` path to match the feature.
+- Update `ext.yml` `contributes:` — add `skills:`/`agents:` blocks if needed. A skill
+  is a `SKILL.md` under `skills/<id>/`; an agent is a `system_prompt.md` that can
+  reference `panels: [id]` and `skills: [id]`.
+- In `view.js`, reuse host CSS classes (`btn-primary`, `btn-secondary`, `form-input`,
+  `form-textarea`, `form-label`) so the panel inherits the theme automatically.
+- In `handler.rb`, define routes relative to the `/api/ext/<id>/` mount.
+
+## Step 5 — Confirm it loads
+
+Run `clacky ext verify` and confirm the new units resolve with no errors. Then tell
+the user to reload the WebUI page — panels and api changes are live on the next request,
+no restart needed.
+
+If verify reports problems, switch to debugging (the ext-debug skill covers this).

data/lib/clacky/default_extensions/general/ext.yml

@@ -0,0 +1,18 @@
+id: general
+name: General
+description: General-purpose digital employee agent
+version: "0.1.0"
+author: OpenClacky
+homepage: https://www.openclacky.com
+license: MIT
+origin: self
+contributes:
+  agents:
+    - id: general
+      title: General
+      title_zh: 通用
+      description: A versatile digital employee living on your computer
+      description_zh: 驻留在你电脑里的多面手数字员工
+      order: 1
+      prompt: agents/general/system_prompt.md
+      panels: [meeting/meeting]

data/lib/clacky/default_extensions/git/ext.yml

@@ -0,0 +1,12 @@
+id: git
+name: Git
+description: Changes panel — a friendly view of what the AI changed in the working tree
+version: "0.1.0"
+author: OpenClacky
+homepage: https://www.openclacky.com
+license: MIT
+origin: self
+contributes:
+  panels:
+    - id: git
+      view: panels/git/view.js

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

@@ -2,7 +2,7 @@
 //
 // "改动 / Changes": a non-technical view of what the AI changed, backed by the
 // built-in git API (GET/POST /api/sessions/:id/git/*). Mounted as a tab in the
-// "session.aside" slot, scoped to agents declaring `panels: [git]`.
+// "session.aside" slot, attached to agents via `attach: [coding]` in ext.yml.
 //
 // Deliberately hides git jargon: no porcelain status codes (M/??), no
 // branch/ahead/behind unless the branch is NOT the main line (main/master) —
@@ -194,7 +194,6 @@
     refresh(ctx.sessionId, root, body, ctx);
     return root;
   }, {
-    panel: "git",
     order: 10,
     tab: { id: "changes", label: () => t("changes.tab") },
   });

data/lib/clacky/default_extensions/meeting/{handler.rb → api/handler.rb}

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "json"
+require "set"
 require "fileutils"
 require "base64"
 require "tmpdir"
@@ -12,7 +13,10 @@ class MeetingExt < Clacky::ApiExtension
 
   MEETINGS_ROOT = File.expand_path("~/.clacky/meetings")
   VOCABULARY_PATH = File.join(MEETINGS_ROOT, "vocabulary.txt")
-  DEFAULT_VOCABULARY = "Clacky, OpenClacky, openclacky"
+  # Always injected into STT vocabulary — these are our own wake words / brand
+  # names and must not be droppable by the user's saved list.
+  SYSTEM_VOCABULARY = "Clacky, 小克".freeze
+  DEFAULT_VOCABULARY = "Clacky, 小克, OpenClacky, openclacky"
 
   # annotate is a read-only analysis: block every side-effecting tool so the
   # forked subagent can only read/think, never write files, run commands,
@@ -56,12 +60,15 @@ class MeetingExt < Clacky::ApiExtension
   end
 
   # POST /api/ext/meeting/end
-  # body: { session_id, meeting_id }
+  # body: { session_id, meeting_id, display_message? }
   # Finalizes the meeting and triggers summarization via the session agent.
   post "/end" do
     sid, mid = json_body.values_at("session_id", "meeting_id")
     error!("session_id and meeting_id required", status: 422) unless sid && mid
 
+    display_message = json_body["display_message"].to_s
+    display_message = "🛑 Meeting ended — generating meeting minutes…" if display_message.strip.empty?
+
     dir = meeting_dir(sid, mid)
     error!("meeting not found", status: 404) unless File.directory?(dir)
 
@@ -71,33 +78,19 @@ class MeetingExt < Clacky::ApiExtension
     File.write(meta_path, JSON.pretty_generate(meta))
 
     transcript_path = File.join(dir, "transcript.jsonl")
-    lines = File.readlines(transcript_path).map { |l| JSON.parse(l)["text"] }.reject(&:empty?)
+    lines = File.readlines(transcript_path).map { |l| JSON.parse(l)["text"] }.reject { |t| t.nil? || t.strip.empty? }
     transcript = lines.join("\n")
 
     logger.info("end: sid=#{sid} mid=#{mid} lines=#{lines.size} transcript_len=#{transcript.length}")
 
-    if transcript.strip.empty?
-      logger.warn("end: transcript is empty, skipping summarization")
-      json(ok: true, meeting_id: mid, skipped: true)
-      next
-    end
-
     prompt = <<~PROMPT
-      A meeting just ended. Invoke the "meeting-summarizer" skill to generate the meeting minutes from the transcript below.
+      A meeting just ended. Your ONLY next action is to call the tool `invoke_skill` with `name: "meeting-summarizer"` and pass the transcript below as the input. Do not use any other tool. Do not answer directly. Do not open a browser or run shell commands.
 
       Transcript:
       #{transcript}
     PROMPT
 
-    begin
-      submit_task(sid, prompt, display_message: "🛑 Meeting ended — generating meeting minutes…")
-      logger.info("end: submit_task succeeded sid=#{sid}")
-    rescue => e
-      logger.error("end: submit_task failed sid=#{sid} error=#{e.message}")
-      json(ok: false, meeting_id: mid, error: e.message)
-      next
-    end
-
+    submit_task(sid, prompt, display_message: display_message, interrupt: true)
     json(ok: true, meeting_id: mid)
   end
 
@@ -116,16 +109,19 @@ class MeetingExt < Clacky::ApiExtension
 
     mime = json_body["mime_type"].to_s.split(";").first.strip
     mime = "audio/webm" if mime.empty?
-    vocabulary = json_body["vocabulary"].to_s.strip
+    vocabulary = merge_vocabulary(json_body["vocabulary"])
     result = call_stt(audio_b64, mime, vocabulary)
 
     if result["success"]
       text = result["text"].to_s.strip
-      unless text.empty?
+      transcript_path = File.join(dir, "transcript.jsonl")
+      if !text.empty? && !hallucinated_transcript?(text, vocabulary, transcript_path)
         entry = { ts: Time.now.utc.iso8601, text: text }
-        File.open(File.join(dir, "transcript.jsonl"), "a") { |f| f.puts(JSON.generate(entry)) }
+        File.open(transcript_path, "a") { |f| f.puts(JSON.generate(entry)) }
+        json(text: text)
+      else
+        json(text: "")
       end
-      json(text: text)
     else
       error!(result["error"] || "STT failed", status: 502)
     end
@@ -138,12 +134,22 @@ class MeetingExt < Clacky::ApiExtension
   # Submits a question to the session agent with recent transcript as context.
   post "/ask" do
     sid, mid = json_body.values_at("session_id", "meeting_id")
-    question = json_body["question"]
-    error!("session_id, meeting_id, question required", status: 422) unless sid && mid && question
+    question = json_body["question"].to_s.strip
+    error!("session_id, meeting_id, question required", status: 422) unless sid && mid && !question.empty?
 
     dir = meeting_dir(sid, mid)
     error!("meeting not found", status: 404) unless File.directory?(dir)
 
+    meaningful = question.gsub(/[^\p{L}\p{N}]/, "")
+    if meaningful.length < 4
+      logger.warn("ask: question too short, dropping (question=#{question.inspect})")
+      next json(ok: false, dropped: true, reason: "question_too_short")
+    end
+    if question.match?(/\A(open)?clacky\z/i) || question.match?(/\A小?克\z/) || question.match?(/\A克拉奇\z/)
+      logger.warn("ask: question is a bare wake/brand word, dropping (question=#{question.inspect})")
+      next json(ok: false, dropped: true, reason: "question_is_brand_word")
+    end
+
     context = recent_transcript(dir, minutes: 5)
 
     prompt = <<~PROMPT
@@ -157,7 +163,7 @@ class MeetingExt < Clacky::ApiExtension
       #{question}
     PROMPT
 
-    submit_task(sid, prompt, display_message: "🎤 #{question}")
+    submit_task(sid, prompt, display_message: "🎤 #{question}", interrupt: true)
     json(ok: true)
   end
 
@@ -286,6 +292,52 @@ class MeetingExt < Clacky::ApiExtension
     saved.empty? ? "" : saved
   end
 
+  private def merge_vocabulary(user_terms)
+    parts = SYSTEM_VOCABULARY.split(/\s*,\s*/) + user_terms.to_s.split(/\s*,\s*/)
+    parts.map(&:strip).reject(&:empty?).uniq.join(", ")
+  end
+
+  HALLUCINATION_PHRASES = Set.new(%w[
+    no no. yes yes. ok okay you bye . .. ...
+    thanks thank\ you
+    uh um hmm mm mm-hmm yeah yeah. yep but and so oh ah ahh huh
+    an a i the more well right hi hey wow
+    嗯 啊 哦 呃 谢谢 谢谢观看 谢谢大家 好 好的 对
+  ]).freeze
+
+  DEDUP_WINDOW_SECONDS = 3.0
+
+  private def hallucinated_transcript?(text, vocabulary, transcript_path)
+    normalized = normalize_transcript(text)
+    return true if normalized.empty?
+    return true if HALLUCINATION_PHRASES.include?(normalized)
+    return true if only_vocabulary_term?(normalized, vocabulary)
+    return true if recent_duplicate?(normalized, transcript_path)
+    false
+  end
+
+  private def normalize_transcript(text)
+    text.to_s.downcase.gsub(/[[:space:][:punct:]]+/, " ").strip
+  end
+
+  private def only_vocabulary_term?(normalized, vocabulary)
+    terms = vocabulary.to_s.split(/\s*,\s*/).map { |t| normalize_transcript(t) }.reject(&:empty?)
+    terms.include?(normalized)
+  end
+
+  private def recent_duplicate?(normalized, transcript_path)
+    return false unless File.exist?(transcript_path)
+
+    cutoff = Time.now.utc - DEDUP_WINDOW_SECONDS
+    File.foreach(transcript_path).to_a.last(5).any? do |line|
+      entry = JSON.parse(line) rescue nil
+      next false unless entry
+      ts = Time.parse(entry["ts"].to_s) rescue nil
+      next false unless ts && ts >= cutoff
+      normalize_transcript(entry["text"]) == normalized
+    end
+  end
+
   private def recent_transcript(dir, minutes: 5)
     path = File.join(dir, "transcript.jsonl")
     return "" unless File.exist?(path)

data/lib/clacky/default_extensions/meeting/ext.yml

@@ -0,0 +1,15 @@
+id: meeting
+name: Meeting
+description: Real-time meeting transcription and AI assistant
+version: "0.1.0"
+author: OpenClacky
+homepage: https://www.openclacky.com
+license: MIT
+origin: self
+contributes:
+  api: api/handler.rb
+  panels:
+    - id: meeting
+      view: panels/meeting/view.js
+  skills:
+    - id: meeting-summarizer