crewly 1.16.0 → 1.17.1

package/README.md

@@ -125,9 +125,11 @@ Optional environment variables (`.env` file or shell):
 ```bash
 GEMINI_API_KEY=your_key_here       # Required for Gemini CLI runtime
 
-SLACK_BOT_TOKEN=xoxb-...           # Optional: Slack integration
+SLACK_BOT_TOKEN=xoxb-...           # Optional: self-hosted Slack app (see "Slack" below)
 SLACK_APP_TOKEN=xapp-...
 SLACK_SIGNING_SECRET=...
+CREWLY_SLACK_SOURCE=cloud          # Optional: env | cloud (unset = Cloud wins when both exist)
+CREWLY_SLACK_PRIMARY=1             # Optional: this instance handles DMs / unmapped channels
 
 LOG_LEVEL=info                     # debug, info, warn, error
 WEB_PORT=8787                      # Dashboard port (default: 8787)
@@ -135,6 +137,36 @@ CREWLY_BIND_HOST=0.0.0.0           # Interface to listen on (127.0.0.1 = this ma
 CREWLY_API_TOKEN=...               # Pin the API token (otherwise generated at ~/.crewly/api-token)
 ```
 
+### Slack
+
+**One click (recommended).** Log in to Crewly Cloud (Settings → Cloud), open
+Settings → Integrations → Slack and press **Connect Slack**. Slack asks you to
+approve the Crewly app once; from then on every Crewly instance signed in to the
+same Crewly account gets Slack automatically — team channels, and one real Slack
+bot user per agent — with no tokens to copy. The instance pulls its config from
+Cloud on boot and every 10 minutes (cached 0600 at
+`~/.crewly/slack-cloud-config.json`); Slack events reach it through the Cloud
+relay, so no Socket Mode connection is opened.
+
+**The one manual step.** Slack only lets an app be created by an *App
+Configuration Token* of a workspace member, and Crewly creates one Slack app per
+agent so each agent is a real bot user (name in the member list, native `@`
+mentions). Generate the token at api.slack.com/apps ("Your App Configuration
+Tokens" → Generate) and paste it in Settings → Slack → Agent Identities. Cloud
+keeps it refreshed. Each new agent then shows an install link you click once.
+
+**Several instances, one workspace.** Every instance registers its teams,
+channels and agents with Cloud (on boot, on team changes, every 5 min); Slack
+traffic for a team channel goes to the instance running that team. Direct
+messages to the Crewly bot and channels no team owns go to the **primary**
+instance — the Settings toggle, or `CREWLY_SLACK_PRIMARY=1`.
+
+**Self-hosted app.** The original path (your own Slack app, Socket Mode,
+`SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` / `SLACK_SIGNING_SECRET` or the form under
+Settings → Slack → Advanced) still works. `CREWLY_SLACK_SOURCE` picks the source:
+`cloud` uses only the Cloud workspace, `env` uses only local tokens and never
+asks Cloud, unset prefers Cloud when both exist (logged once at boot).
+
 ### Securing a server install
 
 Crewly agents run as real shells on the host, and `POST /api/terminal/:session/write`

package/config/roles/orchestrator/prompt.md

@@ -194,17 +194,30 @@ bash {{ORCHESTRATOR_SKILLS_PATH}}/register-self/execute.sh '{"role":"orchestrato
 
 After registering, proceed to Step 4.
 
-### Step 4 — Check Active Goals and Report
+### Step 4 — Check the Missions (OKRs) and Report
 
-After registration, check for active goals and OKRs:
+After registration, read the real goal layer — the Missions API, not your
+memory (memory only holds what someone happened to save):
 
 ```bash
-bash {{AGENT_SKILLS_PATH}}/core/recall/execute.sh '{"context":"OKR goals active tasks","scope":"both","agentId":"{{SESSION_ID}}","projectPath":"{{PROJECT_PATH}}"}'
+bash {{ORCHESTRATOR_SKILLS_PATH}}/list-missions/execute.sh
 ```
 
-**If active OKRs or goals exist:** Report the current status to the user and ask if they want you to take over execution. Do NOT auto-execute unless the user explicitly activates Autonomous Mode (see below). Once the user activates Autonomous Mode in a session, it stays ON for the rest of that session — you do not need to re-ask.
+**If a proposal is `pending_approval`:** tell the owner in one line what is
+waiting (objective + its Key Results) and where to approve it (Missions page).
+Do NOT execute, remind about or decompose it until it is approved.
 
-**If no active goals exist:** Say "Ready" and wait for the user.
+**If live (approved) missions exist:** report each one's KRs (current → target,
+status) in two or three lines and ask whether to take over execution. Do NOT
+auto-execute unless the owner activates Autonomous Mode (below). Once
+activated in a session it stays ON for that session.
+
+**If there are no missions at all** and `get-team-status` shows teams that
+completed work in the last week: draft ONE company-level OKR from that work
+(objective + 2–3 Key Results that can be measured from something already in
+the system — a ticket board, a build log, a folder count; see `count-json`
+and `measurementSource: skill_output`) and ask the owner whether to create it.
+Do not create it yourself. If there is no recent work either, say "Ready".
 
 ## Pipeline-First Planning Discipline (MANDATORY for planning intent)
 
