crewly 1.15.0 → 1.17.0

package/config/skills/agent/core/count-json/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: Count JSON
+description: Run a command that prints JSON and count the entries matching a field=value filter. Built for skill_output Key Results (e.g. "tickets in review") so a KR can be measured from any board or API that speaks JSON.
+version: 1.0.0
+category: measurement
+skillType: claude-skill
+assignableRoles:
+  - orchestrator
+  - team-leader
+  - developer
+  - devops
+  - operations
+  - ops
+triggers:
+  - count json
+  - measure kr
+tags:
+  - okr
+  - measurement
+  - json
+execution:
+  type: script
+  script:
+    file: execute.sh
+    interpreter: bash
+    timeoutMs: 60000
+---
+
+# Count JSON
+
+Runs a command, reads the JSON it prints (an array, or an object holding an
+array under `items` / `tickets` / `data`), applies an optional `field=value`
+filter, and prints `{"count": N, "total": M, "filter": "..."}`.
+
+Made for `measurementSource: "skill_output"` Key Results:
+
+```json
+{ "measurementConfig": { "skill": "count-json",
+                         "args": { "command": "cd /opt/app/web && make tickets TICKET_ARGS=--json",
+                                   "field": "status", "value": "review" },
+                         "jsonPath": ".count" } }
+```
+
+## Parameters
+
+| Name | Required | Meaning |
+|---|---|---|
+| `command` | yes | Shell command whose stdout is JSON (or a `file` path instead) |
+| `file` | no | Read JSON from this file instead of running a command |
+| `field` | no | Top-level field to filter on |
+| `value` | no | Value that `field` must equal (string compare) |
+| `arrayPath` | no | jq path to the array when it is nested (default: auto-detect) |
+
+## Output
+
+```json
+{"count": 6, "total": 21, "filter": "status=review"}
+```
+
+The command runs with a 50 s timeout; a non-JSON result exits 1 with an error
+object on stderr.

package/config/skills/agent/core/count-json/execute.sh

@@ -0,0 +1,52 @@
+#!/bin/bash
+# count-json — run a command (or read a file) that yields JSON, count entries
+# matching field=value. Output: {"count":N,"total":M,"filter":"field=value"}
+#
+# Usage: execute.sh '{"command":"...","field":"status","value":"review"}'
+#        execute.sh '{"file":"/tmp/board.json","field":"status","value":"open"}'
+set -uo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "${SCRIPT_DIR}/../../_common/lib.sh"
+
+INPUT="${1:-}"
+[ -z "$INPUT" ] && error_exit "Usage: execute.sh '{\"command\":\"...\",\"field\":\"status\",\"value\":\"review\"}'"
+
+COMMAND=$(printf '%s' "$INPUT" | jq -r '.command // empty')
+FILE=$(printf '%s' "$INPUT" | jq -r '.file // empty')
+FIELD=$(printf '%s' "$INPUT" | jq -r '.field // empty')
+VALUE=$(printf '%s' "$INPUT" | jq -r '.value // empty')
+ARRAY_PATH=$(printf '%s' "$INPUT" | jq -r '.arrayPath // empty')
+TIMEOUT_S="${COUNT_JSON_TIMEOUT_S:-50}"
+
+[ -z "$COMMAND" ] && [ -z "$FILE" ] && error_exit "command or file is required"
+
+if [ -n "$FILE" ]; then
+  [ -f "$FILE" ] || error_exit "file not found: $FILE"
+  RAW=$(cat "$FILE")
+else
+  if command -v timeout >/dev/null 2>&1; then
+    RAW=$(timeout "$TIMEOUT_S" bash -c "$COMMAND" 2>/dev/null)
+  else
+    RAW=$(bash -c "$COMMAND" 2>/dev/null)
+  fi
+  [ $? -ne 0 ] && [ -z "$RAW" ] && error_exit "command failed or produced no output"
+fi
+
+# Skip any non-JSON preamble (progress lines, banners).
+JSON=$(printf '%s' "$RAW" | awk 'found||/^[[{]/{found=1; print}')
+[ -z "$JSON" ] && error_exit "no JSON found in output"
+
+if [ -n "$ARRAY_PATH" ]; then
+  SELECT="$ARRAY_PATH"
+else
+  SELECT='if type=="array" then . elif (.items|type)=="array" then .items elif (.tickets|type)=="array" then .tickets elif (.data|type)=="array" then .data else [] end'
+fi
+
+if [ -n "$FIELD" ]; then
+  printf '%s' "$JSON" | jq -c --arg f "$FIELD" --arg v "$VALUE" \
+    "($SELECT) as \$arr | {count: (\$arr | map(select((.[\$f] // \"\" | tostring) == \$v)) | length), total: (\$arr | length), filter: (\$f + \"=\" + \$v)}" \
+    || error_exit "output is not valid JSON"
+else
+  printf '%s' "$JSON" | jq -c "($SELECT) as \$arr | {count: (\$arr | length), total: (\$arr | length), filter: \"\"}" \
+    || error_exit "output is not valid JSON"
+fi

