cli-claw-kit 0.0.1

package/container/agent-runner/src/types.ts

@@ -0,0 +1,75 @@
+/**
+ * Shared types for cli-claw Agent Runner.
+ *
+ * These types are used across index.ts, stream-processor.ts, and mcp-tools.ts.
+ */
+
+// Streaming event types (canonical source: shared/stream-event.ts)
+export type { StreamEventType, StreamEvent } from './stream-event.types.js';
+import type { StreamEvent, StreamRuntimeIdentity } from './stream-event.types.js';
+
+export interface ContainerInput {
+  prompt: string;
+  sessionId?: string;
+  turnId?: string;
+  groupFolder: string;
+  chatJid: string;
+  agentType?: 'claude' | 'codex';
+  model?: string | null;
+  reasoningEffort?: string | null;
+  /** @deprecated Use isHome + isAdminHome instead. Kept for backward compatibility with older host processes. */
+  isMain?: boolean;
+  /** Whether this is the user's home container (admin or member). */
+  isHome?: boolean;
+  /** Whether this is the admin's home container (full privileges). */
+  isAdminHome?: boolean;
+  isScheduledTask?: boolean;
+  images?: Array<{ data: string; mimeType?: string }>;
+  agentId?: string;
+  agentName?: string;
+}
+
+export interface ContainerOutput {
+  status: 'success' | 'error' | 'stream' | 'closed';
+  result: string | null;
+  newSessionId?: string;
+  error?: string;
+  alreadyStreamedError?: boolean;
+  runtimeIdentity?: StreamRuntimeIdentity | null;
+  streamEvent?: StreamEvent;
+  turnId?: string;
+  sessionId?: string;
+  sdkMessageUuid?: string;
+  sourceKind?: 'sdk_final' | 'sdk_send_message' | 'interrupt_partial' | 'overflow_partial' | 'compact_partial' | 'legacy' | 'auto_continue';
+  finalizationReason?: 'completed' | 'interrupted' | 'error';
+}
+
+export interface SessionEntry {
+  sessionId: string;
+  fullPath: string;
+  summary: string;
+  firstPrompt: string;
+}
+
+export interface SessionsIndex {
+  entries: SessionEntry[];
+}
+
+export type ImageMediaType = 'image/jpeg' | 'image/png' | 'image/gif' | 'image/webp';
+
+export interface SDKUserMessage {
+  type: 'user';
+  message: {
+    role: 'user';
+    content:
+      | string
+      | Array<{ type: 'text'; text: string } | { type: 'image'; source: { type: 'base64'; media_type: ImageMediaType; data: string } }>;
+  };
+  parent_tool_use_id: null;
+  session_id: string;
+}
+
+export interface ParsedMessage {
+  role: 'user' | 'assistant';
+  content: string;
+}

package/container/agent-runner/src/utils.ts

