@jenga-ai/agent 1.0.0

package/lib/resolve-project-dir.sh

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+# lib/resolve-project-dir.sh
+# Sourced helper: exports JENGA_PROJECT_DIR, JENGA_AGENT_TYPE, JENGA_SESSION_ID
+# by probing known agent environment variables in priority order.
+# Idempotent — no-op if JENGA_PROJECT_DIR is already set.
+
+if [ -n "${JENGA_PROJECT_DIR:-}" ]; then
+  return 0 2>/dev/null || true
+fi
+
+# --- JENGA_PROJECT_DIR ---
+if [ -n "${CLAUDE_PROJECT_DIR:-}" ]; then
+  JENGA_PROJECT_DIR="$CLAUDE_PROJECT_DIR"
+elif [ -n "${COPILOT_WORKSPACE_FOLDER:-}" ]; then
+  JENGA_PROJECT_DIR="$COPILOT_WORKSPACE_FOLDER"
+else
+  _git_root="$(git rev-parse --show-toplevel 2>/dev/null)"
+  if [ -n "$_git_root" ]; then
+    JENGA_PROJECT_DIR="$_git_root"
+  else
+    JENGA_PROJECT_DIR="$(pwd)"
+  fi
+  unset _git_root
+fi
+export JENGA_PROJECT_DIR
+
+# --- JENGA_AGENT_TYPE ---
+if [ -z "${JENGA_AGENT_TYPE:-}" ]; then
+  if [ -n "${CLAUDE_AGENT_TYPE:-}" ]; then
+    JENGA_AGENT_TYPE="$CLAUDE_AGENT_TYPE"
+  else
+    JENGA_AGENT_TYPE="generic"
+  fi
+  export JENGA_AGENT_TYPE
+fi
+
+# --- JENGA_SESSION_ID ---
+if [ -z "${JENGA_SESSION_ID:-}" ]; then
+  if [ -n "${CLAUDE_SESSION_ID:-}" ]; then
+    JENGA_SESSION_ID="$CLAUDE_SESSION_ID"
+  elif command -v uuidgen >/dev/null 2>&1; then
+    JENGA_SESSION_ID="$(uuidgen)"
+  else
+    JENGA_SESSION_ID="session-$(date +%s)-$$"
+  fi
+  export JENGA_SESSION_ID
+fi

package/mcp/execute-ticket/index.js

@@ -0,0 +1,10 @@
+
+/*** TODO
+* Params: <Task identifier>
+*
+* Purpose:
+* Carry out a specific task as specified by the task found in the "project/" directory
+* - Create a subagent 
+* - Create git worktree based on task number and name
+* - Name the session same as the worktree
+***/

package/mcp/execute-ticket/package.json

@@ -0,0 +1,5 @@
+/** TODO
+* 
+* Describe the related MCP service
+*
+**/

package/mcp/help/index.js

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { existsSync, readdirSync, statSync } from "fs";
+import { join, resolve } from "path";
+
+const server = new McpServer({
+  name: "help",
+  version: "1.0.0",
+});
+
+server.tool(
+  "help",
+  "List all available agent skills by scanning the .claude/skills or .agents/skills directory in the given path.",
+  {
+    path: z
+      .string()
+      .optional()
+      .describe(
+        "Absolute or relative path to the project root to scan. Defaults to the current working directory."
+      ),
+  },
+  async ({ path: inputPath }) => {
+    const root = inputPath ? resolve(inputPath) : process.cwd();
+    // The jenga-agent postinstall mirrors skills/ into both .claude/ (Claude Code)
+    // and .agents/ (Copilot / custom agents). Prefer .claude/; fall back to .agents/.
+    const candidates = [
+      join(root, ".claude", "skills"),
+      join(root, ".agents", "skills"),
+    ];
+    const skillsDir = candidates.find(existsSync);
+
+    if (!skillsDir) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `No skills found. Looked in:\n${candidates.map(p => `  - ${p}`).join("\n")}`,
+          },
+        ],
+      };
+    }
+
+    const entries = readdirSync(skillsDir);
+    const folders = entries.filter((entry) => {
+      try {
+        return statSync(join(skillsDir, entry)).isDirectory();
+      } catch {
+        return false;
+      }
+    });
+
+    if (folders.length === 0) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `The skills directory exists at \`${skillsDir}\` but contains no skill folders.`,
+          },
+        ],
+      };
+    }
+
+    const list = folders.map((name) => `- ${name}`).join("\n");
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Available skills in \`${skillsDir}\`:\n\n${list}`,
+        },
+      ],
+    };
+  }
+);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/mcp/help/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "help-mcp-server",
+  "version": "1.0.0",
+  "description": "MCP server that lists available agent skills from .agents/skills",
+  "type": "module",
+  "main": "index.js",
+  "scripts": {
+    "start": "node index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.10.1",
+    "zod": "^3.23.8"
+  }
+}

