agent-messenger 1.15.0 → 2.0.0

package/skills/agent-line/references/authentication.md

@@ -0,0 +1,297 @@
+# Authentication Guide
+
+## Overview
+
+agent-line supports three authentication methods:
+
+1. **QR code login** (recommended) — scan a QR code with the LINE mobile app. No email or password needed.
+2. **Email/password login** — uses your LINE account credentials. May still require PIN verification on your phone.
+3. **Token login** — directly authenticates with an existing auth token.
+
+All methods register the CLI as a secondary device by default (ANDROIDSECONDARY), so your phone and desktop sessions stay active.
+
+## Method 1: QR Code Login
+
+### How It Works
+
+The QR code flow uses LINE's secondary device registration API. This is the same mechanism real secondary devices use.
+
+1. **Request QR session** from LINE's server
+2. A QR code URL is generated and opened in your browser (also printed in the terminal)
+3. **Scan the QR code** with the LINE mobile app
+4. LINE may display a **PIN code** — enter it on your phone to confirm
+5. The CLI polls until you confirm, then receives an auth token
+6. Profile is fetched and credentials are stored
+
+### Interactive Login
+
+```bash
+agent-line auth login
+```
+
+The CLI opens the QR code in your default browser and prints an ASCII version in the terminal as a fallback.
+
+### Non-Interactive Mode (AI Agents)
+
+QR code login requires a TTY. When running outside an interactive terminal, the CLI returns:
+
+```json
+{
+  "next_action": "run_interactive",
+  "message": "QR code login requires an interactive terminal. Run agent-line auth login in a terminal with TTY support."
+}
+```
+
+For non-interactive environments, use email/password or token login instead.
+
+## Method 2: Email/Password Login
+
+### How It Works
+
+1. **Send credentials** (email + password) to LINE's authentication API
+2. LINE may require **PIN verification** — a PIN is displayed in the terminal
+3. Enter the PIN on your phone when prompted
+4. After verification, the CLI receives an auth token
+5. Profile is fetched and credentials are stored
+
+### Usage
+
+```bash
+agent-line auth login --email user@example.com --password mypass
+```
+
+Response types:
+
+**Success:**
+```json
+{
+  "authenticated": true,
+  "account_id": "u1a2b3c4d5e6f7a8b9c0",
+  "display_name": "Alice",
+  "device": "ANDROIDSECONDARY"
+}
+```
+
+**PIN required:**
+
+The CLI displays the PIN in stderr and waits for confirmation:
+
+```
+Enter this PIN in the LINE mobile app: 123456
+```
+
+The CLI automatically polls for confirmation. Wait for it to complete.
+
+**Login failed:**
+```json
+{
+  "error": "login_email_failed",
+  "message": "Login failed"
+}
+```
+
+Check email/password and try again.
+
+## Method 3: Token Login
+
+### How It Works
+
+1. **Authenticate directly** with an existing auth token
+2. The CLI verifies the token by fetching your profile
+3. Credentials are stored with the profile information
+
+### Usage
+
+```bash
+agent-line auth login --token <auth-token>
+```
+
+**Success:**
+```json
+{
+  "authenticated": true,
+  "account_id": "u1a2b3c4d5e6f7a8b9c0",
+  "display_name": "Alice",
+  "device": "ANDROIDSECONDARY"
+}
+```
+
+This is useful when you already have a valid auth token from another source or a previous session.
+
+## Device Types
+
+The `--device` flag controls which device slot the CLI occupies:
+
+| Device           | Type      | V3 Support | Side Effect                              |
+| ---------------- | --------- | ---------- | ---------------------------------------- |
+| ANDROIDSECONDARY | Secondary | Yes        | Coexists with all sessions (default)     |
+| IOSIPAD          | Secondary | No         | Coexists with all sessions               |
+| DESKTOPMAC       | Primary   | Yes        | Replaces existing macOS desktop session  |
+| DESKTOPWIN       | Primary   | Yes        | Replaces existing Windows desktop session|
+
+```bash
+# Default: ANDROIDSECONDARY
+agent-line auth login
+
+# Use iPad slot
+agent-line auth login --device IOSIPAD
+
+# Replace macOS desktop session
+agent-line auth login --device DESKTOPMAC
+```
+
+**Recommendation**: Stick with ANDROIDSECONDARY unless you have a specific reason to use another device type. It coexists with all other sessions and supports the latest protocol version.
+
+## Credential Storage
+
+### Location
+
+```
+~/.config/agent-messenger/line-credentials.json
+```
+
+### Format
+
+```json
+{
+  "current_account": "u1a2b3c4d5e6f7a8b9c0",
+  "accounts": {
+    "u1a2b3c4d5e6f7a8b9c0": {
+      "account_id": "u1a2b3c4d5e6f7a8b9c0",
+      "auth_token": "eyJhbGciOiJIUzI1NiIs...",
+      "device": "ANDROIDSECONDARY",
+      "display_name": "Alice",
+      "created_at": "2025-01-15T10:30:00.000Z",
+      "updated_at": "2025-01-15T10:30:00.000Z"
+    }
+  }
+}
+```
+
+### Security
+
+- File permissions: `0600` (owner read/write only)
+- Tokens are stored in plaintext
+- Keep this file secure — it grants access to your LINE account
+- Never commit to version control
+
+### E2EE Key Storage
+
+E2EE (Letter Sealing) keys are stored separately:
+
+```
+~/.config/agent-messenger/line-storage/<account-id>.json
+```
+
+These keys are managed automatically by the underlying LINE client library.
+
+## Authentication Status
+
+Check current auth state:
+
+```bash
+agent-line auth status
+```
+
+Output when authenticated:
+
+```json
+{
+  "account_id": "u1a2b3c4d5e6f7a8b9c0",
+  "device": "ANDROIDSECONDARY",
+  "display_name": "Alice",
+  "created_at": "2025-01-15T10:30:00.000Z",
+  "updated_at": "2025-01-15T10:30:00.000Z"
+}
+```
+
+Output when not authenticated:
+
+```json
+{
+  "error": "No LINE account configured"
+}
+```
+
+## Multi-Account Support
+
+The CLI supports multiple LINE accounts. Each account is stored by its MID.
+
+```bash
+# List all stored accounts
+agent-line auth list
+
+# Switch active account
+agent-line auth use u1a2b3c4d5e6f7a8b9c0
+
+# Check which account is active
+agent-line auth status
+
+# Remove a specific account
+agent-line auth logout u1a2b3c4d5e6f7a8b9c0
+
+# Remove all accounts
+agent-line auth logout
+```
+
+## Logout
+
+Remove stored credentials:
+
+```bash
+# Remove all accounts
+agent-line auth logout
+
+# Remove specific account
+agent-line auth logout u1a2b3c4d5e6f7a8b9c0
+```
+
+## Token Lifecycle
+
+### When Tokens Expire
+
+LINE auth tokens can expire or be invalidated when:
+
+- You change your LINE password
+- You log out from all devices in the LINE app
+- The token naturally expires
+- LINE's server revokes the session
+
+### Re-authentication
+
+If commands start failing with auth errors:
+
+```bash
+# Login again via QR code
+agent-line auth login
+
+# Or re-login with email/password
+agent-line auth login --email user@example.com --password mypass
+
+# Or use a fresh token
+agent-line auth login --token <new-token>
+
+# Verify it worked
+agent-line auth status
+```
+
+## Security Considerations
+
+### What agent-line Can Access
+
+With stored credentials, agent-line can:
+
+- List your chat rooms (DMs, groups, rooms)
+- Read messages in any chat you're part of
+- Send messages as you
+- See chat member names and MIDs
+- View your profile and friends list
+
+### What agent-line Cannot Do
+
+- Access chats you're not a member of
+- Create or delete chat rooms
+- Upload files or media
+- Add or remove friends
+- Access LINE Pay, games, or other services
+- Modify your profile or settings

