octo-agent 0.11.2

data/lib/octo/default_skills/personal-website/publish.rb

@@ -0,0 +1,235 @@
+#!/usr/bin/env ruby
+# publish.rb — Publish or delete a profile card on the platform
+#
+# Usage:
+#   ruby publish.rb publish --name "NAME" --html-file /path/to/card.html
+#   ruby publish.rb delete  --slug SLUG
+#
+# On first publish, prints the card URL and saves the update token to
+# ~/.octo/card_token (used for future updates/deletes).
+#
+# Environment:
+#   OCTO_LICENSE_SERVER — platform base URL override (default: https://www.octo.com)
+#   CARD_HMAC_SECRET      — shared secret (default matches platform default)
+
+require "net/http"
+require "uri"
+require "json"
+require "openssl"
+require "digest"
+require "optparse"
+require "fileutils"
+
+# ── Config ───────────────────────────────────────────────────────────────────
+
+# Primary CDN-accelerated endpoint.
+# Fallback bypasses EdgeOne and is used when the primary times out or errors.
+PRIMARY_HOST  = ENV.fetch("OCTO_LICENSE_SERVER", "https://www.octo.com")
+FALLBACK_HOST = "https://octo.up.railway.app"
+# When the env override is set we use only that host (dev/test mode).
+API_HOSTS     = ENV["OCTO_LICENSE_SERVER"] ? [PRIMARY_HOST] : [PRIMARY_HOST, FALLBACK_HOST]
+
+HMAC_SECRET  = ENV.fetch("CARD_HMAC_SECRET", "octo-card-v1-default-secret-change-me")
+TOKEN_FILE   = File.expand_path("~/octo_workspace/personal_website/token.json")
+
+# Retry / timeout config
+OPEN_TIMEOUT      = 8
+READ_TIMEOUT      = 15
+ATTEMPTS_PER_HOST = 2
+INITIAL_BACKOFF   = 0.5
+
+# ── HMAC signing ─────────────────────────────────────────────────────────────
+
+def device_fingerprint
+  parts = []
+  parts << `hostname`.strip
+  hw = `system_profiler SPHardwareDataType 2>/dev/null | grep 'Hardware UUID'`.strip
+  parts << hw unless hw.empty?
+  parts << ENV["USER"].to_s
+  Digest::SHA256.hexdigest(parts.join("|"))[0, 16]
+end
+
+def hmac_headers
+  ts          = Time.now.to_i.to_s
+  fingerprint = device_fingerprint
+  payload     = "octo:#{ts}:#{fingerprint}"
+  signature   = OpenSSL::HMAC.hexdigest("SHA256", HMAC_SECRET, payload)
+  {
+    "X-Card-Timestamp"   => ts,
+    "X-Card-Fingerprint" => fingerprint,
+    "X-Card-Signature"   => signature,
+    "Content-Type"       => "application/json"
+  }
+end
+
+# ── HTTP helpers ──────────────────────────────────────────────────────────────
+
+# Resilient HTTP request: retries on transient errors, then fails over to the
+# fallback host before giving up.
+#
+# Returns [http_code_int, parsed_body_hash].
+# Calls exit(1) on network failure (all hosts/attempts exhausted).
+def http_request(method, path, body: nil, extra_headers: {})
+  last_error = nil
+
+  API_HOSTS.each_with_index do |base, host_index|
+    ATTEMPTS_PER_HOST.times do |attempt|
+      begin
+        result = do_http_request(method, base, path, body: body, extra_headers: extra_headers)
+        return result
+      rescue RetryableError => e
+        last_error = e
+        backoff    = INITIAL_BACKOFF * (2**attempt)
+        sleep(backoff)
+      end
+    end
+  end
+
+  warn "❌ Network error: #{last_error&.message || "unknown"}"
+  exit 1
+end
+
+def do_http_request(method, base, path, body:, extra_headers:)
+  uri  = URI.parse("#{base}#{path}")
+  http = Net::HTTP.new(uri.host, uri.port)
+  http.use_ssl      = uri.scheme == "https"
+  http.open_timeout = OPEN_TIMEOUT
+  http.read_timeout = READ_TIMEOUT
+
+  req_class = { "POST" => Net::HTTP::Post, "PATCH" => Net::HTTP::Patch,
+                "DELETE" => Net::HTTP::Delete }[method]
+  req = req_class.new(uri.path)
+  hmac_headers.each { |k, v| req[k] = v }
+  extra_headers.each { |k, v| req[k] = v }
+  req.body = body.to_json if body
+
+  response = http.request(req)
+  parsed   = JSON.parse(response.body) rescue { "raw" => response.body }
+  [response.code.to_i, parsed]
+rescue Net::OpenTimeout, Net::ReadTimeout,
+       Errno::ECONNREFUSED, Errno::EHOSTUNREACH, Errno::ENETUNREACH,
+       Errno::ECONNRESET, EOFError, OpenSSL::SSL::SSLError => e
+  raise RetryableError, e.message
+end
+
+# Sentinel for transient network errors that should trigger retry/failover.
+class RetryableError < StandardError; end
+
+# ── Token storage ─────────────────────────────────────────────────────────────
+
+def load_token_data
+  return {} unless File.exist?(TOKEN_FILE)
+  JSON.parse(File.read(TOKEN_FILE)) rescue {}
+end
+
+def save_token_data(data)
+  FileUtils.mkdir_p(File.dirname(TOKEN_FILE))
+  File.write(TOKEN_FILE, JSON.pretty_generate(data))
+  File.chmod(0600, TOKEN_FILE)
+end
+
+# ── Commands ──────────────────────────────────────────────────────────────────
+
+def cmd_publish(name:, html_file:)
+  unless File.exist?(html_file)
+    warn "❌ HTML file not found: #{html_file}"
+    exit 1
+  end
+
+  html_content = File.read(html_file, encoding: "utf-8")
+
+  if html_content.bytesize > 1_048_576
+    warn "❌ HTML file exceeds 1MB (#{html_content.bytesize / 1024}KB)"
+    exit 1
+  end
+
+  token_data = load_token_data
+
+  # If we already have a slug + token, do an update (PATCH) instead of create
+  if token_data["slug"] && token_data["update_token"]
+    slug  = token_data["slug"]
+    token = token_data["update_token"]
+
+    status, body = http_request("PATCH", "/api/v1/personal_websites/#{slug}",
+                                body: { html_content: html_content },
+                                extra_headers: { "X-Card-Token" => token })
+
+    if status == 200
+      puts "✅ Website updated: #{body["url"]}"
+    else
+      warn "❌ Update failed (#{status}): #{body["error"] || body.inspect}"
+      exit 1
+    end
+  else
+    # First publish — POST to create
+    status, body = http_request("POST", "/api/v1/personal_websites",
+                                body: { name: name, html_content: html_content })
+
+    if status == 201
+      save_token_data("slug" => body["slug"], "update_token" => body["update_token"])
+      puts "✅ Website published: #{body["url"]}"
+      puts "   Slug: #{body["slug"]}"
+      puts "   Token saved to: #{TOKEN_FILE}"
+    else
+      warn "❌ Publish failed (#{status}): #{body["error"] || body.inspect}"
+      exit 1
+    end
+  end
+end
+
+def cmd_delete(slug: nil)
+  token_data = load_token_data
+  token = token_data["update_token"]
+  slug  = slug || token_data["slug"]
+
+  unless token && slug
+    warn "❌ No published website found (#{TOKEN_FILE} missing or incomplete)."
+    warn "   Nothing to delete."
+    exit 1
+  end
+
+  status, body = http_request("DELETE", "/api/v1/personal_websites/#{slug}",
+                              extra_headers: { "X-Card-Token" => token })
+
+  if status == 200
+    File.delete(TOKEN_FILE) if File.exist?(TOKEN_FILE)
+    puts "✅ Personal website deleted: /~#{slug}"
+  else
+    warn "❌ Delete failed (#{status}): #{body["error"] || body.inspect}"
+    exit 1
+  end
+end
+
+# ── CLI parsing ───────────────────────────────────────────────────────────────
+
+command = ARGV.shift
+
+case command
+when "publish"
+  options = {}
+  OptionParser.new do |opts|
+    opts.on("--name NAME")          { |v| options[:name]      = v }
+    opts.on("--html-file FILE")     { |v| options[:html_file] = v }
+  end.parse!
+
+  unless options[:name] && options[:html_file]
+    warn "Usage: ruby publish.rb publish --name NAME --html-file FILE"
+    exit 1
+  end
+
+  cmd_publish(name: options[:name], html_file: File.expand_path(options[:html_file]))
+
+when "delete"
+  options = {}
+  OptionParser.new do |opts|
+    opts.on("--slug SLUG") { |v| options[:slug] = v }  # optional, auto-read from token file
+  end.parse!
+
+  cmd_delete(slug: options[:slug])
+
+else
+  warn "Usage: ruby publish.rb publish|delete [options]"
+  warn "  publish --name NAME --html-file FILE"
+  warn "  delete  --slug SLUG"
+  exit 1
+end

