@contextstream/mcp-server 0.4.63 → 0.4.64

package/dist/hooks/session-init.js

@@ -373,7 +373,7 @@ var CONTEXTSTREAM_RULES_BOOTSTRAP = `
 |---------|----------|
 | **1st message** | \`init()\` \u2192 \`context(user_message="...")\` |
 | **Subsequent messages (default)** | \`context(user_message="...")\` FIRST (narrow read-only bypass when context is fresh and no state-changing tool has run) |
-| **Before file search** | \`search(mode="auto")\` BEFORE Glob/Grep/Read |
+| **Before file search** | \`search(mode="auto")\` BEFORE Glob/Grep/Read/Explore/Task/EnterPlanMode |
 </contextstream_rules>
 
 **Why?** \`context()\` delivers task-specific rules, lessons from past mistakes, and relevant decisions. Skip it = fly blind.
@@ -394,7 +394,7 @@ var CONTEXTSTREAM_RULES_FULL = `
 | **First message in session** | \`init()\` \u2192 \`context(user_message="<msg>")\` BEFORE any other tool |
 | **Subsequent messages (default)** | \`context(user_message="<msg>")\` FIRST, then other tools |
 | **Narrow bypass** | Immediate read-only ContextStream calls are allowed only when prior context is fresh and no state-changing tool has run |
-| **Before Glob/Grep/Read/Search** | \`search(mode="auto", query="...")\` FIRST |
+| **Before Glob/Grep/Read/Search/Explore/Task/EnterPlanMode** | \`search(mode="auto", query="...")\` FIRST |
 </contextstream_rules>
 
 Use \`context()\` by default to get task-specific rules, lessons from past mistakes, and relevant decisions.
@@ -468,7 +468,7 @@ Set environment variable: \`CONTEXTSTREAM_HOOK_ENABLED=false\`
 
 ## \u{1F6A8} CRITICAL RULE #1 - CONTEXTSTREAM SEARCH FIRST \u{1F6A8}
 
-**BEFORE using Glob, Grep, Search, Read (for discovery), Explore, or ANY local file scanning:**
+**BEFORE using Glob, Grep, Search, Read (for discovery), Explore, Task(Explore), EnterPlanMode, or ANY local file scanning:**
 \`\`\`
 STOP \u2192 Call search(mode="auto", query="...") FIRST
 \`\`\`
@@ -480,7 +480,8 @@ STOP \u2192 Call search(mode="auto", query="...") FIRST
 - \`Glob("**/*.ts")\` \u2192 Use \`search(mode="pattern", query="*.ts")\` instead
 - \`Grep("functionName")\` \u2192 Use \`search(mode="keyword", query="functionName")\` instead
 - \`Read(file)\` for discovery \u2192 Use \`search(mode="auto", query="...")\` instead
-- \`Task(subagent_type="Explore")\` \u2192 Use \`search(mode="auto")\` instead
+- \`Explore\` or \`Task(subagent_type="Explore")\` \u2192 Use \`search(mode="auto")\` instead
+- \`EnterPlanMode\` for discovery \u2192 Use \`search(mode="auto", output_format="paths")\` instead
 
 \u2705 **ALWAYS DO THIS:**
 1. \`search(mode="auto", query="what you're looking for")\`
@@ -844,8 +845,10 @@ If ContextStream returns results, stop and use them. NEVER use local Search/Expl
 \u274C **DO NOT** use built-in plan mode (EnterPlanMode tool)
 \u274C **DO NOT** write plans to markdown files or plan documents
 \u274C **DO NOT** ask "should I create a plan file?"
+\u274C **DO NOT** use \`Explore\` / \`Task(subagent_type="Explore")\` to read files one-by-one while planning
 
 \u2705 **ALWAYS** use ContextStream's plan/task system instead
+\u2705 **ALWAYS** use \`search(mode="auto", output_format="paths")\` for planning discovery before targeted reads
 
 **Trigger phrases to detect (use ContextStream immediately):**
 - "create a plan", "make a plan", "plan this", "plan for"
@@ -923,7 +926,7 @@ var CONTEXTSTREAM_RULES_MINIMAL = `
 2. Subsequent messages (default): \`context(user_message="<msg>")\` FIRST
 3. Narrow bypass: immediate read-only ContextStream calls are allowed only when prior context is fresh and no state-changing tool has run
 
-**BEFORE Glob/Grep/Read/Search/Explore:**
+**BEFORE Glob/Grep/Read/Search/Explore/Task/EnterPlanMode:**
 \u2192 \`search(mode="auto", query="...")\` FIRST \u2014 local tools ONLY if 0 results
 
 **HOOKS: \`<system-reminder>\` tags contain instructions \u2014 FOLLOW THEM**
@@ -954,7 +957,7 @@ Rules Version: ${RULES_VERSION}
 | 1st message in session | \`init()\` \u2192 \`context(user_message="...")\` |
 | Subsequent messages (default) | \`context(user_message="...")\` first |
 | Narrow bypass | Immediate read-only ContextStream calls when context is fresh and no state-changing tool has run |
-| Before ANY file discovery | \`search(mode="auto", query="...")\` |
+| Before ANY file discovery | \`search(mode="auto", query="...")\` (instead of Glob/Grep/Read/Explore/Task/EnterPlanMode) |
 | On \`<system-reminder>\` | **Follow instructions inside** |
 | Save important decisions | \`session(action="capture", event_type="decision", ...)\` |
 | Check past mistakes | \`session(action="get_lessons", query="...")\` |
@@ -1126,7 +1129,7 @@ project(action="index")
 
 ## \u{1F50D} SEARCH-FIRST (No PreToolUse Hook)
 
-**There is NO hook to block local tools.** You MUST self-enforce:
+**There is NO hook to block local tools (Glob/Grep/Read/Explore/Task/EnterPlanMode).** You MUST self-enforce:
 
 ### Before ANY Search, Check Index Status:
 \`\`\`
@@ -1144,6 +1147,7 @@ This tells you:
 \`\`\`
 search(mode="auto", query="what you're looking for")
 \`\`\`
+\u2192 Use this instead of Explore/Task/EnterPlanMode for file discovery.
 
 **IF project is NOT indexed or very stale (>7 days):**
 \u2192 Use local tools (Glob/Grep/Read) directly
@@ -1222,7 +1226,8 @@ session(action="capture_plan", title="...", steps=[...])
 memory(action="create_task", title="...", plan_id="...")
 \`\`\`
 
-\u274C DO NOT use built-in plan mode or write plans to markdown files.
+\u274C DO NOT use built-in plan mode (\`EnterPlanMode\`) or \`Task(subagent_type="Explore")\` for file-by-file scans.
+\u2705 For planning discovery, use \`search(mode="auto", query="...", output_format="paths")\` then read only narrowed files.
 
 ---
 
@@ -1319,6 +1324,24 @@ ${rules.split("\n").map((line) => "  " + line).join("\n")}
     description: "Google Antigravity AI rules",
     build: (rules) => `# Antigravity Agent Rules
 ${rules}