package/skills/agent-line/references/common-patterns.md

@@ -0,0 +1,355 @@
+# Common Patterns
+
+## Overview
+
+This guide covers typical workflows for AI agents interacting with LINE using agent-line.
+
+## Pattern 1: Send a Simple Message
+
+**Use case**: Post a message to a chat room
+
+```bash
+#!/bin/bash
+
+CHAT_ID="c7a8b9c0d1e2f3a4b5c6d7e8"
+
+# Direct approach
+agent-line message send "$CHAT_ID" "Deployment completed successfully!"
+
+# With error handling
+RESULT=$(agent-line message send "$CHAT_ID" "Hello world")
+SUCCESS=$(echo "$RESULT" | jq -r '.success')
+if [ "$SUCCESS" = "true" ]; then
+  echo "Message sent!"
+else
+  echo "Failed: $(echo "$RESULT" | jq -r '.error // "Unknown error"')"
+  exit 1
+fi
+```
+
+**When to use**: Simple one-off messages where you know the chat ID.
+
+**Note**: You must know the chat ID (MID). Use `agent-line chat list` to discover chat IDs.
+
+## Pattern 2: Discover Chat Rooms
+
+**Use case**: Find the right chat room to send a message to
+
+```bash
+#!/bin/bash
+
+# List all chats sorted by recent activity
+CHATS=$(agent-line chat list)
+
+# Find a specific chat by display name (works for DMs and groups)
+TARGET_CHAT=$(echo "$CHATS" | jq -r '.[] | select(.display_name | contains("Alice")) | .chat_id')
+
+if [ -z "$TARGET_CHAT" ]; then
+  echo "Chat not found"
+  exit 1
+fi
+
+echo "Found chat: $TARGET_CHAT"
+agent-line message send "$TARGET_CHAT" "Hey Alice!"
+```
+
+**When to use**: First time interacting with a chat, or when the user references a chat by name.
+
+## Pattern 3: Read Recent Messages
+
+**Use case**: Catch up on what happened in a chat
+
+```bash
+#!/bin/bash
+
+CHAT_ID="c7a8b9c0d1e2f3a4b5c6d7e8"
+
+# Get last 50 messages
+MESSAGES=$(agent-line message list "$CHAT_ID" -n 50)
+
+# Display summary
+MSG_COUNT=$(echo "$MESSAGES" | jq 'length')
+echo "Found $MSG_COUNT messages"
+
+# Show messages
+echo "$MESSAGES" | jq -r '.[] | "\(.author_id): \(.text // "[non-text]")"'
+```
+
+**When to use**: Context gathering, summarizing conversations, catching up on missed messages.
+
+## Pattern 4: Monitor for New Messages
+
+**Use case**: Watch a chat room and respond to new messages using the SDK
+
+```typescript
+import { LineClient } from 'agent-messenger/line'
+
+const client = await new LineClient().login()
+try {
+  const chatId = 'c7a8b9c0d1e2f3a4b5c6d7e8'
+  let lastMessageId = ''
+
+  // Poll for new messages
+  setInterval(async () => {
+    const messages = await client.getMessages(chatId, { count: 5 })
+    const latest = messages[messages.length - 1]
+    if (!latest || latest.message_id === lastMessageId) return
+
+    lastMessageId = latest.message_id
+    console.log(`New message from ${latest.author_id}: ${latest.text}`)
+
+    // Process and respond
+    if (latest.text?.includes('ping')) {
+      await client.sendMessage(chatId, 'pong!')
+    }
+  }, 10_000)
+} catch (error) {
+  console.error(error)
+} finally {
+  client.close()
+}
+```
+
+**When to use**: Quick scripts that only need to check for new messages periodically.
+
+**Limitations**: Polling-based, not real-time. Use reasonable intervals (10s+) to avoid rate limiting. For real-time events, use the LineListener (see Pattern 4b).
+
+## Pattern 4b: Real-Time Message Listening (SDK)
+
+**Use case**: React to incoming messages in real-time using the SDK
+
+```typescript
+import { LineClient } from 'agent-messenger/line'
+import { LineListener } from 'agent-messenger/line'
+
+const client = new LineClient()
+const listener = new LineListener(client)
+
+listener.on('connected', (info) => {
+  console.log(`Connected as ${info.account_id}`)
+})
+
+listener.on('message', (event) => {
+  console.log(`[${event.chat_id}] ${event.author_id}: ${event.text}`)
+})
+
+listener.on('error', (error) => {
+  console.error('Listener error:', error.message)
+})
+
+listener.on('disconnected', () => {
+  console.log('Disconnected — will auto-reconnect')
+})
+
+await listener.start()
+
+// Stop when done:
+// listener.stop()
+// client.close()
+```
+
+**When to use**: Building bots, automations, or real-time integrations that need instant message delivery.
+
+**Features**: Auto-reconnects with exponential backoff, typed events, AbortController-based clean shutdown.
+
+## Pattern 5: Get User Profile
+
+**Use case**: Retrieve your own LINE profile information
+
+```bash
+#!/bin/bash
+
+# Get profile
+PROFILE=$(agent-line profile)
+
+# Extract fields
+DISPLAY_NAME=$(echo "$PROFILE" | jq -r '.display_name')
+MID=$(echo "$PROFILE" | jq -r '.mid')
+STATUS=$(echo "$PROFILE" | jq -r '.status_message // "No status"')
+
+echo "Name: $DISPLAY_NAME"
+echo "MID: $MID"
+echo "Status: $STATUS"
+```
+
+**When to use**: Verifying which account is active, getting your own MID for filtering messages.
+
+## Pattern 6: List Friends
+
+**Use case**: Discover contacts and their MIDs
+
+```bash
+#!/bin/bash
+
+# Get all friends
+FRIENDS=$(agent-line friend list)
+
+# Count friends
+FRIEND_COUNT=$(echo "$FRIENDS" | jq 'length')
+echo "You have $FRIEND_COUNT friends"
+
+# Find a specific friend
+FRIEND=$(echo "$FRIENDS" | jq -r '.[] | select(.display_name | contains("Bob"))')
+if [ -n "$FRIEND" ]; then
+  FRIEND_MID=$(echo "$FRIEND" | jq -r '.mid')
+  echo "Bob's MID: $FRIEND_MID"
+
+  # Send a DM
+  agent-line message send "$FRIEND_MID" "Hey Bob!"
+fi
+```
+
+**When to use**: Finding a user's MID to start a DM, building a contact directory.
+
+## Pattern 7: Multi-Account Management
+
+**Use case**: Switch between multiple LINE accounts
+
+```bash
+#!/bin/bash
+
+# List all stored accounts
+ACCOUNTS=$(agent-line auth list)
+echo "Stored accounts:"
+echo "$ACCOUNTS" | jq -r '.[] | "  \(.account_id) — \(.display_name // "Unknown")"'
+
+# Switch to a specific account
+agent-line auth use u1a2b3c4d5e6f7a8b9c0
+
+# Verify the switch
+STATUS=$(agent-line auth status)
+CURRENT=$(echo "$STATUS" | jq -r '.display_name // .account_id')
+echo "Now using: $CURRENT"
+
+# Send a message as this account
+agent-line message send c7a8b9c0d1e2f3a4b5c6d7e8 "Hello from account 1!"
+
+# Switch to another account
+agent-line auth use u9f8e7d6c5b4a3f2e1d0
+agent-line message send c7a8b9c0d1e2f3a4b5c6d7e8 "Hello from account 2!"
+```
+
+**When to use**: Managing multiple LINE identities, testing with different accounts.
+
+## Best Practices
+
+### 1. Cache Chat IDs
+
+```bash
+# Good — discover once, reuse
+CHATS=$(agent-line chat list)
+WORK_CHAT=$(echo "$CHATS" | jq -r '.[] | select(.display_name | contains("Work")) | .chat_id')
+agent-line message send "$WORK_CHAT" "Hello"
+agent-line message send "$WORK_CHAT" "Another message"
+
+# Bad — list chats before every send
+agent-line chat list  # Wasteful
+agent-line message send "..." "Hello"
+agent-line chat list  # Wasteful
+agent-line message send "..." "Another"
+```
+
+### 2. Use Memory for Known IDs
+
+Store frequently used chat IDs in `~/.config/agent-messenger/MEMORY.md` to skip `chat list` calls in future sessions.
+
+### 3. Respect Rate Limits
+
+```bash
+# Good — pause between operations
+for chat_id in "${CHATS[@]}"; do
+  agent-line message send "$chat_id" "$MSG"
+  sleep 2
+done
+
+# Bad — rapid-fire
+for chat_id in "${CHATS[@]}"; do
+  agent-line message send "$chat_id" "$MSG"
+done
+```
+
+### 4. Check Auth Before Multi-Step Workflows
+
+```bash
+# Good — verify auth upfront
+STATUS=$(agent-line auth status)
+if echo "$STATUS" | jq -e '.error' > /dev/null 2>&1; then
+  echo "Not authenticated"
+  exit 1
+fi
+
+# Proceed with workflow
+agent-line chat list
+agent-line message send ...
+```
+
+## Anti-Patterns
+
+### Don't Poll Too Frequently
+
+```bash
+# Bad — too aggressive
+while true; do
+  agent-line message list "$CHAT_ID" -n 1
+  sleep 1
+done
+
+# Good — reasonable interval
+while true; do
+  agent-line message list "$CHAT_ID" -n 1
+  sleep 10
+done
+```
+
+### Don't Ignore Errors
+
+```bash
+# Bad
+agent-line message send "$CHAT_ID" "Hello"
+
+# Good
+RESULT=$(agent-line message send "$CHAT_ID" "Hello")
+if ! echo "$RESULT" | jq -e '.success' > /dev/null 2>&1; then
+  echo "Failed: $(echo "$RESULT" | jq -r '.error // .message // "Unknown"')"
+  exit 1
+fi
+```
+
+### Don't Spam Chats
+
+```bash
+# Bad — sends 100 separate messages
+for i in {1..100}; do
+  agent-line message send "$CHAT_ID" "Item $i"
+done
+
+# Good — batch into single message
+MESSAGE="Updates:"
+for i in {1..100}; do
+  MESSAGE="${MESSAGE}"$'\n'"$i. Item $i"
+done
+agent-line message send "$CHAT_ID" "$MESSAGE"
+```
+
+## SDK Client Lifecycle
+
+When using `LineClient` programmatically, note that calling `close()` sets the internal client to null. Any subsequent method call throws a `LineError` with code `not_connected`. Create a new `LineClient` instance if you need to reconnect. Always use `try/finally` to ensure `close()` runs:
+
+```typescript
+import { LineClient } from 'agent-messenger/line'
+
+const client = await new LineClient().login()
+try {
+  const chats = await client.getChats()
+  const firstChat = chats[0]
+  if (!firstChat) throw new Error('No chats available')
+  await client.sendMessage(firstChat.chat_id, 'Hello!')
+} finally {
+  client.close()
+}
+```
+
+## See Also
+
+- [Authentication Guide](authentication.md) - Setting up credentials
+- [Templates](../templates/) - Runnable example scripts