package/config/skills/agent/core/count-json/execute.test.sh

@@ -0,0 +1,35 @@
+#!/bin/bash
+# Tests for count-json — run with: bash execute.test.sh
+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
+}
+run() { bash "$EXEC" "$1" 2>/dev/null; }
+run_err() { bash "$EXEC" "$1" 2>&1 >/dev/null | jq -r '.error' 2>/dev/null; }
+
+TMP=$(mktemp -d); trap 'rm -rf "$TMP"' EXIT
+printf '%s' '[{"ticketId":"T1","status":"open"},{"ticketId":"T2","status":"review"},{"ticketId":"T3","status":"review"},{"ticketId":"T4","status":"blocked"}]' > "$TMP/board.json"
+printf '%s' 'fetching...
+{"items":[{"s":"a"},{"s":"b"}]}' > "$TMP/nested.txt"
+
+ARGS=$(jq -cn --arg f "$TMP/board.json" '{file:$f, field:"status", value:"review"}')
+check "filter by field=value" "$(run "$ARGS")" '{"count":2,"total":4,"filter":"status=review"}'
+
+ARGS=$(jq -cn --arg f "$TMP/board.json" '{file:$f}')
+check "no filter counts all" "$(run "$ARGS")" '{"count":4,"total":4,"filter":""}'
+
+ARGS=$(jq -cn --arg c "cat $TMP/nested.txt" '{command:$c, field:"s", value:"b"}')
+check "command with preamble and nested items" "$(run "$ARGS")" '{"count":1,"total":2,"filter":"s=b"}'
+
+ARGS=$(jq -cn --arg f "$TMP/board.json" '{file:$f, arrayPath:".", field:"status", value:"open"}')
+check "explicit arrayPath" "$(run "$ARGS")" '{"count":1,"total":4,"filter":"status=open"}'
+
+check "non-JSON errors" "$(run_err '{"command":"echo not json"}')" "no JSON found in output"
+check "missing input errors" "$(run_err '{}')" "command or file is required"
+
+echo "=== Results: $PASS passed, $FAIL failed ==="
+[ "$FAIL" -eq 0 ]

package/config/skills/agent/core/gmail-read/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: Gmail Read
+description: Read one message from the owner's Gmail by id — headers, decoded body (plain text, HTML stripped as fallback) and a list of attachments (names only, nothing downloaded). Read-only.
+version: 1.0.0
+category: communication
+skillType: claude-skill
+assignableRoles:
+  - orchestrator
+  - team-leader
+  - developer
+  - operations
+  - ops
+  - sales
+  - support
+  - generalist
+triggers:
+  - read email
+  - open email
+  - show email
+tags:
+  - google
+  - gmail
+  - email
+execution:
+  type: script
+  script:
+    file: execute.sh
+    interpreter: bash
+    timeoutMs: 30000
+---
+
+# Gmail Read
+
+Fetches one message by the `id` a `gmail-search` hit returned.
+
+```bash
+bash execute.sh --id 18f0a1b2c3d4e5f6
+bash execute.sh '{"id":"18f0a1b2c3d4e5f6"}'
+```
+
+## Parameters
+
+| Name | Required | Meaning |
+|---|---|---|
+| `--id` / `-i` (`id`) | yes | Gmail message id |
+
+## Output
+
+```json
+{"id":"18f…","threadId":"18f…","from":"Ann <ann@example.com>","to":"owner@example.com","cc":"","subject":"Q3 numbers","date":"…","messageId":"<abc@mail.example.com>","body":"Hi —\n…","bodyType":"text","attachments":[{"filename":"deck.pdf","mimeType":"application/pdf","size":12345,"attachmentId":"ANGjd…"}]}
+```
+
+`bodyType` is `text` (text/plain part), `html` (stripped from text/html)
+or `none`. Attachments are listed, never downloaded. To reply in-thread,
+pass `threadId` and `messageId` to `gmail-send`.
+
+## Failures
+
+`{"success":false,"reason":"not_connected","hint":"<connect URL>"}` (exit 1)
+when the owner has not connected Google Workspace; `reason` `google_error`
+with a 404 message when the id is unknown.

