openclacky 0.7.8 → 0.7.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9b2a72212b8b9e8072acb09a055df1afdd8225ee81de41f11dce460a68ff1781
-  data.tar.gz: e8048bb38dc4a8ae8c85937165e10a855f8642d6759c8a2a94aa336b084e4188
+  metadata.gz: 93b025580a849df456c7d9d20089b31f392446c2d46d842117563fe349740c92
+  data.tar.gz: 5a61ab30b81751176a2f612d3db2822bef54f99b3f907f73e7e7bba0c12bc231
 SHA512:
-  metadata.gz: '095710e060b7c29882eb128be1a4008281435c13af07e7da01ec9ad1af27c30e252eb19e77f557882628409058d504f29024ea0dbb396ed20d326b26cfe1925c'
-  data.tar.gz: 2875ac5911322341be5fe396ad44a98e4cbcea51c95ed7d832e3978d5790542ca94ae0f065f6170484d9900be2f1ca190f6db0d25c14a33366f924f9d13a147d
+  metadata.gz: c5a5aefd0945a2296783df6f9b8f6779d4bd36bc35cae587dc743a19e71e59c7714731e742dc8b1ecdba2535896c8f4be434bea1d2adac2dc1bd4ad56762a11e
+  data.tar.gz: 639d2f4e3d72250ac70dc9e27ad3157e91878bac076a3b13edaa8de00bae7f8342b87fe42357475092b2aecaca5425720e124d222e398cbe623207167ef21b2c

data/CHANGELOG.md

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.9] - 2026-03-07
+
+### Added
+- Cursor-paginated message history in web UI for large session navigation
+- `confirm_all` permission mode for WebUI human sessions
+- Re-run onboard entry in settings panel
+
+### Fixed
+- Expand `~` in file system tools path arguments (file_reader, glob, grep, write, edit)
+- Sort sessions newest-first with scheduled sessions at bottom
+- Tasks and skills sidebar items now static — no longer disappear on scroll
+- Delete task now also removes associated schedules
+
+### More
+- Add frontmatter (`name`, `description`, `disable-model-invocation`, `user-invocable`) to onboard skill
+
 ## [0.7.8] - 2026-03-06
 
 ### Added

data/docs/agent-first-ui-design.md

@@ -0,0 +1,77 @@
+# Agent-First UI Design Philosophy
+
+> Guiding principle for all OpenClacky UI and feature design.
+
+---
+
+## Core Principle
+
+**Conversation first, interactive cards when needed.**
+
+Users interact with the Agent through natural language to accomplish everything. When conversation is inconvenient for structured input (e.g. dropdowns, multi-select, precise time picking), the Agent triggers an **interactive card** via the `request_user_feedback` tool — rendered by the frontend as a structured UI component. Cards are a complement to conversation, not a replacement.
+
+---
+
+## Two Interaction Modes
+
+### 1. Conversation (default)
+User expresses intent in natural language, Agent understands and executes.
+
+```
+User:  Send me a daily standup summary every morning at 9
+Agent: Done! Task created, runs Mon–Fri at 09:00 ✅
+```
+
+### 2. Interactive Cards (when conversation falls short)
+When the Agent needs structured input that's hard to express in free text, it calls `request_user_feedback`. The frontend renders this as an interactive card (dropdowns, radio buttons, time pickers, etc.).
+
+```
+Agent calls request_user_feedback → frontend renders a card:
+
+┌─────────────────────────────┐
+│ 📋 Confirm task settings     │
+│ Frequency: [Daily      ▼]   │
+│ Time:      [09:00      ]    │
+│            [✅ Confirm] [Cancel] │
+└─────────────────────────────┘
+
+User fills card → structured data sent back to Agent → execution continues
+```
+
+---
+
+## When to Use Cards
+
+| Situation | Reason |
+|-----------|--------|
+| Choosing from a list of options | Easier than enumerating in chat |
+| Date / time selection | Precise value, error-prone in free text |
+| Sensitive input like API keys | Should not appear in conversation history |
+| Collecting multiple fields at once | One card beats several back-and-forth questions |
+
+Everything else: use conversation.
+
+---
+
+## What Should NOT Exist
+
+- ❌ Persistent configuration form pages
+- ❌ Fields that require users to understand technical details (cron expressions, agent IDs, etc.)
+- ❌ More than 3 action buttons per list row
+- ❌ Standalone "Create" form modals
+
+---
+
+## Role of UI Pages
+
+UI pages are for **displaying state**, not for configuring things:
+
+- ✅ Show task lists, run history, current status
+- ✅ Minimal action set per row: ▶ Run / ✎ Edit (opens conversation) / ✕ Delete
+- ❌ No inline create/edit forms inside list pages
+
+Clicking "Edit" opens an Agent conversation with context pre-filled. The Agent drives the modification flow from there.
+
+---
+
+*Applies to all OpenClacky Web UI and feature design.*

