@rune-kit/rune 2.2.0 → 2.2.2

package/extensions/zalo/skills/zalo-rate-guard.md

@@ -0,0 +1,219 @@
+---
+name: zalo-rate-guard
+pack: "@rune/zalo"
+description: Rate limiting patterns for Zalo OA and personal APIs — token bucket per endpoint, exponential backoff, queue management, quota monitoring, anti-ban strategies.
+model: sonnet
+tools: "Read, Glob, Grep, Bash, Write, Edit"
+---
+
+# zalo-rate-guard
+
+Shared rate limiting layer for both Track A (OA API) and Track B (Personal via zca-js).
+Zalo has **undocumented rate limits** — no official RPM/QPM numbers published.
+Exceeding limits: throttled (429) → warned → OA suspended / account banned.
+Neither `zalo-php-sdk`, `zalo-java-sdk`, nor `zca-js` implement any rate limiting.
+This skill fills that gap.
+
+---
+
+## Estimated Safe Limits
+
+**Track A — OA API:**
+
+| Endpoint | Safe RPM | Burst | Notes |
+|----------|----------|-------|-------|
+| Send CS message | 200 | 10 | Per OA, includes all message types |
+| Send broadcast | 50 | 5 | Monthly quota based on follower count |
+| Get user profile | 300 | 20 | Cacheable — use name cache |
+| Get follower list | 100 | 10 | Paginated, cache results |
+| Upload media | 60 | 5 | Large payloads, slower |
+| Global | 500 | 30 | Total across all endpoints |
+
+**Track B — Personal (zca-js):**
+
+| Action | Safe RPM | Burst | Notes |
+|--------|----------|-------|-------|
+| Send message (DM) | 30 | 5 | Much lower than OA — personal account |
+| Send message (group) | 20 | 3 | Groups are more scrutinized |
+| Friend operations | 10 | 2 | Add/remove friend is very sensitive |
+| Profile lookups | 60 | 10 | Less sensitive, still cache |
+| Global | 100 | 15 | Err on side of caution |
+
+---
+
+## Token Bucket Implementation
+
+```typescript
+import PQueue from 'p-queue'
+
+interface RateLimitConfig {
+  rpm: number        // requests per minute
+  burst: number      // max concurrent
+  retryAfter: number // ms to wait on 429
+}
+
+const LIMITS: Record<string, RateLimitConfig> = {
+  'oa:send_message':   { rpm: 200, burst: 10, retryAfter: 5000 },
+  'oa:broadcast':      { rpm: 50,  burst: 5,  retryAfter: 10000 },
+  'oa:get_profile':    { rpm: 300, burst: 20, retryAfter: 3000 },
+  'oa:upload':         { rpm: 60,  burst: 5,  retryAfter: 5000 },
+  'personal:send_dm':  { rpm: 30,  burst: 5,  retryAfter: 10000 },
+  'personal:send_grp': { rpm: 20,  burst: 3,  retryAfter: 15000 },
+  'personal:friend':   { rpm: 10,  burst: 2,  retryAfter: 30000 },
+}
+
+export class ZaloRateLimiter {
+  private queues = new Map<string, PQueue>()
+
+  constructor() {
+    for (const [key, config] of Object.entries(LIMITS)) {
+      this.queues.set(key, new PQueue({
+        concurrency: config.burst,
+        intervalCap: config.rpm,
+        interval: 60_000, // per minute window
+      }))
+    }
+  }
+
+  async execute<T>(endpoint: string, fn: () => Promise<T>): Promise<T> {
+    const queue = this.queues.get(endpoint)
+    if (!queue) throw new Error(`Unknown endpoint: ${endpoint}`)
+    return queue.add(fn) as Promise<T>
+  }
+
+  queueSize(endpoint: string): number {
+    return this.queues.get(endpoint)?.size ?? 0
+  }
+
+  pending(endpoint: string): number {
+    return this.queues.get(endpoint)?.pending ?? 0
+  }
+}
+```
+
+---
+
+## Exponential Backoff on 429
+
+```typescript
+export async function withBackoff<T>(
+  fn: () => Promise<T>,
+  maxRetries = 3,
+  baseDelay = 1000
+): Promise<T> {
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      return await fn()
+    } catch (error: any) {
+      const isRateLimit = error?.status === 429 || error?.error_code === 429
+      if (!isRateLimit || attempt === maxRetries) throw error
+      const delay = baseDelay * Math.pow(2, attempt) + Math.random() * 1000
+      console.warn(`[zalo-rate-guard] Rate limited. Retry ${attempt + 1}/${maxRetries} in ${Math.round(delay)}ms`)
+      await new Promise(r => setTimeout(r, delay))
+    }
+  }
+  throw new Error('Unreachable')
+}
+```
+
+---
+
+## Quota Monitoring (OA Broadcast)
+
+Broadcast quota is a **hard monthly limit** — exceeding it silently drops messages, no error returned.
+
+```typescript
+interface QuotaTracker {
+  monthly_limit: number  // based on follower count + OA level
+  used: number
+  resets_at: Date        // 1st of each month
+}
+
+export function canBroadcast(tracker: QuotaTracker, recipientCount: number): boolean {
+  const remaining = tracker.monthly_limit - tracker.used
+  if (recipientCount > remaining) {
+    console.error(
+      `[zalo-rate-guard] Broadcast quota insufficient: need ${recipientCount}, have ${remaining}/${tracker.monthly_limit}`
+    )
+    return false
+  }
+  return true
+}
+
+export function trackBroadcastUsed(tracker: QuotaTracker, sent: number): QuotaTracker {
+  return { ...tracker, used: tracker.used + sent }
+}
+```
+
+---
+
+## Integration Pattern
+
+```typescript
+// Singleton — shared across the app
+export const limiter = new ZaloRateLimiter()
+
+// Track A: OA message send with rate limiting
+export async function sendOaMessage(userId: string, text: string) {
+  return limiter.execute('oa:send_message', () =>
+    withBackoff(() =>
+      oaApiCall('/message/cs', {
+        recipient: { user_id: userId },
+        message: { text },
+      })
+    )
+  )
+}
+
+// Track B: Personal DM with rate limiting + human jitter
+export async function sendPersonalMessage(threadId: string, text: string) {
+  const jitter = 500 + Math.random() * 1500 // 500–2000ms
+  await new Promise(r => setTimeout(r, jitter))
+  return limiter.execute('personal:send_dm', () =>
+    withBackoff(() => api.sendMessage(text, threadId, 'User'))
+  )
+}
+
+// Track B: Friend operation — highest-risk, extra jitter
+export async function addFriend(userId: string) {
+  const jitter = 2000 + Math.random() * 3000 // 2–5s
+  await new Promise(r => setTimeout(r, jitter))
+  return limiter.execute('personal:friend', () =>
+    withBackoff(() => api.sendFriendRequest(userId), 2, 5000)
+  )
+}
+```
+
+---
+
+## Anti-Ban Strategies
+
+**Track A (OA):**
+1. Stay under safe RPM limits (table above)
+2. Exponential backoff on ALL 429 responses — never retry immediately
+3. Cache user profiles — avoid repeated lookups for the same user
+4. Spread broadcasts over time — don't burst the entire follower list at once
+5. Monitor quota before each broadcast batch — stop before hitting monthly limit
+6. Use `appsecret_proof` on all requests — proves you're the legitimate app owner
+
+**Track B (Personal):**
+1. Much lower limits than OA — personal accounts are watched more closely
+2. Add human-like jitter: 500–2000ms random delay between messages (not optional)
+3. Avoid 3–6 AM (VN timezone) — traffic at those hours flags automated activity
+4. Never change profile info programmatically — triggers manual review
+5. Friend operations are highest-risk — max 10 RPM, prefer lower in practice
+6. Keep sessions long-lived — repeated login/logout is a strong ban signal
+7. Use a consistent device fingerprint (`userAgent` + `IMEI`) per account
+8. On `DuplicateConnection` (error 3000): wait 30s before reconnecting, never spam reconnects
+
+---
+
+## Sharp Edges
+
+- Rate limits are **estimated** — Zalo does not publish official numbers; treat all figures as conservative targets
+- `p-queue` `intervalCap` applies per window, not per request — test behavior under burst
+- 429 without backoff = accelerating toward ban, not slowing down
+- Broadcast quota overflow **silently drops messages** — no 429, no error, just lost sends
+- Stale cached profile data is acceptable; hitting rate limits for fresh data is not
+- Personal account friend operations are the single highest-risk action — handle with care
+- Human jitter for personal track is a survival strategy, not a nice-to-have