package/mcp/router/README.md

@@ -0,0 +1,19 @@
+# jenga-router
+
+A stdio MCP server that routes incoming prompts to the appropriate Jenga skill.
+
+## Usage
+
+```bash
+node mcp/router/index.js
+```
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `ping` | Health check — returns `{ ok: true, uptime: <ms> }` |
+
+## Protocol
+
+Communicates over stdin/stdout using the Model Context Protocol (MCP) with `StdioServerTransport`.

package/mcp/router/embedder.js

@@ -0,0 +1,23 @@
+import { pipeline } from "@xenova/transformers";
+
+let _pipe = null;
+
+/**
+ * Loads the feature-extraction pipeline for Xenova/all-MiniLM-L6-v2.
+ * Safe to call multiple times — no-op if already loaded.
+ */
+export async function warmUp() {
+  if (_pipe) return;
+  const t = Date.now();
+  _pipe = await pipeline("feature-extraction", "Xenova/all-MiniLM-L6-v2");
+  process.stderr.write(`[jenga-router] Model warmed up in ${Date.now() - t}ms\n`);
+}
+
+/**
+ * Embeds text using the loaded pipeline.
+ * Returns a Float32Array of length 384.
+ */
+export async function embed(text) {
+  const output = await _pipe(text, { pooling: "mean", normalize: true });
+  return output.data;
+}

package/mcp/router/index.js