data/docs/session-skill-invocation.md

@@ -0,0 +1,69 @@
+# Session + Skill Invocation Pattern
+
+> Design pattern for launching an Agent session that immediately runs a skill.
+> Follow this whenever a UI action needs to "open a session and do something automatically."
+
+---
+
+## The Pattern
+
+```
+1. POST /api/sessions          → create a named session
+2. Sessions.add(session)       → register locally
+3. Sessions.renderList()       → update sidebar
+4. _bootUI() if needed         → connect WS (only on first boot)
+5. Sessions.select(session.id) → navigate to session (triggers WS subscribe)
+6. WS.send({ type: "message", session_id, content: "/skill-name" })
+                               → agent runs the skill immediately
+```
+
+The slash command (`/skill-name`) is handled by `Agent#parse_skill_command` on the
+server side — no special API endpoint or pending-state machinery needed.
+
+---
+
+## Real Usages
+
+### Create Task (`tasks.js → createInSession`)
+```js
+Sessions.select(session.id);
+WS.send({ type: "message", session_id: session.id, content: "/create-task" });
+```
+
+### Onboard (`onboard.js → _startSoulSession`)
+```js
+_bootUI();                  // WS.connect() + Tasks/Skills load
+Sessions.add(session);
+Sessions.renderList();
+Sessions.select(session.id);
+WS.send({ type: "message", session_id: session.id, content: "/onboard" });
+```
+
+---
+
+## When to Use `pending_task` Instead
+
+Use the `pending_task` registry field (and the `run_task` WS message) **only** when
+the prompt is a large block of text read from a file (e.g. `POST /api/tasks/run`).
+
+For slash commands, always prefer the direct `WS.send` approach above — simpler and
+no server-side state to manage.
+
+---
+
+## Anti-patterns Avoided
+
+| Anti-pattern | Why it was wrong |
+|---|---|
+| Store `_pendingSessionId` in module state, resolve on `session_list` | Race condition between WS connect and session_list arrival; unnecessary complexity |
+| Custom `takePendingSession()` hook in app.js `session_list` handler | Spread logic across files; hard to trace |
+| Send prompt via `setTimeout` after boot | Fragile timing; breaks if WS is slow |
+
+---
+
+## Key Insight
+
+`Sessions.select(id)` triggers a WS `subscribe` message. Once the server confirms
+with `subscribed`, the client is guaranteed to receive all subsequent broadcasts for
+that session. Sending `WS.send({ type: "message" })` right after `select` is safe
+because the WebSocket driver queues messages until the connection is open.

data/lib/clacky/agent/session_serializer.rb

@@ -131,6 +131,82 @@ module Clacky
         end
       end
 