package/hooks/auto-format/index.cjs

@@ -0,0 +1,48 @@
+// Rune Auto-Format Hook
+// PostToolUse hook on Edit/Write — runs Prettier on JS/TS files after modification
+//
+// Only runs if Prettier is available in the project.
+// Silent pass-through if not applicable.
+
+const { execSync } = require('child_process');
+const path = require('path');
+
+const input = JSON.parse(process.env.CLAUDE_TOOL_INPUT || '{}');
+const filePath = input.file_path || input.filePath || '';
+
+// Only format JS/TS/JSON/CSS files
+if (!/\.(js|jsx|ts|tsx|json|css|scss|md|html|yaml|yml)$/i.test(filePath)) {
+  process.exit(0);
+}
+
+// Check if file exists and is within a project with Prettier
+const dir = path.dirname(filePath);
+
+// Try to find prettier in the project
+let hasPrettier = false;
+try {
+  execSync('npx prettier --version', { cwd: dir, encoding: 'utf-8', stdio: 'pipe', timeout: 5000 });
+  hasPrettier = true;
+} catch {
+  // No Prettier available — skip silently
+}
+
+if (!hasPrettier) {
+  process.exit(0);
+}
+
+// Run Prettier on the file
+try {
+  execSync(`npx prettier --write "${filePath}"`, {
+    cwd: dir,
+    encoding: 'utf-8',
+    stdio: 'pipe',
+    timeout: 10000,
+  });
+  // Silent success — formatted files are seamless
+} catch (e) {
+  // Prettier failed — non-critical, just warn
+  console.log(`[Rune auto-format] Prettier failed on ${path.basename(filePath)}: ${e.message.split('\n')[0]}`);
+}
+
+process.exit(0);

