crewly 1.20.131 → 1.20.133

package/config/constants.ts

@@ -1243,6 +1243,55 @@ export const REDIS_CONSTANTS = {
 	},
 } as const;
 
+/**
+ * Device-code pairing with Crewly Cloud (crewly-auth `/api/cloud/device/*`).
+ *
+ * A machine signs in to the owner's Cloud account without anyone at it: it
+ * shows a short code + link (`crewlyai.com/cloud/pair?code=ABCD-2345`), the
+ * owner approves on their phone, and the machine polls until it receives its
+ * token pair. Shared by `crewly cloud login` (CLI) and the backend's
+ * background pairing used by `/setup` and Settings → Cloud.
+ */
+export const CLOUD_DEVICE_PAIRING_CONSTANTS = {
+	/** crewly-auth endpoints (relative to the Cloud API URL) */
+	CLOUD_ENDPOINTS: {
+		START: '/api/cloud/device/start',
+		POLL: '/api/cloud/device/poll',
+		REDEEM: '/api/cloud/device/redeem',
+	},
+	/** Local backend endpoints (owner-only; mounted under /api/cloud) */
+	LOCAL_ENDPOINTS: {
+		START: '/api/cloud/device/start',
+		STATUS: '/api/cloud/device/status',
+		CANCEL: '/api/cloud/device/cancel',
+	},
+	/** Poll outcomes reported by crewly-auth (RFC 8628 names where one exists) */
+	POLL_STATUS: {
+		PENDING: 'authorization_pending',
+		SLOW_DOWN: 'slow_down',
+		EXPIRED: 'expired',
+		DENIED: 'denied',
+		APPROVED: 'approved',
+	},
+	/** Poll interval when the Cloud does not say (seconds) */
+	DEFAULT_INTERVAL_S: 5,
+	/** Added to the interval on slow_down / rate limiting (seconds) */
+	SLOW_DOWN_INCREMENT_S: 5,
+	/** Longest interval the client will back off to (seconds) */
+	MAX_INTERVAL_S: 60,
+	/** Pairing lifetime when the Cloud does not say (seconds) */
+	DEFAULT_EXPIRES_IN_S: 900,
+	/** Timeout for one start / poll request (ms) */
+	REQUEST_TIMEOUT_MS: 15_000,
+	/** Consecutive network / server errors tolerated while polling */
+	MAX_CONSECUTIVE_POLL_ERRORS: 10,
+	/** `purpose` sent with a pairing (shown to the owner on the approve page) */
+	PURPOSES: {
+		CLI: 'cli',
+		SETUP: 'setup',
+	},
+} as const;
+
 /**
  * Type helpers for extracting literal types from constants
  */

package/config/index.ts

