@miphamai/cli 0.2.3 → 0.3.0

package/skills/standard/superpower.SKILL.md

@@ -1,19 +1,57 @@
 ---
 name: superpower
-description: Use when starting any conversation — establishes how to find and use skills
-version: 1.0.0
+description: Skill discovery and invocation system — find and use skills before any response or action
+version: 2.0.0
 ---
 
-# Superpowers Skill
+# Superpowers — Using Skills
 
-## Instruction Priority
+## The Rule
 
-User's explicit instructions always take precedence.
+**Invoke relevant or requested skills BEFORE any response or action.** Even a 1% chance a skill might apply means you should invoke it to check.
 
 ## How to Access Skills
 
-Use the Skill tool to invoke skills. When you invoke a skill, its content is loaded and presented to you — follow it directly.
+Use the `Skill` tool to invoke skills by name. When you invoke a skill, its content is loaded — follow it directly.
 
-## The Rule
+## Skill Discovery
+
+### Check Available Skills
+
+Skills are listed in `<system-reminder>` messages. Scan this list when receiving a task.
+
+### Matching Algorithm
+
+1. Parse the user's request for intent keywords
+2. Scan skill names and descriptions for matches
+3. If ANY skill matches at ≥1% probability → invoke it
+4. Multiple matches → invoke all that may apply
+5. Invoked skill doesn't fit → that's fine, don't use it
+
+### Priority Order
+
+1. **Process skills first** — brainstorming, systematic-debugging, tdd. These determine HOW to approach
+2. **Implementation skills second** — frontend-design, mcp-builder. These guide execution
+
+## Red Flags
+
+These thoughts mean STOP — you're rationalizing:
+
+| Thought | Reality |
+|---------|---------|
+| "This is just a simple question" | Questions are tasks. Check skills. |
+| "I need more context first" | Skill check comes BEFORE clarifying questions. |
+| "Let me explore the codebase first" | Skills tell you HOW to explore. |
+| "I remember this skill" | Skills evolve. Read current version. |
+| "The skill is overkill" | Simple things become complex. Use it. |
+
+## Skill Types
+
+- **Rigid** (TDD, systematic-debugging): Follow exactly. Don't adapt away discipline.
+- **Flexible** (patterns): Adapt principles to context.
+
+The skill itself tells you which type it is.
+
+## User Instructions
 
-Invoke relevant or requested skills BEFORE any response or action. Even a 1% chance a skill might apply means that you should invoke the skill to check.
+Instructions say WHAT, not HOW. "Add X" or "Fix Y" doesn't mean skip workflows.

package/skills/standard/tdd.SKILL.md

@@ -1,20 +1,93 @@
 ---
 name: tdd
-description: Test-Driven Development workflow — red, green, refactor
-version: 1.0.0
+description: Test-Driven Development — red-green-refactor cycle with language-specific guidance and test design rules
+version: 2.0.0
 ---
 
-# TDD Skill
+# Test-Driven Development (TDD)
 
-## Workflow
+## The Cycle
 
-1. **Red**: Write a failing test that defines the expected behavior
-2. **Green**: Write the minimum code to make the test pass
-3. **Refactor**: Clean up the code while tests remain green
+```
+RED → GREEN → REFACTOR → repeat
+```
 
-## Rules
+### 1. RED — Write a Failing Test
 
-- Never write production code without a failing test
-- Write only enough test to fail
-- Write only enough code to pass
-- Tests must be deterministic and isolated
+Write the smallest test that captures the behavior you want:
+
+- Name the test descriptively: `it('should return 0 for empty string')`
+- Use the AAA pattern: **A**rrange → **A**ct → **A**ssert
+- Run to confirm it **fails** (not errors — fails)
+- If it passes before implementation, your test is wrong
+
+### 2. GREEN — Make It Pass
+
+Write the **minimum** code to make the test pass:
+
+- Don't optimize, don't generalize, don't add features
+- A hardcoded return is fine if it passes the test
+- Run all tests — the new one should pass, old ones should still pass
+
+### 3. REFACTOR — Clean Up
+
+Improve the code while tests stay green:
+
+- Remove duplication (test code and production code)
+- Improve names, extract helpers
+- Simplify logic
+- Run tests after each change
+
+## Test Design Rules
+
+- **Deterministic**: No `Date.now()`, `Math.random()`, or network calls in test bodies
+- **Isolated**: Each test sets up its own state; no test-order dependency
+- **Fast**: Unit tests should run in milliseconds, not seconds
+- **Readable**: Test output should explain what broke without reading source
+
+## Language-Specific Guidance
+
+### TypeScript / JavaScript (Vitest)
+
+```ts
+import { describe, it, expect } from 'vitest'
+
+describe('sum', () => {
+  it('should add two positive numbers', () => {
+    expect(sum(2, 3)).toBe(5)
+  })
+  it('should handle zero', () => {
+    expect(sum(0, 5)).toBe(5)
+  })
+})
+```
+
+File naming: `src/foo.ts` → `test/foo.test.ts`
+
+### Python (pytest)
+
+```python
+def test_sum_positive():
+    assert sum(2, 3) == 5
+
+def test_sum_zero():
+    assert sum(0, 5) == 5
+```
+
+### Go (testing package)
+
+```go
+func TestSumPositive(t *testing.T) {
+    got := Sum(2, 3)
+    want := 5
+    if got != want {
+        t.Errorf("Sum(2,3) = %d; want %d", got, want)
+    }
+}
+```
+
+## When NOT to TDD
+
+- Exploratory spikes (throw away after learning)
+- Configuration files and types (compile-time enforced)
+- Generated code