+`
+  },
+  copilot: {
+    filename: ".github/copilot-instructions.md",
+    description: "VS Code GitHub Copilot instructions",
+    build: (rules) => `## ContextStream MCP Integration
+
+This project uses [ContextStream](https://contextstream.io) for persistent AI memory across sessions. Use the \`contextstream-workflow\` skill for detailed examples and reference material.
+
+${rules}
+
+### VS Code Copilot Notes
+
+- Keep this file concise; put detailed workflows in \`.github/skills/contextstream-workflow/SKILL.md\`
+- Use ContextStream plans/tasks as the persistent record of work
+- Before code discovery, use \`search(mode="auto", query="...")\`
+
+Full docs: https://contextstream.io/docs/mcp/tools
 `
   }
 };
@@ -1334,7 +1357,7 @@ function generateRuleContent(editor, options) {
   const mode = options?.mode || "bootstrap";
   const rules = mode === "full" ? CONTEXTSTREAM_RULES_FULL : mode === "minimal" ? CONTEXTSTREAM_RULES_MINIMAL : mode === "bootstrap" ? CONTEXTSTREAM_RULES_BOOTSTRAP : CONTEXTSTREAM_RULES_DYNAMIC;
   let content = template.build(rules);
-  if (options?.workspaceName || options?.projectName) {
+  if (editor.toLowerCase() !== "copilot" && (options?.workspaceName || options?.projectName)) {
     const header = `
 # Workspace: ${options.workspaceName || "Unknown"}
 ${options.projectName ? `# Project: ${options.projectName}` : ""}

package/dist/hooks/stop.js

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+
+// src/hooks/common.ts
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { homedir } from "node:os";
+var DEFAULT_API_URL = "https://api.contextstream.io";
+function readHookInput() {
+  try {
+    return JSON.parse(fs.readFileSync(0, "utf8"));
+  } catch {
+    return {};
+  }
+}
+function writeHookOutput(output) {
+  const payload = output && (output.additionalContext || output.blocked || output.reason) ? {
+    hookSpecificOutput: output.additionalContext ? {
+      hookEventName: output.hookEventName,
+      additionalContext: output.additionalContext
+    } : void 0,
+    additionalContext: output.additionalContext,
+    blocked: output.blocked,
+    reason: output.reason
+  } : {};
+  console.log(JSON.stringify(payload));
+}
+function extractCwd(input) {
+  const cwd = typeof input.cwd === "string" && input.cwd.trim() ? input.cwd.trim() : process.cwd();
+  return cwd;
+}
+function loadHookConfig(cwd) {
+  let apiUrl = process.env.CONTEXTSTREAM_API_URL || DEFAULT_API_URL;
+  let apiKey = process.env.CONTEXTSTREAM_API_KEY || "";
+  let jwt = process.env.CONTEXTSTREAM_JWT || "";
+  let workspaceId = process.env.CONTEXTSTREAM_WORKSPACE_ID || null;
+  let projectId = process.env.CONTEXTSTREAM_PROJECT_ID || null;
+  let searchDir = path.resolve(cwd);
+  for (let i = 0; i < 6; i++) {
+    if (!apiKey && !jwt) {
+      const mcpPath = path.join(searchDir, ".mcp.json");
+      if (fs.existsSync(mcpPath)) {
+        try {
+          const config = JSON.parse(fs.readFileSync(mcpPath, "utf8"));
+          const env = config.mcpServers?.contextstream?.env;
+          if (env?.CONTEXTSTREAM_API_KEY) apiKey = env.CONTEXTSTREAM_API_KEY;
+          if (env?.CONTEXTSTREAM_JWT) jwt = env.CONTEXTSTREAM_JWT;
+          if (env?.CONTEXTSTREAM_API_URL) apiUrl = env.CONTEXTSTREAM_API_URL;
+          if (env?.CONTEXTSTREAM_WORKSPACE_ID && !workspaceId) workspaceId = env.CONTEXTSTREAM_WORKSPACE_ID;
+          if (env?.CONTEXTSTREAM_PROJECT_ID && !projectId) projectId = env.CONTEXTSTREAM_PROJECT_ID;
+        } catch {
+        }
+      }
+    }
+    if (!workspaceId || !projectId) {
+      const localConfigPath = path.join(searchDir, ".contextstream", "config.json");
+      if (fs.existsSync(localConfigPath)) {
+        try {
+          const localConfig = JSON.parse(fs.readFileSync(localConfigPath, "utf8"));
+          if (localConfig.workspace_id && !workspaceId) workspaceId = localConfig.workspace_id;
+          if (localConfig.project_id && !projectId) projectId = localConfig.project_id;
+        } catch {
+        }
+      }
+    }
+    const parentDir = path.dirname(searchDir);
+    if (parentDir === searchDir) break;
+    searchDir = parentDir;
+  }
+  if (!apiKey && !jwt) {
+    const homeMcpPath = path.join(homedir(), ".mcp.json");
+    if (fs.existsSync(homeMcpPath)) {
+      try {
+        const config = JSON.parse(fs.readFileSync(homeMcpPath, "utf8"));
+        const env = config.mcpServers?.contextstream?.env;
+        if (env?.CONTEXTSTREAM_API_KEY) apiKey = env.CONTEXTSTREAM_API_KEY;
+        if (env?.CONTEXTSTREAM_JWT) jwt = env.CONTEXTSTREAM_JWT;
+        if (env?.CONTEXTSTREAM_API_URL) apiUrl = env.CONTEXTSTREAM_API_URL;
+      } catch {
+      }
+    }
+  }
+  return { apiUrl, apiKey, jwt, workspaceId, projectId };
+}
+function isConfigured(config) {
+  return Boolean(config.apiKey || config.jwt);
+}
+function authHeaders(config) {
+  if (config.apiKey) {
+    return { "X-API-Key": config.apiKey };
+  }
+  if (config.jwt) {
+    return { Authorization: `Bearer ${config.jwt}` };
+  }
+  return {};
+}
+async function apiRequest(config, apiPath, init = {}) {
+  const response = await fetch(`${config.apiUrl}${apiPath}`, {
+    method: init.method || "GET",
+    headers: {
+      "Content-Type": "application/json",
+      ...authHeaders(config)
+    },
+    body: init.body !== void 0 ? JSON.stringify(init.body) : void 0
+  });
+  if (!response.ok) {
+    throw new Error(`${response.status} ${response.statusText}`);
+  }
+  const json = await response.json();
+  if (json && typeof json === "object" && "data" in json) {
+    return json.data;
+  }
+  return json;
+}
+async function postMemoryEvent(config, title, content, tags, eventType = "operation") {
+  if (!isConfigured(config) || !config.workspaceId) return;
+  await apiRequest(config, "/memory/events", {
+    method: "POST",
+    body: {
+      workspace_id: config.workspaceId,
+      project_id: config.projectId || void 0,
+      event_type: eventType,
+      title,
+      content: typeof content === "string" ? content : JSON.stringify(content),
+      metadata: {
+        tags,
+        source: "mcp_hook",
+        captured_at: (/* @__PURE__ */ new Date()).toISOString()
+      }
+    }
+  });
+}
+
+// src/hooks/stop.ts
+async function runStopHook() {
+  if (process.env.CONTEXTSTREAM_STOP_ENABLED === "false") {
+    writeHookOutput();
+    return;
+  }
+  const input = readHookInput();
+  const cwd = extractCwd(input);
+  const config = loadHookConfig(cwd);
+  if (isConfigured(config)) {
+    const sessionId = typeof input.session_id === "string" && input.session_id || "unknown";
+    const reason = typeof input.reason === "string" && input.reason || typeof input.stop_reason === "string" && input.stop_reason || "response_complete";
+    await postMemoryEvent(
+      config,
+      "Stop checkpoint",
+      {
+        session_id: sessionId,
+        reason,
+        hook: "stop",
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        tool_name: typeof input.tool_name === "string" ? input.tool_name : null,
+        model: typeof input.model === "string" ? input.model : null
+      },
+      ["hook", "stop", "checkpoint"]
+    ).catch(() => {
+    });
+  }
+  writeHookOutput();
+}
+var isDirectRun = process.argv[1]?.includes("stop") || process.argv[2] === "stop";
+if (isDirectRun) {
+  runStopHook().catch(() => process.exit(0));
+}
+export {
+  runStopHook
+};

package/dist/hooks/subagent-start.js

@@ -0,0 +1,192 @@
+#!/usr/bin/env node
+
+// src/hooks/common.ts
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { homedir } from "node:os";
+var DEFAULT_API_URL = "https://api.contextstream.io";
+function readHookInput() {
+  try {
+    return JSON.parse(fs.readFileSync(0, "utf8"));
+  } catch {
+    return {};
+  }
+}
+function writeHookOutput(output) {
+  const payload = output && (output.additionalContext || output.blocked || output.reason) ? {
+    hookSpecificOutput: output.additionalContext ? {
+      hookEventName: output.hookEventName,
+      additionalContext: output.additionalContext
+    } : void 0,
+    additionalContext: output.additionalContext,
+    blocked: output.blocked,
+    reason: output.reason
+  } : {};
+  console.log(JSON.stringify(payload));
+}
+function extractCwd(input) {
+  const cwd = typeof input.cwd === "string" && input.cwd.trim() ? input.cwd.trim() : process.cwd();
+  return cwd;
+}
+function loadHookConfig(cwd) {
+  let apiUrl = process.env.CONTEXTSTREAM_API_URL || DEFAULT_API_URL;
+  let apiKey = process.env.CONTEXTSTREAM_API_KEY || "";
+  let jwt = process.env.CONTEXTSTREAM_JWT || "";
+  let workspaceId = process.env.CONTEXTSTREAM_WORKSPACE_ID || null;
+  let projectId = process.env.CONTEXTSTREAM_PROJECT_ID || null;
+  let searchDir = path.resolve(cwd);
+  for (let i = 0; i < 6; i++) {
+    if (!apiKey && !jwt) {
+      const mcpPath = path.join(searchDir, ".mcp.json");
+      if (fs.existsSync(mcpPath)) {
+        try {
+          const config = JSON.parse(fs.readFileSync(mcpPath, "utf8"));
+          const env = config.mcpServers?.contextstream?.env;
+          if (env?.CONTEXTSTREAM_API_KEY) apiKey = env.CONTEXTSTREAM_API_KEY;
+          if (env?.CONTEXTSTREAM_JWT) jwt = env.CONTEXTSTREAM_JWT;
+          if (env?.CONTEXTSTREAM_API_URL) apiUrl = env.CONTEXTSTREAM_API_URL;
+          if (env?.CONTEXTSTREAM_WORKSPACE_ID && !workspaceId) workspaceId = env.CONTEXTSTREAM_WORKSPACE_ID;
+          if (env?.CONTEXTSTREAM_PROJECT_ID && !projectId) projectId = env.CONTEXTSTREAM_PROJECT_ID;
+        } catch {
+        }
+      }
+    }
+    if (!workspaceId || !projectId) {
+      const localConfigPath = path.join(searchDir, ".contextstream", "config.json");
+      if (fs.existsSync(localConfigPath)) {
+        try {
+          const localConfig = JSON.parse(fs.readFileSync(localConfigPath, "utf8"));
+          if (localConfig.workspace_id && !workspaceId) workspaceId = localConfig.workspace_id;
+          if (localConfig.project_id && !projectId) projectId = localConfig.project_id;
+        } catch {
+        }
+      }
+    }
+    const parentDir = path.dirname(searchDir);
+    if (parentDir === searchDir) break;
+    searchDir = parentDir;
+  }
+  if (!apiKey && !jwt) {
+    const homeMcpPath = path.join(homedir(), ".mcp.json");
+    if (fs.existsSync(homeMcpPath)) {
+      try {
+        const config = JSON.parse(fs.readFileSync(homeMcpPath, "utf8"));
+        const env = config.mcpServers?.contextstream?.env;
+        if (env?.CONTEXTSTREAM_API_KEY) apiKey = env.CONTEXTSTREAM_API_KEY;
+        if (env?.CONTEXTSTREAM_JWT) jwt = env.CONTEXTSTREAM_JWT;
+        if (env?.CONTEXTSTREAM_API_URL) apiUrl = env.CONTEXTSTREAM_API_URL;
+      } catch {
+      }
+    }
+  }
+  return { apiUrl, apiKey, jwt, workspaceId, projectId };
+}
+function isConfigured(config) {
+  return Boolean(config.apiKey || config.jwt);
+}
+function authHeaders(config) {
+  if (config.apiKey) {
+    return { "X-API-Key": config.apiKey };
+  }
+  if (config.jwt) {
+    return { Authorization: `Bearer ${config.jwt}` };
+  }
+  return {};
+}
+async function apiRequest(config, apiPath, init = {}) {
+  const response = await fetch(`${config.apiUrl}${apiPath}`, {
+    method: init.method || "GET",
+    headers: {
+      "Content-Type": "application/json",
+      ...authHeaders(config)
+    },
+    body: init.body !== void 0 ? JSON.stringify(init.body) : void 0
+  });
+  if (!response.ok) {
+    throw new Error(`${response.status} ${response.statusText}`);
+  }
+  const json = await response.json();
+  if (json && typeof json === "object" && "data" in json) {
+    return json.data;
+  }
+  return json;
+}
+async function fetchFastContext(config, body) {
+  if (!isConfigured(config)) return null;
+  try {
+    const result = await apiRequest(config, "/context/hook", {
+      method: "POST",
+      body: {
+        workspace_id: config.workspaceId || void 0,
+        project_id: config.projectId || void 0,
+        ...body
+      }
+    });
+    if (typeof result?.context === "string") return result.context;
+    if (typeof result?.data?.context === "string") return result.data.context;
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+// src/hooks/subagent-start.ts
+var SEARCH_PROTOCOL = `[CONTEXTSTREAM SEARCH]
+When searching code, prefer ContextStream search tools first:
+- mcp__contextstream__search(mode="auto", query="...")
+- mcp__contextstream__search(mode="keyword", query="...", include_content=true)
+- mcp__contextstream__graph(...) for dependency analysis
+Fall back to local discovery tools only if ContextStream search returns no results.`;
+var EXPLORE_SEARCH_FIRST = `[CRITICAL: SEARCH-FIRST PROTOCOL]
+You MUST call mcp__contextstream__search(mode="auto", query="...") BEFORE reading source files.
+Read only the small set of files and line ranges identified by search.`;
+var PLAN_SEARCH_FIRST = `[PLAN MODE: SEARCH-FIRST]
+Plan mode does NOT justify file-by-file repository scans.
+Start with ContextStream search, then read only the narrowed files and ranges.`;
+function fallbackContext() {
+  return `${SEARCH_PROTOCOL}
+
+[CONTEXTSTREAM] Call mcp__contextstream__context(user_message="...") for task-specific context.`;
+}
+async function runSubagentStartHook() {
+  if (process.env.CONTEXTSTREAM_SUBAGENT_CONTEXT_ENABLED === "false") {
+    writeHookOutput();
+    return;
+  }
+  const input = readHookInput();
+  const cwd = extractCwd(input);
+  const config = loadHookConfig(cwd);
+  const agentType = typeof input.agent_type === "string" && input.agent_type || typeof input.subagent_type === "string" && input.subagent_type || "unknown";
+  if (!isConfigured(config)) {
+    writeHookOutput({ additionalContext: fallbackContext(), hookEventName: "SubagentStart" });
+    return;
+  }
+  const context = await fetchFastContext(config, {
+    session_id: typeof input.session_id === "string" && input.session_id || typeof input.sessionId === "string" && input.sessionId || void 0,
+    user_message: `SubagentStart:${agentType}`
+  });
+  const parts = [];
+  if (context) parts.push(context);
+  if (agentType.toLowerCase() === "explore") {
+    parts.push(EXPLORE_SEARCH_FIRST);
+  } else if (agentType.toLowerCase() === "plan") {
+    parts.push(PLAN_SEARCH_FIRST);
+    parts.push(
+      `[CONTEXTSTREAM PLAN]
+Save plans to ContextStream with mcp__contextstream__session(action="capture_plan", ...).
+Create tasks with mcp__contextstream__memory(action="create_task", ...).`
+    );
+  }
+  parts.push(SEARCH_PROTOCOL);
+  writeHookOutput({
+    additionalContext: parts.filter(Boolean).join("\n\n") || fallbackContext(),
+    hookEventName: "SubagentStart"
+  });
+}
+var isDirectRun = process.argv[1]?.includes("subagent-start") || process.argv[2] === "subagent-start";
+if (isDirectRun) {
+  runSubagentStartHook().catch(() => process.exit(0));
+}
+export {
+  runSubagentStartHook
+};