package/skills/agent-line/templates/chat-summary.sh

@@ -0,0 +1,63 @@
+#!/bin/bash
+
+set -euo pipefail
+
+if [ $# -lt 1 ]; then
+  echo "Usage: $0 <chat-id> [message-count]"
+  echo ""
+  echo "Examples:"
+  echo "  $0 c0123456789abcdef0123456789abcdef"
+  echo "  $0 c0123456789abcdef0123456789abcdef 50"
+  exit 1
+fi
+
+CHAT_ID="$1"
+COUNT="${2:-20}"
+
+if ! command -v agent-line >/dev/null 2>&1; then
+  echo "Error: agent-line not found"
+  echo "Install it with: npm install -g agent-messenger"
+  exit 1
+fi
+
+if ! command -v jq >/dev/null 2>&1; then
+  echo "Error: jq not found"
+  echo "Install it first to parse agent-line JSON output"
+  exit 1
+fi
+
+AUTH_STATUS=$(agent-line auth status 2>/dev/null || true)
+if echo "$AUTH_STATUS" | jq -e '.error' >/dev/null 2>&1; then
+  echo "Not authenticated. Run: agent-line auth login"
+  exit 1
+fi
+
+MESSAGES=$(agent-line message list "$CHAT_ID" -n "$COUNT" 2>/dev/null || true)
+
+if ! echo "$MESSAGES" | jq -e 'type == "array"' >/dev/null 2>&1; then
+  echo "Failed to fetch messages"
+  exit 1
+fi
+
+TOTAL=$(echo "$MESSAGES" | jq 'length')
+TEXT_COUNT=$(echo "$MESSAGES" | jq '[.[] | select(.text != null)] | length')
+AUTHORS=$(echo "$MESSAGES" | jq -r 'map(.author_id) | unique | .[]')
+FIRST_TIME=$(echo "$MESSAGES" | jq -r '.[0].sent_at // "unknown"')
+LAST_TIME=$(echo "$MESSAGES" | jq -r '.[-1].sent_at // "unknown"')
+
+echo "Chat summary for $CHAT_ID"
+echo "=========================="
+echo "Messages analyzed: $TOTAL"
+echo "Text messages: $TEXT_COUNT"
+echo "Time range: $FIRST_TIME → $LAST_TIME"
+echo ""
+echo "Participants:"
+while IFS= read -r author; do
+  [ -n "$author" ] || continue
+  COUNT_BY_AUTHOR=$(echo "$MESSAGES" | jq --arg author "$author" '[.[] | select(.author_id == $author)] | length')
+  echo "  $author: $COUNT_BY_AUTHOR messages"
+done <<< "$AUTHORS"
+
+echo ""
+echo "Recent messages:"
+echo "$MESSAGES" | jq -r '.[] | "- [\(.sent_at)] \(.author_id): \(.text // "[non-text]")"'