@@ -0,0 +1,114 @@
+/**
+ * Utility functions for cli-claw Agent Runner.
+ *
+ * Pure utility functions with no side effects or state dependencies.
+ */
+
+/**
+ * Shorten a string to maxLen, appending "..." if truncated.
+ */
+export function shorten(input: string, maxLen = 180): string {
+  if (input.length <= maxLen) return input;
+  return `${input.slice(0, maxLen)}...`;
+}
+
+/**
+ * Recursively redact sensitive fields (tokens, passwords, API keys, etc.)
+ * from an object. Limits recursion depth to 3 levels.
+ */
+export function redactSensitive(input: unknown, depth = 0): unknown {
+  if (depth > 3) return '[truncated]';
+  if (input == null) return input;
+  if (typeof input === 'string' || typeof input === 'number' || typeof input === 'boolean') {
+    return input;
+  }
+  if (Array.isArray(input)) {
+    return input.slice(0, 10).map((item) => redactSensitive(item, depth + 1));
+  }
+  if (typeof input === 'object') {
+    const obj = input as Record<string, unknown>;
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(obj)) {
+      if (/(token|password|secret|api[_-]?key|authorization|cookie)/iu.test(k)) {
+        out[k] = '[REDACTED]';
+      } else {
+        out[k] = redactSensitive(v, depth + 1);
+      }
+    }
+    return out;
+  }
+  return '[unsupported]';
+}
+
+/**
+ * Summarize tool input for display in stream events.
+ * Extracts key fields (command, query, path, etc.) or serializes the object.
+ */
+export function summarizeToolInput(input: unknown): string | undefined {
+  if (input == null) return undefined;
+
+  if (typeof input === 'string') {
+    return shorten(input.trim());
+  }
+
+  if (typeof input === 'object') {
+    const obj = input as Record<string, unknown>;
+    const keyCandidates = ['command', 'query', 'path', 'pattern', 'prompt', 'url', 'name'];
+    for (const key of keyCandidates) {
+      const value = obj[key];
+      if (typeof value === 'string' && value.trim()) {
+        return `${key}: ${shorten(value.trim())}`;
+      }
+    }
+    try {
+      const json = JSON.stringify(redactSensitive(obj));
+      // Skip empty or trivial objects (e.g. {} at content_block_start)
+      if (!json || json === '{}' || json === '[]') return undefined;
+      return shorten(json);
+    } catch {
+      return undefined;
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * Extract a skill name from Skill tool input.
+ * Tries skillName, skill, name, command fields, then regex-matches leading slashes.
+ */
+export function extractSkillName(toolName: unknown, input: unknown): string | undefined {
+  if (toolName !== 'Skill') return undefined;
+  if (!input || typeof input !== 'object') return undefined;
+  const obj = input as Record<string, unknown>;
+  const raw =
+    (typeof obj.skillName === 'string' && obj.skillName) ||
+    (typeof obj.skill === 'string' && obj.skill) ||
+    (typeof obj.name === 'string' && obj.name) ||
+    (typeof obj.command === 'string' && obj.command) ||
+    '';
+  if (!raw) return undefined;
+  const matched = raw.match(/\/([A-Za-z0-9._-]+)/);
+  if (matched && matched[1]) return matched[1];
+  return raw.replace(/^\/+/, '').trim() || undefined;
+}
+
+/**
+ * Sanitize a string for use as a filename.
+ * Lowercases, replaces non-alphanumeric characters with hyphens, trims, and limits length.
+ */
+export function sanitizeFilename(summary: string): string {
+  return summary
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}]+/gu, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 50);
+}
+
+/**
+ * Generate a fallback conversation archive filename based on current time.
+ */
+export function generateFallbackName(): string {
+  const time = new Date();
+  return `conversation-${time.getHours().toString().padStart(2, '0')}${time.getMinutes().toString().padStart(2, '0')}`;
+}

package/container/agent-runner/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022"],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "incremental": true,
+    "tsBuildInfoFile": "./dist/.tsbuildinfo"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/container/build.sh

@@ -0,0 +1,28 @@
+#!/bin/bash
+# Build the cli-claw agent container image
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+IMAGE_NAME="cli-claw-agent"
+TAG="${1:-latest}"
+
+echo "Building cli-claw agent container image..."
+echo "Image: ${IMAGE_NAME}:${TAG}"
+
+# Build with Docker (CACHEBUST ensures claude-code is always latest)
+# --progress=plain ensures clean line-based output for piped log capture (WebSocket streaming)
+docker build --progress=plain --build-arg CACHEBUST="$(date +%s)" -f "$SCRIPT_DIR/Dockerfile" -t "${IMAGE_NAME}:${TAG}" "$ROOT_DIR"
+
+echo ""
+echo "Build complete!"
+echo "Image: ${IMAGE_NAME}:${TAG}"
+
+# Touch sentinel so Makefile can detect stale image
+touch "$ROOT_DIR/.docker-build-sentinel"
+
+echo ""
+echo "Test with:"
+echo "  printf '%s' '{\"prompt\":\"What is 2+2?\",\"groupFolder\":\"test\",\"chatJid\":\"test@g.us\",\"isMain\":false}' | docker run -i ${IMAGE_NAME}:${TAG}"

package/container/entrypoint.sh

