@codefilabs/tq 0.0.2 → 0.1.1

package/scripts/tq-telegram-poll

@@ -5,14 +5,23 @@ export PATH="/opt/homebrew/bin:/usr/local/bin:$PATH"
 
 CONFIG_FILE="$HOME/.tq/config/message.yaml"
 OFFSET_FILE="$HOME/.tq/telegram-poll-offset"
+ORCHESTRATOR_SESSION="tq-orchestrator"
+DAEMON_MODE=0
+POLL_TIMEOUT=0
+
+if [[ "${1:-}" == "--daemon" ]]; then
+  DAEMON_MODE=1
+  POLL_TIMEOUT=30
+fi
 
 # --- Read config ---
 if [[ ! -f "$CONFIG_FILE" ]]; then
   exit 0
 fi
 
-CONFIG_SCRIPT=$(mktemp /tmp/tq-poll-config-XXXXXX.py)
-trap 'rm -f "$CONFIG_SCRIPT"' EXIT
+CONFIG_SCRIPT=$(mktemp /tmp/tq-poll-config-XXXXXX)
+PROCESS_SCRIPT=$(mktemp /tmp/tq-poll-process-XXXXXX)
+trap 'rm -f "$CONFIG_SCRIPT" "$PROCESS_SCRIPT"' EXIT
 
 cat > "$CONFIG_SCRIPT" <<'PYEOF'
 import sys, os, re, json
@@ -51,27 +60,6 @@ print(json.dumps({
 }))
 PYEOF
 
-CONFIG_JSON="$(python3 "$CONFIG_SCRIPT" "$CONFIG_FILE")"
-BOT_TOKEN="$(python3 -c "import sys,json; print(json.loads(sys.argv[1]).get('bot_token',''))" "$CONFIG_JSON")"
-USER_ID="$(python3 -c "import sys,json; print(json.loads(sys.argv[1]).get('user_id',''))" "$CONFIG_JSON")"
-
-if [[ -z "$BOT_TOKEN" || -z "$USER_ID" ]]; then
-  exit 0
-fi
-
-# --- Read offset ---
-OFFSET=0
-if [[ -f "$OFFSET_FILE" ]]; then
-  OFFSET="$(cat "$OFFSET_FILE")"
-fi
-
-# --- Fetch updates ---
-UPDATES="$(curl -s "https://api.telegram.org/bot${BOT_TOKEN}/getUpdates?offset=${OFFSET}&limit=10&timeout=0" 2>&1)"
-
-# --- Process updates ---
-PROCESS_SCRIPT=$(mktemp /tmp/tq-poll-process-XXXXXX.py)
-trap 'rm -f "$CONFIG_SCRIPT" "$PROCESS_SCRIPT"' EXIT
-
 cat > "$PROCESS_SCRIPT" <<'PYEOF'
 import sys, json
 
@@ -100,8 +88,11 @@ for update in results:
     if text:
         chat_id = msg['chat']['id']
         message_id = msg['message_id']
-        # Output as tab-separated: chat_id<TAB>message_id<TAB>text
-        messages.append(f"{chat_id}\t{message_id}\t{text}")
+        # Extract reply_to_message_id if present
+        reply_to = msg.get('reply_to_message', {}).get('message_id', '')
+        # Output: chat_id<TAB>message_id<TAB>reply_to<TAB>text
+        # Use '-' placeholder for empty reply_to (bash read collapses consecutive tabs)
+        messages.append(f"{chat_id}\t{message_id}\t{reply_to or '-'}\t{text}")
 
 if new_offset is not None:
     with open(offset_file, 'w') as f:
@@ -111,19 +102,210 @@ for m in messages:
     print(m)
 PYEOF
 
