Skip to content

PR_DESCRIPTION.md

Latest commit

 

History

History
68 lines (58 loc) · 5.69 KB

PR_DESCRIPTION.md

File metadata and controls

68 lines (58 loc) · 5.69 KB
Raw

Overview

This PR completes the full integration of the Skill Pilot provider, implements a complete ecosystem rebrand to spcode, and introduces new dynamic skill-loading features.

To ensure architectural integrity, no "hacks" were used. The Skill Pilot integration hooks natively into the existing provider and auth configurations, ensuring seamless compatibility with both headless (exec) and interactive (tui) modes.

Key Features & Changes

1. The spcode Rebrand

  • Binary & NPM: Renamed the Rust binary from codex to spcode. Updated all package.json namespaces to @skill-pilot/spcode.
  • Node.js Wrapper: Renamed the executable wrapper to bin/spcode.js.
  • UI & Docs: Updated all TUI labels, error messages, default .spcode home directories, and README.md documentation to reflect the new brand.

2. Skill Pilot Provider & Auth Routing

  • Environment Detection: The CLI automatically detects SKILL_PILOT_BASE_URL. When set, it disables standard OSS fallback logic and treats Skill Pilot as a primary, authenticated cloud provider.
  • Native Auth Prompt: Bound SKILL_PILOT_API_KEY to the custom provider profile. If the key is missing, the CLI natively prompts the user for it without ever falling back to the OpenAI login screen.
  • Model Parsing: Routed the Skill Pilot provider through the official ModelsResponse parser. This ensures the /model TUI command successfully fetches from http://127.0.0.1:8000/v1/models and perfectly maps custom reasoning levels (low, medium, high, xhigh).
  • SQLite Fix: Fixed the fallback model slug to strictly use skill-pilot to prevent "thread not found" database crashes during headless execution.

3. Dynamic Skill Loading

Added two new CLI arguments to both exec and TUI modes:

  • --skills-dir <DIR>: Specifies the directory scanned for SKILL.md files (defaults to <project>/.agent, falling back to .agents/skills).
  • --skills <SKILLS>: Accepts a comma-separated list of skills to load, all (default), or none to disable skills entirely.

4. Proprietary Skill Pilot Agent

  • Created a standalone Node.js/TypeScript agent in core/engine/skill_pilot_agent/ utilizing @openai/agents.
  • Added a Bash wrapper at core/bin/skill-pilot-agent.
  • Configured config/ai_providers.json5 to route default.background_llm tasks to this new agent.

5. Multi-Provider Agent with Direct API Access

  • Architecture: Replaced the single-proxy pattern (SKILL_PILOT_BASE_URL) with direct per-provider API access. Each provider specifies its own base URL, API key env var, and protocol adapter.
  • Provider Config: providers.json maps model names to providers (OpenAI, DeepSeek, Anthropic). New providers require one adapter + one config entry.
  • Adapters:
    • OpenAI — pass-through to @openai/agents SDK. Supports any OpenAI-compatible endpoint (OpenAI, DeepSeek, Groq).
    • Anthropic — native @anthropic-ai/sdk integration with tool schema translation and multi-turn tool execution loop.
    • Gemini — native @google/generative-ai integration with tool schema translation and multi-turn tool execution loop.
  • Reasoning Effort: Added --effort CLI flag (low, medium, high, xhigh). Mapped to provider-specific parameters (OpenAI: reasoning.effort, Anthropic: thinking.budget_tokens, Gemini: thinkingBudget).
  • Error Handling: Unknown model, missing API key, and config file errors all fail loudly with actionable messages listing available options.

Files Changed

File Change
core/engine/skill_pilot_agent/package.json Added @anthropic-ai/sdk, @google/generative-ai
core/engine/skill_pilot_agent/providers.json New — provider configuration
core/engine/skill_pilot_agent/src/providers/types.ts New — shared provider types
core/engine/skill_pilot_agent/src/providers/config.ts New — config loader and model resolution
core/engine/skill_pilot_agent/src/providers/openai.ts New — OpenAI-compatible adapter
core/engine/skill_pilot_agent/src/providers/anthropic.ts New — Anthropic adapter
core/engine/skill_pilot_agent/src/providers/gemini.ts New — Gemini adapter
core/engine/skill_pilot_agent/src/index.ts Modified — wired provider registry, --effort flag, adapter routing

Smoke Test Results

  • Missing --model lists all available models from providers.json
  • Unknown model errors with full list of available models
  • Missing API key shows provider-specific error (e.g., OPENAI_API_KEY not set. Required by provider 'openai' for model 'gpt-5.5'.)
  • --effort high flag accepted, provider info shown at startup
  • --help shows --effort option
  • TypeScript compilation and build pass clean

Acceptance Criteria Checklist

All provided test cases have been verified locally:

  • Test 1: Fresh install without SKILL_PILOT_BASE_URL behaves as vanilla Codex (OpenAI login).
  • Test 2: Fresh install with URL + Key bypasses OpenAI auth entirely and uses the Skill Pilot backend natively.
  • Test 3: Fresh install with URL but NO Key natively prompts for SKILL_PILOT_API_KEY.
  • Test 4: Invalid SKILL_PILOT_API_KEY throws a connection/auth error without falling back to OpenAI.
  • Test 5: Existing OpenAI logins are completely ignored when SKILL_PILOT_BASE_URL is active.
  • Test 6: /models command fetches directly from the Skill Pilot API and accurately displays all custom models and reasoning efforts.
  • Test 7: Seamlessly switches between OpenAI and Skill Pilot modes based purely on the presence of the environment variable.
  • Test 8: Unreachable URLs throw clear connection errors without triggering OpenAI fallbacks.