@@ -0,0 +1,64 @@
+#!/bin/bash
+set -e
+
+# Set permissive umask so files created by the container (node user, uid 1000)
+# are writable by the host backend (agent user, uid 1002).
+# Without this, the host cannot delete/modify files created by the container.
+umask 0000
+
+# Fix ownership on mounted volumes.
+# Host uid may differ from container node user (uid 1000), especially in
+# rootless podman where uid remapping causes EACCES on bind mounts.
+# Running as root here so chown works regardless of host uid.
+chown -R node:node /home/node/.claude 2>/dev/null || true
+chown -R node:node /workspace/group /workspace/global /workspace/memory /workspace/ipc 2>/dev/null || true
+
+# Source environment variables from mounted env file
+if [ -f /workspace/env-dir/env ]; then
+  set -a
+  source /workspace/env-dir/env
+  set +a
+fi
+
+# Discover and link skills (builtin → project → user, higher priority overwrites)
+# Only remove entries that conflict with mounted skills (non-symlink with same name),
+# preserving any skills the agent created directly in .claude/skills/.
+mkdir -p /home/node/.claude/skills
+for dir in /opt/builtin-skills /workspace/project-skills /workspace/user-skills; do
+  if [ -d "$dir" ]; then
+    for skill in "$dir"/*/; do
+      if [ -d "$skill" ]; then
+        name=$(basename "$skill")
+        target="/home/node/.claude/skills/$name"
+        # Remove conflicting non-symlink entry (e.g. real directory from a failed agent edit)
+        if [ -e "$target" ] && [ ! -L "$target" ]; then
+          rm -rf "$target" 2>/dev/null || true
+        fi
+        ln -sfn "$skill" "$target" 2>/dev/null || true
+      fi
+    done
+  fi
+done
+chown -R node:node /home/node/.claude/skills 2>/dev/null || true
+
+# Compile TypeScript (agent-runner source may be hot-mounted from host)
+cd /app && npx tsc --outDir /tmp/dist 2>&1 >&2
+ln -s /app/node_modules /tmp/dist/node_modules
+ln -s /app/prompts /tmp/prompts
+chmod -R a-w /tmp/dist
+
+# Buffer stdin to file (container requires EOF to flush stdin pipe)
+cat > /tmp/input.json
+chmod 644 /tmp/input.json
+
+# Fix permissions on exit: Claude Code creates some files with mode 0600
+# (e.g. settings.json), which the host backend (agent user) cannot read.
+# The trap runs as root after the node process exits.
+cleanup() {
+  chmod -R a+rwX /home/node/.claude 2>/dev/null || true
+  chmod -R a+rwX /workspace/group 2>/dev/null || true
+}
+trap cleanup EXIT
+
+# Drop privileges and execute agent-runner as node user
+runuser -u node -- node /tmp/dist/index.js < /tmp/input.json

package/container/skills/agent-browser/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: agent-browser
+description: Browse the web for any task — research topics, read articles, interact with web apps, fill forms, take screenshots, extract data, and test web pages. Use whenever a browser would be useful, not just when the user explicitly asks.
+allowed-tools: Bash(agent-browser:*)
+---
+
+# Browser Automation with agent-browser
+
+## Quick start
+
+```bash
+agent-browser open <url>        # Navigate to page
+agent-browser snapshot -i       # Get interactive elements with refs
+agent-browser click @e1         # Click element by ref
+agent-browser fill @e2 "text"   # Fill input by ref
+agent-browser close             # Close browser
+```
+
+## Core workflow
+
+1. Navigate: `agent-browser open <url>`
+2. Snapshot: `agent-browser snapshot -i` (returns elements with refs like `@e1`, `@e2`)
+3. Interact using refs from the snapshot
+4. Re-snapshot after navigation or significant DOM changes
+
+## Commands
+
+### Navigation
+
+```bash
+agent-browser open <url>      # Navigate to URL
+agent-browser back            # Go back
+agent-browser forward         # Go forward
+agent-browser reload          # Reload page
+agent-browser close           # Close browser
+```
+
+### Snapshot (page analysis)
+
+```bash
+agent-browser snapshot            # Full accessibility tree
+agent-browser snapshot -i         # Interactive elements only (recommended)
+agent-browser snapshot -c         # Compact output
+agent-browser snapshot -d 3       # Limit depth to 3
+agent-browser snapshot -s "#main" # Scope to CSS selector
+```
+
+### Interactions (use @refs from snapshot)
+
+```bash
+agent-browser click @e1           # Click
+agent-browser dblclick @e1        # Double-click
+agent-browser fill @e2 "text"     # Clear and type
+agent-browser type @e2 "text"     # Type without clearing
+agent-browser press Enter         # Press key
+agent-browser hover @e1           # Hover
+agent-browser check @e1           # Check checkbox
+agent-browser uncheck @e1         # Uncheck checkbox
+agent-browser select @e1 "value"  # Select dropdown option
+agent-browser scroll down 500     # Scroll page
+agent-browser upload @e1 file.pdf # Upload files
+```
+
+### Get information
+
+```bash
+agent-browser get text @e1        # Get element text
+agent-browser get html @e1        # Get innerHTML
+agent-browser get value @e1       # Get input value
+agent-browser get attr @e1 href   # Get attribute
+agent-browser get title           # Get page title
+agent-browser get url             # Get current URL
+agent-browser get count ".item"   # Count matching elements
+```
+
+### Screenshots & PDF
+
+```bash
+agent-browser screenshot          # Save to temp directory
+agent-browser screenshot path.png # Save to specific path
+agent-browser screenshot --full   # Full page
+agent-browser pdf output.pdf      # Save as PDF
+```
+
+### Wait
+
+```bash
+agent-browser wait @e1                     # Wait for element
+agent-browser wait 2000                    # Wait milliseconds
+agent-browser wait --text "Success"        # Wait for text
+agent-browser wait --url "**/dashboard"    # Wait for URL pattern
+agent-browser wait --load networkidle      # Wait for network idle
+```
+
+### Semantic locators (alternative to refs)
+
+```bash
+agent-browser find role button click --name "Submit"
+agent-browser find text "Sign In" click
+agent-browser find label "Email" fill "user@test.com"
+agent-browser find placeholder "Search" type "query"
+```
+
+### Authentication with saved state
+
+```bash
+# Login once
+agent-browser open https://app.example.com/login
+agent-browser snapshot -i
+agent-browser fill @e1 "username"
+agent-browser fill @e2 "password"
+agent-browser click @e3
+agent-browser wait --url "**/dashboard"
+agent-browser state save auth.json
+
+# Later: load saved state
+agent-browser state load auth.json
+agent-browser open https://app.example.com/dashboard
+```
+
+### Cookies & Storage
+
+```bash
+agent-browser cookies                     # Get all cookies
+agent-browser cookies set name value      # Set cookie
+agent-browser cookies clear               # Clear cookies
+agent-browser storage local               # Get localStorage
+agent-browser storage local set k v       # Set value
+```
+
+### JavaScript
+
+```bash
+agent-browser eval "document.title"   # Run JavaScript
+```
+
+## Example: Form submission
+
+```bash
+agent-browser open https://example.com/form
+agent-browser snapshot -i
+# Output shows: textbox "Email" [ref=e1], textbox "Password" [ref=e2], button "Submit" [ref=e3]
+
+agent-browser fill @e1 "user@example.com"
+agent-browser fill @e2 "password123"
+agent-browser click @e3
+agent-browser wait --load networkidle
+agent-browser snapshot -i  # Check result
+```
+
+## Example: Data extraction
+
+```bash
+agent-browser open https://example.com/products
+agent-browser snapshot -i
+agent-browser get text @e1  # Get product title
+agent-browser get attr @e2 href  # Get link URL
+agent-browser screenshot products.png
+```

package/container/skills/install-skill/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: install-skill
+description: >
+  When a user requests to install a new skill, this skill guides you to identify
+  the package name from various input formats and use the install_skill MCP tool.
+  Supports skills.sh URLs, GitHub URLs, owner/repo, and owner/repo@skill formats.
+user-invocable: false
+---
+
+# Skill Installation Guide
+
+When a user asks to install a skill (e.g., sends a link, mentions a skill name, or says "install xxx skill"), follow this process:
+
+## 1. Identify the Package Name
+
+Parse the user's input to extract the `owner/repo` or `owner/repo@skill` format:
+
+| Input Format | Example | Extract As |
+|---|---|---|
+| skills.sh URL | `https://skills.sh/s/owner/repo` | `owner/repo` |
+| skills.sh skill URL | `https://skills.sh/s/owner/repo/skill-name` | `owner/repo@skill-name` |
+| GitHub URL | `https://github.com/owner/repo` | `owner/repo` |
+| GitHub tree URL | `https://github.com/owner/repo/tree/main/skills/name` | `owner/repo@name` |
+| Direct package | `owner/repo` | `owner/repo` |
+| Package with skill | `owner/repo@skill` | `owner/repo@skill` |
+
+## 2. Install the Skill
+
+Call the `install_skill` MCP tool with the extracted package name:
+
+```
+install_skill({ "package": "owner/repo" })
+```
+
+Or with a specific skill from the repo:
+
+```
+install_skill({ "package": "owner/repo@skill-name" })
+```
+
+## 3. Handle Results
+
+**On success:**
+- Tell the user which skill(s) were installed (use the `installed` array from the response)
+- Briefly describe what the skill does (if you know from context)
+- Mention they can manage it in the Skills page
+
+**On failure:**
+- Check if the package name format is correct
+- Suggest the user verify the URL or package name
+- Common issues:
+  - Package not found: double-check the owner/repo spelling
+  - Network error: ask user to retry
+  - Invalid format: must be `owner/repo` or `owner/repo@skill`
+
+## 4. Uninstalling
+
+If the user wants to uninstall a skill, use the `uninstall_skill` MCP tool:
+
+```
+uninstall_skill({ "skill_id": "skill-name" })
+```
+
+The `skill_id` is the directory name of the installed skill.