@@ -40,6 +40,7 @@ import {
   SERVER_CONSTANTS,
   API_SECURITY_CONSTANTS,
   EVENT_DEBOUNCE_MS,
+  CLOUD_DEVICE_PAIRING_CONSTANTS,
 
   // Type helpers
   type AgentStatus,
@@ -69,6 +70,7 @@ export {
   SERVER_CONSTANTS,
   API_SECURITY_CONSTANTS,
   EVENT_DEBOUNCE_MS,
+  CLOUD_DEVICE_PAIRING_CONSTANTS,
 
   // Type helpers
   type AgentStatus,

package/config/skills/agent/core/find-skill/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: Find Skill
+description: Find a skill that gives you a capability you lack (a file type you cannot read, a missing tool). Searches bundled Crewly skills, installed skills and the marketplace; says which are official, installed and ready. Run it BEFORE telling the user you cannot do something.
+version: 1.0.0
+category: automation
+skillType: claude-skill
+assignableRoles:
+  - "*"
+triggers:
+  - find skill
+  - missing capability
+  - cannot read this file
+  - not installed
+  - need a tool
+tags:
+  - skills
+  - marketplace
+  - install
+  - capability
+  - auto-install
+execution:
+  type: script
+  script:
+    file: execute.sh
+    interpreter: bash
+    timeoutMs: 60000
+---
+
+# Find Skill
+
+Before you tell the user "I can't do that" or "X is not installed", look for a
+skill that does it.
+
+```bash
+bash {{AGENT_SKILLS_PATH}}/core/find-skill/execute.sh --query "transcribe a voice message"
+bash {{AGENT_SKILLS_PATH}}/core/find-skill/execute.sh --query "read a pdf" --limit 3
+```
+
+## Output
+
+```json
+{"success":true,"query":"transcribe a voice message",
+ "next":"transcribe-audio is an official skill (bundled with Crewly) that is not ready yet. Tell the user in one line that you are installing it (about 6 min), then run install-skill --id transcribe-audio and continue when the completion message arrives.",
+ "candidates":[{"id":"transcribe-audio","official":true,"officialReason":"bundled with Crewly",
+   "installed":true,"ready":false,"setup":{"declared":true,"estimatedMinutes":6,"satisfied":false,"missing":["whisper-cli","whisper-model"]},
+   "executePath":"/…/transcribe-audio/execute.sh","source":"bundled"}]}
+```
+
+Follow `next`:
+
+- **ready** — use the skill now (`executePath`).
+- **official, not ready** — tell the user in one line that you are installing it
+  and roughly how long it takes, then `install-skill --id <id>`.
+- **third-party** (`official:false`) — ask the owner in chat first; install only
+  after they say yes (`install-skill --id <id> --approved-by-owner`).
+- **no candidates** — say plainly what you cannot do.
+
+Official = bundled with Crewly, or listed in the official registry by the Crewly Team.

package/config/skills/agent/core/find-skill/execute.sh

@@ -0,0 +1,67 @@
+#!/bin/bash
+# =============================================================================
+# find-skill — find a skill that gives you a capability you lack.
+#
+# Searches the skills bundled with Crewly, installed marketplace skills and
+# the marketplace registry by capability, name, tags and description.
+# Backed by GET /api/skill-setup/find.
+#
+# Usage:
+#   bash execute.sh --query "transcribe a voice message"
+#   bash execute.sh --query "read a pdf" --limit 3
+#   bash execute.sh '{"query":"…"}'
+#
+# Output: {success, query, candidates:[{id, name, official, officialReason,
+#   installed, ready, setup:{declared, estimatedMinutes, satisfied, missing},
+#   executePath, …}], registryAvailable, next}
+# `next` says what to do: use it, install it (official), or ask the owner.
+# =============================================================================
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "${SCRIPT_DIR}/../../_common/lib.sh"
+
+print_usage() {
+  cat <<'EOF_USAGE'
+Usage:
+  bash execute.sh --query "transcribe a voice message" [--limit 5]
+  bash execute.sh '{"query":"…","limit":5}'
+
+Options:
+  --query | -q   What you need, in plain words (required)
+  --limit        Maximum candidates (default 8)
+  --help  | -h   Show this help
+EOF_USAGE
+}
+
+INPUT_JSON=""; QUERY=""; LIMIT=""
+if [[ $# -gt 0 && ${1:0:1} == '{' ]]; then INPUT_JSON="$1"; shift || true; fi
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --query|-q) [ $# -ge 2 ] || error_exit "--query requires a value"; QUERY="$2"; shift 2 ;;
+    --limit)    [ $# -ge 2 ] || error_exit "--limit requires a value"; LIMIT="$2"; shift 2 ;;
+    --help|-h)  print_usage; exit 0 ;;
+    *) error_exit "Unknown option: $1" ;;
+  esac
+done
+if [ -n "$INPUT_JSON" ]; then
+  INPUT=$(read_json_input "$INPUT_JSON")
+  [ -z "$QUERY" ] && QUERY=$(printf '%s' "$INPUT" | jq -r '.query // empty')
+  [ -z "$LIMIT" ] && LIMIT=$(printf '%s' "$INPUT" | jq -r '.limit // empty')
+fi
+require_param "query (--query)" "$QUERY"
+[ -z "$LIMIT" ] || [[ "$LIMIT" =~ ^[0-9]+$ ]] || error_exit "--limit must be a number"
+
+ENDPOINT="/skill-setup/find?query=$(printf '%s' "$QUERY" | jq -sRr @uri)"
+[ -n "$LIMIT" ] && ENDPOINT="${ENDPOINT}&limit=${LIMIT}"
+
+ERR_FILE=$(mktemp); trap 'rm -f "$ERR_FILE"' EXIT
+RESPONSE=$(api_call GET "$ENDPOINT" 2>"$ERR_FILE") || {
+  ERR=$(tail -n 1 "$ERR_FILE")
+  printf '%s' "$ERR" | jq -c '{success: false, error: (.details.error // .error // "find failed")}' 2>/dev/null \
+    || jq -cn --arg e "$ERR" '{success: false, error: $e}'
+  exit 1
+}
+
+printf '%s' "$RESPONSE" | jq -c '.data | {success: true, query, next, registryAvailable,
+  candidates: [.candidates[] | {id, name, description: (.description | .[0:200]), official, officialReason,
+    installed, ready, setup, executePath, source}]}'

package/config/skills/agent/core/find-skill/execute.test.sh

@@ -0,0 +1,69 @@
+#!/bin/bash
+# Tests for find-skill — run with: bash execute.test.sh </dev/null
+# A python HTTP stub plays the backend; asserts the request and the output shape.
+set -u
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+EXEC="$HERE/execute.sh"
+PASS=0; FAIL=0
+check() {
+  local name="$1"; local got="$2"; local want="$3"
+  if [ "$got" = "$want" ]; then PASS=$((PASS+1)); else FAIL=$((FAIL+1)); echo "FAIL: $name"; echo "  want: $want"; echo "  got:  $got"; fi
+}
+
+PORT=18851
+STUB_LOG="$(mktemp)"; export STUB_LOG; export STUB_PORT="$PORT"
+python3 -u <<'PY' >/dev/null 2>&1 &
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from urllib.parse import urlparse, parse_qs
+import json, os
+LOG = os.environ['STUB_LOG']; PORT = int(os.environ['STUB_PORT'])
+class H(BaseHTTPRequestHandler):
+    def reply(self, code, body):
+        self.send_response(code); self.send_header('Content-Type', 'application/json'); self.end_headers()
+        self.wfile.write(json.dumps(body).encode())
+    def do_GET(self):
+        u = urlparse(self.path); q = parse_qs(u.query)
+        open(LOG, 'w').write(json.dumps({'path': u.path, 'query': q, 'agent': self.headers.get('X-Agent-Session')}))
+        if q.get('query', [''])[0] == 'boom':
+            return self.reply(500, {'success': False, 'error': 'registry exploded'})
+        self.reply(200, {'success': True, 'data': {'query': q['query'][0], 'registryAvailable': True,
+            'next': 'transcribe-audio is an official skill (bundled with Crewly) that is not ready yet. Tell the user…',
+            'candidates': [{'id': 'transcribe-audio', 'name': 'transcribe-audio', 'description': 'x' * 500, 'official': True,
+                'officialReason': 'bundled with Crewly', 'installed': True, 'ready': False, 'tags': ['audio'], 'triggers': [],
+                'setup': {'declared': True, 'estimatedMinutes': 6, 'satisfied': False, 'missing': ['whisper-cli']},
+                'executePath': '/pkg/transcribe-audio/execute.sh', 'source': 'bundled', 'score': 12}]}})
+    def log_message(self, *a, **k): pass
+HTTPServer(('127.0.0.1', PORT), H).serve_forever()
+PY
+STUB_PID=$!
+disown "$STUB_PID" 2>/dev/null || true
+trap 'kill "$STUB_PID" >/dev/null 2>&1; rm -f "$STUB_LOG"' EXIT
+for i in $(seq 1 30); do curl -s -o /dev/null -m 0.2 "http://127.0.0.1:${PORT}/" 2>/dev/null && break; sleep 0.1; done
+
+run() { CREWLY_SESSION_NAME=test-agent CREWLY_API_URL="http://127.0.0.1:${PORT}" bash "$EXEC" "$@" 2>/dev/null; }
+run_err() { CREWLY_SESSION_NAME=test-agent CREWLY_API_URL="http://127.0.0.1:${PORT}" bash "$EXEC" "$@" 2>&1 >/dev/null | jq -rs 'last.error' 2>/dev/null; }
+
+OUT=$(run --query "transcribe a voice message (m4a)" --limit 3)
+check "path" "$(jq -r .path "$STUB_LOG")" "/api/skill-setup/find"
+check "query encoded + sent" "$(jq -r '.query.query[0]' "$STUB_LOG")" "transcribe a voice message (m4a)"
+check "limit sent" "$(jq -r '.query.limit[0]' "$STUB_LOG")" "3"
+check "agent header" "$(jq -r .agent "$STUB_LOG")" "test-agent"
+check "success" "$(printf '%s' "$OUT" | jq -r .success)" "true"
+check "next passed through" "$(printf '%s' "$OUT" | jq -r '.next | startswith("transcribe-audio is an official skill")')" "true"
+check "candidate fields" "$(printf '%s' "$OUT" | jq -c '.candidates[0] | {id, official, ready, source, missing: .setup.missing}')" '{"id":"transcribe-audio","official":true,"ready":false,"source":"bundled","missing":["whisper-cli"]}'
+check "description trimmed" "$(printf '%s' "$OUT" | jq -r '.candidates[0].description | length')" "200"
+check "internal score dropped" "$(printf '%s' "$OUT" | jq -r '.candidates[0] | has("score")')" "false"
+
+run '{"query":"语音 转文字"}' >/dev/null
+check "json input" "$(jq -r '.query.query[0]' "$STUB_LOG")" "语音 转文字"
+
+OUT=$(run --query boom); RC=$?
+check "backend error: exit 1" "$RC" "1"
+check "backend error: message" "$(printf '%s' "$OUT" | jq -r .error)" "registry exploded"
+
+check "missing query" "$(run_err)" "Missing required parameter: query (--query)"
+check "bad limit" "$(run_err --query x --limit lots)" "--limit must be a number"
+check "unknown option" "$(run_err --install)" "Unknown option: --install"
+
+echo "=== Results: $PASS passed, $FAIL failed ==="
+[ "$FAIL" -eq 0 ]

package/config/skills/agent/core/generate-pdf/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: Generate PDF
-description: Convert a Markdown file to a styled PDF with full CJK (Chinese/Japanese/Korean) font support. Uses pandoc for Markdown→HTML and weasyprint for HTML→PDF rendering.
-version: 1.0.0
+description: Convert a Markdown (or HTML) file to a styled PDF with full CJK (Chinese/Japanese/Korean) font support. Thin wrapper over the pdf-tools skill — headless Chrome preferred, WeasyPrint fallback. For multi-part documents, merging or reading PDFs use pdf-tools directly.
+version: 2.0.0
 category: document
 skillType: claude-skill
 assignableRoles:
@@ -29,7 +29,7 @@ tags:
   - pdf
   - document
   - markdown
-  - pandoc
+  - chrome
   - weasyprint
   - cjk
 execution:
@@ -42,47 +42,42 @@ execution:
 
 # Generate PDF
 
-Convert a Markdown file to a professionally styled PDF with full CJK (Chinese/Japanese/Korean) font support.
+Convert a Markdown (or HTML) file to a professionally styled PDF with full CJK
+(Chinese/Japanese/Korean) font support.
+
+This skill is kept for compatibility; it calls **`pdf-tools`**
+(`{{AGENT_SKILLS_PATH}}/pdf-tools/execute.sh`), which also merges several parts
+into one PDF and reads PDFs. Prefer `pdf-tools` for anything beyond one file.
 
 ## Pipeline
 
-1. **Markdown → HTML**: Uses `pandoc` with `--standalone` and an inline CJK-compatible CSS header
-2. **HTML → PDF**: Uses `weasyprint` (NOT Chrome headless, which cannot render CJK characters)
+1. **Markdown → HTML** with a clean A4 stylesheet (CJK font stacks: PingFang /
+   Hiragino on macOS, Noto CJK on Linux). HTML input is printed as-is.
+2. **HTML → PDF** with headless Chrome/Chromium when installed, else WeasyPrint.
+   Chrome renders CJK correctly whenever CJK fonts are installed (macOS has them;
+   on Linux the pdf-tools setup installs `fonts-noto-cjk`).
 
 ## Parameters
 
 | Parameter | Required | Description |
 |-----------|----------|-------------|
-| `input` | Yes | Path to the input Markdown file |
-| `output` | No | Path for the output PDF file (defaults to input path with `.pdf` extension) |
-| `title` | No | Document title for the HTML metadata |
+| `input` | Yes | Path to the input Markdown (or HTML) file |
+| `output` | No | Path for the output PDF (defaults to the input path with `.pdf`) |
+| `title` | No | Document title |
+| `css` | No | Extra stylesheet appended to the default one |
+| `engine` | No | `auto` (default), `chrome`, `weasyprint` |
 
 ## Example
 
 ```bash
-bash config/skills/agent/core/generate-pdf/execute.sh '{"input":"/tmp/report.md","output":"/tmp/report.pdf","title":"My Report"}'
-```
-
-### Minimal usage (auto-generates output path)
-
-```bash
-bash config/skills/agent/core/generate-pdf/execute.sh '{"input":"/tmp/report.md"}'
+bash {{AGENT_SKILLS_PATH}}/core/generate-pdf/execute.sh '{"input":"/tmp/report.md","output":"/tmp/report.pdf","title":"My Report"}'
 ```
 
-This produces `/tmp/report.pdf`.
-
-## Important Notes
-
-- **Always use this skill** instead of manually running pandoc + Chrome headless
-- **Chrome headless cannot render Chinese/CJK characters** — they appear blank in the PDF
-- **weasyprint** properly embeds CJK fonts (PingFang SC, Hiragino Sans GB, STHeiti) on macOS
-- The skill auto-generates a CSS header with CJK font declarations if one doesn't exist
-- Output is a clean, styled PDF suitable for sharing via Slack or email
-
 ## Output
 
-JSON with the path to the generated PDF file:
-
 ```json
-{"success": true, "pdf": "/tmp/report.pdf", "size": 364024}
+{"success": true, "pdf": "/tmp/report.pdf", "size": 364024, "engine": "chrome"}
 ```
+
+If a dependency is missing the result carries `"needsSetup": true, "skill": "pdf-tools"`:
+tell the user you are setting up the PDF tools and run `install-skill --id pdf-tools`.

package/config/skills/agent/core/generate-pdf/execute.sh

@@ -1,88 +1,32 @@
 #!/bin/bash
-# Generate PDF from Markdown with CJK font support
-# Uses pandoc (md→html) + weasyprint (html→pdf)
+# =============================================================================
+# generate-pdf — Markdown (or HTML) → styled PDF with CJK support.
+#
+# Kept for compatibility: the work is done by the `pdf-tools` skill
+# (headless Chrome preferred, WeasyPrint fallback, CJK-ready stylesheet).
+# Input and output shapes are unchanged:
+#   bash execute.sh '{"input":"/tmp/report.md","output":"/tmp/report.pdf","title":"My Report"}'
+#   → {"success":true,"pdf":"/tmp/report.pdf","size":364024,"engine":"chrome"}
+# A missing dependency returns pdf-tools' `needsSetup` JSON
+# (run install-skill --id pdf-tools).
+# =============================================================================
 set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "${SCRIPT_DIR}/../../_common/lib.sh"
+PDF_TOOLS="${SCRIPT_DIR}/../../pdf-tools/execute.sh"
 
 INPUT=$(read_json_input "${1:-}")
 [ -z "$INPUT" ] && error_exit "Usage: execute.sh '{\"input\":\"/tmp/report.md\",\"output\":\"/tmp/report.pdf\",\"title\":\"My Report\"}'"
+[ -f "$PDF_TOOLS" ] || error_exit "pdf-tools skill not found at ${PDF_TOOLS}"
 
-MD_PATH=$(printf '%s' "$INPUT" | jq -r '.input // empty')
-PDF_PATH=$(printf '%s' "$INPUT" | jq -r '.output // empty')
-TITLE=$(printf '%s' "$INPUT" | jq -r '.title // empty')
+SRC=$(printf '%s' "$INPUT" | jq -r '.input // empty')
+require_param "input" "$SRC"
 
-require_param "input" "$MD_PATH"
+REQUEST=$(printf '%s' "$INPUT" | jq -c '{action: "render", input: .input}
+  + (if .output then {output: .output} else {} end)
+  + (if .title then {title: .title} else {} end)
+  + (if .css then {css: .css} else {} end)
+  + (if .engine then {engine: .engine} else {} end)')
 
-# Default output: same path with .pdf extension
-if [ -z "$PDF_PATH" ]; then
-  PDF_PATH="${MD_PATH%.md}.pdf"
-fi
-
-# Intermediate HTML path
-HTML_PATH="${PDF_PATH%.pdf}.html"
-
-# Default title from filename
-if [ -z "$TITLE" ]; then
-  TITLE=$(basename "$MD_PATH" .md | tr '-' ' ' | tr '_' ' ')
-fi
-
-# Ensure the CJK CSS header exists
-CJK_HEADER="/tmp/cjk-header.html"
-if [ ! -f "$CJK_HEADER" ]; then
-  cat > "$CJK_HEADER" << 'CSSEOF'
-<style>
-body {
-  font-family: -apple-system, BlinkMacSystemFont, "PingFang SC", "Hiragino Sans GB", "Noto Sans CJK SC", "Microsoft YaHei", "WenQuanYi Micro Hei", sans-serif;
-  max-width: 900px;
-  margin: 0 auto;
-  padding: 2rem;
-  line-height: 1.8;
-  color: #1a1a1a;
-  font-size: 14px;
-}
-h1, h2, h3, h4 {
-  font-family: -apple-system, "PingFang SC", "Hiragino Sans GB", sans-serif;
-  margin-top: 1.5em;
-  color: #111;
-}
-h1 { font-size: 1.8em; border-bottom: 2px solid #333; padding-bottom: 0.3em; }
-h2 { font-size: 1.4em; border-bottom: 1px solid #ccc; padding-bottom: 0.2em; }
-h3 { font-size: 1.15em; }
-table { border-collapse: collapse; width: 100%; margin: 1em 0; font-size: 13px; }
-th, td { border: 1px solid #ddd; padding: 8px 12px; text-align: left; }
-th { background: #f5f5f5; font-weight: 600; }
-tr:nth-child(even) { background: #fafafa; }
-blockquote { border-left: 4px solid #4a90d9; margin: 1em 0; padding: 0.5em 1em; background: #f0f6ff; color: #333; }
-code { background: #f4f4f4; padding: 2px 5px; border-radius: 3px; font-size: 0.9em; }
-hr { border: none; border-top: 1px solid #ddd; margin: 2em 0; }
-strong { color: #111; }
-</style>
-CSSEOF
-fi
-
-# Check dependencies
-if ! command -v pandoc &>/dev/null; then
-  error_exit "pandoc is not installed. Run: brew install pandoc"
-fi
-if ! command -v weasyprint &>/dev/null; then
-  error_exit "weasyprint is not installed. Run: brew install weasyprint"
-fi
-
-# Step 1: Markdown → HTML (with CJK CSS header)
-pandoc "$MD_PATH" -o "$HTML_PATH" \
-  --standalone \
-  --metadata title="$TITLE" \
-  --include-in-header="$CJK_HEADER" 2>/dev/null
-
-# Step 2: HTML → PDF (weasyprint handles CJK fonts correctly)
-weasyprint "$HTML_PATH" "$PDF_PATH" 2>/dev/null
-
-# Get file size
-PDF_SIZE=$(wc -c < "$PDF_PATH" | tr -d ' ')
-
-# Clean up intermediate HTML
-rm -f "$HTML_PATH"
-
-# Output result
-echo "{\"success\":true,\"pdf\":\"${PDF_PATH}\",\"size\":${PDF_SIZE}}"
+RESULT=$(bash "$PDF_TOOLS" "$REQUEST" </dev/null) || { printf '%s\n' "$RESULT"; exit 1; }
+printf '%s' "$RESULT" | jq -c '{success, pdf, size, engine}'

package/config/skills/agent/core/generate-pdf/execute.test.sh

@@ -0,0 +1,45 @@
+#!/bin/bash
+# Tests for generate-pdf (wrapper over pdf-tools) — run with: bash execute.test.sh </dev/null
+# Uses a fake Chrome and a stub python-markdown on an isolated PATH. Exit 0 on pass.
+set -u
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+EXEC="$HERE/execute.sh"
+PASS=0; FAIL=0
+check() {
+  local name="$1"; local got="$2"; local want="$3"
+  if [ "$got" = "$want" ]; then PASS=$((PASS+1)); else FAIL=$((FAIL+1)); echo "FAIL: $name"; echo "  want: $want"; echo "  got:  $got"; fi
+}
+JQ="$(command -v jq)"; BASH_BIN="${TEST_BASH:-$(command -v bash)}"
+T="$(mktemp -d)"; trap 'rm -rf "$T"' EXIT
+mkdir -p "$T/bin" "$T/stub/markdown"
+for tool in bash jq python3 mktemp cat rm tail head dirname mkdir sed tr wc sleep kill id awk grep basename cp uname date; do
+  src="$(command -v "$tool" 2>/dev/null)" && ln -sf "$src" "$T/bin/$tool"
+done
+printf '%%PDF-1.4\n%% fake\n%%%%EOF\n' > "$T/fixture.pdf"
+cat > "$T/chrome" <<EOT
+#!/bin/bash
+for a in "\$@"; do case "\$a" in --print-to-pdf=*) cp "$T/fixture.pdf" "\${a#--print-to-pdf=}" ;; esac; done
+EOT
+chmod 755 "$T/chrome"
+printf 'def markdown(text, **kw):\n    return "<p>" + text + "</p>"\n' > "$T/stub/markdown/__init__.py"
+printf '# 报告\n' > "$T/report.md"
+run() { env -i HOME="$T" PATH="$T/bin" CREWLY_HOME="$T/.crewly" PYTHONPATH="$T/stub" PDF_TOOLS_CHROME_PATHS="" "$@" "$BASH_BIN" "$EXEC" "$JSON" 2>/dev/null </dev/null; }
+
+JSON="{\"input\":\"$T/report.md\",\"title\":\"报告\"}"
+OUT=$(run CHROME_BIN="$T/chrome")
+check "same output shape" "$(printf '%s' "$OUT" | "$JQ" -c 'keys')" '["engine","pdf","size","success"]'
+check "success" "$(printf '%s' "$OUT" | "$JQ" -r .success)" "true"
+check "default output path" "$(printf '%s' "$OUT" | "$JQ" -r .pdf)" "$T/report.pdf"
+check "engine" "$(printf '%s' "$OUT" | "$JQ" -r .engine)" "chrome"
+
+JSON="{\"input\":\"$T/report.md\",\"output\":\"$T/x/out.pdf\"}"
+OUT=$(run); RC=$?
+check "no engine: exit 1" "$RC" "1"
+check "no engine: needsSetup from pdf-tools" "$(printf '%s' "$OUT" | "$JQ" -r '.needsSetup, .skill' | tr '\n' ' ')" "true pdf-tools "
+
+JSON='{"title":"x"}'
+ERR=$(env -i HOME="$T" PATH="$T/bin" "$BASH_BIN" "$EXEC" "$JSON" 2>&1 >/dev/null </dev/null)
+check "missing input" "$(printf '%s' "$ERR" | "$JQ" -rs 'last.error')" "Missing required parameter: input"
+
+echo "=== Results: $PASS passed, $FAIL failed ==="
+[ "$FAIL" -eq 0 ]

package/config/skills/agent/core/install-skill/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: Install Skill
+description: Install a skill (and the system tools, models and Python packages it declares) as a background job. Returns a job id at once; you get a [SKILL INSTALLED] / [SKILL INSTALL FAILED] message when it ends. Official skills install without asking; third-party ones need the owner's yes in chat first.
+version: 1.0.0
+category: automation
+skillType: claude-skill
+assignableRoles:
+  - "*"
+triggers:
+  - install skill
+  - set up skill
+  - needsSetup
+  - missing dependency
+tags:
+  - skills
+  - marketplace
+  - install
+  - setup
+  - auto-install
+execution:
+  type: script
+  script:
+    file: execute.sh
+    interpreter: bash
+    timeoutMs: 60000
+---
+
+# Install Skill
+
+Use after `find-skill`, or when a skill answered `"needsSetup": true, "skill": "<id>"`.
+
+```bash
+bash {{AGENT_SKILLS_PATH}}/core/install-skill/execute.sh --id transcribe-audio --resume "transcribe the voice message Steve sent in #general"
+```
+
+It returns immediately:
+
+```json
+{"success":true,"jobId":"3f9c1a2b","skillId":"transcribe-audio","state":"running","official":true,
+ "estimatedMinutes":6,"willNotify":["crewly-dev-1"],
+ "next":"Installing transcribe-audio in the background (about 6 min). Tell the user now…"}
+```
+
+or `{"success":true,"state":"already-ready","executePath":"…"}` — use the skill now.
+
+## The flow
+
+1. Tell the user in **one line** that you are installing it and roughly how long it
+   takes ("I can't read audio yet — installing the transcription skill, about 6 min.").
+2. Run `install-skill`. Pass `--resume` with what you were doing; it comes back to you.
+3. When `[SKILL INSTALLED] …` arrives, tell the user it's ready and **do the original
+   task right away**. On `[SKILL INSTALL FAILED] …`, tell the user plainly what is
+   missing and the fix the message gives (e.g. a command the owner must run).
+
+Never answer "X is not installed" and stop.
+
+## Trust
+
+- **Official** (bundled with Crewly, or published by the Crewly Team in the official
+  registry): installs without asking, including the system dependencies it declares.
+- **Third-party**: refused with `reason: owner_approval_required`. Ask the owner in chat
+  (say what it is and who publishes it). Only after they say yes:
+  `install-skill --id <id> --approved-by-owner --owner-said "<their words>"`.
+  The backend checks the owner's recent chat for that yes; claiming it without one fails
+  (`owner_approval_not_found`).
+
+Progress: `GET /api/skill-setup/jobs/<jobId>`. Setup log: `~/.crewly/logs/skill-setup/<id>.log`.