data/lib/octo/default_skills/product-help/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: product-help
+description: 'Use this skill when the user asks about my own features, configuration, or usage — installation, skills, Web UI, CLI, API config, memory, sessions, troubleshooting, or restarting the server. Do NOT trigger for general coding tasks unrelated to me.'
+fork_agent: true
+user-invocable: false
+auto_summarize: true
+forbidden_tools:
+  - write
+  - edit
+  - web_search
+---
+
+# Product Help Subagent
+
+## My self-understanding
+
+I am an AI assistant powered by **Octo**.
+
+Octo is a Ruby tool for interacting with AI models. It speaks **Anthropic Messages**, **OpenAI** (Chat Completions + Responses), and **AWS Bedrock** natively, and works with any provider exposing one of those API shapes. Core capabilities include:
+
+- **Skills** — installable capability packs in Markdown format
+- **Web UI** — browser interface at `localhost:8888`
+- **Memory** — persistent long-term memory across sessions
+- **Sessions** — conversation history and context
+- **CLI** — command-line interface
+- **Config** — model and API key setup
+
+Answer the user's question using the built-in documentation below. Always read the doc first — never answer from memory alone.
+
+## Doc File Table
+
+All docs are bundled inside the gem at `lib/octo/default_skills/product-help/docs/`.
+
+| Topic | File |
+|-------|------|
+| What is Octo, product overview | `what-is-octo.md` |
+| Install on macOS / Linux, setup, install errors | `installation.md` |
+| Install on Windows | `windows-installation.md` |
+| What is a Skill, how to install / use a Skill | `how-to-use-a-skill.md` |
+| Common errors, troubleshooting, FAQ | `faq.md` |
+| Quickstart: create your first Skill | `create-your-first-skill.md` |
+| Skill structure, SKILL.md format, frontmatter options | `skill-basics.md` |
+| Skill writing best practices, prompt tips | `writing-tips.md` |
+| SKILL.md frontmatter fields reference | `skill-frontmatter.md` |
+| Built-in skills, default skills | `built-in-skills.md` |
+| Web UI, octo server, browser interface | `web-server.md` |
+| CLI commands, command line reference | `cli-reference.md` |
+| Model config, API key setup, provider selection | `agent-config.md` |
+| Project rules file, .octorules, custom instructions | `octorules.md` |
+| Memory system, long-term memory | `memory-system.md` |
+| Session management, conversation history | `session-management.md` |
+| Browser automation, browser tool, Chrome, Edge, CDP | `browser-tool.md` |
+| Advanced patterns, best practices | `best-practices.md` |
+
+## Workflow
+
+### Step 1 — Pick the file
+
+Look at the user's question and pick the **single most relevant file** from the table above.
+
+Match on intent, not just keywords. Examples:
+- "帮我打开webui" → `web-server.md`
+- "api key怎么配" → `agent-config.md`
+- "skill怎么写" → `skill-basics.md`
+- "怎么安装skill" → `how-to-use-a-skill.md`
+
+If genuinely unsure between two topics, pick both (max 2).
+
+### Step 2 — Resolve the doc path
+
+The docs are bundled inside the gem. First get the gem installation root:
+
+```
+terminal(command: "ruby -e \"require 'rubygems'; puts begin; Gem::Specification.find_by_name('octo').gem_dir; rescue Exception; Dir.pwd; end\"")
+```
+
+Then read the doc:
+
+```
+file_reader(path: "<gem-root>/lib/octo/default_skills/product-help/docs/<FILE>")
+```
+
+If the gem command fails (e.g. running from source), fall back to searching from the current working directory:
+
+```
+glob(pattern: "**/product-help/docs/<FILE>")
+```
+
+### Step 3 — Answer directly
+
+- Answer the question directly — don't say "the docs say…"
+- Match the user's language (Chinese question → Chinese answer)
+- Use numbered steps for sequences
+- Use code blocks for commands
+
+## Rules
+
+- Always read the doc first — never answer from memory
+- Only use files from the table above — do NOT search the web
+- If the doc doesn't answer the question, try the next most relevant file (max 2 reads)
+- If still no answer, tell the user: "请访问 https://github.com/Leihb/octo 查看更多信息"
+- Keep answers concise — extract what's relevant, don't paste the whole page
+
+## Server restart
+
+### Normal restart
+
+If the user asks to restart the server normally (e.g. "重启", "restart", "请重启octo") — without mentioning failure or errors:
+
+**Do NOT read any docs.** Just return this answer directly:
+
+> To restart the server gracefully (hot restart, zero downtime):
+> ```
+> kill -USR1 $OCTO_MASTER_PID
+> ```
+> This sends USR1 to the Master process, which spawns a new Worker and gracefully stops the old one.
+> The `$OCTO_MASTER_PID` environment variable is already set in the current session.
+
+### Restart failure, upgrade failure, or downgrade
+
+If the user mentions restart failure, upgrade failure, or how to downgrade (e.g. "重启失败", "升级失败", "降级", "restart failed", "upgrade failed", "downgrade", "如何降级"):
+
+→ Read `faq.md` — it has a dedicated Troubleshooting section covering all three scenarios.