@@ -0,0 +1,204 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { writeFileSync, unlinkSync, existsSync, readFileSync, mkdirSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import { buildSkillIndex } from "./skill-index.js";
+import { findBestMatch } from "./matcher.js";
+import { warmUp, embed } from "./embedder.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const projectRoot = join(__dirname, "..", "..");
+const jengaDir = join(process.cwd(), ".jenga");
+const pidFile = join(jengaDir, "router.pid");
+const sessionFile = join(jengaDir, "session.json");
+const startTime = Date.now();
+
+// Load config (optional — defaults used if absent)
+let config = {
+  skillsPath: "skills/",
+  matchThreshold: 0.75,
+  sessionTimeout: 300000,
+  agentTarget: "claude",
+};
+const configPath = join(projectRoot, "jenga.cli.json");
+if (existsSync(configPath)) {
+  try {
+    config = { ...config, ...JSON.parse(readFileSync(configPath, "utf8")) };
+  } catch (e) {
+    process.stderr.write(`Warning: failed to parse jenga.cli.json: ${e.message}\n`);
+  }
+}
+
+// Build skill index (with semantic embeddings)
+let skillIndex = [];
+if (config.skillsPath) {
+  await warmUp();
+  skillIndex = await buildSkillIndex(join(projectRoot, config.skillsPath), { embed });
+}
+
+// Write PID file
+mkdirSync(jengaDir, { recursive: true });
+writeFileSync(pidFile, String(process.pid), "utf8");
+
+// Graceful shutdown
+function shutdown() {
+  try { unlinkSync(pidFile); } catch {}
+  persistSession({ skill: null, startedAt: null });
+  process.exit(0);
+}
+process.on("SIGTERM", shutdown);
+process.on("SIGINT", shutdown);
+
+let activeSession = { skill: null, startedAt: null };
+let sessionTimer = null;
+
+function persistSession(state) {
+  try {
+    writeFileSync(sessionFile, JSON.stringify(state), "utf8");
+  } catch (e) {
+    process.stderr.write(`[jenga-router] Failed to write .session.json: ${e.message}\n`);
+  }
+}
+
+const server = new McpServer({ name: "jenga-router", version: "1.0.0" });
+
+server.tool("ping", "Health check — returns ok and uptime in seconds.", {}, async () => {
+  try {
+    return {
+      content: [{ type: "text", text: JSON.stringify({ ok: true, uptime: Math.floor((Date.now() - startTime) / 1000), skill_count: skillIndex.length }) }],
+    };
+  } catch (e) {
+    return { content: [{ type: "text", text: JSON.stringify({ error: e.message }) }], isError: true };
+  }
+});
+
+server.tool(
+  "route_prompt",
+  "Route a prompt through the skill matching pipeline. Returns { action: 'invoke'|'passthrough', transformed: string, skill: string|null, confidence: number }.",
+  { text: z.string().describe("The user prompt to route") },
+  async ({ text }) => {
+    try {
+      // Stage 1: Passthrough rules
+      if (text.startsWith("/")) {
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({ action: "passthrough", transformed: text, skill: null, confidence: 0 }),
+          }],
+        };
+      }
+
+      // Stage 0: Active session — passthrough all prompts while session is active
+      if (activeSession.skill) {
+        if (sessionTimer) clearTimeout(sessionTimer);
+        sessionTimer = setTimeout(() => {
+          activeSession = { skill: null, startedAt: null };
+          sessionTimer = null;
+          persistSession(activeSession);
+          process.stderr.write(`[jenga-router] Session auto-expired after ${config.sessionTimeout}ms\n`);
+        }, config.sessionTimeout);
+        return {
+          content: [{ type: "text", text: JSON.stringify({ action: "passthrough", transformed: text, skill: activeSession.skill, confidence: 0 }) }],
+        };
+      }
+
+      // Stage 2: Semantic + keyword matching
+      const promptEmbedding = await embed(text);
+      const match = findBestMatch(text, skillIndex, config.matchThreshold, promptEmbedding);
+      if (match) {
+        activeSession = { skill: match.skill.name, startedAt: new Date().toISOString() };
+        persistSession(activeSession);
+        if (sessionTimer) clearTimeout(sessionTimer);
+        sessionTimer = setTimeout(() => {
+          activeSession = { skill: null, startedAt: null };
+          persistSession(activeSession);
+          sessionTimer = null;
+          process.stderr.write(`[jenga-router] Session auto-expired after ${config.sessionTimeout}ms\n`);
+        }, config.sessionTimeout);
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({
+              action: "invoke",
+              transformed: `/${match.skill.name} ${text}`,
+              skill: match.skill.name,
+              confidence: match.confidence,
+            }),
+          }],
+        };
+      }
+
+      // Default: passthrough
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({ action: "passthrough", transformed: text, skill: null, confidence: 0 }),
+        }],
+      };
+    } catch (e) {
+      return { content: [{ type: "text", text: JSON.stringify({ error: e.message }) }], isError: true };
+    }
+  }
+);
+
+server.tool("active_session", "Returns the currently active skill session, if any.", {}, async () => {
+  try {
+    return {
+      content: [{ type: "text", text: JSON.stringify({ skill: activeSession.skill, startedAt: activeSession.startedAt }) }],
+    };
+  } catch (e) {
+    return { content: [{ type: "text", text: JSON.stringify({ error: e.message }) }], isError: true };
+  }
+});
+
+server.tool(
+  "end_session",
+  "Clear the active session for the given skill. No-op if skill is not the active session.",
+  { skill: z.string().describe("The skill name to end the session for") },
+  async ({ skill }) => {
+    try {
+      if (activeSession.skill === skill) {
+        activeSession = { skill: null, startedAt: null };
+        persistSession(activeSession);
+        if (sessionTimer) { clearTimeout(sessionTimer); sessionTimer = null; }
+      }
+      return { content: [{ type: "text", text: JSON.stringify({ ok: true }) }] };
+    } catch (e) {
+      return { content: [{ type: "text", text: JSON.stringify({ error: e.message }) }], isError: true };
+    }
+  }
+);
+
+server.tool(
+  "list_skills",
+  "Returns the current skill index — all loaded skills with their name, description, and keywords.",
+  {},
+  async () => {
+    try {
+      const skills = skillIndex.map(({ name, description, keywords }) => ({ name, description, keywords }));
+      return {
+        content: [{ type: "text", text: JSON.stringify({ skills }) }],
+      };
+    } catch (e) {
+      return { content: [{ type: "text", text: JSON.stringify({ error: e.message }) }], isError: true };
+    }
+  }
+);
+
+server.tool("reload_skills", "Re-scan the skills directory and rebuild the in-memory skill index.", {}, async () => {
+  try {
+    await warmUp();
+    skillIndex = await buildSkillIndex(join(projectRoot, config.skillsPath), { embed });
+    return {
+      content: [{ type: "text", text: JSON.stringify({ ok: true, skill_count: skillIndex.length }) }],
+    };
+  } catch (e) {
+    return { content: [{ type: "text", text: JSON.stringify({ error: e.message }) }], isError: true };
+  }
+});
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/mcp/router/matcher.js