+      # Replay conversation history by calling ui.show_* methods for each message.
+      # Supports cursor-based pagination using created_at timestamps on user messages.
+      # Each "round" starts at a user message and includes all subsequent assistant/tool messages.
+      #
+      # @param ui [Object] UI interface that responds to show_user_message, show_assistant_message, etc.
+      # @param limit [Integer] Maximum number of rounds (user turns) to replay
+      # @param before [Float, nil] Unix timestamp cursor — only replay rounds where the user message
+      #   created_at < before. Pass nil to get the most recent rounds.
+      # @return [Hash] { has_more: Boolean } — whether older rounds exist beyond this page
+      def replay_history(ui, limit: 20, before: nil)
+        # Split @messages into rounds, each starting at a real user message
+        rounds = []
+        current_round = nil
+
+        @messages.each do |msg|
+          role = msg[:role].to_s
+
+          if role == "user" && !msg[:system_injected] && msg[:content].is_a?(String) &&
+             !msg[:content].to_s.start_with?("[SYSTEM]")
+            # Start a new round at each real user message
+            current_round = { user_msg: msg, events: [] }
+            rounds << current_round
+          elsif current_round
+            current_round[:events] << msg
+          end
+        end
+
+        # Apply before-cursor filter: only rounds whose user message created_at < before
+        if before
+          rounds = rounds.select { |r| r[:user_msg][:created_at] && r[:user_msg][:created_at] < before }
+        end
+
+        has_more = rounds.size > limit
+        # Take the most recent `limit` rounds
+        page = rounds.last(limit)
+
+        page.each do |round|
+          msg = round[:user_msg]
+          # Emit user message with its timestamp for dedup on the frontend
+          ui.show_user_message(extract_text_from_content(msg[:content]), created_at: msg[:created_at])
+
+          round[:events].each do |ev|
+            case ev[:role].to_s
+            when "assistant"
+              # Text content
+              text = extract_text_from_content(ev[:content]).to_s.strip
+              ui.show_assistant_message(text) unless text.empty?
+
+              # Tool calls embedded in assistant message
+              Array(ev[:tool_calls]).each do |tc|
+                name     = tc[:name] || tc.dig(:function, :name) || ""
+                args_raw = tc[:arguments] || tc.dig(:function, :arguments) || {}
+                args     = args_raw.is_a?(String) ? (JSON.parse(args_raw) rescue args_raw) : args_raw
+                ui.show_tool_call(name, args)
+              end
+
+            when "user"
+              # Anthropic-format tool results (role: user, content: array of tool_result blocks)
+              next unless ev[:content].is_a?(Array)
+
+              ev[:content].each do |blk|
+                next unless blk.is_a?(Hash) && blk[:type] == "tool_result"
+
+                ui.show_tool_result(blk[:content].to_s)
+              end
+
+            when "tool"
+              # OpenAI-format tool result
+              ui.show_tool_result(ev[:content].to_s)
+            end
+          end
+        end
+
+        { has_more: has_more }
+      end
+
       private
 
       # Extract text from message content (handles string and array formats)

data/lib/clacky/agent/system_prompt_builder.rb

@@ -86,6 +86,25 @@ module Clacky
           prompt += "=" * 80
         end
 
+        # Load agent soul and user profile from ~/.clacky/agents/
+        agents_dir = File.expand_path("~/.clacky/agents")
+        [
+          { file: "SOUL.md", label: "AGENT SOUL" },
+          { file: "USER.md", label: "USER PROFILE" }
+        ].each do |entry|
+          path = File.join(agents_dir, entry[:file])
+          next unless File.exist?(path)
+
+          content = File.read(path).strip
+          next if content.empty?
+
+          prompt += "\n\n" + "=" * 80 + "\n"
+          prompt += "#{entry[:label]} (from ~/.clacky/agents/#{entry[:file]}):\n"
+          prompt += "=" * 80 + "\n"
+          prompt += content
+          prompt += "\n" + "=" * 80
+        end
+
         # Add all loaded skills to system prompt
         skill_context = build_skill_context
         prompt += skill_context if skill_context && !skill_context.empty?

data/lib/clacky/agent/tool_executor.rb

@@ -11,7 +11,11 @@ module Clacky
       # @return [Boolean] true if should auto-execute
       def should_auto_execute?(tool_name, tool_params = {})
         case @config.permission_mode