package/skills/standard/web-search.SKILL.md

@@ -1,23 +1,72 @@
 ---
 name: web-search
-description: Search the web for current information, documentation, and news
-version: 1.0.0
+description: Search the web for current information — documentation, news, technical references, and troubleshooting
+version: 2.0.0
 ---
 
-# Web Search Skill
+# Web Search
 
-Use WebSearch tool to find current information.
+Use `WebSearch` tool to find current, accurate information from the web.
 
 ## When to Use
 
-- Up-to-date documentation for libraries and frameworks
-- Current events and news
-- Technical troubleshooting with recent solutions
-- API reference and version-specific features
+- **Library/framework docs**: API references, migration guides, version-specific features
+- **Current events**: News, releases, incidents (anything after training cutoff)
+- **Troubleshooting**: Error messages, stack traces, known issues
+- **Comparisons**: Technology trade-offs, benchmark data
+- **Code examples**: Real-world usage patterns, configuration snippets
 
-## Best Practices
+## Query Best Practices
 
-- Be specific with search queries
-- Use allowed_domains to focus results
-- Verify information from multiple sources
-- Cite sources in responses
+### Be Specific
+
+```
+❌ "React"                              → too broad
+❌ "React problems"                     → ambiguous
+✅ "React 19 useEffect double mount fix" → specific, versioned
+✅ "Next.js 14 App Router caching behavior 2026" → targeted
+```
+
+### Use Technical Terms
+
+```
+❌ "how to make website fast"
+✅ "Core Web Vitals LCP optimization Next.js 14"
+```
+
+### Include Version Numbers
+
+```
+❌ "prisma query"
+✅ "Prisma 5.0 findMany with nested include filter"
+```
+
+### Domain Filtering
+
+Use `allowed_domains` for authoritative sources:
+- `docs.github.com` — GitHub documentation
+- `nextjs.org` — Next.js official docs
+- `developer.mozilla.org` — MDN Web Docs
+- `nodejs.org` — Node.js official
+
+## Verification
+
+- **Cross-reference**: Verify claims across 2+ independent sources
+- **Recency**: Prefer results from the current year; note article dates
+- **Authority**: Official docs > well-known blogs > Stack Overflow > random forums
+- **Cite sources**: Always include source URLs in responses
+
+## Source Attribution
+
+After answering from search results, end with:
+```markdown
+Sources:
+- [Title](URL) — brief note
+- [Title](URL) — brief note
+```
+
+## When NOT to Search
+
+- Pure logic or algorithmic questions (reasoning, not research)
+- Questions answerable from code already in context
+- Opinions and subjective recommendations (search for data, not consensus)

package/src/core/context.ts

@@ -1,5 +1,7 @@
 import type { Message } from '../shared/index.ts'
 