data/lib/octo/default_skills/product-help/docs/agent-config.md

@@ -0,0 +1,74 @@
+# Model & API Key Configuration
+
+## Interactive Configuration
+
+During a session:
+
+```bash
+> /config
+```
+
+This opens an interactive prompt to set:
+
+- **API Key** — Your model provider key
+- **Model** — Model identifier (e.g., `anthropic/claude-opus-4-7`)
+- **Base URL** — Provider endpoint
+- **Anthropic Format** — Whether to use native Anthropic Messages format
+
+## Config File
+
+Configuration is stored in `~/.octo/config.yml`:
+
+```yaml
+models:
+  - model: anthropic/claude-opus-4-7
+    api_key: sk-xxx
+    base_url: https://api.anthropic.com
+    type: default
+    anthropic_format: true
+  - model: anthropic/claude-haiku-4-5
+    api_key: sk-xxx
+    base_url: https://api.anthropic.com
+    type: lite
+```
+
+## Environment Variables
+
+| Variable | Description |
+|---|---|
+| `OCTO_API_KEY` | Default model API key |
+| `OCTO_BASE_URL` | Default model base URL |
+| `OCTO_MODEL` | Default model name |
+| `OCTO_ANTHROPIC_FORMAT` | Use anthropic format |
+| `OCTO_LITE_API_KEY` | Lite model API key |
+| `OCTO_LITE_BASE_URL` | Lite model base URL |
+| `OCTO_LITE_MODEL` | Lite model name |
+
+ClaudeCode-compatible variables are also supported:
+
+| Variable | Description |
+|---|---|
+| `ANTHROPIC_API_KEY` | API key |
+| `ANTHROPIC_BASE_URL` | Base URL |
+
+## Model Types
+
+- **default** — Primary model for main agent work
+- **lite** — Cheaper/faster model for subagents and simple tasks
+- **fallback** — Used when the primary model is unavailable
+
+## Supported Providers
+
+Octo has built-in presets for:
+
+- **openrouter** — `https://openrouter.ai/api/v1`
+- **anthropic** — `https://api.anthropic.com`
+- **openai** — `https://api.openai.com`
+- **bedrock** — AWS Bedrock
+- **deepseek** — `https://api.deepseek.com`
+- **kimi** — `https://api.moonshot.cn`
+- **minimax** — `https://api.minimax.chat`
+- **qwen** — `https://dashscope.aliyuncs.com`
+- **glm** — `https://open.bigmodel.cn/api/paas/v4`
+
+Use any custom endpoint by specifying `base_url` directly.