-        when :auto_approve
+        when :auto_approve, :confirm_all
+          # Both modes auto-execute all file/shell tools without confirmation.
+          # The difference is only in request_user_feedback handling:
+          #   auto_approve → no human present, inject auto_reply
+          #   confirm_all  → human present, truly wait for user input
           true
         when :confirm_safes
           # Use SafeShell integration for safety check

data/lib/clacky/agent.rb

@@ -163,7 +163,7 @@ module Clacky
 
       # Format user message with images if provided
       user_content = format_user_content(user_input, images)
-      @messages << { role: "user", content: user_content, task_id: task_id }
+      @messages << { role: "user", content: user_content, task_id: task_id, created_at: Time.now.to_f }
       @total_tasks += 1
 
       @hooks.trigger(:on_start, user_input)
@@ -502,12 +502,13 @@ module Clacky
             end
 
             if @config.permission_mode == :auto_approve
-              # Auto-approve mode means no human is watching — inject a reply so the LLM
-              # knows it should make a reasonable decision and keep going
+              # auto_approve means no human is watching (unattended/scheduled tasks).
+              # Inject an auto_reply so the LLM makes a reasonable decision and keeps going.
               result = result.merge(
                 auto_reply: "No user is available. Please make a reasonable decision based on the context and continue."
               )
             else
+              # confirm_all / confirm_safes — a human is present, truly wait for user input.
               awaiting_feedback = true
             end
           else

data/lib/clacky/agent_config.rb

@@ -148,7 +148,7 @@ module Clacky
     # Default model for ClaudeCode environment
     CLAUDE_DEFAULT_MODEL = "claude-sonnet-4-5"
 
-    PERMISSION_MODES = [:auto_approve, :confirm_safes].freeze
+    PERMISSION_MODES = [:auto_approve, :confirm_safes, :confirm_all].freeze
 
     attr_accessor :permission_mode, :max_tokens, :verbose,
                   :enable_compression, :enable_prompt_caching,

data/lib/clacky/cli.rb

@@ -25,8 +25,9 @@ module Clacky
       After completing a task, the agent waits for your next instruction.
 
       Permission modes:
-        auto_approve    - Automatically execute all tools (use with caution)
+        auto_approve    - Automatically execute all tools, no human interaction (use with caution)
         confirm_safes   - Auto-approve safe operations, confirm risky ones (default)
+        confirm_all     - Auto-approve all file/shell tools, but wait for human on interactive prompts
 
       UI themes:
         hacker          - Matrix/hacker-style with bracket symbols (default)
@@ -41,7 +42,7 @@ module Clacky
         $ clacky agent --mode=auto_approve --path /path/to/project
     LONGDESC
     option :mode, type: :string, default: "confirm_safes",
-           desc: "Permission mode: auto_approve, confirm_safes"
+           desc: "Permission mode: auto_approve, confirm_safes, confirm_all"
     option :theme, type: :string, default: "hacker",
            desc: "UI theme: hacker, minimal (default: hacker)"
     option :verbose, type: :boolean, aliases: "-v", default: false, desc: "Show detailed output"

