crewly 1.20.205 → 1.20.207

package/config/hooks/credential-guard/guard.sh

@@ -0,0 +1,243 @@
+#!/usr/bin/env bash
+# Crewly credential guard — a pre-tool hook that refuses an agent's tool call
+# when it reads Crewly's own credentials.
+#
+# Spec: specs/2026-10-04-agent-credential-isolation.md (layer 2).
+#
+# Usage (wired by the backend through a generated wrapper; hook JSON on stdin):
+#   bash guard.sh <format> [<paths-file>]
+#     format:     claude | codex | gemini | antigravity
+#     paths-file: written by the backend; defaults to $CREWLY_CREDENTIAL_GUARD_PATHS
+#
+# Paths-file lines (tab-separated):
+#   home  -     <CREWLY_HOME>
+#   abs   <id>  an absolute credential path (a file, or a directory = its subtree)
+#
+# What it judges — only REAL PATHS, resolved the way the call would resolve them:
+#   - shell commands (Bash, run_shell_command, agy run_command) are tokenised
+#     like a shell: quotes, escapes, `$(…)` and backticks (recursed into),
+#     ~ / $HOME / ${HOME} / $CREWLY_HOME expansion (not inside single quotes;
+#     ~ not inside double quotes). A word is a candidate path only when it
+#     starts with `/`, or contains `/` and is resolved against the call's cwd,
+#     and only when the whole word (or the value after `=`) is that path. A
+#     bare word (`cloud`, `credentials`, `api-token`) never matches, and a
+#     quoted sentence that mentions a path (a commit message) is one word
+#     that is not a path.
+#   - file tools: only argument fields whose NAME says path/file/dir
+#     (file_path, path, AbsolutePath, …), resolved against the cwd. Content
+#     fields (write_file / write_to_file bodies) are never read.
+#   - `security find-generic-password|find-internet-password|export|-i`
+#     in a command that names `crewly`, and any `security dump-keychain`.
+#
+# Deny contract:
+#   claude, codex, gemini  exit 2, reason on stderr (fed back to the model)
+#   antigravity            stdout {"decision":"deny","reason":"..."}, exit 0;
+#                          an allowed call prints NOTHING (agy reads `{}` and
+#                          a non-zero exit as deny)
+#
+# Fails open: no CREWLY_SESSION_NAME (the owner's own runtime), no node, no
+# paths file, unparsable input -> allowed (agy) / non-blocking error (others).
+#
+# Coverage limits: paths built at runtime ($(echo …), base64, globs, other
+# variables), a script the agent writes and then runs, an interpreter reading
+# a computed path. It is a speed bump, not a boundary: same OS user.
+
+set -u
+
+FORMAT="${1:-claude}"
+PATHS_FILE="${2:-${CREWLY_CREDENTIAL_GUARD_PATHS:-}}"
+PREFIX="credential-guard:"
+REASON_TAIL="Crewly credentials are not available to agents. Use the connector skills instead (docs-read, docs-comment, drive-read, sheets-read, gmail-search, ...) — they act for you without handing out a token. If a skill cannot do what you need, tell the owner instead of working around it."
+
+INPUT="$(cat)"
+
+# Owner's own runtime (no agent session): never judged.
+SESSION="${CREWLY_SESSION_NAME:-}"
+[ -z "$SESSION" ] && exit 0
+
+if [ -z "$PATHS_FILE" ] || [ ! -f "$PATHS_FILE" ]; then
+	echo "$PREFIX NO PATHS CHECKED — paths file missing (${PATHS_FILE:-<none>})" >&2
+	[ "$FORMAT" = "antigravity" ] && exit 0
+	exit 1
+fi
+
+if ! command -v node >/dev/null 2>&1; then
+	echo "$PREFIX node not found — nothing checked" >&2
+	[ "$FORMAT" = "antigravity" ] && exit 0
+	exit 1
+fi
+
+# The matcher prints the rule id of the first guarded path the call reads, or nothing.
+read -r -d '' MATCHER <<'JS'
+const fs = require('fs');
+const path = require('path');
+const [pathsFile] = process.argv.slice(1);
+let input = '';
+process.stdin.on('data', (c) => { input += c; });
+process.stdin.on('end', () => {
+  let o;
+  try { o = JSON.parse(input); } catch { return; }
+  let home = '';
+  const guarded = [];
+  for (const line of fs.readFileSync(pathsFile, 'utf8').split('\n')) {
+    const [kind, id, value] = line.split('\t');
+    if (kind === 'home') home = value;
+    else if (kind === 'abs' && id && value) guarded.push({ id, p: path.resolve(value) });
+  }
+  const HOME = process.env.HOME || '';
+  const CH = home || process.env.CREWLY_HOME || '';
+
+  const tool = String(o.tool_name || (o.toolCall && o.toolCall.name) || '');
+  const args = (o.tool_input || (o.toolCall && o.toolCall.args) || {});
+  const cwd = String(o.cwd || (args && args.Cwd) || (Array.isArray(o.workspacePaths) && o.workspacePaths[0]) || process.cwd());
+
+  const hit = (abs) => {
+    const p = path.resolve(abs);
+    for (const g of guarded) if (p === g.p || p.startsWith(g.p + '/')) return g.id;
+    return null;
+  };
+  const expandVars = (s) => s
+    .replace(/\$\{HOME\}|\$HOME(?![A-Za-z0-9_])/g, HOME)
+    .replace(/\$\{CREWLY_HOME\}|\$CREWLY_HOME(?![A-Za-z0-9_])/g, CH);
+  // bareOk: a path FIELD (file tools) — a bare name is a path, and ~ is
+  // expanded here. Shell words arrive already expanded by the tokeniser
+  // (a quoted ~ stays literal, as in a shell).
+  const asPath = (s, bareOk) => {
+    if (!s) return null;
+    if (bareOk && s.startsWith('~/')) s = HOME + s.slice(1);
+    if (s.startsWith('/')) return s;
+    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(s)) return null; // URL
+    if (s.includes('/') || bareOk) return path.resolve(cwd, s);
+    return null;
+  };
+
+  // ---- shell tokeniser ----
+  const OPS = new Set([';', '&', '|', '<', '>', '(', ')', '\n']);
+  function tokenize(cmd) {
+    const out = []; // { w: string|null (null = operator), q: bool quoted }
+    const subs = [];
+    let w = '', started = false, quotedAll = true, i = 0;
+    const push = () => { if (started) out.push({ w, q: quotedAll }); w = ''; started = false; quotedAll = true; };
+    const readSub = (openIdx) => { // $( ... ) with nesting
+      let depth = 1, j = openIdx;
+      while (j < cmd.length && depth > 0) { if (cmd[j] === '(') depth++; else if (cmd[j] === ')') depth--; j++; }
+      subs.push(cmd.slice(openIdx, j - 1));
+      return j;
+    };
+    while (i < cmd.length) {
+      const c = cmd[i];
+      if (c === '\\' && i + 1 < cmd.length) { w += cmd[i + 1]; started = true; quotedAll = false; i += 2; continue; }
+      if (c === "'") { const j = cmd.indexOf("'", i + 1); const end = j < 0 ? cmd.length : j; w += cmd.slice(i + 1, end); started = true; i = end + 1; continue; }
+      if (c === '"') {
+        let j = i + 1, seg = '';
+        while (j < cmd.length && cmd[j] !== '"') {
+          if (cmd[j] === '\\' && j + 1 < cmd.length) { seg += cmd[j + 1]; j += 2; continue; }
+          if (cmd[j] === '$' && cmd[j + 1] === '(') { j = readSub(j + 2); seg += '\u0000'; continue; }
+          if (cmd[j] === '`') { const k = cmd.indexOf('`', j + 1); const e = k < 0 ? cmd.length : k; subs.push(cmd.slice(j + 1, e)); seg += '\u0000'; j = e + 1; continue; }
+          seg += cmd[j]; j++;
+        }
+        w += expandVars(seg); started = true; i = j + 1; continue;
+      }
+      if (c === '$' && cmd[i + 1] === '(') { i = readSub(i + 2); w += '\u0000'; started = true; quotedAll = false; continue; }
+      if (c === '`') { const k = cmd.indexOf('`', i + 1); const e = k < 0 ? cmd.length : k; subs.push(cmd.slice(i + 1, e)); w += '\u0000'; started = true; quotedAll = false; i = e + 1; continue; }
+      if (/\s/.test(c) && c !== '\n') { push(); i++; continue; }
+      if (OPS.has(c)) { push(); out.push({ w: null }); i++; continue; }
+      // unquoted text: ~ at the start of a word, and variables
+      // ~ at the start of a word, or right after `=` / `:` (bash expands --opt=~/x too)
+      if (c === '~' && (!started || /[=:]$/.test(w)) && (cmd[i + 1] === '/' || i + 1 === cmd.length)) { w += HOME; started = true; quotedAll = false; i++; continue; }
+      if (c === '$') {
+        const m = /^\$\{(HOME|CREWLY_HOME)\}|^\$(HOME|CREWLY_HOME)(?![A-Za-z0-9_])/.exec(cmd.slice(i));
+        if (m) { w += (m[1] || m[2]) === 'HOME' ? HOME : CH; started = true; quotedAll = false; i += m[0].length; continue; }
+      }
+      w += c; started = true; quotedAll = false; i++;
+    }
+    push();
+    return { tokens: out, subs };
+  }
+
+  const SKIP = new Set(['sudo', 'command', 'env', 'nohup', 'time', 'xargs', 'exec', 'builtin']);
+  function checkCommand(cmd, depth) {
+    if (depth > 4) return null;
+    const { tokens, subs } = tokenize(cmd);
+    for (const s of subs) { const r = checkCommand(s, depth + 1); if (r) return r; }
+    // simple commands
+    let simple = [];
+    const cmds = [];
+    for (const t of tokens) { if (t.w === null) { if (simple.length) cmds.push(simple); simple = []; } else simple.push(t.w); }
+    if (simple.length) cmds.push(simple);
+    const lowerAll = cmd.toLowerCase();
+    for (const words of cmds) {
+      let k = 0;
+      while (k < words.length && (SKIP.has(words[k]) || /^[A-Za-z_][A-Za-z0-9_]*=/.test(words[k]))) k++;
+      const verb = (words[k] || '').split('/').pop();
+      const rest = words.slice(k + 1).map((x) => x.toLowerCase());
+      if (verb === 'security') {
+        if (rest.includes('dump-keychain')) return 'keychain';
+        if (rest.some((x) => ['find-generic-password', 'find-internet-password', 'export', '-i'].includes(x)) && lowerAll.includes('crewly')) return 'keychain';
+      }
+      for (const word of words) {
+        if (word.includes('\u0000')) continue; // contains a substitution: judged through the substitution
+        const cands = [word];
+        const eq = word.indexOf('=');
+        if (eq > 0) cands.push(word.slice(eq + 1));
+        for (const c of cands) {
+          if (/\s/.test(c)) continue; // a sentence, not a path
+          const p = asPath(c, false);
+          if (p) { const id = hit(p); if (id) return id; }
+        }
+      }
+    }
+    return null;
+  }
+
+  function checkPathFields(obj) {
+    if (!obj || typeof obj !== 'object') return null;
+    for (const [k, v] of Object.entries(obj)) {
+      if (!/path|file|dir/i.test(k)) continue; // never content fields
+      const vals = Array.isArray(v) ? v : [v];
+      for (const x of vals) {
+        if (typeof x !== 'string') continue;
+        const p = asPath(expandVars(x), true);
+        if (p) { const id = hit(p); if (id) return id; }
+      }
+    }
+    return null;
+  }
+
+  const shellCmd = typeof args.command === 'string' ? args.command : typeof args.CommandLine === 'string' ? args.CommandLine : null;
+  const isShell = /^(bash|run_shell_command|run_command|shell|exec_command)$/i.test(tool) || (shellCmd !== null && !/write|replace|edit/i.test(tool));
+  let id = null;
+  if (isShell && shellCmd !== null) id = checkCommand(shellCmd, 0);
+  if (!id && !/write|replace|edit|create/i.test(tool)) id = checkPathFields(args);
+  if (id) process.stdout.write(id);
+});
+JS
+
+MATCH_ID="$(printf '%s' "$INPUT" | node -e "$MATCHER" "$PATHS_FILE" 2>/dev/null)"
+MATCH_ID="$(printf '%s' "$MATCH_ID" | tr -cd 'A-Za-z0-9_-' | cut -c1-64)"
+
+[ -z "$MATCH_ID" ] && exit 0
+
+REASON="Blocked: this reads Crewly's own credentials (${MATCH_ID}). ${REASON_TAIL}"
+
+# ---- tell the backend (warning in its log; the owner hears once a day) ------
+API_URL="${CREWLY_API_URL:-http://localhost:${WEB_PORT:-8787}}"
+if command -v curl >/dev/null 2>&1; then
+	CURL_ARGS=(-s -o /dev/null --max-time 2 -X POST "$API_URL/api/agent-hooks"
+		-H "Content-Type: application/json"
+		-H "User-Agent: crewly-credential-guard/1"
+		-H "X-Agent-Session: $SESSION")
+	if [ -n "${CREWLY_AGENT_BADGE:-}" ]; then
+		CURL_ARGS+=(-H "X-Agent-Badge: $CREWLY_AGENT_BADGE")
+	fi
+	curl "${CURL_ARGS[@]}" --data "{\"event\":\"CredentialAccessBlocked\",\"rule\":\"$MATCH_ID\",\"runtime\":\"$(printf '%s' "$FORMAT" | tr -cd 'a-z')\"}" >/dev/null 2>&1 || true
+fi
+
+if [ "$FORMAT" = "antigravity" ]; then
+	ESCAPED="$(printf '%s' "$REASON" | sed -e 's/\\/\\\\/g' -e 's/"/\\"/g')"
+	printf '{"decision":"deny","reason":"%s"}\n' "$ESCAPED"
+	exit 0
+fi
+
+echo "$REASON" >&2
+exit 2