package/config/skills/agent/core/gmail-read/execute.sh

@@ -0,0 +1,62 @@
+#!/bin/bash
+# =============================================================================
+# gmail-read — Read one message from the owner's Gmail (read-only)
+#
+# Backed by GET /api/google/gmail/messages/:id.
+#
+# Usage:
+#   bash execute.sh --id 18f0a1b2c3d4e5f6
+#   bash execute.sh '{"id":"18f0a1b2c3d4e5f6"}'
+# =============================================================================
+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 --id <gmail message id>
+  bash execute.sh '{"id":"<gmail message id>"}'
+
+Options:
+  --id   | -i   Gmail message id (required; from gmail-search)
+  --help | -h   Show this help
+EOF_USAGE
+}
+
+INPUT_JSON=""
+ID=""
+
+if [[ $# -gt 0 && ${1:0:1} == '{' ]]; then
+  INPUT_JSON="$1"
+  shift || true
+fi
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --id|-i)   [ $# -ge 2 ] || error_exit "--id requires a value"; ID="$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 "$ID" ] && ID=$(printf '%s' "$INPUT" | jq -r '.id // .messageId // empty')
+fi
+
+require_param "id (--id)" "$ID"
+
+ID_ENC=$(jq -rn --arg v "$ID" '$v|@uri')
+RESPONSE=$(api_call GET "/google/gmail/messages/${ID_ENC}" 2>&1) || {
+  printf '%s' "$RESPONSE" | jq -c '{success: false, reason: (.details.error // .details // .error // "unknown"), hint: (.details.hint // ""), message: (.details.message // "")}' 2>/dev/null \
+    || jq -n --arg r "$RESPONSE" '{success: false, reason: $r}'
+  exit 1
+}
+
+# Oversized bodies are parked on disk by api_call; pass that envelope through.
+if printf '%s' "$RESPONSE" | jq -e '.truncated == true' >/dev/null 2>&1; then
+  printf '%s\n' "$RESPONSE"; exit 0
+fi
+
+printf '%s' "$RESPONSE" | jq -c '.data | {id, threadId, from, to, cc, subject, date, messageId, body, bodyType, attachments}'

package/config/skills/agent/core/gmail-read/execute.test.sh

@@ -0,0 +1,68 @@
+#!/bin/bash
+# Tests for gmail-read — run with: bash execute.test.sh
+# Spins up a python HTTP stub as the backend, asserts the request path the
+# skill sends and the JSON it prints. 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
+}
+
+PORT=18802
+STUB_LOG="$(mktemp)"; export STUB_LOG; export STUB_PORT="$PORT"
+python3 -u <<'PY' >/dev/null 2>&1 &
+from http.server import BaseHTTPRequestHandler, HTTPServer
+import json, os
+LOG = os.environ['STUB_LOG']; PORT = int(os.environ['STUB_PORT'])
+MSG = {'id': 'm1', 'threadId': 't1', 'from': 'ann@example.com', 'to': 'owner@example.com', 'cc': '',
+       'subject': 'Q3', 'date': 'D', 'messageId': '<abc@x>', 'snippet': 's', 'body': 'Hi\nthere', 'bodyType': 'text',
+       'attachments': [{'filename': 'deck.pdf', 'mimeType': 'application/pdf', 'size': 12, 'attachmentId': 'A1'}],
+       'labelIds': ['INBOX']}
+class H(BaseHTTPRequestHandler):
+    def do_GET(self):
+        open(LOG, 'w').write(json.dumps({'method': 'GET', 'path': self.path}))
+        if self.path.endswith('/missing'):
+            self.send_response(404); self.send_header('Content-Type', 'application/json'); self.end_headers()
+            self.wfile.write(json.dumps({'success': False, 'error': 'google_error', 'message': 'Requested entity was not found.', 'hint': 'Google or Crewly Cloud failed; retry later.'}).encode()); return
+        if self.path.endswith('/no-grant'):
+            self.send_response(409); self.send_header('Content-Type', 'application/json'); self.end_headers()
+            self.wfile.write(json.dumps({'success': False, 'error': 'not_connected', 'message': 'no grant', 'hint': 'https://cloud/start?token=j'}).encode()); return
+        self.send_response(200); self.send_header('Content-Type', 'application/json'); self.end_headers()
+        self.wfile.write(json.dumps({'success': True, 'data': MSG}).encode())
+    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_API_URL="http://127.0.0.1:${PORT}" bash "$EXEC" "$@" 2>/dev/null; }
+run_err() { CREWLY_API_URL="http://127.0.0.1:${PORT}" bash "$EXEC" "$@" 2>&1 >/dev/null | jq -r '.error' 2>/dev/null; }
+
+WANT='{"id":"m1","threadId":"t1","from":"ann@example.com","to":"owner@example.com","cc":"","subject":"Q3","date":"D","messageId":"<abc@x>","body":"Hi\nthere","bodyType":"text","attachments":[{"filename":"deck.pdf","mimeType":"application/pdf","size":12,"attachmentId":"A1"}]}'
+
+OUT=$(run --id m1)
+check "flags: output (no snippet/labelIds)" "$OUT" "$WANT"
+check "flags: path" "$(jq -r .path "$STUB_LOG")" "/api/google/gmail/messages/m1"
+
+OUT=$(run '{"id":"m 1"}')
+check "json: output" "$OUT" "$WANT"
+check "json: id is URL-encoded" "$(jq -r .path "$STUB_LOG")" "/api/google/gmail/messages/m%201"
+
+OUT=$(CREWLY_API_URL="http://127.0.0.1:${PORT}" bash "$EXEC" --id missing 2>/dev/null); RC=$?
+check "404: exit code" "$RC" "1"
+check "404: reason" "$(printf '%s' "$OUT" | jq -r .reason)" "google_error"
+check "404: message" "$(printf '%s' "$OUT" | jq -r .message)" "Requested entity was not found."
+
+OUT=$(CREWLY_API_URL="http://127.0.0.1:${PORT}" bash "$EXEC" --id no-grant 2>/dev/null)
+check "409: hint is the connect URL" "$(printf '%s' "$OUT" | jq -r .hint)" "https://cloud/start?token=j"
+
+check "missing id errors" "$(run_err)" "Missing required parameter: id (--id)"
+check "unknown option errors" "$(run_err --bogus 1)" "Unknown option: --bogus"
+
+echo "=== Results: $PASS passed, $FAIL failed ==="
+[ "$FAIL" -eq 0 ]

