compact-agent 1.10.0 → 1.11.0

package/resources/ecc/skills/eval-harness/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: eval-harness
 description: Formal evaluation framework for Claude Code sessions implementing eval-driven development (EDD) principles
-allowed-tools: Read, Write, Edit, Bash, Grep, Glob
+origin: ECC
+tools: Read, Write, Edit, Bash, Grep, Glob
 ---
 
 # Eval Harness Skill
@@ -233,3 +234,37 @@ Capability: 5/5 passed (pass@3: 100%)
 Regression: 3/3 passed (pass^3: 100%)
 Status: SHIP IT
 ```
+
+## Product Evals (v1.8)
+
+Use product evals when behavior quality cannot be captured by unit tests alone.
+
+### Grader Types
+
+1. Code grader (deterministic assertions)
+2. Rule grader (regex/schema constraints)
+3. Model grader (LLM-as-judge rubric)
+4. Human grader (manual adjudication for ambiguous outputs)
+
+### pass@k Guidance
+
+- `pass@1`: direct reliability
+- `pass@3`: practical reliability under controlled retries
+- `pass^3`: stability test (all 3 runs must pass)
+
+Recommended thresholds:
+- Capability evals: pass@3 >= 0.90
+- Regression evals: pass^3 = 1.00 for release-critical paths
+
+### Eval Anti-Patterns
+
+- Overfitting prompts to known eval examples
+- Measuring only happy-path outputs
+- Ignoring cost and latency drift while chasing pass rates
+- Allowing flaky graders in release gates
+
+### Minimal Eval Artifact Layout
+
+- `.claude/evals/<feature>.md` definition
+- `.claude/evals/<feature>.log` run history
+- `docs/releases/<version>/eval-summary.md` release snapshot

package/resources/ecc/skills/evm-token-decimals/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: evm-token-decimals
+description: Prevent silent decimal mismatch bugs across EVM chains. Covers runtime decimal lookup, chain-aware caching, bridged-token precision drift, and safe normalization for bots, dashboards, and DeFi tools.
+origin: ECC direct-port adaptation
+version: "1.0.0"
+---
+
+# EVM Token Decimals
+
+Silent decimal mismatches are one of the easiest ways to ship balances or USD values that are off by orders of magnitude without throwing an error.
+
+## When to Use
+
+- Reading ERC-20 balances in Python, TypeScript, or Solidity
+- Calculating fiat values from on-chain balances
+- Comparing token amounts across multiple EVM chains
+- Handling bridged assets
+- Building portfolio trackers, bots, or aggregators
+
+## How It Works
+
+Never assume stablecoins use the same decimals everywhere. Query `decimals()` at runtime, cache by `(chain_id, token_address)`, and use decimal-safe math for value calculations.
+
+## Examples
+
+### Query decimals at runtime
+
+```python
+from decimal import Decimal
+from web3 import Web3
+
+ERC20_ABI = [
+    {"name": "decimals", "type": "function", "inputs": [],
+     "outputs": [{"type": "uint8"}], "stateMutability": "view"},
+    {"name": "balanceOf", "type": "function",
+     "inputs": [{"name": "account", "type": "address"}],
+     "outputs": [{"type": "uint256"}], "stateMutability": "view"},
+]
+
+def get_token_balance(w3: Web3, token_address: str, wallet: str) -> Decimal:
+    contract = w3.eth.contract(
+        address=Web3.to_checksum_address(token_address),
+        abi=ERC20_ABI,
+    )
+    decimals = contract.functions.decimals().call()
+    raw = contract.functions.balanceOf(Web3.to_checksum_address(wallet)).call()
+    return Decimal(raw) / Decimal(10 ** decimals)
+```
+
+Do not hardcode `1_000_000` because a symbol usually has 6 decimals somewhere else.
+
+### Cache by chain and token
+
+```python
+from functools import lru_cache
+
+@lru_cache(maxsize=512)
+def get_decimals(chain_id: int, token_address: str) -> int:
+    w3 = get_web3_for_chain(chain_id)
+    contract = w3.eth.contract(
+        address=Web3.to_checksum_address(token_address),
+        abi=ERC20_ABI,
+    )
+    return contract.functions.decimals().call()
+```
+
+### Handle odd tokens defensively
+
+```python
+try:
+    decimals = contract.functions.decimals().call()
+except Exception:
+    logging.warning(
+        "decimals() reverted on %s (chain %s), defaulting to 18",
+        token_address,
+        chain_id,
+    )
+    decimals = 18
+```
+
+Log the fallback and keep it visible. Old or non-standard tokens still exist.
+
+### Normalize to 18-decimal WAD in Solidity
+
+```solidity
+interface IERC20Metadata {
+    function decimals() external view returns (uint8);
+}
+
+function normalizeToWad(address token, uint256 amount) internal view returns (uint256) {
+    uint8 d = IERC20Metadata(token).decimals();
+    if (d == 18) return amount;
+    if (d < 18) return amount * 10 ** (18 - d);
+    return amount / 10 ** (d - 18);
+}
+```
+
+### TypeScript with ethers
+
+```typescript
+import { Contract, formatUnits } from 'ethers';
+
+const ERC20_ABI = [
+  'function decimals() view returns (uint8)',
+  'function balanceOf(address) view returns (uint256)',
+];
+
+async function getBalance(provider: any, tokenAddress: string, wallet: string): Promise<string> {
+  const token = new Contract(tokenAddress, ERC20_ABI, provider);
+  const [decimals, raw] = await Promise.all([
+    token.decimals(),
+    token.balanceOf(wallet),
+  ]);
+  return formatUnits(raw, decimals);
+}
+```
+
+### Quick on-chain check
+
+```bash
+cast call <token_address> "decimals()(uint8)" --rpc-url <rpc>
+```
+
+## Rules
+
+- Always query `decimals()` at runtime
+- Cache by chain plus token address, not symbol
+- Use `Decimal`, `BigInt`, or equivalent exact math, not float
+- Re-query decimals after bridging or wrapper changes
+- Normalize internal accounting consistently before comparison or pricing

package/resources/ecc/skills/exa-search/SKILL.md

@@ -1,10 +1,15 @@
 ---
 name: exa-search
 description: Neural search via Exa MCP for web, code, and company research. Use when the user needs web search, code examples, company intel, people lookup, or AI-powered deep research with Exa's neural search engine.
+origin: ECC
 ---
 
 # Exa Search
 
+> **Drift-prone skill.** Exa MCP tool names, parameters, and account limits can
+> change. Confirm the exposed tool surface and current Exa docs before relying
+> on a specific search mode, category, or livecrawl behavior.
+
 Neural search for web content, code, companies, and people via the Exa MCP server.
 
 ## When to Activate
@@ -29,6 +34,8 @@ Exa MCP server must be configured. Add to `~/.claude.json`:
 ```
 
 Get an API key at [exa.ai](https://exa.ai).
+This repo's current Exa setup documents the tool surface exposed here: `web_search_exa` and `get_code_context_exa`.
+If your Exa server exposes additional tools, verify their exact names before depending on them in docs or prompts.
 
 ## Core Tools
 
@@ -45,29 +52,9 @@ web_search_exa(query: "latest AI developments 2026", numResults: 5)
 |-------|------|---------|-------|
 | `query` | string | required | Search query |
 | `numResults` | number | 8 | Number of results |
-
-### web_search_advanced_exa
-Filtered search with domain and date constraints.
-
-```
-web_search_advanced_exa(
-  query: "React Server Components best practices",
-  numResults: 5,
-  includeDomains: ["github.com", "react.dev"],
-  startPublishedDate: "2025-01-01"
-)
-```
-
-**Parameters:**
-
-| Param | Type | Default | Notes |
-|-------|------|---------|-------|
-| `query` | string | required | Search query |
-| `numResults` | number | 8 | Number of results |
-| `includeDomains` | string[] | none | Limit to specific domains |
-| `excludeDomains` | string[] | none | Exclude specific domains |
-| `startPublishedDate` | string | none | ISO date filter (start) |
-| `endPublishedDate` | string | none | ISO date filter (end) |
+| `type` | string | `auto` | Search mode |
+| `livecrawl` | string | `fallback` | Prefer live crawling when needed |
+| `category` | string | none | Optional focus such as `company` or `research paper` |
 
 ### get_code_context_exa
 Find code examples and documentation from GitHub, Stack Overflow, and docs sites.
@@ -83,52 +70,6 @@ get_code_context_exa(query: "Python asyncio patterns", tokensNum: 3000)
 | `query` | string | required | Code or API search query |
 | `tokensNum` | number | 5000 | Content tokens (1000-50000) |
 
-### company_research_exa
-Research companies for business intelligence and news.
-
-```
-company_research_exa(companyName: "Anthropic", numResults: 5)
-```
-
-**Parameters:**
-
-| Param | Type | Default | Notes |
-|-------|------|---------|-------|
-| `companyName` | string | required | Company name |
-| `numResults` | number | 5 | Number of results |
-
-### people_search_exa
-Find professional profiles and bios.
-
-```
-people_search_exa(query: "AI safety researchers at Anthropic", numResults: 5)
-```
-
-### crawling_exa
-Extract full page content from a URL.
-
-```
-crawling_exa(url: "https://example.com/article", tokensNum: 5000)
-```
-
-**Parameters:**
-
-| Param | Type | Default | Notes |
-|-------|------|---------|-------|
-| `url` | string | required | URL to extract |
-| `tokensNum` | number | 5000 | Content tokens |
-
-### deep_researcher_start / deep_researcher_check
-Start an AI research agent that runs asynchronously.
-
-```
-# Start research
-deep_researcher_start(query: "comprehensive analysis of AI code editors in 2026")
-
-# Check status (returns results when complete)
-deep_researcher_check(researchId: "<id from start>")
-```
-
 ## Usage Patterns
 
 ### Quick Lookup
@@ -141,27 +82,24 @@ web_search_exa(query: "Node.js 22 new features", numResults: 3)
 get_code_context_exa(query: "Rust error handling patterns Result type", tokensNum: 3000)
 ```
 
-### Company Due Diligence
+### Company or People Research
 ```
-company_research_exa(companyName: "Vercel", numResults: 5)
-web_search_advanced_exa(query: "Vercel funding valuation 2026", numResults: 3)
+web_search_exa(query: "Vercel funding valuation 2026", numResults: 3, category: "company")
+web_search_exa(query: "site:linkedin.com/in AI safety researchers Anthropic", numResults: 5)
 ```
 
 ### Technical Deep Dive
 ```
-# Start async research
-deep_researcher_start(query: "WebAssembly component model status and adoption")
-# ... do other work ...
-deep_researcher_check(researchId: "<id>")
+web_search_exa(query: "WebAssembly component model status and adoption", numResults: 5)
+get_code_context_exa(query: "WebAssembly component model examples", tokensNum: 4000)
 ```
 
 ## Tips
 
-- Use `web_search_exa` for broad queries, `web_search_advanced_exa` for filtered results
+- Use `web_search_exa` for current information, company lookups, and broad discovery
+- Use search operators like `site:`, quoted phrases, and `intitle:` to narrow results
 - Lower `tokensNum` (1000-2000) for focused code snippets, higher (5000+) for comprehensive context
-- Combine `company_research_exa` with `web_search_advanced_exa` for thorough company analysis
-- Use `crawling_exa` to get full content from specific URLs found in search results
-- `deep_researcher_start` is best for comprehensive topics that benefit from AI synthesis
+- Use `get_code_context_exa` when you need API usage or code examples rather than general web pages
 
 ## Related Skills
 

package/resources/ecc/skills/fal-ai-media/SKILL.md

@@ -1,10 +1,15 @@
 ---
 name: fal-ai-media
 description: Unified media generation via fal.ai MCP — image, video, and audio. Covers text-to-image (Nano Banana), text/image-to-video (Seedance, Kling, Veo 3), text-to-speech (CSM-1B), and video-to-audio (ThinkSound). Use when the user wants to generate images, videos, or audio with AI.
+origin: ECC
 ---
 
 # fal.ai Media Generation
 
+> **Drift-prone skill.** fal.ai model IDs, pricing, inputs, and MCP tool names
+> change quickly. Search or fetch the current model metadata before promising a
+> specific model, parameter, output format, or cost.
+
 Generate images, videos, and audio using fal.ai models via MCP.
 
 ## When to Activate
@@ -51,8 +56,8 @@ Best for: quick iterations, drafts, text-to-image, image editing.
 
 ```
 generate(
-  model_name: "fal-ai/nano-banana-2",
-  input: {
+  app_id: "fal-ai/nano-banana-2",
+  input_data: {
     "prompt": "a futuristic cityscape at sunset, cyberpunk style",
     "image_size": "landscape_16_9",
     "num_images": 1,
@@ -66,8 +71,8 @@ Best for: production images, realism, typography, detailed prompts.
 
 ```
 generate(
-  model_name: "fal-ai/nano-banana-pro",
-  input: {
+  app_id: "fal-ai/nano-banana-pro",
+  input_data: {
     "prompt": "professional product photo of wireless headphones on marble surface, studio lighting",
     "image_size": "square",
     "num_images": 1,
@@ -95,8 +100,8 @@ upload(file_path: "/path/to/image.png")
 
 # Then generate with image input
 generate(
-  model_name: "fal-ai/nano-banana-2",
-  input: {
+  app_id: "fal-ai/nano-banana-2",
+  input_data: {
     "prompt": "same scene but in watercolor style",
     "image_url": "<uploaded_url>",
     "image_size": "landscape_16_9"
@@ -113,8 +118,8 @@ Best for: text-to-video, image-to-video with high motion quality.
 
 ```
 generate(
-  model_name: "fal-ai/seedance-1-0-pro",
-  input: {
+  app_id: "fal-ai/seedance-1-0-pro",
+  input_data: {
     "prompt": "a drone flyover of a mountain lake at golden hour, cinematic",
     "duration": "5s",
     "aspect_ratio": "16:9",
@@ -128,8 +133,8 @@ Best for: text/image-to-video with native audio generation.
 
 ```
 generate(
-  model_name: "fal-ai/kling-video/v3/pro",
-  input: {
+  app_id: "fal-ai/kling-video/v3/pro",
+  input_data: {
     "prompt": "ocean waves crashing on a rocky coast, dramatic clouds",
     "duration": "5s",
     "aspect_ratio": "16:9"
@@ -142,8 +147,8 @@ Best for: video with generated sound, high visual quality.
 
 ```
 generate(
-  model_name: "fal-ai/veo-3",
-  input: {
+  app_id: "fal-ai/veo-3",
+  input_data: {
     "prompt": "a bustling Tokyo street market at night, neon signs, crowd noise",
     "aspect_ratio": "16:9"
   }
@@ -155,8 +160,8 @@ Start from an existing image:
 
 ```
 generate(
-  model_name: "fal-ai/seedance-1-0-pro",
-  input: {
+  app_id: "fal-ai/seedance-1-0-pro",
+  input_data: {
     "prompt": "camera slowly zooms out, gentle wind moves the trees",
     "image_url": "<uploaded_image_url>",
     "duration": "5s"
@@ -183,8 +188,8 @@ Text-to-speech with natural, conversational quality.
 
 ```
 generate(
-  model_name: "fal-ai/csm-1b",
-  input: {
+  app_id: "fal-ai/csm-1b",
+  input_data: {
     "text": "Hello, welcome to the demo. Let me show you how this works.",
     "speaker_id": 0
   }
@@ -196,8 +201,8 @@ Generate matching audio from video content.
 
 ```
 generate(
-  model_name: "fal-ai/thinksound",
-  input: {
+  app_id: "fal-ai/thinksound",
+  input_data: {
     "video_url": "<video_url>",
     "prompt": "ambient forest sounds with birds chirping"
   }
@@ -248,7 +253,14 @@ sfx = coll.generate_sound_effect(prompt="thunder crack followed by rain")
 Before generating, check estimated cost:
 
 ```
-estimate_cost(model_name: "fal-ai/nano-banana-pro", input: {...})
+estimate_cost(
+  estimate_type: "unit_price",
+  endpoints: {
+    "fal-ai/nano-banana-pro": {
+      "unit_quantity": 1
+    }
+  }
+)
 ```
 
 ## Model Discovery
@@ -257,7 +269,7 @@ Find models for specific tasks:
 
 ```
 search(query: "text to video")
-find(model_name: "fal-ai/seedance-1-0-pro")
+find(endpoint_ids: ["fal-ai/seedance-1-0-pro"])
 models()
 ```