mcp-castor 2026.3.0

package/index.js

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+/**
+ * Castor - Unified Local Model Agent Harness & MCP Server (version: package.json)
+ *
+ * Architecture:
+ * - Lead Architect: Claude 5 Sonnet in Claude Code / Gemini 3.8 Flash in Antigravity
+ * - Autonomous Execution Coworker: Qwen3.8-27B via Castor Microkernel Harness ($0 text-only execution)
+ * - Serving: Universal 245K context (vLLM + DFlash2 + KVarN @ localhost:18020)
+ * - Zero-Turn Async Architecture: Blocking Long-Poll HTTP Coordinator (localhost:18021)
+ * - 3 Consolidated SOTA Tools: qwen_coworker, qwen_task, qwen_server
+ * - Modularized Clean Architecture (src/)
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createRequire } from "node:module";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { MAX_CONCURRENT_TASKS, TASK_DIR } from "./src/config.js";
+import { killProcessTree, killProcessTreeSync } from "./src/wsl_bridge.js";
+import {
+  acquireTaskSlot,
+  releaseTaskSlot,
+  listTaskSlots,
+  getSlotStatus,
+  slotFilePath,
+  readLease,
+} from "./src/semaphore.js";
+import {
+  tasks,
+  saveTaskToDisk,
+  notifyWaiters,
+  isTaskOrphaned,
+  markTaskOrphanedOnDisk,
+  initStatusServer,
+  setMcpServerFactory,
+  activeSseSessions,
+} from "./src/task_registry.js";
+import { registerTools } from "./src/tools.js";
+import { shutdownSearxng } from "./src/harness/services/searxng_lifecycle.js";
+import { disposeAllBridges } from "./src/harness/services/mcp_bridge.js";
+import { cleanStateDir } from "./src/state_pruner.js";
+
+const require = createRequire(import.meta.url);
+const { name: pkgName, version: pkgVersion } = require("./package.json");
+const __filename = fileURLToPath(import.meta.url);
+
+function setupProcessLifecycleHandlers() {
+  const cleanup = (signal) => {
+    try {
+      // P8: reap any live MCP extension bridge children (native engine)
+      // so none survive process shutdown.
+      disposeAllBridges();
+      for (const session of activeSseSessions.values()) {
+        try {
+          session.transport.close();
+          session.server.close();
+        } catch {}
+      }
+      activeSseSessions.clear();
+      for (const [id, task] of tasks.entries()) {
+        if (!task.done) {
+          task.done = true;
+          task.status = "cancelled";
+          task.isError = true;
+          task.finishedAt = Date.now();
+          task.result = {
+            isError: true,
+            text: `Task cancelled: MCP server process terminating (${signal || "shutdown"}).`,
+            toolCalls: task.toolCallsCount || 0,
+            errors: ["SERVER_PROCESS_TERMINATED"],
+            fileOps: task.fileOps || [],
+          };
+          saveTaskToDisk(task);
+          notifyWaiters(task);
+          if (task.child) {
+            killProcessTreeSync(task.child, task.sessionId);
+          }
+        }
+      }
+      for (let i = 0; i < MAX_CONCURRENT_TASKS; i++) {
+        const file = slotFilePath(i);
+        const lease = readLease(file);
+        if (lease && lease.pid === process.pid) {
+          try {
+            fs.rmSync(file, { force: true });
+          } catch {}
+        }
+      }
+      try {
+        shutdownSearxng().catch(() => {});
+      } catch {}
+    } catch {}
+  };
+
+  process.once("SIGINT", () => {
+    cleanup("SIGINT");
+    process.exit(0);
+  });
+  process.once("SIGTERM", () => {
+    cleanup("SIGTERM");
+    process.exit(0);
+  });
+  process.stdin.on("close", () => {
+    cleanup("stdin_closed");
+    process.exit(0);
+  });
+  process.stdin.on("end", () => {
+    cleanup("stdin_end");
+    process.exit(0);
+  });
+  process.stdout.on("error", (err) => {
+    if (err && (err.code === "EPIPE" || err.code === "ERR_STREAM_DESTROYED")) {
+      cleanup("stdout_epipe");
+      process.exit(0);
+    }
+  });
+  process.stderr.on("error", (err) => {
+    if (err && (err.code === "EPIPE" || err.code === "ERR_STREAM_DESTROYED")) {
+      process.exit(0);
+    }
+  });
+  process.on("beforeExit", () => {
+    cleanup("beforeExit");
+  });
+}
+
+function createMcpServer() {
+  const server = new McpServer({
+    name: pkgName ?? "qwen38-local",
+    version: pkgVersion,
+  });
+  registerTools(server);
+  return server;
+}
+
+setMcpServerFactory(createMcpServer);
+
+/**
+ * Starts the Castor MCP server on the stdio transport.
+ *
+ * Exported so that `bin/castor.js` (the packaged CLI entrypoint) can import
+ * and invoke it, while direct execution of `index.js` still works as before.
+ *
+ * Stdio purity contract: this function must never write to stdout except
+ * through the MCP transport (JSON-RPC frames). All diagnostics go to stderr.
+ */
+export async function startMcpServer() {
+  setupProcessLifecycleHandlers();
+  initStatusServer();
+
+  // Opportunistic state-dir hygiene: prune old sessions / orphan .tmp_* files.
+  // Throttled to at most once per 24h via the .last_prune timestamp, and
+  // best-effort — a failure here must never prevent the MCP server from
+  // starting. Stdio purity: diagnostics go to stderr only.
+  try {
+    const pruneResult = cleanStateDir({ throttled: true });
+    if (!pruneResult.skipped) {
+      const reclaimedMb =
+        (pruneResult.bytesReclaimed + pruneResult.tmpBytesReclaimed) /
+        (1024 * 1024);
+      process.stderr.write(
+        `[state-pruner] pruned ${pruneResult.sessionsPruned} session(s), ` +
+          `${pruneResult.tmpFilesCleaned} orphan .tmp_* file(s) ` +
+          `(${reclaimedMb.toFixed(2)} MB); ` +
+          `${pruneResult.protected} protected\n`
+      );
+    }
+  } catch (err) {
+    process.stderr.write(
+      `[state-pruner] startup cleanup failed (non-fatal): ${
+        err && err.message ? err.message : err
+      }\n`
+    );
+  }
+
+  const server = createMcpServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+export {
+  acquireTaskSlot,
+  releaseTaskSlot,
+  listTaskSlots,
+  getSlotStatus,
+  TASK_DIR,
+  isTaskOrphaned,
+  markTaskOrphanedOnDisk,
+};
+
+// Direct-run guard: only auto-start when this file is the actual entrypoint
+// (e.g. `node index.js`), not when imported by bin/castor.js or tests.
+const isMain = Boolean(
+  process.argv[1] &&
+    (path.resolve(process.argv[1]).toLowerCase() === __filename.toLowerCase() ||
+      process.argv[1].toLowerCase().endsWith("index.js"))
+);
+
+if (isMain) {
+  startMcpServer().catch((err) => {
+    console.error("MCP Server Fatal Error:", err);
+    process.exit(1);
+  });
+}

package/package.json

@@ -0,0 +1,97 @@
+{
+  "name": "mcp-castor",
+  "version": "2026.3.0",
+  "description": "Universal 245K local Castor agent microkernel & MCP server: collaborative Socratic pair-programming, native multi-provider research (Brave, Tavily, Context7 docs, SearXNG, DuckDuckGo), cooperative landing turn ceiling preservation, in-process structural AST surgery (@ast-grep/napi), in-memory syntax gates (JS/TS, Python, JSON, LaTeX, BibTeX), 137-vector zero-trust sandbox, closed-loop evolutionary optimization (.evo/lineage.json), vLLM + DFlash2 + KVarN @ 245K context, and zero-turn reactive OS wait @18021.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ApatheticMioz/Anser.git",
+    "directory": "mcp-castor"
+  },
+  "main": "index.js",
+  "bin": {
+    "castor": "bin/castor.js"
+  },
+  "files": [
+    "bin/",
+    "index.js",
+    "stream_proxy.js",
+    "src/",
+    "skills/",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node tests/canary.test.js && node tests/security.test.js && node tests/syntax_gates.test.js && node tests/edit_file_guard.test.js && node tests/search_code_guard.test.js && node tests/schema_parity.test.js && node tests/platform.test.js && node --test tests/protocol_sync.test.js && node --test tests/prompt_integrity.test.js",
+    "test:fast": "npm test",
+    "test:all": "node tests/security.test.js && node tests/canary.test.js && node tests/tool_output_spill.test.js && node tests/ast_engine.test.js && node tests/ast_batch.test.js && node tests/edit_file_guard.test.js && node tests/apply_patch.test.js && node tests/evo.test.js && node tests/evo_skills.test.js && node tests/semaphore.test.js && node tests/tenant_concurrency.test.js && node tests/stream_proxy.test.js && node tests/utf8_proxy.test.js && node tests/runner_continuation.test.js && node tests/degenerate_final.test.js && node tests/probe_budget.test.js && node tests/session_rollover.test.js && node tests/context_high_watermark.test.js && node tests/kv_prefix_stability.test.js && node tests/prompt_budget.test.js && node tests/wedge_guard.test.js && node tests/platform.test.js && node tests/posix_routing.test.js && node tests/honesty_drift.test.js && node tests/path_canonicalization.test.js && node tests/syntax_gates.test.js && node tests/syntax_integrity.test.js && node tests/provider_reasoning.test.js && node tests/idle_timeout_tier.test.js && node tests/deep_retry_budget.test.js && node tests/provider_usage.test.js && node tests/reasoning_effort_dispatch.test.js && node tests/lineage_integrity.test.js && node tests/mcp_bridge.test.js && node tests/skills.test.js && node tests/reaping.test.js && node tests/status_lifecycle.test.js && node tests/wait_endpoint.test.js && node tests/task_retention.test.js && node tests/orphan_terminal_event.test.js && node tests/orphan_reaper.test.js && node tests/shell_hardening.test.js && node tests/mcp_client.test.js && node tests/runner_mapping.test.js && node tests/fifo_queue.test.js && node tests/lifecycle_locks.test.js && node tests/signal_hardening.test.js && node tests/benchmark.test.js && node tests/stdio_purity.test.js && node tests/tool_errors.test.js && node tests/schema_parity.test.js && node tests/binary_guard.test.js && node tests/search_code_guard.test.js && node tests/sse_transport.test.js && node tests/edit_file_syntax_gate.test.js && node tests/web_service.test.js && node tests/searxng_lifecycle.test.js && node tests/telemetry.test.js && node tests/cooperative_landing.test.js && node tests/multi_provider_search.test.js && node tests/loop_detector.test.js && node tests/lease_extension.test.js && node tests/salvage_pass.test.js && node tests/read_governor.test.js && node tests/session_end_reap.test.js && node --test tests/protocol_sync.test.js && node --test tests/prompt_integrity.test.js",
+    "test:security": "node tests/security.test.js",
+    "test:canary": "node tests/canary.test.js",
+    "test:evo": "node tests/evo.test.js",
+    "test:evo_skills": "node tests/evo_skills.test.js",
+    "test:semaphore": "node tests/semaphore.test.js",
+    "test:tenant": "node tests/tenant_concurrency.test.js",
+    "test:continuation": "node tests/runner_continuation.test.js",
+    "test:wedge": "node tests/wedge_guard.test.js",
+    "test:reasoning": "node tests/provider_reasoning.test.js",
+    "test:usage": "node tests/provider_usage.test.js",
+    "test:canonical": "node tests/path_canonicalization.test.js",
+    "test:syntax": "node tests/syntax_gates.test.js",
+    "test:syntax_integrity": "node tests/syntax_integrity.test.js",
+    "test:stdio": "node tests/stdio_purity.test.js",
+    "test:batch": "node tests/ast_batch.test.js",
+    "test:proxy": "node tests/stream_proxy.test.js && node tests/utf8_proxy.test.js",
+    "test:bridge": "node tests/mcp_bridge.test.js",
+    "test:skills": "node tests/skills.test.js",
+    "test:reaping": "node tests/reaping.test.js",
+    "test:retention": "node tests/task_retention.test.js",
+    "test:benchmark": "node tests/benchmark.test.js",
+    "test:tool_errors": "node tests/tool_errors.test.js",
+    "test:schema_parity": "node tests/schema_parity.test.js",
+    "test:sse": "node tests/sse_transport.test.js",
+    "test:kv_stability": "node tests/kv_prefix_stability.test.js",
+    "test:edit_syntax": "node tests/edit_file_syntax_gate.test.js",
+    "test:web": "node tests/web_service.test.js",
+    "test:telemetry": "node tests/telemetry.test.js",
+    "test:cooperative": "node tests/cooperative_landing.test.js",
+    "test:search": "node tests/multi_provider_search.test.js",
+    "test:prompt_integrity": "node --test tests/prompt_integrity.test.js"
+  },
+  "keywords": [
+    "mcp",
+    "qwen3.8-27b",
+    "vllm",
+    "castor",
+    "evo",
+    "agent-harness",
+    "ast-grep",
+    "sandboxing",
+    "dflash2",
+    "kvarn"
+  ],
+  "author": "ApatheticMioz",
+  "license": "AGPL-3.0-or-later",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@ast-grep/napi": "^0.45.3",
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "@mozilla/readability": "^0.6.0",
+    "duck-duck-scrape": "^2.2.7",
+    "file-type": "^22.1.0",
+    "jsdom": "^29.1.1",
+    "pdf-parse": "^2.4.5",
+    "turndown": "^7.2.4",
+    "typescript": "5.9.3",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@ast-grep/cli": "^0.45.3"
+  },
+  "optionalDependencies": {
+    "@ast-grep/cli-linux-x64-gnu": "^0.45.3",
+    "@ast-grep/cli-win32-x64-msvc": "^0.45.3",
+    "@ast-grep/napi-linux-x64-gnu": "^0.45.3",
+    "@ast-grep/napi-win32-x64-msvc": "^0.45.3"
+  }
+}