package/container/skills/post-test-cleanup/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: post-test-cleanup
+description: 测试完成后的扫尾清理流程。在向某个工作区发送测试指令（如长篇文章生成、耗时任务）后，用此流程彻底清除测试痕迹，防止测试消息残留在会话上下文中持续消耗 token 额度。
+---
+
+# 测试后扫尾清理流程
+
+## 何时使用
+
+- 向某个工作区发送了耗时测试指令（如"写一篇5000字综述"）后
+- 测试完成或中断后，需要清除测试痕迹
+- 发现某工作区残留测试消息影响 AI 上下文时
+
+## 完整清理步骤
+
+### 第一步：停止残留容器
+
+```bash
+# 查看当前运行的容器
+docker ps --format "table {{.Names}}\t{{.Status}}\t{{.RunningFor}}"
+
+# 确认目标容器的 folder（容器名格式：cli-claw-{folder}-{timestamp}）
+ls ~/.cli-claw/ipc/
+
+# 发送中断信号（优雅停止）
+touch ~/.cli-claw/ipc/{folder}/input/_interrupt
+sleep 5
+
+# 若容器仍在运行，发送关闭信号
+touch ~/.cli-claw/ipc/{folder}/input/_close
+sleep 10
+
+# 确认容器已停止
+docker ps --format "{{.Names}}" | grep {folder关键字}
+```
+
+### 第二步：查找测试消息
+
+```python3
+python3 -c "
+import os, sqlite3
+conn = sqlite3.connect(os.path.expanduser('~/.cli-claw/db/messages.db'))
+cur = conn.cursor()
+
+# 先找到 folder 对应的 JID
+cur.execute(\"SELECT jid, folder, name FROM registered_groups WHERE folder = '{folder}'\")
+print('Group:', cur.fetchall())
+
+# 查看最近消息，定位测试消息范围
+cur.execute(\"\"\"
+    SELECT id, content, is_from_me, timestamp
+    FROM messages
+    WHERE chat_jid = '{jid}'
+    ORDER BY timestamp DESC LIMIT 20
+\"\"\")
+for r in cur.fetchall():
+    print(f'id={r[0]} from_me={r[2]} | {str(r[1])[:80]}')
+conn.close()
+"
+```
+
+### 第三步：删除测试消息
+
+```python3
+python3 -c "
+import os, sqlite3
+conn = sqlite3.connect(os.path.expanduser('~/.cli-claw/db/messages.db'))
+cur = conn.cursor()
+
+# 将需要删除的消息 ID 填入列表
+test_ids = [
+    'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
+    # ...
+]
+
+placeholders = ','.join(['?' for _ in test_ids])
+cur.execute(f'DELETE FROM messages WHERE id IN ({placeholders})', test_ids)
+print(f'Deleted {cur.rowcount} messages')
+conn.commit()
+conn.close()
+"
+```
+
+### 第四步：重置 Claude 会话（关键：清除 token 上下文）
+
+```python3
+python3 -c "
+import os, sqlite3, uuid
+conn = sqlite3.connect(os.path.expanduser('~/.cli-claw/db/messages.db'))
+cur = conn.cursor()
+
+# 生成新 session ID，下次启动时以空上下文开始
+new_id = str(uuid.uuid4())
+cur.execute(\"UPDATE sessions SET session_id = ? WHERE group_folder = '{folder}'\", (new_id,))
+print(f'Session reset: {cur.rowcount} rows, new ID: {new_id}')
+conn.commit()
+conn.close()
+"
+```
+
+### 第五步：确认代码无意外修改
+
+```bash
+git status
+git diff --stat
+# 应显示 "nothing to commit, working tree clean"
+```
+
+## 注意事项
+
+- **必须重置 session**：仅删除 DB 消息不够，Claude session 文件中仍保存着历史上下文，下次激活时依然消耗 token
+- **容器名与 folder 的对应关系**：容器名格式为 `cli-claw-{folder}-{timestamp}`，可通过 `ls ~/.cli-claw/ipc/` 查看所有 folder
+- **删除消息前仔细核对**：通过 `is_from_me` 和内容确认，避免误删正常业务消息
+- **全局运行时目录的修改不影响 git**：SQLite 和 IPC 文件均在 `~/.cli-claw/` 下，不纳入版本控制
+
+## 快速检查清单
+
+- [ ] 无残留测试容器在运行（`docker ps`）
+- [ ] 测试消息已从 DB 删除
+- [ ] Claude session ID 已重置为新 UUID
+- [ ] `git status` 显示工作区干净