package/config/skills/agent/core/docs-comment/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: Docs Comment
+description: Handle feedback left as comments in a Google Doc — list comments and replies, reply, resolve, or add a comment (via the Google Workspace grant held by Crewly Cloud). Writes as the owner's Google account — say what you posted.
+version: 1.0.0
+category: productivity
+skillType: claude-skill
+assignableRoles:
+  - orchestrator
+  - team-leader
+  - developer
+  - operations
+  - ops
+  - sales
+  - support
+  - generalist
+triggers:
+  - comments in the doc
+  - google doc comments
+  - reply to the comment
+  - resolve the comment
+  - feedback in the doc
+  - add a comment to the doc
+tags:
+  - google
+  - docs
+  - comments
+execution:
+  type: script
+  script:
+    file: execute.sh
+    interpreter: bash
+    timeoutMs: 60000
+---
+
+# Docs Comment
+
+```bash
+bash execute.sh list    --doc "https://docs.google.com/document/d/1AbC…/edit"
+bash execute.sh list    --doc 1AbC… --include-resolved
+bash execute.sh reply   --doc 1AbC… --comment AAAB… --text "Updated the intro, see paragraph 2."
+bash execute.sh resolve --doc 1AbC… --comment AAAB… --text "Done in v2."
+bash execute.sh resolve --doc 1AbC… --comment AAAB…
+bash execute.sh add     --doc 1AbC… --text "Is this number from Q2?" --quote "grew 40%"
+```
+
+`--doc` takes a document id or its docs.google.com URL. `--account` picks a
+connected Google account (see below).
+
+## Working through feedback
+
+1. `list` the open comments. Each one has the text it is about (`quote`),
+   who wrote it and when, and any replies.
+2. Make the change the comment asks for (for example with `docs-write`), or
+   decide it needs the owner.
+3. `resolve` the comment with a one-line note of what changed, or `reply`
+   with a question if it is unclear. Do not resolve a comment you did not
+   address.
+
+Everything you post appears under the owner's Google name. Tell the owner
+what you replied to or resolved.
+
+## Output
+
+`list`:
+
+```json
+{"success":true,"docId":"1AbC…","count":1,"truncated":false,"comments":[{"id":"AAAB…","author":"Steve","createdTime":"2026-10-03T09:12:00.000Z","content":"Too long","quote":"In this document we…","anchor":"kix.x1","resolved":false,"replies":[{"id":"AAAC…","author":"Ella","createdTime":"…","content":"Trimmed."}]}]}
+```
+
+Resolved comments are left out unless you pass `--include-resolved`.
+`truncated: true` means the document has more than 500 comments and only the
+first 500 were read.
+
+`reply` / `resolve`:
+
+```json
+{"success":true,"action":"reply","docId":"1AbC…","commentId":"AAAB…","replyId":"AAAD…","content":"Updated the intro."}
+```
+
+`add`:
+
+```json
+{"success":true,"action":"add","docId":"1AbC…","commentId":"AAAE…","content":"Is this number from Q2?","quote":"grew 40%"}
+```
+
+## Comments you add are not anchored
+
+Google Docs does not show a comment created through the API as attached to
+text. `--quote` is sent to Google as the quoted text, but in the Docs UI the
+comment **may appear as a general (unanchored) comment** on the whole
+document. When the location matters, quote the passage in the comment text
+too, for example `--text "On 'grew 40%': is this Q2?"`.
+
+## Failures
+
+`{"success":false,"reason":"reauth_required",…}` (exit 1): the Google grant
+can read comments but not write them on this document. Reply, resolve and add
+on a document Crewly did not create need Google Drive edit access, which
+older connections do not include. Run `google-connect --product drive --channel <chat-channel-id>` to
+post a one-tap card for the owner, and tell them in one line what you will do
+once it is granted. Do not paste a link yourself.
+
+`{"success":false,"reason":"not_connected","hint":"…"}` (exit 1): Google
+Drive is not connected. Use `google-connect --product drive` the same way.
+
+`{"success":false,"reason":"not_permitted",…}` (exit 1): this Google
+connection belongs to someone else and is not shared with the person you are
+working for. Say so; do not try another account.
+
+`reason: "google_error"` with a 404 means the document id or comment id is
+wrong, or the account cannot see the document.
+
+## Choosing a Google account
+
+Several Google accounts can be connected at once. Without `--account` the call uses the default one (the first you connected, or whichever you marked default on the Connections page). Name one explicitly when it matters:
+
+```bash
+bash execute.sh list --doc 1AbC… --account work@company.com
+```
+
+The account must be connected *for this product* — Google consent is per product (Gmail / Calendar / Drive), so an account connected only for Calendar cannot read Drive.