package/skills/canary-test-staging/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: canary-test-staging
+description: Stage changes behind a targeted test file and run the narrow suite before the full chain.
+keywords: [canary, smoke test, staging suite, test gate, narrow test, targeted test]
+---
+# Canary Test Staging
+
+Before you trust a change, prove it on the smallest possible surface, then
+widen. Do not run the full test chain as your first signal.
+
+## Checklist
+1. Write or identify ONE targeted test file that exercises exactly the code
+   you changed (a canary).
+2. Run just that file first: `node tests/<canary>.test.js`.
+3. If it passes, run the next-narrower group (the module's related tests).
+4. Only after those are green, run the full chain (`npm test`).
+5. If a canary fails, fix the code — do not weaken the canary to make it pass.
+
+## Rules
+- A canary must be fast (seconds) and deterministic (no network, no flaky
+  timing).
+- Never delete or skip a failing canary to "unblock" the build; that hides
+  the regression.
+- If you add a new capability, add its canary in the same change.

package/skills/evo-mutation-rollback/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: evo-mutation-rollback
+description: Safe propose, evaluate, select, revert sequence for Evo mutations with no irreversible steps.
+keywords: [rollback, revert, mutation, regression, snapshot, candidate]
+---
+# Evo Mutation Rollback
+
+A mutation is only safe if it can always be undone. Never let a budget,
+timeout, or failure land on a step you cannot roll back.
+
+## Sequence
+1. `evo_propose_candidate` — snapshot the target files FIRST. This is the
+   rollback anchor; nothing is mutated until this succeeds.
+2. Apply the mutation to the working files.
+3. `evo_evaluate_candidate` — run the verification command and read the
+   fitness score plus the compact failure digest.
+4. Decision:
+   - Fitness improved and tests pass -> `evo_select_candidate` (commit to
+     the lineage DAG).
+   - Fitness regressed, tests failed, or the digest shows a real bug ->
+     `evo_revert_candidate` (restore the snapshot exactly).
+5. Confirm the revert restored the original file contents before continuing.
+
+## Rules
+- The snapshot (step 1) must always precede any file mutation.
+- If a step is interrupted by a timeout or budget, the next action is to
+  revert to the last good snapshot, not to resume mid-mutation.
+- Never edit a file that is not in the candidate's snapshot list; those
+  changes are not covered by the rollback.

package/skills/hypothesis-generation/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: hypothesis-generation
+description: Evo discipline — state a measurable hypothesis, snapshot, evaluate, then select or revert.
+keywords: [hypothesis, evo, fitness, benchmark, optimization, candidate, lineage]
+---
+# Hypothesis Generation (Evo Discipline)
+
+Every code change you make to improve a metric is a *candidate*. Treat it as
+a falsifiable hypothesis, not a guess.
+
+## Checklist
+1. State the hypothesis in one measurable sentence:
+   "Changing X will raise <metric> from A to B because <mechanism>."
+2. Snapshot the files you are about to mutate with `evo_propose_candidate`
+   BEFORE editing (pass the exact file list).
+3. Make the minimal change that tests the mechanism — one variable at a time.
+4. Run the verification with `evo_evaluate_candidate` (the test command).
+5. Read the fitness score and the compact failure digest.
+6. If it improved: `evo_select_candidate`. If it regressed or failed:
+   `evo_revert_candidate` to restore the snapshot.
+
+## Rules
+- Never batch unrelated changes into one candidate — you cannot attribute
+  the fitness delta.
+- A candidate that cannot be measured is not a hypothesis; do not propose it.
+- Keep the hypothesis text short and specific; it is stored in the lineage.

package/skills/traceback-condensing/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: traceback-condensing
+description: Condense a failing test run into a minimal failure digest before retrying.
+keywords: [traceback, stack trace, error digest, trace_repair, assertion failure, pytest, failed test]
+---
+# Traceback Condensing
+
+When a test run or build fails, do NOT paste the raw multi-hundred-line
+traceback into your reasoning. Condense it into a compact failure digest
+first, then act on the digest.
+
+## Checklist
+1. Identify the FIRST user-code frame (skip site-packages, stdlib, and
+   framework internals). That is where the real bug lives.
+2. Extract the exact file, line, and symbol from that frame.
+3. Capture the assertion message or exception type + message verbatim.
+4. Reduce the digest to at most ~100 tokens:
+   `[FailureDigest] <type> at <file>:<line> in <symbol>: <message>`
+5. Use the digest (not the raw traceback) to form your next hypothesis.
+
+## Rules
+- Never re-emit the full traceback into a tool call or the final answer.
+- If the digest points at a test file (not source), the bug is likely in the
+  code under test — go read that source file next.
+- If the digest is a network/timeout error, that is an environment issue, not
+  a code bug — say so and do not "fix" unrelated code.