package/config/skills/agent/core/gmail-search/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: Gmail Search
+description: Search the owner's Gmail (via the Google Workspace grant held by Crewly Cloud) and list matching messages with sender, subject, date and snippet. Read-only.
+version: 1.0.0
+category: communication
+skillType: claude-skill
+assignableRoles:
+  - orchestrator
+  - team-leader
+  - developer
+  - operations
+  - ops
+  - sales
+  - support
+  - generalist
+triggers:
+  - search gmail
+  - search email
+  - find email
+  - check inbox
+tags:
+  - google
+  - gmail
+  - email
+execution:
+  type: script
+  script:
+    file: execute.sh
+    interpreter: bash
+    timeoutMs: 30000
+---
+
+# Gmail Search
+
+Runs a Gmail search on the owner's mailbox and prints the hits. Uses the
+Google Workspace connection the owner made under Settings → Integrations;
+the mail content goes straight from Google to this instance.
+
+```bash
+bash execute.sh --query "is:unread from:ann@example.com newer_than:2d" --max 10
+bash execute.sh '{"query":"subject:invoice has:attachment","max":5}'
+```
+
+## Parameters
+
+| Name | Required | Meaning |
+|---|---|---|
+| `--query` / `-q` (`query`) | yes | Gmail search syntax (`from:`, `subject:`, `is:unread`, `newer_than:7d`, `has:attachment`, …) |
+| `--max` / `-n` (`max`) | no | Result cap, default 20, max 100 |
+
+## Output
+
+```json
+{"query":"is:unread","count":2,"messages":[{"id":"18f…","threadId":"18f…","from":"Ann <ann@example.com>","to":"owner@example.com","subject":"Q3 numbers","date":"Thu, 18 Sep 2026 10:00:00 +0000","snippet":"Here are the…"}]}
+```
+
+Use the `id` with `gmail-read` to get the body; `threadId` + `gmail-read`'s
+`messageId` with `gmail-send` to reply in-thread.
+
+## Failures
+
+`{"success":false,"reason":"not_connected","hint":"<connect URL>"}` — the
+owner has not connected Google Workspace yet; hand them the hint URL (or
+point them to Settings → Integrations → Google Workspace). Exit code 1.