@@ -0,0 +1,87 @@
+/**
+ * Scores a prompt against a skill using keyword and name matching.
+ * Returns a confidence score between 0 and 1.
+ */
+function scoreSkill(prompt, skill) {
+  const text = prompt.toLowerCase();
+  let score = 0;
+  let matches = 0;
+  let total = 0;
+
+  // Check skill name
+  total++;
+  if (text.includes(skill.name.toLowerCase())) {
+    score += 0.9;
+    matches++;
+  }
+
+  // Check keywords
+  for (const kw of skill.keywords) {
+    total++;
+    if (text.includes(kw.toLowerCase())) {
+      score += 0.7;
+      matches++;
+    }
+  }
+
+  // Check examples (partial match)
+  for (const ex of skill.examples) {
+    const exWords = ex.toLowerCase().split(/\s+/).filter(w => w.length > 3);
+    const matchedWords = exWords.filter(w => text.includes(w));
+    if (matchedWords.length > 0 && exWords.length > 0) {
+      total++;
+      score += 0.5 * (matchedWords.length / exWords.length);
+      matches++;
+    }
+  }
+
+  if (total === 0) return 0;
+  // Normalize: max possible score per item varies, cap at 1.0
+  return Math.min(score / Math.max(total, 1), 1.0);
+}
+
+/**
+ * Computes cosine similarity between two Float32Array vectors.
+ * Result is clamped to [0, 1].
+ */
+function cosineSimilarity(a, b) {
+  let dot = 0, normA = 0, normB = 0;
+  for (let i = 0; i < a.length; i++) {
+    dot += a[i] * b[i];
+    normA += a[i] * a[i];
+    normB += b[i] * b[i];
+  }
+  const denom = Math.sqrt(normA) * Math.sqrt(normB);
+  if (denom === 0) return 0;
+  return Math.max(0, Math.min(1, dot / denom));
+}
+
+/**
+ * Finds the best matching skill for a prompt.
+ * Blends keyword score with semantic cosine similarity when embeddings are available.
+ * Returns { skill, confidence } or null if no match above threshold.
+ */
+export function findBestMatch(prompt, skillIndex, threshold = 0.75, promptEmbedding = null) {
+  let best = null;
+  let bestScore = 0;
+
+  for (const skill of skillIndex) {
+    const keywordScore = scoreSkill(prompt, skill);
+    let finalScore = keywordScore;
+
+    if (promptEmbedding !== null && skill.embedding !== null) {
+      const semanticScore = cosineSimilarity(promptEmbedding, skill.embedding);
+      finalScore = 0.4 * keywordScore + 0.6 * semanticScore;
+    }
+
+    if (finalScore > bestScore) {
+      bestScore = finalScore;
+      best = skill;
+    }
+  }
+
+  if (best && bestScore >= threshold) {
+    return { skill: best, confidence: bestScore };
+  }
+  return null;
+}