package/config/skills/agent/core/docs-comment/execute.sh

@@ -0,0 +1,131 @@
+#!/bin/bash
+# =============================================================================
+# docs-comment — List, reply to, resolve or add comments in a Google Doc
+#
+# Backed by:
+#   GET  /api/google/docs/:id/comments[?includeResolved=1]
+#   POST /api/google/docs/:id/comments                     { text, quote? }
+#   POST /api/google/docs/:id/comments/:commentId/replies  { text }
+#   POST /api/google/docs/:id/comments/:commentId/resolve  { text? }
+#
+# Usage:
+#   bash execute.sh list    --doc <id|url> [--include-resolved]
+#   bash execute.sh reply   --doc <id|url> --comment <id> --text "…"
+#   bash execute.sh resolve --doc <id|url> --comment <id> [--text "…"]
+#   bash execute.sh add     --doc <id|url> --text "…" [--quote "exact text"]
+#   bash execute.sh '{"command":"list","doc":"<id>"}'
+# =============================================================================
+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 list    --doc <id|url> [--include-resolved]
+  bash execute.sh reply   --doc <id|url> --comment <id> --text "…"
+  bash execute.sh resolve --doc <id|url> --comment <id> [--text "…"]
+  bash execute.sh add     --doc <id|url> --text "…" [--quote "exact text in the doc"]
+  bash execute.sh '{"command":"reply","doc":"<id>","comment":"<id>","text":"…"}'
+
+Options:
+  --doc               Document id or docs.google.com URL
+  --comment           Comment id (from list)
+  --text              Reply / comment text (optional for resolve)
+  --quote             Exact document text the new comment is about (add only;
+                      Google Docs may still show it as an unanchored comment)
+  --include-resolved  list: include resolved comments too
+  --account           Which connected Google account to act as (default: your primary)
+  --help | -h         Show this help
+EOF_USAGE
+}
+
+fail_from() {
+  printf '%s' "$1" | jq -c '{success: false, reason: (.details.error // .details // .error // "unknown"), hint: (.details.hint // ""), message: (.details.message // "")}' 2>/dev/null \
+    || jq -n --arg r "$1" '{success: false, reason: $r}'
+  exit 1
+}
+
+uri() { jq -rn --arg v "$1" '$v|@uri'; }
+
+# api_call may print a one-line warning to stderr (no CREWLY_SESSION_NAME);
+# the backend answer is always the last line. On failure print the mapped
+# failure JSON (fail_from) and return 1.
+call() {
+  local out
+  out=$(api_call "$@" 2>&1) || { fail_from "$(printf '%s\n' "$out" | tail -n 1)"; }
+  printf '%s\n' "$out" | tail -n 1
+}
+
+INPUT_JSON=""
+COMMAND=""
+if [[ $# -gt 0 && ${1:0:1} == '{' ]]; then
+  INPUT_JSON="$1"
+  shift || true
+elif [[ $# -gt 0 && ${1:0:1} != '-' ]]; then
+  COMMAND="$1"
+  shift
+fi
+DOC=""; COMMENT=""; TEXT=""; TEXT_SET=0; QUOTE=""; INCLUDE_RESOLVED=0; ACCOUNT=""
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --doc|--id)         [ $# -ge 2 ] || error_exit "$1 requires a value";        DOC="$2";     shift 2 ;;
+    --comment)          [ $# -ge 2 ] || error_exit "--comment requires a value"; COMMENT="$2"; shift 2 ;;
+    --text)             [ $# -ge 2 ] || error_exit "--text requires a value";    TEXT="$2"; TEXT_SET=1; shift 2 ;;
+    --quote)            [ $# -ge 2 ] || error_exit "--quote requires a value";   QUOTE="$2";   shift 2 ;;
+    --include-resolved) INCLUDE_RESOLVED=1; shift ;;
+    --account)          [ $# -ge 2 ] || error_exit "--account requires a value"; ACCOUNT="$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 "$COMMAND" ] && COMMAND=$(printf '%s' "$INPUT" | jq -r '.command // .action // empty')
+  [ -z "$DOC" ]     && DOC=$(printf '%s' "$INPUT" | jq -r '.doc // .id // .documentId // empty')
+  [ -z "$COMMENT" ] && COMMENT=$(printf '%s' "$INPUT" | jq -r '.comment // .commentId // empty')
+  [ "$TEXT_SET" -eq 0 ] && TEXT=$(printf '%s' "$INPUT" | jq -r '.text // empty')
+  [ -z "$QUOTE" ]   && QUOTE=$(printf '%s' "$INPUT" | jq -r '.quote // empty')
+  [ "$INCLUDE_RESOLVED" -eq 0 ] && [ "$(printf '%s' "$INPUT" | jq -r '.includeResolved // false')" = "true" ] && INCLUDE_RESOLVED=1
+  [ -z "$ACCOUNT" ] && ACCOUNT=$(printf '%s' "$INPUT" | jq -r '.account // empty')
+fi
+# Route the call at one connected Google account; unset means the default.
+[ -n "$ACCOUNT" ] && export CREWLY_GOOGLE_ACCOUNT="$ACCOUNT"
+# Accept a full docs.google.com URL too.
+DOC=$(printf '%s' "$DOC" | sed -E 's#.*/document/d/([^/?]+).*#\1#')
+
+[ -n "$COMMAND" ] || error_exit "a command is required: list, reply, resolve or add (see --help)"
+require_param "doc (--doc)" "$DOC"
+BASE="/google/docs/$(uri "$DOC")/comments"
+
+case "$COMMAND" in
+  list)
+    QS=""; [ "$INCLUDE_RESOLVED" -eq 1 ] && QS="?includeResolved=1"
+    RESPONSE=$(call GET "${BASE}${QS}") || { printf '%s\n' "$RESPONSE"; exit 1; }
+    # Oversized answers come back as the output-cap envelope; pass it through.
+    if printf '%s' "$RESPONSE" | jq -e '.truncated == true and has("file")' >/dev/null 2>&1; then printf '%s\n' "$RESPONSE"; exit 0; fi
+    printf '%s' "$RESPONSE" | jq -c '{success: (.success // false), docId: .data.docId, count: (.data.comments | length), truncated: (.data.truncated // false), comments: .data.comments}'
+    ;;
+  reply)
+    require_param "comment (--comment)" "$COMMENT"
+    require_param "text (--text)" "$TEXT"
+    BODY=$(jq -cn --arg text "$TEXT" '{text: $text}')
+    RESPONSE=$(call POST "${BASE}/$(uri "$COMMENT")/replies" "$BODY") || { printf '%s\n' "$RESPONSE"; exit 1; }
+    printf '%s' "$RESPONSE" | jq -c '{success: (.success // false), action: "reply", docId: .data.docId, commentId: .data.commentId, replyId: .data.id, content: .data.content}'
+    ;;
+  resolve)
+    require_param "comment (--comment)" "$COMMENT"
+    BODY=$(jq -cn --arg text "$TEXT" 'if $text != "" then {text: $text} else {} end')
+    RESPONSE=$(call POST "${BASE}/$(uri "$COMMENT")/resolve" "$BODY") || { printf '%s\n' "$RESPONSE"; exit 1; }
+    printf '%s' "$RESPONSE" | jq -c '{success: (.success // false), action: "resolve", docId: .data.docId, commentId: .data.commentId, replyId: .data.id, content: (.data.content // ""), resolved: true}'
+    ;;
+  add)
+    require_param "text (--text)" "$TEXT"
+    BODY=$(jq -cn --arg text "$TEXT" --arg quote "$QUOTE" '{text: $text} + (if $quote != "" then {quote: $quote} else {} end)')
+    RESPONSE=$(call POST "${BASE}" "$BODY") || { printf '%s\n' "$RESPONSE"; exit 1; }
+    printf '%s' "$RESPONSE" | jq -c '{success: (.success // false), action: "add", docId: .data.docId, commentId: .data.id, content: .data.content} + (if .data.quote then {quote: .data.quote} else {} end)'
+    ;;
+  *)
+    error_exit "Unknown command: $COMMAND (expected list, reply, resolve or add)"
+    ;;
+esac