data/lib/clacky/default_skills/onboard/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: onboard
+description: Onboard a new user by collecting AI personality preferences and user profile, then writing SOUL.md and USER.md.
+disable-model-invocation: true
+user-invocable: true
+---
+
+# Skill: onboard
+
+## Purpose
+Guide a new user through personalizing their Clacky experience via interactive cards.
+Collect AI personality preferences and user profile, then write `SOUL.md` and `USER.md`.
+All structured input is gathered through `request_user_feedback` cards — no free-form interrogation.
+
+## Steps
+
+### 1. Greet the user
+
+Send a short, warm welcome message (2–3 sentences). Detect the user's language from any
+text they've already typed; default to English. Do NOT ask any questions yet.
+
+Example (English):
+> Hi! I'm Clacky, your AI coding assistant ⚡
+> Let's take 30 seconds to personalize your experience — I'll ask just a couple of quick things.
+
+### 2. Collect AI personality (card)
+
+Call `request_user_feedback` with a card to set the assistant's name and personality:
+
+```json
+{
+  "question": "First, let's set up your assistant.",
+  "options": [
+    "🎯 Professional — Precise, structured, minimal filler",
+    "😊 Friendly — Warm, encouraging, like a knowledgeable friend",
+    "🎨 Creative — Imaginative, uses metaphors, enthusiastic",
+    "⚡ Concise — Ultra-brief, bullet points, maximum signal"
+  ]
+}
+```
+
+Also ask for a custom name in the same message if the platform supports a text field;
+otherwise follow up with: "What should I call myself? (leave blank to keep 'Clacky')"
+
+Map the chosen option to a personality key:
+- Option 1 → `professional`
+- Option 2 → `friendly`
+- Option 3 → `creative`
+- Option 4 → `concise`
+
+Store: `ai.name` (default `"Clacky"`), `ai.personality`.
+
+### 3. Collect user profile (card)
+
+Call `request_user_feedback` again:
+
+```json
+{
+  "question": "Now a bit about you — all optional, skip anything you like.",
+  "options": []
+}
+```
+
+Ask for the following in the question text (as labeled fields description, since options is empty):
+- Name / nickname
+- Occupation
+- What you want to use AI for most
+- Social / portfolio links (GitHub, Twitter/X, personal site…) — AI will read them to learn about you
+
+Parse the user's reply as free text; extract whatever they provide.
+
+### 4. Learn from links (if any)
+
+For each URL the user provided, use the `web_search` tool or fetch the page to read
+publicly available info: bio, projects, tech stack, interests, writing style, etc.
+Note key facts for the USER.md. Skip silently if a URL is unreachable.
+
+### 5. Write SOUL.md
+
+Write to `~/.clacky/agents/SOUL.md`.
+
+Use `ai.name` and `ai.personality` to shape the content.
+If the user's language appears to be non-English (detected from their replies), write in that language.
+
+**Personality style guide:**
+
+| Key | Tone |
+|-----|------|
+| `professional` | Concise, precise, structured. Gets to the point. Minimal filler. |
+| `friendly` | Warm, uses light humor, feels like a knowledgeable friend. |
+| `creative` | Imaginative, uses metaphors, thinks outside the box, enthusiastic. |
+| `concise` | Ultra-brief. Bullet points. Maximum signal-to-noise ratio. |
+
+Template:
+
+```markdown
+# [AI Name] — Soul
+
+## Identity
+I am [AI Name], an AI coding assistant and technical co-founder.
+[1–2 sentences reflecting the chosen personality.]
+
+## Personality & Tone
+[3–5 bullet points describing communication style.]
+
+## Core Strengths
+- Translating ideas into working code quickly
+- Breaking down complex problems into clear steps
+- Spotting issues before they become problems
+- Adapting explanation depth to the user's background
+
+## Working Style
+[2–3 sentences about how I approach tasks, matching the personality.]
+```
+
+### 6. Write USER.md
+
+Write to `~/.clacky/agents/USER.md`.
+
+```markdown
+# User Profile
+
+## About
+- **Name**: [nickname or "Not provided"]
+- **Occupation**: [or "Not provided"]
+- **Primary Goal**: [or "Not provided"]
+
+## Background & Interests
+[If links were fetched: 3–5 bullet points from what was learned.
+ Otherwise: omit section or write "No additional context."]
+
+## How to Help Best
+[1–2 sentences tailored to the user's goal and background.]
+```
+
+### 7. Confirm and close
+
+Reply with a single short message, e.g.:
+> All set! I've saved your preferences. Feel free to close this tab and start a fresh session — enjoy! 🚀
+
+Do NOT open a new session — the UI handles navigation after the skill finishes.
+
+## Notes
+- Keep both files under 300 words each.
+- Do not ask follow-up questions beyond the two cards above.
+- Work with whatever the user provides; fill in sensible defaults for anything omitted.