data/lib/octo/default_skills/product-help/docs/best-practices.md

@@ -0,0 +1,49 @@
+# Advanced Patterns & Best Practices
+
+## Skill Composition
+
+Break complex workflows into smaller skills that call each other:
+
+- `setup-project` — Initialize repository structure
+- `add-auth` — Add authentication
+- `add-tests` — Add test suite
+
+## Context Management
+
+- Use `fork_agent: true` for tasks that need clean context
+- Use `auto_summarize: true` for long-running tasks
+- Use `forbidden_tools` to restrict what a skill can do
+
+## Testing Skills
+
+Before distributing a skill:
+
+1. Run it yourself in multiple scenarios
+2. Check edge cases (empty input, invalid paths)
+3. Verify it handles errors gracefully
+
+## Versioning
+
+Version skills by directory name:
+
+```
+skills/
+  my-skill-v1/
+  my-skill-v2/
+```
+
+## Project-Specific Defaults
+
+Place a `.octorules` file in project root to give the agent context about your codebase conventions.
+
+## Performance
+
+- Lite models (`anthropic/claude-haiku-4-5`, etc.) are great for simple tasks
+- Use fallback models for reliability
+- Disable memory with `--no-memory` if you don't need persistence
+
+## Security
+
+- Never commit API keys to version control
+- Use `forbidden_tools` to restrict file/shell access for untrusted skills
+- Run with `--mode=confirm_all` when working with sensitive codebases

