lastlight 0.1.15 → 0.2.1

package/skills/github-orchestrator/SKILL.md

@@ -1,103 +0,0 @@
----
-name: github-orchestrator
-description: >
-  Central coordinator for all GitHub work — routes events to the right action
-  (triage, review, build) and orchestrates the Architect→Executor→Reviewer cycle
-  for build requests. All work is tracked via GitHub issues.
-version: 3.0.0
-tags: [github, orchestrator, webhook, build-cycle, coordination]
-related_skills: [architect, pr-review, issue-triage, repo-health]
----
-
-# GitHub Orchestrator
-
-The build cycle is orchestrated programmatically by the harness (`src/engine/orchestrator.ts`).
-This skill file provides guidelines for each phase that the agent should follow.
-
-## Git Authentication
-
-Git is pre-configured by the harness. Clone, push, pull, and fetch work natively:
-
-```bash
-git clone https://github.com/owner/repo.git
-```
-
-If auth fails after ~1 hour, call `refresh_git_auth` MCP tool with the repo path.
-
-## Phase Guidelines
-
-### Phase 0: Context Assembly
-- Read issue context via MCP tools (get_issue, list_issue_comments)
-- Clone the repo via `clone_repo` MCP tool
-- Check for existing branch: `git branch -a --list '*lastlight/{issue-number}*'`
-- If branch exists, read `.lastlight/issue-{N}/status.md` to resume
-- Read repo docs: CLAUDE.md, AGENTS.md, CONTRIBUTING.md
-- Assemble context snapshot: task, desired outcome, known facts, constraints, unknowns, touchpoints
-
-### Phase 1: Architect
-- Create branch: `git checkout -b lastlight/{issue-number}-{slug}`
-- Analyze codebase (read-only — never edit files)
-- Reference specific locations as `file:line`
-- Write plan to `.lastlight/issue-{N}/architect-plan.md`
-- Plan must include: problem statement, files to modify, implementation steps, risks, test strategy, complexity estimate
-- Commit and push the plan
-
-### Phase 2: Executor
-- Read the architect plan from `.lastlight/issue-{N}/architect-plan.md`
-- Follow TDD: write failing test first, then implement, then verify
-- Run tests and include fresh verification output
-- Write summary to `.lastlight/issue-{N}/executor-summary.md`
-- Commit with intent-first messages + Tested/Scope-risk trailers
-
-### Phase 3: Reviewer
-- Independent context — no shared state with executor
-- Review ONLY changed files: `git diff main...HEAD`
-- Read architect-plan.md and executor-summary.md for context
-- Run tests independently
-- Write verdict to `.lastlight/issue-{N}/reviewer-verdict.md`
-- End with exactly: APPROVED or REQUEST_CHANGES
-
-### Phase 4: Fix Loop (max 2 cycles)
-- Fix ONLY issues from reviewer-verdict.md
-- APPEND to executor-summary.md (never overwrite)
-- Re-run reviewer after each fix
-
-### Phase 5: Create PR
-- Use `create_pull_request` MCP tool
-- Link to tracking issue with "Closes #N"
-- Include links to plan, summary, and verdict files on the branch
-- Post PR link as comment on the tracking issue
-
-## Status File: `.lastlight/issue-{N}/status.md`
-
-```markdown
-# Orchestrator Status: #{issue-number}
-
-| Field | Value |
-|-------|-------|
-| issue | {owner}/{repo}#{issue-number} |
-| branch | lastlight/{issue-number}-{slug} |
-| current_phase | {phase_0 / architect / executor / reviewer / fix_loop_N / complete} |
-| last_updated | {ISO timestamp} |
-| fix_cycles | {0, 1, 2} |
-| pr_number | {number or empty} |
-
-## Phase Log
-| Phase | Status | Timestamp | Notes |
-|-------|--------|-----------|-------|
-```
-
-Update after each phase transition. Commit + push alongside phase artifacts.
-
-## Tool Usage
-
-- **GitHub API** (comments, labels, PRs, issues): use MCP tools
-- **Reading repo files**: clone once, read locally. Never use get_file_contents for bulk reads.
-- **Git auth**: pre-configured by harness. Just `git clone`. Call `refresh_git_auth` if auth expires.
-- **Suppress noise**: `git clone --quiet`, `git push --quiet`, `CI=true npm install`
-
-## Always Ignore
-
-- Actions: deleted, edited, labeled, unlabeled, assigned, closed, synchronize
-- Bot senders (sender.type === "Bot" or login ending in "[bot]")
-- Events where sender matches the bot's own login