package/config/skills/agent/core/gmail-search/execute.sh

@@ -0,0 +1,70 @@
+#!/bin/bash
+# =============================================================================
+# gmail-search — Search the owner's Gmail (read-only)
+#
+# Backed by GET /api/google/gmail/search?q=&max= (Cloud holds the Google
+# grant; this instance talks to Gmail directly).
+#
+# Usage:
+#   bash execute.sh --query "is:unread from:ann" [--max 10]
+#   bash execute.sh '{"query":"is:unread","max":10}'
+# =============================================================================
+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 "is:unread from:ann" [--max 10]
+  bash execute.sh '{"query":"is:unread","max":10}'
+
+Options:
+  --query | -q   Gmail search query (required)
+  --max   | -n   Result cap (default 20, max 100)
+  --help  | -h   Show this help
+EOF_USAGE
+}
+
+INPUT_JSON=""
+QUERY=""
+MAX=""
+
+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 ;;
+    --max|-n)   [ $# -ge 2 ] || error_exit "--max requires a value";   MAX="$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 // .q // empty')
+  [ -z "$MAX" ] && MAX=$(printf '%s' "$INPUT" | jq -r '.max // empty')
+fi
+
+require_param "query (--query)" "$QUERY"
+
+Q_ENC=$(jq -rn --arg v "$QUERY" '$v|@uri')
+ENDPOINT="/google/gmail/search?q=${Q_ENC}"
+[ -n "$MAX" ] && ENDPOINT="${ENDPOINT}&max=$(jq -rn --arg v "$MAX" '$v|@uri')"
+
+RESPONSE=$(api_call GET "$ENDPOINT" 2>&1) || {
+  printf '%s' "$RESPONSE" | jq -c '{success: false, reason: (.details.error // .details // .error // "unknown"), hint: (.details.hint // ""), message: (.details.message // "")}' 2>/dev/null \
+    || jq -n --arg r "$RESPONSE" '{success: false, reason: $r}'
+  exit 1
+}
+
+# Oversized bodies are parked on disk by api_call; pass that envelope through.
+if printf '%s' "$RESPONSE" | jq -e '.truncated == true' >/dev/null 2>&1; then
+  printf '%s\n' "$RESPONSE"; exit 0
+fi
+
+printf '%s' "$RESPONSE" | jq -c '{query: .data.query, count: .data.count, messages: [.data.messages[] | {id, threadId, from, to, subject, date, snippet}]}'

package/config/skills/agent/core/gmail-search/execute.test.sh

@@ -0,0 +1,67 @@
+#!/bin/bash
+# Tests for gmail-search — run with: bash execute.test.sh
+# Spins up a python HTTP stub as the backend, asserts the request path the
+# skill sends and the JSON it prints. 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
+}
+
+PORT=18801
+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'])
+HIT = {'id': 'm1', 'threadId': 't1', 'from': 'Ann <ann@example.com>', 'to': 'owner@example.com',
+       'subject': 'Q3 numbers', 'date': 'D', 'snippet': 'hi', 'labelIds': ['INBOX']}
+class H(BaseHTTPRequestHandler):
+    def do_GET(self):
+        open(LOG, 'w').write(json.dumps({'method': 'GET', 'path': self.path}))
+        qs = parse_qs(urlparse(self.path).query)
+        q = qs.get('q', [''])[0]
+        if q == 'no-grant':
+            self.send_response(409); self.send_header('Content-Type', 'application/json'); self.end_headers()
+            self.wfile.write(json.dumps({'success': False, 'error': 'not_connected', 'message': 'no grant',
+                                         'hint': 'https://api.crewlyai.com/api/cloud/google/workspace/start?token=j'}).encode()); return
+        self.send_response(200); self.send_header('Content-Type', 'application/json'); self.end_headers()
+        self.wfile.write(json.dumps({'success': True, 'data': {'query': q, 'count': 1, 'messages': [HIT]}}).encode())
+    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_API_URL="http://127.0.0.1:${PORT}" bash "$EXEC" "$@" 2>/dev/null; }
+run_err() { CREWLY_API_URL="http://127.0.0.1:${PORT}" bash "$EXEC" "$@" 2>&1 >/dev/null | jq -r '.error' 2>/dev/null; }
+
+WANT='{"query":"is:unread from:ann","count":1,"messages":[{"id":"m1","threadId":"t1","from":"Ann <ann@example.com>","to":"owner@example.com","subject":"Q3 numbers","date":"D","snippet":"hi"}]}'
+
+# --- flags ---
+OUT=$(run --query "is:unread from:ann" --max 5)
+check "flags: output drops labelIds" "$OUT" "$WANT"
+check "flags: path is URL-encoded with max" "$(jq -r .path "$STUB_LOG")" "/api/google/gmail/search?q=is%3Aunread%20from%3Aann&max=5"
+
+# --- JSON input ---
+OUT=$(run '{"query":"is:unread from:ann"}')
+check "json: output" "$OUT" "$WANT"
+check "json: no max when absent" "$(jq -r .path "$STUB_LOG")" "/api/google/gmail/search?q=is%3Aunread%20from%3Aann"
+
+# --- not connected → success:false + hint, exit 1 ---
+OUT=$(CREWLY_API_URL="http://127.0.0.1:${PORT}" bash "$EXEC" --query no-grant 2>/dev/null); RC=$?
+check "409: exit code" "$RC" "1"
+check "409: reason + hint" "$OUT" '{"success":false,"reason":"not_connected","hint":"https://api.crewlyai.com/api/cloud/google/workspace/start?token=j","message":"no grant"}'
+
+# --- validation ---
+check "missing query errors" "$(run_err --max 3)" "Missing required parameter: query (--query)"
+check "unknown option errors" "$(run_err --bogus 1)" "Unknown option: --bogus"
+
+echo "=== Results: $PASS passed, $FAIL failed ==="
+[ "$FAIL" -eq 0 ]