-MESSAGES="$(python3 "$PROCESS_SCRIPT" "$UPDATES" "$USER_ID" "$OFFSET_FILE")"
+CONFIG_JSON="$(python3 "$CONFIG_SCRIPT" "$CONFIG_FILE")"
+BOT_TOKEN="$(python3 -c "import sys,json; print(json.loads(sys.argv[1]).get('bot_token',''))" "$CONFIG_JSON")"
+USER_ID="$(python3 -c "import sys,json; print(json.loads(sys.argv[1]).get('user_id',''))" "$CONFIG_JSON")"
+
+if [[ -z "$BOT_TOKEN" || -z "$USER_ID" ]]; then
+  exit 0
+fi
+
+# --- Read offset ---
+OFFSET=0
+if [[ -f "$OFFSET_FILE" ]]; then
+  OFFSET="$(cat "$OFFSET_FILE")"
+fi
+
+# --- Handle Telegram commands ---
+handle_command() {
+  local cmd="$1"
+  local chat_id="$2"
+
+  case "$cmd" in
+    /converse|/converse\ *)
+      if [[ "$ORCHESTRATOR_ACTIVE" == "1" ]]; then
+        curl -s -X POST "https://api.telegram.org/bot${BOT_TOKEN}/sendMessage" \
+          -d "chat_id=${chat_id}" \
+          --data-urlencode "text=Orchestrator already running. Just send messages — they'll be routed automatically." \
+          > /dev/null 2>&1 || true
+      else
+        if command -v tq-converse &>/dev/null; then
+          tq-converse start 2>&1 || true
+          ORCHESTRATOR_ACTIVE=1
+          curl -s -X POST "https://api.telegram.org/bot${BOT_TOKEN}/sendMessage" \
+            -d "chat_id=${chat_id}" \
+            --data-urlencode "text=Orchestrator started. Send messages and they'll be routed to the right conversation." \
+            > /dev/null 2>&1 || true
+        fi
+      fi
+      return 0
+      ;;
+    /stop)
+      if command -v tq-converse &>/dev/null; then
+        tq-converse stop 2>&1 || true
+        ORCHESTRATOR_ACTIVE=0
+        curl -s -X POST "https://api.telegram.org/bot${BOT_TOKEN}/sendMessage" \
+          -d "chat_id=${chat_id}" \
+          --data-urlencode "text=Orchestrator stopped." \
+          > /dev/null 2>&1 || true
+      fi
+      return 0
+      ;;
+    /stop\ *)
+      local SLUG="${cmd#/stop }"
+      if command -v tq-converse &>/dev/null; then
+        tq-converse stop "$SLUG" 2>&1 || true
+        curl -s -X POST "https://api.telegram.org/bot${BOT_TOKEN}/sendMessage" \
+          -d "chat_id=${chat_id}" \
+          --data-urlencode "text=Session '$SLUG' stopped." \
+          > /dev/null 2>&1 || true
+      fi
+      return 0
+      ;;
+    /status)
+      if command -v tq-converse &>/dev/null; then
+        local STATUS_TEXT
+        STATUS_TEXT="$(tq-converse status 2>&1 || true)"
+        curl -s -X POST "https://api.telegram.org/bot${BOT_TOKEN}/sendMessage" \
+          -d "chat_id=${chat_id}" \
+          --data-urlencode "text=${STATUS_TEXT}" \
+          > /dev/null 2>&1 || true
+      fi
+      return 0
+      ;;
+    /list)
+      if command -v tq-converse &>/dev/null; then
+        local LIST_TEXT
+        LIST_TEXT="$(tq-converse list 2>&1 || true)"
+        curl -s -X POST "https://api.telegram.org/bot${BOT_TOKEN}/sendMessage" \
+          -d "chat_id=${chat_id}" \
+          --data-urlencode "text=${LIST_TEXT}" \
+          > /dev/null 2>&1 || true
+      fi
+      return 0
+      ;;
+  esac
+  return 1
+}
+
+# --- poll_once: fetch and process a single batch of updates ---
+poll_once() {
+  local UPDATES MESSAGES
+
+  UPDATES="$(curl -s --max-time $((POLL_TIMEOUT + 10)) "https://api.telegram.org/bot${BOT_TOKEN}/getUpdates?offset=${OFFSET}&limit=10&timeout=${POLL_TIMEOUT}" 2>&1)"
+
+  MESSAGES="$(python3 "$PROCESS_SCRIPT" "$UPDATES" "$USER_ID" "$OFFSET_FILE")"
+
+  # Re-read offset (python may have updated it)
+  if [[ -f "$OFFSET_FILE" ]]; then
+    OFFSET="$(cat "$OFFSET_FILE")"
+  fi
+
+  if [[ -z "$MESSAGES" ]]; then
+    return 0
+  fi
+
+  # Check if orchestrator is running
+  ORCHESTRATOR_ACTIVE=0
+  if tmux has-session -t "$ORCHESTRATOR_SESSION" 2>/dev/null; then
+    ORCHESTRATOR_ACTIVE=1
+  fi
+
+  mkdir -p "$HOME/.tq/workspace"
 
-# --- Spawn tq --prompt for each message ---
-mkdir -p "$HOME/.tq/workspace"
+  while IFS=$'\t' read -r CHAT_ID MSG_ID REPLY_TO MSG; do
+    if [[ -z "$MSG" ]]; then
+      continue
+    fi
+
+    echo "[tq-telegram-poll] message: ${MSG:0:60}"
 
-while IFS=$'\t' read -r CHAT_ID MSG_ID MSG; do
-  if [[ -n "$MSG" ]]; then
-    echo "[tq-telegram-poll] prompt: ${MSG:0:60}"
     # React with 👀 to acknowledge receipt
     curl -s -X POST "https://api.telegram.org/bot${BOT_TOKEN}/setMessageReaction" \
       -H "Content-Type: application/json" \
       --data-raw "{\"chat_id\":${CHAT_ID},\"message_id\":${MSG_ID},\"reaction\":[{\"type\":\"emoji\",\"emoji\":\"👀\"}]}" \
       > /dev/null 2>&1 || true
-    tq --prompt "$MSG"
-  fi
-done <<< "$MESSAGES"
+
+    # Check for Telegram commands first
+    if [[ "$MSG" == /* ]]; then
+      if handle_command "$MSG" "$CHAT_ID"; then
+        continue
+      fi
+    fi
+
+    # --- Routing logic (3-tier) ---
+
+    # Store the latest message ID for reply threading
+    echo "$MSG_ID" > "$HOME/.tq/conversations/latest-msg-id" 2>/dev/null || true
+    echo "$CHAT_ID" > "$HOME/.tq/conversations/latest-chat-id" 2>/dev/null || true
+
+    ROUTED=0
+
+    # Normalize placeholder
+    [[ "$REPLY_TO" == "-" ]] && REPLY_TO=""
+
+    # Tier 1: Telegram reply → deterministic routing via registry
+    if [[ -n "$REPLY_TO" && "$ORCHESTRATOR_ACTIVE" == "1" ]]; then
+      SLUG="$(tq-converse lookup-msg "$REPLY_TO" 2>/dev/null || true)"
+      if [[ -n "$SLUG" ]]; then
+        CHILD_SESSION="tq-conv-${SLUG}"
+        if tmux has-session -t "$CHILD_SESSION" 2>/dev/null; then
+          echo "[tq-telegram-poll] reply-routing to: $SLUG (via msg $REPLY_TO)"
+          tq-converse track-msg "$SLUG" "$MSG_ID"
+          # Store msg_id for this session's reply threading
+          echo "$MSG_ID" > "$HOME/.tq/conversations/sessions/$SLUG/reply-to-msg-id" 2>/dev/null || true
+          tq-converse route "$SLUG" "$MSG"
+          ROUTED=1
+        fi
+      fi
+    fi
+
+    # Tier 2: Explicit #slug prefix → deterministic routing
+    if [[ "$ROUTED" == "0" && "$MSG" == \#* && "$ORCHESTRATOR_ACTIVE" == "1" ]]; then
+      # Extract slug from #slug-name prefix
+      SLUG="$(echo "$MSG" | sed 's/^#\([a-z0-9-]*\).*/\1/')"
+      ACTUAL_MSG="$(echo "$MSG" | sed 's/^#[a-z0-9-]* *//')"
+      if [[ -n "$SLUG" && -n "$ACTUAL_MSG" ]]; then
+        CHILD_SESSION="tq-conv-${SLUG}"
+        if tmux has-session -t "$CHILD_SESSION" 2>/dev/null; then
+          echo "[tq-telegram-poll] explicit routing to: $SLUG"
+          tq-converse track-msg "$SLUG" "$MSG_ID"
+          echo "$MSG_ID" > "$HOME/.tq/conversations/sessions/$SLUG/reply-to-msg-id" 2>/dev/null || true
+          tq-converse route "$SLUG" "$ACTUAL_MSG"
+          ROUTED=1
+        fi
+      fi
+    fi
+
+    # Tier 3: Orchestrator routing (smart, Claude-powered)
+    if [[ "$ROUTED" == "0" && "$ORCHESTRATOR_ACTIVE" == "1" ]]; then
+      echo "[tq-telegram-poll] routing via orchestrator"
+      # Format message with metadata for the orchestrator
+      FORMATTED_MSG="[tq-msg msg_id=${MSG_ID} chat_id=${CHAT_ID}"
+      if [[ -n "$REPLY_TO" ]]; then
+        FORMATTED_MSG="${FORMATTED_MSG} reply_to=${REPLY_TO}"
+      fi
+      FORMATTED_MSG="${FORMATTED_MSG}]
+${MSG}"
+      tq-converse send "$FORMATTED_MSG"
+      ROUTED=1
+    fi
+
+    # Fallback: no orchestrator — spawn one-off task (legacy behavior)
+    if [[ "$ROUTED" == "0" ]]; then
+      echo "[tq-telegram-poll] no orchestrator — spawning one-off task"
+      tq --no-chrome --prompt "$MSG"
+    fi
+
+  done <<< "$MESSAGES" || true
+}
+
+# --- Main: single run or daemon loop ---
+if [[ "$DAEMON_MODE" == "1" ]]; then
+  echo "[tq-telegram-poll] daemon started (long-poll timeout=${POLL_TIMEOUT}s)"
+  while true; do
+    poll_once || true
+  done
+else
+  poll_once
+fi

package/skills/tq/SKILL.md

@@ -3,10 +3,11 @@ name: tq
 description: >
   This skill should be used when the user asks to "add to queue", "run queue", "queue these tasks",
   "schedule with tq", "tq status", "check task queue", "create a tq queue", "set up cron for tq",
-  "run claude in background", "batch prompts in tmux", or wants to manage Claude prompts running
-  in tmux sessions via the tq CLI tool. Triggers on phrases like "queue", "tq", "task queue",
-  "tmux queue", "scheduled claude tasks".
-version: 1.0.0
+  "run claude in background", "batch prompts in tmux", "start a conversation", "converse via telegram",
+  "telegram conversation mode", or wants to manage Claude prompts running in tmux sessions via the
+  tq CLI tool. Triggers on phrases like "queue", "tq", "task queue", "tmux queue", "scheduled claude tasks",
+  "conversation mode", "telegram chat", "converse".
+version: 1.1.0
 ---
 
 # tq — Claude Task Queue Runner
@@ -17,8 +18,9 @@ Installed to PATH via `/install`: `/opt/homebrew/bin/tq`
 
 ## Overview
 
-tq batches Claude prompts into YAML queue files and spawns each as an independent tmux session.
-Tasks are idempotent — running `tq` again skips `done` and live `running` tasks.
+tq manages Claude Code sessions via tmux in two modes:
+1. **Queue mode** — batches prompts into YAML queue files, spawns each as an independent tmux session. Idempotent — running `tq` again skips `done` and live `running` tasks.
+2. **Conversation mode** — persistent interactive Claude Code sessions orchestrated via Telegram. An orchestrator routes messages to the right conversation, creating new sessions or resuming existing ones.
 
 ## Queue File Format
 
@@ -59,6 +61,9 @@ Statuses: `pending` → `running` → `done`
 | `/jobs [filter]` | List all scheduled tq cron jobs |
 | `/health [queue]` | System-wide diagnostics |
 | `/install` | Symlink tq binaries to PATH |
+| `/converse [start\|stop\|status]` | Manage Telegram conversation sessions |
+| `/tq-reply` | Send response back to Telegram (conversation mode) |
+| `/setup-telegram` | Configure Telegram bot token and notifications |
 
 ## CLI Usage
 
@@ -102,6 +107,37 @@ The Claude extension stores the browser name as `bridgeDisplayName` in the exten
 - Right-click the Claude extension icon in the Chrome toolbar → **Options**
 - Or open the sidepanel and look for a settings/gear icon with a name field
 
+## Conversation Mode
+
+Start an orchestrator: `tq-converse start` or send `/converse` from Telegram.
+
+The orchestrator routes incoming Telegram messages to the appropriate conversation session:
+- Telegram reply to a known message → routes to that session automatically
+- `#slug message` → routes to the named session
+- New topic → orchestrator spawns a new session with a descriptive slug
+
+Each conversation is a persistent Claude Code interactive session in its own tmux window.
+Child sessions use `/tq-reply` to send responses back to Telegram as threaded replies.
+
+### Conversation CLI
+
+```bash
+tq-converse start                         # start orchestrator
+tq-converse spawn <slug> --cwd <dir>      # new conversation session
+tq-converse route <slug> <message>        # send to a session
+tq-converse list                          # list active sessions
+tq-converse stop [<slug>]                 # stop session or orchestrator
+```
+
+### Telegram Commands
+
+| Command | Purpose |
+|---------|---------|
+| `/converse` | Start the orchestrator |
+| `/stop [slug]` | Stop orchestrator or a specific session |
+| `/status` | Show all sessions |
+| `/list` | List active conversations |
+
 ## Additional Resources
 
 - **`references/session-naming.md`** — Session/window name generation algorithm and examples

package/skills/tq/references/session-naming.md

@@ -48,3 +48,19 @@ WINDOW="$(echo "$PROMPT" | awk '{print $1" "$2}' \
 - Epoch suffix prevents collision when the same prompt is re-queued after a reset
 - tmux session names must not contain `.` or `:` — the character replacement handles this
 - The `-` separator between base and epoch is always present; if the base ends with `-`, it gets stripped first to avoid `--`
+
+## Conversation Mode Session Names
+
+Conversation sessions use a different naming scheme — slug-based, no epoch suffix:
+
+| Type | Pattern | Example |
+|------|---------|---------|
+| Orchestrator | `tq-orchestrator` (fixed) | `tq-orchestrator` |
+| Child session | `tq-conv-<slug>` | `tq-conv-fix-auth` |
+| Child window | `<slug>` | `fix-auth` |
+
+Slugs are short kebab-case names (2-4 words) chosen by the orchestrator Claude when a
+new conversation is created. Examples: `fix-auth-bug`, `refactor-api`, `update-docs`.
+
+Since there is no epoch suffix, conversation session names are unique by slug. Starting
+a session with an already-active slug will reuse the existing session.