package/skills/mcp/DESCRIPTION.md

@@ -1,3 +0,0 @@
----
-description: Skills for working with MCP (Model Context Protocol) servers, tools, and integrations. Includes the built-in native MCP client (configure servers in config.yaml for automatic tool discovery) and the mcporter CLI bridge for ad-hoc server interaction.
----

package/skills/mcp/mcporter/SKILL.md

@@ -1,122 +0,0 @@
----
-name: mcporter
-description: Use the mcporter CLI to list, configure, auth, and call MCP servers/tools directly (HTTP or stdio), including ad-hoc servers, config edits, and CLI/type generation.
-version: 1.0.0
-author: community
-license: MIT
-metadata:
-  hermes:
-    tags: [MCP, Tools, API, Integrations, Interop]
-    homepage: https://mcporter.dev
-prerequisites:
-  commands: [npx]
----
-
-# mcporter
-
-Use `mcporter` to discover, call, and manage [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) servers and tools directly from the terminal.
-
-## Prerequisites
-
-Requires Node.js:
-```bash
-# No install needed (runs via npx)
-npx mcporter list
-
-# Or install globally
-npm install -g mcporter
-```
-
-## Quick Start
-
-```bash
-# List MCP servers already configured on this machine
-mcporter list
-
-# List tools for a specific server with schema details
-mcporter list <server> --schema
-
-# Call a tool
-mcporter call <server.tool> key=value
-```
-
-## Discovering MCP Servers
-
-mcporter auto-discovers servers configured by other MCP clients (Claude Desktop, Cursor, etc.) on the machine. To find new servers to use, browse registries like [mcpfinder.dev](https://mcpfinder.dev) or [mcp.so](https://mcp.so), then connect ad-hoc:
-
-```bash
-# Connect to any MCP server by URL (no config needed)
-mcporter list --http-url https://some-mcp-server.com --name my_server
-
-# Or run a stdio server on the fly
-mcporter list --stdio "npx -y @modelcontextprotocol/server-filesystem" --name fs
-```
-
-## Calling Tools
-
-```bash
-# Key=value syntax
-mcporter call linear.list_issues team=ENG limit:5
-
-# Function syntax
-mcporter call "linear.create_issue(title: \"Bug fix needed\")"
-
-# Ad-hoc HTTP server (no config needed)
-mcporter call https://api.example.com/mcp.fetch url=https://example.com
-
-# Ad-hoc stdio server
-mcporter call --stdio "bun run ./server.ts" scrape url=https://example.com
-
-# JSON payload
-mcporter call <server.tool> --args '{"limit": 5}'
-
-# Machine-readable output (recommended for Hermes)
-mcporter call <server.tool> key=value --output json
-```
-
-## Auth and Config
-
-```bash
-# OAuth login for a server
-mcporter auth <server | url> [--reset]
-
-# Manage config
-mcporter config list
-mcporter config get <key>
-mcporter config add <server>
-mcporter config remove <server>
-mcporter config import <path>
-```
-
-Config file location: `./config/mcporter.json` (override with `--config`).
-
-## Daemon
-
-For persistent server connections:
-```bash
-mcporter daemon start
-mcporter daemon status
-mcporter daemon stop
-mcporter daemon restart
-```
-
-## Code Generation
-
-```bash
-# Generate a CLI wrapper for an MCP server
-mcporter generate-cli --server <name>
-mcporter generate-cli --command <url>
-
-# Inspect a generated CLI
-mcporter inspect-cli <path> [--json]
-
-# Generate TypeScript types/client
-mcporter emit-ts <server> --mode client
-mcporter emit-ts <server> --mode types
-```
-
-## Notes
-
-- Use `--output json` for structured output that's easier to parse
-- Ad-hoc servers (HTTP URL or `--stdio` command) work without any config — useful for one-off calls
-- OAuth auth may require interactive browser flow — use `terminal(command="mcporter auth <server>", pty=true)` if needed

package/skills/mcp/native-mcp/SKILL.md

@@ -1,356 +0,0 @@
----
-name: native-mcp
-description: Built-in MCP (Model Context Protocol) client that connects to external MCP servers, discovers their tools, and registers them as native Hermes Agent tools. Supports stdio and HTTP transports with automatic reconnection, security filtering, and zero-config tool injection.
-version: 1.0.0
-author: Hermes Agent
-license: MIT
-metadata:
-  hermes:
-    tags: [MCP, Tools, Integrations]
-    related_skills: [mcporter]
----
-
-# Native MCP Client
-
-Hermes Agent has a built-in MCP client that connects to MCP servers at startup, discovers their tools, and makes them available as first-class tools the agent can call directly. No bridge CLI needed -- tools from MCP servers appear alongside built-in tools like `terminal`, `read_file`, etc.
-
-## When to Use
-
-Use this whenever you want to:
-- Connect to MCP servers and use their tools from within Hermes Agent
-- Add external capabilities (filesystem access, GitHub, databases, APIs) via MCP
-- Run local stdio-based MCP servers (npx, uvx, or any command)
-- Connect to remote HTTP/StreamableHTTP MCP servers
-- Have MCP tools auto-discovered and available in every conversation
-
-For ad-hoc, one-off MCP tool calls from the terminal without configuring anything, see the `mcporter` skill instead.
-
-## Prerequisites
-
-- **mcp Python package** -- optional dependency; install with `pip install mcp`. If not installed, MCP support is silently disabled.
-- **Node.js** -- required for `npx`-based MCP servers (most community servers)
-- **uv** -- required for `uvx`-based MCP servers (Python-based servers)
-
-Install the MCP SDK:
-
-```bash
-pip install mcp
-# or, if using uv:
-uv pip install mcp
-```
-
-## Quick Start
-
-Add MCP servers to `~/.hermes/config.yaml` under the `mcp_servers` key:
-
-```yaml
-mcp_servers:
-  time:
-    command: "uvx"
-    args: ["mcp-server-time"]
-```
-
-Restart Hermes Agent. On startup it will:
-1. Connect to the server
-2. Discover available tools
-3. Register them with the prefix `mcp_time_*`
-4. Inject them into all platform toolsets
-
-You can then use the tools naturally -- just ask the agent to get the current time.
-
-## Configuration Reference
-
-Each entry under `mcp_servers` is a server name mapped to its config. There are two transport types: **stdio** (command-based) and **HTTP** (url-based).
-
-### Stdio Transport (command + args)
-
-```yaml
-mcp_servers:
-  server_name:
-    command: "npx"             # (required) executable to run
-    args: ["-y", "pkg-name"]   # (optional) command arguments, default: []
-    env:                       # (optional) environment variables for the subprocess
-      SOME_API_KEY: "value"
-    timeout: 120               # (optional) per-tool-call timeout in seconds, default: 120
-    connect_timeout: 60        # (optional) initial connection timeout in seconds, default: 60
-```
-
-### HTTP Transport (url)
-
-```yaml
-mcp_servers:
-  server_name:
-    url: "https://my-server.example.com/mcp"   # (required) server URL
-    headers:                                     # (optional) HTTP headers
-      Authorization: "Bearer sk-..."
-    timeout: 180               # (optional) per-tool-call timeout in seconds, default: 120
-    connect_timeout: 60        # (optional) initial connection timeout in seconds, default: 60
-```
-
-### All Config Options
-
-| Option            | Type   | Default | Description                                       |
-|-------------------|--------|---------|---------------------------------------------------|
-| `command`         | string | --      | Executable to run (stdio transport, required)     |
-| `args`            | list   | `[]`    | Arguments passed to the command                   |
-| `env`             | dict   | `{}`    | Extra environment variables for the subprocess    |
-| `url`             | string | --      | Server URL (HTTP transport, required)             |
-| `headers`         | dict   | `{}`    | HTTP headers sent with every request              |
-| `timeout`         | int    | `120`   | Per-tool-call timeout in seconds                  |
-| `connect_timeout` | int    | `60`    | Timeout for initial connection and discovery      |
-
-Note: A server config must have either `command` (stdio) or `url` (HTTP), not both.
-
-## How It Works
-
-### Startup Discovery
-
-When Hermes Agent starts, `discover_mcp_tools()` is called during tool initialization:
-
-1. Reads `mcp_servers` from `~/.hermes/config.yaml`
-2. For each server, spawns a connection in a dedicated background event loop
-3. Initializes the MCP session and calls `list_tools()` to discover available tools
-4. Registers each tool in the Hermes tool registry
-
-### Tool Naming Convention
-
-MCP tools are registered with the naming pattern:
-
-```
-mcp_{server_name}_{tool_name}
-```
-
-Hyphens and dots in names are replaced with underscores for LLM API compatibility.
-
-Examples:
-- Server `filesystem`, tool `read_file` → `mcp_filesystem_read_file`
-- Server `github`, tool `list-issues` → `mcp_github_list_issues`
-- Server `my-api`, tool `fetch.data` → `mcp_my_api_fetch_data`
-
-### Auto-Injection
-
-After discovery, MCP tools are automatically injected into all `hermes-*` platform toolsets (CLI, Discord, Telegram, etc.). This means MCP tools are available in every conversation without any additional configuration.
-
-### Connection Lifecycle
-
-- Each server runs as a long-lived asyncio Task in a background daemon thread
-- Connections persist for the lifetime of the agent process
-- If a connection drops, automatic reconnection with exponential backoff kicks in (up to 5 retries, max 60s backoff)
-- On agent shutdown, all connections are gracefully closed
-
-### Idempotency
-
-`discover_mcp_tools()` is idempotent -- calling it multiple times only connects to servers that aren't already connected. Failed servers are retried on subsequent calls.
-
-## Transport Types
-
-### Stdio Transport
-
-The most common transport. Hermes launches the MCP server as a subprocess and communicates over stdin/stdout.
-
-```yaml
-mcp_servers:
-  filesystem:
-    command: "npx"
-    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]
-```
-
-The subprocess inherits a **filtered** environment (see Security section below) plus any variables you specify in `env`.
-
-### HTTP / StreamableHTTP Transport
-
-For remote or shared MCP servers. Requires the `mcp` package to include HTTP client support (`mcp.client.streamable_http`).
-
-```yaml
-mcp_servers:
-  remote_api:
-    url: "https://mcp.example.com/mcp"
-    headers:
-      Authorization: "Bearer sk-..."
-```
-
-If HTTP support is not available in your installed `mcp` version, the server will fail with an ImportError and other servers will continue normally.
-
-## Security
-
-### Environment Variable Filtering
-
-For stdio servers, Hermes does NOT pass your full shell environment to MCP subprocesses. Only safe baseline variables are inherited:
-
-- `PATH`, `HOME`, `USER`, `LANG`, `LC_ALL`, `TERM`, `SHELL`, `TMPDIR`
-- Any `XDG_*` variables
-
-All other environment variables (API keys, tokens, secrets) are excluded unless you explicitly add them via the `env` config key. This prevents accidental credential leakage to untrusted MCP servers.
-
-```yaml
-mcp_servers:
-  github:
-    command: "npx"
-    args: ["-y", "@modelcontextprotocol/server-github"]
-    env:
-      # Only this token is passed to the subprocess
-      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_..."
-```
-
-### Credential Stripping in Error Messages
-
-If an MCP tool call fails, any credential-like patterns in the error message are automatically redacted before being shown to the LLM. This covers:
-
-- GitHub PATs (`ghp_...`)
-- OpenAI-style keys (`sk-...`)
-- Bearer tokens
-- Generic `token=`, `key=`, `API_KEY=`, `password=`, `secret=` patterns
-
-## Troubleshooting
-
-### "MCP SDK not available -- skipping MCP tool discovery"
-
-The `mcp` Python package is not installed. Install it:
-
-```bash
-pip install mcp
-```
-
-### "No MCP servers configured"
-
-No `mcp_servers` key in `~/.hermes/config.yaml`, or it's empty. Add at least one server.
-
-### "Failed to connect to MCP server 'X'"
-
-Common causes:
-- **Command not found**: The `command` binary isn't on PATH. Ensure `npx`, `uvx`, or the relevant command is installed.
-- **Package not found**: For npx servers, the npm package may not exist or may need `-y` in args to auto-install.
-- **Timeout**: The server took too long to start. Increase `connect_timeout`.
-- **Port conflict**: For HTTP servers, the URL may be unreachable.
-
-### "MCP server 'X' requires HTTP transport but mcp.client.streamable_http is not available"
-
-Your `mcp` package version doesn't include HTTP client support. Upgrade:
-
-```bash
-pip install --upgrade mcp
-```
-
-### Tools not appearing
-
-- Check that the server is listed under `mcp_servers` (not `mcp` or `servers`)
-- Ensure the YAML indentation is correct
-- Look at Hermes Agent startup logs for connection messages
-- Tool names are prefixed with `mcp_{server}_{tool}` -- look for that pattern
-
-### Connection keeps dropping
-
-The client retries up to 5 times with exponential backoff (1s, 2s, 4s, 8s, 16s, capped at 60s). If the server is fundamentally unreachable, it gives up after 5 attempts. Check the server process and network connectivity.
-
-## Examples
-
-### Time Server (uvx)
-
-```yaml
-mcp_servers:
-  time:
-    command: "uvx"
-    args: ["mcp-server-time"]
-```
-
-Registers tools like `mcp_time_get_current_time`.
-
-### Filesystem Server (npx)
-
-```yaml
-mcp_servers:
-  filesystem:
-    command: "npx"
-    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/documents"]
-    timeout: 30
-```
-
-Registers tools like `mcp_filesystem_read_file`, `mcp_filesystem_write_file`, `mcp_filesystem_list_directory`.
-
-### GitHub Server with Authentication
-
-```yaml
-mcp_servers:
-  github:
-    command: "npx"
-    args: ["-y", "@modelcontextprotocol/server-github"]
-    env:
-      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxxxxxxxxxxxxxxxxxxx"
-    timeout: 60
-```
-
-Registers tools like `mcp_github_list_issues`, `mcp_github_create_pull_request`, etc.
-
-### Remote HTTP Server
-
-```yaml
-mcp_servers:
-  company_api:
-    url: "https://mcp.mycompany.com/v1/mcp"
-    headers:
-      Authorization: "Bearer sk-xxxxxxxxxxxxxxxxxxxx"
-      X-Team-Id: "engineering"
-    timeout: 180
-    connect_timeout: 30
-```
-
-### Multiple Servers
-
-```yaml
-mcp_servers:
-  time:
-    command: "uvx"
-    args: ["mcp-server-time"]
-
-  filesystem:
-    command: "npx"
-    args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
-
-  github:
-    command: "npx"
-    args: ["-y", "@modelcontextprotocol/server-github"]
-    env:
-      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxxxxxxxxxxxxxxxxxxx"
-
-  company_api:
-    url: "https://mcp.internal.company.com/mcp"
-    headers:
-      Authorization: "Bearer sk-xxxxxxxxxxxxxxxxxxxx"
-    timeout: 300
-```
-
-All tools from all servers are registered and available simultaneously. Each server's tools are prefixed with its name to avoid collisions.
-
-## Sampling (Server-Initiated LLM Requests)
-
-Hermes supports MCP's `sampling/createMessage` capability — MCP servers can request LLM completions through the agent during tool execution. This enables agent-in-the-loop workflows (data analysis, content generation, decision-making).
-
-Sampling is **enabled by default**. Configure per server:
-
-```yaml
-mcp_servers:
-  my_server:
-    command: "npx"
-    args: ["-y", "my-mcp-server"]
-    sampling:
-      enabled: true           # default: true
-      model: "gemini-3-flash" # model override (optional)
-      max_tokens_cap: 4096    # max tokens per request
-      timeout: 30             # LLM call timeout (seconds)
-      max_rpm: 10             # max requests per minute
-      allowed_models: []      # model whitelist (empty = all)
-      max_tool_rounds: 5      # tool loop limit (0 = disable)
-      log_level: "info"       # audit verbosity
-```
-
-Servers can also include `tools` in sampling requests for multi-turn tool-augmented workflows. The `max_tool_rounds` config prevents infinite tool loops. Per-server audit metrics (requests, errors, tokens, tool use count) are tracked via `get_mcp_status()`.
-
-Disable sampling for untrusted servers with `sampling: { enabled: false }`.
-
-## Notes
-
-- MCP tools are called synchronously from the agent's perspective but run asynchronously on a dedicated background event loop
-- Tool results are returned as JSON with either `{"result": "..."}` or `{"error": "..."}`
-- The native MCP client is independent of `mcporter` -- you can use both simultaneously
-- Server connections are persistent and shared across all conversations in the same agent process
-- Adding or removing servers requires restarting the agent (no hot-reload currently)