package/hooks/context-watch/index.cjs

@@ -0,0 +1,68 @@
+// Rune Context Watch Hook
+// Lightweight tool call counter — detects context pressure and suggests rune:context-engine
+// Runs as PreToolUse hook on Edit/Write (high-cost operations)
+//
+// H3 Intelligence: also tracks tool type distribution and session start timestamp
+// for metrics aggregation at session end.
+//
+// Uses a temp file counter (survives across hook invocations within same session).
+// Zero overhead: just reads/increments a number. No token cost.
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// Counter file scoped to current working directory (hash of cwd)
+const cwd = process.cwd();
+const hash = Buffer.from(cwd).toString('base64url').slice(0, 16);
+const counterFile = path.join(os.tmpdir(), `rune-context-watch-${hash}.json`);
+
+// Thresholds
+const FIRST_WARNING = 40;
+const REPEAT_INTERVAL = 20;
+const CRITICAL_THRESHOLD = 80;
+
+// Detect tool type from environment
+const toolName = process.env.CLAUDE_TOOL_NAME || 'unknown';
+
+// Read current state
+let state = { count: 0, lastWarning: 0, sessionStart: null, toolCounts: {} };
+try {
+  const raw = fs.readFileSync(counterFile, 'utf-8');
+  state = JSON.parse(raw);
+  // Ensure toolCounts exists (upgrade from old format)
+  if (!state.toolCounts) state.toolCounts = {};
+  if (!state.sessionStart) state.sessionStart = new Date().toISOString();
+} catch {
+  // First run or corrupted — start fresh
+  state.sessionStart = new Date().toISOString();
+}
+
+// Increment total and per-tool counters
+state.count += 1;
+state.toolCounts[toolName] = (state.toolCounts[toolName] || 0) + 1;
+
+// Check thresholds
+const count = state.count;
+const sinceLast = count - state.lastWarning;
+
+if (count >= CRITICAL_THRESHOLD && sinceLast >= REPEAT_INTERVAL) {
+  console.log(`\n🔴 [Rune context-watch] ${count} tool calls — context likely RED (>85%).`);
+  console.log('  RECOMMENDED: Invoke rune:context-engine for state save + /compact.');
+  console.log('  Risk: auto-compaction may lose critical decisions without state save.\n');
+  state.lastWarning = count;
+} else if (count >= FIRST_WARNING && sinceLast >= REPEAT_INTERVAL) {
+  console.log(`\n🟡 [Rune context-watch] ${count} tool calls — context filling up.`);
+  console.log('  Consider invoking rune:context-engine at the next logical boundary.');
+  console.log('  Or run /compact manually if at a good stopping point.\n');
+  state.lastWarning = count;
+}
+
+// Persist
+try {
+  fs.writeFileSync(counterFile, JSON.stringify(state));
+} catch {
+  // Non-critical — counter resets next run
+}
+
+process.exit(0);