+export type Summarizer = (messages: Message[], heading: string) => Promise<string>
+
 interface ContextConfig {
   maxTokens: number
   compactionThreshold: number // e.g. 0.9 → compact at 90% usage
@@ -19,9 +21,15 @@ export class ContextManager {
   private estimatedTokens = 0
   private checkpoints: Checkpoint[] = []
   private checkpointCounter = 0
+  private summarizer?: Summarizer
 
   constructor(private config: ContextConfig) {}
 
+  /** Set an optional LLM summarizer for intelligent compaction. */
+  setSummarizer(fn: Summarizer): void {
+    this.summarizer = fn
+  }
+
   setSystemPrompt(prompt: string): void {
     this.systemPrompt = prompt
     this.estimatedTokens = this.estimateTokens(prompt)
@@ -46,19 +54,36 @@ export class ContextManager {
     return this.estimatedTokens > this.config.maxTokens * this.config.compactionThreshold
   }
 
-  async compact(_summarizeHeading: string): Promise<void> {
-    // Phase 1: simple truncation — keep last 20 messages, drop oldest
-    if (this.messages.length > 30) {
-      const keep = 20
+  async compact(heading: string): Promise<void> {
+    if (this.messages.length <= 30) return
+
+    const keep = 20
+    const toDrop = this.messages.slice(0, -keep)
+
+    if (this.summarizer && toDrop.length >= 4) {
+      // LLM-based summarization of truncated messages
+      try {
+        const summary = await this.summarizer(toDrop, heading)
+        const summaryMsg: Message = {
+          role: 'user',
+          content: `[Earlier conversation summary]: ${summary}`,
+        }
+        this.messages = [summaryMsg, ...this.messages.slice(-keep)]
+      } catch {
+        // Fall back to truncation on summarizer failure
+        this.messages = this.messages.slice(-keep)
+      }
+    } else {
+      // Simple truncation fallback
       this.messages = this.messages.slice(-keep)
+    }
 
-      // Re-estimate tokens
-      this.estimatedTokens = this.estimateTokens(this.systemPrompt)
-      for (const msg of this.messages) {
-        this.estimatedTokens += this.estimateTokens(
-          typeof msg.content === 'string' ? msg.content : JSON.stringify(msg.content),
-        )
-      }
+    // Re-estimate tokens
+    this.estimatedTokens = this.estimateTokens(this.systemPrompt)
+    for (const msg of this.messages) {
+      this.estimatedTokens += this.estimateTokens(
+        typeof msg.content === 'string' ? msg.content : JSON.stringify(msg.content),
+      )
     }
   }
 
@@ -128,8 +153,43 @@ export class ContextManager {
     return this.checkpoints.at(-1)?.id
   }
 
+  /**
+   * Estimate token count for a text string.
+   *
+   * Uses a character-class-aware heuristic:
+   *   - CJK / emoji: ~1.5 chars per token
+   *   - Other scripts (Latin, Cyrillic, Arabic): ~4 chars per token
+   *   - Whitespace-heavy (code): ~3 chars per token
+   *
+   * This is ~30-40% more accurate than flat 4 chars/token for mixed-language text.
+   */
   private estimateTokens(text: string): number {
-    // Simple estimation: ~4 chars per token
-    return Math.ceil(text.length / 4)
+    if (!text) return 0
+
+    let cjk = 0
+    let latin = 0
+
+    for (const ch of text) {
+      const cp = ch.codePointAt(0)!
+      // CJK Unified Ideographs, Hangul, Kana, CJK Extensions, fullwidth forms
+      if (
+        (cp >= 0x4e00 && cp <= 0x9fff) || // CJK Unified
+        (cp >= 0x3400 && cp <= 0x4dbf) || // CJK Ext-A
+        (cp >= 0x20000 && cp <= 0x2a6df) || // CJK Ext-B
+        (cp >= 0xac00 && cp <= 0xd7af) || // Hangul
+        (cp >= 0x3040 && cp <= 0x30ff) || // Hiragana + Katakana
+        (cp >= 0xff01 && cp <= 0xff60) || // Fullwidth
+        (cp >= 0x1f300 && cp <= 0x1f9ff) // Emoji / pictographs
+      ) {
+        cjk++
+      } else if (cp > 0x7f) {
+        latin++
+      } else {
+        latin++
+      }
+    }
+
+    // CJK: ~1.5 chars/token, Latin/other: ~4 chars/token
+    return Math.max(1, Math.ceil(cjk / 1.5 + latin / 4))
   }
 }

package/src/core/engine.ts

@@ -2,8 +2,11 @@ import type { Message, StreamChunk, ToolDefinition, ToolResult } from '../shared
 import { ProviderRegistry } from '../providers/registry'
 import { ContextManager } from './context'
 import { PermissionSystem } from './permission'
+import type { HookEngine } from './hooks'
 
 export class QueryEngine {
+  private hookEngine?: HookEngine
+
   constructor(
     private registry: ProviderRegistry,
     private context: ContextManager,
@@ -11,11 +14,56 @@ export class QueryEngine {
     private permission: PermissionSystem = new PermissionSystem('bypass'),
   ) {}
 
+  /** Register a hook engine for pre/post tool-use lifecycle events. */
+  setHookEngine(hooks: HookEngine): void {
+    this.hookEngine = hooks
+  }
+
+  /** Wire LLM-based conversation summarization into the context manager. */
+  setupContextSummarizer(): void {
+    this.context.setSummarizer(async (messages, heading) => {
+      const text = messages
+        .map((m) => {
+          const role = m.role
+          const content = typeof m.content === 'string' ? m.content : JSON.stringify(m.content)
+          return `[${role}]: ${content.slice(0, 500)}`
+        })
+        .join('\n')
+
+      // Build a minimal system prompt for summarization
+      const summaryPrompt =
+        `You are a conversation summarizer. Create a concise summary (1-3 paragraphs) of this conversation excerpt. Focus on: key topics discussed, decisions made, code changes mentioned, and open questions. Heading: ${heading}`
+
+      // Collect full summary text from streaming response
+      let summary = ''
+      try {
+        for await (const chunk of this.registry.chat({
+          model: this.registry.getActiveModel(),
+          messages: [
+            { role: 'system', content: summaryPrompt },
+            { role: 'user', content: text },
+          ],
+          maxTokens: 300,
+        })) {
+          if (chunk.type === 'text' && chunk.content) {
+            summary += chunk.content
+          }
+          if (chunk.type === 'stop') break
+          if (chunk.type === 'error') break
+        }
+      } catch {
+        // Return a minimal summary on failure
+      }
+
+      return summary.slice(0, 2000) || 'Prior conversation context omitted.'
+    })
+  }
+
   getPermission(): PermissionSystem {
     return this.permission
   }
 
-  async *process(userInput: string): AsyncGenerator<StreamChunk> {
+  async *process(userInput: string, signal?: AbortSignal): AsyncGenerator<StreamChunk> {
     // Add user message to context
     this.context.addMessage({ role: 'user', content: userInput })
 
@@ -32,11 +80,13 @@ export class QueryEngine {
     const toolUses: Array<{ id: string; name: string; input: Record<string, unknown> }> = []
 
     // Stream model response
+    try {
     for await (const chunk of this.registry.chat({
       model: this.registry.getActiveModel(),
       messages,
       systemPrompt,
       tools: toolDefs.length > 0 ? toolDefs : undefined,
+      signal,
     })) {
       yield chunk
 
@@ -64,6 +114,18 @@ export class QueryEngine {
         }
       }
     }
+    } catch (err) {
+      if (isAbortError(err)) {
+        // User interrupted — keep partial content, stop gracefully
+        if (assistantContent) {
+          this.context.addMessage({ role: 'assistant', content: assistantContent })
+        }
+        yield { type: 'stop' }
+        return
+      }
+      yield { type: 'error', error: String(err) }
+      return
+    }
 
     // Execute any tools that were requested
     for (const toolUse of toolUses) {
@@ -71,7 +133,7 @@ export class QueryEngine {
       yield {
         type: 'tool_result',
         tool_use_id: toolUse.id,
-        content: result.content,
+        content: result.success ? result.content : (result.error || result.content),
       }
 
       // Add tool use + result to context
@@ -87,60 +149,80 @@ export class QueryEngine {
 
     // If tools were executed, recursively continue the conversation
     if (toolUses.length > 0) {
-      yield* this.continueWithTools()
+      yield* this.continueWithTools(signal)
     }
   }
 
-  private async *continueWithTools(): AsyncGenerator<StreamChunk> {
-    const systemPrompt = this.context.getSystemPrompt()
-    const messages = this.context.getMessages()
+  private async *continueWithTools(signal?: AbortSignal): AsyncGenerator<StreamChunk> {
+    const MAX_TURNS = 10
     const toolDefs = this.getToolDefinitions()
 
-    let assistantContent = ''
-    const toolUses: Array<{ id: string; name: string; input: Record<string, unknown> }> = []
+    for (let turn = 0; turn < MAX_TURNS; turn++) {
+      const systemPrompt = this.context.getSystemPrompt()
+      const messages = this.context.getMessages()
 
-    for await (const chunk of this.registry.chat({
-      model: this.registry.getActiveModel(),
-      messages,
-      systemPrompt,
-      tools: toolDefs.length > 0 ? toolDefs : undefined,
-    })) {
-      yield chunk
+      let assistantContent = ''
+      const toolUses: Array<{ id: string; name: string; input: Record<string, unknown> }> = []
 
-      if (chunk.type === 'error') return
-      if (chunk.type === 'text' && chunk.content) assistantContent += chunk.content
+      try {
+      for await (const chunk of this.registry.chat({
+        model: this.registry.getActiveModel(),
+        messages,
+        systemPrompt,
+        tools: toolDefs.length > 0 ? toolDefs : undefined,
+        signal,
+      })) {
+        yield chunk
 
-      if (chunk.type === 'tool_use' && chunk.toolUse) {
-        toolUses.push({
-          id: chunk.toolUse.id,
-          name: chunk.toolUse.name,
-          input: chunk.toolUse.input,
-        })
-      }
-    }
+        if (chunk.type === 'error') return
+        if (chunk.type === 'text' && chunk.content) assistantContent += chunk.content
 
-    if (assistantContent) {
-      this.context.addMessage({ role: 'assistant', content: assistantContent })
-    }
+        if (chunk.type === 'tool_use' && chunk.toolUse) {
+          toolUses.push({
+            id: chunk.toolUse.id,
+            name: chunk.toolUse.name,
+            input: chunk.toolUse.input,
+          })
+        }
+      }
+      } catch (err) {
+        if (isAbortError(err)) {
+          if (assistantContent) {
+            this.context.addMessage({ role: 'assistant', content: assistantContent })
+          }
+          yield { type: 'stop' }
+          return
+        }
+        return
+      }
 
-    // Execute tools (max 1 level of recursion to prevent infinite loops)
-    for (const toolUse of toolUses) {
-      const result = await this.executeTool(toolUse.name, toolUse.input)
-      yield {
-        type: 'tool_result',
-        tool_use_id: toolUse.id,
-        content: result.content,
+      if (assistantContent) {
+        this.context.addMessage({ role: 'assistant', content: assistantContent })
       }
 
-      this.context.addMessage({
-        role: 'assistant',
-        content: [{ type: 'tool_use', id: toolUse.id, name: toolUse.name, input: toolUse.input }],
-      })
-      this.context.addMessage({
-        role: 'user',
-        content: [{ type: 'tool_result', tool_use_id: toolUse.id, content: result.content }],
-      })
+      // No more tool calls — conversation complete
+      if (toolUses.length === 0) return
+
+      // Execute tools and feed results back to the model for the next turn
+      for (const toolUse of toolUses) {
+        const result = await this.executeTool(toolUse.name, toolUse.input)
+        yield {
+          type: 'tool_result',
+          tool_use_id: toolUse.id,
+          content: result.content,
+        }
+
+        this.context.addMessage({
+          role: 'assistant',
+          content: [{ type: 'tool_use', id: toolUse.id, name: toolUse.name, input: toolUse.input }],
+        })
+        this.context.addMessage({
+          role: 'user',
+          content: [{ type: 'tool_result', tool_use_id: toolUse.id, content: result.content }],
+        })
+      }
     }
+    // Max turns reached — safety limit, stop gracefully
   }
 
   private async executeTool(name: string, params: Record<string, unknown>): Promise<ToolResult> {
@@ -158,13 +240,40 @@ export class QueryEngine {
       }
     }
 
+    // Run PreToolUse hooks
+    let effectiveParams = params
+    if (this.hookEngine) {
+      const preResult = await this.hookEngine.executePreToolUse(
+        name,
+        params,
+        'session-1',
+      )
+      if (!preResult.allowed) {
+        return {
+          success: false,
+          content: '',
+          error: preResult.reason || `Tool "${name}" blocked by hook`,
+        }
+      }
+      if (preResult.modifiedInput) {
+        effectiveParams = { ...params, ...preResult.modifiedInput }
+      }
+    }
+
     try {
-      return await tool.execute(params, {
+      const result = await tool.execute(effectiveParams, {
         cwd: process.cwd(),
         sessionId: 'session-1',
         provider: this.registry.getActive().config.id,
         model: this.registry.getActiveModel(),
       })
+
+      // Run PostToolUse hooks
+      if (this.hookEngine) {
+        await this.hookEngine.executePostToolUse(name, effectiveParams, result, 'session-1')
+      }
+
+      return result
     } catch (err) {
       return { success: false, content: '', error: String(err) }
     }
@@ -191,3 +300,9 @@ export class QueryEngine {
     this.registry.switchProvider(providerId, modelId)
   }
 }
+
+function isAbortError(err: unknown): boolean {
+  if (err instanceof Error && err.name === 'AbortError') return true
+  if (typeof DOMException !== 'undefined' && err instanceof DOMException && err.name === 'AbortError') return true
+  return false
+}