package/config/skills/agent/core/docs-comment/execute.test.sh

@@ -0,0 +1,105 @@
+#!/bin/bash
+# Tests for docs-comment — run with: bash execute.test.sh
+# Python HTTP stub as the backend; asserts the request the skill sends and
+# the JSON it prints. No Google call is made. 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=18831
+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'])
+COMMENT = {'id': 'c1', 'author': 'Steve', 'createdTime': 't0', 'content': 'Too long', 'quote': 'intro',
+           'resolved': False, 'replies': [{'id': 'r0', 'author': 'Ella', 'createdTime': 't1', 'content': 'Trimmed'}]}
+class H(BaseHTTPRequestHandler):
+    def _send(self, status, payload):
+        self.send_response(status); self.send_header('Content-Type', 'application/json'); self.end_headers()
+        self.wfile.write(json.dumps(payload).encode())
+    def _reply(self, method, data=None):
+        open(LOG, 'w').write(json.dumps({'method': method, 'path': self.path, 'body': data,
+                                         'account': self.headers.get('X-Google-Account')}))
+        if '/docs/narrow/' in self.path:
+            return self._send(403, {'success': False, 'error': 'reauth_required',
+                                    'message': 'Replying to or adding comments on this document needs Google Drive edit access, which this Google account has not granted yet.',
+                                    'hint': 'Ask the owner to reconnect Google Drive: run the google-connect skill with --product drive.'})
+        if method == 'GET':
+            return self._send(200, {'success': True, 'data': {'docId': 'd1', 'comments': [COMMENT], 'truncated': False}})
+        if self.path.endswith('/replies'):
+            return self._send(200, {'success': True, 'data': {'docId': 'd1', 'commentId': 'c1', 'id': 'r9', 'content': data['text']}})
+        if self.path.endswith('/resolve'):
+            return self._send(200, {'success': True, 'data': {'docId': 'd1', 'commentId': 'c1', 'id': 'r10', 'action': 'resolve', 'content': data.get('text', ''), 'resolved': True}})
+        out = {'docId': 'd1', 'id': 'c7', 'content': data['text'], 'resolved': False, 'replies': []}
+        if 'quote' in data: out['quote'] = data['quote']
+        return self._send(200, {'success': True, 'data': out})
+    def do_GET(self): self._reply('GET')
+    def do_POST(self):
+        n = int(self.headers.get('content-length', '0')); body = self.rfile.read(n).decode() if n else ''
+        self._reply('POST', json.loads(body or '{}'))
+    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; }
+req() { jq -r '.method + " " + .path + " " + (.body|tojson)' "$STUB_LOG"; }
+
+# list
+OUT=$(run list --doc "https://docs.google.com/document/d/d1/edit?tab=t.0")
+check "list: request" "$(req)" 'GET /api/google/docs/d1/comments null'
+check "list: output" "$(printf '%s' "$OUT" | jq -c '{success, docId, count, truncated, first: .comments[0].id, quote: .comments[0].quote, replies: (.comments[0].replies|length)}')" \
+  '{"success":true,"docId":"d1","count":1,"truncated":false,"first":"c1","quote":"intro","replies":1}'
+run list --doc d1 --include-resolved >/dev/null
+check "list: --include-resolved" "$(req)" 'GET /api/google/docs/d1/comments?includeResolved=1 null'
+
+# reply
+OUT=$(run reply --doc d1 --comment c1 --text "Fixed, see para 2")
+check "reply: request" "$(req)" 'POST /api/google/docs/d1/comments/c1/replies {"text":"Fixed, see para 2"}'
+check "reply: output" "$OUT" '{"success":true,"action":"reply","docId":"d1","commentId":"c1","replyId":"r9","content":"Fixed, see para 2"}'
+
+# resolve, with and without a message
+OUT=$(run resolve --doc d1 --comment c1 --text "Done")
+check "resolve: request" "$(req)" 'POST /api/google/docs/d1/comments/c1/resolve {"text":"Done"}'
+check "resolve: output" "$OUT" '{"success":true,"action":"resolve","docId":"d1","commentId":"c1","replyId":"r10","content":"Done","resolved":true}'
+run resolve --doc d1 --comment c1 >/dev/null
+check "resolve: no text" "$(req)" 'POST /api/google/docs/d1/comments/c1/resolve {}'
+
+# add, with and without a quote
+OUT=$(run add --doc d1 --text "Source?" --quote "grew 40%")
+check "add: request" "$(req)" 'POST /api/google/docs/d1/comments {"text":"Source?","quote":"grew 40%"}'
+check "add: output" "$OUT" '{"success":true,"action":"add","docId":"d1","commentId":"c7","content":"Source?","quote":"grew 40%"}'
+run add --doc d1 --text "General" >/dev/null
+check "add: no quote" "$(req)" 'POST /api/google/docs/d1/comments {"text":"General"}'
+
+# JSON input + --account
+run '{"command":"reply","doc":"d1","comment":"c1","text":"via json","account":"work@x.com"}' >/dev/null
+check "json input: request" "$(req)" 'POST /api/google/docs/d1/comments/c1/replies {"text":"via json"}'
+check "json input: account header" "$(jq -r '.account' "$STUB_LOG")" 'work@x.com'
+
+# reauth_required is passed through with its English hint, exit 1
+OUT=$(run reply --doc narrow --comment c1 --text "x"); CODE=$?
+check "reauth: exit code" "$CODE" "1"
+check "reauth: reason" "$(printf '%s' "$OUT" | jq -r '.reason')" "reauth_required"
+check "reauth: hint names the one-tap path" "$(printf '%s' "$OUT" | jq -r '.hint' | grep -c 'google-connect skill with --product drive')" "1"
+
+# argument validation (no request sent)
+check "no command" "$(run_err --doc d1 | grep -c 'command is required')" "1"
+check "unknown command" "$(run_err delete --doc d1 | grep -c 'Unknown command')" "1"
+check "reply needs --comment" "$(run_err reply --doc d1 --text x | grep -c 'comment')" "1"
+check "reply needs --text" "$(run_err reply --doc d1 --comment c1 | grep -c 'text')" "1"
+check "add needs --text" "$(run_err add --doc d1 | grep -c 'text')" "1"
+check "needs --doc" "$(run_err list | grep -c 'doc')" "1"
+
+echo "docs-comment: $PASS passed, $FAIL failed"
+[ "$FAIL" -eq 0 ]