@@ -271,6 +284,8 @@ The `delegate-task` skill emits a stderr WARNING when a brief is missing G/O/E m
 
 5. **Self-check before dispatch** — diff your composed `Expected Outcome` line items against the user's literal words. Every line in Expected Outcome must trace to a word/phrase the user actually wrote. If a line is justified only by recalled history, move it to `Context` or `Suggested Follow-ups` and surface back for confirmation.
 
+6. **Outbound mail under the owner's name is gated.** Sending email from the owner's Gmail (`gmail-send`, or any delegated brief that includes sending) requires the owner's explicit go-ahead in this conversation unless the task brief already grants it in `Decision Rights`; without that grant, draft with the dry-run preview and show it for approval instead of sending.
+
 **Negative pattern to suppress** (the 2026-05-20 ESTestNode shape):
 > User: "update X" → ORC: `recall_memory(X)` → memory has "X had 3 known issues" → ORC: "while you're updating X, handle the 3 known issues too" → executor does all 4 things → user pays for unauthorized scope on prod.
 

package/config/skills/agent/core/calendar-create/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: Calendar Create
+description: Create an event on the owner's Google Calendar (via the Google Workspace grant held by Crewly Cloud) — timed or all-day, with optional description and attendees. Attendees receive an invitation from the owner, so confirm before inviting others.
+version: 1.0.0
+category: communication
+skillType: claude-skill
+assignableRoles:
+  - orchestrator
+  - team-leader
+  - operations
+  - ops
+  - sales
+  - support
+  - generalist
+triggers:
+  - create event
+  - schedule meeting
+  - add to calendar
+  - book a meeting
+tags:
+  - google
+  - calendar
+execution:
+  type: script
+  script:
+    file: execute.sh
+    interpreter: bash
+    timeoutMs: 30000
+---
+
+# Calendar Create
+
+```bash
+bash execute.sh --summary "Design review" --start 2026-09-20T14:00:00 --end 2026-09-20T15:00:00 \
+  --timezone Asia/Shanghai --description "Walk through v2" --attendee ann@example.com
+bash execute.sh --summary "Offsite" --start 2026-10-01 --end 2026-10-02      # all-day (end is exclusive)
+bash execute.sh '{"summary":"Standup","start":"2026-09-21T09:00:00Z","end":"2026-09-21T09:15:00Z"}'
+```
+
+## Parameters
+
+| Name | Required | Meaning |
+|---|---|---|
+| `--summary` (`summary`) | yes | Event title |
+| `--start` (`start`) | yes | ISO 8601 date-time, or `YYYY-MM-DD` for all-day |
+| `--end` (`end`) | yes | ISO 8601 date-time, or `YYYY-MM-DD` (exclusive) for all-day |
+| `--timezone` (`timezone`) | no | IANA zone applied to start/end without an offset |
+| `--description` (`description`) | no | Body text |
+| `--attendee` (`attendees`) | no | Email; repeat for several (JSON: array or comma list) |
+| `--calendar` (`calendarId`) | no | Calendar id; default `primary` |
+
+## Output
+
+```json
+{"success":true,"id":"…","summary":"Design review","start":{"dateTime":"…","timeZone":"Asia/Shanghai"},"end":{…},"htmlLink":"https://…","attendees":[{"email":"ann@example.com","responseStatus":"needsAction"}]}
+```
+
+## Failures
+
+Missing `--summary` / `--start` / `--end` → `{"error":"Missing required parameter: …"}` on stderr, exit 1.
+`{"success":false,"reason":"not_connected","hint":"<connect URL>"}` (exit 1) when the owner has not connected Google Workspace;
+`reason` `validation` when Google cannot parse a time.

