@lythos/skill-arena 0.9.42 → 0.9.44

package/README.md

@@ -49,20 +49,20 @@ Note: Claude `-p` mode has known issues with web tools in Bun.spawn (deferred to
 ```bash
 bun add -d @lythos/skill-arena
 # or use directly
-bunx @lythos/skill-arena@0.9.42 <command>
+bunx @lythos/skill-arena@0.9.44 <command>
 ```
 
 ## Quick Start
 
 ```bash
 # Single: test a deck with one agent
-bunx @lythos/skill-arena@0.9.42 single \
+bunx @lythos/skill-arena@0.9.44 single \
   --deck https://raw.githubusercontent.com/lythos-labs/lythoskill/main/examples/decks/scout.toml \
   --brief "Generate auth flow diagram"
 
 # Vs: compare multiple decks side by side
 curl -fsSL https://raw.githubusercontent.com/lythos-labs/lythoskill/main/examples/arena/research-compare/arena.toml > arena.toml
-bunx @lythos/skill-arena@0.9.42 vs --config ./arena.toml
+bunx @lythos/skill-arena@0.9.44 vs --config ./arena.toml
 ```
 
 ## Commands
@@ -71,23 +71,23 @@ bunx @lythos/skill-arena@0.9.42 vs --config ./arena.toml
 
 ```bash
 # Print execution plan without running
-bunx @lythos/skill-arena@0.9.42 vs --config arena.toml --dry-run
+bunx @lythos/skill-arena@0.9.44 vs --config arena.toml --dry-run
 
 # Execute with per-side runs_per_side and statistical aggregation
-bunx @lythos/skill-arena@0.9.42 vs --config arena.toml
+bunx @lythos/skill-arena@0.9.44 vs --config arena.toml
 ```
 
 ### Scaffold mode (legacy, manual execution)
 
 ```
-bunx @lythos/skill-arena@0.9.42 scaffold --task "Generate auth flow diagram" \
+bunx @lythos/skill-arena@0.9.44 scaffold --task "Generate auth flow diagram" \
   --decks https://raw.githubusercontent.com/lythos-labs/lythoskill/main/examples/decks/scout.toml,https://raw.githubusercontent.com/lythos-labs/lythoskill/main/examples/decks/documents.toml
 ```
 
 ### Viz
 
 ```bash
-bunx @lythos/skill-arena@0.9.42 viz runs/arena-<id>/
+bunx @lythos/skill-arena@0.9.44 viz runs/arena-<id>/
 ```
 
 ## Skill Documentation
@@ -101,7 +101,7 @@ The agent-visible **Skill** layer documentation is here:
 Part of the [lythoskill](https://github.com/lythos-labs/lythoskill) ecosystem — the thin-skill pattern separates heavy logic (this npm package) from lightweight agent instructions (SKILL.md).
 
 ```
-Starter (this package) → npm publish → bunx @lythos/skill-arena@0.9.42 ...
+Starter (this package) → npm publish → bunx @lythos/skill-arena@0.9.44 ...
 Skill   (packages/<name>/skill/)     → build → SKILL.md + thin scripts
 Output  (skills/<name>/)             → git commit → agent-visible skill
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lythos/skill-arena",
-  "version": "0.9.42",
+  "version": "0.9.44",
   "description": "Skill Arena — benchmark skill effectiveness with controlled-variable comparison",
   "keywords": [
     "ai-agent",

package/src/cli.ts

@@ -67,6 +67,8 @@ Examples:
   lythoskill-arena single \\
     --deck https://raw.githubusercontent.com/lythos-labs/lythoskill/main/examples/decks/scout.toml \\
     --brief "Generate auth flow diagram" --player kimi
+  # If you already have a local deck file, point to it directly:
+  # lythoskill-arena single --deck ./examples/decks/scout.toml --brief "..."
 
   # Multi-side comparison (declarative)
   curl -fsSL https://raw.githubusercontent.com/lythos-labs/lythoskill/main/examples/arena/add-remove/arena.toml > arena.toml
@@ -97,21 +99,71 @@ async function singleRun(args: string[]) {
   if (!opts.deck) {
     console.error(`❌ --deck <path|url> is required.
    --deck accepts local paths and http/https URLs (auto-fetched).
-   Example: lythoskill-arena single \\
-              --deck https://raw.githubusercontent.com/lythos-labs/lythoskill/main/examples/decks/scout.toml \\
-              --brief "your task"`)
+
+   Example (no local file needed — URL is auto-fetched):
+     lythoskill-arena single \\
+       --deck https://raw.githubusercontent.com/lythos-labs/lythoskill/main/examples/decks/scout.toml \\
+       --brief "your task"
+
+   Or with a local deck file you already have:
+     lythoskill-arena single --deck ./examples/decks/scout.toml --brief "your task"`)
     process.exit(1)
   }
   if (!opts.task && (!opts.brief || !opts.brief.trim())) {
     console.error(`❌ --task <path> or --brief "<text>" is required.
    --task reads a .agent.md scenario file; --brief takes inline text.
-   Example: lythoskill-arena single \\
-              --deck https://raw.githubusercontent.com/lythos-labs/lythoskill/main/examples/decks/scout.toml \\
-              --brief "your task"`)
+
+   Example (no local file needed — URL is auto-fetched):
+     lythoskill-arena single \\
+       --deck https://raw.githubusercontent.com/lythos-labs/lythoskill/main/examples/decks/scout.toml \\
+       --brief "your task"
+
+   Or with a local deck file:
+     lythoskill-arena single --deck ./examples/decks/scout.toml --brief "your task"`)
     process.exit(1)
   }
 
-  const { resolve, join } = await import('node:path')
+  // Validate --task file early — before any URL fetch — so bad path fails fast without a wasted network call.
+  let resolvedTaskPath: string | undefined
+  if (opts.task) {
+    resolvedTaskPath = resolve(opts.task)
+    if (!existsSync(resolvedTaskPath)) {
+      console.error(`❌ Task file not found: ${resolvedTaskPath}
+   Use --brief for inline tasks, or point --task to an existing .agent.md file.
+   Format: name + description + Given/When/Then/Judge sections.
+
+   Example (URL):  lythoskill-arena single --brief "your task" --deck https://raw.githubusercontent.com/lythos-labs/lythoskill/main/examples/decks/scout.toml
+   Or (local):     lythoskill-arena single --brief "your task" --deck ./examples/decks/scout.toml`)
+      process.exit(1)
+    }
+    const raw = readFileSync(resolvedTaskPath, 'utf-8')
+    if (!raw.startsWith('---')) {
+      console.error(`❌ Invalid .agent.md: missing frontmatter (must start with "---")
+   Correct format:
+   ---
+   name: my-scenario
+   description: what this tests
+   timeout: 120000
+   ---
+   ## Given
+   ...
+   ## When
+   ...
+   ## Then
+   ...
+   ## Judge
+   ...
+   Template: playground/arena-one-shot/TASK-arena.agent.md`)
+      process.exit(1)
+    }
+    if (!raw.includes('## When')) {
+      console.error(`❌ Invalid .agent.md: missing "## When" section.
+   The ## When section defines what the agent should do.
+   See template: playground/arena-one-shot/TASK-arena.agent.md`)
+      process.exit(1)
+    }
+  }
+
   const { existsSync: deckExists, writeFileSync: deckWrite } = await import('node:fs')
   let deckPath: string
   if (opts.deck.startsWith('http://') || opts.deck.startsWith('https://')) {
@@ -124,8 +176,17 @@ async function singleRun(args: string[]) {
     } catch { /* keep original url */ }
     const dest = resolve(process.cwd(), 'arena-deck.toml')
     console.log(`📥 Fetching arena deck: ${url}`)
-    const res = await fetch(url, { signal: AbortSignal.timeout(30_000) })
-    if (!res.ok) { console.error(`❌ Failed to fetch deck (HTTP ${res.status}): ${url}`); process.exit(1) }
+    let res: Response
+    try { res = await fetch(url, { signal: AbortSignal.timeout(30_000) }) } catch (e: any) {
+      console.error(`❌ Cannot reach ${url}
+   Network issue? Try a GitHub proxy mirror:
+     ${url.replace('https://raw.githubusercontent.com/', 'https://ghfast.top/https://raw.githubusercontent.com/')}
+   Or download manually and reference the local file.`)
+      process.exit(1)
+    }
+    if (!res.ok) { console.error(`❌ Failed to fetch deck (HTTP ${res.status}): ${url}
+   Try a GitHub proxy mirror:
+     ${url.replace('https://raw.githubusercontent.com/', 'https://ghfast.top/https://raw.githubusercontent.com/')}`); process.exit(1) }
     deckWrite(dest, await res.text())
     console.log(`   → saved to ${dest}`)
     deckPath = dest
@@ -143,43 +204,16 @@ async function singleRun(args: string[]) {
   try { await import('@lythos/agent-adapter-deepseek-serve') } catch { /* package not installed */ }
   const { runAgentScenario } = await import('@lythos/test-utils/agent-bdd')
   const { resolvePlayer } = await import('./player')
-  const { readFileSync, writeFileSync, mkdirSync } = await import('node:fs')
 
   const player = resolvePlayer(opts.player ?? 'kimi')
   const agent = useAgent(player)
   const outDir = opts.out ? resolve(opts.out) : join(process.cwd(), `agent-output-${new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19)}`)
   mkdirSync(outDir, { recursive: true })
 
-  // Resolve task: --brief builds scenario directly, --task reads .agent.md file
+  // Resolve task: --brief builds scenario directly, --task uses pre-validated path
   const scenarioOpt: Record<string, unknown> = {}
-  if (opts.task) {
-    const taskPath = resolve(opts.task)
-    if (!existsSync(taskPath)) { console.error(`❌ Task file not found: ${taskPath}
-   Use --brief for inline tasks, or point --task to an existing .agent.md file.
-   Format: name + description + Given/When/Then/Judge sections.
-   Example: lythoskill-arena single --brief "your task" --deck <url>`); process.exit(1) }
-    scenarioOpt.scenarioPath = taskPath
-    // Quick validation: check frontmatter presence
-    const raw = readFileSync(taskPath, 'utf-8')
-    if (!raw.startsWith('---')) { console.error(`❌ Invalid .agent.md: missing frontmatter (must start with "---")
-   Correct format:
-   ---
-   name: my-scenario
-   description: what this tests
-   timeout: 120000
-   ---
-   ## Given
-   ...
-   ## When
-   ...
-   ## Then
-   ...
-   ## Judge
-   ...
-   Template: playground/arena-one-shot/TASK-arena.agent.md`); process.exit(1) }
-    if (!raw.includes('## When')) { console.error(`❌ Invalid .agent.md: missing "## When" section.
-   The ## When section defines what the agent should do.
-   See template: playground/arena-one-shot/TASK-arena.agent.md`); process.exit(1) }
+  if (resolvedTaskPath) {
+    scenarioOpt.scenarioPath = resolvedTaskPath
   } else {
     scenarioOpt.scenario = {
       name: 'ad-hoc task',