data/lib/octo/default_skills/product-help/docs/browser-tool.md

@@ -0,0 +1,53 @@
+# Browser Automation
+
+Octo can control a real browser (Chrome or Edge) for web automation tasks.
+
+## Setup
+
+Use the built-in `browser-setup` skill:
+
+```bash
+> /browser-setup
+```
+
+Or manually configure `~/.octo/browser.yml`:
+
+```yaml
+browser: chrome
+remote_debugging_port: 9222
+```
+
+## Requirements
+
+- **macOS**: Chrome or Edge installed
+- **Linux**: Chrome/Chromium installed
+- **Windows/WSL**: Chrome on Windows accessible via remote debugging
+
+## How It Works
+
+Octo connects to the browser via Chrome DevTools Protocol (CDP):
+
+1. Start browser with remote debugging enabled
+2. Octo connects to `localhost:9222`
+3. Agent can navigate, click, type, scroll, and extract page content
+
+## Supported Actions
+
+- Navigate to URLs
+- Click elements
+- Type text / fill forms
+- Scroll pages
+- Take screenshots
+- Evaluate JavaScript
+- Extract page content
+
+## WSL Setup
+
+For WSL users, the `browser-setup` skill guides you through connecting to Windows Chrome from WSL.
+
+## Troubleshooting
+
+If browser automation fails:
+1. Ensure Chrome/Edge is running with `--remote-debugging-port=9222`
+2. Check `~/.octo/browser.yml` configuration
+3. Run `/browser-setup` to reconfigure