package/config/skills/agent/core/gmail-send/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: Gmail Send
+description: Send an email from the owner's Gmail account (via the Google Workspace grant held by Crewly Cloud). Sends on the owner's behalf — needs the owner's go-ahead unless the task brief grants it. Supports in-thread replies and a dry-run preview.
+version: 1.0.0
+category: communication
+skillType: claude-skill
+assignableRoles:
+  - orchestrator
+  - team-leader
+  - operations
+  - ops
+  - sales
+  - support
+  - generalist
+triggers:
+  - send email
+  - reply to email
+  - email someone
+tags:
+  - google
+  - gmail
+  - email
+execution:
+  type: script
+  script:
+    file: execute.sh
+    interpreter: bash
+    timeoutMs: 30000
+---
+
+# Gmail Send
+
+Sends a plain-text email **as the owner**. Because the message carries the
+owner's name, only send when the owner has said so in this conversation or
+the task brief explicitly grants sending; otherwise draft with `--dry-run`
+and show the preview.
+
+```bash
+bash execute.sh --to ann@example.com --subject "Re: Q3 numbers" --text "Looks good, thanks!"
+bash execute.sh --to ann@example.com --subject "Re: Q3 numbers" --text-file /tmp/reply.txt \
+  --thread-id 18f0a1b2c3d4e5f6 --in-reply-to "<abc@mail.example.com>"
+bash execute.sh '{"to":"ann@example.com","subject":"Hi","text":"…"}'
+```
+
+## Parameters
+
+| Name | Required | Meaning |
+|---|---|---|
+| `--to` (`to`) | yes | Recipient(s), comma-separated |
+| `--subject` (`subject`) | yes | Subject (UTF-8 fine) |
+| `--text` / `--text-file` (`text`) | yes | Plain-text body, inline or from a file |
+| `--cc` (`cc`) | no | Cc recipient(s) |
+| `--thread-id` (`threadId`) | no | Gmail thread to reply in (from `gmail-search`) |
+| `--in-reply-to` (`inReplyTo`) | no | `messageId` of the message being answered (from `gmail-read`) |
+| `--dry-run` | no | Print the message preview; send nothing |
+
+`CREWLY_GMAIL_SEND_DRY_RUN=1` in the environment forces dry-run for every
+call — nothing is sent, no request leaves this machine.
+
+## Output
+
+Sent: `{"success":true,"id":"18f…","threadId":"18f…"}`
+
+Dry run: `{"success":true,"dryRun":true,"preview":"To: …\nSubject: …\n\n<body>"}`
+
+## Failures
+
+Missing `--to` / `--subject` / body → `{"error":"Missing required parameter: …"}` on stderr, exit 1, nothing sent.
+`{"success":false,"reason":"not_connected","hint":"<connect URL>"}` (exit 1) when the owner has not connected Google Workspace.