package/hooks/hooks.json

@@ -0,0 +1,99 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|clear|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cjs\" session-start",
+            "async": false
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Read|Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cjs\" pre-tool-guard",
+            "async": false
+          }
+        ]
+      },
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cjs\" context-watch",
+            "async": true
+          }
+        ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cjs\" secrets-scan",
+            "async": false
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cjs\" auto-format",
+            "async": true
+          },
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cjs\" typecheck",
+            "async": true
+          }
+        ]
+      },
+      {
+        "matcher": "Skill",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cjs\" metrics-collector",
+            "async": true
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "matcher": ".*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cjs\" pre-compact",
+            "async": false
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": ".*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cjs\" post-session-reflect",
+            "async": false
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/metrics-collector/index.cjs

@@ -0,0 +1,42 @@
+// Rune Metrics Collector Hook
+// PostToolUse on Skill — captures skill invocations for H3 mesh analytics
+// Append-only JSONL to tmpdir. Flushed to .rune/metrics/ at session end.
+// Async: true — never blocks skill execution.
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const cwd = process.cwd();
+const hash = Buffer.from(cwd).toString('base64url').slice(0, 16);
+const metricsFile = path.join(os.tmpdir(), `rune-metrics-${hash}.jsonl`);
+
+// Extract skill name from tool input
+const toolInput = process.env.CLAUDE_TOOL_INPUT || '';
+let skillName = 'unknown';
+try {
+  const parsed = JSON.parse(toolInput);
+  // Skill tool input has { skill: "rune:cook" } or { skill: "cook" }
+  const raw = parsed.skill || parsed.name || '';
+  skillName = raw.replace(/^rune:/, '');
+} catch {
+  // If not JSON, try raw string match
+  const match = toolInput.match(/(?:rune:)?([a-z][\w-]*)/i);
+  if (match) skillName = match[1];
+}
+
+if (skillName && skillName !== 'unknown') {
+  const entry = JSON.stringify({
+    ts: new Date().toISOString(),
+    skill: skillName,
+    event: 'invoke'
+  });
+
+  try {
+    fs.appendFileSync(metricsFile, entry + '\n');
+  } catch {
+    // Non-critical — metrics are best-effort
+  }
+}
+
+process.exit(0);

package/hooks/post-session-reflect/index.cjs

@@ -0,0 +1,153 @@
+// Rune Post-Session Reflect Hook
+// 1. Flushes session metrics from tmpdir to .rune/metrics/ (H3 Intelligence)
+// 2. Displays structured self-review checklist at session end (Stop event)
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const cwd = process.cwd();
+const hash = Buffer.from(cwd).toString('base64url').slice(0, 16);
+
+// === H3: Flush Session Metrics ===
+
+const metricsJsonl = path.join(os.tmpdir(), `rune-metrics-${hash}.jsonl`);
+const counterFile = path.join(os.tmpdir(), `rune-context-watch-${hash}.json`);
+const runeMetricsDir = path.join(cwd, '.rune', 'metrics');
+
+try {
+  flushMetrics();
+} catch (e) {
+  // Metrics flush is best-effort — never block session end
+  // Silently ignore errors
+}
+
+function flushMetrics() {
+  // Read session skill invocations from tmpdir JSONL
+  let skillEvents = [];
+  if (fs.existsSync(metricsJsonl)) {
+    const lines = fs.readFileSync(metricsJsonl, 'utf-8').trim().split('\n').filter(Boolean);
+    for (const line of lines) {
+      try { skillEvents.push(JSON.parse(line)); } catch { /* skip malformed */ }
+    }
+  }
+
+  // Read context-watch state for tool counts and session timing
+  let watchState = { count: 0, sessionStart: null, toolCounts: {} };
+  if (fs.existsSync(counterFile)) {
+    try {
+      watchState = JSON.parse(fs.readFileSync(counterFile, 'utf-8'));
+    } catch { /* use defaults */ }
+  }
+
+  // Nothing to flush if no data
+  if (skillEvents.length === 0 && watchState.count === 0) return;
+
+  // Ensure .rune/metrics/ exists
+  fs.mkdirSync(runeMetricsDir, { recursive: true });
+
+  const now = new Date().toISOString();
+  const sessionStart = watchState.sessionStart || now;
+  const durationMin = Math.round((new Date(now) - new Date(sessionStart)) / 60000);
+
+  // Build skill usage map
+  const skillCounts = {};
+  const skillChain = [];
+  for (const evt of skillEvents) {
+    skillCounts[evt.skill] = (skillCounts[evt.skill] || 0) + 1;
+    skillChain.push(evt.skill);
+  }
+
+  // Determine primary skill (most invoked)
+  const primarySkill = Object.entries(skillCounts)
+    .sort((a, b) => b[1] - a[1])[0]?.[0] || 'none';
+
+  // Generate session ID
+  const sessionId = `s-${now.slice(0, 10).replace(/-/g, '')}-${now.slice(11, 19).replace(/:/g, '')}`;
+
+  // 1. Append to sessions.jsonl
+  const sessionEntry = {
+    id: sessionId,
+    date: now.slice(0, 10),
+    duration_min: durationMin,
+    tool_calls: watchState.count,
+    tool_distribution: watchState.toolCounts,
+    skill_invocations: skillEvents.length,
+    skills_used: Object.keys(skillCounts),
+    primary_skill: primarySkill
+  };
+
+  const sessionsFile = path.join(runeMetricsDir, 'sessions.jsonl');
+  fs.appendFileSync(sessionsFile, JSON.stringify(sessionEntry) + '\n');
+
+  // Cap at 100 sessions (rotate oldest)
+  try {
+    const allLines = fs.readFileSync(sessionsFile, 'utf-8').trim().split('\n').filter(Boolean);
+    if (allLines.length > 100) {
+      fs.writeFileSync(sessionsFile, allLines.slice(-100).join('\n') + '\n');
+    }
+  } catch { /* cap is best-effort */ }
+
+  // 2. Merge into skills.json (running totals)
+  const skillsFile = path.join(runeMetricsDir, 'skills.json');
+  let skillsData = { version: 1, updated: now, skills: {} };
+  if (fs.existsSync(skillsFile)) {
+    try {
+      skillsData = JSON.parse(fs.readFileSync(skillsFile, 'utf-8'));
+    } catch { /* start fresh */ }
+  }
+
+  for (const [skill, count] of Object.entries(skillCounts)) {
+    if (!skillsData.skills[skill]) {
+      skillsData.skills[skill] = { total_invocations: 0, last_used: now.slice(0, 10) };
+    }
+    skillsData.skills[skill].total_invocations += count;
+    skillsData.skills[skill].last_used = now.slice(0, 10);
+  }
+  skillsData.updated = now;
+
+  fs.writeFileSync(skillsFile, JSON.stringify(skillsData, null, 2) + '\n');
+
+  // 3. Append to chains.jsonl
+  if (skillChain.length > 0) {
+    const chainsFile = path.join(runeMetricsDir, 'chains.jsonl');
+    const chainEntry = {
+      session: sessionId,
+      chain: skillChain,
+      depth: skillChain.length
+    };
+    fs.appendFileSync(chainsFile, JSON.stringify(chainEntry) + '\n');
+  }
+
+  // 4. Cleanup tmpdir files
+  try { fs.unlinkSync(metricsJsonl); } catch { /* already gone */ }
+  // Note: counterFile is cleaned by session-start hook on next session
+
+  // Report metrics flush
+  const skillList = Object.entries(skillCounts)
+    .sort((a, b) => b[1] - a[1])
+    .map(([s, c]) => `${s}(${c})`)
+    .join(', ');
+
+  console.log(`\n📊 [Rune metrics] Session ${sessionId} — ${durationMin}min, ${watchState.count} tool calls, ${skillEvents.length} skill invocations`);
+  if (skillList) console.log(`   Skills: ${skillList}`);
+  console.log(`   Saved to .rune/metrics/\n`);
+}
+
+// === Original: Verification Checklist ===
+
+console.log(`
+┌─────────────────────────────────────────────────────┐
+│  Rune Session End — Verification Checklist          │
+├─────────────────────────────────────────────────────┤
+│  Before closing this session, confirm:              │
+│                                                     │
+│  □ All TodoWrite tasks marked complete?             │
+│  □ Tests ran and passing?                           │
+│  □ No hardcoded secrets introduced?                 │
+│  □ If schema changed: migration + rollback exist?   │
+│  □ Verification ran (lint + types + build)?         │
+│                                                     │
+│  If any item is unclear → address it now.           │
+└─────────────────────────────────────────────────────┘
+`);