data/lib/octo/default_skills/product-help/docs/built-in-skills.md

@@ -0,0 +1,43 @@
+# Built-in Skills
+
+Octo ships with the following default skills:
+
+| Skill | Description |
+|---|---|
+| **browser-setup** | Configure Chrome/Edge for browser automation |
+| **channel-manager** | Set up IM platform integrations (Feishu, WeCom, WeChat, Discord, Telegram) |
+| **code-explorer** | Explore and analyze project/code structure |
+| **cron-task-creator** | Create and manage scheduled automated tasks |
+| **onboard** | New user onboarding guide |
+| **persist-memory** | Save information to long-term memory |
+| **personal-website** | Generate and publish a personal homepage |
+| **product-help** | Help with Octo features, configuration, and usage |
+| **recall-memory** | Recall information from long-term memory |
+| **skill-add** | Install skills from zip URLs or local files |
+| **skill-creator** | Create, modify, and optimize skills |
+
+## Location
+
+Built-in skills are stored in:
+
+```
+lib/octo/default_skills/
+```
+
+## Customization
+
+You can override built-in skills by placing a skill with the same name in:
+
+- `.octo/skills/` (project-level)
+- `~/.octo/skills/` (user-level)
+
+User-level skills take precedence over built-in skills.
+
+## Removed Skills
+
+The following skills were previously built-in but removed due to being too opinionated:
+
+- **deploy** — Coupled to Railway + Rails
+- **new** — Assumed specific Rails scaffolding
+
+These can still be installed as custom skills via `/skill-add`.

data/lib/octo/default_skills/product-help/docs/cli-reference.md

@@ -0,0 +1,82 @@
+# CLI Reference
+
+## Commands
+
+### `octo agent` (default)
+
+Run an AI agent in interactive mode.
+
+```bash
+octo agent [OPTIONS]
+```
+
+**Options:**
+
+| Option | Description |
+|---|---|
+| `--mode=MODE` | Permission mode: `auto_approve`, `confirm_safes`, `confirm_all` (default: `confirm_safes`) |
+| `--theme=THEME` | UI theme: `hacker`, `minimal` (default: `hacker`) |
+| `-v, --verbose` | Show detailed output |
+| `--path=PATH` | Project directory path (default: current directory) |
+| `-c, --continue` | Continue most recent session |
+| `-l, --list` | List recent sessions |
+| `-a, --attach=N` | Attach to session by number or ID prefix |
+| `--json` | Output NDJSON to stdout |
+| `-m, --message=MSG` | Run non-interactively and exit |
+| `-f, --file=PATH` | Attach file(s) (use with `-m`) |
+| `--agent=PROFILE` | Agent profile: `coding`, `general` (default: `coding`) |
+| `--model=MODEL` | Override the model to use |
+
+**Examples:**
+
+```bash
+# Interactive mode
+octo
+
+# Auto-approve all tools
+octo --mode=auto_approve
+
+# Continue previous session
+octo -c
+
+# One-shot task
+octo -m "write a hello world script"
+
+# Attach files
+octo -m "review this code" -f src/main.rb
+```
+
+### `octo server`
+
+Start the Web UI server.
+
+```bash
+octo server [OPTIONS]
+```
+
+| Option | Description |
+|---|---|
+| `-b, --host=HOST` | Bind host (default: `127.0.0.1`) |
+| `-p, --port=N` | Listen port (default: `8888`) |
+| `--no-compression` | Disable message compression |
+| `--no-memory` | Disable automatic memory updates |
+| `--no-caching` | Disable prompt caching |
+| `--no-skill-evolution` | Disable automatic skill evolution |
+
+### `octo tree`
+
+Print a tree of all available commands.
+
+```bash
+octo tree
+```
+
+## Interactive Commands
+
+During an agent session, you can use:
+
+| Command | Description |
+|---|---|
+| `/config` | Open configuration editor |
+| `/` | List and invoke skills |
+| `exit` or `quit` | End the session |