package/config/skills/agent/core/calendar-create/execute.sh

@@ -0,0 +1,91 @@
+#!/bin/bash
+# =============================================================================
+# calendar-create — Create an event on the owner's Google Calendar
+#
+# Backed by POST /api/google/calendar/events.
+#
+# Usage:
+#   bash execute.sh --summary "Review" --start 2026-09-20T14:00:00 --end 2026-09-20T15:00:00
+#                   [--timezone Asia/Shanghai] [--description "…"] [--attendee a@b.c]... [--calendar id]
+#   bash execute.sh '{"summary":"Review","start":"…","end":"…","attendees":["a@b.c"]}'
+# =============================================================================
+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 --summary "Review" --start <ISO|YYYY-MM-DD> --end <ISO|YYYY-MM-DD>
+                  [--timezone Asia/Shanghai] [--description "…"] [--attendee a@b.c]... [--calendar <id>]
+  bash execute.sh '{"summary":"Review","start":"…","end":"…","attendees":["a@b.c"]}'
+
+Options:
+  --summary       Event title (required)
+  --start         Start: ISO 8601 date-time, or YYYY-MM-DD for all-day (required)
+  --end           End: ISO 8601 date-time, or YYYY-MM-DD (exclusive) for all-day (required)
+  --timezone      IANA zone for start/end without an offset
+  --description   Body text
+  --attendee      Attendee email (repeat for several)
+  --calendar      Calendar id (default: primary)
+  --help | -h     Show this help
+EOF_USAGE
+}
+
+INPUT_JSON=""
+SUMMARY=""; START=""; END=""; TIMEZONE=""; DESCRIPTION=""; CALENDAR=""
+ATTENDEES_JSON='[]'
+
+if [[ $# -gt 0 && ${1:0:1} == '{' ]]; then
+  INPUT_JSON="$1"
+  shift || true
+fi
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --summary|--title) [ $# -ge 2 ] || error_exit "--summary requires a value";     SUMMARY="$2";     shift 2 ;;
+    --start)           [ $# -ge 2 ] || error_exit "--start requires a value";       START="$2";       shift 2 ;;
+    --end)             [ $# -ge 2 ] || error_exit "--end requires a value";         END="$2";         shift 2 ;;
+    --timezone|--tz)   [ $# -ge 2 ] || error_exit "--timezone requires a value";    TIMEZONE="$2";    shift 2 ;;
+    --description)     [ $# -ge 2 ] || error_exit "--description requires a value"; DESCRIPTION="$2"; shift 2 ;;
+    --calendar|-c)     [ $# -ge 2 ] || error_exit "--calendar requires a value";    CALENDAR="$2";    shift 2 ;;
+    --attendee)        [ $# -ge 2 ] || error_exit "--attendee requires a value"
+                       ATTENDEES_JSON=$(jq -cn --argjson arr "$ATTENDEES_JSON" --arg v "$2" '$arr + [$v]'); 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 "$SUMMARY" ]     && SUMMARY=$(printf '%s' "$INPUT" | jq -r '.summary // .title // empty')
+  [ -z "$START" ]       && START=$(printf '%s' "$INPUT" | jq -r '.start // empty')
+  [ -z "$END" ]         && END=$(printf '%s' "$INPUT" | jq -r '.end // empty')
+  [ -z "$TIMEZONE" ]    && TIMEZONE=$(printf '%s' "$INPUT" | jq -r '.timezone // .timeZone // empty')
+  [ -z "$DESCRIPTION" ] && DESCRIPTION=$(printf '%s' "$INPUT" | jq -r '.description // empty')
+  [ -z "$CALENDAR" ]    && CALENDAR=$(printf '%s' "$INPUT" | jq -r '.calendarId // .calendar // empty')
+  if [ "$(printf '%s' "$ATTENDEES_JSON" | jq 'length')" -eq 0 ]; then
+    ATTENDEES_JSON=$(printf '%s' "$INPUT" | jq -c '(.attendees // []) | if type == "string" then split(",") | map(gsub("^\\s+|\\s+$"; "")) | map(select(. != "")) else . end')
+  fi
+fi
+
+require_param "summary (--summary)" "$SUMMARY"
+require_param "start (--start)" "$START"
+require_param "end (--end)" "$END"
+
+BODY=$(jq -cn --arg summary "$SUMMARY" --arg start "$START" --arg end "$END" \
+  --arg timezone "$TIMEZONE" --arg description "$DESCRIPTION" --arg calendarId "$CALENDAR" \
+  --argjson attendees "$ATTENDEES_JSON" \
+  '{summary: $summary, start: $start, end: $end}
+   + (if $timezone != "" then {timezone: $timezone} else {} end)
+   + (if $description != "" then {description: $description} else {} end)
+   + (if $calendarId != "" then {calendarId: $calendarId} else {} end)
+   + (if ($attendees | length) > 0 then {attendees: $attendees} else {} end)')
+
+RESPONSE=$(api_call POST "/google/calendar/events" "$BODY" 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
+}
+
+printf '%s' "$RESPONSE" | jq -c '{success: (.success // false)} + (.data | {id, summary, start, end, htmlLink, attendees})'

package/config/skills/agent/core/calendar-create/execute.test.sh

@@ -0,0 +1,80 @@
+#!/bin/bash
+# Tests for calendar-create — run with: bash execute.test.sh
+# Spins up a python HTTP stub as the backend, asserts the request body 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=18805
+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'])
+class H(BaseHTTPRequestHandler):
+    def do_POST(self):
+        n = int(self.headers.get('content-length', '0')); body = self.rfile.read(n).decode() if n else ''
+        data = json.loads(body or '{}')
+        open(LOG, 'w').write(json.dumps({'method': 'POST', 'path': self.path, 'body': data}))
+        if data.get('summary') == '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
+        if data.get('start') == 'tomorrow':
+            self.send_response(400); self.send_header('Content-Type', 'application/json'); self.end_headers()
+            self.wfile.write(json.dumps({'success': False, 'error': 'validation', 'message': '"start" must be YYYY-MM-DD or an ISO 8601 date-time', 'hint': 'Fix the request and retry.'}).encode()); return
+        tz = data.get('timezone')
+        def t(v):
+            if len(v) == 10: return {'date': v}
+            return {'dateTime': v, 'timeZone': tz} if tz else {'dateTime': v}
+        ev = {'id': 'new1', 'summary': data['summary'], 'start': t(data['start']), 'end': t(data['end']), 'htmlLink': 'https://cal/new1',
+              'attendees': [{'email': a, 'responseStatus': 'needsAction'} for a in data.get('attendees', [])], 'status': 'confirmed'}
+        self.send_response(200); self.send_header('Content-Type', 'application/json'); self.end_headers()
+        self.wfile.write(json.dumps({'success': True, 'data': ev}).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; }
+
+# --- timed event with everything ---
+OUT=$(run --summary "Design review" --start 2026-09-20T14:00:00 --end 2026-09-20T15:00:00 --timezone Asia/Shanghai \
+  --description "Walk through v2" --attendee ann@example.com --attendee bob@example.com --calendar ops@example.com)
+check "flags: body" "$(jq -c .body "$STUB_LOG")" '{"summary":"Design review","start":"2026-09-20T14:00:00","end":"2026-09-20T15:00:00","timezone":"Asia/Shanghai","description":"Walk through v2","calendarId":"ops@example.com","attendees":["ann@example.com","bob@example.com"]}'
+check "flags: path" "$(jq -r .path "$STUB_LOG")" "/api/google/calendar/events"
+check "flags: output" "$OUT" '{"success":true,"id":"new1","summary":"Design review","start":{"dateTime":"2026-09-20T14:00:00","timeZone":"Asia/Shanghai"},"end":{"dateTime":"2026-09-20T15:00:00","timeZone":"Asia/Shanghai"},"htmlLink":"https://cal/new1","attendees":[{"email":"ann@example.com","responseStatus":"needsAction"},{"email":"bob@example.com","responseStatus":"needsAction"}]}'
+
+# --- all-day via JSON, comma-separated attendees ---
+OUT=$(run '{"summary":"Offsite","start":"2026-10-01","end":"2026-10-02","attendees":"a@b.c, d@e.f"}')
+check "json: body omits optional keys, splits attendees" "$(jq -c .body "$STUB_LOG")" '{"summary":"Offsite","start":"2026-10-01","end":"2026-10-02","attendees":["a@b.c","d@e.f"]}'
+check "json: all-day output" "$(printf '%s' "$OUT" | jq -c '{start, end}')" '{"start":{"date":"2026-10-01"},"end":{"date":"2026-10-02"}}'
+
+# --- backend validation surfaces ---
+OUT=$(CREWLY_API_URL="http://127.0.0.1:${PORT}" bash "$EXEC" --summary x --start tomorrow --end 2026-10-02 2>/dev/null); RC=$?
+check "400: exit code" "$RC" "1"
+check "400: reason" "$(printf '%s' "$OUT" | jq -r .reason)" "validation"
+
+# --- 409 ---
+OUT=$(CREWLY_API_URL="http://127.0.0.1:${PORT}" bash "$EXEC" --summary no-grant --start 2026-10-01 --end 2026-10-02 2>/dev/null)
+check "409: reason + hint" "$OUT" '{"success":false,"reason":"not_connected","hint":"https://cloud/start?token=j","message":"no grant"}'
+
+# --- local validation (nothing sent) ---
+: > "$STUB_LOG"
+check "missing summary errors" "$(run_err --start 2026-10-01 --end 2026-10-02)" "Missing required parameter: summary (--summary)"
+check "missing start errors" "$(run_err --summary x --end 2026-10-02)" "Missing required parameter: start (--start)"
+check "missing end errors" "$(run_err --summary x --start 2026-10-01)" "Missing required parameter: end (--end)"
+check "validation: no request made" "$(cat "$STUB_LOG")" ""
+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/calendar-list/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: Calendar List
+description: List upcoming events on the owner's Google Calendar (via the Google Workspace grant held by Crewly Cloud). Defaults to the next 7 days on the primary calendar. Read-only.
+version: 1.0.0
+category: communication
+skillType: claude-skill
+assignableRoles:
+  - orchestrator
+  - team-leader
+  - developer
+  - operations
+  - ops
+  - sales
+  - support
+  - generalist
+triggers:
+  - list calendar
+  - check calendar
+  - what's on my calendar
+  - upcoming meetings
+tags:
+  - google
+  - calendar
+execution:
+  type: script
+  script:
+    file: execute.sh
+    interpreter: bash
+    timeoutMs: 30000
+---
+
+# Calendar List
+
+```bash
+bash execute.sh                                   # next 7 days, primary calendar
+bash execute.sh --from 2026-09-18T00:00:00Z --to 2026-09-19T00:00:00Z --max 20
+bash execute.sh '{"calendarId":"team@group.calendar.google.com","from":"…","to":"…"}'
+```
+
+## Parameters
+
+| Name | Required | Meaning |
+|---|---|---|
+| `--from` (`from`) | no | ISO 8601 lower bound; default now |
+| `--to` (`to`) | no | ISO 8601 upper bound; default now + 7 days |
+| `--calendar` (`calendarId`) | no | Calendar id; default `primary` |
+| `--max` (`max`) | no | Result cap, default 50, max 250 |
+
+## Output
+
+```json
+{"count":2,"events":[{"id":"…","summary":"Standup","start":{"dateTime":"2026-09-18T09:00:00+08:00"},"end":{"dateTime":"…"},"attendees":[{"email":"ann@example.com","responseStatus":"accepted"}],"htmlLink":"https://…"}]}
+```
+
+## Failures
+
+`{"success":false,"reason":"not_connected","hint":"<connect URL>"}` (exit 1)
+when the owner has not connected Google Workspace.

package/config/skills/agent/core/calendar-list/execute.sh

@@ -0,0 +1,88 @@
+#!/bin/bash
+# =============================================================================
+# calendar-list — Upcoming events on the owner's Google Calendar (read-only)
+#
+# Backed by GET /api/google/calendar/events?from=&to=&calendarId=&max=.
+# Without --from/--to the window is now → now + 7 days.
+#
+# Usage:
+#   bash execute.sh [--from ISO] [--to ISO] [--calendar id] [--max 20]
+#   bash execute.sh '{"from":"…","to":"…","calendarId":"primary","max":20}'
+# =============================================================================
+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 [--from ISO-8601] [--to ISO-8601] [--calendar <id>] [--max 20]
+  bash execute.sh '{"from":"…","to":"…","calendarId":"primary","max":20}'
+
+Options:
+  --from        Lower bound (default: now)
+  --to          Upper bound (default: now + 7 days)
+  --calendar    Calendar id (default: primary)
+  --max         Result cap (default 50, max 250)
+  --help | -h   Show this help
+EOF_USAGE
+}
+
+DEFAULT_WINDOW_DAYS="${CREWLY_CALENDAR_LIST_DAYS:-7}"
+
+# Portable "now + N days" in UTC ISO 8601 (macOS `date -v`, GNU `date -d`).
+iso_now_plus_days() {
+  local days="$1"
+  if date -u -v+"${days}"d +%Y-%m-%dT%H:%M:%SZ >/dev/null 2>&1; then
+    date -u -v+"${days}"d +%Y-%m-%dT%H:%M:%SZ
+  else
+    date -u -d "+${days} days" +%Y-%m-%dT%H:%M:%SZ
+  fi
+}
+
+INPUT_JSON=""
+FROM=""; TO=""; CALENDAR=""; MAX=""
+
+if [[ $# -gt 0 && ${1:0:1} == '{' ]]; then
+  INPUT_JSON="$1"
+  shift || true
+fi
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --from)        [ $# -ge 2 ] || error_exit "--from requires a value";     FROM="$2";     shift 2 ;;
+    --to)          [ $# -ge 2 ] || error_exit "--to requires a value";       TO="$2";       shift 2 ;;
+    --calendar|-c) [ $# -ge 2 ] || error_exit "--calendar requires a value"; CALENDAR="$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 "$FROM" ]     && FROM=$(printf '%s' "$INPUT" | jq -r '.from // .timeMin // empty')
+  [ -z "$TO" ]       && TO=$(printf '%s' "$INPUT" | jq -r '.to // .timeMax // empty')
+  [ -z "$CALENDAR" ] && CALENDAR=$(printf '%s' "$INPUT" | jq -r '.calendarId // .calendar // empty')
+  [ -z "$MAX" ]      && MAX=$(printf '%s' "$INPUT" | jq -r '.max // empty')
+fi
+
+[ -z "$FROM" ] && FROM=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+[ -z "$TO" ] && TO=$(iso_now_plus_days "$DEFAULT_WINDOW_DAYS")
+
+QS="from=$(jq -rn --arg v "$FROM" '$v|@uri')&to=$(jq -rn --arg v "$TO" '$v|@uri')"
+[ -n "$CALENDAR" ] && QS="${QS}&calendarId=$(jq -rn --arg v "$CALENDAR" '$v|@uri')"
+[ -n "$MAX" ] && QS="${QS}&max=$(jq -rn --arg v "$MAX" '$v|@uri')"
+
+RESPONSE=$(api_call GET "/google/calendar/events?${QS}" 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 '{count: .data.count, events: .data.events}'

package/config/skills/agent/core/calendar-list/execute.test.sh

@@ -0,0 +1,71 @@
+#!/bin/bash
+# Tests for calendar-list — 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=18804
+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'])
+EV = {'id': 'e1', 'summary': 'Standup', 'start': {'dateTime': '2026-09-18T09:00:00Z'}, 'end': {'dateTime': '2026-09-18T09:15:00Z'}, 'attendees': []}
+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)
+        if qs.get('calendarId', [''])[0] == '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': {'count': 1, 'events': [EV]}}).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='{"count":1,"events":[{"id":"e1","summary":"Standup","start":{"dateTime":"2026-09-18T09:00:00Z"},"end":{"dateTime":"2026-09-18T09:15:00Z"},"attendees":[]}]}'
+
+OUT=$(run --from 2026-09-18T00:00:00Z --to 2026-09-19T00:00:00Z --calendar "team@group.calendar.google.com" --max 20)
+check "flags: output" "$OUT" "$WANT"
+check "flags: path" "$(jq -r .path "$STUB_LOG")" "/api/google/calendar/events?from=2026-09-18T00%3A00%3A00Z&to=2026-09-19T00%3A00%3A00Z&calendarId=team%40group.calendar.google.com&max=20"
+
+OUT=$(run '{"from":"2026-09-18T00:00:00Z","to":"2026-09-19T00:00:00Z"}')
+check "json: output" "$OUT" "$WANT"
+check "json: path without optional params" "$(jq -r .path "$STUB_LOG")" "/api/google/calendar/events?from=2026-09-18T00%3A00%3A00Z&to=2026-09-19T00%3A00%3A00Z"
+
+# --- defaults: now → now + 7 days (shape only; values are wall-clock) ---
+run >/dev/null
+P=$(jq -r .path "$STUB_LOG")
+FROM_V=$(printf '%s' "$P" | sed -E 's/.*[?&]from=([^&]*).*/\1/')
+TO_V=$(printf '%s' "$P" | sed -E 's/.*[?&]to=([^&]*).*/\1/')
+[[ "$FROM_V" =~ ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}%3A[0-9]{2}%3A[0-9]{2}Z$ ]] && FROM_OK=yes || FROM_OK=no
+[[ "$TO_V" =~ ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}%3A[0-9]{2}%3A[0-9]{2}Z$ ]] && TO_OK=yes || TO_OK=no
+check "defaults: from is ISO UTC" "$FROM_OK" "yes"
+check "defaults: to is ISO UTC" "$TO_OK" "yes"
+[ "$TO_V" \> "$FROM_V" ] && ORDER=yes || ORDER=no
+check "defaults: to is after from" "$ORDER" "yes"
+
+OUT=$(CREWLY_API_URL="http://127.0.0.1:${PORT}" bash "$EXEC" --calendar no-grant 2>/dev/null); RC=$?
+check "409: exit code" "$RC" "1"
+check "409: reason + hint" "$OUT" '{"success":false,"reason":"not_connected","hint":"https://cloud/start?token=j","message":"no grant"}'
+
+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-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.